Объекты Future

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

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

Важно

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

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

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

Устарело с версии 3.10: Предупреждение об устаревании выводится, если obj не является объектом, подобным Future, параметр loop не указан и цикл событий не запущен.

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

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

Устарело с версии 3.10: Предупреждение об устаревании выводится, если future не является объектом, подобным Future, параметр loop не указан и цикл событий не запущен.

Объект Future

class asyncio.Future(*, loop=None)

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

Future — это объект, поддерживающий await. Сопрограммы могут ожидать объекты Future, пока для них не будет задан результат или исключение либо пока они не будут отменены. Ожидать Future можно несколько раз; результат при этом будет одинаковым.

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

Как правило, объекты Future не следует предоставлять в API для пользователей; рекомендуемый способ создания объекта Future — вызов loop.create_future(). Это позволяет альтернативным реализациям цикла событий использовать собственные оптимизированные реализации объекта Future.

Объекты Future являются обобщёнными относительно типа результата.

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

Устарело с версии 3.10: Предупреждение об устаревании выводится, если параметр loop не указан и цикл событий не запущен.

result()

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

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

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

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

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

set_result(result)

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

Если Future уже завершён (done), возбуждается исключение InvalidStateError.

set_exception(exception)

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

Если Future уже завершён (done), возбуждается исключение InvalidStateError.

done()

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

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

cancelled()

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

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

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

add_done_callback(callback, *, context=None)

Добавляет обратный вызов, который будет выполнен после завершения Future (done).

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

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

Необязательный аргумент context, доступный только по ключевому слову, позволяет указать пользовательский объект contextvars.Context, в котором будет выполняться callback. Если 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(msg=None)

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

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

Необязательный строковый аргумент msg передаётся в качестве аргумента исключению CancelledError, которое возбуждается при ожидании отменённого Future.

Изменено в версии 3.9: Добавлен параметр msg.

exception()

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

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

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

Если Future ещё не завершён (done), этот метод возбуждает исключение 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())