Add support for the limited C API (Py_LIMITED_API)

Examples of API not available in the limited C API:

* PyBytesWriter
* PyConfig_Get(), PyConfig_GetInt().
* PyDict_ContainsString().
* PyFrame_GetBack(), PyFrame_GetVar()
* PyLongWriter_Create() and PyLong_Export()
* PyObject_VisitManagedDict(), PyObject_ClearManagedDict()
* PyThreadState_GetUnchecked()
* PyTime_t API.
* PyUnicodeWriter
* PyUnstable_SetImmortal().
* Py_SETREF(), Py_XSETREF().

Implementation notes:

* PyUnicode_EqualToUTF8AndSize() has no ASCII fast path.
* PyLong_GetSign(), PyLong_IsPositive(), PyLong_IsNegative() and
  PyLong_IsZero() are implemented with PyObject_RichCompareBool().
* PyBytes_Join() calls PyObject_CallMethod(sep, "join", iterable).
* Add PYTHONCAPI_COMPAT_EXPECT_TYPE() macro to raise TypeError.
  There are 3 implementations depending on the API and Python
  version.

test_pythoncapi_compat.py now reuses the setup module to list tests.

Closes #183

Author: vstinner

docs/api.rst

@@ -40,6 +40,8 @@ Python 3.15
 
    See `PyBytesWriter documentation  <https://docs.python.org/dev/c-api/bytes.html#pybyteswriter>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: PyObject* PySys_GetAttr(const char *name)
 
    See `PySys_GetAttr() documentation  <https://docs.python.org/dev/c-api/sys.html#c.PySys_GetAttr>`__.
@@ -60,17 +62,22 @@ Python 3.15
 
    See `PyTuple_FromArray() documentation  <https://docs.python.org/dev/c-api/tuple.html#c.PyTuple_FromArray>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: Py_hash_t PyUnstable_Unicode_GET_CACHED_HASH(PyObject *op)
 
    See `PyUnstable_Unicode_GET_CACHED_HASH() documentation  <https://docs.python.org/dev/c-api/unicode.html#c.PyUnstable_Unicode_GET_CACHED_HASH>`__.
 
    On PyPy, always returns ``-1``.
 
+   Not available with the limited C API.
+
 .. c:function:: int PyUnstable_SetImmortal(PyObject *op)
 
    See `PyUnstable_SetImmortal() documentation  <https://docs.python.org/dev/c-api/object.html#c.PyUnstable_SetImmortal>`__.
 
-   Availability: Python 3.13 and newer, not available on PyPy.
+   Availability: Python 3.13 and newer, not available on PyPy, not available
+   with the limited C API.
 
 Python 3.14
 -----------
@@ -79,38 +86,56 @@ Python 3.14
 
    See `PyLongLayout documentation <https://docs.python.org/dev/c-api/long.html#c.PyLongLayout>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: const PyLongLayout* PyLong_GetNativeLayout(void)
 
    See `PyLong_GetNativeLayout() documentation  <https://docs.python.org/dev/c-api/long.html#c.PyLong_GetNativeLayout>`__.
 
+   Not available with the limited C API.
+
 .. c:struct:: PyLongExport
 
    See `PyLongExport documentation <https://docs.python.org/dev/c-api/long.html#c.PyLongExport>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: int PyLong_Export(PyObject *obj, PyLongExport *export_long)
 
    See `PyLong_Export() documentation  <https://docs.python.org/dev/c-api/long.html#c.PyLong_Export>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: void PyLong_FreeExport(PyLongExport *export_long)
 
    See `PyLong_FreeExport() documentation  <https://docs.python.org/dev/c-api/long.html#c.PyLong_FreeExport>`__.
 
+   Not available with the limited C API.
+
 .. c:struct:: PyLongWriter
 
    See `PyLongWriter documentation <https://docs.python.org/dev/c-api/long.html#c.PyLongWriter>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: PyLongWriter* PyLongWriter_Create(int negative, Py_ssize_t ndigits, void **digits)
 
    See `PyLongWriter_Create() documentation  <https://docs.python.org/dev/c-api/long.html#c.PyLongWriter_Create>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: PyObject* PyLongWriter_Finish(PyLongWriter *writer)
 
    See `PyLongWriter_Finish() documentation  <https://docs.python.org/dev/c-api/long.html#c.PyLongWriter_Finish>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: void PyLongWriter_Discard(PyLongWriter *writer)
 
    See `PyLongWriter_Discard() documentation  <https://docs.python.org/dev/c-api/long.html#c.PyLongWriter_Discard>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: int PyLong_IsPositive(PyObject *obj)
 
    See `PyLong_IsPositive() documentation  <https://docs.python.org/dev/c-api/long.html#c.PyLong_IsPositive>`__.
@@ -147,46 +172,68 @@ Python 3.14
 
    See `PyUnicodeWriter_Create() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter_Create>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: PyObject* PyUnicodeWriter_Finish(PyUnicodeWriter *writer)
 
    See `PyUnicodeWriter_Finish() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter_Finish>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: void PyUnicodeWriter_Discard(PyUnicodeWriter *writer)
 
    See `PyUnicodeWriter_Discard() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter_Discard>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: int PyUnicodeWriter_WriteChar(PyUnicodeWriter *writer, Py_UCS4 ch)
 
    See `PyUnicodeWriter_WriteChar() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter_WriteChar>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: int PyUnicodeWriter_WriteUTF8(PyUnicodeWriter *writer, const char *str, Py_ssize_t size)
 
    See `PyUnicodeWriter_WriteUTF8() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter_WriteUTF8>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: int PyUnicodeWriter_WriteASCII(PyUnicodeWriter *writer, const char *str, Py_ssize_t size)
 
    See `PyUnicodeWriter_WriteASCII() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter_WriteASCII>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: int PyUnicodeWriter_WriteWideChar(PyUnicodeWriter *writer, const wchar_t *str, Py_ssize_t size)
 
    See `PyUnicodeWriter_WriteWideChar() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter_WriteWideChar>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: int PyUnicodeWriter_WriteStr(PyUnicodeWriter *writer, PyObject *obj)
 
    See `PyUnicodeWriter_WriteStr() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter_WriteStr>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: int PyUnicodeWriter_WriteRepr(PyUnicodeWriter *writer, PyObject *obj)
 
    See `PyUnicodeWriter_WriteRepr() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter_WriteRepr>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: int PyUnicodeWriter_WriteSubstring(PyUnicodeWriter *writer, PyObject *str, Py_ssize_t start, Py_ssize_t end)
 
    See `PyUnicodeWriter_WriteSubstring() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter_WriteSubstring>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: int PyUnicodeWriter_Format(PyUnicodeWriter *writer, const char *format, ...)
 
    See `PyUnicodeWriter_Format() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter_Format>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: int PyLong_AsInt32(PyObject *obj, int32_t *pvalue)
 
    See `PyLong_AsInt32() documentation <https://docs.python.org/dev/c-api/long.html#c.PyLong_AsInt32>`__.
@@ -231,16 +278,22 @@ Python 3.14
 
    See `PyConfig_Get() documentation <https://docs.python.org/dev/c-api/init_config.html#c.PyConfig_Get>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: int PyConfig_GetInt(const char *name, int *value)
 
    See `PyConfig_GetInt() documentation <https://docs.python.org/dev/c-api/init_config.html#c.PyConfig_GetInt>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: int PyUnstable_Object_IsUniquelyReferenced(PyObject *op)
 
    See `PyUnstable_Object_IsUniquelyReferenced() documentation <https://docs.python.org/dev/c-api/object.html#c.PyUnstable_Object_IsUniquelyReferenced>`__.
 
    Not available on PyPy. ``Py_REFCNT()`` semantics is different on PyPy.
 
+   Not available with the limited C API.
+
 .. c:function:: int PyUnstable_TryIncRef(PyObject *op)
 
    See `PyUnstable_TryIncRef() documentation <https://docs.python.org/dev/c-api/object.html#c.PyUnstable_TryIncRef>`__.
@@ -336,7 +389,7 @@ Python 3.13
    Return non-zero if the Python interpreter is shutting down, return 0
    otherwise.
 
-   Availability: Python 3.3 and newer, PyPy 7.3 and newer.
+   Availability: Python 3.3 and newer, PyPy 7.3 and newer, limited C API 3.13.
 
    See `Py_IsFinalizing() documentation <https://docs.python.org/dev/c-api/init.html#c.Py_IsFinalizing>`__.
 
@@ -352,15 +405,19 @@ Python 3.13
 
    See `PyObject_VisitManagedDict() documentation <https://docs.python.org/dev/c-api/object.html#c.PyObject_VisitManagedDict>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: void PyObject_ClearManagedDict(PyObject *obj)
 
    See `PyObject_ClearManagedDict() documentation <https://docs.python.org/dev/c-api/object.html#c.PyObject_ClearManagedDict>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: PyThreadState* PyThreadState_GetUnchecked(void)
 
    See `PyThreadState_GetUnchecked() documentation <https://docs.python.org/dev/c-api/init.html#c.PyThreadState_GetUnchecked>`__.
 
-   Available on Python 3.5.2 and newer.
+   Available on Python 3.5.2 and newer. Not available with the limited C API.
 
 .. c:function:: int PyUnicode_EqualToUTF8(PyObject *unicode, const char *str)
 
@@ -390,35 +447,51 @@ Python 3.13
 
    See `Py_HashPointer() documentation <https://docs.python.org/dev/c-api/hash.html#c.Py_HashPointer>`__.
 
+   Not available with the limited C API.
+
 .. c:type:: PyTime_t
 
    A timestamp or duration in nanoseconds, represented as a signed 64-bit
    integer.
 
+   Not available with the limited C API.
+
 .. c:var:: PyTime_t PyTime_MIN
 
    Minimum value of :c:type:`PyTime_t`.
 
+   Not available with the limited C API.
+
 .. c:var:: PyTime_t PyTime_MAX
 
    Maximum value of :c:type:`PyTime_t`.
 
+   Not available with the limited C API.
+
 .. c:function:: double PyTime_AsSecondsDouble(PyTime_t t)
 
    See `PyTime_AsSecondsDouble() documentation <https://docs.python.org/dev/c-api/time.html#c.PyTime_AsSecondsDouble>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: int PyTime_Monotonic(PyTime_t *result)
 
    See `PyTime_Monotonic() documentation <https://docs.python.org/dev/c-api/time.html#c.PyTime_Monotonic>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: int PyTime_Time(PyTime_t *result)
 
    See `PyTime_Time() documentation <https://docs.python.org/dev/c-api/time.html#c.PyTime_Time>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: int PyTime_PerfCounter(PyTime_t *result)
 
    See `PyTime_PerfCounter() documentation <https://docs.python.org/dev/c-api/time.html#c.PyTime_PerfCounter>`__.
 
+   Not available with the limited C API.
+
 .. c:function:: PyObject* PyList_GetItemRef(PyObject *op, Py_ssize_t index)
 
    See `PyList_GetItemRef() documentation <https://docs.python.org/dev/c-api/list.html#c.PyList_GetItemRef>`__.
@@ -447,13 +520,13 @@ Python 3.12
 
    See `PyFrame_GetVar() documentation <https://docs.python.org/dev/c-api/frame.html#c.PyFrame_GetVar>`__.
 
-   Not available on PyPy.
+   Not available on PyPy nor with the limited C API.
 
 .. c:function:: PyObject* PyFrame_GetVarString(PyFrameObject *frame, const char *name)
 
    See `PyFrame_GetVarString() documentation <https://docs.python.org/dev/c-api/frame.html#c.PyFrame_GetVarString>`__.
 
-   Not available on PyPy.
+   Not available on PyPy nor with the limited C API.
 
 .. c:function:: PyObject* Py_GetConstant(unsigned int constant_id)
 
@@ -689,7 +762,7 @@ PyFrameObject
 
    See `PyFrame_GetBack() documentation <https://docs.python.org/dev/c-api/reflection.html#c.PyFrame_GetBack>`__.
 
-   Not available on PyPy
+   Not available on PyPy nor with the limited C API.
 
 
 PyThreadState
@@ -838,7 +911,9 @@ part of the Python C API.
 
 .. c:function:: PyFrameObject* _PyFrame_GetBackBorrow(PyFrameObject *frame)
 
-   :c:func:`PyFrame_GetBack` variant Not available on PyPy.
+   :c:func:`PyFrame_GetBack` variant.
+
+   Not available on PyPy nor with the limited C API.
 
 For example, ``tstate->frame`` can be replaced with
 ``_PyThreadState_GetFrameBorrow(tstate)`` to avoid accessing directly

docs/changelog.rst

@@ -1,6 +1,7 @@
 Changelog
 =========
 
+* 2026-10-04: Add support for the limited C API (``Py_LIMITED_API``).
 * 2026-09-23: ``PyUnstable_Object_IsUniquelyReferenced()``,
   ``PyUnstable_TryIncRef()`` and ``PyUnstable_EnableTryIncRef()`` are no longer
   available on PyPy. ``Py_REFCNT()`` semantics is different on PyPy.