[Python-checkins] gh-107298: Fix C API Buffer documentation (#108011)
vstinner
webhook-mailer at python.org
Wed Aug 16 12:24:50 EDT 2023
https://github.com/python/cpython/commit/c2941cba7a986e6158eebb2a0bf33906dcd78616
commit: c2941cba7a986e6158eebb2a0bf33906dcd78616
branch: main
author: Victor Stinner <vstinner at python.org>
committer: vstinner <vstinner at python.org>
date: 2023-08-16T18:24:46+02:00
summary:
gh-107298: Fix C API Buffer documentation (#108011)
files:
M Doc/c-api/buffer.rst
M Doc/c-api/typeobj.rst
M Doc/tools/.nitignore
diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst
index ba391a5279f20..e572815ffd625 100644
--- a/Doc/c-api/buffer.rst
+++ b/Doc/c-api/buffer.rst
@@ -163,13 +163,6 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
and :c:member:`~Py_buffer.suboffsets` MUST be ``NULL``.
The maximum number of dimensions is given by :c:macro:`PyBUF_MAX_NDIM`.
- .. :c:macro:: PyBUF_MAX_NDIM
-
- The maximum number of dimensions the memory represents.
- Exporters MUST respect this limit, consumers of multi-dimensional
- buffers SHOULD be able to handle up to :c:macro:`!PyBUF_MAX_NDIM` dimensions.
- Currently set to 64.
-
.. c:member:: Py_ssize_t *shape
An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`
@@ -221,6 +214,17 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
freed when the buffer is released. The consumer MUST NOT alter this
value.
+
+Constants:
+
+.. c:macro:: PyBUF_MAX_NDIM
+
+ The maximum number of dimensions the memory represents.
+ Exporters MUST respect this limit, consumers of multi-dimensional
+ buffers SHOULD be able to handle up to :c:macro:`!PyBUF_MAX_NDIM` dimensions.
+ Currently set to 64.
+
+
.. _buffer-request-types:
Buffer request types
@@ -444,7 +448,7 @@ Buffer-related functions
Send a request to *exporter* to fill in *view* as specified by *flags*.
If the exporter cannot provide a buffer of the exact type, it MUST raise
- :c:data:`PyExc_BufferError`, set ``view->obj`` to ``NULL`` and
+ :exc:`BufferError`, set ``view->obj`` to ``NULL`` and
return ``-1``.
On success, fill in *view*, set ``view->obj`` to a new reference
@@ -531,7 +535,7 @@ Buffer-related functions
and :c:macro:`PyBUF_WRITABLE` is set in *flags*.
On success, set ``view->obj`` to a new reference to *exporter* and
- return 0. Otherwise, raise :c:data:`PyExc_BufferError`, set
+ return 0. Otherwise, raise :exc:`BufferError`, set
``view->obj`` to ``NULL`` and return ``-1``;
If this function is used as part of a :ref:`getbufferproc <buffer-structs>`,
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index faa183e27fcfa..d394ce10504b0 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -2443,7 +2443,7 @@ Buffer Object Structures
Except for point (3), an implementation of this function MUST take these
steps:
- (1) Check if the request can be met. If not, raise :c:data:`PyExc_BufferError`,
+ (1) Check if the request can be met. If not, raise :exc:`BufferError`,
set :c:expr:`view->obj` to ``NULL`` and return ``-1``.
(2) Fill in the requested fields.
diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore
index 21b350c4134fd..0f68cefc92b97 100644
--- a/Doc/tools/.nitignore
+++ b/Doc/tools/.nitignore
@@ -2,7 +2,6 @@
# as tested on the CI via check-warnings.py in reusable-docs.yml.
# Keep lines sorted lexicographically to help avoid merge conflicts.
-Doc/c-api/buffer.rst
Doc/c-api/datetime.rst
Doc/c-api/descriptor.rst
Doc/c-api/exceptions.rst
More information about the Python-checkins
mailing list