Разбор аргументов и создание значений¶
Эти функции полезны при создании собственных функций и методов расширений. Дополнительную информацию и примеры можно найти в Расширение и встраивание интерпретатора 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, а не переменное количество аргументов.