Class GraalPyRuntimeUtil

java.lang.Object
io.micronaut.context.python.GraalPyRuntimeUtil
@Internal public final class GraalPyRuntimeUtil extends Object
Runtime utility class for converting GraalPy Values to Java collections. Provides type-safe conversion methods for List, Map, and other collection types.
Since:
5.2.0
Author:
Micronaut Team

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    GraalPyRuntimeUtil.AsyncMemberAdapter
    Adapter invoked from Python async member facades.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    PYTHON
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    GraalPyRuntimeUtil()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> @Nullable T
    asObject(@Nullable Object value)
    Return a value as Object so generated code can perform unchecked generic casts.
    static @Nullable Object
    asyncMemberValue(org.graalvm.polyglot.Value target, @Nullable Object value)
    Convert an injected Java member into a Python-context-local value suitable for async code.
    static org.graalvm.polyglot.Value
    bindPythonDescriptor(org.graalvm.polyglot.Value descriptor, Object receiver, org.graalvm.polyglot.Value owner)
    Bind a raw Python descriptor to a receiver when the descriptor protocol is available.
    static Object[]
    coerceArgumentsToContext(org.graalvm.polyglot.Context context, Object[] args)
    Coerce arguments passed into a target Python context.
    static <E> @Nullable List<Object>
    coerceList(@Nullable List<E> list)
    Coerce a list of types that may extend from ValueCoercible back to a native value list.
    static <V> @Nullable Map<String,Object>
    coerceMap(@Nullable Map<String,V> map)
    Coerce a map of types that may extend from ValueCoercible back to a native value map.
    static @Nullable Object
    coerceToContext(@Nullable Object value, org.graalvm.polyglot.Context context)
    Coerce values passed into a target Python context.
    static @Nullable Object
    coerceToContext(@Nullable Object value, org.graalvm.polyglot.Context context, Class<?> declaredType)
    Coerce a value using the generated Java bridge's declared parameter type.
    static @Nullable Object
    coerceValue(@Nullable Object value)
    Coerce a generated Python-backed Java wrapper back to its native Python value.
    static <T> HttpResponse<T>
    convertHttpResponse(HttpResponse<?> response, Class<T> bodyType)
    Convert a response body to the declared Java body type.
    static <T> HttpResponse<T>
    convertHttpResponse(org.graalvm.polyglot.Value value, Class<T> bodyType)
    Convert a GraalPy-created HttpResponse and its response body to the declared Java body type.
    static <T> @Nullable List<T>
    convertList(@Nullable List<?> list, PolyglotValueConverter<T> converter)
    Convert a Java list that may contain GraalPy values using a generated element converter.
    static <T> @Nullable List<T>
    convertList(org.graalvm.polyglot.Value graalValue, PolyglotValueConverter<T> converter)
    Convert a GraalPy Value representing a list using a generated element converter.
    static <T> @Nullable List<T>
    convertList(org.graalvm.polyglot.Value graalValue, Class<T> elementType)
    Convert a GraalPy Value representing a list to a Java List.
    static <K,V> @Nullable Map<K,V>
    convertMap(org.graalvm.polyglot.Value graalValue, Class<K> keyType, Class<V> valueType)
    Convert a GraalPy Value representing a dict to a Java Map.
    static @Nullable Object
    convertObject(@Nullable org.graalvm.polyglot.Value value)
    Convert a GraalPy value to a general Java object while preserving host objects.
    static <T> Optional<T>
    convertOptional(org.graalvm.polyglot.Value graalValue, Class<T> elementType)
    Convert a GraalPy Value representing an Optional to a Java Optional.
    static <T> @Nullable Publisher<T>
    convertPublisher(org.graalvm.polyglot.Value value, Class<T> itemType)
    Convert a GraalPy Value representing a publisher to a typed Java publisher.
    static <T> Publisher<T>
    convertPublisher(Publisher<?> publisher, Class<T> itemType)
    Convert each item emitted by a Python-returned publisher to the declared Java item type.
    static <T> @Nullable Set<T>
    convertSet(org.graalvm.polyglot.Value graalValue, Class<T> elementType)
    Convert a GraalPy Value representing a set to a Java Set.
    static <T> @Nullable T
    convertValue(org.graalvm.polyglot.Value value, Class<T> targetType)
    Generic value conversion method that handles primitives and recursively converts collections.
    static void
    copyTransferableMembers(@Nullable org.graalvm.polyglot.Value source, @Nullable org.graalvm.polyglot.Value target)
    Copy simple and host-backed Python instance members into another context.
    static String
    enumStringValue(@Nullable org.graalvm.polyglot.Value value)
    Convert a Python enum value to the string representation exposed by Python.
    static @Nullable org.graalvm.polyglot.Value
    getRawClassMember(org.graalvm.polyglot.Value pythonClass, String name)
    Read a Python class member directly from the MRO dictionaries, bypassing descriptor binding.
    static org.graalvm.polyglot.Value
    invokePythonMethod(org.graalvm.polyglot.Value receiver, String name, Object[] arguments)
    Invoke a generated bridge method on a Python receiver.
    static boolean
    isNone(@Nullable org.graalvm.polyglot.Value value)
    Returns whether the value represents Java null or Python None.
    static void
    putMember(org.graalvm.polyglot.Value target, String name, @Nullable Object value)
    Assign a member on a Python value after coercing the value into the same context.
    static @Nullable Object
    unwrapHostObject(@Nullable org.graalvm.polyglot.Value value, Class<?> targetType)
    Unwraps a generated Python wrapper that crossed a polyglot boundary as a host or proxy object.

    Methods inherited from class Object

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

  • Field Details

  • Constructor Details

    • GraalPyRuntimeUtil

      public GraalPyRuntimeUtil()

  • Method Details

    • isNone

      public static boolean isNone(@Nullable org.graalvm.polyglot.Value value)
      Returns whether the value represents Java null or Python None.
      Parameters:
      value - The polyglot value
      Returns:
      Whether the value represents Java null or Python None

    • coerceMap

      public static <V> @Nullable Map<String,Object> coerceMap(@Nullable Map<String,V> map)
      Coerce a map of types that may extend from ValueCoercible back to a native value map.
      Type Parameters:
      V - The value type of the map
      Parameters:
      map - The map
      Returns:
      The resulting map

    • coerceList

      public static <E> @Nullable List<Object> coerceList(@Nullable List<E> list)
      Coerce a list of types that may extend from ValueCoercible back to a native value list.
      Type Parameters:
      E - The element type of the list
      Parameters:
      list - The list
      Returns:
      The resulting list

    • coerceValue

      public static @Nullable Object coerceValue(@Nullable Object value)
      Coerce a generated Python-backed Java wrapper back to its native Python value.
      Parameters:
      value - The value
      Returns:
      The native Python value when available

    • coerceToContext

      public static @Nullable Object coerceToContext(@Nullable Object value, org.graalvm.polyglot.Context context)
      Coerce values passed into a target Python context.
      Parameters:
      value - The value to coerce
      context - The target context
      Returns:
      The coerced value

    • coerceToContext

      public static @Nullable Object coerceToContext(@Nullable Object value, org.graalvm.polyglot.Context context, Class<?> declaredType)
      Coerce a value using the generated Java bridge's declared parameter type. Some host objects implement collection interfaces as an implementation detail and should stay host objects unless the Python method declares the plain collection contract.
      Parameters:
      value - The value to coerce
      context - The target context
      declaredType - The declared Java bridge parameter type
      Returns:
      The coerced value

    • coerceArgumentsToContext

      public static Object[] coerceArgumentsToContext(org.graalvm.polyglot.Context context, Object[] args)
      Coerce arguments passed into a target Python context.
      Parameters:
      context - The target context
      args - The arguments
      Returns:
      The coerced arguments

    • putMember

      public static void putMember(org.graalvm.polyglot.Value target, String name, @Nullable Object value)
      Assign a member on a Python value after coercing the value into the same context.
      Parameters:
      target - The Python object to update
      name - The member name
      value - The member value

    • asyncMemberValue

      public static @Nullable Object asyncMemberValue(org.graalvm.polyglot.Value target, @Nullable Object value)
      Convert an injected Java member into a Python-context-local value suitable for async code.
      Parameters:
      target - The target Python object receiving the member.
      value - The Java value to expose.
      Returns:
      A value that adapts Java async method results to Python awaitables.

    • copyTransferableMembers

      public static void copyTransferableMembers(@Nullable org.graalvm.polyglot.Value source, @Nullable org.graalvm.polyglot.Value target)
      Copy simple and host-backed Python instance members into another context.
      Parameters:
      source - The source Python object.
      target - The target Python object.

    • invokePythonMethod

      public static org.graalvm.polyglot.Value invokePythonMethod(org.graalvm.polyglot.Value receiver, String name, Object[] arguments)
      Invoke a generated bridge method on a Python receiver.

      Generated Java stubs use this method instead of calling Value.invokeMember(String, Object...) directly so every Python call enters the PythonContextRuntime execution tracker for the receiver's actual context. The execution frame keeps graceful shutdown and pooled-context cleanup from observing the context as idle while a bridge invocation, or nested bridge invocation, is still unwinding.

      Invocation is delegated to a context-local Python helper because Python method lookup is not just a map lookup. The helper first uses getattr for normal bound-method behavior, then falls back to walking the class __mro__ and applying __get__ so descriptors and inherited methods are invoked with Python semantics before the result crosses back to Java.

      Parameters:
      receiver - The Python receiver
      name - The method name
      arguments - The method arguments
      Returns:
      The invocation result

    • getRawClassMember

      public static @Nullable org.graalvm.polyglot.Value getRawClassMember(org.graalvm.polyglot.Value pythonClass, String name)
      Read a Python class member directly from the MRO dictionaries, bypassing descriptor binding.
      Parameters:
      pythonClass - The Python class
      name - The member name
      Returns:
      The raw member, or null if none exists

    • bindPythonDescriptor

      public static org.graalvm.polyglot.Value bindPythonDescriptor(org.graalvm.polyglot.Value descriptor, Object receiver, org.graalvm.polyglot.Value owner)
      Bind a raw Python descriptor to a receiver when the descriptor protocol is available.
      Parameters:
      descriptor - The raw descriptor
      receiver - The receiver object
      owner - The owner class
      Returns:
      The bound descriptor, or the original descriptor if it cannot be bound

    • asObject

      public static <T> @Nullable T asObject(@Nullable Object value)
      Return a value as Object so generated code can perform unchecked generic casts.
      Type Parameters:
      T - The target object type
      Parameters:
      value - The value
      Returns:
      The value as an object

    • convertObject

      public static @Nullable Object convertObject(@Nullable org.graalvm.polyglot.Value value)
      Convert a GraalPy value to a general Java object while preserving host objects.
      Parameters:
      value - The source polyglot value
      Returns:
      The converted object

    • unwrapHostObject

      public static @Nullable Object unwrapHostObject(@Nullable org.graalvm.polyglot.Value value, Class<?> targetType)
      Unwraps a generated Python wrapper that crossed a polyglot boundary as a host or proxy object.
      Parameters:
      value - The source polyglot value
      targetType - The expected Java wrapper type
      Returns:
      The existing host wrapper, or null when the value is not one

    • convertList

      public static <T> @Nullable List<T> convertList(org.graalvm.polyglot.Value graalValue, Class<T> elementType)
      Convert a GraalPy Value representing a list to a Java List. Recursively converts nested collections.
      Type Parameters:
      T - the expected list element type
      Parameters:
      graalValue - the GraalPy Value (should be a list-like object)
      elementType - the expected element type for conversion
      Returns:
      a Java List with converted elements

    • convertList

      public static <T> @Nullable List<T> convertList(org.graalvm.polyglot.Value graalValue, PolyglotValueConverter<T> converter)
      Convert a GraalPy Value representing a list using a generated element converter.
      Type Parameters:
      T - the expected list element type
      Parameters:
      graalValue - the GraalPy Value (should be a list-like object)
      converter - the converter to apply to each element
      Returns:
      a Java List with converted elements

    • convertList

      public static <T> @Nullable List<T> convertList(@Nullable List<?> list, PolyglotValueConverter<T> converter)
      Convert a Java list that may contain GraalPy values using a generated element converter.
      Type Parameters:
      T - the expected list element type
      Parameters:
      list - the source list
      converter - the converter to apply to GraalPy elements
      Returns:
      a Java List with converted elements

    • convertMap

      public static <K,V> @Nullable Map<K,V> convertMap(org.graalvm.polyglot.Value graalValue, Class<K> keyType, Class<V> valueType)
      Convert a GraalPy Value representing a dict to a Java Map. Recursively converts nested collections.
      Type Parameters:
      K - the expected key type
      V - the expected value type
      Parameters:
      graalValue - the GraalPy Value (should be a dict-like object)
      keyType - the expected key type for conversion
      valueType - the expected value type for conversion
      Returns:
      a Java Map with converted keys and values

    • convertOptional

      public static <T> Optional<T> convertOptional(org.graalvm.polyglot.Value graalValue, Class<T> elementType)
      Convert a GraalPy Value representing an Optional to a Java Optional. Handles None -> Optional.empty() and value -> Optional.of(value)
      Type Parameters:
      T - the expected optional element type
      Parameters:
      graalValue - the GraalPy Value to convert
      elementType - the expected element type for conversion
      Returns:
      a Java Optional with the converted value or empty

    • convertSet

      public static <T> @Nullable Set<T> convertSet(org.graalvm.polyglot.Value graalValue, Class<T> elementType)
      Convert a GraalPy Value representing a set to a Java Set. Recursively converts nested collections.
      Type Parameters:
      T - the expected set element type
      Parameters:
      graalValue - the GraalPy Value (should be a set-like object)
      elementType - the expected element type for conversion
      Returns:
      a Java Set with converted elements

    • convertValue

      public static <T> @Nullable T convertValue(org.graalvm.polyglot.Value value, Class<T> targetType)
      Generic value conversion method that handles primitives and recursively converts collections.
      Type Parameters:
      T - The target type
      Parameters:
      value - The source polyglot value
      targetType - The target Java type
      Returns:
      The converted value or null

    • convertHttpResponse

      public static <T> HttpResponse<T> convertHttpResponse(org.graalvm.polyglot.Value value, Class<T> bodyType)
      Convert a GraalPy-created HttpResponse and its response body to the declared Java body type.
      Type Parameters:
      T - The response body type
      Parameters:
      value - The source polyglot response
      bodyType - The declared response body type
      Returns:
      The converted response

    • convertPublisher

      public static <T> Publisher<T> convertPublisher(Publisher<?> publisher, Class<T> itemType)
      Convert each item emitted by a Python-returned publisher to the declared Java item type.
      Type Parameters:
      T - The item type
      Parameters:
      publisher - The source publisher
      itemType - The declared publisher item type
      Returns:
      The converted publisher

    • convertPublisher

      public static <T> @Nullable Publisher<T> convertPublisher(org.graalvm.polyglot.Value value, Class<T> itemType)
      Convert a GraalPy Value representing a publisher to a typed Java publisher.
      Type Parameters:
      T - The item type
      Parameters:
      value - The source polyglot publisher
      itemType - The declared publisher item type
      Returns:
      The converted publisher

    • convertHttpResponse

      public static <T> HttpResponse<T> convertHttpResponse(HttpResponse<?> response, Class<T> bodyType)
      Convert a response body to the declared Java body type.
      Type Parameters:
      T - The response body type
      Parameters:
      response - The source response
      bodyType - The declared response body type
      Returns:
      The converted response

    • enumStringValue

      public static String enumStringValue(@Nullable org.graalvm.polyglot.Value value)
      Convert a Python enum value to the string representation exposed by Python.
      Parameters:
      value - The Python enum value
      Returns:
      The enum string value