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

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

loop.run_until_complete(future)

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

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

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

loop.run_forever()

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

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

Если 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.

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

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

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

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

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

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

Этот метод не потокобезопасен.

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

Потокобезопасная версия call_soon(). Используется для планирования обратных вызовов из другого потока.

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

# 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 и Tasks

loop.create_future()

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

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

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

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

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

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

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

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

loop.set_task_factory(factory)

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

Если factory None , будет установлена по умолчанию фабрика задач. В противном случае, factory должен быть вызываемым объектом с сигнатурой, соответствующей (loop, coro), где 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, happy_eyeballs_delay=None, interleave=None)

Открыть подключение к потоковому транспорту по заданному адресу, указанному в 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: если указано и не ложно, создаётся 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.
• local_addr, если задано, является кортежем (local_host, local_port), используемым для привязки сокета к локальному адресу. local_host и local_port ищутся с использованием getaddrinfo(), аналогично host и port.
• ssl_handshake_timeout (для TLS-соединения) — время в секундах ожидания завершения рукопожатия TLS перед прерыванием соединения. 60.0 секунд, если None (по умолчанию).

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

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

Для получения дополнительной информации: https://tools.ietf.org/html/rfc6555

Новое в версии 3.7: Параметр ssl_handshake_timeout.

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

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

См. также

Функция 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_address=None, reuse_port=None, allow_broadcast=None, sock=None)

Примечание

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

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

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

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

Семейство сокета может быть 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-системах. Если константа SO_REUSEPORT не определена, эта возможность не поддерживается.
• allow_broadcast сообщает ядру, что этот конечный пункт может отправлять сообщения на адрес широковещательной передачи.
• sock может быть указан для использования существующего, уже подключённого, объекта socket.socket. Если указан, local_addr и remote_addr должны быть опушены (должны быть None).

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

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

Изменено в версии 3.8.1: Параметр reuse_address больше не поддерживается из-за проблем безопасности.

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

coroutine loop.create_unix_connection(protocol_factory, path=None, *, ssl=None, sock=None, server_hostname=None, ssl_handshake_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.

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

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

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, ssl_handshake_timeout=None, start_serving=True)

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

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

Аргументы:

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

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

  • Если host — строка, TCP-сервер привязывается к одному сетевому интерфейсу, указанному в host.
  • Если host — последовательность строк, TCP-сервер привязывается ко всем сетевым интерфейсам, указанным в последовательности.
  • Если host — пустая строка или None, предполагаются все интерфейсы, и будет возвращён список нескольких сокетов (вероятно, один для IPv4 и другой для IPv6).
• family может быть установлен либо на socket.AF_INET, либо на AF_INET6, чтобы принудительно использовать IPv4 или IPv6. Если не установлен, family определяется по имени хоста (по умолчанию AF_UNSPEC).
• flags — битовая маска для getaddrinfo().
• sock — необязательный параметр, позволяющий использовать существующий сокет. Если указан, host и port не должны быть указаны.
• backlog — максимальное количество подключений в очереди, передаваемое методу listen() (по умолчанию 100).
• ssl может быть установлен на экземпляр SSLContext, чтобы включить TLS для принимаемых подключений.
• reuse_address сообщает ядру использовать локальный сокет в состоянии TIME_WAIT, не ожидая истечения его естественного таймаута. Если не указан, автоматически устанавливается в True на Unix.
• reuse_port сообщает ядру разрешить привязку этого конечного пункта к тому же порту, что и к другим существующим конечным точкам, при условии, что все они установят этот флаг при создании. Этот параметр не поддерживается в Windows.
• ssl_handshake_timeout (для TLS-сервера) — время в секундах ожидания завершения рукопожатия TLS перед прерыванием соединения. 60.0 секунд, если None (по умолчанию).
• start_serving, установленное в True (по умолчанию), заставляет созданный сервер начинать немедленно принимать подключения. При установке в False, пользователь должен дождаться Server.start_serving() или Server.serve_forever(), чтобы запустить сервер и начать принимать подключения.

В версии 3.7: Добавлены параметры ssl_handshake_timeout и start_serving.

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

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

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

См. также

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

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

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

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

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

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

В версии 3.7: Параметры ssl_handshake_timeout и start_serving.

В версии 3.7: Параметр path теперь может быть объектом Path.

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

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

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

Параметры:

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

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

В версии 3.7: Параметр ssl_handshake_timeout.

В версии 3.5.3.

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

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

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

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

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

offset указывает, с какого смещения начать чтение файла. Если указано, count — общее количество байтов для передачи, а не передача файла до достижения конца файла. Положение файла всегда обновляется, даже если метод вызывает ошибку, и 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)

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

Возвращает новый экземпляр транспорта, который protocol должен начать использовать немедленно после await. Экземпляр transport, переданный методу start_tls, больше никогда не должен использоваться.

Параметры:

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

В версии 3.7.

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

loop.add_reader(fd, callback, *args)

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

loop.remove_reader(fd)

Остановить мониторинг дескриптора файла fd на доступность для чтения.

loop.add_writer(fd, callback, *args)

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

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

loop.remove_writer(fd)

Остановить мониторинг дескриптора файла 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 это метод async def.

coroutine loop.sock_recv_into(sock, buf)

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

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

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

Новое в версии 3.7.

coroutine loop.sock_sendall(sock, data)

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

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

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

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

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 это async def метод.

См. также

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 — общее количество байтов для передачи, а не отправка файла до достижения конца файла. Позиция файла всегда обновляется, даже когда этот метод вызывает ошибку, и 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.

Пример:

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)

asyncio.run(main())

Этот метод возвращает объект 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.8: Использование исполнителя, который не является экземпляром ThreadPoolExecutor, устарело и будет вызывать ошибку в Python 3.9.

executor должен быть экземпляром concurrent.futures.ThreadPoolExecutor.

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

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

loop.set_exception_handler(handler)

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

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

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;
• ‘handle’ (необязательно): Объект asyncio.Handle;
• ‘protocol’ (необязательно): Объект протокола;
• ‘transport’ (необязательно): Объект транспорта;
• ‘socket’ (необязательно): Объект socket.socket.

Примечание

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

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

loop.get_debug()

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

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

loop.set_debug(enabled: bool)

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

Изменено в версии 3.7: Новый параметр командной строки -X dev теперь также может использоваться для включения отладочного режима.

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

Методы, описанные в этом разделе, являются низкоуровневыми. В обычном коде 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 может быть одним из следующих:

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

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

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

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

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

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

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

См. конструктор класса 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.get_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.get_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.get_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())