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

---

# Определение модулей расширения

Расширение для CPython на C – это динамическая библиотека (например, файл `.so` в Linux, `.pyd` DLL в Windows), которая может быть загружена в процесс Python (например, скомпилирована с совместимыми настройками компилятора) и экспортирует [функцию инициализации](https://python-all.ru/3/c-api/extension-modules.html#extension-export-hook).

Чтобы библиотека импортировалась по умолчанию (то есть с помощью [`importlib.machinery.ExtensionFileLoader`](https://python-all.ru/3/library/importlib.html#importlib.machinery.ExtensionFileLoader)), она должна быть доступна в [`sys.path`](https://python-all.ru/3/library/sys.html#sys.path), и её имя должно соответствовать имени модуля с расширением, указанным в [`importlib.machinery.EXTENSION_SUFFIXES`](https://python-all.ru/3/library/importlib.html#importlib.machinery.EXTENSION_SUFFIXES).

> **Примечание**
>
> Сборку, упаковку и распространение модулей расширения лучше выполнять с помощью сторонних инструментов, и это выходит за рамки данного документа. Подходящим инструментом является Setuptools, документация которого находится по адресу [https://setuptools.pypa.io/en/latest/setuptools.html](https://python-all.ru/3/c-api/extension-modules.html).

Обычно функция инициализации возвращает определение модуля, инициализированное с помощью [`PyModuleDef_Init()`](https://python-all.ru/3/c-api/extension-modules.html#c.PyModuleDef_Init). Это позволяет разбить процесс создания на несколько этапов:

- До выполнения какого-либо значимого кода Python может определить, какие возможности поддерживает модуль, и может скорректировать окружение или отказаться от загрузки несовместимого расширения.
- По умолчанию Python сам создаёт объект модуля – то есть делает то же самое, что [`object.__new__()`](https://python-all.ru/3/reference/datamodel.html#object.__new__) для классов. Также он устанавливает начальные атрибуты, такие как [`__package__`](https://python-all.ru/3/reference/datamodel.html#module.__package__) и [`__loader__`](https://python-all.ru/3/reference/datamodel.html#module.__loader__).
- Затем объект модуля инициализируется с помощью кода, специфичного для расширения – аналога [`__init__()`](https://python-all.ru/3/reference/datamodel.html#object.__init__) для классов.

Это называется *многофазной инициализацией*, чтобы отличать её от устаревшей (но всё ещё поддерживаемой) схемы *однофазной инициализации*, при которой функция инициализации возвращает полностью сконструированный модуль. Подробнее см. [раздел об однофазной инициализации ниже](https://python-all.ru/3/c-api/extension-modules.html#single-phase-initialization).

Changed in version 3.5: Added support for multi-phase initialization ([**PEP 489**](https://python-all.ru/3/c-api/extension-modules.html)).

## Несколько экземпляров модуля

По умолчанию модули расширения не являются синглтонами. Например, если удалить запись [`sys.modules`](https://python-all.ru/3/library/sys.html#sys.modules) и повторно импортировать модуль, создаётся новый объект модуля, который обычно наполняется новыми объектами методов и типов. Старый модуль подлежит обычной сборке мусора. Такое поведение аналогично поведению модулей на чистом Python.

Additional module instances may be created in [sub-interpreters](https://python-all.ru/3/c-api/subinterpreters.html#sub-interpreter-support) or after Python runtime reinitialization ([`Py_Finalize()`](https://python-all.ru/3/c-api/interp-lifecycle.html#c.Py_Finalize) and [`Py_Initialize()`](https://python-all.ru/3/c-api/interp-lifecycle.html#c.Py_Initialize)). In these cases, sharing Python objects between module instances would likely cause crashes or undefined behavior.

To avoid such issues, each instance of an extension module should be *isolated*: changes to one instance should not implicitly affect the others, and all state owned by the module, including references to Python objects, should be specific to a particular module instance. See [Isolating Extension Modules](https://python-all.ru/3/howto/isolating-extensions.html#isolating-extensions-howto) for more details and a practical guide.

A simpler way to avoid these issues is [raising an error on repeated initialization](https://python-all.ru/3/howto/isolating-extensions.html#isolating-extensions-optout).

All modules are expected to support [sub-interpreters](https://python-all.ru/3/c-api/subinterpreters.html#sub-interpreter-support), or otherwise explicitly signal a lack of support. This is usually achieved by isolation or blocking repeated initialization, as above. A module may also be limited to the main interpreter using the [`Py_mod_multiple_interpreters`](https://python-all.ru/3/c-api/module.html#c.Py_mod_multiple_interpreters) slot.

## Функция инициализации

Функция инициализации, определённая модулем расширения, имеет следующую сигнатуру:

#### `PyObject *PyInit_modulename(void)`

Её имя должно быть `PyInit_<name>`, где `<name>` заменяется на имя модуля.

Для модулей с именами, состоящими только из ASCII, функция должна называться `PyInit_<name>`, где `<name>` заменяется на имя модуля. При использовании [многофазной инициализации](https://python-all.ru/3/c-api/extension-modules.html#multi-phase-initialization) допускаются не-ASCII имена модулей. В этом случае имя функции инициализации – `PyInitU_<name>`, где `<name>` кодируется с помощью кодировки Python *punycode*, а дефисы заменяются символами подчёркивания. В Python:

```python
def initfunc_name(name):
    try:
        suffix = b'_' + name.encode('ascii')
    except UnicodeEncodeError:
        suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')
    return b'PyInit' + suffix
```

Рекомендуется определять функцию инициализации с помощью вспомогательного макроса:

#### `PyMODINIT_FUNC`

Объявляет функцию инициализации модуля расширения. Этот макрос:

- задаёт возвращаемый тип [PyObject](https://python-all.ru/3/c-api/structures.html#c.PyObject)\*,
- добавляет любые специальные объявления компоновки, требуемые платформой, и
- для C++ объявляет функцию как `extern "C"`.

Например, модуль с именем `spam` был бы определён так:

```c
static struct PyModuleDef spam_module = {
    .m_base = PyModuleDef_HEAD_INIT,
    .m_name = "spam",
    ...
};

PyMODINIT_FUNC
PyInit_spam(void)
{
    return PyModuleDef_Init(&spam_module);
}
```

Можно экспортировать несколько модулей из одной динамической библиотеки, определив несколько функций инициализации. Однако для их импорта требуются символические ссылки или собственный импортёр, поскольку по умолчанию находится только функция, соответствующая имени файла. Подробнее см. раздел [Multiple modules in one library](https://python-all.ru/3/c-api/extension-modules.html) в [**PEP 489**](https://python-all.ru/3/c-api/extension-modules.html).

Функция инициализации обычно является единственным элементом, не являющимся `static`, определённым в C-исходном коде модуля.

## Многофазная инициализация

Обычно [функция инициализации](https://python-all.ru/3/c-api/extension-modules.html#extension-export-hook) (`PyInit_modulename`) возвращает экземпляр [`PyModuleDef`](https://python-all.ru/3/c-api/module.html#c.PyModuleDef) с не-`NULL` [`m_slots`](https://python-all.ru/3/c-api/module.html#c.PyModuleDef.m_slots). Перед возвратом экземпляр `PyModuleDef` должен быть инициализирован с помощью следующей функции:

#### `PyObject *PyModuleDef_Init(PyModuleDef *def)`

*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.5.*

Гарантирует, что определение модуля является правильно инициализированным объектом Python, который корректно сообщает свой тип и счетчик ссылок.

Возвращает *def*, приведённый к `PyObject*`, или `NULL` в случае ошибки.

Вызов этой функции требуется для [многофазной инициализации](https://python-all.ru/3/c-api/extension-modules.html#multi-phase-initialization). Она не должна использоваться в других контекстах.

Обратите внимание, что Python предполагает, что структуры `PyModuleDef` выделены статически. Эта функция может вернуть как новую ссылку, так и заимствованную; эту ссылку нельзя освобождать.

Добавлено в версии 3.5.

## Устаревшая однофазная инициализация

> **Внимание**
>
> Однофазная инициализация – это устаревший механизм инициализации модулей расширения с известными недостатками и ошибками проектирования. Авторам модулей расширения рекомендуется вместо этого использовать многофазную инициализацию.

При однофазной инициализации [функция инициализации](https://python-all.ru/3/c-api/extension-modules.html#extension-export-hook) (`PyInit_modulename`) должна создать, наполнить и вернуть объект модуля. Обычно это делается с помощью [`PyModule_Create()`](https://python-all.ru/3/c-api/module.html#c.PyModule_Create) и таких функций, как [`PyModule_AddObjectRef()`](https://python-all.ru/3/c-api/module.html#c.PyModule_AddObjectRef).

Однофазная инициализация отличается от [стандартной](https://python-all.ru/3/c-api/extension-modules.html#multi-phase-initialization) следующим образом:

- Однофазные модули являются, или, точнее, *содержат* «одиночки» (синглтоны).

  При первой инициализации модуля Python сохраняет содержимое `__dict__` модуля (то есть, как правило, функции и типы модуля).

  При последующих импортах Python не вызывает функцию инициализации снова. Вместо этого он создаёт новый объект модуля с новым `__dict__` и копирует в него сохранённое содержимое. Например, для однофазного модуля `_testsinglephase` [\[1\]](https://python-all.ru/3/c-api/extension-modules.html#testsinglephase), который определяет функцию `sum` и класс исключения `error`:

  ```python
  >>> import sys
  >>> import _testsinglephase as one
  >>> del sys.modules['_testsinglephase']
  >>> import _testsinglephase as two
  >>> one is two
  False
  >>> one.__dict__ is two.__dict__
  False
  >>> one.sum is two.sum
  True
  >>> one.error is two.error
  True
  ```

  Точное поведение следует считать деталью реализации CPython.
- Чтобы обойти тот факт, что `PyInit_modulename` не принимает аргумент *spec*, некоторое состояние механизма импорта сохраняется и применяется к первому подходящему модулю, созданному во время вызова `PyInit_modulename`. В частности, при импорте подмодуля этот механизм добавляет имя родительского пакета к имени модуля.

  Функция `PyInit_modulename` однофазного модуля должна создать «свой» объект модуля как можно раньше, до того как могут быть созданы любые другие объекты модулей.
- Не-ASCII имена модулей (`PyInitU_modulename`) не поддерживаются.
- Однофазные модули поддерживают функции поиска модулей, такие как [`PyState_FindModule()`](https://python-all.ru/3/c-api/module.html#c.PyState_FindModule).

\[[1](https://python-all.ru/3/c-api/extension-modules.html#id2)\]

`_testsinglephase` – это внутренний модуль, используемый в наборе тестов CPython; ваша установка может включать его, а может и нет.