`arg.md`

789 строк · 43.1 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/2.6/c-api/arg.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Разбор аргументов и построение значений89Эти функции полезны при создании собственных функций и методов расширений. Дополнительная информация и примеры доступны в [*Расширение и встраивание интерпретатора Python*](https://python-all.ru/2.6/extending/index.html#extending-index).1011Первые три из этих описанных функций, [`PyArg_ParseTuple()`](https://python-all.ru/2.6/c-api/arg.html#PyArg_ParseTuple), [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/2.6/c-api/arg.html#PyArg_ParseTupleAndKeywords) и [`PyArg_Parse()`](https://python-all.ru/2.6/c-api/arg.html#PyArg_Parse), все используют *строки формата*, которые сообщают функции об ожидаемых аргументах. Строки формата используют одинаковый синтаксис для каждой из этих функций.1213Строка формата состоит из нуля или более «единиц формата». Единица формата описывает один объект Python; обычно это один символ или заключенная в скобки последовательность единиц формата. За некоторыми исключениями, единица формата, не являющаяся заключенной в скобки последовательностью, обычно соответствует одному адресному аргументу этих функций. В приведенном ниже описании выделенная кавычками форма – это единица формата; запись в круглых скобках – это тип объекта Python, соответствующий единице формата; а запись в квадратных скобках – это тип переменной (или переменных) C, адрес которой (которых) следует передать.1415**`s` (строка или Unicode) \[const char \*\]**1617Преобразует объект Python строки или Unicode в указатель C на символьную строку. Не нужно предоставлять хранилище для самой строки; указатель на существующую строку сохраняется в переменную-указатель на символ, адрес которой передаётся. Строка C завершается нулевым символом (NUL). Строка Python не должна содержать встроенных нулевых байтов; если они есть, возбуждается исключение1819[`TypeError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.TypeError)2021. Объекты Unicode преобразуются в строки C с использованием кодировки по умолчанию. Если такое преобразование не удаётся, возбуждается2223[`UnicodeError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.UnicodeError)2425.2627**`s#` (строка, Unicode или любой объект, совместимый с буфером чтения) \[const char \*, int (или `Py_ssize_t`, см. ниже)\]**2829Этот вариант `s` сохраняет значения в две переменные C: первая – указатель на символьную строку, вторая – её длина. В этом случае строка Python может содержать встроенные нулевые байты. Объекты Unicode возвращают указатель на строковую версию объекта в кодировке по умолчанию, если такое преобразование возможно. Все остальные объекты, совместимые с буфером чтения, возвращают ссылку на сырое внутреннее представление данных.3031Начиная с Python 2.5, тип аргумента длины можно управлять, определив макрос `PY_SSIZE_T_CLEAN` перед включением `Python.h`. Если макрос определён, length будет иметь тип `Py_ssize_t`, а не int.3233**`s*` (строка, Unicode или любой объект, совместимый с буфером) \[Py\_buffer\]**3435Подобно `s#`, этот код заполняет структуру Py\_buffer, предоставленную вызывающей стороной. Буфер блокируется, так что вызывающая сторона может затем использовать буфер даже внутри блока `Py_BEGIN_ALLOW_THREADS`; вызывающая сторона обязана вызвать `PyBuffer_Release` с этой структурой после обработки данных.3637Новое в версии 2.6.3839**`z` (строка, Unicode или `None`) \[const char \*\]**4041Аналогично4243`s`4445, но объект Python также может быть4647`None`4849, и в этом случае указатель C устанавливается в5051*NULL*5253.5455**`z#` (string, Unicode, `None` or any read buffer compatible object) \[const char \*, int\]**5657Это относится к5859`s#`6061так же, как6263`z`6465относится к6667`s`6869.7071**`z*` (строка, Unicode, `None` или любой объект, совместимый с буфером) \[Py\_buffer\]**7273Это относится к `s*` так же, как `z` относится к `s`.7475Новое в версии 2.6.7677**`u` (Unicode) \[Py\_UNICODE \*\]**7879Преобразует объект Python Unicode в указатель C на буфер 16-битных данных Unicode (UTF-16), завершающийся нулевым символом. Как и в случае с8081`s`8283, нет необходимости предоставлять хранилище для буфера данных Unicode; указатель на существующие данные Unicode сохраняется в переменную-указатель8485[`Py_UNICODE`](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE)8687, адрес которой передаётся.8889**`u#` (Unicode) \[Py\_UNICODE \*, int\]**9091Этот вариант9293`u`9495сохраняет в две переменные C: первая – указатель на буфер данных Unicode, вторая – его длина. Не-Unicode объекты обрабатываются путём интерпретации их указателя буфера чтения как указателя на массив9697[`Py_UNICODE`](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE)9899.100101**`es` (строка, Unicode или объект, совместимый с символьным буфером) \[const char \*encoding, char \*\*buffer\]**102103Этот вариант `s` используется для кодирования Unicode и объектов, преобразуемых в Unicode, в символьный буфер. Он работает только с закодированными данными без встроенных нулевых байтов.104105Этот формат требует два аргумента. Первый используется только как входной и должен быть `const char*`, указывающим на имя кодировки в виде строки, завершающейся нулевым символом, или *NULL*, в этом случае используется кодировка по умолчанию. Возбуждается исключение, если именованная кодировка не известна Python. Второй аргумент должен быть `char**`; значение указателя, на который он ссылается, будет установлено на буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, указанной первым аргументом.106107[`PyArg_ParseTuple()`](https://python-all.ru/2.6/c-api/arg.html#PyArg_ParseTuple) выделит буфер нужного размера, скопирует закодированные данные в этот буфер и изменит *\*buffer* так, чтобы он ссылался на вновь выделенное хранилище. Вызывающая сторона обязана вызвать [`PyMem_Free()`](https://python-all.ru/2.6/c-api/memory.html#PyMem_Free) для освобождения выделенного буфера после использования.108109**`et` (строка, Unicode или объект, совместимый с символьным буфером) \[const char \*encoding, char \*\*buffer\]**110111То же, что112113`es`114115, за исключением того, что 8-битные строковые объекты передаются без перекодирования. Вместо этого реализация предполагает, что строковый объект использует кодировку, переданную в качестве параметра.116117**`es#` (строка, Unicode или объект, совместимый с символьным буфером) \[const char \*encoding, char \*\*buffer, int \*buffer\_length\]**118119Этот вариант `s#` используется для кодирования Unicode и объектов, преобразуемых в Unicode, в символьный буфер. В отличие от формата `es`, этот вариант допускает входные данные, содержащие нулевые символы (NUL).120121Требуется три аргумента. Первый используется только как входной и должен быть `const char*`, указывающим на имя кодировки в виде строки, завершающейся нулевым символом, или *NULL*, в этом случае используется кодировка по умолчанию. Возбуждается исключение, если именованная кодировка не известна Python. Второй аргумент должен быть `char**`; значение указателя, на который он ссылается, будет установлено на буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, указанной первым аргументом. Третий аргумент должен быть указателем на целое число; на которое ссылается, будет установлено количество байт в выходном буфере.122123Существует два режима работы:124125Если *\*buffer* указывает на указатель *NULL*, функция выделит буфер нужного размера, скопирует закодированные данные в этот буфер и установит *\*buffer* так, чтобы он ссылался на вновь выделенное хранилище. Вызывающая сторона обязана вызвать [`PyMem_Free()`](https://python-all.ru/2.6/c-api/memory.html#PyMem_Free) для освобождения выделенного буфера после использования.126127Если *\*buffer* указывает на не-*NULL* указатель (уже выделенный буфер), [`PyArg_ParseTuple()`](https://python-all.ru/2.6/c-api/arg.html#PyArg_ParseTuple) будет использовать это место как буфер и интерпретировать начальное значение *\*buffer\_length* как размер буфера. Затем он скопирует закодированные данные в буфер и завершит его нулевым символом. Если буфер недостаточно велик, будет установлено [`ValueError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.ValueError).128129В обоих случаях *\*buffer\_length* устанавливается в длину закодированных данных без завершающего NUL-байта.130131**`et#` (строка, Unicode или объект, совместимый с символьным буфером) \[const char \*encoding, char \*\*buffer, int \*buffer\_length\]**132133То же, что134135`es#`136137, за исключением того, что строковые объекты передаются без перекодирования. Вместо этого реализация предполагает, что строковый объект использует кодировку, переданную в качестве параметра.138139**`b` (целое число) \[unsigned char\]**140141Преобразует неотрицательное целое число Python в беззнаковое крошечное целое, хранящееся в C142143`unsigned char`144145.146147**`B` (целое) \[unsigned char\]**148149Преобразует целое число Python в маленькое целое без проверки переполнения, сохраняемое в C `unsigned char`.150151Новое в версии 2.3.152153**`h` (целое) \[short int\]**154155Преобразует целое число Python в C156157`short int`158159.160161**`H` (целое) \[unsigned short int\]**162163Преобразует целое число Python в C `unsigned short int` без проверки переполнения.164165Новое в версии 2.3.166167**`i` (целое) \[int\]**168169Преобразует целое число Python в обычный C170171`int`172173.174175**`I` (целое) \[unsigned int\]**176177Преобразует целое число Python в C `unsigned int` без проверки переполнения.178179Новое в версии 2.3.180181**`l` (целое) \[long int\]**182183Преобразует целое число Python в C184185`long int`186187.188189**`k` (целое) \[unsigned long\]**190191Преобразует целое число Python (int или long) в C-тип `unsigned long` без проверки переполнения.192193Новое в версии 2.3.194195**`L` (целое число) \[PY\_LONG\_LONG\]**196197Преобразует целое число Python в C-тип198199`long long`200201. Этот формат доступен только на платформах, поддерживающих202203`long long`204205(или206207`_int64`208209в Windows).210211**`K` (целое число) \[unsigned PY\_LONG\_LONG\]**212213Преобразует целое число Python (int или long) в C-тип `unsigned long long` без проверки переполнения. Этот формат доступен только на платформах, поддерживающих `unsigned long long` (или `unsigned _int64` в Windows).214215Новое в версии 2.3.216217**`n` (целое число) \[Py\_ssize\_t\]**218219Преобразует целое число Python (int или long) в C-тип `Py_ssize_t`.220221Новое в версии 2.5.222223**`c` (строка длины 1) \[char\]**224225Преобразует символ Python, представленный в виде строки длиной 1, в C226227`char`228229.230231**`f` (вещественное) \[float\]**232233Преобразует число с плавающей запятой Python в C234235`float`236237.238239**`d` (вещественное) \[double\]**240241Преобразует число с плавающей запятой Python в C242243`double`244245.246247**`D` (комплексное число) \[Py\_complex\]**248249Преобразует комплексное число Python в структуру C250251[`Py_complex`](https://python-all.ru/2.6/c-api/complex.html#Py_complex)252253.254255**`O` (объект) \[PyObject \*\]**256257Сохраняет объект Python (без какого-либо преобразования) в указателе на объект C. Таким образом, программа на C получает фактический переданный объект. Счётчик ссылок объекта не увеличивается. Сохранённый указатель не является258259*NULL*260261.262263**`O!` (объект) \[*typeobject*, PyObject \*\]**264265Сохраняет объект Python в указатель на объект C. Аналогично266267`O`268269, но принимает два аргумента C: первый – адрес объекта-типа Python, второй – адрес переменной C (типа270271[`PyObject*`](https://python-all.ru/2.6/c-api/structures.html#PyObject)272273), в которую сохраняется указатель на объект. Если объект Python не имеет требуемого типа, вызывается274275[`TypeError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.TypeError)276277.278279**`O&` (объект) \[*converter*, *anything*\]**280281Преобразует объект Python в переменную C через функцию *converter*. Принимает два аргумента: первый – функция, второй – адрес переменной C (произвольного типа), преобразованный в `void *`. Функция *converter* вызывается следующим образом:282283```c284status = converter(object, address);285```286287где *object* – преобразуемый объект Python, а *address* – аргумент `void*`, переданный в функцию [`PyArg_Parse*()`](https://python-all.ru/2.6/c-api/arg.html#PyArg_Parse). Возвращаемое значение *status* должно быть `1` при успешном преобразовании и `0` при неудаче. При неудачном преобразовании функция *converter* должна возбудить исключение и оставить содержимое *address* неизменным.288289**`S` (строка) \[PyStringObject \*\]**290291Аналогично292293`O`294295, но требует, чтобы объект Python был строковым. Вызывает296297[`TypeError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.TypeError)298299, если объект не является строкой. Переменная C может также быть объявлена как300301[`PyObject*`](https://python-all.ru/2.6/c-api/structures.html#PyObject)302303.304305**`U` (строка Unicode) \[PyUnicodeObject \*\]**306307Аналогично308309`O`310311, но требует, чтобы объект Python был строкой Unicode. Вызывает312313[`TypeError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.TypeError)314315, если объект не является строкой Unicode. Переменная C может также быть объявлена как316317[`PyObject*`](https://python-all.ru/2.6/c-api/structures.html#PyObject)318319.320321**`t#` (буфер символов только для чтения) \[char \*, int\]**322323Аналогично324325`s#`326327, но принимает любой объект, реализующий интерфейс буфера только для чтения. Переменная328329`char*`330331устанавливается на первый байт буфера, а332333`int`334335– на длину буфера. Принимаются только односегментные буферные объекты; для всех остальных вызывается336337[`TypeError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.TypeError)338339.340341**`w` (символьный буфер для чтения и записи) \[char \*\]**342343Аналогично344345`s`346347, но принимает любой объект, реализующий интерфейс буфера чтения-записи. Вызывающий код должен определить длину буфера другими средствами или использовать348349`w#`350351. Принимаются только односегментные буферные объекты; для всех остальных вызывается352353[`TypeError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.TypeError)354355.356357**`w#` (буфер символов для чтения-записи) \[char \*, Py\_ssize\_t\]**358359Аналогично360361`s#`362363, но принимает любой объект, реализующий интерфейс буфера чтения-записи. Переменная364365`char *`366367устанавливается на первый байт буфера, а368369`Py_ssize_t`370371– на длину буфера. Принимаются только односегментные буферные объекты; для всех остальных вызывается372373[`TypeError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.TypeError)374375.376377**`w*` (байт-ориентированный буфер для чтения-записи) \[Py\_buffer\]**378379Это то же самое по отношению к `w`, что `s*` к `s`.380381Новое в версии 2.6.382383**`(items)` (кортеж) \[*matching-items*\]**384385Объект должен быть последовательностью Python, длина которой равна количеству форматных единиц в *items*. Аргументы C должны соответствовать отдельным форматным единицам в *items*. Форматные единицы для последовательностей могут быть вложенными.386387> **Примечание**388>389> До версии Python 1.5.2 данный спецификатор формата принимал только кортеж, содержащий отдельные параметры, а не произвольную последовательность. Код, который ранее вызывал здесь [`TypeError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.TypeError), теперь может выполняться без исключения. Для существующего кода это не должно стать проблемой.390391Можно передавать длинные целые Python там, где требуются целые; однако должная проверка диапазона не выполняется – старшие биты бесшумно отбрасываются, если принимающее поле слишком мало для значения (на самом деле семантика унаследована от понижающих приведений в C – результат может отличаться).392393Некоторые другие символы имеют значение в строке формата. Они не могут встречаться внутри вложенных скобок. Вот они:394395**`|`**396397Указывает, что оставшиеся аргументы в списке аргументов Python являются необязательными. Переменные C, соответствующие необязательным аргументам, следует инициализировать значением по умолчанию – если необязательный аргумент не указан,398399[`PyArg_ParseTuple()`](https://python-all.ru/2.6/c-api/arg.html#PyArg_ParseTuple)400401не изменяет содержимое соответствующих переменных C.402403**`:`**404405Список форматных единиц заканчивается здесь; строка после двоеточия используется как имя функции в сообщениях об ошибках (как «связанное значение» исключения, которое вызывает406407[`PyArg_ParseTuple()`](https://python-all.ru/2.6/c-api/arg.html#PyArg_ParseTuple)408409).410411**`;`**412413Список форматных единиц заканчивается здесь; строка после точки с запятой используется как сообщение об ошибке414415*вместо*416417сообщения об ошибке по умолчанию.418419`:`420421и422423`;`424425взаимно исключают друг друга.426427Обратите внимание, что любые ссылки на объекты Python, передаваемые вызывающему, являются *заимствованными* ссылками; уменьшать их счётчик ссылок не следует.428429Дополнительные аргументы, передаваемые этим функциям, должны быть адресами переменных, тип которых определяется строкой формата; они используются для хранения значений из входного кортежа. Существует несколько случаев, как описано в списке форматных единиц выше, когда эти параметры используются как входные значения; они должны соответствовать тому, что указано для соответствующей форматной единицы в этом случае.430431Для успешного преобразования объект *arg* должен соответствовать формату, а формат должен быть полностью исчерпан. При успехе функции [`PyArg_Parse*()`](https://python-all.ru/2.6/c-api/arg.html#PyArg_Parse) возвращают истину, иначе – ложь и возбуждают соответствующее исключение. Когда функции [`PyArg_Parse*()`](https://python-all.ru/2.6/c-api/arg.html#PyArg_Parse) терпят неудачу из-за сбоя преобразования в одной из форматных единиц, переменные по адресам, соответствующим этой и последующим форматным единицам, остаются нетронутыми.432433**int `PyArg_ParseTuple`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*args*, const char *\*format*, ...)**434435Разбирает параметры функции, принимающей только позиционные параметры, в локальные переменные. В случае успеха возвращает true; в случае неудачи возвращает false и возбуждает соответствующее исключение.436437**int `PyArg_VaParse`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*args*, const char *\*format*, va\_list *vargs*)**438439Идентична440441[`PyArg_ParseTuple()`](https://python-all.ru/2.6/c-api/arg.html#PyArg_ParseTuple)442443, за исключением того, что принимает va\_list вместо переменного числа аргументов.444445**int `PyArg_ParseTupleAndKeywords`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*args*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*kw*, const char *\*format*, char *\*keywords\[\]*, ...)**446447Разбирает параметры функции, которая принимает как позиционные, так и именованные параметры, в локальные переменные. Возвращает true в случае успеха; в случае неудачи возвращает false и возбуждает соответствующее исключение.448449**int `PyArg_VaParseTupleAndKeywords`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*args*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*kw*, const char *\*format*, char *\*keywords\[\]*, va\_list *vargs*)**450451Идентична452453[`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/2.6/c-api/arg.html#PyArg_ParseTupleAndKeywords)454455, за исключением того, что принимает va\_list вместо переменного числа аргументов.456457**int `PyArg_Parse`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*args*, const char *\*format*, ...)**458459Функция, используемая для разбора списков аргументов «старостильных» функций – тех, которые используют метод разбора параметров460461[`METH_OLDARGS`](https://python-all.ru/2.6/c-api/structures.html#METH_OLDARGS)462463. Не рекомендуется к использованию для разбора параметров в новом коде; большая часть кода в стандартном интерпретаторе была изменена, чтобы больше не использовать её для этой цели. Однако она остаётся удобным способом разбора других кортежей и может продолжать использоваться для этого.464465**int `PyArg_UnpackTuple`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*args*, const char *\*name*, Py\_ssize\_t *min*, Py\_ssize\_t *max*, ...)**466467Более простая форма извлечения параметров, не использующая строку формата для указания типов аргументов. Функции, использующие этот метод для извлечения своих параметров, должны быть объявлены как [`METH_VARARGS`](https://python-all.ru/2.6/c-api/structures.html#METH_VARARGS) в таблицах функций или методов. Кортеж, содержащий фактические параметры, должен быть передан как *args*; он действительно должен быть кортежем. Длина кортежа должна быть не меньше *min* и не больше *max*; *min* и *max* могут быть равны. В функцию нужно передать дополнительные аргументы, каждый из которых должен быть указателем на переменную типа [`PyObject*`](https://python-all.ru/2.6/c-api/structures.html#PyObject); эти переменные будут заполнены значениями из *args*; они будут содержать заимствованные ссылки. Переменные, соответствующие необязательным параметрам, не указанным в *args*, заполнены не будут; их следует инициализировать вызывающей стороне. Эта функция возвращает true при успехе и false, если *args* не является кортежем или содержит неправильное количество элементов; в случае неудачи будет установлено исключение.468469Пример использования этой функции, взятый из исходников вспомогательного модуля `_weakref` для слабых ссылок:470471```c472static PyObject *473weakref_ref(PyObject *self, PyObject *args)474{475    PyObject *object;476    PyObject *callback = NULL;477    PyObject *result = NULL;478479    if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {480        result = PyWeakref_NewRef(object, callback);481    }482    return result;483}484```485486Вызов [`PyArg_UnpackTuple()`](https://python-all.ru/2.6/c-api/arg.html#PyArg_UnpackTuple) в этом примере полностью эквивалентен следующему вызову [`PyArg_ParseTuple()`](https://python-all.ru/2.6/c-api/arg.html#PyArg_ParseTuple):487488```c489PyArg_ParseTuple(args, "O|O:ref", &object, &callback)490```491492Новое в версии 2.2.493494Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *min* и *max*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.495496**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `Py_BuildValue`(const char *\*format*, ...)**497498*Возвращаемое значение: новая ссылка.*499500Создаёт новое значение на основе строки формата, аналогичной принимаемой функциями семейства [`PyArg_Parse*()`](https://python-all.ru/2.6/c-api/arg.html#PyArg_Parse), и последовательности значений. Возвращает значение или *NULL* в случае ошибки; при возврате *NULL* будет возбуждено исключение.501502[`Py_BuildValue()`](https://python-all.ru/2.6/c-api/arg.html#Py_BuildValue) не всегда создает кортеж. Кортеж строится только в том случае, если его строка формата содержит две или более единиц формата. Если строка формата пуста, возвращается `None`; если содержит ровно одну единицу формата, то возвращается объект, описываемый этой единицей. Чтобы принудительно вернуть кортеж из 0 или 1 элемента, строку формата следует заключить в круглые скобки.503504Когда в качестве параметров передаются буферы памяти для предоставления данных, необходимых для создания объектов, как в форматах `s` и `s#`, требуемые данные копируются. Буферы, предоставленные вызывающим кодом, никогда не используются напрямую объектами, созданными [`Py_BuildValue()`](https://python-all.ru/2.6/c-api/arg.html#Py_BuildValue). Иными словами, если ваш код вызывает `malloc()` и передает выделенную память в [`Py_BuildValue()`](https://python-all.ru/2.6/c-api/arg.html#Py_BuildValue), то после завершения [`Py_BuildValue()`](https://python-all.ru/2.6/c-api/arg.html#Py_BuildValue) ответственность за вызов `free()` для этой памяти лежит на вашем коде.505506В приведённом ниже описании выделенная кавычками форма – это единица формата; запись в круглых скобках – это тип объекта Python, который вернёт единица формата; а запись в квадратных скобках – это тип передаваемого(ых) значения(й) C.507508Символы пробела, табуляции, двоеточия и запятой игнорируются в строках формата (но не внутри единиц формата, таких как `s#`). Это можно использовать, чтобы сделать длинные строки формата чуть более читаемыми.509510**`s` (строка) \[char \*\]**511512Преобразует C-строку, завершающуюся нулевым символом, в объект Python. Если указатель на C-строку равен513514*NULL*515516, используется517518`None`519520.521522**`s#` (строка) \[char \*, int\]**523524Преобразует C-строку и ее длину в объект Python. Если указатель на C-строку равен525526*NULL*527528, длина игнорируется и возвращается529530`None`531532.533534**`z` (строка или `None`) \[char \*\]**535536То же, что и537538`s`539540.541542**`z#` (строка или `None`) \[char \*, int\]**543544То же, что и545546`s#`547548.549550**`u` (строка Unicode) \[Py\_UNICODE \*\]**551552Преобразует буфер данных Unicode (UCS-2 или UCS-4), завершающийся нулевым символом, в объект Python Unicode. Если указатель на буфер Unicode равен553554*NULL*555556, возвращается557558`None`559560.561562**`u#` (строка Unicode) \[Py\_UNICODE \*, int\]**563564Преобразует буфер данных Unicode (UCS-2 или UCS-4) и его длину в объект Python Unicode. Если указатель на буфер Unicode равен565566*NULL*567568, длина игнорируется и возвращается569570`None`571572.573574**`i` (целое) \[int\]**575576Преобразует обычный C577578`int`579580в объект Python целого типа.581582**`b` (целое) \[char\]**583584Преобразует обычный C585586`char`587588в объект Python целого типа.589590**`h` (целое) \[short int\]**591592Преобразует обычное C593594`short int`595596в объект Python int.597598**`l` (целое) \[long int\]**599600Преобразует C601602`long int`603604в объект Python int.605606**`B` (целое) \[unsigned char\]**607608Преобразует C609610`unsigned char`611612в объект Python int.613614**`H` (целое) \[unsigned short int\]**615616Преобразует C617618`unsigned short int`619620в объект Python int.621622**`I` (integer/long) \[unsigned int\]**623624Преобразует C625626`unsigned int`627628в объект Python integer или в объект Python long integer, если значение больше629630`sys.maxint`631632.633634**`k` (integer/long) \[unsigned long\]**635636Преобразует C637638`unsigned long`639640в объект Python integer или в объект Python long integer, если значение больше641642`sys.maxint`643644.645646**`L` (длинное) \[PY\_LONG\_LONG\]**647648Преобразует C649650`long long`651652в объект Python long integer. Доступно только на платформах, поддерживающих653654`long long`655656.657658**`K` (длинное) \[unsigned PY\_LONG\_LONG\]**659660Преобразует C661662`unsigned long long`663664в объект Python long integer. Доступно только на платформах, поддерживающих665666`unsigned long long`667668.669670**`n` (целое) \[Py\_ssize\_t\]**671672Преобразует C `Py_ssize_t` в объект Python integer или long integer.673674Новое в версии 2.5.675676**`c` (строка длины 1) \[char\]**677678Преобразует значение C679680`int`681682, представляющее символ, в строку Python длины 1.683684**`d` (вещественное) \[double\]**685686Преобразует C687688`double`689690в число с плавающей точкой Python.691692**`f` (вещественное) \[float\]**693694То же, что и695696`d`697698.699700**`D` (комплексное) \[Py\_complex \*\]**701702Преобразует структуру C703704[`Py_complex`](https://python-all.ru/2.6/c-api/complex.html#Py_complex)705706в комплексное число Python.707708**`O` (объект) \[PyObject \*\]**709710Передает объект Python без изменений (за исключением счетчика ссылок, который увеличивается на единицу). Если переданный объект является указателем711712*NULL*713714, считается, что это произошло из-за того, что вызов, создающий аргумент, обнаружил ошибку и установил исключение. Поэтому715716[`Py_BuildValue()`](https://python-all.ru/2.6/c-api/arg.html#Py_BuildValue)717718вернет719720*NULL*721722, но не вызовет исключение. Если исключение еще не было установлено, устанавливается723724[`SystemError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.SystemError)725726.727728**`S` (объект) \[PyObject \*\]**729730То же, что и731732`O`733734.735736**`N` (объект) \[PyObject \*\]**737738То же, что и739740`O`741742, за исключением того, что не увеличивает счетчик ссылок на объект. Полезно, когда объект создается вызовом конструктора в списке аргументов.743744**`O&` (объект) \[*converter*, *anything*\]**745746Преобразует747748*anything*749750в объект Python с помощью функции751752*converter*753754. Функция вызывается с аргументом755756*anything*757758(который должен быть совместим с759760`void *`761762) и должна возвращать «новый» объект Python или763764*NULL*765766в случае ошибки.767768**`(items)` (кортеж) \[*matching-items*\]**769770Преобразует последовательность значений C в кортеж Python с тем же количеством элементов.771772**`[items]` (список) \[*matching-items*\]**773774Преобразует последовательность значений C в список Python с тем же количеством элементов.775776**`{items}` (словарь) \[*matching-items*\]**777778Преобразует последовательность значений C в словарь Python. Каждая пара последовательных значений C добавляет один элемент в словарь, выступая в качестве ключа и значения соответственно.779780Если в строке формата есть ошибка, устанавливается исключение [`SystemError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.SystemError) и возвращается *NULL*.781782**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `Py_VaBuildValue`(const char *\*format*, va\_list *vargs*)**783784Идентична785786[`Py_BuildValue()`](https://python-all.ru/2.6/c-api/arg.html#Py_BuildValue)787788, за исключением того, что принимает va\_list вместо переменного числа аргументов.789