Py2kBuffer (Jython API documentation)
Date: 2024-08-18

org.python.core

## Class Py2kBuffer

- java.lang.Object
- - org.python.core.PyObject
  - - org.python.core.PySequence
    - - org.python.core.Py2kBuffer

- All Implemented Interfaces:
    java.io.Serializable, BufferProtocol

      public class Py2kBuffer
      extends PySequence
      implements BufferProtocol

  Implementation of the Python `buffer` type. `buffer` is being superseded in Python 2.7 by `memoryview`, and is provided here to support legacy Python code. Use `memoryview` if you can.

  `buffer` and `memoryview` both wrap the same Jython buffer API: that designed for `memoryview`. In CPython, a new C API (which Jython's resembles) was introduced with `memoryview`. Because of this, `buffer` and `memoryview` may be supplied as arguments in the same places, and will accept as arguments the same (one-dimensional byte-array) types. Their behaviour differs as detailed in the documentation.

  See Also:
    Serialized Form

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.python.core.PyObject

      `PyObject.ConversionException`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static PyType` | `TYPE`

    - ### Fields inherited from class org.python.core.PyObject

      `gcMonitorGlobal`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Py2kBuffer(BufferProtocol object, int offset, int size)` Construct a Py2kBuffer from an object supporting the `BufferProtocol`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `PyObject` | `__add__(PyObject other)` Equivalent to the standard Python __add__ method.
    `int` | `__len__()` Equivalent to the standard Python __len__ method.
    `PyObject` | `__mul__(PyObject o)` Equivalent to the standard Python __mul__ method.
    `PyString` | `__repr__()` Equivalent to the standard Python `__repr__` method.
    `PyObject` | `__rmul__(PyObject o)` Equivalent to the standard Python __rmul__ method.
    `PyString` | `__str__()` Equivalent to the standard Python __str__ method.
    `PyBuffer` | `getBuffer(int flags)` Method by which the consumer requests the buffer from the exporter.
    `void` | `pyset(int index, PyObject value)` Sets the indexed element of the `buffer` to the given value, treating the operation as assignment to a slice of length one.
    `java.lang.String` | `toString()`

    - ### Methods inherited from class org.python.core.PySequence

      `__delitem__, __delslice__, __eq__, __finditem__, __finditem__, __ge__, __getitem__, __getslice__, __gt__, __iter__, __le__, __lt__, __ne__, __nonzero__, __setitem__, __setitem__, __setslice__, __tojava__, isMappingType, isNumberType, isSequenceType`

    - ### Methods inherited from class org.python.core.PyObject

      `__abs__, __and__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __cmp__, __coerce__, __coerce_ex__, __complex__, __contains__, __delattr__, __delattr__, __delete__, __delitem__, __delslice__, __dir__, __div__, __divmod__, __ensure_finalizer__, __findattr__, __findattr__, __findattr_ex__, __finditem__, __float__, __floordiv__, __format__, __get__, __getattr__, __getattr__, __getitem__, __getnewargs__, __getslice__, __hash__, __hex__, __iadd__, __iand__, __idiv__, __idivmod__, __ifloordiv__, __ilshift__, __imod__, __imul__, __index__, __int__, __invert__, __ior__, __ipow__, __irshift__, __isub__, __iternext__, __itruediv__, __ixor__, __long__, __lshift__, __mod__, __neg__, __not__, __oct__, __or__, __pos__, __pow__, __pow__, __radd__, __rand__, __rdiv__, __rdivmod__, __reduce__, __reduce_ex__, __reduce_ex__, __rfloordiv__, __rlshift__, __rmod__, __ror__, __rpow__, __rrshift__, __rshift__, __rsub__, __rtruediv__, __rxor__, __set__, __setattr__, __setattr__, __setitem__, __setslice__, __sub__, __truediv__, __trunc__, __unicode__, __xor__, _add, _and, _callextra, _cmp, _div, _divmod, _doget, _doget, _doset, _eq, _floordiv, _ge, _gt, _iadd, _iand, _idiv, _idivmod, _ifloordiv, _ilshift, _imod, _imul, _in, _ior, _ipow, _irshift, _is, _isnot, _isub, _itruediv, _ixor, _jcall, _jcallexc, _jthrow, _le, _lshift, _lt, _mod, _mul, _ne, _notin, _or, _pow, _rshift, _sub, _truediv, _xor, asDouble, asIndex, asIndex, asInt, asInt, asIterable, asLong, asLong, asName, asName, asString, asString, asStringOrNull, asStringOrNull, bit_length, conjugate, delDict, delType, dispatch__init__, equals, fastGetClass, fastGetDict, getDict, getType, hashCode, implementsDescrDelete, implementsDescrGet, implementsDescrSet, invoke, invoke, invoke, invoke, invoke, invoke, isCallable, isDataDescr, isIndex, isInteger, noAttributeError, object___subclasshook__, readonlyAttributeError, setDict, setType`

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### TYPE

          public static final PyType TYPE

  - ### Constructor Detail

    - #### Py2kBuffer

          public Py2kBuffer(BufferProtocol object,
                            int offset,
                            int size)

      Construct a Py2kBuffer from an object supporting the `BufferProtocol`. The `buffer` takes no lease on the `PyBuffer` at present, but for each action performed obtains a new one and releases it. (Major difference from `memoryview`.) Note that when `size=-1` is given, the buffer reflects the changing size of the underlying object.
      Parameters:
        `object` - the object on which this is to be a buffer.
        `offset` - into the array exposed by the object (0 for start).
        `size` - of the slice or -1 for all of the object.

  - ### Method Detail

    - #### __len__

          public int __len__()

      Description copied from class: `PyObject`
      Equivalent to the standard Python __len__ method. Part of the mapping discipline.
      Overrides:
        `__len__` in class `PyObject`
      Returns:
        the length of the object

    - #### __repr__

          public PyString __repr__()

      Description copied from class: `PyObject`
      Equivalent to the standard Python `__repr__` method. Each sub-class of `PyObject` is likely to re-define this method to provide for its own reproduction.
      Overrides:
        `__repr__` in class `PyObject`

    - #### __str__

          public PyString __str__()

      Description copied from class: `PyObject`
      Equivalent to the standard Python __str__ method. The default implementation (in `PyObject`) calls `PyObject.__repr__()`, making it unnecessary to override `__str__` in sub-classes of `PyObject` where both forms are the same. A common choice is to provide the same implementation to `__str__` and `toString`, for consistency in the printed form of objects between Python and Java.
      Overrides:
        `__str__` in class `PyObject`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `PyObject`

    - #### __add__

          public PyObject __add__(PyObject other)

      Equivalent to the standard Python __add__ method. A `buffer` implements this as concatenation and returns a `str` (`PyString`) result.
      Overrides:
        `__add__` in class `PyObject`
      Parameters:
        `other` - the object to perform this binary operation with (the right-hand operand).
      Returns:
        the result of the add, or null if this operation is not defined.

    - #### __mul__

          public PyObject __mul__(PyObject o)

      Equivalent to the standard Python __mul__ method. On a `buffer` it returns a `str` containing the buffer contents `n` times.
      Overrides:
        `__mul__` in class `PyObject`
      Parameters:
        `o` - the object to perform this binary operation with (the right-hand operand).
      Returns:
        the result of the mul, or null if this operation is not defined

    - #### __rmul__

          public PyObject __rmul__(PyObject o)

      Equivalent to the standard Python __rmul__ method. On a `buffer` it returns a `str` containing the buffer contents `n` times.
      Overrides:
        `__rmul__` in class `PyObject`
      Parameters:
        `o` - the object to perform this binary operation with (the left-hand operand).
      Returns:
        the result of the mul, or null if this operation is not defined.

    - #### getBuffer

          public PyBuffer getBuffer(int flags)

      Method by which the consumer requests the buffer from the exporter. The consumer provides information on its ability to understand buffer navigation. Each consumer requesting a buffer in this way, when it has finished using it, should make a corresponding call to `PyBuffer.release()` on the buffer it obtained, or `PyBuffer.close()` using try-with-resources, since some objects alter their behaviour while buffers are exported.

      The `PyBuffer` returned from this method is provided directly by the underlying object on which this buffer was constructed, taking account of the slicing arguments (offset and size), if these were given when the buffer was constructed.

      Specified by:
        `getBuffer` in interface `BufferProtocol`
      Parameters:
        `flags` - specifying features demanded and the navigational capabilities of the consumer
      Returns:
        exported buffer

    - #### pyset

          public void pyset(int index,
                            PyObject value)
                     throws PyException

      Sets the indexed element of the `buffer` to the given value, treating the operation as assignment to a slice of length one. This is different from the same operation on a byte array, where the assigned value must be an int: here it must have the buffer API and length one. This is an extension point called by PySequence in its implementation of `PySequence.__setitem__(int, org.python.core.PyObject)` It is guaranteed by PySequence that the index is within the bounds of the `buffer`. Any other clients calling `pyset(int, PyObject)` must make the same guarantee.
      Parameters:
        `index` - index of the element to set.
        `value` - to set this element to, regarded as a buffer of length one unit.
      Throws:
        `PyException` - `AttributeError` if value cannot be converted to an integer
        `PyException` - `ValueError` if value<0 or value%gt;255

Jython homepage