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

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

Важно

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

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

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

Устарело начиная с версии 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 — это объект ожидаемого типа. Сопрограммы могут ожидать объекты Future, пока для них не будет установлен результат или исключение либо пока они не будут отменены. Ожидать один и тот же Future можно несколько раз; результат при этом будет одинаковым.

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

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

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

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

result()

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

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

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

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

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

set_result(result)

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

Если Future уже завершён, возникает ошибка InvalidStateError.

set_exception(exception)

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

Если Future уже завершён, возникает ошибка InvalidStateError.

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 будет завершён.

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

Если на момент вызова этого метода Future уже завершён, обратный вызов планируется с помощью 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 уже завершён или отменён, возвращает False. В противном случае состояние Future меняется на отменённое, планируется выполнение обратных вызовов, и возвращается True.

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

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())