PyBUF (Jython API documentation)
Date: 2022-09-10

org.python.core

## Interface PyBUF

- All Known Subinterfaces:
    PyBuffer
  All Known Implementing Classes:
    Base1DBuffer, BaseArrayBuffer, BaseBuffer, BaseNIOBuffer, SimpleBuffer, SimpleNIOBuffer, SimpleStringBuffer, SimpleWritableBuffer, Strided1DBuffer, Strided1DNIOBuffer, Strided1DWritableBuffer, ZeroByteBuffer

      public interface PyBUF

  This interface provides a base for the key interface of the buffer API, `PyBuffer`, including symbolic constants used by the consumer of a `PyBuffer` to specify its requirements and assumptions. The Jython buffer API emulates the CPython buffer API. There are two reasons for separating parts of `PyBuffer` into this interface:
  - The constants defined in CPython have the names `PyBUF_SIMPLE`, `PyBUF_WRITABLE`, etc., and the trick of defining ours here means we can write `PyBUF.SIMPLE`, `PyBUF.WRITABLE`, etc. so source code looks similar.
  - It is not so easy in Java as it is in C to treat a `byte` array as storing anything other than `byte`, and we prepare for the possibility of buffers with a series of different primitive types by defining here those methods that would be in common between (Byte)`Buffer` and an assumed future `FloatBuffer` or `TypedBuffer<T>`. (Compare `java.nio.Buffer`.)
  It is unlikely any classes would implement `PyBUF`, except indirectly through other interfaces. Users of the Jython buffer API can mostly overlook the distinction and just use `PyBuffer`.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `ANY_CONTIGUOUS` A constant used by the consumer in its call to `BufferProtocol.getBuffer(int)` to specify that it will assume a contiguous organisation of the items, but will enquire which organisation it actually is.
    `static int` | `AS_ARRAY` A constant used by the consumer in its call to `BufferProtocol.getBuffer(int)` to specify that it expects to access the buffer contents directly as an array (rather than through the purely abstract part of the API).
    `static int` | `C_CONTIGUOUS` A constant used by the consumer in its call to `BufferProtocol.getBuffer(int)` to specify that it will assume C-order organisation of the items.
    `static int` | `CONTIG` Equivalent to `(ND | WRITABLE)`
    `static int` | `CONTIG_RO` Equivalent to `ND`
    `static int` | `CONTIGUITY` Field mask, used as in if `((flags&CONTIGUITY)== ... ) ...`.
    `static int` | `F_CONTIGUOUS` A constant used by the consumer in its call to `BufferProtocol.getBuffer(int)` to specify that it will assume Fortran-order organisation of the items.
    `static int` | `FORMAT` A constant used by the consumer in its call to `BufferProtocol.getBuffer(int)` to specify that it requires `PyBuffer.getFormat()` to return a `String` indicating the type of the unit.
    `static int` | `FULL` Equivalent to `(INDIRECT | WRITABLE | FORMAT)`.
    `static int` | `FULL_RO` Equivalent to `(INDIRECT | FORMAT)`.
    `static int` | `INDIRECT` A constant used by the consumer in its call to `BufferProtocol.getBuffer(int)` to specify that it understands the `suboffsets` array.
    `static int` | `IS_C_CONTIGUOUS` A constant used by the exporter in processing `BufferProtocol.getBuffer(int)` to check for assumed C-order organisation of the items.
    `static int` | `IS_F_CONTIGUOUS` A constant used by the exporter in processing `BufferProtocol.getBuffer(int)` to check for assumed C-order Fortran-order organisation of the items.
    `static int` | `MAX_NDIM` The maximum allowed number of dimensions (CPython restriction).
    `static int` | `NAVIGATION` Field mask, used as in `if ((flags&NAVIGATION) == STRIDES) ...`.
    `static int` | `ND` A constant used by the consumer in its call to `BufferProtocol.getBuffer(int)` to specify that it is prepared to navigate the buffer as multi-dimensional using the `shape` array.
    `static int` | `RECORDS` Equivalent to `(STRIDES | WRITABLE | FORMAT)`
    `static int` | `RECORDS_RO` Equivalent to `(STRIDES | FORMAT)`
    `static int` | `SIMPLE` A constant used by the consumer in its call to `BufferProtocol.getBuffer(int)` to specify that it assumes a simple one-dimensional organisation of the exported storage with item size of one.
    `static int` | `STRIDED` Equivalent to `(STRIDES | WRITABLE)`
    `static int` | `STRIDED_RO` Equivalent to `STRIDES`
    `static int` | `STRIDES` A constant used by the consumer in its call to `BufferProtocol.getBuffer(int)` to specify that it expects to use the `strides` array.
    `static int` | `WRITABLE` A constant used by the consumer in its call to `BufferProtocol.getBuffer(int)` to specify that it expects to write to the buffer contents.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getItemsize()` The number of bytes stored in each indexable item.
    `int` | `getLen()` The total number of bytes represented by the view, which will be the product of the elements of the `shape` array, and the item size in bytes.
    `int` | `getNdim()` The number of dimensions to the buffer.
    `int[]` | `getShape()` An array reporting the size of the buffer, considered as a multidimensional array, in each dimension and (by its length) giving the number of dimensions.
    `int[]` | `getStrides()` The `strides` array gives the distance in the storage array between adjacent items (in each dimension).
    `int[]` | `getSuboffsets()` The `suboffsets` array is a further part of the support for interpreting the buffer as an n-dimensional array of items, where the array potentially uses indirect addressing (like a real Java array of arrays, in fact).
    `boolean` | `isContiguous(char order)` Enquire whether the array is represented contiguously in the backing storage, according to C or Fortran ordering.
    `boolean` | `isReadonly()` Determine whether the consumer is entitled to write to the exported storage.

- - ### Field Detail

    - #### MAX_NDIM

          static final int MAX_NDIM

      The maximum allowed number of dimensions (CPython restriction).
      See Also:
        Constant Field Values

    - #### WRITABLE

          static final int WRITABLE

      A constant used by the consumer in its call to `BufferProtocol.getBuffer(int)` to specify that it expects to write to the buffer contents. `getBuffer` will raise an exception if the exporter's buffer cannot meet this requirement.
      See Also:
        Constant Field Values

    - #### SIMPLE

          static final int SIMPLE

      A constant used by the consumer in its call to `BufferProtocol.getBuffer(int)` to specify that it assumes a simple one-dimensional organisation of the exported storage with item size of one. `getBuffer` will raise an exception if the consumer sets this flag and the exporter cannot represent itself as byte array data.
      See Also:
        Constant Field Values

    - #### FORMAT

          static final int FORMAT

      A constant used by the consumer in its call to `BufferProtocol.getBuffer(int)` to specify that it requires `PyBuffer.getFormat()` to return a `String` indicating the type of the unit. This exists for compatibility with CPython, as in Jython the format is always provided by `getFormat()`.
      See Also:
        Constant Field Values

    - #### ND

          static final int ND

      A constant used by the consumer in its call to `BufferProtocol.getBuffer(int)` to specify that it is prepared to navigate the buffer as multi-dimensional using the `shape` array. `getBuffer` will raise an exception if consumer does not specify the flag but the exporter's buffer cannot be navigated without taking into account its multiple dimensions.
      See Also:
        Constant Field Values

    - #### STRIDES

          static final int STRIDES

      A constant used by the consumer in its call to `BufferProtocol.getBuffer(int)` to specify that it expects to use the `strides` array. `getBuffer` will raise an exception if consumer does not specify the flag but the exporter's buffer cannot be navigated without using the `strides` array.
      See Also:
        Constant Field Values

    - #### C_CONTIGUOUS

          static final int C_CONTIGUOUS

      A constant used by the consumer in its call to `BufferProtocol.getBuffer(int)` to specify that it will assume C-order organisation of the items. `getBuffer` will raise an exception if the exporter's buffer is not C-ordered. `C_CONTIGUOUS` implies `STRIDES`.
      See Also:
        Constant Field Values

    - #### F_CONTIGUOUS

          static final int F_CONTIGUOUS

      A constant used by the consumer in its call to `BufferProtocol.getBuffer(int)` to specify that it will assume Fortran-order organisation of the items. `getBuffer` will raise an exception if the exporter's buffer is not Fortran-ordered. `F_CONTIGUOUS` implies `STRIDES`.
      See Also:
        Constant Field Values

    - #### ANY_CONTIGUOUS

          static final int ANY_CONTIGUOUS

      A constant used by the consumer in its call to `BufferProtocol.getBuffer(int)` to specify that it will assume a contiguous organisation of the items, but will enquire which organisation it actually is. `getBuffer` will raise an exception if the exporter's buffer is not contiguous. `ANY_CONTIGUOUS` implies `STRIDES`.
      See Also:
        Constant Field Values

    - #### INDIRECT

          static final int INDIRECT

      A constant used by the consumer in its call to `BufferProtocol.getBuffer(int)` to specify that it understands the `suboffsets` array. `getBuffer` will raise an exception if consumer does not specify the flag but the exporter's buffer cannot be navigated without understanding the `suboffsets` array. `INDIRECT` implies `STRIDES`.
      See Also:
        Constant Field Values

    - #### CONTIG

          static final int CONTIG

      Equivalent to `(ND | WRITABLE)`
      See Also:
        Constant Field Values

    - #### CONTIG_RO

          static final int CONTIG_RO

      Equivalent to `ND`
      See Also:
        Constant Field Values

    - #### STRIDED

          static final int STRIDED

      Equivalent to `(STRIDES | WRITABLE)`
      See Also:
        Constant Field Values

    - #### STRIDED_RO

          static final int STRIDED_RO

      Equivalent to `STRIDES`
      See Also:
        Constant Field Values

    - #### RECORDS

          static final int RECORDS

      Equivalent to `(STRIDES | WRITABLE | FORMAT)`
      See Also:
        Constant Field Values

    - #### RECORDS_RO

          static final int RECORDS_RO

      Equivalent to `(STRIDES | FORMAT)`
      See Also:
        Constant Field Values

    - #### FULL

          static final int FULL

      Equivalent to `(INDIRECT | WRITABLE | FORMAT)`. Also use this in the request if you plan only to use the fully-encapsulated API (`byteAt`, `storeAt`, `copyTo`, `copyFrom`, etc.), without ever calling `PyBuffer.getNIOByteBuffer()` or using `PyBuffer.Pointer`.
      See Also:
        Constant Field Values

    - #### FULL_RO

          static final int FULL_RO

      Equivalent to `(INDIRECT | FORMAT)`. Also use this in the request if you plan only to use the fully-encapsulated API (`byteAt`, `copyTo`, etc.), read only, without ever calling `PyBuffer.getNIOByteBuffer()` or using `PyBuffer.Pointer`.
      See Also:
        Constant Field Values

    - #### AS_ARRAY

          static final int AS_ARRAY

      A constant used by the consumer in its call to `BufferProtocol.getBuffer(int)` to specify that it expects to access the buffer contents directly as an array (rather than through the purely abstract part of the API). `getBuffer` will raise an exception if the exporter cannot expose its storage as Java array.
      See Also:
        Constant Field Values

    - #### NAVIGATION

          static final int NAVIGATION

      Field mask, used as in `if ((flags&NAVIGATION) == STRIDES) ...`. The importance of the subset of flags defined by this mask is not so much in their "navigational" character as in the way they are treated in a buffer request.

      The `NAVIGATION` set are used to specify which navigation arrays the consumer will use, and therefore the consumer must ask for all those necessary to use the buffer successfully (which is a function of the buffer's actual type). Asking for extra ones is not an error, since all are supplied (in Jython): asking for too few is an error.

      Flags outside the `NAVIGATION` set, work the other way round. Asking for one the buffer cannot match is an error: not asking for a feature the buffer does not have is an error.

      See Also:
        Constant Field Values

    - #### IS_C_CONTIGUOUS

          static final int IS_C_CONTIGUOUS

      A constant used by the exporter in processing `BufferProtocol.getBuffer(int)` to check for assumed C-order organisation of the items. `C_CONTIGUOUS = IS_C_CONTIGUOUS | STRIDES`.
      See Also:
        Constant Field Values

    - #### IS_F_CONTIGUOUS

          static final int IS_F_CONTIGUOUS

      A constant used by the exporter in processing `BufferProtocol.getBuffer(int)` to check for assumed C-order Fortran-order organisation of the items. `F_CONTIGUOUS = IS_F_CONTIGUOUS | STRIDES`.
      See Also:
        Constant Field Values

    - #### CONTIGUITY

          static final int CONTIGUITY

      Field mask, used as in if `((flags&CONTIGUITY)== ... ) ...`.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### isReadonly

          boolean isReadonly()

      Determine whether the consumer is entitled to write to the exported storage.
      Returns:
        true if writing is not allowed, false if it is.

    - #### getNdim

          int getNdim()

      The number of dimensions to the buffer. This number is the length of the `shape` array. The actual storage may be a linear array, but this is the number of dimensions in the interpretation that the exporting object gives the data.
      Returns:
        number of dimensions

    - #### getShape

          int[] getShape()

      An array reporting the size of the buffer, considered as a multidimensional array, in each dimension and (by its length) giving the number of dimensions. The size of the buffer is its size in "items". An item is the amount of buffer content addressed by one index or set of indices. In the simplest case an item is a single unit (byte), and there is one dimension. In complex cases, the array is multi-dimensional, and the item at each location is multi-unit (multi-byte). The consumer must not modify this array. A valid `shape` array is always returned (difference from CPython).
      Returns:
        the dimensions of the buffer as an array

    - #### getItemsize

          int getItemsize()

      The number of bytes stored in each indexable item.
      Returns:
        the number of bytes comprising each item.

    - #### getLen

          int getLen()

      The total number of bytes represented by the view, which will be the product of the elements of the `shape` array, and the item size in bytes.
      Returns:
        the total number of bytes represented.

    - #### getStrides

          int[] getStrides()

      The `strides` array gives the distance in the storage array between adjacent items (in each dimension). In the rawest parts of the buffer API, the consumer of the buffer is able to navigate the exported storage. The "strides" array is part of the support for interpreting the buffer as an n-dimensional array of items. It provides the coefficients of the "addressing polynomial". (More on this in the CPython documentation.) The consumer must not modify this array. A valid `strides` array is always returned (difference from CPython).
      Returns:
        the distance in the storage array between adjacent items (in each dimension)

    - #### getSuboffsets

          int[] getSuboffsets()

      The `suboffsets` array is a further part of the support for interpreting the buffer as an n-dimensional array of items, where the array potentially uses indirect addressing (like a real Java array of arrays, in fact). This is only applicable when there is more than 1 dimension, and it works in conjunction with the `strides` array. (More on this in the CPython documentation.) When used, `suboffsets[k]` is an integer index, not a byte offset as in CPython. The consumer must not modify this array. When not needed for navigation `null` is returned (as in CPython).
      Returns:
        suboffsets array or `null` if not necessary for navigation

    - #### isContiguous

          boolean isContiguous(char order)

      Enquire whether the array is represented contiguously in the backing storage, according to C or Fortran ordering. A one-dimensional contiguous array is both.
      Parameters:
        `order` - 'C', 'F' or 'A', as the storage order is C, Fortran or either.
      Returns:
        true iff the array is stored contiguously in the order specified

Jython homepage