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

These functions are useful when creating your own extension functions and methods. Additional information and examples are available in Розширення та вбудовування інтерпретатора Python.

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

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

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

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

Примітка

Для Python 3.12 і старших версій, макрос `PY_SSIZE_T_CLEAN`має бути визначено перед включенням :file:`Python.h`, щоб скористатися усіма варіантами форматів `#` (`s#`, `y#` і т.п.), про які йдеться нижче. Його можна не визначати для Python 3.13 і пізніших версій.

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

Якщо не зазначено інше, буфери не завершуються 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).

`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]

  This format accepts any object which implements the read-write buffer interface. It fills a `Py_buffer` structure provided by the caller. The buffer may contain embedded null bytes. The caller has to call `PyBuffer_Release()` when it is done with the buffer.

`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.

### Числа

These formats allow representing Python numbers or single characters as C numbers. Formats that require `int`, `float` or `complex` can also use the corresponding special methods `__index__()`, `__float__()` or `__complex__()` to convert the Python object to the required type.

For signed integer formats, `OverflowError` is raised if the value is out of range for the C type. For unsigned integer formats, the most significant bits are silently truncated when the receiving field is too small to receive the value, and `DeprecationWarning` is emitted when the value is larger than the maximal value for the C type or less than the minimal value for the corresponding signed integer type of the same size.

`b` (`int`) [беззнаковий символ]

  Convert a nonnegative Python integer to an unsigned tiny integer, stored in a C unsigned char.

`B` (`int`) [беззнаковий символ]

  Convert a Python integer to a tiny integer without overflow checking, stored in a C unsigned char. Convert a Python integer to a C unsigned char.

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

  Перетворює ціле число Python на C short int.

`H` (`int`) [unsigned short int]

  Convert a Python integer to a 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.

`l` (`int`) [довге ціле]

  Convert a Python integer to a C long int.

`k` (`int`) [беззнаковий довгий]

  Convert a Python integer to a C unsigned long.

  Змінено в версії 3.14: Use `__index__()` if available.

`L` (`int`) [довгий довгий]

  Convert a Python integer to a C long long.

`K` (`int`) [беззнаковий довгий довгий]

  Convert a Python integer to a C unsigned long long.

  Змінено в версії 3.14: Use `__index__()` if available.

`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`.

Застаріло починаючи з версії 3.15: For unsigned integer formats `B`, `H`, `I`, `k` and `K`, `DeprecationWarning` is emitted when the value is larger than the maximal value for the C type or less than the minimal value for the corresponding signed integer type of the same size.

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

`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&` (object) [converter, address]

  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.

  If the converter returns `Py_CLEANUP_SUPPORTED`, it may get called a second time if the argument parsing eventually fails, giving the converter a chance to release any memory that it had already allocated. In this second call, the object parameter will be `NULL`; address will have the same value as in the original call.

  Examples of converters: `PyUnicode_FSConverter()` and `PyUnicode_FSDecoder()`.

  Змінено в версії 3.1: `Py_CLEANUP_SUPPORTED` was added.

`p` (`bool`) [int]

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

  Added in version 3.3.

`(items)` (sequence) [matching-items]

  The object must be a Python sequence (except `str`, `bytes` or `bytearray`) whose length is the number of format units in items. The C arguments must correspond to the individual format units in items. Format units for sequences may be nested.

  If items contains format units which store a borrowed buffer (`s`, `s#`, `z`, `z#`, `y`, or `y#`) or a borrowed reference (`S`, `Y`, `U`, `O`, or `O!`), the object must be a Python tuple. The converter for the `O&` format unit in items must not store a borrowed buffer or a borrowed reference.

  Змінено в версії 3.14: `str` and `bytearray` objects no longer accepted as a sequence.

  Застаріло починаючи з версії 3.14: Non-tuple sequences are deprecated if items contains format units which store a borrowed buffer or a borrowed reference.

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

`|`

  Вказує, що решта аргументів у списку аргументів 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 *const *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 specified as null-terminated ASCII or UTF-8 encoded C strings. Empty names denote positional-only parameters. Returns true on success; on failure, it returns false and raises the appropriate exception.

  Примітка

  The keywords parameter declaration is char *const* in C and const char *const* in C++. This can be overridden with the `PY_CXX_CONST` macro.

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

  Змінено в версії 3.13: The keywords parameter has now type char *const* in C and const char *const* in C++, instead of char**. Added support for non-ASCII keyword parameter names.

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *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.

  Parse the parameter of a function that takes a single positional parameter into a local variable. Returns true on success; on failure, it returns false and raises the appropriate exception.

  Приклад:

      // Function using METH_O calling convention
      static PyObject*
      my_function(PyObject *module, PyObject *arg)
      {
          int value;
          if (!PyArg_Parse(arg, "i:my_function", &value)) {
              return NULL;
          }
          // ... use value ...
      }

int PyArg_ParseArray(PyObject *const *args, Py_ssize_t nargs, const char *format, ...)

  Parse the parameters of a function that takes only array parameters into local variables (that is, a function using the `METH_FASTCALL` calling convention). Returns true on success; on failure, it returns false and raises the appropriate exception.

  Added in version 3.15.

int PyArg_ParseArrayAndKeywords(PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames, const char *format, const char *const *kwlist, ...)

  Parse the parameters of a function that takes both array and keyword parameters into local variables (that is, a function using the `METH_FASTCALL` `|` `METH_KEYWORDS` calling convention). Returns true on success; on failure, it returns false and raises the appropriate exception.

  Added in version 3.15.

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)

PY_CXX_CONST

  The value to be inserted, if any, before char *const* in the keywords parameter declaration of `PyArg_ParseTupleAndKeywords()` and `PyArg_VaParseTupleAndKeywords()`. Default empty for C and `const` for C++ (const char *const*). To override, define it to the desired value before including `Python.h`.

  Added in version 3.13.

## Формування цінностей

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.

  `p` (`bool`) [int]

    Convert a C int to a Python `bool` object.

    Be aware that this format requires an `int` argument. Unlike most other contexts in C, variadic arguments are not coerced to a suitable type automatically. You can convert another type (for example, a pointer or a float) to a suitable `int` value using `(x) ? 1 : 0` or `!!x`.

    Added in version 3.14.

  `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, а не змінну кількість аргументів.