Определение модулей расширения¶Defining extension modules

Несколько экземпляров модуля¶Multiple module instances

По умолчанию модули расширения не являются синглтонами. Например, если удалить запись sys.modules и повторно импортировать модуль, создаётся новый объект модуля, который обычно наполняется новыми объектами методов и типов. Старый модуль подлежит обычной сборке мусора. Такое поведение аналогично поведению модулей на чистом Python.

Additional module instances may be created in sub-interpreters or after Python runtime reinitialization (Py_Finalize() and 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 for more details and a practical guide.

A simpler way to avoid these issues is raising an error on repeated initialization.

All modules are expected to support sub-interpreters, 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 slot.

Функция инициализации¶Initialization function

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

PyObject *PyInit_modulename(void)¶

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

Для модулей с именами, состоящими только из ASCII, функция должна называться PyInit_<name>, где <name> заменяется на имя модуля. При использовании многофазной инициализации допускаются не-ASCII имена модулей. В этом случае имя функции инициализации – PyInitU_<name>, где <name> кодируется с помощью кодировки Python punycode, а дефисы заменяются символами подчёркивания. В 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*,

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

• для C++ объявляет функцию как extern "C".

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

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 в PEP 489.

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

Многофазная инициализация¶Multi-phase initialization

Обычно функция инициализации (PyInit_modulename) возвращает экземпляр PyModuleDef с не-NULL m_slots. Перед возвратом экземпляр PyModuleDef должен быть инициализирован с помощью следующей функции:

PyObject *PyModuleDef_Init(PyModuleDef *def)¶

Часть Stable ABI начиная с версии 3.5.

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

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

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

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

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

Устаревшая однофазная инициализация¶Legacy single-phase initialization

При однофазной инициализации функция инициализации (PyInit_modulename) должна создать, наполнить и вернуть объект модуля. Обычно это делается с помощью PyModule_Create() и таких функций, как PyModule_AddObjectRef().

Однофазная инициализация отличается от стандартной следующим образом:

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

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

  При последующих импортах Python не вызывает функцию инициализации снова. Вместо этого он создаёт новый объект модуля с новым __dict__ и копирует в него сохранённое содержимое. Например, для однофазного модуля _testsinglephase [1], который определяет функцию sum и класс исключения error:

  >>> 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().