Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/buffer.rst @ 58765:2ba7677bfa95 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
testCopysign was defined twice in test_math; combine the definitions
author Mark Dickinson <dickinsm@gmail.com>
date Sat, 06 Feb 2010 23:11:25 +0000
parents 525f67beeb89
children d1bee7cf6c2f
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. highlightlang:: c
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 .. _bufferobjects:
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
4
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
5 Buffers and Memoryview Objects
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
6 ------------------------------
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 .. sectionauthor:: Greg Stein <gstein@lyra.org>
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
9 .. sectionauthor:: Benjamin Peterson
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
11
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 .. index::
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
13 object: buffer
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 single: buffer interface
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
15
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
16 Python objects implemented in C can export a group of functions called the
53422
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
17 "buffer interface." These functions can be used by an object to expose its
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
18 data in a raw, byte-oriented format. Clients of the object can use the buffer
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
19 interface to access the object data directly, without needing to copy it
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
20 first.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
21
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
22 Two examples of objects that support the buffer interface are strings and
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
23 arrays. The string object exposes the character contents in the buffer
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
24 interface's byte-oriented form. An array can also expose its contents, but it
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
25 should be noted that array elements may be multi-byte values.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
26
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
27 An example user of the buffer interface is the file object's :meth:`write`
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
28 method. Any object that can export a series of bytes through the buffer
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
29 interface can be written to a file. There are a number of format codes to
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 :cfunc:`PyArg_ParseTuple` that operate against an object's buffer interface,
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 returning data from the target object.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
32
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
33 Starting from version 1.6, Python has been providing Python-level buffer
55449
bbd1d90d158a builtin -> built-in.
Georg Brandl <georg@python.org>
parents: 54462
diff changeset
34 objects and a C-level buffer API so that any built-in or used-defined type can
53422
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
35 expose its characteristics. Both, however, have been deprecated because of
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
36 various shortcomings, and have been officially removed in Python 3.0 in favour
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
37 of a new C-level buffer API and a new Python-level object named
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
38 :class:`memoryview`.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
39
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
40 The new buffer API has been backported to Python 2.6, and the
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
41 :class:`memoryview` object has been backported to Python 2.7. It is strongly
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
42 advised to use them rather than the old APIs, unless you are blocked from
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
43 doing so for compatibility reasons.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
44
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
45
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
46 The new-style Py_buffer struct
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
47 ==============================
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
48
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
49
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
50 .. ctype:: Py_buffer
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
51
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
52 .. cmember:: void *buf
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
53
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
54 A pointer to the start of the memory for the object.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
55
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
56 .. cmember:: Py_ssize_t len
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
57 :noindex:
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
58
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
59 The total length of the memory in bytes.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
60
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
61 .. cmember:: int readonly
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
62
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
63 An indicator of whether the buffer is read only.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
64
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
65 .. cmember:: const char *format
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
66 :noindex:
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
67
53422
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
68 A *NULL* terminated string in :mod:`struct` module style syntax giving
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
69 the contents of the elements available through the buffer. If this is
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
70 *NULL*, ``"B"`` (unsigned bytes) is assumed.
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
71
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
72 .. cmember:: int ndim
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
73
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
74 The number of dimensions the memory represents as a multi-dimensional
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
75 array. If it is 0, :cdata:`strides` and :cdata:`suboffsets` must be
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
76 *NULL*.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
77
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
78 .. cmember:: Py_ssize_t *shape
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
79
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
80 An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim` giving the
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
81 shape of the memory as a multi-dimensional array. Note that
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
82 ``((*shape)[0] * ... * (*shape)[ndims-1])*itemsize`` should be equal to
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
83 :cdata:`len`.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
84
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
85 .. cmember:: Py_ssize_t *strides
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
86
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
87 An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim` giving the
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
88 number of bytes to skip to get to a new element in each dimension.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
89
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
90 .. cmember:: Py_ssize_t *suboffsets
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
91
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
92 An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim`. If these
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
93 suboffset numbers are greater than or equal to 0, then the value stored
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
94 along the indicated dimension is a pointer and the suboffset value
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
95 dictates how many bytes to add to the pointer after de-referencing. A
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
96 suboffset value that it negative indicates that no de-referencing should
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
97 occur (striding in a contiguous memory block).
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
98
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
99 Here is a function that returns a pointer to the element in an N-D array
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
100 pointed to by an N-dimesional index when there are both non-NULL strides
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
101 and suboffsets::
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
102
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
103 void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
104 Py_ssize_t *suboffsets, Py_ssize_t *indices) {
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
105 char *pointer = (char*)buf;
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
106 int i;
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
107 for (i = 0; i < ndim; i++) {
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
108 pointer += strides[i] * indices[i];
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
109 if (suboffsets[i] >=0 ) {
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
110 pointer = *((char**)pointer) + suboffsets[i];
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
111 }
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
112 }
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
113 return (void*)pointer;
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
114 }
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
115
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
116
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
117 .. cmember:: Py_ssize_t itemsize
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
118
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
119 This is a storage for the itemsize (in bytes) of each element of the
53422
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
120 shared memory. It is technically un-necessary as it can be obtained
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
121 using :cfunc:`PyBuffer_SizeFromFormat`, however an exporter may know
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
122 this information without parsing the format string and it is necessary
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
123 to know the itemsize for proper interpretation of striding. Therefore,
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
124 storing it is more convenient and faster.
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
125
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
126 .. cmember:: void *internal
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
127
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
128 This is for use internally by the exporting object. For example, this
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
129 might be re-cast as an integer by the exporter and used to store flags
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
130 about whether or not the shape, strides, and suboffsets arrays must be
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
131 freed when the buffer is released. The consumer should never alter this
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
132 value.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
133
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
134
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
135 Buffer related functions
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
136 ========================
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
137
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
138
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
139 .. cfunction:: int PyObject_CheckBuffer(PyObject *obj)
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
140
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
141 Return 1 if *obj* supports the buffer interface otherwise 0.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
142
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
143
54462
5dec7247b249 fix signature
Benjamin Peterson <benjamin@python.org>
parents: 53422
diff changeset
144 .. cfunction:: int PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags)
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
145
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
146 Export *obj* into a :ctype:`Py_buffer`, *view*. These arguments must
53422
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
147 never be *NULL*. The *flags* argument is a bit field indicating what
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
148 kind of buffer the caller is prepared to deal with and therefore what
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
149 kind of buffer the exporter is allowed to return. The buffer interface
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
150 allows for complicated memory sharing possibilities, but some caller may
55561
7b66cd02d60b #6658: fix two typos.
Georg Brandl <georg@python.org>
parents: 55449
diff changeset
151 not be able to handle all the complexity but may want to see if the
53422
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
152 exporter will let them take a simpler view to its memory.
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
153
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
154 Some exporters may not be able to share memory in every possible way and
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
155 may need to raise errors to signal to some consumers that something is
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
156 just not possible. These errors should be a :exc:`BufferError` unless
53422
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
157 there is another error that is actually causing the problem. The
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
158 exporter can use flags information to simplify how much of the
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
159 :cdata:`Py_buffer` structure is filled in with non-default values and/or
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
160 raise an error if the object can't support a simpler view of its memory.
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
161
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
162 0 is returned on success and -1 on error.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
163
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
164 The following table gives possible values to the *flags* arguments.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
165
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
166 +------------------------------+---------------------------------------------------+
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
167 | Flag | Description |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
168 +==============================+===================================================+
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
169 | :cmacro:`PyBUF_SIMPLE` | This is the default flag state. The returned |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
170 | | buffer may or may not have writable memory. The |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
171 | | format of the data will be assumed to be unsigned |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
172 | | bytes. This is a "stand-alone" flag constant. It |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
173 | | never needs to be '|'d to the others. The exporter|
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
174 | | will raise an error if it cannot provide such a |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
175 | | contiguous buffer of bytes. |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
176 | | |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
177 +------------------------------+---------------------------------------------------+
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
178 | :cmacro:`PyBUF_WRITABLE` | The returned buffer must be writable. If it is |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
179 | | not writable, then raise an error. |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
180 +------------------------------+---------------------------------------------------+
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
181 | :cmacro:`PyBUF_STRIDES` | This implies :cmacro:`PyBUF_ND`. The returned |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
182 | | buffer must provide strides information (i.e. the |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
183 | | strides cannot be NULL). This would be used when |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
184 | | the consumer can handle strided, discontiguous |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
185 | | arrays. Handling strides automatically assumes |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
186 | | you can handle shape. The exporter can raise an |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
187 | | error if a strided representation of the data is |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
188 | | not possible (i.e. without the suboffsets). |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
189 | | |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
190 +------------------------------+---------------------------------------------------+
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
191 | :cmacro:`PyBUF_ND` | The returned buffer must provide shape |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
192 | | information. The memory will be assumed C-style |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
193 | | contiguous (last dimension varies the |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
194 | | fastest). The exporter may raise an error if it |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
195 | | cannot provide this kind of contiguous buffer. If |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
196 | | this is not given then shape will be *NULL*. |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
197 | | |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
198 | | |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
199 | | |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
200 +------------------------------+---------------------------------------------------+
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
201 |:cmacro:`PyBUF_C_CONTIGUOUS` | These flags indicate that the contiguity returned |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
202 |:cmacro:`PyBUF_F_CONTIGUOUS` | buffer must be respectively, C-contiguous (last |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
203 |:cmacro:`PyBUF_ANY_CONTIGUOUS`| dimension varies the fastest), Fortran contiguous |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
204 | | (first dimension varies the fastest) or either |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
205 | | one. All of these flags imply |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
206 | | :cmacro:`PyBUF_STRIDES` and guarantee that the |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
207 | | strides buffer info structure will be filled in |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
208 | | correctly. |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
209 | | |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
210 +------------------------------+---------------------------------------------------+
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
211 | :cmacro:`PyBUF_INDIRECT` | This flag indicates the returned buffer must have |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
212 | | suboffsets information (which can be NULL if no |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
213 | | suboffsets are needed). This can be used when |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
214 | | the consumer can handle indirect array |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
215 | | referencing implied by these suboffsets. This |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
216 | | implies :cmacro:`PyBUF_STRIDES`. |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
217 | | |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
218 | | |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
219 | | |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
220 +------------------------------+---------------------------------------------------+
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
221 | :cmacro:`PyBUF_FORMAT` | The returned buffer must have true format |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
222 | | information if this flag is provided. This would |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
223 | | be used when the consumer is going to be checking |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
224 | | for what 'kind' of data is actually stored. An |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
225 | | exporter should always be able to provide this |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
226 | | information if requested. If format is not |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
227 | | explicitly requested then the format must be |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
228 | | returned as *NULL* (which means ``'B'``, or |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
229 | | unsigned bytes) |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
230 +------------------------------+---------------------------------------------------+
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
231 | :cmacro:`PyBUF_STRIDED` | This is equivalent to ``(PyBUF_STRIDES | |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
232 | | PyBUF_WRITABLE)``. |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
233 +------------------------------+---------------------------------------------------+
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
234 | :cmacro:`PyBUF_STRIDED_RO` | This is equivalent to ``(PyBUF_STRIDES)``. |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
235 | | |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
236 +------------------------------+---------------------------------------------------+
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
237 | :cmacro:`PyBUF_RECORDS` | This is equivalent to ``(PyBUF_STRIDES | |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
238 | | PyBUF_FORMAT | PyBUF_WRITABLE)``. |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
239 +------------------------------+---------------------------------------------------+
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
240 | :cmacro:`PyBUF_RECORDS_RO` | This is equivalent to ``(PyBUF_STRIDES | |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
241 | | PyBUF_FORMAT)``. |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
242 +------------------------------+---------------------------------------------------+
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
243 | :cmacro:`PyBUF_FULL` | This is equivalent to ``(PyBUF_INDIRECT | |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
244 | | PyBUF_FORMAT | PyBUF_WRITABLE)``. |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
245 +------------------------------+---------------------------------------------------+
52990
b1404a868d8f Remove redundant backtick.
Georg Brandl <georg@python.org>
parents: 52749
diff changeset
246 | :cmacro:`PyBUF_FULL_RO` | This is equivalent to ``(PyBUF_INDIRECT | |
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
247 | | PyBUF_FORMAT)``. |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
248 +------------------------------+---------------------------------------------------+
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
249 | :cmacro:`PyBUF_CONTIG` | This is equivalent to ``(PyBUF_ND | |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
250 | | PyBUF_WRITABLE)``. |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
251 +------------------------------+---------------------------------------------------+
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
252 | :cmacro:`PyBUF_CONTIG_RO` | This is equivalent to ``(PyBUF_ND)``. |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
253 | | |
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
254 +------------------------------+---------------------------------------------------+
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
255
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
256
55803
9ffa8f887750 #6821: fix signature of PyBuffer_Release().
Georg Brandl <georg@python.org>
parents: 55561
diff changeset
257 .. cfunction:: void PyBuffer_Release(Py_buffer *view)
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
258
55803
9ffa8f887750 #6821: fix signature of PyBuffer_Release().
Georg Brandl <georg@python.org>
parents: 55561
diff changeset
259 Release the buffer *view*. This should be called when the buffer
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
260 is no longer being used as it may free memory from it.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
261
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
262
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
263 .. cfunction:: Py_ssize_t PyBuffer_SizeFromFormat(const char *)
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
264
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
265 Return the implied :cdata:`~Py_buffer.itemsize` from the struct-stype
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
266 :cdata:`~Py_buffer.format`.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
267
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
268
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
269 .. cfunction:: int PyObject_CopyToObject(PyObject *obj, void *buf, Py_ssize_t len, char fortran)
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
270
53422
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
271 Copy *len* bytes of data pointed to by the contiguous chunk of memory
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
272 pointed to by *buf* into the buffer exported by obj. The buffer must of
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
273 course be writable. Return 0 on success and return -1 and raise an error
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
274 on failure. If the object does not have a writable buffer, then an error
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
275 is raised. If *fortran* is ``'F'``, then if the object is
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
276 multi-dimensional, then the data will be copied into the array in
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
277 Fortran-style (first dimension varies the fastest). If *fortran* is
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
278 ``'C'``, then the data will be copied into the array in C-style (last
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
279 dimension varies the fastest). If *fortran* is ``'A'``, then it does not
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
280 matter and the copy will be made in whatever way is more efficient.
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
281
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
282
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
283 .. cfunction:: int PyBuffer_IsContiguous(Py_buffer *view, char fortran)
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
284
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
285 Return 1 if the memory defined by the *view* is C-style (*fortran* is
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
286 ``'C'``) or Fortran-style (*fortran* is ``'F'``) contiguous or either one
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
287 (*fortran* is ``'A'``). Return 0 otherwise.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
288
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
289
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
290 .. cfunction:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t *shape, Py_ssize_t *strides, Py_ssize_t itemsize, char fortran)
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
291
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
292 Fill the *strides* array with byte-strides of a contiguous (C-style if
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
293 *fortran* is ``'C'`` or Fortran-style if *fortran* is ``'F'`` array of the
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
294 given shape with the given number of bytes per element.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
295
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
296
57954
525f67beeb89 #7577: fix signature of PyBuffer_FillInfo().
Georg Brandl <georg@python.org>
parents: 55803
diff changeset
297 .. cfunction:: int PyBuffer_FillInfo(Py_buffer *view, PyObject *obj, void *buf, Py_ssize_t len, int readonly, int infoflags)
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
298
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
299 Fill in a buffer-info structure, *view*, correctly for an exporter that can
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
300 only share a contiguous chunk of memory of "unsigned bytes" of the given
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
301 length. Return 0 on success and -1 (with raising an error) on error.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
302
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
303
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
304 MemoryView objects
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
305 ==================
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
306
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
307 A memoryview object is an extended buffer object that could replace the buffer
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
308 object (but doesn't have to as that could be kept as a simple 1-d memoryview
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
309 object). It, unlike :ctype:`Py_buffer`, is a Python object (exposed as
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
310 :class:`memoryview` in :mod:`builtins`), so it can be used with Python code.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
311
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
312 .. cfunction:: PyObject* PyMemoryView_FromObject(PyObject *obj)
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
313
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
314 Return a memoryview object from an object that defines the buffer interface.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
315
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
316
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
317 Old-style buffer objects
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
318 ========================
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
319
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
320 .. index:: single: PyBufferProcs
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
321
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
322 More information on the old buffer interface is provided in the section
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
323 :ref:`buffer-structs`, under the description for :ctype:`PyBufferProcs`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
324
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
325 A "buffer object" is defined in the :file:`bufferobject.h` header (included by
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
326 :file:`Python.h`). These objects look very similar to string objects at the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
327 Python programming level: they support slicing, indexing, concatenation, and
53422
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
328 some other standard string operations. However, their data can come from one
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
329 of two sources: from a block of memory, or from another object which exports
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
330 the buffer interface.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
331
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
332 Buffer objects are useful as a way to expose the data from another object's
53422
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
333 buffer interface to the Python programmer. They can also be used as a
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
334 zero-copy slicing mechanism. Using their ability to reference a block of
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
335 memory, it is possible to expose any data to the Python programmer quite
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
336 easily. The memory could be a large, constant array in a C extension, it could
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
337 be a raw block of memory for manipulation before passing to an operating
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
338 system library, or it could be used to pass around structured data in its
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
339 native, in-memory format.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
340
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
341
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
342 .. ctype:: PyBufferObject
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
343
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
344 This subtype of :ctype:`PyObject` represents a buffer object.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
345
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
346
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
347 .. cvar:: PyTypeObject PyBuffer_Type
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
348
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
349 .. index:: single: BufferType (in module types)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
350
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
351 The instance of :ctype:`PyTypeObject` which represents the Python buffer type;
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
352 it is the same object as ``buffer`` and ``types.BufferType`` in the Python
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
353 layer. .
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
354
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
355
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
356 .. cvar:: int Py_END_OF_BUFFER
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
357
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
358 This constant may be passed as the *size* parameter to
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
359 :cfunc:`PyBuffer_FromObject` or :cfunc:`PyBuffer_FromReadWriteObject`. It
53422
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
360 indicates that the new :ctype:`PyBufferObject` should refer to *base*
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
361 object from the specified *offset* to the end of its exported buffer.
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
362 Using this enables the caller to avoid querying the *base* object for its
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
363 length.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
364
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
365
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
366 .. cfunction:: int PyBuffer_Check(PyObject *p)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
367
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
368 Return true if the argument has type :cdata:`PyBuffer_Type`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
369
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
370
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
371 .. cfunction:: PyObject* PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
372
53422
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
373 Return a new read-only buffer object. This raises :exc:`TypeError` if
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
374 *base* doesn't support the read-only buffer protocol or doesn't provide
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
375 exactly one buffer segment, or it raises :exc:`ValueError` if *offset* is
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
376 less than zero. The buffer will hold a reference to the *base* object, and
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
377 the buffer's contents will refer to the *base* object's buffer interface,
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
378 starting as position *offset* and extending for *size* bytes. If *size* is
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
379 :const:`Py_END_OF_BUFFER`, then the new buffer's contents extend to the
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
380 length of the *base* object's exported buffer data.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
381
53414
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
382 .. versionchanged:: 2.5
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
383 This function used an :ctype:`int` type for *offset* and *size*. This
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
384 might require changes in your code for properly supporting 64-bit
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
385 systems.
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
386
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
387
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
388 .. cfunction:: PyObject* PyBuffer_FromReadWriteObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
389
53422
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
390 Return a new writable buffer object. Parameters and exceptions are similar
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
391 to those for :cfunc:`PyBuffer_FromObject`. If the *base* object does not
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
392 export the writeable buffer protocol, then :exc:`TypeError` is raised.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
393
53414
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
394 .. versionchanged:: 2.5
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
395 This function used an :ctype:`int` type for *offset* and *size*. This
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
396 might require changes in your code for properly supporting 64-bit
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
397 systems.
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
398
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
399
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
400 .. cfunction:: PyObject* PyBuffer_FromMemory(void *ptr, Py_ssize_t size)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
401
53422
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
402 Return a new read-only buffer object that reads from a specified location
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
403 in memory, with a specified size. The caller is responsible for ensuring
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
404 that the memory buffer, passed in as *ptr*, is not deallocated while the
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
405 returned buffer object exists. Raises :exc:`ValueError` if *size* is less
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
406 than zero. Note that :const:`Py_END_OF_BUFFER` may *not* be passed for the
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
407 *size* parameter; :exc:`ValueError` will be raised in that case.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
408
53414
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
409 .. versionchanged:: 2.5
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
410 This function used an :ctype:`int` type for *size*. This might require
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
411 changes in your code for properly supporting 64-bit systems.
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
412
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
413
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
414 .. cfunction:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
415
53422
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
416 Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
417 writable.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
418
53414
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
419 .. versionchanged:: 2.5
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
420 This function used an :ctype:`int` type for *size*. This might require
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
421 changes in your code for properly supporting 64-bit systems.
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
422
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
423
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
424 .. cfunction:: PyObject* PyBuffer_New(Py_ssize_t size)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
425
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
426 Return a new writable buffer object that maintains its own memory buffer of
53422
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
427 *size* bytes. :exc:`ValueError` is returned if *size* is not zero or
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
428 positive. Note that the memory buffer (as returned by
3b49d30ca541 Since I edited this file, reformat for future edits.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
429 :cfunc:`PyObject_AsWriteBuffer`) is not specifically aligned.
53414
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
430
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
431 .. versionchanged:: 2.5
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
432 This function used an :ctype:`int` type for *size*. This might require
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52990
diff changeset
433 changes in your code for properly supporting 64-bit systems.