Розбір аргументів і створення значень¶

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

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

Розбір аргументів¶

Рядок формату складається з нуля або більше «одиниць формату». Одиниця формату описує один об’єкт Python; зазвичай це один символ або послідовність одиниць формату в дужках. За кількома винятками, одиниця формату, яка не є послідовністю в дужках, зазвичай відповідає одному аргументу адреси для цих функцій. У наступному описі форма в лапках є одиницею формату; запис у (круглих) дужках — це тип об’єкта Python, який відповідає одиниці формату; а запис у [квадратних] дужках — це тип змінної (змінних) C, адреса якої має бути передана.

Рядки та буфери¶

Ці формати дозволяють отримати доступ до об’єкта як до безперервної частини пам’яті. Вам не потрібно надавати необроблене сховище для поверненої області Юнікоду або байтів.

Якщо не зазначено інше, буфери не завершуються NUL.

Є три способи конвертування рядків і буферів для використання в C:

Такі формати, як y* і s*, заповнюють структуру Py_buffer. Це блокує буфер, що лежить в основі, щоб функція, що викликала, могла згодом використовувати буфер навіть всередині блоку Py_BEGIN_ALLOW_THREADS без ризику, що мутабельні дані будуть змінені або знищені. В результаті, ви маєте викликати PyBuffer_Release() після того, як ви закінчите обробку даних (або в будь-якому випадку дострокового переривання).
The es, es#, et and et# formats allocate the result buffer. You have to call PyMem_Free() after you have finished processing the data (or in any early abort case).
Other formats take a str or a read-only bytes-like object, such as bytes, and provide a const char * pointer to its buffer. In this case the buffer is «borrowed»: it is managed by the corresponding Python object, and shares the lifetime of this object. You won’t have to release any memory yourself.

To ensure that the underlying buffer may be safely borrowed, the object’s PyBufferProcs.bf_releasebuffer field must be NULL. This disallows common mutable objects such as bytearray, but also some read-only objects such as memoryview of bytes.

Besides this bf_releasebuffer requirement, there is no check to verify whether the input object is immutable (e.g. whether it would honor a request for a writable buffer, or whether another thread can mutate the data).

Примітка

For all # variants of formats (s#, y#, etc.), the macro PY_SSIZE_T_CLEAN must be defined before including Python.h. On Python 3.9 and older, the type of the length argument is Py_ssize_t if the PY_SSIZE_T_CLEAN macro is defined, or int otherwise.

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 або bytes-like object) [Py_buffer]

Цей формат приймає як об’єкти Unicode, так і байтоподібні об’єкти. Він заповнює структуру Py_buffer, надану абонентом. У цьому випадку результуючий рядок C може містити вбудовані байти NUL. Об’єкти Unicode перетворюються на рядки C за допомогою кодування 'utf-8.

s# (str, лише для читання bytes-like object) [const char *, Py_ssize_t]

Like s*, except that it provides a borrowed buffer. The result is stored into two C variables, the first one a pointer to a C string, the second one its length. The string may contain embedded null bytes. Unicode objects are converted to C strings using 'utf-8' encoding.

z (str або None) [const char *]

Подібно до 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) [const char *, Py_ssize_t]

Подібно до s#, але об’єкт Python також може мати значення None, у цьому випадку вказівник на C встановлюється як NULL.

y (тільки для читання bytes-like object) [const char *]

This format converts a bytes-like object to a C pointer to a borrowed character string; it does not accept Unicode objects. The bytes buffer must not contain embedded null bytes; if it does, a ValueError exception is raised.

Змінено в версії 3.5: Раніше помилка TypeError виникала, коли в буфері байтів зустрічалися вбудовані нульові байти.

y* (bytes-like object) [Py_buffer]

Цей варіант s* не приймає об’єкти Unicode, лише байтоподібні об’єкти. Це рекомендований спосіб приймати двійкові дані.

y# (тільки для читання bytes-like object) [const char *, Py_ssize_t]

Цей варіант s# не приймає об’єкти Unicode, лише байтоподібні об’єкти.

S (bytes) [PyBytesObject *]

Requires that the Python object is a bytes object, without attempting any conversion. Raises TypeError if the object is not a bytes object. The C variable may also be declared as PyObject*.

Y (bytearray) [PyByteArrayObject *]

Requires that the Python object is a bytearray object, without attempting any conversion. Raises TypeError if the object is not a bytearray object. The C variable may also be declared as PyObject*.

U (str) [PyObject *]

Requires that the Python object is a Unicode object, without attempting any conversion. Raises TypeError if the object is not a Unicode object. The C variable may also be declared as PyObject*.

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

Цей формат приймає будь-який об’єкт, який реалізує інтерфейс буфера читання-запису. Він заповнює структуру Py_buffer, надану абонентом. Буфер може містити вбудовані нульові байти. Виклик має викликати PyBuffer_Release(), коли це буде зроблено з буфером.

es (str) [const char *кодування, char **buffer]

Цей варіант на s використовується для кодування Юнікоду в символьний буфер. Він працює лише для закодованих даних без вбудованих байтів NUL.

This format requires two arguments. The first is only used as input, and must be a const char* which points to the name of an encoding as a NUL-terminated string, or NULL, in which case 'utf-8' encoding is used. An exception is raised if the named encoding is not known to Python. The second argument must be a char**; the value of the pointer it references will be set to a buffer with the contents of the argument text. The text will be encoded in the encoding specified by the first argument.

PyArg_ParseTuple() виділить буфер необхідного розміру, скопіює закодовані дані в цей буфер і налаштує *buffer для посилання на щойно виділене сховище. Виклик відповідає за виклик PyMem_Free(), щоб звільнити виділений буфер після використання.

et (str, bytes або bytearray) [const char *кодування, char **buffer]

Те саме, що es, за винятком того, що об’єкти рядків байтів передаються без їх перекодування. Натомість реалізація припускає, що об’єкт рядка байтів використовує кодування, передане як параметр.

es# (str) [const char *кодування, char **буфер, Py_ssize_t *buffer_length]

Цей варіант s# використовується для кодування Юнікоду в символьний буфер. На відміну від формату es, цей варіант дозволяє вводити дані, які містять символи NUL.

It requires three arguments. The first is only used as input, and must be a const char* which points to the name of an encoding as a NUL-terminated string, or NULL, in which case 'utf-8' encoding is used. An exception is raised if the named encoding is not known to Python. The second argument must be a char**; the value of the pointer it references will be set to a buffer with the contents of the argument text. The text will be encoded in the encoding specified by the first argument. The third argument must be a pointer to an integer; the referenced integer will be set to the number of bytes in the output buffer.

Є два режими роботи:

Якщо *buffer вказує на вказівник NULL, функція виділить буфер необхідного розміру, скопіює закодовані дані в цей буфер і встановить *buffer для посилання на щойно виділене сховище. Виклик відповідає за виклик PyMem_Free(), щоб звільнити виділений буфер після використання.

Якщо *buffer вказує на вказівник, відмінний від NULL (уже виділений буфер), PyArg_ParseTuple() використовуватиме це розташування як буфер та інтерпретуватиме початкове значення *buffer_length як розмір буфера. Потім він скопіює закодовані дані в буфер і завершить його NUL. Якщо буфер недостатньо великий, буде встановлено ValueError.

В обох випадках *buffer_length встановлюється на довжину закодованих даних без кінцевого байта NUL.

et# (str, bytes або bytearray) [const char *кодування, char **buffer, Py_ssize_t *buffer_length]

Те саме, що es#, за винятком того, що байтові рядкові об’єкти передаються без їх перекодування. Натомість реалізація припускає, що об’єкт рядка байтів використовує кодування, передане як параметр.

Змінено в версії 3.12: u, u#, Z, and Z# are removed because they used a legacy Py_UNICODE* representation.

Числа¶

b (int) [беззнаковий символ]: Перетворює невід’ємне ціле число Python на unsigned tiny int, що зберігається в C unsigned char.
B (int) [беззнаковий символ]: Перетворює ціле число Python на tiny int без перевірки переповнення, що зберігається в C unsigned char.
h (int) [короткий int]: Перетворює ціле число Python на C short int.
H (int) [unsigned short int]: Перетворює ціле число Python на C unsigned short int без перевірки переповнення.
i (int) [int]: Convert a Python integer to a plain C int.
I (int) [unsigned int]: Convert a Python integer to a C unsigned int, without overflow checking.
l (int) [довге ціле]: Convert a Python integer to a C long int.
k (int) [беззнаковий довгий]: Convert a Python integer to a C unsigned long without overflow checking.
L (int) [довгий довгий]: Convert a Python integer to a C long long.
K (int) [беззнаковий довгий довгий]: Convert a Python integer to a C unsigned long long without overflow checking.
n (int) [Py_ssize_t]: Перетворіть ціле число Python на C Py_ssize_t.
c (bytes або bytearray довжиною 1) [char]: Convert a Python byte, represented as a bytes or bytearray object of length 1, to a C char.

Змінено в версії 3.3: Дозволити об’єкти bytearray.
C (str довжини 1) [int]: Convert a Python character, represented as a str object of length 1, to a C int.
f (float) [float]: Convert a Python floating-point number to a C float.
d (float) [double]: Convert a Python floating-point number to a C double.
D (complex) [Py_complex]: Перетворіть комплексне число Python на структуру C Py_complex.

Інші об’єкти¶

O (об’єкт) [PyObject *]: Store a Python object (without any conversion) in a C object pointer. The C program thus receives the actual object that was passed. A new strong reference to the object is not created (i.e. its reference count is not increased). The pointer stored is not NULL.
O! (об’єкт) [typeobject, PyObject *]: Store a Python object in a C object pointer. This is similar to O, but takes two C arguments: the first is the address of a Python type object, the second is the address of the C variable (of type PyObject*) into which the object pointer is stored. If the Python object does not have the required type, TypeError is raised.

O& (об’єкт) [конвертер, що завгодно]

Convert a Python object to a C variable through a converter function. This takes two arguments: the first is a function, the second is the address of a C variable (of arbitrary type), converted to void*. The converter function in turn is called as follows:

status = converter(object, address);

where object is the Python object to be converted and address is the void* argument that was passed to the PyArg_Parse* function. The returned status should be 1 for a successful conversion and 0 if the conversion has failed. When the conversion fails, the converter function should raise an exception and leave the content of address unmodified.

Якщо конвертер повертає Py_CLEANUP_SUPPORTED, він може бути викликаний вдруге, якщо синтаксичний аналіз аргументу врешті-решт не вдається, даючи конвертеру можливість звільнити будь-яку пам’ять, яку він уже виділив. У цьому другому виклику параметр object буде NULL; адреса матиме те саме значення, що й у вихідному виклику.

Змінено в версії 3.1: Додано Py_CLEANUP_SUPPORTED.

p (bool) [int]

Перевіряє передане значення на істинність (логічне значення pповторне визначення) і перетворює результат на еквівалентне ціле значення C true/false. Встановлює int на 1, якщо вираз був істинним, і 0, якщо він був false. Це приймає будь-яке дійсне значення Python. Перегляньте Перевірка значення на істинність для отримання додаткової інформації про те, як Python перевіряє значення на істинність.

Added in version 3.3.

(items) (tuple) [matching-items]

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

It is possible to pass «long» integers (integers whose value exceeds the platform’s LONG_MAX) however no proper range checking is done — the most significant bits are silently truncated when the receiving field is too small to receive the value (actually, the semantics are inherited from downcasts in C — your mileage may vary).

Кілька інших символів мають значення в рядку формату. Вони можуть не знаходитися всередині вкладених дужок. Вони є:

|: Вказує, що решта аргументів у списку аргументів Python необов’язкові. Змінні C, які відповідають необов’язковим аргументам, мають бути ініціалізовані значенням за замовчуванням — коли необов’язковий аргумент не вказано, PyArg_ParseTuple() не торкається вмісту відповідних змінних C.
$: PyArg_ParseTupleAndKeywords() only: вказує, що решта аргументів у списку аргументів Python є лише ключовими словами. Наразі всі аргументи лише для ключових слів також мають бути необов’язковими, тому | завжди потрібно вказувати перед $ у рядку формату.

Added in version 3.3.
:: Тут список одиниць формату закінчується; рядок після двокрапки використовується як ім’я функції в повідомленнях про помилки («пов’язане значення» винятку, яке викликає PyArg_ParseTuple()).
;: Тут список одиниць формату закінчується; рядок після крапки з комою використовується як повідомлення про помилку замість повідомлення про помилку за замовчуванням. : і ; взаємно виключають один одного.

Note that any Python object references which are provided to the caller are borrowed references; do not release them (i.e. do not decrement their reference count)!

Додатковими аргументами, що передаються цим функціям, повинні бути адреси змінних, тип яких визначається рядком формату; вони використовуються для зберігання значень із вхідного кортежу. Є кілька випадків, як описано у списку одиниць формату вище, де ці параметри використовуються як вхідні значення; вони повинні відповідати тому, що вказано для відповідної одиниці формату в цьому випадку.

For the conversion to succeed, the arg object must match the format and the format must be exhausted. On success, the PyArg_Parse* functions return true, otherwise they return false and raise an appropriate exception. When the PyArg_Parse* functions fail due to conversion failure in one of the format units, the variables at the addresses corresponding to that and the following format units are left untouched.

Функції API¶

int PyArg_ParseTuple(PyObject *args, const char *format, ...)¶: Part of the Stable ABI.
Проаналізуйте параметри функції, яка приймає лише позиційні параметри в локальні змінні. Повертає true в разі успіху; у разі невдачі повертає false і викликає відповідний виняток.

int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)¶: Part of the Stable ABI.
Ідентичний PyArg_ParseTuple(), за винятком того, що він приймає va_list, а не змінну кількість аргументів.

int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)¶: Part of the Stable ABI.
Parse the parameters of a function that takes both positional and keyword parameters into local variables. The keywords argument is a NULL-terminated array of keyword parameter names. Empty names denote positional-only parameters. Returns true on success; on failure, it returns false and raises the appropriate exception.

Змінено в версії 3.6: Додано підтримку позиційних параметрів.

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)¶: Part of the Stable ABI.
Ідентичний PyArg_ParseTupleAndKeywords(), за винятком того, що він приймає va_list, а не змінну кількість аргументів.

int PyArg_ValidateKeywordArguments(PyObject*)¶: Part of the Stable ABI.
Переконайтеся, що ключі в словнику аргументів ключових слів є рядками. Це потрібно, лише якщо PyArg_ParseTupleAndKeywords() не використовується, оскільки останній вже виконує цю перевірку.

Added in version 3.2.

int PyArg_Parse(PyObject *args, const char *format, ...)¶: Part of the Stable ABI.
Function used to deconstruct the argument lists of «old-style» functions — these are functions which use the METH_OLDARGS parameter parsing method, which has been removed in Python 3. This is not recommended for use in parameter parsing in new code, and most code in the standard interpreter has been modified to no longer use this for that purpose. It does remain a convenient way to decompose other tuples, however, and may continue to be used for that purpose.

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

Part of the Stable ABI.

A simpler form of parameter retrieval which does not use a format string to specify the types of the arguments. Functions which use this method to retrieve their parameters should be declared as METH_VARARGS in function or method tables. The tuple containing the actual parameters should be passed as args; it must actually be a tuple. The length of the tuple must be at least min and no more than max; min and max may be equal. Additional arguments must be passed to the function, each of which should be a pointer to a PyObject* variable; these will be filled in with the values from args; they will contain borrowed references. The variables which correspond to optional parameters not given by args will not be filled in; these should be initialized by the caller. This function returns true on success and false if args is not a tuple or contains the wrong number of elements; an exception will be set if there was a failure.

This is an example of the use of this function, taken from the sources for the _weakref helper module for weak references:

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, ...)¶

Return value: New reference. Part of the Stable ABI.

Create a new value based on a format string similar to those accepted by the PyArg_Parse* family of functions and a sequence of values. Returns the value or NULL in the case of an error; an exception will be raised if NULL is returned.

Py_BuildValue() не завжди створює кортеж. Він створює кортеж, лише якщо його рядок формату містить дві або більше одиниць формату. Якщо рядок формату порожній, повертається None; якщо він містить рівно одну одиницю формату, він повертає будь-який об’єкт, описаний цією одиницею формату. Щоб змусити його повертати кортеж розміром 0 або одиницю, візьміть рядок формату в дужки.

Коли буфери пам’яті передаються як параметри для надання даних для створення об’єктів, як і для форматів s і s#, необхідні дані копіюються. Об’єкти, створені Py_BuildValue(), ніколи не посилаються на буфери, надані абонентом. Іншими словами, якщо ваш код викликає malloc() і передає виділену пам’ять Py_BuildValue(), ваш код відповідальний за виклик free() для цієї пам’яті один раз Py_BuildValue() повертає.

У наступному описі форма в лапках є одиницею формату; запис у (круглих) дужках — це тип об’єкта Python, який поверне блок формату; і запис у [квадратних] дужках є типом значень C, які потрібно передати.

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

s (str або None) [const char *]: Перетворіть рядок C із нульовим закінченням на об’єкт Python str за допомогою кодування 'utf-8'. Якщо вказівник на рядок C має значення NULL, використовується None.
s# (str або None) [const char *, Py_ssize_t]: Перетворіть рядок C та його довжину на об’єкт Python str за допомогою кодування 'utf-8'. Якщо покажчик рядка C має значення NULL, довжина ігнорується і повертається None.
y (bytes) [const char *]: Це перетворює рядок C на об’єкт Python bytes. Якщо вказівник на рядок C має значення NULL, повертається None.
y# (bytes) [const char *, Py_ssize_t]: Це перетворює рядок C та його довжину на об’єкт Python. Якщо вказівник на рядок C має значення NULL, повертається None.
z (str або None) [const char *]: Те саме, що s.
z# (str або None) [const char *, Py_ssize_t]: Те саме, що s#.
u (str) [const wchar_t *]: Перетворіть буфер даних Unicode (UTF-16 або UCS-4) wchar_t із закінченням нульовим символом на об’єкт Python Unicode. Якщо покажчик буфера Unicode має значення NULL, повертається None.
u# (str) [const wchar_t *, Py_ssize_t]: Перетворіть буфер даних Unicode (UTF-16 або UCS-4) і його довжину на об’єкт Python Unicode. Якщо покажчик буфера Unicode має значення NULL, довжина ігнорується і повертається None.
U (str або None) [const char *]: Те саме, що s.
U# (str або None) [const char *, Py_ssize_t]: Те саме, що s#.
i (int) [int]: Convert a plain C int to a Python integer object.
b (int) [символ]: Convert a plain C char to a Python integer object.
h (int) [короткий int]: Convert a plain C short int to a Python integer object.
l (int) [довге ціле]: Convert a C long int to a Python integer object.
B (int) [беззнаковий символ]: Convert a C unsigned char to a Python integer object.
H (int) [unsigned short int]: Convert a C unsigned short int to a Python integer object.
I (int) [unsigned int]: Convert a C unsigned int to a Python integer object.
k (int) [беззнаковий довгий]: Convert a C unsigned long to a Python integer object.
L (int) [довгий довгий]: Convert a C long long to a Python integer object.
K (int) [беззнаковий довгий довгий]: Convert a C unsigned long long to a Python integer object.
n (int) [Py_ssize_t]: Перетворіть C Py_ssize_t на ціле число Python.
c (bytes довжиною 1) [символ]: Convert a C int representing a byte to a Python bytes object of length 1.
C (str довжини 1) [int]: Convert a C int representing a character to Python str object of length 1.
d (float) [double]: Convert a C double to a Python floating-point number.
f (float) [float]: Convert a C float to a Python floating-point number.
D (complex) [Py_complex *]: Перетворіть структуру C Py_complex на комплексне число Python.
O (об’єкт) [PyObject *]: Pass a Python object untouched but create a new strong reference to it (i.e. its reference count is incremented by one). If the object passed in is a NULL pointer, it is assumed that this was caused because the call producing the argument found an error and set an exception. Therefore, Py_BuildValue() will return NULL but won’t raise an exception. If no exception has been raised yet, SystemError is set.
S (об’єкт) [PyObject *]: Те саме, що «О».
N (об’єкт) [PyObject *]: Same as O, except it doesn’t create a new strong reference. Useful when the object is created by a call to an object constructor in the argument list.
O& (об’єкт) [конвертер, що завгодно]: Convert anything to a Python object through a converter function. The function is called with anything (which should be compatible with void*) as its argument and should return a «new» Python object, or NULL if an error occurred.
(items) (tuple) [matching-items]: Перетворіть послідовність значень C на кортеж Python із такою ж кількістю елементів.
[items] (list) [matching-items]: Перетворіть послідовність значень C на список Python з такою ж кількістю елементів.
{items} (dict) [відповідні-елементи]: Перетворіть послідовність значень C у словник Python. Кожна пара послідовних значень C додає один елемент до словника, який виконує функції ключа та значення відповідно.

Якщо в рядку формату є помилка, встановлюється виняток SystemError і повертається NULL.

PyObject *Py_VaBuildValue(const char *format, va_list vargs)¶: Return value: New reference. Part of the Stable ABI.
Ідентичний Py_BuildValue(), за винятком того, що він приймає va_list, а не змінну кількість аргументів.

Розбір аргументів і створення значень¶