Since I edited this file, reformat for future edits.
This commit is contained in:
Jeroen Ruigrok van der Werven
parent
c2aa7b8a0a
commit
1ae8c88030
|
|
@ -14,9 +14,10 @@ Buffers and Memoryview Objects
|
|||
single: buffer interface
|
||||
|
||||
Python objects implemented in C can export a group of functions called the
|
||||
"buffer interface." These functions can be used by an object to expose its data
|
||||
in a raw, byte-oriented format. Clients of the object can use the buffer
|
||||
interface to access the object data directly, without needing to copy it first.
|
||||
"buffer interface." These functions can be used by an object to expose its
|
||||
data in a raw, byte-oriented format. Clients of the object can use the buffer
|
||||
interface to access the object data directly, without needing to copy it
|
||||
first.
|
||||
|
||||
Two examples of objects that support the buffer interface are strings and
|
||||
arrays. The string object exposes the character contents in the buffer
|
||||
|
|
@ -30,10 +31,10 @@ interface can be written to a file. There are a number of format codes to
|
|||
returning data from the target object.
|
||||
|
||||
Starting from version 1.6, Python has been providing Python-level buffer
|
||||
objects and a C-level buffer API so that any builtin or used-defined type
|
||||
can expose its characteristics. Both, however, have been deprecated because
|
||||
of various shortcomings, and have been officially removed in Python 3.0 in
|
||||
favour of a new C-level buffer API and a new Python-level object named
|
||||
objects and a C-level buffer API so that any builtin or used-defined type can
|
||||
expose its characteristics. Both, however, have been deprecated because of
|
||||
various shortcomings, and have been officially removed in Python 3.0 in favour
|
||||
of a new C-level buffer API and a new Python-level object named
|
||||
:class:`memoryview`.
|
||||
|
||||
The new buffer API has been backported to Python 2.6, and the
|
||||
|
|
@ -64,9 +65,9 @@ The new-style Py_buffer struct
|
|||
.. cmember:: const char *format
|
||||
:noindex:
|
||||
|
||||
A *NULL* terminated string in :mod:`struct` module style syntax giving the
|
||||
contents of the elements available through the buffer. If this is *NULL*,
|
||||
``"B"`` (unsigned bytes) is assumed.
|
||||
A *NULL* terminated string in :mod:`struct` module style syntax giving
|
||||
the contents of the elements available through the buffer. If this is
|
||||
*NULL*, ``"B"`` (unsigned bytes) is assumed.
|
||||
|
||||
.. cmember:: int ndim
|
||||
|
||||
|
|
@ -116,11 +117,11 @@ The new-style Py_buffer struct
|
|||
.. cmember:: Py_ssize_t itemsize
|
||||
|
||||
This is a storage for the itemsize (in bytes) of each element of the
|
||||
shared memory. It is technically un-necessary as it can be obtained using
|
||||
:cfunc:`PyBuffer_SizeFromFormat`, however an exporter may know this
|
||||
information without parsing the format string and it is necessary to know
|
||||
the itemsize for proper interpretation of striding. Therefore, storing it
|
||||
is more convenient and faster.
|
||||
shared memory. It is technically un-necessary as it can be obtained
|
||||
using :cfunc:`PyBuffer_SizeFromFormat`, however an exporter may know
|
||||
this information without parsing the format string and it is necessary
|
||||
to know the itemsize for proper interpretation of striding. Therefore,
|
||||
storing it is more convenient and faster.
|
||||
|
||||
.. cmember:: void *internal
|
||||
|
||||
|
|
@ -143,20 +144,20 @@ Buffer related functions
|
|||
.. cfunction:: int PyObject_GetBuffer(PyObject *obj, PyObject *view, int flags)
|
||||
|
||||
Export *obj* into a :ctype:`Py_buffer`, *view*. These arguments must
|
||||
never be *NULL*. The *flags* argument is a bit field indicating what kind
|
||||
of buffer the caller is prepared to deal with and therefore what kind of
|
||||
buffer the exporter is allowed to return. The buffer interface allows for
|
||||
complicated memory sharing possibilities, but some caller may not be able
|
||||
to handle all the complexibity but may want to see if the exporter will
|
||||
let them take a simpler view to its memory.
|
||||
never be *NULL*. The *flags* argument is a bit field indicating what
|
||||
kind of buffer the caller is prepared to deal with and therefore what
|
||||
kind of buffer the exporter is allowed to return. The buffer interface
|
||||
allows for complicated memory sharing possibilities, but some caller may
|
||||
not be able to handle all the complexibity but may want to see if the
|
||||
exporter will let them take a simpler view to its memory.
|
||||
|
||||
Some exporters may not be able to share memory in every possible way and
|
||||
may need to raise errors to signal to some consumers that something is
|
||||
just not possible. These errors should be a :exc:`BufferError` unless
|
||||
there is another error that is actually causing the problem. The exporter
|
||||
can use flags information to simplify how much of the :cdata:`Py_buffer`
|
||||
structure is filled in with non-default values and/or raise an error if
|
||||
the object can't support a simpler view of its memory.
|
||||
there is another error that is actually causing the problem. The
|
||||
exporter can use flags information to simplify how much of the
|
||||
:cdata:`Py_buffer` structure is filled in with non-default values and/or
|
||||
raise an error if the object can't support a simpler view of its memory.
|
||||
|
||||
0 is returned on success and -1 on error.
|
||||
|
||||
|
|
@ -267,16 +268,16 @@ Buffer related functions
|
|||
|
||||
.. cfunction:: int PyObject_CopyToObject(PyObject *obj, void *buf, Py_ssize_t len, char fortran)
|
||||
|
||||
Copy *len* bytes of data pointed to by the contiguous chunk of memory pointed
|
||||
to by *buf* into the buffer exported by obj. The buffer must of course be
|
||||
writable. Return 0 on success and return -1 and raise an error on failure.
|
||||
If the object does not have a writable buffer, then an error is raised. If
|
||||
*fortran* is ``'F'``, then if the object is multi-dimensional, then the data
|
||||
will be copied into the array in Fortran-style (first dimension varies the
|
||||
fastest). If *fortran* is ``'C'``, then the data will be copied into the
|
||||
array in C-style (last dimension varies the fastest). If *fortran* is
|
||||
``'A'``, then it does not matter and the copy will be made in whatever way is
|
||||
more efficient.
|
||||
Copy *len* bytes of data pointed to by the contiguous chunk of memory
|
||||
pointed to by *buf* into the buffer exported by obj. The buffer must of
|
||||
course be writable. Return 0 on success and return -1 and raise an error
|
||||
on failure. If the object does not have a writable buffer, then an error
|
||||
is raised. If *fortran* is ``'F'``, then if the object is
|
||||
multi-dimensional, then the data will be copied into the array in
|
||||
Fortran-style (first dimension varies the fastest). If *fortran* is
|
||||
``'C'``, then the data will be copied into the array in C-style (last
|
||||
dimension varies the fastest). If *fortran* is ``'A'``, then it does not
|
||||
matter and the copy will be made in whatever way is more efficient.
|
||||
|
||||
|
||||
.. cfunction:: int PyBuffer_IsContiguous(Py_buffer *view, char fortran)
|
||||
|
|
@ -324,17 +325,18 @@ More information on the old buffer interface is provided in the section
|
|||
A "buffer object" is defined in the :file:`bufferobject.h` header (included by
|
||||
:file:`Python.h`). These objects look very similar to string objects at the
|
||||
Python programming level: they support slicing, indexing, concatenation, and
|
||||
some other standard string operations. However, their data can come from one of
|
||||
two sources: from a block of memory, or from another object which exports the
|
||||
buffer interface.
|
||||
some other standard string operations. However, their data can come from one
|
||||
of two sources: from a block of memory, or from another object which exports
|
||||
the buffer interface.
|
||||
|
||||
Buffer objects are useful as a way to expose the data from another object's
|
||||
buffer interface to the Python programmer. They can also be used as a zero-copy
|
||||
slicing mechanism. Using their ability to reference a block of memory, it is
|
||||
possible to expose any data to the Python programmer quite easily. The memory
|
||||
could be a large, constant array in a C extension, it could be a raw block of
|
||||
memory for manipulation before passing to an operating system library, or it
|
||||
could be used to pass around structured data in its native, in-memory format.
|
||||
buffer interface to the Python programmer. They can also be used as a
|
||||
zero-copy slicing mechanism. Using their ability to reference a block of
|
||||
memory, it is possible to expose any data to the Python programmer quite
|
||||
easily. The memory could be a large, constant array in a C extension, it could
|
||||
be a raw block of memory for manipulation before passing to an operating
|
||||
system library, or it could be used to pass around structured data in its
|
||||
native, in-memory format.
|
||||
|
||||
|
||||
.. ctype:: PyBufferObject
|
||||
|
|
@ -355,9 +357,10 @@ could be used to pass around structured data in its native, in-memory format.
|
|||
|
||||
This constant may be passed as the *size* parameter to
|
||||
:cfunc:`PyBuffer_FromObject` or :cfunc:`PyBuffer_FromReadWriteObject`. It
|
||||
indicates that the new :ctype:`PyBufferObject` should refer to *base* object
|
||||
from the specified *offset* to the end of its exported buffer. Using this
|
||||
enables the caller to avoid querying the *base* object for its length.
|
||||
indicates that the new :ctype:`PyBufferObject` should refer to *base*
|
||||
object from the specified *offset* to the end of its exported buffer.
|
||||
Using this enables the caller to avoid querying the *base* object for its
|
||||
length.
|
||||
|
||||
|
||||
.. cfunction:: int PyBuffer_Check(PyObject *p)
|
||||
|
|
@ -367,14 +370,14 @@ could be used to pass around structured data in its native, in-memory format.
|
|||
|
||||
.. cfunction:: PyObject* PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
|
||||
|
||||
Return a new read-only buffer object. This raises :exc:`TypeError` if *base*
|
||||
doesn't support the read-only buffer protocol or doesn't provide exactly one
|
||||
buffer segment, or it raises :exc:`ValueError` if *offset* is less than zero.
|
||||
The buffer will hold a reference to the *base* object, and the buffer's contents
|
||||
will refer to the *base* object's buffer interface, starting as position
|
||||
*offset* and extending for *size* bytes. If *size* is :const:`Py_END_OF_BUFFER`,
|
||||
then the new buffer's contents extend to the length of the *base* object's
|
||||
exported buffer data.
|
||||
Return a new read-only buffer object. This raises :exc:`TypeError` if
|
||||
*base* doesn't support the read-only buffer protocol or doesn't provide
|
||||
exactly one buffer segment, or it raises :exc:`ValueError` if *offset* is
|
||||
less than zero. The buffer will hold a reference to the *base* object, and
|
||||
the buffer's contents will refer to the *base* object's buffer interface,
|
||||
starting as position *offset* and extending for *size* bytes. If *size* is
|
||||
:const:`Py_END_OF_BUFFER`, then the new buffer's contents extend to the
|
||||
length of the *base* object's exported buffer data.
|
||||
|
||||
.. versionchanged:: 2.5
|
||||
This function used an :ctype:`int` type for *offset* and *size*. This
|
||||
|
|
@ -384,9 +387,9 @@ could be used to pass around structured data in its native, in-memory format.
|
|||
|
||||
.. cfunction:: PyObject* PyBuffer_FromReadWriteObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
|
||||
|
||||
Return a new writable buffer object. Parameters and exceptions are similar to
|
||||
those for :cfunc:`PyBuffer_FromObject`. If the *base* object does not export
|
||||
the writeable buffer protocol, then :exc:`TypeError` is raised.
|
||||
Return a new writable buffer object. Parameters and exceptions are similar
|
||||
to those for :cfunc:`PyBuffer_FromObject`. If the *base* object does not
|
||||
export the writeable buffer protocol, then :exc:`TypeError` is raised.
|
||||
|
||||
.. versionchanged:: 2.5
|
||||
This function used an :ctype:`int` type for *offset* and *size*. This
|
||||
|
|
@ -396,12 +399,12 @@ could be used to pass around structured data in its native, in-memory format.
|
|||
|
||||
.. cfunction:: PyObject* PyBuffer_FromMemory(void *ptr, Py_ssize_t size)
|
||||
|
||||
Return a new read-only buffer object that reads from a specified location in
|
||||
memory, with a specified size. The caller is responsible for ensuring that the
|
||||
memory buffer, passed in as *ptr*, is not deallocated while the returned buffer
|
||||
object exists. Raises :exc:`ValueError` if *size* is less than zero. Note that
|
||||
:const:`Py_END_OF_BUFFER` may *not* be passed for the *size* parameter;
|
||||
:exc:`ValueError` will be raised in that case.
|
||||
Return a new read-only buffer object that reads from a specified location
|
||||
in memory, with a specified size. The caller is responsible for ensuring
|
||||
that the memory buffer, passed in as *ptr*, is not deallocated while the
|
||||
returned buffer object exists. Raises :exc:`ValueError` if *size* is less
|
||||
than zero. Note that :const:`Py_END_OF_BUFFER` may *not* be passed for the
|
||||
*size* parameter; :exc:`ValueError` will be raised in that case.
|
||||
|
||||
.. versionchanged:: 2.5
|
||||
This function used an :ctype:`int` type for *size*. This might require
|
||||
|
|
@ -410,7 +413,8 @@ could be used to pass around structured data in its native, in-memory format.
|
|||
|
||||
.. cfunction:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size)
|
||||
|
||||
Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is writable.
|
||||
Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is
|
||||
writable.
|
||||
|
||||
.. versionchanged:: 2.5
|
||||
This function used an :ctype:`int` type for *size*. This might require
|
||||
|
|
@ -420,9 +424,9 @@ could be used to pass around structured data in its native, in-memory format.
|
|||
.. cfunction:: PyObject* PyBuffer_New(Py_ssize_t size)
|
||||
|
||||
Return a new writable buffer object that maintains its own memory buffer of
|
||||
*size* bytes. :exc:`ValueError` is returned if *size* is not zero or positive.
|
||||
Note that the memory buffer (as returned by :cfunc:`PyObject_AsWriteBuffer`) is
|
||||
not specifically aligned.
|
||||
*size* bytes. :exc:`ValueError` is returned if *size* is not zero or
|
||||
positive. Note that the memory buffer (as returned by
|
||||
:cfunc:`PyObject_AsWriteBuffer`) is not specifically aligned.
|
||||
|
||||
.. versionchanged:: 2.5
|
||||
This function used an :ctype:`int` type for *size*. This might require
|
||||
|
|
|
|||
Loading…
Reference in New Issue