twisted.internet.defer
module documentationtwisted.internet
View Source
Support for results that aren't immediately available.
Maintainer: Glyph Lefkowitz
Class | AlreadyCalledError | Undocumented |
Class | CancelledError | This error is raised by default when a Deferred is
cancelled. |
Class | TimeoutError | This error is raised by default when a Deferred times
out. |
Function | logError | Log and return failure. |
Function | succeed | Return a Deferred that
has already had .callback(result) called. |
Function | fail | Return a Deferred that
has already had .errback(result) called. |
Function | execute | Create a Deferred from
a callable and arguments. |
Function | maybeDeferred | Invoke a function that may or may not return a Deferred . |
Function | timeout | Undocumented |
Function | passthru | Undocumented |
Function | setDebugging | Enable or disable Deferred
debugging. |
Function | getDebugging | Determine whether Deferred
debugging is enabled. |
Class | Deferred | This is a callback which will be put off until later. |
Function | ensureDeferred | No summary |
Class | DebugInfo | Deferred debug helper. |
Class | FirstError | First error to occur in a DeferredList
if fireOnOneErrback is set. |
Class | DeferredList | DeferredList
is a tool for collecting the results of several Deferreds. |
Function | gatherResults | Returns, via a Deferred , a
list with the results of the given Deferred s - in
effect, a "join" of multiple deferred operations. |
Class | waitForDeferred | See deferredGenerator . |
Function | deferredGenerator | No summary |
Function | returnValue | Return val from a inlineCallbacks
generator. |
Function | inlineCallbacks |
|
Class | DeferredLock | A lock for event driven systems. |
Class | DeferredSemaphore | A semaphore for event driven systems. |
Class | QueueOverflow | Undocumented |
Class | QueueUnderflow | Undocumented |
Class | DeferredQueue | An event driven queue. |
Class | AlreadyTryingToLockError | Raised when DeferredFilesystemLock.deferUntilLocked
is called twice on a single DeferredFilesystemLock . |
Class | DeferredFilesystemLock | A FilesystemLock
that allows for a Deferred to be
fired when the lock is acquired. |
Variable | _NO_RESULT | The result used to represent the fact that there is no result. Never ever ever use this as an actual result for a Deferred. You have been warned. |
Variable | _CONTINUE | A marker left in Deferred.callback s
to indicate a Deferred chain. Always accompanied by a Deferred instance in
the args tuple pointing at the Deferred which is chained to the Deferred
which has this marker. |
Function | _cancelledToTimedOutError | A default translation function that translates Failure s that
are CancelledError s
to TimeoutError s. |
Function | _parseDListResult | Undocumented |
Function | _deferGenerator | See deferredGenerator . |
Class | _DefGen_Return | Undocumented |
Class | _CancellationStatus | Cancellation status of an inlineCallbacks
invocation. |
Function | _inlineCallbacks | Carry out the work of inlineCallbacks . |
Function | _cancellableInlineCallbacks | Make an @ inlineCallbacks
cancellable. |
Class | _InternalInlineCallbacksCancelledError | A unique exception used only in _cancellableInlineCallbacks
to verify that an inlineCallbacks
is being cancelled as expected. |
Class | _ConcurrencyPrimitive | No class docstring; 1/3 methods documented |
Deferred.callback
s
to indicate a Deferred chain. Always accompanied by a Deferred instance in
the args tuple pointing at the Deferred which is chained to the Deferred
which has this marker.
Log and return failure.
This method can be used as an errback that passes the failure on to the next errback unmodified. Note that if this is the last errback, and the deferred gets garbage collected after being this errback has been called, the clean up code logs it again.
Return a Deferred
that
has already had .callback(result)
called.
This is useful when you're writing synchronous code to an asynchronous
interface: i.e., some code is calling you expecting a Deferred
result, but you don't actually need to do anything asynchronous. Just
return defer.succeed(theResult)
.
See fail
for
a version of this function that uses a failing Deferred
rather than a successful one.
Parameters | result | The result to give to the Deferred's 'callback' method. |
Returns | (type: Deferred ) |
Return a Deferred
that
has already had .errback(result)
called.
See succeed
's
docstring for rationale.
Parameters | result | The same argument that Deferred.errback
takes. |
Returns | (type: Deferred ) | |
Raises | NoCurrentExceptionError | If result is None
but there is no current exception state. |
Invoke a function that may or may not return a Deferred
.
Call the given function with the given arguments. If the returned
object is a Deferred
,
return it. If the returned object is a Failure
, wrap
it with fail
and return it. Otherwise, wrap it in succeed
and
return it. If an exception is raised, convert it to a Failure
, wrap
it in fail
, and
then return it.
Parameters | f | The callable to invoke (type: Any callable) |
args | The arguments to pass to f | |
kw | The keyword arguments to pass to f | |
Returns | The result of the function call, wrapped in a Deferred if
necessary. (type: Deferred ) |
Enable or disable Deferred
debugging.
When debugging is on, the call stacks from creation and invocation are
recorded, and added to any AlreadyCalledError
s
we raise.
A default translation function that translates Failure
s that
are CancelledError
s
to TimeoutError
s.
Parameters | value | Anything (type: Anything) |
timeout | The timeout (type: int ) | |
Returns | (type: value ) | |
Raises | TimeoutError | |
Present Since | 16.5 |
Schedule the execution of a coroutine that awaits/yields from Deferred
s,
wrapping it in a Deferred
that
will fire on success/failure of the coroutine. If a Deferred is passed to
this function, it will be returned directly (mimicing
asyncio
's ensure_future
function).
Coroutine functions return a coroutine object, similar to how generators work. This function turns that coroutine into a Deferred, meaning that it can be used in regular Twisted code. For example:
import treq from twisted.internet.defer import ensureDeferred from twisted.internet.task import react async def crawl(pages): results = {} for page in pages: results[page] = await treq.content(await treq.get(page)) return results def main(reactor): pages = [ "http://localhost:8080" ] d = ensureDeferred(crawl(pages)) d.addCallback(print) return d react(main)
Parameters | coro | The coroutine object to schedule, or a Deferred . (type: A Python 3.5+ async def coroutine , a Python 3.4+
yield from using types.GeneratorType ,
or a Deferred .) |
Returns | (type: Deferred ) |
Returns, via a Deferred
, a
list with the results of the given Deferred
s - in
effect, a "join" of multiple deferred operations.
The returned Deferred
will
fire when all of the provided Deferred
s have
fired, or when any one of them has failed.
This method can be cancelled by calling the cancel
method
of the Deferred
, all
the Deferred
s in
the list will be cancelled.
This differs from DeferredList
in that you don't need to parse the result for success/failure.
Parameters | consumeErrors | (keyword param) a flag, defaulting to False, indicating that failures in
any of the given Deferred s
should not be propagated to errbacks added to the individual Deferred s
after this gatherResults
invocation. Any such errors in the individual Deferred s will
be converted to a callback result of None .
This is useful to prevent spurious 'Unhandled error in Deferred' messages
from being logged. This parameter is available since 11.1.0. (type: bool ) |
deferredGenerator
and waitForDeferred
help you write Deferred
-using
code that looks like a regular sequential function. Consider the use of inlineCallbacks
instead, which can accomplish the same thing in a more concise manner.
There are two important functions involved: waitForDeferred
,
and deferredGenerator
.
They are used together, like this:
@deferredGenerator def thingummy(): thing = waitForDeferred(makeSomeRequestResultingInDeferred()) yield thing thing = thing.getResult() print(thing) #the result! hoorj!
waitForDeferred
returns something that you should immediately yield; when your generator is
resumed, calling thing.getResult()
will either give you the
result of the Deferred
if it
was a success, or raise an exception if it was a failure. Calling
getResult
is absolutely mandatory. If you do not call
it, your program will not work.
deferredGenerator
takes one of these waitForDeferred-using generator functions and converts
it into a function that returns a Deferred
. The
result of the Deferred
will
be the last value that your generator yielded unless the last value is a waitForDeferred
instance, in which case the result will be None
.
If the function raises an unhandled exception, the Deferred
will
errback instead. Remember that return result
won't work; use
yield result; return
in place of that.
Note that not yielding anything from your generator will make the Deferred
result in None
.
Yielding a Deferred
from
your generator is also an error condition; always yield
waitForDeferred(d)
instead.
The Deferred
returned from your deferred generator may also errback if your generator
raised an exception. For example:
@deferredGenerator def thingummy(): thing = waitForDeferred(makeSomeRequestResultingInDeferred()) yield thing thing = thing.getResult() if thing == 'I love Twisted': # will become the result of the Deferred yield 'TWISTED IS GREAT!' return else: # will trigger an errback raise Exception('DESTROY ALL LIFE')
Put succinctly, these functions connect deferred-using code with this
'fake blocking' style in both directions: waitForDeferred
converts from a Deferred
to
the 'blocking' style, and deferredGenerator
converts from the 'blocking' style to a Deferred
.
Return val from a inlineCallbacks
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.
Carry out the work of inlineCallbacks
.
Iterate the generator produced by an @
inlineCallbacks
-decorated
function, g
, send()
ing it the results of each
value yield
ed by that generator, until a Deferred
is
yielded, at which point a callback is added to that Deferred
to
call this function again.
Parameters | result | The last result seen by this generator. Note that this is never a Deferred - by
the time this function is invoked, the Deferred has
been called back and this will be a particular result at a point in its
callback chain. |
g | a generator object returned by calling a function or method decorated with
@ inlineCallbacks | |
status | a _CancellationStatus
tracking the current status of g |
Make an @
inlineCallbacks
cancellable.
Parameters | g | a generator object returned by calling a function or method decorated with
@ inlineCallbacks |
Returns | Deferred
for the @ inlineCallbacks
that is cancellable. |
inlineCallbacks
helps you write Deferred
-using
code that looks like a regular sequential function. For example:
@inlineCallbacks def thingummy(): thing = yield makeSomeRequestResultingInDeferred() print(thing) # the result! hoorj!
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'.
Things that are not Deferred
s may
also be yielded, and your generator will be resumed with the same object
sent back. This means yield
performs an operation roughly
equivalent to maybeDeferred
.
Your inlineCallbacks-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 returnValue(result)
instead. Falling off the end of
the generator, or simply using return
will cause the Deferred
to
have a result of None
.
Be aware that returnValue
will not accept a Deferred
as a
parameter. If you believe the thing you'd like to return could be a Deferred
, do
this:
result = yield result returnValue(result)
The Deferred
returned from your deferred generator may errback if your generator raised
an exception:
@inlineCallbacks def thingummy(): thing = yield makeSomeRequestResultingInDeferred() if thing == 'I love Twisted': # will become the result of the Deferred returnValue('TWISTED IS GREAT!') else: # will trigger an errback raise Exception('DESTROY ALL LIFE')
It is possible to use the return
statement instead of returnValue
:
@inlineCallbacks def loadData(url): response = yield makeRequest(url) return json.loads(response)
You can cancel the Deferred
returned from your inlineCallbacks
generator before it is fired by your generator completing (either by
reaching its end, a return
statement, or by calling returnValue
).
A CancelledError
will be raised from the yielde
ed
Deferred
that has been cancelled if that Deferred
does not otherwise
suppress it.