`arg.md`

991 строк · 52.6 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.3/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.3/extending/index.html#extending-index).1011Первые три из описанных функций, [`PyArg_ParseTuple()`](https://python-all.ru/3.3/c-api/arg.html#PyArg_ParseTuple), [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.3/c-api/arg.html#PyArg_ParseTupleAndKeywords) и [`PyArg_Parse()`](https://python-all.ru/3.3/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.3/c-api/buffer.html#Py_buffer) заполняется, соответствующий буфер блокируется, чтобы вызывающий код мог затем использовать буфер даже внутри блока [`Py_BEGIN_ALLOW_THREADS`](https://python-all.ru/3.3/c-api/init.html#Py_BEGIN_ALLOW_THREADS) без риска изменения или уничтожения изменяемых данных. Как следствие, **необходимо вызвать** [`PyBuffer_Release()`](https://python-all.ru/3.3/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.3/library/stdtypes.html#str)) \[const char \*\]**3031Преобразует объект Unicode в указатель C на строку символов. Указатель на существующую строку сохраняется в переменной-указателе на символы, адрес которой передаётся. Строка C завершается нулевым символом (NUL). Строка Python не должна содержать встроенных нулевых байтов; если они есть, возбуждается исключение [`TypeError`](https://python-all.ru/3.3/library/exceptions.html#TypeError). Объекты Unicode преобразуются в строки C с использованием кодировки `'utf-8'`. Если это преобразование не удаётся, возбуждается [`UnicodeError`](https://python-all.ru/3.3/library/exceptions.html#UnicodeError).3233> **Примечание**34>35> Этот формат не принимает байтоподобные объекты. Если требуется принимать пути файловой системы и преобразовывать их в строки символов C, предпочтительнее использовать формат `O&` с [`PyUnicode_FSConverter()`](https://python-all.ru/3.3/c-api/unicode.html#PyUnicode_FSConverter) в качестве *преобразователя*.3637**`s*` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3.3/library/functions.html#bytes), [`bytearray`](https://python-all.ru/3.3/library/functions.html#bytearray) or buffer compatible object) \[Py\_buffer\]**3839Этот формат принимает объекты Unicode, а также4041[*байтоподобный объект*](https://python-all.ru/3.3/glossary.html#term-bytes-like-object)4243s. Он заполняет структуру4445[`Py_buffer`](https://python-all.ru/3.3/c-api/buffer.html#Py_buffer)4647, предоставленную вызывающей стороной. В этом случае результирующая C-строка может содержать встроенные нулевые байты (NUL). Объекты Unicode преобразуются в C-строки с использованием кодировки4849`'utf-8'`5051.5253**`s#` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3.3/library/functions.html#bytes) or read-only buffer compatible object) \[const char \*, int or `Py_ssize_t`\]**5455Как5657`s*`5859, за исключением того, что не принимает изменяемые буфероподобные объекты, такие как6061[`bytearray`](https://python-all.ru/3.3/library/functions.html#bytearray)6263. Результат сохраняется в две C-переменные: первая – указатель на C-строку, вторая – её длина. Строка может содержать встроенные нулевые байты. Объекты Unicode преобразуются в C-строки с использованием кодировки6465`'utf-8'`6667.6869**`z` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str) или `None`) \[const char \*\]**7071Аналогично7273`s`7475, но объект Python также может быть7677`None`7879, и в этом случае указатель C устанавливается в8081*NULL*8283.8485**`z*` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3.3/library/functions.html#bytes), [`bytearray`](https://python-all.ru/3.3/library/functions.html#bytearray), buffer compatible object or `None`) \[Py\_buffer\]**8687Как8889`s*`9091, но объект Python также может быть9293`None`9495, и в этом случае поле9697`buf`9899структуры100101[`Py_buffer`](https://python-all.ru/3.3/c-api/buffer.html#Py_buffer)102103устанавливается в104105*NULL*106107.108109**`z#` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3.3/library/functions.html#bytes), read-only buffer compatible object or `None`) \[const char \*, int\]**110111Как112113`s#`114115, но объект Python также может быть116117`None`118119, и в этом случае указатель C устанавливается в120121*NULL*122123.124125**`y` ([`bytes`](https://python-all.ru/3.3/library/functions.html#bytes)) \[const char \*\]**126127Этот формат преобразует объект, подобный байтам, в указатель C на строку символов; он не принимает объекты Unicode. Буфер байтов не должен содержать встроенных нулевых байтов; если они есть, возбуждается исключение128129[`TypeError`](https://python-all.ru/3.3/library/exceptions.html#TypeError)130131.132133**`y*` ([`bytes`](https://python-all.ru/3.3/library/functions.html#bytes), [`bytearray`](https://python-all.ru/3.3/library/functions.html#bytearray) or [*bytes-like object*](https://python-all.ru/3.3/glossary.html#term-bytes-like-object)) \[Py\_buffer\]**134135Этот вариант136137`s*`138139не принимает объекты Unicode, только140141[*байтоподобный объект*](https://python-all.ru/3.3/glossary.html#term-bytes-like-object)142143s.144145**Это рекомендуемый способ приёма двоичных данных.**146147**`y#` ([`bytes`](https://python-all.ru/3.3/library/functions.html#bytes)) \[const char \*, int\]**148149Этот вариант150151`s#`152153не принимает объекты Unicode, только154155[*байтоподобный объект*](https://python-all.ru/3.3/glossary.html#term-bytes-like-object)156157s.158159**`S` ([`bytes`](https://python-all.ru/3.3/library/functions.html#bytes)) \[PyBytesObject \*\]**160161Требует, чтобы объект Python был объектом162163[`bytes`](https://python-all.ru/3.3/library/functions.html#bytes)164165, без попыток преобразования. Возбуждает166167[`TypeError`](https://python-all.ru/3.3/library/exceptions.html#TypeError)168169, если объект не является объектом bytes. Переменная C также может быть объявлена как170171[`PyObject*`](https://python-all.ru/3.3/c-api/structures.html#PyObject)172173.174175**`Y` ([`bytearray`](https://python-all.ru/3.3/library/functions.html#bytearray)) \[PyByteArrayObject \*\]**176177Требует, чтобы объект Python был объектом178179[`bytearray`](https://python-all.ru/3.3/library/functions.html#bytearray)180181, без попыток преобразования. Возбуждает182183[`TypeError`](https://python-all.ru/3.3/library/exceptions.html#TypeError)184185, если объект не является объектом186187[`bytearray`](https://python-all.ru/3.3/library/functions.html#bytearray)188189. Переменная C также может быть объявлена как190191[`PyObject*`](https://python-all.ru/3.3/c-api/structures.html#PyObject)192193.194195**`u` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str)) \[Py\_UNICODE \*\]**196197Преобразует объект Python Unicode в указатель C на буфер символов Unicode, завершающийся нулевым символом. Необходимо передать адрес переменной-указателя [`Py_UNICODE`](https://python-all.ru/3.3/c-api/unicode.html#Py_UNICODE), которая будет заполнена указателем на существующий буфер Unicode. Обратите внимание, что ширина символа [`Py_UNICODE`](https://python-all.ru/3.3/c-api/unicode.html#Py_UNICODE) зависит от опций компиляции (она составляет 16 или 32 бита). Строка Python не должна содержать встроенных нулевых символов; если они есть, возбуждается исключение [`TypeError`](https://python-all.ru/3.3/library/exceptions.html#TypeError).198199> **Примечание**200>201> Поскольку `u` не возвращает длину строки, и она может содержать встроенные нулевые символы, рекомендуется использовать вместо него `u#` или `U`.202203**`u#` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str)) \[Py\_UNICODE \*, int\]**204205Этот вариант206207`u`208209сохраняет значения в две переменные C: первая – указатель на буфер данных Unicode, вторая – его длину.210211**`Z` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str) или `None`) \[Py\_UNICODE \*\]**212213Как и214215`u`216217, но объект Python также может быть218219`None`220221, и в этом случае указатель222223[`Py_UNICODE`](https://python-all.ru/3.3/c-api/unicode.html#Py_UNICODE)224225устанавливается в226227*NULL*228229.230231**`Z#` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str) или `None`) \[Py\_UNICODE \*, int\]**232233Как и234235`u#`236237, но объект Python также может быть238239`None`240241, и в этом случае указатель242243[`Py_UNICODE`](https://python-all.ru/3.3/c-api/unicode.html#Py_UNICODE)244245устанавливается в246247*NULL*248249.250251**`U` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str)) \[PyObject \*\]**252253Требует, чтобы объект Python был объектом Unicode, без попыток какого-либо преобразования. Возбуждает254255[`TypeError`](https://python-all.ru/3.3/library/exceptions.html#TypeError)256257, если объект не является объектом Unicode. Переменная C также может быть объявлена как258259[`PyObject*`](https://python-all.ru/3.3/c-api/structures.html#PyObject)260261.262263**`w*` ([`bytearray`](https://python-all.ru/3.3/library/functions.html#bytearray) или буфер для чтения и записи, ориентированный на байты) \[Py\_buffer\]**264265Этот формат принимает любой объект, реализующий интерфейс буфера для чтения и записи. Он заполняет структуру266267[`Py_buffer`](https://python-all.ru/3.3/c-api/buffer.html#Py_buffer)268269, предоставленную вызывающим кодом. Буфер может содержать встроенные нулевые байты. Вызывающий код должен вызвать270271[`PyBuffer_Release()`](https://python-all.ru/3.3/c-api/buffer.html#PyBuffer_Release)272273после завершения работы с буфером.274275**`es` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str)) \[const char \*encoding, char \*\*buffer\]**276277Этот вариант `s` используется для кодирования Unicode в символьный буфер. Он работает только с закодированными данными без встроенных NUL-байтов.278279Этот формат требует два аргумента. Первый используется только как входной и должен быть `const char*`, указывающим на имя кодировки в виде NUL-терминированной строки, или *NULL*, в этом случае используется кодировка `'utf-8'`. Если указанная кодировка неизвестна Python, возбуждается исключение. Второй аргумент должен быть `char**`; значение указателя, на который он ссылается, будет установлено в буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, указанной первым аргументом.280281[`PyArg_ParseTuple()`](https://python-all.ru/3.3/c-api/arg.html#PyArg_ParseTuple) выделит буфер необходимого размера, скопирует закодированные данные в этот буфер и настроит *\*buffer* так, чтобы он ссылался на новую выделенную память. Вызывающий код отвечает за вызов [`PyMem_Free()`](https://python-all.ru/3.3/c-api/memory.html#PyMem_Free) для освобождения выделенного буфера после использования.282283**`et` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3.3/library/functions.html#bytes) или [`bytearray`](https://python-all.ru/3.3/library/functions.html#bytearray)) \[const char \*encoding, char \*\*buffer\]**284285То же, что и286287`es`288289, за исключением того, что объекты-байтовые строки передаются без перекодирования. Вместо этого реализация предполагает, что объект-байтовая строка использует кодировку, переданную в качестве параметра.290291**`es#` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str)) \[const char \*encoding, char \*\*buffer, int \*buffer\_length\]**292293Этот вариант `s#` используется для кодирования Unicode в символьный буфер. В отличие от формата `es`, этот вариант допускает входные данные, содержащие NUL-символы.294295Требуются три аргумента. Первый используется только как входной и должен быть `const char*`, указывающим на имя кодировки в виде NUL-терминированной строки, или *NULL*, в этом случае используется кодировка `'utf-8'`. Если указанная кодировка неизвестна Python, возбуждается исключение. Второй аргумент должен быть `char**`; значение указателя, на который он ссылается, будет установлено в буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, указанной первым аргументом. Третий аргумент должен быть указателем на целое число; целое число, на которое он ссылается, будет установлено в количество байтов в выходном буфере.296297Существует два режима работы:298299Если *\*buffer* указывает на указатель *NULL*, функция выделит буфер необходимого размера, скопирует закодированные данные в этот буфер и установит *\*buffer* так, чтобы он ссылался на новую выделенную память. Вызывающий код отвечает за вызов [`PyMem_Free()`](https://python-all.ru/3.3/c-api/memory.html#PyMem_Free) для освобождения выделенного буфера после использования.300301Если *\*buffer* указывает на не-*NULL* указатель (уже выделенный буфер), [`PyArg_ParseTuple()`](https://python-all.ru/3.3/c-api/arg.html#PyArg_ParseTuple) будет использовать это место как буфер и интерпретировать начальное значение *\*buffer\_length* как размер буфера. Затем он скопирует закодированные данные в буфер и завершит его NUL. Если буфер недостаточно велик, будет установлено [`ValueError`](https://python-all.ru/3.3/library/exceptions.html#ValueError).302303В обоих случаях *\*buffer\_length* устанавливается в длину закодированных данных без завершающего NUL-байта.304305**`et#` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3.3/library/functions.html#bytes) или [`bytearray`](https://python-all.ru/3.3/library/functions.html#bytearray)) \[const char \*encoding, char \*\*buffer, int \*buffer\_length\]**306307То же, что и308309`es#`310311, за исключением того, что объекты-байтовые строки передаются без перекодирования. Вместо этого реализация предполагает, что объект-байтовая строка использует кодировку, переданную в качестве параметра.312313### Числа314315**`b` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[unsigned char\]**316317Преобразует неотрицательное целое число Python в беззнаковое крошечное целое, хранящееся в C318319`unsigned char`320321.322323**`B` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[unsigned char\]**324325Преобразует целое число Python в крошечное целое без проверки переполнения, хранящееся в C326327`unsigned char`328329.330331**`h` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[short int\]**332333Преобразует целое число Python в C334335`short int`336337.338339**`H` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[unsigned short int\]**340341Преобразует целое число Python в C342343`unsigned short int`344345без проверки переполнения.346347**`i` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[int\]**348349Преобразует целое число Python в обычный C350351`int`352353.354355**`I` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[unsigned int\]**356357Преобразует целое число Python в C358359`unsigned int`360361без проверки переполнения.362363**`l` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[long int\]**364365Преобразует целое число Python в C366367`long int`368369.370371**`k` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[unsigned long\]**372373Преобразует целое число Python в C374375`unsigned long`376377без проверки переполнения.378379**`L` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[PY\_LONG\_LONG\]**380381Преобразует целое число Python в C382383`long long`384385. Этот формат доступен только на платформах, поддерживающих386387`long long`388389(или390391`_int64`392393на Windows).394395**`K` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[unsigned PY\_LONG\_LONG\]**396397Преобразует целое число Python в C398399`unsigned long long`400401без проверки переполнения. Этот формат доступен только на платформах, поддерживающих402403`unsigned long long`404405(или406407`unsigned _int64`408409на Windows).410411**`n` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[Py\_ssize\_t\]**412413Преобразует целое число Python в C414415`Py_ssize_t`416417.418419**`c` ([`bytes`](https://python-all.ru/3.3/library/functions.html#bytes) или [`bytearray`](https://python-all.ru/3.3/library/functions.html#bytearray) длиной 1) \[char\]**420421Преобразует байт Python, представленный как объект [`bytes`](https://python-all.ru/3.3/library/functions.html#bytes) или [`bytearray`](https://python-all.ru/3.3/library/functions.html#bytearray) длиной 1, в C `char`.422423Изменено в версии 3.3: Разрешены объекты [`bytearray`](https://python-all.ru/3.3/library/functions.html#bytearray).424425**`C` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str) длиной 1) \[int\]**426427Преобразует символ Python, представленный как объект428429[`str`](https://python-all.ru/3.3/library/stdtypes.html#str)430431длиной 1, в C432433`int`434435.436437**`f` ([`float`](https://python-all.ru/3.3/library/functions.html#float)) \[float\]**438439Преобразует число с плавающей запятой Python в C440441`float`442443.444445**`d` ([`float`](https://python-all.ru/3.3/library/functions.html#float)) \[double\]**446447Преобразует число с плавающей запятой Python в C448449`double`450451.452453**`D` ([`complex`](https://python-all.ru/3.3/library/functions.html#complex)) \[Py\_complex\]**454455Преобразует комплексное число Python в структуру C456457[`Py_complex`](https://python-all.ru/3.3/c-api/complex.html#Py_complex)458459.460461### Другие объекты462463**`O` (объект) \[PyObject \*\]**464465Сохраняет объект Python (без какого-либо преобразования) в указателе на объект C. Таким образом, программа на C получает фактически переданный объект. Счётчик ссылок объекта не увеличивается. Сохранённый указатель не равен466467*NULL*468469.470471**`O!` (object) \[*typeobject*, PyObject \*\]**472473Сохраняет объект Python в указателе на объект C. Это похоже на474475`O`476477, но принимает два аргумента C: первый – адрес объекта типа Python, второй – адрес переменной C (типа478479[`PyObject*`](https://python-all.ru/3.3/c-api/structures.html#PyObject)480481), в который сохраняется указатель на объект. Если объект Python не имеет требуемого типа, вызывается482483[`TypeError`](https://python-all.ru/3.3/library/exceptions.html#TypeError)484485.486487**`O&` (объект) \[*converter*, *anything*\]**488489Преобразует объект Python в переменную C через функцию *converter*. Эта функция принимает два аргумента: первый – это функция, второй – адрес переменной C (произвольного типа), преобразованный к `void *`. Функция *converter* в свою очередь вызывается следующим образом:490491```c492status = converter(object, address);493```494495где *object* – это объект Python, который нужно преобразовать, а *address* – это аргумент `void*`, переданный функции [`PyArg_Parse*()`](https://python-all.ru/3.3/c-api/arg.html#PyArg_Parse). Возвращаемое значение *status* должно быть `1` при успешном преобразовании и `0` при неудаче. В случае ошибки функция *converter* должна возбудить исключение и оставить содержимое *address* без изменений.496497Если *converter* возвращает `Py_CLEANUP_SUPPORTED`, она может быть вызвана второй раз, если разбор аргументов в конечном итоге завершится неудачей, давая конвертеру возможность освободить любую память, которую он уже выделил. При этом втором вызове параметр *object* будет равен NULL; *address* будет иметь то же значение, что и при исходном вызове.498499Изменено в версии 3.1: `Py_CLEANUP_SUPPORTED` была добавлена.500501**`p` ([`bool`](https://python-all.ru/3.3/library/functions.html#bool)) \[int\]**502503Проверяет переданное значение на истинность (булев **p**редикат) и преобразует результат в эквивалентное целое значение C true/false. Устанавливает int в 1, если выражение истинно, и в 0, если ложно. Принимает любое допустимое значение Python. См. [*Проверка значений на истинность*](https://python-all.ru/3.3/library/stdtypes.html#truth) для получения дополнительной информации о том, как Python проверяет значения на истинность.504505Новое в версии 3.3.506507**`(items)` ([`tuple`](https://python-all.ru/3.3/library/stdtypes.html#tuple)) \[*matching-items*\]**508509Объект должен быть последовательностью Python, длина которой равна количеству единиц формата в510511*элементах*512513. Аргументы C должны соответствовать отдельным единицам формата в514515*элементах*516517. Единицы формата для последовательностей могут быть вложенными.518519Можно передавать «длинные» целые числа (целые, значение которых превышает `LONG_MAX` платформы), однако надлежащая проверка диапазона не выполняется – старшие биты молча отбрасываются, когда принимающее поле слишком мало для значения (на самом деле, семантика унаследована от понижающих приведений в C – результат может отличаться).520521Некоторые другие символы имеют значение в строке формата. Они не могут встречаться внутри вложенных скобок. Вот они:522523**`|`**524525Указывает, что остальные аргументы в списке аргументов Python являются необязательными. Переменные C, соответствующие необязательным аргументам, должны быть инициализированы значением по умолчанию – если необязательный аргумент не указан,526527[`PyArg_ParseTuple()`](https://python-all.ru/3.3/c-api/arg.html#PyArg_ParseTuple)528529не изменяет содержимое соответствующих переменных C.530531**`$`**532533Только для [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.3/c-api/arg.html#PyArg_ParseTupleAndKeywords): Указывает, что остальные аргументы в списке аргументов Python являются только ключевыми. В настоящее время все аргументы, передаваемые только по ключу, также должны быть необязательными, поэтому `|` всегда должен указываться перед `$` в строке формата.534535Новое в версии 3.3.536537**`:`**538539Список единиц формата заканчивается здесь; строка после двоеточия используется как имя функции в сообщениях об ошибках («связанное значение» исключения, которое возбуждает540541[`PyArg_ParseTuple()`](https://python-all.ru/3.3/c-api/arg.html#PyArg_ParseTuple)542543).544545**`;`**546547Список единиц форматирования заканчивается здесь; строка после точки с запятой используется как сообщение об ошибке548549*вместо*550551сообщения об ошибке по умолчанию.552553`:`554555и556557`;`558559взаимно исключают друг друга.560561Обратите внимание, что любые ссылки на объекты Python, передаваемые вызывающему, являются *заимствованными* ссылками; уменьшать их счётчик ссылок не следует.562563Дополнительные аргументы, передаваемые этим функциям, должны быть адресами переменных, тип которых определяется строкой формата; они используются для хранения значений из входного кортежа. Есть несколько случаев, как описано в списке единиц форматирования выше, когда эти параметры используются в качестве входных значений; в этом случае они должны соответствовать тому, что указано для соответствующей единицы форматирования.564565Чтобы преобразование прошло успешно, объект *arg* должен соответствовать формату, а формат должен быть исчерпан. В случае успеха функции [`PyArg_Parse*()`](https://python-all.ru/3.3/c-api/arg.html#PyArg_Parse) возвращают true, иначе возвращают false и возбуждают соответствующее исключение. Когда функции [`PyArg_Parse*()`](https://python-all.ru/3.3/c-api/arg.html#PyArg_Parse) завершаются ошибкой из-за сбоя преобразования в одной из единиц формата, переменные по адресам, соответствующим этой и следующим единицам формата, остаются нетронутыми.566567### API функции568569#### `int PyArg_ParseTuple(PyObject *args, const char *format, ...)`570571Разбирает параметры функции, принимающей только позиционные параметры, в локальные переменные. Возвращает true при успехе; при неудаче возвращает false и возбуждает соответствующее исключение.572573#### `int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)`574575Идентична [`PyArg_ParseTuple()`](https://python-all.ru/3.3/c-api/arg.html#PyArg_ParseTuple), за исключением того, что принимает va\_list вместо переменного числа аргументов.576577#### `int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)`578579Разбирает параметры функции, которая принимает как позиционные, так и именованные параметры, в локальные переменные. Возвращает true в случае успеха; в случае неудачи возвращает false и возбуждает соответствующее исключение.580581#### `int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)`582583Идентична [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.3/c-api/arg.html#PyArg_ParseTupleAndKeywords), за исключением того, что принимает va\_list вместо переменного числа аргументов.584585#### `int PyArg_ValidateKeywordArguments(PyObject *)`586587Гарантирует, что ключи в словаре аргументов keywords являются строками. Это требуется только в том случае, если [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.3/c-api/arg.html#PyArg_ParseTupleAndKeywords) не используется, поскольку последняя уже выполняет эту проверку.588589Новое в версии 3.2.590591#### `int PyArg_Parse(PyObject *args, const char *format, ...)`592593Функция, используемая для разбора списков аргументов «старых» функций – это функции, использующие `METH_OLDARGS` разбор параметров метод. Не рекомендуется использовать его для разбора параметров в новом коде, и большая часть кода в стандартном интерпретаторе была изменена, чтобы больше не использовать этот метод для этой цели. Тем не менее, он остаётся удобным способом разложения других кортежей, однако и может по-прежнему использоваться для этой цели.594595#### `int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)`596597Более простая форма извлечения параметров, которая не использует строку формата для указания типов аргументов. Функции, использующие этот метод для извлечения параметров, должны быть объявлены как [`METH_VARARGS`](https://python-all.ru/3.3/c-api/structures.html#METH_VARARGS) в таблицах функций или методов. Кортеж, содержащий фактические параметры, должен передаваться как *args*; он должен быть именно кортежем. Длина кортежа должна быть не менее *min* и не более *max*; *min* и *max* могут быть равны. Дополнительные аргументы должны быть переданы функции, каждый из которых должен быть указателем на переменную [`PyObject*`](https://python-all.ru/3.3/c-api/structures.html#PyObject); они будут заполнены значениями из *args*; они будут содержать заимствованные ссылки. Переменные, соответствующие необязательным параметрам, не указанным в *args*, не будут заполнены; они должны быть инициализированы вызывающей стороной. Эта функция возвращает true при успехе и false, если *args* не является кортежем или содержит неверное количество элементов; в случае неудачи будет установлено исключение.598599Это пример использования этой функции, взятый из исходников вспомогательного модуля слабых ссылок `_weakref`:600601```c602static PyObject *603weakref_ref(PyObject *self, PyObject *args)604{605    PyObject *object;606    PyObject *callback = NULL;607    PyObject *result = NULL;608609    if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {610        result = PyWeakref_NewRef(object, callback);611    }612    return result;613}614```615616Вызов [`PyArg_UnpackTuple()`](https://python-all.ru/3.3/c-api/arg.html#PyArg_UnpackTuple) в этом примере полностью эквивалентен следующему вызову [`PyArg_ParseTuple()`](https://python-all.ru/3.3/c-api/arg.html#PyArg_ParseTuple):617618```c619PyArg_ParseTuple(args, "O|O:ref", &object, &callback)620```621622## Построение значений623624#### `PyObject* Py_BuildValue(const char *format, ...)`625626*Возвращаемое значение: новая ссылка.*627628Создаёт новое значение на основе строки формата, аналогичной тем, которые принимаются семейством функций [`PyArg_Parse*()`](https://python-all.ru/3.3/c-api/arg.html#PyArg_Parse), и последовательности значений. Возвращает значение или *NULL* в случае ошибки; если возвращается *NULL*, будет возбуждено исключение.629630[`Py_BuildValue()`](https://python-all.ru/3.3/c-api/arg.html#Py_BuildValue) не всегда строит кортеж. Он строит кортеж, только если его строка формата содержит две или более единиц формата. Если строка формата пуста, она возвращает `None`; если содержит ровно одну единицу формата, возвращает объект, описываемый этой единицей формата. Чтобы принудительно вернуть кортеж размером 0 или 1, заключите строку формата в скобки.631632Когда буферы памяти передаются в качестве параметров для предоставления данных для построения объектов, как для форматов `s` и `s#`, необходимые данные копируются. Буферы, предоставленные вызывающей стороной, никогда не используются напрямую объектами, созданными [`Py_BuildValue()`](https://python-all.ru/3.3/c-api/arg.html#Py_BuildValue). Другими словами, если ваш код вызывает `malloc()` и передаёт выделенную память в [`Py_BuildValue()`](https://python-all.ru/3.3/c-api/arg.html#Py_BuildValue), ваш код отвечает за вызов `free()` для этой памяти после возврата из [`Py_BuildValue()`](https://python-all.ru/3.3/c-api/arg.html#Py_BuildValue).633634В следующем описании форма в кавычках – это элемент формата; запись в круглых скобках – это тип объекта Python, который вернёт элемент формата; а запись в квадратных скобках – это тип передаваемого(-ых) значения(-ий) C.635636Символы пробела, табуляции, двоеточия и запятой игнорируются в строках формата (но не внутри единиц формата, таких как `s#`). Это позволяет сделать длинные строки формата немного более читаемыми.637638**`s` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str) или `None`) \[char \*\]**639640Преобразует C-строку, завершающуюся нулевым символом, в объект Python641642[`str`](https://python-all.ru/3.3/library/stdtypes.html#str)643644с использованием кодировки645646`'utf-8'`647648. Если указатель на C-строку равен649650*NULL*651652, используется653654`None`655656.657658**`s#` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str) или `None`) \[char \*, int\]**659660Преобразует C-строку и её длину в объект Python661662[`str`](https://python-all.ru/3.3/library/stdtypes.html#str)663664с использованием кодировки665666`'utf-8'`667668. Если указатель на C-строку равен669670*NULL*671672, длина игнорируется и возвращается673674`None`675676.677678**`y` ([`bytes`](https://python-all.ru/3.3/library/functions.html#bytes)) \[char \*\]**679680Преобразует C-строку в объект Python681682[`bytes`](https://python-all.ru/3.3/library/functions.html#bytes)683684. Если указатель на C-строку равен685686*NULL*687688, возвращается689690`None`691692.693694**`y#` ([`bytes`](https://python-all.ru/3.3/library/functions.html#bytes)) \[char \*, int\]**695696Преобразует C-строку и её длину в объект Python. Если указатель на C-строку равен697698*NULL*699700, возвращается701702`None`703704.705706**`z` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str) или `None`) \[char \*\]**707708То же, что и709710`s`711712.713714**`z#` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str) или `None`) \[char \*, int\]**715716То же, что и717718`s#`719720.721722**`u` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str)) \[Py\_UNICODE \*\]**723724Преобразует буфер с нулевым символом в конце, содержащий данные Unicode (UCS-2 или UCS-4), в объект Unicode Python. Если указатель буфера Unicode равен725726*NULL*727728, возвращается729730`None`731732.733734**`u#` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str)) \[Py\_UNICODE \*, int\]**735736Преобразует буфер данных Unicode (UCS-2 или UCS-4) и его длину в объект Unicode Python. Если указатель буфера Unicode равен737738*NULL*739740, длина игнорируется и возвращается741742`None`743744.745746**`U` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str) или `None`) \[char \*\]**747748То же, что и749750`s`751752.753754**`U#` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str) или `None`) \[char \*, int\]**755756То же, что и757758`s#`759760.761762**`i` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[int\]**763764Преобразует обычный C765766`int`767768в объект Python целого типа.769770**`b` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[char\]**771772Преобразует обычный C773774`char`775776в объект Python целого типа.777778**`h` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[short int\]**779780Преобразует обычное C781782`short int`783784в объект Python int.785786**`l` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[long int\]**787788Преобразует C789790`long int`791792в объект Python int.793794**`B` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[unsigned char\]**795796Преобразует C797798`unsigned char`799800в объект Python int.801802**`H` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[unsigned short int\]**803804Преобразует C805806`unsigned short int`807808в объект Python int.809810**`I` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[unsigned int\]**811812Преобразует C813814`unsigned int`815816в объект Python int.817818**`k` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[unsigned long\]**819820Преобразует C821822`unsigned long`823824в объект Python int.825826**`L` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[PY\_LONG\_LONG\]**827828Преобразует C829830`long long`831832в объект Python int. Доступно только на платформах, поддерживающих833834`long long`835836(или837838`_int64`839840в Windows).841842**`K` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[unsigned PY\_LONG\_LONG\]**843844Преобразует C845846`unsigned long long`847848в объект Python int. Доступно только на платформах, поддерживающих849850`unsigned long long`851852(или853854`unsigned _int64`855856в Windows).857858**`n` ([`int`](https://python-all.ru/3.3/library/functions.html#int)) \[Py\_ssize\_t\]**859860Преобразует C861862`Py_ssize_t`863864в Python int.865866**`c` ([`bytes`](https://python-all.ru/3.3/library/functions.html#bytes) длиной 1) \[char\]**867868Преобразует C869870`int`871872, представляющий байт, в объект Python873874[`bytes`](https://python-all.ru/3.3/library/functions.html#bytes)875876длиной 1.877878**`C` ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str) длиной 1) \[int\]**879880Преобразует C881882`int`883884, представляющий символ, в объект Python885886[`str`](https://python-all.ru/3.3/library/stdtypes.html#str)887888длиной 1.889890**`d` ([`float`](https://python-all.ru/3.3/library/functions.html#float)) \[double\]**891892Преобразует C893894`double`895896в число с плавающей точкой Python.897898**`f` ([`float`](https://python-all.ru/3.3/library/functions.html#float)) \[float\]**899900Преобразует C901902`float`903904в число с плавающей точкой Python.905906**`D` ([`complex`](https://python-all.ru/3.3/library/functions.html#complex)) \[Py\_complex \*\]**907908Преобразует структуру C909910[`Py_complex`](https://python-all.ru/3.3/c-api/complex.html#Py_complex)911912в комплексное число Python.913914**`O` (объект) \[PyObject \*\]**915916Передаёт объект Python без изменений (за исключением счётчика ссылок, который увеличивается на единицу). Если переданный объект является указателем917918*NULL*919920, считается, что это произошло из-за того, что вызов, формирующий аргумент, обнаружил ошибку и установил исключение. Поэтому921922[`Py_BuildValue()`](https://python-all.ru/3.3/c-api/arg.html#Py_BuildValue)923924вернёт925926*NULL*927928, но не вызовет исключение. Если ещё не было установлено никакого исключения, устанавливается929930[`SystemError`](https://python-all.ru/3.3/library/exceptions.html#SystemError)931932.933934**`S` (объект) \[PyObject \*\]**935936То же, что и937938`O`939940.941942**`N` (объект) \[PyObject \*\]**943944То же, что и945946`O`947948, за исключением того, что не увеличивает счётчик ссылок на объект. Полезно, когда объект создаётся вызовом конструктора объекта в списке аргументов.949950**`O&` (объект) \[*converter*, *anything*\]**951952Преобразует953954*anything*955956в объект Python с помощью функции957958*converter*959960. Функция вызывается с аргументом961962*anything*963964(который должен быть совместим с965966`void *`967968) и должна возвращать «новый» объект Python или969970*NULL*971972в случае ошибки.973974**`(items)` ([`tuple`](https://python-all.ru/3.3/library/stdtypes.html#tuple)) \[*matching-items*\]**975976Преобразует последовательность значений C в кортеж Python с тем же количеством элементов.977978**`[items]` ([`list`](https://python-all.ru/3.3/library/stdtypes.html#list)) \[*matching-items*\]**979980Преобразует последовательность значений C в список Python с тем же количеством элементов.981982**`{items}` ([`dict`](https://python-all.ru/3.3/library/stdtypes.html#dict)) \[*matching-items*\]**983984Преобразует последовательность значений C в словарь Python. Каждая пара последовательных значений C добавляет один элемент в словарь, выступая в роли ключа и значения соответственно.985986Если в строке формата есть ошибка, устанавливается исключение [`SystemError`](https://python-all.ru/3.3/library/exceptions.html#SystemError) и возвращается *NULL*.987988#### `PyObject* Py_VaBuildValue(const char *format, va_list vargs)`989990Идентична [`Py_BuildValue()`](https://python-all.ru/3.3/c-api/arg.html#Py_BuildValue), за исключением того, что принимает va\_list вместо переменного числа аргументов.991