org.jpy

## Class PyLib

- java.lang.Object
- - org.jpy.PyLib

-     public class PyLib
      extends Object

  Represents the library that provides the Python interpreter (CPython).

  When the `PyLib` class is loaded, it reads its configuration from a Java properties file called `.jpy` which must exist in the current user's home directory. The configuration file has been written to this location by installing the Python jpy module using `python3 setup.py install --user` on Unix and `python setup.py install`) on Windows.

  Currently, the following properties are recognised in the `.jpy` file:

  - `python.lib` - the Python shared library (usually required on Unix only)
  - `jpy.lib` - the jpy shared library path for Python (Unix: `jpy*.so`, Windows: `jpy*.pyd`)

  jpy API clients should first call `isPythonRunning()` in order to check if a Python interpreter is already available. If not, `startPython(String...)` must be called before any other jpy API is used.

  Important note for developers: If you change the signature of any of the native `PyLib` methods, you must first run `javah` on the compiled class, and then adapt `src/main/c/jni/org_jpy_PyLib.c`.

  Since:
    0.7

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `PyLib.CallableKind` The kind of callable Python objects.
    `static class` | `PyLib.Diag` Controls output of diagnostic information for debugging.

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `assertPythonRuns()` Throws a runtime exception if Python interpreter is not running.
    `static <T> T` | `ensureGil(java.util.function.Supplier<T> runnable)`
    `static int` | `execScript(String script)` Deprecated.
    `static PyObject` | `getCurrentGlobals()` Return a dictionary of the global variables in the current execution frame, or NULL if no frame is currently executing.
    `static PyObject` | `getCurrentLocals()` Return a dictionary of the local variables in the current execution frame, or NULL if no frame is currently executing.
    `static String` | `getDllFilePath()`
    `static PyObject` | `getMainGlobals()`
    `static String` | `getPythonVersion()`
    `static boolean` | `hasGil()`
    `static boolean` | `isPythonRunning()`
    `static boolean` | `setProgramName(String programName)` Useful for virtual environments, helps in setting sys.prefix/exec_prefix.
    `static boolean` | `setPythonHome(String pythonHome)` Does the equivalent of setting the PYTHONHOME environment variable.
    `static void` | `startPython(int flags, String... extraPaths)` Starts the Python interpreter.
    `static void` | `startPython(String... extraPaths)` Delegates to `startPython(int, String...)` with `flags = Diag.F_OFF`.
    `static void` | `stopPython()` Stops the Python interpreter.

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

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

- - ### Method Detail

    - #### getDllFilePath

          public static String getDllFilePath()

    - #### assertPythonRuns

          public static void assertPythonRuns()

      Throws a runtime exception if Python interpreter is not running. Possible reasons for this are
      - You have not called `startPython(String...)` yet.
      - The Python shared library code for the Python interpreter could not be found or could not be be loaded.
      - The Python shared library code for the Python 'jpy' module could not be found or could not be be loaded.
      - The Python interpreter could not be initialised.

    - #### isPythonRunning

          public static boolean isPythonRunning()

      Returns:
        `true` if the Python interpreter is running and the the 'jpy' module has been loaded.

    - #### startPython

          public static void startPython(String... extraPaths)

      Delegates to `startPython(int, String...)` with `flags = Diag.F_OFF`.

    - #### startPython

          public static void startPython(int flags,
                                         String... extraPaths)

      Starts the Python interpreter. It does the following:
      1. Initializes the Python interpreter, if not already running.
      2. Prepends any given extra paths to Python's 'sys.path' (e.g. so that 'jpy' can be loaded from isolated directories).
      3. Imports the 'jpy' extension module, if not already done.
      Parameters:
        `flags` - If non-zero, is passed to `PyLib.Diag.setFlags(int)` before python is started
        `extraPaths` - List of paths that will be prepended to Python's 'sys.path'.
      Throws:
        `RuntimeException` - if Python could not be started or if the 'jpy' extension module could not be loaded.

    - #### setPythonHome

          public static boolean setPythonHome(String pythonHome)

      Does the equivalent of setting the PYTHONHOME environment variable. If used, this must be called prior to calling `startPython()`. Supported for Python 2.7, and Python 3.5 or higher
      Parameters:
        `pythonHome` - Path to Python Home (must be less than 256 characters!)
      Returns:
        true if successful, false if it fails

    - #### setProgramName

          public static boolean setProgramName(String programName)

      Useful for virtual environments, helps in setting sys.prefix/exec_prefix. If used, this must be called prior to calling `startPython()`.
      Parameters:
        `programName` - Path to Python executable (must be less than 256 characters!)
      Returns:
        true if successful, false if it fails
      See Also:
        Py_SetProgramName (2), Py_SetProgramName (3)

    - #### getPythonVersion

          public static String getPythonVersion()

      Returns:
        The Python interpreter version string.

    - #### stopPython

          public static void stopPython()

      Stops the Python interpreter. Important note: Stopping the Python interpreter again after it has been restarted using `startPython(java.lang.String...)` currently causes a fatal error in the the Java Runtime Environment originating from the Python interpreter (function `Py_Finalize` in standard CPython implementation). There is currently no workaround for that problem other than not restarting the Python interpreter from your code. For more information refer to https://github.com/bcdev/jpy/issues/70

    - #### execScript

          @Deprecated
          public static int execScript(String script)

      Deprecated.

    - #### getMainGlobals

          public static PyObject getMainGlobals()

    - #### getCurrentGlobals

          public static PyObject getCurrentGlobals()

      Return a dictionary of the global variables in the current execution frame, or NULL if no frame is currently executing.
      Returns:
        the current globals, or null
      See Also:
        PyEval_GetGlobals (2), PyEval_GetGlobals (3)

    - #### getCurrentLocals

          public static PyObject getCurrentLocals()

      Return a dictionary of the local variables in the current execution frame, or NULL if no frame is currently executing.
      Returns:
        the current locals, or null
      See Also:
        PyEval_GetLocals (2), PyEval_GetLocals (3)

    - #### hasGil

          public static boolean hasGil()

    - #### ensureGil

          public static <T> T ensureGil(java.util.function.Supplier<T> runnable)

Copyright © 2014–2022 Brockmann Consult GmbH. All rights reserved.