| Server IP : 121.121.20.254 / Your IP : 216.73.217.51 Web Server : Microsoft-IIS/10.0 System : Windows NT WEB-SERVER 10.0 build 20348 (Windows Server 2022) AMD64 User : IUSR ( 0) PHP Version : 8.3.28 Disable Function : NONE MySQL : ON | cURL : ON | WGET : OFF | Perl : OFF | Python : OFF | Sudo : OFF | Pkexec : OFF Directory : C:/Python315/Doc/html/c-api/ |
Upload File : |
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta property="og:title" content="Module Objects" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://docs.python.org/3/c-api/module.html" />
<meta property="og:site_name" content="Python documentation" />
<meta property="og:description" content="Module definition: Modules created using the C API are typically defined using an array of PySlot structs, which provides a “description” of how a module should be created. See Definition slots for..." />
<meta property="og:image" content="_static/og-image.png" />
<meta property="og:image:alt" content="Python documentation" />
<meta name="description" content="Module definition: Modules created using the C API are typically defined using an array of PySlot structs, which provides a “description” of how a module should be created. See Definition slots for..." />
<meta name="theme-color" content="#3776ab">
<meta property="og:image:width" content="200">
<meta property="og:image:height" content="200">
<title>Module Objects — Python 3.15.0rc1 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=4365c8fe" />
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
<script src="../_static/documentation_options.js?v=791e38b1"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.15.0rc1 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Iterator Objects" href="iterator.html" />
<link rel="prev" title="File objects" href="file.html" />
<link rel="canonical" href="https://docs.python.org/3/c-api/module.html">
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
<link rel="shortcut icon" type="image/png" href="../_static/py.svg">
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/menu.js"></script>
<script type="text/javascript" src="../_static/search-focus.js"></script>
<script type="text/javascript" src="../_static/themetoggle.js"></script>
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
<meta name="readthedocs-addons-api-version" content="1">
</head>
<body>
<div class="mobile-nav">
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">
<nav class="nav-content" role="navigation">
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<span class="nav-items-wrapper">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Python logo">
</a>
<span class="version_switcher_placeholder"></span>
<form role="search" class="search" action="../search.html" method="get">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
</svg>
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q">
<input type="submit" value="Go">
</form>
</span>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label>
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Module Objects</a><ul>
<li><a class="reference internal" href="#module-definition">Module definition</a><ul>
<li><a class="reference internal" href="#metadata-slots">Metadata slots</a></li>
<li><a class="reference internal" href="#feature-slots">Feature slots</a></li>
<li><a class="reference internal" href="#creation-and-initialization-slots">Creation and initialization slots</a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-state">Module state</a><ul>
<li><a class="reference internal" href="#slots-for-defining-module-state">Slots for defining module state</a></li>
<li><a class="reference internal" href="#module-token">Module token</a></li>
</ul>
</li>
<li><a class="reference internal" href="#creating-extension-modules-dynamically">Creating extension modules dynamically</a></li>
<li><a class="reference internal" href="#module-definition-struct">Module definition struct</a></li>
<li><a class="reference internal" href="#support-functions">Support functions</a><ul>
<li><a class="reference internal" href="#module-lookup-single-phase-initialization">Module lookup (single-phase initialization)</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="file.html"
title="previous chapter">File objects</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="iterator.html"
title="next chapter">Iterator Objects</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "c-api/module.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>This page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a bug</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/main/Doc/c-api/module.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="iterator.html" title="Iterator Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="file.html" title="File objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.15.0rc1 Documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API reference manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
<li class="nav-item nav-item-this"><a href="">Module Objects</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-objects">
<span id="moduleobjects"></span><h1>Module Objects<a class="headerlink" href="#module-objects" title="Link to this heading">¶</a></h1>
<dl class="c var" id="index-0">
<dt class="sig sig-object c" id="c.PyModule_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_Type</span></span></span><a class="headerlink" href="#c.PyModule_Type" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-1">This instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> represents the Python module type. This
is exposed to Python programs as <a class="reference internal" href="../library/types.html#types.ModuleType" title="types.ModuleType"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.ModuleType</span></code></a>.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_Check">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_Check</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">p</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_Check" title="Link to this definition">¶</a><br /></dt>
<dd><p>Return true if <em>p</em> is a module object, or a subtype of a module object.
This function always succeeds.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_CheckExact">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_CheckExact</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">p</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_CheckExact" title="Link to this definition">¶</a><br /></dt>
<dd><p>Return true if <em>p</em> is a module object, but not a subtype of
<a class="reference internal" href="#c.PyModule_Type" title="PyModule_Type"><code class="xref c c-data docutils literal notranslate"><span class="pre">PyModule_Type</span></code></a>. This function always succeeds.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_NewObject">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_NewObject</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">name</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_NewObject" title="Link to this definition">¶</a><br /></dt>
<dd><em class="refcount return_new_ref">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><p id="index-2">Return a new module object with <a class="reference internal" href="../reference/datamodel.html#module.__name__" title="module.__name__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">module.__name__</span></code></a> set to <em>name</em>.
The module’s <code class="xref py py-attr docutils literal notranslate"><span class="pre">__name__</span></code>, <a class="reference internal" href="../reference/datamodel.html#module.__doc__" title="module.__doc__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__doc__</span></code></a>,
<a class="reference internal" href="../reference/datamodel.html#module.__package__" title="module.__package__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__package__</span></code></a> and <a class="reference internal" href="../reference/datamodel.html#module.__loader__" title="module.__loader__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__loader__</span></code></a> attributes are
filled in (all but <code class="xref py py-attr docutils literal notranslate"><span class="pre">__name__</span></code> are set to <code class="docutils literal notranslate"><span class="pre">None</span></code>). The caller is
responsible for setting a <a class="reference internal" href="../reference/datamodel.html#module.__file__" title="module.__file__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__file__</span></code></a> attribute.</p>
<p>Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> with an exception set on error.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.3.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.4: </span><a class="reference internal" href="../reference/datamodel.html#module.__package__" title="module.__package__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__package__</span></code></a> and <a class="reference internal" href="../reference/datamodel.html#module.__loader__" title="module.__loader__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__loader__</span></code></a> are now set to
<code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_New">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_New</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">name</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_New" title="Link to this definition">¶</a><br /></dt>
<dd><em class="refcount return_new_ref">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Similar to <a class="reference internal" href="#c.PyModule_NewObject" title="PyModule_NewObject"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_NewObject()</span></code></a>, but the name is a UTF-8 encoded
string instead of a Unicode object.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_GetDict">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_GetDict</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_GetDict" title="Link to this definition">¶</a><br /></dt>
<dd><em class="refcount return_borrowed_ref">Return value: Borrowed reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-3">Return the dictionary object that implements <em>module</em>’s namespace; this object
is the same as the <a class="reference internal" href="../reference/datamodel.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a> attribute of the module object.
If <em>module</em> is not a module object (or a subtype of a module object),
<a class="reference internal" href="../library/exceptions.html#SystemError" title="SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a> is raised and <code class="docutils literal notranslate"><span class="pre">NULL</span></code> is returned.</p>
<p>It is recommended extensions use other <code class="docutils literal notranslate"><span class="pre">PyModule_*</span></code> and
<code class="docutils literal notranslate"><span class="pre">PyObject_*</span></code> functions rather than directly manipulate a module’s
<a class="reference internal" href="../reference/datamodel.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a>.</p>
<p>The returned reference is borrowed from the module; it is valid until
the module is destroyed.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_GetNameObject">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_GetNameObject</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_GetNameObject" title="Link to this definition">¶</a><br /></dt>
<dd><em class="refcount return_new_ref">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><p id="index-4">Return <em>module</em>’s <a class="reference internal" href="../reference/datamodel.html#module.__name__" title="module.__name__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__name__</span></code></a> value. If the module does not
provide one, or if it is not a string, <a class="reference internal" href="../library/exceptions.html#SystemError" title="SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a> is raised and
<code class="docutils literal notranslate"><span class="pre">NULL</span></code> is returned.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.3.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_GetName">
<span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_GetName</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_GetName" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Similar to <a class="reference internal" href="#c.PyModule_GetNameObject" title="PyModule_GetNameObject"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_GetNameObject()</span></code></a> but return the name encoded to
<code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code>.</p>
<p>The returned buffer is only valid until the module is renamed or destroyed.
Note that Python code may rename a module by setting its <a class="reference internal" href="../reference/datamodel.html#module.__name__" title="module.__name__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__name__</span></code></a>
attribute.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_GetDef">
<a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef"><span class="n"><span class="pre">PyModuleDef</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_GetDef</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_GetDef" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a pointer to the <a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyModuleDef</span></code></a> struct from which the module was
created, or <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if the module wasn’t created from a definition.</p>
<p>On error, return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> with an exception set.
Use <a class="reference internal" href="exceptions.html#c.PyErr_Occurred" title="PyErr_Occurred"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_Occurred()</span></code></a> to tell this case apart from a missing
<code class="xref c c-type docutils literal notranslate"><span class="pre">PyModuleDef</span></code>.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_GetFilenameObject">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_GetFilenameObject</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_GetFilenameObject" title="Link to this definition">¶</a><br /></dt>
<dd><em class="refcount return_new_ref">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-5">Return the name of the file from which <em>module</em> was loaded using <em>module</em>’s
<a class="reference internal" href="../reference/datamodel.html#module.__file__" title="module.__file__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__file__</span></code></a> attribute. If this is not defined, or if it is not a
string, raise <a class="reference internal" href="../library/exceptions.html#SystemError" title="SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a> and return <code class="docutils literal notranslate"><span class="pre">NULL</span></code>; otherwise return
a reference to a Unicode object.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.2.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_GetFilename">
<span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_GetFilename</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_GetFilename" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Similar to <a class="reference internal" href="#c.PyModule_GetFilenameObject" title="PyModule_GetFilenameObject"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_GetFilenameObject()</span></code></a> but return the filename
encoded to ‘utf-8’.</p>
<p>The returned buffer is only valid until the module’s <a class="reference internal" href="../reference/datamodel.html#module.__file__" title="module.__file__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__file__</span></code></a> attribute
is reassigned or the module is destroyed.</p>
<div class="deprecated">
<p><span class="versionmodified deprecated">Deprecated since version 3.2: </span><a class="reference internal" href="#c.PyModule_GetFilename" title="PyModule_GetFilename"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_GetFilename()</span></code></a> raises <a class="reference internal" href="../library/exceptions.html#UnicodeEncodeError" title="UnicodeEncodeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnicodeEncodeError</span></code></a> on
unencodable filenames, use <a class="reference internal" href="#c.PyModule_GetFilenameObject" title="PyModule_GetFilenameObject"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_GetFilenameObject()</span></code></a> instead.</p>
</div>
</dd></dl>
<section id="module-definition">
<span id="pymoduledef-slot"></span><span id="c-module-slots"></span><h2>Module definition<a class="headerlink" href="#module-definition" title="Link to this heading">¶</a></h2>
<p>Modules created using the C API are typically defined using an
array of <a class="reference internal" href="slots.html#c.PySlot" title="PySlot"><code class="xref c c-type docutils literal notranslate"><span class="pre">PySlot</span></code></a> structs, which provides a “description” of how a
module should be created.
See <a class="reference internal" href="slots.html#capi-slots"><span class="std std-ref">Definition slots</span></a> for more information on slots in general.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.15: </span>Previously, a <a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyModuleDef</span></code></a> struct was necessary to define modules.
The older way of defining modules is still available: consult either the
<a class="reference internal" href="#pymoduledef"><span class="std std-ref">Module definition struct</span></a> section or earlier versions of this documentation
if you plan to support earlier Python versions.</p>
</div>
<p>The slots array is usually used to define an extension module’s “main”
module object (see <a class="reference internal" href="extension-modules.html#extension-modules"><span class="std std-ref">Defining extension modules</span></a> for details).
It can also be used to
<a class="reference internal" href="#module-from-slots"><span class="std std-ref">create extension modules dynamically</span></a>.</p>
<p>Unless specified otherwise, the same slot ID may not be repeated
in an array of slots.</p>
<section id="metadata-slots">
<h3>Metadata slots<a class="headerlink" href="#metadata-slots" title="Link to this heading">¶</a></h3>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_mod_name">
<span class="sig-name descname"><span class="n"><span class="pre">Py_mod_name</span></span></span><a class="headerlink" href="#c.Py_mod_name" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> for the name of the new module,
as a NUL-terminated UTF8-encoded <code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></code>.</p>
<p>Note that modules are typically created using a
<a class="reference internal" href="../library/importlib.html#importlib.machinery.ModuleSpec" title="importlib.machinery.ModuleSpec"><code class="xref py py-class docutils literal notranslate"><span class="pre">ModuleSpec</span></code></a>, and when they are, the
name from the spec will be used instead of <code class="xref c c-data docutils literal notranslate"><span class="pre">Py_mod_name</span></code>.
However, it is still recommended to include this slot for introspection
and debugging purposes.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15: </span>Use <a class="reference internal" href="#c.PyModuleDef.m_name" title="PyModuleDef.m_name"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyModuleDef.m_name</span></code></a> instead to support previous versions.</p>
</div>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_mod_doc">
<span class="sig-name descname"><span class="n"><span class="pre">Py_mod_doc</span></span></span><a class="headerlink" href="#c.Py_mod_doc" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-type docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> for the docstring of the new
module, as a NUL-terminated UTF8-encoded <code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></code>.</p>
<p>Usually it is set to a variable created with <a class="reference internal" href="intro.html#c.PyDoc_STRVAR" title="PyDoc_STRVAR"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyDoc_STRVAR</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15: </span>Use <a class="reference internal" href="#c.PyModuleDef.m_doc" title="PyModuleDef.m_doc"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyModuleDef.m_doc</span></code></a> instead to support previous versions.</p>
</div>
</dd></dl>
</section>
<section id="feature-slots">
<h3>Feature slots<a class="headerlink" href="#feature-slots" title="Link to this heading">¶</a></h3>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_mod_abi">
<span class="sig-name descname"><span class="n"><span class="pre">Py_mod_abi</span></span></span><a class="headerlink" href="#c.Py_mod_abi" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> whose value points to
a <a class="reference internal" href="stable.html#c.PyABIInfo" title="PyABIInfo"><code class="xref c c-struct docutils literal notranslate"><span class="pre">PyABIInfo</span></code></a> structure describing the ABI that
the extension is using.</p>
<p>A suitable <code class="xref c c-struct docutils literal notranslate"><span class="pre">PyABIInfo</span></code> variable can be defined using the
<a class="reference internal" href="stable.html#c.PyABIInfo_VAR" title="PyABIInfo_VAR"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyABIInfo_VAR</span></code></a> macro, as in:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyABIInfo_VAR</span><span class="p">(</span><span class="n">abi_info</span><span class="p">);</span>
<span class="k">static</span><span class="w"> </span><span class="n">PySlot</span><span class="w"> </span><span class="n">mymodule_slots</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="n">PySlot_DATA</span><span class="p">(</span><span class="n">Py_mod_abi</span><span class="p">,</span><span class="w"> </span><span class="o">&</span><span class="n">abi_info</span><span class="p">),</span>
<span class="w"> </span><span class="p">...</span>
<span class="p">};</span>
</pre></div>
</div>
<p>When creating a module, Python checks the value of this slot
using <a class="reference internal" href="stable.html#c.PyABIInfo_Check" title="PyABIInfo_Check"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyABIInfo_Check()</span></code></a>.</p>
<p>This slot is required, except for modules created from
<a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef"><code class="xref c c-struct docutils literal notranslate"><span class="pre">PyModuleDef</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_mod_multiple_interpreters">
<span class="sig-name descname"><span class="n"><span class="pre">Py_mod_multiple_interpreters</span></span></span><a class="headerlink" href="#c.Py_mod_multiple_interpreters" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.12.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> whose value is one of:</p>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED">
<span class="sig-name descname"><span class="n"><span class="pre">Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED</span></span></span><a class="headerlink" href="#c.Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED" title="Link to this definition">¶</a><br /></dt>
<dd><p>The module does not support being imported in subinterpreters.</p>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED">
<span class="sig-name descname"><span class="n"><span class="pre">Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED</span></span></span><a class="headerlink" href="#c.Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED" title="Link to this definition">¶</a><br /></dt>
<dd><p>The module supports being imported in subinterpreters,
but only when they share the main interpreter’s GIL.
(See <a class="reference internal" href="../howto/isolating-extensions.html#isolating-extensions-howto"><span class="std std-ref">Isolating Extension Modules</span></a>.)</p>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_MOD_PER_INTERPRETER_GIL_SUPPORTED">
<span class="sig-name descname"><span class="n"><span class="pre">Py_MOD_PER_INTERPRETER_GIL_SUPPORTED</span></span></span><a class="headerlink" href="#c.Py_MOD_PER_INTERPRETER_GIL_SUPPORTED" title="Link to this definition">¶</a><br /></dt>
<dd><p>The module supports being imported in subinterpreters,
even when they have their own GIL.
(See <a class="reference internal" href="../howto/isolating-extensions.html#isolating-extensions-howto"><span class="std std-ref">Isolating Extension Modules</span></a>.)</p>
</dd></dl>
<p>This slot determines whether or not importing this module
in a subinterpreter will fail.</p>
<p>If <code class="docutils literal notranslate"><span class="pre">Py_mod_multiple_interpreters</span></code> is not specified, the import
machinery defaults to <code class="docutils literal notranslate"><span class="pre">Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED</span></code>.</p>
<p>For historical reasons, the values are declared as pointers (<code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code>).
When using <a class="reference internal" href="slots.html#c.PySlot" title="PySlot"><code class="xref c c-type docutils literal notranslate"><span class="pre">PySlot</span></code></a> arrays, use <a class="reference internal" href="slots.html#c.PySlot_DATA" title="PySlot_DATA"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PySlot_DATA</span></code></a> for
<code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_multiple_interpreters</span></code>:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PySlot_DATA</span><span class="p">(</span><span class="n">Py_mod_multiple_interpreters</span><span class="p">,</span>
<span class="w"> </span><span class="n">Py_MOD_PER_INTERPRETER_GIL_SUPPORTED</span><span class="p">)</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.12.</span></p>
</div>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_mod_gil">
<span class="sig-name descname"><span class="n"><span class="pre">Py_mod_gil</span></span></span><a class="headerlink" href="#c.Py_mod_gil" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.13.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> whose value is one of:</p>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_MOD_GIL_USED">
<span class="sig-name descname"><span class="n"><span class="pre">Py_MOD_GIL_USED</span></span></span><a class="headerlink" href="#c.Py_MOD_GIL_USED" title="Link to this definition">¶</a><br /></dt>
<dd><p>The module depends on the presence of the global interpreter lock (GIL),
and may access global state without synchronization.</p>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_MOD_GIL_NOT_USED">
<span class="sig-name descname"><span class="n"><span class="pre">Py_MOD_GIL_NOT_USED</span></span></span><a class="headerlink" href="#c.Py_MOD_GIL_NOT_USED" title="Link to this definition">¶</a><br /></dt>
<dd><p>The module is safe to run without an active GIL.</p>
</dd></dl>
<p>This slot is ignored by Python builds not configured with
<a class="reference internal" href="../using/configure.html#cmdoption-disable-gil"><code class="xref std std-option docutils literal notranslate"><span class="pre">--disable-gil</span></code></a>. Otherwise, it determines whether or not importing
this module will cause the GIL to be automatically enabled. See
<a class="reference internal" href="../whatsnew/3.13.html#whatsnew313-free-threaded-cpython"><span class="std std-ref">Free-threaded CPython</span></a> for more detail.</p>
<p>If <code class="docutils literal notranslate"><span class="pre">Py_mod_gil</span></code> is not specified, the import machinery defaults to
<code class="docutils literal notranslate"><span class="pre">Py_MOD_GIL_USED</span></code>.</p>
<p>For historical reasons, the values are declared as pointers (<code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code>).
When using <a class="reference internal" href="slots.html#c.PySlot" title="PySlot"><code class="xref c c-type docutils literal notranslate"><span class="pre">PySlot</span></code></a> arrays, use <a class="reference internal" href="slots.html#c.PySlot_DATA" title="PySlot_DATA"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PySlot_DATA</span></code></a> for
<code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_gil</span></code>:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PySlot_DATA</span><span class="p">(</span><span class="n">Py_mod_gil</span><span class="p">,</span><span class="w"> </span><span class="n">Py_MOD_GIL_NOT_USED</span><span class="p">)</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.13.</span></p>
</div>
</dd></dl>
</section>
<section id="creation-and-initialization-slots">
<h3>Creation and initialization slots<a class="headerlink" href="#creation-and-initialization-slots" title="Link to this heading">¶</a></h3>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_mod_create">
<span class="sig-name descname"><span class="n"><span class="pre">Py_mod_create</span></span></span><a class="headerlink" href="#c.Py_mod_create" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.5.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> for a function that creates
the module object itself.
The function must have the signature:</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_mod_create.create_module">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">create_module</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">spec</span></span>, <a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef"><span class="n"><span class="pre">PyModuleDef</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">def</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_mod_create.create_module" title="Link to this definition">¶</a><br /></dt>
<dd></dd></dl>
<p>The function will be called with:</p>
<ul class="simple">
<li><p><em>spec</em>: a <code class="docutils literal notranslate"><span class="pre">ModuleSpec</span></code>-like object, meaning that any attributes defined
for <a class="reference internal" href="../library/importlib.html#importlib.machinery.ModuleSpec" title="importlib.machinery.ModuleSpec"><code class="xref py py-class docutils literal notranslate"><span class="pre">importlib.machinery.ModuleSpec</span></code></a> have matching semantics.
However, any of the attributes may be missing.</p></li>
<li><p><em>def</em>: <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, or the module definition if the module is created from one.</p></li>
</ul>
<p>The function should return a new module object, or set an error
and return <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.</p>
<p>This function should be kept minimal. In particular, it should not
call arbitrary Python code, as trying to import the same module again may
result in an infinite loop.</p>
<p>If <code class="docutils literal notranslate"><span class="pre">Py_mod_create</span></code> is not specified, the import machinery will create
a normal module object using <a class="reference internal" href="#c.PyModule_New" title="PyModule_New"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_New()</span></code></a>. The name is taken from
<em>spec</em>, not the definition, to allow extension modules to dynamically adjust
to their place in the module hierarchy and be imported under different
names through symlinks, all while sharing a single module definition.</p>
<p>There is no requirement for the returned object to be an instance of
<a class="reference internal" href="#c.PyModule_Type" title="PyModule_Type"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyModule_Type</span></code></a>.
However, some slots may only be used with
<code class="xref c c-type docutils literal notranslate"><span class="pre">PyModule_Type</span></code> instances; in particular:</p>
<ul class="simple">
<li><p><a class="reference internal" href="#c.Py_mod_exec" title="Py_mod_exec"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_exec</span></code></a>,</p></li>
<li><p><a class="reference internal" href="#ext-module-state-slots"><span class="std std-ref">module state slots</span></a> (<code class="docutils literal notranslate"><span class="pre">Py_mod_state_*</span></code>),</p></li>
<li><p><a class="reference internal" href="#c.Py_mod_token" title="Py_mod_token"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_token</span></code></a>.</p></li>
</ul>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.5.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.15: </span>The <em>slots</em> argument may be a <code class="docutils literal notranslate"><span class="pre">ModuleSpec</span></code>-like object, rather than
a true <a class="reference internal" href="../library/importlib.html#importlib.machinery.ModuleSpec" title="importlib.machinery.ModuleSpec"><code class="xref py py-class docutils literal notranslate"><span class="pre">ModuleSpec</span></code></a> instance.
Note that previous versions of CPython did not enforce this.</p>
<p>The <em>def</em> argument may now be <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, since modules are not necessarily
made from definitions.</p>
</div>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_mod_exec">
<span class="sig-name descname"><span class="n"><span class="pre">Py_mod_exec</span></span></span><a class="headerlink" href="#c.Py_mod_exec" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.5.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> for a function that will
<em class="dfn">execute</em>, or initialize, the module.
This function does the equivalent to executing the code of a Python module:
typically, it adds classes and constants to the module.
The signature of the function is:</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_mod_exec.exec_module">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">exec_module</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_mod_exec.exec_module" title="Link to this definition">¶</a><br /></dt>
<dd></dd></dl>
<p>See the <a class="reference internal" href="#capi-module-support-functions"><span class="std std-ref">Support functions</span></a> section for some useful
functions to call.</p>
<p>For backwards compatibility, the <a class="reference internal" href="#c.PyModuleDef.m_slots" title="PyModuleDef.m_slots"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyModuleDef.m_slots</span></code></a> array may
contain multiple <code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_exec</span></code> slots; these are processed in the
order they appear in the array.
Elsewhere (that is, in arguments to <a class="reference internal" href="#c.PyModule_FromSlotsAndSpec" title="PyModule_FromSlotsAndSpec"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_FromSlotsAndSpec()</span></code></a>
and in return values of <code class="samp docutils literal notranslate"><span class="pre">PyModExport_</span><em><span class="pre"><name></span></em></code>), repeating the slot
is not allowed.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.5.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.15: </span>Repeated <code class="docutils literal notranslate"><span class="pre">Py_mod_exec</span></code> slots are disallowed, except in
<a class="reference internal" href="#c.PyModuleDef.m_slots" title="PyModuleDef.m_slots"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyModuleDef.m_slots</span></code></a>.</p>
</div>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_mod_methods">
<span class="sig-name descname"><span class="n"><span class="pre">Py_mod_methods</span></span></span><a class="headerlink" href="#c.Py_mod_methods" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> for a table of module-level
functions, as an array of <a class="reference internal" href="structures.html#c.PyMethodDef" title="PyMethodDef"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyMethodDef</span></code></a> values suitable as the
<em>functions</em> argument to <a class="reference internal" href="#c.PyModule_AddFunctions" title="PyModule_AddFunctions"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_AddFunctions()</span></code></a>.</p>
<p>Like other slot IDs, a slots array may only contain one
<code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_methods</span></code> entry.
To add functions from multiple <a class="reference internal" href="structures.html#c.PyMethodDef" title="PyMethodDef"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyMethodDef</span></code></a> arrays, call
<a class="reference internal" href="#c.PyModule_AddFunctions" title="PyModule_AddFunctions"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_AddFunctions()</span></code></a> in the <a class="reference internal" href="#c.Py_mod_exec" title="Py_mod_exec"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_exec</span></code></a> function.</p>
<p>The table must be statically allocated (or otherwise guaranteed to outlive
the module object).</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15: </span>Use <a class="reference internal" href="#c.PyModuleDef.m_methods" title="PyModuleDef.m_methods"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyModuleDef.m_methods</span></code></a> instead to support previous versions.</p>
</div>
</dd></dl>
</section>
</section>
<section id="module-state">
<span id="ext-module-state"></span><h2>Module state<a class="headerlink" href="#module-state" title="Link to this heading">¶</a></h2>
<p>Extension modules can have <em>module state</em> – a
piece of memory that is allocated on module creation,
and freed when the module object is deallocated.
The module state is specified using <a class="reference internal" href="#ext-module-state-slots"><span class="std std-ref">dedicated slots</span></a>.</p>
<p>A typical use of module state is storing an exception type – or indeed <em>any</em>
type object defined by the module –</p>
<p>Unlike the module’s Python attributes, Python code cannot replace or delete
data stored in module state.</p>
<p>Keeping per-module information in attributes and module state, rather than in
static globals, makes module objects <em>isolated</em> and safer for use in
multiple sub-interpreters.
It also helps Python do an orderly clean-up when it shuts down.</p>
<p>Extensions that keep references to Python objects as part of module state must
implement <a class="reference internal" href="#c.Py_mod_state_traverse" title="Py_mod_state_traverse"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_state_traverse</span></code></a> and <a class="reference internal" href="#c.Py_mod_state_clear" title="Py_mod_state_clear"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_state_clear</span></code></a>
functions to avoid reference leaks.</p>
<p>To retrieve the state from a given module, use the following functions:</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_GetState">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_GetState</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_GetState" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return the “state” of the module, that is, a pointer to the block of memory
allocated at module creation time, or <code class="docutils literal notranslate"><span class="pre">NULL</span></code>. See
<a class="reference internal" href="#c.Py_mod_state_size" title="Py_mod_state_size"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_state_size</span></code></a>.</p>
<p>On error, return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> with an exception set.
Use <a class="reference internal" href="exceptions.html#c.PyErr_Occurred" title="PyErr_Occurred"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_Occurred()</span></code></a> to tell this case apart from missing
module state.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_GetStateSize">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_GetStateSize</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">result</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_GetStateSize" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p>Set <em>*result</em> to the size of <em>module</em>’s state, as specified
using <a class="reference internal" href="#c.Py_mod_state_size" title="Py_mod_state_size"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_state_size</span></code></a> (or <a class="reference internal" href="#c.PyModuleDef.m_size" title="PyModuleDef.m_size"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyModuleDef.m_size</span></code></a>),
and return 0.</p>
<p>On error, set <em>*result</em> to -1, and return -1 with an exception set.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
<section id="slots-for-defining-module-state">
<span id="ext-module-state-slots"></span><h3>Slots for defining module state<a class="headerlink" href="#slots-for-defining-module-state" title="Link to this heading">¶</a></h3>
<p>The following <a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">slot</span> <span class="pre">IDs</span></code></a> are available for
defining the module state.</p>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_mod_state_size">
<span class="sig-name descname"><span class="n"><span class="pre">Py_mod_state_size</span></span></span><a class="headerlink" href="#c.Py_mod_state_size" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> for the size of the module state,
in bytes.</p>
<p>Setting the value to a non-negative value means that the module can be
re-initialized and specifies the additional amount of memory it requires
for its state.</p>
<p>See <span class="target" id="index-6"></span><a class="pep reference external" href="https://peps.python.org/pep-3121/"><strong>PEP 3121</strong></a> for more details.</p>
<p>Use <a class="reference internal" href="#c.PyModule_GetStateSize" title="PyModule_GetStateSize"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_GetStateSize()</span></code></a> to retrieve the size of a given module.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15: </span>Use <a class="reference internal" href="#c.PyModuleDef.m_size" title="PyModuleDef.m_size"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyModuleDef.m_size</span></code></a> instead to support previous versions.</p>
</div>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_mod_state_traverse">
<span class="sig-name descname"><span class="n"><span class="pre">Py_mod_state_traverse</span></span></span><a class="headerlink" href="#c.Py_mod_state_traverse" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> for a traversal function to call
during GC traversal of the module object.</p>
<p>The signature of the function, and meanings of the arguments,
is similar as for <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyTypeObject.tp_traverse</span></code></a>:</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_mod_state_traverse.traverse_module_state">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">traverse_module_state</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span>, <a class="reference internal" href="gcsupport.html#c.visitproc" title="visitproc"><span class="n"><span class="pre">visitproc</span></span></a><span class="w"> </span><span class="n"><span class="pre">visit</span></span>, <span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">arg</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_mod_state_traverse.traverse_module_state" title="Link to this definition">¶</a><br /></dt>
<dd></dd></dl>
<p>This function is not called if the module state was requested but is not
allocated yet. This is the case immediately after the module is created
and before the module is executed (<a class="reference internal" href="#c.Py_mod_exec" title="Py_mod_exec"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_mod_exec</span></code></a> function). More
precisely, this function is not called if the state size
(<a class="reference internal" href="#c.Py_mod_state_size" title="Py_mod_state_size"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_mod_state_size</span></code></a>) is greater than 0 and the module state
(as returned by <a class="reference internal" href="#c.PyModule_GetState" title="PyModule_GetState"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_GetState()</span></code></a>) is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15: </span>Use <a class="reference internal" href="#c.PyModuleDef.m_traverse" title="PyModuleDef.m_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyModuleDef.m_traverse</span></code></a> instead to support previous versions.</p>
</div>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_mod_state_clear">
<span class="sig-name descname"><span class="n"><span class="pre">Py_mod_state_clear</span></span></span><a class="headerlink" href="#c.Py_mod_state_clear" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> for a clear function to call
during GC clearing of the module object.</p>
<p>The signature of the function is:</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_mod_state_clear.clear_module_state">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">clear_module_state</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_mod_state_clear.clear_module_state" title="Link to this definition">¶</a><br /></dt>
<dd></dd></dl>
<p>This function is not called if the module state was requested but is not
allocated yet. This is the case immediately after the module is created
and before the module is executed (<a class="reference internal" href="#c.Py_mod_exec" title="Py_mod_exec"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_mod_exec</span></code></a> function). More
precisely, this function is not called if the state size
(<a class="reference internal" href="#c.Py_mod_state_size" title="Py_mod_state_size"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_mod_state_size</span></code></a>) is greater than 0 and the module state
(as returned by <a class="reference internal" href="#c.PyModule_GetState" title="PyModule_GetState"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_GetState()</span></code></a>) is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.</p>
<p>Like <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyTypeObject.tp_clear</span></code></a>, this function is not <em>always</em>
called before a module is deallocated. For example, when reference
counting is enough to determine that an object is no longer used,
the cyclic garbage collector is not involved and
the <a class="reference internal" href="#c.Py_mod_state_free" title="Py_mod_state_free"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_state_free</span></code></a> function is called directly.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15: </span>Use <a class="reference internal" href="#c.PyModuleDef.m_clear" title="PyModuleDef.m_clear"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyModuleDef.m_clear</span></code></a> instead to support previous versions.</p>
</div>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_mod_state_free">
<span class="sig-name descname"><span class="n"><span class="pre">Py_mod_state_free</span></span></span><a class="headerlink" href="#c.Py_mod_state_free" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> for a function to call during
deallocation of the module object.</p>
<p>The signature of the function is:</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_mod_state_free.free_module_state">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">free_module_state</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_mod_state_free.free_module_state" title="Link to this definition">¶</a><br /></dt>
<dd></dd></dl>
<p>This function is not called if the module state was requested but is not
allocated yet. This is the case immediately after the module is created
and before the module is executed (<a class="reference internal" href="#c.Py_mod_exec" title="Py_mod_exec"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_mod_exec</span></code></a> function). More
precisely, this function is not called if the state size
(<a class="reference internal" href="#c.Py_mod_state_size" title="Py_mod_state_size"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_mod_state_size</span></code></a>) is greater than 0 and the module state
(as returned by <a class="reference internal" href="#c.PyModule_GetState" title="PyModule_GetState"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_GetState()</span></code></a>) is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15: </span>Use <a class="reference internal" href="#c.PyModuleDef.m_free" title="PyModuleDef.m_free"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyModuleDef.m_free</span></code></a> instead to support previous versions.</p>
</div>
</dd></dl>
</section>
<section id="module-token">
<span id="ext-module-token"></span><h3>Module token<a class="headerlink" href="#module-token" title="Link to this heading">¶</a></h3>
<p>Each module may have an associated <em>token</em>: a pointer-sized value intended to
identify of the module state’s memory layout.
This means that if you have a module object, but you are not sure if it
“belongs” to your extension, you can check using code like this:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyObject</span><span class="w"> </span><span class="o">*</span><span class="n">module</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o"><</span><span class="n">the</span><span class="w"> </span><span class="n">module</span><span class="w"> </span><span class="n">in</span><span class="w"> </span><span class="n">question</span><span class="o">></span>
<span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">module_token</span><span class="p">;</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">PyModule_GetToken</span><span class="p">(</span><span class="n">module</span><span class="p">,</span><span class="w"> </span><span class="o">&</span><span class="n">module_token</span><span class="p">)</span><span class="w"> </span><span class="o"><</span><span class="w"> </span><span class="mi">0</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="nb">NULL</span><span class="p">;</span>
<span class="p">}</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">module_token</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="n">your_token</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="n">PyErr_SetString</span><span class="p">(</span><span class="n">PyExc_ValueError</span><span class="p">,</span><span class="w"> </span><span class="s">"unexpected module"</span><span class="p">)</span>
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="nb">NULL</span><span class="p">;</span>
<span class="p">}</span>
<span class="c1">// This module's state has the expected memory layout; it's safe to cast</span>
<span class="k">struct</span><span class="w"> </span><span class="nc">my_state</span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">(</span><span class="k">struct</span><span class="w"> </span><span class="nc">my_state</span><span class="o">*</span><span class="p">)</span><span class="n">PyModule_GetState</span><span class="p">(</span><span class="n">module</span><span class="p">)</span>
</pre></div>
</div>
<p>A module’s token – and the <em>your_token</em> value to use in the above code – is:</p>
<ul class="simple">
<li><p>For modules created with <a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyModuleDef</span></code></a>: the address of that
<code class="xref c c-type docutils literal notranslate"><span class="pre">PyModuleDef</span></code>;</p></li>
<li><p>For modules defined with the <a class="reference internal" href="#c.Py_mod_token" title="Py_mod_token"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_token</span></code></a> slot: the value
of that slot;</p></li>
<li><p>For modules created from an <code class="docutils literal notranslate"><span class="pre">PyModExport_*</span></code>
<a class="reference internal" href="extension-modules.html#extension-export-hook"><span class="std std-ref">export hook</span></a>: the slots array that the export
hook returned (unless overridden with <a class="reference internal" href="#c.Py_mod_token" title="Py_mod_token"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_token</span></code></a>).</p></li>
</ul>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_mod_token">
<span class="sig-name descname"><span class="n"><span class="pre">Py_mod_token</span></span></span><a class="headerlink" href="#c.Py_mod_token" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> for the module token.</p>
<p>If you use this slot to set the module token (rather than rely on the
default), you must ensure that:</p>
<ul class="simple">
<li><p>The pointer outlives the class, so it’s not reused for something else
while the class exists.</p></li>
<li><p>It “belongs” to the extension module where the class lives, so it will not
clash with other extensions.</p></li>
<li><p>If the token points to a <a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyModuleDef</span></code></a> struct, the module should
behave as if it was created from that <code class="xref c c-type docutils literal notranslate"><span class="pre">PyModuleDef</span></code>.
In particular, the module state must have matching layout and semantics.</p></li>
</ul>
<p>Modules created from <a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyModuleDef</span></code></a> always use the address of
the <code class="xref c c-type docutils literal notranslate"><span class="pre">PyModuleDef</span></code> as the token.
This means that <code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_token</span></code> cannot be used in
<a class="reference internal" href="#c.PyModuleDef.m_slots" title="PyModuleDef.m_slots"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyModuleDef.m_slots</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_GetToken">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_GetToken</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span>, <span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">result</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_GetToken" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p>Set <em>*result</em> to the module token for <em>module</em> and return 0.</p>
<p>On error, set <em>*result</em> to NULL, and return -1 with an exception set.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
<p>See also <a class="reference internal" href="type.html#c.PyType_GetModuleByToken" title="PyType_GetModuleByToken"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_GetModuleByToken()</span></code></a>.</p>
</section>
</section>
<section id="creating-extension-modules-dynamically">
<span id="module-from-slots"></span><h2>Creating extension modules dynamically<a class="headerlink" href="#creating-extension-modules-dynamically" title="Link to this heading">¶</a></h2>
<p>The following functions may be used to create an extension module dynamically,
rather than from an extension’s <a class="reference internal" href="extension-modules.html#extension-export-hook"><span class="std std-ref">export hook</span></a>.</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_FromSlotsAndSpec">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_FromSlotsAndSpec</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><a class="reference internal" href="slots.html#c.PySlot" title="PySlot"><span class="n"><span class="pre">PySlot</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">slots</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">spec</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_FromSlotsAndSpec" title="Link to this definition">¶</a><br /></dt>
<dd><em class="refcount return_new_ref">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p>Create a new module object, given an array of <a class="reference internal" href="#pymoduledef-slot"><span class="std std-ref">slots</span></a>
and the <a class="reference internal" href="../library/importlib.html#importlib.machinery.ModuleSpec" title="importlib.machinery.ModuleSpec"><code class="xref py py-class docutils literal notranslate"><span class="pre">ModuleSpec</span></code></a> <em>spec</em>.</p>
<p>The <em>slots</em> argument must point to an array of <a class="reference internal" href="slots.html#c.PySlot" title="PySlot"><code class="xref c c-type docutils literal notranslate"><span class="pre">PySlot</span></code></a>
structures, terminated by an entry with slot ID of 0
(typically written as <a class="reference internal" href="slots.html#c.PySlot_END" title="PySlot_END"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PySlot_END</span></code></a>).
The array must include a <a class="reference internal" href="#c.Py_mod_abi" title="Py_mod_abi"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_mod_abi</span></code></a> entry.</p>
<p>The <em>spec</em> argument may be any <code class="docutils literal notranslate"><span class="pre">ModuleSpec</span></code>-like object, as described
in <a class="reference internal" href="#c.Py_mod_create" title="Py_mod_create"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_create</span></code></a> documentation.
Currently, the <em>spec</em> must have a <code class="docutils literal notranslate"><span class="pre">name</span></code> attribute.</p>
<p>On success, return the new module.
On error, return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> with an exception set.</p>
<p>Note that this does not process the module’s execution slot
(<a class="reference internal" href="#c.Py_mod_exec" title="Py_mod_exec"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_mod_exec</span></code></a>).
Both <code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_FromSlotsAndSpec()</span></code> and <a class="reference internal" href="#c.PyModule_Exec" title="PyModule_Exec"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_Exec()</span></code></a>
must be called to fully initialize a module.
(See also <a class="reference internal" href="extension-modules.html#multi-phase-initialization"><span class="std std-ref">Multi-phase initialization</span></a>.)</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_Exec">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_Exec</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_Exec" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p>Execute the <a class="reference internal" href="#c.Py_mod_exec" title="Py_mod_exec"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_mod_exec</span></code></a> slot(s) of <em>module</em>.</p>
<p>On success, return 0.
On error, return -1 with an exception set.</p>
<p>For clarity: If <em>module</em> has no slots, for example if it uses
<a class="reference internal" href="extension-modules.html#single-phase-initialization"><span class="std std-ref">legacy single-phase initialization</span></a>,
this function does nothing and returns 0.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
</section>
<section id="module-definition-struct">
<span id="pymoduledef"></span><h2>Module definition struct<a class="headerlink" href="#module-definition-struct" title="Link to this heading">¶</a></h2>
<p>Traditionally, extension modules were defined using a <em>module definition</em>
as the “description” of how a module should be created.
Rather than using an array of <a class="reference internal" href="#pymoduledef-slot"><span class="std std-ref">slots</span></a> directly,
the definition has dedicated members for most common functionality,
and allows additional slots as an extension mechanism.</p>
<p>This way of defining modules is still available and there are no plans to
remove it.</p>
<dl class="c type">
<dt class="sig sig-object c" id="c.PyModuleDef">
<span class="k"><span class="pre">type</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyModuleDef</span></span></span><a class="headerlink" href="#c.PyModuleDef" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> (see below).</em><p>The module definition struct, which holds information needed to create
a module object.</p>
<p>This structure must be statically allocated (or be otherwise guaranteed
to be valid while any modules created from it exist).
Usually, there is only one variable of this type for each extension module
defined this way.</p>
<p>The struct, including all members, is part of the
<a class="reference internal" href="stable.html#stable-abi"><span class="std std-ref">Stable ABI</span></a> for non-free-threaded builds (<code class="docutils literal notranslate"><span class="pre">abi3</span></code>).
In the Stable ABI for free-threaded builds (<code class="docutils literal notranslate"><span class="pre">abi3t</span></code>),
this struct is opaque, and unusable in practice; see <a class="reference internal" href="#pymoduledef-slot"><span class="std std-ref">Module definition</span></a>
for a replacement.</p>
<dl class="c member">
<dt class="sig sig-object c" id="c.PyModuleDef.m_base">
<a class="reference internal" href="#c.PyModuleDef_Base" title="PyModuleDef_Base"><span class="n"><span class="pre">PyModuleDef_Base</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">m_base</span></span></span><a class="headerlink" href="#c.PyModuleDef.m_base" title="Link to this definition">¶</a><br /></dt>
<dd><p>Always initialize this member to <a class="reference internal" href="#c.PyModuleDef_HEAD_INIT" title="PyModuleDef_HEAD_INIT"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyModuleDef_HEAD_INIT</span></code></a>:</p>
<dl class="c type">
<dt class="sig sig-object c" id="c.PyModuleDef_Base">
<span class="k"><span class="pre">type</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyModuleDef_Base</span></span></span><a class="headerlink" href="#c.PyModuleDef_Base" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> (see below).</em><p>The type of <code class="xref c c-member docutils literal notranslate"><span class="pre">PyModuleDef.m_base</span></code>.</p>
<p>The struct is part of the <a class="reference internal" href="stable.html#stable-abi"><span class="std std-ref">Stable ABI</span></a> for
non-free-threaded builds (<code class="docutils literal notranslate"><span class="pre">abi3</span></code>).
In the Stable ABI for Free-Threaded Builds
(<code class="docutils literal notranslate"><span class="pre">abi3t</span></code>), this struct is opaque, and unusable in practice.</p>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.PyModuleDef_HEAD_INIT">
<span class="sig-name descname"><span class="n"><span class="pre">PyModuleDef_HEAD_INIT</span></span></span><a class="headerlink" href="#c.PyModuleDef_HEAD_INIT" title="Link to this definition">¶</a><br /></dt>
<dd><p>The required initial value for <code class="xref c c-member docutils literal notranslate"><span class="pre">PyModuleDef.m_base</span></code>.</p>
</dd></dl>
</dd></dl>
<dl class="c member">
<dt class="sig sig-object c" id="c.PyModuleDef.m_name">
<span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">m_name</span></span></span><a class="headerlink" href="#c.PyModuleDef.m_name" title="Link to this definition">¶</a><br /></dt>
<dd><p>Corresponds to the <a class="reference internal" href="#c.Py_mod_name" title="Py_mod_name"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_name</span></code></a> slot.</p>
</dd></dl>
<dl class="c member">
<dt class="sig sig-object c" id="c.PyModuleDef.m_doc">
<span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">m_doc</span></span></span><a class="headerlink" href="#c.PyModuleDef.m_doc" title="Link to this definition">¶</a><br /></dt>
<dd><p>These members correspond to the <a class="reference internal" href="#c.Py_mod_doc" title="Py_mod_doc"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_doc</span></code></a> slot.
Setting this to NULL is equivalent to omitting the slot.</p>
</dd></dl>
<dl class="c member">
<dt class="sig sig-object c" id="c.PyModuleDef.m_size">
<a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">m_size</span></span></span><a class="headerlink" href="#c.PyModuleDef.m_size" title="Link to this definition">¶</a><br /></dt>
<dd><p>Corresponds to the <a class="reference internal" href="#c.Py_mod_state_size" title="Py_mod_state_size"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_state_size</span></code></a> slot.
Setting this to zero is equivalent to omitting the slot.</p>
<p>When using <a class="reference internal" href="extension-modules.html#single-phase-initialization"><span class="std std-ref">legacy single-phase initialization</span></a>
or when creating modules dynamically using <a class="reference internal" href="#c.PyModule_Create" title="PyModule_Create"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_Create()</span></code></a>
or <a class="reference internal" href="#c.PyModule_Create2" title="PyModule_Create2"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_Create2()</span></code></a>, <code class="xref c c-member docutils literal notranslate"><span class="pre">m_size</span></code> may be set to -1.
This indicates that the module does not support sub-interpreters,
because it has global state.</p>
</dd></dl>
<dl class="c member">
<dt class="sig sig-object c" id="c.PyModuleDef.m_methods">
<a class="reference internal" href="structures.html#c.PyMethodDef" title="PyMethodDef"><span class="n"><span class="pre">PyMethodDef</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">m_methods</span></span></span><a class="headerlink" href="#c.PyModuleDef.m_methods" title="Link to this definition">¶</a><br /></dt>
<dd><p>Corresponds to the <a class="reference internal" href="#c.Py_mod_methods" title="Py_mod_methods"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_methods</span></code></a> slot.
Setting this to NULL is equivalent to omitting the slot.</p>
</dd></dl>
<dl class="c member">
<dt class="sig sig-object c" id="c.PyModuleDef.m_slots">
<a class="reference internal" href="#c.PyModuleDef_Slot" title="PyModuleDef_Slot"><span class="n"><span class="pre">PyModuleDef_Slot</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">m_slots</span></span></span><a class="headerlink" href="#c.PyModuleDef.m_slots" title="Link to this definition">¶</a><br /></dt>
<dd><p>An array of additional slots, terminated by a <code class="docutils literal notranslate"><span class="pre">{0,</span> <span class="pre">NULL}</span></code> entry.
Note that the entries use the older <a class="reference internal" href="#c.PyModuleDef_Slot" title="PyModuleDef_Slot"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyModuleDef_Slot</span></code></a> structure,
rather than <a class="reference internal" href="slots.html#c.PySlot" title="PySlot"><code class="xref c c-type docutils literal notranslate"><span class="pre">PySlot</span></code></a>.</p>
<p>If the array contains slots corresponding to <a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyModuleDef</span></code></a>
members, the values must match.
For example, if you use <a class="reference internal" href="#c.Py_mod_name" title="Py_mod_name"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_name</span></code></a> in <code class="xref c c-member docutils literal notranslate"><span class="pre">m_slots</span></code>,
<a class="reference internal" href="#c.PyModuleDef.m_name" title="PyModuleDef.m_name"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyModuleDef.m_name</span></code></a> must be set to the same pointer
(not just an equal string).</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.5: </span>Prior to version 3.5, this member was always set to <code class="docutils literal notranslate"><span class="pre">NULL</span></code>,
and was defined as:</p>
<blockquote>
<div><dl class="c member">
<dt class="sig sig-object c" id="c.PyModuleDef.m_slots.m_reload">
<a class="reference internal" href="gcsupport.html#c.inquiry" title="inquiry"><span class="n"><span class="pre">inquiry</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">m_reload</span></span></span><a class="headerlink" href="#c.PyModuleDef.m_slots.m_reload" title="Link to this definition">¶</a><br /></dt>
<dd></dd></dl>
</div></blockquote>
</div>
<dl class="c type">
<dt class="sig sig-object c" id="c.PyModuleDef_Slot">
<span class="k"><span class="pre">type</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyModuleDef_Slot</span></span></span><a class="headerlink" href="#c.PyModuleDef_Slot" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> (including all members) since version 3.5.</em><p>Older structure defining additional slots of a module.</p>
<p>Note that a <code class="xref c c-type docutils literal notranslate"><span class="pre">PyModuleDef_Slot</span></code> array may be included in a
<code class="xref c c-type docutils literal notranslate"><span class="pre">PySlot</span></code> array using <a class="reference internal" href="#c.Py_mod_slots" title="Py_mod_slots"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_slots</span></code></a>,
and vice versa using <a class="reference internal" href="slots.html#c.Py_slot_subslots" title="Py_slot_subslots"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_slot_subslots</span></code></a>.</p>
<p>Each <code class="xref c c-type docutils literal notranslate"><span class="pre">PyModuleDef_Slot</span></code> structure <code class="docutils literal notranslate"><span class="pre">modslot</span></code> is interpreted
as the following <a class="reference internal" href="slots.html#c.PySlot" title="PySlot"><code class="xref c c-type docutils literal notranslate"><span class="pre">PySlot</span></code></a> structure:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">PySlot</span><span class="p">){</span>
<span class="w"> </span><span class="p">.</span><span class="n">sl_id</span><span class="o">=</span><span class="n">modslot</span><span class="p">.</span><span class="n">slot</span><span class="p">,</span>
<span class="w"> </span><span class="p">.</span><span class="n">sl_flags</span><span class="o">=</span><span class="n">PySlot_INTPTR</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">sub_static</span><span class="p">,</span>
<span class="w"> </span><span class="p">.</span><span class="n">sl_ptr</span><span class="o">=</span><span class="n">modslot</span><span class="p">.</span><span class="n">value</span>
<span class="p">}</span>
</pre></div>
</div>
<p>where <code class="docutils literal notranslate"><span class="pre">sub_static</span></code> is <code class="docutils literal notranslate"><span class="pre">PySlot_STATIC</span></code> if the slot requires
the flag (such as for <a class="reference internal" href="#c.Py_mod_methods" title="Py_mod_methods"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_methods</span></code></a>), or if this flag
is present on the “parent” <code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_slots</span></code> slot (if any).</p>
<dl class="c member">
<dt class="sig sig-object c" id="c.PyModuleDef_Slot.slot">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">slot</span></span></span><a class="headerlink" href="#c.PyModuleDef_Slot.slot" title="Link to this definition">¶</a><br /></dt>
<dd><p>Corresponds to <a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">PySlot.sl_id</span></code></a>.</p>
</dd></dl>
<dl class="c member">
<dt class="sig sig-object c" id="c.PyModuleDef_Slot.value">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">value</span></span></span><a class="headerlink" href="#c.PyModuleDef_Slot.value" title="Link to this definition">¶</a><br /></dt>
<dd><p>Corresponds to <a class="reference internal" href="slots.html#c.PySlot.sl_ptr" title="PySlot.sl_ptr"><code class="xref c c-member docutils literal notranslate"><span class="pre">PySlot.sl_ptr</span></code></a>.</p>
</dd></dl>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.5.</span></p>
</div>
</dd></dl>
</dd></dl>
<dl class="c member">
<dt class="sig sig-object c" id="c.PyModuleDef.m_traverse">
<a class="reference internal" href="gcsupport.html#c.traverseproc" title="traverseproc"><span class="n"><span class="pre">traverseproc</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">m_traverse</span></span></span><a class="headerlink" href="#c.PyModuleDef.m_traverse" title="Link to this definition">¶</a><br /></dt>
<dt class="sig sig-object c" id="c.PyModuleDef.m_clear">
<a class="reference internal" href="gcsupport.html#c.inquiry" title="inquiry"><span class="n"><span class="pre">inquiry</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">m_clear</span></span></span><a class="headerlink" href="#c.PyModuleDef.m_clear" title="Link to this definition">¶</a><br /></dt>
<dt class="sig sig-object c" id="c.PyModuleDef.m_free">
<a class="reference internal" href="typeobj.html#c.freefunc" title="freefunc"><span class="n"><span class="pre">freefunc</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">m_free</span></span></span><a class="headerlink" href="#c.PyModuleDef.m_free" title="Link to this definition">¶</a><br /></dt>
<dd><p>These members correspond to the <a class="reference internal" href="#c.Py_mod_state_traverse" title="Py_mod_state_traverse"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_state_traverse</span></code></a>,
<a class="reference internal" href="#c.Py_mod_state_clear" title="Py_mod_state_clear"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_state_clear</span></code></a>, and <a class="reference internal" href="#c.Py_mod_state_free" title="Py_mod_state_free"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_state_free</span></code></a> slots,
respectively.</p>
<p>Setting these members to NULL is equivalent to omitting the
corresponding slots.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.9: </span><a class="reference internal" href="#c.PyModuleDef.m_traverse" title="m_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">m_traverse</span></code></a>, <a class="reference internal" href="#c.PyModuleDef.m_clear" title="m_clear"><code class="xref c c-member docutils literal notranslate"><span class="pre">m_clear</span></code></a> and <a class="reference internal" href="#c.PyModuleDef.m_free" title="m_free"><code class="xref c c-member docutils literal notranslate"><span class="pre">m_free</span></code></a>
functions are no longer called before the module state is allocated.</p>
</div>
</dd></dl>
</dd></dl>
<dl class="c var">
<dt class="sig sig-object c" id="c.PyModuleDef_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyModuleDef_Type</span></span></span><a class="headerlink" href="#c.PyModuleDef_Type" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.5.</em><p>The type of <code class="docutils literal notranslate"><span class="pre">PyModuleDef</span></code> objects.</p>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_mod_slots">
<span class="sig-name descname"><span class="n"><span class="pre">Py_mod_slots</span></span></span><a class="headerlink" href="#c.Py_mod_slots" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> that works like
<a class="reference internal" href="slots.html#c.Py_slot_subslots" title="Py_slot_subslots"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_slot_subslots</span></code></a>, except it specifies an array of
<a class="reference internal" href="#c.PyModuleDef_Slot" title="PyModuleDef_Slot"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyModuleDef_Slot</span></code></a> structures.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
<p id="moduledef-dynamic">The following API can be used to create modules from a <code class="xref c c-type docutils literal notranslate"><span class="pre">PyModuleDef</span></code>
struct:</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_Create">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_Create</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef"><span class="n"><span class="pre">PyModuleDef</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">def</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_Create" title="Link to this definition">¶</a><br /></dt>
<dd><em class="refcount return_new_ref">Return value: New reference.</em><p>Create a new module object, given the definition in <em>def</em>.
This is a macro that calls <a class="reference internal" href="#c.PyModule_Create2" title="PyModule_Create2"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_Create2()</span></code></a> with
<em>module_api_version</em> set to <a class="reference internal" href="#c.PYTHON_API_VERSION" title="PYTHON_API_VERSION"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PYTHON_API_VERSION</span></code></a>, or
to <a class="reference internal" href="#c.PYTHON_ABI_VERSION" title="PYTHON_ABI_VERSION"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PYTHON_ABI_VERSION</span></code></a> if using the
<a class="reference internal" href="stable.html#limited-c-api"><span class="std std-ref">limited API</span></a>.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_Create2">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_Create2</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef"><span class="n"><span class="pre">PyModuleDef</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">def</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">module_api_version</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_Create2" title="Link to this definition">¶</a><br /></dt>
<dd><em class="refcount return_new_ref">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Create a new module object, given the definition in <em>def</em>, assuming the
API version <em>module_api_version</em>. If that version does not match the version
of the running interpreter, a <a class="reference internal" href="../library/exceptions.html#RuntimeWarning" title="RuntimeWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeWarning</span></code></a> is emitted.</p>
<p>Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> with an exception set on error.</p>
<p>This function does not support slots.
The <a class="reference internal" href="#c.PyModuleDef.m_slots" title="PyModuleDef.m_slots"><code class="xref c c-member docutils literal notranslate"><span class="pre">m_slots</span></code></a> member of <em>def</em> must be <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Most uses of this function should be using <a class="reference internal" href="#c.PyModule_Create" title="PyModule_Create"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_Create()</span></code></a>
instead; only use this if you are sure you need it.</p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_FromDefAndSpec">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_FromDefAndSpec</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef"><span class="n"><span class="pre">PyModuleDef</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">def</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">spec</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_FromDefAndSpec" title="Link to this definition">¶</a><br /></dt>
<dd><em class="refcount return_new_ref">Return value: New reference.</em><p>This macro calls <a class="reference internal" href="#c.PyModule_FromDefAndSpec2" title="PyModule_FromDefAndSpec2"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_FromDefAndSpec2()</span></code></a> with
<em>module_api_version</em> set to <a class="reference internal" href="#c.PYTHON_API_VERSION" title="PYTHON_API_VERSION"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PYTHON_API_VERSION</span></code></a>, or
to <a class="reference internal" href="#c.PYTHON_ABI_VERSION" title="PYTHON_ABI_VERSION"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PYTHON_ABI_VERSION</span></code></a> if using the
<a class="reference internal" href="stable.html#limited-c-api"><span class="std std-ref">limited API</span></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.5.</span></p>
</div>
<div class="versionchanged soft-deprecated">
<p><span class="versionmodified soft-deprecated"><a class="reference internal" href="../glossary.html#term-soft-deprecated">Soft deprecated</a> since version 3.15.0rc1 (unreleased): </span>Prefer <a class="reference internal" href="#c.PyModule_FromSlotsAndSpec" title="PyModule_FromSlotsAndSpec"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_FromSlotsAndSpec()</span></code></a> in new code.</p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_FromDefAndSpec2">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_FromDefAndSpec2</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef"><span class="n"><span class="pre">PyModuleDef</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">def</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">spec</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">module_api_version</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_FromDefAndSpec2" title="Link to this definition">¶</a><br /></dt>
<dd><em class="refcount return_new_ref">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><p>Create a new module object, given the definition in <em>def</em> and the
ModuleSpec <em>spec</em>, assuming the API version <em>module_api_version</em>.
If that version does not match the version of the running interpreter,
a <a class="reference internal" href="../library/exceptions.html#RuntimeWarning" title="RuntimeWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeWarning</span></code></a> is emitted.</p>
<p>Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> with an exception set on error.</p>
<p>Note that this does not process execution slots (<a class="reference internal" href="#c.Py_mod_exec" title="Py_mod_exec"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_mod_exec</span></code></a>).
Both <code class="docutils literal notranslate"><span class="pre">PyModule_FromDefAndSpec</span></code> and <code class="docutils literal notranslate"><span class="pre">PyModule_ExecDef</span></code> must be called
to fully initialize a module.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Most uses of this function should be using <a class="reference internal" href="#c.PyModule_FromDefAndSpec" title="PyModule_FromDefAndSpec"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_FromDefAndSpec()</span></code></a>
instead; only use this if you are sure you need it.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.5.</span></p>
</div>
<div class="versionchanged soft-deprecated">
<p><span class="versionmodified soft-deprecated"><a class="reference internal" href="../glossary.html#term-soft-deprecated">Soft deprecated</a> since version 3.15.0rc1 (unreleased): </span>Prefer <a class="reference internal" href="#c.PyModule_FromSlotsAndSpec" title="PyModule_FromSlotsAndSpec"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_FromSlotsAndSpec()</span></code></a> in new code.</p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_ExecDef">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_ExecDef</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span>, <a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef"><span class="n"><span class="pre">PyModuleDef</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">def</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_ExecDef" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><p>Process any execution slots (<a class="reference internal" href="#c.Py_mod_exec" title="Py_mod_exec"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_mod_exec</span></code></a>) given in <em>def</em>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.5.</span></p>
</div>
<div class="versionchanged soft-deprecated">
<p><span class="versionmodified soft-deprecated"><a class="reference internal" href="../glossary.html#term-soft-deprecated">Soft deprecated</a> since version 3.15.0rc1 (unreleased): </span>To run a module’s own execution slots, prefer <a class="reference internal" href="#c.PyModule_Exec" title="PyModule_Exec"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_Exec()</span></code></a>,
which works on modules that were not created from a
<a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyModuleDef</span></code></a> structure.</p>
</div>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.PYTHON_API_VERSION">
<span class="sig-name descname"><span class="n"><span class="pre">PYTHON_API_VERSION</span></span></span><a class="headerlink" href="#c.PYTHON_API_VERSION" title="Link to this definition">¶</a><br /></dt>
<dt class="sig sig-object c" id="c.PYTHON_API_STRING">
<span class="sig-name descname"><span class="n"><span class="pre">PYTHON_API_STRING</span></span></span><a class="headerlink" href="#c.PYTHON_API_STRING" title="Link to this definition">¶</a><br /></dt>
<dd><p>The C API version, as an integer (<code class="docutils literal notranslate"><span class="pre">1013</span></code>) and string (<code class="docutils literal notranslate"><span class="pre">"1013"</span></code>), respectively.
Defined for backwards compatibility.</p>
<p>Currently, this constant is not updated in new Python versions, and is not
useful for versioning. This may change in the future.</p>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.PYTHON_ABI_VERSION">
<span class="sig-name descname"><span class="n"><span class="pre">PYTHON_ABI_VERSION</span></span></span><a class="headerlink" href="#c.PYTHON_ABI_VERSION" title="Link to this definition">¶</a><br /></dt>
<dt class="sig sig-object c" id="c.PYTHON_ABI_STRING">
<span class="sig-name descname"><span class="n"><span class="pre">PYTHON_ABI_STRING</span></span></span><a class="headerlink" href="#c.PYTHON_ABI_STRING" title="Link to this definition">¶</a><br /></dt>
<dd><p>Defined as <code class="docutils literal notranslate"><span class="pre">3</span></code> and <code class="docutils literal notranslate"><span class="pre">"3"</span></code>, respectively, for backwards compatibility.</p>
<p>Currently, this constant is not updated in new Python versions, and is not
useful for versioning. This may change in the future.</p>
</dd></dl>
</section>
<section id="support-functions">
<span id="capi-module-support-functions"></span><h2>Support functions<a class="headerlink" href="#support-functions" title="Link to this heading">¶</a></h2>
<p>The following functions are provided to help initialize a module object.
They are intended for a module’s execution slot (<a class="reference internal" href="#c.Py_mod_exec" title="Py_mod_exec"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_mod_exec</span></code></a>),
the initialization function for legacy <a class="reference internal" href="extension-modules.html#single-phase-initialization"><span class="std std-ref">single-phase initialization</span></a>,
or code that creates modules dynamically.</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_AddObjectRef">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_AddObjectRef</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">name</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">value</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_AddObjectRef" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.10.</em><p>Add an object to <em>module</em> as <em>name</em>. This is a convenience function which
can be used from the module’s initialization function.</p>
<p>On success, return <code class="docutils literal notranslate"><span class="pre">0</span></code>. On error, raise an exception and return <code class="docutils literal notranslate"><span class="pre">-1</span></code>.</p>
<p>Example usage:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span><span class="w"> </span><span class="kt">int</span>
<span class="nf">add_spam</span><span class="p">(</span><span class="n">PyObject</span><span class="w"> </span><span class="o">*</span><span class="n">module</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">value</span><span class="p">)</span>
<span class="p">{</span>
<span class="w"> </span><span class="n">PyObject</span><span class="w"> </span><span class="o">*</span><span class="n">obj</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">PyLong_FromLong</span><span class="p">(</span><span class="n">value</span><span class="p">);</span>
<span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">obj</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="nb">NULL</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="mi">-1</span><span class="p">;</span>
<span class="w"> </span><span class="p">}</span>
<span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">res</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">PyModule_AddObjectRef</span><span class="p">(</span><span class="n">module</span><span class="p">,</span><span class="w"> </span><span class="s">"spam"</span><span class="p">,</span><span class="w"> </span><span class="n">obj</span><span class="p">);</span>
<span class="w"> </span><span class="n">Py_DECREF</span><span class="p">(</span><span class="n">obj</span><span class="p">);</span>
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="n">res</span><span class="p">;</span>
<span class="w"> </span><span class="p">}</span>
</pre></div>
</div>
<p>To be convenient, the function accepts <code class="docutils literal notranslate"><span class="pre">NULL</span></code> <em>value</em> with an exception
set. In this case, return <code class="docutils literal notranslate"><span class="pre">-1</span></code> and just leave the raised exception
unchanged.</p>
<p>The example can also be written without checking explicitly if <em>obj</em> is
<code class="docutils literal notranslate"><span class="pre">NULL</span></code>:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span><span class="w"> </span><span class="kt">int</span>
<span class="nf">add_spam</span><span class="p">(</span><span class="n">PyObject</span><span class="w"> </span><span class="o">*</span><span class="n">module</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">value</span><span class="p">)</span>
<span class="p">{</span>
<span class="w"> </span><span class="n">PyObject</span><span class="w"> </span><span class="o">*</span><span class="n">obj</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">PyLong_FromLong</span><span class="p">(</span><span class="n">value</span><span class="p">);</span>
<span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">res</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">PyModule_AddObjectRef</span><span class="p">(</span><span class="n">module</span><span class="p">,</span><span class="w"> </span><span class="s">"spam"</span><span class="p">,</span><span class="w"> </span><span class="n">obj</span><span class="p">);</span>
<span class="w"> </span><span class="n">Py_XDECREF</span><span class="p">(</span><span class="n">obj</span><span class="p">);</span>
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="n">res</span><span class="p">;</span>
<span class="w"> </span><span class="p">}</span>
</pre></div>
</div>
<p>Note that <code class="docutils literal notranslate"><span class="pre">Py_XDECREF()</span></code> should be used instead of <code class="docutils literal notranslate"><span class="pre">Py_DECREF()</span></code> in
this case, since <em>obj</em> can be <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.</p>
<p>The number of different <em>name</em> strings passed to this function
should be kept small, usually by only using statically allocated strings
as <em>name</em>.
For names that aren’t known at compile time, prefer calling
<a class="reference internal" href="unicode.html#c.PyUnicode_FromString" title="PyUnicode_FromString"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_FromString()</span></code></a> and <a class="reference internal" href="object.html#c.PyObject_SetAttr" title="PyObject_SetAttr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_SetAttr()</span></code></a> directly.
For more details, see <a class="reference internal" href="unicode.html#c.PyUnicode_InternFromString" title="PyUnicode_InternFromString"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_InternFromString()</span></code></a>, which may be
used internally to create a key object.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.10.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_Add">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_Add</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">name</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">value</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_Add" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.13.</em><p>Similar to <a class="reference internal" href="#c.PyModule_AddObjectRef" title="PyModule_AddObjectRef"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_AddObjectRef()</span></code></a>, but “<a class="reference internal" href="../glossary.html#term-steal"><span class="xref std std-term">steals</span></a>”
a reference to <em>value</em> (even on error).
It can be called with a result of function that returns a new reference
without bothering to check its result or even saving it to a variable.</p>
<p>Example usage:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">PyModule_Add</span><span class="p">(</span><span class="n">module</span><span class="p">,</span><span class="w"> </span><span class="s">"spam"</span><span class="p">,</span><span class="w"> </span><span class="n">PyBytes_FromString</span><span class="p">(</span><span class="n">value</span><span class="p">))</span><span class="w"> </span><span class="o"><</span><span class="w"> </span><span class="mi">0</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="k">goto</span><span class="w"> </span><span class="n">error</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.13.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_AddObject">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_AddObject</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">name</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">value</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_AddObject" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Similar to <a class="reference internal" href="#c.PyModule_AddObjectRef" title="PyModule_AddObjectRef"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_AddObjectRef()</span></code></a>, but <a class="reference internal" href="../glossary.html#term-steal"><span class="xref std std-term">steals</span></a>
a reference to <em>value</em> on success (if it returns <code class="docutils literal notranslate"><span class="pre">0</span></code>).</p>
<p>The new <a class="reference internal" href="#c.PyModule_Add" title="PyModule_Add"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_Add()</span></code></a> or <a class="reference internal" href="#c.PyModule_AddObjectRef" title="PyModule_AddObjectRef"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_AddObjectRef()</span></code></a>
functions are recommended, since it is
easy to introduce reference leaks by misusing the
<a class="reference internal" href="#c.PyModule_AddObject" title="PyModule_AddObject"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_AddObject()</span></code></a> function.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Unlike other functions that steal references, <code class="docutils literal notranslate"><span class="pre">PyModule_AddObject()</span></code>
only releases the reference to <em>value</em> <strong>on success</strong>.</p>
<p>This means that its return value must be checked, and calling code must
<a class="reference internal" href="refcounting.html#c.Py_XDECREF" title="Py_XDECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_XDECREF()</span></code></a> <em>value</em> manually on error.</p>
</div>
<p>Example usage:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyObject</span><span class="w"> </span><span class="o">*</span><span class="n">obj</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">PyBytes_FromString</span><span class="p">(</span><span class="n">value</span><span class="p">);</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">PyModule_AddObject</span><span class="p">(</span><span class="n">module</span><span class="p">,</span><span class="w"> </span><span class="s">"spam"</span><span class="p">,</span><span class="w"> </span><span class="n">obj</span><span class="p">)</span><span class="w"> </span><span class="o"><</span><span class="w"> </span><span class="mi">0</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="c1">// If 'obj' is not NULL and PyModule_AddObject() failed,</span>
<span class="w"> </span><span class="c1">// 'obj' strong reference must be deleted with Py_XDECREF().</span>
<span class="w"> </span><span class="c1">// If 'obj' is NULL, Py_XDECREF() does nothing.</span>
<span class="w"> </span><span class="n">Py_XDECREF</span><span class="p">(</span><span class="n">obj</span><span class="p">);</span>
<span class="w"> </span><span class="k">goto</span><span class="w"> </span><span class="n">error</span><span class="p">;</span>
<span class="p">}</span>
<span class="c1">// PyModule_AddObject() stole a reference to obj:</span>
<span class="c1">// Py_XDECREF(obj) is not needed here.</span>
</pre></div>
</div>
<div class="versionchanged soft-deprecated">
<p><span class="versionmodified soft-deprecated"><a class="reference internal" href="../glossary.html#term-soft-deprecated">Soft deprecated</a> since version 3.13.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_AddIntConstant">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_AddIntConstant</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">name</span></span>, <span class="kt"><span class="pre">long</span></span><span class="w"> </span><span class="n"><span class="pre">value</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_AddIntConstant" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Add an integer constant to <em>module</em> as <em>name</em>. This convenience function can be
used from the module’s initialization function.
Return <code class="docutils literal notranslate"><span class="pre">-1</span></code> with an exception set on error, <code class="docutils literal notranslate"><span class="pre">0</span></code> on success.</p>
<p>This is a convenience function that calls <a class="reference internal" href="long.html#c.PyLong_FromLong" title="PyLong_FromLong"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyLong_FromLong()</span></code></a> and
<a class="reference internal" href="#c.PyModule_AddObjectRef" title="PyModule_AddObjectRef"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_AddObjectRef()</span></code></a>; see their documentation for details.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_AddStringConstant">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_AddStringConstant</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">name</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">value</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_AddStringConstant" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Add a string constant to <em>module</em> as <em>name</em>. This convenience function can be
used from the module’s initialization function. The string <em>value</em> must be
<code class="docutils literal notranslate"><span class="pre">NULL</span></code>-terminated.
Return <code class="docutils literal notranslate"><span class="pre">-1</span></code> with an exception set on error, <code class="docutils literal notranslate"><span class="pre">0</span></code> on success.</p>
<p>This is a convenience function that calls
<a class="reference internal" href="unicode.html#c.PyUnicode_InternFromString" title="PyUnicode_InternFromString"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_InternFromString()</span></code></a> and <a class="reference internal" href="#c.PyModule_AddObjectRef" title="PyModule_AddObjectRef"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_AddObjectRef()</span></code></a>;
see their documentation for details.</p>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.PyModule_AddIntMacro">
<span class="sig-name descname"><span class="n"><span class="pre">PyModule_AddIntMacro</span></span></span><span class="sig-paren">(</span><span class="n"><span class="pre">module</span></span>, <span class="n"><span class="pre">macro</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_AddIntMacro" title="Link to this definition">¶</a><br /></dt>
<dd><p>Add an int constant to <em>module</em>. The name and the value are taken from
<em>macro</em>. For example <code class="docutils literal notranslate"><span class="pre">PyModule_AddIntMacro(module,</span> <span class="pre">AF_INET)</span></code> adds the int
constant <em>AF_INET</em> with the value of <em>AF_INET</em> to <em>module</em>.
Return <code class="docutils literal notranslate"><span class="pre">-1</span></code> with an exception set on error, <code class="docutils literal notranslate"><span class="pre">0</span></code> on success.</p>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.PyModule_AddStringMacro">
<span class="sig-name descname"><span class="n"><span class="pre">PyModule_AddStringMacro</span></span></span><span class="sig-paren">(</span><span class="n"><span class="pre">module</span></span>, <span class="n"><span class="pre">macro</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_AddStringMacro" title="Link to this definition">¶</a><br /></dt>
<dd><p>Add a string constant to <em>module</em>.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_AddType">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_AddType</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span>, <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_AddType" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.10.</em><p>Add a type object to <em>module</em>.
The type object is finalized by calling internally <a class="reference internal" href="type.html#c.PyType_Ready" title="PyType_Ready"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_Ready()</span></code></a>.
The name of the type object is taken from the last component of
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_name" title="PyTypeObject.tp_name"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_name</span></code></a> after dot.
Return <code class="docutils literal notranslate"><span class="pre">-1</span></code> with an exception set on error, <code class="docutils literal notranslate"><span class="pre">0</span></code> on success.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.9.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_AddFunctions">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_AddFunctions</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span>, <a class="reference internal" href="structures.html#c.PyMethodDef" title="PyMethodDef"><span class="n"><span class="pre">PyMethodDef</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">functions</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_AddFunctions" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><p>Add the functions from the <code class="docutils literal notranslate"><span class="pre">NULL</span></code> terminated <em>functions</em> array to <em>module</em>.
Refer to the <a class="reference internal" href="structures.html#c.PyMethodDef" title="PyMethodDef"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyMethodDef</span></code></a> documentation for details on individual
entries (due to the lack of a shared module namespace, module level
“functions” implemented in C typically receive the module as their first
parameter, making them similar to instance methods on Python classes).</p>
<p>This function is called automatically when creating a module from
<code class="docutils literal notranslate"><span class="pre">PyModuleDef</span></code> (such as when using <a class="reference internal" href="extension-modules.html#multi-phase-initialization"><span class="std std-ref">Multi-phase initialization</span></a>,
<code class="docutils literal notranslate"><span class="pre">PyModule_Create</span></code>, or <code class="docutils literal notranslate"><span class="pre">PyModule_FromDefAndSpec</span></code>).
Some module authors may prefer defining functions in multiple
<a class="reference internal" href="structures.html#c.PyMethodDef" title="PyMethodDef"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyMethodDef</span></code></a> arrays; in that case they should call this function
directly.</p>
<p>The <em>functions</em> array must be statically allocated (or otherwise guaranteed
to outlive the module object).</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.5.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyModule_SetDocString">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyModule_SetDocString</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">docstring</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_SetDocString" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><p>Set the docstring for <em>module</em> to <em>docstring</em>.
This function is called automatically when creating a module from
<code class="docutils literal notranslate"><span class="pre">PyModuleDef</span></code> (such as when using <a class="reference internal" href="extension-modules.html#multi-phase-initialization"><span class="std std-ref">Multi-phase initialization</span></a>,
<code class="docutils literal notranslate"><span class="pre">PyModule_Create</span></code>, or <code class="docutils literal notranslate"><span class="pre">PyModule_FromDefAndSpec</span></code>).</p>
<p>Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success.
Return <code class="docutils literal notranslate"><span class="pre">-1</span></code> with an exception set on error.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.5.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyUnstable_Module_SetGIL">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnstable_Module_SetGIL</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span>, <span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">gil</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnstable_Module_SetGIL" title="Link to this definition">¶</a><br /></dt>
<dd><div class="unstable-c-api warning admonition">
<em>This is <a class="reference internal" href="stable.html#unstable-c-api"><span class="std std-ref">Unstable API</span></a>. It may change without warning in minor releases.</em></div>
<p>Indicate that <em>module</em> does or does not support running without the global
interpreter lock (GIL), using one of the values from
<a class="reference internal" href="#c.Py_mod_gil" title="Py_mod_gil"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_mod_gil</span></code></a>. It must be called during <em>module</em>’s initialization
function when using <a class="reference internal" href="extension-modules.html#single-phase-initialization"><span class="std std-ref">Legacy single-phase initialization</span></a>.
If this function is not called during module initialization, the
import machinery assumes the module does not support running without the
GIL. This function is only available in Python builds configured with
<a class="reference internal" href="../using/configure.html#cmdoption-disable-gil"><code class="xref std std-option docutils literal notranslate"><span class="pre">--disable-gil</span></code></a>.
Return <code class="docutils literal notranslate"><span class="pre">-1</span></code> with an exception set on error, <code class="docutils literal notranslate"><span class="pre">0</span></code> on success.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.13.</span></p>
</div>
</dd></dl>
<section id="module-lookup-single-phase-initialization">
<h3>Module lookup (single-phase initialization)<a class="headerlink" href="#module-lookup-single-phase-initialization" title="Link to this heading">¶</a></h3>
<p>The legacy <a class="reference internal" href="extension-modules.html#single-phase-initialization"><span class="std std-ref">single-phase initialization</span></a>
initialization scheme creates singleton modules that can be looked up
in the context of the current interpreter. This allows the module object to be
retrieved later with only a reference to the module definition.</p>
<p>These functions will not work on modules created using multi-phase initialization,
since multiple such modules can be created from a single definition.</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyState_FindModule">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyState_FindModule</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef"><span class="n"><span class="pre">PyModuleDef</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">def</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyState_FindModule" title="Link to this definition">¶</a><br /></dt>
<dd><em class="refcount return_borrowed_ref">Return value: Borrowed reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Returns the module object that was created from <em>def</em> for the current interpreter.
This method requires that the module object has been attached to the interpreter state with
<a class="reference internal" href="#c.PyState_AddModule" title="PyState_AddModule"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyState_AddModule()</span></code></a> beforehand. In case the corresponding module object is not
found or has not been attached to the interpreter state yet, it returns <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyState_AddModule">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyState_AddModule</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span>, <a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef"><span class="n"><span class="pre">PyModuleDef</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">def</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyState_AddModule" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.3.</em><p>Attaches the module object passed to the function to the interpreter state. This allows
the module object to be accessible via <a class="reference internal" href="#c.PyState_FindModule" title="PyState_FindModule"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyState_FindModule()</span></code></a>.</p>
<p>Only effective on modules created using single-phase initialization.</p>
<p>Python calls <code class="docutils literal notranslate"><span class="pre">PyState_AddModule</span></code> automatically after importing a module
that uses <a class="reference internal" href="extension-modules.html#single-phase-initialization"><span class="std std-ref">single-phase initialization</span></a>,
so it is unnecessary (but harmless) to call it from module initialization
code. An explicit call is needed only if the module’s own init code
subsequently calls <code class="docutils literal notranslate"><span class="pre">PyState_FindModule</span></code>.
The function is mainly intended for implementing alternative import
mechanisms (either by calling it directly, or by referring to its
implementation for details of the required state updates).</p>
<p>If a module was attached previously using the same <em>def</em>, it is replaced
by the new <em>module</em>.</p>
<p>The caller must have an <a class="reference internal" href="../glossary.html#term-attached-thread-state"><span class="xref std std-term">attached thread state</span></a>.</p>
<p>Return <code class="docutils literal notranslate"><span class="pre">-1</span></code> with an exception set on error, <code class="docutils literal notranslate"><span class="pre">0</span></code> on success.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.3.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyState_RemoveModule">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyState_RemoveModule</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef"><span class="n"><span class="pre">PyModuleDef</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">def</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyState_RemoveModule" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.3.</em><p>Removes the module object created from <em>def</em> from the interpreter state.
Return <code class="docutils literal notranslate"><span class="pre">-1</span></code> with an exception set on error, <code class="docutils literal notranslate"><span class="pre">0</span></code> on success.</p>
<p>The caller must have an <a class="reference internal" href="../glossary.html#term-attached-thread-state"><span class="xref std std-term">attached thread state</span></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.3.</span></p>
</div>
</dd></dl>
</section>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Module Objects</a><ul>
<li><a class="reference internal" href="#module-definition">Module definition</a><ul>
<li><a class="reference internal" href="#metadata-slots">Metadata slots</a></li>
<li><a class="reference internal" href="#feature-slots">Feature slots</a></li>
<li><a class="reference internal" href="#creation-and-initialization-slots">Creation and initialization slots</a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-state">Module state</a><ul>
<li><a class="reference internal" href="#slots-for-defining-module-state">Slots for defining module state</a></li>
<li><a class="reference internal" href="#module-token">Module token</a></li>
</ul>
</li>
<li><a class="reference internal" href="#creating-extension-modules-dynamically">Creating extension modules dynamically</a></li>
<li><a class="reference internal" href="#module-definition-struct">Module definition struct</a></li>
<li><a class="reference internal" href="#support-functions">Support functions</a><ul>
<li><a class="reference internal" href="#module-lookup-single-phase-initialization">Module lookup (single-phase initialization)</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="file.html"
title="previous chapter">File objects</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="iterator.html"
title="next chapter">Iterator Objects</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "c-api/module.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>This page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a bug</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/main/Doc/c-api/module.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="iterator.html" title="Iterator Objects"
>next</a> |</li>
<li class="right" >
<a href="file.html" title="File objects"
>previous</a> |</li>
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.15.0rc1 Documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API reference manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
<li class="nav-item nav-item-this"><a href="">Module Objects</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.
<br>
This page is licensed under the Python Software Foundation License Version 2.
<br>
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
<br>
See <a href="/license.html">History and License</a> for more information.<br>
<br>
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br>
<br>
Last updated on Aug 04, 2026 (11:13 UTC).
<a href="/bugs.html">Found a bug</a>?
<br>
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>