18.5.1. Базовый цикл событий¶Base Event Loop

18.5.1.1. Запуск цикла событий¶Run an event loop

BaseEventLoop.run_forever()¶

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

Изменено в версии 3.4.4.

BaseEventLoop.run_until_complete(future)¶

Выполняется до завершения Future.

Если аргумент является объектом корутины, то он оборачивается с помощью async().

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

BaseEventLoop.is_running()¶

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

BaseEventLoop.stop()¶

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

Это приводит к выходу из run_forever() при первой же подходящей возможности (см. описание выше для получения подробностей).

Изменено в версии 3.4.4.

BaseEventLoop.is_closed()¶

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

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

BaseEventLoop.close()¶

Закрывает цикл событий. Цикл не должен выполняться. Ожидающие колбэки будут потеряны.

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

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

18.5.1.2. Вызовы¶Calls

Большинство функций asyncio не принимают именованные аргументы. Если нужно передать именованные аргументы в колбэк, используйте functools.partial(). Например, loop.call_soon(functools.partial(print, "Hello", flush=True)) вызовет print("Hello", flush=True).

BaseEventLoop.call_soon(callback, *args)¶

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

Это работает как очередь FIFO: колбэки вызываются в порядке, в котором они зарегистрированы. Каждый колбэк вызывается ровно один раз.

Любые позиционные аргументы, указанные после колбэка, будут переданы ему при вызове.

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

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

BaseEventLoop.call_soon_threadsafe(callback, *args)¶

Аналог call_soon(), но потокобезопасный.

См. раздел concurrency and multithreading документации.

18.5.1.3. Отложенные вызовы¶Delayed calls

Цикл событий имеет собственные внутренние часы для вычисления тайм-аутов. Какие именно часы используются, зависит от (зависящей от платформы) реализации цикла событий; в идеале это монотонные часы. Обычно это другие часы, отличные от time.time().

BaseEventLoop.call_later(delay, callback, *args)¶

Организует вызов колбэка через заданную задержку в секундах (целое число или float).

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

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

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

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

BaseEventLoop.call_at(when, callback, *args)¶

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

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

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

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

BaseEventLoop.time()¶

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

18.5.1.4. Задачи¶Tasks

BaseEventLoop.create_task(coro)¶

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

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

Этот метод был добавлен в Python 3.4.2. Используйте функцию async(), чтобы поддерживать также старые версии Python.

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

BaseEventLoop.set_task_factory(factory)¶

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

Если factory равен None, будет установлена фабрика задач по умолчанию.

Если factory является вызываемым объектом, его сигнатура должна соответствовать (loop, coro), где loop будет ссылкой на активный цикл событий, а coro – объектом корутины. Вызываемый объект должен возвращать совместимый объект asyncio.Future.

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

BaseEventLoop.get_task_factory()¶

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

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

18.5.1.5. Создание соединений¶Creating connections

coroutine BaseEventLoop.create_connection(protocol_factory, host=None, port=None, *, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None)¶

Создает потоковое транспортное соединение с указанными узлом и портом: семейство сокетов AF_INET или AF_INET6 в зависимости от узла (или family, если задано), тип сокета SOCK_STREAM. protocol_factory должна быть вызываемым объектом, возвращающим экземпляр протокола.

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

Хронологическая последовательность выполняемой операции следующая:

1. Соединение установлено, и создаётся транспорт, представляющий его.
2. protocol_factory вызывается без аргументов и должен возвращать экземпляр протокола.
3. Экземпляр протокола привязан к транспорту, и вызывается его метод connection_made().
4. Корутина успешно завершается, возвращая пару (транспорт, протокол).

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

Примечание

protocol_factory может быть вызываемым объектом любого вида, не обязательно классом. Например, для использования предварительно созданного экземпляра протокола можно передать lambda: my_protocol.

Параметры, позволяющие изменить способ создания соединения:

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

  См. также

  Вопросы безопасности SSL/TLS

• server_hostname используется только вместе с ssl и задаёт или переопределяет имя хоста, с которым будет сравниваться сертификат целевого сервера. По умолчанию используется значение аргумента host. Если host пуст, значение по умолчанию отсутствует, и необходимо передать значение для server_hostname. Если server_hostname является пустой строкой, проверка имени хоста отключается (что представляет серьёзную угрозу безопасности, допуская атаки man-in-the-middle).

• family, proto, flags – необязательные семейство адреса, протокол и флаги, передаваемые в getaddrinfo() для разрешения узла. Если заданы, все они должны быть целыми числами из соответствующих констант модуля socket.

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

• local_addr, если задан, представляет собой кортеж (local_host, local_port), используемый для локальной привязки сокета. local_host и local_port разрешаются с помощью getaddrinfo(), аналогично host и port.

В Windows с ProactorEventLoop SSL/TLS не поддерживается.

См. также

Функция open_connection() может использоваться для получения пары (StreamReader, StreamWriter) вместо протокола.

coroutine BaseEventLoop.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)¶

Создание датаграмного соединения: семейство сокетов AF_INET или AF_INET6 в зависимости от узла (или family, если задано), тип сокета SOCK_DGRAM. protocol_factory должна быть вызываемым объектом, возвращающим экземпляр протокола.

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

Параметры, изменяющие способ создания соединения:

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

В Windows с ProactorEventLoop этот метод не поддерживается.

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

coroutine BaseEventLoop.create_unix_connection(protocol_factory, path, *, ssl=None, sock=None, server_hostname=None)¶

Создание UNIX-соединения: семейство сокетов AF_UNIX, тип сокета SOCK_STREAM. Семейство сокетов AF_UNIX используется для эффективного обмена данными между процессами на одной машине.

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

Смотрите метод BaseEventLoop.create_connection() для получения информации о параметрах.

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

18.5.1.6. Создание принимающих соединений¶Creating listening connections

coroutine BaseEventLoop.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)¶

Создаёт TCP-сервер (тип сокета SOCK_STREAM), привязанный к host и port.

Возвращает объект Server, его атрибут sockets содержит созданные сокеты. Используйте метод Server.close() для остановки сервера: закрывает принимающие сокеты.

Параметры:

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

Этот метод является корутиной.

В Windows с ProactorEventLoop SSL/TLS не поддерживается.

См. также

Функция start_server() создаёт пару StreamReader, StreamWriter и вызывает колбэк-функцию с этой парой.

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

coroutine BaseEventLoop.create_unix_server(protocol_factory, path=None, *, sock=None, backlog=100, ssl=None)¶

Аналогично BaseEventLoop.create_server(), но для семейства сокетов AF_UNIX.

Этот метод является корутиной.

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

18.5.1.7. Отслеживание файловых дескрипторов¶Watch file descriptors

В Windows с SelectorEventLoop поддерживаются только дескрипторы сокетов (например, файловые дескрипторы каналов не поддерживаются).

В Windows с ProactorEventLoop эти методы не поддерживаются.

BaseEventLoop.add_reader(fd, callback, *args)¶

Начать наблюдение за файловым дескриптором на готовность к чтению и затем вызвать колбэк с указанными аргументами.

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

BaseEventLoop.remove_reader(fd)¶

Прекратить наблюдение за файловым дескриптором на готовность к чтению.

BaseEventLoop.add_writer(fd, callback, *args)¶

Начать наблюдение за файловым дескриптором на готовность к записи и затем вызвать колбэк с указанными аргументами.

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

BaseEventLoop.remove_writer(fd)¶

Прекратить наблюдение за файловым дескриптором на готовность к записи.

Пример наблюдения за файловым дескриптором на события чтения использует низкоуровневый метод BaseEventLoop.add_reader() для регистрации файлового дескриптора сокета.

18.5.1.8. Низкоуровневые операции с сокетами¶Low-level socket operations

coroutine BaseEventLoop.sock_recv(sock, nbytes)¶

Получает данные из сокета. Возвращаемое значение – объект типа bytes, представляющий полученные данные. Максимальный объём данных, получаемых за один раз, задаётся параметром nbytes.

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

Этот метод является корутиной.

См. также

Метод socket.socket.recv().

coroutine BaseEventLoop.sock_sendall(sock, data)¶

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

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

Этот метод является корутиной.

См. также

Метод socket.socket.sendall().

coroutine BaseEventLoop.sock_connect(sock, address)¶

Подключается к удалённому сокету по адресу address.

Адрес address должен быть предварительно разрешён, чтобы избежать ситуации, когда весь цикл событий зависает из-за необходимости выполнения DNS-запроса для этого адреса. Например, это должен быть IP-адрес, а не имя хоста, для семейств адресов AF_INET и AF_INET6. Используйте getaddrinfo() для асинхронного разрешения имени хоста.

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

Этот метод является корутиной.

См. также

Метод BaseEventLoop.create_connection(), функция open_connection() и метод socket.socket.connect().

coroutine BaseEventLoop.sock_accept(sock)¶

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

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

Этот метод является корутиной.

См. также

Метод BaseEventLoop.create_server(), функция start_server() и метод socket.socket.accept().

18.5.1.9. Разрешение имени хоста¶Resolve host name

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

Этот метод является корутиной, аналогичной функции socket.getaddrinfo(), но неблокирующей.

coroutine BaseEventLoop.getnameinfo(sockaddr, flags=0)¶

Этот метод является корутиной, аналогичной функции socket.getnameinfo(), но неблокирующей.

18.5.1.10. Подключение каналов¶Connect pipes

В Windows с циклом событий SelectorEventLoop эти методы не поддерживаются. Используйте ProactorEventLoop для поддержки каналов в Windows.

coroutine BaseEventLoop.connect_read_pipe(protocol_factory, pipe)¶

Регистрирует канал чтения в цикле событий.

protocol_factory должен создавать объект с интерфейсом Protocol. pipe – это файлоподобный объект. Возвращает пару (транспорт, протокол), где транспорт поддерживает интерфейс ReadTransport.

В цикле событий SelectorEventLoop канал pipe переводится в неблокирующий режим.

Этот метод является корутиной.

coroutine BaseEventLoop.connect_write_pipe(protocol_factory, pipe)¶

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

protocol_factory должен создавать объект с BaseProtocol интерфейсом. pipe – это файлоподобный объект. Возвращает пару (транспорт, протокол), где транспорт поддерживает интерфейс WriteTransport.

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

Этот метод является корутиной.

18.5.1.11. Сигналы UNIX¶UNIX signals

Доступно: только UNIX.

BaseEventLoop.add_signal_handler(signum, callback, *args)¶

Добавляет обработчик сигнала.

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

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

BaseEventLoop.remove_signal_handler(sig)¶

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

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

18.5.1.12. Исполнитель¶Executor

Executor (пул потоков или пул процессов). По умолчанию цикл событий использует исполнитель на пуле потоков (ThreadPoolExecutor).

coroutine BaseEventLoop.run_in_executor(executor, func, *args)¶

Планирует вызов функции func в указанном исполнителе.

Аргумент executor должен быть экземпляром Executor . Исполнитель по умолчанию используется, если executor равен None.

Используйте functools.partial для передачи именованных аргументов в *func*.

Этот метод является корутиной.

BaseEventLoop.set_default_executor(executor)¶

Устанавливает исполнитель по умолчанию, используемый run_in_executor().

18.5.1.13. API обработки ошибок¶Error Handling API

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

BaseEventLoop.set_exception_handler(handler)¶

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

Если handler равен None, обработчик исключений по умолчанию будет установлен.

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

BaseEventLoop.default_exception_handler(context)¶

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

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

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

BaseEventLoop.call_exception_handler(context)¶

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

context – это объект dict, содержащий следующие ключи (новые ключи могут быть добавлены позже):

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

Примечание

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

18.5.1.14. Режим отладки¶Debug mode

BaseEventLoop.get_debug()¶

Возвращает режим отладки (bool) цикла событий.

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

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

BaseEventLoop.set_debug(enabled: bool)¶

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

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

18.5.1.15. Server¶

class asyncio.Server¶

Сервер, прослушивающий сокеты.

Объект создаётся методом BaseEventLoop.create_server() и функцией start_server(). Не создавайте экземпляр класса напрямую.

close()¶

Прекратить обслуживание: закрыть прослушивающие сокеты и установить атрибут sockets в значение None.

Сокеты, соответствующие уже установленным входящим клиентским подключениям, остаются открытыми.

Сервер закрывается асинхронно, используйте корутину wait_closed() для ожидания закрытия сервера.

coroutine wait_closed()¶

Дождаться завершения метода close().

Этот метод является корутиной.

sockets¶

Список объектов socket.socket, которые прослушивает сервер, или None, если сервер закрыт.

18.5.1.16. Handle¶

class asyncio.Handle¶

Объект-обёртка колбэка, возвращаемый методами BaseEventLoop.call_soon(), BaseEventLoop.call_soon_threadsafe(), BaseEventLoop.call_later(), и BaseEventLoop.call_at().

cancel()¶

Отменяет вызов. Если колбэк уже отменён или выполнен, этот метод ничего не делает.

18.5.1.17. Примеры использования цикла событий¶Event loop examples

import asyncio

def hello_world(loop):
    print('Hello World')
    loop.stop()

loop = asyncio.get_event_loop()

# Запланировать вызов hello_world()
loop.call_soon(hello_world, loop)

# Блокирующий вызов прерван loop.stop()
loop.run_forever()
loop.close()

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()

# Запланировать первый вызов display_date()
end_time = loop.time() + 5.0
loop.call_soon(display_date, end_time, loop)

# Блокирующий вызов прерван loop.stop()
loop.run_forever()
loop.close()

import asyncio
try:
    from socket import socketpair
except ImportError:
    from asyncio.windows_utils import socketpair

# Создать пару связанных файловых дескрипторов
rsock, wsock = socketpair()
loop = asyncio.get_event_loop()

def reader():
    data = rsock.recv(100)
    print("Received:", data.decode())
    # Готово: отменить регистрацию файлового дескриптора
    loop.remove_reader(rsock)
    # Остановить цикл событий
    loop.stop()

# Зарегистрировать файловый дескриптор для события чтения
loop.add_reader(rsock, reader)

# Симулировать приём данных из сети
loop.call_soon(wsock.send, 'abc'.encode())

# Запустить цикл событий
loop.run_forever()

# Готово, закрыть сокеты и цикл событий.
rsock.close()
wsock.close()
loop.close()

import asyncio
import functools
import os
import signal

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

loop = asyncio.get_event_loop()
for signame in ('SIGINT', 'SIGTERM'):
    loop.add_signal_handler(getattr(signal, signame),
                            functools.partial(ask_exit, signame))

print("Event loop running forever, press Ctrl+C to interrupt.")
print("pid %s: send SIGINT or SIGTERM to exit." % os.getpid())
try:
    loop.run_forever()
finally:
    loop.close()