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

Эти функции полезны при создании собственных функций и методов расширений. Дополнительная информация и примеры доступны в Расширение и встраивание интерпретатора Python.

Первые три из описанных функций, PyArg_ParseTuple, PyArg_ParseTupleAndKeywords и PyArg_Parse, используют строки формата, которые сообщают функции об ожидаемых аргументах. Синтаксис строк формата одинаков для всех этих функций.

Строка формата состоит из нуля или более «единиц формата». Единица формата описывает один объект Python; обычно это один символ или заключённая в скобки последовательность единиц формата. За несколькими исключениями, единица формата, не являющаяся последовательностью в скобках, обычно соответствует одному аргументу-адресу этих функций. В следующем описании приведённая в кавычках форма – это единица формата; запись в круглых скобках – тип объекта Python, которому соответствует единица формата; а запись в квадратных скобках – тип переменной(ых) C, чей адрес следует передать.

s (строковый или Unicode-объект) [const char *]

Преобразует строковый или Unicode-объект Python в указатель C на строку символов. Не нужно выделять память для самой строки; указатель на существующую строку сохраняется в переменную-указатель на символ, адрес которой передается. Строка C завершается нулевым символом. Строка Python не должна содержать встроенных нулевых байтов; если они есть, возбуждается исключение TypeError. Unicode-объекты преобразуются в C-строки с использованием кодировки по умолчанию. Если такое преобразование не удается, возбуждается UnicodeError.

Начиная с Python 2.5 тип аргумента длины можно контролировать, определив макрос PY_SSIZE_T_CLEAN до включения Python.h. Если макрос определен, длина имеет тип Py_ssize_t, а не int.

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

Этот вариант похож на s, но код заполняет структуру Py_buffer, предоставленную вызывающим кодом. В этом случае строка Python может содержать встроенные нулевые байты. Unicode-объекты возвращают указатель на строковое представление объекта в кодировке по умолчанию, если такое преобразование возможно. Базовый буфер блокируется, так что вызывающий код может впоследствии использовать буфер даже внутри блока Py_BEGIN_ALLOW_THREADS. Вызывающий код отвечает за вызов PyBuffer_Release со структурой после обработки данных.

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

Этот вариант s сохраняет результат в две C-переменные: первая – указатель на строку символов, вторая – её длина. В этом случае строка Python может содержать встроенные нулевые байты. Unicode-объекты возвращают указатель на строковое представление объекта в кодировке по умолчанию, если такое преобразование возможно. Все остальные объекты, совместимые с буфером чтения, возвращают ссылку на сырое внутреннее представление данных. Поскольку этот формат не допускает объекты, совместимые с буфером записи (например, массивы байтов), предпочтительнее использовать s*.

Тип аргумента длины (int или Py_ssize_t) контролируется определением макроса PY_SSIZE_T_CLEAN до включения Python.h. Если макрос был определен, длина имеет тип Py_ssize_t, а не int. Это поведение изменится в будущей версии Python – будет поддерживаться только Py_ssize_t, а поддержка int будет удалена. Лучше всегда определять PY_SSIZE_T_CLEAN.

y (объект bytes) [const char *]

Этот вариант s преобразует объект Python bytes или bytearray в указатель C на строку символов. Объект bytes не должен содержать встроенных нулевых байтов (NUL); если они есть, возбуждается исключение TypeError.

y* (объект bytes) [Py_buffer *]

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

y# (объект bytes) [const char *, int]

Этот вариант s# сохраняет результат в две C-переменные: первая – указатель на строку символов, вторая – её длина. Он принимает только байтовые объекты, не массивы байтов.

z (строковый или None) [const char *]

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

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

Это относится к s* так же, как z относится к s.

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

Это относится к s# так же, как z относится к s.

u (Unicode-объект) [Py_UNICODE *]

Преобразует Unicode-объект Python в указатель C на буфер с завершающим нулем, содержащий 16-битные Unicode-данные (UTF-16). Как и в s, нет необходимости выделять память для буфера Unicode-данных; указатель на существующие Unicode-данные сохраняется в переменную-указатель Py_UNICODE, адрес которой передается.

u# (Unicode-объект) [Py_UNICODE *, int]

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

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

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

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

Это относится к u# так же, как Z относится к u.

es (строковый, Unicode-объект или объект, совместимый с символьным буфером) [const char *encoding, char **buffer]

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

Этот формат требует два аргумента. Первый используется только как входной и должен быть const char*, указывающим на имя кодировки в виде строки, завершающейся нулем, или NULL; в последнем случае используется кодировка по умолчанию. Если указанная кодировка не известна Python, возбуждается исключение. Второй аргумент должен быть char**; значение указателя, на который он ссылается, будет установлено на буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, указанной первым аргументом.

PyArg_ParseTuple выделит буфер необходимого размера, скопирует закодированные данные в этот буфер и настроит *buffer так, чтобы он ссылался на вновь выделенную память. Вызывающий код отвечает за вызов PyMem_Free для освобождения выделенного буфера после использования.

et (строка, объект Unicode или объект, совместимый с символьным буфером) [const char *encoding, char **buffer]

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

es# (строка, объект Unicode или объект, совместимый с символьным буфером) [const char *encoding, char **buffer, int *buffer_length]

Этот вариант s# используется для кодирования Unicode и объектов, преобразуемых в Unicode, в символьный буфер. В отличие от формата es, этот вариант допускает входные данные, содержащие NUL-символы.

Он требует три аргумента. Первый используется только для ввода и должен быть const char*, указывающим на имя кодировки в виде строки, завершающейся NUL, или NULL; в последнем случае используется кодировка по умолчанию. Если именованная кодировка неизвестна Python, возбуждается исключение. Второй аргумент должен быть char**; значение указателя, на который он ссылается, будет установлено на буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, указанной первым аргументом. Третий аргумент должен быть указателем на целое число; целое число, на которое он ссылается, будет установлено на количество байт в выходном буфере.

Существует два режима работы:

Если *buffer указывает на указатель NULL, функция выделит буфер нужного размера, скопирует закодированные данные в этот буфер и установит *buffer ссылкой на вновь выделенную память. Вызывающий отвечает за вызов PyMem_Free для освобождения выделенного буфера после использования.

If *buffer points to a non-NULL pointer (an already allocated buffer), PyArg_ParseTuple will use this location as the buffer and interpret the initial value of *buffer_length as the buffer size. It will then copy the encoded data into the buffer and NUL-terminate it. If the buffer is not large enough, a ValueError will be set.

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

et# (строка, объект Unicode или объект, совместимый с символьным буфером) [const char *encoding, char **buffer]

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

b (целое число) [unsigned char]

Преобразует неотрицательное целое число Python в беззнаковое крошечное целое, хранящееся в C unsigned char.

B (целое число) [unsigned char]

Преобразует целое число Python в крошечное целое без проверки переполнения, хранящееся в C unsigned char.

h (целое число) [short int]

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

H (целое число) [unsigned short int]

Преобразует целое число Python в C unsigned short int без проверки переполнения.

i (целое число) [int]

Преобразует целое число Python в обычный C int.

I (целое число) [unsigned int]

Преобразует целое число Python в C unsigned int без проверки переполнения.

l (целое число) [long int]

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

k (целое число) [unsigned long]

Преобразует целое число Python в C unsigned long без проверки переполнения.

L (целое число) [PY_LONG_LONG]

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

K (целое число) [unsigned PY_LONG_LONG]

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

n (целое число) [Py_ssize_t]

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

c (строка длиной 1) [char]

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

f (число с плавающей запятой) [float]

Преобразует число с плавающей запятой Python в C float.

d (число с плавающей запятой) [double]

Преобразует число с плавающей запятой Python в C double.

D (комплексное число) [Py_complex]

Преобразует комплексное число Python в структуру C Py_complex.

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

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

O! (объект) [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 без изменений.

S (строка) [PyStringObject *]

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

U (строка Unicode) [PyUnicodeObject *]

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

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

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

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

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

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

Это то же самое по отношению к w, что s* к s.

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

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

(items) (кортеж) [matching-items]

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

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

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

|

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

:

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

;

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

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

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

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

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)

PyObject* Py_BuildValue(const char *format, ...)¶

Возвращаемое значение: новая ссылка.

Создаёт новое значение на основе форматной строки, аналогичной тем, что принимает семейство функций PyArg_Parse*, и последовательности значений. Возвращает значение или NULL в случае ошибки; при возврате NULL возбуждается исключение.

Py_BuildValue не всегда строит кортеж. Он строит кортеж, только если его форматная строка содержит две или более форматных единицы. Если форматная строка пуста, возвращается None; если она содержит ровно одну форматную единицу, возвращается объект, описываемый этой единицей. Чтобы принудительно вернуть кортеж размера 0 или 1, форматную строку нужно заключить в скобки.

Когда буферы памяти передаются в качестве параметров для предоставления данных при создании объектов (как для форматов s и s#), необходимые данные копируются. Буферы, предоставленные вызывающим кодом, никогда не используются напрямую объектами, созданными Py_BuildValue. Другими словами, если код вызывает malloc и передаёт выделенную память в Py_BuildValue, то он же отвечает за вызов free для этой памяти после возврата из Py_BuildValue.

В следующем описании форма в кавычках – это элемент формата; запись в круглых скобках – это тип объекта Python, который вернёт элемент формата; а запись в квадратных скобках – это тип передаваемого(-ых) значения(-ий) C.

Символы пробела, табуляции, двоеточия и запятой игнорируются в строках формата (но не внутри единиц формата, таких как s#). Это позволяет сделать длинные строки формата немного более читаемыми.

s (строка) [char *]

Преобразует C-строку, завершающуюся нулевым символом, в объект Python. Если указатель на C-строку равен NULL, используется None.

s# (строка) [char *, int]

Преобразует C-строку и её длину в объект Python. Если указатель на C-строку равен NULL, длина игнорируется и возвращается None.

y (байты) [char *]

Эта функция преобразует C строку в объект Python bytes(). Если указатель на C строку равен NULL, возвращается None.

y# (байты) [char *, int]

Преобразует C-строку и её длину в объект Python. Если указатель на C-строку равен NULL, возвращается None.

z (строка или None) [char *]

То же, что и s.

z# (строка или None) [char *, int]

То же, что и s#.

u (строка Unicode) [Py_UNICODE *]

Преобразует буфер с нулевым символом в конце, содержащий данные Unicode (UCS-2 или UCS-4), в объект Unicode Python. Если указатель буфера Unicode равен NULL, возвращается None.

u# (строка Unicode) [Py_UNICODE *, int]

Преобразует буфер данных Unicode (UCS-2 или UCS-4) и его длину в объект Unicode Python. Если указатель буфера Unicode равен NULL, длина игнорируется и возвращается None.

U (строка) [char *]

Преобразует C-строку, завершающуюся нулевым символом, в объект Python unicode. Если указатель на C-строку равен NULL, используется None.

U# (строка) [char *, int]

Преобразует C-строку и её длину в объект Python unicode. Если указатель на C-строку равен NULL, длина игнорируется и возвращается None.

i (целое) [int]

Преобразует обычный C int в объект Python целого типа.

b (целое) [char]

Преобразует обычный C char в объект Python целого типа.

h (целое) [short int]

Преобразует обычное C short int в объект Python int.

l (целое) [long int]

Преобразует C long int в объект Python int.

B (целое) [unsigned char]

Преобразует C unsigned char в объект Python int.

H (целое) [unsigned short int]

Преобразует C unsigned short int в объект Python int.

I (целое) [unsigned int]

Преобразует C unsigned int в объект Python int.

k (целое) [unsigned long]

Преобразует C unsigned long в объект Python int.

L (длинное) [PY_LONG_LONG]

Преобразует C long long в объект целого числа Python. Доступно только на платформах, поддерживающих long long.

K (длинное) [unsigned PY_LONG_LONG]

Преобразует C unsigned long long в объект целого числа Python. Доступно только на платформах, поддерживающих unsigned long long.

n (целое) [Py_ssize_t]

Преобразует C Py_ssize_t в Python int.

c (строка длины 1) [char]

Преобразует C int, представляющий символ, в строку Python длины 1.

d (вещественное) [double]

Преобразует C double в число с плавающей точкой Python.

f (вещественное) [float]

То же, что и d.

D (комплексное) [Py_complex *]

Преобразует структуру C Py_complex в комплексное число Python.

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

Передаёт объект Python без изменений (за исключением счётчика ссылок, который увеличивается на единицу). Если переданный объект – указатель NULL, считается, что вызов, формирующий аргумент, обнаружил ошибку и установил исключение. Следовательно, Py_BuildValue вернёт NULL, но не возбудит исключение. Если исключение ещё не было возбуждено, устанавливается SystemError.

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

То же, что и O.

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

То же, что и O, за исключением того, что не увеличивает счётчик ссылок на объект. Полезно, когда объект создаётся вызовом конструктора объекта в списке аргументов.

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

Преобразует anything в объект Python с помощью функции converter. Функция вызывается с аргументом anything (который должен быть совместим с void *) и должна возвращать «новый» объект Python или NULL в случае ошибки.

(items) (кортеж) [matching-items]

Преобразует последовательность значений C в кортеж Python с тем же количеством элементов.

[items] (список) [matching-items]

Преобразует последовательность значений C в список Python с тем же количеством элементов.

{items} (словарь) [matching-items]

Преобразует последовательность значений C в словарь Python. Каждая пара последовательных значений C добавляет один элемент в словарь, выступая в роли ключа и значения соответственно.

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

PyObject* Py_VaBuildValue(const char *format, va_list vargs)¶

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