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

annotate Doc/c-api/buffer.rst @ 84007:dbfbdf2b5c19 3.3

Fix #17967: For ftp urls CWD to target instead of hopping to each directory towards target. This fixes a bug where target is accessible, but parent directories are restricted.

author	Senthil Kumaran <senthil@uthcode.com>
date	Sat, 01 Jun 2013 08:27:06 -0700
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 @ 84007:dbfbdf2b5c19 3.3