twisted.python.failure.Failure

exception documentation

class Failure(BaseException): (source)

Known subclasses: twisted.spread.pb.CopiedFailure, twisted.spread.pb.CopyableFailure

Constructors: Failure(exc_value, exc_type, exc_tb, captureVars), Failure._withoutTraceback(value)

View In Hierarchy

A basic abstraction for an error that has occurred.

This is necessary because Python's built-in error mechanisms are inconvenient for asynchronous communication.

The frame attribute contain the traceback frames. Each frame is a tuple of (funcName, fileName, lineNumber, localsItems, globalsItems), where localsItems and globalsItems are the contents of locals().items()/globals().items() for that frame, or an empty tuple if those details were not captured.

Local/global variables in frame will only be captured if captureVars=True when constructing the Failure.

Method __getstate__ Avoid pickling objects in the traceback.
Method __init__ Initialize me with an explanation of the error.
Method __reduce__ Undocumented
Method __repr__ Undocumented
Method __setstate__ Undocumented
Method __str__ Undocumented
Method check Check if this failure's type is in a predetermined list.
Method cleanFailure Remove references to other objects, replacing them with strings.
Method frames.setter Undocumented
Method getBriefTraceback Undocumented
Method getErrorMessage Get a string of the exception which caused this Failure.
Method getTraceback Undocumented
Method getTracebackObject Get an object that represents this Failure's stack that can be passed to traceback.extract_tb.
Method parents.setter Undocumented
Method printBriefTraceback Print a traceback as densely as possible.
Method printDetailedTraceback Print a traceback with detailed locals and globals information.
Method printTraceback Emulate Python's standard error reporting mechanism.
Method raiseException raise the original exception, preserving traceback information if available.
Method stack.setter Undocumented
Method throwExceptionIntoGenerator Throw the original exception into the given generator, preserving traceback information if available.
Method trap Trap this failure if its type is in a predetermined list.
Class Variable pickled Undocumented
Instance Variable __dict__ Undocumented
Instance Variable captureVars Undocumented
Instance Variable count Undocumented
Instance Variable tb Undocumented
Instance Variable type The exception's class.
Instance Variable value The exception instance responsible for this failure.
Property frames Undocumented
Property parents Undocumented
Property stack Undocumented
Static Method _withoutTraceback Create a Failure for an exception without a traceback.
Method _extrapolate Extrapolate from one failure into another, copying its stack frames.
Instance Variable _frames Undocumented
Instance Variable _parents Undocumented
def __getstate__(self): (source)

Avoid pickling objects in the traceback.

This is not called direclty by pickle, since BaseException implements reduce; instead, pickle calls Failure.__reduce__ which then calls this API.

def __init__(self, exc_value=None, exc_type=None, exc_tb=None, captureVars=False): (source)

Initialize me with an explanation of the error.

By default, this will use the current exception (sys.exc_info()). However, if you want to specify a particular kind of failure, you can pass an exception as an argument.

If no exc_value is passed, then an "original" Failure will be searched for. If the current exception handler that this Failure is being constructed in is handling an exception raised by raiseException, then this Failure will act like the original Failure.

For exc_tb only traceback instances or None are allowed. If None is supplied for exc_value, the value of exc_tb is ignored, otherwise if exc_tb is None, it will be found from execution context (ie, sys.exc_info).

Parameters
exc_valueUndocumented
exc_typeUndocumented
exc_tbUndocumented
captureVarsif set, capture locals and globals of stack frames. This is pretty slow, and makes no difference unless you are going to use printDetailedTraceback.
def __reduce__(self): (source)

Undocumented

def __repr__(self) -> str: (source)

Undocumented

def __setstate__(self, state): (source)

Undocumented

def __str__(self) -> str: (source)

Undocumented

def check(self, *errorTypes): (source)

Check if this failure's type is in a predetermined list.

Parameters
*errorTypes:list of Exception classes or fully-qualified class names.Undocumented
Returns
the matching Exception type, or None if no match.
def cleanFailure(self): (source)

Remove references to other objects, replacing them with strings.

On Python 3, this will also set the __traceback__ attribute of the exception instance to None.

@frames.setter
def frames(self, frames): (source)

Undocumented

def getBriefTraceback(self) -> str: (source)

Undocumented

def getErrorMessage(self) -> str: (source)

Get a string of the exception which caused this Failure.

def getTraceback(self, elideFrameworkCode: int = 0, detail: str = 'default') -> str: (source)

Undocumented

def getTracebackObject(self): (source)

Get an object that represents this Failure's stack that can be passed to traceback.extract_tb.

If the original traceback object is still present, return that. If this traceback object has been lost but we still have the information, return a fake traceback object (see _Traceback). If there is no traceback information at all, return None.

@parents.setter
def parents(self, parents): (source)

Undocumented

def printBriefTraceback(self, file=None, elideFrameworkCode=0): (source)

Print a traceback as densely as possible.

def printDetailedTraceback(self, file=None, elideFrameworkCode=0): (source)

Print a traceback with detailed locals and globals information.

def printTraceback(self, file=None, elideFrameworkCode=False, detail='default'): (source)
overridden in twisted.spread.pb.CopiedFailure

Emulate Python's standard error reporting mechanism.

Parameters
fileIf specified, a file-like object to which to write the traceback.
elideFrameworkCodeDeprecated, ignored.
detailA string indicating how much information to include in the traceback. Must be one of 'brief', 'default', or 'verbose'.
def raiseException(self) -> NoReturn: (source)

raise the original exception, preserving traceback information if available.

@stack.setter
def stack(self, stack): (source)

Undocumented

@_extraneous
def throwExceptionIntoGenerator(self, g): (source)
overridden in twisted.spread.pb.CopiedFailure

Throw the original exception into the given generator, preserving traceback information if available.

Returns
The next value yielded from the generator.
Raises
StopIterationIf there are no more values in the generator.
anything elseAnything that the generator raises.
def trap(self, *errorTypes): (source)

Trap this failure if its type is in a predetermined list.

This allows you to trap a Failure in an error callback. It will be automatically re-raised if it is not a type that you expect.

The reason for having this particular API is because it's very useful in Deferred errback chains:

    def _ebFoo(self, failure):
        r = failure.trap(Spam, Eggs)
        print('The Failure is due to either Spam or Eggs!')
        if r == Spam:
            print('Spam did it!')
        elif r == Eggs:
            print('Eggs did it!')

If the failure is not a Spam or an Eggs, then the Failure will be 'passed on' to the next errback. In Python 2 the Failure will be raised; in Python 3 the underlying exception will be re-raised.

Parameters
*errorTypes:ExceptionUndocumented
pickled: int = (source)

Undocumented

__dict__ = (source)

Undocumented

captureVars = (source)

Undocumented

count = (source)

Undocumented

tb = (source)

Undocumented

type = (source)
overridden in twisted.spread.pb.CopiedFailure

The exception's class.

value = (source)
overridden in twisted.spread.pb.CopiedFailure

The exception instance responsible for this failure.

@property
frames = (source)

Undocumented

@property
parents = (source)

Undocumented

stack = (source)

Deprecated since version 24.10.0: stack was deprecated in Twisted 24.10.0.

Undocumented

@staticmethod
def _withoutTraceback(value: BaseException) -> Failure: (source)

Create a Failure for an exception without a traceback.

By restricting the inputs significantly, this constructor runs much faster.

def _extrapolate(self, otherFailure): (source)

Extrapolate from one failure into another, copying its stack frames.

Parameters
otherFailure:FailureAnother Failure, whose traceback information, if any, should be preserved as part of the stack presented by this one.
_frames = (source)

Undocumented

_parents = (source)

Undocumented