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

org.python.util

## Class jython

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

-     public class jython
      extends java.lang.Object

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `CONSOLE_LOG_FORMAT` The default format for console log messages in the command-line Jython.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `jython()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `loggingToConsole()` Events from within the Jython implementation are surfaced through the `java.util.logging.Logger` `org.python` or a child of it.
    `static void` | `loggingToDefault()` Mostly reverse the effects of `loggingToConsole()`, by removing from the "org.python" logger the handler that prints to the console, and setting the "org.python" logger to propagate records to its parent handlers.
    `static void` | `main(java.lang.String[] args)` Main Jython program, following the structure and logic of CPython `main.c` to produce the same behaviour.
    `static void` | `run(java.lang.String[] args)` Deprecated.
    `static int` | `runJar(java.lang.String filename)` Runs a JAR file, by executing the code found in the file __run__.py, which should be in the root of the JAR archive.

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

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

- - ### Field Detail

    - #### CONSOLE_LOG_FORMAT

          public static final java.lang.String CONSOLE_LOG_FORMAT

      The default format for console log messages in the command-line Jython. See `java.util.logging.SimpleFormatter` for an explanation of the syntax.

      This format is used in the absence of other logging preferences, and only if property `python.logging.default` is not defined. Jython tests for definitions in the system properties of `java.util.logging.config.class`, `java.util.logging.config.file`, and `java.util.logging.SimpleFormatter.format` and if none of these is defined, it sets the last of them to this value.

      You can choose something else, for example to log with millisecond time stamps, launch Jython as:

           jython -vv -J-Djava.util.logging.SimpleFormatter.format="[%1$tT.%1$tL] %3$s: (%4$s) %5$s%n"

      Depending on your shell, the argument may need quoting or escaping.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### jython

          public jython()

  - ### Method Detail

    - #### loggingToConsole

          public static void loggingToConsole()

      Events from within the Jython implementation are surfaced through the `java.util.logging.Logger` `org.python` or a child of it. When Jython is used interactively, we normally want these to emerge on the console, in a succinct form, not via the java.util.logging root logger. This method is called by `main(String[])` to achieve that.

      The root logger format is hard to read for humans. The logging level of the handler defaults to `INFO`, and does not respond to the `-v` option. (It could be made to, but then all logging would be be turned up together.) This method makes these adjustments to logging:

      - The format `SimpleFormatter` is replaced with a simpler format (but only if no other logging customisation is present). (Affects all logging.)
      - A console handler is installed for logger `org.python` using that a `SimpleFormatter` and accepts all levels.
      - Logger `org.python` is told not to propagate records to parent handlers (so that messages are not emitted twice.
      The level of logger `org.python` and its child loggers by default, which determines admission of logging, reflects the "verbosity" set by the `-v` option.

    - #### loggingToDefault

          public static void loggingToDefault()

      Mostly reverse the effects of `loggingToConsole()`, by removing from the "org.python" logger the handler that prints to the console, and setting the "org.python" logger to propagate records to its parent handlers. The method does not try to reset the property `java.util.logging.SimpleFormatter.format`, which is in any case only read during static initialisation by `SimpleFormatter`.

    - #### runJar

          public static int runJar(java.lang.String filename)

      Runs a JAR file, by executing the code found in the file __run__.py, which should be in the root of the JAR archive. Note that `__name__` is set to the base name of the JAR file and not to "__main__" (for historical reasons). This method does not handle exceptions. the caller should handle any `(Py)Exceptions` thrown by the code.
      Parameters:
        `filename` - The path to the filename to run.
      Returns:
        `0` on normal termination (otherwise throws `PyException`).

    - #### run

          @Deprecated
          public static void run(java.lang.String[] args)

      Deprecated.
      Now equivalent to `main(String[])`, which is to be preferred.

    - #### main

          public static void main(java.lang.String[] args)

      Main Jython program, following the structure and logic of CPython `main.c` to produce the same behaviour. The argument to the method is the argument list supplied after the class name in the `java` command. Arguments up to the executable script name are options for Jython; arguments after the executable script are supplied in `sys.argv`. "Executable script" here means a Python source file name, a module name (following the `-m` option), a literal command (following the `-c` option), or a JAR file name (following the `-jar` option). As a special case of the file name, "-" is allowed, meaning take the script from standard input.

      The main difference for the caller stems from a difference between C and Java: in C, the argument list `(argv)` begins with the program name, while in Java all elements of `(args)` are arguments to the program.

      Parameters:
        `args` - arguments to the program.

Jython homepage