Since I edited this file, reformat for future edits.

Doc/c-api/buffer.rst

@@ -14,9 +14,10 @@ Buffers and Memoryview Objects
    single: buffer interface
 
 Python objects implemented in C can export a group of functions called the
-"buffer interface."  These functions can be used by an object to expose its data
+"buffer interface."  These functions can be used by an object to expose its
-in a raw, byte-oriented format. Clients of the object can use the buffer
+data in a raw, byte-oriented format. Clients of the object can use the buffer
-interface to access the object data directly, without needing to copy it first.
+interface to access the object data directly, without needing to copy it
+first.
 
 Two examples of objects that support the buffer interface are strings and
 arrays. The string object exposes the character contents in the buffer
@@ -30,10 +31,10 @@ interface can be written to a file. There are a number of format codes to
 returning data from the target object.
 
 Starting from version 1.6, Python has been providing Python-level buffer
-objects and a C-level buffer API so that any builtin or used-defined type
+objects and a C-level buffer API so that any builtin or used-defined type can
-can expose its characteristics. Both, however, have been deprecated because
+expose its characteristics. Both, however, have been deprecated because of
-of various shortcomings, and have been officially removed in Python 3.0 in
+various shortcomings, and have been officially removed in Python 3.0 in favour
-favour of a new C-level buffer API and a new Python-level object named
+of a new C-level buffer API and a new Python-level object named
 :class:`memoryview`.
 
 The new buffer API has been backported to Python 2.6, and the
@@ -64,9 +65,9 @@ The new-style Py_buffer struct
    .. cmember:: const char *format
       :noindex:
 
-      A *NULL* terminated string in :mod:`struct` module style syntax giving the
+      A *NULL* terminated string in :mod:`struct` module style syntax giving
-      contents of the elements available through the buffer.  If this is *NULL*,
+      the contents of the elements available through the buffer.  If this is
-      ``"B"`` (unsigned bytes) is assumed.
+      *NULL*, ``"B"`` (unsigned bytes) is assumed.
 
    .. cmember:: int ndim
 
@@ -116,11 +117,11 @@ The new-style Py_buffer struct
    .. cmember:: Py_ssize_t itemsize
 
       This is a storage for the itemsize (in bytes) of each element of the
-      shared memory. It is technically un-necessary as it can be obtained using
+      shared memory. It is technically un-necessary as it can be obtained
-      :cfunc:`PyBuffer_SizeFromFormat`, however an exporter may know this
+      using :cfunc:`PyBuffer_SizeFromFormat`, however an exporter may know
-      information without parsing the format string and it is necessary to know
+      this information without parsing the format string and it is necessary
-      the itemsize for proper interpretation of striding. Therefore, storing it
+      to know the itemsize for proper interpretation of striding. Therefore,
-      is more convenient and faster.
+      storing it is more convenient and faster.
 
    .. cmember:: void *internal
 
@@ -143,20 +144,20 @@ Buffer related functions
 .. cfunction:: int PyObject_GetBuffer(PyObject *obj, PyObject *view, int flags)
 
       Export *obj* into a :ctype:`Py_buffer`, *view*.  These arguments must
-      never be *NULL*.  The *flags* argument is a bit field indicating what kind
+      never be *NULL*.  The *flags* argument is a bit field indicating what
-      of buffer the caller is prepared to deal with and therefore what kind of
+      kind of buffer the caller is prepared to deal with and therefore what
-      buffer the exporter is allowed to return.  The buffer interface allows for
+      kind of buffer the exporter is allowed to return.  The buffer interface
-      complicated memory sharing possibilities, but some caller may not be able
+      allows for complicated memory sharing possibilities, but some caller may
-      to handle all the complexibity but may want to see if the exporter will
+      not be able to handle all the complexibity but may want to see if the
-      let them take a simpler view to its memory.
+      exporter will let them take a simpler view to its memory.
 
       Some exporters may not be able to share memory in every possible way and
       may need to raise errors to signal to some consumers that something is
       just not possible. These errors should be a :exc:`BufferError` unless
-      there is another error that is actually causing the problem. The exporter
+      there is another error that is actually causing the problem. The
-      can use flags information to simplify how much of the :cdata:`Py_buffer`
+      exporter can use flags information to simplify how much of the
-      structure is filled in with non-default values and/or raise an error if
+      :cdata:`Py_buffer` structure is filled in with non-default values and/or
-      the object can't support a simpler view of its memory.
+      raise an error if the object can't support a simpler view of its memory.
 
       0 is returned on success and -1 on error.
 
@@ -267,16 +268,16 @@ Buffer related functions
 
 .. cfunction:: int PyObject_CopyToObject(PyObject *obj, void *buf, Py_ssize_t len, char fortran)
 
-   Copy *len* bytes of data pointed to by the contiguous chunk of memory pointed
+   Copy *len* bytes of data pointed to by the contiguous chunk of memory
-   to by *buf* into the buffer exported by obj.  The buffer must of course be
+   pointed to by *buf* into the buffer exported by obj.  The buffer must of
-   writable.  Return 0 on success and return -1 and raise an error on failure.
+   course be writable.  Return 0 on success and return -1 and raise an error
-   If the object does not have a writable buffer, then an error is raised.  If
+   on failure.  If the object does not have a writable buffer, then an error
-   *fortran* is ``'F'``, then if the object is multi-dimensional, then the data
+   is raised.  If *fortran* is ``'F'``, then if the object is
-   will be copied into the array in Fortran-style (first dimension varies the
+   multi-dimensional, then the data will be copied into the array in
-   fastest).  If *fortran* is ``'C'``, then the data will be copied into the
+   Fortran-style (first dimension varies the fastest).  If *fortran* is
-   array in C-style (last dimension varies the fastest).  If *fortran* is
+   ``'C'``, then the data will be copied into the array in C-style (last
-   ``'A'``, then it does not matter and the copy will be made in whatever way is
+   dimension varies the fastest).  If *fortran* is ``'A'``, then it does not
-   more efficient.
+   matter and the copy will be made in whatever way is more efficient.
 
 
 .. cfunction:: int PyBuffer_IsContiguous(Py_buffer *view, char fortran)
@@ -324,17 +325,18 @@ More information on the old buffer interface is provided in the section
 A "buffer object" is defined in the :file:`bufferobject.h` header (included by
 :file:`Python.h`). These objects look very similar to string objects at the
 Python programming level: they support slicing, indexing, concatenation, and
-some other standard string operations. However, their data can come from one of
+some other standard string operations. However, their data can come from one
-two sources: from a block of memory, or from another object which exports the
+of two sources: from a block of memory, or from another object which exports
-buffer interface.
+the buffer interface.
 
 Buffer objects are useful as a way to expose the data from another object's
-buffer interface to the Python programmer. They can also be used as a zero-copy
+buffer interface to the Python programmer. They can also be used as a
-slicing mechanism. Using their ability to reference a block of memory, it is
+zero-copy slicing mechanism. Using their ability to reference a block of
-possible to expose any data to the Python programmer quite easily. The memory
+memory, it is possible to expose any data to the Python programmer quite
-could be a large, constant array in a C extension, it could be a raw block of
+easily. The memory could be a large, constant array in a C extension, it could
-memory for manipulation before passing to an operating system library, or it
+be a raw block of memory for manipulation before passing to an operating
-could be used to pass around structured data in its native, in-memory format.
+system library, or it could be used to pass around structured data in its
+native, in-memory format.
 
 
 .. ctype:: PyBufferObject
@@ -355,9 +357,10 @@ could be used to pass around structured data in its native, in-memory format.
 
    This constant may be passed as the *size* parameter to
    :cfunc:`PyBuffer_FromObject` or :cfunc:`PyBuffer_FromReadWriteObject`.  It
-   indicates that the new :ctype:`PyBufferObject` should refer to *base* object
+   indicates that the new :ctype:`PyBufferObject` should refer to *base*
-   from the specified *offset* to the end of its exported buffer.  Using this
+   object from the specified *offset* to the end of its exported buffer.
-   enables the caller to avoid querying the *base* object for its length.
+   Using this enables the caller to avoid querying the *base* object for its
+   length.
 
 
 .. cfunction:: int PyBuffer_Check(PyObject *p)
@@ -367,14 +370,14 @@ could be used to pass around structured data in its native, in-memory format.
 
 .. cfunction:: PyObject* PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
 
-   Return a new read-only buffer object.  This raises :exc:`TypeError` if *base*
+   Return a new read-only buffer object.  This raises :exc:`TypeError` if
-   doesn't support the read-only buffer protocol or doesn't provide exactly one
+   *base* doesn't support the read-only buffer protocol or doesn't provide
-   buffer segment, or it raises :exc:`ValueError` if *offset* is less than zero.
+   exactly one buffer segment, or it raises :exc:`ValueError` if *offset* is
-   The buffer will hold a reference to the *base* object, and the buffer's contents
+   less than zero.  The buffer will hold a reference to the *base* object, and
-   will refer to the *base* object's buffer interface, starting as position
+   the buffer's contents will refer to the *base* object's buffer interface,
-   *offset* and extending for *size* bytes. If *size* is :const:`Py_END_OF_BUFFER`,
+   starting as position *offset* and extending for *size* bytes. If *size* is
-   then the new buffer's contents extend to the length of the *base* object's
+   :const:`Py_END_OF_BUFFER`, then the new buffer's contents extend to the
-   exported buffer data.
+   length of the *base* object's exported buffer data.
 
    .. versionchanged:: 2.5
       This function used an :ctype:`int` type for *offset* and *size*. This
@@ -384,9 +387,9 @@ could be used to pass around structured data in its native, in-memory format.
 
 .. cfunction:: PyObject* PyBuffer_FromReadWriteObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
 
-   Return a new writable buffer object.  Parameters and exceptions are similar to
+   Return a new writable buffer object.  Parameters and exceptions are similar
-   those for :cfunc:`PyBuffer_FromObject`.  If the *base* object does not export
+   to those for :cfunc:`PyBuffer_FromObject`.  If the *base* object does not
-   the writeable buffer protocol, then :exc:`TypeError` is raised.
+   export the writeable buffer protocol, then :exc:`TypeError` is raised.
 
    .. versionchanged:: 2.5
       This function used an :ctype:`int` type for *offset* and *size*. This
@@ -396,12 +399,12 @@ could be used to pass around structured data in its native, in-memory format.
 
 .. cfunction:: PyObject* PyBuffer_FromMemory(void *ptr, Py_ssize_t size)
 
-   Return a new read-only buffer object that reads from a specified location in
+   Return a new read-only buffer object that reads from a specified location
-   memory, with a specified size.  The caller is responsible for ensuring that the
+   in memory, with a specified size.  The caller is responsible for ensuring
-   memory buffer, passed in as *ptr*, is not deallocated while the returned buffer
+   that the memory buffer, passed in as *ptr*, is not deallocated while the
-   object exists.  Raises :exc:`ValueError` if *size* is less than zero.  Note that
+   returned buffer object exists.  Raises :exc:`ValueError` if *size* is less
-   :const:`Py_END_OF_BUFFER` may *not* be passed for the *size* parameter;
+   than zero.  Note that :const:`Py_END_OF_BUFFER` may *not* be passed for the
-   :exc:`ValueError` will be raised in that case.
+   *size* parameter; :exc:`ValueError` will be raised in that case.
 
    .. versionchanged:: 2.5
       This function used an :ctype:`int` type for *size*. This might require
@@ -410,7 +413,8 @@ could be used to pass around structured data in its native, in-memory format.
 
 .. cfunction:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size)
 
-   Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is writable.
+   Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is
+   writable.
 
    .. versionchanged:: 2.5
       This function used an :ctype:`int` type for *size*. This might require
@@ -420,9 +424,9 @@ could be used to pass around structured data in its native, in-memory format.
 .. cfunction:: PyObject* PyBuffer_New(Py_ssize_t size)
 
    Return a new writable buffer object that maintains its own memory buffer of
-   *size* bytes.  :exc:`ValueError` is returned if *size* is not zero or positive.
+   *size* bytes.  :exc:`ValueError` is returned if *size* is not zero or
-   Note that the memory buffer (as returned by :cfunc:`PyObject_AsWriteBuffer`) is
+   positive.  Note that the memory buffer (as returned by
-   not specifically aligned.
+   :cfunc:`PyObject_AsWriteBuffer`) is not specifically aligned.
 
    .. versionchanged:: 2.5
       This function used an :ctype:`int` type for *size*. This might require