1 files changed, 38 insertions, 0 deletions
diff --git a/Doc/c-api/stable.rst b/Doc/c-api/stable.rst
new file mode 100644
index 0000000..063f856
--- /dev/null
+++ b/Doc/c-api/stable.rst
@@ -0,0 +1,38 @@
+.. highlightlang:: c
+
+.. _stable:
+
+***********************************
+Stable Application Binary Interface
+***********************************
+
+Traditionally, the C API of Python will change with every release.  Most changes
+will be source-compatible, typically by only adding API, rather than changing
+existing API or removing API (although some interfaces do get removed after
+being deprecated first).
+
+Unfortunately, the API compatibility does not extend to binary compatibility
+(the ABI). The reason is primarily the evolution of struct definitions, where
+addition of a new field, or changing the type of a field, might not break the
+API, but can break the ABI.  As a consequence, extension modules need to be
+recompiled for every Python release (although an exception is possible on Unix
+when none of the affected interfaces are used). In addition, on Windows,
+extension modules link with a specific pythonXY.dll and need to be recompiled to
+link with a newer one.
+
+Since Python 3.2, a subset of the API has been declared to guarantee a stable
+ABI. Extension modules wishing to use this API (called "limited API") need to
+define ``Py_LIMITED_API``. A number of interpreter details then become hidden
+from the extension module; in return, a module is built that works on any 3.x
+version (x>=2) without recompilation.
+
+In some cases, the stable ABI needs to be extended with new functions.
+Extension modules wishing to use these new APIs need to set ``Py_LIMITED_API``
+to the ``PY_VERSION_HEX`` value (see :ref:`apiabiversion`) of the minimum Python
+version they want to support (e.g. ``0x03030000`` for Python 3.3). Such modules
+will work on all subsequent Python releases, but fail to load (because of
+missing symbols) on the older releases.
+
+As of Python 3.2, the set of functions available to the limited API is
+documented in PEP 384.  In the C API documentation, API elements that are not
+part of the limited API are marked as "Not part of the limited API."