Issue 33126: Some C buffer protocol APIs not documented

The following C functions are available for C code but not documented:
- PyBuffer_ToContiguous()
- PyBuffer_FromContiguous()
- PyObject_CopyData()

I am not sure how to describe those functions myself.

I fixed PyBuffer_ToContiguous() in 3.3, PyBuffer_FromContiguous() was broken until #23370.

For a start, here's a doc patch for PyBuffer_ToContiguous().

PyBuffer_FromContiguous() does the opposite and loads a contiguous buffer
into a possibly non-contiguous view.

PyObject_CopyData() copies the data from exporter src to the writable exporter dest.

I have never used the last two functions.

Thanks.  The PyBuffer_ToContiguous() API is weird: why pass `len` if it cannot be anything other than `src->len`?
Also, it would be nice to explain whether the actual buffer data is copied around (with a memory allocation?) or if it's just the Py_buffer struct.

Yes, the signatures are weird. In PyBuffer_FromContiguous(), "len" is
the size of "buf" in bytes.

If "buf" contains 6 floats, but "view" only has space for 4, then only
4 are copied into "view".


To avoid that sort of thing, I changed PyBuffer_ToContiguous() to
be more restrictive in 3.3, but kept the len parameter.

In PyBuffer_ToContiguous() it would not matter though if len(buf) > src->len, in which case buf would contain uninitialized bytes at
the end.


TBH, I don't think these functions are used very often. :-)

And if view->len > len in PyBuffer_FromContiguous(), then
view will contain uninitialized bytes, which is bad.

Ok, it seems only PyBuffer_ToContiguous() is worth documenting.

New changeset aa50bf08e64f49d57917ab0b1aadf4308a3168a6 by Antoine Pitrou in branch 'master':
bpo-33126: Document PyBuffer_ToContiguous() (#6292)
https://github.com/python/cpython/commit/aa50bf08e64f49d57917ab0b1aadf4308a3168a6

New changeset 18fdc87207ea65b3906f07cb47c51a609e442f93 by Antoine Pitrou (Miss Islington (bot)) in branch '3.6':
bpo-33126: Document PyBuffer_ToContiguous() (GH-6292) (GH-6293)
https://github.com/python/cpython/commit/18fdc87207ea65b3906f07cb47c51a609e442f93

New changeset 6124d8ec0d1eb8016e5e54a4d341b8f4f995623c by Antoine Pitrou (Miss Islington (bot)) in branch '3.7':
bpo-33126: Document PyBuffer_ToContiguous() (GH-6292) (GH-6294)
https://github.com/python/cpython/commit/6124d8ec0d1eb8016e5e54a4d341b8f4f995623c