Enter Per-Module State¶

Instead of focusing on per-interpreter state, Python’s C API is evolvingto better support the more granularper-module state.This means that C-level data should be attached to amodule object.Each interpreter creates its own module object, keeping the data separate.For testing the isolation, multiple module objects corresponding to a singleextension can even be loaded in a single interpreter.

Per-module state provides an easy way to think about lifetime andresource ownership: the extension module will initialize when amodule object is created, and clean up when it’s freed. In this regard,a module is just like any otherPyObject*; there are no “oninterpreter shutdown” hooks to think—or forget—about.

Note that there are use cases for different kinds of “globals”:per-process, per-interpreter, per-thread or per-task state.With per-module state as the default, these are still possible,but you should treat them as exceptional cases:if you need them, you should give them additional care and testing.(Note that this guide does not cover them.)

Isolated Module Objects¶

The key point to keep in mind when developing an extension module isthat several module objects can be created from a single shared library.For example:

>>>importsys>>>importbinascii>>>old_binascii=binascii>>>delsys.modules['binascii']>>>importbinascii# create a new module object>>>old_binascii==binasciiFalse

As a rule of thumb, the two modules should be completely independent.All objects and state specific to the module should be encapsulatedwithin the module object, not shared with other module objects, andcleaned up when the module object is deallocated.Since this just is a rule of thumb, exceptions are possible(seeManaging Global State), but they will need morethought and attention to edge cases.

While some modules could do with less stringent restrictions, isolatedmodules make it easier to set clear expectations and guidelines thatwork across a variety of use cases.

Surprising Edge Cases¶

Note that isolated modules do create some surprising edge cases. Mostnotably, each module object will typically not share its classes andexceptions with other similar modules. Continuing from theexample above,note thatold_binascii.Error andbinascii.Error areseparate objects. In the following code, the exception isnot caught:

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

This is expected. Notice that pure-Python modules behave the same way:it is a part of how Python works.

The goal is to make extension modules safe at the C level, not to makehacks behave intuitively. Mutatingsys.modules “manually” countsas a hack.

Managing Global State¶

Sometimes, the state associated with a Python module is not specific to that module, butto the entire process (or something else “more global” than a module).For example:

• Thereadline module managesthe terminal.

• A module running on a circuit board wants to controlthe on-boardLED.

In these cases, the Python module should provideaccess to the globalstate, rather thanown it. If possible, write the module so thatmultiple copies of it can access the state independently (along withother libraries, whether for Python or other languages). If that is notpossible, consider explicit locking.

If it is necessary to use process-global state, the simplest way toavoid issues with multiple interpreters is to explicitly prevent amodule from being loaded more than once per process—seeOpt-Out: Limiting to One Module Object per Process.

Managing Per-Module State¶

To use per-module state, usemulti-phase extension module initialization.This signals that your module supports multiple interpreters correctly.

SetPyModuleDef.m_size to a positive number to request that manybytes of storage local to the module. Usually, this will be set to thesize of some module-specificstruct, which can store all of themodule’s C-level state. In particular, it is where you should putpointers to classes (including exceptions, but excluding static types)and settings (e.g.csv’sfield_size_limit)which the C code needs to function.

If the module state includesPyObject pointers, the module objectmust hold references to those objects and implement the module-level hooksm_traverse,m_clear andm_free. These work liketp_traverse,tp_clear andtp_free of a class. Adding them willrequire some work and make the code longer; this is the price formodules which can be unloaded cleanly.

An example of a module with per-module state is currently available asxxlimited;example module initialization shown at the bottom of the file.

Opt-Out: Limiting to One Module Object per Process¶

A non-negativePyModuleDef.m_size signals that a module supportsmultiple interpreters correctly. If this is not yet the case for yourmodule, you can explicitly make your module loadable only once perprocess. For example:

// A process-wide flagstaticintloaded=0;// Mutex to provide thread safety (only needed for free-threaded Python)staticPyMutexmodinit_mutex={0};staticintexec_module(PyObject*module){PyMutex_Lock(&modinit_mutex);if(loaded){PyMutex_Unlock(&modinit_mutex);PyErr_SetString(PyExc_ImportError,"cannot load module more than once per process");return-1;}loaded=1;PyMutex_Unlock(&modinit_mutex);// ... rest of initialization}

If your module’sPyModuleDef.m_clear function is able to preparefor future re-initialization, it should clear theloaded flag.In this case, your module won’t support multiple instances existingconcurrently, but it will, for example, support being loaded afterPython runtime shutdown (Py_FinalizeEx()) and re-initialization(Py_Initialize()).

Module State Access from Functions¶

Accessing the state from module-level functions is straightforward.Functions get the module object as their first argument; for extractingthe state, you can usePyModule_GetState:

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

Changing Static Types to Heap Types¶

Static types can be converted to heap types, but note thatthe heap type API was not designed for “lossless” conversionfrom static types—that is, creating a type that works exactly like a givenstatic type.So, when rewriting the class definition in a new API,you are likely to unintentionally change a few details (e.g. pickleabilityor inherited slots).Always test the details that are important to you.

Watch out for the following two points in particular (but note that this is nota comprehensive list):

• Unlike static types, heap type objects are mutable by default.Use thePy_TPFLAGS_IMMUTABLETYPE flag to prevent mutability.

• Heap types inherittp_new by default,so it may become possible to instantiate them from Python code.You can prevent this with thePy_TPFLAGS_DISALLOW_INSTANTIATION flag.

Defining Heap Types¶

Heap types can be created by filling aPyType_Spec structure, adescription or “blueprint” of a class, and callingPyType_FromModuleAndSpec() to construct a new class object.

The class should generally be stored inboth the module state (forsafe access from C) and the module’s__dict__ (for access fromPython code).

Garbage-Collection Protocol¶

Instances of heap types hold a reference to their type.This ensures that the type isn’t destroyed before all its instances are,but may result in reference cycles that need to be broken by thegarbage collector.

To avoid memory leaks, instances of heap types must implement thegarbage collection protocol.That is, heap types should:

• Have thePy_TPFLAGS_HAVE_GC flag.

• Define a traverse function usingPy_tp_traverse, whichvisits the type (e.g. usingPy_VISIT(Py_TYPE(self))).

Please refer to the documentation ofPy_TPFLAGS_HAVE_GC andtp_traversefor additional considerations.

The API for defining heap types grew organically, leaving itsomewhat awkward to use in its current state.The following sections will guide you through common issues.

staticintmy_traverse(PyObject*self,visitprocvisit,void*arg){if(Py_Version>=0x03090000){Py_VISIT(Py_TYPE(self));}return0;}

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

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

Module State Access from Classes¶

If you have a type object defined withPyType_FromModuleAndSpec(),you can callPyType_GetModule() to get the associated module, and thenPyModule_GetState() to get the module’s state.

To save a some tedious error-handling boilerplate code, you can combinethese two steps withPyType_GetModuleState(), resulting in:

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

Module State Access from Regular Methods¶

Accessing the module-level state from methods of a class is somewhat morecomplicated, but is possible thanks to API introduced in Python 3.9.To get the state, you need to first get thedefining class, and thenget the module state from it.

The largest roadblock is gettingthe class a method was defined in, orthat method’s “defining class” for short. The defining class can have areference to the module it is part of.

Do not confuse the defining class withPy_TYPE(self). If the methodis called on asubclass of your type,Py_TYPE(self) will refer tothat subclass, which may be defined in different module than yours.

classBase:defget_type_of_self(self):returntype(self)defget_defining_class(self):return__class__classSub(Base):pass

For a method to get its “defining class”, it must use theMETH_METHOD | METH_FASTCALL | METH_KEYWORDScallingconventionand the correspondingPyCMethod signature:

PyObject*PyCMethod(PyObject*self,// object the method was called onPyTypeObject*defining_class,// defining classPyObject*const*args,// C array of argumentsPy_ssize_tnargs,// length of "args"PyObject*kwnames)// NULL, or dict of keyword arguments

Once you have the defining class, callPyType_GetModuleState() to getthe state of its associated module.

For example:

staticPyObject*example_method(PyObject*self,PyTypeObject*defining_class,PyObject*const*args,Py_ssize_tnargs,PyObject*kwnames){my_struct*state=(my_struct*)PyType_GetModuleState(defining_class);if(state==NULL){returnNULL;}...// rest of logic}PyDoc_STRVAR(example_method_doc,"...");staticPyMethodDefmy_methods[]={{"example_method",(PyCFunction)(void(*)(void))example_method,METH_METHOD|METH_FASTCALL|METH_KEYWORDS,example_method_doc}{NULL},}

Module State Access from Slot Methods, Getters and Setters¶

Slot methods—the fast C equivalents for special methods, such asnb_add for__add__ ortp_new for initialization—have a very simple API thatdoesn’t allow passing in the defining class, unlike withPyCMethod.The same goes for getters and setters defined withPyGetSetDef.

To access the module state in these cases, use thePyType_GetModuleByDef() function, and pass in the module definition.Once you have the module, callPyModule_GetState()to get the state:

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

PyType_GetModuleByDef() works by searching themethod resolution order (i.e. all superclasses) for the firstsuperclass that has a corresponding module.

Lifetime of the Module State¶

When a module object is garbage-collected, its module state is freed.For each pointer to (a part of) the module state, you must hold a referenceto the module object.

Usually this is not an issue, because types created withPyType_FromModuleAndSpec(), and their instances, hold a referenceto the module.However, you must be careful in reference counting when you referencemodule state from other places, such as callbacks for externallibraries.

Per-Class Scope¶

It is currently (as of Python 3.11) not possible to attach state to individualtypes without relying on CPython implementation details (which may changein the future—perhaps, ironically, to allow a proper solution forper-class scope).

Lossless Conversion to Heap Types¶

The heap type API was not designed for “lossless” conversion from static types;that is, creating a type that works exactly like a given static type.