cpython-lru_cache-weakref: Doc/c-api/buffer.rst annotate

annotate Doc/c-api/buffer.rst @ 55729:d91aff206dfd 3.1

Merged revisions 74551 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r74551 | benjamin.peterson | 2009-08-26 09:35:45 +0200 (Wed, 26 Aug 2009) | 1 line the old buffer object doesn't exist in Python 3 #6659 ........

author	Benjamin Peterson <benjamin@python.org>
date	Wed, 26 Aug 2009 07:38:00 +0000
parents	7b495c8f2a24
children	6f3855038919 57433b833b2a

rev	line source
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	1 .. highlightlang:: c
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	2
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	3 .. _bufferobjects:
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	4
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	5 Buffer Objects
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	6 --------------
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	7
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	8 .. sectionauthor:: Greg Stein <gstein@lyra.org>
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	9 .. sectionauthor:: Benjamin Peterson
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	10
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	11
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	12 .. index::
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	13 single: buffer interface
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	14
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	15 Python objects implemented in C can export a "buffer interface." These
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	16 functions can be used by an object to expose its data in a raw, byte-oriented
53486 0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	17 format. Clients of the object can use the buffer interface to access the
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	18 object data directly, without needing to copy it first.
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	19
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	20 Two examples of objects that support the buffer interface are bytes and
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	21 arrays. The bytes object exposes the character contents in the buffer
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	22 interface's byte-oriented form. An array can also expose its contents, but it
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	23 should be noted that array elements may be multi-byte values.
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	24
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	25 An example user of the buffer interface is the file object's :meth:`write`
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	26 method. Any object that can export a series of bytes through the buffer
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	27 interface can be written to a file. There are a number of format codes to
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	28 :cfunc:`PyArg_ParseTuple` that operate against an object's buffer interface,
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	29 returning data from the target object.
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	30
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	31 .. index:: single: PyBufferProcs
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	32
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49780 diff changeset	33 More information on the buffer interface is provided in the section
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	34 :ref:`buffer-structs`, under the description for :ctype:`PyBufferProcs`.
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	35
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	36 Buffer objects are useful as a way to expose the data from another object's
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	37 buffer interface to the Python programmer. They can also be used as a zero-copy
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	38 slicing mechanism. Using their ability to reference a block of memory, it is
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	39 possible to expose any data to the Python programmer quite easily. The memory
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	40 could be a large, constant array in a C extension, it could be a raw block of
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	41 memory for manipulation before passing to an operating system library, or it
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	42 could be used to pass around structured data in its native, in-memory format.
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	43
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	44
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	45 .. ctype:: Py_buffer
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	46
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	47 .. cmember:: void *buf
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	48
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	49 A pointer to the start of the memory for the object.
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	50
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	51 .. cmember:: Py_ssize_t len
49216 af4c4cf3e01e shut up a few sphinx warnings Benjamin Peterson <benjamin@python.org> parents: 49205 diff changeset	52 :noindex:
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	53
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	54 The total length of the memory in bytes.
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	55
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	56 .. cmember:: int readonly
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	57
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	58 An indicator of whether the buffer is read only.
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	59
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	60 .. cmember:: const char *format
49216 af4c4cf3e01e shut up a few sphinx warnings Benjamin Peterson <benjamin@python.org> parents: 49205 diff changeset	61 :noindex:
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	62
53486 0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	63 A NULL terminated string in :mod:`struct` module style syntax giving
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	64 the contents of the elements available through the buffer. If this is
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	65 NULL, ``"B"`` (unsigned bytes) is assumed.
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	66
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	67 .. cmember:: int ndim
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	68
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	69 The number of dimensions the memory represents as a multi-dimensional
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	70 array. If it is 0, :cdata:`strides` and :cdata:`suboffsets` must be
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	71 NULL.
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	72
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	73 .. cmember:: Py_ssize_t *shape
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	74
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	75 An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim` giving the
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	76 shape of the memory as a multi-dimensional array. Note that
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	77 ``((shape)[0] ... * (shape)[ndims-1])itemsize`` should be equal to
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	78 :cdata:`len`.
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	79
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	80 .. cmember:: Py_ssize_t *strides
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	81
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	82 An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim` giving the
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	83 number of bytes to skip to get to a new element in each dimension.
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	84
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	85 .. cmember:: Py_ssize_t *suboffsets
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	86
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	87 An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim`. If these
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	88 suboffset numbers are greater than or equal to 0, then the value stored
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	89 along the indicated dimension is a pointer and the suboffset value
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	90 dictates how many bytes to add to the pointer after de-referencing. A
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	91 suboffset value that it negative indicates that no de-referencing should
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	92 occur (striding in a contiguous memory block).
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	93
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	94 Here is a function that returns a pointer to the element in an N-D array
52144 e5e64a0c4aa2 #5486: typos. Georg Brandl <georg@python.org> parents: 51944 diff changeset	95 pointed to by an N-dimensional index when there are both non-NULL strides
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	96 and suboffsets::
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	97
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	98 void get_item_pointer(int ndim, void buf, Py_ssize_t *strides,
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	99 Py_ssize_t suboffsets, Py_ssize_t indices) {
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	100 char pointer = (char)buf;
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	101 int i;
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	102 for (i = 0; i < ndim; i++) {
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	103 pointer += strides[i] * indices[i];
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	104 if (suboffsets[i] >=0 ) {
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	105 pointer = ((char*)pointer) + suboffsets[i];
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 49780 diff changeset	106 }
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	107 }
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	108 return (void*)pointer;
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	109 }
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	110
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	111
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	112 .. cmember:: Py_ssize_t itemsize
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	113
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	114 This is a storage for the itemsize (in bytes) of each element of the
53486 0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	115 shared memory. It is technically un-necessary as it can be obtained
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	116 using :cfunc:`PyBuffer_SizeFromFormat`, however an exporter may know
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	117 this information without parsing the format string and it is necessary
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	118 to know the itemsize for proper interpretation of striding. Therefore,
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	119 storing it is more convenient and faster.
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	120
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	121 .. cmember:: void *internal
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	122
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	123 This is for use internally by the exporting object. For example, this
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	124 might be re-cast as an integer by the exporter and used to store flags
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	125 about whether or not the shape, strides, and suboffsets arrays must be
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	126 freed when the buffer is released. The consumer should never alter this
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	127 value.
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	128
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	129
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	130 Buffer related functions
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	131 ========================
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	132
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	133
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	134 .. cfunction:: int PyObject_CheckBuffer(PyObject *obj)
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	135
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	136 Return 1 if obj supports the buffer interface otherwise 0.
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	137
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	138
54501 ced380b40004 Merged revisions 72506,72525-72526,72551,72558,72616,72654-72655,72689,72745,72750,72802,72812,72822,72824,72826-72827,72833,72876,72890,72923,72946,73026,73042,73045,73047,73065,73068-73069 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 53486 diff changeset	139 .. cfunction:: int PyObject_GetBuffer(PyObject obj, Py_buffer view, int flags)
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	140
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	141 Export obj into a :ctype:`Py_buffer`, view. These arguments must
53486 0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	142 never be NULL. The flags argument is a bit field indicating what
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	143 kind of buffer the caller is prepared to deal with and therefore what
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	144 kind of buffer the exporter is allowed to return. The buffer interface
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	145 allows for complicated memory sharing possibilities, but some caller may
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54501 diff changeset	146 not be able to handle all the complexity but may want to see if the
53486 0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	147 exporter will let them take a simpler view to its memory.
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	148
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	149 Some exporters may not be able to share memory in every possible way and
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	150 may need to raise errors to signal to some consumers that something is
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	151 just not possible. These errors should be a :exc:`BufferError` unless
53486 0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	152 there is another error that is actually causing the problem. The
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	153 exporter can use flags information to simplify how much of the
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	154 :cdata:`Py_buffer` structure is filled in with non-default values and/or
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	155 raise an error if the object can't support a simpler view of its memory.
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	156
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	157 0 is returned on success and -1 on error.
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	158
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	159 The following table gives possible values to the flags arguments.
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	160
49780 88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	161 +------------------------------+---------------------------------------------------+
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	162 \| Flag \| Description \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	163 +==============================+===================================================+
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	164 \| :cmacro:`PyBUF_SIMPLE` \| This is the default flag state. The returned \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	165 \| \| buffer may or may not have writable memory. The \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	166 \| \| format of the data will be assumed to be unsigned \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	167 \| \| bytes. This is a "stand-alone" flag constant. It \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	168 \| \| never needs to be '\|'d to the others. The exporter\|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	169 \| \| will raise an error if it cannot provide such a \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	170 \| \| contiguous buffer of bytes. \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	171 \| \| \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	172 +------------------------------+---------------------------------------------------+
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	173 \| :cmacro:`PyBUF_WRITABLE` \| The returned buffer must be writable. If it is \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	174 \| \| not writable, then raise an error. \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	175 +------------------------------+---------------------------------------------------+
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	176 \| :cmacro:`PyBUF_STRIDES` \| This implies :cmacro:`PyBUF_ND`. The returned \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	177 \| \| buffer must provide strides information (i.e. the \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	178 \| \| strides cannot be NULL). This would be used when \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	179 \| \| the consumer can handle strided, discontiguous \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	180 \| \| arrays. Handling strides automatically assumes \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	181 \| \| you can handle shape. The exporter can raise an \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	182 \| \| error if a strided representation of the data is \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	183 \| \| not possible (i.e. without the suboffsets). \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	184 \| \| \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	185 +------------------------------+---------------------------------------------------+
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	186 \| :cmacro:`PyBUF_ND` \| The returned buffer must provide shape \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	187 \| \| information. The memory will be assumed C-style \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	188 \| \| contiguous (last dimension varies the \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	189 \| \| fastest). The exporter may raise an error if it \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	190 \| \| cannot provide this kind of contiguous buffer. If \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	191 \| \| this is not given then shape will be NULL. \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	192 \| \| \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	193 \| \| \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	194 \| \| \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	195 +------------------------------+---------------------------------------------------+
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	196 \|:cmacro:`PyBUF_C_CONTIGUOUS` \| These flags indicate that the contiguity returned \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	197 \|:cmacro:`PyBUF_F_CONTIGUOUS` \| buffer must be respectively, C-contiguous (last \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	198 \|:cmacro:`PyBUF_ANY_CONTIGUOUS`\| dimension varies the fastest), Fortran contiguous \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	199 \| \| (first dimension varies the fastest) or either \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	200 \| \| one. All of these flags imply \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	201 \| \| :cmacro:`PyBUF_STRIDES` and guarantee that the \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	202 \| \| strides buffer info structure will be filled in \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	203 \| \| correctly. \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	204 \| \| \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	205 +------------------------------+---------------------------------------------------+
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	206 \| :cmacro:`PyBUF_INDIRECT` \| This flag indicates the returned buffer must have \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	207 \| \| suboffsets information (which can be NULL if no \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	208 \| \| suboffsets are needed). This can be used when \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	209 \| \| the consumer can handle indirect array \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	210 \| \| referencing implied by these suboffsets. This \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	211 \| \| implies :cmacro:`PyBUF_STRIDES`. \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	212 \| \| \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	213 \| \| \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	214 \| \| \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	215 +------------------------------+---------------------------------------------------+
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	216 \| :cmacro:`PyBUF_FORMAT` \| The returned buffer must have true format \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	217 \| \| information if this flag is provided. This would \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	218 \| \| be used when the consumer is going to be checking \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	219 \| \| for what 'kind' of data is actually stored. An \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	220 \| \| exporter should always be able to provide this \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	221 \| \| information if requested. If format is not \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	222 \| \| explicitly requested then the format must be \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	223 \| \| returned as NULL (which means ``'B'``, or \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	224 \| \| unsigned bytes) \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	225 +------------------------------+---------------------------------------------------+
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	226 \| :cmacro:`PyBUF_STRIDED` \| This is equivalent to ``(PyBUF_STRIDES \| \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	227 \| \| PyBUF_WRITABLE)``. \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	228 +------------------------------+---------------------------------------------------+
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	229 \| :cmacro:`PyBUF_STRIDED_RO` \| This is equivalent to ``(PyBUF_STRIDES)``. \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	230 \| \| \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	231 +------------------------------+---------------------------------------------------+
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	232 \| :cmacro:`PyBUF_RECORDS` \| This is equivalent to ``(PyBUF_STRIDES \| \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	233 \| \| PyBUF_FORMAT \| PyBUF_WRITABLE)``. \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	234 +------------------------------+---------------------------------------------------+
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	235 \| :cmacro:`PyBUF_RECORDS_RO` \| This is equivalent to ``(PyBUF_STRIDES \| \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	236 \| \| PyBUF_FORMAT)``. \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	237 +------------------------------+---------------------------------------------------+
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	238 \| :cmacro:`PyBUF_FULL` \| This is equivalent to ``(PyBUF_INDIRECT \| \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	239 \| \| PyBUF_FORMAT \| PyBUF_WRITABLE)``. \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	240 +------------------------------+---------------------------------------------------+
53072 7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52144 diff changeset	241 \| :cmacro:`PyBUF_FULL_RO` \| This is equivalent to ``(PyBUF_INDIRECT \| \|
49780 88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	242 \| \| PyBUF_FORMAT)``. \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	243 +------------------------------+---------------------------------------------------+
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	244 \| :cmacro:`PyBUF_CONTIG` \| This is equivalent to ``(PyBUF_ND \| \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	245 \| \| PyBUF_WRITABLE)``. \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	246 +------------------------------+---------------------------------------------------+
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	247 \| :cmacro:`PyBUF_CONTIG_RO` \| This is equivalent to ``(PyBUF_ND)``. \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	248 \| \| \|
88ff45e58e94 fix Sphinx table warning Benjamin Peterson <benjamin@python.org> parents: 49216 diff changeset	249 +------------------------------+---------------------------------------------------+
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	250
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	251
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	252 .. cfunction:: void PyBuffer_Release(PyObject obj, Py_buffer view)
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	253
51944 d5f134a3a816 Fixed typo. Hirokazu Yamamoto <ocean-city@m2.ccsnet.ne.jp> parents: 50563 diff changeset	254 Release the buffer view over obj. This should be called when the buffer
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	255 is no longer being used as it may free memory from it.
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	256
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	257
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	258 .. cfunction:: Py_ssize_t PyBuffer_SizeFromFormat(const char *)
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	259
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	260 Return the implied :cdata:`~Py_buffer.itemsize` from the struct-stype
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	261 :cdata:`~Py_buffer.format`.
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	262
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	263
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	264 .. cfunction:: int PyObject_CopyToObject(PyObject obj, void buf, Py_ssize_t len, char fortran)
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	265
53486 0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	266 Copy len bytes of data pointed to by the contiguous chunk of memory
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	267 pointed to by buf into the buffer exported by obj. The buffer must of
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	268 course be writable. Return 0 on success and return -1 and raise an error
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	269 on failure. If the object does not have a writable buffer, then an error
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	270 is raised. If fortran is ``'F'``, then if the object is
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	271 multi-dimensional, then the data will be copied into the array in
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	272 Fortran-style (first dimension varies the fastest). If fortran is
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	273 ``'C'``, then the data will be copied into the array in C-style (last
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	274 dimension varies the fastest). If fortran is ``'A'``, then it does not
0b1674f27b70 Merged revisions 71898-71900,71910,71914-71919 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53072 diff changeset	275 matter and the copy will be made in whatever way is more efficient.
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	276
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	277
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	278 .. cfunction:: int PyBuffer_IsContiguous(Py_buffer *view, char fortran)
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	279
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	280 Return 1 if the memory defined by the view is C-style (fortran is
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	281 ``'C'``) or Fortran-style (fortran is ``'F'``) contiguous or either one
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	282 (fortran is ``'A'``). Return 0 otherwise.
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	283
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	284
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	285 .. cfunction:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t shape, Py_ssize_t strides, Py_ssize_t itemsize, char fortran)
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	286
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	287 Fill the strides array with byte-strides of a contiguous (C-style if
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	288 fortran is ``'C'`` or Fortran-style if fortran is ``'F'`` array of the
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	289 given shape with the given number of bytes per element.
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	290
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	291
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	292 .. cfunction:: int PyBuffer_FillInfo(Py_buffer view, void buf, Py_ssize_t len, int readonly, int infoflags)
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	293
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	294 Fill in a buffer-info structure, view, correctly for an exporter that can
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	295 only share a contiguous chunk of memory of "unsigned bytes" of the given
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	296 length. Return 0 on success and -1 (with raising an error) on error.
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	297
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	298
55729 d91aff206dfd Merged revisions 74551 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	299 .. index::
d91aff206dfd Merged revisions 74551 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	300 object: memoryview
d91aff206dfd Merged revisions 74551 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	301
d91aff206dfd Merged revisions 74551 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	302
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	303 MemoryView objects
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	304 ==================
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	305
55729 d91aff206dfd Merged revisions 74551 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	306 A memoryview object exposes the C level buffer interface to Python.
d91aff206dfd Merged revisions 74551 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	307
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	308
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	309 .. cfunction:: PyObject* PyMemoryView_FromObject(PyObject *obj)
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	310
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	311 Return a memoryview object from an object that defines the buffer interface.
55729 d91aff206dfd Merged revisions 74551 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	312
d91aff206dfd Merged revisions 74551 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	313
d91aff206dfd Merged revisions 74551 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	314 .. cfunction:: PyObject * PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order)
d91aff206dfd Merged revisions 74551 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	315
d91aff206dfd Merged revisions 74551 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	316 Return a memoryview object to a contiguous chunk of memory (in either
d91aff206dfd Merged revisions 74551 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	317 'C' or 'F'ortran order) from an object that defines the buffer
d91aff206dfd Merged revisions 74551 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	318 interface. If memory is contiguous, the memoryview object points to the
d91aff206dfd Merged revisions 74551 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	319 original memory. Otherwise copy is made and the memoryview points to a
d91aff206dfd Merged revisions 74551 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	320 new bytes object.

Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/buffer.rst @ 55729:d91aff206dfd 3.1