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

Start with the C API buffer documentation sections on itemsize, format, PyBUF_SIMPLE, and PyBUF_FORMAT, then read issue #123778 for related context. Done means the documentation consistently explains itemsize and format semantics and clearly identifies valid and invalid flag combinations.