From 1b25b9284f111f23167837347f35e393572e770e Mon Sep 17 00:00:00 2001
From: Benjamin Peterson <benjamin@python.org>
Date: Tue, 9 Sep 2008 22:15:27 +0000
Subject: [PATCH] document the memoryview object a little

---
 Doc/library/functions.rst |  5 +--
 Doc/library/stdtypes.rst  | 91 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 93 insertions(+), 3 deletions(-)

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index aa60be9b657..252ef02ebf9 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -665,9 +665,8 @@ are always available.  They are listed here in alphabetical order.
 
 .. 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])
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 685dd2b2bba..3eb59d99de8 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -2231,6 +2231,97 @@ the particular object.
    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