Buffer requests - `itemsize`, `format`, and `PyBUF_SIMPLE`

Documentation

I am trying to understand the full interaction between itemsize and format in the buffer requests documentation.

Q: If PyBuf_FORMAT is not set in the request, and shape is not NULL, is the real format unknown (real size specified by itemsize) or required to be "B" format?

To quote some pieces:

From itemsize:

Important exception: If a consumer requests a buffer without the PyBUF_FORMAT flag, format will be set to NULL, but itemsize still has the value for the original format.

If shape is NULL as a result of a PyBUF_SIMPLE or a PyBUF_WRITABLE request, the consumer must disregard itemsize and assume itemsize == 1.

From format:

A NULL terminated string in struct module style syntax describing the contents of a single item. If this is NULL, "B" (unsigned bytes) is assumed.

This seems to imply the following contradictory statements to me:

• From itemsize: If PyBUF_FORMAT is not set in the request, then the exporter must leave format as NULL. The original format is unknown to the requester, however itemsize must match the original format's size.
• From format: If PyBUF_FORMAT is not set in the request, then the exporter must leave format as NULL. The format is assumed to be "B" format.

Reading further, the docs also state

PyBUF_FORMAT must be |’d to any of the flags except PyBUF_SIMPLE, because the latter already implies format B (unsigned bytes). PyBUF_FORMAT cannot be used on its own.

It is unclear to me whether this means:

• All requests other than PyBUF_SIMPLE or PyBUF_WRITABLE must also set PyBUF_FORMAT, or
• PyBUF_FORMAT, PyBUF_SIMPLE | PyBUF_FORMAT and PyBUF_WRITABLE | PyBUF_FORMAT are disallowed combinations.

If PyBUF_FORMAT must always be set for nontrivial requests, I think a lot of my confusion above goes away, but the fact that the docs seem to allow for NULL format makes me think this is not the case. (Also compound requests such as PyBUF_STRIDED_RO do not set PyBUF_FORMAT.)

On the other hand, I don't see much technical justification for why standalone PyBUF_FORMAT (optionally in combination with PyBUF_SIMPLE or PyBUF_WRITABLE) would be forbidden. It seems reasonably clear to me that this would have to imply the exporter provides a 1D contiguous array where any format is allowed.

I found #123778 which made some changes in this direction, cc @encukou @ZeroIntensity

先从 C API 缓冲区文档中关于 itemsize、format、PyBUF_SIMPLE 和 PyBUF_FORMAT 的章节开始，然后阅读 issue #123778 以了解相关背景。完成的标准是：文档一致地解释 itemsize 和 format 的语义，并清晰标明有效和无效的标志组合。