# Event loop

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

Передмова

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

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

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

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

asyncio.get_running_loop()

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

  Raise a `RuntimeError` if there is no running event loop.

  This function can only be called from a coroutine or a callback.

  Added in version 3.7.

asyncio.get_event_loop()

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

  When called from a coroutine or a callback (e.g. scheduled with call_soon or similar API), this function will always return the running event loop.

  If there is no running event loop set, the function will return the result of the `get_event_loop_policy().get_event_loop()` call.

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

  As noted above, consider using the higher-level `asyncio.run()` function, instead of using these lower level functions to manually create and close an event loop.

  Змінено в версії 3.14: Raises a `RuntimeError` if there is no current event loop.

  Примітка

  The `asyncio` policy system is deprecated and will be removed in Python 3.16; from there on, this function will return the current running event loop if present else it will return the loop set by `set_event_loop()`.

asyncio.set_event_loop(loop)

  Set loop as the 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 циклу подій.

## Event loop methods

Цикли подій мають 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()

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

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

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

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

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

  Added in version 3.6.

async loop.shutdown_default_executor(timeout=None)

  Schedule the closure of the default executor and wait for it to join all of the threads in the `ThreadPoolExecutor`. Once this method has been called, using the default executor with `loop.run_in_executor()` will raise a `RuntimeError`.

  The timeout parameter specifies the amount of time (in `float` seconds) the executor will be given to finish joining. With the default, `None`, the executor is allowed an unlimited amount of time.

  If the timeout is reached, a `RuntimeWarning` is emitted and the default executor is terminated without waiting for its threads to finish joining.

  Примітка

  Do not call this method when using `asyncio.run()`, as the latter handles default executor shutdown automatically.

  Added in version 3.9.

  Змінено в версії 3.12: Added the timeout parameter.

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

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

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

  Return an instance of `asyncio.Handle`, which can be used later to cancel the callback.

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

  The optional keyword-only context argument specifies a custom `contextvars.Context` for the callback to run in. Callbacks use the current context when no context is provided.

  Unlike `call_soon_threadsafe()`, this method is not thread-safe.

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

  A thread-safe variant of `call_soon()`. When scheduling callbacks from another thread, this function must be used, since `call_soon()` is not thread-safe.

  This function is safe to be called from a reentrant context or signal handler, however, it is not safe or fruitful to use the returned handle in such contexts.

  Викликає `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 буде передзвонено рівно один раз. Якщо два зворотні виклики заплановано на один і той же час, порядок їх викликів не визначений.

  The optional positional args will be passed to the callback when it is called. Use `functools.partial()` to pass keyword arguments to callback.

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

  Примітка

  For performance, callbacks scheduled with `loop.call_later()` may run up to one clock-resolution early (see `time.get_clock_info('monotonic').resolution`).

  Змінено в версії 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`, який можна використовувати для скасування зворотного виклику.

  Примітка

  For performance, callbacks scheduled with `loop.call_at()` may run up to one clock-resolution early (see `time.get_clock_info('monotonic').resolution`).

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

### Creating futures and tasks

loop.create_future()

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

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

  Added in version 3.5.2.

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

  Schedule the execution of coroutine coro. Return a `Task` object.

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

  The full function signature is largely the same as that of the `Task` constructor (or factory) - all of the keyword arguments to this function are passed through to that interface.

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

  An optional keyword-only context argument allows specifying a custom `contextvars.Context` for the coro to run in. The current context copy is created when no context is provided.

  An optional keyword-only eager_start argument allows specifying if the task should execute eagerly during the call to create_task, or be scheduled later. If eager_start is not passed the mode set by `loop.set_task_factory()` will be used.

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

  Змінено в версії 3.11: Added the context parameter.

  Змінено в версії 3.13.3: Added `kwargs` which passes on arbitrary extra parameters, including `name` and `context`.

  Змінено в версії 3.13.4: Rolled back the change that passes on name and context (if it is None), while still passing on other arbitrary keyword arguments (to avoid breaking backwards compatibility with 3.13.3).

  Змінено в версії 3.14: All kwargs are now passed on. The eager_start parameter works with eager task factories.

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, **kwargs)`, where loop is a reference to the active event loop, and coro is a coroutine object. The callable must pass on all kwargs, and return a `asyncio.Task`-compatible object.

  Змінено в версії 3.13.3: Required that all kwargs are passed on to `asyncio.Task`.

  Змінено в версії 3.13.4: name is no longer passed to task factories. context is no longer passed to task factories if it is `None`.

  Змінено в версії 3.14: name and context are now unconditionally passed on to task factories again.

loop.get_task_factory()

  Повертає фабрику завдань або `None`, якщо використовується типова.

### Відкриття мережевих підключень

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

  Відкрийте потокове транспортне з’єднання за вказаною адресою, указаною host і port.

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

    Примітка

    The sock argument transfers ownership of the socket to the transport created. To close the socket, call the transport’s `close()` method.

  - local_addr, якщо вказано, це кортеж `(local_host, local_port)`, який використовується для локального зв’язування сокета. local_host і local_port шукаються за допомогою `getaddrinfo()`, подібно до host і port.

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

  - ssl_shutdown_timeout is the time in seconds to wait for the SSL shutdown to complete before aborting the connection. `30.0` seconds if `None` (default).

  - all_errors determines what exceptions are raised when a connection cannot be created. By default, only a single `Exception` is raised: the first exception if there is only one or all errors have same message, or a single `OSError` with the error messages combined. When `all_errors` is `True`, an `ExceptionGroup` will be raised containing all exceptions (even if there is only one).

  Змінено в версії 3.5: Додано підтримку SSL/TLS у `ProactorEventLoop`.

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

  Змінено в версії 3.7: Додано параметр ssl_handshake_timeout.

  Змінено в версії 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://datatracker.ietf.org/doc/html/rfc6555

  Змінено в версії 3.11: Added the ssl_shutdown_timeout parameter.

  Змінено в версії 3.12: all_errors was added.

  Дивись також

  Функція `open_connection()` є альтернативним API високого рівня. Він повертає пару (`StreamReader`, `StreamWriter`), яку можна використовувати безпосередньо в коді async/await.

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

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

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

    Примітка

    On Windows, when using the proactor event loop with `local_addr=None`, an `OSError` with `errno.WSAEINVAL` will be raised when running it.

  - 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 socket.SO_REUSEPORT constant is not defined then this capability is unsupported.

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

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

    Примітка

    The sock argument transfers ownership of the socket to the transport created. To close the socket, call the transport’s `close()` method.

  Перегляньте приклади 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: Додана підтримка Windows.

  Змінено в версії 3.8.1: The reuse_address parameter is no longer supported, as using socket.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, socket.SO_REUSEPORT is used instead, which specifically prevents processes with differing UIDs from assigning sockets to the same socket address.

  Змінено в версії 3.11: The reuse_address parameter, disabled since Python 3.8.1, 3.7.6 and 3.6.10, has been entirely removed.

async loop.create_unix_connection(protocol_factory, path=None, *, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_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: Додано параметр ssl_handshake_timeout. Параметр path тепер може бути path-like object.

  Змінено в версії 3.11: Added the ssl_shutdown_timeout parameter.

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

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

  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 не повинні вказуватися.

    Примітка

    The sock argument transfers ownership of the socket to the server created. To close the socket, call the server’s `close()` method.

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

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

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

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

  - keep_alive set to `True` keeps connections active by enabling the periodic transmission of messages.

  Змінено в версії 3.13: Added the keep_alive parameter.

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

  - ssl_shutdown_timeout is the time in seconds to wait for the SSL shutdown to complete before aborting the connection. `30.0` seconds if `None` (default).

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

  Змінено в версії 3.5: Додано підтримку SSL/TLS у `ProactorEventLoop`.

  Змінено в версії 3.5.1: Параметр host може бути послідовністю рядків.

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

  Змінено в версії 3.11: Added the ssl_shutdown_timeout parameter.

  Дивись також

  Функція `start_server()` — це альтернативний API вищого рівня, який повертає пару `StreamReader` і `StreamWriter`, які можна використовувати в коді async/await.

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

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

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

  If cleanup_socket is true then the Unix socket will automatically be removed from the filesystem when the server is closed, unless the socket has been replaced after the server has been created.

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

  Availability: Unix.

  Змінено в версії 3.7: Додано параметри ssl_handshake_timeout і start_serving. Параметр path тепер може бути об’єктом `Path`.

  Змінено в версії 3.11: Added the ssl_shutdown_timeout parameter.

  Змінено в версії 3.13: Added the cleanup_socket parameter.

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

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

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

  Параметри:

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

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

    Примітка

    The sock argument transfers ownership of the socket to the transport created. To close the socket, call the transport’s `close()` method.

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

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

  - ssl_shutdown_timeout is the time in seconds to wait for the SSL shutdown to complete before aborting the connection. `30.0` seconds if `None` (default).

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

  Added in version 3.5.3.

  Змінено в версії 3.7: Додано параметр ssl_handshake_timeout.

  Змінено в версії 3.11: Added the ssl_shutdown_timeout parameter.

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

async 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`.

  Added in version 3.7.

### TLS upgrade

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

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

  Create a TLS coder/decoder instance and insert it between the transport and the protocol. The coder/decoder implements both transport-facing protocol and protocol-facing transport.

  Return the created two-interface instance. After await, the protocol must stop using the original transport and communicate with the returned object only because the coder caches protocol-side data and sporadically exchanges extra TLS session packets with transport.

  In some situations (e.g. when the passed transport is already closing) this may return `None`.

  Параметри:

  - екземпляри transport і protocol, які повертають такі методи, як `create_server()` і `create_connection()`.

  - sslcontext: налаштований екземпляр `SSLContext`.

  - server_side передає `True`, коли з’єднання на стороні сервера оновлюється (наприклад, створене `create_server()`).

  - server_hostname: встановлює або замінює ім’я хоста, з яким буде зіставлятися сертифікат цільового сервера.

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

  - ssl_shutdown_timeout is the time in seconds to wait for the SSL shutdown to complete before aborting the connection. `30.0` seconds if `None` (default).

  Added in version 3.7.

  Змінено в версії 3.11: Added the ssl_shutdown_timeout parameter.

### Перегляд дескрипторів файлів

loop.add_reader(fd, callback, *args)

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

  Any preexisting callback registered for fd is cancelled and replaced by callback.

loop.remove_reader(fd)

  Stop monitoring the fd file descriptor for read availability. Returns `True` if fd was previously being monitored for reads.

loop.add_writer(fd, callback, *args)

  Start monitoring the fd file descriptor for write availability and invoke callback with the specified arguments args once fd is available for writing.

  Any preexisting callback registered for fd is cancelled and replaced by callback.

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

loop.remove_writer(fd)

  Stop monitoring the fd file descriptor for write availability. Returns `True` if fd was previously being monitored for writes.

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

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

Загалом, реалізації протоколів, які використовують API на основі транспорту, такі як `loop.create_connection()` і `loop.create_server()`, є швидшими, ніж реалізації, які працюють безпосередньо з сокетами. Однак є деякі випадки використання, коли продуктивність не є критичною, і працювати з об’єктами `socket` напряму зручніше.

async loop.sock_recv(sock, nbytes)

  Отримайте до nbytes від sock. Асинхронна версія `socket.recv()`.

  Повернути отримані дані як об’єкт bytes.

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

  Змінено в версії 3.7: Незважаючи на те, що цей метод завжди документувався як метод співпрограми, випуски до Python 3.7 повертали `Future`. Починаючи з Python 3.7, це метод `async def`.

async loop.sock_recv_into(sock, buf)

  Отримувати дані з sock в буфер buf. Створено за методом блокування `socket.recv_into()`.

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

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

  Added in version 3.7.

async loop.sock_recvfrom(sock, bufsize)

  Receive a datagram of up to bufsize from sock. Asynchronous version of `socket.recvfrom()`.

  Return a tuple of (received data, remote address).

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

  Added in version 3.11.

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

  Receive a datagram of up to nbytes from sock into buf. Asynchronous version of `socket.recvfrom_into()`.

  Return a tuple of (number of bytes received, remote address).

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

  Added in version 3.11.

async loop.sock_sendall(sock, data)

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

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

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

  Змінено в версії 3.7: Незважаючи на те, що метод завжди документувався як метод співпрограми, до Python 3.7 він повертав `Future`. Починаючи з Python 3.7, це метод `async def`.

async loop.sock_sendto(sock, data, address)

  Send a datagram from sock to address. Asynchronous version of `socket.sendto()`.

  Return the number of bytes sent.

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

  Added in version 3.11.

async 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()`.

async 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()`.

async 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 має бути неблокуючим сокетом.

  Added in version 3.7.

### DNS

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

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

async loop.getnameinfo(sockaddr, flags=0)

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

Примітка

Both getaddrinfo and getnameinfo internally utilize their synchronous versions through the loop’s default thread pool executor. When this executor is saturated, these methods may experience delays, which higher-level networking libraries may report as increased timeouts. To mitigate this, consider using a custom executor for other user tasks, or setting a default executor with a larger number of workers.

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

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

async loop.connect_read_pipe(protocol_factory, pipe)

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

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

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

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

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

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

  Set callback as the handler for the signum signal, passing args as positional arguments.

  Зворотний виклик буде викликаний циклом разом з іншими зворотними викликами в черзі та запущеними співпрограмами цього циклу подій. На відміну від обробників сигналів, зареєстрованих за допомогою `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)

  Arrange for func to be called in the specified executor passing args as positional arguments.

  The executor argument should be an `concurrent.futures.Executor` instance. The default executor is used if executor is `None`. The default executor can be set by `loop.set_default_executor()`, otherwise, a `concurrent.futures.ThreadPoolExecutor` will be lazy-initialized and used by `run_in_executor()` if needed.

  Приклад:

      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)

          # 4. Run in a custom interpreter pool:
          with concurrent.futures.InterpreterPoolExecutor() as pool:
              result = await loop.run_in_executor(
                  pool, cpu_bound)
              print('custom interpreter pool', result)

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

  Note that the entry point guard (`if __name__ == '__main__'`) is required for option 3 due to the peculiarities of `multiprocessing`, which is used by `ProcessPoolExecutor`. See Safe importing of main module.

  Цей метод повертає об’єкт `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 must be an instance of `ThreadPoolExecutor`, which includes `InterpreterPoolExecutor`.

  Змінено в версії 3.11: executor must be an instance of `ThreadPoolExecutor`.

### Error handling API

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

loop.set_exception_handler(handler)

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

  Якщо обробник має значення `None`, буде встановлено обробник винятків за умовчанням. В іншому випадку обробник має бути викликом із сигнатурою, що відповідає `(цикл, контекст)`, де `цикл` є посиланням на активний цикл подій, а `контекст` є `dict` об’єкт, що містить деталі винятку (перегляньте документацію `call_exception_handler()`, щоб дізнатися більше про контекст).

  If the handler is called on behalf of a `Task` or `Handle`, it is run in the `contextvars.Context` of that task or callback handle.

  Змінено в версії 3.12: The handler may be called in the `Context` of the task or handle where the exception originated.

loop.get_exception_handler()

  Повертає поточний обробник винятків або `None`, якщо настроюваний обробник винятків не встановлено.

  Added in version 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` екземпляр;

  - „source_traceback“ (optional): Traceback of the source;

  - „handle_traceback“ (optional): Traceback of the handle;

  - „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 тепер також можна використовувати для ввімкнення режиму налагодження.

loop.slow_callback_duration

  This attribute can be used to set the minimum execution duration in seconds that is considered «slow». When debug mode is enabled, «slow» callbacks are logged.

  Default value is 100 milliseconds.

Дивись також

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

### Running subprocesses

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

Примітка

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

async 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

    - an existing file descriptor (a positive integer), for example those created with `os.pipe()`

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

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

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

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

    - a file-like object

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

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

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

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

    - a file-like object

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

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

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

    - константа `subprocess.STDOUT`, яка підключатиме стандартний потік помилок до стандартного потоку виводу процесу

  - Усі інші аргументи ключових слів передаються до `subprocess.Popen` без інтерпретації, за винятком bufsize, universal_newlines, shell, text, encoding і errors, які не слід вказувати в все.

    API підпроцесу `asyncio` не підтримує декодування потоків як тексту. `bytes.decode()` можна використовувати для перетворення байтів, повернутих із потоку, на текст.

  If a file-like object passed as stdin, stdout or stderr represents a pipe, then the other side of this pipe should be registered with `connect_write_pipe()` or `connect_read_pipe()` for use with the event loop.

  Перегляньте конструктор класу `subprocess.Popen` для документації щодо інших аргументів.

  Повертає пару «(transport, protocol)», де transport відповідає базовому класу `asyncio.SubprocessTransport`, а protocol є об’єктом, створеним protocol_factory.

  If the transport is closed or is garbage collected, the child process is killed if it is still running.

async 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.

  If the transport is closed or is garbage collected, the child process is killed if it is still running.

Примітка

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

## Callback handles

class asyncio.Handle

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

  get_context()

    Return the `contextvars.Context` object associated with the handle.

    Added in version 3.12.

  cancel()

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

  cancelled()

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

    Added in version 3.7.

class asyncio.TimerHandle

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

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

  when()

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

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

    Added in version 3.7.

## Server objects

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

Do not instantiate the `Server` 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.

  Змінено в версії 3.11: This class was exposed publicly as `asyncio.Server` in Python 3.9.11, 3.10.3 and 3.11.

  close()

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

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

    The server is closed asynchronously; use the `wait_closed()` coroutine to wait until the server is closed (and no more connections are active).

  close_clients()

    Close all existing incoming client connections.

    Calls `close()` on all associated transports.

    `close()` should be called before `close_clients()` when closing the server to avoid races with new clients connecting.

    Added in version 3.13.

  abort_clients()

    Close all existing incoming client connections immediately, without waiting for pending operations to complete.

    Calls `abort()` on all associated transports.

    `close()` should be called before `abort_clients()` when closing the server to avoid races with new clients connecting.

    Added in version 3.13.

  get_loop()

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

    Added in version 3.7.

  async start_serving()

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

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

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

    Added in version 3.7.

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

    Added in version 3.7.

  is_serving()

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

    Added in version 3.7.

  async wait_closed()

    Wait until the `close()` method completes and all active connections have finished.

  sockets

    List of socket-like objects, `asyncio.trsock.TransportSocket`, which the server is listening on.

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

## Event loop implementations

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

By default asyncio is configured to use `EventLoop`.

class asyncio.SelectorEventLoop

  A subclass of `AbstractEventLoop` based on the `selectors` module.

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

      import asyncio
      import selectors

      async def main():
         ...

      loop_factory = lambda: asyncio.SelectorEventLoop(selectors.SelectSelector())
      asyncio.run(main(), loop_factory=loop_factory)

  Availability: Unix, Windows.

class asyncio.ProactorEventLoop

  A subclass of `AbstractEventLoop` for Windows that uses «I/O Completion Ports» (IOCP).

  Availability: Windows.

  Дивись також

  MSDN documentation on I/O Completion Ports.

class asyncio.EventLoop

  > An alias to the most efficient available subclass of `AbstractEventLoop` for the given platform.

  > It is an alias to `SelectorEventLoop` on Unix and `ProactorEventLoop` on Windows.

  Added in version 3.13.

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

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

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

Дивись також

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

### Показати поточну дату за допомогою call_later()

Приклад зворотного виклику, що відображає поточну дату кожну секунду. Зворотний виклик використовує метод `loop.call_later()`, щоб перепланувати себе через 5 секунд, а потім зупинити цикл подій:

    import asyncio
    import datetime as dt

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

    loop = asyncio.new_event_loop()

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

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

Дивись також

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

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

Зачекайте, доки дескриптор файлу не отримає деякі дані за допомогою методу `loop.add_reader()`, а потім закрийте цикл подій:

    import asyncio
    from socket import socketpair

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

    loop = asyncio.new_event_loop()

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

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

        # Stop the event loop
        loop.stop()

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

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

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

Дивись також

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

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

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

(This `signal` example only works on 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())