Class PythonConversion

java.lang.Object
io.micronaut.context.python.PythonConversion
@Internal public final class PythonConversion extends Object
Conversion of Python values to Java: none checks, scalars, collections, optionals, enums and the generated wrapper types.

Maintainer notes. The public methods are called by generated bridge code (see PythonStubGenerator) on every value that crosses from Python to Java, so they sit on the hot path: keep them free of meta-object lookups and string formatting. The package-private methods are the per-type converters PythonCoercion and convertValue(Value, Class) dispatch to. Every converter follows the same rules: None converts to null (or an empty Optional), a value that is already a host object of the target type is returned as is, a generated wrapper (ValueCoercible) is unwrapped rather than copied, and a conversion that cannot be done is an exception, never an empty result, so a bad element does not silently shrink a collection.

Since:
5.2.0

  • 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 <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 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 String
    enumStringValue(@Nullable org.graalvm.polyglot.Value value)
    Convert a Python enum value to the string representation exposed by Python.
    static boolean
    isNone(@Nullable org.graalvm.polyglot.Value value)
    Returns whether the value represents Java null or Python None.
    static <T> @Nullable T
    subclassWrapper(@Nullable org.graalvm.polyglot.Value value, Class<T> declaredType)
    The wrapper of a Python object for the generated subclass it is an instance of, when the object's own class is a generated subclass of the declared wrapper type: a Python subclass instance passed or returned as its Python base type then keeps its runtime type, and with it its introspection.
    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

  • Method Details

    • isNone

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

      Python None is an interop null, so Value.isNull() is the complete check. This method is on the hot path of every bridge call and conversion, so it must not touch the meta object or the string representation of the value.

      Parameters:
      value - The polyglot value
      Returns:
      Whether the value represents Java null or Python None

    • subclassWrapper

      public static <T> @Nullable T subclassWrapper(@Nullable org.graalvm.polyglot.Value value, Class<T> declaredType)
      The wrapper of a Python object for the generated subclass it is an instance of, when the object's own class is a generated subclass of the declared wrapper type: a Python subclass instance passed or returned as its Python base type then keeps its runtime type, and with it its introspection. Returns null when the object is of the declared type itself, of a class with no generated wrapper, or not a Python object at all, in which case the caller wraps it as the declared type.

      The lookup reads the module and qualified name of the object's class; the resolved factory is cached per declared type and Python class.

      Type Parameters:
      T - The declared wrapper type
      Parameters:
      value - The Python object
      declaredType - The declared wrapper type
      Returns:
      The wrapper of the object's own generated class, or null

    • 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.

      The attempts run in this order, and the order matters: a host object that is a ValueCoercible proxy is unwrapped first (a generated wrapper that went through Python must come back as the same Java object, not a copy); a host object of the target type is returned as is; a Java enum target is resolved from the Python enum's name or value; a mapped wrapper type (TargetTypeMapping) is resolved through the wrapper registry; and only then does Value.as(Class) run, which handles primitives, strings and the collection types by GraalPy's own rules.

      Type Parameters:
      T - The target type
      Parameters:
      value - The source polyglot value
      targetType - The target Java type
      Returns:
      The converted value or null

    • 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