<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"api.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"api.html" title='Python/C API Reference Manual'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"next" href=
"tupleObjects.html" />
<link rel=
"prev" href=
"unicodeObjects.html" />
<link rel=
"parent" href=
"sequenceObjects.html" />
<link rel=
"next" href=
"tupleObjects.html" />
<meta name='aesop' content='information'
/>
<title>7.3.3 Buffer Objects
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"7.3.2.2 Methods and Slot"
href=
"unicodeMethodsAndSlots.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"7.3 Sequence Objects"
href=
"sequenceObjects.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"7.3.4 Tuple Objects"
href=
"tupleObjects.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python/C API Reference Manual
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"unicodeMethodsAndSlots.html">7.3.2.2 Methods and Slot
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"sequenceObjects.html">7.3 Sequence Objects
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"tupleObjects.html">7.3.4 Tuple Objects
</A>
<!--End of Navigation Panel-->
<H2><A NAME=
"SECTION009330000000000000000"></A><A NAME=
"bufferObjects"></A>
<a id='l2h-
548' xml:id='l2h-
548'
></a>Python objects implemented in C can export a group of functions called
the ``buffer
<a id='l2h-
560' xml:id='l2h-
560'
></a> 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
<tt class=
"method">write()
</tt> 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
<tt class=
"cfunction">PyArg_ParseTuple()
</tt> 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
<A href=
"buffer-structs.html#buffer-structs">10.7</A>), under
the description for
<tt class=
"ctype">PyBufferProcs
</tt><a id='l2h-
561' xml:id='l2h-
561'
></a>.
A ``buffer object'' is defined in the
<span class=
"file">bufferobject.h
</span> header
(included by
<span class=
"file">Python.h
</span>). 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
<dl><dt><b><tt class=
"ctype"><a id='l2h-
549' xml:id='l2h-
549'
>PyBufferObject
</a></tt></b></dt>
This subtype of
<tt class=
"ctype">PyObject
</tt> represents a buffer object.
<dl><dt>PyTypeObject
<b><tt id='l2h-
550' xml:id='l2h-
550'
class=
"cdata">PyBuffer_Type
</tt></b></dt>
The instance of
<tt class=
"ctype">PyTypeObject
</tt> which represents the Python
buffer type; it is the same object as
<code>types.BufferType
</code> in the
Python layer.
<a id='l2h-
552' xml:id='l2h-
552'
></a>.
<dl><dt>int
<b><tt id='l2h-
553' xml:id='l2h-
553'
class=
"cdata">Py_END_OF_BUFFER
</tt></b></dt>
This constant may be passed as the
<var>size
</var> parameter to
<tt class=
"cfunction">PyBuffer_FromObject()
</tt> or
<tt class=
"cfunction">PyBuffer_FromReadWriteObject()
</tt>. It indicates that the
new
<tt class=
"ctype">PyBufferObject
</tt> should refer to
<var>base
</var> object from
the specified
<var>offset
</var> to the end of its exported buffer. Using
this enables the caller to avoid querying the
<var>base
</var> object for
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>int
<b><tt id='l2h-
554' xml:id='l2h-
554'
class=
"cfunction">PyBuffer_Check
</tt></b>(
</nobr></td><td>PyObject *
<var>p
</var>)
</td></tr></table></dt>
Return true if the argument has type
<tt class=
"cdata">PyBuffer_Type
</tt>.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>PyObject*
<b><tt id='l2h-
555' xml:id='l2h-
555'
class=
"cfunction">PyBuffer_FromObject
</tt></b>(
</nobr></td><td>PyObject *
<var>base
</var>,
int
<var>offset
</var>, int
<var>size
</var>)
</td></tr></table></dt>
<div class=
"refcount-info">
<span class=
"label">Return value:
</span>
<span class=
"value">New reference.
</span>
Return a new read-only buffer object. This raises
<tt class=
"exception">TypeError
</tt> if
<var>base
</var> doesn't support the read-only
buffer protocol or doesn't provide exactly one buffer segment, or it
raises
<tt class=
"exception">ValueError
</tt> if
<var>offset
</var> is less than zero. The
buffer will hold a reference to the
<var>base
</var> object, and the
buffer's contents will refer to the
<var>base
</var> object's buffer
interface, starting as position
<var>offset
</var> and extending for
<var>size
</var> bytes. If
<var>size
</var> is
<tt class=
"constant">Py_END_OF_BUFFER
</tt>, then
the new buffer's contents extend to the length of the
<var>base
</var>
object's exported buffer data.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>PyObject*
<b><tt id='l2h-
556' xml:id='l2h-
556'
class=
"cfunction">PyBuffer_FromReadWriteObject
</tt></b>(
</nobr></td><td>PyObject *
<var>base
</var>,
int
<var>size
</var>)
</td></tr></table></dt>
<div class=
"refcount-info">
<span class=
"label">Return value:
</span>
<span class=
"value">New reference.
</span>
Return a new writable buffer object. Parameters and exceptions are
similar to those for
<tt class=
"cfunction">PyBuffer_FromObject()
</tt>. If the
<var>base
</var> object does not export the writeable buffer protocol,
then
<tt class=
"exception">TypeError
</tt> is raised.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>PyObject*
<b><tt id='l2h-
557' xml:id='l2h-
557'
class=
"cfunction">PyBuffer_FromMemory
</tt></b>(
</nobr></td><td>void *
<var>ptr
</var>, int
<var>size
</var>)
</td></tr></table></dt>
<div class=
"refcount-info">
<span class=
"label">Return value:
</span>
<span class=
"value">New reference.
</span>
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
<var>ptr
</var>, is not deallocated while the returned buffer object
exists. Raises
<tt class=
"exception">ValueError
</tt> if
<var>size
</var> is less than
zero. Note that
<tt class=
"constant">Py_END_OF_BUFFER
</tt> may
<em>not
</em> be
passed for the
<var>size
</var> parameter;
<tt class=
"exception">ValueError
</tt> will be
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>PyObject*
<b><tt id='l2h-
558' xml:id='l2h-
558'
class=
"cfunction">PyBuffer_FromReadWriteMemory
</tt></b>(
</nobr></td><td>void *
<var>ptr
</var>, int
<var>size
</var>)
</td></tr></table></dt>
<div class=
"refcount-info">
<span class=
"label">Return value:
</span>
<span class=
"value">New reference.
</span>
Similar to
<tt class=
"cfunction">PyBuffer_FromMemory()
</tt>, but the returned
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>PyObject*
<b><tt id='l2h-
559' xml:id='l2h-
559'
class=
"cfunction">PyBuffer_New
</tt></b>(
</nobr></td><td>int
<var>size
</var>)
</td></tr></table></dt>
<div class=
"refcount-info">
<span class=
"label">Return value:
</span>
<span class=
"value">New reference.
</span>
Return a new writable buffer object that maintains its own memory
buffer of
<var>size
</var> bytes.
<tt class=
"exception">ValueError
</tt> is returned if
<var>size
</var> is not zero or positive. Note that the memory buffer (as
returned by
<tt class=
"cfunction">PyObject_AsWriteBuffer()
</tt>) is not specifically
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"7.3.2.2 Methods and Slot"
href=
"unicodeMethodsAndSlots.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"7.3 Sequence Objects"
href=
"sequenceObjects.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"7.3.4 Tuple Objects"
href=
"tupleObjects.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python/C API Reference Manual
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"unicodeMethodsAndSlots.html">7.3.2.2 Methods and Slot
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"sequenceObjects.html">7.3 Sequence Objects
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"tupleObjects.html">7.3.4 Tuple Objects
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.