Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 99a00a4

Browse files
pitroupitrou
committed
Various improvements to the docs of the buffer API
1 parent b78b489 commit 99a00a4

1 file changed

Lines changed: 82 additions & 47 deletions

File tree

‎Doc/c-api/buffer.rst‎

Lines changed: 82 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22

33
.. _bufferobjects:
44

5-
Buffer Objects
6-
--------------
5+
Buffer API
6+
----------
77

88
.. sectionauthor:: Greg Stein <[email protected]>
99
.. sectionauthor:: Benjamin Peterson
@@ -17,30 +17,56 @@ functions can be used by an object to expose its data in a raw, byte-oriented
1717
format. Clients of the object can use the buffer interface to access the
1818
object data directly, without needing to copy it first.
1919

20-
Two examples of objects that support the buffer interface are bytes and
21-
arrays. The bytes 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.
20+
Examples of objects that support the buffer interface are :class:`bytes`,
21+
:class:`bytearray` and :class:`array.array`. The bytes and bytearray objects
22+
exposes their bytes contents in the buffer interface's byte-oriented form.
23+
An :class:`array.array` can also expose its contents, but it should be noted
24+
that array elements may be multi-byte values.
25+
26+
An example consumer of the buffer interface is the :meth:`~io.BufferedIOBase.write`
27+
method of file objects: any object that can export a series of bytes through
28+
the buffer interface can be written to a file. While :meth:`write` only
29+
needs read-only access to the internal contents of the object passed to it,
30+
other methods such as :meth:`~io.BufferedIOBase.readinto` need write access
31+
to the contents of their argument. The buffer interface allows objects to
32+
selectively allow or reject exporting of read-write and read-only buffers.
33+
34+
There are two ways for a consumer of the buffer interface to acquire a buffer
35+
over a target object:
36+
37+
* call :cfunc:`PyObject_GetBuffer` with the right parameters;
38+
39+
* call :cfunc:`PyArg_ParseTuple` (or one of its siblings) with one of the
40+
``y*``, ``w*`` or ``s*`` :ref:`format codes <arg-parsing>`.
41+
42+
In both cases, :cfunc:`PyBuffer_Release` must be called when the buffer
43+
isn't needed anymore. Failure to do so could lead to various issues such as
44+
resource leaks.
2445

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.
3046

3147
.. index:: single: PyBufferProcs
3248

33-
More information on the buffer interface is provided in the section
34-
:ref:`buffer-structs`, under the description for :ctype:`PyBufferProcs`.
49+
How the buffer interface is exposed by a type object is described in the
50+
section :ref:`buffer-structs`, under the description for :ctype:`PyBufferProcs`.
3551

36-
Buffer objects are useful as a way to expose the data from another object's
37-
buffer interface to the Python programmer. They can also be used as a zero-copy
52+
53+
Buffer objects
54+
==============
55+
56+
Buffer objects are useful as a way to expose the binary data from another
57+
object to the Python programmer. They can also be used as a zero-copy
3858
slicing mechanism. Using their ability to reference a block of memory, it is
3959
possible to expose any data to the Python programmer quite easily. The memory
4060
could be a large, constant array in a C extension, it could be a raw block of
4161
memory for manipulation before passing to an operating system library, or it
4262
could be used to pass around structured data in its native, in-memory format.
4363

64+
Contrary to most data types exposed by the Python interpreter, buffer objects
65+
are not :ctype:`PyObject` pointers but rather simple C structures. This
66+
allows them to be created and copied very simply. When a generic wrapper
67+
around a buffer object is needed, a :ref:`memoryview <memoryviewobjects>` object
68+
can be created.
69+
4470

4571
.. ctype:: Py_buffer
4672

@@ -133,18 +159,23 @@ Buffer related functions
133159

134160
.. cfunction:: int PyObject_CheckBuffer(PyObject *obj)
135161

136-
Return 1 if *obj* supports the buffer interface otherwise 0.
162+
Return 1 if *obj* supports the buffer interface otherwise 0. When 1 is
163+
returned, it doesn't guarantee that :cfunc:`PyObject_GetBuffer` will
164+
succeed.
137165

138166

139167
.. cfunction:: int PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags)
140168

141-
Export *obj* into a :ctype:`Py_buffer`, *view*. These arguments must
142-
never be *NULL*. The *flags* argument is a bit field indicating what
143-
kind of buffer the caller is prepared to deal with and therefore what
144-
kind of buffer the exporter is allowed to return. The buffer interface
145-
allows for complicated memory sharing possibilities, but some caller may
146-
not be able to handle all the complexity but may want to see if the
147-
exporter will let them take a simpler view to its memory.
169+
Export a view over some internal data from the target object *obj*.
170+
*obj* must not be NULL, and *view* must point to an existing
171+
:ctype:`Py_buffer` structure allocated by the caller (most uses of
172+
this function will simply declare a local variable of type
173+
:ctype:`Py_buffer`). The *flags* argument is a bit field indicating
174+
what kind of buffer is requested. The buffer interface allows
175+
for complicated memory layout possibilities; however, some callers
176+
won't want to handle all the complexity and instead request a simple
177+
view of the target object (using :cmacro:`PyBUF_SIMPLE` for a read-only
178+
view and :cmacro:`PyBUF_WRITABLE` for a read-write view).
148179

149180
Some exporters may not be able to share memory in every possible way and
150181
may need to raise errors to signal to some consumers that something is
@@ -154,26 +185,31 @@ Buffer related functions
154185
:cdata:`Py_buffer` structure is filled in with non-default values and/or
155186
raise an error if the object can't support a simpler view of its memory.
156187

157-
0 is returned on success and -1 on error.
188+
On success, 0 is returned and the *view* structure is filled with useful
189+
values. On error, -1 is returned and an exception is raised; the *view*
190+
is left in an undefined state.
158191

159192
The following table gives possible values to the *flags* arguments.
160193

161194
+------------------------------+---------------------------------------------------+
162195
| Flag | Description |
163196
+==============================+===================================================+
164-
| :cmacro:`PyBUF_SIMPLE` | This is the default flag state. The returned |
165-
| | buffer may or may not have writable memory. The |
166-
| | format of the data will be assumed to be unsigned |
167-
| | bytes. This is a "stand-alone" flag constant. It |
197+
| .. cmacro:: PyBUF_SIMPLE | This is the default flag. The returned buffer |
198+
| | exposes a read-only memory area. The format of |
199+
| | data is assumed to be raw unsigned bytes, without |
200+
| | any particular structure. This is a "stand-alone"|
201+
| | flag constant. It |
168202
| | never needs to be '|'d to the others. The exporter|
169203
| | will raise an error if it cannot provide such a |
170204
| | contiguous buffer of bytes. |
171205
| | |
172206
+------------------------------+---------------------------------------------------+
173-
| :cmacro:`PyBUF_WRITABLE` | The returned buffer must be writable. If it is |
174-
| | not writable, then raise an error. |
207+
| .. cmacro:: PyBUF_WRITABLE | Like :cmacro:`PyBUF_SIMPLE`, but the returned |
208+
| | buffer is writable. If the exporter doesn't |
209+
| | support |
210+
| | writable buffers, an error is raised. |
175211
+------------------------------+---------------------------------------------------+
176-
| :cmacro:`PyBUF_STRIDES` | This implies :cmacro:`PyBUF_ND`. The returned |
212+
| .. cmacro:: PyBUF_STRIDES | This implies :cmacro:`PyBUF_ND`. The returned |
177213
| | buffer must provide strides information (i.e. the |
178214
| | strides cannot be NULL). This would be used when |
179215
| | the consumer can handle strided, discontiguous |
@@ -183,27 +219,25 @@ Buffer related functions
183219
| | not possible (i.e. without the suboffsets). |
184220
| | |
185221
+------------------------------+---------------------------------------------------+
186-
| :cmacro:`PyBUF_ND` | The returned buffer must provide shape |
222+
| .. cmacro:: PyBUF_ND | The returned buffer must provide shape |
187223
| | information. The memory will be assumed C-style |
188224
| | contiguous (last dimension varies the |
189225
| | fastest). The exporter may raise an error if it |
190226
| | cannot provide this kind of contiguous buffer. If |
191227
| | this is not given then shape will be *NULL*. |
192228
| | |
193-
| | |
194-
| | |
195229
+------------------------------+---------------------------------------------------+
196-
|:cmacro:`PyBUF_C_CONTIGUOUS` | These flags indicate that the contiguity returned |
197-
|:cmacro:`PyBUF_F_CONTIGUOUS` | buffer must be respectively, C-contiguous (last |
198-
|:cmacro:`PyBUF_ANY_CONTIGUOUS`| dimension varies the fastest), Fortran contiguous |
230+
|.. cmacro:: PyBUF_C_CONTIGUOUS| These flags indicate that the contiguity returned |
231+
| PyBUF_F_CONTIGUOUS| buffer must be respectively, C-contiguous (last |
232+
| PyBUF_ANY_CONTIGUOUS| dimension varies the fastest), Fortran contiguous |
199233
| | (first dimension varies the fastest) or either |
200234
| | one. All of these flags imply |
201235
| | :cmacro:`PyBUF_STRIDES` and guarantee that the |
202236
| | strides buffer info structure will be filled in |
203237
| | correctly. |
204238
| | |
205239
+------------------------------+---------------------------------------------------+
206-
| :cmacro:`PyBUF_INDIRECT` | This flag indicates the returned buffer must have |
240+
| .. cmacro:: PyBUF_INDIRECT | This flag indicates the returned buffer must have |
207241
| | suboffsets information (which can be NULL if no |
208242
| | suboffsets are needed). This can be used when |
209243
| | the consumer can handle indirect array |
@@ -213,7 +247,7 @@ Buffer related functions
213247
| | |
214248
| | |
215249
+------------------------------+---------------------------------------------------+
216-
| :cmacro:`PyBUF_FORMAT` | The returned buffer must have true format |
250+
| .. cmacro:: PyBUF_FORMAT | The returned buffer must have true format |
217251
| | information if this flag is provided. This would |
218252
| | be used when the consumer is going to be checking |
219253
| | for what 'kind' of data is actually stored. An |
@@ -223,28 +257,28 @@ Buffer related functions
223257
| | returned as *NULL* (which means ``'B'``, or |
224258
| | unsigned bytes) |
225259
+------------------------------+---------------------------------------------------+
226-
| :cmacro:`PyBUF_STRIDED` | This is equivalent to ``(PyBUF_STRIDES | |
260+
| .. cmacro:: PyBUF_STRIDED | This is equivalent to ``(PyBUF_STRIDES | |
227261
| | PyBUF_WRITABLE)``. |
228262
+------------------------------+---------------------------------------------------+
229-
| :cmacro:`PyBUF_STRIDED_RO` | This is equivalent to ``(PyBUF_STRIDES)``. |
263+
| .. cmacro:: PyBUF_STRIDED_RO | This is equivalent to ``(PyBUF_STRIDES)``. |
230264
| | |
231265
+------------------------------+---------------------------------------------------+
232-
| :cmacro:`PyBUF_RECORDS` | This is equivalent to ``(PyBUF_STRIDES | |
266+
| .. cmacro:: PyBUF_RECORDS | This is equivalent to ``(PyBUF_STRIDES | |
233267
| | PyBUF_FORMAT | PyBUF_WRITABLE)``. |
234268
+------------------------------+---------------------------------------------------+
235-
| :cmacro:`PyBUF_RECORDS_RO` | This is equivalent to ``(PyBUF_STRIDES | |
269+
| .. cmacro:: PyBUF_RECORDS_RO | This is equivalent to ``(PyBUF_STRIDES | |
236270
| | PyBUF_FORMAT)``. |
237271
+------------------------------+---------------------------------------------------+
238-
| :cmacro:`PyBUF_FULL` | This is equivalent to ``(PyBUF_INDIRECT | |
272+
| .. cmacro:: PyBUF_FULL | This is equivalent to ``(PyBUF_INDIRECT | |
239273
| | PyBUF_FORMAT | PyBUF_WRITABLE)``. |
240274
+------------------------------+---------------------------------------------------+
241-
| :cmacro:`PyBUF_FULL_RO` | This is equivalent to ``(PyBUF_INDIRECT | |
275+
| .. cmacro:: PyBUF_FULL_RO | This is equivalent to ``(PyBUF_INDIRECT | |
242276
| | PyBUF_FORMAT)``. |
243277
+------------------------------+---------------------------------------------------+
244-
| :cmacro:`PyBUF_CONTIG` | This is equivalent to ``(PyBUF_ND | |
278+
| .. cmacro:: PyBUF_CONTIG | This is equivalent to ``(PyBUF_ND | |
245279
| | PyBUF_WRITABLE)``. |
246280
+------------------------------+---------------------------------------------------+
247-
| :cmacro:`PyBUF_CONTIG_RO` | This is equivalent to ``(PyBUF_ND)``. |
281+
| .. cmacro:: PyBUF_CONTIG_RO | This is equivalent to ``(PyBUF_ND)``. |
248282
| | |
249283
+------------------------------+---------------------------------------------------+
250284

@@ -299,6 +333,7 @@ Buffer related functions
299333
.. index::
300334
object: memoryview
301335

336+
.. _memoryviewobjects:
302337

303338
MemoryView objects
304339
==================

0 commit comments

Comments
 (0)