Date: 2015-08-04

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.

  - ### Method Summary

    Methods
    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[].
    `float[]` | `getValue_floatarray(java.lang.String str)` Deprecated. use getValue_bytearray and ByteBuffer.asFloatBuffer() or use numpy.ndarray with float32 to get a jep.NDArray
    `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.
    `void` | `setInteractive(boolean v)` Changes behavior of `eval(String)`.
    `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

  - ### Method Detail

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

          @Deprecated
          public float[] getValue_floatarray(java.lang.String str)
                                      throws JepException

      Deprecated. use getValue_bytearray and ByteBuffer.asFloatBuffer() or use numpy.ndarray with float32 to get a jep.NDArray
      Retrieves a Python string object as a Java array.
      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

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