`arg.md`

979 строк · 52.5 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.4/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.4/extending/index.html#extending-index).1011Первые три из описанных функций, [`PyArg_ParseTuple()`](https://python-all.ru/3.4/c-api/arg.html#c.PyArg_ParseTuple), [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.4/c-api/arg.html#c.PyArg_ParseTupleAndKeywords) и [`PyArg_Parse()`](https://python-all.ru/3.4/c-api/arg.html#c.PyArg_Parse), используют *строки формата*, которые сообщают функции об ожидаемых аргументах. Эти строки формата имеют одинаковый синтаксис для всех этих функций.1213## Разбор аргументов1415Строка формата состоит из нуля или более «единиц формата». Единица формата описывает один объект Python; обычно это один символ или заключённая в скобки последовательность единиц формата. За несколькими исключениями, единица формата, не являющаяся последовательностью в скобках, обычно соответствует одному аргументу-адресу этих функций. В следующем описании приведённая в кавычках форма – это единица формата; запись в круглых скобках – тип объекта Python, которому соответствует единица формата; а запись в квадратных скобках – тип переменной(ых) C, чей адрес следует передать.1617### Строки и буферы1819Эти форматы позволяют получить доступ к объекту как к непрерывному блоку памяти. Вам не нужно предоставлять сырое хранилище для возвращаемой области unicode или bytes. Кроме того, вам не придётся самостоятельно освобождать память, за исключением форматов `es`, `es#`, `et` и `et#`.2021Однако, когда структура [`Py_buffer`](https://python-all.ru/3.4/c-api/buffer.html#c.Py_buffer) заполняется, соответствующий буфер блокируется, чтобы вызывающий код мог затем использовать буфер даже внутри блока [`Py_BEGIN_ALLOW_THREADS`](https://python-all.ru/3.4/c-api/init.html#c.Py_BEGIN_ALLOW_THREADS) без риска изменения или уничтожения изменяемых данных. Как следствие, **необходимо вызвать** [`PyBuffer_Release()`](https://python-all.ru/3.4/c-api/buffer.html#c.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.4/library/stdtypes.html#str)) \[const char \*\]**3031Преобразует объект Unicode в указатель C на строку символов. Указатель на существующую строку сохраняется в переменной-указателе на символы, адрес которой передаётся. Строка C завершается нулевым символом (NUL). Строка Python не должна содержать встроенных нулевых байтов; если они есть, возбуждается исключение [`TypeError`](https://python-all.ru/3.4/library/exceptions.html#TypeError). Объекты Unicode преобразуются в строки C с использованием кодировки `'utf-8'`. Если это преобразование не удаётся, возбуждается [`UnicodeError`](https://python-all.ru/3.4/library/exceptions.html#UnicodeError).3233> **Примечание**34>35> Этот формат не принимает [*объекты, подобные байтам*](https://python-all.ru/3.4/glossary.html#term-bytes-like-object). Если требуется принимать пути файловой системы и преобразовывать их в строки C, предпочтительнее использовать формат `O&` с [`PyUnicode_FSConverter()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_FSConverter) в качестве *конвертера*.3637**`s*` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str) или [*объект, подобный байтам*](https://python-all.ru/3.4/glossary.html#term-bytes-like-object)) \[Py\_buffer\]**3839Этот формат принимает как объекты Unicode, так и объекты, подобные байтам. Он заполняет структуру4041[`Py_buffer`](https://python-all.ru/3.4/c-api/buffer.html#c.Py_buffer)4243, предоставленную вызывающим кодом. В этом случае результирующая строка C может содержать встроенные нулевые байты. Объекты Unicode преобразуются в строки C с использованием кодировки4445`'utf-8'`4647.4849**`s#` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str), только для чтения [*объект, подобный байтам*](https://python-all.ru/3.4/glossary.html#term-bytes-like-object)) \[const char \*, int или `Py_ssize_t`\]**5051Аналогично5253`s*`5455, за исключением того, что он не принимает изменяемые объекты, подобные байтам, такие как5657[`bytearray`](https://python-all.ru/3.4/library/functions.html#bytearray)5859. Результат сохраняется в две переменные C: первая – указатель на строку C, вторая – её длина. Строка может содержать встроенные нулевые байты. Объекты Unicode преобразуются в строки C с использованием кодировки6061`'utf-8'`6263.6465**`z` ([`str`](https://python-all.ru/3.4/library/stdtypes.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.4/library/stdtypes.html#str), [*объект, подобный байтам*](https://python-all.ru/3.4/glossary.html#term-bytes-like-object) или `None`) \[Py\_buffer\]**8283Как8485`s*`8687, но объект Python также может быть8889`None`9091, и в этом случае поле9293`buf`9495структуры9697[`Py_buffer`](https://python-all.ru/3.4/c-api/buffer.html#c.Py_buffer)9899устанавливается в100101*NULL*102103.104105**`z#` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str), только для чтения [*объект, подобный байтам*](https://python-all.ru/3.4/glossary.html#term-bytes-like-object) или `None`) \[const char \*, int\]**106107Как108109`s#`110111, но объект Python также может быть112113`None`114115, и в этом случае указатель C устанавливается в116117*NULL*118119.120121**`y` (только для чтения [*объект, подобный байтам*](https://python-all.ru/3.4/glossary.html#term-bytes-like-object)) \[const char \*\]**122123Этот формат преобразует объект, подобный байтам, в указатель C на строку символов; он не принимает объекты Unicode. Буфер байтов не должен содержать встроенных нулевых байтов; если они есть, возбуждается исключение124125[`TypeError`](https://python-all.ru/3.4/library/exceptions.html#TypeError)126127.128129**`y*` ([*объект, подобный байтам*](https://python-all.ru/3.4/glossary.html#term-bytes-like-object)) \[Py\_buffer\]**130131Этот вариант132133`s*`134135не принимает объекты Unicode, только объекты, подобные байтам.136137**Это рекомендуемый способ приёма двоичных данных.**138139**`y#` (только для чтения [*объект, подобный байтам*](https://python-all.ru/3.4/glossary.html#term-bytes-like-object)) \[const char \*, int\]**140141Этот вариант142143`s#`144145не принимает объекты Unicode, только объекты, подобные байтам.146147**`S` ([`bytes`](https://python-all.ru/3.4/library/functions.html#bytes)) \[PyBytesObject \*\]**148149Требует, чтобы объект Python был объектом150151[`bytes`](https://python-all.ru/3.4/library/functions.html#bytes)152153, без попыток преобразования. Возбуждает154155[`TypeError`](https://python-all.ru/3.4/library/exceptions.html#TypeError)156157, если объект не является объектом bytes. Переменная C также может быть объявлена как158159[`PyObject*`](https://python-all.ru/3.4/c-api/structures.html#c.PyObject)160161.162163**`Y` ([`bytearray`](https://python-all.ru/3.4/library/functions.html#bytearray)) \[PyByteArrayObject \*\]**164165Требует, чтобы объект Python был объектом166167[`bytearray`](https://python-all.ru/3.4/library/functions.html#bytearray)168169, без попыток преобразования. Возбуждает170171[`TypeError`](https://python-all.ru/3.4/library/exceptions.html#TypeError)172173, если объект не является объектом174175[`bytearray`](https://python-all.ru/3.4/library/functions.html#bytearray)176177. Переменная C также может быть объявлена как178179[`PyObject*`](https://python-all.ru/3.4/c-api/structures.html#c.PyObject)180181.182183**`u` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str)) \[Py\_UNICODE \*\]**184185Преобразует объект Python Unicode в указатель C на буфер символов Unicode, завершающийся нулевым символом. Необходимо передать адрес переменной-указателя [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE), которая будет заполнена указателем на существующий буфер Unicode. Обратите внимание, что ширина символа [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) зависит от опций компиляции (она составляет 16 или 32 бита). Строка Python не должна содержать встроенных нулевых символов; если они есть, возбуждается исключение [`TypeError`](https://python-all.ru/3.4/library/exceptions.html#TypeError).186187> **Примечание**188>189> Поскольку `u` не возвращает длину строки, и она может содержать встроенные нулевые символы, рекомендуется использовать вместо него `u#` или `U`.190191**`u#` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str)) \[Py\_UNICODE \*, int\]**192193Этот вариант194195`u`196197сохраняет значения в две переменные C: первая – указатель на буфер данных Unicode, вторая – его длину.198199**`Z` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str) или `None`) \[Py\_UNICODE \*\]**200201Как и202203`u`204205, но объект Python также может быть206207`None`208209, и в этом случае указатель210211[`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE)212213устанавливается в214215*NULL*216217.218219**`Z#` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str) или `None`) \[Py\_UNICODE \*, int\]**220221Как и222223`u#`224225, но объект Python также может быть226227`None`228229, и в этом случае указатель230231[`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE)232233устанавливается в234235*NULL*236237.238239**`U` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str)) \[PyObject \*\]**240241Требует, чтобы объект Python был объектом Unicode, без попыток какого-либо преобразования. Возбуждает242243[`TypeError`](https://python-all.ru/3.4/library/exceptions.html#TypeError)244245, если объект не является объектом Unicode. Переменная C также может быть объявлена как246247[`PyObject*`](https://python-all.ru/3.4/c-api/structures.html#c.PyObject)248249.250251**`w*` ([`bytearray`](https://python-all.ru/3.4/library/functions.html#bytearray) или буфер для чтения и записи, ориентированный на байты) \[Py\_buffer\]**252253Этот формат принимает любой объект, реализующий интерфейс буфера для чтения и записи. Он заполняет структуру254255[`Py_buffer`](https://python-all.ru/3.4/c-api/buffer.html#c.Py_buffer)256257, предоставленную вызывающим кодом. Буфер может содержать встроенные нулевые байты. Вызывающий код должен вызвать258259[`PyBuffer_Release()`](https://python-all.ru/3.4/c-api/buffer.html#c.PyBuffer_Release)260261после завершения работы с буфером.262263**`es` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str)) \[const char \*encoding, char \*\*buffer\]**264265Этот вариант `s` используется для кодирования Unicode в символьный буфер. Он работает только с закодированными данными без встроенных NUL-байтов.266267Этот формат требует два аргумента. Первый используется только как входной и должен быть `const char*`, указывающим на имя кодировки в виде NUL-терминированной строки, или *NULL*, в этом случае используется кодировка `'utf-8'`. Если указанная кодировка неизвестна Python, возбуждается исключение. Второй аргумент должен быть `char**`; значение указателя, на который он ссылается, будет установлено в буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, указанной первым аргументом.268269[`PyArg_ParseTuple()`](https://python-all.ru/3.4/c-api/arg.html#c.PyArg_ParseTuple) выделит буфер необходимого размера, скопирует закодированные данные в этот буфер и настроит *\*buffer* так, чтобы он ссылался на новую выделенную память. Вызывающий код отвечает за вызов [`PyMem_Free()`](https://python-all.ru/3.4/c-api/memory.html#c.PyMem_Free) для освобождения выделенного буфера после использования.270271**`et` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes) или [`bytearray`](https://python-all.ru/3.4/library/functions.html#bytearray)) \[const char \*encoding, char \*\*buffer\]**272273То же, что и274275`es`276277, за исключением того, что объекты-байтовые строки передаются без перекодирования. Вместо этого реализация предполагает, что объект-байтовая строка использует кодировку, переданную в качестве параметра.278279**`es#` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str)) \[const char \*encoding, char \*\*buffer, int \*buffer\_length\]**280281Этот вариант `s#` используется для кодирования Unicode в символьный буфер. В отличие от формата `es`, этот вариант допускает входные данные, содержащие NUL-символы.282283Требуются три аргумента. Первый используется только как входной и должен быть `const char*`, указывающим на имя кодировки в виде NUL-терминированной строки, или *NULL*, в этом случае используется кодировка `'utf-8'`. Если указанная кодировка неизвестна Python, возбуждается исключение. Второй аргумент должен быть `char**`; значение указателя, на который он ссылается, будет установлено в буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, указанной первым аргументом. Третий аргумент должен быть указателем на целое число; целое число, на которое он ссылается, будет установлено в количество байтов в выходном буфере.284285Существует два режима работы:286287Если *\*buffer* указывает на указатель *NULL*, функция выделит буфер необходимого размера, скопирует закодированные данные в этот буфер и установит *\*buffer* так, чтобы он ссылался на новую выделенную память. Вызывающий код отвечает за вызов [`PyMem_Free()`](https://python-all.ru/3.4/c-api/memory.html#c.PyMem_Free) для освобождения выделенного буфера после использования.288289Если *\*buffer* указывает на не-*NULL* указатель (уже выделенный буфер), [`PyArg_ParseTuple()`](https://python-all.ru/3.4/c-api/arg.html#c.PyArg_ParseTuple) будет использовать это место как буфер и интерпретировать начальное значение *\*buffer\_length* как размер буфера. Затем он скопирует закодированные данные в буфер и завершит его NUL. Если буфер недостаточно велик, будет установлено [`ValueError`](https://python-all.ru/3.4/library/exceptions.html#ValueError).290291В обоих случаях *\*buffer\_length* устанавливается в длину закодированных данных без завершающего NUL-байта.292293**`et#` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes) или [`bytearray`](https://python-all.ru/3.4/library/functions.html#bytearray)) \[const char \*encoding, char \*\*buffer, int \*buffer\_length\]**294295То же, что и296297`es#`298299, за исключением того, что объекты-байтовые строки передаются без перекодирования. Вместо этого реализация предполагает, что объект-байтовая строка использует кодировку, переданную в качестве параметра.300301### Числа302303**`b` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[unsigned char\]**304305Преобразует неотрицательное целое число Python в беззнаковое крошечное целое, хранящееся в C306307`unsigned char`308309.310311**`B` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[unsigned char\]**312313Преобразует целое число Python в крошечное целое без проверки переполнения, хранящееся в C314315`unsigned char`316317.318319**`h` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[short int\]**320321Преобразует целое число Python в C322323`short int`324325.326327**`H` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[unsigned short int\]**328329Преобразует целое число Python в C330331`unsigned short int`332333без проверки переполнения.334335**`i` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[int\]**336337Преобразует целое число Python в обычный C338339`int`340341.342343**`I` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[unsigned int\]**344345Преобразует целое число Python в C346347`unsigned int`348349без проверки переполнения.350351**`l` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[long int\]**352353Преобразует целое число Python в C354355`long int`356357.358359**`k` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[unsigned long\]**360361Преобразует целое число Python в C362363`unsigned long`364365без проверки переполнения.366367**`L` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[PY\_LONG\_LONG\]**368369Преобразует целое число Python в C370371`long long`372373. Этот формат доступен только на платформах, поддерживающих374375`long long`376377(или378379`_int64`380381на Windows).382383**`K` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[unsigned PY\_LONG\_LONG\]**384385Преобразует целое число Python в C386387`unsigned long long`388389без проверки переполнения. Этот формат доступен только на платформах, поддерживающих390391`unsigned long long`392393(или394395`unsigned _int64`396397на Windows).398399**`n` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[Py\_ssize\_t\]**400401Преобразует целое число Python в C402403`Py_ssize_t`404405.406407**`c` ([`bytes`](https://python-all.ru/3.4/library/functions.html#bytes) or [`bytearray`](https://python-all.ru/3.4/library/functions.html#bytearray) of length 1) \[char\]**408409Преобразует байт Python, представленный как объект [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes) или [`bytearray`](https://python-all.ru/3.4/library/functions.html#bytearray) длиной 1, в C `char`.410411Изменено в версии 3.3: Разрешены объекты [`bytearray`](https://python-all.ru/3.4/library/functions.html#bytearray).412413**`C` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str) of length 1) \[int\]**414415Преобразует символ Python, представленный как объект416417[`str`](https://python-all.ru/3.4/library/stdtypes.html#str)418419длиной 1, в C420421`int`422423.424425**`f` ([`float`](https://python-all.ru/3.4/library/functions.html#float)) \[float\]**426427Преобразует число с плавающей запятой Python в C428429`float`430431.432433**`d` ([`float`](https://python-all.ru/3.4/library/functions.html#float)) \[double\]**434435Преобразует число с плавающей запятой Python в C436437`double`438439.440441**`D` ([`complex`](https://python-all.ru/3.4/library/functions.html#complex)) \[Py\_complex\]**442443Преобразует комплексное число Python в структуру C444445[`Py_complex`](https://python-all.ru/3.4/c-api/complex.html#c.Py_complex)446447.448449### Другие объекты450451**`O` (object) \[PyObject \*\]**452453Сохраняет объект Python (без какого-либо преобразования) в указателе на объект C. Таким образом, программа на C получает фактически переданный объект. Счётчик ссылок объекта не увеличивается. Сохранённый указатель не равен454455*NULL*456457.458459**`O!` (object) \[*typeobject*, PyObject \*\]**460461Сохраняет объект Python в указателе на объект C. Это похоже на462463`O`464465, но принимает два аргумента C: первый – адрес объекта типа Python, второй – адрес переменной C (типа466467[`PyObject*`](https://python-all.ru/3.4/c-api/structures.html#c.PyObject)468469), в который сохраняется указатель на объект. Если объект Python не имеет требуемого типа, вызывается470471[`TypeError`](https://python-all.ru/3.4/library/exceptions.html#TypeError)472473.474475**`O&` (object) \[*converter*, *anything*\]**476477Преобразует объект Python в переменную C через функцию *converter*. Эта функция принимает два аргумента: первый – это функция, второй – адрес переменной C (произвольного типа), преобразованный к `void *`. Функция *converter* в свою очередь вызывается следующим образом:478479```c480status = converter(object, address);481```482483где *object* – это объект Python, который нужно преобразовать, а *address* – это аргумент `void*`, переданный функции [`PyArg_Parse*()`](https://python-all.ru/3.4/c-api/arg.html#c.PyArg_Parse). Возвращаемое значение *status* должно быть `1` при успешном преобразовании и `0` при неудаче. В случае ошибки функция *converter* должна возбудить исключение и оставить содержимое *address* без изменений.484485Если *converter* возвращает `Py_CLEANUP_SUPPORTED`, она может быть вызвана второй раз, если разбор аргументов в конечном итоге завершится неудачей, давая конвертеру возможность освободить любую память, которую он уже выделил. При этом втором вызове параметр *object* будет равен NULL; *address* будет иметь то же значение, что и при исходном вызове.486487Изменено в версии 3.1: `Py_CLEANUP_SUPPORTED` была добавлена.488489**`p` ([`bool`](https://python-all.ru/3.4/library/functions.html#bool)) \[int\]**490491Проверяет переданное значение на истинность (булев **p**редикат) и преобразует результат в эквивалентное целое значение C true/false. Устанавливает int в 1, если выражение истинно, и в 0, если ложно. Принимает любое допустимое значение Python. См. [*Проверка значений на истинность*](https://python-all.ru/3.4/library/stdtypes.html#truth) для получения дополнительной информации о том, как Python проверяет значения на истинность.492493Новое в версии 3.3.494495**`(items)` ([`tuple`](https://python-all.ru/3.4/library/stdtypes.html#tuple)) \[*matching-items*\]**496497Объект должен быть последовательностью Python, длина которой равна количеству единиц формата в498499*элементах*500501. Аргументы C должны соответствовать отдельным единицам формата в502503*элементах*504505. Единицы формата для последовательностей могут быть вложенными.506507Можно передавать «длинные» целые числа (целые, значение которых превышает `LONG_MAX` платформы), однако надлежащая проверка диапазона не выполняется – старшие биты молча отбрасываются, когда принимающее поле слишком мало для значения (на самом деле, семантика унаследована от понижающих приведений в C – результат может отличаться).508509Некоторые другие символы имеют значение в строке формата. Они не могут встречаться внутри вложенных скобок. Вот они:510511**`|`**512513Указывает, что остальные аргументы в списке аргументов Python являются необязательными. Переменные C, соответствующие необязательным аргументам, должны быть инициализированы значением по умолчанию – если необязательный аргумент не указан,514515[`PyArg_ParseTuple()`](https://python-all.ru/3.4/c-api/arg.html#c.PyArg_ParseTuple)516517не изменяет содержимое соответствующих переменных C.518519**`$`**520521Только для [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.4/c-api/arg.html#c.PyArg_ParseTupleAndKeywords): Указывает, что остальные аргументы в списке аргументов Python являются только ключевыми. В настоящее время все аргументы, передаваемые только по ключу, также должны быть необязательными, поэтому `|` всегда должен указываться перед `$` в строке формата.522523Новое в версии 3.3.524525**`:`**526527Список единиц формата заканчивается здесь; строка после двоеточия используется как имя функции в сообщениях об ошибках («связанное значение» исключения, которое возбуждает528529[`PyArg_ParseTuple()`](https://python-all.ru/3.4/c-api/arg.html#c.PyArg_ParseTuple)530531).532533**`;`**534535Список единиц форматирования заканчивается здесь; строка после точки с запятой используется как сообщение об ошибке536537*вместо*538539сообщения об ошибке по умолчанию.540541`:`542543и544545`;`546547взаимно исключают друг друга.548549Обратите внимание, что любые ссылки на объекты Python, передаваемые вызывающему, являются *заимствованными* ссылками; уменьшать их счётчик ссылок не следует.550551Дополнительные аргументы, передаваемые этим функциям, должны быть адресами переменных, тип которых определяется строкой формата; они используются для хранения значений из входного кортежа. Есть несколько случаев, как описано в списке единиц форматирования выше, когда эти параметры используются в качестве входных значений; в этом случае они должны соответствовать тому, что указано для соответствующей единицы форматирования.552553Чтобы преобразование прошло успешно, объект *arg* должен соответствовать формату, а формат должен быть исчерпан. В случае успеха функции [`PyArg_Parse*()`](https://python-all.ru/3.4/c-api/arg.html#c.PyArg_Parse) возвращают true, иначе возвращают false и возбуждают соответствующее исключение. Когда функции [`PyArg_Parse*()`](https://python-all.ru/3.4/c-api/arg.html#c.PyArg_Parse) завершаются ошибкой из-за сбоя преобразования в одной из единиц формата, переменные по адресам, соответствующим этой и следующим единицам формата, остаются нетронутыми.554555### API функции556557#### `int PyArg_ParseTuple(PyObject *args, const char *format, ...)`558559Разбирает параметры функции, принимающей только позиционные параметры, в локальные переменные. Возвращает true при успехе; при неудаче возвращает false и возбуждает соответствующее исключение.560561#### `int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)`562563Идентична [`PyArg_ParseTuple()`](https://python-all.ru/3.4/c-api/arg.html#c.PyArg_ParseTuple), за исключением того, что принимает va\_list вместо переменного числа аргументов.564565#### `int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)`566567Разбирает параметры функции, которая принимает как позиционные, так и именованные параметры, в локальные переменные. Возвращает true в случае успеха; в случае неудачи возвращает false и возбуждает соответствующее исключение.568569#### `int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)`570571Идентична [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.4/c-api/arg.html#c.PyArg_ParseTupleAndKeywords), за исключением того, что принимает va\_list вместо переменного числа аргументов.572573#### `int PyArg_ValidateKeywordArguments(PyObject *)`574575Гарантирует, что ключи в словаре аргументов keywords являются строками. Это требуется только в том случае, если [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.4/c-api/arg.html#c.PyArg_ParseTupleAndKeywords) не используется, поскольку последняя уже выполняет эту проверку.576577Новое в версии 3.2.578579#### `int PyArg_Parse(PyObject *args, const char *format, ...)`580581Функция для разбора списков аргументов «устаревших» функций – это функции, которые используют метод разбора параметров `METH_OLDARGS`, удалённый в Python 3. Не рекомендуется использовать её для разбора параметров в новом коде, и большая часть кода в стандартном интерпретаторе была изменена, чтобы больше не использовать её для этой цели. Однако она остаётся удобным способом разложения других кортежей и может продолжать использоваться для этой цели.582583#### `int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)`584585Более простая форма извлечения параметров, которая не использует строку формата для указания типов аргументов. Функции, использующие этот метод для извлечения параметров, должны быть объявлены как [`METH_VARARGS`](https://python-all.ru/3.4/c-api/structures.html#METH_VARARGS) в таблицах функций или методов. Кортеж, содержащий фактические параметры, должен передаваться как *args*; он должен быть именно кортежем. Длина кортежа должна быть не менее *min* и не более *max*; *min* и *max* могут быть равны. Дополнительные аргументы должны быть переданы функции, каждый из которых должен быть указателем на переменную [`PyObject*`](https://python-all.ru/3.4/c-api/structures.html#c.PyObject); они будут заполнены значениями из *args*; они будут содержать заимствованные ссылки. Переменные, соответствующие необязательным параметрам, не указанным в *args*, не будут заполнены; они должны быть инициализированы вызывающей стороной. Эта функция возвращает true при успехе и false, если *args* не является кортежем или содержит неверное количество элементов; в случае неудачи будет установлено исключение.586587Это пример использования этой функции, взятый из исходников вспомогательного модуля слабых ссылок `_weakref`:588589```c590static PyObject *591weakref_ref(PyObject *self, PyObject *args)592{593    PyObject *object;594    PyObject *callback = NULL;595    PyObject *result = NULL;596597    if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {598        result = PyWeakref_NewRef(object, callback);599    }600    return result;601}602```603604Вызов [`PyArg_UnpackTuple()`](https://python-all.ru/3.4/c-api/arg.html#c.PyArg_UnpackTuple) в этом примере полностью эквивалентен следующему вызову [`PyArg_ParseTuple()`](https://python-all.ru/3.4/c-api/arg.html#c.PyArg_ParseTuple):605606```c607PyArg_ParseTuple(args, "O|O:ref", &object, &callback)608```609610## Построение значений611612#### `PyObject* Py_BuildValue(const char *format, ...)`613614*Возвращаемое значение: новая ссылка.*615616Создаёт новое значение на основе строки формата, аналогичной тем, которые принимаются семейством функций [`PyArg_Parse*()`](https://python-all.ru/3.4/c-api/arg.html#c.PyArg_Parse), и последовательности значений. Возвращает значение или *NULL* в случае ошибки; если возвращается *NULL*, будет возбуждено исключение.617618[`Py_BuildValue()`](https://python-all.ru/3.4/c-api/arg.html#c.Py_BuildValue) не всегда строит кортеж. Он строит кортеж, только если его строка формата содержит две или более единиц формата. Если строка формата пуста, она возвращает `None`; если содержит ровно одну единицу формата, возвращает объект, описываемый этой единицей формата. Чтобы принудительно вернуть кортеж размером 0 или 1, заключите строку формата в скобки.619620Когда буферы памяти передаются в качестве параметров для предоставления данных для построения объектов, как для форматов `s` и `s#`, необходимые данные копируются. Буферы, предоставленные вызывающей стороной, никогда не используются напрямую объектами, созданными [`Py_BuildValue()`](https://python-all.ru/3.4/c-api/arg.html#c.Py_BuildValue). Другими словами, если ваш код вызывает `malloc()` и передаёт выделенную память в [`Py_BuildValue()`](https://python-all.ru/3.4/c-api/arg.html#c.Py_BuildValue), ваш код отвечает за вызов `free()` для этой памяти после возврата из [`Py_BuildValue()`](https://python-all.ru/3.4/c-api/arg.html#c.Py_BuildValue).621622В следующем описании форма в кавычках – это элемент формата; запись в круглых скобках – это тип объекта Python, который вернёт элемент формата; а запись в квадратных скобках – это тип передаваемого(-ых) значения(-ий) C.623624Символы пробела, табуляции, двоеточия и запятой игнорируются в строках формата (но не внутри единиц формата, таких как `s#`). Это позволяет сделать длинные строки формата немного более читаемыми.625626**`s` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str) или `None`) \[char \*\]**627628Преобразует C-строку, завершающуюся нулевым символом, в объект Python629630[`str`](https://python-all.ru/3.4/library/stdtypes.html#str)631632с использованием кодировки633634`'utf-8'`635636. Если указатель на C-строку равен637638*NULL*639640, используется641642`None`643644.645646**`s#` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str) или `None`) \[char \*, int\]**647648Преобразует C-строку и её длину в объект Python649650[`str`](https://python-all.ru/3.4/library/stdtypes.html#str)651652с использованием кодировки653654`'utf-8'`655656. Если указатель на C-строку равен657658*NULL*659660, длина игнорируется и возвращается661662`None`663664.665666**`y` ([`bytes`](https://python-all.ru/3.4/library/functions.html#bytes)) \[char \*\]**667668Преобразует C-строку в объект Python669670[`bytes`](https://python-all.ru/3.4/library/functions.html#bytes)671672. Если указатель на C-строку равен673674*NULL*675676, возвращается677678`None`679680.681682**`y#` ([`bytes`](https://python-all.ru/3.4/library/functions.html#bytes)) \[char \*, int\]**683684Преобразует C-строку и её длину в объект Python. Если указатель на C-строку равен685686*NULL*687688, возвращается689690`None`691692.693694**`z` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str) или `None`) \[char \*\]**695696То же, что и697698`s`699700.701702**`z#` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str) или `None`) \[char \*, int\]**703704То же, что и705706`s#`707708.709710**`u` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str)) \[Py\_UNICODE \*\]**711712Преобразует буфер с нулевым символом в конце, содержащий данные Unicode (UCS-2 или UCS-4), в объект Unicode Python. Если указатель буфера Unicode равен713714*NULL*715716, возвращается717718`None`719720.721722**`u#` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str)) \[Py\_UNICODE \*, int\]**723724Преобразует буфер данных Unicode (UCS-2 или UCS-4) и его длину в объект Unicode Python. Если указатель буфера Unicode равен725726*NULL*727728, длина игнорируется и возвращается729730`None`731732.733734**`U` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str) или `None`) \[char \*\]**735736То же, что и737738`s`739740.741742**`U#` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str) или `None`) \[char \*, int\]**743744То же, что и745746`s#`747748.749750**`i` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[int\]**751752Преобразует обычный C753754`int`755756в объект Python целого типа.757758**`b` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[char\]**759760Преобразует обычный C761762`char`763764в объект Python целого типа.765766**`h` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[short int\]**767768Преобразует обычное C769770`short int`771772в объект Python int.773774**`l` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[long int\]**775776Преобразует C777778`long int`779780в объект Python int.781782**`B` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[unsigned char\]**783784Преобразует C785786`unsigned char`787788в объект Python int.789790**`H` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[unsigned short int\]**791792Преобразует C793794`unsigned short int`795796в объект Python int.797798**`I` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[unsigned int\]**799800Преобразует C801802`unsigned int`803804в объект Python int.805806**`k` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[unsigned long\]**807808Преобразует C809810`unsigned long`811812в объект Python int.813814**`L` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[PY\_LONG\_LONG\]**815816Преобразует C817818`long long`819820в объект Python int. Доступно только на платформах, поддерживающих821822`long long`823824(или825826`_int64`827828в Windows).829830**`K` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[unsigned PY\_LONG\_LONG\]**831832Преобразует C833834`unsigned long long`835836в объект Python int. Доступно только на платформах, поддерживающих837838`unsigned long long`839840(или841842`unsigned _int64`843844в Windows).845846**`n` ([`int`](https://python-all.ru/3.4/library/functions.html#int)) \[Py\_ssize\_t\]**847848Преобразует C849850`Py_ssize_t`851852в Python int.853854**`c` ([`bytes`](https://python-all.ru/3.4/library/functions.html#bytes) длиной 1) \[char\]**855856Преобразует C857858`int`859860, представляющий байт, в объект Python861862[`bytes`](https://python-all.ru/3.4/library/functions.html#bytes)863864длиной 1.865866**`C` ([`str`](https://python-all.ru/3.4/library/stdtypes.html#str) длиной 1) \[int\]**867868Преобразует C869870`int`871872, представляющий символ, в объект Python873874[`str`](https://python-all.ru/3.4/library/stdtypes.html#str)875876длиной 1.877878**`d` ([`float`](https://python-all.ru/3.4/library/functions.html#float)) \[double\]**879880Преобразует C881882`double`883884в число с плавающей точкой Python.885886**`f` ([`float`](https://python-all.ru/3.4/library/functions.html#float)) \[float\]**887888Преобразует C889890`float`891892в число с плавающей точкой Python.893894**`D` ([`complex`](https://python-all.ru/3.4/library/functions.html#complex)) \[Py\_complex \*\]**895896Преобразует структуру C897898[`Py_complex`](https://python-all.ru/3.4/c-api/complex.html#c.Py_complex)899900в комплексное число Python.901902**`O` (объект) \[PyObject \*\]**903904Передаёт объект Python без изменений (за исключением счётчика ссылок, который увеличивается на единицу). Если переданный объект является указателем905906*NULL*907908, считается, что это произошло из-за того, что вызов, формирующий аргумент, обнаружил ошибку и установил исключение. Поэтому909910[`Py_BuildValue()`](https://python-all.ru/3.4/c-api/arg.html#c.Py_BuildValue)911912вернёт913914*NULL*915916, но не вызовет исключение. Если ещё не было установлено никакого исключения, устанавливается917918[`SystemError`](https://python-all.ru/3.4/library/exceptions.html#SystemError)919920.921922**`S` (объект) \[PyObject \*\]**923924То же, что и925926`O`927928.929930**`N` (объект) \[PyObject \*\]**931932То же, что и933934`O`935936, за исключением того, что не увеличивает счётчик ссылок на объект. Полезно, когда объект создаётся вызовом конструктора объекта в списке аргументов.937938**`O&` (объект) \[*converter*, *anything*\]**939940Преобразует941942*anything*943944в объект Python с помощью функции945946*converter*947948. Функция вызывается с аргументом949950*anything*951952(который должен быть совместим с953954`void *`955956) и должна возвращать «новый» объект Python или957958*NULL*959960в случае ошибки.961962**`(items)` ([`tuple`](https://python-all.ru/3.4/library/stdtypes.html#tuple)) \[*matching-items*\]**963964Преобразует последовательность значений C в кортеж Python с тем же количеством элементов.965966**`[items]` ([`list`](https://python-all.ru/3.4/library/stdtypes.html#list)) \[*matching-items*\]**967968Преобразует последовательность значений C в список Python с тем же количеством элементов.969970**`{items}` ([`dict`](https://python-all.ru/3.4/library/stdtypes.html#dict)) \[*matching-items*\]**971972Преобразует последовательность значений C в словарь Python. Каждая пара последовательных значений C добавляет один элемент в словарь, выступая в роли ключа и значения соответственно.973974Если в строке формата есть ошибка, устанавливается исключение [`SystemError`](https://python-all.ru/3.4/library/exceptions.html#SystemError) и возвращается *NULL*.975976#### `PyObject* Py_VaBuildValue(const char *format, va_list vargs)`977978Идентична [`Py_BuildValue()`](https://python-all.ru/3.4/c-api/arg.html#c.Py_BuildValue), за исключением того, что принимает va\_list вместо переменного числа аргументов.979