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

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

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

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

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

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

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

s (str) [const char *]

Преобразование объекта Unicode в указатель C на строку символов. Указатель на существующую строку сохраняется в переменной типа указатель на символ, адрес которой вы передаёте. Строка C завершается символом NULL. Строка 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 *, 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 *]

Этот формат преобразует объект типа 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 *, int or Py_ssize_t]

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

S (bytes) [PyBytesObject *]

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

Y (bytearray) [PyByteArrayObject *]

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

u (str) [const Py_UNICODE *]

Преобразуйте объект Python Unicode в указатель C на завершаемый символом NULL буфер символов 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, завершаемой символом NULL, или 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 как размер буфера. Затем он скопирует закодированные данные в буфер и добавит завершающий нулевой байт. Если буфер недостаточно велик, будет установлено исключение ValueError.

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

et# (str, bytes or bytearray) [const char *encoding, char **buffer, int or Py_ssize_t *buffer_length]

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

Числа

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, anything]

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

status = converter(object, address);

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

Если конвертер возвращает 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)