classification
Title: buffer c-api: memoryview object documentation
Type: Stage:
Components: Documentation Versions: Python 3.1, Python 3.2
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: benjamin.peterson Nosy List: ash, benjamin.peterson, georg.brandl, pitrou
Priority: normal Keywords:

Created on 2009-08-06 12:07 by ash, last changed 2009-08-26 07:36 by benjamin.peterson. This issue is now closed.

Messages (5)
msg91357 - (view) Author: Alexey Shamrin (ash) Date: 2009-08-06 12:07
"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
msg91371 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2009-08-06 17:45
Benjamin is listed as the section author.
msg91376 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2009-08-06 18:06
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.
msg91394 - (view) Author: Alexey Shamrin (ash) Date: 2009-08-07 08:03
Antoine, it seems, this sentence was taken literally from PEP3118
(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 PEP3118, 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.
msg91963 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2009-08-26 07:36
Fixed in r74551.
History
Date User Action Args
2009-08-26 07:36:12benjamin.petersonsetstatus: open -> closed
resolution: fixed
messages: + msg91963
2009-08-07 08:03:41ashsetmessages: + msg91394
2009-08-06 18:06:02pitrousetnosy: + pitrou
messages: + msg91376
2009-08-06 17:45:30georg.brandlsetassignee: georg.brandl -> benjamin.peterson

messages: + msg91371
nosy: + benjamin.peterson
2009-08-06 12:07:34ashcreate