Go to the latest version of this document.

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

class documentation

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

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

Constructor: `Deferred(canceller)`

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 | `__init__` | Initialize a `Deferred`.
Method | `__init_subclass__` | Undocumented
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 | `unpause` | Process all callbacks made since `pause`() was called.
Class Variable | `debug` | 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
Property | `callbacks` | 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 | `_callbacks` | 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: `Coroutine[Deferred[Any], Any, _T] | Generator[Deferred[Any], Any, _T]`) -> `Deferred[_T]`: (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:`Coroutine[Deferred[Any], Any, _T] | Generator[Deferred[Any], 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: `Future[_SelfResultT]`) -> `Deferred[_SelfResultT]`: (source)

Adapt a `Future` to a `Deferred`.

Parameters
future:`Future[_SelfResultT]` | The `Future` to adapt.

Returns
`Deferred[_SelfResultT]` | 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 __init__(self, canceller: `Callable[[Deferred[Any]], None] | None` = 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 __init_subclass__(cls: `type[Deferred[Any]]`, **kwargs: `Any`): (source)

Undocumented

def __iter__(self) -> `Generator[Deferred[_SelfResultT], None, _SelfResultT]`: (source)

Undocumented

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

Return a string representation of this `Deferred`.

@overload
def addBoth(self, callback: `Callable[Concatenate[_SelfResultT | Failure, _P], Failure]`, *args: `_P.args`, **kwargs: `_P.kwargs`) -> `Deferred[_NextResultT]`:
@overload
def addBoth(self, callback: `Callable[Concatenate[_SelfResultT | Failure, _P], Failure | Deferred[_NextResultT]]`, *args: `_P.args`, **kwargs: `_P.kwargs`) -> `Deferred[_NextResultT]`:
@overload
def addBoth(self, callback: `Callable[Concatenate[_SelfResultT | Failure, _P], Failure | _NextResultT]`, *args: `_P.args`, **kwargs: `_P.kwargs`) -> `Deferred[_NextResultT]`:
@overload
def addBoth(self, callback: `Callable[Concatenate[_SelfResultT | Failure, _P], Deferred[_NextResultT]]`, *args: `_P.args`, **kwargs: `_P.kwargs`) -> `Deferred[_NextResultT]`:
@overload
def addBoth(self, callback: `Callable[Concatenate[_SelfResultT | Failure, _P], Deferred[_NextResultT] | _NextResultT]`, *args: `_P.args`, **kwargs: `_P.kwargs`) -> `Deferred[_NextResultT]`:
@overload
def addBoth(self, callback: `Callable[Concatenate[_SelfResultT | Failure, _P], _NextResultT]`, *args: `_P.args`, **kwargs: `_P.kwargs`) -> `Deferred[_NextResultT]`:
@overload
def addBoth(self, callback: `Callable[Concatenate[_T, _P], _T]`, *args: `_P.args`, **kwargs: `_P.kwargs`) -> `Deferred[_SelfResultT]`:
(source)

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

See `addCallbacks`.

@overload
def addCallback(self, callback: `Callable[Concatenate[_SelfResultT, _P], Failure]`, *args: `_P.args`, **kwargs: `_P.kwargs`) -> `Deferred[_NextResultT]`:
@overload
def addCallback(self, callback: `Callable[Concatenate[_SelfResultT, _P], Failure | Deferred[_NextResultT]]`, *args: `_P.args`, **kwargs: `_P.kwargs`) -> `Deferred[_NextResultT]`:
@overload
def addCallback(self, callback: `Callable[Concatenate[_SelfResultT, _P], Failure | _NextResultT]`, *args: `_P.args`, **kwargs: `_P.kwargs`) -> `Deferred[_NextResultT]`:
@overload
def addCallback(self, callback: `Callable[Concatenate[_SelfResultT, _P], Deferred[_NextResultT]]`, *args: `_P.args`, **kwargs: `_P.kwargs`) -> `Deferred[_NextResultT]`:
@overload
def addCallback(self, callback: `Callable[Concatenate[_SelfResultT, _P], Deferred[_NextResultT] | _NextResultT]`, *args: `_P.args`, **kwargs: `_P.kwargs`) -> `Deferred[_NextResultT]`:
@overload
def addCallback(self, callback: `Callable[Concatenate[_SelfResultT, _P], _NextResultT]`, *args: `_P.args`, **kwargs: `_P.kwargs`) -> `Deferred[_NextResultT]`:
(source)

Convenience method for adding just a callback.

See `addCallbacks`.

def addCallbacks(self, callback: `Callable[..., _NextResultT] | Callable[..., Deferred[_NextResultT]] | Callable[..., Failure] | Callable[..., _NextResultT | Deferred[_NextResultT] | Failure]`, errback: `Callable[..., _NextResultT] | Callable[..., Deferred[_NextResultT]] | Callable[..., Failure] | Callable[..., _NextResultT | Deferred[_NextResultT] | Failure] | None` = None, callbackArgs: `tuple[Any, ...]` = (), callbackKeywords: `Mapping[str, Any]` = _NONE_KWARGS, errbackArgs: `_CallbackOrderedArguments` = (), errbackKeywords: `_CallbackKeywordArguments` = _NONE_KWARGS) -> `Deferred[_NextResultT]`: (source)

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

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

Returns
`Deferred[_NextResultT]` | `self`.

Note
The signature of this function was designed many years before PEP 612; ParamSpec provides no mechanism to annotate parameters like `callbackArgs`; this is therefore inherently less type-safe than calling `addCallback` and `addErrback` separately.

@overload
def addErrback(self, errback: `Callable[Concatenate[Failure, _P], Deferred[_NextResultT]]`, *args: `_P.args`, **kwargs: `_P.kwargs`) -> `Deferred[_SelfResultT | _NextResultT]`:
@overload
def addErrback(self, errback: `Callable[Concatenate[Failure, _P], Failure]`, *args: `_P.args`, **kwargs: `_P.kwargs`) -> `Deferred[_SelfResultT]`:
@overload
def addErrback(self, errback: `Callable[Concatenate[Failure, _P], _NextResultT]`, *args: `_P.args`, **kwargs: `_P.kwargs`) -> `Deferred[_SelfResultT | _NextResultT]`:
(source)

Convenience method for adding just an errback.

See `addCallbacks`.

def addTimeout(self, timeout: `float`, clock: `IReactorTime`, onTimeoutCancel: `Callable[[(_SelfResultT | Failure), float], _NextResultT | Failure] | None` = None) -> `Deferred[_SelfResultT | _NextResultT]`: (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:`Callable[[(_SelfResultT | Failure), float], _NextResultT | Failure] | None`

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[_SelfResultT | _NextResultT]` | `self`.

Present Since
16.5

def asFuture(self, loop: `AbstractEventLoop`) -> `Future[_SelfResultT]`: (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[_SelfResultT]` | 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: `_SelfResultT | Failure`): (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:`_SelfResultT | 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: `Deferred[_SelfResultT]`) -> `Deferred[None]`: (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`.

Returns
`Deferred[None]` | `self`.

def errback(self, fail: `Failure | BaseException | None` = 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:`Failure | BaseException | None` | 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.

def unpause(self): (source)

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

debug: `bool` = (source)

Undocumented

called: `bool` = (source)

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

paused: `int` = (source)

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

result = (source)

Undocumented

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

Deprecated since version 25.5.0: `callbacks` was deprecated in Twisted 25.5.0.

Undocumented

def _continuation(self) -> `_CallbackChain`: (source)

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

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: `object`): (source)

Undocumented

_callbacks: `list[_CallbackChain]` = (source)

Undocumented

_canceller = (source)

Undocumented

_chainedTo: `Deferred[Any] | None` = (source)

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

_debugInfo: `DebugInfo | None` = (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.