`arg.md`

1051 строк · 52.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.1/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.1/extending/index.html#extending-index).1011Первые три из описанных функций, [`PyArg_ParseTuple()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_ParseTuple), [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_ParseTupleAndKeywords) и [`PyArg_Parse()`](https://python-all.ru/3.1/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.1/c-api/buffer.html#Py_buffer) заполняется, соответствующий буфер блокируется, чтобы вызывающий код мог затем использовать буфер даже внутри блока [`Py_BEGIN_ALLOW_THREADS`](https://python-all.ru/3.1/c-api/init.html#Py_BEGIN_ALLOW_THREADS) без риска изменения или уничтожения изменяемых данных. Как следствие, **необходимо вызвать** [`PyBuffer_Release()`](https://python-all.ru/3.1/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.1/library/functions.html#str)) \[const char \*\]**3031Преобразует объект Unicode в указатель C на строку символов. Указатель на существующую строку сохраняется в переменной-указателе на символы, адрес которой передаётся. Строка C завершается нулевым символом (NUL). Строка Python не должна содержать встроенных нулевых байтов; если они есть, возбуждается исключение [`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError). Объекты Unicode преобразуются в строки C с использованием кодировки `'utf-8'`. Если это преобразование не удаётся, возбуждается [`UnicodeError`](https://python-all.ru/3.1/library/exceptions.html#UnicodeError).3233> **Примечание**34>35> Этот формат не принимает байтоподобные объекты. Если требуется принимать пути файловой системы и преобразовывать их в строки символов C, предпочтительнее использовать формат `O&` с [`PyUnicode_FSConverter()`](https://python-all.ru/3.1/c-api/unicode.html#PyUnicode_FSConverter) в качестве *преобразователя*.3637**`s*` ([`str`](https://python-all.ru/3.1/library/functions.html#str), [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes), [`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray) или объект, совместимый с буфером) \[Py\_buffer\]**3839Этот формат принимает Unicode-объекты, а также объекты, поддерживающие протокол буфера. Он заполняет структуру4041[`Py_buffer`](https://python-all.ru/3.1/c-api/buffer.html#Py_buffer)4243, предоставленную вызывающей стороной. В этом случае результирующая C-строка может содержать встроенные NUL-байты. Unicode-объекты преобразуются в C-строки с использованием кодировки4445`'utf-8'`4647.4849**`s#` ([`str`](https://python-all.ru/3.1/library/functions.html#str), [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes) или объект, совместимый с буфером только для чтения) \[const char \*, int или `Py_ssize_t`\]**5051Как5253`s*`5455, за исключением того, что не принимает изменяемые буфероподобные объекты, такие как5657[`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray)5859. Результат сохраняется в две C-переменные: первая – указатель на C-строку, вторая – её длина. Строка может содержать встроенные нулевые байты. Объекты Unicode преобразуются в C-строки с использованием кодировки6061`'utf-8'`6263.6465**`z` ([`str`](https://python-all.ru/3.1/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.1/library/functions.html#str), [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes), [`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray), объект, совместимый с буфером или `None`) \[Py\_buffer\]**8283Как8485`s*`8687, но объект Python также может быть8889`None`9091, и в этом случае поле9293`buf`9495структуры9697[`Py_buffer`](https://python-all.ru/3.1/c-api/buffer.html#Py_buffer)9899устанавливается в100101*NULL*102103.104105**`z#` ([`str`](https://python-all.ru/3.1/library/functions.html#str), [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes), объект, совместимый с буфером только для чтения или `None`) \[const char \*, int\]**106107Как108109`s#`110111, но объект Python также может быть112113`None`114115, и в этом случае указатель C устанавливается в116117*NULL*118119.120121**`y` ([`bytes`](https://python-all.ru/3.1/library/functions.html#bytes)) \[const char \*\]**122123Этот формат преобразует объект, подобный байтам, в указатель C на строку символов; он не принимает объекты Unicode. Буфер байтов не должен содержать встроенных нулевых байтов; если они есть, возбуждается исключение124125[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)126127.128129**`y*` ([`bytes`](https://python-all.ru/3.1/library/functions.html#bytes), [`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray) или объект, совместимый с буфером) \[Py\_buffer\]**130131Этот вариант132133`s*`134135не принимает Unicode-объекты, только объекты, поддерживающие протокол буфера.136137**Это рекомендуемый способ приёма двоичных данных.**138139**`y#` ([`bytes`](https://python-all.ru/3.1/library/functions.html#bytes)) \[const char \*, int\]**140141Этот вариант142143`s#`144145не принимает объекты Unicode, только объекты, подобные байтам.146147**`S` ([`bytes`](https://python-all.ru/3.1/library/functions.html#bytes)) \[PyBytesObject \*\]**148149Требует, чтобы объект Python был объектом150151[`bytes`](https://python-all.ru/3.1/library/functions.html#bytes)152153, без попыток преобразования. Возбуждает154155[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)156157, если объект не является объектом bytes. Переменная C также может быть объявлена как158159[`PyObject*`](https://python-all.ru/3.1/c-api/structures.html#PyObject)160161.162163**`Y` ([`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray)) \[PyByteArrayObject \*\]**164165Требует, чтобы объект Python был объектом166167[`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray)168169, без попыток преобразования. Возбуждает170171[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)172173, если объект не является объектом174175[`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray)176177. Переменная C также может быть объявлена как178179[`PyObject*`](https://python-all.ru/3.1/c-api/structures.html#PyObject)180181.182183**`u` ([`str`](https://python-all.ru/3.1/library/functions.html#str)) \[Py\_UNICODE \*\]**184185Преобразует объект Python Unicode в указатель C на буфер Unicode, завершающийся NUL. Необходимо передать адрес переменной-указателя [`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE), которая будет заполнена указателем на существующий буфер Unicode. Обратите внимание, что ширина символа [`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) зависит от опций компиляции (она составляет 16 или 32 бита).186187> **Примечание**188>189> Поскольку `u` не возвращает длину строки, и она может содержать встроенные нулевые символы, рекомендуется использовать вместо него `u#` или `U`.190191**`u#` ([`str`](https://python-all.ru/3.1/library/functions.html#str)) \[Py\_UNICODE \*, int\]**192193Этот вариант194195`u`196197сохраняет значения в две переменные C: первая – указатель на буфер данных Unicode, вторая – его длину.198199**`Z` ([`str`](https://python-all.ru/3.1/library/functions.html#str) или `None`) \[Py\_UNICODE \*\]**200201Как и202203`u`204205, но объект Python также может быть206207`None`208209, и в этом случае указатель210211[`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE)212213устанавливается в214215*NULL*216217.218219**`Z#` ([`str`](https://python-all.ru/3.1/library/functions.html#str) или `None`) \[Py\_UNICODE \*, int\]**220221Как и222223`u#`224225, но объект Python также может быть226227`None`228229, и в этом случае указатель230231[`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE)232233устанавливается в234235*NULL*236237.238239**`U` ([`str`](https://python-all.ru/3.1/library/functions.html#str)) \[PyUnicodeObject \*\]**240241Требует, чтобы объект Python был объектом Unicode, без попыток какого-либо преобразования. Возбуждает242243[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)244245, если объект не является объектом Unicode. Переменная C также может быть объявлена как246247[`PyObject*`](https://python-all.ru/3.1/c-api/structures.html#PyObject)248249.250251**`t#` ([`bytes`](https://python-all.ru/3.1/library/functions.html#bytes), [`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray) или буфер символов только для чтения) \[char \*, int\]**252253Как и254255`s#`256257, но принимает любой объект, реализующий интерфейс буфера только для чтения. Переменная258259`char*`260261устанавливается указателем на первый байт буфера, а262263`int`264265– длиной буфера. Принимаются только объекты с односегментным буфером; для всех остальных возбуждается266267[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)268269.270271**`w` ([`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray) или буфер символов для чтения и записи) \[char \*\]**272273Похож на274275`y`276277, но принимает любой объект, реализующий интерфейс буфера для чтения и записи. Вызывающая сторона должна определить длину буфера иным способом или использовать278279`w#`280281. Принимаются только объекты с односегментным буфером; для всех остальных возбуждается282283[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)284285.286287**`w*` ([`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray) или буфер для чтения и записи, ориентированный на байты) \[Py\_buffer\]**288289Это относится к290291`w`292293так же, как294295`y*`296297относится к298299`y`300301.302303**`w#` ([`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray) или буфер символов для чтения и записи) \[char \*, int\]**304305Как и306307`y#`308309, но принимает любой объект, реализующий интерфейс буфера для чтения и записи. Переменная310311`char *`312313устанавливается указателем на первый байт буфера, а314315`int`316317– длиной буфера. Принимаются только объекты с односегментным буфером; для всех остальных возбуждается318319[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)320321.322323**`es` ([`str`](https://python-all.ru/3.1/library/functions.html#str)) \[const char \*encoding, char \*\*buffer\]**324325Этот вариант `s` используется для кодирования Unicode в символьный буфер. Он работает только с закодированными данными без встроенных NUL-байтов.326327Этот формат требует два аргумента. Первый используется только как входной и должен быть `const char*`, указывающим на имя кодировки в виде NUL-терминированной строки, или *NULL*, в этом случае используется кодировка `'utf-8'`. Если указанная кодировка неизвестна Python, возбуждается исключение. Второй аргумент должен быть `char**`; значение указателя, на который он ссылается, будет установлено в буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, указанной первым аргументом.328329[`PyArg_ParseTuple()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_ParseTuple) выделит буфер необходимого размера, скопирует закодированные данные в этот буфер и настроит *\*buffer* так, чтобы он ссылался на новую выделенную память. Вызывающий код отвечает за вызов [`PyMem_Free()`](https://python-all.ru/3.1/c-api/memory.html#PyMem_Free) для освобождения выделенного буфера после использования.330331**`et` ([`str`](https://python-all.ru/3.1/library/functions.html#str), [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes) или [`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray)) \[const char \*encoding, char \*\*buffer\]**332333То же, что и334335`es`336337, за исключением того, что объекты-байтовые строки передаются без перекодирования. Вместо этого реализация предполагает, что объект-байтовая строка использует кодировку, переданную в качестве параметра.338339**`es#` ([`str`](https://python-all.ru/3.1/library/functions.html#str)) \[const char \*encoding, char \*\*buffer, int \*buffer\_length\]**340341Этот вариант `s#` используется для кодирования Unicode в символьный буфер. В отличие от формата `es`, этот вариант допускает входные данные, содержащие NUL-символы.342343Требуются три аргумента. Первый используется только как входной и должен быть `const char*`, указывающим на имя кодировки в виде NUL-терминированной строки, или *NULL*, в этом случае используется кодировка `'utf-8'`. Если указанная кодировка неизвестна Python, возбуждается исключение. Второй аргумент должен быть `char**`; значение указателя, на который он ссылается, будет установлено в буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, указанной первым аргументом. Третий аргумент должен быть указателем на целое число; целое число, на которое он ссылается, будет установлено в количество байтов в выходном буфере.344345Существует два режима работы:346347Если *\*buffer* указывает на указатель *NULL*, функция выделит буфер необходимого размера, скопирует закодированные данные в этот буфер и установит *\*buffer* так, чтобы он ссылался на новую выделенную память. Вызывающий код отвечает за вызов [`PyMem_Free()`](https://python-all.ru/3.1/c-api/memory.html#PyMem_Free) для освобождения выделенного буфера после использования.348349Если *\*buffer* указывает на не-*NULL* указатель (уже выделенный буфер), [`PyArg_ParseTuple()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_ParseTuple) будет использовать это место как буфер и интерпретировать начальное значение *\*buffer\_length* как размер буфера. Затем он скопирует закодированные данные в буфер и завершит его NUL. Если буфер недостаточно велик, будет установлено [`ValueError`](https://python-all.ru/3.1/library/exceptions.html#ValueError).350351В обоих случаях *\*buffer\_length* устанавливается в длину закодированных данных без завершающего NUL-байта.352353**`et#` ([`str`](https://python-all.ru/3.1/library/functions.html#str), [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes) или [`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray)) \[const char \*encoding, char \*\*buffer, int \*buffer\_length\]**354355То же, что и356357`es#`358359, за исключением того, что объекты-байтовые строки передаются без перекодирования. Вместо этого реализация предполагает, что объект-байтовая строка использует кодировку, переданную в качестве параметра.360361### Числа362363**`b` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned char\]**364365Преобразует неотрицательное целое число Python в беззнаковое крошечное целое, хранящееся в C366367`unsigned char`368369.370371**`B` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned char\]**372373Преобразует целое число Python в крошечное целое без проверки переполнения, хранящееся в C374375`unsigned char`376377.378379**`h` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[short int\]**380381Преобразует целое число Python в C382383`short int`384385.386387**`H` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned short int\]**388389Преобразует целое число Python в C390391`unsigned short int`392393без проверки переполнения.394395**`i` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[int\]**396397Преобразует целое число Python в обычный C398399`int`400401.402403**`I` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned int\]**404405Преобразует целое число Python в C406407`unsigned int`408409без проверки переполнения.410411**`l` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[long int\]**412413Преобразует целое число Python в C414415`long int`416417.418419**`k` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned long\]**420421Преобразует целое число Python в C422423`unsigned long`424425без проверки переполнения.426427**`L` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[PY\_LONG\_LONG\]**428429Преобразует целое число Python в C430431`long long`432433. Этот формат доступен только на платформах, поддерживающих434435`long long`436437(или438439`_int64`440441на Windows).442443**`K` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned PY\_LONG\_LONG\]**444445Преобразует целое число Python в C446447`unsigned long long`448449без проверки переполнения. Этот формат доступен только на платформах, поддерживающих450451`unsigned long long`452453(или454455`unsigned _int64`456457на Windows).458459**`n` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[Py\_ssize\_t\]**460461Преобразует целое число Python в C462463`Py_ssize_t`464465.466467**`c` ([`bytes`](https://python-all.ru/3.1/library/functions.html#bytes) длиной 1) \[char\]**468469Преобразует Python-байт, представленный в виде объекта470471[`bytes`](https://python-all.ru/3.1/library/functions.html#bytes)472473длины 1, в C-тип474475`char`476477.478479**`C` ([`str`](https://python-all.ru/3.1/library/functions.html#str) длиной 1) \[int\]**480481Преобразует символ Python, представленный как объект482483[`str`](https://python-all.ru/3.1/library/functions.html#str)484485длиной 1, в C486487`int`488489.490491**`f` ([`float`](https://python-all.ru/3.1/library/functions.html#float)) \[float\]**492493Преобразует число с плавающей запятой Python в C494495`float`496497.498499**`d` ([`float`](https://python-all.ru/3.1/library/functions.html#float)) \[double\]**500501Преобразует число с плавающей запятой Python в C502503`double`504505.506507**`D` ([`complex`](https://python-all.ru/3.1/library/functions.html#complex)) \[Py\_complex\]**508509Преобразует комплексное число Python в структуру C510511[`Py_complex`](https://python-all.ru/3.1/c-api/complex.html#Py_complex)512513.514515### Другие объекты516517**`O` (объект) \[PyObject \*\]**518519Сохраняет объект Python (без какого-либо преобразования) в указателе на объект C. Таким образом, программа на C получает фактически переданный объект. Счётчик ссылок объекта не увеличивается. Сохранённый указатель не равен520521*NULL*522523.524525**`O!` (object) \[*typeobject*, PyObject \*\]**526527Сохраняет объект Python в указателе на объект C. Это похоже на528529`O`530531, но принимает два аргумента C: первый – адрес объекта типа Python, второй – адрес переменной C (типа532533[`PyObject*`](https://python-all.ru/3.1/c-api/structures.html#PyObject)534535), в который сохраняется указатель на объект. Если объект Python не имеет требуемого типа, вызывается536537[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)538539.540541**`O&` (объект) \[*converter*, *anything*\]**542543Преобразует объект Python в переменную C через функцию *converter*. Эта функция принимает два аргумента: первый – это функция, второй – адрес переменной C (произвольного типа), преобразованный к `void *`. Функция *converter* в свою очередь вызывается следующим образом:544545```c546status = converter(object, address);547```548549где *object* – это объект Python, который нужно преобразовать, а *address* – это аргумент `void*`, переданный функции [`PyArg_Parse*()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_Parse). Возвращаемое значение *status* должно быть `1` при успешном преобразовании и `0` при неудаче. В случае ошибки функция *converter* должна возбудить исключение и оставить содержимое *address* без изменений.550551Если *converter* возвращает `Py_CLEANUP_SUPPORTED`, она может быть вызвана второй раз, если разбор аргументов в конечном итоге завершится неудачей, давая конвертеру возможность освободить любую память, которую он уже выделил. При этом втором вызове параметр *object* будет равен NULL; *address* будет иметь то же значение, что и при исходном вызове.552553Изменено в версии 3.1: `Py_CLEANUP_SUPPORTED` была добавлена.554555**`(items)` ([`tuple`](https://python-all.ru/3.1/library/functions.html#tuple)) \[*matching-items*\]**556557Объект должен быть последовательностью Python, длина которой равна количеству единиц формата в558559*элементах*560561. Аргументы C должны соответствовать отдельным единицам формата в562563*элементах*564565. Единицы формата для последовательностей могут быть вложенными.566567Можно передавать «длинные» целые числа (целые, значение которых превышает `LONG_MAX` платформы), однако надлежащая проверка диапазона не выполняется – старшие биты молча отбрасываются, когда принимающее поле слишком мало для значения (на самом деле, семантика унаследована от понижающих приведений в C – результат может отличаться).568569Некоторые другие символы имеют значение в строке формата. Они не могут встречаться внутри вложенных скобок. Вот они:570571**`|`**572573Указывает, что остальные аргументы в списке аргументов Python являются необязательными. Переменные C, соответствующие необязательным аргументам, должны быть инициализированы значением по умолчанию – если необязательный аргумент не указан,574575[`PyArg_ParseTuple()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_ParseTuple)576577не изменяет содержимое соответствующих переменных C.578579**`:`**580581Список единиц формата заканчивается здесь; строка после двоеточия используется как имя функции в сообщениях об ошибках («связанное значение» исключения, которое возбуждает582583[`PyArg_ParseTuple()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_ParseTuple)584585).586587**`;`**588589Список единиц форматирования заканчивается здесь; строка после точки с запятой используется как сообщение об ошибке590591*вместо*592593сообщения об ошибке по умолчанию.594595`:`596597и598599`;`600601взаимно исключают друг друга.602603Обратите внимание, что любые ссылки на объекты Python, передаваемые вызывающему, являются *заимствованными* ссылками; уменьшать их счётчик ссылок не следует.604605Дополнительные аргументы, передаваемые этим функциям, должны быть адресами переменных, тип которых определяется строкой формата; они используются для хранения значений из входного кортежа. Есть несколько случаев, как описано в списке единиц форматирования выше, когда эти параметры используются в качестве входных значений; в этом случае они должны соответствовать тому, что указано для соответствующей единицы форматирования.606607Чтобы преобразование прошло успешно, объект *arg* должен соответствовать формату, а формат должен быть исчерпан. В случае успеха функции [`PyArg_Parse*()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_Parse) возвращают true, иначе возвращают false и возбуждают соответствующее исключение. Когда функции [`PyArg_Parse*()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_Parse) завершаются ошибкой из-за сбоя преобразования в одной из единиц формата, переменные по адресам, соответствующим этой и следующим единицам формата, остаются нетронутыми.608609### API функции610611**int `PyArg_ParseTuple`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*args*, const char *\*format*, ...)**612613Разбирает параметры функции, принимающей только позиционные параметры, в локальные переменные. Возвращает true при успехе; при неудаче возвращает false и возбуждает соответствующее исключение.614615**int `PyArg_VaParse`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*args*, const char *\*format*, va\_list *vargs*)**616617Идентична618619[`PyArg_ParseTuple()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_ParseTuple)620621, за исключением того, что принимает va\_list вместо переменного числа аргументов.622623**int `PyArg_ParseTupleAndKeywords`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*args*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*kw*, const char *\*format*, char *\*keywords\[\]*, ...)**624625Разбирает параметры функции, которая принимает как позиционные, так и именованные параметры, в локальные переменные. Возвращает true в случае успеха; в случае неудачи возвращает false и возбуждает соответствующее исключение.626627**int `PyArg_VaParseTupleAndKeywords`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*args*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*kw*, const char *\*format*, char *\*keywords\[\]*, va\_list *vargs*)**628629Идентична630631[`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_ParseTupleAndKeywords)632633, за исключением того, что принимает va\_list вместо переменного числа аргументов.634635**int `PyArg_Parse`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*args*, const char *\*format*, ...)**636637Функция, используемая для разбора списков аргументов «старых» функций – это функции, использующие638639`METH_OLDARGS`640641разбор параметров метод. Не рекомендуется использовать его для разбора параметров в новом коде, и большая часть кода в стандартном интерпретаторе была изменена, чтобы больше не использовать этот метод для этой цели. Тем не менее, он остаётся удобным способом разложения других кортежей, однако и может по-прежнему использоваться для этой цели.642643**int `PyArg_UnpackTuple`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*args*, const char *\*name*, Py\_ssize\_t *min*, Py\_ssize\_t *max*, ...)**644645Более простая форма извлечения параметров, которая не использует строку формата для указания типов аргументов. Функции, использующие этот метод для извлечения параметров, должны быть объявлены как [`METH_VARARGS`](https://python-all.ru/3.1/c-api/structures.html#METH_VARARGS) в таблицах функций или методов. Кортеж, содержащий фактические параметры, должен передаваться как *args*; он должен быть именно кортежем. Длина кортежа должна быть не менее *min* и не более *max*; *min* и *max* могут быть равны. Дополнительные аргументы должны быть переданы функции, каждый из которых должен быть указателем на переменную [`PyObject*`](https://python-all.ru/3.1/c-api/structures.html#PyObject); они будут заполнены значениями из *args*; они будут содержать заимствованные ссылки. Переменные, соответствующие необязательным параметрам, не указанным в *args*, не будут заполнены; они должны быть инициализированы вызывающей стороной. Эта функция возвращает true при успехе и false, если *args* не является кортежем или содержит неверное количество элементов; в случае неудачи будет установлено исключение.646647Это пример использования этой функции, взятый из исходников вспомогательного модуля слабых ссылок `_weakref`:648649```c650static PyObject *651weakref_ref(PyObject *self, PyObject *args)652{653    PyObject *object;654    PyObject *callback = NULL;655    PyObject *result = NULL;656657    if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {658        result = PyWeakref_NewRef(object, callback);659    }660    return result;661}662```663664Вызов [`PyArg_UnpackTuple()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_UnpackTuple) в этом примере полностью эквивалентен следующему вызову [`PyArg_ParseTuple()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_ParseTuple):665666```c667PyArg_ParseTuple(args, "O|O:ref", &object, &callback)668```669670## Построение значений671672**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `Py_BuildValue`(const char *\*format*, ...)**673674*Возвращаемое значение: новая ссылка.*675676Создаёт новое значение на основе строки формата, аналогичной тем, которые принимаются семейством функций [`PyArg_Parse*()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_Parse), и последовательности значений. Возвращает значение или *NULL* в случае ошибки; если возвращается *NULL*, будет возбуждено исключение.677678[`Py_BuildValue()`](https://python-all.ru/3.1/c-api/arg.html#Py_BuildValue) не всегда строит кортеж. Он строит кортеж, только если его строка формата содержит две или более единиц формата. Если строка формата пуста, она возвращает `None`; если содержит ровно одну единицу формата, возвращает объект, описываемый этой единицей формата. Чтобы принудительно вернуть кортеж размером 0 или 1, заключите строку формата в скобки.679680Когда буферы памяти передаются в качестве параметров для предоставления данных для построения объектов, как для форматов `s` и `s#`, необходимые данные копируются. Буферы, предоставленные вызывающей стороной, никогда не используются напрямую объектами, созданными [`Py_BuildValue()`](https://python-all.ru/3.1/c-api/arg.html#Py_BuildValue). Другими словами, если ваш код вызывает `malloc()` и передаёт выделенную память в [`Py_BuildValue()`](https://python-all.ru/3.1/c-api/arg.html#Py_BuildValue), ваш код отвечает за вызов `free()` для этой памяти после возврата из [`Py_BuildValue()`](https://python-all.ru/3.1/c-api/arg.html#Py_BuildValue).681682В следующем описании форма в кавычках – это элемент формата; запись в круглых скобках – это тип объекта Python, который вернёт элемент формата; а запись в квадратных скобках – это тип передаваемого(-ых) значения(-ий) C.683684Символы пробела, табуляции, двоеточия и запятой игнорируются в строках формата (но не внутри единиц формата, таких как `s#`). Это позволяет сделать длинные строки формата немного более читаемыми.685686**`s` ([`str`](https://python-all.ru/3.1/library/functions.html#str) или `None`) \[char \*\]**687688Преобразует C-строку, завершающуюся нулевым символом, в объект Python689690[`str`](https://python-all.ru/3.1/library/functions.html#str)691692с использованием кодировки693694`'utf-8'`695696. Если указатель на C-строку равен697698*NULL*699700, используется701702`None`703704.705706**`s#` ([`str`](https://python-all.ru/3.1/library/functions.html#str) или `None`) \[char \*, int\]**707708Преобразует C-строку и её длину в объект Python709710[`str`](https://python-all.ru/3.1/library/functions.html#str)711712с использованием кодировки713714`'utf-8'`715716. Если указатель на C-строку равен717718*NULL*719720, длина игнорируется и возвращается721722`None`723724.725726**`y` ([`bytes`](https://python-all.ru/3.1/library/functions.html#bytes)) \[char \*\]**727728Эта функция преобразует C строку в объект Python729730[`bytes()`](https://python-all.ru/3.1/library/functions.html#bytes)731732. Если указатель на C строку равен733734*NULL*735736, возвращается737738`None`739740.741742**`y#` ([`bytes`](https://python-all.ru/3.1/library/functions.html#bytes)) \[char \*, int\]**743744Преобразует C-строку и её длину в объект Python. Если указатель на C-строку равен745746*NULL*747748, возвращается749750`None`751752.753754**`z` ([`str`](https://python-all.ru/3.1/library/functions.html#str) или `None`) \[char \*\]**755756То же, что и757758`s`759760.761762**`z#` ([`str`](https://python-all.ru/3.1/library/functions.html#str) или `None`) \[char \*, int\]**763764То же, что и765766`s#`767768.769770**`u` ([`str`](https://python-all.ru/3.1/library/functions.html#str)) \[Py\_UNICODE \*\]**771772Преобразует буфер с нулевым символом в конце, содержащий данные Unicode (UCS-2 или UCS-4), в объект Unicode Python. Если указатель буфера Unicode равен773774*NULL*775776, возвращается777778`None`779780.781782**`u#` ([`str`](https://python-all.ru/3.1/library/functions.html#str)) \[Py\_UNICODE \*, int\]**783784Преобразует буфер данных Unicode (UCS-2 или UCS-4) и его длину в объект Unicode Python. Если указатель буфера Unicode равен785786*NULL*787788, длина игнорируется и возвращается789790`None`791792.793794**`U` ([`str`](https://python-all.ru/3.1/library/functions.html#str) или `None`) \[char \*\]**795796Преобразует C-строку, завершающуюся нулевым символом, в объект Python unicode. Если указатель на C-строку равен797798*NULL*799800, используется801802`None`803804.805806**`U#` ([`str`](https://python-all.ru/3.1/library/functions.html#str) или `None`) \[char \*, int\]**807808Преобразует C-строку и её длину в объект Python unicode. Если указатель на C-строку равен809810*NULL*811812, длина игнорируется и возвращается813814`None`815816.817818**`i` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[int\]**819820Преобразует обычный C821822`int`823824в объект Python целого типа.825826**`b` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[char\]**827828Преобразует обычный C829830`char`831832в объект Python целого типа.833834**`h` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[short int\]**835836Преобразует обычное C837838`short int`839840в объект Python int.841842**`l` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[long int\]**843844Преобразует C845846`long int`847848в объект Python int.849850**`B` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned char\]**851852Преобразует C853854`unsigned char`855856в объект Python int.857858**`H` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned short int\]**859860Преобразует C861862`unsigned short int`863864в объект Python int.865866**`I` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned int\]**867868Преобразует C869870`unsigned int`871872в объект Python int.873874**`k` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned long\]**875876Преобразует C877878`unsigned long`879880в объект Python int.881882**`L` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[PY\_LONG\_LONG\]**883884Преобразует C885886`long long`887888в объект Python int. Доступно только на платформах, поддерживающих889890`long long`891892(или893894`_int64`895896в Windows).897898**`K` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned PY\_LONG\_LONG\]**899900Преобразует C901902`unsigned long long`903904в объект Python int. Доступно только на платформах, поддерживающих905906`unsigned long long`907908(или909910`unsigned _int64`911912в Windows).913914**`n` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[Py\_ssize\_t\]**915916Преобразует C917918`Py_ssize_t`919920в Python int.921922**`c` ([`bytes`](https://python-all.ru/3.1/library/functions.html#bytes) длиной 1) \[char\]**923924Преобразует C925926`int`927928, представляющий байт, в объект Python929930[`bytes`](https://python-all.ru/3.1/library/functions.html#bytes)931932длиной 1.933934**`C` ([`str`](https://python-all.ru/3.1/library/functions.html#str) длиной 1) \[int\]**935936Преобразует C937938`int`939940, представляющий символ, в объект Python941942[`str`](https://python-all.ru/3.1/library/functions.html#str)943944длиной 1.945946**`d` ([`float`](https://python-all.ru/3.1/library/functions.html#float)) \[double\]**947948Преобразует C949950`double`951952в число с плавающей точкой Python.953954**`f` ([`float`](https://python-all.ru/3.1/library/functions.html#float)) \[float\]**955956Преобразует C957958`float`959960в число с плавающей точкой Python.961962**`D` ([`complex`](https://python-all.ru/3.1/library/functions.html#complex)) \[Py\_complex \*\]**963964Преобразует структуру C965966[`Py_complex`](https://python-all.ru/3.1/c-api/complex.html#Py_complex)967968в комплексное число Python.969970**`O` (объект) \[PyObject \*\]**971972Передаёт объект Python без изменений (за исключением счётчика ссылок, который увеличивается на единицу). Если переданный объект является указателем973974*NULL*975976, считается, что это произошло из-за того, что вызов, формирующий аргумент, обнаружил ошибку и установил исключение. Поэтому977978[`Py_BuildValue()`](https://python-all.ru/3.1/c-api/arg.html#Py_BuildValue)979980вернёт981982*NULL*983984, но не вызовет исключение. Если ещё не было установлено никакого исключения, устанавливается985986[`SystemError`](https://python-all.ru/3.1/library/exceptions.html#SystemError)987988.989990**`S` (объект) \[PyObject \*\]**991992То же, что и993994`O`995996.997998**`N` (объект) \[PyObject \*\]**9991000То же, что и10011002`O`10031004, за исключением того, что не увеличивает счётчик ссылок на объект. Полезно, когда объект создаётся вызовом конструктора объекта в списке аргументов.10051006**`O&` (объект) \[*converter*, *anything*\]**10071008Преобразует10091010*anything*10111012в объект Python с помощью функции10131014*converter*10151016. Функция вызывается с аргументом10171018*anything*10191020(который должен быть совместим с10211022`void *`10231024) и должна возвращать «новый» объект Python или10251026*NULL*10271028в случае ошибки.10291030**`(items)` ([`tuple`](https://python-all.ru/3.1/library/functions.html#tuple)) \[*matching-items*\]**10311032Преобразует последовательность значений C в кортеж Python с тем же количеством элементов.10331034**`[items]` ([`list`](https://python-all.ru/3.1/library/functions.html#list)) \[*matching-items*\]**10351036Преобразует последовательность значений C в список Python с тем же количеством элементов.10371038**`{items}` ([`dict`](https://python-all.ru/3.1/library/stdtypes.html#dict)) \[*matching-items*\]**10391040Преобразует последовательность значений C в словарь Python. Каждая пара последовательных значений C добавляет один элемент в словарь, выступая в роли ключа и значения соответственно.10411042Если в строке формата есть ошибка, устанавливается исключение [`SystemError`](https://python-all.ru/3.1/library/exceptions.html#SystemError) и возвращается *NULL*.10431044**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `Py_VaBuildValue`(const char *\*format*, va\_list *vargs*)**10451046Идентична10471048[`Py_BuildValue()`](https://python-all.ru/3.1/c-api/arg.html#Py_BuildValue)10491050, за исключением того, что принимает va\_list вместо переменного числа аргументов.1051