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

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

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

В целом, когда формат устанавливает указатель на буфер, буфер управляется соответствующим объектом Python и существует в течение его времени жизни. Освобождать память самостоятельно не потребуется. Единственные исключения: es, es#, et и et#.

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

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

Некоторые форматы требуют только для чтения байтоподобный объект и устанавливают указатель вместо структуры буфера. Они работают, проверяя, что поле PyBufferProcs.bf_releasebuffer объекта равно NULL, что запрещает изменяемые объекты, такие как bytearray.

s (str) [const char *]

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

Примечание

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

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

s* (str или байтоподобный объект) [Py_buffer]

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

s# (str, только для чтения байтоподобный объект) [const char *, int или Py_ssize_t]

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

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

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

z* (str, байтоподобный объект или None) [Py_buffer]

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

z# (str, только для чтения байтоподобный объект или None) [const char *, int или Py_ssize_t]

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

y (байтоподобный объект только для чтения) [const char *]

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

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

y* (байтоподобный объект) [Py_buffer]

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

y# (только для чтения байтоподобный объект) [const char *, int или 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 *]

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

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

Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API Py_UNICODE; переходите на использование PyUnicode_AsWideCharString().

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

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

Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API Py_UNICODE; переходите на использование PyUnicode_AsWideCharString().

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

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

Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API Py_UNICODE; переходите на использование PyUnicode_AsWideCharString().

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

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

Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API Py_UNICODE; переходите на использование PyUnicode_AsWideCharString().

U (str) [PyObject *]

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

w* (байтоподобный объект для чтения и записи) [Py_buffer]

Этот формат принимает любой объект, реализующий интерфейс буфера для чтения-записи. Он заполняет структуру Py_buffer, предоставленную вызывающей стороной. Буфер может содержать встроенные нулевые байты. Вызывающая сторона должна вызвать PyBuffer_Release(), когда закончит работу с буфером.

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

Этот вариант s используется для кодирования Unicode в символьный буфер. Он работает только с закодированными данными без встроенных NUL-байтов.

Этот формат требует два аргумента. Первый используется только как входной и должен быть const char*, указывающим на имя кодировки в виде строки, завершающейся нулевым символом, или 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 или 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 как размер буфера. Затем он скопирует закодированные данные в буфер и завершит их NUL. Если буфер недостаточно велик, будет установлено ValueError.

В обоих случаях *buffer_length устанавливается в длину закодированных данных без завершающего NUL-байта.

et# (str, bytes или bytearray) [const char *encoding, char **buffer, int или Py_ssize_t *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) [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 или bytearray длиной 1) [char]

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

Изменено в версии 3.3: Допускаются объекты bytearray.

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& (object) [конвертер, что угодно]

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

status = converter(object, address);

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

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

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

p (bool) [int]

Проверяет переданное значение на истинность (булев предикат p) и преобразует результат в эквивалентное целое C true/false. Устанавливает int в 1, если выражение истинно, и в 0, если ложно. Принимает любое корректное значение Python. См. Проверка истинности значений для получения дополнительной информации о том, как Python проверяет значения на истинность.

Новое в версии 3.3.

(items) (tuple) [соответствующие элементы]

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

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

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

|

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

$

PyArg_ParseTupleAndKeywords() only: Указывает, что остальные аргументы в списке аргументов Python являются только ключевыми. В настоящее время все только ключевые аргументы также должны быть необязательными, поэтому | всегда должен указываться перед $ в строке формата.

Новое в версии 3.3.

:

Список единиц форматирования заканчивается здесь; строка после двоеточия используется как имя функции в сообщениях об ошибках («связанное значение» исключения, которое вызывает 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[], ...)¶

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

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

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

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

int PyArg_ValidateKeywordArguments(PyObject *)¶

Гарантирует, что ключи в словаре аргументов-ключевых слов являются строками. Это нужно только в случае, если PyArg_ParseTupleAndKeywords() не используется, поскольку последняя уже выполняет эту проверку.

Новое в версии 3.2.

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

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

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)