1544 lines
164 KiB
HTML
1544 lines
164 KiB
HTML
<!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.0 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=48df1187" />
|
||
<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=0fe728b1"></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.0 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/3.15/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 class="root-icon"><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.0 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="../builtins/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="../builtins/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="../builtins/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="../builtins/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="../builtins/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: </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="../builtins/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: </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: </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/3.15/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 class="root-icon"><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.0 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 Oct 09, 2026 (11:35 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> |