[docs] [issue24278] Docs on Parsing arguments should say something about mem mgmt for formatters returning C strings

[Martin Panter]

Martin Panter added the comment:

This is my understanding of where the buffers would be managed and what governs their lifetimes, though I haven’t analyzed the code to verify:

s, z: str -> UTF-8 cache -> pointer for object lifetime
s*, z*: str -> UTF-8 cache -> buffer; bytes-like -> buffer; until release
y*: bytes-like -> buffer until release
S: bytes borrowed object
Y: bytearray borrowed object
u, u#, Z, Z#: str -> Py_UNICODE cache -> pointer for object lifetime
U: str borrowed object
w*: writable bytes-like -> buffer until release
es, es#: str -> encoded -> pointer until free (or pre-allocated for es#)
et, et#: str -> encoded -> pointer; bytes, bytearray -> pointer; until free (or pre-allocated for et#)

One open question that has worried me a bit is the “s#”, “z#”, “y”, “y#” codes, which are documented as requiring immutable bytes-like objects, but do not return a buffer structure. I guess this is designed for objects like bytes(), where the pointer would remain valid for the object’s lifetime, even if it has been released according to the buffer protocol. But how is this guaranteed for arbitrary buffer objects? Some undocumented requirement of the buffer’s “readonly” flag perhaps?

So I propose to add:

* Lifetime of all Py_buffer return values is until PyBuffer_Release() is called
* Unless otherwise documented, for conversions that return pointers to buffers, the buffer is managed or cached inside the Python object, and the lifetime of that buffer is the same as the whole Python object
* Unconverted Python objects are borrowed references
* For the four immutable bytes-like conversions I mentioned that return pointers, the buffer management and lifetime is not documented (unless somebody comes up with a better explanation)

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue24278>
_______________________________________