From 4e40251ef2ed5bff2fe2757803ddf02b8ad9d74c Mon Sep 17 00:00:00 2001 From: ZeroIntensity Date: Fri, 6 Sep 2024 09:05:28 -0400 Subject: [PATCH 1/6] Clarify usage of standalone PyBUF_FORMAT --- Doc/c-api/buffer.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst index 9500fe465c7d94..f000a1d61cf2c9 100644 --- a/Doc/c-api/buffer.rst +++ b/Doc/c-api/buffer.rst @@ -265,8 +265,12 @@ 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` can 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` also cannot +be standalone, because :c:macro:`PyBUF_SIMPLE` is defined as zero, so it's equivalent +to :c:expr:`PyBUF_SIMPLE | PyBUF_FORMAT`. However, standalone :c:macro:`PyBUF_FORMAT` is not directly +disallowed by :c:func:`PyBuffer_FillInfo`, so it's possible to do this on some objects (for +example, :class:`bytes` supports this, but :class:`memoryview` does not). shape, strides, suboffsets From 82f7d21f5021451627a4ab625b6956873887aa4b Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Fri, 6 Sep 2024 09:49:25 -0400 Subject: [PATCH 2/6] Update Doc/c-api/buffer.rst Co-authored-by: Petr Viktorin --- Doc/c-api/buffer.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst index f000a1d61cf2c9..d6616ad984f6a4 100644 --- a/Doc/c-api/buffer.rst +++ b/Doc/c-api/buffer.rst @@ -265,12 +265,10 @@ 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`, because -the latter already implies format ``B`` (unsigned bytes). :c:macro:`PyBUF_FORMAT` also cannot -be standalone, because :c:macro:`PyBUF_SIMPLE` is defined as zero, so it's equivalent -to :c:expr:`PyBUF_SIMPLE | PyBUF_FORMAT`. However, standalone :c:macro:`PyBUF_FORMAT` is not directly -disallowed by :c:func:`PyBuffer_FillInfo`, so it's possible to do this on some objects (for -example, :class:`bytes` supports this, but :class:`memoryview` does not). +: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). +Since :c:macro:`!PyBUF_SIMPLE` is defined as 0, :c:macro:`!PyBUF_FORMAT` cannot be +used as a stand-alone flag. shape, strides, suboffsets From 55dfc6bdead01686b0787573fca7d4a779eefacc Mon Sep 17 00:00:00 2001 From: ZeroIntensity Date: Sun, 8 Sep 2024 10:52:55 -0400 Subject: [PATCH 3/6] Try and make the message more user facing. --- Doc/c-api/buffer.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst index d6616ad984f6a4..09ecba6e7a44ce 100644 --- a/Doc/c-api/buffer.rst +++ b/Doc/c-api/buffer.rst @@ -265,10 +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). -Since :c:macro:`!PyBUF_SIMPLE` is defined as 0, :c:macro:`!PyBUF_FORMAT` cannot be -used as a stand-alone flag. +:c:macro:`PyBUF_FORMAT` can be \|'d to any of the flags except :c:macro:`PyBUF_SIMPLE`, because +the latter already implies format ``B`` (unsigned bytes). Likewise, :c:macro:`!PyBUF_FORMAT` cannot be +used on it's own: it must be \|'d to another flag. shape, strides, suboffsets From 3aac9bbf5d5441515ea4516d3066db0497f31f28 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Mon, 9 Sep 2024 08:09:55 -0400 Subject: [PATCH 4/6] Add example to the buffer request types paragraph. --- Doc/c-api/buffer.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst index 09ecba6e7a44ce..738057456de178 100644 --- a/Doc/c-api/buffer.rst +++ b/Doc/c-api/buffer.rst @@ -233,7 +233,8 @@ Buffer request types Buffers are usually obtained by sending a buffer request to an exporting object via :c:func:`PyObject_GetBuffer`. Since the complexity of the logical structure of the memory can vary drastically, the consumer uses the *flags* -argument to specify the exact buffer type it can handle. +argument to specify the exact buffer type it can handle. For example, :c:expr:`PyBUF_SIMPLE | PyBUF_WRITABLE` +can be used to request a simple writable buffer. All :c:type:`Py_buffer` fields are unambiguously defined by the request type. @@ -244,7 +245,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 ~~~~~~~~~~~~~~~~ From 6256646cafb9d860a3f757727dbf3b65c21445ff Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Mon, 9 Sep 2024 08:11:42 -0400 Subject: [PATCH 5/6] Update buffer.rst --- Doc/c-api/buffer.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst index 738057456de178..5eb4f5ad13dc19 100644 --- a/Doc/c-api/buffer.rst +++ b/Doc/c-api/buffer.rst @@ -233,8 +233,7 @@ Buffer request types Buffers are usually obtained by sending a buffer request to an exporting object via :c:func:`PyObject_GetBuffer`. Since the complexity of the logical structure of the memory can vary drastically, the consumer uses the *flags* -argument to specify the exact buffer type it can handle. For example, :c:expr:`PyBUF_SIMPLE | PyBUF_WRITABLE` -can be used to request a simple writable buffer. +argument to specify the exact buffer type it can handle. All :c:type:`Py_buffer` fields are unambiguously defined by the request type. @@ -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 From beee9850dfb4e637535d97f8da720ea382862d94 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Mon, 9 Sep 2024 11:16:35 -0400 Subject: [PATCH 6/6] Update buffer.rst Co-authored-by: Petr Viktorin --- Doc/c-api/buffer.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst index 5eb4f5ad13dc19..dc43a3d5fcb094 100644 --- a/Doc/c-api/buffer.rst +++ b/Doc/c-api/buffer.rst @@ -265,9 +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`, because -the latter already implies format ``B`` (unsigned bytes). Likewise, :c:macro:`!PyBUF_FORMAT` cannot be -used on it's own: it must be \|'d to another flag. +: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