intro.md
1> **Источник:** https://python-all.ru/3/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## Совместимость версий языка1617C API Python совместим с версиями C11 и C++11 языков C и C++.1819Это нижняя граница: C API не требует возможностей более поздних версий C/C++. *не* нужно включать режим c11 компилятора.2021## Стандарты кодирования2223При написании кода на C для включения в CPython **необходимо** следовать рекомендациям и стандартам, определённым в [**PEP 7**](https://python-all.ru/3/c-api/intro.html). Эти рекомендации действуют независимо от версии Python, в которую вносится вклад. Следование этим соглашениям не обязательно для собственных сторонних модулей расширения, если не планируется в конечном счёте передать их в Python.2425## Заголовочные файлы2627Все определения функций, типов и макросов, необходимые для использования Python/C API, включаются в код с помощью следующей строки:2829```c30#define PY_SSIZE_T_CLEAN31#include <Python.h>32```3334Это подразумевает включение следующих стандартных заголовочных файлов: `<stdio.h>`, `<string.h>`, `<errno.h>`, `<limits.h>`, `<assert.h>` и `<stdlib.h>` (если доступны).3536> **Примечание**37>38> Поскольку Python может определять некоторые директивы препроцессора, которые влияют на стандартные заголовочные файлы в некоторых системах, *необходимо* включать `Python.h` до того, как будут включены любые стандартные заголовочные файлы.39>40> Рекомендуется всегда определять `PY_SSIZE_T_CLEAN` перед включением `Python.h`. См. [Разбор аргументов и создание значений](https://python-all.ru/3/c-api/arg.html#arg-parsing) для описания этого макроса.4142Все видимые пользователю имена, определённые Python.h (кроме тех, что определены включёнными стандартными заголовками), имеют один из префиксов `Py` или `_Py`. Имена, начинающиеся с `_Py`, предназначены для внутреннего использования реализацией Python и не должны использоваться разработчиками расширений. Имена членов структур не имеют зарезервированного префикса.4344> **Примечание**45>46> Пользовательский код никогда не должен определять имена, начинающиеся с `Py` или `_Py`. Это сбивает с толку читателя и ставит под угрозу переносимость пользовательского кода на будущие версии Python, которые могут определять дополнительные имена, начинающиеся с одного из этих префиксов.4748Заголовочные файлы обычно устанавливаются вместе с Python. В Unix они находятся в каталогах `prefix/include/pythonversion/` и `exec_prefix/include/pythonversion/`, где [`prefix`](https://python-all.ru/3/using/configure.html#cmdoption-prefix) и [`exec_prefix`](https://python-all.ru/3/using/configure.html#cmdoption-exec-prefix) определяются соответствующими параметрами сценария **configure** Python, а *version* – `'%d.%d' % sys.version_info[:2]`. В Windows заголовочные файлы устанавливаются в `prefix/include`, где `prefix` – каталог установки, указанный в программе установки.4950Чтобы включить заголовочные файлы, поместите оба каталога (если они разные) в путь поиска include компилятора. *Не* помещайте родительские каталоги в путь поиска, а затем используйте `#include <pythonX.Y/Python.h>`; это нарушит сборку на нескольких платформах, поскольку независимые от платформы заголовочные файлы в [`prefix`](https://python-all.ru/3/using/configure.html#cmdoption-prefix) включают специфичные для платформы заголовочные файлы из [`exec_prefix`](https://python-all.ru/3/using/configure.html#cmdoption-exec-prefix).5152Пользователям C++ следует отметить, что, хотя API полностью определён с использованием C, заголовочные файлы правильно объявляют точки входа как `extern "C"`. В результате нет необходимости делать что-то особенное для использования API из C++.5354## Полезные макросы5556В заголовочных файлах Python определено несколько полезных макросов. Многие из них определены рядом с местом их использования (например, [`Py_RETURN_NONE`](https://python-all.ru/3/c-api/none.html#c.Py_RETURN_NONE), [`PyMODINIT_FUNC`](https://python-all.ru/3/c-api/extension-modules.html#c.PyMODINIT_FUNC)). Другие, более общего назначения, определены здесь. Этот список не обязательно полон.5758#### `Py_CAN_START_THREADS`5960Если этот макрос определён, то текущая система может запускать потоки.6162В настоящее время все системы, поддерживаемые CPython (согласно [**PEP 11**](https://python-all.ru/3/c-api/intro.html)), за исключением некоторых платформ WebAssembly, поддерживают запуск потоков.6364Добавлено в версии 3.13.6566#### `Py_GETENV(s)`6768Как `getenv(s)`, но возвращает `NULL`, если [`-E`](https://python-all.ru/3/using/cmdline.html#cmdoption-E) был передан в командной строке (см. [`PyConfig.use_environment`](https://python-all.ru/3/c-api/init_config.html#c.PyConfig.use_environment)).6970### Макросы строк документации7172#### `PyDoc_STRVAR(name, str)`7374Создаёт переменную с именем *name*, которую можно использовать в строках документации. Если Python собран без строк документации ([`--without-doc-strings`](https://python-all.ru/3/using/configure.html#cmdoption-without-doc-strings)), значением будет пустая строка.7576Пример:7778```c79PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element.");8081static PyMethodDef deque_methods[] = {82 // ...83 {"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},84 // ...85}86```8788Расширяется до `PyDoc_VAR(name) = PyDoc_STR(str)`.8990#### `PyDoc_STR(str)`9192Расширяется до заданной входной строки или пустой строки, если строки документации отключены ([`--without-doc-strings`](https://python-all.ru/3/using/configure.html#cmdoption-without-doc-strings)).9394Пример:9596```c97static PyMethodDef pysqlite_row_methods[] = {98 {"keys", (PyCFunction)pysqlite_row_keys, METH_NOARGS,99 PyDoc_STR("Returns the keys of the row.")},100 {NULL, NULL}101};102```103104#### `PyDoc_VAR(name)`105106Объявляет статическую переменную-массив символов с заданным именем *name*. Расширяется до `static const char name[]`107108Например:109110```c111PyDoc_VAR(python_doc) = PyDoc_STR(112 "A genus of constricting snakes in the Pythonidae family native "113 "to the tropics and subtropics of the Eastern Hemisphere.");114```115116### Макросы общего назначения117118Следующие макросы предназначены для общих задач, не специфичных для Python.119120#### `Py_UNUSED(arg)`121122Используется для неиспользуемых аргументов в определении функции, чтобы подавить предупреждения компилятора. Пример: `int func(int a, int Py_UNUSED(b)) { return a; }`.123124Добавлено в версии 3.4.125126#### `Py_GCC_ATTRIBUTE(name)`127128Использует атрибут GCC *name*, скрывая его от компиляторов, не поддерживающих атрибуты GCC (например, MSVC).129130Расширяется до `__attribute__((name))` на компиляторе GCC и не расширяется на компиляторах, которые не поддерживают атрибуты GCC.131132#### Числовые утилиты133134#### `Py_ABS(x)`135136Возвращает абсолютное значение `x`.137138Аргумент может вычисляться более одного раза. Следовательно, не передавайте в этот макрос выражение с побочными эффектами напрямую.139140Если результат не может быть представлен (например, если `x` имеет значение `INT_MIN` для типа int), поведение не определено.141142Примерно соответствует `((x) < 0 ? -(x) : (x))`143144Добавлено в версии 3.3.145146#### `Py_MAX(x, y)`147148#### `Py_MIN(x, y)`149150Возвращает больший или меньший из аргументов, соответственно.151152Любые аргументы могут вычисляться более одного раза. Следовательно, не передавайте в этот макрос выражение с побочными эффектами напрямую.153154`Py_MAX` примерно соответствует `(((x) > (y)) ? (x) : (y))`.155156Добавлено в версии 3.3.157158#### `Py_ARITHMETIC_RIGHT_SHIFT(type, integer, positions)`159160Аналогично `integer >> positions`, но принудительно расширяет знак, так как стандарт C не определяет, будет ли сдвиг вправо знакового целого числа расширять знак или заполнять нулями.161162*integer* должен быть любым знаковым целым типом. *positions* – количество позиций для сдвига вправо.163164И *integer*, и *positions* могут вычисляться более одного раза; поэтому избегайте прямой передачи вызова функции или другой операции с побочными эффектами в этот макрос. Вместо этого сохраните результат в переменную и затем передайте его.165166*type* не используется и сохранён только для обратной совместимости. Исторически *type* использовался для приведения *integer*.167168Изменено в версии 3.1: Этот макрос теперь действителен для всех знаковых целых типов, а не только тех, для которых `unsigned type` допустим. В результате *type* больше не используется.169170#### `Py_CHARMASK(c)`171172Аргумент должен быть символом или целым числом в диапазоне \[-128, 127\] или \[0, 255\]. Этот макрос возвращает `c`, приведённый к `unsigned char`.173174#### Утилиты для утверждений175176#### `Py_UNREACHABLE()`177178Используйте этот макрос, когда есть путь выполнения, который по замыслу не может быть достигнут. Например, в ветке `default:` оператора `switch`, для которого все возможные значения покрыты ветками `case`. Используйте его в местах, где вы могли бы попытаться поместить вызов `assert(0)` или `abort()`.179180В релизном режиме макрос помогает компилятору оптимизировать код и избегает предупреждения о недостижимом коде. Например, макрос реализован с помощью `__builtin_unreachable()` в GCC в релизном режиме.181182В режиме отладки и на неподдерживаемых компиляторах макрос раскрывается в вызов [`Py_FatalError()`](https://python-all.ru/3/c-api/sys.html#c.Py_FatalError).183184Одно из применений `Py_UNREACHABLE()` – после вызова функции, которая никогда не возвращает управление, но не объявлена как `_Noreturn`.185186Если путь выполнения является крайне маловероятным, но может быть достигнут в исключительных случаях, этот макрос использовать нельзя. Например, при нехватке памяти или если системный вызов возвращает значение за пределами ожидаемого диапазона. В этом случае лучше сообщить об ошибке вызывающему коду. Если ошибка не может быть сообщена вызывающему коду, можно использовать [`Py_FatalError()`](https://python-all.ru/3/c-api/sys.html#c.Py_FatalError).187188Добавлено в версии 3.7.189190#### `Py_SAFE_DOWNCAST(value, larger, smaller)`191192Приводит *value* к типу *smaller* из типа *larger*, проверяя, что ни одна информация не была потеряна.193194В релизных сборках Python это примерно эквивалентно `((smaller) value)` (в C++ будет использоваться `static_cast<smaller>(value)`).195196В отладочных сборках (подразумевая, что определён [`Py_DEBUG`](https://python-all.ru/3/c-api/intro.html#c.Py_DEBUG)) это утверждает, что при приведении от *larger* к *smaller* не было потеряно информации.197198*value*, *larger* и *smaller* могут вычисляться более одного раза в выражении; следовательно, не передавайте в этот макрос выражение с побочными эффектами напрямую.199200#### `Py_BUILD_ASSERT(cond)`201202Утверждает условие времени компиляции *cond* в виде инструкции. Сборка завершится ошибкой, если условие ложно или не может быть вычислено во время компиляции.203204Примерно соответствует `static_assert(cond)` в C23 и новее.205206Например:207208```c209Py_BUILD_ASSERT(sizeof(PyTime_t) == sizeof(int64_t));210```211212Добавлено в версии 3.3.213214#### `Py_BUILD_ASSERT_EXPR(cond)`215216Asserts 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.217218Например:219220```c221#define foo_to_char(foo) \222 ((char *)(foo) + Py_BUILD_ASSERT_EXPR(offsetof(struct foo, string) == 0))223```224225Добавлено в версии 3.3.226227#### Утилиты для определения размера типов228229#### `Py_ARRAY_LENGTH(array)`230231Вычисляет длину статически выделенного C-массива во время компиляции.232233Аргумент *array* должен быть C-массивом с размером, известным на этапе компиляции. Передача массива с неизвестным размером, например, выделенного в куче, приведёт к ошибке компиляции в некоторых компиляторах или даст неверные результаты.234235Это примерно эквивалентно:236237```c238sizeof(array) / sizeof((array)[0])239```240241#### `Py_MEMBER_SIZE(type, member)`242243Возвращает размер поля *member* структуры (*type*) в байтах.244245Примерно соответствует `sizeof(((type *)NULL)->member)`.246247Добавлено в версии 3.6.248249#### Утилиты для определения макросов250251#### `Py_FORCE_EXPANSION(X)`252253Это эквивалентно `X`, что полезно для склеивания токенов в макросах, так как раскрытие макросов в *X* принудительно вычисляется препроцессором.254255#### `Py_STRINGIFY(x)`256257Преобразует `x` в C-строку. Например, `Py_STRINGIFY(123)` возвращает `"123"`.258259Добавлено в версии 3.4.260261### Утилиты для объявлений262263Следующие макросы можно использовать в объявлениях. Они наиболее полезны для определения самого C API и имеют ограниченное применение для разработчиков расширений. Большинство из них раскрываются в специфичные для компилятора варианты распространённых расширений языка C.264265#### `Py_ALWAYS_INLINE`266267Предлагает компилятору всегда встраивать статическую встраиваемую функцию. Компилятор может проигнорировать это и решить не встраивать функцию.268269Соответствует атрибуту `always_inline` в GCC и `__forceinline` в MSVC.270271Его можно использовать для встраивания критичных по производительности статических встраиваемых функций при сборке Python в режиме отладки с отключённым встраиванием функций. Например, MSC отключает встраивание функций при сборке в режиме отладки.272273Слепое пометивание статической встраиваемой функции макросом Py\_ALWAYS\_INLINE может привести к ухудшению производительности (например, из-за увеличения размера кода). Компилятор обычно умнее разработчика в анализе затрат и выгод.274275Если Python [собран в режиме отладки](https://python-all.ru/3/using/configure.html#debug-build) (если определён макрос [`Py_DEBUG`](https://python-all.ru/3/c-api/intro.html#c.Py_DEBUG)), макрос [`Py_ALWAYS_INLINE`](https://python-all.ru/3/c-api/intro.html#c.Py_ALWAYS_INLINE) ничего не делает.276277Он должен быть указан перед типом возвращаемого значения функции. Использование:278279```c280static inline Py_ALWAYS_INLINE int random(void) { return 4; }281```282283Добавлено в версии 3.12.284285#### `Py_NO_INLINE`286287Отключает встраивание функции. Например, это уменьшает потребление стека C: полезно при сборках с LTO+PGO, которые активно встраивают код (см. [bpo-33720](https://python-all.ru/3/c-api/intro.html)).288289Соответствует атрибуту/спецификации `noinline` в GCC и MSVC.290291Использование:292293```c294Py_NO_INLINE static int random(void) { return 4; }295```296297Добавлено в версии 3.12.298299#### `Py_DEPRECATED(version)`300301Используйте этот макрос для объявления API, которые были помечены как устаревшие в определённой версии CPython. Макрос должен быть размещён перед именем символа.302303Пример:304305```c306Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);307```308309Изменено в версии 3.8: добавлена поддержка MSVC.310311#### `Py_LOCAL(type)`312313Объявляет функцию, возвращающую указанный *тип*, с квалификатором быстрого вызова для функций, локальных для текущего файла. Семантически это эквивалентно `static type`.314315#### `Py_LOCAL_INLINE(type)`316317Эквивалентно [`Py_LOCAL`](https://python-all.ru/3/c-api/intro.html#c.Py_LOCAL), но дополнительно требует встраивания функции.318319#### `Py_LOCAL_SYMBOL`320321Макрос, используемый для объявления символа как локального для общей библиотеки (скрытого). На поддерживаемых платформах гарантирует, что символ не экспортируется.322323В совместимых версиях GCC/Clang раскрывается в `__attribute__((visibility("hidden")))`.324325#### `Py_EXPORTED_SYMBOL`326327Макрос, используемый для объявления символа (функции или данных) как экспортируемого. В Windows раскрывается в `__declspec(dllexport)`. В совместимых версиях GCC/Clang раскрывается в `__attribute__((visibility("default")))`. Этот макрос предназначен для определения самого C API; модули расширения не должны его использовать.328329#### `Py_IMPORTED_SYMBOL`330331Макрос, используемый для объявления символа как импортируемого. В Windows раскрывается в `__declspec(dllimport)`. Этот макрос предназначен для определения самого C API; модули расширения не должны его использовать.332333#### `PyAPI_FUNC(type)`334335Макрос, используемый CPython для объявления функции как части C API. Его раскрытие зависит от платформы и конфигурации сборки. Этот макрос предназначен для определения самого C API CPython; модули расширения не должны использовать его для своих собственных символов.336337#### `PyAPI_DATA(type)`338339Макрос, используемый CPython для объявления публичной глобальной переменной как части C API. Его раскрытие зависит от платформы и конфигурации сборки. Этот макрос предназначен для определения самого C API CPython; модули расширения не должны использовать его для своих собственных символов.340341### Устаревшие макросы342343Следующие макросы использовались для обозначения возможностей, стандартизированных в C11.344345#### `Py_ALIGNED(num)`346347Задают выравнивание на *num* байтов в компиляторах, которые это поддерживают.348349Рекомендуется использовать спецификатор `_Alignas` из стандарта C11 вместо этого макроса.350351#### `Py_LL(number)`352353#### `Py_ULL(number)`354355Используйте *number* как целочисленный литерал `long long` или `unsigned long long`, соответственно.356357Раскрывается в *number*, за которым следует `LL` или `LLU` соответственно, но в некоторых старых компиляторах будет раскрываться в некоторые специфичные для компилятора суффиксы.358359Рекомендуется использовать стандартные суффиксы C99 `LL` и `LLU` напрямую.360361#### `Py_MEMCPY(dest, src, n)`362363Это псевдоним `memcpy()`.364365[Мягко устарело](https://python-all.ru/3/glossary.html#term-soft-deprecated) с версии 3.14: Вместо этого используйте непосредственно `memcpy()`.366367#### `Py_VA_COPY`368369Это псевдоним функции `va_copy` стандарта C99.370371Исторически для копирования `va_list` использовался метод, зависящий от конкретного компилятора.372373Изменено в версии 3.6: Теперь это псевдоним для `va_copy`.374375[Soft deprecated](https://python-all.ru/3/glossary.html#term-soft-deprecated) since version 3.14.376377## Объекты, типы и счетчики ссылок378379Большинство функций Python/C API имеют один или несколько аргументов, а также возвращаемое значение типа [PyObject](https://python-all.ru/3/c-api/structures.html#c.PyObject)\*. Этот тип является указателем на непрозрачный тип данных, представляющий произвольный объект Python. Поскольку все типы объектов Python обрабатываются одинаково в большинстве ситуаций (например, присваивание, правила области видимости и передача аргументов), вполне уместно, чтобы они представлялись одним типом C. Почти все объекты Python живут в куче: никогда не объявляются автоматические или статические переменные типа [`PyObject`](https://python-all.ru/3/c-api/structures.html#c.PyObject), можно объявлять только переменные-указатели типа PyObject\*. Единственным исключением являются объекты типа; поскольку они никогда не должны освобождаться, они обычно являются статическими объектами [`PyTypeObject`](https://python-all.ru/3/c-api/type.html#c.PyTypeObject).380381Все объекты Python (даже целые числа Python) имеют *тип* и *счетчик ссылок*. Тип объекта определяет, что это за объект (например, целое число, список или пользовательская функция; существует гораздо больше типов, как описано в [Стандартная иерархия типов](https://python-all.ru/3/reference/datamodel.html#types)). Для каждого из известных типов существует макрос, проверяющий, является ли объект объектом этого типа; например, `PyList_Check(a)` истинно тогда и только тогда, когда объект, на который указывает *a*, является списком Python.382383### Счетчики ссылок384385Счетчик ссылок важен, потому что современные компьютеры имеют конечный (и часто сильно ограниченный) размер памяти; он подсчитывает, сколько различных мест имеют [сильную ссылку](https://python-all.ru/3/glossary.html#term-strong-reference) на объект. Таким местом может быть другой объект, глобальная (или статическая) переменная C или локальная переменная в какой-либо функции C. Когда последняя сильная ссылка на объект освобождается (т.е. его счетчик ссылок становится нулевым), объект освобождается. Если он содержит ссылки на другие объекты, эти ссылки освобождаются. Эти другие объекты могут быть освобождены в свою очередь, если на них больше нет ссылок, и так далее. (Здесь очевидна проблема с объектами, ссылающимися друг на друга; на данный момент решение – «не делайте так».)386387Счетчики ссылок всегда изменяются явным образом. Обычный способ – использовать макрос [`Py_INCREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_INCREF) для получения новой ссылки на объект (т.е. увеличить его счетчик ссылок на единицу) и [`Py_DECREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_DECREF) для освобождения этой ссылки (т.е. уменьшить счетчик ссылок на единицу). Макрос `Py_DECREF()` значительно сложнее, чем макрос incref, поскольку он должен проверять, не стал ли счетчик ссылок нулевым, и затем вызывать деаллокатор объекта. Деаллокатор – это указатель на функцию, содержащийся в структуре типа объекта. Деаллокатор, специфичный для типа, отвечает за освобождение ссылок на другие объекты, содержащиеся в объекте, если это составной тип объекта (например, список), а также за выполнение любой дополнительной финализации, которая требуется. Нет возможности переполнения счетчика ссылок; для хранения счетчика ссылок используется по крайней мере столько битов, сколько существует различных ячеек памяти в виртуальной памяти (при условии `sizeof(Py_ssize_t) >= sizeof(void*)`). Таким образом, увеличение счетчика ссылок – простая операция.388389Нет необходимости удерживать [сильную ссылку](https://python-all.ru/3/glossary.html#term-strong-reference) (т.е. увеличивать счетчик ссылок) для каждой локальной переменной, содержащей указатель на объект. Теоретически счетчик ссылок объекта увеличивается на единицу, когда переменная начинает указывать на него, и уменьшается на единицу, когда переменная выходит из области видимости. Однако эти два действия компенсируют друг друга, поэтому в итоге счетчик ссылок не меняется. Единственная реальная причина использовать счетчик ссылок – предотвратить освобождение объекта, пока наша переменная указывает на него. Если мы знаем, что существует по крайней мере одна другая ссылка на объект, которая живет как минимум столько же, сколько наша переменная, нет необходимости временно получать новую сильную ссылку (т.е. увеличивать счетчик ссылок). Важная ситуация, в которой это возникает, – объекты, передаваемые в качестве аргументов функциям C в модуле расширения, которые вызываются из Python; механизм вызова гарантирует удержание ссылки на каждый аргумент на время вызова.390391Однако распространенная ошибка – извлечь объект из списка и удерживать его некоторое время, не получая новую ссылку. Какая-нибудь другая операция может удалить объект из списка, освободив эту ссылку, и, возможно, освободить его. Реальная опасность в том, что безобидные на первый взгляд операции могут вызвать произвольный код Python, который способен это сделать; существует путь выполнения, который позволяет управлению вернуться к пользователю из [`Py_DECREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_DECREF), поэтому практически любая операция потенциально опасна.392393Безопасный подход – всегда использовать обобщенные операции (функции, имя которых начинается с `PyObject_`, `PyNumber_`, `PySequence_` или `PyMapping_`). Эти операции всегда создают новую [сильную ссылку](https://python-all.ru/3/glossary.html#term-strong-reference) (т.е. увеличивают счетчик ссылок) возвращаемого объекта. Это возлагает на вызывающего обязанность вызвать [`Py_DECREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_DECREF), когда он закончит работу с результатом; это быстро входит в привычку.394395#### Подробности о счетчиках ссылок396397Поведение функций Python/C API в отношении счетчиков ссылок лучше всего объяснять в терминах *владения ссылками*. Владение относится к ссылкам, никогда к объектам (объектами не владеют: они всегда разделяются). «Владение ссылкой» означает ответственность за вызов Py\_DECREF для нее, когда ссылка больше не нужна. Владение также может передаваться, что означает, что код, получающий владение ссылкой, становится ответственным за ее освобождение путем вызова [`Py_DECREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_DECREF) или [`Py_XDECREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_XDECREF), когда она больше не нужна, или за передачу этой ответственности дальше (обычно своему вызывающему). Когда функция передает владение ссылкой своему вызывающему, говорят, что вызывающий получает *новую* ссылку. Когда владение не передается, говорят, что вызывающий *заимствует* ссылку. Для [заимствованной ссылки](https://python-all.ru/3/glossary.html#term-borrowed-reference) ничего делать не нужно.398399И наоборот, когда вызывающая функция передает ссылку на объект, есть две возможности: функция *крадет* ссылку на объект или нет.400401*Кража ссылки* означает, что при передаче ссылки функции эта функция предполагает, что теперь она владеет этой ссылкой. Поскольку новый владелец может использовать `Py_DECREF()` по своему усмотрению, вызывающий не должен использовать эту ссылку после вызова.402403Немногие функции крадут ссылки; двумя заметными исключениями являются [`PyList_SetItem()`](https://python-all.ru/3/c-api/list.html#c.PyList_SetItem) и [`PyTuple_SetItem()`](https://python-all.ru/3/c-api/tuple.html#c.PyTuple_SetItem), которые крадут ссылку на элемент (но не на кортеж или список, в который помещается элемент!). Эти функции были спроектированы так, чтобы красть ссылку из-за распространенного идиоматического приема заполнения кортежа или списка только что созданными объектами; например, код для создания кортежа `(1, 2, "three")` может выглядеть так (пока забывая об обработке ошибок; лучший способ написать это показан ниже):404405```c406PyObject *t;407408t = PyTuple_New(3);409PyTuple_SetItem(t, 0, PyLong_FromLong(1L));410PyTuple_SetItem(t, 1, PyLong_FromLong(2L));411PyTuple_SetItem(t, 2, PyUnicode_FromString("three"));412```413414Здесь [`PyLong_FromLong()`](https://python-all.ru/3/c-api/long.html#c.PyLong_FromLong) возвращает новую ссылку, которая немедленно крадется [`PyTuple_SetItem()`](https://python-all.ru/3/c-api/tuple.html#c.PyTuple_SetItem). Если требуется продолжать использовать объект, хотя ссылка на него будет украдена, используйте [`Py_INCREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_INCREF), чтобы получить другую ссылку перед вызовом функции, крадущей ссылки.415416Кстати, [`PyTuple_SetItem()`](https://python-all.ru/3/c-api/tuple.html#c.PyTuple_SetItem) – это *единственный* способ задать элементы кортежа. [`PySequence_SetItem()`](https://python-all.ru/3/c-api/sequence.html#c.PySequence_SetItem) и [`PyObject_SetItem()`](https://python-all.ru/3/c-api/object.html#c.PyObject_SetItem) отказываются это делать, поскольку кортежи – неизменяемый тип данных. Используйте `PyTuple_SetItem()` только для кортежей, которые создаёте самостоятельно.417418Эквивалентный код для заполнения списка можно написать с помощью [`PyList_New()`](https://python-all.ru/3/c-api/list.html#c.PyList_New) и [`PyList_SetItem()`](https://python-all.ru/3/c-api/list.html#c.PyList_SetItem).419420Однако на практике эти способы создания и заполнения кортежа или списка используются редко. Существует универсальная функция [`Py_BuildValue()`](https://python-all.ru/3/c-api/arg.html#c.Py_BuildValue), которая может создавать большинство распространённых объектов из значений C, управляемая *строкой формата*. Например, два приведённых выше блока кода можно заменить следующим (который также выполняет проверку ошибок):421422```c423PyObject *tuple, *list;424425tuple = Py_BuildValue("(iis)", 1, 2, "three");426list = Py_BuildValue("[iis]", 1, 2, "three");427```428429Гораздо чаще [`PyObject_SetItem()`](https://python-all.ru/3/c-api/object.html#c.PyObject_SetItem) и подобные функции используются с элементами, ссылки на которые только заимствуются, например, с аргументами, переданными в функцию. В этом случае их поведение в отношении ссылок гораздо разумнее, поскольку не нужно получать новую ссылку только для того, чтобы отдать её («позволить её украсть»). Например, эта функция устанавливает все элементы списка (фактически любой изменяемой последовательности) в заданный элемент:430431```c432int433set_all(PyObject *target, PyObject *item)434{435 Py_ssize_t i, n;436437 n = PyObject_Length(target);438 if (n < 0)439 return -1;440 for (i = 0; i < n; i++) {441 PyObject *index = PyLong_FromSsize_t(i);442 if (!index)443 return -1;444 if (PyObject_SetItem(target, index, item) < 0) {445 Py_DECREF(index);446 return -1;447 }448 Py_DECREF(index);449 }450 return 0;451}452```453454Ситуация немного отличается для возвращаемых значений функций. Хотя передача ссылки большинству функций не меняет обязанности по владению этой ссылкой, многие функции, возвращающие ссылку на объект, передают владение ссылкой вызывающему. Причина проста: во многих случаях возвращаемый объект создаётся на лету, и полученная ссылка является единственной ссылкой на объект. Поэтому универсальные функции, возвращающие ссылки на объекты, такие как [`PyObject_GetItem()`](https://python-all.ru/3/c-api/object.html#c.PyObject_GetItem) и [`PySequence_GetItem()`](https://python-all.ru/3/c-api/sequence.html#c.PySequence_GetItem), всегда возвращают новую ссылку (вызывающий становится владельцем ссылки).455456Важно понимать, что владение ссылкой, возвращённой функцией, зависит только от того, какая функция вызывается – *оперение* (тип объекта, переданного в качестве аргумента функции) *не играет роли!* Таким образом, при извлечении элемента из списка с помощью [`PyList_GetItem()`](https://python-all.ru/3/c-api/list.html#c.PyList_GetItem) ссылка не переходит во владение – но при получении того же элемента из того же списка с помощью [`PySequence_GetItem()`](https://python-all.ru/3/c-api/sequence.html#c.PySequence_GetItem) (которая принимает точно такие же аргументы) возвращённая ссылка переходит во владение.457458Вот пример того, как можно написать функцию, вычисляющую сумму элементов списка целых чисел; один раз с помощью [`PyList_GetItem()`](https://python-all.ru/3/c-api/list.html#c.PyList_GetItem), и один раз с помощью [`PySequence_GetItem()`](https://python-all.ru/3/c-api/sequence.html#c.PySequence_GetItem).459460```c461long462sum_list(PyObject *list)463{464 Py_ssize_t i, n;465 long total = 0, value;466 PyObject *item;467468 n = PyList_Size(list);469 if (n < 0)470 return -1; /* Не список */471 for (i = 0; i < n; i++) {472 item = PyList_GetItem(list, i); /* Не может завершиться ошибкой */473 if (!PyLong_Check(item)) continue; /* Пропустить нецелые значения */474 value = PyLong_AsLong(item);475 if (value == -1 && PyErr_Occurred())476 /* Целое число слишком велико для C long, выход */477 return -1;478 total += value;479 }480 return total;481}482```483484```c485long486sum_sequence(PyObject *sequence)487{488 Py_ssize_t i, n;489 long total = 0, value;490 PyObject *item;491 n = PySequence_Length(sequence);492 if (n < 0)493 return -1; /* Не имеет длины */494 for (i = 0; i < n; i++) {495 item = PySequence_GetItem(sequence, i);496 if (item == NULL)497 return -1; /* Не последовательность или другая ошибка */498 if (PyLong_Check(item)) {499 value = PyLong_AsLong(item);500 Py_DECREF(item);501 if (value == -1 && PyErr_Occurred())502 /* Целое число слишком велико для C long, выход */503 return -1;504 total += value;505 }506 else {507 Py_DECREF(item); /* Отказ от владения ссылкой */508 }509 }510 return total;511}512```513514### Типы515516Существует ещё несколько типов данных, играющих важную роль в Python/C API; большинство из них – простые типы C, такие как int, long, double и char\*. Некоторые структурные типы используются для описания статических таблиц, в которых перечисляются функции, экспортируемые модулем, или атрибуты данных нового типа объекта, а другой тип используется для описания значения комплексного числа. Они будут рассмотрены вместе с функциями, которые их используют.517518#### `type Py_ssize_t`519520*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*521522Знаковый целочисленный тип, такой что `sizeof(Py_ssize_t) == sizeof(size_t)`. C99 не определяет такой тип напрямую (size\_t – это беззнаковый целочисленный тип). Подробнее см. [**PEP 353**](https://python-all.ru/3/c-api/intro.html). `PY_SSIZE_T_MAX` – это наибольшее положительное значение типа [`Py_ssize_t`](https://python-all.ru/3/c-api/intro.html#c.Py_ssize_t).523524## Исключения525526Программисту на Python требуется обрабатывать исключения только в тех случаях, когда необходима специфическая обработка ошибок; необработанные исключения автоматически передаются вызывающему, затем вызывающему вызывающего и так далее, пока не достигнут интерпретатора верхнего уровня, где они сообщаются пользователю вместе с трассировкой стека.527528Однако для C-программистов проверка ошибок всегда должна быть явной. Все функции Python/C API могут вызывать исключения, если в документации функции не указано иное. В общем случае, когда функция обнаруживает ошибку, она устанавливает исключение, отбрасывает все принадлежащие ей ссылки на объекты и возвращает индикатор ошибки. Если не задокументировано иное, этот индикатор – либо `NULL`, либо `-1`, в зависимости от типа возвращаемого значения функции. Некоторые функции возвращают логический результат true/false, где false указывает на ошибку. Очень немногие функции не возвращают явного индикатора ошибки или имеют неоднозначное возвращаемое значение и требуют явной проверки на ошибки с помощью [`PyErr_Occurred()`](https://python-all.ru/3/c-api/exceptions.html#c.PyErr_Occurred). Такие исключения всегда явно документируются.529530Состояние исключения хранится в памяти, привязанной к потоку (это эквивалентно использованию глобальной памяти в однопоточном приложении). Поток может находиться в одном из двух состояний: произошло исключение или нет. Функция [`PyErr_Occurred()`](https://python-all.ru/3/c-api/exceptions.html#c.PyErr_Occurred) может использоваться для проверки этого: она возвращает заимствованную ссылку на объект типа исключения, если произошло исключение, и `NULL` в противном случае. Существует ряд функций для установки состояния исключения: [`PyErr_SetString()`](https://python-all.ru/3/c-api/exceptions.html#c.PyErr_SetString) является наиболее распространённой (хотя и не самой общей) функцией для установки состояния исключения, а [`PyErr_Clear()`](https://python-all.ru/3/c-api/exceptions.html#c.PyErr_Clear) очищает состояние исключения.531532Полное состояние исключения состоит из трёх объектов (все они могут быть `NULL`): типа исключения, соответствующего значения исключения и трассировки стека. Они имеют тот же смысл, что и результат Python `sys.exc_info()`; однако они не одно и то же: объекты Python представляют последнее исключение, обрабатываемое оператором [`try`](https://python-all.ru/3/reference/compound_stmts.html#try) … [`except`](https://python-all.ru/3/reference/compound_stmts.html#except), в то время как состояние исключения на уровне C существует только пока исключение передаётся между C-функциями, пока не достигнет основного цикла интерпретатора байт-кода Python, который заботится о его передаче в `sys.exc_info()` и подобные.533534Обратите внимание, что начиная с Python 1.5 предпочтительным потокобезопасным способом доступа к состоянию исключения из кода Python является вызов функции [`sys.exc_info()`](https://python-all.ru/3/library/sys.html#sys.exc_info), которая возвращает состояние исключения для текущего потока в коде Python. Кроме того, семантика обоих способов доступа к состоянию исключения была изменена таким образом, что функция, перехватывающая исключение, сохраняет и восстанавливает состояние исключения своего потока, чтобы сохранить состояние исключения вызывающей функции. Это предотвращает распространённые ошибки в коде обработки исключений, вызванные тем, что безобидная на вид функция перезаписывает обрабатываемое исключение; это также уменьшает часто нежелательное продление времени жизни объектов, на которые ссылаются кадры стека в трассировке.535536В качестве общего принципа: функция, которая вызывает другую функцию для выполнения некоторой задачи, должна проверять, вызвала ли вызываемая функция исключение, и если да, передавать состояние исключения своему вызывающему. Она должна отбрасывать все принадлежащие ей ссылки на объекты и возвращать индикатор ошибки, но *не* должна устанавливать другое исключение – это перезапишет только что вызванное исключение и приведёт к потере важной информации о точной причине ошибки.537538Простой пример обнаружения исключений и их передачи показан в примере `sum_sequence()` выше. Так получилось, что этому примеру не нужно очищать принадлежащие ссылки при обнаружении ошибки. Следующая примерная функция показывает некоторую очистку при ошибке. Сначала, чтобы напомнить о преимуществах Python, приведён эквивалентный код на Python:539540```c541def incr_item(dict, key):542 try:543 item = dict[key]544 except KeyError:545 item = 0546 dict[key] = item + 1547```548549А вот соответствующий код на C во всей своей красе:550551```c552int553incr_item(PyObject *dict, PyObject *key)554{555 /* Все объекты инициализированы в NULL для Py_XDECREF */556 PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;557 int rv = -1; /* Возвращаемое значение инициализировано как -1 (ошибка) */558559 item = PyObject_GetItem(dict, key);560 if (item == NULL) {561 /* Обрабатывать только KeyError: */562 if (!PyErr_ExceptionMatches(PyExc_KeyError))563 goto error;564565 /* Очистить ошибку и использовать ноль: */566 PyErr_Clear();567 item = PyLong_FromLong(0L);568 if (item == NULL)569 goto error;570 }571 const_one = PyLong_FromLong(1L);572 if (const_one == NULL)573 goto error;574575 incremented_item = PyNumber_Add(item, const_one);576 if (incremented_item == NULL)577 goto error;578579 if (PyObject_SetItem(dict, key, incremented_item) < 0)580 goto error;581 rv = 0; /* Успех */582 /* Продолжить с кодом очистки */583584 error:585 /* Код очистки, общий для путей успеха и ошибки */586587 /* Используйте Py_XDECREF() для игнорирования NULL-ссылок */588 Py_XDECREF(item);589 Py_XDECREF(const_one);590 Py_XDECREF(incremented_item);591592 return rv; /* -1 для ошибки, 0 для успеха */593}594```595596Этот пример представляет собой одобренное использование оператора `goto` в C! Он иллюстрирует использование [`PyErr_ExceptionMatches()`](https://python-all.ru/3/c-api/exceptions.html#c.PyErr_ExceptionMatches) и [`PyErr_Clear()`](https://python-all.ru/3/c-api/exceptions.html#c.PyErr_Clear) для обработки конкретных исключений, а также использование [`Py_XDECREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_XDECREF) для освобождения принадлежащих ссылок, которые могут быть `NULL` (обратите внимание на `'X'` в имени; [`Py_DECREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_DECREF) аварийно завершится при столкновении с `NULL` ссылкой). Важно, чтобы переменные, используемые для хранения принадлежащих ссылок, были инициализированы значением `NULL` для корректной работы; аналогично, предлагаемое возвращаемое значение инициализируется как `-1` (неудача) и устанавливается в успех только после того, как последний вызов завершится успешно.597598## Встраивание Python599600Единственная важная задача, о которой должны беспокоиться только разработчики, встраивающие интерпретатор Python (в отличие от разработчиков расширений), – это инициализация и, возможно, финализация интерпретатора Python. Большинство функций интерпретатора могут использоваться только после его инициализации.601602Основная функция инициализации – [`Py_Initialize()`](https://python-all.ru/3/c-api/interp-lifecycle.html#c.Py_Initialize). Она инициализирует таблицу загруженных модулей и создаёт фундаментальные модули [`builtins`](https://python-all.ru/3/library/builtins.html#module-builtins), [`__main__`](https://python-all.ru/3/library/__main__.html#module-__main__) и [`sys`](https://python-all.ru/3/library/sys.html#module-sys). Также она инициализирует путь поиска модулей (`sys.path`).603604[`Py_Initialize()`](https://python-all.ru/3/c-api/interp-lifecycle.html#c.Py_Initialize) не устанавливает «список аргументов сценария» (`sys.argv`). Если эта переменная необходима коду Python, который будет выполняться позже, необходимо установить [`PyConfig.argv`](https://python-all.ru/3/c-api/init_config.html#c.PyConfig.argv) и [`PyConfig.parse_argv`](https://python-all.ru/3/c-api/init_config.html#c.PyConfig.parse_argv): см. [Python Initialization Configuration](https://python-all.ru/3/c-api/init_config.html#init-config).605606В большинстве систем (в частности, в Unix и Windows, хотя детали несколько различаются) [`Py_Initialize()`](https://python-all.ru/3/c-api/interp-lifecycle.html#c.Py_Initialize) вычисляет путь поиска модулей, основываясь на наилучшем предположении о местоположении исполняемого файла стандартного интерпретатора Python, предполагая, что библиотека Python находится в фиксированном месте относительно исполняемого файла интерпретатора Python. В частности, он ищет каталог с именем `lib/pythonX.Y` относительно родительского каталога, где находится исполняемый файл с именем `python` в пути поиска команд оболочки (переменная окружения `PATH`).607608Например, если исполняемый файл Python находится в `/usr/local/bin/python`, то будет предполагаться, что библиотеки находятся в `/usr/local/lib/pythonX.Y`. (Фактически, этот конкретный путь также является «запасным» местоположением, используемым, когда исполняемый файл с именем `python` не найден вдоль `PATH`.) Пользователь может переопределить это поведение, установив переменную окружения [`PYTHONHOME`](https://python-all.ru/3/using/cmdline.html#envvar-PYTHONHOME), или вставить дополнительные каталоги в начало стандартного пути, установив [`PYTHONPATH`](https://python-all.ru/3/using/cmdline.html#envvar-PYTHONPATH).609610Встраиваемое приложение может управлять поиском, установив [`PyConfig.program_name`](https://python-all.ru/3/c-api/init_config.html#c.PyConfig.program_name) *до* вызова [`Py_InitializeFromConfig()`](https://python-all.ru/3/c-api/interp-lifecycle.html#c.Py_InitializeFromConfig). Обратите внимание, что [`PYTHONHOME`](https://python-all.ru/3/using/cmdline.html#envvar-PYTHONHOME) по-прежнему переопределяет это, а [`PYTHONPATH`](https://python-all.ru/3/using/cmdline.html#envvar-PYTHONPATH) всё ещё вставляется перед стандартным путём. Приложение, требующее полного контроля, должно предоставить собственную реализацию [`Py_GetPath()`](https://python-all.ru/3/c-api/interp-lifecycle.html#c.Py_GetPath), [`Py_GetPrefix()`](https://python-all.ru/3/c-api/interp-lifecycle.html#c.Py_GetPrefix), [`Py_GetExecPrefix()`](https://python-all.ru/3/c-api/interp-lifecycle.html#c.Py_GetExecPrefix) и [`Py_GetProgramFullPath()`](https://python-all.ru/3/c-api/interp-lifecycle.html#c.Py_GetProgramFullPath) (все они определены в `Modules/getpath.c`).611612Иногда бывает желательно «деинициализировать» Python. Например, приложение может захотеть начать заново (сделать ещё один вызов [`Py_Initialize()`](https://python-all.ru/3/c-api/interp-lifecycle.html#c.Py_Initialize)) или просто завершить использование Python и освободить память, выделенную Python. Это можно сделать, вызвав [`Py_FinalizeEx()`](https://python-all.ru/3/c-api/interp-lifecycle.html#c.Py_FinalizeEx). Функция [`Py_IsInitialized()`](https://python-all.ru/3/c-api/interp-lifecycle.html#c.Py_IsInitialized) возвращает true, если Python в настоящее время находится в инициализированном состоянии. Дополнительная информация об этих функциях приведена в следующей главе. Обратите внимание, что `Py_FinalizeEx()` *не* освобождает всю память, выделенную интерпретатором Python, например, память, выделенная модулями расширения, в настоящее время не может быть освобождена.613614## Отладочные сборки615616Python может быть собран с несколькими макросами для включения дополнительных проверок интерпретатора и модулей расширения. Эти проверки, как правило, добавляют значительные накладные расходы во время выполнения, поэтому они не включены по умолчанию.617618Полный список различных типов отладочных сборок находится в файле `Misc/SpecialBuilds.txt` в дистрибутиве исходного кода Python. Доступны сборки, поддерживающие трассировку счётчиков ссылок, отладку распределителя памяти или низкоуровневое профилирование основного цикла интерпретатора. В оставшейся части этого раздела будут описаны только наиболее часто используемые сборки.619620#### `Py_DEBUG`621622Компиляция интерпретатора с определённым макросом `Py_DEBUG` даёт то, что обычно называют [отладочной сборкой Python](https://python-all.ru/3/using/configure.html#debug-build). `Py_DEBUG` включается в сборке Unix добавлением [`--with-pydebug`](https://python-all.ru/3/using/configure.html#cmdoption-with-pydebug) к команде `./configure`. Оно также подразумевается наличием неспецифичного для Python макроса `_DEBUG`. Когда `Py_DEBUG` включён в сборке Unix, оптимизация компилятора отключается.623624В дополнение к отладке подсчёта ссылок, описанной ниже, выполняются дополнительные проверки; см. [Отладочная сборка Python](https://python-all.ru/3/using/configure.html#debug-build).625626Определение `Py_TRACE_REFS` включает отслеживание ссылок (см. [`configure --with-trace-refs option`](https://python-all.ru/3/using/configure.html#cmdoption-with-trace-refs)). При определении ведётся циклический двусвязный список активных объектов с помощью добавления двух дополнительных полей к каждому [`PyObject`](https://python-all.ru/3/c-api/structures.html#c.PyObject). Также отслеживаются общие выделения памяти. При выходе печатаются все существующие ссылки. (В интерактивном режиме это происходит после каждого выполненного интерпретатором оператора.)627628См. `Misc/SpecialBuilds.txt` в дистрибутиве исходных текстов Python для получения более подробной информации.629630## Рекомендуемые сторонние инструменты631632Следующие сторонние инструменты предлагают как более простые, так и более сложные подходы к созданию расширений для Python на C, C++ и Rust:633634- [Cython](https://python-all.ru/3/c-api/intro.html)635- [cffi](https://python-all.ru/3/c-api/intro.html)636- [HPy](https://python-all.ru/3/c-api/intro.html)637- [nanobind](https://python-all.ru/3/c-api/intro.html) (C++)638- [Numba](https://python-all.ru/3/c-api/intro.html)639- [pybind11](https://python-all.ru/3/c-api/intro.html) (C++)640- [PyO3](https://python-all.ru/3/c-api/intro.html) (Rust)641- [SWIG](https://python-all.ru/3/c-api/intro.html)642643Использование таких инструментов помогает избежать написания кода, жёстко привязанного к конкретной версии CPython, избежать ошибок подсчёта ссылок и сосредоточиться больше на собственном коде, а не на использовании API CPython. В целом, новые версии Python поддерживаются путём обновления инструмента, и ваш код часто будет автоматически использовать более новые и эффективные API. Некоторые инструменты также поддерживают компиляцию для других реализаций Python из единого набора исходников.644645Эти проекты не поддерживаются теми же людьми, которые поддерживают Python, и вопросы необходимо направлять непосредственно проектам. Не забудьте проверить, что проект всё ещё поддерживается, так как приведённый выше список может устареть.646647> **См. также**648>649> **[Руководство пользователя по упаковке Python: Бинарные расширения](https://python-all.ru/3/c-api/intro.html)**650>651> Руководство пользователя по упаковке Python (Python Packaging User Guide) не только охватывает несколько доступных инструментов, упрощающих создание двоичных расширений, но и обсуждает различные причины, по которым создание модуля расширения может быть желательным в первую очередь.652