Package jep

Class 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) 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 Description
      Jep()
      Deprecated.
      Deprecated in 3.9.
      Jep​(boolean interactive)
      Deprecated.
      Please use Jep(JepConfig) instead.
      Jep​(boolean interactive, java.lang.String includePath)
      Deprecated.
      Please use Jep(JepConfig) instead.
      Jep​(boolean interactive, java.lang.String includePath, java.lang.ClassLoader cl)
      Deprecated.
      Please use Jep(JepConfig) instead.
      Jep​(boolean interactive, java.lang.String includePath, java.lang.ClassLoader cl, ClassEnquirer ce)
      Deprecated.
      Please use Jep(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)
      Like Interpreter.getValue(String) but allows specifying the return type.
      byte[] getValue_bytearray​(java.lang.String str)
      Deprecated.
      use Python 3 bytes object instead and getValue(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.
      Use set(String, Object) instead.
      void set​(java.lang.String name, boolean[] v)
      Deprecated.
      Use set(String, Object) instead.
      void set​(java.lang.String name, byte b)
      Deprecated.
      Use set(String, Object) instead.
      void set​(java.lang.String name, byte[] v)
      Deprecated.
      Use set(String, Object) instead.
      void set​(java.lang.String name, char v)
      Deprecated.
      Use set(String, Object) instead.
      void set​(java.lang.String name, char[] v)
      Deprecated.
      Use set(String, Object) instead.
      void set​(java.lang.String name, double v)
      Deprecated.
      Use set(String, Object) instead.
      void set​(java.lang.String name, double[] v)
      Deprecated.
      Use set(String, Object) instead.
      void set​(java.lang.String name, float v)
      Deprecated.
      Use set(String, Object) instead.
      void set​(java.lang.String name, float[] v)
      Deprecated.
      Use set(String, Object) instead.
      void set​(java.lang.String name, int v)
      Deprecated.
      Use set(String, Object) instead.
      void set​(java.lang.String name, int[] v)
      Deprecated.
      Use set(String, Object) instead.
      void set​(java.lang.String name, long v)
      Deprecated.
      Use set(String, Object) instead.
      void set​(java.lang.String name, long[] v)
      Deprecated.
      Use set(String, Object) instead.
      void set​(java.lang.String name, short v)
      Deprecated.
      Use set(String, Object) instead.
      void set​(java.lang.String name, short[] v)
      Deprecated.
      Use set(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.
      Use set(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 use MainInterpreter.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 use MainInterpreter.setSharedModulesArgv(String...) instead.

      • 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​(boolean interactive)
    throws JepException
        Deprecated.
        Please use Jep(JepConfig) instead.
        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

        @Deprecated
public Jep​(boolean interactive,
           java.lang.String includePath)
    throws JepException
        Deprecated.
        Please use Jep(JepConfig) instead.
        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

        @Deprecated
public Jep​(boolean interactive,
           java.lang.String includePath,
           java.lang.ClassLoader cl)
    throws JepException
        Deprecated.
        Please use Jep(JepConfig) instead.
        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

        @Deprecated
public Jep​(boolean interactive,
           java.lang.String includePath,
           java.lang.ClassLoader cl,
           ClassEnquirer ce)
    throws JepException
        Deprecated.
        Please use Jep(JepConfig) instead.
        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

        @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

      • setInitParams

        @Deprecated
public static void setInitParams​(PyConfig config)
                          throws JepException
        Deprecated.
        Please use MainInterpreter.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 use MainInterpreter.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 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

      • 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 - 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
        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 String representation of the object. This fallback behavior will probably change in the future and should not be relied upon.

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

      • getValue_bytearray

        @Deprecated
public byte[] getValue_bytearray​(java.lang.String str)
                          throws JepException
        Deprecated.
        use Python 3 bytes object instead and getValue(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 - a ClassLoader value

      • setInteractive

        @Deprecated
public void setInteractive​(boolean v)
        Deprecated.
        This may be removed in a future version of Jep.
        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

        @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 interface Interpreter
        Parameters:
        name - the Python name for the variable
        v - an Object value
        Throws:
        JepException - if an error occurs

      • set

        @Deprecated
public void set​(java.lang.String name,
                java.lang.String v)
         throws JepException
        Deprecated.
        Use set(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 variable
        v - a String value
        Throws:
        JepException - if an error occurs

      • set

        @Deprecated
public void set​(java.lang.String name,
                boolean v)
         throws JepException
        Deprecated.
        Use set(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 variable
        v - a boolean value
        Throws:
        JepException - if an error occurs

      • set

        @Deprecated
public void set​(java.lang.String name,
                int v)
         throws JepException
        Deprecated.
        Use set(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 variable
        v - an int value
        Throws:
        JepException - if an error occurs

      • set

        @Deprecated
public void set​(java.lang.String name,
                short v)
         throws JepException
        Deprecated.
        Use set(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 variable
        v - an int value
        Throws:
        JepException - if an error occurs

      • set

        @Deprecated
public void set​(java.lang.String name,
                char[] v)
         throws JepException
        Deprecated.
        Use set(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 variable
        v - a char[] value
        Throws:
        JepException - if an error occurs

      • set

        @Deprecated
public void set​(java.lang.String name,
                char v)
         throws JepException
        Deprecated.
        Use set(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 variable
        v - a char value
        Throws:
        JepException - if an error occurs

      • set

        @Deprecated
public void set​(java.lang.String name,
                byte b)
         throws JepException
        Deprecated.
        Use set(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 variable
        b - a byte value
        Throws:
        JepException - if an error occurs

      • set

        @Deprecated
public void set​(java.lang.String name,
                long v)
         throws JepException
        Deprecated.
        Use set(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 variable
        v - a long value
        Throws:
        JepException - if an error occurs

      • set

        @Deprecated
public void set​(java.lang.String name,
                double v)
         throws JepException
        Deprecated.
        Use set(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 variable
        v - a double value
        Throws:
        JepException - if an error occurs

      • set

        @Deprecated
public void set​(java.lang.String name,
                float v)
         throws JepException
        Deprecated.
        Use set(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 variable
        v - a float value
        Throws:
        JepException - if an error occurs

      • set

        @Deprecated
public void set​(java.lang.String name,
                boolean[] v)
         throws JepException
        Deprecated.
        Use set(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 variable
        v - a boolean[] value
        Throws:
        JepException - if an error occurs

      • set

        @Deprecated
public void set​(java.lang.String name,
                int[] v)
         throws JepException
        Deprecated.
        Use set(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 variable
        v - an int[] value
        Throws:
        JepException - if an error occurs

      • set

        @Deprecated
public void set​(java.lang.String name,
                short[] v)
         throws JepException
        Deprecated.
        Use set(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 variable
        v - a short[] value
        Throws:
        JepException - if an error occurs

      • set

        @Deprecated
public void set​(java.lang.String name,
                byte[] v)
         throws JepException
        Deprecated.
        Use set(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 variable
        v - a byte[] value
        Throws:
        JepException - if an error occurs

      • set

        @Deprecated
public void set​(java.lang.String name,
                long[] v)
         throws JepException
        Deprecated.
        Use set(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 variable
        v - a long[] value
        Throws:
        JepException - if an error occurs

      • set

        @Deprecated
public void set​(java.lang.String name,
                double[] v)
         throws JepException
        Deprecated.
        Use set(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 variable
        v - a double[] value
        Throws:
        JepException - if an error occurs

      • set

        @Deprecated
public void set​(java.lang.String name,
                float[] v)
         throws JepException
        Deprecated.
        Use set(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 variable
        v - a float[] 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 interface java.lang.AutoCloseable
        Specified by:
        close in interface Interpreter
        Throws:
        JepException