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

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

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

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

Существует три способа преобразования строк и буферов в C:

• Форматы, такие как y* и s* заполняют структуру Py_buffer. Это блокирует лежащий в основе буфер, так что вызывающая сторона может впоследствии использовать буфер даже внутри блока Py_BEGIN_ALLOW_THREADS, не рискуя изменением размера или уничтожением изменяемых данных. В результате, вы должны вызвать PyBuffer_Release() после обработки данных (или в случае любого преждевременного прерывания).
• Форматы es, es#, et и et# выделяют буфер результата. Вы должны вызвать PyMem_Free() после обработки данных (или в случае любого преждевременного прерывания).

• Другие форматы принимают str или только для чтения объект типа bytes-like, такой как 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.

Примечание

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

Изменено в версии 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 *, 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 *]

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

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

y* (bytes-like object) [Py_buffer]

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

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

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

S (bytes) [PyBytesObject *]

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

Y (bytearray) [PyByteArrayObject *]

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

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*, указывающим на имя кодировки как строку с завершением нулём, или 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#, за исключением того, что объекты строк байтов передаются без перекодирования. Вместо этого реализация предполагает, что объект строки байтов использует кодировку, переданную в качестве параметра.

Числа

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 неизменным.

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

Изменено в версии 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. Элементы последовательностей могут быть вложены.

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

Часть стабильного 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)