Add Stable ABI documentation.

diff --git a/Doc/c-api/index.rst b/Doc/c-api/index.rst
index 12a1ec70727447e921f8a67372ad75ba465b4fbd..a0cb6e510bf9f76fba320b5cc5c5c80864c987ba 100644 (file)
--- a/Doc/c-api/index.rst
+++ b/Doc/c-api/index.rst
@@ -25,3 +25,4 @@ document the API functions in detail.
    init.rst
    memory.rst
    objimpl.rst
+   stable.rst

diff --git a/Doc/c-api/stable.rst b/Doc/c-api/stable.rst
new file mode 100644 (file)
index 0000000..d95536c
--- /dev/null
+++ b/Doc/c-api/stable.rst
@@ -0,0 +1,39 @@
+.. highlightlang:: c
+
+.. _stable:
+
+**********************************
+Stable Appliction 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 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. Extensions modules
+wishing to use these new APIs need to set Py_LIMITED_API to the
+PY_VERSION_HEX value 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.
+
+.. XXX copy exact list here? Into each functions definition?