Разбор аргументов и построение значений¶Parsing arguments and building values

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

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

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

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

s (str) [const char *]

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

Примечание

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

s* (str, bytes, bytearray или объект, совместимый с буфером) [Py_buffer]

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

s# (str, bytes или объект, совместимый с буфером только для чтения) [const char *, int или Py_ssize_t]

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

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

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

z* (str, bytes, bytearray, объект, совместимый с буфером или None) [Py_buffer]

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

z# (str, bytes, объект, совместимый с буфером только для чтения или None) [const char *, int]

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

y (bytes) [const char *]

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

y* (bytes, bytearray или объект, совместимый с буфером) [Py_buffer]

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

y# (bytes) [const char *, int]

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

S (bytes) [PyBytesObject *]

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

Y (bytearray) [PyByteArrayObject *]

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

u (str) [Py_UNICODE *]

Преобразует объект Python Unicode в указатель C на буфер Unicode, завершающийся NUL. Необходимо передать адрес переменной-указателя Py_UNICODE, которая будет заполнена указателем на существующий буфер Unicode. Обратите внимание, что ширина символа Py_UNICODE зависит от опций компиляции (она составляет 16 или 32 бита).

Примечание

Поскольку u не возвращает длину строки, и она может содержать встроенные нулевые символы, рекомендуется использовать вместо него u# или U.

u# (str) [Py_UNICODE *, int]

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

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

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

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

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

U (str) [PyUnicodeObject *]

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

t# (bytes, bytearray или буфер символов только для чтения) [char *, int]

Как и s#, но принимает любой объект, реализующий интерфейс буфера только для чтения. Переменная char* устанавливается указателем на первый байт буфера, а int – длиной буфера. Принимаются только объекты с односегментным буфером; для всех остальных возбуждается TypeError.

w (bytearray или буфер символов для чтения и записи) [char *]

Похож на y, но принимает любой объект, реализующий интерфейс буфера для чтения и записи. Вызывающая сторона должна определить длину буфера иным способом или использовать w#. Принимаются только объекты с односегментным буфером; для всех остальных возбуждается TypeError.

w* (bytearray или буфер для чтения и записи, ориентированный на байты) [Py_buffer]

Это относится к w так же, как y* относится к y.

w# (bytearray или буфер символов для чтения и записи) [char *, int]

Как и y#, но принимает любой объект, реализующий интерфейс буфера для чтения и записи. Переменная char * устанавливается указателем на первый байт буфера, а int – длиной буфера. Принимаются только объекты с односегментным буфером; для всех остальных возбуждается TypeError.

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

Этот вариант s используется для кодирования Unicode в символьный буфер. Он работает только с закодированными данными без встроенных 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, int *buffer_length]

Этот вариант s# используется для кодирования Unicode в символьный буфер. В отличие от формата 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, int *buffer_length]

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

Числа¶Numbers

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) [PY_LONG_LONG]

Преобразует целое число Python в C long long. Этот формат доступен только на платформах, поддерживающих long long (или _int64 на Windows).

K (int) [unsigned PY_LONG_LONG]

Преобразует целое число Python в C unsigned long long без проверки переполнения. Этот формат доступен только на платформах, поддерживающих unsigned long long (или unsigned _int64 на Windows).

n (int) [Py_ssize_t]

Преобразует целое число Python в C Py_ssize_t.

c (bytes длиной 1) [char]

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

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.

Другие объекты¶Other objects

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

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

O! (object) [typeobject, PyObject *]

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

O& (объект) [converter, anything]

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

status = converter(object, address);

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

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

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

(items) (tuple) [matching-items]

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

Можно передавать «длинные» целые числа (целые, значение которых превышает LONG_MAX платформы), однако надлежащая проверка диапазона не выполняется – старшие биты молча отбрасываются, когда принимающее поле слишком мало для значения (на самом деле, семантика унаследована от понижающих приведений в C – результат может отличаться).

Некоторые другие символы имеют значение в строке формата. Они не могут встречаться внутри вложенных скобок. Вот они:

|

Указывает, что остальные аргументы в списке аргументов Python являются необязательными. Переменные C, соответствующие необязательным аргументам, должны быть инициализированы значением по умолчанию – если необязательный аргумент не указан, PyArg_ParseTuple() не изменяет содержимое соответствующих переменных C.

:

Список единиц формата заканчивается здесь; строка после двоеточия используется как имя функции в сообщениях об ошибках («связанное значение» исключения, которое возбуждает PyArg_ParseTuple()).

;

Список единиц форматирования заканчивается здесь; строка после точки с запятой используется как сообщение об ошибке вместо сообщения об ошибке по умолчанию. : и ; взаимно исключают друг друга.

Обратите внимание, что любые ссылки на объекты Python, передаваемые вызывающему, являются заимствованными ссылками; уменьшать их счётчик ссылок не следует.

Дополнительные аргументы, передаваемые этим функциям, должны быть адресами переменных, тип которых определяется строкой формата; они используются для хранения значений из входного кортежа. Есть несколько случаев, как описано в списке единиц форматирования выше, когда эти параметры используются в качестве входных значений; в этом случае они должны соответствовать тому, что указано для соответствующей единицы форматирования.

Чтобы преобразование прошло успешно, объект arg должен соответствовать формату, а формат должен быть исчерпан. В случае успеха функции PyArg_Parse*() возвращают true, иначе возвращают false и возбуждают соответствующее исключение. Когда функции PyArg_Parse*() завершаются ошибкой из-за сбоя преобразования в одной из единиц формата, переменные по адресам, соответствующим этой и следующим единицам формата, остаются нетронутыми.

API функции¶API Functions

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

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

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

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

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

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

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

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

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

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

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

Более простая форма извлечения параметров, которая не использует строку формата для указания типов аргументов. Функции, использующие этот метод для извлечения параметров, должны быть объявлены как 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)