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

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

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

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

Эти форматы позволяют обращаться к объекту как к непрерывному блоку памяти. Не нужно предоставлять сырую память для возвращаемой области Unicode или bytes. Также не нужно самостоятельно освобождать память, за исключением форматов es, es#, et и et#.

s (строка или Unicode) [const char *]

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

s# (строка, Unicode или любой объект, совместимый с read buffer) [const char *, int (или Py_ssize_t, см. ниже)]

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

Начиная с 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# (строка, Unicode, None или любой объект, совместимый с read buffer) [const char *, int]

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

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

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

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

u (Unicode) [Py_UNICODE *]

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

u# (Unicode) [Py_UNICODE *, int]

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

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

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

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

Если *buffer указывает на не-NULL указатель (уже выделенный буфер), PyArg_ParseTuple() будет использовать это место как буфер и интерпретировать начальное значение *buffer_length как размер буфера. Затем он скопирует закодированные данные в буфер и добавит завершающий NUL. Если буфер недостаточно велик, будет установлен TypeError. Примечание: начиная с Python 3.6 будет установлен 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 в tiny int без проверки переполнения, сохраняет в 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& (object) [конвертер, что угодно]

Преобразует объект 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) (кортеж) [соответствующие элементы]

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

Примечание

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

Можно передавать длинные целые Python там, где требуются целые; однако должная проверка диапазона не выполняется – старшие биты бесшумно отбрасываются, если принимающее поле слишком мало для значения (на самом деле семантика унаследована от понижающих приведений в 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)

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

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

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

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

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

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

Когда буферы памяти передаются как параметры для предоставления данных для построения объектов, как в форматах 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.

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.

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 (целое/long) [unsigned int]

Преобразует значение C unsigned int в объект Python integer или Python long integer, если оно больше sys.maxint.

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

Преобразует значение C unsigned long в объект Python integer или Python long integer, если оно больше sys.maxint.

L (long) [PY_LONG_LONG]

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

K (long) [unsigned PY_LONG_LONG]

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

n (int) [Py_ssize_t]

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

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

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

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

d (float) [double]

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

f (float) [float]

То же, что и d.

D (complex) [Py_complex *]

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

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

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

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

То же, что и O.

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

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

O& (object) [конвертер, что угодно]

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

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

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

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

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

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

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

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

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

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