Парсинг аргументов и построение значений

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

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

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

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

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

Некоторые форматы требуют только для чтения объект типа bytes-like, и устанавливают указатель вместо структуры буфера. Они работают, проверяя, что поле PyBufferProcs.bf_releasebuffer объекта равно NULL, что запрещает изменяемые объекты, такие как bytearray.

s (str) [const char *]

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

Примечание

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

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

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

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

s# (str, read-only bytes-like object) [const char *, int or 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 *, int or Py_ssize_t]

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

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

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

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

y* (bytes-like object) [Py_buffer]

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

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

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

S (bytes) [PyBytesObject *]

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

Y (bytearray) [PyByteArrayObject *]

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

u (str) [const Py_UNICODE *]

Преобразовать объект Python Unicode в указатель C на завершаемый символом NUL буфер символов Unicode. Вы должны передать адрес переменной указателя Py_UNICODE, которая будет заполнена указателем на существующий буфер Unicode. Обратите внимание, что ширина символа Py_UNICODE зависит от параметров компиляции (она составляет либо 16, либо 32 бита). Строка Python не должна содержать вложенных нулевых кодовых точек; в противном случае возникает исключение ValueError.

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

Устарело начиная с версии 3.3, будет удалено в версии 3.12: Часть старого стиля API Py_UNICODE; пожалуйста, перейдите к использованию PyUnicode_AsWideCharString().

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

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

Устарело начиная с версии 3.3, будет удалено в версии 3.12: Часть старого стиля API Py_UNICODE; пожалуйста, перейдите к использованию PyUnicode_AsWideCharString().

Z (str or None) [const Py_UNICODE *]

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

Устарело начиная с версии 3.3, будет удалено в версии 3.12: Часть старого стиля API Py_UNICODE; пожалуйста, перейдите к использованию PyUnicode_AsWideCharString().

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

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

Устарело начиная с версии 3.3, будет удалено в версии 3.12: Часть старого стиля API Py_UNICODE; пожалуйста, перейдите к использованию PyUnicode_AsWideCharString().

U (str) [PyObject *]

Требует, чтобы объект Python был объектом Unicode, без попыток преобразования. Возбуждает TypeError, если объект не является объектом Unicode. Переменная 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*, который указывает на имя кодировки в виде строки C, завершающейся символом NUL, или NULL, в этом случае используется кодировка 'utf-8'. Если заданная кодировка не известна Python, возникает исключение. Второй аргумент должен быть char**; значение указателя, на который он ссылается, будет установлено в буфер с содержимым аргумента text. Текст будет закодирован в кодировке, указанной первым аргументом.

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

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

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

es# (str) [const char *encoding, char **buffer, int or 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, int or Py_ssize_t *buffer_length]

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

Числа

b (int) [unsigned char]

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

B (int) [unsigned char]

Преобразование целого числа Python в целое число tiny без проверки переполнения, хранящееся в 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, anything]

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

status = converter(object, address);

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

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

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

p (bool) [int]

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

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

(items) (tuple) [matching-items]

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

Возможна передача «длинных» целых чисел (целых чисел, значение которых превышает LONG_MAX платформы), однако никакой проверки диапазона не выполняется — наиболее значимые биты обрезаются без предупреждения, когда получаемое поле слишком мало для приёма значения (на самом деле, семантика унаследована от приведений типов в 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 *)

Убеждается, что ключи в словаре аргумента keywords — это строки. Это необходимо только в том случае, если не используется PyArg_ParseTupleAndKeywords(), так как последний уже выполняет эту проверку.

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