Разбор аргументов и создание значений¶

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

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

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

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

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

Примечание

В Python 3.12 и старше макрос PY_SSIZE_T_CLEAN должен быть определен до включения Python.h, чтобы использовать все варианты форматов # (s#, y# и т. д.), описанные ниже. В Python 3.13 и более поздних версиях это не требуется.

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

Если не указано иное, буферы не имеют NUL-терминации.

Существует три способа преобразования строк и буферов в C:

Такие форматы, как y* и s*, заполняют структуру Py_buffer. Это блокирует базовый буфер, так что вызывающая сторона может впоследствии использовать буфер даже внутри блока Py_BEGIN_ALLOW_THREADS без риска изменения размера или уничтожения мутируемых данных. В результате вам придется вызывать PyBuffer_Release() после завершения обработки данных (или в случае раннего прерывания).
Форматы es, es#, et и et# выделяют буфер результата. Вы должны вызвать PyMem_Free() после завершения обработки данных (или в случае раннего прерывания).
Другие форматы принимают str или bytes-like object, доступный только для чтения, например bytes, и предоставляют указатель const char * на свой буфер. В этом случае буфер «заимствуется»: он управляется соответствующим объектом Python и имеет общее время жизни с этим объектом. Вам не придется освобождать память самостоятельно.

Чтобы гарантировать, что базовый буфер можно безопасно заимствовать, поле PyBufferProcs.bf_releasebuffer объекта должно быть равно NULL. Это не позволяет использовать обычные мутируемые объекты, такие как bytearray, а также некоторые объекты, доступные только для чтения, например memoryview и bytes.

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

s (str) [const char *]

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

Примечание

Этот формат не принимает bytes-like objects. Если вы хотите принимать пути файловой системы и преобразовывать их в строки символов C, предпочтительнее использовать формат O& с PyUnicode_FSConverter() в качестве конвертера.

Изменено в версии 3.5: Ранее при обнаружении в строке Python встроенных точек нулевого кода возникала ошибка TypeError.

s* (str или bytes-like object) [Py_buffer]

Этот формат принимает объекты Unicode, а также байтоподобные объекты. Он заполняет структуру Py_buffer, предоставленную вызывающей стороной. В этом случае результирующая строка C может содержать встроенные байты NUL. Объекты Unicode преобразуются в строки C с использованием кодировки 'utf-8'.

s# (str, только для чтения bytes-like object) [const char *, Py_ssize_t]

Аналогично s*, за исключением того, что он предоставляет borrowed buffer. Результат сохраняется в двух переменных C, первая из которых - указатель на строку C, а вторая - ее длина. Строка может содержать встроенные нулевые байты. Объекты Unicode преобразуются в строки C с использованием кодировки 'utf-8'.

z (str или None) [const char *]

Как и s, но объект Python может быть и None, в этом случае указатель C устанавливается на NULL.

z* (str, bytes-like object или None) [Py_buffer]

Как и s*, но объект Python может быть и None, в этом случае член buf структуры Py_buffer устанавливается в NULL.

z# (str, только для чтения bytes-like object или None) [const char *, Py_ssize_t]

Как и s#, но объект Python может быть и None, в этом случае указатель C устанавливается на NULL.

y (только для чтения bytes-like object) [const char *]

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

Изменено в версии 3.5: Ранее при обнаружении в буфере байтов встроенных нулевых байтов возникала ошибка TypeError.

y* (bytes-like object) [Py_buffer]

Этот вариант на s* не принимает объекты Unicode, только байтоподобные объекты. Это рекомендуемый способ приема двоичных данных.

y# (только для чтения bytes-like object) [const char *, Py_ssize_t]

Этот вариант на s# не принимает объекты Unicode, только байтоподобные объекты.

S (bytes) [PyBytesObject *]

Требует, чтобы объект Python был объектом bytes, не пытаясь преобразовать его. Вызывает TypeError, если объект не является объектом байта. Переменная C также может быть объявлена как PyObject*.

Y (bytearray) [PyByteArrayObject *]

Требует, чтобы объект Python был объектом bytearray, не пытаясь преобразовать его. Вызывает TypeError, если объект не является объектом bytearray. Переменная C также может быть объявлена как PyObject*.

U (str) [PyObject *]

Требует, чтобы объект Python был объектом Unicode, не пытаясь преобразовать его. Вызывает TypeError, если объект не является объектом Юникода. Переменная C также может быть объявлена как PyObject*.

w* (чтение-запись bytes-like object) [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, Py_ssize_t *длина_буфера]

Этот вариант 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, Py_ssize_t *длина_буфера]

То же, что и es#, за исключением того, что объекты байтовых строк передаются без их перекодировки. Вместо этого реализация предполагает, что объект байтовой строки использует кодировку, переданную в качестве параметра.

Изменено в версии 3.12: u, u#, Z и Z# удалены, поскольку они использовали унаследованное представление Py_UNICODE*.

Номера¶

b (int) [unsigned char]: Преобразование неотрицательного целого числа Python в беззнаковое число tiny 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 в число float в языке C.
d (float) [double]: Преобразование числа с плавающей точкой в языке Python в число double в языке C.
D (complex) [Py_complex]: Преобразование комплексного числа Python в структуру C Py_complex.

Другие объекты¶

O (объект) [PyObject *]: Сохраните объект Python (без преобразования) в указателе объекта C. Таким образом, программа на языке C получает реальный объект, который был передан. Новый strong reference на объект не создается (т. е. количество ссылок на него не увеличивается). Хранимый указатель не является NULL.
O! (объект) [typeobject, PyObject *]: Хранит объект Python в объектном указателе C. Эта функция аналогична O, но принимает два аргумента C: первый - адрес объекта типа Python, второй - адрес переменной C (типа PyObject*), в которой хранится указатель объекта. Если объект Python не имеет требуемого типа, выдается сообщение TypeError.

O& (объект) [конвертер, любая вещь]

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

status = converter(object, address);

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

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

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

p (bool) [int]

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

Added in version 3.3.

(items) (tuple) [matching-items]

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

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

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

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

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

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

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

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

Функции API¶

int PyArg_ParseTuple(PyObject *args, const char *format, ...)¶: Часть Стабильный ABI.
Разбор параметров функции, принимающей только позиционные параметры, в локальные переменные. В случае успеха возвращает true; в случае неудачи возвращает false и вызывает соответствующее исключение.

int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)¶: Часть Стабильный ABI.
Идентичен PyArg_ParseTuple(), за исключением того, что принимает va_list, а не переменное количество аргументов.

int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, ...)¶: Часть Стабильный ABI.
Разбор параметров функции, принимающей как позиционные, так и ключевые параметры, в локальные переменные. Аргумент keywords представляет собой NULL-конечный массив имен параметров ключевых слов, заданных в виде нуль-терминированных строк ASCII или UTF-8 в кодировке C. Пустые имена обозначают positional-only parameters. В случае успеха возвращает true; в случае неудачи возвращает false и вызывает соответствующее исключение.

Примечание

Объявление параметров keywords - это char *const* в C и const char *const* в C++. Это можно переопределить с помощью макроса PY_CXX_CONST.

Изменено в версии 3.6: Добавлена поддержка positional-only parameters.

Изменено в версии 3.13: Параметр keywords теперь имеет тип char *const* в C и const char *const* в C++, вместо char**. Добавлена поддержка имен параметров ключевых слов, отличных от ASCII.

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, va_list vargs)¶: Часть Стабильный ABI.
Идентичен PyArg_ParseTupleAndKeywords(), за исключением того, что принимает va_list, а не переменное количество аргументов.

int PyArg_ValidateKeywordArguments(PyObject*)¶: Часть Стабильный ABI.
Убедитесь, что ключи в словаре аргументов keywords являются строками. Это необходимо только в том случае, если не используется PyArg_ParseTupleAndKeywords(), поскольку последний уже выполняет эту проверку.

Added in version 3.2.

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

Часть Стабильный ABI.

Разбор параметра функции, принимающей один позиционный параметр, в локальную переменную. В случае успеха возвращает true; в случае неудачи возвращает false и вызывает соответствующее исключение.

Пример:

// Function using METH_O calling convention
static PyObject*
my_function(PyObject *module, PyObject *arg)
{
    int value;
    if (!PyArg_Parse(arg, "i:my_function", &value)) {
        return NULL;
    }
    // ... use value ...
}

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

Часть Стабильный ABI.

Более простая форма получения параметров, которая не использует строку формата для указания типов аргументов. Функции, использующие этот метод для получения своих параметров, должны быть объявлены как METH_VARARGS в таблицах функций или методов. Кортеж, содержащий фактические параметры, должен передаваться как args; на самом деле это должен быть кортеж. Длина кортежа должна быть не менее min и не более max; min и max могут быть равны. Функции должны быть переданы дополнительные аргументы, каждый из которых должен быть указателем на переменную PyObject*; они будут заполнены значениями из args; они будут содержать borrowed references. Переменные, соответствующие необязательным параметрам, не указанным в args, не будут заполнены; они должны быть инициализированы вызывающей стороной. Эта функция возвращает true в случае успеха и false, если 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)

PY_CXX_CONST¶: Значение, которое должно быть вставлено перед char *const* в объявлении параметра keywords в PyArg_ParseTupleAndKeywords() и PyArg_VaParseTupleAndKeywords(), если таковое имеется. По умолчанию пусто для C и const для C++ (const char *const*). Чтобы переопределить его, задайте нужное значение перед включением Python.h.

Added in version 3.13.

Строительные ценности¶

PyObject *Py_BuildValue(const char *format, ...)¶

Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.

Создает новое значение на основе строки формата, аналогичной тем, которые принимаются семейством функций 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 *, 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 *, Py_ssize_t: Преобразует строку C и ее длину в объект Python. Если указатель строки C равен NULL, возвращается None.
z (str или None) [const char *]: То же, что и s.
z# (str или None) [const char *, Py_ssize_t]: То же, что и s#.
u (str) [const wchar_t *]: Преобразование нуль-терминированного wchar_t буфера данных Unicode (UTF-16 или UCS-4) в объект Python Unicode. Если указатель буфера Unicode равен NULL, возвращается None.
u# (str) [const wchar_t *, Py_ssize_t: Преобразование буфера данных Unicode (UTF-16 или UCS-4) и его длины в объект Python Unicode. Если указатель буфера Unicode равен NULL, длина игнорируется и возвращается None.
U (str или None) [const char *]: То же, что и s.
U# (str или None) [const char *, 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 нетронутым, но создайте для него новый strong reference (т. е. количество ссылок увеличивается на единицу). Если переданный объект является указателем NULL, предполагается, что это произошло из-за того, что вызов, выдавший аргумент, обнаружил ошибку и создал исключение. Следовательно, Py_BuildValue() вернет NULL, но не вызовет исключения. Если исключение не было вызвано, устанавливается SystemError.
S (объект) [PyObject *]: То же, что и O.
N (объект) [PyObject *]: То же самое, что и O, за исключением того, что не создает новый strong reference. Полезно, когда объект создается вызовом конструктора объектов в списке аргументов.
O& (объект) [конвертер, любая вещь]: Преобразуйте любую вещь в объект Python с помощью функции конвертер. Функция вызывается с аргументом anything (который должен быть совместим с void*) и должна вернуть «новый» объект Python, или NULL, если произошла ошибка.
(items) (tuple) [matching-items]: Преобразуйте последовательность значений на языке C в кортеж на языке Python с тем же количеством элементов.
[items] (list) [matching-items]: Преобразуйте последовательность значений C в список Python с тем же количеством элементов.
{items} (dict) [matching-items]: Преобразуйте последовательность значений C в словарь Python. Каждая пара последовательных значений C добавляет один элемент в словарь, выступая в качестве ключа и значения соответственно.

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

PyObject *Py_VaBuildValue(const char *format, va_list vargs)¶: Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Идентичен Py_BuildValue(), за исключением того, что принимает va_list, а не переменное количество аргументов.

Разбор аргументов и создание значений¶