| FazBrowse GitHub Viewer | Trending | | Home |
| Tools: [Download Repo ZIP] [Original HTTPS Page] |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -806,15 +806,15 @@ because the :ref:`call protocol <call>` takes care of recursion handling. | |||
| 806 | 806 | depth limit. | |
| 807 | 807 | ||
| 808 | 808 | .. versionchanged:: 3.9 | |
| 809 | - This function is now also available in the limited API. | ||
| 809 | + This function is now also available in the :ref:`limited API <limited-c-api>`. | ||
| 810 | 810 | ||
| 811 | 811 | .. c:function:: void Py_LeaveRecursiveCall(void) | |
| 812 | 812 | ||
| 813 | 813 | Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each | |
| 814 | 814 | *successful* invocation of :c:func:`Py_EnterRecursiveCall`. | |
| 815 | 815 | ||
| 816 | 816 | .. versionchanged:: 3.9 | |
| 817 | - This function is now also available in the limited API. | ||
| 817 | + This function is now also available in the :ref:`limited API <limited-c-api>`. | ||
| 818 | 818 | ||
| 819 | 819 | Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types requires | |
| 820 | 820 | special recursion handling. In addition to protecting the stack, | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -25,19 +25,19 @@ are private API that can change without notice even in patch releases. | |||
| 25 | 25 | Stable Application Binary Interface | |
| 26 | 26 | =================================== | |
| 27 | 27 | ||
| 28 | + For simplicity, this document talks about *extensions*, but the Limited API | ||
| 29 | + and Stable ABI work the same way for all uses of the API – for example, | ||
| 30 | + embedding Python. | ||
| 31 | + | ||
| 32 | + .. _limited-c-api: | ||
| 33 | + | ||
| 34 | + Limited C API | ||
| 35 | + ------------- | ||
| 36 | + | ||
| 28 | 37 | Python 3.2 introduced the *Limited API*, a subset of Python's C API. | |
| 29 | 38 | Extensions that only use the Limited API can be | |
| 30 | 39 | compiled once and work with multiple versions of Python. | |
| 31 | - Contents of the Limited API are :ref:`listed below <stable-abi-list>`. | ||
| 32 | - | ||
| 33 | - To enable this, Python provides a *Stable ABI*: a set of symbols that will | ||
| 34 | - remain compatible across Python 3.x versions. The Stable ABI contains symbols | ||
| 35 | - exposed in the Limited API, but also other ones – for example, functions | ||
| 36 | - necessary to support older versions of the Limited API. | ||
| 37 | - | ||
| 38 | - (For simplicity, this document talks about *extensions*, but the Limited API | ||
| 39 | - and Stable ABI work the same way for all uses of the API – for example, | ||
| 40 | - embedding Python.) | ||
| 40 | + Contents of the Limited API are :ref:`listed below <limited-api-list>`. | ||
| 41 | 41 | ||
| 42 | 42 | .. c:macro:: Py_LIMITED_API | |
| 43 | 43 | ||
@@ -57,6 +57,19 @@ embedding Python.) | |||
| 57 | 57 | You can also define ``Py_LIMITED_API`` to ``3``. This works the same as | |
| 58 | 58 | ``0x03020000`` (Python 3.2, the version that introduced Limited API). | |
| 59 | 59 | ||
| 60 | + | ||
| 61 | + .. _stable-abi: | ||
| 62 | + | ||
| 63 | + Stable ABI | ||
| 64 | + ---------- | ||
| 65 | + | ||
| 66 | + To enable this, Python provides a *Stable ABI*: a set of symbols that will | ||
| 67 | + remain compatible across Python 3.x versions. | ||
| 68 | + | ||
| 69 | + The Stable ABI contains symbols exposed in the :ref:`Limited API | ||
| 70 | + <limited-c-api>`, but also other ones – for example, functions necessary to | ||
| 71 | + support older versions of the Limited API. | ||
| 72 | + | ||
| 60 | 73 | On Windows, extensions that use the Stable ABI should be linked against | |
| 61 | 74 | ``python3.dll`` rather than a version-specific library such as | |
| 62 | 75 | ``python39.dll``. | |
@@ -101,9 +114,9 @@ Limited API Caveats | |||
| 101 | 114 | ------------------- | |
| 102 | 115 | ||
| 103 | 116 | Note that compiling with ``Py_LIMITED_API`` is *not* a complete guarantee that | |
| 104 | - code conforms to the Limited API or the Stable ABI. ``Py_LIMITED_API`` only | ||
| 105 | - covers definitions, but an API also includes other issues, such as expected | ||
| 106 | - semantics. | ||
| 117 | + code conforms to the :ref:`Limited API <limited-c-api>` or the :ref:`Stable ABI | ||
| 118 | + <stable-abi>`. ``Py_LIMITED_API`` only covers definitions, but an API also | ||
| 119 | + includes other issues, such as expected semantics. | ||
| 107 | 120 | ||
| 108 | 121 | One issue that ``Py_LIMITED_API`` does not guard against is calling a function | |
| 109 | 122 | with arguments that are invalid in a lower Python version. | |
@@ -136,9 +149,9 @@ Platform Considerations | |||
| 136 | 149 | ======================= | |
| 137 | 150 | ||
| 138 | 151 | ABI stability depends not only on Python, but also on the compiler used, | |
| 139 | - lower-level libraries and compiler options. For the purposes of the Stable ABI, | ||
| 140 | - these details define a “platform”. They usually depend on the OS | ||
| 141 | - type and processor architecture | ||
| 152 | + lower-level libraries and compiler options. For the purposes of | ||
| 153 | + the :ref:`Stable ABI <stable-abi>`, these details define a “platform”. They | ||
| 154 | + usually depend on the OS type and processor architecture | ||
| 142 | 155 | ||
| 143 | 156 | It is the responsibility of each particular distributor of Python | |
| 144 | 157 | to ensure that all Python versions on a particular platform are built | |
@@ -147,12 +160,12 @@ This is the case with Windows and macOS releases from ``python.org`` and many | |||
| 147 | 160 | third-party distributors. | |
| 148 | 161 | ||
| 149 | 162 | ||
| 150 | - .. _stable-abi-list: | ||
| 163 | + .. _limited-api-list: | ||
| 151 | 164 | ||
| 152 | 165 | Contents of Limited API | |
| 153 | 166 | ======================= | |
| 154 | 167 | ||
| 155 | 168 | ||
| 156 | - Currently, the Limited API includes the following items: | ||
| 169 | + Currently, the :ref:`Limited API <limited-c-api>` includes the following items: | ||
| 157 | 170 | ||
| 158 | 171 | .. limited-api-list:: | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -318,7 +318,7 @@ There are these calling conventions: | |||
| 318 | 318 | ||
| 319 | 319 | .. versionchanged:: 3.10 | |
| 320 | 320 | ||
| 321 | - ``METH_FASTCALL`` is now part of the stable ABI. | ||
| 321 | + ``METH_FASTCALL`` is now part of the :ref:`stable ABI <stable-abi>`. | ||
| 322 | 322 | ||
| 323 | 323 | ||
| 324 | 324 | .. _METH_FASTCALL-METH_KEYWORDS: | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -42,7 +42,7 @@ Type Objects | |||
| 42 | 42 | Return the :c:member:`~PyTypeObject.tp_flags` member of *type*. This function is primarily | |
| 43 | 43 | meant for use with ``Py_LIMITED_API``; the individual flag bits are | |
| 44 | 44 | guaranteed to be stable across Python releases, but access to | |
| 45 | - :c:member:`~PyTypeObject.tp_flags` itself is not part of the limited API. | ||
| 45 | + :c:member:`~PyTypeObject.tp_flags` itself is not part of the :ref:`limited API <limited-c-api>`. | ||
| 46 | 46 | ||
| 47 | 47 | .. versionadded:: 3.2 | |
| 48 | 48 | ||
@@ -301,7 +301,7 @@ The following functions and structs are used to create | |||
| 301 | 301 | .. versionchanged:: 3.11 | |
| 302 | 302 | :c:member:`~PyBufferProcs.bf_getbuffer` and | |
| 303 | 303 | :c:member:`~PyBufferProcs.bf_releasebuffer` are now available | |
| 304 | - under the limited API. | ||
| 304 | + under the :ref:`limited API <limited-c-api>`. | ||
| 305 | 305 | ||
| 306 | 306 | .. c:member:: void *PyType_Slot.pfunc | |
| 307 | 307 | ||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -2082,7 +2082,7 @@ This results in types that are limited relative to types defined in Python: | |||
| 2082 | 2082 | include any subinterpreter-specific state. | |
| 2083 | 2083 | ||
| 2084 | 2084 | Also, since :c:type:`PyTypeObject` is only part of the :ref:`Limited API | |
| 2085 | - <stable>` as an opaque struct, any extension modules using static types must be | ||
| 2085 | + <limited-c-api>` as an opaque struct, any extension modules using static types must be | ||
| 2086 | 2086 | compiled for a specific Python minor version. | |
| 2087 | 2087 | ||
| 2088 | 2088 | ||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -1084,7 +1084,7 @@ These are the UTF-8 codec APIs: | |||
| 1084 | 1084 | The return type is now ``const char *`` rather of ``char *``. | |
| 1085 | 1085 | ||
| 1086 | 1086 | .. versionchanged:: 3.10 | |
| 1087 | - This function is a part of the :ref:`limited API <stable>`. | ||
| 1087 | + This function is a part of the :ref:`limited API <limited-c-api>`. | ||
| 1088 | 1088 | ||
| 1089 | 1089 | ||
| 1090 | 1090 | .. c:function:: const char* PyUnicode_AsUTF8(PyObject *unicode) | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -461,7 +461,7 @@ Module State Access from Slot Methods, Getters and Setters | |||
| 461 | 461 | ||
| 462 | 462 | .. After adding to limited API: | |
| 463 | 463 | ||
| 464 | - If you use the :ref:`limited API <stable>, | ||
| 464 | + If you use the :ref:`limited API <limited-c-api>`, | ||
| 465 | 465 | you must update ``Py_LIMITED_API`` to ``0x030b0000``, losing ABI | |
| 466 | 466 | compatibility with earlier versions. | |
| 467 | 467 | ||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -2654,7 +2654,7 @@ Removed | |||
| 2654 | 2654 | * :c:func:`PyMarshal_WriteObjectToString` | |
| 2655 | 2655 | * the ``Py_MARSHAL_VERSION`` macro | |
| 2656 | 2656 | ||
| 2657 | - These are not part of the :ref:`limited API <stable-abi-list>`. | ||
| 2657 | + These are not part of the :ref:`limited API <limited-api-list>`. | ||
| 2658 | 2658 | ||
| 2659 | 2659 | (Contributed by Victor Stinner in :issue:`45474`.) | |
| 2660 | 2660 | ||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -4980,7 +4980,7 @@ Removed documentation for the removed ``PyParser_*`` C API. | |||
| 4980 | 4980 | .. nonce: fy0AXK | |
| 4981 | 4981 | .. section: C API | |
| 4982 | 4982 | ||
| 4983 | - The list in :ref:`stable-abi-list` now shows the public name | ||
| 4983 | + The list in :ref:`limited-api-list` now shows the public name | ||
| 4984 | 4984 | :c:struct:`PyFrameObject` rather than ``_frame``. The non-existing entry | |
| 4985 | 4985 | ``_node`` no longer appears in the list. | |
| 4986 | 4986 | ||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -1234,7 +1234,7 @@ defined: | |||
| 1234 | 1234 | * :c:func:`PyMarshal_WriteObjectToString` | |
| 1235 | 1235 | * the ``Py_MARSHAL_VERSION`` macro | |
| 1236 | 1236 | ||
| 1237 | - These are not part of the :ref:`limited API <stable-abi-list>`. | ||
| 1237 | + These are not part of the :ref:`limited API <limited-api-list>`. | ||
| 1238 | 1238 | ||
| 1239 | 1239 | Patch by Victor Stinner. | |
| 1240 | 1240 | ||
| Back | FazBrowse Home | New Git URL |
0 commit comments