Top Description Fields Constructors Methods
org.python.core

public Class PyException

extends RuntimeException
implements Traverseproc
Class Inheritance
All Implemented Interfaces
org.python.core.Traverseproc
Known Direct Subclasses
org.python.core.PyIndentationError, org.python.core.PySyntaxError
Imports
java.io.*
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.

Field Summary

Modifier and TypeField and Description
private boolean
isReRaise

Whether the exception was re-raised, such as when a traceback is specified to 'raise', or via a 'finally' block.

private boolean
normalized

private boolean
printingStackTrace

public PyTraceback
traceback

The exception traceback object.

public PyObject
type

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

public PyObject
value

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

Constructor Summary

AccessConstructor and Description
public
PyException()

public
PyException(PyObject type)

public
PyException(PyObject type, PyObject value)

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

public
PyException(PyObject type, String value)

Method Summary

Modifier and TypeMethod and Description
public static PyException

Returns:

a PyException wrapper
doRaise(PyObject
the first arg to raise, a type or an instance
type, PyObject
the second arg, the instance of the class or arguments to its constructor
value, PyObject
a traceback object
traceback)

Logic for the raise statement

public static String

Returns:

String exception name
exceptionClassName(PyObject
a PyObject exception
obj)

Get the name of the exception's class

public Throwable
fillInStackTrace()

Overrides java.lang.Throwable.fillInStackTrace.

Fills in the execution stack trace.

public String
getMessage()

Overrides java.lang.Throwable.getMessage.

Returns the detail message string of this throwable.

public static boolean

Returns:

true if an exception
isExceptionClass(PyObject
a PyObject
obj)

Determine whether obj is a Python exception class

public static boolean

Returns:

true if an exception instance
isExceptionInstance(PyObject
a PyObject
obj)

Determine whether obj is an Python exception instance

private static boolean

Returns:

true if an exception
isPy3kExceptionClass(PyObject
a PyObject
obj)

Determine whether obj is a Python 3 exception class

public boolean

Returns:

true if a match
match(PyObject
a PyObject exception type
exc)

Determine if this PyException is a match for exc.

public void
normalize()

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

public void
printStackTrace()

Overrides java.lang.Throwable.printStackTrace.

Prints this throwable and its backtrace to the standard error stream.

public synchronized void
printStackTrace(PrintStream
PrintStream to use for output
s)

Overrides java.lang.Throwable.printStackTrace.

Prints this throwable and its backtrace to the specified print stream.

public boolean
refersDirectlyTo(PyObject ob)

Implements org.python.core.Traverseproc.refersDirectlyTo.

Optional operation.

public synchronized void
super__printStackTrace(PrintWriter w)

public synchronized String
toString()

Overrides java.lang.Throwable.toString.

Returns a short description of this throwable.

public void
tracebackHere(PyFrame
the current PyFrame
here)

Register frame as having been visited in the traceback.

public void
tracebackHere(PyFrame
the current PyFrame
here, boolean
whether caller is a Python finally block
isFinally)

Register frame as having been visited in the traceback.

public int
traverse(Visitproc visit, Object arg)

Implements org.python.core.Traverseproc.traverse.

Traverses all directly contained PyObjects.

Field Detail

isReRaiseback to summary
private boolean isReRaise

Whether the exception was re-raised, such as when a traceback is specified to 'raise', or via a 'finally' block.

normalizedback to summary
private boolean normalized
printingStackTraceback to summary
private boolean printingStackTrace
tracebackback to summary
public PyTraceback traceback

The exception traceback object.

typeback to summary
public PyObject type

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

valueback to summary
public PyObject value

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

Constructor Detail

PyExceptionback to summary
public PyException()
PyExceptionback to summary
public PyException(PyObject type)
PyExceptionback to summary
public PyException(PyObject type, PyObject value)
PyExceptionback to summary
public PyException(PyObject type, PyObject value, PyTraceback traceback)
PyExceptionback to summary
public PyException(PyObject type, String value)

Method Detail

doRaiseback to summary
public static PyException doRaise(PyObject type, PyObject value, PyObject traceback)

Logic for the raise statement

Parameters
type:PyObject

the first arg to raise, a type or an instance

value:PyObject

the second arg, the instance of the class or arguments to its constructor

traceback:PyObject

a traceback object

Returns:PyException

a PyException wrapper

exceptionClassNameback to summary
public static String exceptionClassName(PyObject obj)

Get the name of the exception's class

Parameters
obj:PyObject

a PyObject exception

Returns:String

String exception name

fillInStackTraceback to summary
public Throwable fillInStackTrace()

Overrides java.lang.Throwable.fillInStackTrace.

Doc from java.lang.Throwable.fillInStackTrace.

Fills in the execution stack trace. This method records within this Throwable object information about the current state of the stack frames for the current thread.

If the stack trace of this Throwable is not writable, calling this method has no effect.

Returns:Throwable

a reference to this Throwable instance.

Annotations
@Override

getMessageback to summary
public String getMessage()

Overrides java.lang.Throwable.getMessage.

Doc from java.lang.Throwable.getMessage.

Returns the detail message string of this throwable.

Returns:String

the detail message string of this Throwable instance (which may be null).

Annotations
@Override

isExceptionClassback to summary
public static boolean isExceptionClass(PyObject obj)

Determine whether obj is a Python exception class

Parameters
obj:PyObject

a PyObject

Returns:boolean

true if an exception

isExceptionInstanceback to summary
public static boolean isExceptionInstance(PyObject obj)

Determine whether obj is an Python exception instance

Parameters
obj:PyObject

a PyObject

Returns:boolean

true if an exception instance

isPy3kExceptionClassback to summary
private static boolean isPy3kExceptionClass(PyObject obj)

Determine whether obj is a Python 3 exception class

Parameters
obj:PyObject

a PyObject

Returns:boolean

true if an exception

matchback to summary
public boolean match(PyObject exc)

Determine if this PyException is a match for exc.

Parameters
exc:PyObject

a PyObject exception type

Returns:boolean

true if a match

normalizeback to summary
public void normalize()

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

printStackTraceback to summary
public void printStackTrace()

Overrides java.lang.Throwable.printStackTrace.

Doc from java.lang.Throwable.printStackTrace.

Prints this throwable and its backtrace to the standard error stream. This method prints a stack trace for this Throwable object on the error output stream that is the value of the field System.err. The first line of output contains the result of the toString() method for this object. Remaining lines represent data previously recorded by the method fillInStackTrace(). The format of this information depends on the implementation, but the following example may be regarded as typical: 

java.lang.NullPointerException
        at MyClass.mash(MyClass.java:9)
        at MyClass.crunch(MyClass.java:6)
        at MyClass.main(MyClass.java:3)
This example was produced by running the program: 
class MyClass {
    public static void main(String[] args) {
        crunch(null);
    }
    static void crunch(int[] a) {
        mash(a);
    }
    static void mash(int[] b) {
        System.out.println(b[0]);
    }
}
The backtrace for a throwable with an initialized, non-null cause should generally include the backtrace for the cause. The format of this information depends on the implementation, but the following example may be regarded as typical: 
HighLevelException: MidLevelException: LowLevelException
        at Junk.a(Junk.java:13)
        at Junk.main(Junk.java:4)
Caused by: MidLevelException: LowLevelException
        at Junk.c(Junk.java:23)
        at Junk.b(Junk.java:17)
        at Junk.a(Junk.java:11)
        ... 1 more
Caused by: LowLevelException
        at Junk.e(Junk.java:30)
        at Junk.d(Junk.java:27)
        at Junk.c(Junk.java:21)
        ... 3 more
Note the presence of lines containing the characters "...". These lines indicate that the remainder of the stack trace for this exception matches the indicated number of frames from the bottom of the stack trace of the exception that was caused by this exception (the "enclosing" exception). This shorthand can greatly reduce the length of the output in the common case where a wrapped exception is thrown from the same method as the "causative exception" is caught. The above example was produced by running the program: 
public class Junk {
    public static void main(String args[]) {
        try {
            a();
        } catch(HighLevelException e) {
            e.printStackTrace();
        }
    }
    static void a() throws HighLevelException {
        try {
            b();
        } catch(MidLevelException e) {
            throw new HighLevelException(e);
        }
    }
    static void b() throws MidLevelException {
        c();
    }
    static void c() throws MidLevelException {
        try {
            d();
        } catch(LowLevelException e) {
            throw new MidLevelException(e);
        }
    }
    static void d() throws LowLevelException {
       e();
    }
    static void e() throws LowLevelException {
        throw new LowLevelException();
    }
}

class HighLevelException extends Exception {
    HighLevelException(Throwable cause) { super(cause); }
}

class MidLevelException extends Exception {
    MidLevelException(Throwable cause)  { super(cause); }
}

class LowLevelException extends Exception {
}
As of release 7, the platform supports the notion of suppressed exceptions (in conjunction with the try-with-resources statement). Any exceptions that were suppressed in order to deliver an exception are printed out beneath the stack trace. The format of this information depends on the implementation, but the following example may be regarded as typical: 
Exception in thread "main" java.lang.Exception: Something happened
        at Foo.bar(Foo.java:10)
        at Foo.main(Foo.java:5)
        Suppressed: Resource$CloseFailException: Resource ID = 0
                at Resource.close(Resource.java:26)
                at Foo.bar(Foo.java:9)
                ... 1 more
Note that the "... n more" notation is used on suppressed exceptions just as it is used on causes. Unlike causes, suppressed exceptions are indented beyond their "containing exceptions."

An exception can have both a cause and one or more suppressed exceptions: 

Exception in thread "main" java.lang.Exception: Main block
        at Foo3.main(Foo3.java:7)
        Suppressed: Resource$CloseFailException: Resource ID = 2
                at Resource.close(Resource.java:26)
                at Foo3.main(Foo3.java:5)
        Suppressed: Resource$CloseFailException: Resource ID = 1
                at Resource.close(Resource.java:26)
                at Foo3.main(Foo3.java:5)
Caused by: java.lang.Exception: I did it
        at Foo3.main(Foo3.java:8)
Likewise, a suppressed exception can have a cause: 
Exception in thread "main" java.lang.Exception: Main block
        at Foo4.main(Foo4.java:6)
        Suppressed: Resource2$CloseFailException: Resource ID = 1
                at Resource2.close(Resource2.java:20)
                at Foo4.main(Foo4.java:5)
        Caused by: java.lang.Exception: Rats, you caught me
                at Resource2$CloseFailException.<init>(Resource2.java:45)
                ... 2 more
Annotations
@Override
printStackTraceback to summary
public synchronized void printStackTrace(PrintStream s)

Overrides java.lang.Throwable.printStackTrace.

Doc from java.lang.Throwable.printStackTrace.

Prints this throwable and its backtrace to the specified print stream.

Parameters
s:PrintStream

PrintStream to use for output

Annotations
@Override
refersDirectlyToback to summary
public boolean refersDirectlyTo(PyObject ob)

Implements org.python.core.Traverseproc.refersDirectlyTo.

Doc from org.python.core.Traverseproc.refersDirectlyTo.

Optional operation. Should only be implemented if it is more efficient than calling traverse(Visitproc, Object) with a visitproc that just watches out for ob. Must return false if ob is null.

Annotations
@Override
super__printStackTraceback to summary
public synchronized void super__printStackTrace(PrintWriter w)
toStringback to summary
public synchronized String toString()

Overrides java.lang.Throwable.toString.

Doc from java.lang.Throwable.toString.

Returns a short description of this throwable. The result is the concatenation of:

  • the name of the class of this object
  • ": " (a colon and a space)
  • the result of invoking this object's getLocalizedMessage method
If getLocalizedMessage returns null, then just the class name is returned.
Returns:String

a string representation of this throwable.

Annotations
@Override

tracebackHereback to summary
public void tracebackHere(PyFrame here)

Register frame as having been visited in the traceback.

Parameters
here:PyFrame

the current PyFrame

tracebackHereback to summary
public void tracebackHere(PyFrame here, boolean isFinally)

Register frame as having been visited in the traceback.

Parameters
here:PyFrame

the current PyFrame

isFinally:boolean

whether caller is a Python finally block

traverseback to summary
public int traverse(Visitproc visit, Object arg)

Implements org.python.core.Traverseproc.traverse.

Doc from org.python.core.Traverseproc.traverse.

Traverses all directly contained PyObjects. 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.

Annotations
@Override