Class PythonContextRuntime

java.lang.Object
io.micronaut.context.python.PythonContextRuntime
public final class PythonContextRuntime extends Object
Runtime coordination point for generated Python bridge classes.

This type owns access to the primary GraalPy context, resolves classes and scripts from the primary context or a PythonPool, mirrors host members into event-loop contexts, executes shared Python helper functions, and tracks active executions so contexts and engines can be closed safely.

Since:
5.2.0
Author:
Micronaut Team

  • Method Details

    • asyncInstance

      public static org.graalvm.polyglot.Value asyncInstance(org.graalvm.polyglot.Value fallback, PythonContextRuntime.PythonClassReference classReference)
      Resolve a Python instance for the current asyncio event loop when one is active.
      Parameters:
      fallback - The startup-context instance
      classReference - The Python class reference
      Returns:
      An event-loop-local instance, or the fallback when no event-loop context is active
      Since:
      5.2.0

    • rememberAsyncMember

      public static void rememberAsyncMember(org.graalvm.polyglot.Value source, String name, @Nullable Object value)
      Remember a host-side member assigned to a Python object so async event-loop contexts can mirror it.
      Parameters:
      source - The startup-context Python object.
      name - The member name.
      value - The host value.

    • findPooledClass

      public static org.graalvm.polyglot.Value findPooledClass(PythonContextRuntime.PythonClassReference classReference)
      Obtain a pooled Python class instance (per-context cached).
      Parameters:
      classReference - The Python class reference
      Returns:
      The pooled class instance (Value) from some context
      Since:
      5.2.0

    • findPooledClass

      public static org.graalvm.polyglot.Value findPooledClass(PythonContextRuntime.PythonClassReference classReference, org.graalvm.polyglot.Context context)
      Obtain a pooled Python class instance from a specific context.
      Parameters:
      classReference - The Python class reference
      context - The context
      Returns:
      The pooled class instance (Value)
      Since:
      5.2.0

    • withPooled

      public static <T> T withPooled(PythonContextRuntime.PythonClassReference classReference, Function<org.graalvm.polyglot.Value, T> fn)
      Execute a function with a borrowed pooled class instance.
      Type Parameters:
      T - Result type returned by the function
      Parameters:
      classReference - The Python class reference
      fn - Function receiving the pooled Value
      Returns:
      Result returned from the function
      Since:
      5.2.0

    • findPooledScript

      public static org.graalvm.polyglot.Value findPooledScript(String packageName, String scriptName)
      Obtain a pooled Python script/module object.
      Parameters:
      packageName - The Python package
      scriptName - The script/module name
      Returns:
      A pooled script Value

    • findPooledScript

      public static org.graalvm.polyglot.Value findPooledScript(String packageName, String scriptName, org.graalvm.polyglot.Context context)
      Obtain a pooled Python script/module object from a specific context.
      Parameters:
      packageName - The Python package
      scriptName - The script/module name
      context - The context
      Returns:
      A pooled script Value

    • withPooledScript

      public static <T> T withPooledScript(String packageName, String scriptName, Function<org.graalvm.polyglot.Value, T> fn)
      Execute a function with a borrowed pooled script/module object.
      Type Parameters:
      T - Result type returned by the function
      Parameters:
      packageName - The package
      scriptName - The script name
      fn - Function receiving the script Value
      Returns:
      Result returned from the function

    • withPooledValue

      public static PooledValue withPooledValue(String expression)
      Create a wrapper for a Python value that is evaluated and cached in each pooled context.
      Parameters:
      expression - The Python expression or statements to evaluate
      Returns:
      A pooled value wrapper
      Since:
      5.2.0

    • withPooledValue

      public static <T> T withPooledValue(String expression, Function<org.graalvm.polyglot.Value, T> fn)
      Execute a callback with a Python value evaluated and cached in a borrowed pooled context.
      Type Parameters:
      T - Result type returned by the function
      Parameters:
      expression - The Python expression or statements to evaluate
      fn - Function receiving the pooled value
      Returns:
      Result returned from the function
      Since:
      5.2.0

    • injectPooledScript

      public static void injectPooledScript(String packageName, String scriptName, String attribute, Object value)
      Inject an attribute into all pooled script contexts.
      Parameters:
      packageName - The package
      scriptName - The script name
      attribute - The attribute name
      value - The value to inject

    • injectPooledScriptAsync

      public static void injectPooledScriptAsync(String packageName, String scriptName, String attribute, Object value)
      Inject an async-adapted attribute into all pooled script contexts.
      Parameters:
      packageName - The package
      scriptName - The script name
      attribute - The attribute name
      value - The value to inject

    • invokePooled

      public static org.graalvm.polyglot.Value invokePooled(PythonContextRuntime.PythonClassReference classReference, String methodName, Object... args)
      Invoke a method on a pooled class instance.
      Parameters:
      classReference - The Python class reference
      methodName - The method name
      args - Arguments
      Returns:
      The polyglot result
      Since:
      5.2.0

    • invokePooledScript

      public static org.graalvm.polyglot.Value invokePooledScript(String packageName, String scriptName, String methodName, Object... args)
      Invoke a method on a pooled script instance.
      Parameters:
      packageName - The package
      scriptName - The script name
      methodName - The method name
      args - Arguments
      Returns:
      The polyglot result

    • getContext

      public static org.graalvm.polyglot.Context getContext()

    • newIntroduction

      public static org.graalvm.polyglot.Value newIntroduction(PythonContextRuntime.PythonClassReference classReference, Object... args)
      Create an instance that is abstract and fill out the abstract methods with stubs to be later populated.
      Parameters:
      classReference - The Python class reference
      args - The args
      Returns:
      The new instance
      Since:
      5.2.0

    • newIntroductionWithDefaultedTrailingNulls

      public static org.graalvm.polyglot.Value newIntroductionWithDefaultedTrailingNulls(PythonContextRuntime.PythonClassReference classReference, int requiredArgCount, Object... args)
      Create a new abstract introduction instance, omitting trailing null arguments that correspond to Python constructor defaults.
      Parameters:
      classReference - The Python class reference
      requiredArgCount - The number of non-defaulted positional constructor arguments
      args - The arguments
      Returns:
      The new instance
      Since:
      5.2.0

    • newInstance

      public static org.graalvm.polyglot.Value newInstance(PythonContextRuntime.PythonClassReference classReference, Object... args)
      Create a new instance for the given class reference and args.
      Parameters:
      classReference - The Python class reference
      args - The args
      Returns:
      The new instance
      Since:
      5.2.0

    • enumValue

      public static org.graalvm.polyglot.Value enumValue(PythonContextRuntime.PythonClassReference classReference, String name)
      Resolve a Python enum constant by its Java enum name.
      Parameters:
      classReference - The Python class reference
      name - The enum constant name
      Returns:
      The Python enum constant
      Since:
      5.2.0

    • newInstanceWithDefaultedTrailingNulls

      public static org.graalvm.polyglot.Value newInstanceWithDefaultedTrailingNulls(PythonContextRuntime.PythonClassReference classReference, int requiredArgCount, Object... args)
      Create a new instance, omitting trailing null arguments that correspond to Python constructor defaults.
      Parameters:
      classReference - The Python class reference
      requiredArgCount - The number of non-defaulted positional constructor arguments
      args - The arguments
      Returns:
      The new instance
      Since:
      5.2.0

    • newUninitializedInstance

      public static org.graalvm.polyglot.Value newUninitializedInstance(PythonContextRuntime.PythonClassReference classReference)
      Create a Python instance without invoking __init__.
      Parameters:
      classReference - The Python class reference
      Returns:
      The new uninitialized instance
      Since:
      5.2.0

    • newInstance

      public static org.graalvm.polyglot.Value newInstance(PythonContextRuntime.PythonClassReference classReference, Map<String,Object> props)
      Create a new instance and set properties via member assignment when no constructor exists.
      Parameters:
      classReference - The Python class reference
      props - Map of property names to values
      Returns:
      The new instance with members populated
      Since:
      5.2.0

    • newFrozenDataclassInstance

      public static org.graalvm.polyglot.Value newFrozenDataclassInstance(PythonContextRuntime.PythonClassReference classReference, Map<String,Object> props)
      Create a new frozen dataclass instance and set properties without invoking __init__.
      Parameters:
      classReference - The Python class reference
      props - Map of property names to values
      Returns:
      The new frozen dataclass instance with members populated
      Since:
      5.2.0

    • findClass

      public static org.graalvm.polyglot.Value findClass(PythonContextRuntime.PythonClassReference classReference)
      Find a Python class by pre-split class reference.
      Parameters:
      classReference - The Python class reference
      Returns:
      The class Value
      Since:
      5.2.0

    • findScript

      public static org.graalvm.polyglot.Value findScript(String packageName, String scriptName)
      Find a Python script/module Value.
      Parameters:
      packageName - The package name (or python for top-level)
      scriptName - The script/module name
      Returns:
      The module Value

    • invokeStaticMethod

      public static org.graalvm.polyglot.Value invokeStaticMethod(PythonContextRuntime.PythonClassReference classReference, String methodName, Object... args)
      Invoke a static method on the given Python class.
      Parameters:
      classReference - The Python class reference
      methodName - The method name
      args - The method arguments
      Returns:
      The method result
      Since:
      5.2.0

    • setContext

      public static void setContext(org.graalvm.polyglot.Context context)
      Set the GraalPy context. This method is called by GraalPyContextFactory during application startup.
      Parameters:
      context - The GraalPy context to set

    • setContext

      public static void setContext(org.graalvm.polyglot.Context context, @Nullable ClassLoader classLoader)
      Set the GraalPy context and the application class loader that should be active when generated bridge classes enter Python from arbitrary runtime threads.
      Parameters:
      context - The GraalPy context to set
      classLoader - The application class loader used to build the context

    • getContextClassLoader

      public static @Nullable ClassLoader getContextClassLoader()
      Returns the application class loader associated with the current GraalPy context.
      Returns:
      The application class loader

    • isInitialized

      public static boolean isInitialized()
      Check if the context has been initialized.
      Returns:
      true if the context is available, false otherwise

    • resetContext

      public static void resetContext()
      Reset the context to null. This method is called during application shutdown to ensure proper cleanup and prevent memory leaks.

    • setReuseContext

      public static void setReuseContext(boolean reuse)
      If context reuse is set to true, then the context will never be cleared.
      Parameters:
      reuse - tells if the context should be reused

    • isReuseContext

      public static boolean isReuseContext()
      Returns true if the context should be reused.
      Returns:
      the reuse flag