jep

Class Jep

java.lang.Object

jep.Jep

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public final class Jep
extends java.lang.Object
implements java.io.Closeable

Embeds CPython in Java. Each Jep instance can be considered a Python sub-intepreter, mostly sandboxed from other Jep instances. However, it is not guaranteed to be completely sandboxed, as one sub-interpreter may be able to affect another when using CPython extensions or referencing the same Java objects in different sub-interpreters.

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() Creates a new Jep instance and its associated sub-interpreter.
Jep(boolean interactive) Creates a new Jep instance and its associated sub-interpreter.
Jep(boolean interactive, java.lang.String includePath) Creates a new Jep instance and its associated sub-interpreter.
Jep(boolean interactive, java.lang.String includePath, java.lang.ClassLoader cl) Creates a new Jep instance and its associated sub-interpreter.
Jep(boolean interactive, java.lang.String includePath, java.lang.ClassLoader cl, ClassEnquirer ce) Creates a new Jep instance and its associated sub-interpreter.
Jep(JepConfig config)

Method Summary

Modifier and Type	Method and Description
void	close() Shuts down the Python sub-interpreter.
jep.python.PyModule	createModule(java.lang.String name) Create a Python module on the interpreter.
boolean	eval(java.lang.String str) Evaluate Python statements.
byte[]	getValue_bytearray(java.lang.String str) Retrieves a Python string object as a Java byte[].
java.lang.Object	getValue(java.lang.String str) Retrieves a value from this Python sub-interpreter.
java.lang.Object	invoke(java.lang.String name, java.lang.Object... args) Invokes a Python function.
boolean	isInteractive() Gets whether or not this sub-interpreter is interactive.
void	isValidThread() Checks if the current thread is valid for the method call.
void	runScript(java.lang.String script) Runs a Python script.
void	runScript(java.lang.String script, java.lang.ClassLoader cl) Runs a Python script.
void	set(java.lang.String name, boolean v) Sets the Java boolean into the sub-interpreter's global scope with the specified variable name.
void	set(java.lang.String name, boolean[] v) Sets the Java boolean[] into the sub-interpreter's global scope with the specified variable name.
void	set(java.lang.String name, byte b) Sets the Java byte into the sub-interpreter's global scope with the specified variable name.
void	set(java.lang.String name, byte[] v) Sets the Java byte[] into the sub-interpreter's global scope with the specified variable name.
void	set(java.lang.String name, char v) Sets the Java char into the sub-interpreter's global scope with the specified variable name.
void	set(java.lang.String name, char[] v) Sets the Java char[] into the sub-interpreter's global scope with the specified variable name.
void	set(java.lang.String name, double v) Sets the Java double into the sub-interpreter's global scope with the specified variable name.
void	set(java.lang.String name, double[] v) Sets the Java double[] into the sub-interpreter's global scope with the specified variable name.
void	set(java.lang.String name, float v) Sets the Java float into the sub-interpreter's global scope with the specified variable name.
void	set(java.lang.String name, float[] v) Sets the Java float[] into the sub-interpreter's global scope with the specified variable name.
void	set(java.lang.String name, int v) Sets the Java int into the sub-interpreter's global scope with the specified variable name.
void	set(java.lang.String name, int[] v) Sets the Java int[] into the sub-interpreter's global scope with the specified variable name.
void	set(java.lang.String name, long v) Sets the Java long into the sub-interpreter's global scope with the specified variable name.
void	set(java.lang.String name, long[] v) Sets the Java long[] into the sub-interpreter's global scope with the specified variable name.
void	set(java.lang.String name, java.lang.Object v) Sets the Java Object into the sub-interpreter's global scope with the specified variable name.
void	set(java.lang.String name, short v) Sets the Java short into the sub-interpreter's global scope with the specified variable name.
void	set(java.lang.String name, short[] v) Sets the Java short[] into the sub-interpreter's global scope with the specified variable name.
void	set(java.lang.String name, java.lang.String v) Sets the Java String into the sub-interpreter's global scope with the specified variable name.
void	setClassLoader(java.lang.ClassLoader cl) Sets the default classloader.
static void	setInitParams(PyConfig config) Sets interpreter settings for the top Python interpreter.
void	setInteractive(boolean v) Changes behavior of eval(String).
static void	setSharedModulesArgv(java.lang.String... argv) Sets the sys.argv values on the top interpreter.
jep.python.PyObject	trackObject(jep.python.PyObject obj) Track Python objects we create so they can be smoothly shutdown with no risk of crashes due to bad reference counting.
jep.python.PyObject	trackObject(jep.python.PyObject obj, boolean inc) Track Python objects we create so they can be smoothly shutdown with no risk of crashes due to bad reference counting.

Methods inherited from class java.lang.Object

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

Constructor Detail

Jep

public Jep()
    throws JepException

Creates a new Jep instance and its associated sub-interpreter.

Throws:

JepException - if an error occurs

Jep

public Jep(boolean interactive)
    throws JepException

Creates a new Jep instance and its associated sub-interpreter.

Parameters:

interactive - whether eval(String) should support the slower behavior of potentially waiting for multiple statements

Throws:

JepException - if an error occurs

Jep

public Jep(boolean interactive,
           java.lang.String includePath)
    throws JepException

Creates a new Jep instance and its associated sub-interpreter.

Parameters:

interactive - whether eval(String) should support the slower behavior of potentially waiting for multiple statements

includePath - a path of directories separated by File.pathSeparator that will be appended to the sub-intepreter's sys.path

Throws:

JepException - if an error occurs

Jep

public Jep(boolean interactive,
           java.lang.String includePath,
           java.lang.ClassLoader cl)
    throws JepException

Creates a new Jep instance and its associated sub-interpreter.

Parameters:

interactive - whether eval(String) should support the slower behavior of potentially waiting for multiple statements

includePath - a path of directories separated by File.pathSeparator that will be appended to the sub-intepreter's sys.path

cl - the ClassLoader to use when importing Java classes from Python

Throws:

JepException - if an error occurs

Jep

public Jep(boolean interactive,
           java.lang.String includePath,
           java.lang.ClassLoader cl,
           ClassEnquirer ce)
    throws JepException

Creates a new Jep instance and its associated sub-interpreter.

Parameters:

interactive - whether eval(String) should support the slower behavior of potentially waiting for multiple statements

includePath - a path of directories separated by File.pathSeparator that will be appended to the sub-intepreter's sys.path

cl - the ClassLoader to use when importing Java classes from Python

ce - a ClassEnquirer to determine which imports are Python vs Java, or null for the default ClassList

Throws:

JepException - if an error occurs

Jep

public Jep(JepConfig config)
    throws JepException

Throws:

JepException

Method Detail

setInitParams

public static void setInitParams(PyConfig config)
                          throws JepException

Sets interpreter settings for the top Python interpreter. This method must be called before the first Jep instance is created in the process.

Parameters:

config - the python configuration to use.

Throws:

JepException

Since:

3.6

setSharedModulesArgv

public static void setSharedModulesArgv(java.lang.String... argv)
                                 throws JepException

Sets the sys.argv values on the top interpreter. This is a workaround for issues with shared modules and should be considered experimental.

Parameters:

argv - the arguments to be set on Python's sys.argv for the top/main interpreter

Throws:

JepException

Since:

3.7

isValidThread

public void isValidThread()
                   throws JepException

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

Throws:

JepException - if an error occurs

runScript

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

Runs a Python script.

Parameters:

script - a String absolute path to script file.

Throws:

JepException - if an error occurs

runScript

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

Runs a Python script.

Parameters:

script - a String absolute path to script file.

cl - a ClassLoader value, may be null.

Throws:

JepException - if an error occurs

invoke

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

Invokes a Python function.

Parameters:

name - must be a valid Python function name in globals dict

args - args to pass to the function in order

Returns:

an Object value

Throws:

JepException - if an error occurs

eval

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

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 getValue(String) instead.

Parameters:

str - a String statement to eval

Returns:

true if statement complete and was executed.

Throws:

JepException - if an error occurs

getValue

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

Retrieves a value from this Python sub-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 String representation of the object. This fallback behavior will probably change in the future and should not be relied upon.

 Python is pretty picky about what it accepts here. The general syntax
 
 jep.eval("a = 5");
 String a = (String) jep.getValue("a");
 
 will work.
 

Parameters:

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

Returns:

an Object value

Throws:

JepException - if an error occurs

getValue_bytearray

public byte[] getValue_bytearray(java.lang.String str)
                          throws JepException

Retrieves a Python string object as a Java byte[].

Parameters:

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

Returns:

an Object array

Throws:

JepException - if an error occurs

trackObject

public jep.python.PyObject trackObject(jep.python.PyObject obj)
                                throws JepException

Track Python objects we create so they can be smoothly shutdown with no risk of crashes due to bad reference counting. Internal use only.

Parameters:

obj - a PyObject value

Returns:

same object, for inlining stuff

Throws:

JepException - if an error occurs

trackObject

public jep.python.PyObject trackObject(jep.python.PyObject obj,
                                       boolean inc)
                                throws JepException

Track Python objects we create so they can be smoothly shutdown with no risk of crashes due to bad reference counting. Internal use only.

Parameters:

obj - a PyObject value

inc - should trackObject incref()

Returns:

same object, for inlining stuff

Throws:

JepException - if an error occurs

createModule

public jep.python.PyModule createModule(java.lang.String name)
                                 throws JepException

Create a Python module on the interpreter. If the given name is valid, imported module, this method will return that module.

Parameters:

name - a String value

Returns:

a PyModule value

Throws:

JepException - if an error occurs

setClassLoader

public void setClassLoader(java.lang.ClassLoader cl)

Sets the default classloader.

Parameters:

cl - a ClassLoader value

setInteractive

public void setInteractive(boolean v)

Changes behavior of eval(String). Interactive mode can wait for further Python statements to be evaled, while non-interactive mode can only execute complete Python statements.

Parameters:

v - if the sub-interpreter should run in interactive mode

isInteractive

public boolean isInteractive()

Gets whether or not this sub-interpreter is interactive.

Returns:

whether or not the sub-interpreter is interactive

set

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

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

Parameters:

name - the Python name for the variable

v - an Object value

Throws:

JepException - if an error occurs

set

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

Sets the Java String into the sub-interpreter's global scope with the specified variable name.

Parameters:

name - the Python name for the variable

v - a String value

Throws:

JepException - if an error occurs

set

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

Sets the Java boolean into the sub-interpreter's global scope with the specified variable name.

Parameters:

name - the Python name for the variable

v - a boolean value

Throws:

JepException - if an error occurs

set

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

Sets the Java int into the sub-interpreter's global scope with the specified variable name.

Parameters:

name - the Python name for the variable

v - an int value

Throws:

JepException - if an error occurs

set

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

Sets the Java short into the sub-interpreter's global scope with the specified variable name.

Parameters:

name - the Python name for the variable

v - an int value

Throws:

JepException - if an error occurs

set

public void set(java.lang.String name,
                char[] v)
         throws JepException

Sets the Java char[] into the sub-interpreter's global scope with the specified variable name.

Parameters:

name - the Python name for the variable

v - a char[] value

Throws:

JepException - if an error occurs

set

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

Sets the Java char into the sub-interpreter's global scope with the specified variable name.

Parameters:

name - the Python name for the variable

v - a char value

Throws:

JepException - if an error occurs

set

public void set(java.lang.String name,
                byte b)
         throws JepException

Sets the Java byte into the sub-interpreter's global scope with the specified variable name.

Parameters:

name - the Python name for the variable

b - a byte value

Throws:

JepException - if an error occurs

set

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

Sets the Java long into the sub-interpreter's global scope with the specified variable name.

Parameters:

name - the Python name for the variable

v - a long value

Throws:

JepException - if an error occurs

set

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

Sets the Java double into the sub-interpreter's global scope with the specified variable name.

Parameters:

name - the Python name for the variable

v - a double value

Throws:

JepException - if an error occurs

set

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

Sets the Java float into the sub-interpreter's global scope with the specified variable name.

Parameters:

name - the Python name for the variable

v - a float value

Throws:

JepException - if an error occurs

set

public void set(java.lang.String name,
                boolean[] v)
         throws JepException

Sets the Java boolean[] into the sub-interpreter's global scope with the specified variable name.

Parameters:

name - the Python name for the variable

v - a boolean[] value

Throws:

JepException - if an error occurs

set

public void set(java.lang.String name,
                int[] v)
         throws JepException

Sets the Java int[] into the sub-interpreter's global scope with the specified variable name.

Parameters:

name - the Python name for the variable

v - an int[] value

Throws:

JepException - if an error occurs

set

public void set(java.lang.String name,
                short[] v)
         throws JepException

Sets the Java short[] into the sub-interpreter's global scope with the specified variable name.

Parameters:

name - the Python name for the variable

v - a short[] value

Throws:

JepException - if an error occurs

set

public void set(java.lang.String name,
                byte[] v)
         throws JepException

Sets the Java byte[] into the sub-interpreter's global scope with the specified variable name.

Parameters:

name - the Python name for the variable

v - a byte[] value

Throws:

JepException - if an error occurs

set

public void set(java.lang.String name,
                long[] v)
         throws JepException

Sets the Java long[] into the sub-interpreter's global scope with the specified variable name.

Parameters:

name - the Python name for the variable

v - a long[] value

Throws:

JepException - if an error occurs

set

public void set(java.lang.String name,
                double[] v)
         throws JepException

Sets the Java double[] into the sub-interpreter's global scope with the specified variable name.

Parameters:

name - the Python name for the variable

v - a double[] value

Throws:

JepException - if an error occurs

set

public void set(java.lang.String name,
                float[] v)
         throws JepException

Sets the Java float[] into the sub-interpreter's global scope with the specified variable name.

Parameters:

name - the Python name for the variable

v - a float[] value

Throws:

JepException - if an error occurs

close

public void close()

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

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable