`arg.md`

977 строк · 54.1 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.5/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.5/extending/index.html#extending-index).1011Первые три из описанных функций, [`PyArg_ParseTuple()`](https://python-all.ru/3.5/c-api/arg.html#c.PyArg_ParseTuple), [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.5/c-api/arg.html#c.PyArg_ParseTupleAndKeywords) и [`PyArg_Parse()`](https://python-all.ru/3.5/c-api/arg.html#c.PyArg_Parse), используют *строки формата*, которые сообщают функции об ожидаемых аргументах. Строки формата имеют одинаковый синтаксис для каждой из этих функций.1213## Разбор аргументов1415Строка формата состоит из нуля или более «единиц формата». Единица формата описывает один объект Python; обычно это один символ или заключённая в скобки последовательность единиц формата. За несколькими исключениями, единица формата, не являющаяся последовательностью в скобках, обычно соответствует одному аргументу-адресу этих функций. В следующем описании приведённая в кавычках форма – это единица формата; запись в круглых скобках – тип объекта Python, которому соответствует единица формата; а запись в квадратных скобках – тип переменной(ых) C, чей адрес следует передать.1617### Строки и буферы1819Эти форматы позволяют обращаться к объекту как к непрерывному блоку памяти. Не нужно предоставлять сырое хранилище для возвращаемой области unicode или bytes.2021В целом, когда формат устанавливает указатель на буфер, буфер управляется соответствующим объектом Python и существует в течение его времени жизни. Освобождать память самостоятельно не потребуется. Единственные исключения: `es`, `es#`, `et` и `et#`.2223Однако, когда структура [`Py_buffer`](https://python-all.ru/3.5/c-api/buffer.html#c.Py_buffer) заполняется, нижележащий буфер блокируется, чтобы вызывающий код мог затем использовать буфер даже внутри блока [`Py_BEGIN_ALLOW_THREADS`](https://python-all.ru/3.5/c-api/init.html#c.Py_BEGIN_ALLOW_THREADS) без риска изменения размера или уничтожения изменяемых данных. Поэтому **необходимо вызвать** [`PyBuffer_Release()`](https://python-all.ru/3.5/c-api/buffer.html#c.PyBuffer_Release) после завершения обработки данных (или при досрочном прерывании).2425Если не указано иное, буферы не завершаются нулевым символом (NUL).2627Некоторые форматы требуют [объекта, подобного байтам](https://python-all.ru/3.5/glossary.html#term-bytes-like-object), доступного только для чтения, и устанавливают указатель вместо структуры буфера. Они работают, проверяя, что поле [`PyBufferProcs.bf_releasebuffer`](https://python-all.ru/3.5/c-api/typeobj.html#c.PyBufferProcs.bf_releasebuffer) объекта равно *NULL*, что запрещает изменяемые объекты, такие как [`bytearray`](https://python-all.ru/3.5/library/functions.html#bytearray).2829> **Примечание**30>31> Для всех вариантов форматов `#` (`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`.3233**`s` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str)) \[const char \*\]**3435Преобразует объект Unicode в указатель C на строку символов. Указатель на существующую строку сохраняется в переменной-указателе на символ, адрес которой передаётся. Строка C заканчивается нулевым символом (NUL). Строка Python не должна содержать встроенные нулевые кодовые точки; если содержит, возбуждается исключение [`ValueError`](https://python-all.ru/3.5/library/exceptions.html#ValueError). Объекты Unicode преобразуются в строки C с использованием кодировки `'utf-8'`. Если это преобразование не удаётся, возбуждается [`UnicodeError`](https://python-all.ru/3.5/library/exceptions.html#UnicodeError).3637> **Примечание**38>39> Этот формат не принимает [байтоподобные объекты](https://python-all.ru/3.5/glossary.html#term-bytes-like-object). Если требуется принимать пути файловой системы и преобразовывать их в строки символов C, предпочтительнее использовать формат `O&` с [`PyUnicode_FSConverter()`](https://python-all.ru/3.5/c-api/unicode.html#c.PyUnicode_FSConverter) в качестве *конвертера*.4041Изменено в версии 3.5: Ранее [`TypeError`](https://python-all.ru/3.5/library/exceptions.html#TypeError) возбуждалось, когда в строке Python обнаруживались встроенные нулевые кодовые точки.4243**`s*` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str) или [байтоподобный объект](https://python-all.ru/3.5/glossary.html#term-bytes-like-object)) \[Py\_buffer\]**4445Этот формат принимает как объекты Unicode, так и байтоподобные объекты. Он заполняет структуру4647[`Py_buffer`](https://python-all.ru/3.5/c-api/buffer.html#c.Py_buffer)4849, предоставленную вызывающей стороной. В этом случае результирующая строка C может содержать встроенные нулевые байты (NUL). Объекты Unicode преобразуются в строки C с использованием кодировки5051`'utf-8'`5253.5455**`s#` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str), только для чтения [байтоподобный объект](https://python-all.ru/3.5/glossary.html#term-bytes-like-object)) \[const char \*, int или `Py_ssize_t`\]**5657Как и5859`s*`6061, за исключением того, что не принимает изменяемые объекты. Результат сохраняется в две переменные C: первая – указатель на C-строку, вторая – её длина. Строка может содержать встроенные нулевые байты. Объекты Unicode преобразуются в C-строки с использованием кодировки6263`'utf-8'`6465.6667**`z` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str) или `None`) \[const char \*\]**6869Как7071`s`7273, но объект Python также может быть7475`None`7677, и в этом случае указатель C устанавливается в7879*NULL*8081.8283**`z*` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str), [байтоподобный объект](https://python-all.ru/3.5/glossary.html#term-bytes-like-object) или `None`) \[Py\_buffer\]**8485Как8687`s*`8889, но объект Python также может быть9091`None`9293, и в этом случае элемент9495`buf`9697структуры9899[`Py_buffer`](https://python-all.ru/3.5/c-api/buffer.html#c.Py_buffer)100101устанавливается в102103*NULL*104105.106107**`z#` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str), [объект, подобный байтам](https://python-all.ru/3.5/glossary.html#term-bytes-like-object), доступный только для чтения, или `None`) \[const char \*, int\]**108109Как110111`s#`112113, но объект Python также может быть114115`None`116117, и в этом случае указатель C устанавливается в118119*NULL*120121.122123**`y` ([байтоподобный объект](https://python-all.ru/3.5/glossary.html#term-bytes-like-object) только для чтения) \[const char \*\]**124125Этот формат преобразует байтоподобный объект в указатель C на строку символов; он не принимает объекты Unicode. Буфер байтов не должен содержать встроенные нулевые байты; если это происходит, возбуждается исключение [`ValueError`](https://python-all.ru/3.5/library/exceptions.html#ValueError).126127Изменено в версии 3.5: Ранее [`TypeError`](https://python-all.ru/3.5/library/exceptions.html#TypeError) возбуждалось, когда в байтовом буфере обнаруживались встроенные нулевые байты.128129**`y*` ([байтоподобный объект](https://python-all.ru/3.5/glossary.html#term-bytes-like-object)) \[Py\_buffer\]**130131Этот вариант132133`s*`134135не принимает объекты Unicode, только байтоподобные объекты.136137**Это рекомендуемый способ приёма двоичных данных.**138139**`y#` ([объект, подобный байтам](https://python-all.ru/3.5/glossary.html#term-bytes-like-object), доступный только для чтения) \[const char \*, int\]**140141Этот вариант142143`s#`144145не принимает объекты Unicode, только байтоподобные объекты.146147**`S` ([`bytes`](https://python-all.ru/3.5/library/functions.html#bytes)) \[PyBytesObject \*\]**148149Требует, чтобы объект Python был объектом150151[`bytes`](https://python-all.ru/3.5/library/functions.html#bytes)152153, без попыток преобразования. Возбуждает154155[`TypeError`](https://python-all.ru/3.5/library/exceptions.html#TypeError)156157, если объект не является объектом bytes. Переменная C также может быть объявлена как158159[`PyObject*`](https://python-all.ru/3.5/c-api/structures.html#c.PyObject)160161.162163**`Y` ([`bytearray`](https://python-all.ru/3.5/library/functions.html#bytearray)) \[PyByteArrayObject \*\]**164165Требует, чтобы объект Python был объектом166167[`bytearray`](https://python-all.ru/3.5/library/functions.html#bytearray)168169, без попыток преобразования. Возбуждает170171[`TypeError`](https://python-all.ru/3.5/library/exceptions.html#TypeError)172173, если объект не является объектом174175[`bytearray`](https://python-all.ru/3.5/library/functions.html#bytearray)176177. Переменная C также может быть объявлена как178179[`PyObject*`](https://python-all.ru/3.5/c-api/structures.html#c.PyObject)180181.182183**`u` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str)) \[Py\_UNICODE \*\]**184185Преобразует объект Unicode Python в указатель C на NUL-завершенный буфер символов Unicode. Необходимо передать адрес переменной-указателя [`Py_UNICODE`](https://python-all.ru/3.5/c-api/unicode.html#c.Py_UNICODE), которая будет заполнена указателем на существующий буфер Unicode. Обратите внимание, что ширина символа [`Py_UNICODE`](https://python-all.ru/3.5/c-api/unicode.html#c.Py_UNICODE) зависит от параметров компиляции (16 или 32 бита). Строка Python не должна содержать встроенных нулевых кодовых точек; если они есть, возбуждается исключение [`ValueError`](https://python-all.ru/3.5/library/exceptions.html#ValueError).186187Изменено в версии 3.5: Ранее [`TypeError`](https://python-all.ru/3.5/library/exceptions.html#TypeError) возбуждалось, когда в строке Python обнаруживались встроенные нулевые кодовые точки.188189**`u#` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str)) \[Py\_UNICODE \*, int\]**190191Этот вариант192193`u`194195сохраняет значения в две переменные C: первую – указатель на буфер данных Unicode, вторую – его длину. Этот вариант допускает нулевые кодовые точки.196197**`Z` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str) или `None`) \[Py\_UNICODE \*\]**198199Как200201`u`202203, но объект Python также может быть204205`None`206207, и в этом случае указатель208209[`Py_UNICODE`](https://python-all.ru/3.5/c-api/unicode.html#c.Py_UNICODE)210211устанавливается в212213*NULL*214215.216217**`Z#` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str) или `None`) \[Py\_UNICODE \*, int\]**218219Как220221`u#`222223, но объект Python также может быть224225`None`226227, и в этом случае указатель228229[`Py_UNICODE`](https://python-all.ru/3.5/c-api/unicode.html#c.Py_UNICODE)230231устанавливается в232233*NULL*234235.236237**`U` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str)) \[PyObject \*\]**238239Требует, чтобы объект Python был объектом Unicode, без попыток преобразования. Возбуждает240241[`TypeError`](https://python-all.ru/3.5/library/exceptions.html#TypeError)242243, если объект не является объектом Unicode. Переменная C также может быть объявлена как244245[`PyObject*`](https://python-all.ru/3.5/c-api/structures.html#c.PyObject)246247.248249**`w*` ([байтоподобный объект](https://python-all.ru/3.5/glossary.html#term-bytes-like-object) для чтения и записи) \[Py\_buffer\]**250251Этот формат принимает любой объект, реализующий интерфейс буфера для чтения-записи. Он заполняет структуру252253[`Py_buffer`](https://python-all.ru/3.5/c-api/buffer.html#c.Py_buffer)254255, предоставленную вызывающей стороной. Буфер может содержать встроенные нулевые байты. Вызывающая сторона должна вызвать256257[`PyBuffer_Release()`](https://python-all.ru/3.5/c-api/buffer.html#c.PyBuffer_Release)258259, когда закончит работу с буфером.260261**`es` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str)) \[const char \*encoding, char \*\*buffer\]**262263Этот вариант `s` используется для кодирования Unicode в символьный буфер. Он работает только с закодированными данными без встроенных NUL-байтов.264265Этот формат требует двух аргументов. Первый используется только как входной и должен быть `const char*`, который указывает на имя кодировки в виде строки, завершающейся NUL, или *NULL*, и в этом случае используется кодировка `'utf-8'`. Исключение возбуждается, если указанная кодировка неизвестна Python. Второй аргумент должен быть `char**`; значение указателя, на который он ссылается, будет установлено на буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, указанной первым аргументом.266267[`PyArg_ParseTuple()`](https://python-all.ru/3.5/c-api/arg.html#c.PyArg_ParseTuple) выделит буфер нужного размера, скопирует закодированные данные в этот буфер и настроит *\*buffer* так, чтобы он ссылался на вновь выделенную память. Вызывающая сторона отвечает за вызов [`PyMem_Free()`](https://python-all.ru/3.5/c-api/memory.html#c.PyMem_Free) для освобождения выделенного буфера после использования.268269**`et` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3.5/library/functions.html#bytes) или [`bytearray`](https://python-all.ru/3.5/library/functions.html#bytearray)) \[const char \*encoding, char \*\*buffer\]**270271То же, что и272273`es`274275, за исключением того, что объекты байтовой строки передаются без перекодирования. Вместо этого реализация предполагает, что объект байтовой строки использует кодировку, переданную в качестве параметра.276277**`es#` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str)) \[const char \*encoding, char \*\*buffer, int \*buffer\_length\]**278279Этот вариант `s#` используется для кодирования Unicode в символьный буфер. В отличие от формата `es`, этот вариант допускает входные данные, содержащие NUL-символы.280281Требуется три аргумента. Первый используется только как входной и должен быть `const char*`, который указывает на имя кодировки в виде строки, завершающейся NUL, или *NULL*, и в этом случае используется кодировка `'utf-8'`. Исключение возбуждается, если указанная кодировка неизвестна Python. Второй аргумент должен быть `char**`; значение указателя, на который он ссылается, будет установлено на буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, указанной первым аргументом. Третий аргумент должен быть указателем на целое число; целое число, на которое он ссылается, будет установлено на количество байтов в выходном буфере.282283Существует два режима работы:284285Если *\*buffer* указывает на указатель *NULL*, функция выделит буфер нужного размера, скопирует закодированные данные в этот буфер и установит *\*buffer* так, чтобы он ссылался на новую выделенную память. Вызывающий отвечает за вызов [`PyMem_Free()`](https://python-all.ru/3.5/c-api/memory.html#c.PyMem_Free) для освобождения выделенного буфера после использования.286287Если *\*buffer* указывает на не-*NULL* указатель (уже выделенный буфер), [`PyArg_ParseTuple()`](https://python-all.ru/3.5/c-api/arg.html#c.PyArg_ParseTuple) будет использовать это место как буфер и интерпретировать начальное значение *\*buffer\_length* как размер буфера. Затем он скопирует закодированные данные в буфер и дополнит его NUL. Если буфер недостаточно велик, будет установлен [`TypeError`](https://python-all.ru/3.5/library/exceptions.html#TypeError). Примечание: начиная с Python 3.6 будет установлен [`ValueError`](https://python-all.ru/3.5/library/exceptions.html#ValueError).288289В обоих случаях *\*buffer\_length* устанавливается в длину закодированных данных без завершающего NUL-байта.290291**`et#` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3.5/library/functions.html#bytes) или [`bytearray`](https://python-all.ru/3.5/library/functions.html#bytearray)) \[const char \*encoding, char \*\*buffer, int \*buffer\_length\]**292293То же, что и294295`es#`296297, за исключением того, что объекты байтовой строки передаются без перекодирования. Вместо этого реализация предполагает, что объект байтовой строки использует кодировку, переданную в качестве параметра.298299### Числа300301**`b` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[unsigned char\]**302303Преобразует неотрицательное целое число Python в беззнаковое крошечное целое, хранящееся в C304305`unsigned char`306307.308309**`B` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[unsigned char\]**310311Преобразует целое число Python в крошечное целое без проверки переполнения, хранящееся в C312313`unsigned char`314315.316317**`h` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[short int\]**318319Преобразует целое число Python в C320321`short int`322323.324325**`H` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[unsigned short int\]**326327Преобразует целое число Python в C328329`unsigned short int`330331без проверки переполнения.332333**`i` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[int\]**334335Преобразует целое число Python в обычное C336337`int`338339.340341**`I` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[unsigned int\]**342343Преобразует целое число Python в C344345`unsigned int`346347без проверки переполнения.348349**`l` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[long int\]**350351Преобразует целое число Python в C352353`long int`354355.356357**`k` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[unsigned long\]**358359Преобразует целое число Python в C360361`unsigned long`362363без проверки переполнения.364365**`L` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[PY\_LONG\_LONG\]**366367Преобразует целое число Python в C368369`long long`370371. Этот формат доступен только на платформах, поддерживающих372373`long long`374375(или376377`_int64`378379на Windows).380381**`K` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[unsigned PY\_LONG\_LONG\]**382383Преобразует целое число Python в C384385`unsigned long long`386387без проверки переполнения. Этот формат доступен только на платформах, поддерживающих388389`unsigned long long`390391(или392393`unsigned _int64`394395на Windows).396397**`n` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[Py\_ssize\_t\]**398399Преобразует целое число Python в C400401`Py_ssize_t`402403.404405**`c` ([`bytes`](https://python-all.ru/3.5/library/functions.html#bytes) или [`bytearray`](https://python-all.ru/3.5/library/functions.html#bytearray) длиной 1) \[char\]**406407Преобразует байт Python, представленный как объект [`bytes`](https://python-all.ru/3.5/library/functions.html#bytes) или [`bytearray`](https://python-all.ru/3.5/library/functions.html#bytearray) длиной 1, в C-тип `char`.408409Изменено в версии 3.3: Допускаются объекты [`bytearray`](https://python-all.ru/3.5/library/functions.html#bytearray).410411**`C` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str) длины 1) \[int\]**412413Преобразует символ Python, представленный как объект414415[`str`](https://python-all.ru/3.5/library/stdtypes.html#str)416417длиной 1, в C-тип418419`int`420421.422423**`f` ([`float`](https://python-all.ru/3.5/library/functions.html#float)) \[float\]**424425Преобразует число с плавающей точкой Python в C-тип426427`float`428429.430431**`d` ([`float`](https://python-all.ru/3.5/library/functions.html#float)) \[double\]**432433Преобразует число с плавающей точкой Python в C-тип434435`double`436437.438439**`D` ([`complex`](https://python-all.ru/3.5/library/functions.html#complex)) \[Py\_complex\]**440441Преобразует комплексное число Python в структуру C442443[`Py_complex`](https://python-all.ru/3.5/c-api/complex.html#c.Py_complex)444445.446447### Другие объекты448449**`O` (объект) \[PyObject \*\]**450451Сохраняет объект Python (без какого-либо преобразования) в указателе на объект C. Таким образом, программа на C получает фактически переданный объект. Счётчик ссылок объекта не увеличивается. Сохранённый указатель не равен452453*NULL*454455.456457**`O!` (object) \[*typeobject*, PyObject \*\]**458459Сохраняет объект Python в указателе на объект C. Это похоже на460461`O`462463, но принимает два аргумента C: первый – адрес объекта типа Python, второй – адрес C-переменной (типа464465[`PyObject*`](https://python-all.ru/3.5/c-api/structures.html#c.PyObject)466467), в которую сохраняется указатель на объект. Если объект Python не имеет требуемого типа, возбуждается468469[`TypeError`](https://python-all.ru/3.5/library/exceptions.html#TypeError)470471.472473**`O&` (object) \[*конвертер*, *что угодно*\]**474475Преобразует объект Python в C-переменную с помощью функции-*преобразователя*. Она принимает два аргумента: первый – функция, второй – адрес C-переменной (произвольного типа), преобразованный в `void *`. Функция-*преобразователь*, в свою очередь, вызывается следующим образом:476477```c478status = converter(object, address);479```480481где *объект* – это преобразуемый объект Python, а *адрес* – это аргумент `void*`, переданный функции [`PyArg_Parse*()`](https://python-all.ru/3.5/c-api/arg.html#c.PyArg_Parse). Возвращаемый *статус* должен быть `1` при успешном преобразовании и `0` при неудаче. При неудачном преобразовании функция-*преобразователь* должна возбудить исключение и оставить содержимое *адреса* без изменений.482483Если *преобразователь* возвращает `Py_CLEANUP_SUPPORTED`, он может быть вызван повторно в случае, если разбор аргументов в итоге завершится неудачей, что даёт преобразователю возможность освободить уже выделенную память. При этом втором вызове параметр *object* будет равен NULL; *address* будет иметь то же значение, что и в исходном вызове.484485Изменено в версии 3.1: `Py_CLEANUP_SUPPORTED` добавлен.486487**`p` ([`bool`](https://python-all.ru/3.5/library/functions.html#bool)) \[int\]**488489Проверяет переданное значение на истинность (булев предикат **p**) и преобразует результат в эквивалентное целое C true/false. Устанавливает int в `1`, если выражение истинно, и в `0`, если ложно. Принимает любое корректное значение Python. См. [Проверка истинности значений](https://python-all.ru/3.5/library/stdtypes.html#truth) для получения дополнительной информации о том, как Python проверяет значения на истинность.490491Новое в версии 3.3.492493**`(items)` ([`tuple`](https://python-all.ru/3.5/library/stdtypes.html#tuple)) \[*соответствующие элементы*\]**494495Объект должен быть последовательностью Python, длина которой равна количеству единиц формата в496497*элементах*498499. Аргументы C должны соответствовать отдельным единицам формата в500501*элементах*502503. Единицы формата для последовательностей могут быть вложенными.504505Можно передавать «длинные» целые числа (целые, значение которых превышает `LONG_MAX` платформы), однако надлежащая проверка диапазона не выполняется – старшие биты молча отбрасываются, если принимающее поле слишком мало для этого значения (на самом деле семантика унаследована от понижающих приведений в C – результаты могут отличаться).506507Некоторые другие символы имеют значение в строке формата. Они не могут встречаться внутри вложенных скобок. Вот они:508509**`|`**510511Указывает, что остальные аргументы в списке аргументов Python являются необязательными. Переменные C, соответствующие необязательным аргументам, должны быть инициализированы значением по умолчанию – когда необязательный аргумент не указан,512513[`PyArg_ParseTuple()`](https://python-all.ru/3.5/c-api/arg.html#c.PyArg_ParseTuple)514515не трогает содержимое соответствующих переменных C.516517**`$`**518519[`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.5/c-api/arg.html#c.PyArg_ParseTupleAndKeywords) only: Указывает, что остальные аргументы в списке аргументов Python являются только ключевыми. В настоящее время все только ключевые аргументы также должны быть необязательными, поэтому `|` всегда должен указываться перед `$` в строке формата.520521Новое в версии 3.3.522523**`:`**524525Список единиц форматирования заканчивается здесь; строка после двоеточия используется как имя функции в сообщениях об ошибках («связанное значение» исключения, которое вызывает526527[`PyArg_ParseTuple()`](https://python-all.ru/3.5/c-api/arg.html#c.PyArg_ParseTuple)528529).530531**`;`**532533Список единиц форматирования заканчивается здесь; строка после точки с запятой используется как сообщение об ошибке534535*вместо*536537сообщения об ошибке по умолчанию.538539`:`540541и542543`;`544545взаимно исключают друг друга.546547Обратите внимание, что любые ссылки на объекты Python, передаваемые вызывающему, являются *заимствованными* ссылками; уменьшать их счётчик ссылок не следует.548549Дополнительные аргументы, передаваемые этим функциям, должны быть адресами переменных, тип которых определяется строкой формата; они используются для хранения значений из входного кортежа. Есть несколько случаев, как описано в списке единиц форматирования выше, когда эти параметры используются в качестве входных значений; в этом случае они должны соответствовать тому, что указано для соответствующей единицы форматирования.550551Для успешного преобразования объект *arg* должен соответствовать формату, и формат должен быть исчерпан. При успехе функции [`PyArg_Parse*()`](https://python-all.ru/3.5/c-api/arg.html#c.PyArg_Parse) возвращают true, в противном случае они возвращают false и возбуждают соответствующее исключение. Когда функции [`PyArg_Parse*()`](https://python-all.ru/3.5/c-api/arg.html#c.PyArg_Parse) завершаются ошибкой из-за неудачи преобразования в одной из единиц форматирования, переменные по адресам, соответствующим этой и последующим единицам форматирования, остаются нетронутыми.552553### API функции554555#### `int PyArg_ParseTuple(PyObject *args, const char *format, ...)`556557Разбирает параметры функции, принимающей только позиционные параметры, в локальные переменные. Возвращает true при успехе; при неудаче возвращает false и возбуждает соответствующее исключение.558559#### `int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)`560561Идентична [`PyArg_ParseTuple()`](https://python-all.ru/3.5/c-api/arg.html#c.PyArg_ParseTuple), за исключением того, что принимает va\_list вместо переменного числа аргументов.562563#### `int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)`564565Разбирает параметры функции, которая принимает как позиционные, так и именованные параметры, в локальные переменные. Возвращает true в случае успеха; в случае неудачи возвращает false и возбуждает соответствующее исключение.566567#### `int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)`568569Идентична [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.5/c-api/arg.html#c.PyArg_ParseTupleAndKeywords), но принимает va\_list вместо переменного числа аргументов.570571#### `int PyArg_ValidateKeywordArguments(PyObject *)`572573Гарантирует, что ключи в словаре аргументов-ключевых слов являются строками. Это нужно только в случае, если [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.5/c-api/arg.html#c.PyArg_ParseTupleAndKeywords) не используется, поскольку последняя уже выполняет эту проверку.574575Новое в версии 3.2.576577#### `int PyArg_Parse(PyObject *args, const char *format, ...)`578579Функция, используемая для разбора списков аргументов функций «старого стиля» – это функции, использующие метод разбора параметров `METH_OLDARGS`, который был удалён в Python 3. Не рекомендуется использовать её для разбора параметров в новом коде; большая часть кода в стандартном интерпретаторе была изменена, чтобы больше не использовать её для этой цели. Однако она остаётся удобным способом разложения других кортежей и может продолжать использоваться для этого.580581#### `int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)`582583Упрощённый способ извлечения параметров, не использующий строку формата для указания типов аргументов. Функции, которые получают свои параметры таким образом, должны объявляться как [`METH_VARARGS`](https://python-all.ru/3.5/c-api/structures.html#METH_VARARGS) в таблицах функций или методов. Кортеж с фактическими параметрами должен передаваться как *args*; он обязательно должен быть кортежем. Длина кортежа должна быть не меньше *min* и не больше *max*; *min* и *max* могут быть равны. В функцию необходимо передать дополнительные аргументы, каждый из которых должен быть указателем на переменную типа [`PyObject*`](https://python-all.ru/3.5/c-api/structures.html#c.PyObject); они будут заполнены значениями из *args* и будут содержать заимствованные ссылки. Переменные, соответствующие необязательным параметрам, отсутствующим в *args*, заполнены не будут; их следует инициализировать вызывающей стороне. Эта функция возвращает true при успехе и false, если *args* не является кортежем или содержит неверное количество элементов; в случае ошибки устанавливается исключение.584585Это пример использования этой функции, взятый из исходных кодов вспомогательного модуля для слабых ссылок `_weakref`:586587```c588static PyObject *589weakref_ref(PyObject *self, PyObject *args)590{591    PyObject *object;592    PyObject *callback = NULL;593    PyObject *result = NULL;594595    if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {596        result = PyWeakref_NewRef(object, callback);597    }598    return result;599}600```601602Вызов [`PyArg_UnpackTuple()`](https://python-all.ru/3.5/c-api/arg.html#c.PyArg_UnpackTuple) в этом примере полностью эквивалентен вызову [`PyArg_ParseTuple()`](https://python-all.ru/3.5/c-api/arg.html#c.PyArg_ParseTuple):603604```c605PyArg_ParseTuple(args, "O|O:ref", &object, &callback)606```607608## Построение значений609610#### `PyObject* Py_BuildValue(const char *format, ...)`611612*Возвращаемое значение: новая ссылка.*613614Создаёт новое значение на основе строки формата, аналогичной используемым в семействе функций [`PyArg_Parse*()`](https://python-all.ru/3.5/c-api/arg.html#c.PyArg_Parse), и последовательности значений. Возвращает значение или *NULL* в случае ошибки; если возвращён *NULL*, будет возбуждено исключение.615616[`Py_BuildValue()`](https://python-all.ru/3.5/c-api/arg.html#c.Py_BuildValue) не всегда строит кортеж. Он строит кортеж, только если строка формата содержит два или более элемента формата. Если строка формата пуста, возвращается `None`; если она содержит ровно один элемент формата, возвращается объект, описываемый этим элементом. Чтобы принудительно вернуть кортеж размера 0 или 1, заключите строку формата в скобки.617618Когда буферы памяти передаются как параметры для предоставления данных для создания объектов, как для форматов `s` и `s#`, необходимые данные копируются. Буферы, предоставленные вызывающим, никогда не используются напрямую объектами, созданными с помощью [`Py_BuildValue()`](https://python-all.ru/3.5/c-api/arg.html#c.Py_BuildValue). Другими словами, если ваш код вызывает `malloc()` и передает выделенную память в [`Py_BuildValue()`](https://python-all.ru/3.5/c-api/arg.html#c.Py_BuildValue), ваш код отвечает за вызов `free()` для этой памяти после того, как [`Py_BuildValue()`](https://python-all.ru/3.5/c-api/arg.html#c.Py_BuildValue) вернет управление.619620В следующем описании форма в кавычках – это элемент формата; запись в круглых скобках – это тип объекта Python, который вернёт элемент формата; а запись в квадратных скобках – это тип передаваемого(-ых) значения(-ий) C.621622Символы пробела, табуляции, двоеточия и запятой в строках формата игнорируются (но не внутри элементов формата, таких как `s#`). Это можно использовать, чтобы сделать длинные строки формата чуть более читаемыми.623624**`s` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str) или `None`) \[char \*\]**625626Преобразует C-строку с нулевым символом на конце в объект Python627628[`str`](https://python-all.ru/3.5/library/stdtypes.html#str)629630, используя кодировку631632`'utf-8'`633634. Если указатель на C-строку равен635636*NULL*637638, используется639640`None`641642.643644**`s#` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str) или `None`) \[char \*, int\]**645646Преобразует C-строку и её длину в объект Python647648[`str`](https://python-all.ru/3.5/library/stdtypes.html#str)649650, используя кодировку651652`'utf-8'`653654. Если указатель на C-строку равен655656*NULL*657658, длина игнорируется и возвращается659660`None`661662.663664**`y` ([`bytes`](https://python-all.ru/3.5/library/functions.html#bytes)) \[char \*\]**665666Преобразует C-строку в объект Python667668[`bytes`](https://python-all.ru/3.5/library/functions.html#bytes)669670. Если указатель на C-строку равен671672*NULL*673674, возвращается675676`None`677678.679680**`y#` ([`bytes`](https://python-all.ru/3.5/library/functions.html#bytes)) \[char \*, int\]**681682Преобразует C-строку и её длину в объект Python. Если указатель на C-строку равен683684*NULL*685686, возвращается687688`None`689690.691692**`z` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str) or `None`) \[char \*\]**693694То же, что и695696`s`697698.699700**`z#` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str) or `None`) \[char \*, int\]**701702То же, что и703704`s#`705706.707708**`u` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str)) \[Py\_UNICODE \*\]**709710Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a Python Unicode object. If the Unicode buffer pointer is711712*NULL*713714,715716`None`717718is returned.719720**`u#` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str)) \[Py\_UNICODE \*, int\]**721722Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a Python Unicode object. If the Unicode buffer pointer is723724*NULL*725726, the length is ignored and727728`None`729730is returned.731732**`U` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str) or `None`) \[char \*\]**733734То же, что и735736`s`737738.739740**`U#` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str) or `None`) \[char \*, int\]**741742То же, что и743744`s#`745746.747748**`i` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[int\]**749750Преобразует простой C-тип751752`int`753754в объект целого числа Python.755756**`b` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[char\]**757758Преобразует простой C-тип759760`char`761762в объект целого числа Python.763764**`h` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[short int\]**765766Преобразует простой C-тип767768`short int`769770в объект целого числа Python.771772**`l` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[long int\]**773774Преобразует C775776`long int`777778в объект Python int.779780**`B` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[unsigned char\]**781782Преобразует C783784`unsigned char`785786в объект Python int.787788**`H` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[unsigned short int\]**789790Преобразует C791792`unsigned short int`793794в объект Python int.795796**`I` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[unsigned int\]**797798Преобразует C799800`unsigned int`801802в объект Python int.803804**`k` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[unsigned long\]**805806Преобразует C807808`unsigned long`809810в объект Python int.811812**`L` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[PY\_LONG\_LONG\]**813814Преобразует815816`long long`817818языка C в объект целого числа Python. Доступно только на платформах, поддерживающих819820`long long`821822(или823824`_int64`825826в Windows).827828**`K` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[unsigned PY\_LONG\_LONG\]**829830Преобразует831832`unsigned long long`833834языка C в объект целого числа Python. Доступно только на платформах, поддерживающих835836`unsigned long long`837838(или839840`unsigned _int64`841842в Windows).843844**`n` ([`int`](https://python-all.ru/3.5/library/functions.html#int)) \[Py\_ssize\_t\]**845846Преобразует C847848`Py_ssize_t`849850в целое число Python.851852**`c` ([`bytes`](https://python-all.ru/3.5/library/functions.html#bytes) длины 1) \[char\]**853854Преобразует C855856`int`857858, представляющий байт, в объект859860[`bytes`](https://python-all.ru/3.5/library/functions.html#bytes)861862Python длиной 1.863864**`C` ([`str`](https://python-all.ru/3.5/library/stdtypes.html#str) длины 1) \[int\]**865866Преобразует C867868`int`869870, представляющий символ, в объект871872[`str`](https://python-all.ru/3.5/library/stdtypes.html#str)873874Python длиной 1.875876**`d` ([`float`](https://python-all.ru/3.5/library/functions.html#float)) \[double\]**877878Преобразует C879880`double`881882в Python-число с плавающей запятой.883884**`f` ([`float`](https://python-all.ru/3.5/library/functions.html#float)) \[float\]**885886Преобразует C887888`float`889890в Python-число с плавающей запятой.891892**`D` ([`complex`](https://python-all.ru/3.5/library/functions.html#complex)) \[Py\_complex \*\]**893894Преобразует структуру C895896[`Py_complex`](https://python-all.ru/3.5/c-api/complex.html#c.Py_complex)897898в комплексное число Python.899900**`O` (объект) \[PyObject \*\]**901902Передаёт Python-объект без изменений (за исключением его счётчика ссылок, который увеличивается на единицу). Если переданный объект является указателем903904*NULL*905906, считается, что это произошло из-за того, что вызов, формирующий аргумент, обнаружил ошибку и установил исключение. Следовательно,907908[`Py_BuildValue()`](https://python-all.ru/3.5/c-api/arg.html#c.Py_BuildValue)909910вернёт911912*NULL*913914, но не вызовет исключение. Если исключение ещё не было вызвано, устанавливается915916[`SystemError`](https://python-all.ru/3.5/library/exceptions.html#SystemError)917918.919920**`S` (объект) \[PyObject \*\]**921922То же, что и923924`O`925926.927928**`N` (объект) \[PyObject \*\]**929930То же, что и931932`O`933934, за исключением того, что не увеличивает счётчик ссылок на объект. Полезно, когда объект создаётся вызовом конструктора объекта в списке аргументов.935936**`O&` (object) \[*конвертер*, *что угодно*\]**937938Преобразует939940*что угодно*941942в Python-объект с помощью943944*функции-преобразователя*945946. Функция вызывается с947948*чем угодно*949950(которое должно быть совместимо с951952`void *`953954) в качестве аргумента и должна вернуть «новый» Python-объект или955956*NULL*957958, если произошла ошибка.959960**`(items)` ([`tuple`](https://python-all.ru/3.5/library/stdtypes.html#tuple)) \[*соответствующие элементы*\]**961962Преобразует последовательность значений C в кортеж Python с тем же количеством элементов.963964**`[items]` ([`list`](https://python-all.ru/3.5/library/stdtypes.html#list)) \[*соответствующие элементы*\]**965966Преобразует последовательность значений C в список Python с тем же количеством элементов.967968**`{items}` ([`dict`](https://python-all.ru/3.5/library/stdtypes.html#dict)) \[*соответствующие элементы*\]**969970Преобразует последовательность значений C в словарь Python. Каждая пара последовательных значений C добавляет один элемент в словарь, выступая в роли ключа и значения соответственно.971972Если в строке формата есть ошибка, устанавливается исключение [`SystemError`](https://python-all.ru/3.5/library/exceptions.html#SystemError) и возвращается *NULL*.973974#### `PyObject* Py_VaBuildValue(const char *format, va_list vargs)`975976Идентична [`Py_BuildValue()`](https://python-all.ru/3.5/c-api/arg.html#c.Py_BuildValue), за исключением того, что принимает va\_list вместо переменного числа аргументов.977