Search code examples
pythoncpythonpep3118pybuffer

What's the usage "multi-dimensional array" of Py_buffer in 2.x?


http://docs.python.org/2/c-api/buffer.html

int ndim

The number of dimensions the memory represents as a multi-dimensional array. If it is 0, strides and suboffsets must be NULL.

What's the real world usage for this? Is it used for scatter gather vector buffers?


Solution

  • Using ndim and shape is primarily for multidimensional fixed-shape arrays. For example, if you wanted to build something like NumPy from scratch, you might build it around the buffer API. There are also variations to make things easy for NumPy, PIL, and modules that wrap typical C and Fortran array-processing libraries.

    If you read a bit further down, the next two values both say "See complex arrays for more information." If you click that link, it gives you an example of doing something like NumPy, and describes how it works.

    Also see PEP 3118 for some rationale.

    It's not (primarily) for jagged-shaped arrays, like the scatter/gather use. While you can use PIL-style suboffsets for that, it's generally simpler to just use a list or array of buffers (unless you're trying to interface with PIL, of course).

    (The old-style buffer API did support a mode designed specifically for scatter/gather-like use, but it was dropped in Python 3.x, and deprecated in 2.6+ once the 3.x API was backported, basically because nobody ever used it.)