From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Fri, 1 Nov 2024 19:38:23 +0000 (+0100)
Subject: [3.12] gh-123609: Clarify usage of standalone `PyBUF_FORMAT` (GH-123778) (GH-123904)
X-Git-Tag: v3.12.8~125
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=ce5bb3ca850392227ed9d5790c60789eb30daf5f;p=thirdparty%2FPython%2Fcpython.git

[3.12] gh-123609: Clarify usage of standalone `PyBUF_FORMAT` (GH-123778) (GH-123904)

gh-123609: Clarify usage of standalone `PyBUF_FORMAT` (GH-123778)
(cherry picked from commit 962304a54ca79da0838cf46dd4fb744045167cdd)

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
---

diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst
index 9500fe465c7d..dc43a3d5fcb0 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