4. Building C and C++ Extensions¶
A C extension for CPython is a shared library (e.g. a .so
file on Linux,
.pyd
on Windows), which exports an initialization function.
To be importable, the shared library must be available on PYTHONPATH
,
and must be named after the module name, with an appropriate extension.
When using setuptools, the correct filename is generated automatically.
The initialization function has the signature:
It returns either a fully initialized module, or a PyModuleDef
instance. See Initializing C modules for details.
For modules with ASCII-only names, the function must be named
PyInit_<modulename>
, with <modulename>
replaced by the name of the
module. When using Multi-phase initialization, non-ASCII module names
are allowed. In this case, the initialization function name is
PyInitU_<modulename>
, with <modulename>
encoded using Python’s
punycode encoding with hyphens replaced by underscores. In 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
It is possible to export multiple modules from a single shared library by defining multiple initialization functions. However, importing them requires using symbolic links or a custom importer, because by default only the function corresponding to the filename is found. See the „Multiple modules in one library” section in PEP 489 for details.
4.1. Building C and C++ Extensions with setuptools¶
Python 3.12 and newer no longer come with distutils. Please refer to the
setuptools
documentation at
https://setuptools.readthedocs.io/en/latest/setuptools.html
to learn more about how build and distribute C/C++ extensions with setuptools.