Анализ аргументов и построение значений¶

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

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

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

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

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

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

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

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

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

s (str) [ постоянный символ *]

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

Примечание

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

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

s* (str или bytes-like object) [Py_buffer]

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

s# (str, доступен только для чтения bytes-like object) [постоянный символ *, Py_ssize_t]

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

z (str или None) [постоянный символ *]

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

z* (str, bytes-like object или None) [Py_buffer]

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

z# (str, доступен только для чтения bytes-like object или None) [постоянный символ *, Py_ssize_t]

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

y (доступно только для чтения bytes-like object) [постоянный символ *]

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

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

y* (bytes-like object) [ Py_buffer]

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

y# (только для чтения bytes-like object) [постоянный символ *, Py_ssize_t]

Этот вариант для s# не поддерживает объекты в Юникоде, только объекты, подобные байтам.

S (bytes) [ PyBytesObject *]

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

Y (bytearray) [ PyByteArrayObject *]

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

u (str) [ константа Py_UNICODE *]

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

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

Утратил актуальность с версии 3.3, будет удален в версии 3.12: Часть старого интерфейса Py_UNICODE Пожалуйста, перейдите на использование PyUnicode_AsWideCharString().

u# (str) [ константа Py_UNICODE *, Py_ssize_t]

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

Утратил актуальность с версии 3.3, будет удален в версии 3.12: Часть старого интерфейса Py_UNICODE Пожалуйста, перейдите на использование PyUnicode_AsWideCharString().

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

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

Утратил актуальность с версии 3.3, будет удален в версии 3.12: Часть старого интерфейса Py_UNICODE Пожалуйста, перейдите на использование PyUnicode_AsWideCharString().

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

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

Утратил актуальность с версии 3.3, будет удален в версии 3.12: Часть старого интерфейса Py_UNICODE Пожалуйста, перейдите на использование PyUnicode_AsWideCharString().

U (str) [ PyObject *]

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

w* (чтение-запись bytes-like object) [Py_buffer]

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

es (str) [ const char *кодировка, char **буфер]

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

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

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

et (str, bytes или bytearray) [const char *кодировка, char **буфер]

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

es# (str) [ постоянный символ *кодировка, символ **буфер, Py_ssize_t *длина буфера]

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

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

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

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

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

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

et# (str, bytes или bytearray) [постоянный символ *кодировка, символ **буфер, Py_ssize_t *длина буфера]

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

Числа¶

b (int) [ неподписанный символ]

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

B (int) [ неподписанный символ]

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

h (int) [ короткий int]

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

H (int) [ беззнаковое короткое значение int]

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

i (int) [ инт]

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

I (int) [ неподписанный int]

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

l (int) [ длинный int]

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

k (int) [ длинный без знака]

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

L (int) [ долго, долго]

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

K (int) [ неподписанный длинный длинный]

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

n (int) [: c:type:Py_ssize_t]

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

c (bytes или bytearray длины 1) [символ]

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

Изменено в версии 3.3: Разрешить bytearray объектов.

C (str длины 1) [int]

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

f (float) [ плавать]

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

d (float) [ двойной]

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

D (complex) [ Py_complex]

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

Другие объекты¶

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

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

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

Храните объект Python в указателе на объект C. Это аналогично O, но принимает два аргумента C: первый - это адрес объекта типа Python, второй - адрес переменной C (типа : c:expr:PyObject*), в которой хранится указатель на объект. Если объект Python не имеет требуемого типа, вызывается TypeError.

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

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

status = converter(object, address);

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

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

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

p (bool) [ инт]

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

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

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

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

Можно передавать «длинные» целые числа (целые числа, значение которых превышает значение платформы 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¶

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

Part of the Стабильный ABI.

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

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

Part of the Стабильный ABI.

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

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

Part of the Стабильный ABI.

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

Изменено в версии 3.6: Добавлена поддержка positional-only parameters.

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

Part of the Стабильный ABI.

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

int PyArg_ValidateKeywordArguments(PyObject*)¶

Part of the Стабильный ABI.

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

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

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

Part of the Стабильный ABI.

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

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

Part of the Стабильный ABI.

Более простая форма поиска параметров, которая не использует строку формата для указания типов аргументов. Функции, которые используют этот метод для получения своих параметров, должны быть объявлены как METH_VARARGS в таблицах функций или методов. Кортеж, содержащий фактические параметры, должен быть передан как args; на самом деле это должен быть кортеж. Длина кортежа должна быть не менее min и не более max; min и max могут быть равны. Функции должны быть переданы дополнительные аргументы, каждый из которых должен быть указателем на переменную PyObject*; они будут заполнены значениями из args; они будут содержать borrowed references. Переменные, которые соответствуют необязательным параметрам, не указанным в 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)