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

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

Эти форматы позволяют получить доступ к объекту как к непрерывному блоку памяти. Вам не нужно предоставлять исходное хранилище для возвращаемой области 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 не должна содержать вложенных кодовых точек null; если они есть, возникает исключение ValueError. Объекты Unicode преобразуются в строки C с использованием кодировки 'utf-8'. Если это преобразование завершается неудачно, возникает UnicodeError.

Примечание

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

Изменено в версии 3.5: Ранее, при обнаружении вложенных кодовых точек null в строке 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) [const Py_UNICODE *]

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

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

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

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

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

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

Он требует трех аргументов. Первый используется только как входной и должен быть 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 в целое без знака типа tiny int, хранящееся в C unsigned char.

B (int) [unsigned char]

Преобразует целое число Python в tiny 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 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). Устанавливает значение 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)