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

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

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

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

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

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

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

Изменено в версии 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, если объект не является объектом типа байты. Переменная 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 неизменным.

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

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

p (bool) [int]

Проверяет значение, переданное на истинность (булево предикат) и преобразует результат в эквивалентное C-целое значение true/false. Устанавливает целое число в 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 *const *keywords, ...)

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

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

Примечание

Объявление параметра keywords — char *const* в C и const char *const* в C++. Это можно переопределить с помощью макроса PY_CXX_CONST.

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

Изменено в версии 3.13: Параметр keywords теперь имеет тип char *const* в C и const char *const* в C++, вместо char**. Добавлена поддержка имён именованных параметров, не являющихся ASCII.

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

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

Пример:

// Function using METH_O calling convention
static PyObject*
my_function(PyObject *module, PyObject *arg)
{
    int value;
    if (!PyArg_Parse(arg, "i:my_function", &value)) {
        return NULL;
    }
    // ... use value ...
}

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)

PY_CXX_CONST

Значение для вставки, если необходимо, перед char *const* в объявлении параметра keywords функций PyArg_ParseTupleAndKeywords() и PyArg_VaParseTupleAndKeywords(). По умолчанию пустое для C и const для C++ (const char *const*). Для переопределения, задайте нужное значение перед включением Python.h.

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