7.2.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 PyArgs_ParseTuple() that operate
against an object's buffer interface, returning data from the target
object.
More information on the buffer interface is provided in the section
``Buffer Object Structures'' (section 10.5), 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
interface.
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
format.
- PyBufferObject
-
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_FromObject() or
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 its
length.
- int PyBuffer_Check(PyObject *p)
-
Return true if the argument has type PyBuffer_Type.
- PyObject* PyBuffer_FromObject(PyObject *base,
int offset, int size)
-
Return value:
New reference.
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,
int offset,
int size)
-
Return value:
New reference.
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, int size)
-
Return value:
New reference.
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, int size)
-
Return value:
New reference.
Similar to PyBuffer_FromMemory(), but the returned buffer
is writable.
- PyObject* PyBuffer_New(int size)
-
Return value:
New reference.
Returns a new writable buffer object that maintains its own memory
buffer of size bytes. ValueError is returned if
size is not zero or positive.
See About this document... for information on suggesting changes.
