intro.md
1> **Источник:** https://python-all.ru/3.13/c-api/intro.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Введение89Интерфейс прикладного программирования Python предоставляет программистам на C и C++ доступ к интерпретатору Python на различных уровнях. API одинаково пригоден для использования из C++, но для краткости его обычно называют Python/C API. Есть две принципиально разные причины для использования Python/C API. Первая – написание *модулей расширения* для конкретных целей; это модули на C, которые расширяют интерпретатор Python. Вероятно, это наиболее распространённое применение. Вторая – использование Python как компонента в более крупном приложении; этот метод обычно называют *встраиванием* Python в приложение.1011Написание модуля расширения – относительно хорошо понятный процесс, где хорошо работает подход «кулинарной книги» (cookbook). Существует несколько инструментов, которые в некоторой степени автоматизируют этот процесс. Хотя Python встраивали в другие приложения с самого начала его существования, процесс встраивания Python менее прямолинейный, чем написание расширения.1213Многие функции API полезны независимо от того, встраивается Python или расширяется; более того, большинство приложений, встраивающих Python, также должны предоставлять собственное расширение, поэтому, вероятно, стоит ознакомиться с написанием расширения, прежде чем пытаться встроить Python в реальное приложение.1415## Стандарты кодирования1617При написании кода на C для включения в CPython **необходимо** следовать рекомендациям и стандартам, определённым в [**PEP 7**](https://python-all.ru/3.13/c-api/intro.html). Эти рекомендации действуют независимо от версии Python, в которую вносится вклад. Следование этим соглашениям не обязательно для собственных сторонних модулей расширения, если не планируется в конечном счёте передать их в Python.1819## Заголовочные файлы2021Все определения функций, типов и макросов, необходимые для использования Python/C API, включаются в код с помощью следующей строки:2223```c24#define PY_SSIZE_T_CLEAN25#include <Python.h>26```2728Это подразумевает включение следующих стандартных заголовочных файлов: `<stdio.h>`, `<string.h>`, `<errno.h>`, `<limits.h>`, `<assert.h>` и `<stdlib.h>` (если доступны).2930> **Примечание**31>32> Поскольку Python может определять некоторые директивы препроцессора, которые влияют на стандартные заголовочные файлы в некоторых системах, *необходимо* включать `Python.h` до того, как будут включены любые стандартные заголовочные файлы.33>34> Рекомендуется всегда определять `PY_SSIZE_T_CLEAN` перед включением `Python.h`. См. [Разбор аргументов и создание значений](https://python-all.ru/3.13/c-api/arg.html#arg-parsing) для описания этого макроса.3536Все видимые пользователю имена, определённые Python.h (кроме тех, что определены включёнными стандартными заголовками), имеют один из префиксов `Py` или `_Py`. Имена, начинающиеся с `_Py`, предназначены для внутреннего использования реализацией Python и не должны использоваться разработчиками расширений. Имена членов структур не имеют зарезервированного префикса.3738> **Примечание**39>40> Пользовательский код никогда не должен определять имена, начинающиеся с `Py` или `_Py`. Это сбивает с толку читателя и ставит под угрозу переносимость пользовательского кода на будущие версии Python, которые могут определять дополнительные имена, начинающиеся с одного из этих префиксов.4142Заголовочные файлы обычно устанавливаются вместе с Python. В Unix они находятся в каталогах `prefix/include/pythonversion/` и `exec_prefix/include/pythonversion/`, где [`prefix`](https://python-all.ru/3.13/using/configure.html#cmdoption-prefix) и [`exec_prefix`](https://python-all.ru/3.13/using/configure.html#cmdoption-exec-prefix) определяются соответствующими параметрами сценария **configure** Python, а *version* – `'%d.%d' % sys.version_info[:2]`. В Windows заголовочные файлы устанавливаются в `prefix/include`, где `prefix` – каталог установки, указанный в программе установки.4344Чтобы включить заголовочные файлы, поместите оба каталога (если они разные) в путь поиска include компилятора. *Не* помещайте родительские каталоги в путь поиска, а затем используйте `#include <pythonX.Y/Python.h>`; это нарушит сборку на нескольких платформах, поскольку независимые от платформы заголовочные файлы в [`prefix`](https://python-all.ru/3.13/using/configure.html#cmdoption-prefix) включают специфичные для платформы заголовочные файлы из [`exec_prefix`](https://python-all.ru/3.13/using/configure.html#cmdoption-exec-prefix).4546Пользователям C++ следует отметить, что, хотя API полностью определён с использованием C, заголовочные файлы правильно объявляют точки входа как `extern "C"`. В результате нет необходимости делать что-то особенное для использования API из C++.4748## Полезные макросы4950В заголовочных файлах Python определено несколько полезных макросов. Многие из них находятся рядом с местом применения (например, [`Py_RETURN_NONE`](https://python-all.ru/3.13/c-api/none.html#c.Py_RETURN_NONE)). Макросы более общего назначения приведены здесь. Это не обязательно полный перечень.5152#### `PyMODINIT_FUNC`5354Объявляет функцию инициализации модуля расширения `PyInit`. Тип возвращаемого значения – [PyObject](https://python-all.ru/3.13/c-api/structures.html#c.PyObject)\*. Макрос объявляет все необходимые для платформы специальные объявления компоновки, а для C++ объявляет функцию как `extern "C"`.5556Имя функции инициализации должно быть `PyInit_name`, где *name* – это имя модуля. Она должна быть единственным элементом в файле модуля, не являющимся `static`. Пример:5758```c59static struct PyModuleDef spam_module = {60 .m_base = PyModuleDef_HEAD_INIT,61 .m_name = "spam",62 ...63};6465PyMODINIT_FUNC66PyInit_spam(void)67{68 return PyModuleDef_Init(&spam_module);69}70```7172#### `Py_ABS(x)`7374Возвращает абсолютное значение `x`.7576Если результат не может быть представлен (например, если `x` имеет значение `INT_MIN` для типа int), поведение не определено.7778Добавлено в версии 3.3.7980#### `Py_ALIGNED(num)`8182Задают выравнивание на *num* байтов в компиляторах, которые это поддерживают.8384Рекомендуется использовать спецификатор `_Alignas` из стандарта C11 вместо этого макроса.8586#### `Py_ARITHMETIC_RIGHT_SHIFT(type, integer, positions)`8788Подобно `integer >> positions`, но принудительно выполняет знаковое расширение, поскольку стандарт C не определяет, будет ли сдвиг вправо знакового целого числа выполнять знаковое расширение или заполнение нулями.8990*integer* должен быть любым знаковым целым типом. *positions* – количество позиций для сдвига вправо.9192И *integer*, и *positions* могут вычисляться более одного раза; поэтому избегайте прямой передачи вызова функции или другой операции с побочными эффектами в этот макрос. Вместо этого сохраните результат в переменную и затем передайте его.9394*type* не используется и сохранён только для обратной совместимости. Исторически *type* использовался для приведения *integer*.9596Изменено в версии 3.1: Этот макрос теперь действителен для всех знаковых целых типов, а не только тех, для которых `unsigned type` допустим. В результате *type* больше не используется.9798#### `Py_ALWAYS_INLINE`99100Предлагает компилятору всегда встраивать статическую встраиваемую функцию. Компилятор может проигнорировать это и решить не встраивать функцию.101102Его можно использовать для встраивания критичных по производительности статических встраиваемых функций при сборке Python в режиме отладки с отключённым встраиванием функций. Например, MSC отключает встраивание функций при сборке в режиме отладки.103104Слепое пометивание статической встраиваемой функции макросом Py\_ALWAYS\_INLINE может привести к ухудшению производительности (например, из-за увеличения размера кода). Компилятор обычно умнее разработчика в анализе затрат и выгод.105106Если Python [собран в режиме отладки](https://python-all.ru/3.13/using/configure.html#debug-build) (если определён макрос [`Py_DEBUG`](https://python-all.ru/3.13/c-api/intro.html#c.Py_DEBUG)), макрос [`Py_ALWAYS_INLINE`](https://python-all.ru/3.13/c-api/intro.html#c.Py_ALWAYS_INLINE) ничего не делает.107108Он должен быть указан перед типом возвращаемого значения функции. Использование:109110```c111static inline Py_ALWAYS_INLINE int random(void) { return 4; }112```113114Добавлено в версии 3.12.115116#### `Py_CAN_START_THREADS`117118Если этот макрос определён, то текущая система может запускать потоки.119120В настоящее время все системы, поддерживаемые CPython (согласно [**PEP 11**](https://python-all.ru/3.13/c-api/intro.html)), за исключением некоторых платформ WebAssembly, поддерживают запуск потоков.121122Добавлено в версии 3.13.123124#### `Py_CHARMASK(c)`125126Аргумент должен быть символом или целым числом в диапазоне \[-128, 127\] или \[0, 255\]. Этот макрос возвращает `c`, приведённый к `unsigned char`.127128#### `Py_DEPRECATED(version)`129130Используется для объявлений устаревших элементов. Макрос должен располагаться перед именем символа.131132Пример:133134```c135Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);136```137138Изменено в версии 3.8: добавлена поддержка MSVC.139140#### `Py_FORCE_EXPANSION(X)`141142Это эквивалентно `X`, что полезно для склеивания токенов в макросах, так как раскрытие макросов в *X* принудительно вычисляется препроцессором.143144#### `Py_GCC_ATTRIBUTE(name)`145146Использует атрибут GCC *name*, скрывая его от компиляторов, не поддерживающих атрибуты GCC (например, MSVC).147148Этот макрос раскрывается в `__attribute__((name))` в компиляторе GCC и ни во что не раскрывается в компиляторах, не поддерживающих атрибуты GCC.149150#### `Py_GETENV(s)`151152Подобен `getenv(s)`, но возвращает `NULL`, если [`-E`](https://python-all.ru/3.13/using/cmdline.html#cmdoption-E) был передан в командной строке (см. [`PyConfig.use_environment`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.use_environment)).153154#### `Py_LL(number)`155156Используйте *number* как целочисленный литерал `long long`.157158Обычно раскрывается в *number*, за которым следует `LL`, но на старых компиляторах может раскрываться в некоторые специфичные для компилятора суффиксы (например, `I64`).159160В современных версиях Python этот макрос не очень полезен, поскольку C99 и более поздние стандарты требуют, чтобы суффикс `LL` был допустимым для целого числа.161162#### `Py_LOCAL(type)`163164Объявляет функцию, возвращающую указанный *тип*, с квалификатором быстрого вызова для функций, локальных для текущего файла. Семантически это эквивалентно `static type`.165166#### `Py_LOCAL_INLINE(type)`167168Эквивалентно [`Py_LOCAL`](https://python-all.ru/3.13/c-api/intro.html#c.Py_LOCAL), но дополнительно требует встраивания функции.169170#### `Py_LOCAL_SYMBOL`171172Макрос, используемый для объявления символа как локального для общей библиотеки (скрытого). На поддерживаемых платформах гарантирует, что символ не экспортируется.173174В совместимых версиях GCC/Clang раскрывается в `__attribute__((visibility("hidden")))`.175176#### `Py_MAX(x, y)`177178Возвращает максимум из `x` и `y`.179180Добавлено в версии 3.3.181182#### `Py_MEMBER_SIZE(type, member)`183184Возвращает размер структуры (`type`) `member` в байтах.185186Добавлено в версии 3.6.187188#### `Py_MIN(x, y)`189190Возвращает минимальное значение между `x` и `y`.191192Добавлено в версии 3.3.193194#### `Py_NO_INLINE`195196Отключает встраивание функции. Например, это уменьшает потребление стека C: полезно при сборках с LTO+PGO, которые активно встраивают код (см. [bpo-33720](https://python-all.ru/3.13/c-api/intro.html)).197198Использование:199200```c201Py_NO_INLINE static int random(void) { return 4; }202```203204Добавлено в версии 3.12.205206#### `Py_SAFE_DOWNCAST(value, larger, smaller)`207208Приводит *value* к типу *smaller* из типа *larger*, проверяя, что ни одна информация не была потеряна.209210В релизных сборках Python это примерно эквивалентно `(smaller) value` (в C++ вместо него будет использоваться `static_cast<smaller>(value)`).211212В отладочных сборках (подразумевая, что определён [`Py_DEBUG`](https://python-all.ru/3.13/c-api/intro.html#c.Py_DEBUG)) это утверждает, что при приведении от *larger* к *smaller* не было потеряно информации.213214*value*, *larger* и *smaller* могут вычисляться более одного раза в выражении; поэтому не передавайте в этот макрос напрямую выражение с побочными эффектами.215216#### `Py_STRINGIFY(x)`217218Преобразует `x` в C-строку. Например, `Py_STRINGIFY(123)` возвращает `"123"`.219220Добавлено в версии 3.4.221222#### `Py_ULL(number)`223224Похож на [`Py_LL`](https://python-all.ru/3.13/c-api/intro.html#c.Py_LL), но *number* будет литералом `unsigned long long`. Это делается добавлением `U` к результату `Py_LL`.225226В современных версиях Python этот макрос не очень полезен, так как C99 и более поздние стандарты требуют, чтобы суффиксы `ULL`/`LLU` были допустимы для целого числа.227228#### `Py_UNREACHABLE()`229230Используйте этот макрос, когда есть путь выполнения, который по замыслу не может быть достигнут. Например, в ветке `default:` оператора `switch`, для которого все возможные значения покрыты ветками `case`. Используйте его в местах, где вы могли бы попытаться поместить вызов `assert(0)` или `abort()`.231232В релизном режиме макрос помогает компилятору оптимизировать код и избегает предупреждения о недостижимом коде. Например, макрос реализован с помощью `__builtin_unreachable()` в GCC в релизном режиме.233234Одно из применений `Py_UNREACHABLE()` – после вызова функции, которая никогда не возвращает управление, но не объявлена как `_Py_NO_RETURN`.235236Если путь выполнения является крайне маловероятным, но может быть достигнут в исключительных случаях, этот макрос использовать нельзя. Например, при нехватке памяти или если системный вызов возвращает значение за пределами ожидаемого диапазона. В этом случае лучше сообщить об ошибке вызывающему коду. Если ошибка не может быть сообщена вызывающему коду, можно использовать [`Py_FatalError()`](https://python-all.ru/3.13/c-api/sys.html#c.Py_FatalError).237238Добавлено в версии 3.7.239240#### `Py_UNUSED(arg)`241242Используется для неиспользуемых аргументов в определении функции, чтобы подавить предупреждения компилятора. Пример: `int func(int a, int Py_UNUSED(b)) { return a; }`.243244Добавлено в версии 3.4.245246#### `Py_BUILD_ASSERT(cond)`247248Утверждает условие времени компиляции *cond* в виде инструкции. Сборка завершится ошибкой, если условие ложно или не может быть вычислено во время компиляции.249250Например:251252```c253Py_BUILD_ASSERT(sizeof(PyTime_t) == sizeof(int64_t));254```255256Добавлено в версии 3.3.257258#### `Py_BUILD_ASSERT_EXPR(cond)`259260Asserts a compile-time condition *cond*, as an expression that evaluates to `0`. The build will fail if the condition is false or cannot be evaluated at compile time.261262Например:263264```c265#define foo_to_char(foo) \266 ((char *)(foo) + Py_BUILD_ASSERT_EXPR(offsetof(struct foo, string) == 0))267```268269Добавлено в версии 3.3.270271#### `PyDoc_STRVAR(name, str)`272273Создаёт переменную с именем *name*, которую можно использовать в строках документации. Если Python собран без строк документации, значение будет пустым.274275Используйте [`PyDoc_STRVAR`](https://python-all.ru/3.13/c-api/intro.html#c.PyDoc_STRVAR) для строк документации, чтобы поддерживать сборку Python без строк документации, как указано в [**PEP 7**](https://python-all.ru/3.13/c-api/intro.html).276277Пример:278279```c280PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element.");281282static PyMethodDef deque_methods[] = {283 // ...284 {"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},285 // ...286}287```288289#### `PyDoc_STR(str)`290291Создаёт строку документации для заданной входной строки или пустую строку, если строки документации отключены.292293Используйте [`PyDoc_STR`](https://python-all.ru/3.13/c-api/intro.html#c.PyDoc_STR) при указании строк документации, чтобы поддерживать сборку Python без строк документации, как указано в [**PEP 7**](https://python-all.ru/3.13/c-api/intro.html).294295Пример:296297```c298static PyMethodDef pysqlite_row_methods[] = {299 {"keys", (PyCFunction)pysqlite_row_keys, METH_NOARGS,300 PyDoc_STR("Returns the keys of the row.")},301 {NULL, NULL}302};303```304305#### `PyDoc_VAR(name)`306307Объявляет статическую переменную-массив символов с заданным именем *name*.308309Например:310311```c312PyDoc_VAR(python_doc) = PyDoc_STR("A genus of constricting snakes in the Pythonidae family native "313 "to the tropics and subtropics of the Eastern Hemisphere.");314```315316#### `Py_ARRAY_LENGTH(array)`317318Вычисляет длину статически выделенного C-массива во время компиляции.319320Аргумент *array* должен быть C-массивом с размером, известным на этапе компиляции. Передача массива с неизвестным размером, например, выделенного в куче, приведёт к ошибке компиляции в некоторых компиляторах или даст неверные результаты.321322Это примерно эквивалентно:323324```c325sizeof(array) / sizeof((array)[0])326```327328#### `Py_EXPORTED_SYMBOL`329330Макрос, используемый для объявления символа (функции или данных) как экспортируемого. В Windows раскрывается в `__declspec(dllexport)`. В совместимых версиях GCC/Clang раскрывается в `__attribute__((visibility("default")))`. Этот макрос предназначен для определения самого C API; модули расширения не должны его использовать.331332#### `Py_IMPORTED_SYMBOL`333334Макрос, используемый для объявления символа как импортируемого. В Windows раскрывается в `__declspec(dllimport)`. Этот макрос предназначен для определения самого C API; модули расширения не должны его использовать.335336#### `PyAPI_FUNC(type)`337338Макрос, используемый CPython для объявления функции как части C API. Его раскрытие зависит от платформы и конфигурации сборки. Этот макрос предназначен для определения самого C API CPython; модули расширения не должны использовать его для своих собственных символов.339340#### `PyAPI_DATA(type)`341342Макрос, используемый CPython для объявления публичной глобальной переменной как части C API. Его раскрытие зависит от платформы и конфигурации сборки. Этот макрос предназначен для определения самого C API CPython; модули расширения не должны использовать его для своих собственных символов.343344#### `Py_VA_COPY`345346Это [мягко устаревший](https://python-all.ru/3.13/glossary.html#term-soft-deprecated) псевдоним для функции C99 `va_copy`.347348Исторически для копирования `va_list` использовался метод, зависящий от конкретного компилятора.349350Изменено в версии 3.6: Теперь это псевдоним для `va_copy`.351352## Объекты, типы и счетчики ссылок353354Большинство функций Python/C API имеют один или несколько аргументов, а также возвращаемое значение типа [PyObject](https://python-all.ru/3.13/c-api/structures.html#c.PyObject)\*. Этот тип является указателем на непрозрачный тип данных, представляющий произвольный объект Python. Поскольку все типы объектов Python обрабатываются одинаково в большинстве ситуаций (например, присваивание, правила области видимости и передача аргументов), вполне уместно, чтобы они представлялись одним типом C. Почти все объекты Python живут в куче: никогда не объявляются автоматические или статические переменные типа [`PyObject`](https://python-all.ru/3.13/c-api/structures.html#c.PyObject), можно объявлять только переменные-указатели типа PyObject\*. Единственным исключением являются объекты типа; поскольку они никогда не должны освобождаться, они обычно являются статическими объектами [`PyTypeObject`](https://python-all.ru/3.13/c-api/type.html#c.PyTypeObject).355356Все объекты Python (даже целые числа Python) имеют *тип* и *счетчик ссылок*. Тип объекта определяет, что это за объект (например, целое число, список или пользовательская функция; существует гораздо больше типов, как описано в [Стандартная иерархия типов](https://python-all.ru/3.13/reference/datamodel.html#types)). Для каждого из известных типов существует макрос, проверяющий, является ли объект объектом этого типа; например, `PyList_Check(a)` истинно тогда и только тогда, когда объект, на который указывает *a*, является списком Python.357358### Счетчики ссылок359360Счетчик ссылок важен, потому что современные компьютеры имеют конечный (и часто сильно ограниченный) размер памяти; он подсчитывает, сколько различных мест имеют [сильную ссылку](https://python-all.ru/3.13/glossary.html#term-strong-reference) на объект. Таким местом может быть другой объект, глобальная (или статическая) переменная C или локальная переменная в какой-либо функции C. Когда последняя сильная ссылка на объект освобождается (т.е. его счетчик ссылок становится нулевым), объект освобождается. Если он содержит ссылки на другие объекты, эти ссылки освобождаются. Эти другие объекты могут быть освобождены в свою очередь, если на них больше нет ссылок, и так далее. (Здесь очевидна проблема с объектами, ссылающимися друг на друга; на данный момент решение – «не делайте так».)361362Счетчики ссылок всегда изменяются явным образом. Обычный способ – использовать макрос [`Py_INCREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_INCREF) для получения новой ссылки на объект (т.е. увеличить его счетчик ссылок на единицу) и [`Py_DECREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_DECREF) для освобождения этой ссылки (т.е. уменьшить счетчик ссылок на единицу). Макрос `Py_DECREF()` значительно сложнее, чем макрос incref, поскольку он должен проверять, не стал ли счетчик ссылок нулевым, и затем вызывать деаллокатор объекта. Деаллокатор – это указатель на функцию, содержащийся в структуре типа объекта. Деаллокатор, специфичный для типа, отвечает за освобождение ссылок на другие объекты, содержащиеся в объекте, если это составной тип объекта (например, список), а также за выполнение любой дополнительной финализации, которая требуется. Нет возможности переполнения счетчика ссылок; для хранения счетчика ссылок используется по крайней мере столько битов, сколько существует различных ячеек памяти в виртуальной памяти (при условии `sizeof(Py_ssize_t) >= sizeof(void*)`). Таким образом, увеличение счетчика ссылок – простая операция.363364Нет необходимости удерживать [сильную ссылку](https://python-all.ru/3.13/glossary.html#term-strong-reference) (т.е. увеличивать счетчик ссылок) для каждой локальной переменной, содержащей указатель на объект. Теоретически счетчик ссылок объекта увеличивается на единицу, когда переменная начинает указывать на него, и уменьшается на единицу, когда переменная выходит из области видимости. Однако эти два действия компенсируют друг друга, поэтому в итоге счетчик ссылок не меняется. Единственная реальная причина использовать счетчик ссылок – предотвратить освобождение объекта, пока наша переменная указывает на него. Если мы знаем, что существует по крайней мере одна другая ссылка на объект, которая живет как минимум столько же, сколько наша переменная, нет необходимости временно получать новую сильную ссылку (т.е. увеличивать счетчик ссылок). Важная ситуация, в которой это возникает, – объекты, передаваемые в качестве аргументов функциям C в модуле расширения, которые вызываются из Python; механизм вызова гарантирует удержание ссылки на каждый аргумент на время вызова.365366Однако распространенная ошибка – извлечь объект из списка и удерживать его некоторое время, не получая новую ссылку. Какая-нибудь другая операция может удалить объект из списка, освободив эту ссылку, и, возможно, освободить его. Реальная опасность в том, что безобидные на первый взгляд операции могут вызвать произвольный код Python, который способен это сделать; существует путь выполнения, который позволяет управлению вернуться к пользователю из [`Py_DECREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_DECREF), поэтому практически любая операция потенциально опасна.367368Безопасный подход – всегда использовать обобщенные операции (функции, имя которых начинается с `PyObject_`, `PyNumber_`, `PySequence_` или `PyMapping_`). Эти операции всегда создают новую [сильную ссылку](https://python-all.ru/3.13/glossary.html#term-strong-reference) (т.е. увеличивают счетчик ссылок) возвращаемого объекта. Это возлагает на вызывающего обязанность вызвать [`Py_DECREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_DECREF), когда он закончит работу с результатом; это быстро входит в привычку.369370#### Подробности о счетчиках ссылок371372Поведение функций Python/C API в отношении счетчиков ссылок лучше всего объяснять в терминах *владения ссылками*. Владение относится к ссылкам, никогда к объектам (объектами не владеют: они всегда разделяются). «Владение ссылкой» означает ответственность за вызов Py\_DECREF для нее, когда ссылка больше не нужна. Владение также может передаваться, что означает, что код, получающий владение ссылкой, становится ответственным за ее освобождение путем вызова [`Py_DECREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_DECREF) или [`Py_XDECREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_XDECREF), когда она больше не нужна, или за передачу этой ответственности дальше (обычно своему вызывающему). Когда функция передает владение ссылкой своему вызывающему, говорят, что вызывающий получает *новую* ссылку. Когда владение не передается, говорят, что вызывающий *заимствует* ссылку. Для [заимствованной ссылки](https://python-all.ru/3.13/glossary.html#term-borrowed-reference) ничего делать не нужно.373374И наоборот, когда вызывающая функция передает ссылку на объект, есть две возможности: функция *крадет* ссылку на объект или нет.375376*Кража ссылки* означает, что при передаче ссылки функции эта функция предполагает, что теперь она владеет этой ссылкой. Поскольку новый владелец может использовать `Py_DECREF()` по своему усмотрению, вызывающий не должен использовать эту ссылку после вызова.377378Немногие функции крадут ссылки; двумя заметными исключениями являются [`PyList_SetItem()`](https://python-all.ru/3.13/c-api/list.html#c.PyList_SetItem) и [`PyTuple_SetItem()`](https://python-all.ru/3.13/c-api/tuple.html#c.PyTuple_SetItem), которые крадут ссылку на элемент (но не на кортеж или список, в который помещается элемент!). Эти функции были спроектированы так, чтобы красть ссылку из-за распространенного идиоматического приема заполнения кортежа или списка только что созданными объектами; например, код для создания кортежа `(1, 2, "three")` может выглядеть так (пока забывая об обработке ошибок; лучший способ написать это показан ниже):379380```c381PyObject *t;382383t = PyTuple_New(3);384PyTuple_SetItem(t, 0, PyLong_FromLong(1L));385PyTuple_SetItem(t, 1, PyLong_FromLong(2L));386PyTuple_SetItem(t, 2, PyUnicode_FromString("three"));387```388389Здесь [`PyLong_FromLong()`](https://python-all.ru/3.13/c-api/long.html#c.PyLong_FromLong) возвращает новую ссылку, которая немедленно крадется [`PyTuple_SetItem()`](https://python-all.ru/3.13/c-api/tuple.html#c.PyTuple_SetItem). Если требуется продолжать использовать объект, хотя ссылка на него будет украдена, используйте [`Py_INCREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_INCREF), чтобы получить другую ссылку перед вызовом функции, крадущей ссылки.390391Кстати, [`PyTuple_SetItem()`](https://python-all.ru/3.13/c-api/tuple.html#c.PyTuple_SetItem) – это *единственный* способ задать элементы кортежа. [`PySequence_SetItem()`](https://python-all.ru/3.13/c-api/sequence.html#c.PySequence_SetItem) и [`PyObject_SetItem()`](https://python-all.ru/3.13/c-api/object.html#c.PyObject_SetItem) отказываются это делать, поскольку кортежи – неизменяемый тип данных. Используйте `PyTuple_SetItem()` только для кортежей, которые создаёте самостоятельно.392393Эквивалентный код для заполнения списка можно написать с помощью [`PyList_New()`](https://python-all.ru/3.13/c-api/list.html#c.PyList_New) и [`PyList_SetItem()`](https://python-all.ru/3.13/c-api/list.html#c.PyList_SetItem).394395Однако на практике эти способы создания и заполнения кортежа или списка используются редко. Существует универсальная функция [`Py_BuildValue()`](https://python-all.ru/3.13/c-api/arg.html#c.Py_BuildValue), которая может создавать большинство распространённых объектов из значений C, управляемая *строкой формата*. Например, два приведённых выше блока кода можно заменить следующим (который также выполняет проверку ошибок):396397```c398PyObject *tuple, *list;399400tuple = Py_BuildValue("(iis)", 1, 2, "three");401list = Py_BuildValue("[iis]", 1, 2, "three");402```403404Гораздо чаще [`PyObject_SetItem()`](https://python-all.ru/3.13/c-api/object.html#c.PyObject_SetItem) и подобные функции используются с элементами, ссылки на которые только заимствуются, например, с аргументами, переданными в функцию. В этом случае их поведение в отношении ссылок гораздо разумнее, поскольку не нужно получать новую ссылку только для того, чтобы отдать её («позволить её украсть»). Например, эта функция устанавливает все элементы списка (фактически любой изменяемой последовательности) в заданный элемент:405406```c407int408set_all(PyObject *target, PyObject *item)409{410 Py_ssize_t i, n;411412 n = PyObject_Length(target);413 if (n < 0)414 return -1;415 for (i = 0; i < n; i++) {416 PyObject *index = PyLong_FromSsize_t(i);417 if (!index)418 return -1;419 if (PyObject_SetItem(target, index, item) < 0) {420 Py_DECREF(index);421 return -1;422 }423 Py_DECREF(index);424 }425 return 0;426}427```428429Ситуация немного отличается для возвращаемых значений функций. Хотя передача ссылки большинству функций не меняет обязанности по владению этой ссылкой, многие функции, возвращающие ссылку на объект, передают владение ссылкой вызывающему. Причина проста: во многих случаях возвращаемый объект создаётся на лету, и полученная ссылка является единственной ссылкой на объект. Поэтому универсальные функции, возвращающие ссылки на объекты, такие как [`PyObject_GetItem()`](https://python-all.ru/3.13/c-api/object.html#c.PyObject_GetItem) и [`PySequence_GetItem()`](https://python-all.ru/3.13/c-api/sequence.html#c.PySequence_GetItem), всегда возвращают новую ссылку (вызывающий становится владельцем ссылки).430431Важно понимать, что владение ссылкой, возвращённой функцией, зависит только от того, какая функция вызывается – *оперение* (тип объекта, переданного в качестве аргумента функции) *не играет роли!* Таким образом, при извлечении элемента из списка с помощью [`PyList_GetItem()`](https://python-all.ru/3.13/c-api/list.html#c.PyList_GetItem) ссылка не переходит во владение – но при получении того же элемента из того же списка с помощью [`PySequence_GetItem()`](https://python-all.ru/3.13/c-api/sequence.html#c.PySequence_GetItem) (которая принимает точно такие же аргументы) возвращённая ссылка переходит во владение.432433Вот пример того, как можно написать функцию, вычисляющую сумму элементов списка целых чисел; один раз с помощью [`PyList_GetItem()`](https://python-all.ru/3.13/c-api/list.html#c.PyList_GetItem), и один раз с помощью [`PySequence_GetItem()`](https://python-all.ru/3.13/c-api/sequence.html#c.PySequence_GetItem).434435```c436long437sum_list(PyObject *list)438{439 Py_ssize_t i, n;440 long total = 0, value;441 PyObject *item;442443 n = PyList_Size(list);444 if (n < 0)445 return -1; /* Не список */446 for (i = 0; i < n; i++) {447 item = PyList_GetItem(list, i); /* Не может завершиться ошибкой */448 if (!PyLong_Check(item)) continue; /* Пропустить нецелые значения */449 value = PyLong_AsLong(item);450 if (value == -1 && PyErr_Occurred())451 /* Целое число слишком велико для C long, выход */452 return -1;453 total += value;454 }455 return total;456}457```458459```c460long461sum_sequence(PyObject *sequence)462{463 Py_ssize_t i, n;464 long total = 0, value;465 PyObject *item;466 n = PySequence_Length(sequence);467 if (n < 0)468 return -1; /* Не имеет длины */469 for (i = 0; i < n; i++) {470 item = PySequence_GetItem(sequence, i);471 if (item == NULL)472 return -1; /* Не последовательность или другая ошибка */473 if (PyLong_Check(item)) {474 value = PyLong_AsLong(item);475 Py_DECREF(item);476 if (value == -1 && PyErr_Occurred())477 /* Целое число слишком велико для C long, выход */478 return -1;479 total += value;480 }481 else {482 Py_DECREF(item); /* Отказ от владения ссылкой */483 }484 }485 return total;486}487```488489### Типы490491Существует ещё несколько типов данных, играющих важную роль в Python/C API; большинство из них – простые типы C, такие как int, long, double и char\*. Некоторые структурные типы используются для описания статических таблиц, в которых перечисляются функции, экспортируемые модулем, или атрибуты данных нового типа объекта, а другой тип используется для описания значения комплексного числа. Они будут рассмотрены вместе с функциями, которые их используют.492493#### `type Py_ssize_t`494495*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*496497Знаковый целочисленный тип, такой что `sizeof(Py_ssize_t) == sizeof(size_t)`. C99 не определяет такой тип напрямую (size\_t – это беззнаковый целочисленный тип). Подробнее см. [**PEP 353**](https://python-all.ru/3.13/c-api/intro.html). `PY_SSIZE_T_MAX` – это наибольшее положительное значение типа [`Py_ssize_t`](https://python-all.ru/3.13/c-api/intro.html#c.Py_ssize_t).498499## Исключения500501Программисту на Python требуется обрабатывать исключения только в тех случаях, когда необходима специфическая обработка ошибок; необработанные исключения автоматически передаются вызывающему, затем вызывающему вызывающего и так далее, пока не достигнут интерпретатора верхнего уровня, где они сообщаются пользователю вместе с трассировкой стека.502503Однако для C-программистов проверка ошибок всегда должна быть явной. Все функции Python/C API могут вызывать исключения, если в документации функции не указано иное. В общем случае, когда функция обнаруживает ошибку, она устанавливает исключение, отбрасывает все принадлежащие ей ссылки на объекты и возвращает индикатор ошибки. Если не задокументировано иное, этот индикатор – либо `NULL`, либо `-1`, в зависимости от типа возвращаемого значения функции. Некоторые функции возвращают логический результат true/false, где false указывает на ошибку. Очень немногие функции не возвращают явного индикатора ошибки или имеют неоднозначное возвращаемое значение и требуют явной проверки на ошибки с помощью [`PyErr_Occurred()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Occurred). Такие исключения всегда явно документируются.504505Состояние исключения хранится в памяти, привязанной к потоку (это эквивалентно использованию глобальной памяти в однопоточном приложении). Поток может находиться в одном из двух состояний: произошло исключение или нет. Функция [`PyErr_Occurred()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Occurred) может использоваться для проверки этого: она возвращает заимствованную ссылку на объект типа исключения, если произошло исключение, и `NULL` в противном случае. Существует ряд функций для установки состояния исключения: [`PyErr_SetString()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_SetString) является наиболее распространённой (хотя и не самой общей) функцией для установки состояния исключения, а [`PyErr_Clear()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Clear) очищает состояние исключения.506507Полное состояние исключения состоит из трёх объектов (все они могут быть `NULL`): типа исключения, соответствующего значения исключения и трассировки стека. Они имеют тот же смысл, что и результат Python `sys.exc_info()`; однако они не одно и то же: объекты Python представляют последнее исключение, обрабатываемое оператором [`try`](https://python-all.ru/3.13/reference/compound_stmts.html#try) … [`except`](https://python-all.ru/3.13/reference/compound_stmts.html#except), в то время как состояние исключения на уровне C существует только пока исключение передаётся между C-функциями, пока не достигнет основного цикла интерпретатора байт-кода Python, который заботится о его передаче в `sys.exc_info()` и подобные.508509Обратите внимание, что начиная с Python 1.5 предпочтительным потокобезопасным способом доступа к состоянию исключения из кода Python является вызов функции [`sys.exc_info()`](https://python-all.ru/3.13/library/sys.html#sys.exc_info), которая возвращает состояние исключения для текущего потока в коде Python. Кроме того, семантика обоих способов доступа к состоянию исключения была изменена таким образом, что функция, перехватывающая исключение, сохраняет и восстанавливает состояние исключения своего потока, чтобы сохранить состояние исключения вызывающей функции. Это предотвращает распространённые ошибки в коде обработки исключений, вызванные тем, что безобидная на вид функция перезаписывает обрабатываемое исключение; это также уменьшает часто нежелательное продление времени жизни объектов, на которые ссылаются кадры стека в трассировке.510511В качестве общего принципа: функция, которая вызывает другую функцию для выполнения некоторой задачи, должна проверять, вызвала ли вызываемая функция исключение, и если да, передавать состояние исключения своему вызывающему. Она должна отбрасывать все принадлежащие ей ссылки на объекты и возвращать индикатор ошибки, но *не* должна устанавливать другое исключение – это перезапишет только что вызванное исключение и приведёт к потере важной информации о точной причине ошибки.512513Простой пример обнаружения исключений и их передачи показан в примере `sum_sequence()` выше. Так получилось, что этому примеру не нужно очищать принадлежащие ссылки при обнаружении ошибки. Следующая примерная функция показывает некоторую очистку при ошибке. Сначала, чтобы напомнить о преимуществах Python, приведён эквивалентный код на Python:514515```c516def incr_item(dict, key):517 try:518 item = dict[key]519 except KeyError:520 item = 0521 dict[key] = item + 1522```523524А вот соответствующий код на C во всей своей красе:525526```c527int528incr_item(PyObject *dict, PyObject *key)529{530 /* Все объекты инициализированы в NULL для Py_XDECREF */531 PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;532 int rv = -1; /* Возвращаемое значение инициализировано как -1 (ошибка) */533534 item = PyObject_GetItem(dict, key);535 if (item == NULL) {536 /* Обрабатывать только KeyError: */537 if (!PyErr_ExceptionMatches(PyExc_KeyError))538 goto error;539540 /* Очистить ошибку и использовать ноль: */541 PyErr_Clear();542 item = PyLong_FromLong(0L);543 if (item == NULL)544 goto error;545 }546 const_one = PyLong_FromLong(1L);547 if (const_one == NULL)548 goto error;549550 incremented_item = PyNumber_Add(item, const_one);551 if (incremented_item == NULL)552 goto error;553554 if (PyObject_SetItem(dict, key, incremented_item) < 0)555 goto error;556 rv = 0; /* Успех */557 /* Продолжить с кодом очистки */558559 error:560 /* Код очистки, общий для путей успеха и ошибки */561562 /* Используйте Py_XDECREF() для игнорирования NULL-ссылок */563 Py_XDECREF(item);564 Py_XDECREF(const_one);565 Py_XDECREF(incremented_item);566567 return rv; /* -1 для ошибки, 0 для успеха */568}569```570571Этот пример представляет собой одобренное использование оператора `goto` в C! Он иллюстрирует использование [`PyErr_ExceptionMatches()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_ExceptionMatches) и [`PyErr_Clear()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Clear) для обработки конкретных исключений, а также использование [`Py_XDECREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_XDECREF) для освобождения принадлежащих ссылок, которые могут быть `NULL` (обратите внимание на `'X'` в имени; [`Py_DECREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_DECREF) аварийно завершится при столкновении с `NULL` ссылкой). Важно, чтобы переменные, используемые для хранения принадлежащих ссылок, были инициализированы значением `NULL` для корректной работы; аналогично, предлагаемое возвращаемое значение инициализируется как `-1` (неудача) и устанавливается в успех только после того, как последний вызов завершится успешно.572573## Встраивание Python574575Единственная важная задача, о которой должны беспокоиться только разработчики, встраивающие интерпретатор Python (в отличие от разработчиков расширений), – это инициализация и, возможно, финализация интерпретатора Python. Большинство функций интерпретатора могут использоваться только после его инициализации.576577Основная функция инициализации – [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize). Она инициализирует таблицу загруженных модулей и создаёт фундаментальные модули [`builtins`](https://python-all.ru/3.13/library/builtins.html#module-builtins), [`__main__`](https://python-all.ru/3.13/library/__main__.html#module-__main__) и [`sys`](https://python-all.ru/3.13/library/sys.html#module-sys). Также она инициализирует путь поиска модулей (`sys.path`).578579[`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize) не устанавливает «список аргументов сценария» (`sys.argv`). Если эта переменная необходима коду Python, который будет выполняться позже, необходимо установить [`PyConfig.argv`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.argv) и [`PyConfig.parse_argv`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.parse_argv): см. [Python Initialization Configuration](https://python-all.ru/3.13/c-api/init_config.html#init-config).580581В большинстве систем (в частности, в Unix и Windows, хотя детали несколько различаются) [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize) вычисляет путь поиска модулей, основываясь на наилучшем предположении о местоположении исполняемого файла стандартного интерпретатора Python, предполагая, что библиотека Python находится в фиксированном месте относительно исполняемого файла интерпретатора Python. В частности, он ищет каталог с именем `lib/pythonX.Y` относительно родительского каталога, где находится исполняемый файл с именем `python` в пути поиска команд оболочки (переменная окружения `PATH`).582583Например, если исполняемый файл Python находится в `/usr/local/bin/python`, то будет предполагаться, что библиотеки находятся в `/usr/local/lib/pythonX.Y`. (Фактически, этот конкретный путь также является «запасным» местоположением, используемым, когда исполняемый файл с именем `python` не найден вдоль `PATH`.) Пользователь может переопределить это поведение, установив переменную окружения [`PYTHONHOME`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONHOME), или вставить дополнительные каталоги в начало стандартного пути, установив [`PYTHONPATH`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONPATH).584585Встраиваемое приложение может управлять поиском, установив [`PyConfig.program_name`](https://python-all.ru/3.13/c-api/init_config.html#c.PyConfig.program_name) *до* вызова [`Py_InitializeFromConfig()`](https://python-all.ru/3.13/c-api/init.html#c.Py_InitializeFromConfig). Обратите внимание, что [`PYTHONHOME`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONHOME) по-прежнему переопределяет это, а [`PYTHONPATH`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONPATH) всё ещё вставляется перед стандартным путём. Приложение, требующее полного контроля, должно предоставить собственную реализацию [`Py_GetPath()`](https://python-all.ru/3.13/c-api/init.html#c.Py_GetPath), [`Py_GetPrefix()`](https://python-all.ru/3.13/c-api/init.html#c.Py_GetPrefix), [`Py_GetExecPrefix()`](https://python-all.ru/3.13/c-api/init.html#c.Py_GetExecPrefix) и [`Py_GetProgramFullPath()`](https://python-all.ru/3.13/c-api/init.html#c.Py_GetProgramFullPath) (все они определены в `Modules/getpath.c`).586587Иногда бывает желательно «деинициализировать» Python. Например, приложение может захотеть начать заново (сделать ещё один вызов [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize)) или просто завершить использование Python и освободить память, выделенную Python. Это можно сделать, вызвав [`Py_FinalizeEx()`](https://python-all.ru/3.13/c-api/init.html#c.Py_FinalizeEx). Функция [`Py_IsInitialized()`](https://python-all.ru/3.13/c-api/init.html#c.Py_IsInitialized) возвращает true, если Python в настоящее время находится в инициализированном состоянии. Дополнительная информация об этих функциях приведена в следующей главе. Обратите внимание, что `Py_FinalizeEx()` *не* освобождает всю память, выделенную интерпретатором Python, например, память, выделенная модулями расширения, в настоящее время не может быть освобождена.588589## Отладочные сборки590591Python может быть собран с несколькими макросами для включения дополнительных проверок интерпретатора и модулей расширения. Эти проверки, как правило, добавляют значительные накладные расходы во время выполнения, поэтому они не включены по умолчанию.592593Полный список различных типов отладочных сборок находится в файле `Misc/SpecialBuilds.txt` в дистрибутиве исходного кода Python. Доступны сборки, поддерживающие трассировку счётчиков ссылок, отладку распределителя памяти или низкоуровневое профилирование основного цикла интерпретатора. В оставшейся части этого раздела будут описаны только наиболее часто используемые сборки.594595#### `Py_DEBUG`596597Компиляция интерпретатора с определённым макросом `Py_DEBUG` даёт то, что обычно называют [отладочной сборкой Python](https://python-all.ru/3.13/using/configure.html#debug-build). `Py_DEBUG` включается в сборке Unix добавлением [`--with-pydebug`](https://python-all.ru/3.13/using/configure.html#cmdoption-with-pydebug) к команде `./configure`. Оно также подразумевается наличием неспецифичного для Python макроса `_DEBUG`. Когда `Py_DEBUG` включён в сборке Unix, оптимизация компилятора отключается.598599В дополнение к отладке подсчёта ссылок, описанной ниже, выполняются дополнительные проверки; см. [Отладочная сборка Python](https://python-all.ru/3.13/using/configure.html#debug-build).600601Определение `Py_TRACE_REFS` включает отслеживание ссылок (см. [`configure --with-trace-refs option`](https://python-all.ru/3.13/using/configure.html#cmdoption-with-trace-refs)). При определении ведётся циклический двусвязный список активных объектов с помощью добавления двух дополнительных полей к каждому [`PyObject`](https://python-all.ru/3.13/c-api/structures.html#c.PyObject). Также отслеживаются общие выделения памяти. При выходе печатаются все существующие ссылки. (В интерактивном режиме это происходит после каждого выполненного интерпретатором оператора.)602603См. `Misc/SpecialBuilds.txt` в дистрибутиве исходных текстов Python для получения более подробной информации.604605## Рекомендуемые сторонние инструменты606607Следующие сторонние инструменты предлагают как более простые, так и более сложные подходы к созданию расширений для Python на C, C++ и Rust:608609- [Cython](https://python-all.ru/3.13/c-api/intro.html)610- [cffi](https://python-all.ru/3.13/c-api/intro.html)611- [HPy](https://python-all.ru/3.13/c-api/intro.html)612- [nanobind](https://python-all.ru/3.13/c-api/intro.html) (C++)613- [Numba](https://python-all.ru/3.13/c-api/intro.html)614- [pybind11](https://python-all.ru/3.13/c-api/intro.html) (C++)615- [PyO3](https://python-all.ru/3.13/c-api/intro.html) (Rust)616- [SWIG](https://python-all.ru/3.13/c-api/intro.html)617618Использование таких инструментов помогает избежать написания кода, жёстко привязанного к конкретной версии CPython, избежать ошибок подсчёта ссылок и сосредоточиться больше на собственном коде, а не на использовании API CPython. В целом, новые версии Python поддерживаются путём обновления инструмента, и ваш код часто будет автоматически использовать более новые и эффективные API. Некоторые инструменты также поддерживают компиляцию для других реализаций Python из единого набора исходников.619620Эти проекты не поддерживаются теми же людьми, которые поддерживают Python, и вопросы необходимо направлять непосредственно проектам. Не забудьте проверить, что проект всё ещё поддерживается, так как приведённый выше список может устареть.621622> **См. также**623>624> **[Руководство пользователя по упаковке Python: Бинарные расширения](https://python-all.ru/3.13/c-api/intro.html)**625>626> Руководство пользователя по упаковке Python (Python Packaging User Guide) не только охватывает несколько доступных инструментов, упрощающих создание двоичных расширений, но и обсуждает различные причины, по которым создание модуля расширения может быть желательным в первую очередь.627