Анализ аргументов и сборка значений

Данные функции полезны при создании ваших собственных функций и методов расширений. Дополнительная информация и примеры доступны в Расширение и встраивание интерпретатора Python.

Первые три из рассмотренных функций PyArg_ParseTuple(), PyArg_ParseTupleAndKeywords() и PyArg_Parse(), используют форматированные строки, которые используются для сообщения функции об ожидаемых аргументах. Строки формата используют один и тот же синтаксис для каждой из этих функций.

Разбор аргументов

Строка формата состоит из нуля или более «единиц формата». Единица формата определяет один объект Python; Обычно это один символ или заключенная в скобки последовательность единиц формата. За некоторыми исключениями, единица формата, не заключенная в скобки, обычно соответствует одному аргументу адреса для этих функций. В следующем описании цитируемая форма является единицей формата; запись в круглых скобках — это тип объекта Python, соответствующий единице формата; а запись в [квадратных] скобках — это тип переменной (ей) C, адрес которой должен быть передан.

Строки и буферы

Эти форматы позволяют получить доступ к объекту как к непрерывному фрагменту памяти. Вам не нужно предоставлять необработанное хранилище для возвращаемой области юникода или байтов.

В общем, когда формат устанавливает указатель на буфер, буфер управляется соответствующим объектом Python, и буфер разделяет время жизни этого объекта. Вам не придется самому освобождать память. Единственными исключениями являются es, es#, et и et#.

Однако, когда структура Py_buffer заполняется, базовый буфер блокируется, так что вызывающая сторона может впоследствии использовать буфер даже внутри блока Py_BEGIN_ALLOW_THREADS без риска изменения размера или уничтожения изменяемых данных. В результате вы должны вызвать PyBuffer_Release() после завершения обработки данных (или в любом случае преждевременного прерывания).

Если не указано иное, буферы не завершаются NUL.

Некоторые форматы требуют байтоподобного объекта только для чтения и устанавливают указатель вместо структуры буфера. Они работают, проверяя, что поле объекта PyBufferProcs.bf_releasebuffer имеет значение NULL, что запрещает изменяемые объекты, такие как bytearray.

Примечание

Для всех вариантов форматов # (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.

s (str) [const char *]

Преобразовывает объект Юникод в указатель C на строку символов. Указатель на существующую строку сохраняется в указателе символа переменная, адрес которой вы передаете. Строка C заканчивается NUL. Строка Python не должна содержать встроенных нулевых кодовых точек; если это так , вызывается исключение ValueError. Объекты Юникод преобразуются в строки C с использованием кодировки 'utf-8'. Если это преобразование не удается, файл вызывает UnicodeError.

Примечание

Данный формат не принимает байтоподобные объекты. Если вы хотите принять пути файловой системы и преобразовать их в строки символов C, предпочтительно использовать формат O& с PyUnicode_FSConverter() как converter.

Изменено в версии 3.5: Раньше TypeError вызывался, когда в строке Python встречались встроенные нулевые кодовые точки.

s* (str или байтоподобный объект) [Py_buffer]
Данный формат принимает объекты Юникод, а также байтовые объекты. Он заполняет структуру Py_buffer, предоставленную вызывающей стороной. В этом случае результирующая строка C может содержать встроенные байты NUL. Объекты Юникод преобразуются в строки C с использованием кодировки 'utf-8'.
s# (str, только для чтения байтоподобный объект) [const char *, int или Py_ssize_t]
Как s*, за исключением того, что он не принимает изменяемые объекты. Результат сохраняется в двух переменных C первая — указатель на строку C, вторая — её длину. Строка может содержать встроенные нулевые байты. Объекты Юникод преобразуются в строки C с использованием кодировки 'utf-8'.
z (str или None) [const char *]
Подобно s, но объект Python также может быть None, и в этом случае C указатель установлен на NULL.
z* (str, байтоподобный объект или None) [Py_buffer]
Подобно s*, но объект Python также может быть None, и в этом случае расширение Член buf структуры Py_buffer имеет значение NULL.
z# (str, только для чтения байтоподобный объект или None) [const char *, int или Py_ssize_t]
Подобно s#, но объект Python также может быть None, и в этом случае C указатель установлен на NULL.
y (только для чтения байтоподобный объект) [const char *]

Данный формат преобразует байтовый объект в указатель C на Символ нить; он не принимает объекты Юникод. Буфер байтов не должен содержат встроенные нулевые байты; если да, то вызывается исключение ValueError.

Изменено в версии 3.5: Раньше TypeError вызывался, когда в байтовом буфере встречались встроенные нулевые байты.

y* (байтоподобный объект) [Py_buffer]
Данный вариант на s* не принимает только объекты Юникод байтовые объекты. ** Это рекомендуемый способ принять двоичные данные. **
y# (только для чтения байтоподобный объект) [const char *, int или Py_ssize_t]
Данный вариант на s# не принимает объекты Юникод, только байтовые объекты.
S (bytes) [PyBytesObject *]
Требуется, чтобы объект Python был объектом bytes без попытки любого преобразования. Вызывает TypeError, если объект не является байтовым. Переменная C также может быть объявлена как PyObject*.
Y (bytearray) [PyByteArrayObject *]
Требуется, чтобы объект Python был объектом bytearray без попытки любого преобразования. Вызывает TypeError, если объекта не bytearray. Переменная C также может быть объявлена как PyObject*.
u (str) [const Py_UNICODE *]

Преобразовывает объект Python Юникод в указатель C на буфер с завершающим нулем Символы Юникода. Вы должны передать адрес Py_UNICODE указатель переменной, которая будет заполнена указателем на существующий Буфер Юникода. Обратите внимание, что ширина Py_UNICODE символ зависит от параметров компиляции (16 или 32 бита). Строка Python не должна содержать встроенных нулевых кодовых точек; если это так , вызывается исключение ValueError.

Изменено в версии 3.5: Раньше TypeError вызывался, когда в строке Python встречались встроенные нулевые кодовые точки.

Устарело с версии 3.3, будет удалено в 4.0 версии.: Часть старого API Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_AsWideCharString().

u# (str) [const Py_UNICODE *, int или Py_ssize_t]

Данный вариант на u сохраняет в двух переменных C, первая из которых является указателем на Буфер данных Юникод, второй — его длина. Данный вариант позволяет нулевые кодовые точки.

Устарело с версии 3.3, будет удалено в 4.0 версии.: Часть старого API Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_AsWideCharString().

Z (str или None) [const Py_UNICODE *]

Подобно u, но объект Python также может быть None, и в этом случае файл Указатель Py_UNICODE установлен на NULL.

Устарело с версии 3.3, будет удалено в 4.0 версии.: Часть старого API Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_AsWideCharString().

Z# (str или None) [const Py_UNICODE *, int или Py_ssize_t]

Подобно u#, но объект Python также может быть None, и в этом случае файл Указатель Py_UNICODE установлен на NULL.

Устарело с версии 3.3, будет удалено в 4.0 версии.: Часть старого API Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_AsWideCharString().

U (str) [PyObject *]
Требует, чтобы объект Python был объектом Юникод, без попытки любого преобразования. Вызывает TypeError, если объект не является Юникод объектом. Переменная C также может быть объявлена как PyObject*.
w* (чтение-запись байтоподобный объект) [Py_buffer]
Данный формат принимает любой объект, реализующий буфер чтения-записи интерфейс. Он заполняет структуру Py_buffer, предоставленную вызывающей стороной. Буфер может содержать встроенные нулевые байты. Вызывающий должен вызвать PyBuffer_Release(), когда это делается с буфером.
es (str) [const char *encoding, char **buffer]

Данный вариант на s используется для кодирования Юникод в символьный буфер. Он работает только для закодированных данных без встроенных байтов NUL.

Данный формат требует двух аргументов. Первый используется только как входной и должен быть const char*, который указывает на имя кодировки в виде строки с завершающим NUL, или NULL, в этом случае используется кодировка 'utf-8'. Вызывается исключение, если указанная кодировка неизвестна Python. Второй аргумент должен быть char**; значение указателя, на которое он ссылается, будет установлено в буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, указанной первым аргументом.

PyArg_ParseTuple() выделит буфер необходимого размера, скопирует закодированные данные в данный буфер и настроит *buffer для ссылки на вновь выделенное хранилище. Вызывающая сторона отвечает за вызов PyMem_Free(), чтобы освободить выделенный буфер после использования.

et (str, bytes или bytearray) [const char *encoding, char **buffer]
То же, что и es, за исключением того, что объекты байтовой строки проходят без него перекодировать их. Вместо этого реализация предполагает, что объект байтовой строки использует кодировка, переданная в качестве параметра.
es# (str) [const char *encoding, char **buffer, int или Py_ssize_t *buffer_length]

Данный вариант на s# используется для кодирования Юникод в символьный буфер. В отличие от формата es, данный вариант позволяет вводить данные, содержащие NUL Символы.

Требуется три аргумента. Первый используется только в качестве входных данных и должен быть const char*, который указывает на имя кодировки в виде строки с завершающим NUL, или NULL, в этом случае используется кодировка 'utf-8'. Вызывается исключение, если указанная кодировка неизвестна Python. Второй аргумент должен быть char**; значение указателя, на которое он ссылается, будет установлено в буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, указанной первым аргументом. Третий аргумент должен быть указателем на целое число; указанное целое число будет установлено равным количеству байтов в выходном буфере.

Есть два режима работы:

Если *buffer указывает указатель NULL, функция выделит буфер необходимого размера, скопирует закодированные данные в данный буфер и установит *buffer для ссылки на вновь выделенное хранилище. Вызывающая сторона отвечает за вызов PyMem_Free(), чтобы освободить выделенный буфер после использования.

Если *buffer указывает на указатель, отличный от NULL (уже выделенный буфер), PyArg_ParseTuple() будет использовать это местоположение в качестве буфера и интерпретировать начальное значение *buffer_length как размер буфера. Затем он скопирует закодированные данные в буфер и завершит их NUL. Если буфер недостаточно велик, будет установлен ValueError.

В обоих случаях *buffer_length устанавливается равным длине закодированных данных без завершающего байта NUL.

et# (str, bytes или bytearray) [const char *encoding, char **buffer, int or Py_ssize_t *buffer_length]
То же, что и es#, за исключением того, что объекты байтовой строки передаются без перекодирования их. Вместо этого реализация предполагает, что объект байтовой строки использует расширение кодировка передается как параметр.

Числа

b (int) [unsigned char]
Преобразовывает неотрицательное целое число Python в беззнаковый крошечный int, хранящийся в C unsigned char.
B (int) [unsigned char]
Преобразовывает целое число Python в крошечный int без проверки переполнения, сохраненное в C unsigned char.
h (int) [short int]
Преобразовывает целое число Python в C short int.
H (int) [unsigned short int]
Преобразовывает целое число Python в C unsigned short int без переполнения проверка.
i (int) [int]
Преобразовывает целое число Python в простой C int.
I (int) [unsigned int]
Преобразовывает целое число Python в C unsigned int без переполнения проверка.
l (int) [long int]
Преобразовывает целое число Python в C long int.
k (int) [unsigned long]
Преобразовывает целое число Python в C unsigned long без проверка переполнения.
L (int) [long long]
Преобразовывает целое число Python в C long long.
K (int) [unsigned long long]
Преобразовывает целое число Python в C unsigned long long без проверки переполнения.
n (int) [Py_ssize_t]
Преобразовывает целое число Python в C Py_ssize_t.
c (bytes или bytearray длины 1) [char]

Преобразовывает байт Python, представленный как bytes или bytearray объект длины 1 в C char.

Изменено в версии 3.3: Разрешить объекты bytearray.

C (str длины 1) [int]
Преобразовывает символ Python, представленный как объект str из длина 1, к C int.
f (float) [float]
Преобразовывает число с плавающей запятой Python в C float.
d (float) [double]
Преобразовывает число с плавающей запятой Python в C double.
D (complex) [Py_complex]
Преобразовывает комплексное число Python в структуру C Py_complex.

Прочие объекты

O (объект) [PyObject *]
Сохраняет объект Python (без какого-либо преобразования) в указателе объекта C. Модель C таким образом программа получает фактический переданный объект. Ссылка на объект кол-во не увеличивается. Сохраненный указатель не NULL.
O! (объект) [typeobject, PyObject *]
Сохраняет объект Python в указателе объекта C. Это похоже на O, но принимает два аргумента C: первый — это адрес объекта типа Python, расширение второй — это адрес переменной C (типа PyObject*), в которую указатель объекта сохраняется. Если у объекта Python нет необходимого типа, вызывается TypeError.
O& (объект) [converter, anything]

Преобразовывает объект Python в переменную C с помощью функции converter. Данный принимает два аргумента: первый — функция, второй — адрес C переменная (произвольного типа), преобразованная в void *. Модель converter функция в свою очередь вызывается следующим образом:

status = converter(object, address);

где object — это объект Python, который нужно преобразовать, а address — это аргумент void*, переданный в функцию PyArg_Parse*(). Возвращенное значение status должно быть 1 для успешного преобразования и 0 в случае сбоя преобразования. В случае сбоя преобразования функция converter должна вызвать исключение и оставить содержимое address без изменений.

Если converter возвращает Py_CLEANUP_SUPPORTED, он может быть вызван второй раз, если парсинг аргумента в конечном итоге завершится неудачно, давая конвертеру возможность освободить любую память, которую он уже выделил. В этом втором вызове параметр object будет NULL; address будет иметь то же значение, что и в исходном вызове.

Изменено в версии 3.1: Добавлен Py_CLEANUP_SUPPORTED.

p (bool) [int]

Проверяет переданное значение на истинность (логическое значение p redicate) и преобразует результат равняется его эквивалентному целочисленному значению C истина/ложь. Устанавливает для int значение 1, если выражение было истинным, и 0, если оно было Ложным. Это принимает любое допустимое значение Python. См. Проверка истинности для получения дополнительной информации информация о том, как Python проверяет истинность значений.

Добавлено в версии 3.3.

(items) (tuple) [matching-items]
Объект должен быть последовательностью Python, длина которой равна количеству единиц формата в items. Аргументы C должны соответствовать отдельным единицам формата в items. Единицы формата для последовательностей могут быть вложенными.

Можно передавать «длинные» целые числа (целые числа, значение которых превышает LONG_MAX платформы), однако надлежащая проверка диапазона не выполняется, — наиболее значимые биты без уведомления усекаются, когда принимающее поле слишком мало для получения значения (фактически, семантика унаследовал от убогих в C — пробег может отличаться).

Некоторые другие символы имеют значение в строке формата. Их не может быть внутри вложенных круглых скобок. Они есть:

|
Указывает, что остальные аргументы в списке аргументов Python являются необязательными. Переменные C, соответствующие необязательным аргументам, должны быть инициализированы их значение по умолчанию, — когда необязательный аргумент не Указан PyArg_ParseTuple() не затрагивает содержимое соответствующего C переменная(ые).
$

Только PyArg_ParseTupleAndKeywords(): Указывает, что остальные аргументы в списке аргументов Python имеют значение только по ключевым словам. В настоящее время все только ключевые аргументы, также должны быть необязательными аргументы, поэтому | всегда нужно указывать перед $ в формате строки.

Добавлено в версии 3.3.

:
Список единиц формата на этом заканчивается; строка после двоеточия используется как имя функции в сообщениях об ошибках («связанное значение» исключения, которое PyArg_ParseTuple() вызывает).
;
Список единиц формата на этом заканчивается; строка после точки с запятой используется как сообщение об ошибке instead сообщения об ошибке по умолчанию. : и ; взаимно исключают друг друга.

Обратите внимание, что любые ссылки на объекты Python, которые предоставляются вызывающей стороне, являются ссылками borrowed; не уменьшайте их количество ссылок!

Дополнительные аргументы, передаваемые этим функциям, должны быть адресами переменных, тип которых определяется строкой формата; они используются для хранения значений из входного кортежа. Есть несколько случаев, как приведено в списке единиц формата выше, когда эти параметры используются в качестве входных значений; в этом случае они должны соответствовать тому, что указано для соответствующей единицы формата.

Для успешного преобразования объект arg должен соответствовать формату, а формат должен быть исчерпан. В случае успеха функции PyArg_Parse*() возвращают истину, в противном случае они возвращают ложь и вызывают соответствующее исключение. Когда функции PyArg_Parse*() не работают из-за сбоя преобразования в одном из блоков формата, переменные по адресам, соответствующим этому и следующим блокам формата, остаются Нетронутыми.

Функции API

int PyArg_ParseTuple(PyObject *args, const char *format, ...)

Анализирет параметры функции, которая принимает только позиционные параметры в локальные переменные. Возвращает истину в случае успеха; в случае неудачи он возвращает ложь и вызывает соответствующее исключение.

int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)

Идентична PyArg_ParseTuple(), за исключением того, что принимает va_list, а не переменное количество аргументов.

int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)

Анализирет параметры функции, которая принимает как позиционные, так и ключевые параметры в локальные переменные. Аргумент keywords представляет собой массив имён параметров ключевого слова, завершающийся NULL. Пустые имена обозначают только позиционные параметры. Возвращает истину в случае успеха; в случае неудачи он возвращает ложь и вызывает соответствующее исключение.

Изменено в версии 3.6: Добавлена поддержка только позиционные параметры.

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)

Идентичен PyArg_ParseTupleAndKeywords(), за исключением того, что принимает va_list, а не переменное количество аргументов.

int PyArg_ValidateKeywordArguments(PyObject *)

Убедиться, что ключи в словаре ключевых аргументов являются строками. Это необходимо только в том случае, если PyArg_ParseTupleAndKeywords() не используется, поскольку последний уже выполняет эту проверку.

Добавлено в версии 3.2.

int PyArg_Parse(PyObject *args, const char *format, ...)

Функция, используемая для деконструкции списков аргументов функций «старого стиля» —. Это функции, которые используют метод синтаксического анализа параметров METH_OLDARGS, который был удален в Python 3. Его не рекомендуется использовать при парсинге параметров в новом коде, и в большинстве кодов в стандартном интерпретаторе был изменен, чтобы больше не использовать его для этой цели. Однако это остается удобным способом разложения других кортежей, и его можно продолжать использовать для этой цели.

int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)

Более простая форма получения параметров, которая не использует строку формата для указания типов аргументов. Функции, которые используют данный метод для получения своих параметров, должны быть объявлены как METH_VARARGS в таблицах функций или методов. Кортеж, содержащий фактические параметры, следует передавать как args; это должен быть кортеж. Длина кортежа должна быть не менее min и не более max; min и max могут быть равны. В функцию должны быть переданы дополнительные аргументы, каждый из которых должен быть указателем на переменную PyObject*; они будут заполнены значениями из args; они будут содержать заимствованные ссылки. Переменные, которые соответствуют необязательным параметрам, не указанным в args, не будут заполнены; они должны быть инициализированы вызывающей стороной. Данная функция возвращает истину в случае успеха и ложь, если args не является кортежем или содержит неправильное количество элементов; исключение будет установлено, если произошёл сбой.

Пример использования функции, взятый из исходников для вспомогательного модуля _weakref для слабых ссылок:

static PyObject *
weakref_ref(PyObject *self, PyObject *args)
{
    PyObject *object;
    PyObject *callback = NULL;
    PyObject *result = NULL;

    if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
        result = PyWeakref_NewRef(object, callback);
    }
    return result;
}

Вызов PyArg_UnpackTuple() в этом примере полностью эквивалентен этому вызову PyArg_ParseTuple():

PyArg_ParseTuple(args, "O|O:ref", &object, &callback)

Создание значений

PyObject* Py_BuildValue(const char *format, ...)
Return value: New reference.

Создает новое значение на основе строки формата, аналогичной принятой в семействе функций PyArg_Parse*(), и последовательности значений. Возвращает значение NULL или в случае ошибки; исключение будет вызвано, если будет возвращено NULL.

Py_BuildValue() не всегда создает кортеж. Он создает кортеж, только если его строка формата содержит две или более единиц формата. Если строка формата пуста, возвращается None; если она содержит ровно одну единицу формата, она возвращает любой объект, реализованный данной единицей формата. Чтобы заставить его возвращать кортеж размером 0 или 1, заключите строку формата в скобки.

Когда буферы памяти передаются в качестве параметров для предоставления данных для построения объектов, как в форматах s и s#, необходимые данные копируются. На буферы, предоставленные вызывающей стороной, никогда не ссылаются объекты, созданные Py_BuildValue(). Другими словами, если ваш код вызывает malloc() и передает выделенную память Py_BuildValue(), ваш код отвечает за вызов free() для этой памяти после возврата Py_BuildValue().

В следующем описании цитируемая форма является единицей формата; запись в круглых скобках — это тип объекта Python, который вернёт блок форматирования; а запись в [квадратных] скобках — это тип передаваемых значений C.

Пробел, табуляция, двоеточие и запятая игнорируются в строках формата (но не в таких единицах формата, как s#). Это можно использовать, чтобы сделать строки длинного формата более читабельными.

s (str или None) [const char *]
Преобразовывает строку C с завершающим нулем в объект Python str, используя 'utf-8' кодирование. Если указатель строки C — NULL, используется None.
s# (str или None) [const char *, int или Py_ssize_t]
Преобразовывает строку C и её длину в объект Python str с помощью 'utf-8' кодирование. Если указатель строки C — NULL, длина игнорируется и None возвращается.
y (bytes) [const char *]
Это преобразует строку C в объект Python bytes. Если C указатель строки — NULL, возвращается None.
y# (bytes) [const char *, int или Py_ssize_t]
Это преобразует строку C и её длину в объект Python. Если C указатель строки — NULL, возвращается None.
z (str или None) [const char *]
То же, что и s.
z# (str или None) [const char *, int или Py_ssize_t]
То же, что и s#.
u (str) [const wchar_t *]
Преобразование буфера wchar_t с завершающим нулем в Юникод (UTF-16 или UCS-4) данные в объект Юникод Python. Если указатель буфера Юникод — NULL , None возвращается.
u# (str) [const wchar_t *, int или Py_ssize_t]
Преобразовывает буфер данных Юникод (UTF-16 или UCS-4) и его длину в Python Объект Юникод. Если указатель буфера Юникод — NULL, длина игнорируется и возвращается None.
U (str или None) [const char *]
То же, что и s.
U# (str или None) [const char *, int или Py_ssize_t]
То же, что и s#.
i (int) [int]
Преобразовывает простой C int в целочисленный объект Python.
b (int) [char]
Преобразовывает простой C char в целочисленный объект Python.
h (int) [short int]
Преобразовывает простой C short int в целочисленный объект Python.
l (int) [long int]
Преобразовывает C long int в целочисленный объект Python.
B (int) [unsigned char]
Преобразовывает C unsigned char в целочисленный объект Python.
H (int) [unsigned short int]
Преобразовывает C unsigned short int в целочисленный объект Python.
I (int) [unsigned int]
Преобразовывает C unsigned int в целочисленный объект Python.
k (int) [unsigned long]
Преобразовывает C unsigned long в целочисленный объект Python.
L (int) [long long]
Преобразовывает C long long в целочисленный объект Python.
K (int) [unsigned long long]
Преобразовывает C unsigned long long в целочисленный объект Python.
n (int) [Py_ssize_t]
Преобразовывает C Py_ssize_t в целое число Python.
c (bytes длины 1) [char]
Преобразовывает C int, представляющий байт, в объект Python bytes размером длина 1.
C (str длины 1) [int]
Преобразовывает C int, представляющий символ, в Python str объект длиной 1.
d (float) [double]
Преобразовывает C double в число с плавающей запятой Python.
f (float) [float]
Преобразовывает C float в число с плавающей запятой Python.
D (complex) [Py_complex *]
Преобразовывает структуру C Py_complex в комплексное число Python.
O (объект) [PyObject *]
Передать объект Python нетронутым (за исключением его счётчика ссылок, который равен увеличивается на единицу). Предполагается, что переданный объект является указателем NULL что это было вызвано тем, что вызов, производящий аргумент, обнаружил ошибку и установить исключение. Следовательно, Py_BuildValue() вернёт NULL, но не вернёт вызвать исключение. Если исключение ещё не возникло, будет SystemError Установленный.
S (объект) [PyObject *]
То же, что и O.
N (объект) [PyObject *]
То же, что и O, за исключением того, что он не увеличивает счётчик ссылок на объект. Полезно, когда объект создается путем вызова конструктора объекта в список аргументов.
O& (объект) [converter, anything]
Преобразовывает anything в объект Python с помощью функции converter. Файл функция вызывается с anything (который должен быть совместим с void*) в качестве аргумента и должен возвращать «новый» объект Python или NULL, если файл Возникла ошибка.
(items) (tuple) [matching-items]
Преобразовывает последовательность значений C в кортеж Python с тем же количеством Элементов.
[items] (list) [matching-items]
Преобразовывает последовательность значений C в список Python с тем же количеством Элементов.
{items} (dict) [matching-items]
Преобразовывает последовательность значений C в словарь Python. Каждая пара подряд C values добавляет в словарь один элемент, который служит ключом и значением соответственно.

Если в строке формата есть ошибка, устанавливается исключение SystemError и возвращается NULL.

PyObject* Py_VaBuildValue(const char *format, va_list vargs)
Return value: New reference.

Идентичен Py_BuildValue(), за исключением того, что принимает va_list, а не переменное количество аргументов.