Package 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
    Description
    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.
    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).
    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.
    static final int
    CONTIG
    Equivalent to (ND | WRITABLE)
    static final int
    CONTIG_RO
    Equivalent to ND
    static final int
    CONTIGUITY
    Field mask, used as in if ((flags&CONTIGUITY)== ... ) ....
    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.
    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.
    static final int
    FULL
    Equivalent to (INDIRECT | WRITABLE | FORMAT).
    static final int
    FULL_RO
    Equivalent to (INDIRECT | FORMAT).
    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.
    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.
    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.
    static final int
    MAX_NDIM
    The maximum allowed number of dimensions (CPython restriction).
    static final int
    NAVIGATION
    Field mask, used as in if ((flags&NAVIGATION) == STRIDES) ....
    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.
    static final int
    RECORDS
    Equivalent to (STRIDES | WRITABLE | FORMAT)
    static final int
    RECORDS_RO
    Equivalent to (STRIDES | FORMAT)
    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.
    static final int
    STRIDED
    Equivalent to (STRIDES | WRITABLE)
    static final int
    STRIDED_RO
    Equivalent to 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.
    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.

  • Method Summary

    Modifier and Type
    Method
    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 Details

    • MAX_NDIM

      static final int MAX_NDIM
      The maximum allowed number of dimensions (CPython restriction).
      See Also:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • CONTIG

      static final int CONTIG
      Equivalent to (ND | WRITABLE)
      See Also:

    • CONTIG_RO

      static final int CONTIG_RO
      Equivalent to ND
      See Also:

    • STRIDED

      static final int STRIDED
      Equivalent to (STRIDES | WRITABLE)
      See Also:

    • STRIDED_RO

      static final int STRIDED_RO
      Equivalent to STRIDES
      See Also:

    • RECORDS

      static final int RECORDS
      Equivalent to (STRIDES | WRITABLE | FORMAT)
      See Also:

    • RECORDS_RO

      static final int RECORDS_RO
      Equivalent to (STRIDES | FORMAT)
      See Also:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • CONTIGUITY

      static final int CONTIGUITY
      Field mask, used as in if ((flags&CONTIGUITY)== ... ) ....
      See Also:

  • Method Details

    • 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