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

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

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

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

Строка формата состоит из нуля или более «единиц формата». Единица формата описывает один объект 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, а не переменное количество аргументов.