> **Источник:** https://python-all.ru/3.1/c-api/arg.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# Разбор аргументов и построение значений

Эти функции полезны при создании собственных функций и методов расширений. Дополнительная информация и примеры доступны в [*Расширение и встраивание интерпретатора Python*](https://python-all.ru/3.1/extending/index.html#extending-index).

Первые три из описанных функций, [`PyArg_ParseTuple()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_ParseTuple), [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_ParseTupleAndKeywords) и [`PyArg_Parse()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_Parse), используют *строки формата*, которые сообщают функции об ожидаемых аргументах. Эти строки формата имеют одинаковый синтаксис для всех этих функций.

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

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

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

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

Однако, когда структура [`Py_buffer`](https://python-all.ru/3.1/c-api/buffer.html#Py_buffer) заполняется, соответствующий буфер блокируется, чтобы вызывающий код мог затем использовать буфер даже внутри блока [`Py_BEGIN_ALLOW_THREADS`](https://python-all.ru/3.1/c-api/init.html#Py_BEGIN_ALLOW_THREADS) без риска изменения или уничтожения изменяемых данных. Как следствие, **необходимо вызвать** [`PyBuffer_Release()`](https://python-all.ru/3.1/c-api/buffer.html#PyBuffer_Release) после завершения обработки данных (или в случае досрочного прерывания).

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

> **Примечание**
>
> Для всех вариантов форматов `#` (`s#`, `y#` и т.д.), тип аргумента длины (int или `Py_ssize_t`) определяется определением макроса `PY_SSIZE_T_CLEAN` до включения `Python.h`. Если макрос определён, длина имеет тип `Py_ssize_t`, а не `int`. В будущей версии Python это поведение изменится: будет поддерживаться только `Py_ssize_t`, а поддержка `int` будет удалена. Рекомендуется всегда определять `PY_SSIZE_T_CLEAN`.

**`s` ([`str`](https://python-all.ru/3.1/library/functions.html#str)) \[const char \*\]**

Преобразует объект Unicode в указатель C на строку символов. Указатель на существующую строку сохраняется в переменной-указателе на символы, адрес которой передаётся. Строка C завершается нулевым символом (NUL). Строка Python не должна содержать встроенных нулевых байтов; если они есть, возбуждается исключение [`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError). Объекты Unicode преобразуются в строки C с использованием кодировки `'utf-8'`. Если это преобразование не удаётся, возбуждается [`UnicodeError`](https://python-all.ru/3.1/library/exceptions.html#UnicodeError).

> **Примечание**
>
> Этот формат не принимает байтоподобные объекты. Если требуется принимать пути файловой системы и преобразовывать их в строки символов C, предпочтительнее использовать формат `O&` с [`PyUnicode_FSConverter()`](https://python-all.ru/3.1/c-api/unicode.html#PyUnicode_FSConverter) в качестве *преобразователя*.

**`s*` ([`str`](https://python-all.ru/3.1/library/functions.html#str), [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes), [`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray) или объект, совместимый с буфером) \[Py\_buffer\]**

Этот формат принимает Unicode-объекты, а также объекты, поддерживающие протокол буфера. Он заполняет структуру

[`Py_buffer`](https://python-all.ru/3.1/c-api/buffer.html#Py_buffer)

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

`'utf-8'`

.

**`s#` ([`str`](https://python-all.ru/3.1/library/functions.html#str), [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes) или объект, совместимый с буфером только для чтения) \[const char \*, int или `Py_ssize_t`\]**

Как

`s*`

, за исключением того, что не принимает изменяемые буфероподобные объекты, такие как

[`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray)

. Результат сохраняется в две C-переменные: первая – указатель на C-строку, вторая – её длина. Строка может содержать встроенные нулевые байты. Объекты Unicode преобразуются в C-строки с использованием кодировки

`'utf-8'`

.

**`z` ([`str`](https://python-all.ru/3.1/library/functions.html#str) или `None`) \[const char \*\]**

Аналогично

`s`

, но объект Python также может быть

`None`

, и в этом случае указатель C устанавливается в

*NULL*

.

**`z*` ([`str`](https://python-all.ru/3.1/library/functions.html#str), [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes), [`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray), объект, совместимый с буфером или `None`) \[Py\_buffer\]**

Как

`s*`

, но объект Python также может быть

`None`

, и в этом случае поле

`buf`

структуры

[`Py_buffer`](https://python-all.ru/3.1/c-api/buffer.html#Py_buffer)

устанавливается в

*NULL*

.

**`z#` ([`str`](https://python-all.ru/3.1/library/functions.html#str), [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes), объект, совместимый с буфером только для чтения или `None`) \[const char \*, int\]**

Как

`s#`

, но объект Python также может быть

`None`

, и в этом случае указатель C устанавливается в

*NULL*

.

**`y` ([`bytes`](https://python-all.ru/3.1/library/functions.html#bytes)) \[const char \*\]**

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

[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)

.

**`y*` ([`bytes`](https://python-all.ru/3.1/library/functions.html#bytes), [`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray) или объект, совместимый с буфером) \[Py\_buffer\]**

Этот вариант

`s*`

не принимает Unicode-объекты, только объекты, поддерживающие протокол буфера.

**Это рекомендуемый способ приёма двоичных данных.**

**`y#` ([`bytes`](https://python-all.ru/3.1/library/functions.html#bytes)) \[const char \*, int\]**

Этот вариант

`s#`

не принимает объекты Unicode, только объекты, подобные байтам.

**`S` ([`bytes`](https://python-all.ru/3.1/library/functions.html#bytes)) \[PyBytesObject \*\]**

Требует, чтобы объект Python был объектом

[`bytes`](https://python-all.ru/3.1/library/functions.html#bytes)

, без попыток преобразования. Возбуждает

[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)

, если объект не является объектом bytes. Переменная C также может быть объявлена как

[`PyObject*`](https://python-all.ru/3.1/c-api/structures.html#PyObject)

.

**`Y` ([`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray)) \[PyByteArrayObject \*\]**

Требует, чтобы объект Python был объектом

[`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray)

, без попыток преобразования. Возбуждает

[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)

, если объект не является объектом

[`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray)

. Переменная C также может быть объявлена как

[`PyObject*`](https://python-all.ru/3.1/c-api/structures.html#PyObject)

.

**`u` ([`str`](https://python-all.ru/3.1/library/functions.html#str)) \[Py\_UNICODE \*\]**

Преобразует объект Python Unicode в указатель C на буфер Unicode, завершающийся NUL. Необходимо передать адрес переменной-указателя [`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE), которая будет заполнена указателем на существующий буфер Unicode. Обратите внимание, что ширина символа [`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE) зависит от опций компиляции (она составляет 16 или 32 бита).

> **Примечание**
>
> Поскольку `u` не возвращает длину строки, и она может содержать встроенные нулевые символы, рекомендуется использовать вместо него `u#` или `U`.

**`u#` ([`str`](https://python-all.ru/3.1/library/functions.html#str)) \[Py\_UNICODE \*, int\]**

Этот вариант

`u`

сохраняет значения в две переменные C: первая – указатель на буфер данных Unicode, вторая – его длину.

**`Z` ([`str`](https://python-all.ru/3.1/library/functions.html#str) или `None`) \[Py\_UNICODE \*\]**

Как и

`u`

, но объект Python также может быть

`None`

, и в этом случае указатель

[`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE)

устанавливается в

*NULL*

.

**`Z#` ([`str`](https://python-all.ru/3.1/library/functions.html#str) или `None`) \[Py\_UNICODE \*, int\]**

Как и

`u#`

, но объект Python также может быть

`None`

, и в этом случае указатель

[`Py_UNICODE`](https://python-all.ru/3.1/c-api/unicode.html#Py_UNICODE)

устанавливается в

*NULL*

.

**`U` ([`str`](https://python-all.ru/3.1/library/functions.html#str)) \[PyUnicodeObject \*\]**

Требует, чтобы объект Python был объектом Unicode, без попыток какого-либо преобразования. Возбуждает

[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)

, если объект не является объектом Unicode. Переменная C также может быть объявлена как

[`PyObject*`](https://python-all.ru/3.1/c-api/structures.html#PyObject)

.

**`t#` ([`bytes`](https://python-all.ru/3.1/library/functions.html#bytes), [`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray) или буфер символов только для чтения) \[char \*, int\]**

Как и

`s#`

, но принимает любой объект, реализующий интерфейс буфера только для чтения. Переменная

`char*`

устанавливается указателем на первый байт буфера, а

`int`

– длиной буфера. Принимаются только объекты с односегментным буфером; для всех остальных возбуждается

[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)

.

**`w` ([`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray) или буфер символов для чтения и записи) \[char \*\]**

Похож на

`y`

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

`w#`

. Принимаются только объекты с односегментным буфером; для всех остальных возбуждается

[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)

.

**`w*` ([`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray) или буфер для чтения и записи, ориентированный на байты) \[Py\_buffer\]**

Это относится к

`w`

так же, как

`y*`

относится к

`y`

.

**`w#` ([`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray) или буфер символов для чтения и записи) \[char \*, int\]**

Как и

`y#`

, но принимает любой объект, реализующий интерфейс буфера для чтения и записи. Переменная

`char *`

устанавливается указателем на первый байт буфера, а

`int`

– длиной буфера. Принимаются только объекты с односегментным буфером; для всех остальных возбуждается

[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)

.

**`es` ([`str`](https://python-all.ru/3.1/library/functions.html#str)) \[const char \*encoding, char \*\*buffer\]**

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

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

[`PyArg_ParseTuple()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_ParseTuple) выделит буфер необходимого размера, скопирует закодированные данные в этот буфер и настроит *\*buffer* так, чтобы он ссылался на новую выделенную память. Вызывающий код отвечает за вызов [`PyMem_Free()`](https://python-all.ru/3.1/c-api/memory.html#PyMem_Free) для освобождения выделенного буфера после использования.

**`et` ([`str`](https://python-all.ru/3.1/library/functions.html#str), [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes) или [`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray)) \[const char \*encoding, char \*\*buffer\]**

То же, что и

`es`

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

**`es#` ([`str`](https://python-all.ru/3.1/library/functions.html#str)) \[const char \*encoding, char \*\*buffer, int \*buffer\_length\]**

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

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

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

Если *\*buffer* указывает на указатель *NULL*, функция выделит буфер необходимого размера, скопирует закодированные данные в этот буфер и установит *\*buffer* так, чтобы он ссылался на новую выделенную память. Вызывающий код отвечает за вызов [`PyMem_Free()`](https://python-all.ru/3.1/c-api/memory.html#PyMem_Free) для освобождения выделенного буфера после использования.

Если *\*buffer* указывает на не-*NULL* указатель (уже выделенный буфер), [`PyArg_ParseTuple()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_ParseTuple) будет использовать это место как буфер и интерпретировать начальное значение *\*buffer\_length* как размер буфера. Затем он скопирует закодированные данные в буфер и завершит его NUL. Если буфер недостаточно велик, будет установлено [`ValueError`](https://python-all.ru/3.1/library/exceptions.html#ValueError).

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

**`et#` ([`str`](https://python-all.ru/3.1/library/functions.html#str), [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes) или [`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray)) \[const char \*encoding, char \*\*buffer, int \*buffer\_length\]**

То же, что и

`es#`

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

### Числа

**`b` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned char\]**

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

`unsigned char`

.

**`B` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned char\]**

Преобразует целое число Python в крошечное целое без проверки переполнения, хранящееся в C

`unsigned char`

.

**`h` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[short int\]**

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

`short int`

.

**`H` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned short int\]**

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

`unsigned short int`

без проверки переполнения.

**`i` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[int\]**

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

`int`

.

**`I` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned int\]**

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

`unsigned int`

без проверки переполнения.

**`l` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[long int\]**

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

`long int`

.

**`k` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned long\]**

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

`unsigned long`

без проверки переполнения.

**`L` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[PY\_LONG\_LONG\]**

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

`long long`

. Этот формат доступен только на платформах, поддерживающих

`long long`

(или

`_int64`

на Windows).

**`K` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned PY\_LONG\_LONG\]**

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

`unsigned long long`

без проверки переполнения. Этот формат доступен только на платформах, поддерживающих

`unsigned long long`

(или

`unsigned _int64`

на Windows).

**`n` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[Py\_ssize\_t\]**

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

`Py_ssize_t`

.

**`c` ([`bytes`](https://python-all.ru/3.1/library/functions.html#bytes) длиной 1) \[char\]**

Преобразует Python-байт, представленный в виде объекта

[`bytes`](https://python-all.ru/3.1/library/functions.html#bytes)

длины 1, в C-тип

`char`

.

**`C` ([`str`](https://python-all.ru/3.1/library/functions.html#str) длиной 1) \[int\]**

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

[`str`](https://python-all.ru/3.1/library/functions.html#str)

длиной 1, в C

`int`

.

**`f` ([`float`](https://python-all.ru/3.1/library/functions.html#float)) \[float\]**

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

`float`

.

**`d` ([`float`](https://python-all.ru/3.1/library/functions.html#float)) \[double\]**

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

`double`

.

**`D` ([`complex`](https://python-all.ru/3.1/library/functions.html#complex)) \[Py\_complex\]**

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

[`Py_complex`](https://python-all.ru/3.1/c-api/complex.html#Py_complex)

.

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

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

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

*NULL*

.

**`O!` (object) \[*typeobject*, PyObject \*\]**

Сохраняет объект Python в указателе на объект C. Это похоже на

`O`

, но принимает два аргумента C: первый – адрес объекта типа Python, второй – адрес переменной C (типа

[`PyObject*`](https://python-all.ru/3.1/c-api/structures.html#PyObject)

), в который сохраняется указатель на объект. Если объект Python не имеет требуемого типа, вызывается

[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)

.

**`O&` (объект) \[*converter*, *anything*\]**

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

```c
status = converter(object, address);
```

где *object* – это объект Python, который нужно преобразовать, а *address* – это аргумент `void*`, переданный функции [`PyArg_Parse*()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_Parse). Возвращаемое значение *status* должно быть `1` при успешном преобразовании и `0` при неудаче. В случае ошибки функция *converter* должна возбудить исключение и оставить содержимое *address* без изменений.

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

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

**`(items)` ([`tuple`](https://python-all.ru/3.1/library/functions.html#tuple)) \[*matching-items*\]**

Объект должен быть последовательностью Python, длина которой равна количеству единиц формата в

*элементах*

. Аргументы C должны соответствовать отдельным единицам формата в

*элементах*

. Единицы формата для последовательностей могут быть вложенными.

Можно передавать «длинные» целые числа (целые, значение которых превышает `LONG_MAX` платформы), однако надлежащая проверка диапазона не выполняется – старшие биты молча отбрасываются, когда принимающее поле слишком мало для значения (на самом деле, семантика унаследована от понижающих приведений в C – результат может отличаться).

Некоторые другие символы имеют значение в строке формата. Они не могут встречаться внутри вложенных скобок. Вот они:

**`|`**

Указывает, что остальные аргументы в списке аргументов Python являются необязательными. Переменные C, соответствующие необязательным аргументам, должны быть инициализированы значением по умолчанию – если необязательный аргумент не указан,

[`PyArg_ParseTuple()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_ParseTuple)

не изменяет содержимое соответствующих переменных C.

**`:`**

Список единиц формата заканчивается здесь; строка после двоеточия используется как имя функции в сообщениях об ошибках («связанное значение» исключения, которое возбуждает

[`PyArg_ParseTuple()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_ParseTuple)

).

**`;`**

Список единиц форматирования заканчивается здесь; строка после точки с запятой используется как сообщение об ошибке

*вместо*

сообщения об ошибке по умолчанию.

`:`

и

`;`

взаимно исключают друг друга.

Обратите внимание, что любые ссылки на объекты Python, передаваемые вызывающему, являются *заимствованными* ссылками; уменьшать их счётчик ссылок не следует.

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

Чтобы преобразование прошло успешно, объект *arg* должен соответствовать формату, а формат должен быть исчерпан. В случае успеха функции [`PyArg_Parse*()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_Parse) возвращают true, иначе возвращают false и возбуждают соответствующее исключение. Когда функции [`PyArg_Parse*()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_Parse) завершаются ошибкой из-за сбоя преобразования в одной из единиц формата, переменные по адресам, соответствующим этой и следующим единицам формата, остаются нетронутыми.

### API функции

**int `PyArg_ParseTuple`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*args*, const char *\*format*, ...)**

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

**int `PyArg_VaParse`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*args*, const char *\*format*, va\_list *vargs*)**

Идентична

[`PyArg_ParseTuple()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_ParseTuple)

, за исключением того, что принимает va\_list вместо переменного числа аргументов.

**int `PyArg_ParseTupleAndKeywords`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*args*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*kw*, const char *\*format*, char *\*keywords\[\]*, ...)**

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

**int `PyArg_VaParseTupleAndKeywords`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*args*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*kw*, const char *\*format*, char *\*keywords\[\]*, va\_list *vargs*)**

Идентична

[`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_ParseTupleAndKeywords)

, за исключением того, что принимает va\_list вместо переменного числа аргументов.

**int `PyArg_Parse`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*args*, const char *\*format*, ...)**

Функция, используемая для разбора списков аргументов «старых» функций – это функции, использующие

`METH_OLDARGS`

разбор параметров метод. Не рекомендуется использовать его для разбора параметров в новом коде, и большая часть кода в стандартном интерпретаторе была изменена, чтобы больше не использовать этот метод для этой цели. Тем не менее, он остаётся удобным способом разложения других кортежей, однако и может по-прежнему использоваться для этой цели.

**int `PyArg_UnpackTuple`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*args*, const char *\*name*, Py\_ssize\_t *min*, Py\_ssize\_t *max*, ...)**

Более простая форма извлечения параметров, которая не использует строку формата для указания типов аргументов. Функции, использующие этот метод для извлечения параметров, должны быть объявлены как [`METH_VARARGS`](https://python-all.ru/3.1/c-api/structures.html#METH_VARARGS) в таблицах функций или методов. Кортеж, содержащий фактические параметры, должен передаваться как *args*; он должен быть именно кортежем. Длина кортежа должна быть не менее *min* и не более *max*; *min* и *max* могут быть равны. Дополнительные аргументы должны быть переданы функции, каждый из которых должен быть указателем на переменную [`PyObject*`](https://python-all.ru/3.1/c-api/structures.html#PyObject); они будут заполнены значениями из *args*; они будут содержать заимствованные ссылки. Переменные, соответствующие необязательным параметрам, не указанным в *args*, не будут заполнены; они должны быть инициализированы вызывающей стороной. Эта функция возвращает true при успехе и false, если *args* не является кортежем или содержит неверное количество элементов; в случае неудачи будет установлено исключение.

Это пример использования этой функции, взятый из исходников вспомогательного модуля слабых ссылок `_weakref`:

```c
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()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_UnpackTuple) в этом примере полностью эквивалентен следующему вызову [`PyArg_ParseTuple()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_ParseTuple):

```c
PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
```

## Построение значений

**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `Py_BuildValue`(const char *\*format*, ...)**

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

Создаёт новое значение на основе строки формата, аналогичной тем, которые принимаются семейством функций [`PyArg_Parse*()`](https://python-all.ru/3.1/c-api/arg.html#PyArg_Parse), и последовательности значений. Возвращает значение или *NULL* в случае ошибки; если возвращается *NULL*, будет возбуждено исключение.

[`Py_BuildValue()`](https://python-all.ru/3.1/c-api/arg.html#Py_BuildValue) не всегда строит кортеж. Он строит кортеж, только если его строка формата содержит две или более единиц формата. Если строка формата пуста, она возвращает `None`; если содержит ровно одну единицу формата, возвращает объект, описываемый этой единицей формата. Чтобы принудительно вернуть кортеж размером 0 или 1, заключите строку формата в скобки.

Когда буферы памяти передаются в качестве параметров для предоставления данных для построения объектов, как для форматов `s` и `s#`, необходимые данные копируются. Буферы, предоставленные вызывающей стороной, никогда не используются напрямую объектами, созданными [`Py_BuildValue()`](https://python-all.ru/3.1/c-api/arg.html#Py_BuildValue). Другими словами, если ваш код вызывает `malloc()` и передаёт выделенную память в [`Py_BuildValue()`](https://python-all.ru/3.1/c-api/arg.html#Py_BuildValue), ваш код отвечает за вызов `free()` для этой памяти после возврата из [`Py_BuildValue()`](https://python-all.ru/3.1/c-api/arg.html#Py_BuildValue).

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

Символы пробела, табуляции, двоеточия и запятой игнорируются в строках формата (но не внутри единиц формата, таких как `s#`). Это позволяет сделать длинные строки формата немного более читаемыми.

**`s` ([`str`](https://python-all.ru/3.1/library/functions.html#str) или `None`) \[char \*\]**

Преобразует C-строку, завершающуюся нулевым символом, в объект Python

[`str`](https://python-all.ru/3.1/library/functions.html#str)

с использованием кодировки

`'utf-8'`

. Если указатель на C-строку равен

*NULL*

, используется

`None`

.

**`s#` ([`str`](https://python-all.ru/3.1/library/functions.html#str) или `None`) \[char \*, int\]**

Преобразует C-строку и её длину в объект Python

[`str`](https://python-all.ru/3.1/library/functions.html#str)

с использованием кодировки

`'utf-8'`

. Если указатель на C-строку равен

*NULL*

, длина игнорируется и возвращается

`None`

.

**`y` ([`bytes`](https://python-all.ru/3.1/library/functions.html#bytes)) \[char \*\]**

Эта функция преобразует C строку в объект Python

[`bytes()`](https://python-all.ru/3.1/library/functions.html#bytes)

. Если указатель на C строку равен

*NULL*

, возвращается

`None`

.

**`y#` ([`bytes`](https://python-all.ru/3.1/library/functions.html#bytes)) \[char \*, int\]**

Преобразует C-строку и её длину в объект Python. Если указатель на C-строку равен

*NULL*

, возвращается

`None`

.

**`z` ([`str`](https://python-all.ru/3.1/library/functions.html#str) или `None`) \[char \*\]**

То же, что и

`s`

.

**`z#` ([`str`](https://python-all.ru/3.1/library/functions.html#str) или `None`) \[char \*, int\]**

То же, что и

`s#`

.

**`u` ([`str`](https://python-all.ru/3.1/library/functions.html#str)) \[Py\_UNICODE \*\]**

Преобразует буфер с нулевым символом в конце, содержащий данные Unicode (UCS-2 или UCS-4), в объект Unicode Python. Если указатель буфера Unicode равен

*NULL*

, возвращается

`None`

.

**`u#` ([`str`](https://python-all.ru/3.1/library/functions.html#str)) \[Py\_UNICODE \*, int\]**

Преобразует буфер данных Unicode (UCS-2 или UCS-4) и его длину в объект Unicode Python. Если указатель буфера Unicode равен

*NULL*

, длина игнорируется и возвращается

`None`

.

**`U` ([`str`](https://python-all.ru/3.1/library/functions.html#str) или `None`) \[char \*\]**

Преобразует C-строку, завершающуюся нулевым символом, в объект Python unicode. Если указатель на C-строку равен

*NULL*

, используется

`None`

.

**`U#` ([`str`](https://python-all.ru/3.1/library/functions.html#str) или `None`) \[char \*, int\]**

Преобразует C-строку и её длину в объект Python unicode. Если указатель на C-строку равен

*NULL*

, длина игнорируется и возвращается

`None`

.

**`i` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[int\]**

Преобразует обычный C

`int`

в объект Python целого типа.

**`b` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[char\]**

Преобразует обычный C

`char`

в объект Python целого типа.

**`h` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[short int\]**

Преобразует обычное C

`short int`

в объект Python int.

**`l` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[long int\]**

Преобразует C

`long int`

в объект Python int.

**`B` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned char\]**

Преобразует C

`unsigned char`

в объект Python int.

**`H` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned short int\]**

Преобразует C

`unsigned short int`

в объект Python int.

**`I` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned int\]**

Преобразует C

`unsigned int`

в объект Python int.

**`k` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned long\]**

Преобразует C

`unsigned long`

в объект Python int.

**`L` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[PY\_LONG\_LONG\]**

Преобразует C

`long long`

в объект Python int. Доступно только на платформах, поддерживающих

`long long`

(или

`_int64`

в Windows).

**`K` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[unsigned PY\_LONG\_LONG\]**

Преобразует C

`unsigned long long`

в объект Python int. Доступно только на платформах, поддерживающих

`unsigned long long`

(или

`unsigned _int64`

в Windows).

**`n` ([`int`](https://python-all.ru/3.1/library/functions.html#int)) \[Py\_ssize\_t\]**

Преобразует C

`Py_ssize_t`

в Python int.

**`c` ([`bytes`](https://python-all.ru/3.1/library/functions.html#bytes) длиной 1) \[char\]**

Преобразует C

`int`

, представляющий байт, в объект Python

[`bytes`](https://python-all.ru/3.1/library/functions.html#bytes)

длиной 1.

**`C` ([`str`](https://python-all.ru/3.1/library/functions.html#str) длиной 1) \[int\]**

Преобразует C

`int`

, представляющий символ, в объект Python

[`str`](https://python-all.ru/3.1/library/functions.html#str)

длиной 1.

**`d` ([`float`](https://python-all.ru/3.1/library/functions.html#float)) \[double\]**

Преобразует C

`double`

в число с плавающей точкой Python.

**`f` ([`float`](https://python-all.ru/3.1/library/functions.html#float)) \[float\]**

Преобразует C

`float`

в число с плавающей точкой Python.

**`D` ([`complex`](https://python-all.ru/3.1/library/functions.html#complex)) \[Py\_complex \*\]**

Преобразует структуру C

[`Py_complex`](https://python-all.ru/3.1/c-api/complex.html#Py_complex)

в комплексное число Python.

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

Передаёт объект Python без изменений (за исключением счётчика ссылок, который увеличивается на единицу). Если переданный объект является указателем

*NULL*

, считается, что это произошло из-за того, что вызов, формирующий аргумент, обнаружил ошибку и установил исключение. Поэтому

[`Py_BuildValue()`](https://python-all.ru/3.1/c-api/arg.html#Py_BuildValue)

вернёт

*NULL*

, но не вызовет исключение. Если ещё не было установлено никакого исключения, устанавливается

[`SystemError`](https://python-all.ru/3.1/library/exceptions.html#SystemError)

.

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

То же, что и

`O`

.

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

То же, что и

`O`

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

**`O&` (объект) \[*converter*, *anything*\]**

Преобразует

*anything*

в объект Python с помощью функции

*converter*

. Функция вызывается с аргументом

*anything*

(который должен быть совместим с

`void *`

) и должна возвращать «новый» объект Python или

*NULL*

в случае ошибки.

**`(items)` ([`tuple`](https://python-all.ru/3.1/library/functions.html#tuple)) \[*matching-items*\]**

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

**`[items]` ([`list`](https://python-all.ru/3.1/library/functions.html#list)) \[*matching-items*\]**

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

**`{items}` ([`dict`](https://python-all.ru/3.1/library/stdtypes.html#dict)) \[*matching-items*\]**

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

Если в строке формата есть ошибка, устанавливается исключение [`SystemError`](https://python-all.ru/3.1/library/exceptions.html#SystemError) и возвращается *NULL*.

**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `Py_VaBuildValue`(const char *\*format*, va\_list *vargs*)**

Идентична

[`Py_BuildValue()`](https://python-all.ru/3.1/c-api/arg.html#Py_BuildValue)

, за исключением того, что принимает va\_list вместо переменного числа аргументов.