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
Documentation
I am trying to understand the full interaction between
itemsizeandformatin the buffer requests documentation.Q: If
PyBuf_FORMATis not set in the request, andshapeis not NULL, is the real format unknown (real size specified byitemsize) or required to be"B"format?To quote some pieces:
From itemsize:
From format:
This seems to imply the following contradictory statements to me:
PyBUF_FORMATis not set in the request, then the exporter must leaveformatasNULL. The original format is unknown to the requester, howeveritemsizemust match the original format's size.PyBUF_FORMATis not set in the request, then the exporter must leaveformatasNULL. The format is assumed to be"B"format.Reading further, the docs also state
It is unclear to me whether this means:
PyBUF_SIMPLEorPyBUF_WRITABLEmust also setPyBUF_FORMAT, orPyBUF_FORMAT,PyBUF_SIMPLE | PyBUF_FORMATandPyBUF_WRITABLE | PyBUF_FORMATare disallowed combinations.If
PyBUF_FORMATmust 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 asPyBUF_STRIDED_ROdo not setPyBUF_FORMAT.)On the other hand, I don't see much technical justification for why standalone
PyBUF_FORMAT(optionally in combination withPyBUF_SIMPLEorPyBUF_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