From 1ae8c880300aeebf8976ee39db5c346c3861192a Mon Sep 17 00:00:00 2001 From: Jeroen Ruigrok van der Werven Date: Sat, 25 Apr 2009 19:04:15 +0000 Subject: Since I edited this file, reformat for future edits. --- Doc/c-api/buffer.rst | 140 ++++++++++++++++++++++++++------------------------- 1 file changed, 72 insertions(+), 68 deletions(-) diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst index 1e80abc..da7a8e4 100644 --- a/Doc/c-api/buffer.rst +++ b/Doc/c-api/buffer.rst @@ -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 -- cgit v0.12