summaryrefslogtreecommitdiffstats
path: root/Doc/c-api/buffer.rst
diff options
context:
space:
mode:
authorAntoine Pitrou <solipsis@pitrou.net>2010-12-12 19:59:47 (GMT)
committerAntoine Pitrou <solipsis@pitrou.net>2010-12-12 19:59:47 (GMT)
commit8abc93580d2f0e74a1931fb25803a4b9fd8e0e7d (patch)
tree054ee92a570081bb087833cbe941149127a7c3f6 /Doc/c-api/buffer.rst
parent36730e8bc157901bd891df9a2dbe8a153538fe43 (diff)
downloadcpython-8abc93580d2f0e74a1931fb25803a4b9fd8e0e7d.zip
cpython-8abc93580d2f0e74a1931fb25803a4b9fd8e0e7d.tar.gz
cpython-8abc93580d2f0e74a1931fb25803a4b9fd8e0e7d.tar.bz2
Better explain the buffer interface (hopefully)
Diffstat (limited to 'Doc/c-api/buffer.rst')
-rw-r--r--Doc/c-api/buffer.rst40
1 files changed, 25 insertions, 15 deletions
diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst
index 64e8360..e4c3209 100644
--- a/Doc/c-api/buffer.rst
+++ b/Doc/c-api/buffer.rst
@@ -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 :c:type:`PyBufferProcs`.
-
-
The buffer structure
====================