Futures

Объекты Future используются для связи кода на низком уровне с использованием обратных вызовов с кодом на высоком уровне async/await.

Функции Future

asyncio.isfuture(obj)

Возвращает True если obj является одним из:

• экземпляром asyncio.Future,
• экземпляром asyncio.Task,
• объектом типа Future с атрибутом _asyncio_future_blocking.

Новая в версии 3.5.

asyncio.ensure_future(obj, *, loop=None)

Возвращает:

• аргумент obj без изменений, если obj является Future, Task или объектом типа Future (isfuture() используется для проверки.)
• объект Task, оборачивающий obj, если obj — это корутина (iscoroutine() используется для проверки); в этом случае корутина будет запланирована ensure_future().
• объект Task, который будет ожидать obj, если obj является объектом-awaitable (inspect.isawaitable() используется для проверки.)

Если obj не соответствует ни одному из вышеперечисленных типов, будет поднято исключение TypeError.

Важно

См. также функцию create_task(), которая является предпочтительным способом создания новых задач.

Изменено в версии 3.5.1: Функция принимает любой объект-awaitable.

asyncio.wrap_future(future, *, loop=None)

Оборачивает объект concurrent.futures.Future в объект asyncio.Future.

Объект Future

class asyncio.Future(*, loop=None)

Future представляет собой конечный результат асинхронной операции. Не потокобезопасен.

Future — это объект-awaitable. Корутины могут ожидать объектов Future, пока те не получат результат, исключение или не будут отменены.

Обычно Future используются для взаимодействия кода на низком уровне с использованием обратных вызовов (например, в протоколах, реализованных с использованием asyncio транспорты) с кодом на высоком уровне async/await.

Правило гласит: никогда не экспонируйте объекты Future в пользовательских API, и рекомендуется создавать объекты Future с помощью вызова loop.create_future(). Это позволяет другим реализациям цикла событий вводить свои оптимизированные реализации объекта Future.

Изменено в версии 3.7: Добавлена поддержка модуля contextvars.

result()

Возвращает результат Future.

Если Future завершён и имеет результат, установленный методом set_result(), возвращается значение результата.

Если Future завершён и имеет исключение, установленное методом set_exception(), это метод поднимает исключение.

Если Future был отменён, этот метод поднимает исключение CancelledError.

Если результат Future ещё недоступен, метод поднимает исключение InvalidStateError.

set_result(result)

Помечает Future как завершённый и устанавливает его результат.

Поднимает исключение InvalidStateError, если Future уже завершён.

set_exception(exception)

Помечает Future как завершённый и устанавливает исключение.

Поднимает исключение InvalidStateError, если Future уже завершён.

done()

Возвращает True если Future завершён.

Future завершён, если он был отменён или если у него есть результат или исключение, установленные с помощью вызовов set_result() или set_exception().

cancelled()

Возвращает True если Future был отменён.

Метод обычно используется для проверки, не был ли Future отменён перед установкой результата или исключения для него:

if not fut.cancelled():
    fut.set_result(42)

add_done_callback(callback, *, context=None)

Добавляет обратный вызов, который будет выполнен, когда Future завершён.

Обратный вызов вызывается с объектом Future в качестве единственного аргумента.

Если Future уже завершён при вызове этого метода, обратный вызов планируется с помощью loop.call_soon().

Необязательный ключевой аргумент context позволяет указать пользовательский contextvars.Context для выполнения обратного вызова. При отсутствии context используется текущий контекст.

functools.partial() может быть использован для передачи параметров обратному вызову, например:

# Call 'print("Future:", fut)' when "fut" is done.
fut.add_done_callback(
    functools.partial(print, "Future:"))

Изменено в версии 3.7: Добавлен ключевой параметр context. Дополнительные сведения см. в PEP 567.

remove_done_callback(callback)

Удаляет обратный вызов из списка обратных вызовов.

Возвращает количество удалённых обратных вызовов, обычно 1, если обратный вызов был добавлен более одного раза.

cancel()

Отменяет Future и планирует обратные вызовы.

Если Future уже завершён или отменён, возвращает False. В противном случае состояние Future изменяется на отменённый, планируются обратные вызовы и возвращается True.

exception()

Возвращает исключение, установленное в этом Future.

Исключение (или None если исключение не было установлено) возвращается только если Future завершён.

Если Future был отменён, этот метод поднимает исключение CancelledError.

Если Future ещё не завершён, этот метод поднимает исключение InvalidStateError.

get_loop()

Возвращает цикл событий, к которому привязан объект Future.

Новая в версии 3.7.

В этом примере создаётся объект Future, создаётся и планируется асинхронная задача для установки результата в Future, и ожидается, пока Future не получит результат:

async def set_after(fut, delay, value):
    # Sleep for *delay* seconds.
    await asyncio.sleep(delay)

    # Set *value* as a result of *fut* Future.
    fut.set_result(value)

async def main():
    # Get the current event loop.
    loop = asyncio.get_running_loop()

    # Create a new Future object.
    fut = loop.create_future()

    # Run "set_after()" coroutine in a parallel Task.
    # We are using the low-level "loop.create_task()" API here because
    # we already have a reference to the event loop at hand.
    # Otherwise we could have just used "asyncio.create_task()".
    loop.create_task(
        set_after(fut, 1, '... world'))

    print('hello ...')

    # Wait until *fut* has a result (1 second) and print it.
    print(await fut)

asyncio.run(main())