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

Здесь приведены полезные функции при создании собственных функций и методов расширения. Дополнительная информация и примеры приведены в Расширение и встраивание интерпретатора 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() как конвертер.

Изменено в версии 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 в буфер, заканчивающийся NUL, состоящий из символов Юникода. Необходимо передать адрес переменной указателя Py_UNICODE, которая будет заполнена указателем, существующему буферу Юникода. Обратите внимание, что ширина Py_UNICODE символ зависит от параметров компиляции (16 или 32 бита). Python строка не должен содержать внедренные нулевые точки код; в этом случае возникает ValueError исключение.

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

Deprecated since version 3.3, will be removed in version 4.0: Часть старого стиля Py_UNICODE API; выполните миграцию с использованием PyUnicode_AsWideCharString().

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

Это вариант u сохраняет две переменные C, первая - указатель на буфер данных Юникода, вторая - его длину. Этот вариант допускает нулевые точки код.

Deprecated since version 3.3, will be removed in version 4.0: Часть старого стиля Py_UNICODE API; выполните миграцию с использованием PyUnicode_AsWideCharString().

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

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

Deprecated since version 3.3, will be removed in version 4.0: Часть старого стиля Py_UNICODE API; выполните миграцию с использованием PyUnicode_AsWideCharString().

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

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

Deprecated since version 3.3, will be removed in version 4.0: Часть старого стиля Py_UNICODE API; выполните миграцию с использованием 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 или Py_ssize_t *buffer_length]

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

Числа

b (int) [unsigned char]

Преобразовать неотрицательного Python целого числа в беззнаковый крошечный int, хранящейся в C unsigned char.

B (int) [unsigned char]

Преобразовать целое число Python в крошечное число без проверки переполнения, хранящееся в C unsigned char.

h (int) [short int]

Преобразовать в Python integer в C:c:type: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]

Преобразование целого число 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, в char C.

Изменено в версии 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]

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

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

(items) (tuple) [matching-items]

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

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

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

|

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

$

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

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

:

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

;

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

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

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

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

Функции API

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

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

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-заканчивающимся массивом имен ключевых параметров. Пустые имена обозначают только позиционные параметры. Возвращает true на успех; при сбое оно возвращает false и вызывает соответствующее исключение.

Изменено в версии 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() не используеncz, так как последний уже делает эту проверку.

Добавлено в версии 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, заполняться не будут; они должны инициализироваться вызывающим. Эта функция возвращает 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)

Сборочные значения

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]

Преобразование простого int C в Python целочисленный объект.

b (int) [char]

Преобразование простого char C в Python целочисленный объект.

h (int) [short int]

Преобразование простого C short int в Python целочисленный объект.

l (int) [long int]

Преобразование C long int в Python целочисленный объект.

B (int) [unsigned char]

Преобразование C:c:type: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]

Преобразование double C в Python число с плавающей запятой.

f (float) [float]

Преобразование 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) [соответствующие-элементы]

Преобразование последовательности C значений в кортеж Python с одинаковым количеством элементов.

[items] (list) [соответствующие-элементы]

Преобразование последовательности C значений в список Python с одинаковым количеством элементов.

{items} (dict) [соответствующие-элементы]

Преобразование последовательности C значений в Python словарь. Каждая пара последовательных C значений добавляет в словарь один элемент, служащий соответственно ключом и значением.

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

PyObject* Py_VaBuildValue(const char *format, va_list vargs)

Return value: New reference.

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