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

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

Эти форматы позволяют получить доступ к объекту как к непрерывному блоку памяти. Вам не нужно предоставлять исходное хранилище для возвращенной области 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 завершается символом NUL. Строка 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) [const Py_UNICODE *]

Преобразуйте объект Python Unicode в указатель C на завершаемый нулём буфер символов 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 *, 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 *, 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 используется для кодирования Юникода в буфер символов. Он работает только для закодированных данных без вложенных байтов NUL.

Этот формат требует два аргумента. Первый используется только как входной и должен быть 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# используется для кодирования Юникода в буфер символов. В отличие от формата 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 в беззнаковое маленькое целое число, хранящееся в 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. Устанавливает значение 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)