org.python.core.PyBUF Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of jython-slim Show documentation
Show all versions of jython-slim Show documentation
Jython is an implementation of the high-level, dynamic, object-oriented
language Python written in 100% Pure Java, and seamlessly integrated with
the Java platform. It thus allows you to run Python on any Java platform.
package org.python.core;
/**
* This interface provides a base for the key interface of the buffer API, {@link PyBuffer},
* including symbolic constants used by the consumer of a {@code PyBuffer} to specify its
* requirements and assumptions. The Jython buffer API emulates the CPython buffer API. There are
* two reasons for separating parts of {@code PyBuffer} into this interface:
*
* - The constants defined in CPython have the names {@code PyBUF_SIMPLE}, {@code PyBUF_WRITABLE},
* etc., and the trick of defining ours here means we can write {@code PyBUF.SIMPLE},
* {@code PyBUF.WRITABLE}, etc. so source code looks similar.
* - It is not so easy in Java as it is in C to treat a {@code byte} array as storing anything
* other than {@code 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){@code Buffer} and an assumed future {@code FloatBuffer} or {@code TypedBuffer
}.
* (Compare {@code java.nio.Buffer}.)
*
* It is unlikely any classes would implement {@code PyBUF}, except indirectly through other
* interfaces. Users of the Jython buffer API can mostly overlook the distinction and just use
* {@code PyBuffer}.
*/
public interface PyBUF {
/**
* Determine whether the consumer is entitled to write to the exported storage.
*
* @return true if writing is not allowed, false if it is.
*/
boolean isReadonly();
/**
* The number of dimensions to the buffer. This number is the length of the {@code 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.
*
* @return number of dimensions
*/
int getNdim();
/**
* 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 {@code shape} array is always
* returned (difference from CPython).
*
* @return the dimensions of the buffer as an array
*/
int[] getShape();
/**
* The number of bytes stored in each indexable item.
*
* @return the number of bytes comprising each item.
*/
int getItemsize();
/**
* The total number of bytes represented by the view, which will be the product of the elements
* of the {@code shape} array, and the item size in bytes.
*
* @return the total number of bytes represented.
*/
int getLen();
/**
* The {@code 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 {@code strides} array is always returned (difference from
* CPython).
*
* @return the distance in the storage array between adjacent items (in each dimension)
*/
int[] getStrides();
/**
* The {@code 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 {@code strides} array. (More on this in the
* CPython documentation.) When used, {@code 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
* {@code null} is returned (as in CPython).
*
* @return suboffsets array or {@code null} if not necessary for navigation
*/
int[] getSuboffsets();
/**
* Enquire whether the array is represented contiguously in the backing storage, according to C
* or Fortran ordering. A one-dimensional contiguous array is both.
*
* @param order 'C', 'F' or 'A', as the storage order is C, Fortran or either.
* @return true iff the array is stored contiguously in the order specified
*/
boolean isContiguous(char order);
/* Constants taken from CPython object.h in v3.3 */
/**
* The maximum allowed number of dimensions (CPython restriction).
*/
static final int MAX_NDIM = 64;
/**
* A constant used by the consumer in its call to {@link BufferProtocol#getBuffer(int)} to
* specify that it expects to write to the buffer contents. {@code getBuffer} will raise an
* exception if the exporter's buffer cannot meet this requirement.
*/
static final int WRITABLE = 0x0001;
/**
* A constant used by the consumer in its call to {@link BufferProtocol#getBuffer(int)} to
* specify that it assumes a simple one-dimensional organisation of the exported storage with
* item size of one. {@code getBuffer} will raise an exception if the consumer sets this flag
* and the exporter cannot represent itself as byte array data.
*/
static final int SIMPLE = 0;
/**
* A constant used by the consumer in its call to {@link BufferProtocol#getBuffer(int)} to
* specify that it requires {@link PyBuffer#getFormat()} to return a {@code String} indicating
* the type of the unit. This exists for compatibility with CPython, as in Jython the format is
* always provided by {@code getFormat()}.
*/
static final int FORMAT = 0x0004;
/**
* A constant used by the consumer in its call to {@link BufferProtocol#getBuffer(int)} to
* specify that it is prepared to navigate the buffer as multi-dimensional using the
* {@code shape} array. {@code 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.
*/
static final int ND = 0x0008;
/**
* A constant used by the consumer in its call to {@link BufferProtocol#getBuffer(int)} to
* specify that it expects to use the {@code strides} array. {@code getBuffer} will raise an
* exception if consumer does not specify the flag but the exporter's buffer cannot be navigated
* without using the {@code strides} array.
*/
static final int STRIDES = 0x0010 | ND;
/**
* A constant used by the consumer in its call to {@link BufferProtocol#getBuffer(int)} to
* specify that it will assume C-order organisation of the items. {@code getBuffer} will raise
* an exception if the exporter's buffer is not C-ordered. {@code C_CONTIGUOUS} implies
* {@code STRIDES}.
*/
// It is possible this should have been (0x20|ND) expressing the idea that C-order addressing
// will be assumed *instead of* using a strides array.
static final int C_CONTIGUOUS = 0x0020 | STRIDES;
/**
* A constant used by the consumer in its call to {@link BufferProtocol#getBuffer(int)} to
* specify that it will assume Fortran-order organisation of the items. {@code getBuffer} will
* raise an exception if the exporter's buffer is not Fortran-ordered. {@code F_CONTIGUOUS}
* implies {@code STRIDES}.
*/
static final int F_CONTIGUOUS = 0x0040 | STRIDES;
/**
* A constant used by the consumer in its call to {@link BufferProtocol#getBuffer(int)} to
* specify that it will assume a contiguous organisation of the items, but will enquire which
* organisation it actually is.
*
* {@code getBuffer} will raise an exception if the exporter's buffer is not contiguous.
* {@code ANY_CONTIGUOUS} implies {@code STRIDES}.
*/
// Further CPython strangeness since it uses the strides array to answer the enquiry.
static final int ANY_CONTIGUOUS = 0x0080 | STRIDES;
/**
* A constant used by the consumer in its call to {@link BufferProtocol#getBuffer(int)} to
* specify that it understands the {@code suboffsets} array. {@code getBuffer} will raise an
* exception if consumer does not specify the flag but the exporter's buffer cannot be navigated
* without understanding the {@code suboffsets} array. {@code INDIRECT} implies {@code STRIDES}.
*/
static final int INDIRECT = 0x0100 | STRIDES;
/**
* Equivalent to {@code (ND | WRITABLE)}
*/
static final int CONTIG = ND | WRITABLE;
/**
* Equivalent to {@code ND}
*/
static final int CONTIG_RO = ND;
/**
* Equivalent to {@code (STRIDES | WRITABLE)}
*/
static final int STRIDED = STRIDES | WRITABLE;
/**
* Equivalent to {@code STRIDES}
*/
static final int STRIDED_RO = STRIDES;
/**
* Equivalent to {@code (STRIDES | WRITABLE | FORMAT)}
*/
static final int RECORDS = STRIDES | WRITABLE | FORMAT;
/**
* Equivalent to {@code (STRIDES | FORMAT)}
*/
static final int RECORDS_RO = STRIDES | FORMAT;
/**
* Equivalent to {@code (INDIRECT | WRITABLE | FORMAT)}. Also use this in the request if you
* plan only to use the fully-encapsulated API ({@code byteAt}, {@code storeAt}, {@code copyTo},
* {@code copyFrom}, etc.), without ever calling {@link PyBuffer#getNIOByteBuffer()} or using
* {@link PyBuffer.Pointer}.
*/
static final int FULL = INDIRECT | WRITABLE | FORMAT;
/**
* Equivalent to {@code (INDIRECT | FORMAT)}. Also use this in the request if you plan only to
* use the fully-encapsulated API ({@code byteAt}, {@code copyTo}, etc.), read only, without
* ever calling {@link PyBuffer#getNIOByteBuffer()} or using {@link PyBuffer.Pointer}.
*/
static final int FULL_RO = INDIRECT | FORMAT;
/* Constants for additional feature(s), not standard for CPython */
/**
* A constant used by the consumer in its call to {@link 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). {@code getBuffer} will raise an exception if
* the exporter cannot expose its storage as Java array.
*/
// XXX Pending: @Deprecated
static final int AS_ARRAY = 0x10000000;
/* Constants for readability, not standard for CPython */
/**
* Field mask, used as in {@code 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 {@code 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 {@code 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.
*/
static final int NAVIGATION = SIMPLE | ND | STRIDES | INDIRECT;
/**
* A constant used by the exporter in processing {@link BufferProtocol#getBuffer(int)} to check
* for assumed C-order organisation of the items.
* {@code C_CONTIGUOUS = IS_C_CONTIGUOUS | STRIDES}.
*/
static final int IS_C_CONTIGUOUS = C_CONTIGUOUS & ~STRIDES;
/**
* A constant used by the exporter in processing {@link BufferProtocol#getBuffer(int)} to check
* for assumed C-order Fortran-order organisation of the items.
* {@code F_CONTIGUOUS = IS_F_CONTIGUOUS | STRIDES}.
*/
static final int IS_F_CONTIGUOUS = F_CONTIGUOUS & ~STRIDES;
/**
* Field mask, used as in if {@code ((flags&CONTIGUITY)== ... ) ...}.
*/
static final int CONTIGUITY = (C_CONTIGUOUS | F_CONTIGUOUS | ANY_CONTIGUOUS) & ~STRIDES;
}