com.chaquo.python

Class PyObject

java.lang.Object

java.util.AbstractMap<String,PyObject>

com.chaquo.python.PyObject

All Implemented Interfaces:

AutoCloseable, Map<String,PyObject>

public class PyObject
extends AbstractMap<String,PyObject>
implements AutoCloseable

Interface to a Python object.

• Python None is represented by Java null. Other PyObjects can be converted to their Java equivalents using toJava().
• If a Python object is retrieved for which a PyObject already exists, the same PyObject will be returned.

Unless otherwise specified, all methods in this class throw PyException on failure.

Nested Class Summary

Nested classes/interfaces inherited from class java.util.AbstractMap

AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Method Summary

Modifier and Type	Method and Description
List<PyObject>	asList() Returns a view of the Python object as a list.
Map<PyObject,PyObject>	asMap() Returns a view of the Python object as a map.
Set<PyObject>	asSet() Returns a view of the Python object as a set.
PyObject	call(Object... args) Equivalent to Python () syntax.
PyObject	callAttr(String key, Object... args) Same as get(key).call(args), except it throws a PyException if the attribute does not exist.
PyObject	callAttrThrows(String key, Object... args) Same as callAttr(), except it directly passes any Java exception thrown by the Python code.
PyObject	callThrows(Object... args) Same as call(), except it directly passes any Java exception thrown by the Python code.
void	clear() Attempts to remove all attributes returned by keySet().
void	close() Releases the reference to the Python object.
boolean	containsKey(Object key) Equivalent to Python hasattr().
boolean	containsValue(Object o) Returns whether any attribute has the given value.
Set<Map.Entry<String,PyObject>>	entrySet() See notes on keySet().
boolean	equals(Object that) Equivalent to Python == operator.
protected void	finalize() Calls close().
static PyObject	fromJava(Object o) Converts the given Java object to a Python object.
PyObject	get(Object key) Equivalent to Python getattr().
int	hashCode() Equivalent to Python hash().
long	id() Equivalent to Python id().
boolean	isEmpty() Equivalent to keySet().isEmpty().
Set<String>	keySet() Equivalent to Python dir().
PyObject	put(String key, Object value) Equivalent to Python setattr().
PyObject	put(String key, PyObject value) Equivalent to Python setattr().
PyObject	remove(Object key) Equivalent to Python delattr().
String	repr() Equivalent to Python repr().
boolean	toBoolean() Converts a Python bool to a Java boolean.
byte	toByte() Converts a Python int to a Java byte.
char	toChar() Converts a 1-character Python string to a Java char.
double	toDouble() Converts a Python float or int to a Java double.
float	toFloat() Converts a Python float or int to a Java float.
int	toInt() Converts a Python int to a Java int.
<T> T	toJava(Class<T> klass) Converts the Python object to the given Java type.
long	toLong() Converts a Python int to a Java long.
short	toShort() Converts a Python int to a Java short.
String	toString() Equivalent to Python str().
PyObject	type() Equivalent to Python type().

Methods inherited from class java.util.AbstractMap

clone, putAll, size, values

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll

Method Detail

asList

@NotNull
public List<PyObject> asList()

Returns a view of the Python object as a list. The view is backed by the object, so changes to the object are reflected in the view, and vice-versa.

To add Java objects to the Python container through the view, first convert them using fromJava().

Throws:

UnsupportedOperationException - if the Python object does not implement the methods __getitem__ and __len__.

asMap

@NotNull
public Map<PyObject,PyObject> asMap()

Returns a view of the Python object as a map. The view is backed by the object, so changes to the object are reflected in the view, and vice-versa.

PyObject already implements the Map interface, but that is for attribute access (Python "." syntax), whereas the Map returned by this method is for container access (Python "[]" syntax).

To add Java objects to the Python container through the view, first convert them using fromJava().

Throws:

UnsupportedOperationException - if the Python object does not implement the methods __contains__, __getitem__, __iter__ and __len__.

asSet

@NotNull
public Set<PyObject> asSet()

Returns a view of the Python object as a set. The view is backed by the object, so changes to the object are reflected in the view, and vice-versa.

To add Java objects to the Python container through the view, first convert them using fromJava().

Throws:

UnsupportedOperationException - if the Python object does not implement the methods __contains__, __iter__ and __len__.

call

public PyObject call(Object... args)

Equivalent to Python () syntax. Arguments will be converted as described at fromJava(). Keyword arguments can be passed using instances of Kwarg at the end of the argument list.

callAttr

public PyObject callAttr(@NotNull
                         String key,
                         Object... args)

Same as get(key).call(args), except it throws a PyException if the attribute does not exist.

callAttrThrows

public PyObject callAttrThrows(@NotNull
                               String key,
                               Object... args)
                        throws Throwable

Same as callAttr(), except it directly passes any Java exception thrown by the Python code.

Throws:

Throwable

callThrows

public PyObject callThrows(Object... args)
                    throws Throwable

Same as call(), except it directly passes any Java exception thrown by the Python code.

Throws:

Throwable

clear

public void clear()

Attempts to remove all attributes returned by keySet(). See notes on isEmpty().

Specified by:

clear in interface Map<String,PyObject>

Overrides:

clear in class AbstractMap<String,PyObject>

close

public void close()

Releases the reference to the Python object. Unless the object represents an expensive resource, there's no need to call this method: it will be called automatically when the PyObject is garbage-collected.

After calling close, the PyObject can no longer be used. If there are no other references to the underlying object, it may be destroyed by Python. If it continues to exist and is retrieved by Java code again, a new PyObject will be returned.

Caution: any references to the same Python object elsewhere in your program will be represented by the same PyObject, so they will all be invalidated by this call.

Specified by:

close in interface AutoCloseable

containsKey

public boolean containsKey(@NotNull
                           Object key)

Equivalent to Python hasattr().

Specified by:

containsKey in interface Map<String,PyObject>

Overrides:

containsKey in class AbstractMap<String,PyObject>

containsValue

public boolean containsValue(Object o)

Returns whether any attribute has the given value. The value will be converted as described at fromJava().

Specified by:

containsValue in interface Map<String,PyObject>

Overrides:

containsValue in class AbstractMap<String,PyObject>

entrySet

@NotNull
public Set<Map.Entry<String,PyObject>> entrySet()

See notes on keySet().

Specified by:

entrySet in interface Map<String,PyObject>

Specified by:

entrySet in class AbstractMap<String,PyObject>

equals

public boolean equals(Object that)

Equivalent to Python == operator. The given object will be converted as described at fromJava()

Specified by:

equals in interface Map<String,PyObject>

Overrides:

equals in class AbstractMap<String,PyObject>

finalize

protected void finalize()
                 throws Throwable

Calls close().

Overrides:

finalize in class Object

Throws:

Throwable

fromJava

public static PyObject fromJava(Object o)

Converts the given Java object to a Python object. There's usually no need to call this method: it will be called automatically by the methods of this class which take Object parameters.

For details of how Java objects are represented in Python, see the Python API.

get

public PyObject get(@NotNull
                    Object key)

Equivalent to Python getattr(). In accordance with the Map interface, when the attribute does not exist, this method returns null rather than throwing an exception. To distinguish this from an attribute with a value of None, use containsKey().

Specified by:

get in interface Map<String,PyObject>

Overrides:

get in class AbstractMap<String,PyObject>

hashCode

public int hashCode()

Equivalent to Python hash().

Specified by:

hashCode in interface Map<String,PyObject>

Overrides:

hashCode in class AbstractMap<String,PyObject>

id

public long id()

Equivalent to Python id().

isEmpty

public boolean isEmpty()

Equivalent to keySet().isEmpty(). Because keySet usually includes the object's class attributes, isEmpty will never return true even after calling clear(), unless the object has a custom __dir__ method.

Specified by:

isEmpty in interface Map<String,PyObject>

Overrides:

isEmpty in class AbstractMap<String,PyObject>

keySet

@NotNull
public Set<String> keySet()

Equivalent to Python dir(). Unless the object has a custom __dir__ method, this means the result will include attributes from the object's class as well as the object itself.

The returned set is backed by the Python object, so changes to the object are reflected in the set, and vice-versa. If the object is modified while an iteration over the set is in progress (except through the iterator's own remove operation), the results of the iteration are undefined. The set supports element removal, but see the notes on remove(). It does not support the add or addAll operations.

Specified by:

keySet in interface Map<String,PyObject>

Overrides:

keySet in class AbstractMap<String,PyObject>

put

public PyObject put(@NotNull
                    String key,
                    Object value)

Equivalent to Python setattr(). The value will be converted as described at fromJava().

put

public PyObject put(@NotNull
                    String key,
                    PyObject value)

Equivalent to Python setattr().

Specified by:

put in interface Map<String,PyObject>

Overrides:

put in class AbstractMap<String,PyObject>

remove

public PyObject remove(@NotNull
                       Object key)

Equivalent to Python delattr(). This means it can only remove attributes of the object itself, even though keySet() usually includes the object's class attributes as well.

In accordance with the Map interface, when the attribute does not exist, this method returns null rather than throwing an exception.

Specified by:

remove in interface Map<String,PyObject>

Overrides:

remove in class AbstractMap<String,PyObject>

repr

@NotNull
public String repr()

Equivalent to Python repr().

toBoolean

public boolean toBoolean()

Converts a Python bool to a Java boolean.

Throws:

ClassCastException - if the Python object is not compatible

toByte

public byte toByte()

Converts a Python int to a Java byte.

Throws:

ClassCastException - if the Python object is not compatible

toChar

public char toChar()

Converts a 1-character Python string to a Java char.

Throws:

ClassCastException - if the Python object is not compatible

toDouble

public double toDouble()

Converts a Python float or int to a Java double.

Throws:

ClassCastException - if the Python object is not compatible

toFloat

public float toFloat()

Converts a Python float or int to a Java float.

Throws:

ClassCastException - if the Python object is not compatible

toInt

public int toInt()

Converts a Python int to a Java int.

Throws:

ClassCastException - if the Python object is not compatible

toJava

@NotNull
public <T> T toJava(@NotNull
                             Class<T> klass)

Converts the Python object to the given Java type.

If klass is a primitive type such as int, or an immutable value type such as Integer or String, and the Python object is compatible with it, an equivalent Java object will be returned. However, it's more efficient to use the specific methods like toInt(), toString(), etc.

If klass is an array type, and the Python object is a sequence, then a copy of the sequence will be returned as a new array. In general, each element will be converted as if toJava was called on it recursively. However, when converting a Python bytes or bytearray object to a Java byte[] array, there is an unsigned-to-signed conversion: Python values 128 to 255 will be mapped to Java values -128 to -1.

If the Python object is a jclass or jarray object which is compatible with klass, the underlying Java object will be returned.

Otherwise, a ClassCastException will be thrown.

toLong

public long toLong()

Converts a Python int to a Java long.

Throws:

ClassCastException - if the Python object is not compatible

toShort

public short toShort()

Converts a Python int to a Java short.

Throws:

ClassCastException - if the Python object is not compatible

toString

@NotNull
public String toString()

Equivalent to Python str().

Overrides:

toString in class AbstractMap<String,PyObject>

type

@NotNull
public PyObject type()

Equivalent to Python type().