Some C buffer protocol APIs not documented

[pitrou]

BPO	33126
Nosy	@pitrou, @skrah
PRs	bpo-33126: Document PyBuffer_ToContiguous() #6292 [3.6] bpo-33126: Document PyBuffer_ToContiguous() (GH-6292) #6293 [3.7] bpo-33126: Document PyBuffer_ToContiguous() (GH-6292) #6294
Files	issue33126.diff

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2018-03-28.15:50:58.906>
created_at = <Date 2018-03-23.16:49:06.181>
labels = ['3.8', 'type-bug', '3.7', 'docs']
title = 'Some C buffer protocol APIs not documented'
updated_at = <Date 2018-03-28.15:50:58.905>
user = 'https://github.com/pitrou'

bugs.python.org fields:

activity = <Date 2018-03-28.15:50:58.905>
actor = 'pitrou'
assignee = 'docs@python'
closed = True
closed_date = <Date 2018-03-28.15:50:58.906>
closer = 'pitrou'
components = ['Documentation']
creation = <Date 2018-03-23.16:49:06.181>
creator = 'pitrou'
dependencies = []
files = ['47497']
hgrepos = []
issue_num = 33126
keywords = ['patch']
message_count = 9.0
messages = ['314315', '314387', '314388', '314424', '314425', '314605', '314608', '314611', '314612']
nosy_count = 3.0
nosy_names = ['pitrou', 'skrah', 'docs@python']
pr_nums = ['6292', '6293', '6294']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue33126'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8']

[pitrou]

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.

[skrah]

I fixed PyBuffer_ToContiguous() in 3.3, PyBuffer_FromContiguous() was broken until bpo-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.

[pitrou]

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.

[skrah]

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. :-)

[skrah]

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

[pitrou]

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

[pitrou]

New changeset aa50bf0 by Antoine Pitrou in branch 'master':
bpo-33126: Document PyBuffer_ToContiguous() (bpo-6292)
aa50bf0

[pitrou]

New changeset 18fdc87 by Antoine Pitrou (Miss Islington (bot)) in branch '3.6':
bpo-33126: Document PyBuffer_ToContiguous() (GH-6292) (GH-6293)
18fdc87

[pitrou]

New changeset 6124d8e by Antoine Pitrou (Miss Islington (bot)) in branch '3.7':
bpo-33126: Document PyBuffer_ToContiguous() (GH-6292) (GH-6294)
6124d8e