https://github.com/python/cpython/commit/d7ea5ba95e2e6fb821a3dd30ff955fce21b82502
commit: d7ea5ba95e2e6fb821a3dd30ff955fce21b82502
branch: main
author: Petr Viktorin <[email protected]>
committer: encukou <[email protected]>
date: 2026-10-28T16:04:49+01:00
summary:
gh-156870: Use shared Stable ABI notes for remaining entries in tables
(GH-160551)
- Use a shared Stable ABI note
- Convert some to list-table for maintainability
files:
M Doc/c-api/buffer.rst
M Doc/c-api/long.rst
M Doc/c-api/structures.rst
diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst
index dc3e0f37c36c5b..956d0b0939efee 100644
--- a/Doc/c-api/buffer.rst
+++ b/Doc/c-api/buffer.rst
@@ -284,19 +284,38 @@ The flags that control the logical structure of the
memory are listed
in decreasing order of complexity. Note that each flag contains all bits
of the flags below it.
-.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|
-
-+-----------------------------+-------+---------+------------+
-| Request | shape | strides | suboffsets |
-+=============================+=======+=========+============+
-| .. c:macro:: PyBUF_INDIRECT | yes | yes | if needed |
-+-----------------------------+-------+---------+------------+
-| .. c:macro:: PyBUF_STRIDES | yes | yes | NULL |
-+-----------------------------+-------+---------+------------+
-| .. c:macro:: PyBUF_ND | yes | NULL | NULL |
-+-----------------------------+-------+---------+------------+
-| .. c:macro:: PyBUF_SIMPLE | NULL | NULL | NULL |
-+-----------------------------+-------+---------+------------+
+.. stable-abi-note::
+
+ These values are available when compiling for the
+ :ref:`Stable ABI <stable>` since version 3.11.
+
+.. omit-stable-abi-notes::
+
+ .. list-table::
+ :align: left
+ :widths: auto
+ :header-rows: 1
+
+ * - Request
+ - shape
+ - strides
+ - suboffsets
+ * - .. c:macro:: PyBUF_INDIRECT
+ - yes
+ - yes
+ - if needed
+ * - .. c:macro:: PyBUF_STRIDES
+ - yes
+ - yes
+ - NULL
+ * - .. c:macro:: PyBUF_ND
+ - yes
+ - NULL
+ - NULL
+ * - .. c:macro:: PyBUF_SIMPLE
+ - NULL
+ - NULL
+ - NULL
.. index:: contiguous, C-contiguous, Fortran contiguous
@@ -308,19 +327,43 @@ C or Fortran :term:`contiguity <contiguous>` can be
explicitly requested,
with and without stride information. Without stride information, the buffer
must be C-contiguous.
-.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|l|
-
-+-----------------------------------+-------+---------+------------+--------+
-| Request | shape | strides | suboffsets | contig |
-+===================================+=======+=========+============+========+
-| .. c:macro:: PyBUF_C_CONTIGUOUS | yes | yes | NULL | C |
-+-----------------------------------+-------+---------+------------+--------+
-| .. c:macro:: PyBUF_F_CONTIGUOUS | yes | yes | NULL | F |
-+-----------------------------------+-------+---------+------------+--------+
-| .. c:macro:: PyBUF_ANY_CONTIGUOUS | yes | yes | NULL | C or F |
-+-----------------------------------+-------+---------+------------+--------+
-| :c:macro:`PyBUF_ND` | yes | NULL | NULL | C |
-+-----------------------------------+-------+---------+------------+--------+
+.. stable-abi-note::
+
+ These values are available when compiling for the
+ :ref:`Stable ABI <stable>` since version 3.11.
+
+.. omit-stable-abi-notes::
+
+ .. list-table::
+ :align: left
+ :widths: auto
+ :header-rows: 1
+
+ * - Request
+ - shape
+ - strides
+ - suboffsets
+ - contig
+ * - .. c:macro:: PyBUF_C_CONTIGUOUS
+ - yes
+ - yes
+ - NULL
+ - C
+ * - .. c:macro:: PyBUF_F_CONTIGUOUS
+ - yes
+ - yes
+ - NULL
+ - F
+ * - .. c:macro:: PyBUF_ANY_CONTIGUOUS
+ - yes
+ - yes
+ - NULL
+ - C or F
+ * - :c:macro:`PyBUF_ND`
+ - yes
+ - NULL
+ - NULL
+ - C
compound requests
@@ -333,27 +376,81 @@ used combinations as single flags.
In the following table *U* stands for undefined contiguity. The consumer would
have to call :c:func:`PyBuffer_IsContiguous` to determine contiguity.
-.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|l|l|l|
-
-+-------------------------------+-------+---------+------------+--------+----------+--------+
-| Request | shape | strides | suboffsets | contig |
readonly | format |
-+===============================+=======+=========+============+========+==========+========+
-| .. c:macro:: PyBUF_FULL | yes | yes | if needed | U |
0 | yes |
-+-------------------------------+-------+---------+------------+--------+----------+--------+
-| .. c:macro:: PyBUF_FULL_RO | yes | yes | if needed | U | 1
or 0 | yes |
-+-------------------------------+-------+---------+------------+--------+----------+--------+
-| .. c:macro:: PyBUF_RECORDS | yes | yes | NULL | U |
0 | yes |
-+-------------------------------+-------+---------+------------+--------+----------+--------+
-| .. c:macro:: PyBUF_RECORDS_RO | yes | yes | NULL | U | 1
or 0 | yes |
-+-------------------------------+-------+---------+------------+--------+----------+--------+
-| .. c:macro:: PyBUF_STRIDED | yes | yes | NULL | U |
0 | NULL |
-+-------------------------------+-------+---------+------------+--------+----------+--------+
-| .. c:macro:: PyBUF_STRIDED_RO | yes | yes | NULL | U | 1
or 0 | NULL |
-+-------------------------------+-------+---------+------------+--------+----------+--------+
-| .. c:macro:: PyBUF_CONTIG | yes | NULL | NULL | C |
0 | NULL |
-+-------------------------------+-------+---------+------------+--------+----------+--------+
-| .. c:macro:: PyBUF_CONTIG_RO | yes | NULL | NULL | C | 1
or 0 | NULL |
-+-------------------------------+-------+---------+------------+--------+----------+--------+
+.. stable-abi-note::
+
+ These values are available when compiling for the
+ :ref:`Stable ABI <stable>` since version 3.11.
+
+.. omit-stable-abi-notes::
+
+ .. list-table::
+ :align: left
+ :widths: auto
+ :header-rows: 1
+
+ * - Request
+ - shape
+ - strides
+ - suboffsets
+ - contig
+ - readonly
+ - format
+ * - .. c:macro:: PyBUF_FULL
+ - yes
+ - yes
+ - if needed
+ - U
+ - 0
+ - yes
+ * - .. c:macro:: PyBUF_FULL_RO
+ - yes
+ - yes
+ - if needed
+ - U
+ - 1 or 0
+ - yes
+ * - .. c:macro:: PyBUF_RECORDS
+ - yes
+ - yes
+ - NULL
+ - U
+ - 0
+ - yes
+ * - .. c:macro:: PyBUF_RECORDS_RO
+ - yes
+ - yes
+ - NULL
+ - U
+ - 1 or 0
+ - yes
+ * - .. c:macro:: PyBUF_STRIDED
+ - yes
+ - yes
+ - NULL
+ - U
+ - 0
+ - NULL
+ * - .. c:macro:: PyBUF_STRIDED_RO
+ - yes
+ - yes
+ - NULL
+ - U
+ - 1 or 0
+ - NULL
+ * - .. c:macro:: PyBUF_CONTIG
+ - yes
+ - NULL
+ - NULL
+ - C
+ - 0
+ - NULL
+ * - .. c:macro:: PyBUF_CONTIG_RO
+ - yes
+ - NULL
+ - NULL
+ - C
+ - 1 or 0
+ - NULL
Complex arrays
diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
index b25dec161cb6f1..c0da28d557a2ad 100644
--- a/Doc/c-api/long.rst
+++ b/Doc/c-api/long.rst
@@ -535,17 +535,24 @@ distinguished from a number. Use
:c:func:`PyErr_Occurred` to disambiguate.
.. c:namespace:: NULL
- ============================================= ======
- Flag Value
- ============================================= ======
- .. c:macro:: Py_ASNATIVEBYTES_DEFAULTS ``-1``
- .. c:macro:: Py_ASNATIVEBYTES_BIG_ENDIAN ``0``
- .. c:macro:: Py_ASNATIVEBYTES_LITTLE_ENDIAN ``1``
- .. c:macro:: Py_ASNATIVEBYTES_NATIVE_ENDIAN ``3``
- .. c:macro:: Py_ASNATIVEBYTES_UNSIGNED_BUFFER ``4``
- .. c:macro:: Py_ASNATIVEBYTES_REJECT_NEGATIVE ``8``
- .. c:macro:: Py_ASNATIVEBYTES_ALLOW_INDEX ``16``
- ============================================= ======
+ .. stable-abi-note::
+
+ These values are available when compiling for the
+ :ref:`Stable ABI <stable>` since version 3.14.
+
+ .. omit-stable-abi-notes::
+
+ ============================================= ======
+ Flag Value
+ ============================================= ======
+ .. c:macro:: Py_ASNATIVEBYTES_DEFAULTS ``-1``
+ .. c:macro:: Py_ASNATIVEBYTES_BIG_ENDIAN ``0``
+ .. c:macro:: Py_ASNATIVEBYTES_LITTLE_ENDIAN ``1``
+ .. c:macro:: Py_ASNATIVEBYTES_NATIVE_ENDIAN ``3``
+ .. c:macro:: Py_ASNATIVEBYTES_UNSIGNED_BUFFER ``4``
+ .. c:macro:: Py_ASNATIVEBYTES_REJECT_NEGATIVE ``8``
+ .. c:macro:: Py_ASNATIVEBYTES_ALLOW_INDEX ``16``
+ ============================================= ======
Specifying ``Py_ASNATIVEBYTES_NATIVE_ENDIAN`` will override any other endian
flags. Passing ``2`` is reserved.
diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst
index d9557491bc93bd..2f2c8e06f668b9 100644
--- a/Doc/c-api/structures.rst
+++ b/Doc/c-api/structures.rst
@@ -812,29 +812,77 @@ If that is not possible, an exception such as
:exc:`TypeError` or
Unless marked (D), attributes defined this way cannot be deleted
using e.g. :keyword:`del` or :py:func:`delattr`.
-================================ =============================
======================
-Macro name C type Python type
-================================ =============================
======================
-.. c:macro:: Py_T_BYTE :c:expr:`char` :py:class:`int`
-.. c:macro:: Py_T_SHORT :c:expr:`short` :py:class:`int`
-.. c:macro:: Py_T_INT :c:expr:`int` :py:class:`int`
-.. c:macro:: Py_T_LONG :c:expr:`long` :py:class:`int`
-.. c:macro:: Py_T_LONGLONG :c:expr:`long long` :py:class:`int`
-.. c:macro:: Py_T_UBYTE :c:expr:`unsigned char` :py:class:`int`
-.. c:macro:: Py_T_UINT :c:expr:`unsigned int` :py:class:`int`
-.. c:macro:: Py_T_USHORT :c:expr:`unsigned short` :py:class:`int`
-.. c:macro:: Py_T_ULONG :c:expr:`unsigned long` :py:class:`int`
-.. c:macro:: Py_T_ULONGLONG :c:expr:`unsigned long long` :py:class:`int`
-.. c:macro:: Py_T_PYSSIZET :c:expr:`Py_ssize_t` :py:class:`int`
-.. c:macro:: Py_T_FLOAT :c:expr:`float`
:py:class:`float`
-.. c:macro:: Py_T_DOUBLE :c:expr:`double`
:py:class:`float`
-.. c:macro:: Py_T_BOOL :c:expr:`char` :py:class:`bool`
- (written as 0 or 1)
-.. c:macro:: Py_T_STRING :c:expr:`const char *` (*) :py:class:`str`
(RO)
-.. c:macro:: Py_T_STRING_INPLACE :c:expr:`const char[]` (*) :py:class:`str`
(RO)
-.. c:macro:: Py_T_CHAR :c:expr:`char` (0-127) :py:class:`str`
(**)
-.. c:macro:: Py_T_OBJECT_EX :c:expr:`PyObject *`
:py:class:`object` (D)
-================================ =============================
======================
+.. stable-abi-note::
+
+ These values are available when compiling for the
+ :ref:`Stable ABI <stable>` since version 3.12.
+
+.. omit-stable-abi-notes::
+
+ .. list-table::
+ :align: left
+ :widths: auto
+ :header-rows: 1
+
+ * - Macro name
+ - C type
+ - Python type
+ * - .. c:macro:: Py_T_BYTE
+ - :c:expr:`char`
+ - :py:class:`int`
+ * - .. c:macro:: Py_T_SHORT
+ - :c:expr:`short`
+ - :py:class:`int`
+ * - .. c:macro:: Py_T_INT
+ - :c:expr:`int`
+ - :py:class:`int`
+ * - .. c:macro:: Py_T_LONG
+ - :c:expr:`long`
+ - :py:class:`int`
+ * - .. c:macro:: Py_T_LONGLONG
+ - :c:expr:`long long`
+ - :py:class:`int`
+ * - .. c:macro:: Py_T_UBYTE
+ - :c:expr:`unsigned char`
+ - :py:class:`int`
+ * - .. c:macro:: Py_T_UINT
+ - :c:expr:`unsigned int`
+ - :py:class:`int`
+ * - .. c:macro:: Py_T_USHORT
+ - :c:expr:`unsigned short`
+ - :py:class:`int`
+ * - .. c:macro:: Py_T_ULONG
+ - :c:expr:`unsigned long`
+ - :py:class:`int`
+ * - .. c:macro:: Py_T_ULONGLONG
+ - :c:expr:`unsigned long long`
+ - :py:class:`int`
+ * - .. c:macro:: Py_T_PYSSIZET
+ - :c:expr:`Py_ssize_t`
+ - :py:class:`int`
+ * - .. c:macro:: Py_T_FLOAT
+ - :c:expr:`float`
+ - :py:class:`float`
+ * - .. c:macro:: Py_T_DOUBLE
+ - :c:expr:`double`
+ - :py:class:`float`
+ * - .. c:macro:: Py_T_BOOL
+ - :c:expr:`char` (written as 0 or 1)
+ - :py:class:`bool`
+ * - .. c:macro:: Py_T_STRING
+ - :c:expr:`const char *` (*)
+ - :py:class:`str` (RO)
+ * - .. c:macro:: Py_T_STRING_INPLACE
+ - :c:expr:`const char[]` (*)
+ - :py:class:`str` (RO)
+ * - .. c:macro:: Py_T_CHAR
+ - :c:expr:`char` (0-127)
+ - :py:class:`str` (**)
+ * - .. c:macro:: Py_T_OBJECT_EX
+ - :c:expr:`PyObject *`
+ - :py:class:`object` (D)
+
+..
(*): Zero-terminated, UTF8-encoded C string.
With :c:macro:`!Py_T_STRING` the C representation is a pointer;
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
