# ``twisted`.`python`.`failure`.`Failure``

class documentation

`class Failure(BaseException): (source)`

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

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 `stack` and `frame` attributes contain 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.

Method | `__getstate__` | Avoid pickling objects in the traceback.
Method | `__init__` | Initialize me with an explanation of the error.
Method | `__repr__` | 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 | `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 | `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 | `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 | `frames` | list of frames, innermost first.
Instance Variable | `parents` | Undocumented
Instance Variable | `stack` | list of frames, innermost last, excluding `Failure.__init__`.
Instance Variable | `tb` | Undocumented
Instance Variable | `type` | The exception's class.
Instance Variable | `value` | The exception instance responsible for this failure.
Class Method | `_findFailure` | Find the failure that represents the exception currently in context.
Method | `_extrapolate` | Extrapolate from one failure into another, copying its stack frames.
Class Variable | `_yieldOpcode` | Undocumented

def __getstate__(self): (source)
Avoid pickling objects in the traceback.
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_value | Undocumented
exc_type | Undocumented
exc_tb | Undocumented
captureVars | if set, capture locals and globals of stack frames. This is pretty slow, and makes no difference unless you are going to use `printDetailedTraceback`.

def __repr__(self): (source)

Undocumented

Returns
`str` | Undocumented

def __str__(self): (source)

Undocumented

Returns
`str` | 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`.

def getBriefTraceback(self): (source)

Undocumented

Returns
`str` | Undocumented

def getErrorMessage(self): (source)
Get a string of the exception which caused this Failure.

Returns
`str` | Undocumented

def getTraceback(self, elideFrameworkCode=0, detail='default'): (source)

Undocumented

Parameters
elideFrameworkCode:`int` | Undocumented
detail:`str` | Undocumented
Returns
`str` | 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.

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
file | If specified, a file-like object to which to write the traceback.
elideFrameworkCode | A flag indicating whether to attempt to remove uninteresting frames from within Twisted itself from the output.
detail | A string indicating how much information to include in the traceback. Must be one of `'brief'`, `'default'`, or `'verbose'`.

def raiseException(self): (source)
raise the original exception, preserving traceback information if available.
@_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
`StopIteration` | If there are no more values in the generator.
`anything else` | Anything 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:`Exception` | Undocumented

pickled: `int` = (source)

Undocumented

__dict__ = (source)

Undocumented

captureVars = (source)

Undocumented

count = (source)

Undocumented

frames = (source)
list of frames, innermost first.
parents = (source)

Undocumented

stack: `list` = (source)
list of frames, innermost last, excluding `Failure.__init__`.
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.
@classmethod
def _findFailure(cls): (source)
Find the failure that represents the exception currently in context.
def _extrapolate(self, otherFailure): (source)
Extrapolate from one failure into another, copying its stack frames.

Parameters
otherFailure:`Failure` | Another `Failure`, whose traceback information, if any, should be preserved as part of the stack presented by this one.

_yieldOpcode = (source)

Undocumented