Class PythonExceptions

java.lang.Object
io.micronaut.context.python.PythonExceptions
@Internal public final class PythonExceptions extends Object
Support for the Java classes generated for Python exceptions that extend a Java exception class.

At runtime such a Python class is a plain Python exception whose args hold the arguments of its super().__init__(...) call. The generated Java class reads them back through these helpers to call the matching Java super constructor, so the message, the cause and any other state of the Java base class survive the crossing into Java.

Since:
5.2.0

  • Method Summary

    Modifier and Type
    Method
    Description
    static @Nullable org.graalvm.polyglot.Value
    argument(org.graalvm.polyglot.Value exception, int index)
    Positional argument index of the Python exception (exception.args[index]).
    static @Nullable String
    argumentAsString(org.graalvm.polyglot.Value exception, int index)
    Positional argument index of the Python exception as a string: the value itself when it is a string, its str() otherwise, the way a Python exception message reads.
    static @Nullable String
    asString(@Nullable org.graalvm.polyglot.Value value)
    str(value): the value itself when it is a string, its Python str() otherwise.
    static void
    attachCause(Throwable throwable, org.graalvm.polyglot.Value exception)
    Attach the Python cause (raise ... from cause, or the exception being handled when the exception was raised inside an except block) to the generated Java exception when the cause is a Java exception and the Java exception has no cause yet.
    static @Nullable Throwable
    declared(org.graalvm.polyglot.PolyglotException exception, Class<?> generatedClass, Class<?>... declaredTypes)
    The exception a generated bridge method declaring checked exceptions rethrows for the exception of its Python call: a host exception of one of the declared types (raised in Python, or thrown by a Java method the Python code called), or the generated Java exception of a Python exception class extending one of the declared types.
    static boolean
    isTruffleStackTrace(@Nullable Throwable suppressed)
    Whether a suppressed exception is Truffle bookkeeping rather than an exception the application suppressed.
    static @Nullable String
    message(org.graalvm.polyglot.Value exception)
    The message of the Python exception: str(exception) when the exception carries arguments, null otherwise (a Python exception raised without arguments has an empty message, a Java exception a null one).
    static org.graalvm.polyglot.Value
    primitiveArgument(org.graalvm.polyglot.Value exception, int index, String parameterType)
    Positional argument index of the Python exception for a primitive parameter of the Java super constructor, which cannot take a missing or None argument.
    static Throwable[]
    suppressed(Throwable throwable)
    The exceptions the application suppressed on a throwable that crossed Python.

    Methods inherited from class Object

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

  • Method Details

    • isTruffleStackTrace

      public static boolean isTruffleStackTrace(@Nullable Throwable suppressed)
      Whether a suppressed exception is Truffle bookkeeping rather than an exception the application suppressed.

      A Java exception that Python creates and raises is wrapped by Truffle, which shares the guest frames it unwinds through with the host throwable by attaching a TruffleStackTrace.LazyStackTrace to it as a suppressed exception. That entry carries no message and no stack trace of its own, it is not an exception the application suppressed, and a serializer rendering the suppressed exceptions of an error response has nothing to write for it: the problem+json body of a Java problem raised from Python failed with No serializable introspection present for type LazyStackTrace and the client saw a 500.

      Parameters:
      suppressed - A suppressed exception
      Returns:
      true when the entry is Truffle's guest stack trace
      Since:
      5.2.4

    • suppressed

      public static Throwable[] suppressed(Throwable throwable)
      The exceptions the application suppressed on a throwable that crossed Python.

      Throwable.getSuppressed() of a Java exception that crossed Python also reports Truffle's guest stack trace (see isTruffleStackTrace(Throwable)). The entry cannot be taken off the throwable: Throwable.addSuppressed(Throwable) and Throwable.getSuppressed() are final, there is no removal, and the field behind them is in java.base/java.lang, which is not open. This is the view of the suppressed exceptions without it, for code that reports or serializes them; the genuine entries keep their order.

      Parameters:
      throwable - The throwable
      Returns:
      The suppressed exceptions of the application
      Since:
      5.2.4

    • argument

      public static @Nullable org.graalvm.polyglot.Value argument(org.graalvm.polyglot.Value exception, int index)
      Positional argument index of the Python exception (exception.args[index]).
      Parameters:
      exception - The Python exception
      index - The argument index
      Returns:
      The argument, or null when the exception has fewer arguments

    • primitiveArgument

      public static org.graalvm.polyglot.Value primitiveArgument(org.graalvm.polyglot.Value exception, int index, String parameterType)
      Positional argument index of the Python exception for a primitive parameter of the Java super constructor, which cannot take a missing or None argument.
      Parameters:
      exception - The Python exception
      index - The argument index
      parameterType - The name of the primitive parameter type
      Returns:
      The argument
      Throws:
      IllegalArgumentException - When the exception has fewer arguments or the argument is None

    • argumentAsString

      public static @Nullable String argumentAsString(org.graalvm.polyglot.Value exception, int index)
      Positional argument index of the Python exception as a string: the value itself when it is a string, its str() otherwise, the way a Python exception message reads.
      Parameters:
      exception - The Python exception
      index - The argument index
      Returns:
      The argument, or null when the exception has fewer arguments or the argument is None

    • message

      public static @Nullable String message(org.graalvm.polyglot.Value exception)
      The message of the Python exception: str(exception) when the exception carries arguments, null otherwise (a Python exception raised without arguments has an empty message, a Java exception a null one).
      Parameters:
      exception - The Python exception
      Returns:
      The message, or null

    • declared

      public static @Nullable Throwable declared(org.graalvm.polyglot.PolyglotException exception, Class<?> generatedClass, Class<?>... declaredTypes)
      The exception a generated bridge method declaring checked exceptions rethrows for the exception of its Python call: a host exception of one of the declared types (raised in Python, or thrown by a Java method the Python code called), or the generated Java exception of a Python exception class extending one of the declared types. Any other Python exception is reported as the PolyglotException itself.
      Parameters:
      exception - The exception of the Python call
      generatedClass - The generated class of the bridge method, whose class loader loads the generated exceptions
      declaredTypes - The checked exception types the bridge method declares
      Returns:
      The exception to rethrow, or null when the Python exception is none of them

    • attachCause

      public static void attachCause(Throwable throwable, org.graalvm.polyglot.Value exception)
      Attach the Python cause (raise ... from cause, or the exception being handled when the exception was raised inside an except block) to the generated Java exception when the cause is a Java exception and the Java exception has no cause yet.
      Parameters:
      throwable - The generated Java exception
      exception - The Python exception it was created from

    • asString

      public static @Nullable String asString(@Nullable org.graalvm.polyglot.Value value)
      str(value): the value itself when it is a string, its Python str() otherwise.
      Parameters:
      value - The value
      Returns:
      The string, or null for None