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

Функции работы с задачами

asyncio.isfuture(obj)

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

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

Добавлена в версии 3.5.

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

Возвращает:

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

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

Важно

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

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

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

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

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

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

Устарело начиная с версии 3.10: Выводится предупреждение об устаревании, если 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 как завершённый и устанавливает его результат.

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