Futures

Функции 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 является ожидаемым объектом (inspect.isawaitable() используется для проверки).

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

Важно

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

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

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)

Удаляет 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())