`arg.md`

973 строк · 50.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.2/c-api/arg.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Разбор аргументов и построение значений89Эти функции полезны при создании собственных функций и методов расширений. Дополнительная информация и примеры доступны в [*Расширение и встраивание интерпретатора Python*](https://python-all.ru/3.2/extending/index.html#extending-index).1011Первые три из описанных функций, [`PyArg_ParseTuple()`](https://python-all.ru/3.2/c-api/arg.html#PyArg_ParseTuple), [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.2/c-api/arg.html#PyArg_ParseTupleAndKeywords) и [`PyArg_Parse()`](https://python-all.ru/3.2/c-api/arg.html#PyArg_Parse), используют *строки формата*, которые сообщают функции об ожидаемых аргументах. Эти строки формата имеют одинаковый синтаксис для всех этих функций.1213## Разбор аргументов1415Строка формата состоит из нуля или более «единиц формата». Единица формата описывает один объект Python; обычно это один символ или заключённая в скобки последовательность единиц формата. За несколькими исключениями, единица формата, не являющаяся последовательностью в скобках, обычно соответствует одному аргументу-адресу этих функций. В следующем описании приведённая в кавычках форма – это единица формата; запись в круглых скобках – тип объекта Python, которому соответствует единица формата; а запись в квадратных скобках – тип переменной(ых) C, чей адрес следует передать.1617### Строки и буферы1819Эти форматы позволяют получить доступ к объекту как к непрерывному блоку памяти. Вам не нужно предоставлять сырое хранилище для возвращаемой области unicode или bytes. Кроме того, вам не придётся самостоятельно освобождать память, за исключением форматов `es`, `es#`, `et` и `et#`.2021Однако, когда структура [`Py_buffer`](https://python-all.ru/3.2/c-api/buffer.html#Py_buffer) заполняется, соответствующий буфер блокируется, чтобы вызывающий код мог затем использовать буфер даже внутри блока [`Py_BEGIN_ALLOW_THREADS`](https://python-all.ru/3.2/c-api/init.html#Py_BEGIN_ALLOW_THREADS) без риска изменения или уничтожения изменяемых данных. Как следствие, **необходимо вызвать** [`PyBuffer_Release()`](https://python-all.ru/3.2/c-api/buffer.html#PyBuffer_Release) после завершения обработки данных (или в случае досрочного прерывания).2223Если не указано иное, буферы не завершаются нулевым символом (NUL).2425> **Примечание**26>27> Для всех вариантов форматов `#` (`s#`, `y#` и т.д.), тип аргумента длины (int или `Py_ssize_t`) определяется определением макроса `PY_SSIZE_T_CLEAN` до включения `Python.h`. Если макрос определён, длина имеет тип `Py_ssize_t`, а не `int`. В будущей версии Python это поведение изменится: будет поддерживаться только `Py_ssize_t`, а поддержка `int` будет удалена. Рекомендуется всегда определять `PY_SSIZE_T_CLEAN`.2829**`s` ([`str`](https://python-all.ru/3.2/library/functions.html#str)) \[const char \*\]**3031Преобразует объект Unicode в указатель C на строку символов. Указатель на существующую строку сохраняется в переменной-указателе на символы, адрес которой передаётся. Строка C завершается нулевым символом (NUL). Строка Python не должна содержать встроенных нулевых байтов; если они есть, возбуждается исключение [`TypeError`](https://python-all.ru/3.2/library/exceptions.html#TypeError). Объекты Unicode преобразуются в строки C с использованием кодировки `'utf-8'`. Если это преобразование не удаётся, возбуждается [`UnicodeError`](https://python-all.ru/3.2/library/exceptions.html#UnicodeError).3233> **Примечание**34>35> Этот формат не принимает байтоподобные объекты. Если требуется принимать пути файловой системы и преобразовывать их в строки символов C, предпочтительнее использовать формат `O&` с [`PyUnicode_FSConverter()`](https://python-all.ru/3.2/c-api/unicode.html#PyUnicode_FSConverter) в качестве *преобразователя*.3637**`s*` ([`str`](https://python-all.ru/3.2/library/functions.html#str), [`bytes`](https://python-all.ru/3.2/library/functions.html#bytes), [`bytearray`](https://python-all.ru/3.2/library/functions.html#bytearray) or buffer compatible object) \[Py\_buffer\]**3839Этот формат принимает Unicode-объекты, а также объекты, поддерживающие протокол буфера. Он заполняет структуру4041[`Py_buffer`](https://python-all.ru/3.2/c-api/buffer.html#Py_buffer)4243, предоставленную вызывающей стороной. В этом случае результирующая C-строка может содержать встроенные NUL-байты. Unicode-объекты преобразуются в C-строки с использованием кодировки4445`'utf-8'`4647.4849**`s#` ([`str`](https://python-all.ru/3.2/library/functions.html#str), [`bytes`](https://python-all.ru/3.2/library/functions.html#bytes) or read-only buffer compatible object) \[const char \*, int or `Py_ssize_t`\]**5051Как5253`s*`5455, за исключением того, что не принимает изменяемые буфероподобные объекты, такие как5657[`bytearray`](https://python-all.ru/3.2/library/functions.html#bytearray)5859. Результат сохраняется в две C-переменные: первая – указатель на C-строку, вторая – её длина. Строка может содержать встроенные нулевые байты. Объекты Unicode преобразуются в C-строки с использованием кодировки6061`'utf-8'`6263.6465**`z` ([`str`](https://python-all.ru/3.2/library/functions.html#str) или `None`) \[const char \*\]**6667Аналогично6869`s`7071, но объект Python также может быть7273`None`7475, и в этом случае указатель C устанавливается в7677*NULL*7879.8081**`z*` ([`str`](https://python-all.ru/3.2/library/functions.html#str), [`bytes`](https://python-all.ru/3.2/library/functions.html#bytes), [`bytearray`](https://python-all.ru/3.2/library/functions.html#bytearray), buffer compatible object or `None`) \[Py\_buffer\]**8283Как8485`s*`8687, но объект Python также может быть8889`None`9091, и в этом случае поле9293`buf`9495структуры9697[`Py_buffer`](https://python-all.ru/3.2/c-api/buffer.html#Py_buffer)9899устанавливается в100101*NULL*102103.104105**`z#` ([`str`](https://python-all.ru/3.2/library/functions.html#str), [`bytes`](https://python-all.ru/3.2/library/functions.html#bytes), read-only buffer compatible object or `None`) \[const char \*, int\]**106107Как108109`s#`110111, но объект Python также может быть112113`None`114115, и в этом случае указатель C устанавливается в116117*NULL*118119.120121**`y` ([`bytes`](https://python-all.ru/3.2/library/functions.html#bytes)) \[const char \*\]**122123Этот формат преобразует объект, подобный байтам, в указатель C на строку символов; он не принимает объекты Unicode. Буфер байтов не должен содержать встроенных нулевых байтов; если они есть, возбуждается исключение124125[`TypeError`](https://python-all.ru/3.2/library/exceptions.html#TypeError)126127.128129**`y*` ([`bytes`](https://python-all.ru/3.2/library/functions.html#bytes), [`bytearray`](https://python-all.ru/3.2/library/functions.html#bytearray) or buffer compatible object) \[Py\_buffer\]**130131Этот вариант132133`s*`134135не принимает Unicode-объекты, только объекты, поддерживающие протокол буфера.136137**Это рекомендуемый способ приёма двоичных данных.**138139**`y#` ([`bytes`](https://python-all.ru/3.2/library/functions.html#bytes)) \[const char \*, int\]**140141Этот вариант142143`s#`144145не принимает объекты Unicode, только объекты, подобные байтам.146147**`S` ([`bytes`](https://python-all.ru/3.2/library/functions.html#bytes)) \[PyBytesObject \*\]**148149Требует, чтобы объект Python был объектом150151[`bytes`](https://python-all.ru/3.2/library/functions.html#bytes)152153, без попыток преобразования. Возбуждает154155[`TypeError`](https://python-all.ru/3.2/library/exceptions.html#TypeError)156157, если объект не является объектом bytes. Переменная C также может быть объявлена как158159[`PyObject*`](https://python-all.ru/3.2/c-api/structures.html#PyObject)160161.162163**`Y` ([`bytearray`](https://python-all.ru/3.2/library/functions.html#bytearray)) \[PyByteArrayObject \*\]**164165Требует, чтобы объект Python был объектом166167[`bytearray`](https://python-all.ru/3.2/library/functions.html#bytearray)168169, без попыток преобразования. Возбуждает170171[`TypeError`](https://python-all.ru/3.2/library/exceptions.html#TypeError)172173, если объект не является объектом174175[`bytearray`](https://python-all.ru/3.2/library/functions.html#bytearray)176177. Переменная C также может быть объявлена как178179[`PyObject*`](https://python-all.ru/3.2/c-api/structures.html#PyObject)180181.182183**`u` ([`str`](https://python-all.ru/3.2/library/functions.html#str)) \[Py\_UNICODE \*\]**184185Преобразует объект Python Unicode в указатель C на буфер символов Unicode, завершающийся нулевым символом. Необходимо передать адрес переменной-указателя [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE), которая будет заполнена указателем на существующий буфер Unicode. Обратите внимание, что ширина символа [`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE) зависит от опций компиляции (она составляет 16 или 32 бита). Строка Python не должна содержать встроенных нулевых символов; если они есть, возбуждается исключение [`TypeError`](https://python-all.ru/3.2/library/exceptions.html#TypeError).186187> **Примечание**188>189> Поскольку `u` не возвращает длину строки, и она может содержать встроенные нулевые символы, рекомендуется использовать вместо него `u#` или `U`.190191**`u#` ([`str`](https://python-all.ru/3.2/library/functions.html#str)) \[Py\_UNICODE \*, int\]**192193Этот вариант194195`u`196197сохраняет значения в две переменные C: первая – указатель на буфер данных Unicode, вторая – его длину.198199**`Z` ([`str`](https://python-all.ru/3.2/library/functions.html#str) или `None`) \[Py\_UNICODE \*\]**200201Как и202203`u`204205, но объект Python также может быть206207`None`208209, и в этом случае указатель210211[`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE)212213устанавливается в214215*NULL*216217.218219**`Z#` ([`str`](https://python-all.ru/3.2/library/functions.html#str) или `None`) \[Py\_UNICODE \*, int\]**220221Как и222223`u#`224225, но объект Python также может быть226227`None`228229, и в этом случае указатель230231[`Py_UNICODE`](https://python-all.ru/3.2/c-api/unicode.html#Py_UNICODE)232233устанавливается в234235*NULL*236237.238239**`U` ([`str`](https://python-all.ru/3.2/library/functions.html#str)) \[PyUnicodeObject \*\]**240241Требует, чтобы объект Python был объектом Unicode, без попыток какого-либо преобразования. Возбуждает242243[`TypeError`](https://python-all.ru/3.2/library/exceptions.html#TypeError)244245, если объект не является объектом Unicode. Переменная C также может быть объявлена как246247[`PyObject*`](https://python-all.ru/3.2/c-api/structures.html#PyObject)248249.250251**`w*` ([`bytearray`](https://python-all.ru/3.2/library/functions.html#bytearray) или буфер для чтения и записи, ориентированный на байты) \[Py\_buffer\]**252253Этот формат принимает любой объект, реализующий интерфейс буфера для чтения и записи. Он заполняет структуру254255[`Py_buffer`](https://python-all.ru/3.2/c-api/buffer.html#Py_buffer)256257, предоставленную вызывающим кодом. Буфер может содержать встроенные нулевые байты. Вызывающий код должен вызвать258259[`PyBuffer_Release()`](https://python-all.ru/3.2/c-api/buffer.html#PyBuffer_Release)260261после завершения работы с буфером.262263**`es` ([`str`](https://python-all.ru/3.2/library/functions.html#str)) \[const char \*encoding, char \*\*buffer\]**264265Этот вариант `s` используется для кодирования Unicode в символьный буфер. Он работает только с закодированными данными без встроенных NUL-байтов.266267Этот формат требует два аргумента. Первый используется только как входной и должен быть `const char*`, указывающим на имя кодировки в виде NUL-терминированной строки, или *NULL*, в этом случае используется кодировка `'utf-8'`. Если указанная кодировка неизвестна Python, возбуждается исключение. Второй аргумент должен быть `char**`; значение указателя, на который он ссылается, будет установлено в буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, указанной первым аргументом.268269[`PyArg_ParseTuple()`](https://python-all.ru/3.2/c-api/arg.html#PyArg_ParseTuple) выделит буфер необходимого размера, скопирует закодированные данные в этот буфер и настроит *\*buffer* так, чтобы он ссылался на новую выделенную память. Вызывающий код отвечает за вызов [`PyMem_Free()`](https://python-all.ru/3.2/c-api/memory.html#PyMem_Free) для освобождения выделенного буфера после использования.270271**`et` ([`str`](https://python-all.ru/3.2/library/functions.html#str), [`bytes`](https://python-all.ru/3.2/library/functions.html#bytes) или [`bytearray`](https://python-all.ru/3.2/library/functions.html#bytearray)) \[const char \*encoding, char \*\*buffer\]**272273То же, что и274275`es`276277, за исключением того, что объекты-байтовые строки передаются без перекодирования. Вместо этого реализация предполагает, что объект-байтовая строка использует кодировку, переданную в качестве параметра.278279**`es#` ([`str`](https://python-all.ru/3.2/library/functions.html#str)) \[const char \*encoding, char \*\*buffer, int \*buffer\_length\]**280281Этот вариант `s#` используется для кодирования Unicode в символьный буфер. В отличие от формата `es`, этот вариант допускает входные данные, содержащие NUL-символы.282283Требуются три аргумента. Первый используется только как входной и должен быть `const char*`, указывающим на имя кодировки в виде NUL-терминированной строки, или *NULL*, в этом случае используется кодировка `'utf-8'`. Если указанная кодировка неизвестна Python, возбуждается исключение. Второй аргумент должен быть `char**`; значение указателя, на который он ссылается, будет установлено в буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, указанной первым аргументом. Третий аргумент должен быть указателем на целое число; целое число, на которое он ссылается, будет установлено в количество байтов в выходном буфере.284285Существует два режима работы:286287Если *\*buffer* указывает на указатель *NULL*, функция выделит буфер необходимого размера, скопирует закодированные данные в этот буфер и установит *\*buffer* так, чтобы он ссылался на новую выделенную память. Вызывающий код отвечает за вызов [`PyMem_Free()`](https://python-all.ru/3.2/c-api/memory.html#PyMem_Free) для освобождения выделенного буфера после использования.288289Если *\*buffer* указывает на не-*NULL* указатель (уже выделенный буфер), [`PyArg_ParseTuple()`](https://python-all.ru/3.2/c-api/arg.html#PyArg_ParseTuple) будет использовать это место как буфер и интерпретировать начальное значение *\*buffer\_length* как размер буфера. Затем он скопирует закодированные данные в буфер и завершит его NUL. Если буфер недостаточно велик, будет установлено [`ValueError`](https://python-all.ru/3.2/library/exceptions.html#ValueError).290291В обоих случаях *\*buffer\_length* устанавливается в длину закодированных данных без завершающего NUL-байта.292293**`et#` ([`str`](https://python-all.ru/3.2/library/functions.html#str), [`bytes`](https://python-all.ru/3.2/library/functions.html#bytes) или [`bytearray`](https://python-all.ru/3.2/library/functions.html#bytearray)) \[const char \*encoding, char \*\*buffer, int \*buffer\_length\]**294295То же, что и296297`es#`298299, за исключением того, что объекты-байтовые строки передаются без перекодирования. Вместо этого реализация предполагает, что объект-байтовая строка использует кодировку, переданную в качестве параметра.300301### Числа302303**`b` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[unsigned char\]**304305Преобразует неотрицательное целое число Python в беззнаковое крошечное целое, хранящееся в C306307`unsigned char`308309.310311**`B` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[unsigned char\]**312313Преобразует целое число Python в крошечное целое без проверки переполнения, хранящееся в C314315`unsigned char`316317.318319**`h` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[short int\]**320321Преобразует целое число Python в C322323`short int`324325.326327**`H` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[unsigned short int\]**328329Преобразует целое число Python в C330331`unsigned short int`332333без проверки переполнения.334335**`i` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[int\]**336337Преобразует целое число Python в обычный C338339`int`340341.342343**`I` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[unsigned int\]**344345Преобразует целое число Python в C346347`unsigned int`348349без проверки переполнения.350351**`l` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[long int\]**352353Преобразует целое число Python в C354355`long int`356357.358359**`k` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[unsigned long\]**360361Преобразует целое число Python в C362363`unsigned long`364365без проверки переполнения.366367**`L` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[PY\_LONG\_LONG\]**368369Преобразует целое число Python в C370371`long long`372373. Этот формат доступен только на платформах, поддерживающих374375`long long`376377(или378379`_int64`380381на Windows).382383**`K` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[unsigned PY\_LONG\_LONG\]**384385Преобразует целое число Python в C386387`unsigned long long`388389без проверки переполнения. Этот формат доступен только на платформах, поддерживающих390391`unsigned long long`392393(или394395`unsigned _int64`396397на Windows).398399**`n` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[Py\_ssize\_t\]**400401Преобразует целое число Python в C402403`Py_ssize_t`404405.406407**`c` ([`bytes`](https://python-all.ru/3.2/library/functions.html#bytes) длиной 1) \[char\]**408409Преобразует Python-байт, представленный в виде объекта410411[`bytes`](https://python-all.ru/3.2/library/functions.html#bytes)412413длины 1, в C-тип414415`char`416417.418419**`C` ([`str`](https://python-all.ru/3.2/library/functions.html#str) длиной 1) \[int\]**420421Преобразует символ Python, представленный как объект422423[`str`](https://python-all.ru/3.2/library/functions.html#str)424425длиной 1, в C426427`int`428429.430431**`f` ([`float`](https://python-all.ru/3.2/library/functions.html#float)) \[float\]**432433Преобразует число с плавающей запятой Python в C434435`float`436437.438439**`d` ([`float`](https://python-all.ru/3.2/library/functions.html#float)) \[double\]**440441Преобразует число с плавающей запятой Python в C442443`double`444445.446447**`D` ([`complex`](https://python-all.ru/3.2/library/functions.html#complex)) \[Py\_complex\]**448449Преобразует комплексное число Python в структуру C450451[`Py_complex`](https://python-all.ru/3.2/c-api/complex.html#Py_complex)452453.454455### Другие объекты456457**`O` (объект) \[PyObject \*\]**458459Сохраняет объект Python (без какого-либо преобразования) в указателе на объект C. Таким образом, программа на C получает фактически переданный объект. Счётчик ссылок объекта не увеличивается. Сохранённый указатель не равен460461*NULL*462463.464465**`O!` (object) \[*typeobject*, PyObject \*\]**466467Сохраняет объект Python в указателе на объект C. Это похоже на468469`O`470471, но принимает два аргумента C: первый – адрес объекта типа Python, второй – адрес переменной C (типа472473[`PyObject*`](https://python-all.ru/3.2/c-api/structures.html#PyObject)474475), в который сохраняется указатель на объект. Если объект Python не имеет требуемого типа, вызывается476477[`TypeError`](https://python-all.ru/3.2/library/exceptions.html#TypeError)478479.480481**`O&` (объект) \[*converter*, *anything*\]**482483Преобразует объект Python в переменную C через функцию *converter*. Эта функция принимает два аргумента: первый – это функция, второй – адрес переменной C (произвольного типа), преобразованный к `void *`. Функция *converter* в свою очередь вызывается следующим образом:484485```c486status = converter(object, address);487```488489где *object* – это объект Python, который нужно преобразовать, а *address* – это аргумент `void*`, переданный функции [`PyArg_Parse*()`](https://python-all.ru/3.2/c-api/arg.html#PyArg_Parse). Возвращаемое значение *status* должно быть `1` при успешном преобразовании и `0` при неудаче. В случае ошибки функция *converter* должна возбудить исключение и оставить содержимое *address* без изменений.490491Если *converter* возвращает `Py_CLEANUP_SUPPORTED`, она может быть вызвана второй раз, если разбор аргументов в конечном итоге завершится неудачей, давая конвертеру возможность освободить любую память, которую он уже выделил. При этом втором вызове параметр *object* будет равен NULL; *address* будет иметь то же значение, что и при исходном вызове.492493Изменено в версии 3.1: `Py_CLEANUP_SUPPORTED` был добавлен.494495**`(items)` ([`tuple`](https://python-all.ru/3.2/library/functions.html#tuple)) \[*matching-items*\]**496497Объект должен быть последовательностью Python, длина которой равна количеству единиц формата в498499*элементах*500501. Аргументы C должны соответствовать отдельным единицам формата в502503*элементах*504505. Единицы формата для последовательностей могут быть вложенными.506507Можно передавать «длинные» целые числа (целые, значение которых превышает `LONG_MAX` платформы), однако надлежащая проверка диапазона не выполняется – старшие биты молча отбрасываются, когда принимающее поле слишком мало для значения (на самом деле, семантика унаследована от понижающих приведений в C – результат может отличаться).508509Некоторые другие символы имеют значение в строке формата. Они не могут встречаться внутри вложенных скобок. Вот они:510511**`|`**512513Указывает, что остальные аргументы в списке аргументов Python являются необязательными. Переменные C, соответствующие необязательным аргументам, должны быть инициализированы значением по умолчанию – если необязательный аргумент не указан,514515[`PyArg_ParseTuple()`](https://python-all.ru/3.2/c-api/arg.html#PyArg_ParseTuple)516517не изменяет содержимое соответствующих переменных C.518519**`:`**520521Список единиц формата заканчивается здесь; строка после двоеточия используется как имя функции в сообщениях об ошибках («связанное значение» исключения, которое возбуждает522523[`PyArg_ParseTuple()`](https://python-all.ru/3.2/c-api/arg.html#PyArg_ParseTuple)524525).526527**`;`**528529Список единиц форматирования заканчивается здесь; строка после точки с запятой используется как сообщение об ошибке530531*вместо*532533сообщения об ошибке по умолчанию.534535`:`536537и538539`;`540541взаимно исключают друг друга.542543Обратите внимание, что любые ссылки на объекты Python, передаваемые вызывающему, являются *заимствованными* ссылками; уменьшать их счётчик ссылок не следует.544545Дополнительные аргументы, передаваемые этим функциям, должны быть адресами переменных, тип которых определяется строкой формата; они используются для хранения значений из входного кортежа. Есть несколько случаев, как описано в списке единиц форматирования выше, когда эти параметры используются в качестве входных значений; в этом случае они должны соответствовать тому, что указано для соответствующей единицы форматирования.546547Чтобы преобразование прошло успешно, объект *arg* должен соответствовать формату, а формат должен быть исчерпан. В случае успеха функции [`PyArg_Parse*()`](https://python-all.ru/3.2/c-api/arg.html#PyArg_Parse) возвращают true, иначе возвращают false и возбуждают соответствующее исключение. Когда функции [`PyArg_Parse*()`](https://python-all.ru/3.2/c-api/arg.html#PyArg_Parse) завершаются ошибкой из-за сбоя преобразования в одной из единиц формата, переменные по адресам, соответствующим этой и следующим единицам формата, остаются нетронутыми.548549### API функции550551#### `int PyArg_ParseTuple(PyObject *args, const char *format, ...)`552553Разбирает параметры функции, принимающей только позиционные параметры, в локальные переменные. Возвращает true при успехе; при неудаче возвращает false и возбуждает соответствующее исключение.554555#### `int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)`556557Идентична [`PyArg_ParseTuple()`](https://python-all.ru/3.2/c-api/arg.html#PyArg_ParseTuple), за исключением того, что принимает va\_list вместо переменного числа аргументов.558559#### `int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)`560561Разбирает параметры функции, которая принимает как позиционные, так и именованные параметры, в локальные переменные. Возвращает true в случае успеха; в случае неудачи возвращает false и возбуждает соответствующее исключение.562563#### `int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)`564565Идентична [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.2/c-api/arg.html#PyArg_ParseTupleAndKeywords), за исключением того, что принимает va\_list вместо переменного числа аргументов.566567#### `int PyArg_ValidateKeywordArguments(PyObject *)`568569Гарантирует, что ключи в словаре аргументов keywords являются строками. Это требуется только в том случае, если [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.2/c-api/arg.html#PyArg_ParseTupleAndKeywords) не используется, поскольку последняя уже выполняет эту проверку.570571Новое в версии 3.2.572573#### `int PyArg_Parse(PyObject *args, const char *format, ...)`574575Функция, используемая для разбора списков аргументов «старых» функций – это функции, использующие `METH_OLDARGS` разбор параметров метод. Не рекомендуется использовать его для разбора параметров в новом коде, и большая часть кода в стандартном интерпретаторе была изменена, чтобы больше не использовать этот метод для этой цели. Тем не менее, он остаётся удобным способом разложения других кортежей, однако и может по-прежнему использоваться для этой цели.576577#### `int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)`578579Более простая форма извлечения параметров, которая не использует строку формата для указания типов аргументов. Функции, использующие этот метод для извлечения параметров, должны быть объявлены как [`METH_VARARGS`](https://python-all.ru/3.2/c-api/structures.html#METH_VARARGS) в таблицах функций или методов. Кортеж, содержащий фактические параметры, должен передаваться как *args*; он должен быть именно кортежем. Длина кортежа должна быть не менее *min* и не более *max*; *min* и *max* могут быть равны. Дополнительные аргументы должны быть переданы функции, каждый из которых должен быть указателем на переменную [`PyObject*`](https://python-all.ru/3.2/c-api/structures.html#PyObject); они будут заполнены значениями из *args*; они будут содержать заимствованные ссылки. Переменные, соответствующие необязательным параметрам, не указанным в *args*, не будут заполнены; они должны быть инициализированы вызывающей стороной. Эта функция возвращает true при успехе и false, если *args* не является кортежем или содержит неверное количество элементов; в случае неудачи будет установлено исключение.580581Это пример использования этой функции, взятый из исходников вспомогательного модуля слабых ссылок `_weakref`:582583```c584static PyObject *585weakref_ref(PyObject *self, PyObject *args)586{587    PyObject *object;588    PyObject *callback = NULL;589    PyObject *result = NULL;590591    if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {592        result = PyWeakref_NewRef(object, callback);593    }594    return result;595}596```597598Вызов [`PyArg_UnpackTuple()`](https://python-all.ru/3.2/c-api/arg.html#PyArg_UnpackTuple) в этом примере полностью эквивалентен следующему вызову [`PyArg_ParseTuple()`](https://python-all.ru/3.2/c-api/arg.html#PyArg_ParseTuple):599600```c601PyArg_ParseTuple(args, "O|O:ref", &object, &callback)602```603604## Построение значений605606#### `PyObject* Py_BuildValue(const char *format, ...)`607608*Возвращаемое значение: новая ссылка.*609610Создаёт новое значение на основе строки формата, аналогичной тем, которые принимаются семейством функций [`PyArg_Parse*()`](https://python-all.ru/3.2/c-api/arg.html#PyArg_Parse), и последовательности значений. Возвращает значение или *NULL* в случае ошибки; если возвращается *NULL*, будет возбуждено исключение.611612[`Py_BuildValue()`](https://python-all.ru/3.2/c-api/arg.html#Py_BuildValue) не всегда строит кортеж. Он строит кортеж, только если его строка формата содержит две или более единиц формата. Если строка формата пуста, она возвращает `None`; если содержит ровно одну единицу формата, возвращает объект, описываемый этой единицей формата. Чтобы принудительно вернуть кортеж размером 0 или 1, заключите строку формата в скобки.613614Когда буферы памяти передаются в качестве параметров для предоставления данных для построения объектов, как для форматов `s` и `s#`, необходимые данные копируются. Буферы, предоставленные вызывающей стороной, никогда не используются напрямую объектами, созданными [`Py_BuildValue()`](https://python-all.ru/3.2/c-api/arg.html#Py_BuildValue). Другими словами, если ваш код вызывает `malloc()` и передаёт выделенную память в [`Py_BuildValue()`](https://python-all.ru/3.2/c-api/arg.html#Py_BuildValue), ваш код отвечает за вызов `free()` для этой памяти после возврата из [`Py_BuildValue()`](https://python-all.ru/3.2/c-api/arg.html#Py_BuildValue).615616В следующем описании форма в кавычках – это элемент формата; запись в круглых скобках – это тип объекта Python, который вернёт элемент формата; а запись в квадратных скобках – это тип передаваемого(-ых) значения(-ий) C.617618Символы пробела, табуляции, двоеточия и запятой игнорируются в строках формата (но не внутри единиц формата, таких как `s#`). Это позволяет сделать длинные строки формата немного более читаемыми.619620**`s` ([`str`](https://python-all.ru/3.2/library/functions.html#str) или `None`) \[char \*\]**621622Преобразует C-строку, завершающуюся нулевым символом, в объект Python623624[`str`](https://python-all.ru/3.2/library/functions.html#str)625626с использованием кодировки627628`'utf-8'`629630. Если указатель на C-строку равен631632*NULL*633634, используется635636`None`637638.639640**`s#` ([`str`](https://python-all.ru/3.2/library/functions.html#str) или `None`) \[char \*, int\]**641642Преобразует C-строку и её длину в объект Python643644[`str`](https://python-all.ru/3.2/library/functions.html#str)645646с использованием кодировки647648`'utf-8'`649650. Если указатель на C-строку равен651652*NULL*653654, длина игнорируется и возвращается655656`None`657658.659660**`y` ([`bytes`](https://python-all.ru/3.2/library/functions.html#bytes)) \[char \*\]**661662Эта функция преобразует C строку в объект Python663664[`bytes()`](https://python-all.ru/3.2/library/functions.html#bytes)665666. Если указатель на C строку равен667668*NULL*669670, возвращается671672`None`673674.675676**`y#` ([`bytes`](https://python-all.ru/3.2/library/functions.html#bytes)) \[char \*, int\]**677678Преобразует C-строку и её длину в объект Python. Если указатель на C-строку равен679680*NULL*681682, возвращается683684`None`685686.687688**`z` ([`str`](https://python-all.ru/3.2/library/functions.html#str) или `None`) \[char \*\]**689690То же, что и691692`s`693694.695696**`z#` ([`str`](https://python-all.ru/3.2/library/functions.html#str) или `None`) \[char \*, int\]**697698То же, что и699700`s#`701702.703704**`u` ([`str`](https://python-all.ru/3.2/library/functions.html#str)) \[Py\_UNICODE \*\]**705706Преобразует буфер с нулевым символом в конце, содержащий данные Unicode (UCS-2 или UCS-4), в объект Unicode Python. Если указатель буфера Unicode равен707708*NULL*709710, возвращается711712`None`713714.715716**`u#` ([`str`](https://python-all.ru/3.2/library/functions.html#str)) \[Py\_UNICODE \*, int\]**717718Преобразует буфер данных Unicode (UCS-2 или UCS-4) и его длину в объект Unicode Python. Если указатель буфера Unicode равен719720*NULL*721722, длина игнорируется и возвращается723724`None`725726.727728**`U` ([`str`](https://python-all.ru/3.2/library/functions.html#str) или `None`) \[char \*\]**729730То же, что и731732`s`733734.735736**`U#` ([`str`](https://python-all.ru/3.2/library/functions.html#str) или `None`) \[char \*, int\]**737738То же, что и739740`s#`741742.743744**`i` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[int\]**745746Преобразует обычный C747748`int`749750в объект Python целого типа.751752**`b` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[char\]**753754Преобразует обычный C755756`char`757758в объект Python целого типа.759760**`h` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[short int\]**761762Преобразует обычное C763764`short int`765766в объект Python int.767768**`l` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[long int\]**769770Преобразует C771772`long int`773774в объект Python int.775776**`B` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[unsigned char\]**777778Преобразует C779780`unsigned char`781782в объект Python int.783784**`H` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[unsigned short int\]**785786Преобразует C787788`unsigned short int`789790в объект Python int.791792**`I` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[unsigned int\]**793794Преобразует C795796`unsigned int`797798в объект Python int.799800**`k` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[unsigned long\]**801802Преобразует C803804`unsigned long`805806в объект Python int.807808**`L` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[PY\_LONG\_LONG\]**809810Преобразует C811812`long long`813814в объект Python int. Доступно только на платформах, поддерживающих815816`long long`817818(или819820`_int64`821822в Windows).823824**`K` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[unsigned PY\_LONG\_LONG\]**825826Преобразует C827828`unsigned long long`829830в объект Python int. Доступно только на платформах, поддерживающих831832`unsigned long long`833834(или835836`unsigned _int64`837838в Windows).839840**`n` ([`int`](https://python-all.ru/3.2/library/functions.html#int)) \[Py\_ssize\_t\]**841842Преобразует C843844`Py_ssize_t`845846в Python int.847848**`c` ([`bytes`](https://python-all.ru/3.2/library/functions.html#bytes) длиной 1) \[char\]**849850Преобразует C851852`int`853854, представляющий байт, в объект Python855856[`bytes`](https://python-all.ru/3.2/library/functions.html#bytes)857858длиной 1.859860**`C` ([`str`](https://python-all.ru/3.2/library/functions.html#str) длиной 1) \[int\]**861862Преобразует C863864`int`865866, представляющий символ, в объект Python867868[`str`](https://python-all.ru/3.2/library/functions.html#str)869870длиной 1.871872**`d` ([`float`](https://python-all.ru/3.2/library/functions.html#float)) \[double\]**873874Преобразует C875876`double`877878в число с плавающей точкой Python.879880**`f` ([`float`](https://python-all.ru/3.2/library/functions.html#float)) \[float\]**881882Преобразует C883884`float`885886в число с плавающей точкой Python.887888**`D` ([`complex`](https://python-all.ru/3.2/library/functions.html#complex)) \[Py\_complex \*\]**889890Преобразует структуру C891892[`Py_complex`](https://python-all.ru/3.2/c-api/complex.html#Py_complex)893894в комплексное число Python.895896**`O` (объект) \[PyObject \*\]**897898Передаёт объект Python без изменений (за исключением счётчика ссылок, который увеличивается на единицу). Если переданный объект является указателем899900*NULL*901902, считается, что это произошло из-за того, что вызов, формирующий аргумент, обнаружил ошибку и установил исключение. Поэтому903904[`Py_BuildValue()`](https://python-all.ru/3.2/c-api/arg.html#Py_BuildValue)905906вернёт907908*NULL*909910, но не вызовет исключение. Если ещё не было установлено никакого исключения, устанавливается911912[`SystemError`](https://python-all.ru/3.2/library/exceptions.html#SystemError)913914.915916**`S` (объект) \[PyObject \*\]**917918То же, что и919920`O`921922.923924**`N` (объект) \[PyObject \*\]**925926То же, что и927928`O`929930, за исключением того, что не увеличивает счётчик ссылок на объект. Полезно, когда объект создаётся вызовом конструктора объекта в списке аргументов.931932**`O&` (объект) \[*converter*, *anything*\]**933934Преобразует935936*anything*937938в объект Python с помощью функции939940*converter*941942. Функция вызывается с аргументом943944*anything*945946(который должен быть совместим с947948`void *`949950) и должна возвращать «новый» объект Python или951952*NULL*953954в случае ошибки.955956**`(items)` ([`tuple`](https://python-all.ru/3.2/library/functions.html#tuple)) \[*matching-items*\]**957958Преобразует последовательность значений C в кортеж Python с тем же количеством элементов.959960**`[items]` ([`list`](https://python-all.ru/3.2/library/functions.html#list)) \[*matching-items*\]**961962Преобразует последовательность значений C в список Python с тем же количеством элементов.963964**`{items}` ([`dict`](https://python-all.ru/3.2/library/stdtypes.html#dict)) \[*matching-items*\]**965966Преобразует последовательность значений C в словарь Python. Каждая пара последовательных значений C добавляет один элемент в словарь, выступая в роли ключа и значения соответственно.967968Если в строке формата есть ошибка, устанавливается исключение [`SystemError`](https://python-all.ru/3.2/library/exceptions.html#SystemError) и возвращается *NULL*.969970#### `PyObject* Py_VaBuildValue(const char *format, va_list vargs)`971972Идентична [`Py_BuildValue()`](https://python-all.ru/3.2/c-api/arg.html#Py_BuildValue), за исключением того, что принимает va\_list вместо переменного числа аргументов.973