Цикл обработки событий

Запуск и остановка цикла

loop.run_until_complete(future)

Запуск до завершения future (экземпляра Future).

Если аргументом является объект корутины, он неявно планируется для выполнения как asyncio.Task.

Возвращает результат Future или поднимает исключение.

loop.run_forever()

Запуск цикла событий до вызова stop().

Если stop() вызывается до run_forever(), цикл проверит I/O-селектор один раз с таймаутом 0, выполнит все обратные вызовы, запланированные в ответ на I/O-события (и те, которые уже были запланированы), а затем завершится.

Если stop() вызывается во время выполнения run_forever(), цикл выполнит текущую партию обратных вызовов и затем завершится. Обратите внимание, что новые обратные вызовы, запланированные обратными вызовами, в этом случае не будут выполнены; вместо этого они будут выполнены в следующий раз, когда будет вызван run_forever() или run_until_complete().

loop.stop()

Остановка цикла событий.

loop.is_running()

Возвращает True, если цикл событий в данный момент запущен.

loop.is_closed()

Возвращает True, если цикл событий был закрыт.

loop.close()

Закрытие цикла событий.

Цикл не должен быть запущен, когда вызывается эта функция. Все ожидающие обратные вызовы будут отброшены.

Этот метод очищает все очереди и завершает выполнение исполнителя, но не ждет завершения исполнения.

Этот метод идемпотентен и необратим. После закрытия цикла событий не следует вызывать другие методы.

coroutine loop.shutdown_asyncgens()

Планирует закрытие всех открытых в настоящее время асинхронных генераторов с вызовом aclose(). После вызова этого метода цикл событий будет выдавать предупреждение, если новый асинхронный генератор будет итерирован. Это следует использовать для надежной финализации всех запланированных асинхронных генераторов.

Обратите внимание, что нет необходимости вызывать эту функцию при использовании asyncio.run().

Пример:

try:
    loop.run_forever()
finally:
    loop.run_until_complete(loop.shutdown_asyncgens())
    loop.close()

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

coroutine loop.shutdown_default_executor(timeout=None)

Планирует закрытие исполнителя по умолчанию и ждет, пока он присоединит все потоки в ThreadPoolExecutor. После вызова этого метода использование исполнителя по умолчанию с loop.run_in_executor() будет вызывать RuntimeError.

Параметр timeout задаёт время (в секундах, float), которое будет дано исполнителю для завершения присоединения. По умолчанию, None, исполнителю предоставляется неограниченное время.

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

Примечание

Не вызывайте этот метод при использовании asyncio.run(), так как последний автоматически обрабатывает завершение исполнителя по умолчанию.

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

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

Планирование обратных вызовов

loop.call_soon(callback, *args, context=None)

Планирует вызов обратного вызова callback с аргументами args на следующей итерации цикла событий.

Возвращает экземпляр asyncio.Handle, который можно использовать для отмены обратного вызова позже.

Обратные вызовы вызываются в порядке регистрации. Каждый обратный вызов будет вызван ровно один раз.

Необязательный ключевой параметр context задаёт пользовательский contextvars.Context для выполнения callback. Обратные вызовы используют текущий контекст, если параметр context не предоставлен.

В отличие от call_soon_threadsafe(), этот метод не потокобезопасен.

loop.call_soon_threadsafe(callback, *args, context=None)

Потокобезопасный вариант call_soon(). При планировании обратных вызовов из другого потока необходимо использовать эту функцию, так как call_soon() не потокобезопасна.

Вызывает RuntimeError, если вызывается в цикле, который был закрыт. Это может произойти во вторичном потоке, когда основное приложение завершает работу.

См. раздел конкурентности и многопоточности документации.

Изменено в версии 3.7: Добавлен необязательный ключевой параметр context. См. PEP 567 для получения более подробной информации.

# will schedule "print("Hello", flush=True)"
loop.call_soon(
    functools.partial(print, "Hello", flush=True))

Планирование отложенных обратных вызовов

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

loop.call_later(delay, callback, *args, context=None)

Запланировать вызов callback через заданное количество секунд delay (может быть целым или дробным числом).

Возвращается экземпляр asyncio.TimerHandle, который можно использовать для отмены обратного вызова.

callback будет вызван ровно один раз. Если два обратных вызова запланированы на одно и то же время, порядок их вызова не определён.

Дополнительные позиционные аргументы args будут переданы обратному вызову при его вызове. Если вы хотите, чтобы обратный вызов вызывался с именованными аргументами, используйте functools.partial().

Необязательный именованный аргумент context позволяет указать пользовательский contextvars.Context для выполнения callback. Если context не указан, используется текущий контекст.

Изменено в версии 3.7: Добавлен именованный параметр context. Дополнительные сведения см. в PEP 567.

Изменено в версии 3.8: В Python 3.7 и ранее с реализацией цикла событий по умолчанию delay не мог превышать одного дня. Эта проблема исправлена в Python 3.8.

loop.call_at(when, callback, *args, context=None)

Запланировать вызов callback в заданный абсолютный момент времени when (целое или дробное число), используя ту же временную отметку, что и loop.time().

Поведение этого метода такое же, как у call_later().

Возвращается экземпляр asyncio.TimerHandle, который можно использовать для отмены обратного вызова.

Изменено в версии 3.7: Добавлен именованный параметр context. Дополнительные сведения см. в PEP 567.

Изменено в версии 3.8: В Python 3.7 и ранее разница между when и текущим временем не могла превышать одного дня. Эта проблема исправлена в Python 3.8.

loop.time()

Возвращает текущее время в виде значения float по внутренним монотонным часам цикла событий.

Создание объектов Future и Task

loop.create_future()

Создаёт объект asyncio.Future, привязанный к циклу событий.

Это предпочтительный способ создания объектов Future в asyncio. Это позволяет сторонним циклам событий предоставлять альтернативные реализации объекта Future (с лучшей производительностью или инструментировкой).

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

loop.create_task(coro, *, name=None, context=None)

Планирует выполнение корутины coro. Возвращает объект Task.

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

Если аргумент name указан и не None, он устанавливается как имя задачи с помощью Task.set_name().

Необязательный именованный аргумент context позволяет указать пользовательский contextvars.Context для выполнения coro. При отсутствии context создается копия текущего контекста.

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

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

loop.set_task_factory(factory)

Установить фабрику задач, которая будет использоваться методом loop.create_task().

Если factory None, будет установлена фабрика задач по умолчанию. В противном случае, factory должна быть функцией с сигнатурой, соответствующей (loop, coro, context=None), где loop — ссылка на активный цикл событий, а coro — объект корутины. Функция должна возвращать совместимый с asyncio.Future объект.

loop.get_task_factory()

Возвращает фабрику задач или None, если используется фабрика по умолчанию.

Открытие сетевых подключений

coroutine loop.create_connection(protocol_factory, host=None, port=None, *, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, happy_eyeballs_delay=None, interleave=None, all_errors=False)

Открытие потокового транспортного соединения с заданным адресом, указанным host и port.

Семейство сокетов может быть либо AF_INET, либо AF_INET6 в зависимости от host (или аргумента family, если он предоставлен).

Тип сокета будет SOCK_STREAM.

protocol_factory должно быть вызываемым объектом, возвращающим реализацию протокола asyncio.

Этот метод попытается установить подключение в фоновом режиме. При успехе он возвращает пару (transport, protocol).

Хронологический обзор базовой операции:

1. Подключение устанавливается, и для него создается транспорт.
2. protocol_factory вызывается без аргументов и ожидается, что он вернет экземпляр протокола.
3. Экземпляр протокола связывается с транспортом, вызывая его метод connection_made().
4. В случае успеха возвращается кортеж (transport, protocol).

Созданный транспорт представляет собой двусторонний поток, реализация которого зависит от конкретной реализации.

Другие аргументы:

• ssl: если указано и не равно false, создается транспорт SSL/TLS (по умолчанию создается обычный TCP-транспорт). Если ssl — объект ssl.SSLContext, этот контекст используется для создания транспорта; если ssl равно True, используется контекст по умолчанию, возвращаемый из ssl.create_default_context().

  См. также

  Рекомендации по безопасности SSL/TLS

• server_hostname устанавливает или переопределяет имя хоста, с которым будет сравниваться сертификат целевого сервера. Должен передаваться только если ssl не None. По умолчанию используется значение аргумента host. Если host пустое, по умолчанию нет значения, и вы должны указать значение для server_hostname. Если server_hostname пустая строка, сопоставление имени хоста отключено (что представляет серьезную угрозу безопасности, позволяющую потенциальные атаки «человек посередине»).
• family, proto, flags — необязательные семейство адреса, протокол и флаги, которые передаются в getaddrinfo() для разрешения host. Если указаны, все они должны быть целыми числами из соответствующих констант модуля socket.
• happy_eyeballs_delay, если задано, включает Happy Eyeballs для этого подключения. Это должно быть число с плавающей точкой, представляющее количество секунд ожидания завершения попытки подключения перед началом следующей попытки параллельно. Это «Задержка попытки подключения», как определено в RFC 8305. Рекомендуемое разумное значение по умолчанию, рекомендованное RFC, составляет 0.25 (250 миллисекунд).
• interleave управляет повторной упорядочиванием адресов, когда имя хоста разрешается на несколько IP-адресов. Если 0 или не указано, повторное упорядочение не выполняется, и адреса пытаются в порядке, возвращаемом getaddrinfo(). Если указано положительное целое число, адреса переупорядочиваются по семейству адресов, и указанное целое число интерпретируется как «Количество семейств адресов в первую очередь», как определено в RFC 8305. Значение по умолчанию составляет 0, если happy_eyeballs_delay не указано, и 1, если оно указано.

• sock, если указан, должен быть существующим, уже подключенным объектом socket.socket, который будет использоваться транспортом. Если sock задан, не должны быть указаны host, port, family, proto, flags, happy_eyeballs_delay, interleave и local_addr.

  Примечание

  Аргумент sock передает транспортному средству право собственности на сокет. Для закрытия сокета вызовите метод транспорта close().

• local_addr, если указан, представляет собой кортеж (local_host, local_port), используемый для привязки сокета локально. local_host и local_port ищутся с помощью getaddrinfo(), аналогично host и port.
• ssl_handshake_timeout — (для TLS-соединения) время в секундах, которое нужно подождать завершения рукопожатия TLS перед прерыванием соединения. 60.0 секунд, если None (по умолчанию).
• ssl_shutdown_timeout — время в секундах ожидания завершения закрытия SSL перед прерыванием соединения. 30.0 секунд, если None (по умолчанию).
• all_errors определяет, какие исключения генерируются при невозможности создания соединения. По умолчанию генерируется только одно Exception: первое исключение, если их только одно, или все ошибки имеют одинаковое сообщение, или одно OSError с объединенными сообщениями об ошибках. Если all_errors равно True, будет сгенерировано ExceptionGroup, содержащее все исключения (даже если их только одно).

Изменено в версии 3.5: Добавлена поддержка SSL/TLS в ProactorEventLoop.

Изменено в версии 3.6: Параметр socket.TCP_NODELAY устанавливается по умолчанию для всех TCP-соединений.

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

Изменено в версии 3.8: Добавлены параметры happy_eyeballs_delay и interleave.

Алгоритм Happy Eyeballs: Успех с хостами с двойной стековой системой. Когда путь и протокол IPv4 сервера работают, но путь и протокол IPv6 сервера не работают, клиентское приложение с двойной стековой системой испытывает значительную задержку подключения по сравнению с клиентом только IPv4. Это нежелательно, так как это приводит к худшему пользовательскому опыту клиента с двойной стековой системой. Данный документ определяет требования к алгоритмам, которые уменьшают эту задержку, видимую пользователю, и предоставляет такой алгоритм.

Дополнительная информация: https://datatracker.ietf.org/doc/html/rfc6555

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

Изменено в версии 3.12: Добавлен all_errors.

См. также

Функция open_connection() — это альтернативный API высокого уровня. Она возвращает пару (StreamReader, StreamWriter), которые могут быть использованы непосредственно в коде async/await.

coroutine loop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, *, family=0, proto=0, flags=0, reuse_port=None, allow_broadcast=None, sock=None)

Создать подключение дейтаграммного типа.

Семейство сокетов может быть AF_INET, AF_INET6 или AF_UNIX, в зависимости от host (или аргумента family, если он указан).

Тип сокета будет SOCK_DGRAM.

protocol_factory должно быть вызываемым объектом, возвращающим реализацию протокола.

В случае успеха возвращается кортеж (transport, protocol).

Другие аргументы:

• local_addr, если указан, представляет кортеж (local_host, local_port), используемый для привязки сокета локально. local_host и local_port определяются с помощью getaddrinfo().
• remote_addr, если указан, представляет кортеж (remote_host, remote_port), используемый для подключения сокета к удалённому адресу. remote_host и remote_port определяются с помощью getaddrinfo().
• family, proto, flags — необязательные семейство адресов, протокол и флаги, которые передаются в getaddrinfo() для разрешения host. Если указаны, они должны быть целыми числами, соответствующими константам модуля socket.
• reuse_port указывает ядру разрешить привязку данного конечной точки к тому же порту, что и другие существующие конечные точки, при условии, что все они установили этот флаг при создании. Этот параметр не поддерживается на Windows и некоторых Unix-системах. Если константа socket.SO_REUSEPORT не определена, то эта возможность не поддерживается.
• allow_broadcast указывает ядру разрешить отправку сообщений по широковещательному адресу.

• sock можно указать для использования существующего, уже подключённого объекта socket.socket, который будет использоваться транспортом. Если указан, local_addr и remote_addr должны быть пропущены (должны быть None).

  Примечание

  Аргумент sock передаёт право владения сокетом созданному транспорту. Для закрытия сокета вызовите метод close() транспорта.

См. примеры клиента протокола эхо UDP и сервера протокола эхо UDP.

Изменено в версии 3.4.4: Добавлены параметры family, proto, flags, reuse_address, reuse_port, allow_broadcast и sock.

Изменено в версии 3.8: Добавлена поддержка Windows.

Изменено в версии 3.8.1: Параметр reuse_address больше не поддерживается, так как использование socket.SO_REUSEADDR создаёт значительную проблему безопасности для UDP. Явное указание reuse_address=True вызовет исключение.

Когда несколько процессов с разными идентификаторами пользователя (UID) присваивают сокеты идентичному адресу UDP-сокета с SO_REUSEADDR, входящие пакеты могут случайным образом распределяться между сокетами.

На поддерживаемых платформах можно использовать reuse_port как замену для похожих функций. С reuse_port используется socket.SO_REUSEPORT, что специально предотвращает присвоение сокетов процессами с разными UID тому же адресу сокета.

Изменено в версии 3.11: Параметр reuse_address, отключённый с Python 3.8.1, 3.7.6 и 3.6.10, был полностью удалён.

coroutine loop.create_unix_connection(protocol_factory, path=None, *, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

Создать подключение Unix-доменного сокета.

Семейство сокетов будет AF_UNIX; тип сокета будет SOCK_STREAM.

В случае успеха возвращается кортеж (transport, protocol).

path — имя Unix-доменного сокета, необходимое, если не указан параметр sock. Поддерживаются абстрактные Unix-сокеты, пути str, bytes и Path.

Обратитесь к документации метода loop.create_connection() за информацией об аргументах этого метода.

Доступность: Unix.

Изменено в версии 3.7: Добавлен параметр ssl_handshake_timeout. Параметр path теперь может быть объектом, подобным пути.

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

Создание сетевых серверов

coroutine loop.create_server(protocol_factory, host=None, port=None, *, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None, keep_alive=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, start_serving=True)

Создаёт TCP-сервер (тип сокета SOCK_STREAM), слушающий на порту заданного хоста.

Возвращает объект Server.

Аргументы:

• protocol_factory должен быть вызываемым объектом, возвращающим реализацию протокола.

• Параметр host может принимать несколько типов, определяющих, где сервер будет слушать:

  • Если host — строка, TCP-сервер привязывается к одному сетевому интерфейсу, указанному в host.
  • Если host — последовательность строк, TCP-сервер привязывается ко всем сетевым интерфейсам, указанным в последовательности.
  • Если host — пустая строка или None, предполагаются все интерфейсы, и будет возвращён список нескольких сокетов (вероятно, один для IPv4 и другой для IPv6).
• Параметр port может быть задан для указания порта, на котором сервер должен слушать. Если 0 или None (по умолчанию), будет выбран случайный свободный порт (обратите внимание, что если host соответствует нескольким сетевым интерфейсам, для каждого интерфейса будет выбран другой случайный порт).
• family может быть задан как socket.AF_INET или AF_INET6, чтобы принудительно использовать IPv4 или IPv6. Если не задано, family определяется по имени хоста (по умолчанию AF_UNSPEC).
• flags — битовая маска для getaddrinfo().

• sock может быть указан для использования существующего объекта сокета. Если указан, host и port не должны быть указаны.

  Примечание

  Аргумент sock передаёт право собственности на сокет созданному серверу. Для закрытия сокета вызовите метод close() сервера.

• backlog — максимальное количество ожидающих подключений, передаваемое listen() (по умолчанию 100).
• ssl может быть задан как экземпляр SSLContext для включения TLS для принятых подключений.
• reuse_address указывает ядру использовать локальный сокет в состоянии TIME_WAIT, без ожидания его естественного таймаута. Если не указано, автоматически устанавливается в True на Unix.
• reuse_port указывает ядру разрешить этому конечной точке привязываться к тому же порту, что и другие существующие конечные точки, при условии, что все они устанавливают этот флаг при создании. Этот параметр не поддерживается в Windows.
• keep_alive, установленный в True, поддерживает активность подключений, позволяя периодически передавать сообщения.

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

• ssl_handshake_timeout (для TLS-сервера) — время в секундах ожидания завершения TLS-рукопожатия перед прерыванием подключения. 60.0 секунд, если None (по умолчанию).
• ssl_shutdown_timeout — время в секундах ожидания завершения закрытия SSL перед прерыванием подключения. 30.0 секунд, если None (по умолчанию).
• start_serving, установленный в True (по умолчанию), заставляет созданный сервер сразу начинать принимать подключения. При установке в False пользователь должен ожидать Server.start_serving() или Server.serve_forever(), чтобы запустить сервер на приём подключений.

Изменено в версии 3.5: Добавлена поддержка SSL/TLS в ProactorEventLoop.

Изменено в версии 3.5.1: Параметр host может быть последовательностью строк.

Изменено в версии 3.6: Добавлены параметры ssl_handshake_timeout и start_serving. Параметр socket.TCP_NODELAY по умолчанию устанавливается для всех TCP-соединений.

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

См. также

Функция start_server() — это альтернативный API более высокого уровня, который возвращает пару StreamReader и StreamWriter, которые могут использоваться в асинхронном коде.

coroutine loop.create_unix_server(protocol_factory, path=None, *, sock=None, backlog=100, ssl=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, start_serving=True, cleanup_socket=True)

Аналогично loop.create_server(), но работает с семейством сокетов AF_UNIX.

path — имя Unix-доменного сокета, обязательно, если не указан параметр sock. Поддерживаются пути с абстрактными Unix-сокетами, str, bytes и Path.

Если cleanup_socket — true, Unix-сокет автоматически удаляется из файловой системы при закрытии сервера, если сокет не был заменён после создания сервера.

См. документацию метода loop.create_server() для информации об аргументах этого метода.

Доступность: Unix.

Изменено в версии 3.7: Добавлены параметры ssl_handshake_timeout и start_serving. Параметр path теперь может быть объектом Path.

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

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

coroutine loop.connect_accepted_socket(protocol_factory, sock, *, ssl=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

Оборачивает уже принятое соединение в пару транспорт/протокол.

Этот метод может использоваться серверами, которые принимают подключения вне asyncio, но используют asyncio для их обработки.

Параметры:

• protocol_factory должен быть вызываемым объектом, возвращающим реализацию протокола.

• sock — существующий объект сокета, возвращённый из socket.accept.

  Примечание

  Аргумент sock передаёт право собственности на сокет созданному транспорту. Для закрытия сокета вызовите метод close() транспорта.

• ssl может быть задан как экземпляр SSLContext для включения SSL для принятых подключений.
• ssl_handshake_timeout (для SSL-соединения) — время в секундах ожидания завершения SSL-рукопожатия перед прерыванием подключения. 60.0 секунд, если None (по умолчанию).
• ssl_shutdown_timeout — время в секундах ожидания завершения закрытия SSL перед прерыванием подключения. 30.0 секунд, если None (по умолчанию).

Возвращает пару (transport, protocol).

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

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

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

Передача файлов

coroutine loop.sendfile(transport, file, offset=0, count=None, *, fallback=True)

Отправляет файл по транспорту. Возвращает общее количество отправленных байтов.

Метод использует высокопроизводительный метод os.sendfile(), если он доступен.

Файл должен быть объектом обычного файла, открытым в двоичном режиме.

Смещение указывает, с какой позиции начать чтение файла. Если задано, количество — это общее количество байтов для передачи, а не передача файла до достижения EOF. Позиция файла всегда обновляется, даже при возникновении ошибки в этом методе, и file.tell() можно использовать для получения фактического количества отправленных байтов.

Fallback, установленное на True, заставляет asyncio вручную читать и отправлять файл, когда платформа не поддерживает системный вызов sendfile (например, Windows или сокет SSL на Unix).

Возникает SendfileNotAvailableError, если система не поддерживает вызов sendfile и fallback установлено на False.

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

Обновление TLS

coroutine loop.start_tls(transport, protocol, sslcontext, *, server_side=False, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

Обновляет существующее подключение на основе транспорта до TLS.

Создает экземпляр кодера/декодера TLS и вставляет его между транспортом и протоколом. Кодер/декодер реализует как протокол со стороны транспорта, так и транспорт со стороны протокола.

Возвращает созданный экземпляр с двумя интерфейсами. После await протокол должен перестать использовать исходный транспорт и общаться только с возвращенным объектом, потому что кодер кэширует данные со стороны протокола и время от времени обменивается дополнительными пакетами сеанса TLS с транспортом.

В некоторых ситуациях (например, когда передаваемый транспорт уже закрывается) это может вернуть None.

Параметры:

• экземпляры транспорта и протокола, которые возвращают методы, такие как create_server() и create_connection().
• sslcontext: настроенный экземпляр SSLContext.
• server_side передать True, когда обновляется подключение на стороне сервера (как то, что создано create_server()).
• server_hostname: устанавливает или переопределяет имя хоста, по которому будет проверяться сертификат целевого сервера.
• ssl_handshake_timeout — время в секундах ожидания завершения рукопожатия TLS перед прерыванием соединения. 60.0 секунд, если None (по умолчанию).
• ssl_shutdown_timeout — время в секундах ожидания завершения закрытия SSL перед прерыванием соединения. 30.0 секунд, если None (по умолчанию).

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

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

Отслеживание дескрипторов файлов

loop.add_reader(fd, callback, *args)

Начинает отслеживание дескриптора файла fd на доступность для чтения и вызывает callback со заданными аргументами, как только fd станет доступным для чтения.

loop.remove_reader(fd)

Останавливает отслеживание дескриптора файла fd на доступность для чтения. Возвращает True, если fd ранее отслеживался для чтения.

loop.add_writer(fd, callback, *args)

Начинает отслеживание дескриптора файла fd на доступность для записи и вызывает callback со заданными аргументами, как только fd станет доступным для записи.

Используйте functools.partial() для передачи ключевых аргументов в callback.

loop.remove_writer(fd)

Останавливает отслеживание дескриптора файла fd на доступность для записи. Возвращает True, если fd ранее отслеживался для записи.

См. также раздел Поддержка платформ для некоторых ограничений этих методов.

Работа с объектами сокетов напрямую

В общем случае, реализации протоколов, использующие транспортно-ориентированные API, такие как loop.create_connection() и loop.create_server(), быстрее, чем реализации, работающие напрямую с сокетами. Однако, существуют некоторые случаи использования, когда производительность не является критичной, и работа с socket объектами напрямую более удобна.

coroutine loop.sock_recv(sock, nbytes)

Принять до nbytes байтов из sock. Асинхронная версия socket.recv().

Возвращает полученные данные в виде объекта bytes.

sock должен быть неблокирующим сокетом.

Изменено в версии 3.7: Несмотря на то, что этот метод всегда был документирован как метод корутины, в версиях до Python 3.7 он возвращал Future. Начиная с Python 3.7 это метод корутина.

coroutine loop.sock_recv_into(sock, buf)

Принимает данные из sock в буфер buf. Моделируется по блокирующему методу socket.recv_into().

Возвращает количество байтов, записанных в буфер.

sock должен быть неблокирующим сокетом.

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

coroutine loop.sock_recvfrom(sock, bufsize)

Принимает дейтаграмму размером до bufsize из sock. Асинхронная версия socket.recvfrom().

Возвращает кортеж (полученные данные, удалённый адрес).

sock должен быть неблокирующим сокетом.

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

coroutine loop.sock_recvfrom_into(sock, buf, nbytes=0)

Принимает дейтаграмму размером до nbytes из sock в buf. Асинхронная версия socket.recvfrom_into().

Возвращает кортеж (количество полученных байтов, удалённый адрес).

sock должен быть неблокирующим сокетом.

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

coroutine loop.sock_sendall(sock, data)

Отправляет data на сокет sock. Асинхронная версия socket.sendall().

Этот метод продолжает отправку данных на сокет, пока либо все данные из data не будут отправлены, либо произойдёт ошибка. При успешной отправке возвращается None. В случае ошибки генерируется исключение. Кроме того, нет способа определить, сколько данных, если таковые имеются, было успешно обработано принимающей стороной подключения.

sock должен быть неблокирующим сокетом.

Изменено в версии 3.7: Несмотря на то, что метод всегда документировался как метод корутины, до Python 3.7 он возвращал Future. Начиная с Python 3.7, это метод корутина.

coroutine loop.sock_sendto(sock, data, address)

Отправляет дейтаграмму из sock на address. Асинхронная версия socket.sendto().

Возвращает количество отправленных байтов.

sock должен быть неблокирующим сокетом.

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

coroutine loop.sock_connect(sock, address)

Устанавливает соединение sock с удалённым сокетом по адресу address.

Асинхронная версия socket.connect().

sock должен быть неблокирующим сокетом.

Изменено в версии 3.5.2: address больше не нуждается в разрешении. sock_connect попытается проверить, уже ли разрешён адрес, вызвав socket.inet_pton(). Если нет, будет использоваться loop.getaddrinfo() для разрешения адреса.

См. также

loop.create_connection() и asyncio.open_connection().

coroutine loop.sock_accept(sock)

Принимает подключение. Моделируется по блокирующему методу socket.accept().

Сокет должен быть привязан к адресу и ожидать подключений. Результат — пара (conn, address), где conn — новый объект сокета, используемый для отправки и получения данных по подключению, а address — адрес, привязанный к сокету на другом конце подключения.

sock должен быть неблокирующим сокетом.

Изменено в версии 3.7: Несмотря на то, что метод всегда документировался как метод корутины, до Python 3.7 он возвращал Future. Начиная с Python 3.7, это метод корутина.

См. также

loop.create_server() и start_server().

coroutine loop.sock_sendfile(sock, file, offset=0, count=None, *, fallback=True)

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

Асинхронная версия socket.sendfile().

sock должен быть неблокирующим сокетом типа socket.SOCK_STREAM socket.

file должен быть объектом файла, открытым в двоичном режиме.

offset указывает, с какой позиции начать чтение файла. Если указано, count — общее количество байтов для передачи вместо отправки файла до достижения EOF. Позиция файла всегда обновляется, даже когда этот метод вызывает ошибку, и file.tell() может быть использован для получения фактического количества отправленных байтов.

fallback, если установлено в True, заставляет asyncio вручную читать и отправлять файл, когда платформа не поддерживает системный вызов sendfile (например, Windows или SSL-сокет на Unix).

Вызывает SendfileNotAvailableError, если система не поддерживает системный вызов sendfile, и fallback установлено в False.

sock должен быть неблокирующим сокетом.

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

DNS

coroutine loop.getaddrinfo(host, port, *, family=0, type=0, proto=0, flags=0)

Асинхронная версия socket.getaddrinfo().

coroutine loop.getnameinfo(sockaddr, flags=0)

Асинхронная версия socket.getnameinfo().

Работа с каналами

coroutine loop.connect_read_pipe(protocol_factory, pipe)

Регистрация входного конца канала pipe в цикле событий.

protocol_factory должно быть вызываемым объектом, возвращающим реализацию протокола asyncio-протокол.

pipe — это объект, подобный файлу.

Возвращает пару (transport, protocol), где transport поддерживает интерфейс ReadTransport, а protocol — объект, созданный по protocol_factory.

С циклом событий SelectorEventLoop канал pipe устанавливается в режим без ожидания.

coroutine loop.connect_write_pipe(protocol_factory, pipe)

Регистрация выходного конца канала pipe в цикле событий.

protocol_factory должно быть вызываемым объектом, возвращающим реализацию протокола asyncio-протокол.

pipe — объект, подобный файлу.

Возвращает пару (transport, protocol), где transport поддерживает интерфейс WriteTransport, а protocol — объект, созданный по protocol_factory.

С циклом событий SelectorEventLoop канал pipe устанавливается в режим без ожидания.

Сигналы Unix

loop.add_signal_handler(signum, callback, *args)

Устанавливает callback в качестве обработчика сигнала signum.

Обработчик будет вызван циклом loop вместе с другими очередями обратных вызовов и выполняемыми корутинами этого цикла событий. В отличие от обработчиков сигналов, зарегистрированных с помощью signal.signal(), обработчик, зарегистрированный с помощью этой функции, может взаимодействовать с циклом событий.

Вызовет ValueError, если номер сигнала недопустим или неперехватываем. Вызовет RuntimeError, если возникла проблема с настройкой обработчика.

Используйте functools.partial(), чтобы передать ключевые аргументы в callback.

Как и signal.signal(), эта функция должна вызываться в основном потоке.

loop.remove_signal_handler(sig)

Удаляет обработчик сигнала sig.

Возвращает True, если обработчик сигнала был удалён, или False, если обработчик сигнала не был установлен для данного сигнала.

Доступность: Unix.

Выполнение кода в пулах потоков или процессов

awaitable loop.run_in_executor(executor, func, *args)

Указывает на то, что func будет вызван в указанном исполнителе.

Аргумент executor должен быть экземпляром concurrent.futures.Executor. Если executor равен None, используется исполнители по умолчанию. Исполнитель по умолчанию может быть установлен с помощью loop.set_default_executor(), иначе concurrent.futures.ThreadPoolExecutor будет лениво инициализирован и использован run_in_executor() при необходимости.

Пример:

import asyncio
import concurrent.futures

def blocking_io():
    # File operations (such as logging) can block the
    # event loop: run them in a thread pool.
    with open('/dev/urandom', 'rb') as f:
        return f.read(100)

def cpu_bound():
    # CPU-bound operations will block the event loop:
    # in general it is preferable to run them in a
    # process pool.
    return sum(i * i for i in range(10 ** 7))

async def main():
    loop = asyncio.get_running_loop()

    ## Options:

    # 1. Run in the default loop's executor:
    result = await loop.run_in_executor(
        None, blocking_io)
    print('default thread pool', result)

    # 2. Run in a custom thread pool:
    with concurrent.futures.ThreadPoolExecutor() as pool:
        result = await loop.run_in_executor(
            pool, blocking_io)
        print('custom thread pool', result)

    # 3. Run in a custom process pool:
    with concurrent.futures.ProcessPoolExecutor() as pool:
        result = await loop.run_in_executor(
            pool, cpu_bound)
        print('custom process pool', result)

if __name__ == '__main__':
    asyncio.run(main())

Обратите внимание, что для варианта 3 требуется защитный блок (if __name__ == '__main__') из-за особенностей multiprocessing, который используется ProcessPoolExecutor. См. Безопасный импорт основного модуля.

Этот метод возвращает объект asyncio.Future.

Используйте functools.partial(), чтобы передать ключевые аргументы в func.

Изменено в версии 3.5.3: loop.run_in_executor() больше не настраивает max_workers исполнителя пула потоков, который он создаёт, вместо этого предоставляя исполнителю пула потоков (ThreadPoolExecutor) возможность установить значение по умолчанию.

loop.set_default_executor(executor)

Устанавливает executor в качестве исполнителя по умолчанию, используемого run_in_executor(). executor должен быть экземпляром ThreadPoolExecutor.

Изменено в версии 3.11: executor должен быть экземпляром ThreadPoolExecutor.

Обработка ошибок API

Позволяет настраивать, как обрабатываются исключения в цикле событий.

loop.set_exception_handler(handler)

Устанавливает handler в качестве нового обработчика исключений цикла событий.

Если handler равен None, будет установлен обработчик исключений по умолчанию. В противном случае, handler должен быть вызываемым объектом с сигнатурой, соответствующей (loop, context), где loop является ссылкой на активный цикл событий, а context — объект dict, содержащий подробности о возникшем исключении (подробности о контексте см. в документации call_exception_handler()).

Если обработчик вызывается от имени Task или Handle, он выполняется в contextvars.Context этой задачи или обработчика.

Изменено в версии 3.12: Обработчик может вызываться в Context задачи или обработчика, где возникло исключение.

loop.get_exception_handler()

Возвращает текущий обработчик исключений или None, если не был установлен пользовательский обработчик исключений.

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

loop.default_exception_handler(context)

Обработчик исключений по умолчанию.

Вызывается при возникновении исключения, если обработчик исключений не установлен. Его можно вызвать пользовательским обработчиком исключений, для делегирования поведения обработчика по умолчанию.

Параметр context имеет такое же значение, как и в call_exception_handler().

loop.call_exception_handler(context)

Вызывает текущий обработчик исключений цикла событий.

context — объект dict, содержащий следующие ключи (в будущих версиях Python могут быть добавлены новые ключи):

• ‘message’: Сообщение об ошибке;
• ‘exception’ (необязательно): Объект исключения;
• ‘future’ (необязательно): экземпляр asyncio.Future;
• ‘task’ (необязательно): экземпляр asyncio.Task;
• ‘handle’ (необязательно): экземпляр asyncio.Handle;
• ‘protocol’ (необязательно): экземпляр Protocol;
• ‘transport’ (необязательно): экземпляр Transport;
• ‘socket’ (необязательно): экземпляр socket.socket;

• ‘asyncgen’ (необязательно): Асинхронный генератор, вызвавший

  исключение.

Примечание

Этот метод не следует переопределять в подклассах циклов событий. Для пользовательской обработки исключений используйте метод set_exception_handler().

Включение отладочного режима

loop.get_debug()

Получить отладочный режим (bool) цикла событий.

Значение по умолчанию — True, если переменная среды PYTHONASYNCIODEBUG установлена с ненулевым значением, False в противном случае.

loop.set_debug(enabled: bool)

Установить отладочный режим цикла событий.

Изменено в версии 3.7: Теперь можно также использовать новый режим разработки Python для включения отладочного режима.

loop.slow_callback_duration

Этот атрибут можно использовать для установки минимальной продолжительности выполнения в секундах, которая считается «медленной». В режиме отладки «медленные» обратные вызовы регистрируются.

Значение по умолчанию — 100 миллисекунд.

Запуск дочерних процессов

Методы, описанные в этом подразделе, являются низкоуровневыми. В обычном коде async/await следует использовать высокоуровневые функции asyncio.create_subprocess_shell() и asyncio.create_subprocess_exec() для удобства.

coroutine loop.subprocess_exec(protocol_factory, *args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)

Создаёт дочерний процесс из одного или нескольких строковых аргументов, указанных в args.

args должен быть списком строк, представленных:

• str;
• или bytes, закодированных в кодировку файловой системы.

Первая строка определяет исполняемый файл программы, а оставшиеся строки — аргументы. Вместе строковые аргументы образуют argv программы.

Это аналогично классу subprocess.Popen стандартной библиотеки, вызываемому с shell=False и списком строк, переданным в качестве первого аргумента; однако, где Popen принимает один аргумент — список строк, subprocess_exec принимает несколько строковых аргументов.

protocol_factory должен быть вызываемым объектом, возвращающим подкласс класса asyncio.SubprocessProtocol.

Другие параметры:

• stdin может быть любым из следующих:

  • объект типа файла
  • существующий дескриптор файла (положительное целое число), например, созданный с помощью os.pipe()
  • константа subprocess.PIPE (по умолчанию), которая создаст новую трубу и подключит её,
  • значение None, которое заставит дочерний процесс унаследовать дескриптор файла от этого процесса
  • константа subprocess.DEVNULL, указывающая, что будет использован специальный файл os.devnull

• stdout может быть любым из следующих:

  • объект типа файла
  • константа subprocess.PIPE (по умолчанию), которая создаст новую трубу и подключит её,
  • значение None, которое заставит дочерний процесс унаследовать дескриптор файла от этого процесса
  • константа subprocess.DEVNULL, указывающая, что будет использован специальный файл os.devnull

• stderr может быть любым из следующих:

  • объект типа файла
  • константа subprocess.PIPE (по умолчанию), которая создаст новую трубу и подключит её,
  • значение None, которое заставит дочерний процесс унаследовать дескриптор файла от этого процесса
  • константа subprocess.DEVNULL, указывающая, что будет использован специальный файл os.devnull
  • константа subprocess.STDOUT, которая подключит поток стандартной ошибки к потоку стандартного вывода процесса

• Все остальные ключевые аргументы передаются в subprocess.Popen без интерпретации, за исключением bufsize, universal_newlines, shell, text, encoding и errors, которые не должны указываться.

  API дочерних процессов asyncio не поддерживает декодирование потоков как текста. bytes.decode() можно использовать для преобразования байтов, возвращённых из потока, в текст.

Если объект типа файла, переданный как stdin, stdout или stderr, представляет собой трубу, то другую сторону этой трубы следует зарегистрировать с помощью connect_write_pipe() или connect_read_pipe() для использования с циклом событий.

См. конструктор класса subprocess.Popen для документации по другим аргументам.

Возвращает пару (transport, protocol), где transport соответствует базовому классу asyncio.SubprocessTransport, а protocol — объекту, созданному по шаблону protocol_factory.

coroutine loop.subprocess_shell(protocol_factory, cmd, *, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)

Создаёт дочерний процесс из cmd, которое может быть строкой str или bytes, закодированной в кодировку файловой системы, используя синтаксис «оболочки» платформы.

Это аналогично вызову класса subprocess.Popen стандартной библиотеки с shell=True.

protocol_factory должен быть вызываемым объектом, возвращающим подкласс класса SubprocessProtocol.

См. subprocess_exec() для получения дополнительных сведений об оставшихся аргументах.

Возвращает пару (transport, protocol), где transport соответствует базовому классу SubprocessTransport, а protocol — объекту, созданному по шаблону protocol_factory.

Привет, мир с call_soon()

Пример использования метода loop.call_soon() для планирования обратного вызова. Обратный вызов отображает "Hello World" и затем останавливает событийную петлю:

import asyncio

def hello_world(loop):
    """A callback to print 'Hello World' and stop the event loop"""
    print('Hello World')
    loop.stop()

loop = asyncio.new_event_loop()

# Schedule a call to hello_world()
loop.call_soon(hello_world, loop)

# Blocking call interrupted by loop.stop()
try:
    loop.run_forever()
finally:
    loop.close()

Отображение текущей даты с помощью call_later()

Пример обратного вызова, отображающего текущую дату каждую секунду. Обратный вызов использует метод loop.call_later() для повторного планирования себя через 5 секунд, а затем останавливает событийную петлю:

import asyncio
import datetime

def display_date(end_time, loop):
    print(datetime.datetime.now())
    if (loop.time() + 1.0) < end_time:
        loop.call_later(1, display_date, end_time, loop)
    else:
        loop.stop()

loop = asyncio.new_event_loop()

# Schedule the first call to display_date()
end_time = loop.time() + 5.0
loop.call_soon(display_date, end_time, loop)

# Blocking call interrupted by loop.stop()
try:
    loop.run_forever()
finally:
    loop.close()

Отслеживание дескриптора файла на события чтения

Ожидание, пока дескриптор файла получит данные с использованием метода loop.add_reader(), и затем закрытие событийной петли:

import asyncio
from socket import socketpair

# Create a pair of connected file descriptors
rsock, wsock = socketpair()

loop = asyncio.new_event_loop()

def reader():
    data = rsock.recv(100)
    print("Received:", data.decode())

    # We are done: unregister the file descriptor
    loop.remove_reader(rsock)

    # Stop the event loop
    loop.stop()

# Register the file descriptor for read event
loop.add_reader(rsock, reader)

# Simulate the reception of data from the network
loop.call_soon(wsock.send, 'abc'.encode())

try:
    # Run the event loop
    loop.run_forever()
finally:
    # We are done. Close sockets and the event loop.
    rsock.close()
    wsock.close()
    loop.close()

Установка обработчиков сигналов для SIGINT и SIGTERM

(Этот signals пример работает только в Unix.)

Регистрация обработчиков сигналов SIGINT и SIGTERM с помощью метода loop.add_signal_handler():

import asyncio
import functools
import os
import signal

def ask_exit(signame, loop):
    print("got signal %s: exit" % signame)
    loop.stop()

async def main():
    loop = asyncio.get_running_loop()

    for signame in {'SIGINT', 'SIGTERM'}:
        loop.add_signal_handler(
            getattr(signal, signame),
            functools.partial(ask_exit, signame, loop))

    await asyncio.sleep(3600)

print("Event loop running for 1 hour, press Ctrl+C to interrupt.")
print(f"pid {os.getpid()}: send SIGINT or SIGTERM to exit.")

asyncio.run(main())