diff options
| -rw-r--r-- | Doc/c-api/buffer.rst | 40 | ||||
| -rw-r--r-- | Doc/c-api/typeobj.rst | 2 |
2 files changed, 26 insertions, 16 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 ==================== diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 25d0793..4a6335c 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -1195,7 +1195,7 @@ Buffer Object Structures .. sectionauthor:: Benjamin Peterson -The buffer interface exports a model where an object can expose its internal +The :ref:`buffer interface <bufferobjects>` exports a model where an object can expose its internal data. If an object does not export the buffer interface, then its :attr:`tp_as_buffer` |