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

annotate Doc/c-api/buffer.rst @ 87690:66c1c9f32567 default tip

Add use_weakref option to functools.lru_cache The use_weakref option makes lru_cache create weak references to the function arguments when creating the cache key, which prevents them from staying in the memory forever even after all other references to them are gone. This is a proof of concept for http://bugs.python.org/issue19859

author	Radomir Dopieralski <devel@sheep.art.pl>
date	Tue, 03 Dec 2013 16:02:48 +0100
parents	3ae74b361f53
children	75512a165318

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
80542 325f80d792b9 Improve str() and object.__str__() documentation (issue #13538). Chris Jerdonek <chris.jerdonek@gmail.com> parents: 80541 diff changeset	3 .. index::
325f80d792b9 Improve str() and object.__str__() documentation (issue #13538). Chris Jerdonek <chris.jerdonek@gmail.com> parents: 80541 diff changeset	4 single: buffer protocol
325f80d792b9 Improve str() and object.__str__() documentation (issue #13538). Chris Jerdonek <chris.jerdonek@gmail.com> parents: 80541 diff changeset	5 single: buffer interface; (see buffer protocol)
325f80d792b9 Improve str() and object.__str__() documentation (issue #13538). Chris Jerdonek <chris.jerdonek@gmail.com> parents: 80541 diff changeset	6 single: buffer object; (see buffer protocol)
325f80d792b9 Improve str() and object.__str__() documentation (issue #13538). Chris Jerdonek <chris.jerdonek@gmail.com> parents: 80541 diff changeset	7
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	8 .. _bufferobjects:
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	9
64997 dc4555646e80 Merged revisions 85082 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64995 diff changeset	10 Buffer Protocol
dc4555646e80 Merged revisions 85082 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64995 diff changeset	11 ---------------
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	12
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	13 .. 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	14 .. sectionauthor:: Benjamin Peterson
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	15 .. sectionauthor:: Stefan Krah
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	16
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	17
66860 99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	18 Certain objects available in Python wrap access to an underlying memory
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	19 array or buffer. Such objects include the built-in :class:`bytes` and
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	20 :class:`bytearray`, and some extension types like :class:`array.array`.
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	21 Third-party libraries may define their own types for special purposes, such
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	22 as image processing or numeric analysis.
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	23
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	24 While each of these types have their own semantics, they share the common
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	25 characteristic of being backed by a possibly large memory buffer. It is
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	26 then desirable, in some situations, to access that buffer directly and
66860 99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	27 without intermediate copying.
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	28
80542 325f80d792b9 Improve str() and object.__str__() documentation (issue #13538). Chris Jerdonek <chris.jerdonek@gmail.com> parents: 80541 diff changeset	29 Python provides such a facility at the C level in the form of the :ref:`buffer
325f80d792b9 Improve str() and object.__str__() documentation (issue #13538). Chris Jerdonek <chris.jerdonek@gmail.com> parents: 80541 diff changeset	30 protocol <bufferobjects>`. This protocol has two sides:
66860 99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	31
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	32 .. index:: single: PyBufferProcs
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	33
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	34 - on the producer side, a type can export a "buffer interface" which allows
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	35 objects of that type to expose information about their underlying buffer.
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	36 This interface is described in the section :ref:`buffer-structs`;
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	37
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	38 - on the consumer side, several means are available to obtain a pointer to
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	39 the raw underlying data of an object (for example a method parameter).
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	40
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	41 Simple objects such as :class:`bytes` and :class:`bytearray` expose their
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	42 underlying buffer in byte-oriented form. Other forms are possible; for example,
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 65109 diff changeset	43 the elements exposed by a :class:`array.array` can be multi-byte values.
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	44
64995 5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	45 An example consumer of the buffer interface is the :meth:`~io.BufferedIOBase.write`
5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	46 method of file objects: any object that can export a series of bytes through
5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	47 the buffer interface can be written to a file. While :meth:`write` only
5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	48 needs read-only access to the internal contents of the object passed to it,
5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	49 other methods such as :meth:`~io.BufferedIOBase.readinto` need write access
5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	50 to the contents of their argument. The buffer interface allows objects to
5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	51 selectively allow or reject exporting of read-write and read-only buffers.
5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	52
5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	53 There are two ways for a consumer of the buffer interface to acquire a buffer
5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	54 over a target object:
5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	55
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 65032 diff changeset	56 * call :c:func:`PyObject_GetBuffer` with the right parameters;
64995 5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	57
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 65032 diff changeset	58 * call :c:func:`PyArg_ParseTuple` (or one of its siblings) with one of the
64995 5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	59 ``y``, ``w`` or ``s*`` :ref:`format codes <arg-parsing>`.
5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	60
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 65032 diff changeset	61 In both cases, :c:func:`PyBuffer_Release` must be called when the buffer
64995 5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	62 isn't needed anymore. Failure to do so could lead to various issues such as
5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	63 resource leaks.
5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	64
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	65
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	66 .. _buffer-structure:
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	67
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	68 Buffer structure
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	69 ================
64995 5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	70
64997 dc4555646e80 Merged revisions 85082 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64995 diff changeset	71 Buffer structures (or simply "buffers") are useful as a way to expose the
dc4555646e80 Merged revisions 85082 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64995 diff changeset	72 binary data from another object to the Python programmer. They can also be
dc4555646e80 Merged revisions 85082 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64995 diff changeset	73 used as a zero-copy slicing mechanism. Using their ability to reference a
dc4555646e80 Merged revisions 85082 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64995 diff changeset	74 block of memory, it is possible to expose any data to the Python programmer
dc4555646e80 Merged revisions 85082 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64995 diff changeset	75 quite easily. The memory could be a large, constant array in a C extension,
dc4555646e80 Merged revisions 85082 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64995 diff changeset	76 it could be a raw block of memory for manipulation before passing to an
dc4555646e80 Merged revisions 85082 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64995 diff changeset	77 operating system library, or it could be used to pass around structured data
dc4555646e80 Merged revisions 85082 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64995 diff changeset	78 in its native, in-memory format.
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	79
64997 dc4555646e80 Merged revisions 85082 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64995 diff changeset	80 Contrary to most data types exposed by the Python interpreter, buffers
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 65032 diff changeset	81 are not :c:type:`PyObject` pointers but rather simple C structures. This
64995 5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	82 allows them to be created and copied very simply. When a generic wrapper
64999 c869ea07cd9d Merged revisions 85084 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64997 diff changeset	83 around a buffer is needed, a :ref:`memoryview <memoryview-objects>` object
64995 5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	84 can be created.
5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	85
75455 da2aaced21bd Issue #14181: Improve clarity in the documentation for the multi-purpose Stefan Krah <skrah@bytereef.org> parents: 75254 diff changeset	86 For short instructions how to write an exporting object, see
da2aaced21bd Issue #14181: Improve clarity in the documentation for the multi-purpose Stefan Krah <skrah@bytereef.org> parents: 75254 diff changeset	87 :ref:`Buffer Object Structures <buffer-structs>`. For obtaining
da2aaced21bd Issue #14181: Improve clarity in the documentation for the multi-purpose Stefan Krah <skrah@bytereef.org> parents: 75254 diff changeset	88 a buffer, see :c:func:`PyObject_GetBuffer`.
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	89
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 65032 diff changeset	90 .. c:type:: Py_buffer
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	91
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	92 .. c:member:: void \*obj
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	93
75455 da2aaced21bd Issue #14181: Improve clarity in the documentation for the multi-purpose Stefan Krah <skrah@bytereef.org> parents: 75254 diff changeset	94 A new reference to the exporting object. The reference is owned by
da2aaced21bd Issue #14181: Improve clarity in the documentation for the multi-purpose Stefan Krah <skrah@bytereef.org> parents: 75254 diff changeset	95 the consumer and automatically decremented and set to NULL by
da2aaced21bd Issue #14181: Improve clarity in the documentation for the multi-purpose Stefan Krah <skrah@bytereef.org> parents: 75254 diff changeset	96 :c:func:`PyBuffer_Release`. The field is the equivalent of the return
da2aaced21bd Issue #14181: Improve clarity in the documentation for the multi-purpose Stefan Krah <skrah@bytereef.org> parents: 75254 diff changeset	97 value of any standard C-API function.
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	98
75455 da2aaced21bd Issue #14181: Improve clarity in the documentation for the multi-purpose Stefan Krah <skrah@bytereef.org> parents: 75254 diff changeset	99 As a special case, for temporary buffers that are wrapped by
da2aaced21bd Issue #14181: Improve clarity in the documentation for the multi-purpose Stefan Krah <skrah@bytereef.org> parents: 75254 diff changeset	100 :c:func:`PyMemoryView_FromBuffer` or :c:func:`PyBuffer_FillInfo`
da2aaced21bd Issue #14181: Improve clarity in the documentation for the multi-purpose Stefan Krah <skrah@bytereef.org> parents: 75254 diff changeset	101 this field is NULL. In general, exporting objects MUST NOT
da2aaced21bd Issue #14181: Improve clarity in the documentation for the multi-purpose Stefan Krah <skrah@bytereef.org> parents: 75254 diff changeset	102 use this scheme.
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	103
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	104 .. c:member:: void \*buf
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	105
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	106 A pointer to the start of the logical structure described by the buffer
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	107 fields. This can be any location within the underlying physical memory
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	108 block of the exporter. For example, with negative :c:member:`~Py_buffer.strides`
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	109 the value may point to the end of the memory block.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	110
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	111 For contiguous arrays, the value points to the beginning of the memory
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	112 block.
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	113
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 65032 diff changeset	114 .. c:member:: Py_ssize_t len
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	115
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	116 ``product(shape) * itemsize``. For contiguous arrays, this is the length
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	117 of the underlying memory block. For non-contiguous arrays, it is the length
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	118 that the logical structure would have if it were copied to a contiguous
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	119 representation.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	120
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	121 Accessing ``((char )buf)[0] up to ((char )buf)[len-1]`` is only valid
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	122 if the buffer has been obtained by a request that guarantees contiguity. In
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	123 most cases such a request will be :c:macro:`PyBUF_SIMPLE` or :c:macro:`PyBUF_WRITABLE`.
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	124
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 65032 diff changeset	125 .. c:member:: int readonly
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	126
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	127 An indicator of whether the buffer is read-only. This field is controlled
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	128 by the :c:macro:`PyBUF_WRITABLE` flag.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	129
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	130 .. c:member:: Py_ssize_t itemsize
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	131
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	132 Item size in bytes of a single element. Same as the value of :func:`struct.calcsize`
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	133 called on non-NULL :c:member:`~Py_buffer.format` values.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	134
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	135 Important exception: If a consumer requests a buffer without the
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	136 :c:macro:`PyBUF_FORMAT` flag, :c:member:`~Py_Buffer.format` will
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	137 be set to NULL, but :c:member:`~Py_buffer.itemsize` still has
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	138 the value for the original format.
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	139
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	140 If :c:member:`~Py_Buffer.shape` is present, the equality
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	141 ``product(shape) * itemsize == len`` still holds and the consumer
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	142 can use :c:member:`~Py_buffer.itemsize` to navigate the buffer.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	143
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	144 If :c:member:`~Py_Buffer.shape` is NULL as a result of a :c:macro:`PyBUF_SIMPLE`
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	145 or a :c:macro:`PyBUF_WRITABLE` request, the consumer must disregard
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	146 :c:member:`~Py_buffer.itemsize` and assume ``itemsize == 1``.
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	147
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	148 .. c:member:: const char \*format
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	149
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	150 A NUL terminated string in :mod:`struct` module style syntax describing
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	151 the contents of a single item. If this is NULL, ``"B"`` (unsigned bytes)
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	152 is assumed.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	153
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	154 This field is controlled by the :c:macro:`PyBUF_FORMAT` flag.
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	155
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 65032 diff changeset	156 .. c:member:: int ndim
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	157
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	158 The number of dimensions the memory represents as an n-dimensional array.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	159 If it is 0, :c:member:`~Py_Buffer.buf` points to a single item representing
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	160 a scalar. In this case, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer.strides`
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	161 and :c:member:`~Py_buffer.suboffsets` MUST be NULL.
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	162
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	163 The macro :c:macro:`PyBUF_MAX_NDIM` limits the maximum number of dimensions
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	164 to 64. Exporters MUST respect this limit, consumers of multi-dimensional
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	165 buffers SHOULD be able to handle up to :c:macro:`PyBUF_MAX_NDIM` dimensions.
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	166
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	167 .. c:member:: Py_ssize_t \*shape
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	168
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	169 An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	170 indicating the shape of the memory as an n-dimensional array. Note that
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	171 ``shape[0] * ... * shape[ndim-1] * itemsize`` MUST be equal to
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	172 :c:member:`~Py_buffer.len`.
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	173
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	174 Shape values are restricted to ``shape[n] >= 0``. The case
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	175 ``shape[n] == 0`` requires special attention. See `complex arrays`_
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	176 for further information.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	177
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	178 The shape array is read-only for the consumer.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	179
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	180 .. c:member:: Py_ssize_t \*strides
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	181
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	182 An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	183 giving the number of bytes to skip to get to a new element in each
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	184 dimension.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	185
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	186 Stride values can be any integer. For regular arrays, strides are
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	187 usually positive, but a consumer MUST be able to handle the case
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	188 ``strides[n] <= 0``. See `complex arrays`_ for further information.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	189
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	190 The strides array is read-only for the consumer.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	191
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	192 .. c:member:: Py_ssize_t \*suboffsets
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	193
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	194 An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	195 If ``suboffsets[n] >= 0``, the values stored along the nth dimension are
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	196 pointers and the suboffset value dictates how many bytes to add to each
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	197 pointer after de-referencing. A suboffset value that is negative
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	198 indicates that no de-referencing should occur (striding in a contiguous
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	199 memory block).
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	200
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	201 This type of array representation is used by the Python Imaging Library
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	202 (PIL). See `complex arrays`_ for further information how to access elements
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	203 of such an array.
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	204
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	205 The suboffsets array is read-only for the consumer.
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	206
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	207 .. c:member:: void \*internal
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	208
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	209 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	210 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	211 about whether or not the shape, strides, and suboffsets arrays must be
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	212 freed when the buffer is released. The consumer MUST NOT alter this
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	213 value.
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	214
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	215 .. _buffer-request-types:
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	216
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	217 Buffer request types
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	218 ====================
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	219
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	220 Buffers are usually obtained by sending a buffer request to an exporting
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	221 object via :c:func:`PyObject_GetBuffer`. Since the complexity of the logical
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	222 structure of the memory can vary drastically, the consumer uses the flags
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	223 argument to specify the exact buffer type it can handle.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	224
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	225 All :c:data:`Py_buffer` fields are unambiguously defined by the request
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	226 type.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	227
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	228 request-independent fields
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	229 ~~~~~~~~~~~~~~~~~~~~~~~~~~
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	230 The following fields are not influenced by flags and must always be filled in
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	231 with the correct values: :c:member:`~Py_buffer.obj`, :c:member:`~Py_buffer.buf`,
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	232 :c:member:`~Py_buffer.len`, :c:member:`~Py_buffer.itemsize`, :c:member:`~Py_buffer.ndim`.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	233
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	234
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	235 readonly, format
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	236 ~~~~~~~~~~~~~~~~
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	237
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	238 .. c:macro:: PyBUF_WRITABLE
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	239
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	240 Controls the :c:member:`~Py_buffer.readonly` field. If set, the exporter
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	241 MUST provide a writable buffer or else report failure. Otherwise, the
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	242 exporter MAY provide either a read-only or writable buffer, but the choice
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	243 MUST be consistent for all consumers.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	244
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	245 .. c:macro:: PyBUF_FORMAT
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	246
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	247 Controls the :c:member:`~Py_buffer.format` field. If set, this field MUST
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	248 be filled in correctly. Otherwise, this field MUST be NULL.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	249
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	250
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	251 :c:macro:`PyBUF_WRITABLE` can be \\|'d to any of the flags in the next section.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	252 Since :c:macro:`PyBUF_SIMPLE` is defined as 0, :c:macro:`PyBUF_WRITABLE`
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	253 can be used as a stand-alone flag to request a simple writable buffer.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	254
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	255 :c:macro:`PyBUF_FORMAT` can be \\|'d to any of the flags except :c:macro:`PyBUF_SIMPLE`.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	256 The latter already implies format ``B`` (unsigned bytes).
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	257
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	258
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	259 shape, strides, suboffsets
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	260 ~~~~~~~~~~~~~~~~~~~~~~~~~~
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	261
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	262 The flags that control the logical structure of the memory are listed
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	263 in decreasing order of complexity. Note that each flag contains all bits
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	264 of the flags below it.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	265
82986 3ae74b361f53 Closes #4159: add LaTeX tabular column specifications to tables that otherwise are cut off or have overlapping text. Georg Brandl <georg@python.org> parents: 80542 diff changeset	266 .. tabularcolumns:: \|p{0.35\linewidth}\|l\|l\|l\|
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	267
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	268 +-----------------------------+-------+---------+------------+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	269 \| Request \| shape \| strides \| suboffsets \|
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	270 +=============================+=======+=========+============+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	271 \| .. c:macro:: PyBUF_INDIRECT \| yes \| yes \| if needed \|
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	272 +-----------------------------+-------+---------+------------+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	273 \| .. c:macro:: PyBUF_STRIDES \| yes \| yes \| NULL \|
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	274 +-----------------------------+-------+---------+------------+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	275 \| .. c:macro:: PyBUF_ND \| yes \| NULL \| NULL \|
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	276 +-----------------------------+-------+---------+------------+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	277 \| .. c:macro:: PyBUF_SIMPLE \| NULL \| NULL \| NULL \|
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	278 +-----------------------------+-------+---------+------------+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	279
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	280
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	281 contiguity requests
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	282 ~~~~~~~~~~~~~~~~~~~
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	283
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	284 C or Fortran contiguity can be explicitly requested, with and without stride
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	285 information. Without stride information, the buffer must be C-contiguous.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	286
82986 3ae74b361f53 Closes #4159: add LaTeX tabular column specifications to tables that otherwise are cut off or have overlapping text. Georg Brandl <georg@python.org> parents: 80542 diff changeset	287 .. tabularcolumns:: \|p{0.35\linewidth}\|l\|l\|l\|l\|
3ae74b361f53 Closes #4159: add LaTeX tabular column specifications to tables that otherwise are cut off or have overlapping text. Georg Brandl <georg@python.org> parents: 80542 diff changeset	288
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	289 +-----------------------------------+-------+---------+------------+--------+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	290 \| Request \| shape \| strides \| suboffsets \| contig \|
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	291 +===================================+=======+=========+============+========+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	292 \| .. c:macro:: PyBUF_C_CONTIGUOUS \| yes \| yes \| NULL \| C \|
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	293 +-----------------------------------+-------+---------+------------+--------+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	294 \| .. c:macro:: PyBUF_F_CONTIGUOUS \| yes \| yes \| NULL \| F \|
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	295 +-----------------------------------+-------+---------+------------+--------+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	296 \| .. c:macro:: PyBUF_ANY_CONTIGUOUS \| yes \| yes \| NULL \| C or F \|
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	297 +-----------------------------------+-------+---------+------------+--------+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	298 \| .. c:macro:: PyBUF_ND \| yes \| NULL \| NULL \| C \|
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	299 +-----------------------------------+-------+---------+------------+--------+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	300
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	301
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	302 compound requests
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	303 ~~~~~~~~~~~~~~~~~
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	304
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	305 All possible requests are fully defined by some combination of the flags in
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	306 the previous section. For convenience, the buffer protocol provides frequently
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	307 used combinations as single flags.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	308
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	309 In the following table U stands for undefined contiguity. The consumer would
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	310 have to call :c:func:`PyBuffer_IsContiguous` to determine contiguity.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	311
82986 3ae74b361f53 Closes #4159: add LaTeX tabular column specifications to tables that otherwise are cut off or have overlapping text. Georg Brandl <georg@python.org> parents: 80542 diff changeset	312 .. tabularcolumns:: \|p{0.35\linewidth}\|l\|l\|l\|l\|l\|l\|
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	313
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	314 +-------------------------------+-------+---------+------------+--------+----------+--------+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	315 \| Request \| shape \| strides \| suboffsets \| contig \| readonly \| format \|
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	316 +===============================+=======+=========+============+========+==========+========+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	317 \| .. c:macro:: PyBUF_FULL \| yes \| yes \| if needed \| U \| 0 \| yes \|
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	318 +-------------------------------+-------+---------+------------+--------+----------+--------+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	319 \| .. c:macro:: PyBUF_FULL_RO \| yes \| yes \| if needed \| U \| 1 or 0 \| yes \|
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	320 +-------------------------------+-------+---------+------------+--------+----------+--------+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	321 \| .. c:macro:: PyBUF_RECORDS \| yes \| yes \| NULL \| U \| 0 \| yes \|
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	322 +-------------------------------+-------+---------+------------+--------+----------+--------+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	323 \| .. c:macro:: PyBUF_RECORDS_RO \| yes \| yes \| NULL \| U \| 1 or 0 \| yes \|
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	324 +-------------------------------+-------+---------+------------+--------+----------+--------+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	325 \| .. c:macro:: PyBUF_STRIDED \| yes \| yes \| NULL \| U \| 0 \| NULL \|
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	326 +-------------------------------+-------+---------+------------+--------+----------+--------+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	327 \| .. c:macro:: PyBUF_STRIDED_RO \| yes \| yes \| NULL \| U \| 1 or 0 \| NULL \|
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	328 +-------------------------------+-------+---------+------------+--------+----------+--------+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	329 \| .. c:macro:: PyBUF_CONTIG \| yes \| NULL \| NULL \| C \| 0 \| NULL \|
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	330 +-------------------------------+-------+---------+------------+--------+----------+--------+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	331 \| .. c:macro:: PyBUF_CONTIG_RO \| yes \| NULL \| NULL \| C \| 1 or 0 \| NULL \|
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	332 +-------------------------------+-------+---------+------------+--------+----------+--------+
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	333
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	334
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	335 Complex arrays
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	336 ==============
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	337
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	338 NumPy-style: shape and strides
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	339 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	340
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	341 The logical structure of NumPy-style arrays is defined by :c:member:`~Py_buffer.itemsize`,
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	342 :c:member:`~Py_buffer.ndim`, :c:member:`~Py_buffer.shape` and :c:member:`~Py_buffer.strides`.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	343
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	344 If ``ndim == 0``, the memory location pointed to by :c:member:`~Py_buffer.buf` is
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	345 interpreted as a scalar of size :c:member:`~Py_buffer.itemsize`. In that case,
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	346 both :c:member:`~Py_buffer.shape` and :c:member:`~Py_buffer.strides` are NULL.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	347
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	348 If :c:member:`~Py_buffer.strides` is NULL, the array is interpreted as
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	349 a standard n-dimensional C-array. Otherwise, the consumer must access an
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	350 n-dimensional array as follows:
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	351
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	352 ``ptr = (char )buf + indices[0] strides[0] + ... + indices[n-1] * strides[n-1]``
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	353 ``item = ((typeof(item) )ptr);``
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	354
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	355
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	356 As noted above, :c:member:`~Py_buffer.buf` can point to any location within
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	357 the actual memory block. An exporter can check the validity of a buffer with
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	358 this function:
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	359
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	360 .. code-block:: python
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	361
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	362 def verify_structure(memlen, itemsize, ndim, shape, strides, offset):
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	363 """Verify that the parameters represent a valid array within
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	364 the bounds of the allocated memory:
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	365 char *mem: start of the physical memory block
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	366 memlen: length of the physical memory block
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	367 offset: (char *)buf - mem
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	368 """
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	369 if offset % itemsize:
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	370 return False
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	371 if offset < 0 or offset+itemsize > memlen:
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	372 return False
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	373 if any(v % itemsize for v in strides):
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	374 return False
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	375
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	376 if ndim <= 0:
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	377 return ndim == 0 and not shape and not strides
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	378 if 0 in shape:
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	379 return True
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	380
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	381 imin = sum(strides[j]*(shape[j]-1) for j in range(ndim)
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	382 if strides[j] <= 0)
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	383 imax = sum(strides[j]*(shape[j]-1) for j in range(ndim)
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	384 if strides[j] > 0)
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	385
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	386 return 0 <= offset+imin and offset+imax+itemsize <= memlen
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	387
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	388
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	389 PIL-style: shape, strides and suboffsets
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	390 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	391
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	392 In addition to the regular items, PIL-style arrays can contain pointers
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	393 that must be followed in order to get to the next element in a dimension.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	394 For example, the regular three-dimensional C-array ``char v[2][2][3]`` can
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	395 also be viewed as an array of 2 pointers to 2 two-dimensional arrays:
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	396 ``char (*v[2])[2][3]``. In suboffsets representation, those two pointers
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	397 can be embedded at the start of :c:member:`~Py_buffer.buf`, pointing
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	398 to two ``char x[2][3]`` arrays that can be located anywhere in memory.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	399
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	400
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	401 Here is a function that returns a pointer to the element in an N-D array
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	402 pointed to by an N-dimensional index when there are both non-NULL strides
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	403 and suboffsets::
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	404
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	405 void get_item_pointer(int ndim, void buf, Py_ssize_t *strides,
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	406 Py_ssize_t suboffsets, Py_ssize_t indices) {
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	407 char pointer = (char)buf;
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	408 int i;
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	409 for (i = 0; i < ndim; i++) {
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	410 pointer += strides[i] * indices[i];
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	411 if (suboffsets[i] >=0 ) {
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	412 pointer = ((char*)pointer) + suboffsets[i];
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	413 }
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	414 }
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	415 return (void*)pointer;
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	416 }
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	417
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	418
64999 c869ea07cd9d Merged revisions 85084 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64997 diff changeset	419 Buffer-related functions
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	420 ========================
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	421
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 65032 diff changeset	422 .. c:function:: int PyObject_CheckBuffer(PyObject *obj)
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	423
64995 5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	424 Return 1 if obj supports the buffer interface otherwise 0. When 1 is
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 65032 diff changeset	425 returned, it doesn't guarantee that :c:func:`PyObject_GetBuffer` will
64995 5522c6b2af87 Merged revisions 85080 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64981 diff changeset	426 succeed.
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	427
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	428
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	429 .. c:function:: int PyObject_GetBuffer(PyObject exporter, Py_buffer view, int flags)
65033 cb2fbb5e6409 Merged revisions 85132 via svnmerge from Georg Brandl <georg@python.org> parents: 64999 diff changeset	430
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	431 Send a request to exporter to fill in view as specified by flags.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	432 If the exporter cannot provide a buffer of the exact type, it MUST raise
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	433 :c:data:`PyExc_BufferError`, set :c:member:`view->obj` to NULL and
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	434 return -1.
65033 cb2fbb5e6409 Merged revisions 85132 via svnmerge from Georg Brandl <georg@python.org> parents: 64999 diff changeset	435
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	436 On success, fill in view, set :c:member:`view->obj` to a new reference
75455 da2aaced21bd Issue #14181: Improve clarity in the documentation for the multi-purpose Stefan Krah <skrah@bytereef.org> parents: 75254 diff changeset	437 to exporter and return 0. In the case of chained buffer providers
da2aaced21bd Issue #14181: Improve clarity in the documentation for the multi-purpose Stefan Krah <skrah@bytereef.org> parents: 75254 diff changeset	438 that redirect requests to a single object, :c:member:`view->obj` MAY
da2aaced21bd Issue #14181: Improve clarity in the documentation for the multi-purpose Stefan Krah <skrah@bytereef.org> parents: 75254 diff changeset	439 refer to this object instead of exporter (See :ref:`Buffer Object Structures <buffer-structs>`).
65033 cb2fbb5e6409 Merged revisions 85132 via svnmerge from Georg Brandl <georg@python.org> parents: 64999 diff changeset	440
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	441 Successful calls to :c:func:`PyObject_GetBuffer` must be paired with calls
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	442 to :c:func:`PyBuffer_Release`, similar to :c:func:`malloc` and :c:func:`free`.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	443 Thus, after the consumer is done with the buffer, :c:func:`PyBuffer_Release`
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	444 must be called exactly once.
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	445
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	446
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 65032 diff changeset	447 .. c:function:: void PyBuffer_Release(Py_buffer *view)
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	448
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	449 Release the buffer view and decrement the reference count for
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	450 :c:member:`view->obj`. This function MUST be called when the buffer
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	451 is no longer being used, otherwise reference leaks may occur.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	452
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	453 It is an error to call this function on a buffer that was not obtained via
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	454 :c:func:`PyObject_GetBuffer`.
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	455
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	456
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 65032 diff changeset	457 .. c:function:: Py_ssize_t PyBuffer_SizeFromFormat(const char *)
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	458
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	459 Return the implied :c:data:`~Py_buffer.itemsize` from :c:data:`~Py_buffer.format`.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	460 This function is not yet implemented.
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	461
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	462
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	463 .. c:function:: int PyBuffer_IsContiguous(Py_buffer *view, char order)
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	464
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	465 Return 1 if the memory defined by the view is C-style (order is
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	466 ``'C'``) or Fortran-style (order is ``'F'``) contiguous or either one
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	467 (order is ``'A'``). Return 0 otherwise.
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	468
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	469
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	470 .. c:function:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t shape, Py_ssize_t strides, Py_ssize_t itemsize, char order)
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	471
3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	472 Fill the strides array with byte-strides of a contiguous (C-style if
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	473 order is ``'C'`` or Fortran-style if order is ``'F'``) array of the
49205 3302045bae97 add documentation for the new buffer interface based on PEP 3118; I hope it's at least 60% right... Benjamin Peterson <benjamin@python.org> parents: 44812 diff changeset	474 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	475
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	476
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	477 .. c:function:: int PyBuffer_FillInfo(Py_buffer view, PyObject exporter, void *buf, Py_ssize_t len, int readonly, int flags)
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	478
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	479 Handle buffer requests for an exporter that wants to expose buf of size len
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	480 with writability set according to readonly. buf is interpreted as a sequence
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	481 of unsigned bytes.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	482
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	483 The flags argument indicates the request type. This function always fills in
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	484 view as specified by flags, unless buf has been designated as read-only
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	485 and :c:macro:`PyBUF_WRITABLE` is set in 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	486
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	487 On success, set :c:member:`view->obj` to a new reference to exporter and
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	488 return 0. Otherwise, raise :c:data:`PyExc_BufferError`, set
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	489 :c:member:`view->obj` to NULL and return -1;
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	490
75254 3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	491 If this function is used as part of a :ref:`getbufferproc <buffer-structs>`,
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	492 exporter MUST be set to the exporting object. Otherwise, exporter MUST
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	493 be NULL.
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	494
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	495
3f9b3b6f7ff0 - Issue #10181: New memoryview implementation fixes multiple ownership Stefan Krah <skrah@bytereef.org> parents: 70224 diff changeset	496

Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/buffer.rst @ 87690:66c1c9f32567 default tip