mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-04 00:48:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

Merged revisions 87188-87190,87192-87194 via svnmerge from

Browse source 
svn+ssh://pythondev@svn.python.org/python/branches/py3k

........
  r87188 | antoine.pitrou | 2010-12-12 19:25:25 +0100 (dim., 12 déc. 2010) | 3 lines

  Make this a warning and fix indentation
........
  r87189 | antoine.pitrou | 2010-12-12 20:59:47 +0100 (dim., 12 déc. 2010) | 3 lines

  Better explain the buffer interface (hopefully)
........
  r87190 | antoine.pitrou | 2010-12-12 21:01:43 +0100 (dim., 12 déc. 2010) | 3 lines

  Add link to the buffer protocol description from the memory description.
........
  r87192 | antoine.pitrou | 2010-12-12 21:09:18 +0100 (dim., 12 déc. 2010) | 3 lines

  Remove redundant sentence, and fix markup
........
  r87193 | antoine.pitrou | 2010-12-12 21:13:31 +0100 (dim., 12 déc. 2010) | 3 lines

  Fix heading level
........
  r87194 | antoine.pitrou | 2010-12-12 21:17:29 +0100 (dim., 12 déc. 2010) | 3 lines

  Consistent ordering of availability statements
........
This commit is contained in:
Antoine Pitrou 2010-12-12 21:07:49 +00:00
parent 0101a3a827
commit a92d1f5041
5 changed files with 40 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

40
Doc/c-api/buffer.rst
View file

@ -12,16 +12,32 @@ Buffer Protocol
.. index::
single: buffer interface
Python objects implemented in C can export a "buffer interface." These
functions can be used by an object to expose its data in a raw, byte-oriented
format. Clients of the object can use the buffer interface to access the
object data directly, without needing to copy it first.
Certain objects available in Python wrap access to an underlying memory
array or *buffer*. Such objects include the built-in :class:`bytes` and
:class:`bytearray`, and some extension types like :class:`array.array`.
Third-party libraries may define their own types for special purposes, such
as image processing or numeric analysis.
Examples of objects that support the buffer interface are :class:`bytes`,
:class:`bytearray` and :class:`array.array`. The bytes and bytearray objects
exposes their bytes contents in the buffer interface's byte-oriented form.
An :class:`array.array` can also expose its contents, but it should be noted
that array elements may be multi-byte values.
While each of these types have their own semantics, they share the common
characteristic of being backed by a possibly large memory buffer. It is
then desireable, in some situations, to access that buffer directly and
without intermediate copying.
Python provides such a facility at the C level in the form of the *buffer
protocol*. This protocol has two sides:
.. index:: single: PyBufferProcs
- on the producer side, a type can export a "buffer interface" which allows
objects of that type to expose information about their underlying buffer.
This interface is described in the section :ref:`buffer-structs`;
- on the consumer side, several means are available to obtain a pointer to
the raw underlying data of an object (for example a method parameter).
Simple objects such as :class:`bytes` and :class:`bytearray` expose their
underlying buffer in byte-oriented form. Other forms are possible; for example,
the elements exposed by a :class:`array.array` can be multi-byte values.
An example consumer of the buffer interface is the :meth:`~io.BufferedIOBase.write`
method of file objects: any object that can export a series of bytes through
@ -44,12 +60,6 @@ isn't needed anymore. Failure to do so could lead to various issues such as
resource leaks.
.. index:: single: PyBufferProcs
How the buffer interface is exposed by a type object is described in the
section :ref:`buffer-structs`, under the description for :ctype:`PyBufferProcs`.
The buffer structure
====================