PyMemoryView (Jython API documentation)
Date: 2017-06-30

org.python.core

## Class PyMemoryView

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

- All Implemented Interfaces:
    Serializable, BufferProtocol, Traverseproc

      public class PyMemoryView
      extends PySequence
      implements BufferProtocol, Traverseproc

  Class implementing the Python `memoryview` type. It provides a wrapper around the Jython buffer API.
  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
    `PyMemoryView(BufferProtocol pybuf)` Construct a `PyMemoryView` from an object bearing the `BufferProtocol` interface.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `PyObject` | `__enter__()` Called at the start of a context-managed suite (supporting the `with` clause).
    `PyObject` | `__eq__(PyObject other)` Equivalent to the standard Python __eq__ method.
    `boolean` | `__exit__(PyObject type, PyObject value, PyObject traceback)` Called at the end of a context-managed suite (supporting the `with` clause), and will release the `memoryview`.
    `PyObject` | `__ge__(PyObject other)` Equivalent to the standard Python __ge__ method.
    `PyObject` | `__gt__(PyObject other)` Equivalent to the standard Python __gt__ method.
    `PyObject` | `__le__(PyObject other)` Equivalent to the standard Python __le__ method.
    `int` | `__len__()` Equivalent to the standard Python __len__ method.
    `PyObject` | `__lt__(PyObject other)` Equivalent to the standard Python __lt__ method.
    `PyObject` | `__ne__(PyObject other)` Equivalent to the standard Python __ne__ method.
    `String` | `format()`
    `PyBuffer` | `getBuffer(int flags)` Method by which the consumer requests the buffer from the exporter.
    `int` | `hashCode()`
    `int` | `itemsize()`
    `void` | `memoryview_release()`
    `int` | `ndim()`
    `PyObject` | `obj()`
    `void` | `pyset(int index, PyObject value)` Sets the indexed element of the memoryview to the given value, treating the operation as assignment to a slice of length one.
    `boolean` | `readonly()`
    `boolean` | `refersDirectlyTo(PyObject ob)` Optional operation.
    `void` | `release()` Request a release of the underlying buffer exposed by the `memoryview` object.
    `PyObject` | `shape()`
    `PyObject` | `strides()`
    `PyObject` | `suboffsets()`
    `PyString` | `tobytes()` Implementation of Python `tobytes()`.
    `PyList` | `tolist()` Implementation of Python `tolist()`.
    `int` | `traverse(Visitproc visit, Object arg)` Traverses all directly contained `PyObject`s.

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

      `__delitem__, __delslice__, __finditem__, __finditem__, __getitem__, __getslice__, __iter__, __nonzero__, __setitem__, __setitem__, __setslice__, __tojava__, isMappingType, isNumberType, isSequenceType`

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

      `__abs__, __add__, __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__, __mul__, __neg__, __not__, __oct__, __or__, __pos__, __pow__, __pow__, __radd__, __rand__, __rdiv__, __rdivmod__, __reduce__, __reduce_ex__, __reduce_ex__, __repr__, __rfloordiv__, __rlshift__, __rmod__, __rmul__, __ror__, __rpow__, __rrshift__, __rshift__, __rsub__, __rtruediv__, __rxor__, __set__, __setattr__, __setattr__, __setitem__, __setslice__, __str__, __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, implementsDescrDelete, implementsDescrGet, implementsDescrSet, invoke, invoke, invoke, invoke, invoke, invoke, isCallable, isDataDescr, isIndex, isInteger, noAttributeError, object___subclasshook__, readonlyAttributeError, setDict, setType, toString`

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

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

- - ### Field Detail

    - #### TYPE

          public static final PyType TYPE

  - ### Constructor Detail

    - #### PyMemoryView

          public PyMemoryView(BufferProtocol pybuf)

      Construct a `PyMemoryView` from an object bearing the `BufferProtocol` interface. If this object is already an exported buffer, the `memoryview` takes a new lease on it. The buffer so obtained will be writable if the underlying object permits it.
      Parameters:
        `pybuf` - buffer exported by some underlying object

  - ### Method Detail

    - #### obj

          public PyObject obj()

    - #### format

          public String format()

    - #### itemsize

          public int itemsize()

    - #### shape

          public PyObject shape()

    - #### ndim

          public int ndim()

    - #### strides

          public PyObject strides()

    - #### suboffsets

          public PyObject suboffsets()

    - #### readonly

          public boolean readonly()

    - #### tobytes

          public PyString tobytes()

      Implementation of Python `tobytes()`. Return the data in the buffer as a byte string (an object of class `str`).
      Returns:
        byte string of buffer contents.

    - #### tolist

          public PyList tolist()

      Implementation of Python `tolist()`. Return the data in the buffer as a `list` where the elements are an appropriate type (`int` in the case of a byte-oriented buffer, which is the only case presently supported).
      Returns:
        a list of buffer contents.

    - #### __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

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `PyObject`

    - #### __eq__

          public PyObject __eq__(PyObject other)

      Description copied from class: `PyObject`
      Equivalent to the standard Python __eq__ method.
      Overrides:
        `__eq__` in class `PySequence`
      Parameters:
        `other` - the object to compare this with.
      Returns:
        the result of the comparison.

    - #### __ne__

          public PyObject __ne__(PyObject other)

      Description copied from class: `PyObject`
      Equivalent to the standard Python __ne__ method.
      Overrides:
        `__ne__` in class `PySequence`
      Parameters:
        `other` - the object to compare this with.
      Returns:
        the result of the comparison.

    - #### __lt__

          public PyObject __lt__(PyObject other)

      Description copied from class: `PyObject`
      Equivalent to the standard Python __lt__ method.
      Overrides:
        `__lt__` in class `PySequence`
      Parameters:
        `other` - the object to compare this with.
      Returns:
        the result of the comparison.

    - #### __le__

          public PyObject __le__(PyObject other)

      Description copied from class: `PyObject`
      Equivalent to the standard Python __le__ method.
      Overrides:
        `__le__` in class `PySequence`
      Parameters:
        `other` - the object to compare this with.
      Returns:
        the result of the comparison.

    - #### __ge__

          public PyObject __ge__(PyObject other)

      Description copied from class: `PyObject`
      Equivalent to the standard Python __ge__ method.
      Overrides:
        `__ge__` in class `PySequence`
      Parameters:
        `other` - the object to compare this with.
      Returns:
        the result of the comparison.

    - #### __gt__

          public PyObject __gt__(PyObject other)

      Description copied from class: `PyObject`
      Equivalent to the standard Python __gt__ method.
      Overrides:
        `__gt__` in class `PySequence`
      Parameters:
        `other` - the object to compare this with.
      Returns:
        the result of the comparison.

    - #### __enter__

          public PyObject __enter__()

      Called at the start of a context-managed suite (supporting the `with` clause).
      Returns:
        this object

    - #### __exit__

          public boolean __exit__(PyObject type,
                                  PyObject value,
                                  PyObject traceback)

      Called at the end of a context-managed suite (supporting the `with` clause), and will release the `memoryview`.
      Returns:
        false

    - #### getBuffer

          public PyBuffer getBuffer(int flags)

      Method by which the consumer requests the buffer from the exporter. The consumer provides information on its intended method of navigation and the features the buffer object is asked (or assumed) to provide. 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, since some objects alter their behaviour while buffers are exported.

      The `PyBuffer` returned from this method is just the one on which the `memoryview` was first constructed. The Jython buffer API is such that sharing directly is safe (as long as the get-release discipline is observed).

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

    - #### release

          public void release()

      Request a release of the underlying buffer exposed by the `memoryview` object. Many objects take special actions when a view is held on them (for example, a `bytearray` would temporarily forbid resizing); therefore, calling `release()` is handy to remove these restrictions (and free any dangling resources) as soon as possible.

      After this method has been called, any further operation on the view raises a `ValueError` (except `release()` itself which can be called multiple times with the same effect as just one call).

      This becomes an exposed method in CPython from 3.2. The Jython implementation of `memoryview` follows the Python 3.3 design internally and therefore safely anticipates Python 3 in exposing `memoryview.release` along with the related context-management behaviour.

    - #### memoryview_release

          public final void memoryview_release()

    - #### pyset

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

      Sets the indexed element of the memoryview 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 memoryview. 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>255
        `PyException`

    - #### traverse

          public int traverse(Visitproc visit,
                              Object arg)

      Description copied from interface: `Traverseproc`
      Traverses all directly contained `PyObject`s. Like in CPython, `arg` must be passed unmodified to `visit` as its second parameter. If `Visitproc.visit(PyObject, Object)` returns nonzero, this return value must be returned immediately by traverse. `Visitproc.visit(PyObject, Object)` must not be called with a `null` PyObject-argument.
      Specified by:
        `traverse` in interface `Traverseproc`

    - #### refersDirectlyTo

          public boolean refersDirectlyTo(PyObject ob)

      Description copied from interface: `Traverseproc`
      Optional operation. Should only be implemented if it is more efficient than calling `Traverseproc.traverse(Visitproc, Object)` with a visitproc that just watches out for `ob`. Must return `false` if `ob` is `null`.
      Specified by:
        `refersDirectlyTo` in interface `Traverseproc`

Jython homepage