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.
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
......
.. 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
......
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