|
1 .. highlightlang:: c |
|
2 |
|
3 .. _bufferobjects: |
|
4 |
|
5 Buffer Objects |
|
6 -------------- |
|
7 |
|
8 .. sectionauthor:: Greg Stein <gstein@lyra.org> |
|
9 |
|
10 |
|
11 .. index:: |
|
12 object: buffer |
|
13 single: buffer interface |
|
14 |
|
15 Python objects implemented in C can export a group of functions called the |
|
16 "buffer interface." These functions can be used by an object to expose its data |
|
17 in a raw, byte-oriented format. Clients of the object can use the buffer |
|
18 interface to access the object data directly, without needing to copy it first. |
|
19 |
|
20 Two examples of objects that support the buffer interface are strings and |
|
21 arrays. The string object exposes the character contents in the buffer |
|
22 interface's byte-oriented form. An array can also expose its contents, but it |
|
23 should be noted that array elements may be multi-byte values. |
|
24 |
|
25 An example user of the buffer interface is the file object's :meth:`write` |
|
26 method. Any object that can export a series of bytes through the buffer |
|
27 interface can be written to a file. There are a number of format codes to |
|
28 :cfunc:`PyArg_ParseTuple` that operate against an object's buffer interface, |
|
29 returning data from the target object. |
|
30 |
|
31 .. index:: single: PyBufferProcs |
|
32 |
|
33 More information on the buffer interface is provided in the section |
|
34 :ref:`buffer-structs`, under the description for :ctype:`PyBufferProcs`. |
|
35 |
|
36 A "buffer object" is defined in the :file:`bufferobject.h` header (included by |
|
37 :file:`Python.h`). These objects look very similar to string objects at the |
|
38 Python programming level: they support slicing, indexing, concatenation, and |
|
39 some other standard string operations. However, their data can come from one of |
|
40 two sources: from a block of memory, or from another object which exports the |
|
41 buffer interface. |
|
42 |
|
43 Buffer objects are useful as a way to expose the data from another object's |
|
44 buffer interface to the Python programmer. They can also be used as a zero-copy |
|
45 slicing mechanism. Using their ability to reference a block of memory, it is |
|
46 possible to expose any data to the Python programmer quite easily. The memory |
|
47 could be a large, constant array in a C extension, it could be a raw block of |
|
48 memory for manipulation before passing to an operating system library, or it |
|
49 could be used to pass around structured data in its native, in-memory format. |
|
50 |
|
51 |
|
52 .. ctype:: PyBufferObject |
|
53 |
|
54 This subtype of :ctype:`PyObject` represents a buffer object. |
|
55 |
|
56 |
|
57 .. cvar:: PyTypeObject PyBuffer_Type |
|
58 |
|
59 .. index:: single: BufferType (in module types) |
|
60 |
|
61 The instance of :ctype:`PyTypeObject` which represents the Python buffer type; |
|
62 it is the same object as ``buffer`` and ``types.BufferType`` in the Python |
|
63 layer. . |
|
64 |
|
65 |
|
66 .. cvar:: int Py_END_OF_BUFFER |
|
67 |
|
68 This constant may be passed as the *size* parameter to |
|
69 :cfunc:`PyBuffer_FromObject` or :cfunc:`PyBuffer_FromReadWriteObject`. It |
|
70 indicates that the new :ctype:`PyBufferObject` should refer to *base* object |
|
71 from the specified *offset* to the end of its exported buffer. Using this |
|
72 enables the caller to avoid querying the *base* object for its length. |
|
73 |
|
74 |
|
75 .. cfunction:: int PyBuffer_Check(PyObject *p) |
|
76 |
|
77 Return true if the argument has type :cdata:`PyBuffer_Type`. |
|
78 |
|
79 |
|
80 .. cfunction:: PyObject* PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size) |
|
81 |
|
82 Return a new read-only buffer object. This raises :exc:`TypeError` if *base* |
|
83 doesn't support the read-only buffer protocol or doesn't provide exactly one |
|
84 buffer segment, or it raises :exc:`ValueError` if *offset* is less than zero. |
|
85 The buffer will hold a reference to the *base* object, and the buffer's contents |
|
86 will refer to the *base* object's buffer interface, starting as position |
|
87 *offset* and extending for *size* bytes. If *size* is :const:`Py_END_OF_BUFFER`, |
|
88 then the new buffer's contents extend to the length of the *base* object's |
|
89 exported buffer data. |
|
90 |
|
91 |
|
92 .. cfunction:: PyObject* PyBuffer_FromReadWriteObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size) |
|
93 |
|
94 Return a new writable buffer object. Parameters and exceptions are similar to |
|
95 those for :cfunc:`PyBuffer_FromObject`. If the *base* object does not export |
|
96 the writeable buffer protocol, then :exc:`TypeError` is raised. |
|
97 |
|
98 |
|
99 .. cfunction:: PyObject* PyBuffer_FromMemory(void *ptr, Py_ssize_t size) |
|
100 |
|
101 Return a new read-only buffer object that reads from a specified location in |
|
102 memory, with a specified size. The caller is responsible for ensuring that the |
|
103 memory buffer, passed in as *ptr*, is not deallocated while the returned buffer |
|
104 object exists. Raises :exc:`ValueError` if *size* is less than zero. Note that |
|
105 :const:`Py_END_OF_BUFFER` may *not* be passed for the *size* parameter; |
|
106 :exc:`ValueError` will be raised in that case. |
|
107 |
|
108 |
|
109 .. cfunction:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size) |
|
110 |
|
111 Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is writable. |
|
112 |
|
113 |
|
114 .. cfunction:: PyObject* PyBuffer_New(Py_ssize_t size) |
|
115 |
|
116 Return a new writable buffer object that maintains its own memory buffer of |
|
117 *size* bytes. :exc:`ValueError` is returned if *size* is not zero or positive. |
|
118 Note that the memory buffer (as returned by :cfunc:`PyObject_AsWriteBuffer`) is |
|
119 not specifically aligned. |