`arg.md`

552 строк · 61.5 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.15/c-api/arg.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Разбор аргументов и построение значений89Эти функции полезны при создании собственных функций и методов расширения. Дополнительная информация и примеры доступны в [Extending and Embedding the Python Interpreter](https://python-all.ru/3.15/extending/index.html#extending-index).1011Первые три из описанных функций, [`PyArg_ParseTuple()`](https://python-all.ru/3.15/c-api/arg.html#c.PyArg_ParseTuple), [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.15/c-api/arg.html#c.PyArg_ParseTupleAndKeywords) и [`PyArg_Parse()`](https://python-all.ru/3.15/c-api/arg.html#c.PyArg_Parse), используют *строки формата*, которые сообщают функции об ожидаемых аргументах. Строки формата имеют одинаковый синтаксис для каждой из этих функций.1213## Разбор аргументов1415Строка формата состоит из нуля или более «единиц формата». Единица формата описывает один объект Python; обычно это один символ или заключённая в скобки последовательность единиц формата. За несколькими исключениями, единица формата, не являющаяся последовательностью в скобках, обычно соответствует одному аргументу-адресу этих функций. В следующем описании приведённая в кавычках форма – это единица формата; запись в круглых скобках – тип объекта Python, которому соответствует единица формата; а запись в квадратных скобках – тип переменной(ых) C, чей адрес следует передать.1617### Строки и буферы1819> **Примечание**20>21> В Python 3.12 и старше макрос `PY_SSIZE_T_CLEAN` должен быть определён до включения `Python.h`, чтобы использовать все `#` варианты форматов (`s#`, `y#` и т.д.), описанные ниже. В Python 3.13 и новее это не требуется.2223Эти форматы позволяют обращаться к объекту как к непрерывному блоку памяти. Не нужно предоставлять сырое хранилище для возвращаемой области unicode или bytes.2425Если не указано иное, буферы не завершаются нулевым символом (NUL).2627Существует три способа преобразования строк и буферов в C:2829- Форматы, такие как `y*` и `s*`, заполняют структуру [`Py_buffer`](https://python-all.ru/3.15/c-api/buffer.html#c.Py_buffer). Это блокирует нижележащий буфер, чтобы вызывающий код мог впоследствии использовать буфер даже внутри блока [`Py_BEGIN_ALLOW_THREADS`](https://python-all.ru/3.15/c-api/threads.html#c.Py_BEGIN_ALLOW_THREADS) без риска изменения размера или уничтожения изменяемых данных. В результате **необходимо вызывать** [`PyBuffer_Release()`](https://python-all.ru/3.15/c-api/buffer.html#c.PyBuffer_Release) после завершения обработки данных (или в случае досрочного прерывания).30- Форматы `es`, `es#`, `et` и `et#` выделяют буфер для результата. **Необходимо вызывать** [`PyMem_Free()`](https://python-all.ru/3.15/c-api/memory.html#c.PyMem_Free) после завершения обработки данных (или в случае досрочного прерывания).31- Другие форматы принимают [`str`](https://python-all.ru/3.15/library/stdtypes.html#str) или [байтоподобный объект](https://python-all.ru/3.15/glossary.html#term-bytes-like-object) только для чтения, такой как [`bytes`](https://python-all.ru/3.15/library/stdtypes.html#bytes), и предоставляют указатель `const char *` на его буфер. В этом случае буфер является «заимствованным»: он управляется соответствующим объектом Python и разделяет время жизни этого объекта. Самостоятельно освобождать память не потребуется.3233  Чтобы гарантировать возможность безопасного заимствования базового буфера, поле [`PyBufferProcs.bf_releasebuffer`](https://python-all.ru/3.15/c-api/typeobj.html#c.PyBufferProcs.bf_releasebuffer) объекта должно быть `NULL`. Это исключает обычные изменяемые объекты, такие как [`bytearray`](https://python-all.ru/3.15/library/stdtypes.html#bytearray), но также и некоторые объекты только для чтения, такие как [`memoryview`](https://python-all.ru/3.15/library/stdtypes.html#memoryview) из [`bytes`](https://python-all.ru/3.15/library/stdtypes.html#bytes).3435  Кроме этого требования `bf_releasebuffer`, не существует проверки на то, является ли входной объект неизменяемым (например, будет ли он выполнять запрос на буфер для записи или сможет ли другой поток изменить данные).3637**`s` ([`str`](https://python-all.ru/3.15/library/stdtypes.html#str)) \[const char \*\]**3839Преобразует объект Unicode в указатель C на строку символов. Указатель на существующую строку сохраняется в переменной-указателе на символ, адрес которой передаётся. Строка C заканчивается нулевым символом (NUL). Строка Python не должна содержать встроенные нулевые кодовые точки; если содержит, возбуждается исключение [`ValueError`](https://python-all.ru/3.15/library/exceptions.html#ValueError). Объекты Unicode преобразуются в строки C с использованием кодировки `'utf-8'`. Если это преобразование не удаётся, возбуждается [`UnicodeError`](https://python-all.ru/3.15/library/exceptions.html#UnicodeError).4041> **Примечание**42>43> Этот формат не принимает [байтоподобные объекты](https://python-all.ru/3.15/glossary.html#term-bytes-like-object). Если требуется принимать пути файловой системы и преобразовывать их в строки символов C, предпочтительнее использовать формат `O&` с [`PyUnicode_FSConverter()`](https://python-all.ru/3.15/c-api/unicode.html#c.PyUnicode_FSConverter) в качестве *конвертера*.4445Изменено в версии 3.5: Ранее [`TypeError`](https://python-all.ru/3.15/library/exceptions.html#TypeError) возбуждалось, когда в строке Python обнаруживались встроенные нулевые кодовые точки.4647**`s*` ([`str`](https://python-all.ru/3.15/library/stdtypes.html#str) или [байтоподобный объект](https://python-all.ru/3.15/glossary.html#term-bytes-like-object)) \[Py\_buffer\]**4849Этот формат принимает как объекты Unicode, так и байтоподобные объекты. Он заполняет структуру [`Py_buffer`](https://python-all.ru/3.15/c-api/buffer.html#c.Py_buffer), предоставленную вызывающей стороной. В этом случае результирующая строка C может содержать встроенные нулевые байты (NUL). Объекты Unicode преобразуются в строки C с использованием кодировки `'utf-8'`.5051**`s#` ([`str`](https://python-all.ru/3.15/library/stdtypes.html#str), [байтоподобный объект](https://python-all.ru/3.15/glossary.html#term-bytes-like-object) только для чтения) \[const char \*, [`Py_ssize_t`](https://python-all.ru/3.15/c-api/intro.html#c.Py_ssize_t)\]**5253Как `s*`, за исключением того, что предоставляет [заимствованный буфер](https://python-all.ru/3.15/c-api/arg.html#c-arg-borrowed-buffer). Результат сохраняется в две переменные C: первая – указатель на строку C, вторая – её длина. Строка может содержать встроенные нулевые байты. Объекты Unicode преобразуются в строки C с использованием кодировки `'utf-8'`.5455**`z` ([`str`](https://python-all.ru/3.15/library/stdtypes.html#str) или `None`) \[const char \*\]**5657Как `s`, но объект Python также может быть `None`, и в этом случае указатель C устанавливается в `NULL`.5859**`z*` ([`str`](https://python-all.ru/3.15/library/stdtypes.html#str), [байтоподобный объект](https://python-all.ru/3.15/glossary.html#term-bytes-like-object) или `None`) \[Py\_buffer\]**6061Как `s*`, но объект Python также может быть `None`, и в этом случае элемент `buf` структуры [`Py_buffer`](https://python-all.ru/3.15/c-api/buffer.html#c.Py_buffer) устанавливается в `NULL`.6263**`z#` ([`str`](https://python-all.ru/3.15/library/stdtypes.html#str), [байтоподобный объект](https://python-all.ru/3.15/glossary.html#term-bytes-like-object) только для чтения или `None`) \[const char \*, [`Py_ssize_t`](https://python-all.ru/3.15/c-api/intro.html#c.Py_ssize_t)\]**6465Как `s#`, но объект Python также может быть `None`, и в этом случае указатель C устанавливается в `NULL`.6667**`y` ([байтоподобный объект](https://python-all.ru/3.15/glossary.html#term-bytes-like-object) только для чтения) \[const char \*\]**6869Этот формат преобразует байтоподобный объект в указатель C на [заимствованную](https://python-all.ru/3.15/c-api/arg.html#c-arg-borrowed-buffer) строку символов; он не принимает объекты Unicode. Байтовый буфер не должен содержать встроенные нулевые байты; если содержит, возбуждается исключение [`ValueError`](https://python-all.ru/3.15/library/exceptions.html#ValueError).7071Изменено в версии 3.5: Ранее [`TypeError`](https://python-all.ru/3.15/library/exceptions.html#TypeError) возбуждалось, когда в байтовом буфере обнаруживались встроенные нулевые байты.7273**`y*` ([байтоподобный объект](https://python-all.ru/3.15/glossary.html#term-bytes-like-object)) \[Py\_buffer\]**7475Этот вариант `s*` не принимает объекты Unicode, только байтоподобные объекты. **Это рекомендуемый способ приёма двоичных данных.**7677**`y#` ([байтоподобный объект](https://python-all.ru/3.15/glossary.html#term-bytes-like-object) только для чтения) \[const char \*, [`Py_ssize_t`](https://python-all.ru/3.15/c-api/intro.html#c.Py_ssize_t)\]**7879Этот вариант `s#` не принимает объекты Unicode, только байтоподобные объекты.8081**`S` ([`bytes`](https://python-all.ru/3.15/library/stdtypes.html#bytes)) \[PyBytesObject \*\]**8283Требует, чтобы объект Python был объектом [`bytes`](https://python-all.ru/3.15/library/stdtypes.html#bytes), без попыток какого-либо преобразования. Возбуждает [`TypeError`](https://python-all.ru/3.15/library/exceptions.html#TypeError), если объект не является объектом bytes. Переменная C также может быть объявлена как [PyObject](https://python-all.ru/3.15/c-api/structures.html#c.PyObject)\*.8485**`Y` ([`bytearray`](https://python-all.ru/3.15/library/stdtypes.html#bytearray)) \[PyByteArrayObject \*\]**8687Требует, чтобы объект Python был объектом [`bytearray`](https://python-all.ru/3.15/library/stdtypes.html#bytearray), без попыток какого-либо преобразования. Возбуждает [`TypeError`](https://python-all.ru/3.15/library/exceptions.html#TypeError), если объект не является объектом `bytearray`. Переменная C также может быть объявлена как [PyObject](https://python-all.ru/3.15/c-api/structures.html#c.PyObject)\*.8889**`U` ([`str`](https://python-all.ru/3.15/library/stdtypes.html#str)) \[PyObject \*\]**9091Требует, чтобы объект Python был объектом Unicode, без попыток какого-либо преобразования. Возбуждает [`TypeError`](https://python-all.ru/3.15/library/exceptions.html#TypeError), если объект не является объектом Unicode. Переменная C также может быть объявлена как [PyObject](https://python-all.ru/3.15/c-api/structures.html#c.PyObject)\*.9293**`w*` ([байтоподобный объект](https://python-all.ru/3.15/glossary.html#term-bytes-like-object) для чтения и записи) \[Py\_buffer\]**9495Этот формат принимает любой объект, реализующий интерфейс буфера чтения-записи. Он заполняет структуру [`Py_buffer`](https://python-all.ru/3.15/c-api/buffer.html#c.Py_buffer), предоставленную вызывающей стороной. Буфер может содержать встроенные нулевые байты. Вызывающая сторона должна вызвать [`PyBuffer_Release()`](https://python-all.ru/3.15/c-api/buffer.html#c.PyBuffer_Release), когда закончит работу с буфером.9697**`es` ([`str`](https://python-all.ru/3.15/library/stdtypes.html#str)) \[const char \*encoding, char \*\*buffer\]**9899Этот вариант `s` используется для кодирования Unicode в символьный буфер. Он работает только с закодированными данными без встроенных NUL-байтов.100101Этот формат требует два аргумента. Первый используется только как входной и должен быть const char\*, указывающим на имя кодировки в виде строки, завершающейся NUL, или `NULL`, в этом случае используется кодировка `'utf-8'`. Исключение возникает, если указанная кодировка неизвестна Python. Второй аргумент должен быть char\*\*; значение указателя, на который он ссылается, будет установлено на буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, заданной первым аргументом.102103[`PyArg_ParseTuple()`](https://python-all.ru/3.15/c-api/arg.html#c.PyArg_ParseTuple) выделит буфер нужного размера, скопирует закодированные данные в этот буфер и настроит *\*buffer* так, чтобы он ссылался на вновь выделенную память. Вызывающая сторона отвечает за вызов [`PyMem_Free()`](https://python-all.ru/3.15/c-api/memory.html#c.PyMem_Free) для освобождения выделенного буфера после использования.104105**`et` ([`str`](https://python-all.ru/3.15/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3.15/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.15/library/stdtypes.html#bytearray)) \[const char \*encoding, char \*\*buffer\]**106107То же, что и `es`, за исключением того, что объекты байтовой строки передаются без перекодирования. Вместо этого реализация предполагает, что объект байтовой строки использует кодировку, переданную в качестве параметра.108109**`es#` ([`str`](https://python-all.ru/3.15/library/stdtypes.html#str)) \[const char \*encoding, char \*\*buffer, [`Py_ssize_t`](https://python-all.ru/3.15/c-api/intro.html#c.Py_ssize_t) \*buffer\_length\]**110111Этот вариант `s#` используется для кодирования Unicode в символьный буфер. В отличие от формата `es`, этот вариант допускает входные данные, содержащие NUL-символы.112113Требуется три аргумента. Первый используется только как входной и должен быть const char\*, указывающим на имя кодировки в виде строки, завершающейся NUL, или `NULL`, в этом случае используется кодировка `'utf-8'`. Исключение возникает, если указанная кодировка неизвестна Python. Второй аргумент должен быть char\*\*; значение указателя, на который он ссылается, будет установлено на буфер с содержимым текста аргумента. Текст будет закодирован в кодировке, заданной первым аргументом. Третий аргумент должен быть указателем на целое число; указанное целое число будет установлено в количество байтов в выходном буфере.114115Существует два режима работы:116117Если *\*buffer* указывает на указатель `NULL`, функция выделит буфер нужного размера, скопирует закодированные данные в этот буфер и установит *\*buffer* так, чтобы он ссылался на вновь выделенную память. Вызывающая сторона отвечает за вызов [`PyMem_Free()`](https://python-all.ru/3.15/c-api/memory.html#c.PyMem_Free) для освобождения выделенного буфера после использования.118119Если *\*buffer* указывает на не-`NULL` указатель (уже выделенный буфер), [`PyArg_ParseTuple()`](https://python-all.ru/3.15/c-api/arg.html#c.PyArg_ParseTuple) будет использовать это место как буфер и интерпретировать начальное значение *\*buffer\_length* как размер буфера. Затем он скопирует закодированные данные в буфер и завершит их NUL. Если буфер недостаточно велик, будет установлено [`ValueError`](https://python-all.ru/3.15/library/exceptions.html#ValueError).120121В обоих случаях *\*buffer\_length* устанавливается в длину закодированных данных без завершающего NUL-байта.122123**`et#` ([`str`](https://python-all.ru/3.15/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3.15/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.15/library/stdtypes.html#bytearray)) \[const char \*encoding, char \*\*buffer, [`Py_ssize_t`](https://python-all.ru/3.15/c-api/intro.html#c.Py_ssize_t) \*buffer\_length\]**124125То же, что и `es#`, за исключением того, что объекты байтовой строки передаются без перекодирования. Вместо этого реализация предполагает, что объект байтовой строки использует кодировку, переданную в качестве параметра.126127Изменено в версии 3.12: `u`, `u#`, `Z` и `Z#` удалены, поскольку они использовали устаревшее представление `Py_UNICODE*`.128129### Числа130131Эти форматы позволяют представлять числа Python или одиночные символы как числа C. Форматы, требующие [`int`](https://python-all.ru/3.15/library/functions.html#int), [`float`](https://python-all.ru/3.15/library/functions.html#float) или [`complex`](https://python-all.ru/3.15/library/functions.html#complex), также могут использовать соответствующие специальные методы [`__index__()`](https://python-all.ru/3.15/reference/datamodel.html#object.__index__), [`__float__()`](https://python-all.ru/3.15/reference/datamodel.html#object.__float__) или [`__complex__()`](https://python-all.ru/3.15/reference/datamodel.html#object.__complex__) для преобразования объекта Python в требуемый тип.132133Для знаковых целочисленных форматов [`OverflowError`](https://python-all.ru/3.15/library/exceptions.html#OverflowError) возникает, если значение выходит за пределы диапазона типа C. Для беззнаковых целочисленных форматов старшие биты молча отбрасываются, когда принимающее поле слишком мало для размещения значения, и [`DeprecationWarning`](https://python-all.ru/3.15/library/exceptions.html#DeprecationWarning) генерируется, когда значение больше максимального значения для типа C или меньше минимального значения для соответствующего знакового целочисленного типа того же размера.134135**`b` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[unsigned char\]**136137Преобразует неотрицательное целое число Python в беззнаковое крошечное целое, хранящееся в C unsigned char.138139**`B` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[unsigned char\]**140141Преобразует целое число Python в крошечное целое без проверки переполнения, хранящееся в C unsigned char. Преобразует целое число Python в C unsigned char.142143**`h` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[short int\]**144145Преобразует целое число Python в C short int.146147**`H` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[unsigned short int\]**148149Преобразует целое число Python в C unsigned short int.150151**`i` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[int\]**152153Преобразует целое число Python в обычный C int.154155**`I` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[unsigned int\]**156157Преобразует целое число Python в C unsigned int.158159**`l` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[long int\]**160161Преобразует целое число Python в C long int.162163**`k` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[unsigned long\]**164165Преобразует целое число Python в C unsigned long.166167Изменено в версии 3.14: Используйте [`__index__()`](https://python-all.ru/3.15/reference/datamodel.html#object.__index__), если доступно.168169**`L` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[long long\]**170171Преобразует целое число Python в C long long.172173**`K` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[unsigned long long\]**174175Преобразует целое число Python в C unsigned long long.176177Изменено в версии 3.14: Используйте [`__index__()`](https://python-all.ru/3.15/reference/datamodel.html#object.__index__), если доступно.178179**`n` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[[`Py_ssize_t`](https://python-all.ru/3.15/c-api/intro.html#c.Py_ssize_t)\]**180181Преобразует целое число Python в C [`Py_ssize_t`](https://python-all.ru/3.15/c-api/intro.html#c.Py_ssize_t).182183**`c` ([`bytes`](https://python-all.ru/3.15/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.15/library/stdtypes.html#bytearray) длиной 1) \[char\]**184185Преобразует байт Python, представленный как объект [`bytes`](https://python-all.ru/3.15/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.15/library/stdtypes.html#bytearray) длиной 1, в C char.186187Изменено в версии 3.3: Допускаются объекты [`bytearray`](https://python-all.ru/3.15/library/stdtypes.html#bytearray).188189**`C` ([`str`](https://python-all.ru/3.15/library/stdtypes.html#str) длины 1) \[int\]**190191Преобразует символ Python, представленный как объект [`str`](https://python-all.ru/3.15/library/stdtypes.html#str) длиной 1, в C int.192193**`f` ([`float`](https://python-all.ru/3.15/library/functions.html#float)) \[float\]**194195Преобразует число с плавающей запятой Python в C float.196197**`d` ([`float`](https://python-all.ru/3.15/library/functions.html#float)) \[double\]**198199Преобразует число с плавающей запятой Python в C double.200201**`D` ([`complex`](https://python-all.ru/3.15/library/functions.html#complex)) \[Py\_complex\]**202203Преобразует комплексное число Python в структуру C [`Py_complex`](https://python-all.ru/3.15/c-api/complex.html#c.Py_complex).204205Устарело с версии 3.15: Для беззнаковых целочисленных форматов `B`, `H`, `I`, `k` и `K`, [`DeprecationWarning`](https://python-all.ru/3.15/library/exceptions.html#DeprecationWarning) выдается, когда значение превышает максимальное значение для типа C или меньше минимального значения для соответствующего знакового целочисленного типа того же размера.206207### Другие объекты208209**`O` (объект) \[PyObject \*\]**210211Сохраняет объект Python (без преобразования) в указателе на объект C. Таким образом, программа на C получает фактически переданный объект. Новая [сильная ссылка](https://python-all.ru/3.15/glossary.html#term-strong-reference) на объект не создается (т.е. его счетчик ссылок не увеличивается). Сохраненный указатель не является `NULL`.212213**`O!` (object) \[*typeobject*, PyObject \*\]**214215Сохраняет объект Python в указателе на объект C. Это похоже на `O`, но принимает два аргумента C: первый – адрес объекта типа Python, второй – адрес переменной C (типа [PyObject](https://python-all.ru/3.15/c-api/structures.html#c.PyObject)\*), в которую сохраняется указатель на объект. Если объект Python не имеет требуемого типа, вызывается [`TypeError`](https://python-all.ru/3.15/library/exceptions.html#TypeError).216217**`O&` (object) \[*конвертер*, *address*\]**218219Преобразует объект Python в переменную C с помощью функции *конвертера*. Она принимает два аргумента: первый – функция, второй – адрес переменной C (произвольного типа), преобразованный в void\*. Сама функция *конвертера* вызывается следующим образом:220221```c222status = converter(object, address);223```224225где *object* – преобразуемый объект Python, а *address* – это аргумент void\*, переданный функции `PyArg_Parse*`. Возвращаемое значение *status* должно быть `1` при успешном преобразовании и `0`, если преобразование не удалось. При неудачном преобразовании функция *конвертера* должна вызвать исключение и оставить содержимое *address* без изменений.226227Если *конвертер* возвращает `Py_CLEANUP_SUPPORTED`, он может быть вызван повторно, если в конечном итоге разбор аргументов завершится неудачей, давая конвертеру возможность освободить память, которую он уже выделил. При повторном вызове параметр *object* будет равен `NULL`; *address* будет иметь то же значение, что и при первоначальном вызове.228229Примеры преобразователей: [`PyUnicode_FSConverter()`](https://python-all.ru/3.15/c-api/unicode.html#c.PyUnicode_FSConverter) и [`PyUnicode_FSDecoder()`](https://python-all.ru/3.15/c-api/unicode.html#c.PyUnicode_FSDecoder).230231Изменено в версии 3.1: `Py_CLEANUP_SUPPORTED` добавлен.232233**`p` ([`bool`](https://python-all.ru/3.15/library/functions.html#bool)) \[int\]**234235Проверяет переданное значение на истинность (булев предикат **p**) и преобразует результат в эквивалентное целое C true/false. Устанавливает int в `1`, если выражение истинно, и в `0`, если ложно. Принимает любое корректное значение Python. См. [Проверка истинности значений](https://python-all.ru/3.15/library/stdtypes.html#truth) для получения дополнительной информации о том, как Python проверяет значения на истинность.236237Добавлено в версии 3.3.238239**`(items)` (последовательность) \[*matching-items*\]**240241Объект должен быть последовательностью Python (за исключением [`str`](https://python-all.ru/3.15/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3.15/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.15/library/stdtypes.html#bytearray)), длина которой равна количеству единиц форматирования в *items*. Аргументы C должны соответствовать отдельным единицам форматирования в *items*. Единицы форматирования для последовательностей могут быть вложенными.242243Если *items* содержит единицы форматирования, которые хранят [заимствованный буфер](https://python-all.ru/3.15/c-api/arg.html#c-arg-borrowed-buffer) (`s`, `s#`, `z`, `z#`, `y` или `y#`) или [заимствованную ссылку](https://python-all.ru/3.15/glossary.html#term-borrowed-reference) (`S`, `Y`, `U`, `O` или `O!`), объект должен быть кортежем Python. *Преобразователь* для единицы форматирования `O&` в *items* не должен хранить заимствованный буфер или заимствованную ссылку.244245Изменено в версии 3.14: объекты [`str`](https://python-all.ru/3.15/library/stdtypes.html#str) и [`bytearray`](https://python-all.ru/3.15/library/stdtypes.html#bytearray) больше не принимаются как последовательность.246247Устарело с версии 3.14: Последовательности, не являющиеся кортежами, считаются устаревшими, если *items* содержит единицы форматирования, которые хранят заимствованный буфер или заимствованную ссылку.248249Некоторые другие символы имеют значение в строке формата. Они не могут встречаться внутри вложенных скобок. Вот они:250251**`|`**252253Указывает, что остальные аргументы в списке аргументов Python являются необязательными. Переменные C, соответствующие необязательным аргументам, должны быть инициализированы значением по умолчанию – когда необязательный аргумент не указан, [`PyArg_ParseTuple()`](https://python-all.ru/3.15/c-api/arg.html#c.PyArg_ParseTuple) не трогает содержимое соответствующих переменных C.254255**`$`**256257[`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.15/c-api/arg.html#c.PyArg_ParseTupleAndKeywords) only: Указывает, что остальные аргументы в списке аргументов Python являются только ключевыми. В настоящее время все только ключевые аргументы также должны быть необязательными, поэтому `|` всегда должен указываться перед `$` в строке формата.258259Добавлено в версии 3.3.260261**`:`**262263Список единиц форматирования заканчивается здесь; строка после двоеточия используется как имя функции в сообщениях об ошибках («связанное значение» исключения, которое вызывает [`PyArg_ParseTuple()`](https://python-all.ru/3.15/c-api/arg.html#c.PyArg_ParseTuple)).264265**`;`**266267Список единиц форматирования заканчивается здесь; строка после точки с запятой используется как сообщение об ошибке *вместо* сообщения об ошибке по умолчанию. `:` и `;` взаимно исключают друг друга.268269Обратите внимание, что все ссылки на объекты Python, предоставляемые вызывающей стороне, являются *заимствованными* ссылками; не освобождайте их (т.е. не уменьшайте их счетчик ссылок)!270271Дополнительные аргументы, передаваемые этим функциям, должны быть адресами переменных, тип которых определяется строкой формата; они используются для хранения значений из входного кортежа. Есть несколько случаев, как описано в списке единиц форматирования выше, когда эти параметры используются в качестве входных значений; в этом случае они должны соответствовать тому, что указано для соответствующей единицы форматирования.272273Для успешного преобразования объект *arg* должен соответствовать формату, и формат должен быть исчерпан. При успехе функции `PyArg_Parse*` возвращают true, в противном случае они возвращают false и возбуждают соответствующее исключение. Когда функции `PyArg_Parse*` завершаются ошибкой из-за неудачи преобразования в одной из единиц форматирования, переменные по адресам, соответствующим этой и последующим единицам форматирования, остаются нетронутыми.274275### API функции276277#### `int PyArg_ParseTuple(PyObject *args, const char *format, ...)`278279*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*280281Разбирает параметры функции, принимающей только позиционные параметры, в локальные переменные. Возвращает true при успехе; при неудаче возвращает false и возбуждает соответствующее исключение.282283#### `int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)`284285*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*286287Идентична [`PyArg_ParseTuple()`](https://python-all.ru/3.15/c-api/arg.html#c.PyArg_ParseTuple), за исключением того, что принимает va\_list вместо переменного числа аргументов.288289#### `int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, ...)`290291*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*292293Разбирает параметры функции, принимающей как позиционные, так и ключевые параметры, в локальные переменные. Аргумент *keywords* представляет собой массив имен ключевых параметров, завершающийся `NULL`, заданных в виде строк C, закодированных в ASCII или UTF-8 с нулевым завершением. Пустые имена обозначают [только позиционные параметры](https://python-all.ru/3.15/glossary.html#positional-only-parameter). Возвращает true при успехе; при неудаче возвращает false и возбуждает соответствующее исключение.294295> **Примечание**296>297> Объявление параметра *keywords* – это char \*const\* в C и const char \*const\* в C++. Это можно переопределить с помощью макроса [`PY_CXX_CONST`](https://python-all.ru/3.15/c-api/arg.html#c.PY_CXX_CONST).298299Изменено в версии 3.6: Добавлена поддержка [только позиционных параметров](https://python-all.ru/3.15/glossary.html#positional-only-parameter).300301Изменено в версии 3.13: Параметр *keywords* теперь имеет тип char \*const\* в C и const char \*const\* в C++, вместо char\*\*. Добавлена поддержка имен не-ASCII для параметров-ключевых слов.302303#### `int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, va_list vargs)`304305*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*306307Идентична [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.15/c-api/arg.html#c.PyArg_ParseTupleAndKeywords), но принимает va\_list вместо переменного числа аргументов.308309#### `int PyArg_ValidateKeywordArguments(PyObject*)`310311*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*312313Гарантирует, что ключи в словаре аргументов-ключевых слов являются строками. Это нужно только в случае, если [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.15/c-api/arg.html#c.PyArg_ParseTupleAndKeywords) не используется, поскольку последняя уже выполняет эту проверку.314315Добавлено в версии 3.2.316317#### `int PyArg_Parse(PyObject *args, const char *format, ...)`318319*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*320321Разбирает параметр функции, которая принимает один позиционный параметр, в локальную переменную. Возвращает true при успехе; при неудаче возвращает false и возбуждает соответствующее исключение.322323Пример:324325```c326// Функция, использующая соглашение вызова METH_O327static PyObject*328my_function(PyObject *module, PyObject *arg)329{330    int value;331    if (!PyArg_Parse(arg, "i:my_function", &value)) {332        return NULL;333    }334    // ... использовать значение ...335}336```337338#### `int PyArg_ParseArray(PyObject *const *args, Py_ssize_t nargs, const char *format, ...)`339340Разбирает параметры функции, которая принимает только параметры-массивы, в локальные переменные (то есть функцию, использующую соглашение о вызове [`METH_FASTCALL`](https://python-all.ru/3.15/c-api/structures.html#c.METH_FASTCALL)). Возвращает true при успехе; при неудаче возвращает false и возбуждает соответствующее исключение.341342Добавлено в версии 3.15.343344#### `int PyArg_ParseArrayAndKeywords(PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames, const char *format, const char *const *kwlist, ...)`345346Разбирает параметры функции, которая принимает как параметры-массивы, так и ключевые параметры, в локальные переменные (то есть функцию, использующую соглашение о вызове [`METH_FASTCALL`](https://python-all.ru/3.15/c-api/structures.html#c.METH_FASTCALL) `|` [`METH_KEYWORDS`](https://python-all.ru/3.15/c-api/structures.html#c.METH_KEYWORDS)). Возвращает true при успехе; при неудаче возвращает false и возбуждает соответствующее исключение.347348Добавлено в версии 3.15.349350#### `int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)`351352*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*353354Более простая форма извлечения параметров, не использующая строку формата для указания типов аргументов. Функции, использующие этот метод для получения своих параметров, должны быть объявлены как [`METH_VARARGS`](https://python-all.ru/3.15/c-api/structures.html#c.METH_VARARGS) в таблицах функций или методов. Кортеж, содержащий фактические параметры, должен передаваться как *args*; он должен быть именно кортежем. Длина кортежа должна быть не менее *min* и не более *max*; *min* и *max* могут быть равны. Дополнительные аргументы должны передаваться в функцию, каждый из которых должен быть указателем на переменную типа [PyObject](https://python-all.ru/3.15/c-api/structures.html#c.PyObject)\*; они будут заполнены значениями из *args*; они будут содержать [заимствованные ссылки](https://python-all.ru/3.15/glossary.html#term-borrowed-reference). Переменные, соответствующие необязательным параметрам, не заданным в *args*, заполнены не будут; их должен инициализировать вызывающий. Эта функция возвращает true при успехе и false, если *args* не является кортежем или содержит неверное количество элементов; в случае неудачи будет установлено исключение.355356Это пример использования этой функции, взятый из исходных кодов вспомогательного модуля для слабых ссылок `_weakref`:357358```c359static PyObject *360weakref_ref(PyObject *self, PyObject *args)361{362    PyObject *object;363    PyObject *callback = NULL;364    PyObject *result = NULL;365366    if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {367        result = PyWeakref_NewRef(object, callback);368    }369    return result;370}371```372373Вызов [`PyArg_UnpackTuple()`](https://python-all.ru/3.15/c-api/arg.html#c.PyArg_UnpackTuple) в этом примере полностью эквивалентен вызову [`PyArg_ParseTuple()`](https://python-all.ru/3.15/c-api/arg.html#c.PyArg_ParseTuple):374375```c376PyArg_ParseTuple(args, "O|O:ref", &object, &callback)377```378379#### `PY_CXX_CONST`380381Значение, которое должно быть вставлено, если есть, перед char \*const\* в объявлении параметра *keywords* функций [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.15/c-api/arg.html#c.PyArg_ParseTupleAndKeywords) и [`PyArg_VaParseTupleAndKeywords()`](https://python-all.ru/3.15/c-api/arg.html#c.PyArg_VaParseTupleAndKeywords). По умолчанию пусто для C и `const` для C++ (const char \*const\*). Чтобы переопределить, задайте нужное значение перед включением `Python.h`.382383Добавлено в версии 3.13.384385## Построение значений386387#### `PyObject *Py_BuildValue(const char *format, ...)`388389*Возвращаемое значение: новая ссылка.*390391*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*392393Создает новое значение на основе строки формата, аналогичной тем, что принимаются семейством функций `PyArg_Parse*`, и последовательности значений. Возвращает значение или `NULL` в случае ошибки; будет возбуждено исключение, если возвращается `NULL`.394395[`Py_BuildValue()`](https://python-all.ru/3.15/c-api/arg.html#c.Py_BuildValue) не всегда строит кортеж. Он строит кортеж, только если строка формата содержит два или более элемента формата. Если строка формата пуста, возвращается `None`; если она содержит ровно один элемент формата, возвращается объект, описываемый этим элементом. Чтобы принудительно вернуть кортеж размера 0 или 1, заключите строку формата в скобки.396397Когда буферы памяти передаются как параметры для предоставления данных для создания объектов, как для форматов `s` и `s#`, необходимые данные копируются. Буферы, предоставленные вызывающим, никогда не используются напрямую объектами, созданными с помощью [`Py_BuildValue()`](https://python-all.ru/3.15/c-api/arg.html#c.Py_BuildValue). Другими словами, если ваш код вызывает `malloc()` и передает выделенную память в `Py_BuildValue()`, ваш код отвечает за вызов `free()` для этой памяти после того, как `Py_BuildValue()` вернет управление.398399В следующем описании форма в кавычках – это элемент формата; запись в круглых скобках – это тип объекта Python, который вернёт элемент формата; а запись в квадратных скобках – это тип передаваемого(-ых) значения(-ий) C.400401Символы пробела, табуляции, двоеточия и запятой в строках формата игнорируются (но не внутри элементов формата, таких как `s#`). Это можно использовать, чтобы сделать длинные строки формата чуть более читаемыми.402403**`s` ([`str`](https://python-all.ru/3.15/library/stdtypes.html#str) или `None`) \[const char \*\]**404405Преобразует C-строку, завершающуюся нулём, в объект Python [`str`](https://python-all.ru/3.15/library/stdtypes.html#str), используя кодировку `'utf-8'`. Если указатель на C-строку равен `NULL`, используется `None`.406407**`s#` ([`str`](https://python-all.ru/3.15/library/stdtypes.html#str) или `None`) \[const char \*, [`Py_ssize_t`](https://python-all.ru/3.15/c-api/intro.html#c.Py_ssize_t)\]**408409Преобразует C-строку и её длину в объект Python [`str`](https://python-all.ru/3.15/library/stdtypes.html#str), используя кодировку `'utf-8'`. Если указатель на C-строку равен `NULL`, длина игнорируется и возвращается `None`.410411**`y` ([`bytes`](https://python-all.ru/3.15/library/stdtypes.html#bytes)) \[const char \*\]**412413Преобразует C-строку в объект Python [`bytes`](https://python-all.ru/3.15/library/stdtypes.html#bytes). Если указатель на C-строку равен `NULL`, возвращается `None`.414415**`y#` ([`bytes`](https://python-all.ru/3.15/library/stdtypes.html#bytes)) \[const char \*, [`Py_ssize_t`](https://python-all.ru/3.15/c-api/intro.html#c.Py_ssize_t)\]**416417Преобразует C-строку и её длину в объект Python. Если указатель на C-строку равен `NULL`, возвращается `None`.418419**`z` ([`str`](https://python-all.ru/3.15/library/stdtypes.html#str) или `None`) \[const char \*\]**420421То же, что и `s`.422423**`z#` ([`str`](https://python-all.ru/3.15/library/stdtypes.html#str) или `None`) \[const char \*, [`Py_ssize_t`](https://python-all.ru/3.15/c-api/intro.html#c.Py_ssize_t)\]**424425То же, что и `s#`.426427**`u` ([`str`](https://python-all.ru/3.15/library/stdtypes.html#str)) \[const wchar\_t \*\]**428429Преобразует буфер `wchar_t` данных Unicode (UTF-16 или UCS-4), завершающийся нулём, в объект Python Unicode. Если указатель на буфер Unicode равен `NULL`, возвращается `None`.430431**`u#` ([`str`](https://python-all.ru/3.15/library/stdtypes.html#str)) \[const wchar\_t \*, [`Py_ssize_t`](https://python-all.ru/3.15/c-api/intro.html#c.Py_ssize_t)\]**432433Преобразует буфер данных Unicode (UTF-16 или UCS-4) и его длину в объект Python Unicode. Если указатель на буфер Unicode равен `NULL`, длина игнорируется и возвращается `None`.434435**`U` ([`str`](https://python-all.ru/3.15/library/stdtypes.html#str) или `None`) \[const char \*\]**436437То же, что и `s`.438439**`U#` ([`str`](https://python-all.ru/3.15/library/stdtypes.html#str) или `None`) \[const char \*, [`Py_ssize_t`](https://python-all.ru/3.15/c-api/intro.html#c.Py_ssize_t)\]**440441То же, что и `s#`.442443**`i` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[int\]**444445Преобразует обычный C int в объект Python целого типа.446447**`b` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[char\]**448449Преобразует обычный C char в объект Python целого типа.450451**`h` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[short int\]**452453Преобразует обычный C short int в объект Python целого типа.454455**`l` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[long int\]**456457Преобразует C long int в объект Python целого типа.458459**`B` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[unsigned char\]**460461Преобразует C unsigned char в объект Python целого типа.462463**`H` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[unsigned short int\]**464465Преобразует C unsigned short int в объект Python целого числа.466467**`I` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[unsigned int\]**468469Преобразует C unsigned int в объект Python целого числа.470471**`k` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[unsigned long\]**472473Преобразует C unsigned long в объект Python целого числа.474475**`L` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[long long\]**476477Преобразует C long long в объект Python целого числа.478479**`K` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[unsigned long long\]**480481Преобразует C unsigned long long в объект Python целого числа.482483**`n` ([`int`](https://python-all.ru/3.15/library/functions.html#int)) \[[`Py_ssize_t`](https://python-all.ru/3.15/c-api/intro.html#c.Py_ssize_t)\]**484485Преобразует C [`Py_ssize_t`](https://python-all.ru/3.15/c-api/intro.html#c.Py_ssize_t) в целое число Python.486487**`p` ([`bool`](https://python-all.ru/3.15/library/functions.html#bool)) \[int\]**488489Преобразует C int в объект Python [`bool`](https://python-all.ru/3.15/library/functions.html#bool).490491Имейте в виду, что для этого формата требуется аргумент `int`. В отличие от большинства других контекстов в C, вариативные аргументы не приводятся автоматически к подходящему типу. Другой тип (например, указатель или число с плавающей запятой) можно преобразовать в подходящее значение `int` с помощью `(x) ? 1 : 0` или `!!x`.492493Добавлено в версии 3.14.494495**`c` ([`bytes`](https://python-all.ru/3.15/library/stdtypes.html#bytes) длины 1) \[char\]**496497Преобразует C int, представляющий байт, в объект Python [`bytes`](https://python-all.ru/3.15/library/stdtypes.html#bytes) длины 1.498499**`C` ([`str`](https://python-all.ru/3.15/library/stdtypes.html#str) длины 1) \[int\]**500501Преобразует C int, представляющий символ, в объект Python [`str`](https://python-all.ru/3.15/library/stdtypes.html#str) длины 1.502503**`d` ([`float`](https://python-all.ru/3.15/library/functions.html#float)) \[double\]**504505Преобразует C double в число с плавающей запятой Python.506507**`f` ([`float`](https://python-all.ru/3.15/library/functions.html#float)) \[float\]**508509Преобразует C float в число с плавающей запятой Python.510511**`D` ([`complex`](https://python-all.ru/3.15/library/functions.html#complex)) \[Py\_complex \*\]**512513Преобразует структуру C [`Py_complex`](https://python-all.ru/3.15/c-api/complex.html#c.Py_complex) в комплексное число Python.514515**`O` (объект) \[PyObject \*\]**516517Передаёт объект Python без изменений, но создаёт новую [сильную ссылку](https://python-all.ru/3.15/glossary.html#term-strong-reference) на него (т.е. его счётчик ссылок увеличивается на единицу). Если переданный объект является указателем `NULL`, предполагается, что это произошло потому, что вызов, создавший аргумент, обнаружил ошибку и установил исключение. Поэтому [`Py_BuildValue()`](https://python-all.ru/3.15/c-api/arg.html#c.Py_BuildValue) вернёт `NULL`, но не вызовет исключение. Если ещё не было установлено исключение, устанавливается [`SystemError`](https://python-all.ru/3.15/library/exceptions.html#SystemError).518519**`S` (объект) \[PyObject \*\]**520521То же, что и `O`.522523**`N` (объект) \[PyObject \*\]**524525То же, что и `O`, за исключением того, что не создаёт новую [сильную ссылку](https://python-all.ru/3.15/glossary.html#term-strong-reference). Полезно, когда объект создаётся вызовом конструктора объекта в списке аргументов.526527**`O&` (object) \[*конвертер*, *что угодно*\]**528529Преобразует *любой объект* в объект Python с помощью *функции-преобразователя*. Функция вызывается с *любым объектом* (который должен быть совместим с void\*) в качестве аргумента и должна вернуть «новый» объект Python или `NULL` в случае ошибки.530531**`(items)` ([`tuple`](https://python-all.ru/3.15/library/stdtypes.html#tuple)) \[*соответствующие элементы*\]**532533Преобразует последовательность значений C в кортеж Python с тем же количеством элементов.534535**`[items]` ([`list`](https://python-all.ru/3.15/library/stdtypes.html#list)) \[*соответствующие элементы*\]**536537Преобразует последовательность значений C в список Python с тем же количеством элементов.538539**`{items}` ([`dict`](https://python-all.ru/3.15/library/stdtypes.html#dict)) \[*соответствующие элементы*\]**540541Преобразует последовательность значений C в словарь Python. Каждая пара последовательных значений C добавляет один элемент в словарь, выступая в роли ключа и значения соответственно.542543Если в строке формата есть ошибка, устанавливается исключение [`SystemError`](https://python-all.ru/3.15/library/exceptions.html#SystemError) и возвращается `NULL`.544545#### `PyObject *Py_VaBuildValue(const char *format, va_list vargs)`546547*Возвращаемое значение: новая ссылка.*548549*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*550551Идентична [`Py_BuildValue()`](https://python-all.ru/3.15/c-api/arg.html#c.Py_BuildValue), за исключением того, что принимает va\_list вместо переменного числа аргументов.552