org.python.core

Class PyMemoryView

java.lang.Object

org.python.core.PyObject

org.python.core.PySequence

org.python.core.PyMemoryView

All Implemented Interfaces:

java.io.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.PySequence

PySequence.DefaultIndexDelegate

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.PySequence

delegator

Fields inherited from class org.python.core.PyObject

attributes, gcMonitorGlobal, objtype

Constructor Summary

Constructors

Constructor and Description
PyMemoryView(BufferProtocol pybuf) Construct a PyMemoryView from an object bearing the BufferProtocol interface.

Method Summary

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.
protected void	checkNotReleased() Check that the memoryview is not released and raise a ValueError if it is.
java.lang.String	format()
PyBuffer	getBuffer(int flags) Method by which the consumer requests the buffer from the exporter.
protected PyMemoryView	getslice(int start, int stop, int step) Returns a slice of elements from this sequence as a PyMemoryView.
int	hashCode()
int	itemsize()
void	memoryview_release()
int	ndim()
PyObject	obj()
protected PyString	pyget(int index) Gets the indexed element of the memoryview as a one byte string.
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.
protected PyMemoryView	repeat(int count) memoryview*int is not implemented in Python, so this should never be called.
protected void	setslice(int start, int stop, int step, PyObject value) Sets the given range of elements according to Python slice assignment semantics.
PyObject	shape()
PyObject	strides()
PyObject	suboffsets()
PyString	tobytes() Implementation of Python tobytes().
PyList	tolist() Implementation of Python tolist().
int	traverse(Visitproc visit, java.lang.Object arg) Traverses all directly contained PyObjects.

Methods inherited from class org.python.core.PySequence

__delitem__, __delslice__, __finditem__, __finditem__, __getitem__, __getslice__, __iter__, __nonzero__, __setitem__, __setitem__, __setslice__, __tojava__, boundToSequence, cmp, del, delRange, delslice, fastSequence, isMappingType, isNumberType, isSequenceType, isSubType, runsupportedopMessage, sliceLength, unsupportedopMessage

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__, __rawdir__, __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, _unsupportedop, _xor, adaptToCoerceTuple, asDouble, asIndex, asIndex, asInt, asInt, asIterable, asLong, asLong, asName, asName, asString, asString, asStringOrNull, asStringOrNull, bit_length, conjugate, delDict, delType, dispatch__init__, equals, fastGetClass, fastGetDict, finalize, getDict, getJavaProxy, getType, impAttr, implementsDescrDelete, implementsDescrGet, implementsDescrSet, invoke, invoke, invoke, invoke, invoke, invoke, isCallable, isDataDescr, isIndex, isInteger, mergeClassDict, mergeDictAttr, mergeListAttr, noAttributeError, object___subclasshook__, readonlyAttributeError, setDict, setType, toString

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, wait, wait, wait

Field Detail

TYPE

public static final PyType TYPE

Constructor Detail

PyMemoryView

public PyMemoryView(BufferProtocol pybuf)
             throws java.lang.ClassCastException

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

Throws:

java.lang.ClassCastException - in cases where pybuf.getBuffer does so.

Method Detail

obj

public PyObject obj()

format

public java.lang.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 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 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()

checkNotReleased

protected void checkNotReleased()

Check that the memoryview is not released and raise a ValueError if it is. Almost every operation must call this before it starts work.

pyget

protected PyString pyget(int index)

Gets the indexed element of the memoryview as a one byte string. This is an extension point called by PySequence in its implementation of PySequence.__getitem__(org.python.core.PyObject). It is guaranteed by PySequence that the index is within the bounds of the memoryview.

Specified by:

pyget in class PySequence

Parameters:

index - index of the element to get.

Returns:

one-character string formed from the byte at the index

getslice

protected PyMemoryView getslice(int start,
                                int stop,
                                int step)

Returns a slice of elements from this sequence as a PyMemoryView.

Specified by:

getslice in class PySequence

Parameters:

start - the position of the first element.

stop - one more than the position of the last element.

step - the step size.

Returns:

a PyMemoryView corresponding the the given range of elements.

repeat

protected PyMemoryView repeat(int count)
                       throws PyException

memoryview*int is not implemented in Python, so this should never be called. We still have to override it to satisfy PySequence.

Specified by:

repeat in class PySequence

Parameters:

count - the number of times to repeat this.

Returns:

never

Throws:

PyException - NotImplemented always

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.

Overrides:

pyset in class PySequence

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

setslice

protected void setslice(int start,
                        int stop,
                        int step,
                        PyObject value)

Sets the given range of elements according to Python slice assignment semantics. If the step size is one, it is a simple slice and the operation is equivalent to replacing that slice, with the value, accessing the value via the buffer protocol.

 a = bytearray(b'abcdefghijklmnopqrst')
 m = memoryview(a)
 m[2:7] = "ABCDE"
 

Results in a=bytearray(b'abABCDEhijklmnopqrst').

If the step size is one, but stop-start does not match the length of the right-hand-side a ValueError is thrown.

If the step size is not one, and start!=stop, the slice defines a certain number of elements to be replaced. This function is not available in Python 2.7 (but it is in Python 3.3).

 a = bytearray(b'abcdefghijklmnopqrst')
 a[2:12:2] = iter( [65, 66, 67, long(68), "E"] )
 

Results in a=bytearray(b'abAdBfChDjElmnopqrst') in Python 3.3.

Overrides:

setslice in class PySequence

Parameters:

start - the position of the first element.

stop - one more than the position of the last element.

step - the step size.

value - an object consistent with the slice assignment

traverse

public int traverse(Visitproc visit,
                    java.lang.Object arg)

Description copied from interface: Traverseproc

Traverses all directly contained PyObjects. 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