Class Jep
- java.lang.Object
-
- jep.Jep
-
- All Implemented Interfaces:
java.lang.AutoCloseable
,Interpreter
- Direct Known Subclasses:
SharedInterpreter
,SubInterpreter
public 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)
andinvoke(String, Object...)
can be used to execute Python code. Python variables can be accessed usinggetValue(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 Description Jep()
Deprecated.Deprecated in 3.9.Jep(boolean interactive)
Deprecated.Please useJep(JepConfig)
instead.Jep(boolean interactive, java.lang.String includePath)
Deprecated.Please useJep(JepConfig)
instead.Jep(boolean interactive, java.lang.String includePath, java.lang.ClassLoader cl)
Deprecated.Please useJep(JepConfig)
instead.Jep(boolean interactive, java.lang.String includePath, java.lang.ClassLoader cl, ClassEnquirer ce)
Deprecated.Please useJep(JepConfig)
instead.Jep(JepConfig config)
Deprecated.Deprecated in 3.9.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description 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)
LikeInterpreter.getValue(String)
but allows specifying the return type.byte[]
getValue_bytearray(java.lang.String str)
Deprecated.use Python 3 bytes object instead andgetValue(String,Class)
with byte[].class Retrieves a Python string object as a Java byte[].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.java.lang.Object
invoke(java.lang.String name, java.util.Map<java.lang.String,java.lang.Object> kwargs)
Invokes a Python function.boolean
isInteractive()
Deprecated.This may be removed in a future version of Jep.void
isValidThread()
Deprecated.For internal usage only.void
runScript(java.lang.String script)
Runs a Python script.void
runScript(java.lang.String script, java.lang.ClassLoader cl)
Deprecated.This may be removed in a future version of Jep, as Jep does not fully support changing the ClassLoader after construction.void
set(java.lang.String name, boolean v)
Deprecated.Useset(String, Object)
instead.void
set(java.lang.String name, boolean[] v)
Deprecated.Useset(String, Object)
instead.void
set(java.lang.String name, byte b)
Deprecated.Useset(String, Object)
instead.void
set(java.lang.String name, byte[] v)
Deprecated.Useset(String, Object)
instead.void
set(java.lang.String name, char v)
Deprecated.Useset(String, Object)
instead.void
set(java.lang.String name, char[] v)
Deprecated.Useset(String, Object)
instead.void
set(java.lang.String name, double v)
Deprecated.Useset(String, Object)
instead.void
set(java.lang.String name, double[] v)
Deprecated.Useset(String, Object)
instead.void
set(java.lang.String name, float v)
Deprecated.Useset(String, Object)
instead.void
set(java.lang.String name, float[] v)
Deprecated.Useset(String, Object)
instead.void
set(java.lang.String name, int v)
Deprecated.Useset(String, Object)
instead.void
set(java.lang.String name, int[] v)
Deprecated.Useset(String, Object)
instead.void
set(java.lang.String name, long v)
Deprecated.Useset(String, Object)
instead.void
set(java.lang.String name, long[] v)
Deprecated.Useset(String, Object)
instead.void
set(java.lang.String name, short v)
Deprecated.Useset(String, Object)
instead.void
set(java.lang.String name, short[] v)
Deprecated.Useset(String, Object)
instead.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.void
set(java.lang.String name, java.lang.String v)
Deprecated.Useset(String, Object)
instead.void
setClassLoader(java.lang.ClassLoader cl)
Deprecated.This may be removed in a future version of Jep.static void
setInitParams(PyConfig config)
Deprecated.Please useMainInterpreter.setInitParams(PyConfig)
instead.void
setInteractive(boolean v)
Deprecated.This may be removed in a future version of Jep.static void
setSharedModulesArgv(java.lang.String... argv)
Deprecated.Please useMainInterpreter.setSharedModulesArgv(String...)
instead.
-
-
-
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 newJep
instance and its associated interpreter.- Throws:
JepException
- if an error occurs
-
Jep
@Deprecated public Jep(boolean interactive) throws JepException
Deprecated.Please useJep(JepConfig)
instead.Creates a newJep
instance and its associated sub-interpreter.- Parameters:
interactive
- whethereval(String)
should support the slower behavior of potentially waiting for multiple statements- Throws:
JepException
- if an error occurs
-
Jep
@Deprecated public Jep(boolean interactive, java.lang.String includePath) throws JepException
Deprecated.Please useJep(JepConfig)
instead.Creates a newJep
instance and its associated sub-interpreter.- Parameters:
interactive
- whethereval(String)
should support the slower behavior of potentially waiting for multiple statementsincludePath
- a path of directories separated by File.pathSeparator that will be appended to the sub-intepreter'ssys.path
- Throws:
JepException
- if an error occurs
-
Jep
@Deprecated public Jep(boolean interactive, java.lang.String includePath, java.lang.ClassLoader cl) throws JepException
Deprecated.Please useJep(JepConfig)
instead.Creates a newJep
instance and its associated sub-interpreter.- Parameters:
interactive
- whethereval(String)
should support the slower behavior of potentially waiting for multiple statementsincludePath
- a path of directories separated by File.pathSeparator that will be appended to the sub-intepreter'ssys.path
cl
- the ClassLoader to use when importing Java classes from Python- Throws:
JepException
- if an error occurs
-
Jep
@Deprecated public Jep(boolean interactive, java.lang.String includePath, java.lang.ClassLoader cl, ClassEnquirer ce) throws JepException
Deprecated.Please useJep(JepConfig)
instead.Creates a newJep
instance and its associated sub-interpreter.- Parameters:
interactive
- whethereval(String)
should support the slower behavior of potentially waiting for multiple statementsincludePath
- a path of directories separated by File.pathSeparator that will be appended to the sub-intepreter'ssys.path
cl
- the ClassLoader to use when importing Java classes from Pythonce
- aClassEnquirer
to determine which imports are Python vs Java, or null for the defaultClassList
- 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 newJep
instance and its associated interpreter.- Parameters:
config
- the configuration for the Jep instance- Throws:
JepException
- if an error occurs
-
-
Method Detail
-
setInitParams
@Deprecated public static void setInitParams(PyConfig config) throws JepException
Deprecated.Please useMainInterpreter.setInitParams(PyConfig)
instead.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
- if an error occurs- Since:
- 3.6
-
setSharedModulesArgv
@Deprecated public static void setSharedModulesArgv(java.lang.String... argv) throws JepException
Deprecated.Please useMainInterpreter.setSharedModulesArgv(String...)
instead.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
- if an error occurs- Since:
- 3.7
-
isValidThread
@Deprecated public void isValidThread() throws JepException
Deprecated.For internal usage only. Internal OnlyChecks 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 interfaceInterpreter
- Parameters:
script
- aString
absolute path to script file.- Throws:
JepException
- if an error occurs
-
runScript
@Deprecated public void runScript(java.lang.String script, java.lang.ClassLoader cl) throws JepException
Deprecated.This may be removed in a future version of Jep, as Jep does not fully support changing the ClassLoader after construction.Runs a Python script.- Parameters:
script
- aString
absolute path to script file.cl
- aClassLoader
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
Description copied from interface:Interpreter
Invokes a Python function.- Specified by:
invoke
in interfaceInterpreter
- Parameters:
name
- a Python function name in globals dict or the name of a global object and method using dot notationargs
- 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 interfaceInterpreter
- Parameters:
name
- a Python function name in globals dict or the name of a global object and method using dot notationkwargs
- 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 interfaceInterpreter
- Parameters:
name
- a Python function name in globals dict or the name of a global object and method using dot notationargs
- args to pass to the function in orderkwargs
- 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 interfaceInterpreter
- Parameters:
str
- aString
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 interfaceInterpreter
- 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 String representation of the object. This fallback behavior will probably change in the future and should not be relied upon.
- Specified by:
getValue
in interfaceInterpreter
- 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
LikeInterpreter.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
, arrayWhen 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 String
,PyObject
String conversion will likely be removed in future versions of Jep so it is unsafe to depend on this behavior. - Specified by:
getValue
in interfaceInterpreter
- 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 scopeclazz
- the Java class of the return type.- Returns:
- a Java version of the variable
- Throws:
JepException
- if an error occurs
-
getValue_bytearray
@Deprecated public byte[] getValue_bytearray(java.lang.String str) throws JepException
Deprecated.use Python 3 bytes object instead andgetValue(String,Class)
with byte[].class 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
-
setClassLoader
@Deprecated public void setClassLoader(java.lang.ClassLoader cl)
Deprecated.This may be removed in a future version of Jep. Jep does not fully support changing the ClassLoader after construction.Sets the default classloader.- Parameters:
cl
- aClassLoader
value
-
setInteractive
@Deprecated public void setInteractive(boolean v)
Deprecated.This may be removed in a future version of Jep.Changes behavior ofeval(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
@Deprecated public boolean isInteractive()
Deprecated.This may be removed in a future version of Jep.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
Description copied from interface:Interpreter
Sets the Java Object into the interpreter's global scope with the specified variable name.- Specified by:
set
in interfaceInterpreter
- Parameters:
name
- the Python name for the variablev
- anObject
value- Throws:
JepException
- if an error occurs
-
set
@Deprecated public void set(java.lang.String name, java.lang.String v) throws JepException
Deprecated.Useset(String, Object)
instead.Sets the Java String into the sub-interpreter's global scope with the specified variable name.- Parameters:
name
- the Python name for the variablev
- aString
value- Throws:
JepException
- if an error occurs
-
set
@Deprecated public void set(java.lang.String name, boolean v) throws JepException
Deprecated.Useset(String, Object)
instead.Sets the Java boolean into the sub-interpreter's global scope with the specified variable name.- Parameters:
name
- the Python name for the variablev
- aboolean
value- Throws:
JepException
- if an error occurs
-
set
@Deprecated public void set(java.lang.String name, int v) throws JepException
Deprecated.Useset(String, Object)
instead.Sets the Java int into the sub-interpreter's global scope with the specified variable name.- Parameters:
name
- the Python name for the variablev
- anint
value- Throws:
JepException
- if an error occurs
-
set
@Deprecated public void set(java.lang.String name, short v) throws JepException
Deprecated.Useset(String, Object)
instead.Sets the Java short into the sub-interpreter's global scope with the specified variable name.- Parameters:
name
- the Python name for the variablev
- anint
value- Throws:
JepException
- if an error occurs
-
set
@Deprecated public void set(java.lang.String name, char[] v) throws JepException
Deprecated.Useset(String, Object)
instead.Sets the Java char[] into the sub-interpreter's global scope with the specified variable name.- Parameters:
name
- the Python name for the variablev
- achar[]
value- Throws:
JepException
- if an error occurs
-
set
@Deprecated public void set(java.lang.String name, char v) throws JepException
Deprecated.Useset(String, Object)
instead.Sets the Java char into the sub-interpreter's global scope with the specified variable name.- Parameters:
name
- the Python name for the variablev
- achar
value- Throws:
JepException
- if an error occurs
-
set
@Deprecated public void set(java.lang.String name, byte b) throws JepException
Deprecated.Useset(String, Object)
instead.Sets the Java byte into the sub-interpreter's global scope with the specified variable name.- Parameters:
name
- the Python name for the variableb
- abyte
value- Throws:
JepException
- if an error occurs
-
set
@Deprecated public void set(java.lang.String name, long v) throws JepException
Deprecated.Useset(String, Object)
instead.Sets the Java long into the sub-interpreter's global scope with the specified variable name.- Parameters:
name
- the Python name for the variablev
- along
value- Throws:
JepException
- if an error occurs
-
set
@Deprecated public void set(java.lang.String name, double v) throws JepException
Deprecated.Useset(String, Object)
instead.Sets the Java double into the sub-interpreter's global scope with the specified variable name.- Parameters:
name
- the Python name for the variablev
- adouble
value- Throws:
JepException
- if an error occurs
-
set
@Deprecated public void set(java.lang.String name, float v) throws JepException
Deprecated.Useset(String, Object)
instead.Sets the Java float into the sub-interpreter's global scope with the specified variable name.- Parameters:
name
- the Python name for the variablev
- afloat
value- Throws:
JepException
- if an error occurs
-
set
@Deprecated public void set(java.lang.String name, boolean[] v) throws JepException
Deprecated.Useset(String, Object)
instead.Sets the Java boolean[] into the sub-interpreter's global scope with the specified variable name.- Parameters:
name
- the Python name for the variablev
- aboolean[]
value- Throws:
JepException
- if an error occurs
-
set
@Deprecated public void set(java.lang.String name, int[] v) throws JepException
Deprecated.Useset(String, Object)
instead.Sets the Java int[] into the sub-interpreter's global scope with the specified variable name.- Parameters:
name
- the Python name for the variablev
- anint[]
value- Throws:
JepException
- if an error occurs
-
set
@Deprecated public void set(java.lang.String name, short[] v) throws JepException
Deprecated.Useset(String, Object)
instead.Sets the Java short[] into the sub-interpreter's global scope with the specified variable name.- Parameters:
name
- the Python name for the variablev
- ashort[]
value- Throws:
JepException
- if an error occurs
-
set
@Deprecated public void set(java.lang.String name, byte[] v) throws JepException
Deprecated.Useset(String, Object)
instead.Sets the Java byte[] into the sub-interpreter's global scope with the specified variable name.- Parameters:
name
- the Python name for the variablev
- abyte[]
value- Throws:
JepException
- if an error occurs
-
set
@Deprecated public void set(java.lang.String name, long[] v) throws JepException
Deprecated.Useset(String, Object)
instead.Sets the Java long[] into the sub-interpreter's global scope with the specified variable name.- Parameters:
name
- the Python name for the variablev
- along[]
value- Throws:
JepException
- if an error occurs
-
set
@Deprecated public void set(java.lang.String name, double[] v) throws JepException
Deprecated.Useset(String, Object)
instead.Sets the Java double[] into the sub-interpreter's global scope with the specified variable name.- Parameters:
name
- the Python name for the variablev
- adouble[]
value- Throws:
JepException
- if an error occurs
-
set
@Deprecated public void set(java.lang.String name, float[] v) throws JepException
Deprecated.Useset(String, Object)
instead.Sets the Java float[] into the sub-interpreter's global scope with the specified variable name.- Parameters:
name
- the Python name for the variablev
- afloat[]
value- Throws:
JepException
- if an error occurs
-
close
public void close() throws JepException
Shuts down the Python interpreter. Make sure you call this to prevent memory leaks.- Specified by:
close
in interfacejava.lang.AutoCloseable
- Specified by:
close
in interfaceInterpreter
- Throws:
JepException
-
-