diff options
| -rw-r--r-- | Doc/c-api/abstract.rst | 1 | ||||
| -rw-r--r-- | Doc/c-api/buffer.rst | 27 | ||||
| -rw-r--r-- | Doc/c-api/concrete.rst | 1 | ||||
| -rw-r--r-- | Doc/c-api/objbuffer.rst | 17 |
4 files changed, 22 insertions, 24 deletions
diff --git a/Doc/c-api/abstract.rst b/Doc/c-api/abstract.rst index db4c02a..ad53881 100644 --- a/Doc/c-api/abstract.rst +++ b/Doc/c-api/abstract.rst @@ -22,4 +22,5 @@ but whose items have not been set to some non-\ ``NULL`` value yet. sequence.rst mapping.rst iter.rst + buffer.rst objbuffer.rst diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst index 8b64e6c..dbd1e4d 100644 --- a/Doc/c-api/buffer.rst +++ b/Doc/c-api/buffer.rst @@ -2,8 +2,8 @@ .. _bufferobjects: -Buffer API ----------- +Buffer Protocol +--------------- .. sectionauthor:: Greg Stein <gstein@lyra.org> .. sectionauthor:: Benjamin Peterson @@ -50,21 +50,22 @@ How the buffer interface is exposed by a type object is described in the 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. diff --git a/Doc/c-api/concrete.rst b/Doc/c-api/concrete.rst index 8096054..7e8f08c 100644 --- a/Doc/c-api/concrete.rst +++ b/Doc/c-api/concrete.rst @@ -68,7 +68,6 @@ intrinsic to the Python language. bytes.rst bytearray.rst unicode.rst - buffer.rst tuple.rst list.rst diff --git a/Doc/c-api/objbuffer.rst b/Doc/c-api/objbuffer.rst index ef4e4ea..728d383 100644 --- a/Doc/c-api/objbuffer.rst +++ b/Doc/c-api/objbuffer.rst @@ -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 @@ Therefore, it is recommended that you call :cfunc:`PyObject_GetBuffer` 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 |