buffer c-api: memoryview object documentation

[ash]

BPO	6659
Nosy	@birkenfeld, @pitrou, @benjaminp

^{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 = 'https://github.com/benjaminp'
closed_at = <Date 2009-08-26.07:36:12.270>
created_at = <Date 2009-08-06.12:07:34.611>
labels = ['docs']
title = 'buffer c-api: memoryview object documentation'
updated_at = <Date 2009-08-26.07:36:12.227>
user = 'https://bugs.python.org/ash'

bugs.python.org fields:

activity = <Date 2009-08-26.07:36:12.227>
actor = 'benjamin.peterson'
assignee = 'benjamin.peterson'
closed = True
closed_date = <Date 2009-08-26.07:36:12.270>
closer = 'benjamin.peterson'
components = ['Documentation']
creation = <Date 2009-08-06.12:07:34.611>
creator = 'ash'
dependencies = []
files = []
hgrepos = []
issue_num = 6659
keywords = []
message_count = 5.0
messages = ['91357', '91371', '91376', '91394', '91963']
nosy_count = 4.0
nosy_names = ['georg.brandl', 'pitrou', 'benjamin.peterson', 'ash']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue6659'
versions = ['Python 3.1', 'Python 3.2']

[ash]

"A memoryview object is an extended buffer object that could replace the
buffer object (but doesn’t have to as that could be kept as a simple 1-d
memoryview object)."

Well, buffer object was dropped Python 3, wasn't it?

http://docs.python.org/dev/py3k/c-api/buffer.html#memoryview-objects
http://docs.python.org/3.1/c-api/buffer.html#memoryview-objects

[birkenfeld]

Benjamin is listed as the section author.

[pitrou]

Well, the terminology in these docs is not very precise and helpful.
There are two things here:

• the buffer /struct/ a.k.a Py_buffer, which can only be used from C
  code and using the dedicated "new buffer API"
• the memoryview, which is a Python object (a PyObject *) wrapping a
  buffer struct; as a PyObject *, it can be used everywhere a regular
  Python object is expected (whether in C or in Python)

Then, as you point out, there's a third thing: the old "buffer" object
from Python 2.x; but it should not be mentioned at all in the 3.x docs,
since it's completely gone.

Endly... to be honest, I don't understand what the sentence you've
quoted is supposed to mean :-(, so I don't know how to correct it.

[ash]

Antoine, it seems, this sentence was taken literally from PEP-3118
(http://www.python.org/dev/peps/pep-3118/#new-c-api-calls-are-proposed).
PEP authors discussed if __builtins__.buffer should be removed.

I agree, old __builtins__.buffer should not be mentioned here at all.

I think, the best way to fix is to describe what is memoryview at the
C-level and properly document its C API. For example,
PyMemoryView_GetContiguous is not documented here at all (some
documentation is in header file - see memoryobject.h). I suggest
rewriting the whole section (see below).

Notes:

1. I haven't documented #define's from memoryview.h - do we need to?

2. I have renamed 'fort' to 'order'. It sounds much better now I
   think... Can we also change memoryview.h to use 'order'? I also want to
   rename 'obj' to 'buffer'. What do you think? It will simplify
   description of these functions...

3. I haven't documented 'buffertype'. Feel free to do so ;-) There's
   some text in PEP-3118, in memoryview.h and memoryview.c.

MemoryView objects
==================

PyMemoryViewObject is a subtype of PyObject representing Python
:class:`memoryview` object.

.. cfunction:: PyObject* PyMemoryView_FromObject(PyObject *obj)

Return a memoryview object from an object that defines the buffer
interface.

.. cfunction:: PyObject * PyMemoryView_GetContiguous(PyObject *obj, int
buffertype, char order)

Return a memoryview object to a contiguous chunk of memory (in either
'C' or 'F'ortran order) from an object that defines the buffer
interface. If memory is contiguous, the memoryview object points to the
original memory. Otherwise copy is made and the memoryview points to a
new bytes object.

[benjaminp]

Fixed in r74551.