jep

Class Jep

java.lang.Object

jep.Jep

All Implemented Interfaces:

java.lang.AutoCloseable, Interpreter

Direct Known Subclasses:

SharedInterpreter, SubInterpreter

public abstract class Jep
extends java.lang.Object
implements Interpreter

As of Jep 3.9, you should strive to instantiate either a SubInterpreter or a SharedInterpreter instance and for interacting with the interpreter use the interface Interpreter. If you previously used Jep instances, use SubInterpreter instances to retain the same behavior.

Embeds CPython in Java. Each Jep provides access to a Python interpreter and maintains an independent global namespace for Python variables. Values can be passed from Java to Python using the various set() methods. Various methods, such as eval(String) and invoke(String, Object...) can be used to execute Python code. Python variables can be accessed using getValue(String).

In general, methods called on a Jep instance must be called from the same thread that created the instance. To maintain stability, avoid having two Jep instances running on the same thread at the same time. Instead provide different threads or close() one before instantiating another on the same thread. Jep instances should always be closed when no longer needed to prevent memory leaks.

Constructor Summary

Constructors

Constructor and Description
Jep() Deprecated. Deprecated in 3.9. Use SubInterpreter or SharedInterpreter instead. If you used Jep objects in previous releases, use SubIntepreter for the same behavior.
Jep(JepConfig config) Deprecated. Deprecated in 3.9. Use SubInterpreter or SharedInterpreter instead. If you used Jep objects in previous releases, use SubIntepreter for the same behavior.

Method Summary

Modifier and Type	Method and Description
Interpreter	attach(boolean shareGlobals) Attach the currently executing thread to the interpreter state for this Interpreter.
void	close() Shuts down the Python interpreter.
boolean	eval(java.lang.String str) Evaluate Python statements.
void	exec(java.lang.String str) Execute an arbitrary number of Python statements in this interpreter.
java.lang.Object	getValue(java.lang.String str) Retrieves a value from this Python interpreter.
<T> T	getValue(java.lang.String str, java.lang.Class<T> clazz) Like Interpreter.getValue(String) but allows specifying the return type.
java.lang.Object	invoke(java.lang.String name, java.util.Map<java.lang.String,java.lang.Object> kwargs) Invokes a Python function.
java.lang.Object	invoke(java.lang.String name, java.lang.Object... args) Invokes a Python function.
java.lang.Object	invoke(java.lang.String name, java.lang.Object[] args, java.util.Map<java.lang.String,java.lang.Object> kwargs) Invokes a Python function.
void	isValidThread() Deprecated. For internal usage only. Internal Only
void	runScript(java.lang.String script) Runs a Python script.
void	set(java.lang.String name, java.lang.Object v) Sets the Java Object into the interpreter's global scope with the specified variable name.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Jep

@Deprecated
public Jep()
                throws JepException

Deprecated. Deprecated in 3.9. Use SubInterpreter or SharedInterpreter instead. If you used Jep objects in previous releases, use SubIntepreter for the same behavior.

Creates a new Jep instance and its associated interpreter.

Throws:

JepException - if an error occurs

Jep

@Deprecated
public Jep(JepConfig config)
                throws JepException

Deprecated. Deprecated in 3.9. Use SubInterpreter or SharedInterpreter instead. If you used Jep objects in previous releases, use SubIntepreter for the same behavior.

Creates a new Jep instance and its associated interpreter.

Parameters:

config - the configuration for the Jep instance

Throws:

JepException - if an error occurs

Method Detail

isValidThread

@Deprecated
public void isValidThread()
                               throws JepException

Deprecated. For internal usage only. Internal Only

Checks if the current thread is valid for the method call. All calls must check the thread.

Throws:

JepException - if an error occurs

runScript

public void runScript(java.lang.String script)
               throws JepException

Description copied from interface: Interpreter

Runs a Python script.

Specified by:

runScript in interface Interpreter

Parameters:

script - a String absolute path to script file.

Throws:

JepException - if an error occurs

invoke

public java.lang.Object invoke(java.lang.String name,
                               java.lang.Object... args)
                        throws JepException

Description copied from interface: Interpreter

Invokes a Python function.

Specified by:

invoke in interface Interpreter

Parameters:

name - a Python function name in globals dict or the name of a global object and method using dot notation

args - args to pass to the function in order

Returns:

an Object value

Throws:

JepException - if an error occurs

invoke

public java.lang.Object invoke(java.lang.String name,
                               java.util.Map<java.lang.String,java.lang.Object> kwargs)
                        throws JepException

Description copied from interface: Interpreter

Invokes a Python function.

Specified by:

invoke in interface Interpreter

Parameters:

name - a Python function name in globals dict or the name of a global object and method using dot notation

kwargs - a Map of keyword args

Returns:

an Object value

Throws:

JepException - if an error occurs

invoke

public java.lang.Object invoke(java.lang.String name,
                               java.lang.Object[] args,
                               java.util.Map<java.lang.String,java.lang.Object> kwargs)
                        throws JepException

Description copied from interface: Interpreter

Invokes a Python function.

Specified by:

invoke in interface Interpreter

Parameters:

name - a Python function name in globals dict or the name of a global object and method using dot notation

args - args to pass to the function in order

kwargs - a Map of keyword args

Returns:

an Object value

Throws:

JepException - if an error occurs

eval

public boolean eval(java.lang.String str)
             throws JepException

Description copied from interface: Interpreter

Evaluate Python statements.

In interactive mode, Jep may not immediately execute the given lines of code. In that case, eval() returns false and the statement is stored and is appended to the next incoming string.

If you're running an unknown number of statements, finish with eval(null) to flush the statement buffer.

Interactive mode is slower than a straight eval call since it has to compile the code strings to detect the end of the block. Non-interactive mode is faster, but code blocks must be complete. For example:

 interactive mode == false
 jep.eval("if(Test):\n    print('Hello world')");
 

 interactive mode == true
 jep.eval("if(Test):");
 jep.eval("    print('Hello world')");
 jep.eval(null);
 
 

Also, Python does not readily return object values from eval(). Use Interpreter.getValue(String) instead.

Note: Interactive mode will be removed in a future release. This method may still be used for executing individual statements. See console.py for an example of how to interactively execute Python using the builtin compile() and exec() functions.

Specified by:

eval in interface Interpreter

Parameters:

str - a String statement to eval

Returns:

true if statement complete and was executed.

Throws:

JepException - if an error occurs

exec

public void exec(java.lang.String str)
          throws JepException

Description copied from interface: Interpreter

Execute an arbitrary number of Python statements in this interpreter. Similar to the Python builtin exec function.

Specified by:

exec in interface Interpreter

Parameters:

str - Python code to exececute

Throws:

JepException - if an error occurs

getValue

public java.lang.Object getValue(java.lang.String str)
                          throws JepException

Description copied from interface: Interpreter

Retrieves a value from this Python interpreter. Supports retrieving:

• Java objects
• Python None (null)
• Python strings
• Python True and False
• Python numbers
• Python lists
• Python tuples
• Python dictionaries

For Python containers, such as lists and dictionaries, getValue will recursively move through the container and convert each item. If the type of the value retrieved is not supported, Jep will fall back to returning a PyObject representation of the object.

Specified by:

getValue in interface Interpreter

Parameters:

str - the name of the Python variable to get from the interpreter's global scope

Returns:

an Object value

Throws:

JepException - if an error occurs

getValue

public <T> T getValue(java.lang.String str,
                      java.lang.Class<T> clazz)
               throws JepException

Description copied from interface: Interpreter

Like Interpreter.getValue(String) but allows specifying the return type. If Jep cannot convert the variable to the specified type then a JepException is thrown. This can be used to safely ensure that the return value is an expected type. The following table describes what conversions are currently possible.

The valid classes for Python to Java conversions

Python Class	Java Classes	Notes
str/unicode	String, Character	Character conversion will fail if the str is longer than 1.
bool	Boolean
int/long	Long, Integer, Short, Byte	Conversion fails if the number is outside the valid range for the Java type
float	Double, Float
list, tuple	List, array	When a tuple is converted to a List it is unmodifiable.
dict	Map
function, method	Any FunctionalInterface
Buffer Protocol	array	This includes Python classes such as bytes, bytearray and array.array
numpy.ndarray	NDArray	Only if Jep was built with numpy support
numpy.float64	Double, Float
numpy.float32	Float, Double
numpy.int64	Long, Integer, Short, Byte	Conversion fails if the number is outside the valid range for the Java type
numpy.int32	Integer, Long, Short, Byte	Conversion fails if the number is outside the valid range for the Java type
numpy.int16	Short, Integer, Long, Byte	Conversion fails if the number is outside the valid range for the Java type
numpy.int8	Byte. Short, Integer, Long
NoneType	Any(null)
Jep objects such as PyJObjects and jarrays will be returned if the Java type of the wrapped object is compatible.
Anything else	PyObject, String

Specified by:

getValue in interface Interpreter

Type Parameters:

T - the generic type of the return type

Parameters:

str - the name of the Python variable to get from the interpreter's global scope

clazz - the Java class of the return type.

Returns:

a Java version of the variable

Throws:

JepException - if an error occurs

set

public void set(java.lang.String name,
                java.lang.Object v)
         throws JepException

Description copied from interface: Interpreter

Sets the Java Object into the interpreter's global scope with the specified variable name.

Specified by:

set in interface Interpreter

Parameters:

name - the Python name for the variable

v - an Object value

Throws:

JepException - if an error occurs

attach

public Interpreter attach(boolean shareGlobals)

Description copied from interface: Interpreter

Attach the currently executing thread to the interpreter state for this Interpreter. The returned Interpreter will share state with this interpreter including sys.modules and other internal Python structures including the GIL. PyObjects can be used on any thread attached to the same interpreter state.

When this is used with a SharedInterpreter it is identical to creating a new SharedInterpreter except it adds the ability to share global variables between Interpreters.

When this is used with a SubInterpreter then all Interpreters created from the same SubInterpreter have sharing between each other but are still isolated from other Interpreters. If the original SubInterpreter is closed while other threads are attached to the interpreter state then the state remains open until the last attached interpreter is closed.

Concurrency between threads attached to the same interpreter state works just like threads created using the threading module and synchronization mechanisms from that module may be used to control concurrency.

Unlike most Interpreter methods this method must be called from a different thread then the thread where the existing Interpreter is running. The new Interpreter can only be used on the thread where it was created and must be closed when it is no longer used. A thread can only be attached to one interpreter at a time and must be closed before it can be attached to a different Interpreter.

Specified by:

attach in interface Interpreter

Parameters:

shareGlobals - If true then the globals of the new interpreter will be the same dict as this interpreter. If false the new interpreter will have it's own independent globals.

Returns:

a new Interpreter valid on the current thread which shares state with this Interpreter.

close

public void close()
           throws JepException

Shuts down the Python interpreter. Make sure you call this to prevent memory leaks.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface Interpreter

Throws:

JepException