Skip to content

gh-156870: Use shared Stable ABI notes for remaining entries in tables #160551

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
encukou wants to merge 3 commits into
base: main
Choose a base branch
from
Open

gh-156870: Use shared Stable ABI notes for remaining entries in tables #160551

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8a3ef41
Make the table with PyBUF_* docs more compact
encukou Oct 23, 2026
9312578
Make the buffer tables more compact
encukou Oct 23, 2026
be96e9e
Make Py_T_* and Py_ASNATIVEBYTES_* tables more compact
encukou Oct 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
191 changes: 144 additions & 47 deletions Doc/c-api/buffer.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
29 changes: 18 additions & 11 deletions Doc/c-api/long.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
94 changes: 71 additions & 23 deletions Doc/c-api/structures.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
Loading