PyException (Jython API documentation)
Date: 2024-08-18

org.python.core

## Class PyException

- java.lang.Object
- - java.lang.Throwable
  - - java.lang.Exception
    - - java.lang.RuntimeException
      - - org.python.core.PyException

- All Implemented Interfaces:
    java.io.Serializable, Traverseproc
  Direct Known Subclasses:
    PyIndentationError, PySyntaxError

      public class PyException
      extends java.lang.RuntimeException
      implements Traverseproc

  A wrapper for all python exception. Note that the well-known python exceptions are not subclasses of PyException. Instead the python exception class is stored in the `type` field and value or class instance is stored in the `value` field.
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `PyTraceback` | `traceback` The exception traceback object.
    `PyObject` | `type` The python exception class (for class exception) or identifier (for string exception).
    `PyObject` | `value` The exception instance (for class exception) or exception value (for string exception).

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PyException()`
    `PyException(PyObject type)`
    `PyException(PyObject type, PyObject value)`
    `PyException(PyObject type, PyObject value, PyTraceback traceback)`
    `PyException(PyObject type, java.lang.String value)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static PyException` | `doRaise(PyObject type, PyObject value, PyObject traceback)` Logic for the raise statement
    `static java.lang.String` | `exceptionClassName(PyObject obj)` Get the name of the exception's class
    `java.lang.Throwable` | `fillInStackTrace()`
    `java.lang.String` | `getMessage()`
    `static boolean` | `isExceptionClass(PyObject obj)` Determine whether obj is a Python exception class
    `static boolean` | `isExceptionInstance(PyObject obj)` Determine whether obj is an Python exception instance
    `boolean` | `match(PyObject exc)` Determine if this PyException is a match for exc.
    `void` | `normalize()` Instantiates the exception value if it is not already an instance.
    `void` | `printStackTrace()`
    `void` | `printStackTrace(java.io.PrintStream s)`
    `boolean` | `refersDirectlyTo(PyObject ob)` Optional operation.
    `void` | `super__printStackTrace(java.io.PrintWriter w)`
    `java.lang.String` | `toString()`
    `void` | `tracebackHere(PyFrame here)` Register frame as having been visited in the traceback.
    `void` | `tracebackHere(PyFrame here, boolean isFinally)` Register frame as having been visited in the traceback.
    `int` | `traverse(Visitproc visit, java.lang.Object arg)` Traverses all directly contained `PyObject`s.

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

      `addSuppressed, getCause, getLocalizedMessage, getStackTrace, getSuppressed, initCause, printStackTrace, setStackTrace`

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

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### type

          public PyObject type

      The python exception class (for class exception) or identifier (for string exception).

    - #### value

          public PyObject value

      The exception instance (for class exception) or exception value (for string exception).

    - #### traceback

          public PyTraceback traceback

      The exception traceback object.

  - ### Constructor Detail

    - #### PyException

          public PyException()

    - #### PyException

          public PyException(PyObject type)

    - #### PyException

          public PyException(PyObject type,
                             PyObject value)

    - #### PyException

          public PyException(PyObject type,
                             PyObject value,
                             PyTraceback traceback)

    - #### PyException

          public PyException(PyObject type,
                             java.lang.String value)

  - ### Method Detail

    - #### printStackTrace

          public void printStackTrace()

      Overrides:
        `printStackTrace` in class `java.lang.Throwable`

    - #### fillInStackTrace

          public java.lang.Throwable fillInStackTrace()

      Overrides:
        `fillInStackTrace` in class `java.lang.Throwable`

    - #### getMessage

          public java.lang.String getMessage()

      Overrides:
        `getMessage` in class `java.lang.Throwable`

    - #### printStackTrace

          public void printStackTrace(java.io.PrintStream s)

      Overrides:
        `printStackTrace` in class `java.lang.Throwable`

    - #### super__printStackTrace

          public void super__printStackTrace(java.io.PrintWriter w)

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Throwable`

    - #### normalize

          public void normalize()

      Instantiates the exception value if it is not already an instance.

    - #### tracebackHere

          public void tracebackHere(PyFrame here)

      Register frame as having been visited in the traceback.
      Parameters:
        `here` - the current PyFrame

    - #### tracebackHere

          public void tracebackHere(PyFrame here,
                                    boolean isFinally)

      Register frame as having been visited in the traceback.
      Parameters:
        `here` - the current PyFrame
        `isFinally` - whether caller is a Python finally block

    - #### doRaise

          public static PyException doRaise(PyObject type,
                                            PyObject value,
                                            PyObject traceback)

      Logic for the raise statement
      Parameters:
        `type` - the first arg to raise, a type or an instance
        `value` - the second arg, the instance of the class or arguments to its constructor
        `traceback` - a traceback object
      Returns:
        a PyException wrapper

    - #### match

          public boolean match(PyObject exc)

      Determine if this PyException is a match for exc.
      Parameters:
        `exc` - a PyObject exception type
      Returns:
        true if a match

    - #### isExceptionClass

          public static boolean isExceptionClass(PyObject obj)

      Determine whether obj is a Python exception class
      Parameters:
        `obj` - a PyObject
      Returns:
        true if an exception

    - #### isExceptionInstance

          public static boolean isExceptionInstance(PyObject obj)

      Determine whether obj is an Python exception instance
      Parameters:
        `obj` - a PyObject
      Returns:
        true if an exception instance

    - #### exceptionClassName

          public static java.lang.String exceptionClassName(PyObject obj)

      Get the name of the exception's class
      Parameters:
        `obj` - a PyObject exception
      Returns:
        String exception name

    - #### traverse

          public int traverse(Visitproc visit,
                              java.lang.Object arg)

      Description copied from interface: `Traverseproc`
      Traverses all directly contained `PyObject`s. Like in CPython, `arg` must be passed unmodified to `visit` as its second parameter. If `Visitproc.visit(PyObject, Object)` returns nonzero, this return value must be returned immediately by traverse. `Visitproc.visit(PyObject, Object)` must not be called with a `null` PyObject-argument.
      Specified by:
        `traverse` in interface `Traverseproc`

    - #### refersDirectlyTo

          public boolean refersDirectlyTo(PyObject ob)

      Description copied from interface: `Traverseproc`
      Optional operation. Should only be implemented if it is more efficient than calling `Traverseproc.traverse(Visitproc, Object)` with a visitproc that just watches out for `ob`. Must return `false` if `ob` is `null`.
      Specified by:
        `refersDirectlyTo` in interface `Traverseproc`

Jython homepage