https://github.com/python/cpython/commit/3e16aefafabb31df7f8b6b80fdee6091e025debf commit: 3e16aefafabb31df7f8b6b80fdee6091e025debf branch: 3.15 author: Miss Islington (bot) <[email protected]> committer: encukou <[email protected]> date: 2026-10-28T15:13:12Z summary:
[3.15] gh-156870: Use shared Stable ABI notes for remaining entries in tables (GH-160551) (GH-160827) - Use a shared Stable ABI note - Convert some to list-table for maintainability (cherry picked from commit d7ea5ba95e2e6fb821a3dd30ff955fce21b82502) Co-authored-by: Petr Viktorin <[email protected]> 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 4fa7de67acdfd7..233d0fad27d11a 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]
