[Numpy-svn] r4129 - trunk/numpy/doc

numpy-svn@scip... numpy-svn@scip...
Tue Sep 25 05:56:29 CDT 2007


Author: stefan
Date: 2007-09-25 05:56:04 -0500 (Tue, 25 Sep 2007)
New Revision: 4129

Modified:
   trunk/numpy/doc/pep_buffer.txt
Log:
ReST markup fixes.


Modified: trunk/numpy/doc/pep_buffer.txt
===================================================================
--- trunk/numpy/doc/pep_buffer.txt	2007-09-25 10:50:42 UTC (rev 4128)
+++ trunk/numpy/doc/pep_buffer.txt	2007-09-25 10:56:04 UTC (rev 4129)
@@ -16,17 +16,17 @@
 function pointers) to improve the way Python allows memory sharing
 in Python 3.0
 
-In particular, it is proposed that the character buffer portion 
-of the API be elminated and the multiple-segment portion be 
+In particular, it is proposed that the character buffer portion
+of the API be elminated and the multiple-segment portion be
 re-designed in conjunction with allowing for strided memory
-to be shared.   In addition, the new buffer interface will 
+to be shared.   In addition, the new buffer interface will
 allow the sharing of any multi-dimensional nature of the
-memory and what data-format the memory contains. 
+memory and what data-format the memory contains.
 
-This interface will allow any extension module to either 
+This interface will allow any extension module to either
 create objects that share memory or create algorithms that
-use and manipulate raw memory from arbitrary objects that 
-export the interface. 
+use and manipulate raw memory from arbitrary objects that
+export the interface.
 
 
 Rationale
@@ -39,7 +39,7 @@
 has issues:
 
 1. There is the little used "sequence-of-segments" option
-   (bf_getsegcount) that is not well motivated. 
+   (bf_getsegcount) that is not well motivated.
 
 2. There is the apparently redundant character-buffer option
    (bf_getcharbuffer)
@@ -62,36 +62,36 @@
    Libraries, ctypes, NumPy, data-base interfaces, etc.)
 
 6. There is no way to share discontiguous memory (except through
-   the sequence of segments notion).  
+   the sequence of segments notion).
 
    There are two widely used libraries that use the concept of
    discontiguous memory: PIL and NumPy.  Their view of discontiguous
    arrays is different, though.  The proposed buffer interface allows
-   sharing of either memory model.  Exporters will use only one        
-   approach and consumers may choose to support discontiguous 
-   arrays of each type however they choose. 
+   sharing of either memory model.  Exporters will use only one
+   approach and consumers may choose to support discontiguous
+   arrays of each type however they choose.
 
    NumPy uses the notion of constant striding in each dimension as its
    basic concept of an array. With this concept, a simple sub-region
-   of a larger array can be described without copying the data.   
+   of a larger array can be described without copying the data.
    Thus, stride information is the additional information that must be
-   shared. 
+   shared.
 
    The PIL uses a more opaque memory representation. Sometimes an
    image is contained in a contiguous segment of memory, but sometimes
    it is contained in an array of pointers to the contiguous segments
    (usually lines) of the image.  The PIL is where the idea of multiple
-   buffer segments in the original buffer interface came from.   
+   buffer segments in the original buffer interface came from.
 
    NumPy's strided memory model is used more often in computational
    libraries and because it is so simple it makes sense to support
-   memory sharing using this model.  The PIL memory model is sometimes 
+   memory sharing using this model.  The PIL memory model is sometimes
    used in C-code where a 2-d array can be then accessed using double
-   pointer indirection:  e.g. image[i][j].  
+   pointer indirection:  e.g. image[i][j].
 
    The buffer interface should allow the object to export either of these
    memory models.  Consumers are free to either require contiguous memory
-   or write code to handle one or both of these memory models. 
+   or write code to handle one or both of these memory models.
 
 Proposal Overview
 =================
@@ -102,7 +102,7 @@
 * Unify the read/write versions of getting the buffer.
 
 * Add a new function to the interface that should be called when
-  the consumer object is "done" with the memory area.  
+  the consumer object is "done" with the memory area.
 
 * Add a new variable to allow the interface to describe what is in
   memory (unifying what is currently done now in struct and
@@ -112,8 +112,8 @@
 
 * Add a new variable for sharing stride information
 
-* Add a new mechanism for sharing arrays that must 
-  be accessed using pointer indirection. 
+* Add a new mechanism for sharing arrays that must
+  be accessed using pointer indirection.
 
 * Fix all objects in the core and the standard library to conform
   to the new interface
@@ -121,10 +121,10 @@
 * Extend the struct module to handle more format specifiers
 
 * Extend the buffer object into a new memory object which places
-  a Python veneer around the buffer interface. 
+  a Python veneer around the buffer interface.
 
 * Add a few functions to make it easy to copy contiguous data
-  in and out of object supporting the buffer interface. 
+  in and out of object supporting the buffer interface.
 
 Specification
 =============
@@ -151,7 +151,7 @@
 
 ::
 
-    typedef int (*getbufferproc)(PyObject *obj, PyBuffer *view, int flags) 
+    typedef int (*getbufferproc)(PyObject *obj, PyBuffer *view, int flags)
 
 This function returns 0 on success and -1 on failure (and raises an
 error). The first variable is the "exporting" object.  The second
@@ -167,29 +167,29 @@
 
 The exporter can use this information to simplify how much of the PyBuffer
 structure is filled in and/or raise an error if the object can't support
-a simpler view of its memory. 
+a simpler view of its memory.
 
 Thus, the caller can request a simple "view" and either receive it or
 have an error raised if it is not possible.
 
 All of the following assume that at least buf, len, and readonly
-will always be utilized by the caller.  
+will always be utilized by the caller.
 
-Py_BUF_SIMPLE 
+Py_BUF_SIMPLE
 
    The returned buffer will be assumed to be readable (the object may
    or may not have writeable memory).  Only the buf, len, and readonly
    variables may be accessed. The format will be assumed to be
    unsigned bytes .  This is a "stand-alone" flag constant.  It never
-   needs to be |'d to the others.  The exporter will raise an 
-   error if it cannot provide such a contiguous buffer. 
+   needs to be \|'d to the others.  The exporter will raise an
+   error if it cannot provide such a contiguous buffer.
 
 Py_BUF_WRITEABLE
 
    The returned buffer must be writeable.  If it is not writeable,
    then raise an error.
 
-Py_BUF_READONLY 
+Py_BUF_READONLY
 
    The returned buffer must be readonly.  If the object is already
    read-only or it can make its memory read-only (and there are no
@@ -198,32 +198,32 @@
    (or cannot make it read-only), then an error should be raised.
 
 Py_BUF_FORMAT
-        
-   The returned buffer must have true format information.  This would 
+
+   The returned buffer must have true format information.  This would
    be used when the consumer is going to be checking for what 'kind'
    of data is actually stored.  An exporter should always be able
-   to provide this information if requested. 
+   to provide this information if requested.
 
-Py_BUF_SHAPE 
+Py_BUF_SHAPE
 
    The returned buffer must have shape information.  The memory will
    be assumed C-style contiguous (last dimension varies the fastest).
-   The exporter may raise an error if it cannot provide this kind 
-   of contiguous buffer. 
-   
-Py_BUF_STRIDES (implies Py_BUF_SHAPE) 
+   The exporter may raise an error if it cannot provide this kind
+   of contiguous buffer.
 
+Py_BUF_STRIDES (implies Py_BUF_SHAPE)
+
    The returned buffer must have strides information. This would be
-   used when the consumer can handle strided, discontiguous arrays. 
-   Handling strides automatically assumes you can handle shape. 
+   used when the consumer can handle strided, discontiguous arrays.
+   Handling strides automatically assumes you can handle shape.
    The exporter may raise an error if cannot provide a strided-only
-   representation of the data (i.e. without the suboffsets). 
+   representation of the data (i.e. without the suboffsets).
 
 Py_BUF_OFFSETS (implies Py_BUF_STRIDES)
 
    The returned buffer must have suboffsets information.  This would
    be used when the consumer can handle indirect array referencing
-   implied by these suboffsets.  
+   implied by these suboffsets.
 
 Py_BUF_FULL (Py_BUF_OFFSETS | Py_BUF_WRITEABLE | Py_BUF_FORMAT)
 
@@ -232,7 +232,7 @@
 how to make use of the most complicated cases could use Py_BUF_INDIRECT.
 
 If format information is going to be probed, then Py_BUF_FORMAT must
-be |'d to the flags otherwise the consumer assumes it is unsigned
+be \|'d to the flags otherwise the consumer assumes it is unsigned
 bytes.
 
 There is a C-API that simple exporting objects can use to fill-in the
@@ -268,7 +268,7 @@
 buf
     a pointer to the start of the memory for the object
 
-len 
+len
     the total bytes of memory the object uses.  This should be the
     same as the product of the shape array multiplied by the number of
     bytes per item of memory.
@@ -278,7 +278,7 @@
     readonly.  1 means the memory is readonly, zero means the
     memory is writeable.
 
-format 
+format
     a NULL-terminated format-string (following the struct-style syntax
     including extensions) indicating what is in each element of
     memory.  The number of elements is len / itemsize, where itemsize
@@ -287,7 +287,7 @@
 
 ndims
     a variable storing the number of dimensions the memory represents.
-    Must be >=0. 
+    Must be >=0.
 
 shape
     an array of ``Py_ssize_t`` of length ``ndims`` indicating the
@@ -295,7 +295,7 @@
     ... * (*shape)[ndims-1])*itemsize = len``.  If ndims is 0 (indicating
     a scalar), then this must be NULL.
 
-strides 
+strides
     address of a ``Py_ssize_t*`` variable that will be filled with a
     pointer to an array of ``Py_ssize_t`` of length ``ndims`` (or NULL
     if ndims is 0).  indicating the number of bytes to skip to get to
@@ -314,7 +314,7 @@
     indicated dimension is a pointer and the suboffset value dictates
     how many bytes to add to the pointer after de-referencing.  A
     suboffset value that it negative indicates that no de-referencing
-    should occur (striding in a contiguous memory block).  If all 
+    should occur (striding in a contiguous memory block).  If all
     suboffsets are negative (i.e. no de-referencing is needed, then
     this must be NULL.
 
@@ -339,22 +339,22 @@
     Thus slicing in the ith dimension would add to the suboffsets in
     the (i-1)st dimension.  Slicing in the first dimension would change
     the location of the starting pointer directly (i.e. buf would
-    be modified).  
+    be modified).
 
 itemsize
     This is a storage for the itemsize of each element of the shared
     memory.  It can be obtained using PyBuffer_SizeFromFormat but an
     exporter may know it without making this call and thus storing it
-    is more convenient and faster. 
+    is more convenient and faster.
 
 internal
     This is for use internally by the exporting object.  For example,
-    this might be re-cast as an integer by the exporter and used to 
+    this might be re-cast as an integer by the exporter and used to
     store flags about whether or not the shape, strides, and suboffsets
     arrays must be freed when the buffer is released.   The consumer
-    should never touch this value. 
-    
+    should never touch this value.
 
+
 The exporter is responsible for making sure the memory pointed to by
 buf, format, shape, strides, and suboffsets is valid until
 releasebuffer is called.  If the exporter wants to be able to change
@@ -366,7 +366,7 @@
 
 The same bufferinfo struct should be used in the release-buffer
 interface call. The caller is responsible for the memory of the
-bufferinfo structure itself. 
+bufferinfo structure itself.
 
 ``typedef int (*releasebufferproc)(PyObject *obj, PyBuffer *view)``
     Callers of getbufferproc must make sure that this function is
@@ -378,8 +378,8 @@
     Both of these routines are optional for a type object
 
     If the releasebuffer function is not provided then it does not ever
-    need to be called. 
-    
+    need to be called.
+
 Exporters will need to define a releasebuffer function if they can
 re-allocate their memory, strides, shape, suboffsets, or format
 variables which they might share through the struct bufferinfo.
@@ -387,7 +387,7 @@
 calls have been made and shared.  Either a single variable could be
 used to keep track of how many "views" have been exported, or a
 linked-list of bufferinfo structures filled in could be maintained in
-each object.  
+each object.
 
 All that is specifically required by the exporter, however, is to
 ensure that any memory shared through the bufferinfo structure remains
@@ -405,8 +405,8 @@
 
 ::
 
-    int PyObject_GetBuffer(PyObject *obj, PyBuffer *view, 
-                           int flags)  
+    int PyObject_GetBuffer(PyObject *obj, PyBuffer *view,
+                           int flags)
 
 This is a C-API version of the getbuffer function call.  It checks to
 make sure object has the required function pointer and issues the
@@ -414,6 +414,7 @@
 success.
 
 ::
+
     int PyObject_ReleaseBuffer(PyObject *obj, PyBuffer *view)
 
 This is a C-API version of the releasebuffer function call.  It checks
@@ -435,7 +436,7 @@
 
   typedef struct {
       PyObject_HEAD
-      PyObject *base;      
+      PyObject *base;
       int ndims;
       Py_ssize_t *starts;  /* slice starts */
       Py_ssize_t *stops;   /* slice stops */
@@ -444,12 +445,12 @@
 
 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 needed. 
+re-grabbed using the buffer-protocol, whenever it is needed.
 
 The getbuffer and releasebuffer for this object use the underlying
 base object (adjusted 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. 
+when a new view is requested, then the getbuffer will trigger an error.
 
 This memory-view object will support mult-dimensional slicing.  Slices
 of the memory-view object are other memory-view objects. When an
@@ -478,9 +479,9 @@
 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.  
+efficient.
 
-:: 
+::
 
     int PyObject_CopyToObject(PyObject *obj, void *buf, Py_ssize_t len,
                               char fortran)
@@ -509,7 +510,7 @@
 These last three C-API calls allow a standard way of getting data in and
 out of Python objects into contiguous memory areas no matter how it is
 actually stored.  These calls use the extended buffer interface to perform
-their work. 
+their work.
 
 ::
 
@@ -521,7 +522,7 @@
 ::
 
     void PyBuffer_FillContiguousStrides(int *ndims, Py_ssize_t *shape,
-                                        int itemsize, 
+                                        int itemsize,
                                         Py_ssize_t *strides, char fortran)
 
 Fill the strides array with byte-strides of a contiguous (C-style if
@@ -529,13 +530,14 @@
 shape with the given number of bytes per element.
 
 ::
-    int PyBuffer_FillInfo(PyBuffer *view, void *buf, 
+
+    int PyBuffer_FillInfo(PyBuffer *view, void *buf,
                           Py_ssize_t len, int readonly, int infoflags)
 
 Fills in a buffer-info structure correctly for an exporter that can
 only share a contiguous chunk of memory of "unsigned bytes" of the
 given length.  Returns 0 on success and -1 (with raising an error) on
-error. 
+error.
 
 
 Additions to the struct string-syntax
@@ -543,7 +545,7 @@
 
 The struct string-syntax is missing some characters to fully
 implement data-format descriptions already available elsewhere (in
-ctypes and NumPy for example).  The Python 2.5 specification is 
+ctypes and NumPy for example).  The Python 2.5 specification is
 at http://docs.python.org/lib/module-struct.html
 
 Here are the proposed additions:
@@ -554,19 +556,19 @@
 ================  ===========
 't'               bit (number before states how many bits)
 '?'               platform _Bool type
-'g'               long double  
-'c'               ucs-1 (latin-1) encoding 
-'u'               ucs-2 
-'w'               ucs-4 
-'O'               pointer to Python Object 
+'g'               long double
+'c'               ucs-1 (latin-1) encoding
+'u'               ucs-2
+'w'               ucs-4
+'O'               pointer to Python Object
 'Z'               complex (whatever the next specifier is)
-'&'               specific pointer (prefix before another charater) 
-'T{}'             structure (detailed layout inside {}) 
-'(k1,k2,...,kn)'  multi-dimensional array of whatever follows 
-':name:'          optional name of the preceeding element 
-'X{}'             pointer to a function (optional function 
+'&'               specific pointer (prefix before another charater)
+'T{}'             structure (detailed layout inside {})
+'(k1,k2,...,kn)'  multi-dimensional array of whatever follows
+':name:'          optional name of the preceeding element
+'X{}'             pointer to a function (optional function
                                          signature inside {})
-' \n\t'           ignored (allow better readability) 
+' \n\t'           ignored (allow better readability)
                              -- this may already be true
 ================  ===========
 
@@ -588,7 +590,7 @@
 previously-specified endian string is in force until changed.  The
 default endian is '@' which means native data-types and alignment.  If
 un-aligned, native data-types are requested, then the endian
-specification is '^'.  
+specification is '^'.
 
 According to the struct-module, a number can preceed a character
 code to specify how many of that type there are.  The
@@ -603,7 +605,7 @@
 ====================================
 
 Here are some examples of C-structures and how they would be
-represented using the struct-style syntax. 
+represented using the struct-style syntax.
 
 <named> is the constructor for a named-tuple (not-specified yet).
 
@@ -614,7 +616,7 @@
 RGB Pixel data
     'BBB' <--> (int, int, int)
     'B:r: B:g: B:b:' <--> <named>((int, int, int), ('r','g','b'))
-    
+
 Mixed endian (weird but possible)
     '>i:big: <i:little:' <--> <named>((int, int), ('big', 'little'))
 
@@ -629,10 +631,10 @@
                  unsigned char cval;
              } sub;
         }
-        """i:ival: 
+        """i:ival:
            T{
-              H:sval: 
-              B:bval: 
+              H:sval:
+              B:bval:
               B:cval:
             }:sub:
         """
@@ -643,7 +645,7 @@
              int ival;
              double data[16*4];
         }
-        """i:ival: 
+        """i:ival:
            (16,4)d:data:
         """
 
@@ -662,7 +664,7 @@
 * mmap module
 * ctypes module
 
-Anything else using the buffer API.  
+Anything else using the buffer API.
 
 
 Issues and Details
@@ -692,9 +694,9 @@
 Memory management of the format string, the shape array, the strides
 array, and the suboffsets array in the bufferinfo structure is always
 the responsibility of the exporting object.  The consumer should not
-set these pointers to any other memory or try to free them. 
+set these pointers to any other memory or try to free them.
 
-Several ideas were discussed and rejected: 
+Several ideas were discussed and rejected:
 
     Having a "releaser" object whose release-buffer was called.  This
     was deemed unacceptable because it caused the protocol to be
@@ -706,7 +708,7 @@
     This had the advantage that it allowed one to set NULL to
     variables that were not of interest, but it also made the function
     call more difficult.  The flags variable allows the same
-    ability of consumers to be "simple" in how they call the protocol. 
+    ability of consumers to be "simple" in how they call the protocol.
 
 Code
 ========
@@ -723,7 +725,7 @@
 Ex. 1
 -----------
 
-This example shows how an image object that uses contiguous lines might expose its buffer.::
+This example shows how an image object that uses contiguous lines might expose its buffer.
 
 ::
 
@@ -749,8 +751,6 @@
 
 So what does ImageObject's getbuffer do?  Leaving error checking out::
 
-::
-
   int Image_getbuffer(PyObject *self, PyBuffer *view, int flags) {
 
       static Py_ssize_t suboffsets[2] = { -1, 0 };
@@ -762,7 +762,7 @@
       self->shape_array[0] = height;
       self->shape_array[1] = width;
       view->shape = &self->shape_array;
-      self->stride_array[0] = sizeof(struct rgba*);  
+      self->stride_array[0] = sizeof(struct rgba*);
       self->stride_array[1] = sizeof(struct rgba);
       view->strides = &self->stride_array;
       view->suboffsets = suboffsets;
@@ -770,7 +770,7 @@
       self->view_count ++;
 
       return 0;
-  } 
+  }
 
 
   int Image_releasebuffer(PyObject *self, PyBuffer *view) {
@@ -793,17 +793,16 @@
       void *buf;
       Py_ssize_t len;
       int readonly=0;
-        
+
       buf = /* Point to buffer */
       len = /* Set to size of buffer */
       readonly = /* Set to 1 if readonly */
-  
-      return PyObject_FillBufferInfo(view, buf, len, readonly, flags);    
+
+      return PyObject_FillBufferInfo(view, buf, len, readonly, flags);
   }
 
-/* No releasebuffer is necessary because the memory will never 
-be re-allocated so the locking mechanism is not needed
-*/
+No releasebuffer is necessary because the memory will never
+be re-allocated so the locking mechanism is not needed.
 
 Ex.  3
 -----------
@@ -815,7 +814,7 @@
 
   PyBuffer view;
   int ret;
-      
+
   if (PyObject_GetBuffer(obj, &view, Py_BUF_SIMPLE) < 0) {
        /* error return */
   }
@@ -824,15 +823,15 @@
           view.len is the length
           view.readonly is whether or not the memory is read-only.
    */
-  
 
+
   /* After using the information and you don't need it anymore */
-  
+
   if (PyObject_ReleaseBuffer(obj, &view) < 0) {
           /* error return */
   }
-  
 
+
 Ex. 4
 -----------
 
@@ -851,21 +850,20 @@
 
     /* process memory pointed to by buffer if format is correct */
 
-    /* Optional: 
-    
+    /* Optional:
+
        if, after processing, we want to copy data from buffer back
-       into the the object  
- 
+       into the the object
+
        we could do
        */
 
     if (PyObject_CopyToObject(obj, buf, len, 0) < 0) {
            /*        error return */
     }
-   
 
+
 Copyright
 =========
 
 This PEP is placed in the public domain
-



More information about the Numpy-svn mailing list