Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/buffer.rst @ 80661:94de77bd0b4b 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #16194: document imp.load_dynamic problems when read several extension modules from the same binary object file.
author Andrew Svetlov <andrew.svetlov@gmail.com>
date Thu, 29 Nov 2012 19:51:28 +0200
parents 8aab13719c02
children 75512a165318
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
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
17 "buffer interface." These functions can be used by an object to expose its
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
18 data in a raw, byte-oriented format. Clients of the object can use the buffer
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
19 interface to access the object data directly, without needing to copy it
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
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
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
30 :c:func:`PyArg_ParseTuple` that operate against an object's buffer interface,
44796
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
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
33 Starting from version 1.6, Python has been providing Python-level buffer
56818
3e15a07a32fa Merged revisions 74209 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56812
diff changeset
34 objects and a C-level buffer API so that any built-in or used-defined type can
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
35 expose its characteristics. Both, however, have been deprecated because of
76732
8aab13719c02 Use Python 3 instead of 3.0.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 74395
diff changeset
36 various shortcomings, and have been officially removed in Python 3 in favour
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
37 of a new C-level buffer API and a new Python-level object named
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
38 :class:`memoryview`.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
39
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
40 The new buffer API has been backported to Python 2.6, and the
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
41 :class:`memoryview` object has been backported to Python 2.7. It is strongly
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
42 advised to use them rather than the old APIs, unless you are blocked from
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
43 doing so for compatibility reasons.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
44
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
45
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
46 The new-style Py_buffer struct
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
47 ==============================
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
48
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
49
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
50 .. c:type:: Py_buffer
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
51
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
52 .. c:member:: void *buf
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
53
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
54 A pointer to the start of the memory for the object.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
55
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
56 .. c:member:: Py_ssize_t len
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
57 :noindex:
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
58
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
59 The total length of the memory in bytes.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
60
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
61 .. c:member:: int readonly
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
62
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
63 An indicator of whether the buffer is read only.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
64
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
65 .. c:member:: const char *format
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
66 :noindex:
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
67
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
68 A *NULL* terminated string in :mod:`struct` module style syntax giving
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
69 the contents of the elements available through the buffer. If this is
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
70 *NULL*, ``"B"`` (unsigned bytes) is assumed.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
71
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
72 .. c:member:: int ndim
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
73
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
74 The number of dimensions the memory represents as a multi-dimensional
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
75 array. If it is 0, :c:data:`strides` and :c:data:`suboffsets` must be
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
76 *NULL*.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
77
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
78 .. c:member:: Py_ssize_t *shape
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
79
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
80 An array of :c:type:`Py_ssize_t`\s the length of :c:data:`ndim` giving the
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
81 shape of the memory as a multi-dimensional array. Note that
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
82 ``((*shape)[0] * ... * (*shape)[ndims-1])*itemsize`` should be equal to
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
83 :c:data:`len`.
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
84
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
85 .. c:member:: Py_ssize_t *strides
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
86
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
87 An array of :c:type:`Py_ssize_t`\s the length of :c:data:`ndim` giving the
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
88 number of bytes to skip to get to a new element in each dimension.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
89
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
90 .. c:member:: Py_ssize_t *suboffsets
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
91
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
92 An array of :c:type:`Py_ssize_t`\s the length of :c:data:`ndim`. If these
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
93 suboffset numbers are greater than or equal to 0, then the value stored
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
94 along the indicated dimension is a pointer and the suboffset value
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
95 dictates how many bytes to add to the pointer after de-referencing. A
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
96 suboffset value that it negative indicates that no de-referencing should
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
97 occur (striding in a contiguous memory block).
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
98
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
99 Here is a function that returns a pointer to the element in an N-D array
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
100 pointed to by an N-dimesional index when there are both non-NULL strides
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
101 and suboffsets::
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
102
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
103 void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
104 Py_ssize_t *suboffsets, Py_ssize_t *indices) {
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
105 char *pointer = (char*)buf;
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
106 int i;
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
107 for (i = 0; i < ndim; i++) {
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
108 pointer += strides[i] * indices[i];
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
109 if (suboffsets[i] >=0 ) {
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
110 pointer = *((char**)pointer) + suboffsets[i];
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
111 }
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
112 }
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
113 return (void*)pointer;
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
114 }
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
115
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
116
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
117 .. c:member:: Py_ssize_t itemsize
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
118
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
119 This is a storage for the itemsize (in bytes) of each element of the
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
120 shared memory. It is technically un-necessary as it can be obtained
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
121 using :c:func:`PyBuffer_SizeFromFormat`, however an exporter may know
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
122 this information without parsing the format string and it is necessary
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
123 to know the itemsize for proper interpretation of striding. Therefore,
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
124 storing it is more convenient and faster.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
125
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
126 .. c:member:: void *internal
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
127
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
128 This is for use internally by the exporting object. For example, this
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
129 might be re-cast as an integer by the exporter and used to store flags
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
130 about whether or not the shape, strides, and suboffsets arrays must be
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
131 freed when the buffer is released. The consumer should never alter this
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
132 value.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
133
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
134
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
135 Buffer related functions
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
136 ========================
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
137
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
138
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
139 .. c:function:: int PyObject_CheckBuffer(PyObject *obj)
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
140
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
141 Return 1 if *obj* supports the buffer interface otherwise 0.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
142
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
143
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
144 .. c:function:: int PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags)
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
145
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
146 Export *obj* into a :c:type:`Py_buffer`, *view*. These arguments must
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
147 never be *NULL*. The *flags* argument is a bit field indicating what
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
148 kind of buffer the caller is prepared to deal with and therefore what
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
149 kind of buffer the exporter is allowed to return. The buffer interface
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
150 allows for complicated memory sharing possibilities, but some caller may
56819
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56818
diff changeset
151 not be able to handle all the complexity but may want to see if the
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
152 exporter will let them take a simpler view to its memory.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
153
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
154 Some exporters may not be able to share memory in every possible way and
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
155 may need to raise errors to signal to some consumers that something is
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
156 just not possible. These errors should be a :exc:`BufferError` unless
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
157 there is another error that is actually causing the problem. The
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
158 exporter can use flags information to simplify how much of the
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
159 :c:data:`Py_buffer` structure is filled in with non-default values and/or
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
160 raise an error if the object can't support a simpler view of its memory.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
161
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
162 0 is returned on success and -1 on error.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
163
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
164 The following table gives possible values to the *flags* arguments.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
165
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
166 +-------------------------------+---------------------------------------------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
167 | Flag | Description |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
168 +===============================+===================================================+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
169 | :c:macro:`PyBUF_SIMPLE` | This is the default flag state. The returned |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
170 | | buffer may or may not have writable memory. The |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
171 | | format of the data will be assumed to be unsigned |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
172 | | bytes. This is a "stand-alone" flag constant. It |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
173 | | never needs to be '|'d to the others. The exporter|
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
174 | | will raise an error if it cannot provide such a |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
175 | | contiguous buffer of bytes. |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
176 | | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
177 +-------------------------------+---------------------------------------------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
178 | :c:macro:`PyBUF_WRITABLE` | The returned buffer must be writable. If it is |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
179 | | not writable, then raise an error. |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
180 +-------------------------------+---------------------------------------------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
181 | :c:macro:`PyBUF_STRIDES` | This implies :c:macro:`PyBUF_ND`. The returned |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
182 | | buffer must provide strides information (i.e. the |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
183 | | strides cannot be NULL). This would be used when |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
184 | | the consumer can handle strided, discontiguous |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
185 | | arrays. Handling strides automatically assumes |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
186 | | you can handle shape. The exporter can raise an |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
187 | | error if a strided representation of the data is |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
188 | | not possible (i.e. without the suboffsets). |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
189 | | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
190 +-------------------------------+---------------------------------------------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
191 | :c:macro:`PyBUF_ND` | The returned buffer must provide shape |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
192 | | information. The memory will be assumed C-style |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
193 | | contiguous (last dimension varies the |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
194 | | fastest). The exporter may raise an error if it |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
195 | | cannot provide this kind of contiguous buffer. If |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
196 | | this is not given then shape will be *NULL*. |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
197 | | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
198 | | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
199 | | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
200 +-------------------------------+---------------------------------------------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
201 |:c:macro:`PyBUF_C_CONTIGUOUS` | These flags indicate that the contiguity returned |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
202 |:c:macro:`PyBUF_F_CONTIGUOUS` | buffer must be respectively, C-contiguous (last |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
203 |:c:macro:`PyBUF_ANY_CONTIGUOUS`| dimension varies the fastest), Fortran contiguous |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
204 | | (first dimension varies the fastest) or either |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
205 | | one. All of these flags imply |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
206 | | :c:macro:`PyBUF_STRIDES` and guarantee that the |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
207 | | strides buffer info structure will be filled in |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
208 | | correctly. |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
209 | | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
210 +-------------------------------+---------------------------------------------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
211 | :c:macro:`PyBUF_INDIRECT` | This flag indicates the returned buffer must have |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
212 | | suboffsets information (which can be NULL if no |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
213 | | suboffsets are needed). This can be used when |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
214 | | the consumer can handle indirect array |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
215 | | referencing implied by these suboffsets. This |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
216 | | implies :c:macro:`PyBUF_STRIDES`. |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
217 | | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
218 | | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
219 | | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
220 +-------------------------------+---------------------------------------------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
221 | :c:macro:`PyBUF_FORMAT` | The returned buffer must have true format |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
222 | | information if this flag is provided. This would |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
223 | | be used when the consumer is going to be checking |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
224 | | for what 'kind' of data is actually stored. An |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
225 | | exporter should always be able to provide this |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
226 | | information if requested. If format is not |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
227 | | explicitly requested then the format must be |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
228 | | returned as *NULL* (which means ``'B'``, or |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
229 | | unsigned bytes) |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
230 +-------------------------------+---------------------------------------------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
231 | :c:macro:`PyBUF_STRIDED` | This is equivalent to ``(PyBUF_STRIDES | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
232 | | PyBUF_WRITABLE)``. |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
233 +-------------------------------+---------------------------------------------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
234 | :c:macro:`PyBUF_STRIDED_RO` | This is equivalent to ``(PyBUF_STRIDES)``. |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
235 | | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
236 +-------------------------------+---------------------------------------------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
237 | :c:macro:`PyBUF_RECORDS` | This is equivalent to ``(PyBUF_STRIDES | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
238 | | PyBUF_FORMAT | PyBUF_WRITABLE)``. |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
239 +-------------------------------+---------------------------------------------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
240 | :c:macro:`PyBUF_RECORDS_RO` | This is equivalent to ``(PyBUF_STRIDES | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
241 | | PyBUF_FORMAT)``. |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
242 +-------------------------------+---------------------------------------------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
243 | :c:macro:`PyBUF_FULL` | This is equivalent to ``(PyBUF_INDIRECT | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
244 | | PyBUF_FORMAT | PyBUF_WRITABLE)``. |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
245 +-------------------------------+---------------------------------------------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
246 | :c:macro:`PyBUF_FULL_RO` | This is equivalent to ``(PyBUF_INDIRECT | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
247 | | PyBUF_FORMAT)``. |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
248 +-------------------------------+---------------------------------------------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
249 | :c:macro:`PyBUF_CONTIG` | This is equivalent to ``(PyBUF_ND | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
250 | | PyBUF_WRITABLE)``. |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
251 +-------------------------------+---------------------------------------------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
252 | :c:macro:`PyBUF_CONTIG_RO` | This is equivalent to ``(PyBUF_ND)``. |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
253 | | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
254 +-------------------------------+---------------------------------------------------+
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
255
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
256
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
257 .. c:function:: void PyBuffer_Release(Py_buffer *view)
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
258
56820
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56819
diff changeset
259 Release the buffer *view*. This should be called when the buffer
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
260 is no longer being used as it may free memory from it.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
261
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
262
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
263 .. c:function:: Py_ssize_t PyBuffer_SizeFromFormat(const char *)
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
264
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
265 Return the implied :c:data:`~Py_buffer.itemsize` from the struct-stype
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
266 :c:data:`~Py_buffer.format`.
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
267
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
268
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
269 .. c:function:: int PyBuffer_IsContiguous(Py_buffer *view, char fortran)
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
270
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
271 Return 1 if the memory defined by the *view* is C-style (*fortran* is
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
272 ``'C'``) or Fortran-style (*fortran* is ``'F'``) contiguous or either one
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
273 (*fortran* is ``'A'``). Return 0 otherwise.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
274
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
275
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
276 .. c:function:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t *shape, Py_ssize_t *strides, Py_ssize_t itemsize, char fortran)
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
277
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
278 Fill the *strides* array with byte-strides of a contiguous (C-style if
70222
6a546bf5252f #12072: add missing parenthesis in the doc. Patch by Sandro Tosi.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68426
diff changeset
279 *fortran* is ``'C'`` or Fortran-style if *fortran* is ``'F'``) array of the
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
280 given shape with the given number of bytes per element.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
281
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
282
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
283 .. c:function:: int PyBuffer_FillInfo(Py_buffer *view, PyObject *obj, void *buf, Py_ssize_t len, int readonly, int infoflags)
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
284
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
285 Fill in a buffer-info structure, *view*, correctly for an exporter that can
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
286 only share a contiguous chunk of memory of "unsigned bytes" of the given
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
287 length. Return 0 on success and -1 (with raising an error) on error.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
288
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
289
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
290 MemoryView objects
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
64982
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
293 .. versionadded:: 2.7
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
294
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
295 A :class:`memoryview` object exposes the new C level buffer interface as a
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
296 Python object which can then be passed around like any other object.
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
297
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
298 .. c:function:: PyObject *PyMemoryView_FromObject(PyObject *obj)
64982
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
299
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
300 Create a memoryview object from an object that defines the new buffer
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
301 interface.
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
302
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
303
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
304 .. c:function:: PyObject *PyMemoryView_FromBuffer(Py_buffer *view)
64982
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
305
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
306 Create a memoryview object wrapping the given buffer-info structure *view*.
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
307 The memoryview object then owns the buffer, which means you shouldn't
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
308 try to release it yourself: it will be released on deallocation of the
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
309 memoryview object.
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
310
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
311
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
312 .. c:function:: PyObject *PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order)
64982
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
313
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
314 Create a memoryview object to a contiguous chunk of memory (in either
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
315 'C' or 'F'ortran *order*) from an object that defines the buffer
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
316 interface. If memory is contiguous, the memoryview object points to the
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
317 original memory. Otherwise copy is made and the memoryview points to a
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
318 new bytes object.
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
319
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
320
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
321 .. c:function:: int PyMemoryView_Check(PyObject *obj)
64982
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
322
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
323 Return true if the object *obj* is a memoryview object. It is not
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
324 currently allowed to create subclasses of :class:`memoryview`.
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
325
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
326
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
327 .. c:function:: Py_buffer *PyMemoryView_GET_BUFFER(PyObject *obj)
64982
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
328
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
329 Return a pointer to the buffer-info structure wrapped by the given
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
330 object. The object **must** be a memoryview instance; this macro doesn't
d1bee7cf6c2f Merged revisions 85066 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 57954
diff changeset
331 check its type, you must do it yourself or you will risk crashes.
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
332
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
333
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
334 Old-style buffer objects
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
335 ========================
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
336
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
337 .. index:: single: PyBufferProcs
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
338
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 50522
diff changeset
339 More information on the old buffer interface is provided in the section
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
340 :ref:`buffer-structs`, under the description for :c:type:`PyBufferProcs`.
44796
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 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
343 :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
344 Python programming level: they support slicing, indexing, concatenation, and
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
345 some other standard string operations. However, their data can come from one
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
346 of two sources: from a block of memory, or from another object which exports
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
347 the buffer interface.
44796
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 Buffer objects are useful as a way to expose the data from another object's
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
350 buffer interface to the Python programmer. They can also be used as a
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
351 zero-copy slicing mechanism. Using their ability to reference a block of
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
352 memory, it is possible to expose any data to the Python programmer quite
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
353 easily. The memory could be a large, constant array in a C extension, it could
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
354 be a raw block of memory for manipulation before passing to an operating
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
355 system library, or it could be used to pass around structured data in its
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
356 native, in-memory format.
44796
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
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
359 .. c:type:: PyBufferObject
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
360
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
361 This subtype of :c:type:`PyObject` represents a buffer object.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
362
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
363
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
364 .. c:var:: PyTypeObject PyBuffer_Type
44796
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 .. 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
367
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
368 The instance of :c:type:`PyTypeObject` which represents the Python buffer type;
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
369 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
370 layer. .
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
371
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
372
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
373 .. c:var:: int Py_END_OF_BUFFER
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
374
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
375 This constant may be passed as the *size* parameter to
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
376 :c:func:`PyBuffer_FromObject` or :c:func:`PyBuffer_FromReadWriteObject`. It
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
377 indicates that the new :c:type:`PyBufferObject` should refer to *base*
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
378 object from the specified *offset* to the end of its exported buffer.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
379 Using this enables the caller to avoid querying the *base* object for its
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
380 length.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
381
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
382
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
383 .. c:function:: int PyBuffer_Check(PyObject *p)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
384
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
385 Return true if the argument has type :c:data:`PyBuffer_Type`.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
386
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
387
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
388 .. c:function:: PyObject* PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
389
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
390 Return a new read-only buffer object. This raises :exc:`TypeError` if
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
391 *base* doesn't support the read-only buffer protocol or doesn't provide
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
392 exactly one buffer segment, or it raises :exc:`ValueError` if *offset* is
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
393 less than zero. The buffer will hold a reference to the *base* object, and
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
394 the buffer's contents will refer to the *base* object's buffer interface,
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
395 starting as position *offset* and extending for *size* bytes. If *size* is
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
396 :const:`Py_END_OF_BUFFER`, then the new buffer's contents extend to the
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
397 length of the *base* object's exported buffer data.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
398
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
399 .. versionchanged:: 2.5
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
400 This function used an :c:type:`int` type for *offset* and *size*. This
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
401 might require changes in your code for properly supporting 64-bit
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
402 systems.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
403
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
404
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
405 .. c:function:: PyObject* PyBuffer_FromReadWriteObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
406
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
407 Return a new writable buffer object. Parameters and exceptions are similar
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
408 to those for :c:func:`PyBuffer_FromObject`. If the *base* object does not
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
409 export the writeable buffer protocol, then :exc:`TypeError` is raised.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
410
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
411 .. versionchanged:: 2.5
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
412 This function used an :c:type:`int` type for *offset* and *size*. This
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
413 might require changes in your code for properly supporting 64-bit
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
414 systems.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
415
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
416
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
417 .. c:function:: PyObject* PyBuffer_FromMemory(void *ptr, Py_ssize_t size)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
418
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
419 Return a new read-only buffer object that reads from a specified location
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
420 in memory, with a specified size. The caller is responsible for ensuring
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
421 that the memory buffer, passed in as *ptr*, is not deallocated while the
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
422 returned buffer object exists. Raises :exc:`ValueError` if *size* is less
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
423 than zero. Note that :const:`Py_END_OF_BUFFER` may *not* be passed for the
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
424 *size* parameter; :exc:`ValueError` will be raised in that case.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
425
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
426 .. versionchanged:: 2.5
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
427 This function used an :c:type:`int` type for *size*. This might require
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
428 changes in your code for properly supporting 64-bit systems.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
429
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
430
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
431 .. c:function:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
432
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
433 Similar to :c:func:`PyBuffer_FromMemory`, but the returned buffer is
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
434 writable.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
435
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
436 .. versionchanged:: 2.5
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
437 This function used an :c:type:`int` type for *size*. This might require
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
438 changes in your code for properly supporting 64-bit systems.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
439
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
440
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
441 .. c:function:: PyObject* PyBuffer_New(Py_ssize_t size)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
442
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
443 Return a new writable buffer object that maintains its own memory buffer of
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
444 *size* bytes. :exc:`ValueError` is returned if *size* is not zero or
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
445 positive. Note that the memory buffer (as returned by
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
446 :c:func:`PyObject_AsWriteBuffer`) is not specifically aligned.
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
447
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
448 .. versionchanged:: 2.5
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70222
diff changeset
449 This function used an :c:type:`int` type for *size*. This might require
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
450 changes in your code for properly supporting 64-bit systems.