classification
Title: Some C buffer protocol APIs not documented
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, pitrou, skrah
Priority: normal Keywords: patch

Created on 2018-03-23 16:49 by pitrou, last changed 2018-03-28 15:50 by pitrou. This issue is now closed.

Files
File name Uploaded Description Edit
issue33126.diff skrah, 2018-03-24 21:53
Pull Requests
URL Status Linked Edit
PR 6292 merged pitrou, 2018-03-28 15:04
PR 6293 merged miss-islington, 2018-03-28 15:27
PR 6294 merged miss-islington, 2018-03-28 15:29
Messages (9)
msg314315 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2018-03-23 16:49
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.
msg314387 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2018-03-24 21:53
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.
msg314388 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2018-03-24 22:37
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.
msg314424 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2018-03-25 18:18
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. :-)
msg314425 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2018-03-25 18:32
And if view->len > len in PyBuffer_FromContiguous(), then
view will contain uninitialized bytes, which is bad.
msg314605 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2018-03-28 15:04
Ok, it seems only PyBuffer_ToContiguous() is worth documenting.
msg314608 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2018-03-28 15:26
New changeset aa50bf08e64f49d57917ab0b1aadf4308a3168a6 by Antoine Pitrou in branch 'master':
bpo-33126: Document PyBuffer_ToContiguous() (#6292)
https://github.com/python/cpython/commit/aa50bf08e64f49d57917ab0b1aadf4308a3168a6
msg314611 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2018-03-28 15:47
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
msg314612 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2018-03-28 15:50
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
History
Date User Action Args
2018-03-28 15:50:58pitrousetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2018-03-28 15:50:27pitrousetmessages: + msg314612
2018-03-28 15:47:36pitrousetmessages: + msg314611
2018-03-28 15:29:01miss-islingtonsetpull_requests: + pull_request6018
2018-03-28 15:27:55miss-islingtonsetpull_requests: + pull_request6017
2018-03-28 15:26:37pitrousetmessages: + msg314608
2018-03-28 15:04:53pitrousetmessages: + msg314605
2018-03-28 15:04:27pitrousetstage: needs patch -> patch review
pull_requests: + pull_request6016
2018-03-25 18:32:25skrahsetmessages: + msg314425
2018-03-25 18:18:51skrahsetmessages: + msg314424
2018-03-24 22:37:54pitrousetmessages: + msg314388
2018-03-24 21:53:19skrahsetfiles: + issue33126.diff
keywords: + patch
messages: + msg314387
2018-03-23 16:49:06pitroucreate