Extending and Embedding Python, Release 3.9.5 systems use one global namespace for the Python interpreter and all extension modules (Windows, for example), whereas others require an explicit list of imported symbols at module link time (AIX is one example), or offer a choice of different strategies (most Unices). And even if symbols are globally visible, the module whose functions one wishes to call might not have been loaded yet! Portability therefore requires not to make any assumptions about symbol visibility. This means that all symbols in extension modules should be declared$_{static}$, except for the module’s initialization function, in order to avoid name clashes with other extension modules (as discussed in section The Module’s Method Table and Initialization Function ). And it means that symbols that should be accessible from other extension modules must be exported in a different way. Python provides a special mechanism to pass C-level information (pointers) from one extension module to another one: Capsules. A Capsule is a Python data type which stores a pointer ($_{void *}$ ). Capsules can only be created and accessed via their C API, but they can be passed around like any other Python object. In particular, they can be assigned to a name in an extension module’s namespace. Other extension modules can then import this module, retrieve the value of this name, and then retrieve the pointer from the Capsule. There are many ways in which Capsules can be used to export the C API of an extension module. Each function could get its own Capsule, or all C API pointers could be stored in an array whose address is published in a Capsule. And the various tasks of storing and retrieving the pointers can be distributed in different ways between the module providing the code and the client modules. Whichever method you choose, it’s important to name your Capsules properly. The function PyCapsule_New() takes a name parameter ($_{const char *}$ ); you’re permitted to pass in a$_{NULL}$ name, but we strongly encourage you to specify a name. Properly named Capsules provide a degree of runtime type-safety; there is no feasible way to tell one unnamed Capsule from another. In particular, Capsules used to expose C APIs should be given a name following this convention: modulename.attributename The convenience function$_{PyCapsule_Import()}$ makes it easy to load a C API provided via a Capsule, but only if the Capsule’s name matches this convention. This behavior gives C API users a high degree of certainty that the Capsule they load contains the correct C API. The following example demonstrates an approach that puts most of the burden on the writer of the exporting module, which is appropriate for commonly used library modules. It stores all C API pointers (just one in the example!) in an array of$_{void}$pointers which becomes the value of a Capsule. The header file corresponding to the module provides a macro that takes care of importing the module and retrieving its C API pointers; client modules only have to call this macro before accessing the C API. The exporting module is a modification of the$_{spam}$module from section A Simple Example . The function$_{spam.}$ system() does not call the C library function$_{system()}$ directly, but a function$_{PySpam_System()}$ , which would of course do something more complicated in reality (such as adding “spam” to every command). This function PySpam_System() is also exported to other extension modules. The function$_{PySpam_System()}$ is a plain C function, declared$_{static}$like everything else: static int PySpam_System( const char *command) { return system(command); } static PyObject * spam_system(PyObject *self, PyObject*args) { const char *command; int sts; if (!PyArg_ParseTuple(args, "s",&command)) The function$_{spam_system()}$ is modified in a trivial way: (continues on next page) Chapter 2. Creating extensions without third party tools 20