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

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

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

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

Существует три способа преобразования строк и буферов в C:

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

• Форматы es, es#, et и et# выделяют буфер для результата. Необходимо вызывать PyMem_Free() после завершения обработки данных (или в случае досрочного прерывания).

• Другие форматы принимают str или байтоподобный объект только для чтения, такой как bytes, и предоставляют указатель const char * на его буфер. В этом случае буфер является «заимствованным»: он управляется соответствующим объектом Python и разделяет время жизни этого объекта. Самостоятельно освобождать память не потребуется.

  Чтобы гарантировать возможность безопасного заимствования базового буфера, поле PyBufferProcs.bf_releasebuffer объекта должно быть NULL. Это исключает обычные изменяемые объекты, такие как bytearray, но также и некоторые объекты только для чтения, такие как memoryview из bytes.

  Кроме этого требования bf_releasebuffer, не существует проверки на то, является ли входной объект неизменяемым (например, будет ли он выполнять запрос на буфер для записи или сможет ли другой поток изменить данные).

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

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

et (str, bytes или bytearray) [const char *encoding, char **buffer]

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

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

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

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

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

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

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

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

et# (str, bytes или bytearray) [const char *encoding, char **buffer, Py_ssize_t *buffer_length]

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

Числа¶Numbers

Эти форматы позволяют представлять числа Python или одиночные символы как числа C. Форматы, требующие int, float или complex, также могут использовать соответствующие специальные методы __index__(), __float__() или __complex__() для преобразования объекта Python в требуемый тип.

Для форматов целых чисел со знаком OverflowError возбуждается, если значение выходит за пределы диапазона для типа C. Для беззнаковых форматов проверка диапазона не выполняется – старшие биты молча отбрасываются, когда принимающее поле слишком мало для значения.

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) [конвертер, address]

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

status = converter(object, address);

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

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

Примеры преобразователей: PyUnicode_FSConverter() и PyUnicode_FSDecoder().

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

p (bool) [int]

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

Добавлено в версии 3.3.

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

Объект должен быть последовательностью Python, длина которой равна количеству единиц формата в элементах. Аргументы 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, ...)¶

Часть Stable ABI.

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

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

Часть Stable ABI.

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

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

Часть Stable ABI.

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

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

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

Часть Stable ABI.

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

int PyArg_ValidateKeywordArguments(PyObject*)¶

Часть Stable ABI.

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

Добавлено в версии 3.2.

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

Часть Stable ABI.

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

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

Часть Stable ABI.

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