`asyncio-future.md`

206 строк · 16.5 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.14/library/asyncio-future.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Future89**Исходный код:** [Lib/asyncio/futures.py](https://python-all.ru/src/3.14/Lib/asyncio/futures.py), [Lib/asyncio/base\_futures.py](https://python-all.ru/src/3.14/Lib/asyncio/base_futures.py)1011---1213*Future*-объекты используются для связи **низкоуровневого кода на основе колбэков** с высокоуровневым кодом async/await.1415## Функции Future1617#### `asyncio.isfuture(obj)`1819Возвращает `True`, если *obj* – это:2021- экземпляр [`asyncio.Future`](https://python-all.ru/3.14/library/asyncio-future.html#asyncio.Future),22- экземпляр [`asyncio.Task`](https://python-all.ru/3.14/library/asyncio-task.html#asyncio.Task),23- Future-подобный объект с атрибутом `_asyncio_future_blocking`.2425Добавлено в версии 3.5.2627#### `asyncio.ensure_future(obj, *, loop=None)`2829Возвращает:3031- *obj* как есть, если *obj* – [`Future`](https://python-all.ru/3.14/library/asyncio-future.html#asyncio.Future), [`Task`](https://python-all.ru/3.14/library/asyncio-task.html#asyncio.Task) или Future-подобный объект (проверка выполняется с помощью [`isfuture()`](https://python-all.ru/3.14/library/asyncio-future.html#asyncio.isfuture)).32- объект [`Task`](https://python-all.ru/3.14/library/asyncio-task.html#asyncio.Task), оборачивающий *obj*, если *obj* – корутина (проверка выполняется с помощью [`iscoroutine()`](https://python-all.ru/3.14/library/asyncio-task.html#asyncio.iscoroutine)); в этом случае корутина будет запланирована через `ensure_future()`.33- объект [`Task`](https://python-all.ru/3.14/library/asyncio-task.html#asyncio.Task), который будет ожидать *obj*, если *obj* является ожидаемым объектом (проверка выполняется с помощью [`inspect.isawaitable()`](https://python-all.ru/3.14/library/inspect.html#inspect.isawaitable)).3435Если *obj* не является ни одним из вышеперечисленных, возбуждается [`TypeError`](https://python-all.ru/3.14/library/exceptions.html#TypeError).3637> **Важно**38>39> Сохраняйте ссылку на результат этой функции, чтобы избежать исчезновения задачи во время выполнения.40>41> Также см. функцию [`create_task()`](https://python-all.ru/3.14/library/asyncio-task.html#asyncio.create_task) – предпочтительный способ создания новых задач, или используйте [`asyncio.TaskGroup`](https://python-all.ru/3.14/library/asyncio-task.html#asyncio.TaskGroup), которая внутренне хранит ссылку на задачу.4243Изменено в версии 3.5.1: Функция принимает любой [ожидаемый](https://python-all.ru/3.14/glossary.html#term-awaitable) объект.4445Устарело с версии 3.10: Предупреждение об устаревании выводится, если *obj* не является Future-подобным объектом и *loop* не указан, и нет работающего цикла событий.4647#### `asyncio.wrap_future(future, *, loop=None)`4849Оборачивает объект [`concurrent.futures.Future`](https://python-all.ru/3.14/library/concurrent.futures.html#concurrent.futures.Future) в объект [`asyncio.Future`](https://python-all.ru/3.14/library/asyncio-future.html#asyncio.Future).5051Устарело с версии 3.10: Предупреждение об устаревании выводится, если *future* не является Future-подобным объектом и *loop* не указан, и нет работающего цикла событий.5253## Объект Future5455#### `class asyncio.Future(*, loop=None)`5657Future представляет собой окончательный результат асинхронной операции. Не потокобезопасен.5859Future – это [ожидаемый](https://python-all.ru/3.14/glossary.html#term-awaitable) объект. Корутины могут ожидать объекты Future, пока у них не будет установлен результат или исключение, или пока они не будут отменены. Future можно ожидать несколько раз, и результат будет одинаковым.6061Обычно Futures используются для того, чтобы низкоуровневый код на основе колбэков (например, в протоколах, реализованных с помощью asyncio [транспорты](https://python-all.ru/3.14/library/asyncio-protocol.html#asyncio-transports-protocols)) мог взаимодействовать с высокоуровневым кодом async/await.6263Эмпирическое правило: никогда не предоставлять объекты Future в пользовательских API, а рекомендуемый способ создания объекта Future – вызвать [`loop.create_future()`](https://python-all.ru/3.14/library/asyncio-eventloop.html#asyncio.loop.create_future). Таким образом, альтернативные реализации цикла событий могут внедрять свои собственные оптимизированные реализации объекта Future.6465Futures являются [обобщёнными](https://python-all.ru/3.14/library/typing.html#generics) относительно типа их результатов.6667Изменено в версии 3.7: Добавлена поддержка модуля [`contextvars`](https://python-all.ru/3.14/library/contextvars.html#module-contextvars).6869Устарело с версии 3.10: Предупреждение об устаревании выводится, если *loop* не указан и нет работающего цикла событий.7071#### `result()`7273Возвращает результат объекта Future.7475Если Future находится в состоянии *done* и имеет результат, установленный методом [`set_result()`](https://python-all.ru/3.14/library/asyncio-future.html#asyncio.Future.set_result), возвращается значение результата.7677Если Future находится в состоянии *done* и имеет исключение, установленное методом [`set_exception()`](https://python-all.ru/3.14/library/asyncio-future.html#asyncio.Future.set_exception), этот метод возбуждает это исключение.7879Если Future был *отменён*, этот метод возбуждает исключение [`CancelledError`](https://python-all.ru/3.14/library/asyncio-exceptions.html#asyncio.CancelledError).8081Если результат Future ещё недоступен, этот метод возбуждает исключение [`InvalidStateError`](https://python-all.ru/3.14/library/asyncio-exceptions.html#asyncio.InvalidStateError).8283#### `set_result(result)`8485Помечает Future как *done* и устанавливает его результат.8687Возбуждает ошибку [`InvalidStateError`](https://python-all.ru/3.14/library/asyncio-exceptions.html#asyncio.InvalidStateError), если Future уже находится в состоянии *done*.8889#### `set_exception(exception)`9091Помечает Future как *done* и устанавливает исключение.9293Возбуждает ошибку [`InvalidStateError`](https://python-all.ru/3.14/library/asyncio-exceptions.html#asyncio.InvalidStateError), если Future уже находится в состоянии *done*.9495#### `done()`9697Возвращает `True`, если Future находится в состоянии *done*.9899Future находится в состоянии *done*, если оно было *отменено* или если у него есть результат или исключение, установленные вызовами [`set_result()`](https://python-all.ru/3.14/library/asyncio-future.html#asyncio.Future.set_result) или [`set_exception()`](https://python-all.ru/3.14/library/asyncio-future.html#asyncio.Future.set_exception).100101#### `cancelled()`102103Возвращает `True`, если Future был *отменён*.104105Этот метод обычно используется для проверки того, не был ли Future *отменён*, перед установкой результата или исключения:106107```python108if not fut.cancelled():109    fut.set_result(42)110```111112#### `add_done_callback(callback, *, context=None)`113114Добавляет колбэк, который будет выполнен, когда Future перейдёт в состояние *done*.115116*Колбэк* вызывается с объектом Future в качестве единственного аргумента.117118Если Future уже находится в состоянии *done* на момент вызова этого метода, колбэк планируется с помощью [`loop.call_soon()`](https://python-all.ru/3.14/library/asyncio-eventloop.html#asyncio.loop.call_soon).119120Необязательный аргумент *context* (только ключевой) позволяет указать пользовательский [`contextvars.Context`](https://python-all.ru/3.14/library/contextvars.html#contextvars.Context) для выполнения *колбэка*. Если *context* не указан, используется текущий контекст.121122[`functools.partial()`](https://python-all.ru/3.14/library/functools.html#functools.partial) можно использовать для передачи параметров колбэку, например:123124```python125# Вызвать 'print("Future:", fut)', когда "fut" будет завершён.126fut.add_done_callback(127    functools.partial(print, "Future:"))128```129130Изменено в версии 3.7: Добавлен параметр *context* (только ключевой). Подробнее см. [**PEP 567**](https://python-all.ru/3.14/library/asyncio-future.html).131132#### `remove_done_callback(callback)`133134Удаляет *колбэк* из списка колбэков.135136Возвращает количество удалённых колбэков – обычно 1, если только колбэк не был добавлен более одного раза.137138#### `cancel(msg=None)`139140Отменяет Future и планирует выполнение колбэков.141142Если Future уже *завершён* или *отменён*, вернуть `False`. Иначе перевести Future в состояние *отменён*, запланировать колбэки и вернуть `True`.143144Необязательный строковый аргумент *msg* передаётся в качестве аргумента исключению [`CancelledError`](https://python-all.ru/3.14/library/asyncio-exceptions.html#asyncio.CancelledError), которое возбуждается при ожидании отменённого Future.145146Изменено в версии 3.9: Добавлен параметр *msg*.147148#### `exception()`149150Возвращает исключение, которое было установлено для этого Future.151152Исключение (или `None`, если исключение не было установлено) возвращается только если Future *завершён*.153154Если Future был *отменён*, этот метод возбуждает исключение [`CancelledError`](https://python-all.ru/3.14/library/asyncio-exceptions.html#asyncio.CancelledError).155156Если Future ещё не *завершён*, этот метод возбуждает исключение [`InvalidStateError`](https://python-all.ru/3.14/library/asyncio-exceptions.html#asyncio.InvalidStateError).157158#### `get_loop()`159160Возвращает цикл событий, к которому привязан объект Future.161162Добавлено в версии 3.7.163164В этом примере создаётся объект Future, создаётся и планируется асинхронная задача для установки результата Future, и выполняется ожидание, пока Future не получит результат:165166```python167async def set_after(fut, delay, value):168    # Приостановиться на *delay* секунд.169    await asyncio.sleep(delay)170171    # Установить *value* в качестве результата Future *fut*.172    fut.set_result(value)173174async def main():175    # Получить текущий цикл событий.176    loop = asyncio.get_running_loop()177178    # Создать новый объект Future.179    fut = loop.create_future()180181    # Запустить корутину "set_after()" в параллельной задаче.182    # Мы используем низкоуровневый API "loop.create_task()", поскольку183    # у нас уже есть ссылка на цикл событий.184    # В противном случае можно было бы просто использовать "asyncio.create_task()".185    loop.create_task(186        set_after(fut, 1, '... world'))187188    print('hello ...')189190    # Ожидать, пока у *fut* не появится результат (1 секунда), и вывести его.191    print(await fut)192193asyncio.run(main())194```195196> **Важно**197>198> Объект Future был спроектирован так, чтобы имитировать [`concurrent.futures.Future`](https://python-all.ru/3.14/library/concurrent.futures.html#concurrent.futures.Future). Ключевые отличия включают:199>200> - в отличие от asyncio Future, экземпляры [`concurrent.futures.Future`](https://python-all.ru/3.14/library/concurrent.futures.html#concurrent.futures.Future) нельзя ожидать.201> - [`asyncio.Future.result()`](https://python-all.ru/3.14/library/asyncio-future.html#asyncio.Future.result) и [`asyncio.Future.exception()`](https://python-all.ru/3.14/library/asyncio-future.html#asyncio.Future.exception) не принимают аргумент *timeout*.202> - [`asyncio.Future.result()`](https://python-all.ru/3.14/library/asyncio-future.html#asyncio.Future.result) и [`asyncio.Future.exception()`](https://python-all.ru/3.14/library/asyncio-future.html#asyncio.Future.exception) возбуждают исключение [`InvalidStateError`](https://python-all.ru/3.14/library/asyncio-exceptions.html#asyncio.InvalidStateError), когда Future не *завершён*.203> - Колбэки, зарегистрированные с помощью [`asyncio.Future.add_done_callback()`](https://python-all.ru/3.14/library/asyncio-future.html#asyncio.Future.add_done_callback), вызываются не сразу. Вместо этого они планируются с помощью [`loop.call_soon()`](https://python-all.ru/3.14/library/asyncio-eventloop.html#asyncio.loop.call_soon).204> - asyncio Future несовместим с функциями [`concurrent.futures.wait()`](https://python-all.ru/3.14/library/concurrent.futures.html#concurrent.futures.wait) и [`concurrent.futures.as_completed()`](https://python-all.ru/3.14/library/concurrent.futures.html#concurrent.futures.as_completed).205> - [`asyncio.Future.cancel()`](https://python-all.ru/3.14/library/asyncio-future.html#asyncio.Future.cancel) принимает необязательный аргумент `msg`, а [`concurrent.futures.Future.cancel()`](https://python-all.ru/3.14/library/concurrent.futures.html#concurrent.futures.Future.cancel) – нет.206