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

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

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

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

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

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 в 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) (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 *keywords[], ...)

Часть стабильного ABI.

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

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

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *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.

Функция для разбора списков аргументов функций «старого образца» — функций, использующих метод разбора параметров METH_OLDARGS, удалённый в Python 3. Не рекомендуется использовать этот метод для разбора параметров в новом коде; большая часть кода стандартного интерпретатора была изменена и больше не использует его для этой цели. Однако он по-прежнему удобен для разбора других кортежей и может использоваться для этой цели.

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)