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

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

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

Дополнительные экземпляры модуля могут создаваться в субинтерпретаторах или после повторной инициализации среды выполнения Python (Py_Finalize() и Py_Initialize()). В этих случаях совместное использование объектов Python экземплярами модуля, вероятно, приведёт к сбоям или неопределённому поведению.

Чтобы избежать подобных проблем, каждый экземпляр модуля расширения должен быть изолирован: изменения одного экземпляра не должны неявно влиять на остальные, а всё состояние, принадлежащее модулю, включая ссылки на объекты Python, должно относиться к конкретному экземпляру модуля. Дополнительные сведения и практическое руководство см. в разделе «Изоляция модулей расширения».

Более простой способ избежать этих проблем — вызывать ошибку при повторной инициализации.

Предполагается, что все модули поддерживают субинтерпретаторы или явно сообщают об отсутствии такой поддержки. Обычно этого достигают изоляцией или блокировкой повторной инициализации, как описано выше. Модуль также можно ограничить основным интерпретатором с помощью слота Py_mod_multiple_interpreters.

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

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

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);
}

Можно экспортировать несколько модулей из одной разделяемой библиотеки, определив несколько функций инициализации. Однако для их импорта необходимо использовать символические ссылки или пользовательский импортёр, поскольку по умолчанию находится только функция, соответствующая имени файла. Подробности см. в разделе «Несколько модулей в одной библиотеке» в PEP 489.

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

Многоэтапная инициализация

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

PyObject *PyModuleDef_Init(PyModuleDef *def)

Входит в стабильный ABI начиная с версии 3.5.

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

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

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

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

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

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

При одноэтапной инициализации функция инициализации (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().