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

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

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

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

Существует три способа преобразования строк и буферов в 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 завершается нулевым символом. Строка 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 может содержать встроенные нулевые байты. Объекты 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 он не принимает. Буфер байтов не должен содержать встроенных нулевых байтов; в противном случае вызывается исключение ValueError.

Изменено в версии 3.5: Ранее при обнаружении встроенных нулевых байтов в буфере байтов вызывалось исключение 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 в символьный буфер. Он работает только с кодированными данными, не содержащими встроенных нулевых байтов.

Для этого формата требуются два аргумента. Первый используется только как входной и должен иметь тип const char* и указывать на имя кодировки в виде строки, завершающейся нулевым символом, либо быть равным 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, этот вариант допускает входные данные, содержащие нулевые символы.

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

Предусмотрено два режима работы:

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

Если *buffer указывает на ненулевой указатель NULL (на уже выделенный буфер), PyArg_ParseTuple() использует эту область как буфер и интерпретирует исходное значение *buffer_length как размер буфера. Затем функция скопирует закодированные данные в буфер и добавит завершающий нулевой символ. Если буфер недостаточно велик, будет установлено исключение ValueError.

В обоих случаях *buffer_length устанавливается в длину закодированных данных без завершающего нулевого байта.

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 без проверки переполнения.

Изменено в версии 3.14: Используется __index__(), если он доступен.

L (int) [long long]

Преобразует целое число Python в целое число C типа long long.

K (int) [unsigned long long]

Преобразует целое число Python в целое число C типа unsigned long long без проверки переполнения.

Изменено в версии 3.14: Используется __index__(), если он доступен.

n (int) [Py_ssize_t]

Преобразует целое число Python в тип C Py_ssize_t.

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) (sequence) [matching-items]

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

Если items содержит единицы формата, сохраняющие заимствованный буфер (s, s#, z, z#, y или y#) или заимствованную ссылку (S, Y, U, O или O!), объект должен быть кортежем Python. Преобразователь для единицы формата O& в items не должен сохранять заимствованный буфер или заимствованную ссылку.

Изменено в версии 3.14: Объекты str и bytearray больше не принимаются в качестве последовательности.

Устарело с версии 3.14: Последовательности, не являющиеся кортежами, считаются устаревшими, если items содержит единицы формата, сохраняющие заимствованный буфер или заимствованную ссылку.

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

|

Указывает, что оставшиеся аргументы в списке аргументов Python необязательны. Переменным C, соответствующим необязательным аргументам, следует присвоить значения по умолчанию: если необязательный аргумент не указан, PyArg_ParseTuple() не изменяет содержимое соответствующей переменной или переменных C. Например, строке формата "OO|OO" соответствует сигнатура Python f(a, b, c=None, d=None).

$

Только для PyArg_ParseTupleAndKeywords(): указывает, что оставшиеся аргументы в списке аргументов Python должны передаваться только по ключевому слову. Они необязательны, если перед $ указан |, и обязательны в противном случае. | нельзя указывать после $. Например, строке формата "O|O$O" соответствует сигнатура Python f(a, b=None, *, c=None), а строке формата "OO$OO" — f(a, b, *, c, d).

Добавлено в версии 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.