PythonInterpreter (Jython API documentation)
Date: 2015-04-29

org.python.util

## Class PythonInterpreter

- java.lang.Object
- - org.python.util.PythonInterpreter

- All Implemented Interfaces:
    Closeable, AutoCloseable
  Direct Known Subclasses:
    InteractiveInterpreter

      public class PythonInterpreter
      extends Object
      implements AutoCloseable, Closeable

  The PythonInterpreter class is a standard wrapper for a Jython interpreter for embedding in a Java application.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `PythonInterpreter()` Creates a new interpreter with an empty local namespace.
    `PythonInterpreter(PyObject dict)` Creates a new interpreter with a specified local namespace.
    `PythonInterpreter(PyObject dict, PySystemState systemState)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `cleanup()`
    `void` | `close()`
    `PyCode` | `compile(Reader reader)`
    `PyCode` | `compile(Reader reader, String filename)`
    `PyCode` | `compile(String script)` Compiles a string of Python source as either an expression (if possible) or a module.
    `PyCode` | `compile(String script, String filename)`
    `PyObject` | `eval(PyObject code)` Evaluates a Python code object and returns the result.
    `PyObject` | `eval(String s)` Evaluates a string as a Python expression and returns the result.
    `void` | `exec(PyObject code)` Executes a Python code object in the local namespace.
    `void` | `exec(String s)` Executes a string of Python source in the local namespace.
    `void` | `execfile(InputStream s)`
    `void` | `execfile(InputStream s, String name)`
    `void` | `execfile(String filename)` Executes a file of Python source in the local namespace.
    `PyObject` | `get(String name)` Returns the value of a variable in the local namespace.
    `<T> T` | `get(String name, Class<T> javaclass)` Returns the value of a variable in the local namespace.
    `PyObject` | `getLocals()`
    `PySystemState` | `getSystemState()`
    `static void` | `initialize(Properties preProperties, Properties postProperties, String[] argv)` Initializes the Jython runtime.
    `void` | `set(String name, Object value)` Sets a variable in the local namespace.
    `void` | `set(String name, PyObject value)` Sets a variable in the local namespace.
    `void` | `setErr(OutputStream outStream)`
    `void` | `setErr(PyObject outStream)` Sets a Python object to use for the standard output stream, `sys.stderr`.
    `void` | `setErr(Writer outStream)` Sets a `Writer` to use for the standard output stream, `sys.stdout`.
    `void` | `setIn(InputStream inStream)` Sets a `InputStream` to use for the standard input stream.
    `void` | `setIn(PyObject inStream)` Sets a Python object to use for the standard input stream, `sys.stdin`.
    `void` | `setIn(Reader inStream)` Sets a `Reader` to use for the standard input stream, `sys.stdin`.
    `void` | `setLocals(PyObject d)`
    `void` | `setOut(OutputStream outStream)` Sets a `OutputStream` to use for the standard output stream.
    `void` | `setOut(PyObject outStream)` Sets a Python object to use for the standard output stream, `sys.stdout`.
    `void` | `setOut(Writer outStream)` Sets a `Writer` to use for the standard output stream, `sys.stdout`.
    `static PythonInterpreter` | `threadLocalStateInterpreter(PyObject dict)` Creates a new interpreter with the ability to maintain a separate local namespace for each thread (set by invoking setLocals()).

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### PythonInterpreter

          public PythonInterpreter()

      Creates a new interpreter with an empty local namespace.

    - #### PythonInterpreter

          public PythonInterpreter(PyObject dict)

      Creates a new interpreter with a specified local namespace.
      Parameters:
        `dict` - a Python mapping object (e.g., a dictionary) for use as the namespace

    - #### PythonInterpreter

          public PythonInterpreter(PyObject dict,
                           PySystemState systemState)

  - ### Method Detail

    - #### initialize

          public static void initialize(Properties preProperties,
                        Properties postProperties,
                        String[] argv)

      Initializes the Jython runtime. This should only be called once, before any other Python objects (including PythonInterpreter) are created.
      Parameters:
        `preProperties` - A set of properties. Typically System.getProperties() is used. preProperties override properties from the registry file.
        `postProperties` - Another set of properties. Values like python.home, python.path and all other values from the registry files can be added to this property set. postProperties override system properties and registry properties.
        `argv` - Command line arguments, assigned to sys.argv.

    - #### threadLocalStateInterpreter

          public static PythonInterpreter threadLocalStateInterpreter(PyObject dict)

      Creates a new interpreter with the ability to maintain a separate local namespace for each thread (set by invoking setLocals()).
      Parameters:
        `dict` - a Python mapping object (e.g., a dictionary) for use as the default namespace

    - #### getSystemState

          public PySystemState getSystemState()

    - #### setIn

          public void setIn(PyObject inStream)

      Sets a Python object to use for the standard input stream, `sys.stdin`. This stream is used in a byte-oriented way, through calls to `read` and `readline` on the object.
      Parameters:
        `inStream` - a Python file-like object to use as the input stream

    - #### setIn

          public void setIn(Reader inStream)

      Sets a `Reader` to use for the standard input stream, `sys.stdin`. This stream is wrapped such that characters will be narrowed to bytes. A character greater than `U+00FF` will raise a Java `IllegalArgumentException` from within `PyString`.
      Parameters:
        `inStream` - to use as the input stream

    - #### setIn

          public void setIn(InputStream inStream)

      Sets a `InputStream` to use for the standard input stream.
      Parameters:
        `inStream` - InputStream to use as input stream

    - #### setOut

          public void setOut(PyObject outStream)

      Sets a Python object to use for the standard output stream, `sys.stdout`. This stream is used in a byte-oriented way (mostly) that depends on the type of file-like object. The behaviour as implemented is:

      | Python type of object `o` written
      | `str/bytes` | `unicode` | Any other type
      --- | --- | --- | ---
      `PyFile` | as bytes directly | respect `PyFile.encoding` | call `str(o)` first
      `PyFileWriter` | each byte value as a `char` | write as Java `char`s | call `o.toString()` first
      Other `PyObject` `f` | invoke `f.write(str(o))` | invoke `f.write(o)` | invoke `f.write(str(o))`

      Parameters:
        `outStream` - Python file-like object to use as the output stream

    - #### setOut

          public void setOut(Writer outStream)

      Sets a `Writer` to use for the standard output stream, `sys.stdout`. The behaviour as implemented is to output each object `o` by calling `o.toString()` and writing this as UTF-16.
      Parameters:
        `outStream` - to use as the output stream

    - #### setOut

          public void setOut(OutputStream outStream)

      Sets a `OutputStream` to use for the standard output stream.
      Parameters:
        `outStream` - OutputStream to use as output stream

    - #### setErr

          public void setErr(PyObject outStream)

      Sets a Python object to use for the standard output stream, `sys.stderr`. This stream is used in a byte-oriented way (mostly) that depends on the type of file-like object, in the same way as `setOut(PyObject)`.
      Parameters:
        `outStream` - Python file-like object to use as the error output stream

    - #### setErr

          public void setErr(Writer outStream)

      Sets a `Writer` to use for the standard output stream, `sys.stdout`. The behaviour as implemented is to output each object `o` by calling `o.toString()` and writing this as UTF-16.
      Parameters:
        `outStream` - to use as the error output stream

    - #### setErr

          public void setErr(OutputStream outStream)

    - #### eval

          public PyObject eval(String s)

      Evaluates a string as a Python expression and returns the result.

    - #### eval

          public PyObject eval(PyObject code)

      Evaluates a Python code object and returns the result.

    - #### exec

          public void exec(String s)

      Executes a string of Python source in the local namespace.

    - #### exec

          public void exec(PyObject code)

      Executes a Python code object in the local namespace.

    - #### execfile

          public void execfile(String filename)

      Executes a file of Python source in the local namespace.

    - #### execfile

          public void execfile(InputStream s)

    - #### execfile

          public void execfile(InputStream s,
                      String name)

    - #### compile

          public PyCode compile(String script)

      Compiles a string of Python source as either an expression (if possible) or a module. Designed for use by a JSR 223 implementation: "the Scripting API does not distinguish between scripts which return values and those which do not, nor do they make the corresponding distinction between evaluating or executing objects." (SCR.4.2.1)

    - #### compile

          public PyCode compile(Reader reader)

    - #### compile

          public PyCode compile(String script,
                       String filename)

    - #### compile

          public PyCode compile(Reader reader,
                       String filename)

    - #### getLocals

          public PyObject getLocals()

    - #### setLocals

          public void setLocals(PyObject d)

    - #### set

          public void set(String name,
                 Object value)

      Sets a variable in the local namespace.
      Parameters:
        `name` - the name of the variable
        `value` - the object to set the variable to (as converted to an appropriate Python object)

    - #### set

          public void set(String name,
                 PyObject value)

      Sets a variable in the local namespace.
      Parameters:
        `name` - the name of the variable
        `value` - the Python object to set the variable to

    - #### get

          public PyObject get(String name)

      Returns the value of a variable in the local namespace.
      Parameters:
        `name` - the name of the variable
      Returns:
        the value of the variable, or null if that name isn't assigned

    - #### get

          public <T> T get(String name,
                  Class<T> javaclass)

      Returns the value of a variable in the local namespace. The value will be returned as an instance of the given Java class. `interp.get("foo", Object.class)` will return the most appropriate generic Java object.
      Parameters:
        `name` - the name of the variable
        `javaclass` - the class of object to return
      Returns:
        the value of the variable as the given class, or null if that name isn't assigned

    - #### cleanup

          public void cleanup()

    - #### close

          public void close()

      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`

Jython homepage