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

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

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

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

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

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

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

s (str) [const char *]

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

Примечание

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

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

s* (str или bytes-like object) [Py_buffer].

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

s# (str, только для чтения bytes-like object) [const char *, Py_ssize_t]

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

z (str или None) [const char *]

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

z* (str, bytes-like object или None) [Py_buffer].

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

z# (str, только для чтения bytes-like object или None) [const char *, Py_ssize_t]

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

y (только для чтения bytes-like object) [const char *]

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

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

y* (bytes-like object) [Py_buffer].

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

y# (только для чтения bytes-like object) [const char *, 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 на буфер символов Unicode с NUL-терминацией. Вы должны передать адрес переменной-указателя Py_UNICODE, которая будет заполнена указателем на существующий буфер Unicode. Обратите внимание, что ширина символа Py_UNICODE зависит от параметров компиляции (она составляет 16 или 32 бита). Строка Python не должна содержать встроенных нулевых точек кода; если это так, то будет вызвано исключение ValueError.

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

Deprecated since version 3.3, will be removed in version 3.12: Часть API старого образца Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_AsWideCharString().

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

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

Deprecated since version 3.3, will be removed in version 3.12: Часть API старого образца Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_AsWideCharString().

Z (str или None) [const Py_UNICODE *]

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

Deprecated since version 3.3, will be removed in version 3.12: Часть API старого образца Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_AsWideCharString().

Z# (str или None) [const Py_UNICODE *, Py_ssize_t]

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

Deprecated since version 3.3, will be removed in version 3.12: Часть API старого образца Py_UNICODE; пожалуйста, перейдите на использование PyUnicode_AsWideCharString().

U (str) [PyObject *]

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

w* (чтение-запись bytes-like object) [Py_buffer].

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

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

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

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

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

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

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

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

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

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

Номера¶

b (int) [unsigned char]

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

B (int) [unsigned char]

Преобразование целого числа Python в крошечный int без проверки переполнения, хранящийся в 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 или bytearray длиной 1) [char]

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

Изменено в версии 3.3: Разрешить объекты bytearray.

C (str длины 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 (объект) [PyObject *]

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

O! (объект) [typeobject, PyObject *]

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

O& (объект) [конвертер, любой предмет].

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

status = converter(object, address);

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

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

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

p (bool) [int]

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

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

(items) (tuple) [matching-items]

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

Можно передавать «длинные» целые числа (целые числа, значение которых превышает установленное платформой 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, ...)¶

Part of the Stable ABI.

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

int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)¶

Part of the Stable ABI.

Идентичен PyArg_ParseTuple(), за исключением того, что принимает va_list, а не переменное количество аргументов.

int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)¶

Part of the Stable ABI.

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

Изменено в версии 3.6: Добавлена поддержка positional-only parameters.

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)¶

Part of the Stable ABI.

Идентичен PyArg_ParseTupleAndKeywords(), за исключением того, что принимает va_list, а не переменное количество аргументов.

int PyArg_ValidateKeywordArguments(PyObject*)¶

Part of the Stable ABI.

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

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

int PyArg_Parse(PyObject *args, const char *format, ...)¶

Part of the Stable ABI.

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

int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)¶

Part of the Stable ABI.

Более простая форма получения параметров, которая не использует форматную строку для указания типов аргументов. Функции, использующие этот метод для получения параметров, должны быть объявлены как METH_VARARGS в таблицах функций или методов. Кортеж, содержащий фактические параметры, должен быть передан как args; на самом деле это должен быть кортеж. Длина кортежа должна быть не менее min и не более max; min и max могут быть равны. В функцию должны быть переданы дополнительные аргументы, каждый из которых должен быть указателем на переменную PyObject*; они будут заполнены значениями из args; они будут содержать borrowed references. Переменные, соответствующие необязательным параметрам, не заданным 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)