Изолирование модулей расширений

Переход к состоянию по модулю

Вместо того, чтобы сосредотачиваться на состоянии по интерпретатору, API Python C развивается, чтобы лучше поддерживать более мелкозернистое состояние по модулю. Это означает, что данные на уровне C должны быть привязаны к объекту модуля. Каждый интерпретатор создает свой объект модуля, сохраняя данные разделенными.

Для тестирования изоляции несколько объектов модуля, соответствующих одному расширению, могут даже быть загружены в один интерпретатор.

Состояние по модулю обеспечивает простой способ подумать о жизненном цикле и владении ресурсами: модуль расширения будет инициализирован при создании объекта модуля и очищен при освобождении. В этом отношении, модуль такой же, как и любой другой PyObject*; нет никаких «хуков при завершении работы интерпретатора», о которых нужно думать или забывать.

Обратите внимание, что существуют случаи использования для различных типов «глобальных» переменных: состояние по процессу, по интерпретатору, по потоку или по задаче. С состоянием по модулю по умолчанию эти возможности все еще доступны, но вы должны рассматривать их как исключительные случаи: если вам они нужны, вы должны уделить им дополнительное внимание и тестирование. (Обратите внимание, что в этом руководстве они не рассматриваются.)

Изолированные объекты модулей

Ключевой момент, который следует учитывать при разработке модуля расширения, заключается в том, что из одной общей библиотеки могут быть созданы несколько объектов модулей. Например:

>>> import sys
>>> import binascii
>>> old_binascii = binascii
>>> del sys.modules['binascii']
>>> import binascii  # create a new module object
>>> old_binascii == binascii
False

Как правило, два модуля должны быть полностью независимыми. Все объекты и состояние, специфичные для модуля, должны быть инкапсулированы внутри объекта модуля, а не совместно использоваться с другими объектами модулей и очищаться при освобождении объекта модуля. Поскольку это просто правило, исключения возможны (см. Управление глобальным состоянием), но они потребуют большего внимания и внимания к граничным случаям.

Хотя некоторые модули могут обойтись без таких строгих ограничений, изолированные модули облегчают установление четких ожиданий и руководящих принципов, которые работают в различных случаях использования.

Удивительные граничные случаи

Обратите внимание, что изолированные модули создают некоторые неожиданные граничные случаи. В частности, каждый объект модуля, как правило, не будет совместно использовать свои классы и исключения с другими подобными модулями. Продолжая пример из раздела выше, обратите внимание, что old_binascii.Error и binascii.Error — это отдельные объекты. В следующем коде исключение не перехватывается:

>>> old_binascii.Error == binascii.Error
False
>>> try:
...     old_binascii.unhexlify(b'qwertyuiop')
... except binascii.Error:
...     print('boo')
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
binascii.Error: Non-hexadecimal digit found

Это ожидаемо. Обратите внимание, что чистые модули Python ведут себя аналогично: это часть того, как работает Python.

Цель состоит в том, чтобы сделать модули расширений безопасными на уровне C, а не в том, чтобы сделать поведение хаков интуитивным. Изменение sys.modules «вручную» считается взломом.

Управление глобальным состоянием

Иногда состояние, связанное с модулем Python, не является специфичным для этого модуля, а для всего процесса (или чего-то еще «более глобального», чем модуль). Например:

• Модуль readline управляет терминалом.
• Модуль, работающий на плате, хочет управлять встроенным светодиодом.

В этих случаях модуль Python должен предоставлять доступ к глобальному состоянию, а не владеть им. Если это возможно, напишите модуль так, чтобы несколько копий его могли независимо получать доступ к состоянию (наряду с другими библиотеками, как для Python, так и для других языков). Если это невозможно, рассмотрите явную блокировку.

Если необходимо использовать глобальное состояние процесса, самый простой способ избежать проблем с несколькими интерпретаторами — явно запретить загрузку модуля более одного раза в процессе — см. Исключение из правил: ограничение до одного объекта модуля на процесс.

Управление состоянием по модулю

Для использования состояния по модулю используйте многофазную инициализацию модулей расширений. Это сигнал, что ваш модуль правильно поддерживает несколько интерпретаторов.

Установите PyModuleDef.m_size на положительное число, чтобы запросить столько байтов памяти, локально выделенных для модуля. Обычно это будет размер некоторого специфичного для модуля struct, который может хранить все состояние уровня C модуля. В частности, именно сюда вы должны поместить указатели на классы (включая исключения, но исключая статические типы) и настройки (например, csv’s field_size_limit) которые необходимы коду C для функционирования.

Если состояние модуля включает PyObject указатели, объект модуля должен содержать ссылки на эти объекты и реализовывать хуки на уровне модуля m_traverse, m_clear и m_free. Эти хуки работают как tp_traverse, tp_clear и tp_free класса. Добавление их потребует определённой работы и сделает код длиннее; это плата за модули, которые могут быть корректно разгружены.

Пример модуля со статусом по модулю в настоящее время доступен в виде xxlimited; пример инициализации модуля показан в конце файла.

Исключение из правил: ограничение до одного объекта модуля на процесс

Неотрицательное значение PyModuleDef.m_size сигнализирует, что модуль поддерживает несколько интерпретаторов правильно. Если это еще не так для вашего модуля, вы можете явно сделать ваш модуль загружаемым только один раз на процесс. Например:

static int loaded = 0;

static int
exec_module(PyObject* module)
{
    if (loaded) {
        PyErr_SetString(PyExc_ImportError,
                        "cannot load module more than once per process");
        return -1;
    }
    loaded = 1;
    // ... rest of initialization
}

Доступ к состоянию модуля из функций

Доступ к состоянию из функций на уровне модуля прост. Функции получают объект модуля в качестве первого аргумента; для извлечения состояния вы можете использовать PyModule_GetState:

static PyObject *
func(PyObject *module, PyObject *args)
{
    my_struct *state = (my_struct*)PyModule_GetState(module);
    if (state == NULL) {
        return NULL;
    }
    // ... rest of logic
}

Изменение статических типов на типы кучи

Статические типы могут быть преобразованы в типы кучи, но обратите внимание, что API типов кучи не был разработан для «беспричинного» преобразования из статических типов — то есть, для создания типа, работающего точно так же, как данный статический тип. Таким образом, при переписывании определения класса в новом API вы, вероятно, случайно измените несколько деталей (например, возможность сериализации pickle или унаследованные слоты). Всегда тестируйте детали, которые для вас важны.

Обратите особое внимание на следующие два момента (хотя это не исчерпывающий список):

• В отличие от статических типов, объекты типа кучи по умолчанию изменяемы. Используйте флаг Py_TPFLAGS_IMMUTABLETYPE, чтобы предотвратить изменяемость.
• Типы кучи по умолчанию наследуют tp_new, поэтому их можно будет создать из кода Python. Вы можете предотвратить это с помощью флага Py_TPFLAGS_DISALLOW_INSTANTIATION.

Определение типов кучи

Типы кучи можно создать, заполнив структуру PyType_Spec, описание или «чертёж» класса, и вызвав PyType_FromModuleAndSpec() для построения нового объекта класса.

Класс в целом должен храниться как в состоянии модуля (для безопасного доступа из C), так и в __dict__ модуля (для доступа из кода Python).

Протокол сбора мусора

Экземпляры типов кучи содержат ссылку на их тип. Это гарантирует, что тип не будет уничтожен до того, как будут уничтожены все его экземпляры, но может привести к циклам ссылок, которые необходимо разорвать сборщику мусора.

Для предотвращения утечек памяти экземпляры типов кучи должны реализовывать протокол сбора мусора. То есть, типы кучи должны:

• Иметь флаг Py_TPFLAGS_HAVE_GC.
• Определить функцию обхода с помощью Py_tp_traverse, которая посещает тип (например, используя Py_VISIT(Py_TYPE(self))).

Дополнительные соображения см. в документации по Py_TPFLAGS_HAVE_GC и tp_traverse.

API для определения типов кучи развивался органически, что делает его немного неудобным в текущем состоянии. Следующие разделы помогут вам разобраться с распространёнными проблемами.

static int my_traverse(PyObject *self, visitproc visit, void *arg)
{
    if (Py_Version >= 0x03090000) {
        Py_VISIT(Py_TYPE(self));
    }
    return 0;
}

base->tp_traverse(self, visit, arg)

if (base->tp_flags & Py_TPFLAGS_HEAPTYPE) {
    // a heap type's tp_traverse already visited Py_TYPE(self)
} else {
    if (Py_Version >= 0x03090000) {
        Py_VISIT(Py_TYPE(self));
    }
}

static void my_dealloc(PyObject *self)
{
    PyObject_GC_UnTrack(self);
    ...
    PyTypeObject *type = Py_TYPE(self);
    type->tp_free(self);
    Py_DECREF(type);
}

Доступ к состоянию модуля из классов

Если у вас есть объект типа, определённый с помощью PyType_FromModuleAndSpec(), вы можете вызвать PyType_GetModule() для получения связанного модуля, а затем PyModule_GetState() для получения состояния модуля.

Чтобы сэкономить некоторые трудоёмкие шаги по обработке ошибок, вы можете объединить эти два шага с помощью PyType_GetModuleState(), что даёт:

my_struct *state = (my_struct*)PyType_GetModuleState(type);
if (state == NULL) {
    return NULL;
}

Доступ к состоянию модуля из обычных методов

Доступ к состоянию модуля из методов класса несколько сложнее, но возможен благодаря API, представленному в Python 3.9. Чтобы получить состояние, сначала необходимо получить определяющий класс, а затем состояние модуля из него.

Основной проблемой является получение класса, в котором был определён метод, или «определяющий класс» этого метода вкратце. Определяющий класс может иметь ссылку на модуль, частью которого он является.

Не путайте определяющий класс с Py_TYPE(self). Если метод вызывается на подклассе вашего типа, Py_TYPE(self) будет ссылаться на этот подкласс, который может быть определён в другом модуле, нежели ваш.

class Base:
    def get_type_of_self(self):
        return type(self)

    def get_defining_class(self):
        return __class__

class Sub(Base):
    pass

Чтобы метод получил свой «определяющий класс», он должен использовать METH_METHOD | METH_FASTCALL | METH_KEYWORDS calling convention и соответствующую PyCMethod сигнатуру:

PyObject *PyCMethod(
    PyObject *self,               // object the method was called on
    PyTypeObject *defining_class, // defining class
    PyObject *const *args,        // C array of arguments
    Py_ssize_t nargs,             // length of "args"
    PyObject *kwnames)            // NULL, or dict of keyword arguments

После получения определяющего класса вызовите PyType_GetModuleState() для получения состояния связанного с ним модуля.

Например:

static PyObject *
example_method(PyObject *self,
        PyTypeObject *defining_class,
        PyObject *const *args,
        Py_ssize_t nargs,
        PyObject *kwnames)
{
    my_struct *state = (my_struct*)PyType_GetModuleState(defining_class);
    if (state == NULL) {
        return NULL;
    }
    ... // rest of logic
}

PyDoc_STRVAR(example_method_doc, "...");

static PyMethodDef my_methods[] = {
    {"example_method",
      (PyCFunction)(void(*)(void))example_method,
      METH_METHOD|METH_FASTCALL|METH_KEYWORDS,
      example_method_doc}
    {NULL},
}

Доступ к состоянию модуля из методов слотов, геттеров и сеттеров

Методы слотов — быстрые C-эквиваленты специальных методов, таких как nb_add для __add__ или tp_new для инициализации — имеют очень простой API, не позволяющий передавать определяющий класс, в отличие от PyCMethod. То же самое относится к геттерам и сеттерам, определённым с помощью PyGetSetDef.

Для доступа к состоянию модуля в этих случаях используйте функцию PyType_GetModuleByDef() и передайте определение модуля. После получения модуля вызовите PyModule_GetState() для получения состояния:

PyObject *module = PyType_GetModuleByDef(Py_TYPE(self), &module_def);
my_struct *state = (my_struct*)PyModule_GetState(module);
if (state == NULL) {
    return NULL;
}

PyType_GetModuleByDef() работает путём поиска в порядке разрешения методов (то есть, во всех суперклассах) первого суперкласса, у которого есть соответствующий модуль.

Срок существования состояния модуля

При сборке мусора объекта модуля его состояние модуля освобождается. Для каждого указателя на (часть) состояние модуля необходимо удерживать ссылку на объект модуля.

Обычно это не проблема, так как типы, созданные с помощью PyType_FromModuleAndSpec(), и их экземпляры, удерживают ссылку на модуль. Однако необходимо быть внимательными с подсчётом ссылок, когда вы ссылаетесь на состояние модуля из других мест, таких как обратные вызовы для внешних библиотек.

Область действия по классам

В настоящее время (на момент Python 3.11) невозможно прикрепить состояние к отдельным типам без обращения к особенностям реализации CPython (что может измениться в будущем — возможно, ирония заключается в том, что для этого появится правильное решение для области действия по классам).

Безотходное преобразование в типы кучи

API типов кучи не был разработан для «безотходного» преобразования из статических типов; то есть, создания типа, который работает точно так же, как заданный статический тип.