arg.md

1> **Источник:** https://python-all.ru/3.0/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.0/extending/index.html#extending-index).1011Первые три из описанных функций, [`PyArg_ParseTuple`](https://python-all.ru/3.0/c-api/arg.html#PyArg_ParseTuple), [`PyArg_ParseTupleAndKeywords`](https://python-all.ru/3.0/c-api/arg.html#PyArg_ParseTupleAndKeywords) и [`PyArg_Parse`](https://python-all.ru/3.0/c-api/arg.html#PyArg_Parse), используют *строки формата*, которые сообщают функции об ожидаемых аргументах. Синтаксис строк формата одинаков для всех этих функций.1213Строка формата состоит из нуля или более «единиц формата». Единица формата описывает один объект Python; обычно это один символ или заключённая в скобки последовательность единиц формата. За несколькими исключениями, единица формата, не являющаяся последовательностью в скобках, обычно соответствует одному аргументу-адресу этих функций. В следующем описании приведённая в кавычках форма – это единица формата; запись в круглых скобках – тип объекта Python, которому соответствует единица формата; а запись в квадратных скобках – тип переменной(ых) C, чей адрес следует передать.1415**`s` (строковый или Unicode-объект) \[const char \*\]**1617Преобразует строковый или Unicode-объект Python в указатель C на строку символов. Не нужно выделять память для самой строки; указатель на существующую строку сохраняется в переменную-указатель на символ, адрес которой передается. Строка C завершается нулевым символом. Строка Python не должна содержать встроенных нулевых байтов; если они есть, возбуждается исключение [`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError). Unicode-объекты преобразуются в C-строки с использованием кодировки по умолчанию. Если такое преобразование не удается, возбуждается [`UnicodeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.UnicodeError).1819Начиная с Python 2.5 тип аргумента длины можно контролировать, определив макрос `PY_SSIZE_T_CLEAN` до включения `Python.h`. Если макрос определен, длина имеет тип `Py_ssize_t`, а не int.2021**`s*` (строковый, Unicode или любой объект, совместимый с буфером) \[Py\_buffer \*\]**2223Этот вариант похож на2425`s`2627, но код заполняет структуру2829[`Py_buffer`](https://python-all.ru/3.0/c-api/buffer.html#Py_buffer)3031, предоставленную вызывающим кодом. В этом случае строка Python может содержать встроенные нулевые байты. Unicode-объекты возвращают указатель на строковое представление объекта в кодировке по умолчанию, если такое преобразование возможно. Базовый буфер блокируется, так что вызывающий код может впоследствии использовать буфер даже внутри блока3233`Py_BEGIN_ALLOW_THREADS`3435.3637**Вызывающий код отвечает**3839за вызов4041`PyBuffer_Release`4243со структурой после обработки данных.4445**`s#` (строковый, Unicode или любой объект, совместимый с буфером чтения) \[const char \*, int или `Py_ssize_t`\]**4647Этот вариант `s` сохраняет результат в две C-переменные: первая – указатель на строку символов, вторая – её длина. В этом случае строка Python может содержать встроенные нулевые байты. Unicode-объекты возвращают указатель на строковое представление объекта в кодировке по умолчанию, если такое преобразование возможно. Все остальные объекты, совместимые с буфером чтения, возвращают ссылку на сырое внутреннее представление данных. Поскольку этот формат не допускает объекты, совместимые с буфером записи (например, массивы байтов), предпочтительнее использовать `s*`.4849Тип аргумента длины (int или `Py_ssize_t`) контролируется определением макроса `PY_SSIZE_T_CLEAN` до включения `Python.h`. Если макрос был определен, длина имеет тип `Py_ssize_t`, а не int. Это поведение изменится в будущей версии Python – будет поддерживаться только `Py_ssize_t`, а поддержка int будет удалена. Лучше всегда определять `PY_SSIZE_T_CLEAN`.5051**`y` (объект bytes) \[const char \*\]**5253Этот вариант5455`s`5657преобразует объект Python bytes или bytearray в указатель C на строку символов. Объект bytes не должен содержать встроенных нулевых байтов (NUL); если они есть, возбуждается исключение5859[`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)6061.6263**`y*` (объект bytes) \[Py\_buffer \*\]**6465Это относится к6667`s*`6869так же, как7071`y`7273относится к7475`s`7677.7879**`y#` (объект bytes) \[const char \*, int\]**8081Этот вариант8283`s#`8485сохраняет результат в две C-переменные: первая – указатель на строку символов, вторая – её длина. Он принимает только байтовые объекты, не массивы байтов.8687**`z` (строковый или `None`) \[const char \*\]**8889Аналогично9091`s`9293, но объект Python также может быть9495`None`9697, и в этом случае указатель C устанавливается в9899*NULL*100101.102103**`z*` (строковый, `None` или любой объект, совместимый с буфером) \[Py\_buffer\*\]**104105Это относится к106107`s*`108109так же, как110111`z`112113относится к114115`s`116117.118119**`z#` (строковый, `None` или любой объект, совместимый с буфером чтения) \[const char \*, int\]**120121Это относится к122123`s#`124125так же, как126127`z`128129относится к130131`s`132133.134135**`u` (Unicode-объект) \[Py\_UNICODE \*\]**136137Преобразует Unicode-объект Python в указатель C на буфер с завершающим нулем, содержащий 16-битные Unicode-данные (UTF-16). Как и в138139`s`140141, нет необходимости выделять память для буфера Unicode-данных; указатель на существующие Unicode-данные сохраняется в переменную-указатель142143[`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE)144145, адрес которой передается.146147**`u#` (Unicode-объект) \[Py\_UNICODE \*, int\]**148149Этот вариант150151`u`152153сохраняет результат в две C-переменные: первая – указатель на буфер Unicode-данных, вторая – его длина. Не-Unicode-объекты обрабатываются путем интерпретации их указателя буфера чтения как указателя на массив154155[`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE)156157.158159**`Z` (Unicode или `None`) \[Py\_UNICODE \*\]**160161Аналогично162163`s`164165, но объект Python также может быть166167`None`168169, и в этом случае указатель C устанавливается в170171*NULL*172173.174175**`Z#` (Unicode или `None`) \[Py\_UNICODE \*, int\]**176177Это относится к178179`u#`180181так же, как182183`Z`184185относится к186187`u`188189.190191**`es` (строковый, Unicode-объект или объект, совместимый с символьным буфером) \[const char \*encoding, char \*\*buffer\]**192193Этот вариант `s` используется для кодирования Unicode и объектов, преобразуемых в Unicode, в символьный буфер. Он работает только с закодированными данными без встроенных нулевых байтов (NUL).194195Этот формат требует два аргумента. Первый используется только как входной и должен быть `const char*`, указывающим на имя кодировки в виде строки, завершающейся нулем, или *NULL*; в последнем случае используется кодировка по умолчанию. Если указанная кодировка не известна Python, возбуждается исключение. Второй аргумент должен быть `char**`; значение указателя, на который он ссылается, будет установлено на буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, указанной первым аргументом.196197[`PyArg_ParseTuple`](https://python-all.ru/3.0/c-api/arg.html#PyArg_ParseTuple) выделит буфер необходимого размера, скопирует закодированные данные в этот буфер и настроит *\*buffer* так, чтобы он ссылался на вновь выделенную память. Вызывающий код отвечает за вызов [`PyMem_Free`](https://python-all.ru/3.0/c-api/memory.html#PyMem_Free) для освобождения выделенного буфера после использования.198199**`et` (строка, объект Unicode или объект, совместимый с символьным буфером) \[const char \*encoding, char \*\*buffer\]**200201То же, что и202203`es`204205, за исключением того, что 8-битные строковые объекты передаются без перекодировки. Вместо этого реализация предполагает, что строковый объект использует кодировку, переданную в качестве параметра.206207**`es#` (строка, объект Unicode или объект, совместимый с символьным буфером) \[const char \*encoding, char \*\*buffer, int \*buffer\_length\]**208209Этот вариант `s#` используется для кодирования Unicode и объектов, преобразуемых в Unicode, в символьный буфер. В отличие от формата `es`, этот вариант допускает входные данные, содержащие NUL-символы.210211Он требует три аргумента. Первый используется только для ввода и должен быть `const char*`, указывающим на имя кодировки в виде строки, завершающейся NUL, или *NULL*; в последнем случае используется кодировка по умолчанию. Если именованная кодировка неизвестна Python, возбуждается исключение. Второй аргумент должен быть `char**`; значение указателя, на который он ссылается, будет установлено на буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, указанной первым аргументом. Третий аргумент должен быть указателем на целое число; целое число, на которое он ссылается, будет установлено на количество байт в выходном буфере.212213Существует два режима работы:214215Если *\*buffer* указывает на указатель *NULL*, функция выделит буфер нужного размера, скопирует закодированные данные в этот буфер и установит *\*buffer* ссылкой на вновь выделенную память. Вызывающий отвечает за вызов [`PyMem_Free`](https://python-all.ru/3.0/c-api/memory.html#PyMem_Free) для освобождения выделенного буфера после использования.216217If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer), [`PyArg_ParseTuple`](https://python-all.ru/3.0/c-api/arg.html#PyArg_ParseTuple) will use this location as the buffer and interpret the initial value of *\*buffer\_length* as the buffer size. It will then copy the encoded data into the buffer and NUL-terminate it. If the buffer is not large enough, a [`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError) will be set.218219В обоих случаях *\*buffer\_length* устанавливается в длину закодированных данных без завершающего NUL-байта.220221**`et#` (строка, объект Unicode или объект, совместимый с символьным буфером) \[const char \*encoding, char \*\*buffer\]**222223То же, что и224225`es#`226227, за исключением того, что строковые объекты передаются без перекодировки. Вместо этого реализация предполагает, что строковый объект использует кодировку, переданную в качестве параметра.228229**`b` (целое число) \[unsigned char\]**230231Преобразует неотрицательное целое число Python в беззнаковое крошечное целое, хранящееся в C232233`unsigned char`234235.236237**`B` (целое число) \[unsigned char\]**238239Преобразует целое число Python в крошечное целое без проверки переполнения, хранящееся в C240241`unsigned char`242243.244245**`h` (целое число) \[short int\]**246247Преобразует целое число Python в C248249`short int`250251.252253**`H` (целое число) \[unsigned short int\]**254255Преобразует целое число Python в C256257`unsigned short int`258259без проверки переполнения.260261**`i` (целое число) \[int\]**262263Преобразует целое число Python в обычный C264265`int`266267.268269**`I` (целое число) \[unsigned int\]**270271Преобразует целое число Python в C272273`unsigned int`274275без проверки переполнения.276277**`l` (целое число) \[long int\]**278279Преобразует целое число Python в C280281`long int`282283.284285**`k` (целое число) \[unsigned long\]**286287Преобразует целое число Python в C288289`unsigned long`290291без проверки переполнения.292293**`L` (целое число) \[PY\_LONG\_LONG\]**294295Преобразует целое число Python в C296297`long long`298299. Этот формат доступен только на платформах, поддерживающих300301`long long`302303(или304305`_int64`306307на Windows).308309**`K` (целое число) \[unsigned PY\_LONG\_LONG\]**310311Преобразует целое число Python в C312313`unsigned long long`314315без проверки переполнения. Этот формат доступен только на платформах, поддерживающих316317`unsigned long long`318319(или320321`unsigned _int64`322323на Windows).324325**`n` (целое число) \[Py\_ssize\_t\]**326327Преобразует целое число Python в C328329`Py_ssize_t`330331.332333**`c` (строка длиной 1) \[char\]**334335Преобразует символ Python, представленный в виде строки длиной 1, в C336337`char`338339.340341**`f` (число с плавающей запятой) \[float\]**342343Преобразует число с плавающей запятой Python в C344345`float`346347.348349**`d` (число с плавающей запятой) \[double\]**350351Преобразует число с плавающей запятой Python в C352353`double`354355.356357**`D` (комплексное число) \[Py\_complex\]**358359Преобразует комплексное число Python в структуру C360361[`Py_complex`](https://python-all.ru/3.0/c-api/complex.html#Py_complex)362363.364365**`O` (объект) \[PyObject \*\]**366367Сохраняет объект Python (без какого-либо преобразования) в указателе на объект C. Таким образом, программа на C получает фактически переданный объект. Счётчик ссылок объекта не увеличивается. Сохранённый указатель не равен368369*NULL*370371.372373**`O!` (объект) \[*typeobject*, PyObject \*\]**374375Сохраняет объект Python в указателе на объект C. Это похоже на376377`O`378379, но принимает два аргумента C: первый – адрес объекта типа Python, второй – адрес переменной C (типа380381[`PyObject*`](https://python-all.ru/3.0/c-api/structures.html#PyObject)382383), в который сохраняется указатель на объект. Если объект Python не имеет требуемого типа, вызывается384385[`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)386387.388389**`O&` (объект) \[*converter*, *anything*\]**390391Преобразует объект Python в переменную C через функцию *converter*. Эта функция принимает два аргумента: первый – это функция, второй – адрес переменной C (произвольного типа), преобразованный к `void *`. Функция *converter* в свою очередь вызывается следующим образом:392393```c394status = converter(object, address);395```396397где *object* – это преобразуемый объект Python, а *address* – это аргумент `void*`, переданный функции [`PyArg_Parse*`](https://python-all.ru/3.0/c-api/arg.html#PyArg_Parse). Возвращаемый *status* должен быть `1` при успешном преобразовании и `0`, если преобразование завершилось неудачей. При неудаче функция *converter* должна возбудить исключение и оставить содержимое *address* без изменений.398399**`S` (строка) \[PyStringObject \*\]**400401Подобно402403`O`404405, но требует, чтобы объект Python был строковым объектом. Возбуждает406407[`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)408409, если объект не является строковым. C-переменная может также быть объявлена как410411[`PyObject*`](https://python-all.ru/3.0/c-api/structures.html#PyObject)412413.414415**`U` (строка Unicode) \[PyUnicodeObject \*\]**416417Подобно418419`O`420421, но требует, чтобы объект Python был объектом Unicode. Возбуждает422423[`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)424425, если объект не является объектом Unicode. C-переменная может также быть объявлена как426427[`PyObject*`](https://python-all.ru/3.0/c-api/structures.html#PyObject)428429.430431**`t#` (буфер символов только для чтения) \[char \*, int\]**432433Как и434435`s#`436437, но принимает любой объект, реализующий интерфейс буфера только для чтения. Переменная438439`char*`440441устанавливается указателем на первый байт буфера, а442443`int`444445– длиной буфера. Принимаются только объекты с односегментным буфером; для всех остальных возбуждается446447[`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)448449.450451**`w` (символьный буфер для чтения и записи) \[char \*\]**452453Аналогично454455`s`456457, но принимает любой объект, реализующий интерфейс буфера для чтения и записи. Вызывающий код должен определить длину буфера другим способом или использовать458459`w#`460461. Принимаются только односегментные буферы; для всех остальных возбуждается462463[`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)464465.466467**`w*` (байт-ориентированный буфер для чтения и записи) \[Py\_buffer \*\]**468469Это то же самое по отношению к470471`w`472473, что474475`s*`476477к478479`s`480481.482483**`w#` (символьный буфер для чтения и записи) \[char \*, int\]**484485Как486487`s#`488489, но принимает любой объект, реализующий интерфейс буфера для чтения и записи. Переменная490491`char *`492493устанавливается так, чтобы указывать на первый байт буфера, а494495`int`496497– на длину буфера. Принимаются только односегментные буферы; для всех остальных возбуждается498499[`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)500501.502503**`(items)` (кортеж) \[*matching-items*\]**504505Объект должен быть последовательностью Python, длина которой равна количеству единиц формата в506507*элементах*508509. Аргументы C должны соответствовать отдельным единицам формата в510511*элементах*512513. Единицы формата для последовательностей могут быть вложенными.514515Можно передавать «длинные» целые числа (целые, значение которых превышает `LONG_MAX` платформы), однако надлежащая проверка диапазона не выполняется – старшие биты молча отбрасываются, когда принимающее поле слишком мало для значения (на самом деле, семантика унаследована от понижающих приведений в C – результат может отличаться).516517Некоторые другие символы имеют значение в строке формата. Они не могут встречаться внутри вложенных скобок. Вот они:518519**`|`**520521Указывает, что остальные аргументы в списке аргументов Python являются необязательными. Переменные C, соответствующие необязательным аргументам, должны быть инициализированы значением по умолчанию – если необязательный аргумент не указан,522523[`PyArg_ParseTuple`](https://python-all.ru/3.0/c-api/arg.html#PyArg_ParseTuple)524525не изменяет содержимое соответствующих переменных C.526527**`:`**528529Список форматных единиц заканчивается здесь; строка после двоеточия используется как имя функции в сообщениях об ошибках (так называемое «связанное значение» исключения, которое возбуждает530531[`PyArg_ParseTuple`](https://python-all.ru/3.0/c-api/arg.html#PyArg_ParseTuple)532533).534535**`;`**536537Список единиц форматирования заканчивается здесь; строка после точки с запятой используется как сообщение об ошибке538539*вместо*540541сообщения об ошибке по умолчанию.542543`:`544545и546547`;`548549взаимно исключают друг друга.550551Обратите внимание, что любые ссылки на объекты Python, передаваемые вызывающему, являются *заимствованными* ссылками; уменьшать их счётчик ссылок не следует.552553Дополнительные аргументы, передаваемые этим функциям, должны быть адресами переменных, тип которых определяется строкой формата; они используются для хранения значений из входного кортежа. Есть несколько случаев, как описано в списке единиц форматирования выше, когда эти параметры используются в качестве входных значений; в этом случае они должны соответствовать тому, что указано для соответствующей единицы форматирования.554555Для успешного преобразования объект *arg* должен соответствовать формату, и формат должен быть полностью исчерпан. В случае успеха функции [`PyArg_Parse*`](https://python-all.ru/3.0/c-api/arg.html#PyArg_Parse) возвращают true, иначе – false и возбуждают соответствующее исключение. Когда функции [`PyArg_Parse*`](https://python-all.ru/3.0/c-api/arg.html#PyArg_Parse) завершаются ошибкой из-за сбоя преобразования в одной из форматных единиц, переменные по адресам, соответствующим этой и последующим форматным единицам, остаются нетронутыми.556557**\[PyArg\_ParseTuple\]int `PyArg_ParseTuple`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*args*, const char *\*format*, ...)**558559Разбирает параметры функции, принимающей только позиционные параметры, в локальные переменные. Возвращает true при успехе; при неудаче возвращает false и возбуждает соответствующее исключение.560561**\[PyArg\_VaParse\]int `PyArg_VaParse`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*args*, const char *\*format*, va\_list *vargs*)**562563Идентична564565[`PyArg_ParseTuple`](https://python-all.ru/3.0/c-api/arg.html#PyArg_ParseTuple)566567, за исключением того, что принимает va\_list вместо переменного числа аргументов.568569**\[PyArg\_ParseTupleAndKeywords\]int `PyArg_ParseTupleAndKeywords`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*args*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*kw*, const char *\*format*, char *\*keywords\[\]*, ...)**570571Разбирает параметры функции, которая принимает как позиционные, так и именованные параметры, в локальные переменные. Возвращает true в случае успеха; в случае неудачи возвращает false и возбуждает соответствующее исключение.572573**\[PyArg\_VaParseTupleAndKeywords\]int `PyArg_VaParseTupleAndKeywords`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*args*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*kw*, const char *\*format*, char *\*keywords\[\]*, va\_list *vargs*)**574575Идентична576577[`PyArg_ParseTupleAndKeywords`](https://python-all.ru/3.0/c-api/arg.html#PyArg_ParseTupleAndKeywords)578579, за исключением того, что принимает va\_list вместо переменного числа аргументов.580581**\[PyArg\_Parse\]int `PyArg_Parse`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*args*, const char *\*format*, ...)**582583Функция, используемая для разбора списков аргументов «старых» функций – это функции, использующие584585`METH_OLDARGS`586587разбор параметров метод. Не рекомендуется использовать его для разбора параметров в новом коде, и большая часть кода в стандартном интерпретаторе была изменена, чтобы больше не использовать этот метод для этой цели. Тем не менее, он остаётся удобным способом разложения других кортежей, однако и может по-прежнему использоваться для этой цели.588589**\[PyArg\_UnpackTuple\]int `PyArg_UnpackTuple`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*args*, const char *\*name*, Py\_ssize\_t *min*, Py\_ssize\_t *max*, ...)**590591Более простая форма извлечения параметров, которая не использует строку формата для указания типов аргументов. Функции, использующие этот метод для извлечения параметров, должны быть объявлены как [`METH_VARARGS`](https://python-all.ru/3.0/c-api/structures.html#METH_VARARGS) в таблицах функций или методов. Кортеж, содержащий фактические параметры, должен передаваться как *args*; он должен быть именно кортежем. Длина кортежа должна быть не менее *min* и не более *max*; *min* и *max* могут быть равны. Дополнительные аргументы должны быть переданы функции, каждый из которых должен быть указателем на переменную [`PyObject*`](https://python-all.ru/3.0/c-api/structures.html#PyObject); они будут заполнены значениями из *args*; они будут содержать заимствованные ссылки. Переменные, соответствующие необязательным параметрам, не указанным в *args*, не будут заполнены; они должны быть инициализированы вызывающей стороной. Эта функция возвращает true при успехе и false, если *args* не является кортежем или содержит неверное количество элементов; в случае неудачи будет установлено исключение.592593Это пример использования этой функции, взятый из исходников вспомогательного модуля слабых ссылок `_weakref`:594595```c596static PyObject *597weakref_ref(PyObject *self, PyObject *args)598{599    PyObject *object;600    PyObject *callback = NULL;601    PyObject *result = NULL;602603    if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {604        result = PyWeakref_NewRef(object, callback);605    }606    return result;607}608```609610Вызов [`PyArg_UnpackTuple`](https://python-all.ru/3.0/c-api/arg.html#PyArg_UnpackTuple) в этом примере полностью эквивалентен вызову [`PyArg_ParseTuple`](https://python-all.ru/3.0/c-api/arg.html#PyArg_ParseTuple):611612```c613PyArg_ParseTuple(args, "O|O:ref", &object, &callback)614```615616**\[Py\_BuildValue\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `Py_BuildValue`(const char *\*format*, ...)**617618*Возвращаемое значение: новая ссылка.*619620Создаёт новое значение на основе форматной строки, аналогичной тем, что принимает семейство функций [`PyArg_Parse*`](https://python-all.ru/3.0/c-api/arg.html#PyArg_Parse), и последовательности значений. Возвращает значение или *NULL* в случае ошибки; при возврате *NULL* возбуждается исключение.621622[`Py_BuildValue`](https://python-all.ru/3.0/c-api/arg.html#Py_BuildValue) не всегда строит кортеж. Он строит кортеж, только если его форматная строка содержит две или более форматных единицы. Если форматная строка пуста, возвращается `None`; если она содержит ровно одну форматную единицу, возвращается объект, описываемый этой единицей. Чтобы принудительно вернуть кортеж размера 0 или 1, форматную строку нужно заключить в скобки.623624Когда буферы памяти передаются в качестве параметров для предоставления данных при создании объектов (как для форматов `s` и `s#`), необходимые данные копируются. Буферы, предоставленные вызывающим кодом, никогда не используются напрямую объектами, созданными [`Py_BuildValue`](https://python-all.ru/3.0/c-api/arg.html#Py_BuildValue). Другими словами, если код вызывает `malloc` и передаёт выделенную память в [`Py_BuildValue`](https://python-all.ru/3.0/c-api/arg.html#Py_BuildValue), то он же отвечает за вызов `free` для этой памяти после возврата из [`Py_BuildValue`](https://python-all.ru/3.0/c-api/arg.html#Py_BuildValue).625626В следующем описании форма в кавычках – это элемент формата; запись в круглых скобках – это тип объекта Python, который вернёт элемент формата; а запись в квадратных скобках – это тип передаваемого(-ых) значения(-ий) C.627628Символы пробела, табуляции, двоеточия и запятой игнорируются в строках формата (но не внутри единиц формата, таких как `s#`). Это позволяет сделать длинные строки формата немного более читаемыми.629630**`s` (строка) \[char \*\]**631632Преобразует C-строку, завершающуюся нулевым символом, в объект Python. Если указатель на C-строку равен633634*NULL*635636, используется637638`None`639640.641642**`s#` (строка) \[char \*, int\]**643644Преобразует C-строку и её длину в объект Python. Если указатель на C-строку равен645646*NULL*647648, длина игнорируется и возвращается649650`None`651652.653654**`y` (байты) \[char \*\]**655656Эта функция преобразует C строку в объект Python657658[`bytes()`](https://python-all.ru/3.0/library/functions.html#bytes)659660. Если указатель на C строку равен661662*NULL*663664, возвращается665666`None`667668.669670**`y#` (байты) \[char \*, int\]**671672Преобразует C-строку и её длину в объект Python. Если указатель на C-строку равен673674*NULL*675676, возвращается677678`None`679680.681682**`z` (строка или `None`) \[char \*\]**683684То же, что и685686`s`687688.689690**`z#` (строка или `None`) \[char \*, int\]**691692То же, что и693694`s#`695696.697698**`u` (строка Unicode) \[Py\_UNICODE \*\]**699700Преобразует буфер с нулевым символом в конце, содержащий данные Unicode (UCS-2 или UCS-4), в объект Unicode Python. Если указатель буфера Unicode равен701702*NULL*703704, возвращается705706`None`707708.709710**`u#` (строка Unicode) \[Py\_UNICODE \*, int\]**711712Преобразует буфер данных Unicode (UCS-2 или UCS-4) и его длину в объект Unicode Python. Если указатель буфера Unicode равен713714*NULL*715716, длина игнорируется и возвращается717718`None`719720.721722**`U` (строка) \[char \*\]**723724Преобразует C-строку, завершающуюся нулевым символом, в объект Python unicode. Если указатель на C-строку равен725726*NULL*727728, используется729730`None`731732.733734**`U#` (строка) \[char \*, int\]**735736Преобразует C-строку и её длину в объект Python unicode. Если указатель на C-строку равен737738*NULL*739740, длина игнорируется и возвращается741742`None`743744.745746**`i` (целое) \[int\]**747748Преобразует обычный C749750`int`751752в объект Python целого типа.753754**`b` (целое) \[char\]**755756Преобразует обычный C757758`char`759760в объект Python целого типа.761762**`h` (целое) \[short int\]**763764Преобразует обычное C765766`short int`767768в объект Python int.769770**`l` (целое) \[long int\]**771772Преобразует C773774`long int`775776в объект Python int.777778**`B` (целое) \[unsigned char\]**779780Преобразует C781782`unsigned char`783784в объект Python int.785786**`H` (целое) \[unsigned short int\]**787788Преобразует C789790`unsigned short int`791792в объект Python int.793794**`I` (целое) \[unsigned int\]**795796Преобразует C797798`unsigned int`799800в объект Python int.801802**`k` (целое) \[unsigned long\]**803804Преобразует C805806`unsigned long`807808в объект Python int.809810**`L` (длинное) \[PY\_LONG\_LONG\]**811812Преобразует C813814`long long`815816в объект целого числа Python. Доступно только на платформах, поддерживающих817818`long long`819820.821822**`K` (длинное) \[unsigned PY\_LONG\_LONG\]**823824Преобразует C825826`unsigned long long`827828в объект целого числа Python. Доступно только на платформах, поддерживающих829830`unsigned long long`831832.833834**`n` (целое) \[Py\_ssize\_t\]**835836Преобразует C837838`Py_ssize_t`839840в Python int.841842**`c` (строка длины 1) \[char\]**843844Преобразует C845846`int`847848, представляющий символ, в строку Python длины 1.849850**`d` (вещественное) \[double\]**851852Преобразует C853854`double`855856в число с плавающей точкой Python.857858**`f` (вещественное) \[float\]**859860То же, что и861862`d`863864.865866**`D` (комплексное) \[Py\_complex \*\]**867868Преобразует структуру C869870[`Py_complex`](https://python-all.ru/3.0/c-api/complex.html#Py_complex)871872в комплексное число Python.873874**`O` (объект) \[PyObject \*\]**875876Передаёт объект Python без изменений (за исключением счётчика ссылок, который увеличивается на единицу). Если переданный объект – указатель877878*NULL*879880, считается, что вызов, формирующий аргумент, обнаружил ошибку и установил исключение. Следовательно,881882[`Py_BuildValue`](https://python-all.ru/3.0/c-api/arg.html#Py_BuildValue)883884вернёт885886*NULL*887888, но не возбудит исключение. Если исключение ещё не было возбуждено, устанавливается889890[`SystemError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.SystemError)891892.893894**`S` (объект) \[PyObject \*\]**895896То же, что и897898`O`899900.901902**`N` (объект) \[PyObject \*\]**903904То же, что и905906`O`907908, за исключением того, что не увеличивает счётчик ссылок на объект. Полезно, когда объект создаётся вызовом конструктора объекта в списке аргументов.909910**`O&` (объект) \[*converter*, *anything*\]**911912Преобразует913914*anything*915916в объект Python с помощью функции917918*converter*919920. Функция вызывается с аргументом921922*anything*923924(который должен быть совместим с925926`void *`927928) и должна возвращать «новый» объект Python или929930*NULL*931932в случае ошибки.933934**`(items)` (кортеж) \[*matching-items*\]**935936Преобразует последовательность значений C в кортеж Python с тем же количеством элементов.937938**`[items]` (список) \[*matching-items*\]**939940Преобразует последовательность значений C в список Python с тем же количеством элементов.941942**`{items}` (словарь) \[*matching-items*\]**943944Преобразует последовательность значений C в словарь Python. Каждая пара последовательных значений C добавляет один элемент в словарь, выступая в роли ключа и значения соответственно.945946Если в строке формата есть ошибка, устанавливается исключение [`SystemError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.SystemError) и возвращается *NULL*.947948**\[Py\_VaBuildValue\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `Py_VaBuildValue`(const char *\*format*, va\_list *vargs*)**949950Идентична951952[`Py_BuildValue`](https://python-all.ru/3.0/c-api/arg.html#Py_BuildValue)953954, за исключением того, что принимает va\_list вместо переменного числа аргументов.955