devdocs/python~3.12/extending%2Fbuilding.html


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

 <span id="building"></span><h1> Building C and C++ Extensions</h1> <p>A C extension for CPython is a shared library (e.g. a <code>.so</code> file on Linux, <code>.pyd</code> on Windows), which exports an <em>initialization function</em>.</p> <p>To be importable, the shared library must be available on <span class="target" id="index-0"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONPATH"><code>PYTHONPATH</code></a>, and must be named after the module name, with an appropriate extension. When using setuptools, the correct filename is generated automatically.</p> <p>The initialization function has the signature:</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PyInit_modulename">
<code>PyObject *PyInit_modulename(void)</code> </dt> <dd></dd>
</dl> <p>It returns either a fully initialized module, or a <a class="reference internal" href="../c-api/module#c.PyModuleDef" title="PyModuleDef"><code>PyModuleDef</code></a> instance. See <a class="reference internal" href="../c-api/module#initializing-modules"><span class="std std-ref">Initializing C modules</span></a> for details.</p> <p>For modules with ASCII-only names, the function must be named <code>PyInit_&lt;modulename&gt;</code>, with <code>&lt;modulename&gt;</code> replaced by the name of the module. When using <a class="reference internal" href="../c-api/module#multi-phase-initialization"><span class="std std-ref">Multi-phase initialization</span></a>, non-ASCII module names are allowed. In this case, the initialization function name is <code>PyInitU_&lt;modulename&gt;</code>, with <code>&lt;modulename&gt;</code> encoded using Python’s <em>punycode</em> encoding with hyphens replaced by underscores. In Python:</p> <pre data-language="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
</pre> <p>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 <em>“Multiple modules in one library”</em> section in <span class="target" id="index-1"></span><a class="pep reference external" href="https://peps.python.org/pep-0489/"><strong>PEP 489</strong></a> for details.</p> <section id="building-c-and-c-extensions-with-setuptools"> <span id="setuptools-index"></span><span id="install-index"></span><h2>
<span class="section-number">4.1. </span>Building C and C++ Extensions with setuptools</h2> <p>Python 3.12 and newer no longer come with distutils. Please refer to the <code>setuptools</code> documentation at <a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html">https://setuptools.readthedocs.io/en/latest/setuptools.html</a> to learn more about how build and distribute C/C++ extensions with setuptools.</p> </section> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
    <a href="https://docs.python.org/3.12/extending/building.html" class="_attribution-link">https://docs.python.org/3.12/extending/building.html</a>
  </p>
</div>