https://github.com/python/cpython/commit/962304a54ca79da0838cf46dd4fb744045167cdd
commit: 962304a54ca79da0838cf46dd4fb744045167cdd
branch: main
author: Peter Bierma <[email protected]>
committer: encukou <[email protected]>
date: 2024-09-10T15:05:28+02:00
summary:
gh-123609: Clarify usage of standalone `PyBUF_FORMAT` (GH-123778)
files:
M Doc/c-api/buffer.rst
diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst
index 9500fe465c7d94..dc43a3d5fcb094 100644
--- a/Doc/c-api/buffer.rst
+++ b/Doc/c-api/buffer.rst
@@ -244,7 +244,6 @@ The following fields are not influenced by *flags* and must
always be filled in
with the correct values: :c:member:`~Py_buffer.obj`,
:c:member:`~Py_buffer.buf`,
:c:member:`~Py_buffer.len`, :c:member:`~Py_buffer.itemsize`,
:c:member:`~Py_buffer.ndim`.
-
readonly, format
~~~~~~~~~~~~~~~~
@@ -253,7 +252,8 @@ readonly, format
Controls the :c:member:`~Py_buffer.readonly` field. If set, the exporter
MUST provide a writable buffer or else report failure. Otherwise, the
exporter MAY provide either a read-only or writable buffer, but the
choice
- MUST be consistent for all consumers.
+ MUST be consistent for all consumers. For example, :c:expr:`PyBUF_SIMPLE
| PyBUF_WRITABLE`
+ can be used to request a simple writable buffer.
.. c:macro:: PyBUF_FORMAT
@@ -265,8 +265,9 @@ readonly, format
Since :c:macro:`PyBUF_SIMPLE` is defined as 0, :c:macro:`PyBUF_WRITABLE`
can be used as a stand-alone flag to request a simple writable buffer.
-:c:macro:`PyBUF_FORMAT` can be \|'d to any of the flags except
:c:macro:`PyBUF_SIMPLE`.
-The latter already implies format ``B`` (unsigned bytes).
+:c:macro:`PyBUF_FORMAT` must be \|'d to any of the flags except
:c:macro:`PyBUF_SIMPLE`, because
+the latter already implies format ``B`` (unsigned bytes).
:c:macro:`!PyBUF_FORMAT` cannot be
+used on its own.
shape, strides, suboffsets
_______________________________________________
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]
