CINXE.COM

<!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="Initializing C modules: Modules objects are usually created from extension modules (shared libraries which export an initialization function), or compiled-in modules (where the initialization funct..." /> <meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" /> <meta property="og:image:alt" content="Python documentation" /> <meta name="description" content="Initializing C modules: Modules objects are usually created from extension modules (shared libraries which export an initialization function), or compiled-in modules (where the initialization funct..." /> <meta property="og:image:width" content="200" /> <meta property="og:image:height" content="200" /> <meta name="theme-color" content="#3776ab" /> <title>Module Objects — Python 3.13.2 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/pydoctheme.css?v=23252803" /> <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" /> <script src="../_static/documentation_options.js?v=f92f4e34"></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.13.2 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" /> <script defer data-domain="docs.python.org" src="https://plausible.io/js/script.js"></script> <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"> </label> <a href="https://www.python.org/" class="nav-logo"> <img src="../_static/py.svg" alt="Python logo"/> </a> <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> </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="#initializing-c-modules">Initializing C modules</a><ul> <li><a class="reference internal" href="#single-phase-initialization">Single-phase initialization</a></li> <li><a class="reference internal" href="#multi-phase-initialization">Multi-phase initialization</a></li> <li><a class="reference internal" href="#low-level-module-creation-functions">Low-level module creation functions</a></li> <li><a class="reference internal" href="#support-functions">Support functions</a></li> </ul> </li> <li><a class="reference internal" href="#module-lookup">Module lookup</a></li> </ul> </li> </ul> </div> <div> <h4>Previous topic</h4> <a href="file.html" title="previous chapter">File Objects</a> </div> <div> <h4>Next topic</h4> <a href="iterator.html" title="next chapter">Iterator Objects</a> </div> <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 href="https://github.com/python/cpython/blob/main/Doc/c-api/module.rst" 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.13.2 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"> <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">PyTypeObject</a> PyModule_Type<a class="headerlink" href="#c.PyModule_Type" title="Link to this definition">¶</a> </dt> <dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.This instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate">PyTypeObject</code></a> represents the Python module type. This is exposed to Python programs as <code class="docutils literal notranslate">types.ModuleType</code>. </dd></dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyModule_Check"> int PyModule_Check(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *p)<a class="headerlink" href="#c.PyModule_Check" title="Link to this definition">¶</a> </dt> <dd>Return true if p is a module object, or a subtype of a module object. This function always succeeds. </dd></dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyModule_CheckExact"> int PyModule_CheckExact(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *p)<a class="headerlink" href="#c.PyModule_CheckExact" title="Link to this definition">¶</a> </dt> <dd>Return true if p 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">PyModule_Type</code></a>. This function always succeeds. </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">PyObject</a> *PyModule_NewObject(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *name)<a class="headerlink" href="#c.PyModule_NewObject" title="Link to this definition">¶</a> </dt> <dd>Return value: New reference. Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a> since version 3.7.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">module.__name__</code></a> set to name. The module’s <code class="xref py py-attr docutils literal notranslate">__name__</code>, <a class="reference internal" href="../reference/datamodel.html#module.__doc__" title="module.__doc__"><code class="xref py py-attr docutils literal notranslate">__doc__</code></a>, <a class="reference internal" href="../reference/datamodel.html#module.__package__" title="module.__package__"><code class="xref py py-attr docutils literal notranslate">__package__</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">__loader__</code></a> attributes are filled in (all but <code class="xref py py-attr docutils literal notranslate">__name__</code> are set to <code class="docutils literal notranslate">None</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">__file__</code></a> attribute. Return <code class="docutils literal notranslate">NULL</code> with an exception set on error. <div class="versionadded"> Added in version 3.3. </div> <div class="versionchanged"> Changed in version 3.4: <a class="reference internal" href="../reference/datamodel.html#module.__package__" title="module.__package__"><code class="xref py py-attr docutils literal notranslate">__package__</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">__loader__</code></a> are now set to <code class="docutils literal notranslate">None</code>. </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">PyObject</a> *PyModule_New(const char *name)<a class="headerlink" href="#c.PyModule_New" title="Link to this definition">¶</a> </dt> <dd>Return value: New reference. Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Similar to <a class="reference internal" href="#c.PyModule_NewObject" title="PyModule_NewObject"><code class="xref c c-func docutils literal notranslate">PyModule_NewObject()</code></a>, but the name is a UTF-8 encoded string instead of a Unicode object. </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">PyObject</a> *PyModule_GetDict(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *module)<a class="headerlink" href="#c.PyModule_GetDict" title="Link to this definition">¶</a> </dt> <dd>Return value: Borrowed reference. Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Return the dictionary object that implements module’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">__dict__</code></a> attribute of the module object. If module 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">SystemError</code></a> is raised and <code class="docutils literal notranslate">NULL</code> is returned. It is recommended extensions use other <code class="docutils literal notranslate">PyModule_*</code> and <code class="docutils literal notranslate">PyObject_*</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">__dict__</code></a>. </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">PyObject</a> *PyModule_GetNameObject(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *module)<a class="headerlink" href="#c.PyModule_GetNameObject" title="Link to this definition">¶</a> </dt> <dd>Return value: New reference. Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a> since version 3.7.Return module’s <a class="reference internal" href="../reference/datamodel.html#module.__name__" title="module.__name__"><code class="xref py py-attr docutils literal notranslate">__name__</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">SystemError</code></a> is raised and <code class="docutils literal notranslate">NULL</code> is returned. <div class="versionadded"> Added in version 3.3. </div> </dd></dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyModule_GetName"> const char *PyModule_GetName(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *module)<a class="headerlink" href="#c.PyModule_GetName" title="Link to this definition">¶</a> </dt> <dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Similar to <a class="reference internal" href="#c.PyModule_GetNameObject" title="PyModule_GetNameObject"><code class="xref c c-func docutils literal notranslate">PyModule_GetNameObject()</code></a> but return the name encoded to <code class="docutils literal notranslate">'utf-8'</code>. </dd></dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyModule_GetState"> void *PyModule_GetState(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *module)<a class="headerlink" href="#c.PyModule_GetState" title="Link to this definition">¶</a> </dt> <dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.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">NULL</code>. See <a class="reference internal" href="#c.PyModuleDef.m_size" title="PyModuleDef.m_size"><code class="xref c c-member docutils literal notranslate">PyModuleDef.m_size</code></a>. </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">PyModuleDef</a> *PyModule_GetDef(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *module)<a class="headerlink" href="#c.PyModule_GetDef" title="Link to this definition">¶</a> </dt> <dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Return a pointer to the <a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef"><code class="xref c c-type docutils literal notranslate">PyModuleDef</code></a> struct from which the module was created, or <code class="docutils literal notranslate">NULL</code> if the module wasn’t created from a definition. </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">PyObject</a> *PyModule_GetFilenameObject(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *module)<a class="headerlink" href="#c.PyModule_GetFilenameObject" title="Link to this definition">¶</a> </dt> <dd>Return value: New reference. Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Return the name of the file from which module was loaded using module’s <a class="reference internal" href="../reference/datamodel.html#module.__file__" title="module.__file__"><code class="xref py py-attr docutils literal notranslate">__file__</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">SystemError</code></a> and return <code class="docutils literal notranslate">NULL</code>; otherwise return a reference to a Unicode object. <div class="versionadded"> Added in version 3.2. </div> </dd></dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyModule_GetFilename"> const char *PyModule_GetFilename(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *module)<a class="headerlink" href="#c.PyModule_GetFilename" title="Link to this definition">¶</a> </dt> <dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Similar to <a class="reference internal" href="#c.PyModule_GetFilenameObject" title="PyModule_GetFilenameObject"><code class="xref c c-func docutils literal notranslate">PyModule_GetFilenameObject()</code></a> but return the filename encoded to ‘utf-8’. <div class="deprecated"> Deprecated since version 3.2: <a class="reference internal" href="#c.PyModule_GetFilename" title="PyModule_GetFilename"><code class="xref c c-func docutils literal notranslate">PyModule_GetFilename()</code></a> raises <a class="reference internal" href="../library/exceptions.html#UnicodeEncodeError" title="UnicodeEncodeError"><code class="xref py py-exc docutils literal notranslate">UnicodeEncodeError</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">PyModule_GetFilenameObject()</code></a> instead. </div> </dd></dl> <section id="initializing-c-modules"> <h2>Initializing C modules<a class="headerlink" href="#initializing-c-modules" title="Link to this heading">¶</a></h2> Modules objects are usually created from extension modules (shared libraries which export an initialization function), or compiled-in modules (where the initialization function is added using <a class="reference internal" href="import.html#c.PyImport_AppendInittab" title="PyImport_AppendInittab"><code class="xref c c-func docutils literal notranslate">PyImport_AppendInittab()</code></a>). See <a class="reference internal" href="../extending/building.html#building">Building C and C++ Extensions</a> or <a class="reference internal" href="../extending/embedding.html#extending-with-embedding">Extending Embedded Python</a> for details. The initialization function can either pass a module definition instance to <a class="reference internal" href="#c.PyModule_Create" title="PyModule_Create"><code class="xref c c-func docutils literal notranslate">PyModule_Create()</code></a>, and return the resulting module object, or request “multi-phase initialization” by returning the definition struct itself. <dl class="c type"> <dt class="sig sig-object c" id="c.PyModuleDef"> type PyModuleDef<a class="headerlink" href="#c.PyModuleDef" title="Link to this definition">¶</a> </dt> <dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a> (including all members).The module definition struct, which holds all information needed to create a module object. There is usually only one statically initialized variable of this type for each module. <dl class="c member"> <dt class="sig sig-object c" id="c.PyModuleDef.m_base"> PyModuleDef_Base m_base<a class="headerlink" href="#c.PyModuleDef.m_base" title="Link to this definition">¶</a> </dt> <dd>Always initialize this member to <code class="xref c c-macro docutils literal notranslate">PyModuleDef_HEAD_INIT</code>. </dd></dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyModuleDef.m_name"> const char *m_name<a class="headerlink" href="#c.PyModuleDef.m_name" title="Link to this definition">¶</a> </dt> <dd>Name for the new module. </dd></dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyModuleDef.m_doc"> const char *m_doc<a class="headerlink" href="#c.PyModuleDef.m_doc" title="Link to this definition">¶</a> </dt> <dd>Docstring for the module; usually a docstring 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">PyDoc_STRVAR</code></a> is used. </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">Py_ssize_t</a> m_size<a class="headerlink" href="#c.PyModuleDef.m_size" title="Link to this definition">¶</a> </dt> <dd>Module state may be kept in a per-module memory area that can be retrieved with <a class="reference internal" href="#c.PyModule_GetState" title="PyModule_GetState"><code class="xref c c-func docutils literal notranslate">PyModule_GetState()</code></a>, rather than in static globals. This makes modules safe for use in multiple sub-interpreters. This memory area is allocated based on m_size on module creation, and freed when the module object is deallocated, after the <a class="reference internal" href="#c.PyModuleDef.m_free" title="PyModuleDef.m_free"><code class="xref c c-member docutils literal notranslate">m_free</code></a> function has been called, if present. Setting <code class="docutils literal notranslate">m_size</code> to <code class="docutils literal notranslate">-1</code> means that the module does not support sub-interpreters, because it has global state. Setting it 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. Non-negative <code class="docutils literal notranslate">m_size</code> is required for multi-phase initialization. See <a class="pep reference external" href="https://peps.python.org/pep-3121/">PEP 3121</a> for more details. </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">PyMethodDef</a> *m_methods<a class="headerlink" href="#c.PyModuleDef.m_methods" title="Link to this definition">¶</a> </dt> <dd>A pointer to a table of module-level functions, described by <a class="reference internal" href="structures.html#c.PyMethodDef" title="PyMethodDef"><code class="xref c c-type docutils literal notranslate">PyMethodDef</code></a> values. Can be <code class="docutils literal notranslate">NULL</code> if no functions are present. </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">PyModuleDef_Slot</a> *m_slots<a class="headerlink" href="#c.PyModuleDef.m_slots" title="Link to this definition">¶</a> </dt> <dd>An array of slot definitions for multi-phase initialization, terminated by a <code class="docutils literal notranslate">{0, NULL}</code> entry. When using single-phase initialization, m_slots must be <code class="docutils literal notranslate">NULL</code>. <div class="versionchanged"> Changed in version 3.5: Prior to version 3.5, this member was always set to <code class="docutils literal notranslate">NULL</code>, and was defined as: <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">inquiry</a> m_reload<a class="headerlink" href="#c.PyModuleDef.m_slots.m_reload" title="Link to this definition">¶</a> </dt> <dd></dd></dl> </div></blockquote> </div> </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">traverseproc</a> m_traverse<a class="headerlink" href="#c.PyModuleDef.m_traverse" title="Link to this definition">¶</a> </dt> <dd>A traversal function to call during GC traversal of the module object, or <code class="docutils literal notranslate">NULL</code> if not needed. 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">Py_mod_exec</code></a> function). More precisely, this function is not called if <a class="reference internal" href="#c.PyModuleDef.m_size" title="PyModuleDef.m_size"><code class="xref c c-member docutils literal notranslate">m_size</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">PyModule_GetState()</code></a>) is <code class="docutils literal notranslate">NULL</code>. <div class="versionchanged"> Changed in version 3.9: No longer called before the module state is allocated. </div> </dd></dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyModuleDef.m_clear"> <a class="reference internal" href="gcsupport.html#c.inquiry" title="inquiry">inquiry</a> m_clear<a class="headerlink" href="#c.PyModuleDef.m_clear" title="Link to this definition">¶</a> </dt> <dd>A clear function to call during GC clearing of the module object, or <code class="docutils literal notranslate">NULL</code> if not needed. 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">Py_mod_exec</code></a> function). More precisely, this function is not called if <a class="reference internal" href="#c.PyModuleDef.m_size" title="PyModuleDef.m_size"><code class="xref c c-member docutils literal notranslate">m_size</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">PyModule_GetState()</code></a>) is <code class="docutils literal notranslate">NULL</code>. 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">PyTypeObject.tp_clear</code></a>, this function is not always 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 <a class="reference internal" href="#c.PyModuleDef.m_free" title="PyModuleDef.m_free"><code class="xref c c-member docutils literal notranslate">m_free</code></a> is called directly. <div class="versionchanged"> Changed in version 3.9: No longer called before the module state is allocated. </div> </dd></dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyModuleDef.m_free"> <a class="reference internal" href="typeobj.html#c.freefunc" title="freefunc">freefunc</a> m_free<a class="headerlink" href="#c.PyModuleDef.m_free" title="Link to this definition">¶</a> </dt> <dd>A function to call during deallocation of the module object, or <code class="docutils literal notranslate">NULL</code> if not needed. 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">Py_mod_exec</code></a> function). More precisely, this function is not called if <a class="reference internal" href="#c.PyModuleDef.m_size" title="PyModuleDef.m_size"><code class="xref c c-member docutils literal notranslate">m_size</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">PyModule_GetState()</code></a>) is <code class="docutils literal notranslate">NULL</code>. <div class="versionchanged"> Changed in version 3.9: No longer called before the module state is allocated. </div> </dd></dl> </dd></dl> <section id="single-phase-initialization"> <h3>Single-phase initialization<a class="headerlink" href="#single-phase-initialization" title="Link to this heading">¶</a></h3> The module initialization function may create and return the module object directly. This is referred to as “single-phase initialization”, and uses one of the following two module creation functions: <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">PyObject</a> *PyModule_Create(<a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef">PyModuleDef</a> *def)<a class="headerlink" href="#c.PyModule_Create" title="Link to this definition">¶</a> </dt> <dd>Return value: New reference.Create a new module object, given the definition in def. This behaves like <a class="reference internal" href="#c.PyModule_Create2" title="PyModule_Create2"><code class="xref c c-func docutils literal notranslate">PyModule_Create2()</code></a> with module_api_version set to <code class="xref c c-macro docutils literal notranslate">PYTHON_API_VERSION</code>. </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">PyObject</a> *PyModule_Create2(<a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef">PyModuleDef</a> *def, int module_api_version)<a class="headerlink" href="#c.PyModule_Create2" title="Link to this definition">¶</a> </dt> <dd>Return value: New reference. Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Create a new module object, given the definition in def, assuming the API version module_api_version. 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">RuntimeWarning</code></a> is emitted. Return <code class="docutils literal notranslate">NULL</code> with an exception set on error. <div class="admonition note"> Note 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">PyModule_Create()</code></a> instead; only use this if you are sure you need it. </div> </dd></dl> Before it is returned from in the initialization function, the resulting module object is typically populated using functions like <a class="reference internal" href="#c.PyModule_AddObjectRef" title="PyModule_AddObjectRef"><code class="xref c c-func docutils literal notranslate">PyModule_AddObjectRef()</code></a>. </section> <section id="multi-phase-initialization"> <h3>Multi-phase initialization<a class="headerlink" href="#multi-phase-initialization" title="Link to this heading">¶</a></h3> An alternate way to specify extensions is to request “multi-phase initialization”. Extension modules created this way behave more like Python modules: the initialization is split between the creation phase, when the module object is created, and the execution phase, when it is populated. The distinction is similar to the <code class="xref py py-meth docutils literal notranslate">__new__()</code> and <code class="xref py py-meth docutils literal notranslate">__init__()</code> methods of classes. Unlike modules created using single-phase initialization, these modules are not singletons: if the sys.modules entry is removed and the module is re-imported, a new module object is created, and the old module is subject to normal garbage collection – as with Python modules. By default, multiple modules created from the same definition should be independent: changes to one should not affect the others. This means that all state should be specific to the module object (using e.g. using <a class="reference internal" href="#c.PyModule_GetState" title="PyModule_GetState"><code class="xref c c-func docutils literal notranslate">PyModule_GetState()</code></a>), or its contents (such as the module’s <a class="reference internal" href="../reference/datamodel.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate">__dict__</code></a> or individual classes created with <a class="reference internal" href="type.html#c.PyType_FromSpec" title="PyType_FromSpec"><code class="xref c c-func docutils literal notranslate">PyType_FromSpec()</code></a>). All modules created using multi-phase initialization are expected to support <a class="reference internal" href="init.html#sub-interpreter-support">sub-interpreters</a>. Making sure multiple modules are independent is typically enough to achieve this. To request multi-phase initialization, the initialization function (PyInit_modulename) returns a <a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef"><code class="xref c c-type docutils literal notranslate">PyModuleDef</code></a> instance with non-empty <a class="reference internal" href="#c.PyModuleDef.m_slots" title="PyModuleDef.m_slots"><code class="xref c c-member docutils literal notranslate">m_slots</code></a>. Before it is returned, the <code class="docutils literal notranslate">PyModuleDef</code> instance must be initialized with the following function: <dl class="c function"> <dt class="sig sig-object c" id="c.PyModuleDef_Init"> <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyModuleDef_Init(<a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef">PyModuleDef</a> *def)<a class="headerlink" href="#c.PyModuleDef_Init" title="Link to this definition">¶</a> </dt> <dd>Return value: Borrowed reference. Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a> since version 3.5.Ensures a module definition is a properly initialized Python object that correctly reports its type and reference count. Returns def cast to <code class="docutils literal notranslate">PyObject*</code>, or <code class="docutils literal notranslate">NULL</code> if an error occurred. <div class="versionadded"> Added in version 3.5. </div> </dd></dl> The m_slots member of the module definition must point to an array of <code class="docutils literal notranslate">PyModuleDef_Slot</code> structures: <dl class="c type"> <dt class="sig sig-object c" id="c.PyModuleDef_Slot"> type PyModuleDef_Slot<a class="headerlink" href="#c.PyModuleDef_Slot" title="Link to this definition">¶</a> </dt> <dd><dl class="c member"> <dt class="sig sig-object c" id="c.PyModuleDef_Slot.slot"> int slot<a class="headerlink" href="#c.PyModuleDef_Slot.slot" title="Link to this definition">¶</a> </dt> <dd>A slot ID, chosen from the available values explained below. </dd></dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyModuleDef_Slot.value"> void *value<a class="headerlink" href="#c.PyModuleDef_Slot.value" title="Link to this definition">¶</a> </dt> <dd>Value of the slot, whose meaning depends on the slot ID. </dd></dl> <div class="versionadded"> Added in version 3.5. </div> </dd></dl> The m_slots array must be terminated by a slot with id 0. The available slot types are: <dl class="c macro"> <dt class="sig sig-object c" id="c.Py_mod_create"> Py_mod_create<a class="headerlink" href="#c.Py_mod_create" title="Link to this definition">¶</a> </dt> <dd>Specifies a function that is called to create the module object itself. The value pointer of this slot must point to a function of the signature: <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">PyObject</a> *create_module(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *spec, <a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef">PyModuleDef</a> *def)<a class="headerlink" href="#c.Py_mod_create.create_module" title="Link to this definition">¶</a> </dt> <dd></dd></dl> The function receives 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">ModuleSpec</code></a> instance, as defined in <a class="pep reference external" href="https://peps.python.org/pep-0451/">PEP 451</a>, and the module definition. It should return a new module object, or set an error and return <code class="docutils literal notranslate">NULL</code>. 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. Multiple <code class="docutils literal notranslate">Py_mod_create</code> slots may not be specified in one module definition. If <code class="docutils literal notranslate">Py_mod_create</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">PyModule_New()</code></a>. The name is taken from spec, 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. 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">PyModule_Type</code></a>. Any type can be used, as long as it supports setting and getting import-related attributes. However, only <code class="docutils literal notranslate">PyModule_Type</code> instances may be returned if the <code class="docutils literal notranslate">PyModuleDef</code> has non-<code class="docutils literal notranslate">NULL</code> <code class="docutils literal notranslate">m_traverse</code>, <code class="docutils literal notranslate">m_clear</code>, <code class="docutils literal notranslate">m_free</code>; non-zero <code class="docutils literal notranslate">m_size</code>; or slots other than <code class="docutils literal notranslate">Py_mod_create</code>. </dd></dl> <dl class="c macro"> <dt class="sig sig-object c" id="c.Py_mod_exec"> Py_mod_exec<a class="headerlink" href="#c.Py_mod_exec" title="Link to this definition">¶</a> </dt> <dd>Specifies a function that is called to execute the module. This is equivalent to executing the code of a Python module: typically, this function adds classes and constants to the module. The signature of the function is: <dl class="c function"> <dt class="sig sig-object c" id="c.Py_mod_exec.exec_module"> int exec_module(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *module)<a class="headerlink" href="#c.Py_mod_exec.exec_module" title="Link to this definition">¶</a> </dt> <dd></dd></dl> If multiple <code class="docutils literal notranslate">Py_mod_exec</code> slots are specified, they are processed in the order they appear in the m_slots array. </dd></dl> <dl class="c macro"> <dt class="sig sig-object c" id="c.Py_mod_multiple_interpreters"> Py_mod_multiple_interpreters<a class="headerlink" href="#c.Py_mod_multiple_interpreters" title="Link to this definition">¶</a> </dt> <dd>Specifies one of the following values: <dl class="c macro"> <dt class="sig sig-object c" id="c.Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED"> Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED<a class="headerlink" href="#c.Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED" title="Link to this definition">¶</a> </dt> <dd>The module does not support being imported in subinterpreters. </dd></dl> <dl class="c macro"> <dt class="sig sig-object c" id="c.Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED"> Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED<a class="headerlink" href="#c.Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED" title="Link to this definition">¶</a> </dt> <dd>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">Isolating Extension Modules</a>.) </dd></dl> <dl class="c macro"> <dt class="sig sig-object c" id="c.Py_MOD_PER_INTERPRETER_GIL_SUPPORTED"> Py_MOD_PER_INTERPRETER_GIL_SUPPORTED<a class="headerlink" href="#c.Py_MOD_PER_INTERPRETER_GIL_SUPPORTED" title="Link to this definition">¶</a> </dt> <dd>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">Isolating Extension Modules</a>.) </dd></dl> This slot determines whether or not importing this module in a subinterpreter will fail. Multiple <code class="docutils literal notranslate">Py_mod_multiple_interpreters</code> slots may not be specified in one module definition. If <code class="docutils literal notranslate">Py_mod_multiple_interpreters</code> is not specified, the import machinery defaults to <code class="docutils literal notranslate">Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED</code>. <div class="versionadded"> Added in version 3.12. </div> </dd></dl> <dl class="c macro"> <dt class="sig sig-object c" id="c.Py_mod_gil"> Py_mod_gil<a class="headerlink" href="#c.Py_mod_gil" title="Link to this definition">¶</a> </dt> <dd>Specifies one of the following values: <dl class="c macro"> <dt class="sig sig-object c" id="c.Py_MOD_GIL_USED"> Py_MOD_GIL_USED<a class="headerlink" href="#c.Py_MOD_GIL_USED" title="Link to this definition">¶</a> </dt> <dd>The module depends on the presence of the global interpreter lock (GIL), and may access global state without synchronization. </dd></dl> <dl class="c macro"> <dt class="sig sig-object c" id="c.Py_MOD_GIL_NOT_USED"> Py_MOD_GIL_NOT_USED<a class="headerlink" href="#c.Py_MOD_GIL_NOT_USED" title="Link to this definition">¶</a> </dt> <dd>The module is safe to run without an active GIL. </dd></dl> 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">--disable-gil</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">Free-threaded CPython</a> for more detail. Multiple <code class="docutils literal notranslate">Py_mod_gil</code> slots may not be specified in one module definition. If <code class="docutils literal notranslate">Py_mod_gil</code> is not specified, the import machinery defaults to <code class="docutils literal notranslate">Py_MOD_GIL_USED</code>. <div class="versionadded"> Added in version 3.13. </div> </dd></dl> See <a class="pep reference external" href="https://peps.python.org/pep-0489/">PEP 489</a> for more details on multi-phase initialization. </section> <section id="low-level-module-creation-functions"> <h3>Low-level module creation functions<a class="headerlink" href="#low-level-module-creation-functions" title="Link to this heading">¶</a></h3> The following functions are called under the hood when using multi-phase initialization. They can be used directly, for example when creating module objects dynamically. Note that both <code class="docutils literal notranslate">PyModule_FromDefAndSpec</code> and <code class="docutils literal notranslate">PyModule_ExecDef</code> must be called to fully initialize a module. <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">PyObject</a> *PyModule_FromDefAndSpec(<a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef">PyModuleDef</a> *def, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *spec)<a class="headerlink" href="#c.PyModule_FromDefAndSpec" title="Link to this definition">¶</a> </dt> <dd>Return value: New reference.Create a new module object, given the definition in def and the ModuleSpec spec. This behaves like <a class="reference internal" href="#c.PyModule_FromDefAndSpec2" title="PyModule_FromDefAndSpec2"><code class="xref c c-func docutils literal notranslate">PyModule_FromDefAndSpec2()</code></a> with module_api_version set to <code class="xref c c-macro docutils literal notranslate">PYTHON_API_VERSION</code>. <div class="versionadded"> Added in version 3.5. </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">PyObject</a> *PyModule_FromDefAndSpec2(<a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef">PyModuleDef</a> *def, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *spec, int module_api_version)<a class="headerlink" href="#c.PyModule_FromDefAndSpec2" title="Link to this definition">¶</a> </dt> <dd>Return value: New reference. Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a> since version 3.7.Create a new module object, given the definition in def and the ModuleSpec spec, assuming the API version module_api_version. 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">RuntimeWarning</code></a> is emitted. Return <code class="docutils literal notranslate">NULL</code> with an exception set on error. <div class="admonition note"> Note 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">PyModule_FromDefAndSpec()</code></a> instead; only use this if you are sure you need it. </div> <div class="versionadded"> Added in version 3.5. </div> </dd></dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyModule_ExecDef"> int PyModule_ExecDef(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *module, <a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef">PyModuleDef</a> *def)<a class="headerlink" href="#c.PyModule_ExecDef" title="Link to this definition">¶</a> </dt> <dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a> since version 3.7.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">Py_mod_exec</code></a>) given in def. <div class="versionadded"> Added in version 3.5. </div> </dd></dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyModule_SetDocString"> int PyModule_SetDocString(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *module, const char *docstring)<a class="headerlink" href="#c.PyModule_SetDocString" title="Link to this definition">¶</a> </dt> <dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a> since version 3.7.Set the docstring for module to docstring. This function is called automatically when creating a module from <code class="docutils literal notranslate">PyModuleDef</code>, using either <code class="docutils literal notranslate">PyModule_Create</code> or <code class="docutils literal notranslate">PyModule_FromDefAndSpec</code>. <div class="versionadded"> Added in version 3.5. </div> </dd></dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyModule_AddFunctions"> int PyModule_AddFunctions(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *module, <a class="reference internal" href="structures.html#c.PyMethodDef" title="PyMethodDef">PyMethodDef</a> *functions)<a class="headerlink" href="#c.PyModule_AddFunctions" title="Link to this definition">¶</a> </dt> <dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a> since version 3.7.Add the functions from the <code class="docutils literal notranslate">NULL</code> terminated functions array to module. Refer to the <a class="reference internal" href="structures.html#c.PyMethodDef" title="PyMethodDef"><code class="xref c c-type docutils literal notranslate">PyMethodDef</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). This function is called automatically when creating a module from <code class="docutils literal notranslate">PyModuleDef</code>, using either <code class="docutils literal notranslate">PyModule_Create</code> or <code class="docutils literal notranslate">PyModule_FromDefAndSpec</code>. <div class="versionadded"> Added in version 3.5. </div> </dd></dl> </section> <section id="support-functions"> <h3>Support functions<a class="headerlink" href="#support-functions" title="Link to this heading">¶</a></h3> The module initialization function (if using single phase initialization) or a function called from a module execution slot (if using multi-phase initialization), can use the following functions to help initialize the module state: <dl class="c function"> <dt class="sig sig-object c" id="c.PyModule_AddObjectRef"> int PyModule_AddObjectRef(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *module, const char *name, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *value)<a class="headerlink" href="#c.PyModule_AddObjectRef" title="Link to this definition">¶</a> </dt> <dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a> since version 3.10.Add an object to module as name. This is a convenience function which can be used from the module’s initialization function. On success, return <code class="docutils literal notranslate">0</code>. On error, raise an exception and return <code class="docutils literal notranslate">-1</code>. Example usage: <div class="highlight-c notranslate"><div class="highlight"><pre>static int add_spam(PyObject *module, int value) { PyObject *obj = PyLong_FromLong(value); if (obj == NULL) { return -1; } int res = PyModule_AddObjectRef(module, "spam", obj); Py_DECREF(obj); return res; } </pre></div> </div> To be convenient, the function accepts <code class="docutils literal notranslate">NULL</code> value with an exception set. In this case, return <code class="docutils literal notranslate">-1</code> and just leave the raised exception unchanged. The example can also be written without checking explicitly if obj is <code class="docutils literal notranslate">NULL</code>: <div class="highlight-c notranslate"><div class="highlight"><pre>static int add_spam(PyObject *module, int value) { PyObject *obj = PyLong_FromLong(value); int res = PyModule_AddObjectRef(module, "spam", obj); Py_XDECREF(obj); return res; } </pre></div> </div> Note that <code class="docutils literal notranslate">Py_XDECREF()</code> should be used instead of <code class="docutils literal notranslate">Py_DECREF()</code> in this case, since obj can be <code class="docutils literal notranslate">NULL</code>. The number of different name strings passed to this function should be kept small, usually by only using statically allocated strings as name. 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">PyUnicode_FromString()</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">PyObject_SetAttr()</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">PyUnicode_InternFromString()</code></a>, which may be used internally to create a key object. <div class="versionadded"> Added in version 3.10. </div> </dd></dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyModule_Add"> int PyModule_Add(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *module, const char *name, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *value)<a class="headerlink" href="#c.PyModule_Add" title="Link to this definition">¶</a> </dt> <dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a> since version 3.13.Similar to <a class="reference internal" href="#c.PyModule_AddObjectRef" title="PyModule_AddObjectRef"><code class="xref c c-func docutils literal notranslate">PyModule_AddObjectRef()</code></a>, but “steals” a reference to value. 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. Example usage: <div class="highlight-c notranslate"><div class="highlight"><pre>if (PyModule_Add(module, "spam", PyBytes_FromString(value)) < 0) { goto error; } </pre></div> </div> <div class="versionadded"> Added in version 3.13. </div> </dd></dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyModule_AddObject"> int PyModule_AddObject(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *module, const char *name, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *value)<a class="headerlink" href="#c.PyModule_AddObject" title="Link to this definition">¶</a> </dt> <dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Similar to <a class="reference internal" href="#c.PyModule_AddObjectRef" title="PyModule_AddObjectRef"><code class="xref c c-func docutils literal notranslate">PyModule_AddObjectRef()</code></a>, but steals a reference to value on success (if it returns <code class="docutils literal notranslate">0</code>). The new <a class="reference internal" href="#c.PyModule_Add" title="PyModule_Add"><code class="xref c c-func docutils literal notranslate">PyModule_Add()</code></a> or <a class="reference internal" href="#c.PyModule_AddObjectRef" title="PyModule_AddObjectRef"><code class="xref c c-func docutils literal notranslate">PyModule_AddObjectRef()</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">PyModule_AddObject()</code></a> function. <div class="admonition note"> Note Unlike other functions that steal references, <code class="docutils literal notranslate">PyModule_AddObject()</code> only releases the reference to value on success. 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">Py_XDECREF()</code></a> value manually on error. </div> Example usage: <div class="highlight-c notranslate"><div class="highlight"><pre>PyObject *obj = PyBytes_FromString(value); if (PyModule_AddObject(module, "spam", obj) < 0) { // If 'obj' is not NULL and PyModule_AddObject() failed, // 'obj' strong reference must be deleted with Py_XDECREF(). // If 'obj' is NULL, Py_XDECREF() does nothing. Py_XDECREF(obj); goto error; } // PyModule_AddObject() stole a reference to obj: // Py_XDECREF(obj) is not needed here. </pre></div> </div> <div class="deprecated"> Deprecated since version 3.13: <a class="reference internal" href="#c.PyModule_AddObject" title="PyModule_AddObject"><code class="xref c c-func docutils literal notranslate">PyModule_AddObject()</code></a> is <a class="reference internal" href="../glossary.html#term-soft-deprecated">soft deprecated</a>. </div> </dd></dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyModule_AddIntConstant"> int PyModule_AddIntConstant(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *module, const char *name, long value)<a class="headerlink" href="#c.PyModule_AddIntConstant" title="Link to this definition">¶</a> </dt> <dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Add an integer constant to module as name. This convenience function can be used from the module’s initialization function. Return <code class="docutils literal notranslate">-1</code> with an exception set on error, <code class="docutils literal notranslate">0</code> on success. 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">PyLong_FromLong()</code></a> and <a class="reference internal" href="#c.PyModule_AddObjectRef" title="PyModule_AddObjectRef"><code class="xref c c-func docutils literal notranslate">PyModule_AddObjectRef()</code></a>; see their documentation for details. </dd></dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyModule_AddStringConstant"> int PyModule_AddStringConstant(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *module, const char *name, const char *value)<a class="headerlink" href="#c.PyModule_AddStringConstant" title="Link to this definition">¶</a> </dt> <dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Add a string constant to module as name. This convenience function can be used from the module’s initialization function. The string value must be <code class="docutils literal notranslate">NULL</code>-terminated. Return <code class="docutils literal notranslate">-1</code> with an exception set on error, <code class="docutils literal notranslate">0</code> on success. 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">PyUnicode_InternFromString()</code></a> and <a class="reference internal" href="#c.PyModule_AddObjectRef" title="PyModule_AddObjectRef"><code class="xref c c-func docutils literal notranslate">PyModule_AddObjectRef()</code></a>; see their documentation for details. </dd></dl> <dl class="c macro"> <dt class="sig sig-object c" id="c.PyModule_AddIntMacro"> PyModule_AddIntMacro(module, macro)<a class="headerlink" href="#c.PyModule_AddIntMacro" title="Link to this definition">¶</a> </dt> <dd>Add an int constant to module. The name and the value are taken from macro. For example <code class="docutils literal notranslate">PyModule_AddIntMacro(module, AF_INET)</code> adds the int constant AF_INET with the value of AF_INET to module. Return <code class="docutils literal notranslate">-1</code> with an exception set on error, <code class="docutils literal notranslate">0</code> on success. </dd></dl> <dl class="c macro"> <dt class="sig sig-object c" id="c.PyModule_AddStringMacro"> PyModule_AddStringMacro(module, macro)<a class="headerlink" href="#c.PyModule_AddStringMacro" title="Link to this definition">¶</a> </dt> <dd>Add a string constant to module. </dd></dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyModule_AddType"> int PyModule_AddType(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *module, <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> *type)<a class="headerlink" href="#c.PyModule_AddType" title="Link to this definition">¶</a> </dt> <dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a> since version 3.10.Add a type object to module. 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">PyType_Ready()</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">tp_name</code></a> after dot. Return <code class="docutils literal notranslate">-1</code> with an exception set on error, <code class="docutils literal notranslate">0</code> on success. <div class="versionadded"> Added in version 3.9. </div> </dd></dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyUnstable_Module_SetGIL"> int PyUnstable_Module_SetGIL(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *module, void *gil)<a class="headerlink" href="#c.PyUnstable_Module_SetGIL" title="Link to this definition">¶</a> </dt> <dd><div class="unstable-c-api warning admonition"> This is <a class="reference internal" href="stable.html#unstable-c-api">Unstable API</a>. It may change without warning in minor releases.</div> Indicate that module 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">Py_mod_gil</code></a>. It must be called during module’s initialization function. 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">--disable-gil</code></a>. Return <code class="docutils literal notranslate">-1</code> with an exception set on error, <code class="docutils literal notranslate">0</code> on success. <div class="versionadded"> Added in version 3.13. </div> </dd></dl> </section> </section> <section id="module-lookup"> <h2>Module lookup<a class="headerlink" href="#module-lookup" title="Link to this heading">¶</a></h2> Single-phase initialization 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. These functions will not work on modules created using multi-phase initialization, since multiple such modules can be created from a single definition. <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">PyObject</a> *PyState_FindModule(<a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef">PyModuleDef</a> *def)<a class="headerlink" href="#c.PyState_FindModule" title="Link to this definition">¶</a> </dt> <dd>Return value: Borrowed reference. Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Returns the module object that was created from def 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">PyState_AddModule()</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">NULL</code>. </dd></dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyState_AddModule"> int PyState_AddModule(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *module, <a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef">PyModuleDef</a> *def)<a class="headerlink" href="#c.PyState_AddModule" title="Link to this definition">¶</a> </dt> <dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a> since version 3.3.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">PyState_FindModule()</code></a>. Only effective on modules created using single-phase initialization. Python calls <code class="docutils literal notranslate">PyState_AddModule</code> automatically after importing a module, 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">PyState_FindModule</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). The caller must hold the GIL. Return <code class="docutils literal notranslate">-1</code> with an exception set on error, <code class="docutils literal notranslate">0</code> on success. <div class="versionadded"> Added in version 3.3. </div> </dd></dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyState_RemoveModule"> int PyState_RemoveModule(<a class="reference internal" href="#c.PyModuleDef" title="PyModuleDef">PyModuleDef</a> *def)<a class="headerlink" href="#c.PyState_RemoveModule" title="Link to this definition">¶</a> </dt> <dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a> since version 3.3.Removes the module object created from def from the interpreter state. Return <code class="docutils literal notranslate">-1</code> with an exception set on error, <code class="docutils literal notranslate">0</code> on success. The caller must hold the GIL. <div class="versionadded"> Added in version 3.3. </div> </dd></dl> </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="#initializing-c-modules">Initializing C modules</a><ul> <li><a class="reference internal" href="#single-phase-initialization">Single-phase initialization</a></li> <li><a class="reference internal" href="#multi-phase-initialization">Multi-phase initialization</a></li> <li><a class="reference internal" href="#low-level-module-creation-functions">Low-level module creation functions</a></li> <li><a class="reference internal" href="#support-functions">Support functions</a></li> </ul> </li> <li><a class="reference internal" href="#module-lookup">Module lookup</a></li> </ul> </li> </ul> </div> <div> <h4>Previous topic</h4> <a href="file.html" title="previous chapter">File Objects</a> </div> <div> <h4>Next topic</h4> <a href="iterator.html" title="next chapter">Iterator Objects</a> </div> <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 href="https://github.com/python/cpython/blob/main/Doc/c-api/module.rst" rel="nofollow">Show Source </a> </li> </ul> </div> </div> <div id="sidebarbutton" title="Collapse sidebar"> « </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.13.2 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-2025, Python Software Foundation. This page is licensed under the Python Software Foundation License Version 2. Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License. See <a href="/license.html">History and License</a> for more information. The Python Software Foundation is a non-profit corporation. <a href="https://www.python.org/psf/donations/">Please donate.</a> Last updated on Feb 17, 2025 (16:47 UTC). <a href="/bugs.html">Found a bug</a>? Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.1.3. </div> <script type="text/javascript" src="../_static/switchers.js"></script> </body> </html>