`arg.md`

415 строк · 43.1 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/2.7/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.7/extending/index.html#extending-index).1011Первые три из описанных функций, [`PyArg_ParseTuple()`](https://python-all.ru/2.7/c-api/arg.html#c.PyArg_ParseTuple), [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/2.7/c-api/arg.html#c.PyArg_ParseTupleAndKeywords) и [`PyArg_Parse()`](https://python-all.ru/2.7/c-api/arg.html#c.PyArg_Parse), используют *строки формата*, которые сообщают функции об ожидаемых аргументах. Строки формата используют один и тот же синтаксис для каждой из этих функций.1213Строка формата состоит из нуля или более «единиц формата». Единица формата описывает один объект Python; обычно это один символ или заключенная в скобки последовательность единиц формата. За некоторыми исключениями, единица формата, не являющаяся заключенной в скобки последовательностью, обычно соответствует одному адресному аргументу этих функций. В приведенном ниже описании выделенная кавычками форма – это единица формата; запись в круглых скобках – это тип объекта Python, соответствующий единице формата; а запись в квадратных скобках – это тип переменной (или переменных) C, адрес которой (которых) следует передать.1415Эти форматы позволяют обращаться к объекту как к непрерывному блоку памяти. Не нужно предоставлять сырую память для возвращаемой области Unicode или bytes. Также не нужно самостоятельно освобождать память, за исключением форматов `es`, `es#`, `et` и `et#`.1617**`s` (строка или Unicode) \[const char \*\]**1819Преобразует строку Python или объект Unicode в указатель C на строку символов. Не нужно выделять память для самой строки; указатель на существующую строку сохраняется в переменную-указатель на символы, адрес которой передается. Строка C завершается NUL. Строка Python не должна содержать встроенных NUL-байтов; если они есть, возбуждается исключение [`TypeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.TypeError). Объекты Unicode преобразуются в строки C с использованием кодировки по умолчанию. Если такое преобразование не удается, возбуждается [`UnicodeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.UnicodeError).2021**`s#` (строка, Unicode или любой объект, совместимый с read buffer) \[const char \*, int (или `Py_ssize_t`, см. ниже)\]**2223Этот вариант `s` сохраняет значения в две переменные C: первая – указатель на строку символов, вторая – ее длина. В этом случае строка Python может содержать встроенные нулевые байты. Объекты Unicode возвращают указатель на версию объекта, закодированную в кодировке по умолчанию, если такое преобразование возможно. Все остальные объекты, совместимые с read buffer, возвращают ссылку на сырое внутреннее представление данных.2425Начиная с Python 2.5, тип аргумента длины можно контролировать, определив макрос `PY_SSIZE_T_CLEAN` до включения `Python.h`. Если макрос определен, length является `Py_ssize_t`, а не int.2627**`s*` (строка, Unicode или любой объект, совместимый с буфером) \[Py\_buffer\]**2829Аналогично `s#`, этот код заполняет структуру Py\_buffer, предоставленную вызывающей стороной. Буфер блокируется, так что вызывающая сторона может затем использовать буфер даже внутри блока `Py_BEGIN_ALLOW_THREADS`; вызывающая сторона обязана вызвать `PyBuffer_Release` со структурой после обработки данных.3031Новое в версии 2.6.3233**`z` (строка, Unicode или `None`) \[const char \*\]**3435Как `s`, но объект Python также может быть `None`, и в этом случае указатель C устанавливается в *NULL*.3637**`z#` (строка, Unicode, `None` или любой объект, совместимый с read buffer) \[const char \*, int\]**3839Это относится к `s#` так же, как `z` относится к `s`.4041**`z*` (строка, Unicode, `None` или любой объект, совместимый с буфером) \[Py\_buffer\]**4243Это относится к `s*` так же, как `z` относится к `s`.4445Новое в версии 2.6.4647**`u` (Unicode) \[Py\_UNICODE \*\]**4849Преобразует объект Unicode Python в указатель C на буфер с завершающим NUL, содержащий 16-битные данные Unicode (UTF-16). Как и в случае с `s`, не нужно выделять память для буфера данных Unicode; указатель на существующие данные Unicode сохраняется в переменную-указатель [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE), адрес которой передается.5051**`u#` (Unicode) \[Py\_UNICODE \*, int\]**5253Этот вариант `u` сохраняет значения в две переменные C: первая – указатель на буфер данных Unicode, вторая – его длина. Не-Unicode объекты обрабатываются путем интерпретации их указателя read-buffer как указателя на массив [`Py_UNICODE`](https://python-all.ru/2.7/c-api/unicode.html#c.Py_UNICODE).5455**`es` (строка, Unicode или объект, совместимый с буфером символов) \[const char \*encoding, char \*\*buffer\]**5657Этот вариант `s` используется для кодирования Unicode и объектов, преобразуемых в Unicode, в буфер символов. Он работает только для закодированных данных без встроенных NUL-байтов.5859Этот формат требует два аргумента. Первый используется только как входной и должен быть `const char*`, который указывает на имя кодировки в виде строки с завершающим NUL, или *NULL*, в этом случае используется кодировка по умолчанию. Исключение возбуждается, если указанная кодировка неизвестна Python. Второй аргумент должен быть `char**`; значение указателя, на который он ссылается, будет установлено на буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, указанной первым аргументом.6061[`PyArg_ParseTuple()`](https://python-all.ru/2.7/c-api/arg.html#c.PyArg_ParseTuple) выделит буфер необходимого размера, скопирует закодированные данные в этот буфер и настроит *\*buffer* так, чтобы он ссылался на вновь выделенную память. Вызывающая сторона обязана вызвать [`PyMem_Free()`](https://python-all.ru/2.7/c-api/memory.html#c.PyMem_Free) для освобождения выделенного буфера после использования.6263**`et` (строка, Unicode или объект, совместимый с буфером символов) \[const char \*encoding, char \*\*buffer\]**6465То же, что и `es`, за исключением того, что 8-битные строковые объекты передаются без перекодирования. Вместо этого реализация предполагает, что строковый объект использует кодировку, переданную в качестве параметра.6667**`es#` (строка, Unicode или объект, совместимый с буфером символов) \[const char \*encoding, char \*\*buffer, int \*buffer\_length\]**6869Этот вариант `s#` используется для кодирования Unicode и объектов, преобразуемых в Unicode, в буфер символов. В отличие от формата `es`, этот вариант допускает входные данные, содержащие символы NUL.7071Требует три аргумента. Первый используется только как входной и должен быть `const char*`, который указывает на имя кодировки в виде строки с завершающим NUL, или *NULL*, в этом случае используется кодировка по умолчанию. Исключение возбуждается, если указанная кодировка неизвестна Python. Второй аргумент должен быть `char**`; значение указателя, на который он ссылается, будет установлено на буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, указанной первым аргументом. Третий аргумент должен быть указателем на целое число; соответствующее целое число будет установлено в количество байт в выходном буфере.7273Существует два режима работы:7475Если *\*buffer* указывает на указатель *NULL*, функция выделит буфер необходимого размера, скопирует закодированные данные в этот буфер и установит *\*buffer* так, чтобы он ссылался на вновь выделенную память. Вызывающая сторона обязана вызвать [`PyMem_Free()`](https://python-all.ru/2.7/c-api/memory.html#c.PyMem_Free) для освобождения выделенного буфера после использования.7677Если *\*buffer* указывает на не-*NULL* указатель (уже выделенный буфер), [`PyArg_ParseTuple()`](https://python-all.ru/2.7/c-api/arg.html#c.PyArg_ParseTuple) будет использовать это место как буфер и интерпретировать начальное значение *\*buffer\_length* как размер буфера. Затем он скопирует закодированные данные в буфер и добавит завершающий NUL. Если буфер недостаточно велик, будет установлен [`TypeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.TypeError). Примечание: начиная с Python 3.6 будет установлен [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError).7879В обоих случаях *\*buffer\_length* устанавливается в длину закодированных данных без завершающего NUL-байта.8081**`et#` (строка, Unicode или объект, совместимый с буфером символов) \[const char \*encoding, char \*\*buffer, int \*buffer\_length\]**8283Аналогично `es#` за исключением того, что строковые объекты передаются без перекодировки. Вместо этого реализация предполагает, что строковый объект использует кодировку, переданную в качестве параметра.8485**`b` (целое) \[unsigned char\]**8687Преобразует неотрицательное целое число Python в беззнаковое крошечное целое, хранящееся в C `unsigned char`.8889**`B` (целое) \[unsigned char\]**9091Преобразует целое число Python в tiny int без проверки переполнения, сохраняет в C `unsigned char`.9293Новое в версии 2.3.9495**`h` (целое) \[short int\]**9697Преобразует целое число Python в C `short int`.9899**`H` (целое) \[unsigned short int\]**100101Преобразует целое число Python в C `unsigned short int` без проверки переполнения.102103Новое в версии 2.3.104105**`i` (целое) \[int\]**106107Преобразует целое число Python в обычное C `int`.108109**`I` (целое) \[unsigned int\]**110111Преобразует целое число Python в C `unsigned int` без проверки переполнения.112113Новое в версии 2.3.114115**`l` (целое) \[long int\]**116117Преобразует целое число Python в C `long int`.118119**`k` (целое) \[unsigned long\]**120121Преобразует целое число Python (int или long) в C `unsigned long` без проверки переполнения.122123Новое в версии 2.3.124125**`L` (целое) \[PY\_LONG\_LONG\]**126127Преобразует целое число Python в C `long long`. Этот формат доступен только на платформах, поддерживающих `long long` (или `_int64` в Windows).128129**`K` (целое) \[unsigned PY\_LONG\_LONG\]**130131Преобразует целое число Python (int или long) в C `unsigned long long` без проверки переполнения. Этот формат доступен только на платформах, поддерживающих `unsigned long long` (или `unsigned _int64` в Windows).132133Новое в версии 2.3.134135**`n` (целое) \[Py\_ssize\_t\]**136137Преобразует целое число Python (int или long) в C `Py_ssize_t`.138139Новое в версии 2.5.140141**`c` (строка длиной 1) \[char\]**142143Преобразует символ Python, представленный как строка длиной 1, в C `char`.144145**`f` (число с плавающей запятой) \[float\]**146147Преобразует число с плавающей точкой Python в C-тип `float`.148149**`d` (число с плавающей запятой) \[double\]**150151Преобразует число с плавающей точкой Python в C-тип `double`.152153**`D` (комплексное) \[Py\_complex\]**154155Преобразует комплексное число Python в структуру C [`Py_complex`](https://python-all.ru/2.7/c-api/complex.html#c.Py_complex).156157**`O` (объект) \[PyObject \*\]**158159Сохраняет объект Python (без какого-либо преобразования) в указателе на объект C. Таким образом, программа на C получает фактический переданный объект. Счётчик ссылок объекта не увеличивается. Сохранённый указатель не является *NULL*.160161**`O!` (объект) \[*typeobject*, PyObject \*\]**162163Сохраняет объект Python в указателе на объект C. Это похоже на `O`, но принимает два аргумента C: первый – адрес объекта типа Python, второй – адрес переменной C (типа [`PyObject*`](https://python-all.ru/2.7/c-api/structures.html#c.PyObject)), в которую сохраняется указатель на объект. Если объект Python не имеет требуемого типа, возбуждается [`TypeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.TypeError).164165**`O&` (object) \[*конвертер*, *что угодно*\]**166167Преобразует объект Python в переменную C с помощью функции *converter*. Эта функция принимает два аргумента: первый – функция, второй – адрес переменной C (произвольного типа), преобразованный в `void *`. Функция *converter*, в свою очередь, вызывается следующим образом:168169```c170status = converter(object, address);171```172173где *object* – это преобразуемый объект Python, а *address* – это аргумент `void*`, переданный функции [`PyArg_Parse*()`](https://python-all.ru/2.7/c-api/arg.html#c.PyArg_Parse) функции. Возвращаемый *status* должен быть `1` для успешного преобразования и `0`, если преобразование не удалось. Когда преобразование не удалось, функция *converter* должна возбудить исключение и оставить содержимое *address* без изменений.174175**`S` (строка) \[PyStringObject \*\]**176177Аналогично `O`, но требует, чтобы объект Python был строковым объектом. Возбуждает [`TypeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.TypeError), если объект не является строковым. Переменная C может также объявляться как [`PyObject*`](https://python-all.ru/2.7/c-api/structures.html#c.PyObject).178179**`U` (строка Unicode) \[PyUnicodeObject \*\]**180181Аналогично `O`, но требует, чтобы объект Python был объектом Unicode. Возбуждает [`TypeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.TypeError), если объект не является объектом Unicode. Переменная C может также объявляться как [`PyObject*`](https://python-all.ru/2.7/c-api/structures.html#c.PyObject).182183**`t#` (буфер символов только для чтения) \[char \*, int\]**184185Аналогично `s#`, но принимает любой объект, реализующий интерфейс буфера только для чтения. Переменная `char*` устанавливается указывающей на первый байт буфера, а `int` устанавливается в длину буфера. Принимаются только односегментные буферные объекты; для всех остальных возбуждается [`TypeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.TypeError).186187**`w` (буфер символов для чтения и записи) \[char \*\]**188189Аналогично `s`, но принимает любой объект, реализующий интерфейс буфера для чтения и записи. Вызывающий должен определить длину буфера другими средствами или использовать `w#` вместо этого. Принимаются только односегментные буферные объекты; для всех остальных возбуждается [`TypeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.TypeError).190191**`w#` (буфер символов для чтения и записи) \[char \*, Py\_ssize\_t\]**192193Аналогично `s#`, но принимает любой объект, реализующий интерфейс буфера для чтения и записи. Переменная `char *` устанавливается указывающей на первый байт буфера, а `Py_ssize_t` устанавливается в длину буфера. Принимаются только односегментные буферные объекты; [`TypeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.TypeError) возбуждается для всех остальных.194195**`w*` (байт-ориентированный буфер для чтения и записи) \[Py\_buffer\]**196197Это относится к `w` так же, как `s*` относится к `s`.198199Новое в версии 2.6.200201**`(items)` (кортеж) \[*соответствующие элементы*\]**202203Объект должен быть последовательностью Python, длина которой равна количеству форматных единиц в *items*. Аргументы C должны соответствовать отдельным форматным единицам в *items*. Форматные единицы для последовательностей могут быть вложенными.204205> **Примечание**206>207> До версии Python 1.5.2 этот спецификатор формата принимал только кортеж, содержащий отдельные параметры, а не произвольную последовательность. Код, который ранее вызывал возбуждение [`TypeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.TypeError), теперь может выполняться без исключения. Ожидается, что это не станет проблемой для существующего кода.208209Можно передавать длинные целые Python там, где требуются целые; однако должная проверка диапазона не выполняется – старшие биты бесшумно отбрасываются, если принимающее поле слишком мало для значения (на самом деле семантика унаследована от понижающих приведений в C – результат может отличаться).210211Некоторые другие символы имеют значение в строке формата. Они не могут встречаться внутри вложенных скобок. Вот они:212213**`|`**214215Указывает, что остальные аргументы в списке аргументов Python являются необязательными. Переменные C, соответствующие необязательным аргументам, должны быть инициализированы значением по умолчанию – если необязательный аргумент не указан, [`PyArg_ParseTuple()`](https://python-all.ru/2.7/c-api/arg.html#c.PyArg_ParseTuple) не изменяет содержимое соответствующей переменной (переменных) C.216217**`:`**218219Список форматных единиц заканчивается здесь; строка после двоеточия используется как имя функции в сообщениях об ошибках («связанное значение» исключения, которое возбуждает [`PyArg_ParseTuple()`](https://python-all.ru/2.7/c-api/arg.html#c.PyArg_ParseTuple)).220221**`;`**222223Список форматных единиц заканчивается здесь; строка после точки с запятой используется как сообщение об ошибке *вместо* сообщения об ошибке по умолчанию. `:` и `;` взаимно исключают друг друга.224225Обратите внимание, что любые ссылки на объекты Python, передаваемые вызывающему, являются *заимствованными* ссылками; уменьшать их счётчик ссылок не следует.226227Дополнительные аргументы, передаваемые этим функциям, должны быть адресами переменных, тип которых определяется строкой формата; они используются для хранения значений из входного кортежа. Существует несколько случаев, как описано в списке форматных единиц выше, когда эти параметры используются как входные значения; они должны соответствовать тому, что указано для соответствующей форматной единицы в этом случае.228229Для успешного преобразования объект *arg* должен соответствовать формату, а формат должен быть полностью использован. В случае успеха функции [`PyArg_Parse*()`](https://python-all.ru/2.7/c-api/arg.html#c.PyArg_Parse) возвращают true, в противном случае они возвращают false и возбуждают соответствующее исключение. Если функции [`PyArg_Parse*()`](https://python-all.ru/2.7/c-api/arg.html#c.PyArg_Parse) завершаются ошибкой из-за сбоя преобразования в одной из форматных единиц, переменные по адресам, соответствующим этой и следующим форматным единицам, остаются нетронутыми.230231#### `int PyArg_ParseTuple(PyObject *args, const char *format, ...)`232233Разбирает параметры функции, принимающей только позиционные параметры, в локальные переменные. В случае успеха возвращает true; в случае неудачи возвращает false и возбуждает соответствующее исключение.234235#### `int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)`236237Идентична [`PyArg_ParseTuple()`](https://python-all.ru/2.7/c-api/arg.html#c.PyArg_ParseTuple), за исключением того, что принимает va\_list вместо переменного числа аргументов.238239#### `int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)`240241Разбирает параметры функции, которая принимает как позиционные, так и именованные параметры, в локальные переменные. Возвращает true в случае успеха; в случае неудачи возвращает false и возбуждает соответствующее исключение.242243#### `int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)`244245Идентична [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/2.7/c-api/arg.html#c.PyArg_ParseTupleAndKeywords), но принимает va\_list вместо переменного числа аргументов.246247#### `int PyArg_Parse(PyObject *args, const char *format, ...)`248249Функция, используемая для разбора списков аргументов «устаревших» функций – это функции, которые используют метод разбора параметров [`METH_OLDARGS`](https://python-all.ru/2.7/c-api/structures.html#METH_OLDARGS). Не рекомендуется использовать её для разбора параметров в новом коде, и большая часть кода в стандартном интерпретаторе была изменена, чтобы больше не использовать её для этой цели. Однако она остаётся удобным способом разложения других кортежей и может продолжать использоваться для этой цели.250251#### `int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)`252253Более простая форма извлечения параметров, которая не использует строку формата для указания типов аргументов. Функции, использующие этот метод для извлечения своих параметров, должны быть объявлены как [`METH_VARARGS`](https://python-all.ru/2.7/c-api/structures.html#METH_VARARGS) в таблицах функций или методов. Кортеж, содержащий фактические параметры, должен передаваться как *args*; он должен быть именно кортежем. Длина кортежа должна быть не менее *min* и не более *max*; *min* и *max* могут быть равны. В функцию должны передаваться дополнительные аргументы, каждый из которых должен быть указателем на переменную [`PyObject*`](https://python-all.ru/2.7/c-api/structures.html#c.PyObject); они будут заполнены значениями из *args*; они будут содержать заимствованные ссылки. Переменные, соответствующие необязательным параметрам, не указанным в *args*, не будут заполнены; они должны быть инициализированы вызывающим. Эта функция возвращает true в случае успеха и false, если *args* не является кортежем или содержит неправильное количество элементов; в случае ошибки будет установлено исключение.254255Это пример использования данной функции, взятый из исходников вспомогательного модуля `_weakref` для слабых ссылок:256257```c258static PyObject *259weakref_ref(PyObject *self, PyObject *args)260{261    PyObject *object;262    PyObject *callback = NULL;263    PyObject *result = NULL;264265    if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {266        result = PyWeakref_NewRef(object, callback);267    }268    return result;269}270```271272Вызов [`PyArg_UnpackTuple()`](https://python-all.ru/2.7/c-api/arg.html#c.PyArg_UnpackTuple) в этом примере полностью эквивалентен вызову [`PyArg_ParseTuple()`](https://python-all.ru/2.7/c-api/arg.html#c.PyArg_ParseTuple):273274```c275PyArg_ParseTuple(args, "O|O:ref", &object, &callback)276```277278Новое в версии 2.2.279280Изменено в версии 2.5: Эта функция использовала тип `int` для *min* и *max*. Это может потребовать изменений в вашем коде для корректной поддержки 64-разрядных систем.281282#### `PyObject* Py_BuildValue(const char *format, ...)`283284*Возвращаемое значение: новая ссылка.*285286Создаёт новое значение на основе строки формата, аналогичной принимаемым семейством функций [`PyArg_Parse*()`](https://python-all.ru/2.7/c-api/arg.html#c.PyArg_Parse), и последовательности значений. Возвращает значение или *NULL* в случае ошибки; будет возбуждено исключение, если возвращён *NULL*.287288[`Py_BuildValue()`](https://python-all.ru/2.7/c-api/arg.html#c.Py_BuildValue) не всегда создаёт кортеж. Он создаёт кортеж, только если его строка формата содержит две или более форматные единицы. Если строка формата пуста, он возвращает `None`; если она содержит ровно одну форматную единицу, он возвращает объект, описываемый этой форматной единицей. Чтобы заставить его вернуть кортеж размера `0` или один, заключите строку формата в круглые скобки.289290Когда буферы памяти передаются как параметры для предоставления данных для построения объектов, как в форматах `s` и `s#`, необходимые данные копируются. Буферы, предоставленные вызывающим, никогда не используются напрямую объектами, созданными [`Py_BuildValue()`](https://python-all.ru/2.7/c-api/arg.html#c.Py_BuildValue). Другими словами, если ваш код вызывает `malloc()` и передаёт выделенную память в [`Py_BuildValue()`](https://python-all.ru/2.7/c-api/arg.html#c.Py_BuildValue), ваш код отвечает за вызов `free()` для этой памяти после того, как [`Py_BuildValue()`](https://python-all.ru/2.7/c-api/arg.html#c.Py_BuildValue) вернёт управление.291292В приведённом ниже описании выделенная кавычками форма – это единица формата; запись в круглых скобках – это тип объекта Python, который вернёт единица формата; а запись в квадратных скобках – это тип передаваемого(ых) значения(й) C.293294Символы пробела, табуляции, двоеточия и запятой в строках формата игнорируются (но не внутри единиц формата, таких как `s#`). Это можно использовать, чтобы сделать длинные строки формата чуть более читаемыми.295296**`s` (строка) \[char \*\]**297298Преобразует C-строку, завершающуюся нулём, в объект Python. Если указатель на C-строку равен *NULL*, используется `None`.299300**`s#` (строка) \[char \*, int\]**301302Преобразует C-строку и её длину в объект Python. Если указатель на C-строку равен *NULL*, длина игнорируется и возвращается `None`.303304**`z` (строка или `None`) \[char \*\]**305306То же, что и `s`.307308**`z#` (строка или `None`) \[char \*, int\]**309310То же, что и `s#`.311312**`u` (строка Unicode) \[Py\_UNICODE \*\]**313314Преобразует буфер данных Unicode (UCS‑2 или UCS‑4), завершающийся нулём, в объект Python Unicode. Если указатель на буфер Unicode равен *NULL*, возвращается `None`.315316**`u#` (строка Unicode) \[Py\_UNICODE \*, int\]**317318Преобразует буфер данных Unicode (UCS‑2 или UCS‑4) и его длину в объект Python Unicode. Если указатель на буфер Unicode равен *NULL*, длина игнорируется и возвращается `None`.319320**`i` (целое) \[int\]**321322Преобразует простой C-тип `int` в объект целого числа Python.323324**`b` (целое) \[char\]**325326Преобразует простой C-тип `char` в объект целого числа Python.327328**`h` (целое) \[short int\]**329330Преобразует простой C-тип `short int` в объект целого числа Python.331332**`l` (целое) \[long int\]**333334Преобразует C `long int` в объект Python int.335336**`B` (целое) \[unsigned char\]**337338Преобразует C `unsigned char` в объект Python int.339340**`H` (целое) \[unsigned short int\]**341342Преобразует C `unsigned short int` в объект Python int.343344**`I` (целое/long) \[unsigned int\]**345346Преобразует значение C `unsigned int` в объект Python integer или Python long integer, если оно больше `sys.maxint`.347348**`k` (целое/long) \[unsigned long\]**349350Преобразует значение C `unsigned long` в объект Python integer или Python long integer, если оно больше `sys.maxint`.351352**`L` (long) \[PY\_LONG\_LONG\]**353354Преобразует значение C `long long` в объект Python long integer. Доступно только на платформах, поддерживающих `long long`.355356**`K` (long) \[unsigned PY\_LONG\_LONG\]**357358Преобразует значение C `unsigned long long` в объект Python long integer. Доступно только на платформах, поддерживающих `unsigned long long`.359360**`n` (int) \[Py\_ssize\_t\]**361362Преобразует значение C `Py_ssize_t` в Python integer или long integer.363364Новое в версии 2.5.365366**`c` (строка длины 1) \[char\]**367368Преобразует значение C `int`, представляющее символ, в строку Python длины 1.369370**`d` (float) \[double\]**371372Преобразует C `double` в Python-число с плавающей запятой.373374**`f` (float) \[float\]**375376То же, что и `d`.377378**`D` (complex) \[Py\_complex \*\]**379380Преобразует структуру C [`Py_complex`](https://python-all.ru/2.7/c-api/complex.html#c.Py_complex) в комплексное число Python.381382**`O` (объект) \[PyObject \*\]**383384Передаёт объект Python без изменений (за исключением его счётчика ссылок, который увеличивается на единицу). Если переданный объект является указателем *NULL*, считается, что это произошло из-за того, что вызов, формирующий аргумент, обнаружил ошибку и установил исключение. Следовательно, [`Py_BuildValue()`](https://python-all.ru/2.7/c-api/arg.html#c.Py_BuildValue) вернёт *NULL*, но не вызовет исключение. Если исключение ещё не было вызвано, устанавливается [`SystemError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.SystemError).385386**`S` (объект) \[PyObject \*\]**387388То же, что и `O`.389390**`N` (объект) \[PyObject \*\]**391392То же, что и `O`, за исключением того, что не увеличивает счётчик ссылок на объект. Полезно, когда объект создаётся вызовом конструктора объекта в списке аргументов.393394**`O&` (object) \[*конвертер*, *что угодно*\]**395396Преобразует *произвольное значение* в объект Python с помощью функции *преобразователя*. Функция вызывается с *произвольным значением* (которое должно быть совместимо с `void *`) в качестве аргумента и должна вернуть «новый» объект Python или *NULL* в случае ошибки.397398**`(items)` (tuple) \[*соответствующие элементы*\]**399400Преобразует последовательность значений C в кортеж Python с тем же количеством элементов.401402**`[items]` (list) \[*соответствующие элементы*\]**403404Преобразует последовательность значений C в список Python с тем же количеством элементов.405406**`{items}` (dictionary) \[*соответствующие элементы*\]**407408Преобразует последовательность значений C в словарь Python. Каждая пара последовательных значений C добавляет один элемент в словарь, выступая в качестве ключа и значения соответственно.409410Если в строке формата есть ошибка, устанавливается исключение [`SystemError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.SystemError) и возвращается *NULL*.411412#### `PyObject* Py_VaBuildValue(const char *format, va_list vargs)`413414Идентична [`Py_BuildValue()`](https://python-all.ru/2.7/c-api/arg.html#c.Py_BuildValue), за исключением того, что принимает va\_list вместо переменного числа аргументов.415