[Python-checkins] r85083 - in python/branches/release31-maint/Doc/c-api: abstract.rst buffer.rst concrete.rst objbuffer.rst

[antoine.pitrou]

Author: antoine.pitrou
Date: Wed Sep 29 01:41:31 2010
New Revision: 85083

Log:
Merged revisions 85082 via svnmerge from 
svn+ssh://pythondev@svn.python.org/python/branches/py3k

........
  r85082 | antoine.pitrou | 2010-09-29 01:39:41 +0200 (mer., 29 sept. 2010) | 4 lines
  
  Buffers are not sequence objects (!). Put them in the abstract objects layers
  instead.
........


Modified:
   python/branches/release31-maint/Doc/c-api/abstract.rst
   python/branches/release31-maint/Doc/c-api/buffer.rst
   python/branches/release31-maint/Doc/c-api/concrete.rst
   python/branches/release31-maint/Doc/c-api/objbuffer.rst

Modified: python/branches/release31-maint/Doc/c-api/abstract.rst
==============================================================================
--- python/branches/release31-maint/Doc/c-api/abstract.rst	(original)
+++ python/branches/release31-maint/Doc/c-api/abstract.rst	Wed Sep 29 01:41:31 2010
@@ -22,4 +22,5 @@
    sequence.rst
    mapping.rst
    iter.rst
+   buffer.rst
    objbuffer.rst

Modified: python/branches/release31-maint/Doc/c-api/buffer.rst
==============================================================================
--- python/branches/release31-maint/Doc/c-api/buffer.rst	(original)
+++ python/branches/release31-maint/Doc/c-api/buffer.rst	Wed Sep 29 01:41:31 2010
@@ -2,8 +2,8 @@
 
 .. _bufferobjects:
 
-Buffer API
-----------
+Buffer Protocol
+---------------
 
 .. sectionauthor:: Greg Stein <gstein at lyra.org>
 .. sectionauthor:: Benjamin Peterson
@@ -50,21 +50,22 @@
 section :ref:`buffer-structs`, under the description for :ctype:`PyBufferProcs`.
 
 
-Buffer objects
-==============
+The buffer structure
+====================
 
-Buffer objects are useful as a way to expose the binary data from another
-object to the Python programmer.  They can also be used as a zero-copy
-slicing mechanism.  Using their ability to reference a block of memory, it is
-possible to expose any data to the Python programmer quite easily.  The memory
-could be a large, constant array in a C extension, it could be a raw block of
-memory for manipulation before passing to an operating system library, or it
-could be used to pass around structured data in its native, in-memory format.
+Buffer structures (or simply "buffers") are useful as a way to expose the
+binary data from another object to the Python programmer.  They can also be
+used as a zero-copy slicing mechanism.  Using their ability to reference a
+block of memory, it is possible to expose any data to the Python programmer
+quite easily.  The memory could be a large, constant array in a C extension,
+it could be a raw block of memory for manipulation before passing to an
+operating system library, or it could be used to pass around structured data
+in its native, in-memory format.
 
-Contrary to most data types exposed by the Python interpreter, buffer objects
+Contrary to most data types exposed by the Python interpreter, buffers
 are not :ctype:`PyObject` pointers but rather simple C structures.  This
 allows them to be created and copied very simply.  When a generic wrapper
-around a buffer object is needed, a :ref:`memoryview <memoryviewobjects>` object
+around a buffer is needed, a :ref:`memoryview <memoryviewobjects>` object
 can be created.
 
 

Modified: python/branches/release31-maint/Doc/c-api/concrete.rst
==============================================================================
--- python/branches/release31-maint/Doc/c-api/concrete.rst	(original)
+++ python/branches/release31-maint/Doc/c-api/concrete.rst	Wed Sep 29 01:41:31 2010
@@ -68,7 +68,6 @@
    bytes.rst
    bytearray.rst
    unicode.rst
-   buffer.rst
    tuple.rst
    list.rst
 

Modified: python/branches/release31-maint/Doc/c-api/objbuffer.rst
==============================================================================
--- python/branches/release31-maint/Doc/c-api/objbuffer.rst	(original)
+++ python/branches/release31-maint/Doc/c-api/objbuffer.rst	Wed Sep 29 01:41:31 2010
@@ -1,15 +1,16 @@
 .. highlightlang:: c
 
-Old buffer API
---------------
+Old Buffer Protocol
+-------------------
 
 .. deprecated:: 3.0
 
 These functions were part of the "old buffer protocol" API in Python 2.
-In Python 3, these functions are still exposed for ease of porting code.
-They act as a compatibility wrapper around the :ref:`new buffer API
-<bufferobjects>`, but they don't give you control over the lifetime of
-the resources acquired when a buffer is exported.
+In Python 3, this protocol doesn't exist anymore but the functions are still
+exposed to ease porting 2.x code.  They act as a compatibility wrapper
+around the :ref:`new buffer protocol <bufferobjects>`, but they don't give
+you control over the lifetime of the resources acquired when a buffer is
+exported.
 
 Therefore, it is recommended that you call :cfunc:`PyObject_GetBuffer`
 (or the ``y*`` or ``w*`` :ref:`format codes <arg-parsing>` with the
@@ -17,10 +18,6 @@
 an object, and :cfunc:`PyBuffer_Release` when the buffer view can be released.
 
 
-Buffer Protocol
-===============
-
-
 .. cfunction:: int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)
 
    Returns a pointer to a read-only memory location usable as character-based