Go to the latest version of this document.
search in docstrings

Search bar offers the following options:

- Term presence. The below example searches for documents that must contain “foo”, might contain “bar” and must not contain “baz”: `+foo bar -baz`
- Wildcards. The below example searches for documents with words beginning with “foo”: `foo*`
- Search in specific fields. The following search matches all objects in "twisted.mail" that matches “search”: `+qname:twisted.mail.* +search`

  Possible fields: 'name', 'qname' (fully qualified name), 'docstring', and 'kind'. Last two fields are only applicable if "search in docstrings" is enabled.

- Fuzzy matches. The following search matches all documents that have a word within 1 edit distance of “foo”: `foo~1`

Results provided by Lunr.js

# ``twisted`.`internet`.`defer`.`Deferred``

class documentation

`class Deferred(Awaitable[_DeferredResultT]): (source)`

Known subclasses: `twisted.internet.defer.DeferredList`, `twisted.persisted.crefutil._Defer`

View In Hierarchy

This is a callback which will be put off until later.

Why do we want this? Well, in cases where a function in a threaded program would block until it gets a result, for Twisted it should not block. Instead, it should return a `Deferred`.

This can be implemented for protocols that run over the network by writing an asynchronous protocol for `twisted.internet`. For methods that come from outside packages that are not under our control, we use threads (see for example `twisted.enterprise.adbapi`).

For more information about Deferreds, see doc/core/howto/defer.html or http://twistedmatrix.com/documents/current/core/howto/defer.html

When creating a Deferred, you may provide a canceller function, which will be called by d.cancel() to let you do any clean-up necessary if the user decides not to wait for the deferred to complete.

Class Method | `fromCoroutine` | Schedule the execution of a coroutine that awaits on `Deferred`s, wrapping it in a `Deferred` that will fire on success/failure of the coroutine.
Class Method | `fromFuture` | Adapt a `Future` to a `Deferred`.
Method | `__await__` | Undocumented
Method | `__init__` | Initialize a `Deferred`.
Method | `__iter__` | Undocumented
Method | `__str__` | Return a string representation of this `Deferred`.
Method | `addBoth` | Convenience method for adding a single callable as both a callback and an errback.
Method | `addCallback` | Convenience method for adding just a callback.
Method | `addCallbacks` | Add a pair of callbacks (success and error) to this `Deferred`.
Method | `addErrback` | Convenience method for adding just an errback.
Method | `addTimeout` | Time out this `Deferred` by scheduling it to be cancelled after `timeout` seconds.
Method | `asFuture` | Adapt this `Deferred` into a `Future` which is bound to `loop`.
Method | `callback` | Run all success callbacks that have been added to this `Deferred`.
Method | `cancel` | Cancel this `Deferred`.
Method | `chainDeferred` | Chain another `Deferred` to this `Deferred`.
Method | `errback` | Run all error callbacks that have been added to this `Deferred`.
Method | `pause` | Stop processing on a `Deferred` until `unpause`() is called.
Method | `send` | Undocumented
Method | `unpause` | Process all callbacks made since `pause`() was called.
Class Variable | `debug` | Undocumented
Instance Variable | `callbacks` | Undocumented
Instance Variable | `called` | A flag which is `False` until either `callback` or `errback` is called and afterwards always `True`.
Instance Variable | `paused` | A counter of how many unmatched `pause` calls have been made on this instance.
Instance Variable | `result` | Undocumented
Method | `_continuation` | Build a tuple of callback and errback with `_Sentinel._CONTINUE`.
Method | `_runCallbacks` | Run the chain of callbacks once a result is available.
Method | `_startRunCallbacks` | Undocumented
Instance Variable | `_canceller` | Undocumented
Instance Variable | `_chainedTo` | If this `Deferred` is waiting for the result of another `Deferred`, this is a reference to the other Deferred. Otherwise, `None`.
Instance Variable | `_debugInfo` | Undocumented
Instance Variable | `_runningCallbacks` | A flag which is `True` while this instance is executing its callback chain, used to stop recursive execution of `_runCallbacks`
Instance Variable | `_suppressAlreadyCalled` | A flag used by the cancellation mechanism which is `True` if the Deferred has no canceller and has been cancelled, `False` otherwise. If `True`, it can be expected that `callback` or `errback` will eventually be called and the result should be silently discarded.

@classmethod
def fromCoroutine(cls, coro): (source)

Schedule the execution of a coroutine that awaits on `Deferred`s, wrapping it in a `Deferred` that will fire on success/failure of the coroutine.

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 Deferred
        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 = Deferred.fromCoroutine(crawl(pages))
            d.addCallback(print)
            return d

        react(main)

Parameters
coro:`Union[Coroutine[Deferred[_T], Any, _T], Generator[Deferred[_T], Any, _T]]` | The coroutine object to schedule.
Returns
`Deferred[_T]` | Undocumented
Raises
`ValueError` | If `coro` is not a coroutine or generator.
Present Since
Twisted 21.2.0

@classmethod
def fromFuture(cls, future): (source)

Adapt a `Future` to a `Deferred`.

Parameters
future:`Future` | The `Future` to adapt.
Returns
`Deferred[Any]` | A `Deferred` which will fire when the `Future` fires.
Present Since
Twisted 17.5.0
Note
This creates a `Deferred` from a `Future`, not from a `coroutine`; in other words, you will need to call `asyncio.ensure_future`, `asyncio.loop.create_task` or create an `asyncio.Task` yourself to get from a `coroutine` to a `Future` if what you have is an awaitable coroutine and not a `Future`. (The length of this list of techniques is exactly why we have left it to the caller!)

def __await__(self): (source)

Undocumented

Returns
`Generator[Any, None, _DeferredResultT]` | Undocumented

def __init__(self, canceller=None): (source)
overridden in `twisted.internet.defer.DeferredList`, `twisted.persisted.crefutil._Defer`

Initialize a `Deferred`.

Parameters

canceller:a 1-argument callable which takes a `Deferred`. The return result is ignored.

a callable used to stop the pending operation scheduled by this `Deferred` when `Deferred.cancel` is invoked. The canceller will be passed the deferred whose cancellation is requested (i.e., `self`).

If a canceller is not given, or does not invoke its argument's `callback` or `errback` method, `Deferred.cancel` will invoke `Deferred.errback` with a `CancelledError`.

Note that if a canceller is not given, `callback` or `errback` may still be invoked exactly once, even though defer.py will have already invoked `errback`, as described above. This allows clients of code which returns a `Deferred` to cancel it without requiring the `Deferred` instantiator to provide any specific implementation support for cancellation. New in 10.1.

def __iter__(self): (source)

Undocumented

Returns
`Deferred[_DeferredResultT]` | Undocumented

def __str__(self): (source)

Return a string representation of this `Deferred`.

Returns
`str` | Undocumented

def addBoth(self, callback, *args, **kwargs): (source)

Convenience method for adding a single callable as both a callback and an errback.

See `addCallbacks`.

Parameters
callback:`Callable[..., Union[_NextDeferredResultT, Deferred[_NextDeferredResultT]]]` | Undocumented
*args:`object` | Undocumented
**kwargs:`object` | Undocumented
Returns
`Deferred[_NextDeferredResultT]` | Undocumented

def addCallback(self, callback, *args, **kwargs): (source)

Convenience method for adding just a callback.

See `addCallbacks`.

Parameters
callback:`Callable[..., Union[_NextDeferredResultT, Deferred[_NextDeferredResultT]]]` | Undocumented
*args:`object` | Undocumented
**kwargs:`object` | Undocumented
Returns
`Deferred[_NextDeferredResultT]` | Undocumented

def addCallbacks(self, callback, errback=_failthru, callbackArgs=(), callbackKeywords=_NONE_KWARGS, errbackArgs=(), errbackKeywords=_NONE_KWARGS): (source)

Add a pair of callbacks (success and error) to this `Deferred`.

These will be executed when the 'master' callback is run.

Parameters
callback:`Callable[..., Union[_NextDeferredResultT, Deferred[_NextDeferredResultT]]]` | Undocumented
errback:`Callable[..., Union[Failure, _NextDeferredResultT, Deferred[_NextDeferredResultT]]]` | Undocumented
callbackArgs:`_CallbackOrderedArguments` | Undocumented
callbackKeywords:`_CallbackKeywordArguments` | Undocumented
errbackArgs:`_CallbackOrderedArguments` | Undocumented
errbackKeywords:`_CallbackKeywordArguments` | Undocumented
Returns
`Deferred[_NextDeferredResultT]` | `self`.

def addErrback(self, errback, *args, **kwargs): (source)

Convenience method for adding just an errback.

See `addCallbacks`.

Parameters
errback:`Callable[..., Union[Failure, _NextDeferredResultT, Deferred[_NextDeferredResultT]]]` | Undocumented
*args:`object` | Undocumented
**kwargs:`object` | Undocumented
Returns
`Deferred[Union[_DeferredResultT, _NextDeferredResultT]]` | Undocumented

def addTimeout(self, timeout, clock, onTimeoutCancel=None): (source)

Time out this `Deferred` by scheduling it to be cancelled after `timeout` seconds.

The timeout encompasses all the callbacks and errbacks added to this `defer.Deferred` before the call to `addTimeout`, and none added after the call.

If this `Deferred` gets timed out, it errbacks with a `TimeoutError`, unless a cancelable function was passed to its initialization or unless a different `onTimeoutCancel` callable is provided.

Parameters
timeout:`float` | number of seconds to wait before timing out this `Deferred`
clock:`IReactorTime` | The object which will be used to schedule the timeout.

onTimeoutCancel:`Optional[Callable[[object, float], object]]`

A callable which is called immediately after this `Deferred` times out, and not if this `Deferred` is otherwise cancelled before the timeout. It takes an arbitrary value, which is the value of this `Deferred` at that exact point in time (probably a `CancelledError` `Failure`), and the `timeout`. The default callable (if `None` is provided) will translate a `CancelledError` `Failure` into a `TimeoutError`.

Returns
`Deferred[_DeferredResultT]` | `self`.
Present Since
16.5

def asFuture(self, loop): (source)

Adapt this `Deferred` into a `Future` which is bound to `loop`.

Parameters
loop:`AbstractEventLoop` | The `asyncio` event loop to bind the `Future` to.
Returns
`Future[_DeferredResultT]` | A `Future` which will fire when the `Deferred` fires.
Present Since
Twisted 17.5.0
Note
converting a `Deferred` to an `Future` consumes both its result and its errors, so this method implicitly converts `self` into a `Deferred` firing with `None`, regardless of what its result previously would have been.

def callback(self, result): (source)

Run all success callbacks that have been added to this `Deferred`.

Each callback will have its result passed as the first argument to the next; this way, the callbacks act as a 'processing chain'. If the success-callback returns a `Failure` or raises an `Exception`, processing will continue on the *error* callback chain. If a callback (or errback) returns another `Deferred`, this `Deferred` will be chained to it (and further callbacks will not run until that `Deferred` has a result).

An instance of `Deferred` may only have either `callback` or `errback` called on it, and only once.

Parameters
result:`Union[_DeferredResultT, Failure]` | The object which will be passed to the first callback added to this `Deferred` (via `addCallback`), unless `result` is a `Failure`, in which case the behavior is the same as calling `errback(result)`.
Raises
`AlreadyCalledError` | If `callback` or `errback` has already been called on this `Deferred`.

def cancel(self): (source)
overridden in `twisted.internet.defer.DeferredList`

Cancel this `Deferred`.

If the `Deferred` has not yet had its `errback` or `callback` method invoked, call the canceller function provided to the constructor. If that function does not invoke `callback` or `errback`, or if no canceller function was provided, errback with `CancelledError`.

If this `Deferred` is waiting on another `Deferred`, forward the cancellation to the other `Deferred`.

def chainDeferred(self, d): (source)

Chain another `Deferred` to this `Deferred`.

This method adds callbacks to this `Deferred` to call `d`'s callback or errback, as appropriate. It is merely a shorthand way of performing the following:

        d1.addCallbacks(d2.callback, d2.errback)

When you chain a deferred `d2` to another deferred `d1` with `d1.chainDeferred(d2)`, you are making `d2` participate in the callback chain of `d1`. Thus any event that fires `d1` will also fire `d2`. However, the converse is not true; if `d2` is fired, `d1` will not be affected.

Note that unlike the case where chaining is caused by a `Deferred` being returned from a callback, it is possible to cause the call stack size limit to be exceeded by chaining many `Deferred`s together with `chainDeferred`.

Parameters
d:`Deferred[_DeferredResultT]` | Undocumented
Returns
`Deferred[None]` | `self`.

def errback(self, fail=None): (source)

Run all error callbacks that have been added to this `Deferred`.

Each callback will have its result passed as the first argument to the next; this way, the callbacks act as a 'processing chain'. Also, if the error-callback returns a non-Failure or doesn't raise an `Exception`, processing will continue on the *success*-callback chain.

If the argument that's passed to me is not a `Failure` instance, it will be embedded in one. If no argument is passed, a `Failure` instance will be created based on the current traceback stack.

Passing a string as `fail' is deprecated, and will be punished with a warning message.

An instance of `Deferred` may only have either `callback` or `errback` called on it, and only once.

Parameters
fail:`Optional[Union[Failure, BaseException]]` | The `Failure` object which will be passed to the first errback added to this `Deferred` (via `addErrback`). Alternatively, a `Exception` instance from which a `Failure` will be constructed (with no traceback) or `None` to create a `Failure` instance from the current exception state (with a traceback).
Raises
`AlreadyCalledError` | If `callback` or `errback` has already been called on this `Deferred`.
`NoCurrentExceptionError` | If `fail` is `None` but there is no current exception state.

def pause(self): (source)

Stop processing on a `Deferred` until `unpause`() is called.

@_extraneous
def send(self, value=None): (source)

Undocumented

Parameters
value:`object` | Undocumented
Returns
`Deferred[_DeferredResultT]` | Undocumented

def unpause(self): (source)

Process all callbacks made since `pause`() was called.

debug: `bool` = (source)

Undocumented

callbacks: `List[_CallbackChain]` = (source)

Undocumented

called: `bool` = (source)

A flag which is `False` until either `callback` or `errback` is called and afterwards always `True`.

paused = (source)

A counter of how many unmatched `pause` calls have been made on this instance.

result = (source)

Undocumented

def _continuation(self): (source)

Build a tuple of callback and errback with `_Sentinel._CONTINUE`.

Returns
`_CallbackChain` | Undocumented

def _runCallbacks(self): (source)

Run the chain of callbacks once a result is available.

This consists of a simple loop over all of the callbacks, calling each with the current result and making the current result equal to the return value (or raised exception) of that call.

If `_runningCallbacks` is true, this loop won't run at all, since it is already running above us on the call stack. If `self.paused` is true, the loop also won't run, because that's what it means to be paused.

The loop will terminate before processing all of the callbacks if a `Deferred` without a result is encountered.

If a `Deferred` with a result is encountered, that result is taken and the loop proceeds.

Note
The implementation is complicated slightly by the fact that chaining (associating two `Deferred`s with each other such that one will wait for the result of the other, as happens when a Deferred is returned from a callback on another `Deferred`) is supported iteratively rather than recursively, to avoid running out of stack frames when processing long chains.

def _startRunCallbacks(self, result): (source)

Undocumented

Parameters
result:`object` | Undocumented

_canceller = (source)

Undocumented

_chainedTo: `Optional[Deferred[Any]]` = (source)

If this `Deferred` is waiting for the result of another `Deferred`, this is a reference to the other Deferred. Otherwise, `None`.

_debugInfo = (source)

Undocumented

_runningCallbacks: `bool` = (source)

A flag which is `True` while this instance is executing its callback chain, used to stop recursive execution of `_runCallbacks`

_suppressAlreadyCalled: `bool` = (source)

A flag used by the cancellation mechanism which is `True` if the Deferred has no canceller and has been cancelled, `False` otherwise. If `True`, it can be expected that `callback` or `errback` will eventually be called and the result should be silently discarded.