505 lines
29 KiB
HTML
505 lines
29 KiB
HTML
|
||
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta name="color-scheme" content="light dark">
|
||
<title>PEP 384 – Defining a Stable ABI | peps.python.org</title>
|
||
<link rel="shortcut icon" href="../_static/py.png">
|
||
<link rel="canonical" href="https://peps.python.org/pep-0384/">
|
||
<link rel="stylesheet" href="../_static/style.css" type="text/css">
|
||
<link rel="stylesheet" href="../_static/mq.css" type="text/css">
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light">
|
||
<link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark">
|
||
<link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss">
|
||
<meta property="og:title" content='PEP 384 – Defining a Stable ABI | peps.python.org'>
|
||
<meta property="og:description" content="Currently, each feature release introduces a new name for the Python DLL on Windows, and may cause incompatibilities for extension modules on Unix. This PEP proposes to define a stable set of API functions which are guaranteed to be available for the li...">
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:url" content="https://peps.python.org/pep-0384/">
|
||
<meta property="og:site_name" content="Python Enhancement Proposals (PEPs)">
|
||
<meta property="og:image" content="https://peps.python.org/_static/og-image.png">
|
||
<meta property="og:image:alt" content="Python PEPs">
|
||
<meta property="og:image:width" content="200">
|
||
<meta property="og:image:height" content="200">
|
||
<meta name="description" content="Currently, each feature release introduces a new name for the Python DLL on Windows, and may cause incompatibilities for extension modules on Unix. This PEP proposes to define a stable set of API functions which are guaranteed to be available for the li...">
|
||
<meta name="theme-color" content="#3776ab">
|
||
</head>
|
||
<body>
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
|
||
<symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Following system colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<circle cx="12" cy="12" r="9"></circle>
|
||
<path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Selected dark colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
|
||
<path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Selected light colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<circle cx="12" cy="12" r="5"></circle>
|
||
<line x1="12" y1="1" x2="12" y2="3"></line>
|
||
<line x1="12" y1="21" x2="12" y2="23"></line>
|
||
<line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
|
||
<line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
|
||
<line x1="1" y1="12" x2="3" y2="12"></line>
|
||
<line x1="21" y1="12" x2="23" y2="12"></line>
|
||
<line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
|
||
<line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
|
||
</svg>
|
||
</symbol>
|
||
</svg>
|
||
<script>
|
||
|
||
document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto"
|
||
</script>
|
||
<section id="pep-page-section">
|
||
<header>
|
||
<h1>Python Enhancement Proposals</h1>
|
||
<ul class="breadcrumbs">
|
||
<li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li>
|
||
<li><a href="../pep-0000/">PEP Index</a> » </li>
|
||
<li>PEP 384</li>
|
||
</ul>
|
||
<button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())">
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg>
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg>
|
||
<span class="visually-hidden">Toggle light / dark / auto colour theme</span>
|
||
</button>
|
||
</header>
|
||
<article>
|
||
<section id="pep-content">
|
||
<h1 class="page-title">PEP 384 – Defining a Stable ABI</h1>
|
||
<dl class="rfc2822 field-list simple">
|
||
<dt class="field-odd">Author<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Martin von Löwis <martin at v.loewis.de></dd>
|
||
<dt class="field-even">Status<span class="colon">:</span></dt>
|
||
<dd class="field-even"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd>
|
||
<dt class="field-odd">Type<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd>
|
||
<dt class="field-even">Created<span class="colon">:</span></dt>
|
||
<dd class="field-even">17-May-2009</dd>
|
||
<dt class="field-odd">Python-Version<span class="colon">:</span></dt>
|
||
<dd class="field-odd">3.2</dd>
|
||
<dt class="field-even">Post-History<span class="colon">:</span></dt>
|
||
<dd class="field-even"><p></p></dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<section id="contents">
|
||
<details><summary>Table of Contents</summary><ul class="simple">
|
||
<li><a class="reference internal" href="#abstract">Abstract</a></li>
|
||
<li><a class="reference internal" href="#rationale">Rationale</a></li>
|
||
<li><a class="reference internal" href="#specification">Specification</a><ul>
|
||
<li><a class="reference internal" href="#terminology">Terminology</a></li>
|
||
<li><a class="reference internal" href="#header-files-and-preprocessor-definitions">Header Files and Preprocessor Definitions</a></li>
|
||
<li><a class="reference internal" href="#structures">Structures</a></li>
|
||
<li><a class="reference internal" href="#type-objects">Type Objects</a></li>
|
||
<li><a class="reference internal" href="#typedefs">typedefs</a></li>
|
||
<li><a class="reference internal" href="#functions-and-function-like-macros">Functions and function-like Macros</a></li>
|
||
<li><a class="reference internal" href="#excluded-functions">Excluded Functions</a></li>
|
||
<li><a class="reference internal" href="#global-variables">Global Variables</a></li>
|
||
<li><a class="reference internal" href="#other-macros">Other Macros</a></li>
|
||
<li><a class="reference internal" href="#the-buffer-interface">The Buffer Interface</a></li>
|
||
<li><a class="reference internal" href="#signature-changes">Signature Changes</a></li>
|
||
<li><a class="reference internal" href="#linkage">Linkage</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#implementation-strategy">Implementation Strategy</a></li>
|
||
<li><a class="reference internal" href="#references">References</a></li>
|
||
<li><a class="reference internal" href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
</details></section>
|
||
<div class="pep-banner canonical-doc sticky-banner admonition important">
|
||
<p class="admonition-title">Important</p>
|
||
<p>This PEP is a historical document. The up-to-date, canonical documentation can now be found at <a class="reference external" href="https://docs.python.org/3/c-api/stable.html#stable" title="(in Python v3.12)"><span>C API Stability</span></a> (user docs) and
|
||
<a class="reference external" href="https://devguide.python.org/developer-workflow/c-api/#c-api" title="(in Python Developer's Guide)"><span>Changing Python’s C API</span></a> (development docs).</p>
|
||
<p class="close-button">×</p>
|
||
<p>See <a class="pep reference internal" href="../pep-0001/" title="PEP 1 – PEP Purpose and Guidelines">PEP 1</a> for how to propose changes.</p>
|
||
</div>
|
||
<section id="abstract">
|
||
<h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2>
|
||
<p>Currently, each feature release introduces a new name for the
|
||
Python DLL on Windows, and may cause incompatibilities for extension
|
||
modules on Unix. This PEP proposes to define a stable set of API
|
||
functions which are guaranteed to be available for the lifetime
|
||
of Python 3, and which will also remain binary-compatible across
|
||
versions. Extension modules and applications embedding Python
|
||
can work with different feature releases as long as they restrict
|
||
themselves to this stable ABI.</p>
|
||
</section>
|
||
<section id="rationale">
|
||
<h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2>
|
||
<p>The primary source of ABI incompatibility are changes to the lay-out
|
||
of in-memory structures. For example, the way in which string interning
|
||
works, or the data type used to represent the size of an object, have
|
||
changed during the life of Python 2.x. As a consequence, extension
|
||
modules making direct access to fields of strings, lists, or tuples,
|
||
would break if their code is loaded into a newer version of the
|
||
interpreter without recompilation: offsets of other fields may have
|
||
changed, making the extension modules access the wrong data.</p>
|
||
<p>In some cases, the incompatibilities only affect internal objects of
|
||
the interpreter, such as frame or code objects. For example, the way
|
||
line numbers are represented has changed in the 2.x lifetime, as has
|
||
the way in which local variables are stored (due to the introduction
|
||
of closures). Even though most applications probably never used these
|
||
objects, changing them had required to change the PYTHON_API_VERSION.</p>
|
||
<p>On Linux, changes to the ABI are often not much of a problem: the
|
||
system will provide a default Python installation, and many extension
|
||
modules are already provided pre-compiled for that version. If additional
|
||
modules are needed, or additional Python versions, users can typically
|
||
compile them themselves on the system, resulting in modules that use
|
||
the right ABI.</p>
|
||
<p>On Windows, multiple simultaneous installations of different Python
|
||
versions are common, and extension modules are compiled by their
|
||
authors, not by end users. To reduce the risk of ABI incompatibilities,
|
||
Python currently introduces a new DLL name pythonXY.dll for each
|
||
feature release, whether or not ABI incompatibilities actually exist.</p>
|
||
<p>With this PEP, it will be possible to reduce the dependency of binary
|
||
extension modules on a specific Python feature release, and applications
|
||
embedding Python can be made work with different releases.</p>
|
||
</section>
|
||
<section id="specification">
|
||
<h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2>
|
||
<p>The ABI specification falls into two parts: an API specification,
|
||
specifying what function (groups) are available for use with the
|
||
ABI, and a linkage specification specifying what libraries to link
|
||
with. The actual ABI (layout of structures in memory, function
|
||
calling conventions) is not specified, but implied by the
|
||
compiler. As a recommendation, a specific ABI is recommended for
|
||
selected platforms.</p>
|
||
<p>During evolution of Python, new ABI functions will be added.
|
||
Applications using them will then have a requirement on a minimum
|
||
version of Python; this PEP provides no mechanism for such
|
||
applications to fall back when the Python library is too old.</p>
|
||
<section id="terminology">
|
||
<h3><a class="toc-backref" href="#terminology" role="doc-backlink">Terminology</a></h3>
|
||
<p>Applications and extension modules that want to use this ABI
|
||
are collectively referred to as “applications” from here on.</p>
|
||
</section>
|
||
<section id="header-files-and-preprocessor-definitions">
|
||
<h3><a class="toc-backref" href="#header-files-and-preprocessor-definitions" role="doc-backlink">Header Files and Preprocessor Definitions</a></h3>
|
||
<p>Applications shall only include the header file Python.h (before
|
||
including any system headers), or, optionally, include pyconfig.h, and
|
||
then Python.h.</p>
|
||
<p>During the compilation of applications, the preprocessor macro
|
||
Py_LIMITED_API must be defined. Doing so will hide all definitions
|
||
that are not part of the ABI.</p>
|
||
</section>
|
||
<section id="structures">
|
||
<h3><a class="toc-backref" href="#structures" role="doc-backlink">Structures</a></h3>
|
||
<p>Only the following structures and structure fields are accessible to
|
||
applications:</p>
|
||
<ul class="simple">
|
||
<li>PyObject (ob_refcnt, ob_type)</li>
|
||
<li>PyVarObject (ob_base, ob_size)</li>
|
||
<li>PyMethodDef (ml_name, ml_meth, ml_flags, ml_doc)</li>
|
||
<li>PyMemberDef (name, type, offset, flags, doc)</li>
|
||
<li>PyGetSetDef (name, get, set, doc, closure)</li>
|
||
<li>PyModuleDefBase (ob_base, m_init, m_index, m_copy)</li>
|
||
<li>PyModuleDef (m_base, m_name, m_doc, m_size, m_methods, m_traverse,
|
||
m_clear, m_free)</li>
|
||
<li>PyStructSequence_Field (name, doc)</li>
|
||
<li>PyStructSequence_Desc (name, doc, fields, sequence)</li>
|
||
<li>PyType_Slot (see below)</li>
|
||
<li>PyType_Spec (see below)</li>
|
||
</ul>
|
||
<p>The accessor macros to these fields (Py_REFCNT, Py_TYPE, Py_SIZE)
|
||
are also available to applications.</p>
|
||
<p>The following types are available, but opaque (i.e. incomplete):</p>
|
||
<ul class="simple">
|
||
<li>PyThreadState</li>
|
||
<li>PyInterpreterState</li>
|
||
<li>struct _frame</li>
|
||
<li>struct symtable</li>
|
||
<li>struct _node</li>
|
||
<li>PyWeakReference</li>
|
||
<li>PyLongObject</li>
|
||
<li>PyTypeObject</li>
|
||
</ul>
|
||
</section>
|
||
<section id="type-objects">
|
||
<h3><a class="toc-backref" href="#type-objects" role="doc-backlink">Type Objects</a></h3>
|
||
<p>The structure of type objects is not available to applications;
|
||
declaration of “static” type objects is not possible anymore
|
||
(for applications using this ABI).
|
||
Instead, type objects get created dynamically. To allow an
|
||
easy creation of types (in particular, to be able to fill out
|
||
function pointers easily), the following structures and functions
|
||
are available:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">typedef</span> <span class="n">struct</span><span class="p">{</span>
|
||
<span class="nb">int</span> <span class="n">slot</span><span class="p">;</span> <span class="o">/*</span> <span class="n">slot</span> <span class="nb">id</span><span class="p">,</span> <span class="n">see</span> <span class="n">below</span> <span class="o">*/</span>
|
||
<span class="n">void</span> <span class="o">*</span><span class="n">pfunc</span><span class="p">;</span> <span class="o">/*</span> <span class="n">function</span> <span class="n">pointer</span> <span class="o">*/</span>
|
||
<span class="p">}</span> <span class="n">PyType_Slot</span><span class="p">;</span>
|
||
|
||
<span class="n">typedef</span> <span class="n">struct</span><span class="p">{</span>
|
||
<span class="n">const</span> <span class="n">char</span><span class="o">*</span> <span class="n">name</span><span class="p">;</span>
|
||
<span class="nb">int</span> <span class="n">basicsize</span><span class="p">;</span>
|
||
<span class="nb">int</span> <span class="n">itemsize</span><span class="p">;</span>
|
||
<span class="n">unsigned</span> <span class="nb">int</span> <span class="n">flags</span><span class="p">;</span>
|
||
<span class="n">PyType_Slot</span> <span class="o">*</span><span class="n">slots</span><span class="p">;</span> <span class="o">/*</span> <span class="n">terminated</span> <span class="n">by</span> <span class="n">slot</span><span class="o">==</span><span class="mf">0.</span> <span class="o">*/</span>
|
||
<span class="p">}</span> <span class="n">PyType_Spec</span><span class="p">;</span>
|
||
|
||
<span class="n">PyObject</span><span class="o">*</span> <span class="n">PyType_FromSpec</span><span class="p">(</span><span class="n">PyType_Spec</span><span class="o">*</span><span class="p">);</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>To specify a slot, a unique slot id must be provided. New Python
|
||
versions may introduce new slot ids, but slot ids will never be
|
||
recycled. Slots may get deprecated, but continue to be supported
|
||
throughout Python 3.x.</p>
|
||
<p>The slot ids are named like the field names of the structures that
|
||
hold the pointers in Python 3.1, with an added <code class="docutils literal notranslate"><span class="pre">Py_</span></code> prefix (i.e.
|
||
Py_tp_dealloc instead of just tp_dealloc):</p>
|
||
<ul class="simple">
|
||
<li>tp_dealloc, tp_getattr, tp_setattr, tp_repr,
|
||
tp_hash, tp_call, tp_str, tp_getattro, tp_setattro,
|
||
tp_doc, tp_traverse, tp_clear, tp_richcompare, tp_iter,
|
||
tp_iternext, tp_methods, tp_base, tp_descr_get, tp_descr_set,
|
||
tp_init, tp_alloc, tp_new, tp_is_gc, tp_bases, tp_del</li>
|
||
<li>nb_add nb_subtract nb_multiply nb_remainder nb_divmod nb_power
|
||
nb_negative nb_positive nb_absolute nb_bool nb_invert nb_lshift
|
||
nb_rshift nb_and nb_xor nb_or nb_int nb_float nb_inplace_add
|
||
nb_inplace_subtract nb_inplace_multiply nb_inplace_remainder
|
||
nb_inplace_power nb_inplace_lshift nb_inplace_rshift nb_inplace_and
|
||
nb_inplace_xor nb_inplace_or nb_floor_divide nb_true_divide
|
||
nb_inplace_floor_divide nb_inplace_true_divide nb_index</li>
|
||
<li>sq_length sq_concat sq_repeat sq_item sq_ass_item
|
||
sq_contains sq_inplace_concat sq_inplace_repeat</li>
|
||
<li>mp_length mp_subscript mp_ass_subscript</li>
|
||
</ul>
|
||
<p>The following fields cannot be set during type definition:
|
||
- tp_dict tp_mro tp_cache tp_subclasses tp_weaklist tp_print
|
||
- tp_weaklistoffset tp_dictoffset</p>
|
||
</section>
|
||
<section id="typedefs">
|
||
<h3><a class="toc-backref" href="#typedefs" role="doc-backlink">typedefs</a></h3>
|
||
<p>In addition to the typedefs for structs listed above, the following
|
||
typedefs are available. Their inclusion in the ABI means that the
|
||
underlying type must not change on a platform (even though it may
|
||
differ across platforms).</p>
|
||
<ul class="simple">
|
||
<li>Py_uintptr_t Py_intptr_t Py_ssize_t</li>
|
||
<li>unaryfunc binaryfunc ternaryfunc inquiry lenfunc ssizeargfunc
|
||
ssizessizeargfunc ssizeobjargproc ssizessizeobjargproc objobjargproc
|
||
objobjproc visitproc traverseproc
|
||
destructor getattrfunc getattrofunc setattrfunc setattrofunc reprfunc
|
||
hashfunc richcmpfunc getiterfunc iternextfunc descrgetfunc
|
||
descrsetfunc initproc newfunc allocfunc</li>
|
||
<li>PyCFunction PyCFunctionWithKeywords PyNoArgsFunction
|
||
PyCapsule_Destructor</li>
|
||
<li>getter setter</li>
|
||
<li>PyOS_sighandler_t</li>
|
||
<li>PyGILState_STATE</li>
|
||
<li>Py_UCS4</li>
|
||
</ul>
|
||
<p>Most notably, Py_UNICODE is not available as a typedef,
|
||
since the same Python version may use different definitions
|
||
of it on the same platform (depending on whether it uses narrow
|
||
or wide code units). Applications that need to access the contents
|
||
of a Unicode string can convert it to wchar_t.</p>
|
||
</section>
|
||
<section id="functions-and-function-like-macros">
|
||
<h3><a class="toc-backref" href="#functions-and-function-like-macros" role="doc-backlink">Functions and function-like Macros</a></h3>
|
||
<p>By default, all functions are available, unless they are excluded
|
||
below.
|
||
Whether a function is documented or not does not matter.</p>
|
||
<p>Function-like macros (in particular, field access macros) remain
|
||
available to applications, but get replaced by function calls
|
||
(unless their definition only refers to features of the ABI, such
|
||
as the various _Check macros)</p>
|
||
<p>ABI function declarations will not change their parameters or return
|
||
types. If a change to the signature becomes necessary, a new function
|
||
will be introduced. If the new function is source-compatible (e.g. if
|
||
just the return type changes), an alias macro may get added to
|
||
redirect calls to the new function when the applications is
|
||
recompiled.</p>
|
||
<p>If continued provision of the old function is not possible, it may get
|
||
deprecated, then removed, causing
|
||
applications that use that function to break.</p>
|
||
</section>
|
||
<section id="excluded-functions">
|
||
<h3><a class="toc-backref" href="#excluded-functions" role="doc-backlink">Excluded Functions</a></h3>
|
||
<p>All functions starting with _Py are not available to applications.
|
||
Also, all functions that expect parameter types that are unavailable
|
||
to applications are excluded from the ABI, such as PyAST_FromNode
|
||
(which expects a <code class="docutils literal notranslate"><span class="pre">node*</span></code>).</p>
|
||
<p>Functions declared in the following header files are not part
|
||
of the ABI:</p>
|
||
<ul class="simple">
|
||
<li>bytes_methods.h</li>
|
||
<li>cellobject.h</li>
|
||
<li>classobject.h</li>
|
||
<li>code.h</li>
|
||
<li>compile.h</li>
|
||
<li>datetime.h</li>
|
||
<li>dtoa.h</li>
|
||
<li>frameobject.h</li>
|
||
<li>funcobject.h</li>
|
||
<li>genobject.h</li>
|
||
<li>longintrepr.h</li>
|
||
<li>parsetok.h</li>
|
||
<li>pyarena.h</li>
|
||
<li>pyatomic.h</li>
|
||
<li>pyctype.h</li>
|
||
<li>pydebug.h</li>
|
||
<li>pytime.h</li>
|
||
<li>symtable.h</li>
|
||
<li>token.h</li>
|
||
<li>ucnhash.h</li>
|
||
</ul>
|
||
<p>In addition, functions expecting <code class="docutils literal notranslate"><span class="pre">FILE*</span></code> are not part of
|
||
the ABI, to avoid depending on a specific version of the
|
||
Microsoft C runtime DLL on Windows.</p>
|
||
<p>Module and type initializer and finalizer functions are not available
|
||
(PyByteArray_Init, PyOS_FiniInterrupts
|
||
and all functions ending in _Fini or _ClearFreeList).</p>
|
||
<p>Several functions dealing with interpreter implementation
|
||
details are not available:</p>
|
||
<ul class="simple">
|
||
<li>PyInterpreterState_Head, PyInterpreterState_Next,
|
||
PyInterpreterState_ThreadHead, PyThreadState_Next</li>
|
||
<li>Py_SubversionRevision, Py_SubversionShortBranch</li>
|
||
</ul>
|
||
<p>PyStructSequence_InitType is not available, as it requires
|
||
the caller to provide a static type object.</p>
|
||
<p>Py_FatalError will be moved from pydebug.h into some other
|
||
header file (e.g. pyerrors.h).</p>
|
||
<p>The exact list of functions being available is given
|
||
in the Windows module definition file for python3.dll <a class="footnote-reference brackets" href="#id5" id="id1">[1]</a>.</p>
|
||
</section>
|
||
<section id="global-variables">
|
||
<h3><a class="toc-backref" href="#global-variables" role="doc-backlink">Global Variables</a></h3>
|
||
<p>Global variables representing types and exceptions are available
|
||
to applications. In addition, selected global variables referenced
|
||
in macros (such as Py_True and Py_False) are available.</p>
|
||
<p>A complete list of global variable definitions is given in the
|
||
python3.def file <a class="footnote-reference brackets" href="#id5" id="id2">[1]</a>; those declared DATA denote variables.</p>
|
||
</section>
|
||
<section id="other-macros">
|
||
<h3><a class="toc-backref" href="#other-macros" role="doc-backlink">Other Macros</a></h3>
|
||
<p>All macros defining symbolic constants are available to applications;
|
||
the numeric values will not change.</p>
|
||
<p>In addition, the following macros are available:</p>
|
||
<ul class="simple">
|
||
<li>Py_BEGIN_ALLOW_THREADS, Py_BLOCK_THREADS, Py_UNBLOCK_THREADS,
|
||
Py_END_ALLOW_THREADS</li>
|
||
</ul>
|
||
</section>
|
||
<section id="the-buffer-interface">
|
||
<h3><a class="toc-backref" href="#the-buffer-interface" role="doc-backlink">The Buffer Interface</a></h3>
|
||
<p>The buffer interface (type Py_buffer, type slots bf_getbuffer and
|
||
bf_releasebuffer, etc) has been omitted from the ABI, since the stability
|
||
of the Py_buffer structure is not clear at this time. Inclusion in the
|
||
ABI can be considered in future releases.</p>
|
||
</section>
|
||
<section id="signature-changes">
|
||
<h3><a class="toc-backref" href="#signature-changes" role="doc-backlink">Signature Changes</a></h3>
|
||
<p>A number of functions currently expect a specific struct, even though
|
||
callers typically have PyObject* available. These have been changed
|
||
to expect PyObject* as the parameter; this will cause warnings in
|
||
applications that currently explicitly cast to the parameter type.
|
||
These functions are PySlice_GetIndices, PySlice_GetIndicesEx,
|
||
PyUnicode_AsWideChar, and PyEval_EvalCode.</p>
|
||
</section>
|
||
<section id="linkage">
|
||
<h3><a class="toc-backref" href="#linkage" role="doc-backlink">Linkage</a></h3>
|
||
<p>On Windows, applications shall link with python3.dll; an import
|
||
library python3.lib will be available. This DLL will redirect all of
|
||
its API functions through /export linker options to the full
|
||
interpreter DLL, i.e. python3y.dll.</p>
|
||
<p>On Unix systems, the ABI is typically provided by the python
|
||
executable itself. PyModule_Create is changed to pass <code class="docutils literal notranslate"><span class="pre">3</span></code> as the API
|
||
version if the extension module was compiled with Py_LIMITED_API; the
|
||
version check for the API version will accept either 3 or the current
|
||
PYTHON_API_VERSION as conforming. If Python is compiled as a shared
|
||
library, it is installed as both libpython3.so, and libpython3.y.so;
|
||
applications conforming to this PEP should then link to the former
|
||
(extension modules can continue to link with no libpython shared object,
|
||
but rather rely on runtime linking).
|
||
The ABI version is symbolically available as <code class="docutils literal notranslate"><span class="pre">PYTHON_ABI_VERSION</span></code>.</p>
|
||
<p>Also on Unix, the <a class="pep reference internal" href="../pep-3149/" title="PEP 3149 – ABI version tagged .so files">PEP 3149</a> tag abi<PYTHON_ABI_VERSION> is accepted
|
||
in file names of extension modules. No checking is performed that
|
||
files named in this way are actually restricted to the limited API,
|
||
and no support for building such files will be added to distutils
|
||
due to the distutils code freeze.</p>
|
||
</section>
|
||
</section>
|
||
<section id="implementation-strategy">
|
||
<h2><a class="toc-backref" href="#implementation-strategy" role="doc-backlink">Implementation Strategy</a></h2>
|
||
<p>This PEP will be implemented in a branch <a class="footnote-reference brackets" href="#id6" id="id3">[2]</a>, allowing users to check
|
||
whether their modules conform to the ABI. To avoid users having to
|
||
rewrite their type definitions, a script to convert C source code
|
||
containing type definitions will be provided <a class="footnote-reference brackets" href="#id7" id="id4">[3]</a>.</p>
|
||
</section>
|
||
<section id="references">
|
||
<h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2>
|
||
<aside class="footnote-list brackets">
|
||
<aside class="footnote brackets" id="id5" role="doc-footnote">
|
||
<dt class="label" id="id5">[1]<em> (<a href='#id1'>1</a>, <a href='#id2'>2</a>) </em></dt>
|
||
<dd>“python3 module definition file”:
|
||
<a class="reference external" href="http://svn.python.org/projects/python/branches/pep-0384/PC/python3.def">http://svn.python.org/projects/python/branches/pep-0384/PC/python3.def</a></aside>
|
||
<aside class="footnote brackets" id="id6" role="doc-footnote">
|
||
<dt class="label" id="id6">[<a href="#id3">2</a>]</dt>
|
||
<dd>“PEP 384 branch”:
|
||
<a class="reference external" href="http://svn.python.org/projects/python/branches/pep-0384/">http://svn.python.org/projects/python/branches/pep-0384/</a></aside>
|
||
<aside class="footnote brackets" id="id7" role="doc-footnote">
|
||
<dt class="label" id="id7">[<a href="#id4">3</a>]</dt>
|
||
<dd>“ABI type conversion script”:
|
||
<a class="reference external" href="http://svn.python.org/projects/python/branches/pep-0384/Tools/scripts/abitype.py">http://svn.python.org/projects/python/branches/pep-0384/Tools/scripts/abitype.py</a></aside>
|
||
</aside>
|
||
</section>
|
||
<section id="copyright">
|
||
<h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2>
|
||
<p>This document has been placed in the public domain.</p>
|
||
</section>
|
||
</section>
|
||
<hr class="docutils" />
|
||
<p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0384.rst">https://github.com/python/peps/blob/main/peps/pep-0384.rst</a></p>
|
||
<p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0384.rst">2023-09-09 17:39:29 GMT</a></p>
|
||
|
||
</article>
|
||
<nav id="pep-sidebar">
|
||
<h2>Contents</h2>
|
||
<ul>
|
||
<li><a class="reference internal" href="#abstract">Abstract</a></li>
|
||
<li><a class="reference internal" href="#rationale">Rationale</a></li>
|
||
<li><a class="reference internal" href="#specification">Specification</a><ul>
|
||
<li><a class="reference internal" href="#terminology">Terminology</a></li>
|
||
<li><a class="reference internal" href="#header-files-and-preprocessor-definitions">Header Files and Preprocessor Definitions</a></li>
|
||
<li><a class="reference internal" href="#structures">Structures</a></li>
|
||
<li><a class="reference internal" href="#type-objects">Type Objects</a></li>
|
||
<li><a class="reference internal" href="#typedefs">typedefs</a></li>
|
||
<li><a class="reference internal" href="#functions-and-function-like-macros">Functions and function-like Macros</a></li>
|
||
<li><a class="reference internal" href="#excluded-functions">Excluded Functions</a></li>
|
||
<li><a class="reference internal" href="#global-variables">Global Variables</a></li>
|
||
<li><a class="reference internal" href="#other-macros">Other Macros</a></li>
|
||
<li><a class="reference internal" href="#the-buffer-interface">The Buffer Interface</a></li>
|
||
<li><a class="reference internal" href="#signature-changes">Signature Changes</a></li>
|
||
<li><a class="reference internal" href="#linkage">Linkage</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#implementation-strategy">Implementation Strategy</a></li>
|
||
<li><a class="reference internal" href="#references">References</a></li>
|
||
<li><a class="reference internal" href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
|
||
<br>
|
||
<a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0384.rst">Page Source (GitHub)</a>
|
||
</nav>
|
||
</section>
|
||
<script src="../_static/colour_scheme.js"></script>
|
||
<script src="../_static/wrap_tables.js"></script>
|
||
<script src="../_static/sticky_banner.js"></script>
|
||
</body>
|
||
</html> |