Kaydet (Commit) f7ba2fa3 authored tarafından Antoine Pitrou's avatar Antoine Pitrou

Buffers are not sequence objects (!). Put them in the abstract objects layers

instead.
üst 99a00a45
...@@ -22,4 +22,5 @@ but whose items have not been set to some non-\ ``NULL`` value yet. ...@@ -22,4 +22,5 @@ but whose items have not been set to some non-\ ``NULL`` value yet.
sequence.rst sequence.rst
mapping.rst mapping.rst
iter.rst iter.rst
buffer.rst
objbuffer.rst objbuffer.rst
...@@ -2,8 +2,8 @@ ...@@ -2,8 +2,8 @@
.. _bufferobjects: .. _bufferobjects:
Buffer API Buffer Protocol
---------- ---------------
.. sectionauthor:: Greg Stein <gstein@lyra.org> .. sectionauthor:: Greg Stein <gstein@lyra.org>
.. sectionauthor:: Benjamin Peterson .. sectionauthor:: Benjamin Peterson
...@@ -50,21 +50,22 @@ How the buffer interface is exposed by a type object is described in the ...@@ -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`. 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 Buffer structures (or simply "buffers") are useful as a way to expose the
object to the Python programmer. They can also be used as a zero-copy binary data from another object to the Python programmer. They can also be
slicing mechanism. Using their ability to reference a block of memory, it is used as a zero-copy slicing mechanism. Using their ability to reference a
possible to expose any data to the Python programmer quite easily. The memory block of memory, it is possible to expose any data to the Python programmer
could be a large, constant array in a C extension, it could be a raw block of quite easily. The memory could be a large, constant array in a C extension,
memory for manipulation before passing to an operating system library, or it it could be a raw block of memory for manipulation before passing to an
could be used to pass around structured data in its native, in-memory format. 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 are not :ctype:`PyObject` pointers but rather simple C structures. This
allows them to be created and copied very simply. When a generic wrapper 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. can be created.
......
...@@ -68,7 +68,6 @@ intrinsic to the Python language. ...@@ -68,7 +68,6 @@ intrinsic to the Python language.
bytes.rst bytes.rst
bytearray.rst bytearray.rst
unicode.rst unicode.rst
buffer.rst
tuple.rst tuple.rst
list.rst list.rst
......
.. highlightlang:: c .. highlightlang:: c
Old buffer API Old Buffer Protocol
-------------- -------------------
.. deprecated:: 3.0 .. deprecated:: 3.0
These functions were part of the "old buffer protocol" API in Python 2. 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. In Python 3, this protocol doesn't exist anymore but the functions are still
They act as a compatibility wrapper around the :ref:`new buffer API exposed to ease porting 2.x code. They act as a compatibility wrapper
<bufferobjects>`, but they don't give you control over the lifetime of around the :ref:`new buffer protocol <bufferobjects>`, but they don't give
the resources acquired when a buffer is exported. you control over the lifetime of the resources acquired when a buffer is
exported.
Therefore, it is recommended that you call :cfunc:`PyObject_GetBuffer` Therefore, it is recommended that you call :cfunc:`PyObject_GetBuffer`
(or the ``y*`` or ``w*`` :ref:`format codes <arg-parsing>` with the (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` ...@@ -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. 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) .. 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 Returns a pointer to a read-only memory location usable as character-based
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment