Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/buffer.rst @ 66807:d28126ebd60d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Entries for datetime, callable, and collections.Counter.
author Raymond Hettinger <python@rcn.com>
date Thu, 09 Dec 2010 16:41:54 +0000
parents 521eac31a893
children 5bfa436a287b
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
64996
4cf77d193f57 Buffers are not sequence objects (!). Put them in the abstract objects layers
Antoine Pitrou <solipsis@pitrou.net>
parents: 64994
diff changeset
5 Buffer Protocol
4cf77d193f57 Buffers are not sequence objects (!). Put them in the abstract objects layers
Antoine Pitrou <solipsis@pitrou.net>
parents: 64994
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
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
15 Python objects implemented in C can export a "buffer interface." These
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
16 functions can be used by an object to expose its data in a raw, byte-oriented
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
17 format. Clients of the object can use the buffer interface to access 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
18 object data directly, without needing to copy it first.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
19
64994
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
20 Examples of objects that support the buffer interface are :class:`bytes`,
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
21 :class:`bytearray` and :class:`array.array`. The bytes and bytearray objects
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
22 exposes their bytes contents in the buffer interface's byte-oriented form.
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
23 An :class:`array.array` can also expose its contents, but it should be noted
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
24 that array elements may be multi-byte values.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
25
64994
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
26 An example consumer of the buffer interface is the :meth:`~io.BufferedIOBase.write`
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
27 method of file objects: any object that can export a series of bytes through
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
28 the buffer interface can be written to a file. While :meth:`write` only
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
29 needs read-only access to the internal contents of the object passed to it,
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
30 other methods such as :meth:`~io.BufferedIOBase.readinto` need write access
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
31 to the contents of their argument. The buffer interface allows objects to
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
32 selectively allow or reject exporting of read-write and read-only buffers.
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
33
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
34 There are two ways for a consumer of the buffer interface to acquire a buffer
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
35 over a target object:
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
36
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
37 * call :c:func:`PyObject_GetBuffer` with the right parameters;
64994
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
38
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
39 * call :c:func:`PyArg_ParseTuple` (or one of its siblings) with one of the
64994
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
40 ``y*``, ``w*`` or ``s*`` :ref:`format codes <arg-parsing>`.
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
41
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
42 In both cases, :c:func:`PyBuffer_Release` must be called when the buffer
64994
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
43 isn't needed anymore. Failure to do so could lead to various issues such as
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
44 resource leaks.
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
45
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
46
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
47 .. index:: single: PyBufferProcs
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
48
64994
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
49 How the buffer interface is exposed by a type object is described in the
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
50 section :ref:`buffer-structs`, under the description for :c:type:`PyBufferProcs`.
64994
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
51
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
52
64996
4cf77d193f57 Buffers are not sequence objects (!). Put them in the abstract objects layers
Antoine Pitrou <solipsis@pitrou.net>
parents: 64994
diff changeset
53 The buffer structure
4cf77d193f57 Buffers are not sequence objects (!). Put them in the abstract objects layers
Antoine Pitrou <solipsis@pitrou.net>
parents: 64994
diff changeset
54 ====================
64994
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
55
64996
4cf77d193f57 Buffers are not sequence objects (!). Put them in the abstract objects layers
Antoine Pitrou <solipsis@pitrou.net>
parents: 64994
diff changeset
56 Buffer structures (or simply "buffers") are useful as a way to expose the
4cf77d193f57 Buffers are not sequence objects (!). Put them in the abstract objects layers
Antoine Pitrou <solipsis@pitrou.net>
parents: 64994
diff changeset
57 binary data from another object to the Python programmer. They can also be
4cf77d193f57 Buffers are not sequence objects (!). Put them in the abstract objects layers
Antoine Pitrou <solipsis@pitrou.net>
parents: 64994
diff changeset
58 used as a zero-copy slicing mechanism. Using their ability to reference a
4cf77d193f57 Buffers are not sequence objects (!). Put them in the abstract objects layers
Antoine Pitrou <solipsis@pitrou.net>
parents: 64994
diff changeset
59 block of memory, it is possible to expose any data to the Python programmer
4cf77d193f57 Buffers are not sequence objects (!). Put them in the abstract objects layers
Antoine Pitrou <solipsis@pitrou.net>
parents: 64994
diff changeset
60 quite easily. The memory could be a large, constant array in a C extension,
4cf77d193f57 Buffers are not sequence objects (!). Put them in the abstract objects layers
Antoine Pitrou <solipsis@pitrou.net>
parents: 64994
diff changeset
61 it could be a raw block of memory for manipulation before passing to an
4cf77d193f57 Buffers are not sequence objects (!). Put them in the abstract objects layers
Antoine Pitrou <solipsis@pitrou.net>
parents: 64994
diff changeset
62 operating system library, or it could be used to pass around structured data
4cf77d193f57 Buffers are not sequence objects (!). Put them in the abstract objects layers
Antoine Pitrou <solipsis@pitrou.net>
parents: 64994
diff changeset
63 in its native, in-memory format.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
64
64996
4cf77d193f57 Buffers are not sequence objects (!). Put them in the abstract objects layers
Antoine Pitrou <solipsis@pitrou.net>
parents: 64994
diff changeset
65 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
66 are not :c:type:`PyObject` pointers but rather simple C structures. This
64994
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
67 allows them to be created and copied very simply. When a generic wrapper
64998
06f5e190855a Give a dedicated page to memoryview objects, so that they can be part
Antoine Pitrou <solipsis@pitrou.net>
parents: 64996
diff changeset
68 around a buffer is needed, a :ref:`memoryview <memoryview-objects>` object
64994
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
69 can be created.
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
70
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
71
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
72 .. 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
73
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
74 .. 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
75
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
76 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
77
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
78 .. c:member:: Py_ssize_t len
49216
af4c4cf3e01e shut up a few sphinx warnings
Benjamin Peterson <benjamin@python.org>
parents: 49205
diff changeset
79 :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
80
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
81 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
82
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
83 .. 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
84
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 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
86
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
87 .. c:member:: const char *format
49216
af4c4cf3e01e shut up a few sphinx warnings
Benjamin Peterson <benjamin@python.org>
parents: 49205
diff changeset
88 :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
89
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
90 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
91 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
92 *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
93
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
94 .. 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
95
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 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
97 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
98 *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
99
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
100 .. c:member:: Py_ssize_t *shape
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
101
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
102 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
103 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
104 ``((*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
105 :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
106
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
107 .. 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
108
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
109 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
110 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
111
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
112 .. 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
113
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
114 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
115 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
116 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
117 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
118 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
119 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
120
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 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
122 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
123 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
124
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 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
126 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
127 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
128 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
129 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
130 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
131 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
132 pointer = *((char**)pointer) + suboffsets[i];
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49780
diff changeset
133 }
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
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 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
136 }
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
137
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
138
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
139 .. c:member:: Py_ssize_t itemsize
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
140
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
141 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
142 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
143 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
144 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
145 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
146 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
147
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
148 .. 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
149
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
150 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
151 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
152 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
153 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
154 value.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
155
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
156
64998
06f5e190855a Give a dedicated page to memoryview objects, so that they can be part
Antoine Pitrou <solipsis@pitrou.net>
parents: 64996
diff changeset
157 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
158 ========================
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
159
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
160
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
161 .. c:function:: int PyObject_CheckBuffer(PyObject *obj)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
162
64994
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
163 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
164 returned, it doesn't guarantee that :c:func:`PyObject_GetBuffer` will
64994
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
165 succeed.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
166
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
167
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
168 .. 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
169
64994
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
170 Export a view over some internal data from the target object *obj*.
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
171 *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
172 :c:type:`Py_buffer` structure allocated by the caller (most uses of
64994
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
173 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
174 :c:type:`Py_buffer`). The *flags* argument is a bit field indicating
64994
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
175 what kind of buffer is requested. The buffer interface allows
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
176 for complicated memory layout possibilities; however, some callers
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
177 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
178 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
179 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
180
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
181 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
182 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
183 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
184 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
185 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
186 :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
187 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
188
64994
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
189 On success, 0 is returned and the *view* structure is filled with useful
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
190 values. On error, -1 is returned and an exception is raised; the *view*
d12d550ebf34 Various improvements to the docs of the buffer API
Antoine Pitrou <solipsis@pitrou.net>
parents: 64980
diff changeset
191 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
192
65032
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
193 The following are the possible values to the *flags* arguments.
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
194
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
195 .. c:macro:: PyBUF_SIMPLE
65032
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
196
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
197 This is the default flag. The returned buffer exposes a read-only
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
198 memory area. The format of data is assumed to be raw unsigned bytes,
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
199 without any particular structure. This is a "stand-alone" flag
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
200 constant. It never needs to be '|'d to the others. The exporter will
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
201 raise an error if it cannot provide such a contiguous buffer of bytes.
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
202
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
203 .. c:macro:: PyBUF_WRITABLE
65032
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
204
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
205 Like :c:macro:`PyBUF_SIMPLE`, but the returned buffer is writable. If
65032
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
206 the exporter doesn't support writable buffers, an error is raised.
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
207
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
208 .. c:macro:: PyBUF_STRIDES
65032
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
209
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
210 This implies :c:macro:`PyBUF_ND`. The returned buffer must provide
65032
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
211 strides information (i.e. the strides cannot be NULL). This would be
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
212 used when the consumer can handle strided, discontiguous arrays.
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
213 Handling strides automatically assumes you can handle shape. The
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
214 exporter can raise an error if a strided representation of the data is
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
215 not possible (i.e. without the suboffsets).
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
216
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
217 .. c:macro:: PyBUF_ND
65032
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
218
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
219 The returned buffer must provide shape information. The memory will be
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
220 assumed C-style contiguous (last dimension varies the fastest). The
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
221 exporter may raise an error if it cannot provide this kind of
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
222 contiguous buffer. If this is not given then shape will be *NULL*.
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
223
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
224 .. c:macro:: PyBUF_C_CONTIGUOUS
65032
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
225 PyBUF_F_CONTIGUOUS
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
226 PyBUF_ANY_CONTIGUOUS
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
227
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
228 These flags indicate that the contiguity returned buffer must be
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
229 respectively, C-contiguous (last dimension varies the fastest), Fortran
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
230 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
231 these flags imply :c:macro:`PyBUF_STRIDES` and guarantee that the
65032
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
232 strides buffer info structure will be filled in correctly.
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
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_INDIRECT
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
235
65032
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
236 This flag indicates the returned buffer must have suboffsets
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
237 information (which can be NULL if no suboffsets are needed). This can
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
238 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
239 by these suboffsets. This implies :c:macro:`PyBUF_STRIDES`.
65032
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
240
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
241 .. c:macro:: PyBUF_FORMAT
65032
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
242
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
243 The returned buffer must have true format information if this flag is
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
244 provided. This would be used when the consumer is going to be checking
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
245 for what 'kind' of data is actually stored. An exporter should always
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
246 be able to provide this information if requested. If format is not
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
247 explicitly requested then the format must be returned as *NULL* (which
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
248 means ``'B'``, or unsigned bytes).
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
249
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
250 .. c:macro:: PyBUF_STRIDED
65032
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
251
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
252 This is equivalent to ``(PyBUF_STRIDES | PyBUF_WRITABLE)``.
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
253
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
254 .. c:macro:: PyBUF_STRIDED_RO
65032
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
255
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
256 This is equivalent to ``(PyBUF_STRIDES)``.
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
257
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
258 .. c:macro:: PyBUF_RECORDS
65032
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
259
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
260 This is equivalent to ``(PyBUF_STRIDES | PyBUF_FORMAT |
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
261 PyBUF_WRITABLE)``.
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
262
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
263 .. c:macro:: PyBUF_RECORDS_RO
65032
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
264
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
265 This is equivalent to ``(PyBUF_STRIDES | PyBUF_FORMAT)``.
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
266
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
267 .. c:macro:: PyBUF_FULL
65032
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
268
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
269 This is equivalent to ``(PyBUF_INDIRECT | PyBUF_FORMAT |
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
270 PyBUF_WRITABLE)``.
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
271
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
272 .. c:macro:: PyBUF_FULL_RO
65032
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
273
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
274 This is equivalent to ``(PyBUF_INDIRECT | PyBUF_FORMAT)``.
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
275
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
276 .. c:macro:: PyBUF_CONTIG
65032
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
277
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
278 This is equivalent to ``(PyBUF_ND | PyBUF_WRITABLE)``.
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
279
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
280 .. c:macro:: PyBUF_CONTIG_RO
65032
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
281
282c77db3d38 Fix weird markup that caused latex to fail.
Georg Brandl <georg@python.org>
parents: 64998
diff changeset
282 This is equivalent to ``(PyBUF_ND)``.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
283
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
284
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
285 .. 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
286
62199
d32b0e80faac Fix #8946. Extra PyObject* parameter documented which doesn't exist.
Brian Curtin <brian.curtin@gmail.com>
parents: 57956
diff changeset
287 Release the buffer *view*. This should be called when the buffer is no
d32b0e80faac Fix #8946. Extra PyObject* parameter documented which doesn't exist.
Brian Curtin <brian.curtin@gmail.com>
parents: 57956
diff changeset
288 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
289
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
290
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
291 .. 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
292
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
293 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
294 :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
295
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
296
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
297 .. c:function:: int PyObject_CopyToObject(PyObject *obj, void *buf, Py_ssize_t len, 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
298
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
299 Copy *len* bytes of data pointed to by the contiguous chunk of memory
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53072
diff changeset
300 pointed to by *buf* into the buffer exported by obj. The buffer must of
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53072
diff changeset
301 course be writable. Return 0 on success and return -1 and raise an error
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53072
diff changeset
302 on failure. If the object does not have a writable buffer, then an error
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53072
diff changeset
303 is raised. If *fortran* is ``'F'``, then if the object 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
304 multi-dimensional, then the data will be copied into the array in
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53072
diff changeset
305 Fortran-style (first dimension varies the fastest). If *fortran* 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
306 ``'C'``, then the data will be copied into the array in C-style (last
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53072
diff changeset
307 dimension varies the fastest). If *fortran* is ``'A'``, then it does not
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53072
diff changeset
308 matter and the copy will be made in whatever way is more efficient.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
309
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
310
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
311 .. 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
312
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 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
314 ``'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
315 (*fortran* is ``'A'``). Return 0 otherwise.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
316
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
317
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
318 .. 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
319
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
320 Fill the *strides* array with byte-strides of a contiguous (C-style if
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
321 *fortran* is ``'C'`` or Fortran-style if *fortran* is ``'F'`` array of the
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 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
323
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
324
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 65032
diff changeset
325 .. 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
326
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
327 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
328 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
329 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
330