The new-style Py_buffer struct¶

Py_buffer¶

void *buf¶

A pointer to the start of the memory for the object.

Py_ssize_tlen

The total length of the memory in bytes.

intreadonly¶

An indicator of whether the buffer is read only.

const char *format

ANULL terminated string instruct module style syntax givingthe contents of the elements available through the buffer. If this isNULL,"B" (unsigned bytes) is assumed.

intndim¶

The number of dimensions the memory represents as a multi-dimensionalarray. If it is0,strides andsuboffsets must beNULL.

Py_ssize_t *shape¶

An array ofPy_ssize_ts the length ofndim giving theshape of the memory as a multi-dimensional array. Note that((*shape)[0]*...*(*shape)[ndims-1])*itemsize should be equal tolen.

Py_ssize_t *strides¶

An array ofPy_ssize_ts the length ofndim giving thenumber of bytes to skip to get to a new element in each dimension.

Py_ssize_t *suboffsets¶

An array ofPy_ssize_ts the length ofndim. If thesesuboffset numbers are greater than or equal to 0, then the value storedalong the indicated dimension is a pointer and the suboffset valuedictates how many bytes to add to the pointer after de-referencing. Asuboffset value that it negative indicates that no de-referencing shouldoccur (striding in a contiguous memory block).

If all suboffsets are negative (i.e. no de-referencing is needed), thenthis field must be NULL (the default value).

Here is a function that returns a pointer to the element in an N-D arraypointed to by an N-dimensional index when there are both non-NULL stridesand suboffsets:

void*get_item_pointer(intndim,void*buf,Py_ssize_t*strides,Py_ssize_t*suboffsets,Py_ssize_t*indices){char*pointer=(char*)buf;inti;for(i=0;i<ndim;i++){pointer+=strides[i]*indices[i];if(suboffsets[i]>=0){pointer=*((char**)pointer)+suboffsets[i];}}return(void*)pointer;}

Py_ssize_titemsize¶

This is a storage for the itemsize (in bytes) of each element of theshared memory. It is technically un-necessary as it can be obtainedusingPyBuffer_SizeFromFormat(), however an exporter may knowthis information without parsing the format string and it is necessaryto know the itemsize for proper interpretation of striding. Therefore,storing it is more convenient and faster.

void *internal¶

This is for use internally by the exporting object. For example, thismight be re-cast as an integer by the exporter and used to store flagsabout whether or not the shape, strides, and suboffsets arrays must befreed when the buffer is released. The consumer should never alter thisvalue.

Buffer related functions¶

intPyObject_CheckBuffer(PyObject *obj)¶

Return1 ifobj supports the buffer interface otherwise0.

intPyObject_GetBuffer(PyObject *obj,Py_buffer *view, int flags)¶

Exportobj into aPy_buffer,view. These arguments mustnever beNULL. Theflags argument is a bit field indicating whatkind of buffer the caller is prepared to deal with and therefore whatkind of buffer the exporter is allowed to return. The buffer interfaceallows for complicated memory sharing possibilities, but some caller maynot be able to handle all the complexity but may want to see if theexporter will let them take a simpler view to its memory.

Some exporters may not be able to share memory in every possible way andmay need to raise errors to signal to some consumers that something isjust not possible. These errors should be aBufferError unlessthere is another error that is actually causing the problem. Theexporter can use flags information to simplify how much of thePy_buffer structure is filled in with non-default values and/orraise an error if the object can’t support a simpler view of its memory.

0 is returned on success and-1 on error.

The following table gives possible values to theflags arguments.

Flag	Description
PyBUF_SIMPLE	This is the default flag state. The returnedbuffer may or may not have writable memory. Theformat of the data will be assumed to be unsignedbytes. This is a “stand-alone” flag constant. Itnever needs to be ‘|’d to the others. The exporterwill raise an error if it cannot provide such acontiguous buffer of bytes.
PyBUF_WRITABLE	The returned buffer must be writable. If it isnot writable, then raise an error.
PyBUF_STRIDES	This impliesPyBUF_ND. The returnedbuffer must provide strides information (i.e. thestrides cannot be NULL). This would be used whenthe consumer can handle strided, discontiguousarrays. Handling strides automatically assumesyou can handle shape. The exporter can raise anerror if a strided representation of the data isnot possible (i.e. without the suboffsets).
PyBUF_ND	The returned buffer must provide shapeinformation. The memory will be assumed C-stylecontiguous (last dimension varies thefastest). The exporter may raise an error if itcannot provide this kind of contiguous buffer. Ifthis is not given then shape will beNULL.
PyBUF_C_CONTIGUOUSPyBUF_F_CONTIGUOUSPyBUF_ANY_CONTIGUOUS	These flags indicate that the contiguity returnedbuffer must be respectively, C-contiguous (lastdimension varies the fastest), Fortran contiguous(first dimension varies the fastest) or eitherone. All of these flags implyPyBUF_STRIDES and guarantee that thestrides buffer info structure will be filled incorrectly.
PyBUF_INDIRECT	This flag indicates the returned buffer must havesuboffsets information (which can be NULL if nosuboffsets are needed). This can be used whenthe consumer can handle indirect arrayreferencing implied by these suboffsets. ThisimpliesPyBUF_STRIDES.
PyBUF_FORMAT	The returned buffer must have true formatinformation if this flag is provided. This wouldbe used when the consumer is going to be checkingfor what ‘kind’ of data is actually stored. Anexporter should always be able to provide thisinformation if requested. If format is notexplicitly requested then the format must bereturned asNULL (which means'B', orunsigned bytes)
PyBUF_STRIDED	This is equivalent to(PyBUF_STRIDES|PyBUF_WRITABLE).
PyBUF_STRIDED_RO	This is equivalent to(PyBUF_STRIDES).
PyBUF_RECORDS	This is equivalent to(PyBUF_STRIDES|PyBUF_FORMAT|PyBUF_WRITABLE).
PyBUF_RECORDS_RO	This is equivalent to(PyBUF_STRIDES|PyBUF_FORMAT).
PyBUF_FULL	This is equivalent to(PyBUF_INDIRECT|PyBUF_FORMAT|PyBUF_WRITABLE).
PyBUF_FULL_RO	This is equivalent to(PyBUF_INDIRECT|PyBUF_FORMAT).
PyBUF_CONTIG	This is equivalent to(PyBUF_ND|PyBUF_WRITABLE).
PyBUF_CONTIG_RO	This is equivalent to(PyBUF_ND).

voidPyBuffer_Release(Py_buffer *view)¶

Release the bufferview. This should be called when the bufferis no longer being used as it may free memory from it.

Py_ssize_tPyBuffer_SizeFromFormat(const char *)¶

Return the implieditemsize from the struct-stypeformat.

intPyBuffer_IsContiguous(Py_buffer *view, char fortran)¶

Return1 if the memory defined by theview is C-style (fortran is'C') or Fortran-style (fortran is'F') contiguous or either one(fortran is'A'). Return0 otherwise.

voidPyBuffer_FillContiguousStrides(int ndims, Py_ssize_t *shape, Py_ssize_t *strides, int itemsize, char fortran)¶

Fill thestrides array with byte-strides of a contiguous (C-style iffortran is'C' or Fortran-style iffortran is'F') array of thegiven shape with the given number of bytes per element.

intPyBuffer_FillInfo(Py_buffer *view,PyObject *obj, void *buf, Py_ssize_t len, int readonly, int infoflags)¶

Fill in a buffer-info structure,view, correctly for an exporter that canonly share a contiguous chunk of memory of “unsigned bytes” of the givenlength. Return0 on success and-1 (with raising an error) on error.

MemoryView objects¶

Amemoryview object exposes the new C level buffer interface as aPython object which can then be passed around like any other object.

PyObject *PyMemoryView_FromObject(PyObject *obj)¶

Create a memoryview object from an object that defines the new bufferinterface.

PyObject *PyMemoryView_FromBuffer(Py_buffer *view)¶

Create a memoryview object wrapping the given buffer-info structureview.The memoryview object then owns the buffer, which means you shouldn’ttry to release it yourself: it will be released on deallocation of thememoryview object.

PyObject *PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order)¶

Create a memoryview object to a contiguous chunk of memory (in either‘C’ or ‘F’ortranorder) from an object that defines the bufferinterface. If memory is contiguous, the memoryview object points to theoriginal memory. Otherwise copy is made and the memoryview points to anew bytes object.

intPyMemoryView_Check(PyObject *obj)¶

Return true if the objectobj is a memoryview object. It is notcurrently allowed to create subclasses ofmemoryview.

Py_buffer *PyMemoryView_GET_BUFFER(PyObject *obj)¶

Return a pointer to the buffer-info structure wrapped by the givenobject. The objectmust be a memoryview instance; this macro doesn’tcheck its type, you must do it yourself or you will risk crashes.

Old-style buffer objects¶

More information on the old buffer interface is provided in the sectionBuffer Object Structures, under the description forPyBufferProcs.

A “buffer object” is defined in thebufferobject.h header (included byPython.h). These objects look very similar to string objects at thePython programming level: they support slicing, indexing, concatenation, andsome other standard string operations. However, their data can come from oneof two sources: from a block of memory, or from another object which exportsthe buffer interface.

Buffer objects are useful as a way to expose the data from another object’sbuffer interface to the Python programmer. They can also be used as azero-copy slicing mechanism. Using their ability to reference a block ofmemory, it is possible to expose any data to the Python programmer quiteeasily. The memory could be a large, constant array in a C extension, it couldbe a raw block of memory for manipulation before passing to an operatingsystem library, or it could be used to pass around structured data in itsnative, in-memory format.

PyBufferObject¶

This subtype ofPyObject represents a buffer object.

PyTypeObjectPyBuffer_Type¶

The instance ofPyTypeObject which represents the Python buffer type;it is the same object asbuffer andtypes.BufferType in the Pythonlayer. .

intPy_END_OF_BUFFER¶

This constant may be passed as thesize parameter toPyBuffer_FromObject() orPyBuffer_FromReadWriteObject(). Itindicates that the newPyBufferObject should refer tobaseobject from the specifiedoffset to the end of its exported buffer.Using this enables the caller to avoid querying thebase object for itslength.

intPyBuffer_Check(PyObject *p)¶

Return true if the argument has typePyBuffer_Type.

PyObject*PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)¶

Return value: New reference.

Return a new read-only buffer object. This raisesTypeError ifbase doesn’t support the read-only buffer protocol or doesn’t provideexactly one buffer segment, or it raisesValueError ifoffset isless than zero. The buffer will hold a reference to thebase object, andthe buffer’s contents will refer to thebase object’s buffer interface,starting as positionoffset and extending forsize bytes. Ifsize isPy_END_OF_BUFFER, then the new buffer’s contents extend to thelength of thebase object’s exported buffer data.

Changed in version 2.5:This function used anint type foroffset andsize. Thismight require changes in your code for properly supporting 64-bitsystems.

PyObject*PyBuffer_FromReadWriteObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)¶

Return value: New reference.

Return a new writable buffer object. Parameters and exceptions are similarto those forPyBuffer_FromObject(). If thebase object does notexport the writeable buffer protocol, thenTypeError is raised.

Changed in version 2.5:This function used anint type foroffset andsize. Thismight require changes in your code for properly supporting 64-bitsystems.

PyObject*PyBuffer_FromMemory(void *ptr, Py_ssize_t size)¶

Return value: New reference.

Return a new read-only buffer object that reads from a specified locationin memory, with a specified size. The caller is responsible for ensuringthat the memory buffer, passed in asptr, is not deallocated while thereturned buffer object exists. RaisesValueError ifsize is lessthan zero. Note thatPy_END_OF_BUFFER maynot be passed for thesize parameter;ValueError will be raised in that case.

Changed in version 2.5:This function used anint type forsize. This might requirechanges in your code for properly supporting 64-bit systems.

PyObject*PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size)¶

Return value: New reference.

Similar toPyBuffer_FromMemory(), but the returned buffer iswritable.

Changed in version 2.5:This function used anint type forsize. This might requirechanges in your code for properly supporting 64-bit systems.

PyObject*PyBuffer_New(Py_ssize_t size)¶

Return value: New reference.

Return a new writable buffer object that maintains its own memory buffer ofsize bytes.ValueError is returned ifsize is not zero orpositive. Note that the memory buffer (as returned byPyObject_AsWriteBuffer()) is not specifically aligned.

Changed in version 2.5:This function used anint type forsize. This might requirechanges in your code for properly supporting 64-bit systems.