[Python-3000-checkins] r66357 - in python/branches/py3k/Doc/library: functions.rst stdtypes.rst

[benjamin.peterson]

Author: benjamin.peterson
Date: Wed Sep 10 00:15:27 2008
New Revision: 66357

Log:
document the memoryview object a little

Modified:
   python/branches/py3k/Doc/library/functions.rst
   python/branches/py3k/Doc/library/stdtypes.rst

Modified: python/branches/py3k/Doc/library/functions.rst
==============================================================================
--- python/branches/py3k/Doc/library/functions.rst	(original)
+++ python/branches/py3k/Doc/library/functions.rst	Wed Sep 10 00:15:27 2008
@@ -665,9 +665,8 @@
 
 .. function:: memoryview(obj)
 
-   Return a "memory view" object created from the given argument.
-   
-   XXX: To be documented.
+   Return a "memory view" object created from the given argument.  See
+   :ref:`typememoryview` for more information.
 
 
 .. function:: min(iterable[, args...], *[, key])

Modified: python/branches/py3k/Doc/library/stdtypes.rst
==============================================================================
--- python/branches/py3k/Doc/library/stdtypes.rst	(original)
+++ python/branches/py3k/Doc/library/stdtypes.rst	Wed Sep 10 00:15:27 2008
@@ -2231,6 +2231,97 @@
    mode the value of this attribute will be ``None``.
 
 
+.. _typememoryview:
+
+memoryview Types
+================
+
+:class:`memoryview`\s allow Python code to access the internal data of an object
+that supports the buffer protocol.  Memory can be interpreted as simple bytes or
+complex data structures.
+
+.. class:: memoryview(obj)
+
+   Create a :class:`memoryview`\s that references *obj*.  *obj* must support the
+   buffer protocol.  Builtin objects that support the buffer protocol include
+   :class:`bytes` and :class:`bytearray`.
+
+   A :class:`memoryview`\s supports slicing to expose its data.  Taking a single
+   index will return a single byte.  Full slicing will result in a subview/ ::
+
+      >>> v = memoryview(b'abcefg')
+      >>> v[1]
+      b'b'
+      >>> v[-1]
+      b'g'
+      >>> v[1:4]
+      <memory at 0x77ab28>
+      >>> bytes(v[1:4])
+      b'bce'
+      >>> v[3:-1]
+      <memory at 0x744f18>
+      >>> bytes(v[4:-1])
+
+   If the object the memoryview is over supports changing it's data, the
+   memoryview supports slice assignment. ::
+
+      >>> data = bytearray(b'abcefg')
+      >>> v = memoryview(data)
+      >>> v.readonly
+      False
+      >>> v[0] = 'z'
+      >>> data
+      bytearray(b'zbcefg')
+      >>> v[1:4] = b'123'
+      >>> data
+      bytearray(b'a123fg')
+      >>> v[2] = b'spam'
+      Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+      ValueError: cannot modify size of memoryview object
+
+   Notice how the size of the memoryview object can not be changed.
+
+
+   :class:`memoryview` has one method:
+
+   .. method:: tobytes()
+
+      Convert the data in the buffer to a bytestring and return it.
+
+   There are also several readonly attributes available:
+
+   .. attribute:: format
+
+      A string containing the format (in :mod:`struct` module style) for each
+      element in the view.  This defaults to ``'B'``, a simple bytestring.
+
+   .. attribute:: itemsize
+
+      The size in bytes of each element of the memoryview.
+
+   .. attribute:: shape
+
+      A tuple of integers the length of :attr:`~memoryview.ndim` giving the
+      shape of the memory as a N-dimensional array.
+
+   .. attribute:: ndim
+
+      An integer indicating how many dimensions of a multi-dimensional array the
+      memory represents.
+
+   .. attribute:: strides
+
+      A tuple of integers the length of :attr:`~memoryview.ndim` giving the size
+      in bytes to access each element for each dimension of the array.
+
+   .. attribute:: size
+
+      The number of bytes in the buffer.  Also available as ``len(view)``.
+
+   .. memoryview.suboffsets isn't documented because it only seems useful for C
+
+
 .. _typecontextmanager:
 
 Context Manager Types