From 8a3ef41ac660a755550310cfc94c9a638d770bcb Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Fri, 23 Oct 2026 16:10:56 -0700 Subject: [PATCH 1/3] Make the table with PyBUF_* docs more compact - Use a shared Stable ABI note - Convert to list-table for maintainability --- Doc/c-api/buffer.rst | 45 +++++++++++++++++++++++++++++++------------- 1 file changed, 32 insertions(+), 13 deletions(-) diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst index dc3e0f37c36c5b..da84d26bb2c778 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 ` 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 From 9312578d6f386835c0e991a0d555186421804eea Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Fri, 23 Oct 2026 16:24:55 -0700 Subject: [PATCH 2/3] Make the buffer tables more compact - Use a shared Stable ABI note - Convert to list-table for maintainability --- Doc/c-api/buffer.rst | 144 +++++++++++++++++++++++++++++++++---------- 1 file changed, 111 insertions(+), 33 deletions(-) diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst index da84d26bb2c778..956d0b0939efee 100644 --- a/Doc/c-api/buffer.rst +++ b/Doc/c-api/buffer.rst @@ -327,19 +327,43 @@ C or Fortran :term:`contiguity ` 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| +.. stable-abi-note:: + + These values are available when compiling for the + :ref:`Stable ABI ` since version 3.11. + +.. omit-stable-abi-notes:: -+-----------------------------------+-------+---------+------------+--------+ -| 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 | -+-----------------------------------+-------+---------+------------+--------+ + .. 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 @@ -352,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 ` 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 From be96e9e9bddaaf4d54a8df5dc0b4f25282fce35e Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Fri, 23 Oct 2026 16:33:57 -0700 Subject: [PATCH 3/3] Make Py_T_* and Py_ASNATIVEBYTES_* tables more compact - Use a shared Stable ABI note - Convert the Py_T_* table to list-table for maintainability --- Doc/c-api/long.rst | 29 ++++++++----- Doc/c-api/structures.rst | 94 ++++++++++++++++++++++++++++++---------- 2 files changed, 89 insertions(+), 34 deletions(-) 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 ` 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 ` 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;