Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/buffer.rst @ 70817:dd775b1561ba

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix markup.
author Georg Brandl <georg@python.org>
date Tue, 14 Jun 2011 21:09:55 +0200
parents 68dd623f77f4
children f32f1cb508ad 3f9b3b6f7ff0
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. highlightlang:: c
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 .. _bufferobjects:
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
4
64997
dc4555646e80 Merged revisions 85082 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64995
diff changeset
5 Buffer Protocol
dc4555646e80 Merged revisions 85082 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64995
diff changeset
6 ---------------
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 .. sectionauthor:: Greg Stein <gstein@lyra.org>
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
9 .. sectionauthor:: Benjamin Peterson
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
11
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 .. index::
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
13 single: buffer interface
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
14
66860
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
15 Certain objects available in Python wrap access to an underlying memory
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
16 array or *buffer*. Such objects include the built-in :class:`bytes` and
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
17 :class:`bytearray`, and some extension types like :class:`array.array`.
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
18 Third-party libraries may define their own types for special purposes, such
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
19 as image processing or numeric analysis.
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
20
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
21 While each of these types have their own semantics, they share the common
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
22 characteristic of being backed by a possibly large memory buffer. It is
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
23 then desireable, in some situations, to access that buffer directly and
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
24 without intermediate copying.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
25
66860
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
26 Python provides such a facility at the C level in the form of the *buffer
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
27 protocol*. This protocol has two sides:
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
28
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
29 .. index:: single: PyBufferProcs
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
30
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
31 - on the producer side, a type can export a "buffer interface" which allows
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
32 objects of that type to expose information about their underlying buffer.
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
33 This interface is described in the section :ref:`buffer-structs`;
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
34
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
35 - on the consumer side, several means are available to obtain a pointer to
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
36 the raw underlying data of an object (for example a method parameter).
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
37
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
38 Simple objects such as :class:`bytes` and :class:`bytearray` expose their
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
39 underlying buffer in byte-oriented form. Other forms are possible; for example,
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 65109
diff changeset
40 the elements exposed by a :class:`array.array` can be multi-byte values.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
41
64995
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
42 An example consumer of the buffer interface is the :meth:`~io.BufferedIOBase.write`
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
43 method of file objects: any object that can export a series of bytes through
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
44 the buffer interface can be written to a file. While :meth:`write` only
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
45 needs read-only access to the internal contents of the object passed to it,
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
46 other methods such as :meth:`~io.BufferedIOBase.readinto` need write access
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
47 to the contents of their argument. The buffer interface allows objects to
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
48 selectively allow or reject exporting of read-write and read-only buffers.
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
49
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
50 There are two ways for a consumer of the buffer interface to acquire a buffer
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
51 over a target object:
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
52
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
53 * call :c:func:`PyObject_GetBuffer` with the right parameters;
64995
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
54
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
55 * call :c:func:`PyArg_ParseTuple` (or one of its siblings) with one of the
64995
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
56 ``y*``, ``w*`` or ``s*`` :ref:`format codes <arg-parsing>`.
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
57
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
58 In both cases, :c:func:`PyBuffer_Release` must be called when the buffer
64995
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
59 isn't needed anymore. Failure to do so could lead to various issues such as
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
60 resource leaks.
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
61
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
62
64997
dc4555646e80 Merged revisions 85082 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64995
diff changeset
63 The buffer structure
dc4555646e80 Merged revisions 85082 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64995
diff changeset
64 ====================
64995
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
65
64997
dc4555646e80 Merged revisions 85082 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64995
diff changeset
66 Buffer structures (or simply "buffers") are useful as a way to expose the
dc4555646e80 Merged revisions 85082 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64995
diff changeset
67 binary data from another object to the Python programmer. They can also be
dc4555646e80 Merged revisions 85082 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64995
diff changeset
68 used as a zero-copy slicing mechanism. Using their ability to reference a
dc4555646e80 Merged revisions 85082 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64995
diff changeset
69 block of memory, it is possible to expose any data to the Python programmer
dc4555646e80 Merged revisions 85082 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64995
diff changeset
70 quite easily. The memory could be a large, constant array in a C extension,
dc4555646e80 Merged revisions 85082 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64995
diff changeset
71 it could be a raw block of memory for manipulation before passing to an
dc4555646e80 Merged revisions 85082 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64995
diff changeset
72 operating system library, or it could be used to pass around structured data
dc4555646e80 Merged revisions 85082 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64995
diff changeset
73 in its native, in-memory format.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
74
64997
dc4555646e80 Merged revisions 85082 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64995
diff changeset
75 Contrary to most data types exposed by the Python interpreter, buffers
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
76 are not :c:type:`PyObject` pointers but rather simple C structures. This
64995
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
77 allows them to be created and copied very simply. When a generic wrapper
64999
c869ea07cd9d Merged revisions 85084 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64997
diff changeset
78 around a buffer is needed, a :ref:`memoryview <memoryview-objects>` object
64995
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
79 can be created.
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
80
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
81
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
82 .. c:type:: Py_buffer
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
83
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
84 .. c:member:: void *buf
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
85
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
86 A pointer to the start of the memory for the object.
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
87
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
88 .. c:member:: Py_ssize_t len
49216
af4c4cf3e01e shut up a few sphinx warnings
Benjamin Peterson <benjamin@python.org>
parents: 49205
diff changeset
89 :noindex:
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
90
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
91 The total length of the memory in bytes.
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
92
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
93 .. c:member:: int readonly
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
94
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
95 An indicator of whether the buffer is read only.
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
96
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
97 .. c:member:: const char *format
49216
af4c4cf3e01e shut up a few sphinx warnings
Benjamin Peterson <benjamin@python.org>
parents: 49205
diff changeset
98 :noindex:
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
99
53486
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53072
diff changeset
100 A *NULL* terminated string in :mod:`struct` module style syntax giving
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53072
diff changeset
101 the contents of the elements available through the buffer. If this is
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53072
diff changeset
102 *NULL*, ``"B"`` (unsigned bytes) is assumed.
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
103
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
104 .. c:member:: int ndim
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
105
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
106 The number of dimensions the memory represents as a multi-dimensional
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
107 array. If it is 0, :c:data:`strides` and :c:data:`suboffsets` must be
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
108 *NULL*.
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
109
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
110 .. c:member:: Py_ssize_t *shape
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
111
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
112 An array of :c:type:`Py_ssize_t`\s the length of :c:data:`ndim` giving the
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
113 shape of the memory as a multi-dimensional array. Note that
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
114 ``((*shape)[0] * ... * (*shape)[ndims-1])*itemsize`` should be equal to
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
115 :c:data:`len`.
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
116
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
117 .. c:member:: Py_ssize_t *strides
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
118
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
119 An array of :c:type:`Py_ssize_t`\s the length of :c:data:`ndim` giving the
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
120 number of bytes to skip to get to a new element in each dimension.
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
121
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
122 .. c:member:: Py_ssize_t *suboffsets
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
123
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
124 An array of :c:type:`Py_ssize_t`\s the length of :c:data:`ndim`. If these
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
125 suboffset numbers are greater than or equal to 0, then the value stored
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
126 along the indicated dimension is a pointer and the suboffset value
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
127 dictates how many bytes to add to the pointer after de-referencing. A
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
128 suboffset value that it negative indicates that no de-referencing should
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
129 occur (striding in a contiguous memory block).
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
130
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
131 Here is a function that returns a pointer to the element in an N-D array
52144
e5e64a0c4aa2 #5486: typos.
Georg Brandl <georg@python.org>
parents: 51944
diff changeset
132 pointed to by an N-dimensional index when there are both non-NULL strides
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
133 and suboffsets::
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
134
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
135 void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
136 Py_ssize_t *suboffsets, Py_ssize_t *indices) {
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
137 char *pointer = (char*)buf;
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
138 int i;
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
139 for (i = 0; i < ndim; i++) {
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
140 pointer += strides[i] * indices[i];
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
141 if (suboffsets[i] >=0 ) {
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
142 pointer = *((char**)pointer) + suboffsets[i];
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49780
diff changeset
143 }
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
144 }
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
145 return (void*)pointer;
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
146 }
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
147
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
148
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
149 .. c:member:: Py_ssize_t itemsize
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
150
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
151 This is a storage for the itemsize (in bytes) of each element of the
53486
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53072
diff changeset
152 shared memory. It is technically un-necessary as it can be obtained
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
153 using :c:func:`PyBuffer_SizeFromFormat`, however an exporter may know
53486
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53072
diff changeset
154 this information without parsing the format string and it is necessary
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53072
diff changeset
155 to know the itemsize for proper interpretation of striding. Therefore,
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53072
diff changeset
156 storing it is more convenient and faster.
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
157
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
158 .. c:member:: void *internal
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
159
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
160 This is for use internally by the exporting object. For example, this
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
161 might be re-cast as an integer by the exporter and used to store flags
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
162 about whether or not the shape, strides, and suboffsets arrays must be
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
163 freed when the buffer is released. The consumer should never alter this
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
164 value.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
165
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
166
64999
c869ea07cd9d Merged revisions 85084 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64997
diff changeset
167 Buffer-related functions
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
168 ========================
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
169
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
170
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
171 .. c:function:: int PyObject_CheckBuffer(PyObject *obj)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
172
64995
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
173 Return 1 if *obj* supports the buffer interface otherwise 0. When 1 is
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
174 returned, it doesn't guarantee that :c:func:`PyObject_GetBuffer` will
64995
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
175 succeed.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
176
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
177
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
178 .. c:function:: int PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags)
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
179
64995
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
180 Export a view over some internal data from the target object *obj*.
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
181 *obj* must not be NULL, and *view* must point to an existing
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
182 :c:type:`Py_buffer` structure allocated by the caller (most uses of
64995
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
183 this function will simply declare a local variable of type
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
184 :c:type:`Py_buffer`). The *flags* argument is a bit field indicating
64995
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
185 what kind of buffer is requested. The buffer interface allows
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
186 for complicated memory layout possibilities; however, some callers
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
187 won't want to handle all the complexity and instead request a simple
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
188 view of the target object (using :c:macro:`PyBUF_SIMPLE` for a read-only
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
189 view and :c:macro:`PyBUF_WRITABLE` for a read-write view).
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
190
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
191 Some exporters may not be able to share memory in every possible way and
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
192 may need to raise errors to signal to some consumers that something is
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
193 just not possible. These errors should be a :exc:`BufferError` unless
53486
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53072
diff changeset
194 there is another error that is actually causing the problem. The
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53072
diff changeset
195 exporter can use flags information to simplify how much of the
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
196 :c:data:`Py_buffer` structure is filled in with non-default values and/or
53486
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53072
diff changeset
197 raise an error if the object can't support a simpler view of its memory.
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
198
64995
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
199 On success, 0 is returned and the *view* structure is filled with useful
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
200 values. On error, -1 is returned and an exception is raised; the *view*
5522c6b2af87 Merged revisions 85080 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 64981
diff changeset
201 is left in an undefined state.
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
202
65033
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
203 The following are the possible values to the *flags* arguments.
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
204
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
205 .. c:macro:: PyBUF_SIMPLE
65033
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
206
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
207 This is the default flag. The returned buffer exposes a read-only
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
208 memory area. The format of data is assumed to be raw unsigned bytes,
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
209 without any particular structure. This is a "stand-alone" flag
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
210 constant. It never needs to be '|'d to the others. The exporter will
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
211 raise an error if it cannot provide such a contiguous buffer of bytes.
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
212
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
213 .. c:macro:: PyBUF_WRITABLE
65033
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
214
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
215 Like :c:macro:`PyBUF_SIMPLE`, but the returned buffer is writable. If
65033
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
216 the exporter doesn't support writable buffers, an error is raised.
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
217
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
218 .. c:macro:: PyBUF_STRIDES
65033
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
219
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
220 This implies :c:macro:`PyBUF_ND`. The returned buffer must provide
65033
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
221 strides information (i.e. the strides cannot be NULL). This would be
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
222 used when the consumer can handle strided, discontiguous arrays.
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
223 Handling strides automatically assumes you can handle shape. The
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
224 exporter can raise an error if a strided representation of the data is
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
225 not possible (i.e. without the suboffsets).
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
226
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
227 .. c:macro:: PyBUF_ND
65033
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
228
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
229 The returned buffer must provide shape information. The memory will be
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
230 assumed C-style contiguous (last dimension varies the fastest). The
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
231 exporter may raise an error if it cannot provide this kind of
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
232 contiguous buffer. If this is not given then shape will be *NULL*.
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
233
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
234 .. c:macro:: PyBUF_C_CONTIGUOUS
65032
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
235 PyBUF_F_CONTIGUOUS
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
236 PyBUF_ANY_CONTIGUOUS
65033
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
237
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
238 These flags indicate that the contiguity returned buffer must be
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
239 respectively, C-contiguous (last dimension varies the fastest), Fortran
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
240 contiguous (first dimension varies the fastest) or either one. All of
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
241 these flags imply :c:macro:`PyBUF_STRIDES` and guarantee that the
65033
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
242 strides buffer info structure will be filled in correctly.
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
243
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
244 .. c:macro:: PyBUF_INDIRECT
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
245
65033
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
246 This flag indicates the returned buffer must have suboffsets
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
247 information (which can be NULL if no suboffsets are needed). This can
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
248 be used when the consumer can handle indirect array referencing implied
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
249 by these suboffsets. This implies :c:macro:`PyBUF_STRIDES`.
65033
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
250
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
251 .. c:macro:: PyBUF_FORMAT
65033
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
252
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
253 The returned buffer must have true format information if this flag is
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
254 provided. This would be used when the consumer is going to be checking
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
255 for what 'kind' of data is actually stored. An exporter should always
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
256 be able to provide this information if requested. If format is not
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
257 explicitly requested then the format must be returned as *NULL* (which
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
258 means ``'B'``, or unsigned bytes).
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
259
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
260 .. c:macro:: PyBUF_STRIDED
65033
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
261
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
262 This is equivalent to ``(PyBUF_STRIDES | PyBUF_WRITABLE)``.
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
263
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
264 .. c:macro:: PyBUF_STRIDED_RO
65033
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
265
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
266 This is equivalent to ``(PyBUF_STRIDES)``.
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
267
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
268 .. c:macro:: PyBUF_RECORDS
65033
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
269
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
270 This is equivalent to ``(PyBUF_STRIDES | PyBUF_FORMAT |
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
271 PyBUF_WRITABLE)``.
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
272
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
273 .. c:macro:: PyBUF_RECORDS_RO
65033
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
274
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
275 This is equivalent to ``(PyBUF_STRIDES | PyBUF_FORMAT)``.
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
276
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
277 .. c:macro:: PyBUF_FULL
65033
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
278
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
279 This is equivalent to ``(PyBUF_INDIRECT | PyBUF_FORMAT |
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
280 PyBUF_WRITABLE)``.
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
281
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
282 .. c:macro:: PyBUF_FULL_RO
65033
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
283
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
284 This is equivalent to ``(PyBUF_INDIRECT | PyBUF_FORMAT)``.
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
285
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
286 .. c:macro:: PyBUF_CONTIG
65033
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
287
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
288 This is equivalent to ``(PyBUF_ND | PyBUF_WRITABLE)``.
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
289
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
290 .. c:macro:: PyBUF_CONTIG_RO
65033
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
291
cb2fbb5e6409 Merged revisions 85132 via svnmerge from
Georg Brandl <georg@python.org>
parents: 64999
diff changeset
292 This is equivalent to ``(PyBUF_ND)``.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
293
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
294
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
295 .. c:function:: void PyBuffer_Release(Py_buffer *view)
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
296
62200
6f3855038919 Merged revisions 81851 via svnmerge from
Brian Curtin <brian.curtin@gmail.com>
parents: 55729
diff changeset
297 Release the buffer *view*. This should be called when the buffer is no
6f3855038919 Merged revisions 81851 via svnmerge from
Brian Curtin <brian.curtin@gmail.com>
parents: 55729
diff changeset
298 longer being used as it may free memory from it.
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
299
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
300
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
301 .. c:function:: Py_ssize_t PyBuffer_SizeFromFormat(const char *)
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
302
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
303 Return the implied :c:data:`~Py_buffer.itemsize` from the struct-stype
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
304 :c:data:`~Py_buffer.format`.
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
305
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
306
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
307 .. c:function:: int PyBuffer_IsContiguous(Py_buffer *view, char fortran)
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
308
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
309 Return 1 if the memory defined by the *view* is C-style (*fortran* is
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
310 ``'C'``) or Fortran-style (*fortran* is ``'F'``) contiguous or either one
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
311 (*fortran* is ``'A'``). Return 0 otherwise.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
312
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
313
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
314 .. c:function:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t *shape, Py_ssize_t *strides, Py_ssize_t itemsize, char fortran)
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
315
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
316 Fill the *strides* array with byte-strides of a contiguous (C-style if
70223
68134a384c73 #12072: add missing parenthesis in the doc. Patch by Sandro Tosi.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68423
diff changeset
317 *fortran* is ``'C'`` or Fortran-style if *fortran* is ``'F'``) array of the
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
318 given shape with the given number of bytes per element.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
319
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
320
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
321 .. c:function:: int PyBuffer_FillInfo(Py_buffer *view, PyObject *obj, void *buf, Py_ssize_t len, int readonly, int infoflags)
49205
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
322
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
323 Fill in a buffer-info structure, *view*, correctly for an exporter that can
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
324 only share a contiguous chunk of memory of "unsigned bytes" of the given
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
325 length. Return 0 on success and -1 (with raising an error) on error.
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right...
Benjamin Peterson <benjamin@python.org>
parents: 44812
diff changeset
326