Small framework for asynchronous programming.
The Deferred allows to chain callbacks.
There are two type of callbacks: normal callbacks and errbacks, which handle an exception in a normal callback.
The callbacks are processed in pairs consisting of a normal callback and an errback. A normal callback will return its result to the callback of the next pair. If an exception occurs, it will be handled by the errback of the next pair. If an errback doesn’t raise an error again, the callback of the next pair will be called with the return value of the errback. Otherwise the exception of the errback will be returned to the errback of the next pair:
CALLBACK1 ERRBACK1
| \ / |
result failure result failure
| \ / |
| \ / |
| X |
| / \ |
| / \ |
| / \ |
CALLBACK2 ERRBACK2
| \ / |
result failure result failure
| \ / |
| \ / |
| X |
| / \ |
| / \ |
| / \ |
CALLBACK3 ERRBACK3
Add a callable (function or method) to the callback chain only.
An error would be passed through to the next errback.
The first argument is the callable instance followed by any additional argument that will be passed to the callback.
The callback method will get the result of the previous callback and any additional arguments that was specified in add_callback.
>>> def callback(previous, counter=False):
... if counter:
... return previous + 1
... return previous
>>> deferred = Deferred()
>>> deferred.add_callback(callback, counter=True)
>>> deferred.callback(1)
>>> deferred.result
2
Add a pair of callables (function or method) to the callback and errback chain.
Keyword arguments: callback – the next chained challback errback – the next chained errback callback_args – list of additional arguments for the callback callback_kwargs – dict of additional arguments for the callback errback_args – list of additional arguments for the errback errback_kwargs – dict of additional arguments for the errback
In the following example the first callback pairs raises an exception that is catched by the errback of the second one and processed by the third one.
>>> def callback(previous):
... '''Return the previous result.'''
... return "Got: %s" % previous
>>> def callback_raise(previous):
... '''Fail and raise an exception.'''
... raise Exception("Test")
>>> def errback(error):
... '''Recover from an exception.'''
... #error.catch(Exception)
... return "catched"
>>> deferred = Deferred()
>>> deferred.callback("start")
>>> deferred.result
'start'
>>> deferred.add_callbacks(callback_raise, errback)
>>> deferred.result #doctest: +ELLIPSIS
<defer.DeferredException object at 0x...>
>>> deferred.add_callbacks(callback, errback)
>>> deferred.result
'catched'
>>> deferred.add_callbacks(callback, errback)
>>> deferred.result
'Got: catched'
Add a callable (function or method) to the errback chain only.
If there isn’t any exception the result will be passed through to the callback of the next pair.
The first argument is the callable instance followed by any additional argument that will be passed to the errback.
The errback method will get the most recent DeferredException and and any additional arguments that was specified in add_errback.
If the errback can catch the exception it can return a value that will be passed to the next callback in the chain. Otherwise the errback chain will not be processed anymore.
See the documentation of defer.DeferredException.catch for further information.
>>> def catch_error(deferred_error, ignore=False):
... if ignore:
... return "ignored"
... deferred_error.catch(Exception)
... return "catched"
>>> deferred = Deferred()
>>> deferred.errback(SystemError())
>>> deferred.add_errback(catch_error, ignore=True)
>>> deferred.result
'ignored'
Start processing the callback chain starting with the provided result.
It will be send to the first callback or stored as finally one if not any further callback has been specified yet.
>>> deferred = Deferred()
>>> deferred.callback("done")
>>> deferred.result
'done'
Start processing the errorback chain starting with the provided exception or DeferredException.
If an exception is specified it will be wrapped into a DeferredException. It will be send to the first errback or stored as finally result if not any further errback has been specified yet.
>>> deferred = Deferred()
>>> deferred.errback(Exception("Test Error"))
>>> deferred.result #doctest: +ELLIPSIS
<defer.DeferredException object at 0x...>
>>> deferred.result.raise_exception()
Traceback (most recent call last):
...
Exception: Test Error
Allows to defer exceptions.
Check if the stored exception is a subclass of one of the provided exception classes. If this is the case return the matching exception class. Otherwise raise the stored exception.
>>> exc = DeferredException(SystemError())
>>> exc.catch(Exception) # Will catch the exception and return it
<type 'exceptions.Exception'>
>>> exc.catch(OSError) # Won't catch and raise the stored exception
Traceback (most recent call last):
...
SystemError
This method can be used in errbacks of a Deferred:
>>> def dummy_errback(deferred_exception):
... '''Error handler for OSError'''
... deferred_exception.catch(OSError)
... return "catched"
The above errback can handle an OSError:
>>> deferred = Deferred()
>>> deferred.add_errback(dummy_errback)
>>> deferred.errback(OSError())
>>> deferred.result
'catched'
But fails to handle a SystemError:
>>> deferred2 = Deferred()
>>> deferred2.add_errback(dummy_errback)
>>> deferred2.errback(SystemError())
>>> deferred2.result #doctest: +ELLIPSIS
<defer.DeferredException object at 0x...>
>>> deferred2.result.value
SystemError()
Invoke the given function that may or not may be a Deferred.
If the return object of the function call is a Deferred return, it. Otherwise wrap it into a Deferred.
>>> defer(lambda x: x, 10) #doctest: +ELLIPSIS
<defer.Deferred object at 0x...>
>>> deferred = defer(lambda x: x, "done")
>>> deferred.result
'done'
>>> deferred = Deferred()
>>> defer(lambda: deferred) == deferred
True
inline_callbacks helps you write Deferred-using code that looks like a regular sequential function. For example:
def thingummy():
thing = yield makeSomeRequestResultingInDeferred()
print thing #the result! hoorj!
thingummy = inline_callbacks(thingummy)
When you call anything that results in a Deferred, you can simply yield it; your generator will automatically be resumed when the Deferred’s result is available. The generator will be sent the result of the Deferred with the ‘send’ method on generators, or if the result was a failure, ‘throw’.
Your inline_callbacks-enabled generator will return a Deferred object, which will result in the return value of the generator (or will fail with a failure object if your generator raises an unhandled exception). Note that you can’t use return result to return a value; use return_value(result) instead. Falling off the end of the generator, or simply using return will cause the Deferred to have a result of None.
The Deferred returned from your deferred generator may errback if your generator raised an exception:
def thingummy():
thing = yield makeSomeRequestResultingInDeferred()
if thing == 'I love Twisted':
# will become the result of the Deferred
return_value('TWISTED IS GREAT!')
else:
# will trigger an errback
raise Exception('DESTROY ALL LIFE')
thingummy = inline_callbacks(thingummy)
Return val from a inline_callbacks generator.
Note: this is currently implemented by raising an exception derived from BaseException. You might want to change any ‘except:’ clauses to an ‘except Exception:’ clause so as not to catch this exception.
Also: while this function currently will work when called from within arbitrary functions called from within the generator, do not rely upon this behavior.