classification
Title: Improve Memoryview/Buffer documentation
Type: behavior Stage: needs patch
Components: Documentation Versions: Python 3.1, Python 3.2, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: pitrou Nosy List: benjamin.peterson, cmcqueen1975, flox, georg.brandl, pitrou, r.david.murray, teoliphant, vstinner
Priority: normal Keywords:

Created on 2010-01-13 21:33 by flox, last changed 2010-10-24 15:57 by benjamin.peterson. This issue is now closed.

Messages (12)
msg97738 - (view) Author: Florent Xicluna (flox) * (Python committer) Date: 2010-01-13 21:33
Various notes while reading the Memoryview documentation:

 - “memoryviews allow Python code to access the internal data of an object that supports the buffer protocol without copying. Memory can be interpreted as simple bytes or complex data structures.” This is quite obscure because there's no definition of the "buffer protocol".

 - a link from 6.10 to the c-api/buffer.html page may be useful

 - the memoryview.suboffsets attribute is not documented on the "6.10 memoryview Type" page

 - there's no glossary entry for the "buffer protocol" (does it deserve an entry?)

 - "Memoryview" is title-cased in one case (c-api/buffer.html) but lowercased for the title of section 6.10 (stdtypes.html#memoryview-types)
msg102280 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2010-04-03 15:52
memoryview() function is not documented in library/functions.rst, whereas it's a builtin function.
msg102296 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2010-04-03 21:07
> This is quite obscure because there's no definition of the "buffer 
> protocol".

You can find it at http://www.python.org/dev/peps/pep-3118/#id5 (assuming it is not outdated)

> the memoryview.suboffsets attribute is not documented on the "6.10 
> memoryview Type" page

I don't know what it does.

By the way, I don't really know how to do links and glossary entries. I suppose someone else knows (and enjoys) ReST formatting better than I do.
msg102297 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2010-04-03 21:17
> memoryview() function is not documented in library/functions.rst

You should look more carefully...
See http://docs.python.org/dev/library/functions.html#max
(I don't know why it doesn't have its own anchor, though)
msg102340 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-04-04 13:33
> (I don't know why it doesn't have its own anchor, though)

Because that is only a link to the real description:

http://docs.python.org/dev/library/stdtypes.html#memoryview

And I think even you, Mr Potrou, could infer how to add glossary entries from one look at glossary.rst :)
msg110061 - (view) Author: Craig McQueen (cmcqueen1975) Date: 2010-07-12 01:04
The documentation implies that memoryview always accesses bytes:
* "len(view) returns the total number of bytes in the memoryview, view."
* "Taking a single index will return a single byte."

But, the following example shows this is misleading:

    >>> from array import array
    >>> ar = array('H', [1,2,3])
    >>> arv = memoryview(ar)
    >>> len(arv)
    3
    >>> arv[1]
    b'\x02\x00'
msg110062 - (view) Author: Craig McQueen (cmcqueen1975) Date: 2010-07-12 01:08
My previous comment was referring to Python 3.x, by the way. Python 2.7 has not implemented the buffer protocol for `array`.
msg110131 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2010-07-12 20:15
Craig, thanks for pointing it out. I've committed a patch to fix the doc. It should probably appear online soon.
msg110867 - (view) Author: Craig McQueen (cmcqueen1975) Date: 2010-07-20 05:19
I've seen the changes Mr Pitrou made, both for the 2.x and 3.x docs. That's a good improvement--thanks very much.
msg119486 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-10-24 05:17
Antoine, is there more that remains to be done on this, or can it be closed?
msg119520 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2010-10-24 15:44
> Antoine, is there more that remains to be done on this, or can it be closed?

I don't know really. I have done what I thought necessary on
memoryview/buffer maintenance, and I don't really want to go any
further.
msg119521 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2010-10-24 15:57
Let's close then.
History
Date User Action Args
2010-10-24 15:57:57benjamin.petersonsetstatus: open -> closed

nosy: + benjamin.peterson
messages: + msg119521

resolution: fixed
2010-10-24 15:44:13pitrousetmessages: + msg119520
2010-10-24 05:17:40r.david.murraysetnosy: + r.david.murray
messages: + msg119486
2010-07-20 05:19:56cmcqueen1975setmessages: + msg110867
2010-07-12 20:15:48pitrousetmessages: + msg110131
2010-07-12 11:25:29pitrousetassignee: teoliphant -> pitrou
2010-07-12 01:08:08cmcqueen1975setmessages: + msg110062
2010-07-12 01:04:55cmcqueen1975setnosy: + cmcqueen1975
messages: + msg110061
2010-04-04 13:33:41georg.brandlsetmessages: + msg102340
2010-04-03 21:17:14pitrousetmessages: + msg102297
2010-04-03 21:07:40pitrousetassignee: pitrou -> teoliphant

messages: + msg102296
nosy: + teoliphant
2010-04-03 15:52:05vstinnersetmessages: + msg102280
2010-04-02 08:41:01georg.brandlsetassignee: georg.brandl -> pitrou

nosy: + pitrou
2010-03-24 17:14:39floxsetpriority: normal
nosy: + vstinner

type: behavior
stage: needs patch
2010-03-24 17:14:02floxlinkissue8223 superseder
2010-01-13 21:33:50floxcreate