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

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

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

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

Есть три способа преобразовать строки и буферы в C:

• Форматы, такие как y* и s*, заполняют структуру Py_buffer. Это блокирует базовый буфер, чтобы вызывающий код мог впоследствии использовать его даже внутри блока Py_BEGIN_ALLOW_THREADS без риска изменения размера или уничтожения изменяемых данных. Поэтому необходимо вызвать PyBuffer_Release() после завершения обработки данных (или при любом досрочном прекращении обработки).
• Форматы es, es#, et и et# выделяют буфер для результата. Необходимо вызвать PyMem_Free() после завершения обработки данных (или при любом досрочном прекращении обработки).

• Другие форматы принимают str или доступный только для чтения объект, подобный bytes, например bytes, и предоставляют указатель const char * на его буфер. В этом случае буфер является «заимствованным»: им управляет соответствующий объект Python, и его время жизни совпадает со временем жизни этого объекта. Вам не потребуется самостоятельно освобождать память.

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

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

s (str) [const char *]

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

Примечание

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

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

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

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

s# (str, read-only bytes-like object) [const char *, Py_ssize_t]

Как s*, но предоставляет заимствованный буфер. Результат сохраняется в двух переменных C: первая — указатель на строку C, вторая — её длина. Строка может содержать встроенные нулевые байты. Объекты Unicode преобразуются в строки C с использованием кодировки 'utf-8'.

z (str or None) [const char *]

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

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

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

z# (str, read-only bytes-like object or None) [const char *, Py_ssize_t]

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

y (read-only bytes-like object) [const char *]

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

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

y* (bytes-like object) [Py_buffer]

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

y# (read-only bytes-like object) [const char *, Py_ssize_t]

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

S (bytes) [PyBytesObject *]

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

Y (bytearray) [PyByteArrayObject *]

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

U (str) [PyObject *]

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

w* (read-write bytes-like object) [Py_buffer]

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

es (str) [const char *encoding, char **buffer]

Этот вариант s используется для кодирования Unicode в символьный буфер. Он работает только с кодированными данными, не содержащими встроенных байтов NUL.

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

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

et (str, bytes or bytearray) [const char *encoding, char **buffer]

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

es# (str) [const char *encoding, char **buffer, Py_ssize_t *buffer_length]

Этот вариант s# используется для кодирования Unicode в символьный буфер. В отличие от формата 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 or bytearray) [const char *encoding, char **buffer, Py_ssize_t *buffer_length]

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

Числа

Эти форматы позволяют представлять числа Python или отдельные символы в виде чисел C. В форматах, которым требуются int, float или complex, также можно использовать соответствующие специальные методы __index__(), __float__() или __complex__() для преобразования объекта Python к требуемому типу.

Для форматов знаковых целых чисел, если значение выходит за пределы диапазона типа C, возникает исключение OverflowError. Для форматов беззнаковых целых чисел проверка диапазона не выполняется: наиболее значимые биты отбрасываются без предупреждения, если принимающее поле недостаточно велико для размещения значения.

b (int) [unsigned char]

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

B (int) [unsigned char]

Преобразует целое число Python в крошечное целое число без проверки переполнения, хранящееся в 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 в Py_ssize_t типа C.

c (bytes or bytearray of length 1) [char]

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

Изменено в версии 3.3: Добавлена поддержка объектов bytearray.

C (str of length 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 (object) [PyObject *]

Сохраняет объект Python (без какого-либо преобразования) в указатель на объект C. Таким образом программа на C получает именно тот объект, который был передан. Новая сильная ссылка на объект не создаётся (то есть его счётчик ссылок не увеличивается). Сохранённый указатель не равен NULL.

O! (object) [typeobject, PyObject *]

Сохраняет объект Python в указатель на объект C. Это похоже на O, но принимает два аргумента C: первый — адрес объекта типа Python, второй — адрес переменной C (типа PyObject*), в которую сохраняется указатель на объект. Если объект Python не имеет требуемого типа, возникает исключение TypeError.

O& (object) [converter, address]

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

status = converter(object, address);

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

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

Примеры преобразователей: PyUnicode_FSConverter() и PyUnicode_FSDecoder().

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

p (bool) [int]

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

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

(items) (tuple) [matching-items]

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

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

|

Указывает, что оставшиеся аргументы в списке аргументов 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, ...)

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

Примечание

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

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

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

Добавлено в версии 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 и будут содержать заимствованные ссылки. Переменные, соответствующие необязательным параметрам, не переданным в 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 это пустое значение, а для C++ — const (const char *const*). Чтобы переопределить его, задайте нужное значение перед включением Python.h.

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