mirror of https://github.com/python/cpython.git
Buffers are not sequence objects (!). Put them in the abstract objects layers
instead.
This commit is contained in:
parent
99a00a455c
commit
f7ba2fa3d6
|
@ -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
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
||||
|
|
|
@ -68,7 +68,6 @@ intrinsic to the Python language.
|
|||
bytes.rst
|
||||
bytearray.rst
|
||||
unicode.rst
|
||||
buffer.rst
|
||||
tuple.rst
|
||||
list.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
|
||||
|
|
Loading…
Reference in New Issue