Цикл подій

Вихідний код: Lib/asyncio/events.py, Lib/asyncio/base_events.py

---

Передмова

Цикл подій є ядром кожної асинхронної програми. Цикли подій запускають асинхронні завдання та зворотні виклики, виконують мережеві операції вводу-виводу та запускають підпроцеси.

Розробникам додатків зазвичай слід використовувати асинхронні функції високого рівня, такі як asyncio.run(), і їм рідко потрібно посилатися на об’єкт циклу або викликати його методи. Цей розділ призначений переважно для авторів коду нижчого рівня, бібліотек і фреймворків, яким потрібен точніший контроль над поведінкою циклу подій.

Отримання циклу подій

Наступні функції низького рівня можна використовувати для отримання, встановлення або створення циклу подій:

asyncio.get_running_loop()

Повернути запущений цикл подій у поточному потоці ОС.

If there is no running event loop a RuntimeError is raised. This function can only be called from a coroutine or a callback.

Нове в версії 3.7.

asyncio.get_event_loop()

Отримати поточний цикл подій.

If there is no current event loop set in the current OS thread, the OS thread is main, and set_event_loop() has not yet been called, asyncio will create a new event loop and set it as the current one.

Оскільки ця функція має досить складну поведінку (особливо, коли використовуються користувацькі політики циклу подій), використанню функції get_running_loop() краще, ніж get_event_loop() у співпрограмах і зворотних викликах.

Consider also using the asyncio.run() function instead of using lower level functions to manually create and close an event loop.

asyncio.set_event_loop(loop)

Set loop as a current event loop for the current OS thread.

asyncio.new_event_loop()

Створити та повернути новий об’єкт циклу подій.

Зауважте, що поведінку функцій get_event_loop(), set_event_loop() і new_event_loop() можна змінити шляхом встановлення спеціальної політики циклу подій.

Зміст

Ця сторінка документації містить такі розділи:

• Розділ Event Loop Methods є довідковою документацією щодо API циклу подій;

• Розділ Callback Handles документує екземпляри Handle і TimerHandle, які повертаються з таких методів планування, як loop.call_soon() і loop.call_later();

• Розділ Server Objects документує типи, що повертаються з методів циклу подій, таких як loop.create_server();

• Розділ Event Loop Implementations документує класи SelectorEventLoop і ProactorEventLoop;

• Розділ Examples демонструє, як працювати з деякими API циклу подій.

Методи циклу подій

Цикли подій мають API низького рівня для наступного:

Запуск і зупинка циклу

loop.run_until_complete(future)

Виконуйте, доки future (примірник Future) не завершиться.

Якщо аргумент є об’єктом співпрограми, він неявно запланований для виконання як asyncio.Task.

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

loop.run_forever()

Запускайте цикл подій, доки не буде викликано stop().

If stop() is called before run_forever() is called, the loop will poll the I/O selector once with a timeout of zero, run all callbacks scheduled in response to I/O events (and those that were already scheduled), and then exit.

Якщо stop() викликається під час роботи run_forever(), цикл запустить поточний пакет зворотних викликів, а потім завершить роботу. Зауважте, що нові зворотні виклики, заплановані зворотними викликами, не виконуватимуться в цьому випадку; натомість вони запустяться під час наступного виклику run_forever() або run_until_complete().

loop.stop()

Зупиніть цикл подій.

loop.is_running()

Повертає True, якщо цикл подій зараз запущено.

loop.is_closed()

Повертає True, якщо цикл події було закрито.

loop.close()

Закрийте цикл подій.

Під час виклику цієї функції цикл не повинен працювати. Усі зворотні виклики, що очікують на розгляд, буде відхилено.

Цей метод очищає всі черги та вимикає виконавець, але не чекає, поки виконавець завершить роботу.

Цей метод є ідемпотентним і необоротним. Ніякі інші методи не повинні викликатися після закриття циклу подій.

coroutine loop.shutdown_asyncgens()

Schedule all currently open asynchronous generator objects to close with an aclose() call. After calling this method, the event loop will issue a warning if a new asynchronous generator is iterated. This should be used to reliably finalize all scheduled asynchronous generators.

Зауважте, що немає потреби викликати цю функцію, коли використовується asyncio.run().

Приклад:

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

Нове в версії 3.6.

coroutine loop.shutdown_default_executor()

Schedule the closure of the default executor and wait for it to join all of the threads in the ThreadPoolExecutor. After calling this method, a RuntimeError will be raised if loop.run_in_executor() is called while using the default executor.

Зауважте, що немає потреби викликати цю функцію, коли використовується asyncio.run().

Нове в версії 3.9.

Планування зворотних дзвінків

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

Заплануйте виклик callback callback з аргументами args на наступній ітерації циклу подій.

Зворотні виклики викликаються в тому порядку, в якому вони зареєстровані. Кожен зворотній виклик буде викликано рівно один раз.

Необов’язковий аргумент context, що містить лише ключове слово, дозволяє вказати спеціальний contextvars.Context для виконання зворотного виклику. Поточний контекст використовується, якщо контексту не надано.

An instance of asyncio.Handle is returned, which can be used later to cancel the callback.

This method is not thread-safe.

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

A thread-safe variant of call_soon(). Must be used to schedule callbacks from another thread.

Викликає RuntimeError, якщо викликається в закритому циклі. Це може статися у вторинному потоці, коли основна програма вимикається.

Перегляньте розділ паралелізм і багатопотоковість документації.

Змінено в версії 3.7: Додано параметр context тільки для ключового слова. Дивіться PEP 567 для більш детальної інформації.

Примітка

Більшість функцій планування asyncio не дозволяють передавати ключові аргументи. Для цього скористайтеся functools.partial():

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

Використання часткових об’єктів зазвичай зручніше, ніж використання лямбда-виразів, оскільки asyncio може краще відтворювати часткові об’єкти в повідомленнях про налагодження та помилки.

Планування відкладених зворотних викликів

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

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

Розклад зворотного виклику для виклику після заданої затримки у секундах (може бути як int, так і float).

Повертається екземпляр asyncio.TimerHandle, який можна використовувати для скасування зворотного виклику.

callback буде передзвонено рівно один раз. Якщо два зворотні виклики заплановано на один і той же час, порядок їх викликів не визначений.

Додатковий позиційний args буде передано зворотному виклику під час його виклику. Якщо ви хочете, щоб зворотній виклик викликався з аргументами ключового слова, використовуйте functools.partial().

Необов’язковий аргумент context, що містить лише ключове слово, дозволяє вказати спеціальний contextvars.Context для виконання зворотного виклику. Поточний контекст використовується, якщо контексту не надано.

Змінено в версії 3.7: Додано параметр context тільки для ключового слова. Дивіться PEP 567 для більш детальної інформації.

Змінено в версії 3.8: У Python 3.7 і раніше з реалізацією циклу подій за замовчуванням затримка не могла перевищувати один день. Це було виправлено в Python 3.8.

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

Заплануйте виклик callback у вказану абсолютну позначку часу when (int або float), використовуючи те саме посилання на час, що й loop.time().

Поведінка цього методу така ж, як і call_later().

Повертається екземпляр asyncio.TimerHandle, який можна використовувати для скасування зворотного виклику.

Змінено в версії 3.7: Додано параметр context тільки для ключового слова. Дивіться PEP 567 для більш детальної інформації.

Змінено в версії 3.8: У Python 3.7 і раніше з реалізацією циклу подій за замовчуванням різниця між when і поточним часом не могла перевищувати одного дня. Це було виправлено в Python 3.8.

loop.time()

Повертає поточний час у вигляді значення float відповідно до внутрішнього монотонного годинника циклу подій.

Примітка

Змінено в версії 3.8: У Python 3.7 та попередніх версіях тайм-аути (відносна затримка або абсолютна коли) не повинні перевищувати одного дня. Це було виправлено в Python 3.8.

Дивись також

Функція asyncio.sleep().

Створення ф’ючерсів і завдань

loop.create_future()

Створіть об’єкт asyncio.Future, приєднаний до циклу подій.

Це найкращий спосіб створення ф’ючерсів в асинхронному режимі. Це дозволяє стороннім циклам подій надавати альтернативні реалізації об’єкта Future (з кращою продуктивністю або інструментарієм).

Нове в версії 3.5.2.

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

Schedule the execution of a Співпрограми. Return a Task object.

Сторонні цикли подій можуть використовувати власний підклас Task для взаємодії. У цьому випадку тип результату є підкласом Task.

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

Змінено в версії 3.8: Added the name parameter.

loop.set_task_factory(factory)

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

If factory is None the default task factory will be set. Otherwise, factory must be a callable with the signature matching (loop, coro), where loop is a reference to the active event loop, and coro is a coroutine object. The callable must return a asyncio.Future-compatible object.

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.

The socket family can be either AF_INET or AF_INET6 depending on host (or the family argument, if provided).

The socket type will be SOCK_STREAM.

protocol_factory має бути викликом, що повертає реалізацію asyncio protocol.

Цей метод намагатиметься встановити з’єднання у фоновому режимі. У разі успіху він повертає пару (транспорт, протокол).

Хронологічний синопсис основної операції такий:

1. З’єднання встановлюється та для нього створюється транспорт.

2. protocol_factory викликається без аргументів і має повернути екземпляр protocol.

3. Екземпляр протоколу з’єднується з транспортом шляхом виклику його методу connection_made().

4. Кортеж (транспорт, протокол) повертається в разі успіху.

Створений транспорт є двонаправленим потоком, що залежить від реалізації.

Інші аргументи:

• 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 не повинен бути вказаний.

• 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 Algorithm: Success with Dual-Stack Hosts. When a server’s IPv4 path and protocol are working, but the server’s IPv6 path and protocol are not working, a dual-stack client application experiences significant connection delay compared to an IPv4-only client. This is undesirable because it causes the dual- stack client to have a worse user experience. This document specifies requirements for algorithms that reduce this user-visible delay and provides an algorithm.

For more information: https://tools.ietf.org/html/rfc6555

Нове в версії 3.7: The ssl_handshake_timeout parameter.

Змінено в версії 3.6: The socket option TCP_NODELAY is set by default for all TCP connections.

Змінено в версії 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)

Примітка

The parameter reuse_address is no longer supported, as using SO_REUSEADDR poses a significant security concern for UDP. Explicitly passing reuse_address=True will raise an exception.

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

For supported platforms, reuse_port can be used as a replacement for similar functionality. With reuse_port, SO_REUSEPORT is used instead, which specifically prevents processes with differing UIDs from assigning sockets to the same socket address.

Створіть з’єднання дейтаграми.

The socket family can be either AF_INET, AF_INET6, or AF_UNIX, depending on host (or the family argument, if provided).

The socket type will be SOCK_DGRAM.

protocol_factory має бути викликом, що повертає реалізацію 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 tells the kernel to allow this endpoint to be bound to the same port as other existing endpoints are bound to, so long as they all set this flag when being created. This option is not supported on Windows and some Unixes. If the SO_REUSEPORT constant is not defined then this capability is unsupported.

• allow_broadcast повідомляє ядру дозволити цій кінцевій точці надсилати повідомлення на широкомовну адресу.

• Опціонально можна вказати sock, щоб використовувати існуючий, уже підключений об’єкт socket.socket, який буде використовуватися транспортом. Якщо вказано, local_addr і remote_addr слід опустити (має бути None).

Перегляньте приклади UDP echo client protocol і UDP echo server protocol прикладів.

Змінено в версії 3.4.4: The family, proto, flags, reuse_address, reuse_port, *allow_broadcast, and sock parameters were added.

Змінено в версії 3.8.1: The reuse_address parameter is no longer supported due to security concerns.

Змінено в версії 3.8: Додана підтримка Windows.

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

Створіть підключення Unix.

The socket family will be AF_UNIX; socket type will be SOCK_STREAM.

Кортеж (транспорт, протокол) повертається в разі успіху.

path — це ім’я сокета домену Unix і є обов’язковим, якщо не вказано параметр sock. Підтримуються абстрактні сокети Unix, шляхи str, bytes і Path.

Перегляньте документацію методу loop.create_connection(), щоб отримати інформацію про аргументи цього методу.

Availability: Unix.

Нове в версії 3.7: The ssl_handshake_timeout parameter.

Змінено в версії 3.7: The path parameter can now be a path-like object.

Створення мережевих серверів

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)

Create a TCP server (socket type SOCK_STREAM) listening on port of the host address.

Повертає об’єкт Server.

Аргументи:

• protocol_factory має бути викликом, що повертає реалізацію protocol.

• Для параметра host можна встановити кілька типів, які визначають, де сервер буде слухати:

  • Якщо host є рядком, сервер TCP прив’язаний до єдиного мережевого інтерфейсу, визначеного host.

  • Якщо host є послідовністю рядків, TCP-сервер прив’язаний до всіх мережевих інтерфейсів, визначених цією послідовністю.

  • Якщо host є порожнім рядком або None, усі інтерфейси передбачаються, і буде повернено список кількох сокетів (швидше за все, один для IPv4 та інший для IPv6).

• Параметр port можна встановити, щоб вказати, який порт сервер повинен слухати. Якщо 0 або None (за замовчуванням), буде вибрано випадковий невикористаний порт (зауважте, що якщо host розпізнає кілька мережевих інтерфейсів, для кожного інтерфейсу буде вибрано окремий випадковий порт).

• family can be set to either socket.AF_INET or AF_INET6 to force the socket to use IPv4 or IPv6. If not set, the family will be determined from host name (defaults to AF_UNSPEC).

• flags — це бітова маска для getaddrinfo().

• За бажанням можна вказати sock, щоб використовувати вже існуючий об’єкт socket. Якщо вказано, host і port не повинні вказуватися.

• backlog — це максимальна кількість підключень у черзі, переданих до listen() (за замовчуванням 100).

• ssl можна встановити як екземпляр SSLContext, щоб увімкнути TLS через прийнятні з’єднання.

• reuse_address повідомляє ядру повторно використовувати локальний сокет у стані TIME_WAIT, не чекаючи закінчення його природного часу очікування. Якщо не вказано, для Unix буде автоматично встановлено значення True.

• reuse_port повідомляє ядру дозволити цю кінцеву точку прив’язувати до того самого порту, до якого прив’язані інші існуючі кінцеві точки, за умови, що всі вони встановлюють цей прапор під час створення. Цей параметр не підтримується в Windows.

• ssl_handshake_timeout — це (для TLS-сервера) час у секундах очікування завершення рукостискання TLS перед розривом з’єднання. 60.0 секунд, якщо None (за замовчуванням).

• start_serving встановлений на True (за замовчуванням), змушує створений сервер негайно приймати підключення. Якщо встановлено значення False, користувач повинен чекати Server.start_serving() або Server.serve_forever(), щоб змусити сервер почати приймати з’єднання.

Нове в версії 3.7: Added ssl_handshake_timeout and start_serving parameters.

Змінено в версії 3.6: The socket option TCP_NODELAY is set by default for all TCP connections.

Змінено в версії 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)

Similar to loop.create_server() but works with the AF_UNIX socket family.

path — це ім’я сокета домену Unix і є обов’язковим, якщо не надано аргумент sock. Підтримуються абстрактні сокети Unix, шляхи str, bytes і Path.

Перегляньте документацію методу loop.create_server() для отримання інформації про аргументи цього методу.

Availability: Unix.

Нове в версії 3.7: The ssl_handshake_timeout and start_serving parameters.

Змінено в версії 3.7: The path parameter can now be a Path object.

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

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

Цей метод може використовуватися серверами, які приймають з’єднання за межами asyncio, але використовують asyncio для їх обробки.

Параметри:

• protocol_factory має бути викликом, що повертає реалізацію protocol.

• sock — це вже існуючий об’єкт сокета, який повертається з socket.accept.

• ssl можна встановити як SSLContext, щоб увімкнути SSL через прийнятні з’єднання.

• ssl_handshake_timeout — це (для з’єднання SSL) час у секундах очікування завершення рукостискання SSL перед розривом з’єднання. 60.0 секунд, якщо None (за замовчуванням).

Повертає пару (транспорт, протокол).

Нове в версії 3.7: The ssl_handshake_timeout parameter.

Нове в версії 3.5.3.

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

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

Надіслати файл через транспорт. Повертає загальну кількість надісланих байтів.

Метод використовує високопродуктивний os.sendfile(), якщо він доступний.

file має бути звичайним файловим об’єктом, відкритим у двійковому режимі.

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

Оновіть існуюче транспортне підключення до TLS.

Return a new transport instance, that the protocol must start using immediately after the await. The transport instance passed to the start_tls method should never be used again.

Параметри:

• екземпляри 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)

Stop monitoring the fd file descriptor for read availability.

loop.add_writer(fd, callback, *args)

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

Використовуйте functools.partial() , щоб передати аргументи ключового слова в callback.

loop.remove_writer(fd)

Stop monitoring the fd file descriptor for write availability.

Перегляньте також розділ Підтримка платформи, щоб дізнатися про деякі обмеження цих методів.

Безпосередня робота з об’єктами сокетів

Загалом, реалізації протоколів, які використовують 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)

Надішліть дані в сокет sock. Асинхронна версія socket.sendall().

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

sock має бути неблокуючим сокетом.

Змінено в версії 3.7: Even though the method was always documented as a coroutine method, before Python 3.7 it returned an Future. Since Python 3.7, this is an async def method.

coroutine loop.sock_connect(sock, address)

Підключіть sock до віддаленої розетки за адресою.

Асинхронна версія 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 — це загальна кількість байтів для передачі, а не надсилання файлу до досягнення 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().

Змінено в версії 3.7: Обидва методи getaddrinfo і getnameinfo завжди були задокументовані для повернення співпрограми, але до Python 3.7 вони фактично повертали об’єкти asyncio.Future. Починаючи з Python 3.7 обидва методи є співпрограмами.

Робота з трубами

coroutine loop.connect_read_pipe(protocol_factory, pipe)

Зареєструйте прочитаний кінець pipe у циклі подій.

protocol_factory має бути викликом, що повертає реалізацію asyncio protocol.

pipe — це файлоподібний об’єкт.

Повернена пара (транспорт, протокол), де transport підтримує інтерфейс ReadTransport, а protocol є об’єктом, створеним protocol_factory.

За допомогою циклу подій SelectorEventLoop pipe встановлюється в неблокуючий режим.

coroutine loop.connect_write_pipe(protocol_factory, pipe)

Зареєструйте кінець запису pipe у циклі подій.

protocol_factory має бути викликом, що повертає реалізацію asyncio protocol.

pipe — це файлоподібний об’єкт.

Повернена пара (транспорт, протокол), де transport підтримує інтерфейс WriteTransport, а protocol є об’єктом, створеним protocol_factory.

За допомогою циклу подій SelectorEventLoop pipe встановлюється в неблокуючий режим.

Примітка

SelectorEventLoop не підтримує наведені вище методи в Windows. Використовуйте ProactorEventLoop замість цього для Windows.

Дивись також

Методи loop.subprocess_exec() і loop.subprocess_shell().

Сигнали Unix

loop.add_signal_handler(signum, callback, *args)

Встановіть callback як обробник для сигналу signum.

Зворотний виклик буде викликаний циклом разом з іншими зворотними викликами в черзі та запущеними співпрограмами цього циклу подій. На відміну від обробників сигналів, зареєстрованих за допомогою signal.signal(), зворотній виклик, зареєстрований у цій функції, може взаємодіяти з циклом подій.

Викликайте ValueError, якщо номер сигналу недійсний або не вловлюється. Викликати RuntimeError, якщо є проблема з налаштуванням обробника.

Використовуйте functools.partial() , щоб передати аргументи ключового слова в callback.

Подібно до signal.signal(), ця функція має бути викликана в основному потоці.

loop.remove_signal_handler(sig)

Видаліть обробник для сигналу sig.

Повертає True, якщо обробник сигналу було видалено, або False, якщо обробник не встановлено для даного сигналу.

Availability: Unix.

Дивись також

Модуль signal.

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

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

Організувати виклик func у вказаному виконавці.

The executor argument should be an concurrent.futures.Executor instance. The default executor is used if executor is 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)

Set executor as the default executor used by run_in_executor(). executor should be an instance of ThreadPoolExecutor.

Застаріло починаючи з версії 3.8: Using an executor that is not an instance of ThreadPoolExecutor is deprecated and will trigger an error in Python 3.9.

executor must be an instance of concurrent.futures.ThreadPoolExecutor.

API обробки помилок

Дозволяє налаштувати спосіб обробки винятків у циклі подій.

loop.set_exception_handler(handler)

Встановіть обробник як новий обробник винятків циклу подій.

Якщо обробник має значення None, буде встановлено обробник винятків за умовчанням. В іншому випадку обробник має бути викликом із сигнатурою, що відповідає (цикл, контекст), де цикл є посиланням на активний цикл подій, а контекст є 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“ (необов’язковий): об’єкт винятку;

• „майбутнє“ (необов’язково): екземпляр asyncio.Future;

• „task“ (необов’язковий): asyncio.Task екземпляр;

• „handle“ (необов’язковий): asyncio.Handle екземпляр;

• „протокол“ (необов’язково): примірник протоколу;

• „transport“ (необов’язковий): Transport екземпляр;

• „socket“ (необов’язковий): socket.socket екземпляр;

• „asyncgen“ (необов’язково): асинхронний генератор, який викликав

  виняток.

Примітка

This method should not be overloaded in subclassed event loops. For custom exception handling, use the set_exception_handler() method.

Увімкнення режиму налагодження

loop.get_debug()

Отримати режим налагодження (bool) циклу подій.

Значенням за замовчуванням є True, якщо змінна середовища PYTHONASYNCIODEBUG має значення непорожнього рядка, False в іншому випадку.

loop.set_debug(enabled: bool)

Встановіть режим налагодження циклу подій.

Змінено в версії 3.7: Новий Режим розробки Python тепер також можна використовувати для ввімкнення режиму налагодження.

Дивись також

режим налагодження asyncio.

Запущені підпроцеси

Методи, описані в цьому підрозділі, є низькорівневими. У звичайному коді async/await розгляньте можливість використовувати натомість зручні функції високого рівня asyncio.create_subprocess_shell() і asyncio.create_subprocess_exec().

Примітка

У Windows типовий цикл подій ProactorEventLoop підтримує підпроцеси, тоді як SelectorEventLoop не підтримує. Дивіться Підтримку підпроцесів у Windows, щоб дізнатися більше.

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 може бути будь-яким із цих:

  • a file-like object representing a pipe to be connected to the subprocess’s standard input stream using connect_write_pipe()

  • константа subprocess.PIPE (за замовчуванням), яка створить новий канал і з’єднає його,

  • значення None, яке змусить підпроцес успадкувати дескриптор файлу від цього процесу

  • константа subprocess.DEVNULL, яка вказує, що буде використовуватися спеціальний файл os.devnull

• stdout може бути будь-яким із цього:

  • a file-like object representing a pipe to be connected to the subprocess’s standard output stream using connect_write_pipe()

  • константа subprocess.PIPE (за замовчуванням), яка створить новий канал і з’єднає його,

  • значення None, яке змусить підпроцес успадкувати дескриптор файлу від цього процесу

  • константа subprocess.DEVNULL, яка вказує, що буде використовуватися спеціальний файл os.devnull

• stderr може бути будь-яким із цього:

  • a file-like object representing a pipe to be connected to the subprocess’s standard error stream using 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.

Примітка

Програма несе відповідальність за те, щоб усі пробіли та спеціальні символи були взяті в лапки належним чином, щоб уникнути вразливості впровадження оболонки. Функцію shlex.quote() можна використати для правильного екранування пробілів і спеціальних символів у рядках, які використовуватимуться для створення команд оболонки.

Ручки зворотного виклику

class asyncio.Handle

Об’єкт оболонки зворотного виклику, повернутий loop.call_soon(), loop.call_soon_threadsafe().

cancel()

Скасувати зворотний дзвінок. Якщо зворотний виклик уже скасовано або виконано, цей метод не має ефекту.

cancelled()

Повертає True, якщо зворотний виклик було скасовано.

Нове в версії 3.7.

class asyncio.TimerHandle

Об’єкт оболонки зворотного виклику, повернутий loop.call_later() і loop.call_at().

Цей клас є підкласом Handle.

when()

Повертає запланований час зворотного виклику як float секунди.

Час – це абсолютна позначка часу, яка використовує те саме посилання на час, що й loop.time().

Нове в версії 3.7.

Серверні об’єкти

Серверні об’єкти створюються функціями loop.create_server(), loop.create_unix_server(), start_server() і start_unix_server().

Do not instantiate the class directly.

class asyncio.Server

Об’єкти Server є асинхронними менеджерами контексту. При використанні в операторі async with гарантується, що об’єкт Server закритий і не приймає нових з’єднань після завершення оператора async with:

srv = await loop.create_server(...)

async with srv:
    # some code

# At this point, srv is closed and no longer accepts new connections.

Змінено в версії 3.7: Серверний об’єкт — це асинхронний менеджер контексту, починаючи з Python 3.7.

close()

Зупинити обслуговування: закрийте сокети прослуховування та встановіть для атрибута sockets значення None.

Сокети, які представляють наявні вхідні підключення клієнта, залишаються відкритими.

The server is closed asynchronously, use the wait_closed() coroutine to wait until the server is closed.

get_loop()

Повертає цикл подій, пов’язаний з об’єктом сервера.

Нове в версії 3.7.

coroutine start_serving()

Почніть приймати підключення.

This method is idempotent, so it can be called when the server is already being serving.

Ключовий параметр start_serving для loop.create_server() і asyncio.start_server() дозволяє створити об’єкт сервера, який спочатку не приймає підключення. У цьому випадку Server.start_serving() або Server.serve_forever() можна використати, щоб сервер почав приймати з’єднання.

Нове в версії 3.7.

coroutine serve_forever()

Почніть приймати підключення, доки співпрограму не буде скасовано. Скасування завдання serve_forever призводить до закриття сервера.

Цей метод можна викликати, якщо сервер уже приймає підключення. На один об’єкт Server може існувати лише одне завдання serve_forever.

Приклад:

async def client_connected(reader, writer):
    # Communicate with the client with
    # reader/writer streams.  For example:
    await reader.readline()

async def main(host, port):
    srv = await asyncio.start_server(
        client_connected, host, port)
    await srv.serve_forever()

asyncio.run(main('127.0.0.1', 0))

Нове в версії 3.7.

is_serving()

Повертає True, якщо сервер приймає нові підключення.

Нове в версії 3.7.

coroutine wait_closed()

Wait until the close() method completes.

sockets

List of socket.socket objects the server is listening on.

Змінено в версії 3.7: До Python 3.7 Server.sockets використовувався для безпосереднього повернення внутрішнього списку серверних сокетів. У 3.7 повертається копія цього списку.

Реалізації циклу подій

asyncio постачається з двома різними реалізаціями циклу подій: SelectorEventLoop і ProactorEventLoop.

By default asyncio is configured to use SelectorEventLoop on Unix and ProactorEventLoop on Windows.

class asyncio.SelectorEventLoop

An event loop based on the selectors module.

Використовує найефективніший селектор, доступний для даної платформи. Також можна вручну налаштувати точну реалізацію селектора, яка буде використовуватися:

import asyncio
import selectors

selector = selectors.SelectSelector()
loop = asyncio.SelectorEventLoop(selector)
asyncio.set_event_loop(loop)

Availability: Unix, Windows.

class asyncio.ProactorEventLoop

An event loop for Windows that uses «I/O Completion Ports» (IOCP).

Availability: Windows.

Дивись також

MSDN documentation on I/O Completion Ports.

class asyncio.AbstractEventLoop

Абстрактний базовий клас для асинційно-сумісних циклів подій.

The Event Loop Methods section lists all methods that an alternative implementation of AbstractEventLoop should have defined.

Приклади

Зверніть увагу, що всі приклади в цьому розділі цілеспрямовано показують, як використовувати API циклу подій низького рівня, такі як loop.run_forever() і loop.call_soon(). Сучасні асинхронні програми рідко потрібно писати таким чином; подумайте про використання функцій високого рівня, таких як asyncio.run().

Привіт, світ із 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()

Дивись також

Подібний приклад Hello World, створений за допомогою співпрограми та функції run().

Показати поточну дату за допомогою 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()

Дивись також

Схожий приклад current date, створений за допомогою співпрограми та функції run().

Спостерігайте за подіями читання файлового дескриптора

Зачекайте, доки дескриптор файлу не отримає деякі дані за допомогою методу 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()

Дивись також

• Подібний приклад з використанням транспортів, протоколів і методу loop.create_connection().

• Інший подібний приклад з використанням високорівневої функції asyncio.open_connection() і потоків.

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

(Цей приклад сигналів працює лише в Unix.)

Register handlers for signals SIGINT and SIGTERM using the loop.add_signal_handler() method:

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