Документация Python неофициальный перевод

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

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

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

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

s (строка или Unicode) [const char *]
Преобразует объект Python строки или Unicode в указатель C на символьную строку. Не нужно предоставлять хранилище для самой строки; указатель на существующую строку сохраняется в переменную-указатель на символ, адрес которой передаётся. Строка C завершается нулевым символом (NUL). Строка Python не должна содержать встроенных нулевых байтов; если они есть, возбуждается исключение TypeError. Объекты Unicode преобразуются в строки C с использованием кодировки по умолчанию. Если такое преобразование не удаётся, возбуждается UnicodeError.
s# (строка, Unicode или любой объект, совместимый с буфером чтения) [const char *, int (или Py_ssize_t, см. ниже)]

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

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

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

Подобно s#, этот код заполняет структуру Py_buffer, предоставленную вызывающей стороной. Буфер блокируется, так что вызывающая сторона может затем использовать буфер даже внутри блока Py_BEGIN_ALLOW_THREADS; вызывающая сторона обязана вызвать PyBuffer_Release с этой структурой после обработки данных.

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

z (строка, Unicode или None) [const char *]
Аналогично s, но объект Python также может быть None, и в этом случае указатель C устанавливается в NULL.
z# (string, Unicode, None or any read buffer compatible object) [const char *, int]
Это относится к s# так же, как z относится к s.
z* (строка, Unicode, None или любой объект, совместимый с буфером) [Py_buffer]

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

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

u (Unicode) [Py_UNICODE *]
Преобразует объект Python Unicode в указатель C на буфер 16-битных данных Unicode (UTF-16), завершающийся нулевым символом. Как и в случае с s, нет необходимости предоставлять хранилище для буфера данных Unicode; указатель на существующие данные Unicode сохраняется в переменную-указатель Py_UNICODE, адрес которой передаётся.
u# (Unicode) [Py_UNICODE *, int]
Этот вариант u сохраняет в две переменные C: первая – указатель на буфер данных Unicode, вторая – его длина. Не-Unicode объекты обрабатываются путём интерпретации их указателя буфера чтения как указателя на массив Py_UNICODE.
es (строка, Unicode или объект, совместимый с символьным буфером) [const char *encoding, char **buffer]

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

Этот формат требует два аргумента. Первый используется только как входной и должен быть 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*, указывающим на имя кодировки в виде строки, завершающейся нулевым символом, или NULL, в этом случае используется кодировка по умолчанию. Возбуждается исключение, если именованная кодировка не известна Python. Второй аргумент должен быть char**; значение указателя, на который он ссылается, будет установлено на буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, указанной первым аргументом. Третий аргумент должен быть указателем на целое число; на которое ссылается, будет установлено количество байт в выходном буфере.

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

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

Если *buffer указывает на не-NULL указатель (уже выделенный буфер), PyArg_ParseTuple() будет использовать это место как буфер и интерпретировать начальное значение *buffer_length как размер буфера. Затем он скопирует закодированные данные в буфер и завершит его нулевым символом. Если буфер недостаточно велик, будет установлено ValueError.

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

et# (строка, Unicode или объект, совместимый с символьным буфером) [const char *encoding, char **buffer, int *buffer_length]
То же, что es#, за исключением того, что строковые объекты передаются без перекодирования. Вместо этого реализация предполагает, что строковый объект использует кодировку, переданную в качестве параметра.
b (целое число) [unsigned char]
Преобразует неотрицательное целое число Python в беззнаковое крошечное целое, хранящееся в C unsigned char.
B (целое) [unsigned char]

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

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

h (целое) [short int]
Преобразует целое число Python в C short int.
H (целое) [unsigned short int]

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

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

i (целое) [int]
Преобразует целое число Python в обычный C int.
I (целое) [unsigned int]

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

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

l (целое) [long int]
Преобразует целое число Python в C long int.
k (целое) [unsigned long]

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

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

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

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

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

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

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

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

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# (буфер символов для чтения-записи) [char *, Py_ssize_t]
Аналогично s#, но принимает любой объект, реализующий интерфейс буфера чтения-записи. Переменная char * устанавливается на первый байт буфера, а Py_ssize_t – на длину буфера. Принимаются только односегментные буферные объекты; для всех остальных вызывается TypeError.
w* (байт-ориентированный буфер для чтения-записи) [Py_buffer]

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

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

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

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

Примечание

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

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

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

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

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

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

Для успешного преобразования объект arg должен соответствовать формату, а формат должен быть полностью исчерпан. При успехе функции PyArg_Parse*() возвращают истину, иначе – ложь и возбуждают соответствующее исключение. Когда функции 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)

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

Изменено в версии 2.5: Раньше эта функция использовала тип int для min и max. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

PyObject* Py_BuildValue(const char *format, ...)
Возвращаемое значение: новая ссылка.

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

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

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

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

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

s (строка) [char *]
Преобразует C-строку, завершающуюся нулевым символом, в объект Python. Если указатель на C-строку равен NULL, используется None.
s# (строка) [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), завершающийся нулевым символом, в объект Python Unicode. Если указатель на буфер Unicode равен NULL, возвращается None.
u# (строка Unicode) [Py_UNICODE *, int]
Преобразует буфер данных Unicode (UCS-2 или UCS-4) и его длину в объект Python Unicode. Если указатель на буфер Unicode равен 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 (integer/long) [unsigned int]
Преобразует C unsigned int в объект Python integer или в объект Python long integer, если значение больше sys.maxint.
k (integer/long) [unsigned long]
Преобразует C unsigned long в объект Python integer или в объект Python long integer, если значение больше sys.maxint.
L (длинное) [PY_LONG_LONG]
Преобразует C long long в объект Python long integer. Доступно только на платформах, поддерживающих long long.
K (длинное) [unsigned PY_LONG_LONG]
Преобразует C unsigned long long в объект Python long integer. Доступно только на платформах, поддерживающих unsigned long long.
n (целое) [Py_ssize_t]

Преобразует C Py_ssize_t в объект Python integer или long integer.

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

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 вместо переменного числа аргументов.