Асинхронные задачи

Функции 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 является awaitable объектом. Корутины могут ожидать 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 как выполненный и задаёт его результат.

Вызывает ошибку 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(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())