[Python-checkins] r56891 - peps/trunk/pep-3118.txt

[travis.oliphant]

Author: travis.oliphant
Date: Fri Aug 10 09:54:25 2007
New Revision: 56891

Modified:
   peps/trunk/pep-3118.txt
Log:
Changes to MemoryViewObject portion of PEP 3118 to reflect code.

Modified: peps/trunk/pep-3118.txt
==============================================================================
--- peps/trunk/pep-3118.txt	(original)
+++ peps/trunk/pep-3118.txt	Fri Aug 10 09:54:25 2007
@@ -156,7 +156,7 @@
 argument is the address to a bufferinfo structure.  If view is ``NULL``,
 then no information is returned but a lock on the memory is still
 obtained.  In this case, the corresponding releasebuffer should also
-be called with ``NULL``.
+be called with ``NULL``.  
 
 The third argument indicates what kind of buffer the consumer is
 prepared to deal with and therefore what kind of buffer the exporter
@@ -490,46 +490,42 @@
   typedef struct {
       PyObject_HEAD
       PyObject *base;
-      int ndims;
-      Py_ssize_t *starts;  /* slice starts */
-      Py_ssize_t *stops;   /* slice stops */
-      Py_ssize_t *steps;   /* slice steps */
+      PyBuffer view;
   } PyMemoryViewObject;
 
-This is functionally similar to the current buffer object except only
-a reference to base is kept.  The actual memory for base must be
-re-grabbed using the buffer-protocol, whenever it is actually
-needed (after which it is immediately released). 
-
-The getbuffer and releasebuffer for this object use the underlying
-base object (adjusted as needed using the slice information).  If the
-number of dimensions of the base object (or the strides or the size)
-has changed when a new view is requested, then the getbuffer will
-trigger an error.  Methods on the MemoryView object will allow
-manual locking and unlocking of the underlying buffer. 
+This is functionally similar to the current buffer object except a
+reference to base is kept and the memory view is not re-grabbed.
+Thus, this memory view object holds on to the memory of base until it
+is deleted.
+
+The getbuffer and releasebuffer for this object increments and
+decrements the lock on base, but passes on the contents of view to the
+caller.
 
-This memory-view object will support mult-dimensional slicing and be
+This memory-view object will support multi-dimensional slicing and be
 the first object provided with Python to do so.  Slices of the
-memory-view object are other memory-view objects. When an "element"
-from the memory-view is returned it is always a bytes object whose
-format should be interpreted by the format attribute of the memoryview
-object.  The struct module can be used to "decode" the bytes in Python
-if desired.
+memory-view object are other memory-view objects with the same base
+but with a different view of the base object.
+
+When an "element" from the memory-view is returned it is always a
+bytes object whose format should be interpreted by the format
+attribute of the memoryview object.  The struct module can be used to
+"decode" the bytes in Python if desired.  Or the contents can be
+passed to a NumPy array or other object consuming the buffer protocol.
 
 The Python name will be 
 
-``__builtin__.memory``
+``__builtin__.memoryview``
 
 Methods:
 
-|  ``lock``
-|  ``unlock``
 |  ``__getitem__``  (will support multi-dimensional slicing)
 |  ``__setitem__``  (will support multi-dimensional slicing)  
-|  ``tobytes``      (obtain a bytes-object of everything in the memory).
+|  ``tobytes``      (obtain a new bytes-object of a copy of the memory).
 |  ``tolist``       (obtain a "nested" list of the memory.  Everything
                     is interpreted into standard Python objects
-                    as the struct module unpack would do). 
+                    as the struct module unpack would do -- in fact
+                    it uses struct.unpack to accomplish it). 
 
 Attributes (taken from the memory of the base object):
 
@@ -552,25 +548,36 @@
 
 ::
 
-    int PyObject_GetContiguous(PyObject *obj, void **buf, Py_ssize_t *len,
-                               char **format, int writeable, char fortran)
-
-Return a contiguous chunk of memory representing the buffer.  If a
-copy is made then return 1.  If no copy was needed return 0.  If an
-error occurred in probing the buffer interface, then return -1.  The
-contiguous chunk of memory is pointed to by ``*buf`` and the length of
-that memory is ``*len``.  If writeable is 1, then the returned memory
-must be writeable or else an error is raised. Otherwise, the memory
-may or may not be writeable.  If the object is multi-dimensional, then
-if fortran is 'F', the first dimension of the underlying array will
-vary the fastest in the buffer.  If fortran is 'C', then the last
-dimension will vary the fastest (C-style contiguous). If fortran is
-'A', then it does not matter and you will get whatever the object
-decides is more efficient.  If a copy is made, then the memory must be
-freed by calling ``PyMem_Free``.
+    PyObject * PyMemoryView_GetContiguous(PyObject *obj,  int buffertype, 
+                                          char fort)
 
-PyObject_ReleaseBuffer must be called on obj after you are done with the
-memory even if a copy is made. 
+Return a memoryview object to a contiguous chunk of memory represented
+by obj. If a copy must be made (because the memory pointed to by obj
+is not contiguous), then a new bytes object will be created and become
+the base object for the returned memory view object. 
+
+The buffertype argument can be PyBUF_READ, PyBUF_WRITE,
+PyBUF_UPDATEIFCOPY to determine whether the returned buffer should be
+READONLY, WRITEABLE, or set to update the original buffer if a copy
+must be made.  If buffertype is PyBUF_WRITE and the buffer is not
+contiguous an error will be raised.  In this circumstance, the user
+can use PyBUF_UPDATEIFCOPY to ensure that a a writeable temporary
+contiguous buffer is returned.  The contents of this contiguous buffer
+will be copied back into the original object after the memoryview
+object is deleted as long as the original object is writeable and
+allows setting its memory to "readonly".  If this is not allowed by
+the original object, then a BufferError is raised.
+
+If the object is multi-dimensional, then if fortran is 'F', the first
+dimension of the underlying array will vary the fastest in the buffer.
+If fortran is 'C', then the last dimension will vary the fastest
+(C-style contiguous). If fortran is 'A', then it does not matter and
+you will get whatever the object decides is more efficient.  If a copy
+is made, then the memory must be freed by calling ``PyMem_Free``.
+
+You receive a new reference to the memoryview object which will also
+hold a lock on the objects data area (this lock will be released when
+the memoryview object is deleted).
 
 ::