PythonInterpreter (Jython API documentation)
Date: 2024-08-18

org.python.util

## Class PythonInterpreter

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

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable
  Direct Known Subclasses:
    InteractiveInterpreter

      public class PythonInterpreter
      extends java.lang.Object
      implements java.lang.AutoCloseable, java.io.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

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `cleanup()`
    `void` | `close()`
    `PyCode` | `compile(java.io.Reader reader)`
    `PyCode` | `compile(java.io.Reader reader, java.lang.String filename)`
    `PyCode` | `compile(java.lang.String script)` Compiles a string of Python source as either an expression (if possible) or a module.
    `PyCode` | `compile(java.lang.String script, java.lang.String filename)`
    `PyObject` | `eval(PyObject code)` Evaluates a Python code object and returns the result.
    `PyObject` | `eval(java.lang.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(java.lang.String s)` Executes a string of Python source in the local namespace.
    `void` | `execfile(java.io.InputStream s)`
    `void` | `execfile(java.io.InputStream s, java.lang.String name)`
    `void` | `execfile(java.lang.String filename)` Executes a file of Python source in the local namespace.
    `PyObject` | `get(java.lang.String name)` Returns the value of a variable in the local namespace.
    `<T> T` | `get(java.lang.String name, java.lang.Class<T> javaclass)` Returns the value of a variable in the local namespace.
    `PyObject` | `getLocals()`
    `PySystemState` | `getSystemState()`
    `static void` | `initialize(java.util.Properties preProperties, java.util.Properties postProperties, java.lang.String[] argv)` Initializes the Jython runtime.
    `void` | `set(java.lang.String name, java.lang.Object value)` Sets a variable in the local namespace.
    `void` | `set(java.lang.String name, PyObject value)` Sets a variable in the local namespace.
    `void` | `setErr(java.io.OutputStream outStream)`
    `void` | `setErr(PyObject outStream)` Sets a Python object to use for the standard output stream, `sys.stderr`.
    `void` | `setErr(java.io.Writer outStream)` Sets a `Writer` to use for the standard output stream, `sys.stdout`.
    `void` | `setIn(java.io.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(java.io.Reader inStream)` Sets a `Reader` to use for the standard input stream, `sys.stdin`.
    `void` | `setLocals(PyObject d)`
    `void` | `setOut(java.io.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(java.io.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(java.util.Properties preProperties,
                                        java.util.Properties postProperties,
                                        java.lang.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(java.io.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(java.io.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:

      Stream behaviour for various object types
      | 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(java.io.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(java.io.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(java.io.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(java.io.OutputStream outStream)

    - #### eval

          public PyObject eval(java.lang.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(java.lang.String s)

      Executes a string of Python source in the local namespace. In some environments, such as Windows, Unicode characters in the script will be converted into ascii question marks (?). This can be avoided by first compiling the fragment using PythonInterpreter.compile(), and using the overridden form of this method which takes a PyCode object. Code page declarations are not supported.

    - #### exec

          public void exec(PyObject code)

      Executes a Python code object in the local namespace.

    - #### execfile

          public void execfile(java.lang.String filename)

      Executes a file of Python source in the local namespace.

    - #### execfile

          public void execfile(java.io.InputStream s)

    - #### execfile

          public void execfile(java.io.InputStream s,
                               java.lang.String name)

    - #### compile

          public PyCode compile(java.lang.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(java.io.Reader reader)

    - #### compile

          public PyCode compile(java.lang.String script,
                                java.lang.String filename)

    - #### compile

          public PyCode compile(java.io.Reader reader,
                                java.lang.String filename)

    - #### getLocals

          public PyObject getLocals()

    - #### setLocals

          public void setLocals(PyObject d)

    - #### set

          public void set(java.lang.String name,
                          java.lang.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(java.lang.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(java.lang.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(java.lang.String name,
                           java.lang.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 `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`

Jython homepage