7.3.3 Buffer Objects
Python objects implemented in C can export a group of functions called
the ``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.
Two examples of objects that support
the buffer interface are strings and arrays. The string object exposes
the character contents in the buffer interface's byte-oriented
form. An array can also expose its contents, but it should be noted
that array elements may be multi-byte values.
An example user of the buffer interface is the file object's
write() method. Any object that can export a series of bytes
through the buffer interface can be written to a file. There are a
number of format codes to PyArg_ParseTuple() that operate
against an object's buffer interface, returning data from the target
More information on the buffer interface is provided in the section
``Buffer Object Structures'' (section 10.7), under
the description for PyBufferProcs.
A ``buffer object'' is defined in the bufferobject.h header
(included by Python.h). These objects look very similar to
string objects at the Python programming level: they support slicing,
indexing, concatenation, and some other standard string
operations. However, their data can come from one of two sources: from
a block of memory, or from another object which exports the buffer
Buffer objects are useful as a way to expose the data from another
object's buffer interface 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
This subtype of PyObject represents a buffer object.
- PyTypeObject PyBuffer_Type
The instance of PyTypeObject which represents the Python
buffer type; it is the same object as
types.BufferType in the Python layer.
- int Py_END_OF_BUFFER
This constant may be passed as the size parameter to
PyBuffer_FromReadWriteObject(). It indicates that the
new PyBufferObject should refer to base object from
the specified offset to the end of its exported buffer. Using
this enables the caller to avoid querying the base object for
|int PyBuffer_Check(||PyObject *p)|
Return true if the argument has type PyBuffer_Type.
|PyObject* PyBuffer_FromObject(||PyObject *base,
Py_ssize_t offset, Py_ssize_t size)|
Return a new read-only buffer object. This raises
TypeError if base doesn't support the read-only
buffer protocol or doesn't provide exactly one buffer segment, or it
raises ValueError if offset is less than zero. The
buffer will hold a reference to the base object, and the
buffer's contents will refer to the base object's buffer
interface, starting as position offset and extending for
size bytes. If size is Py_END_OF_BUFFER, then
the new buffer's contents extend to the length of the base
object's exported buffer data.
|PyObject* PyBuffer_FromReadWriteObject(||PyObject *base,
Return a new writable buffer object. Parameters and exceptions are
similar to those for PyBuffer_FromObject(). If the
base object does not export the writeable buffer protocol,
then TypeError is raised.
|PyObject* PyBuffer_FromMemory(||void *ptr, Py_ssize_t size)|
Return a new read-only buffer object that reads from a specified
location in memory, with a specified size. The caller is
responsible for ensuring that the memory buffer, passed in as
ptr, is not deallocated while the returned buffer object
exists. Raises ValueError if size is less than
zero. Note that Py_END_OF_BUFFER may not be
passed for the size parameter; ValueError will be
raised in that case.
|PyObject* PyBuffer_FromReadWriteMemory(||void *ptr, Py_ssize_t size)|
Similar to PyBuffer_FromMemory(), but the returned
buffer is writable.
|PyObject* PyBuffer_New(||Py_ssize_t size)|
Return a new writable buffer object that maintains its own memory
buffer of size bytes. ValueError is returned if
size is not zero or positive. Note that the memory buffer (as
returned by PyObject_AsWriteBuffer()) is not specifically
See About this document... for information on suggesting changes.