`asyncio-protocol.md`

753 строк · 52.5 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.9/library/asyncio-protocol.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Транспорты и протоколы89Предисловие1011Транспорты и протоколы используются **низкоуровневыми** API цикла событий, такими как [`loop.create_connection()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.create_connection). Они используют стиль программирования на основе колбэков и позволяют создавать высокопроизводительные реализации сетевых протоколов и протоколов межпроцессного взаимодействия (например, HTTP).1213По существу, транспорты и протоколы следует использовать только в библиотеках и фреймворках, но никогда в высокоуровневых приложениях asyncio.1415Эта страница документации охватывает как [транспорты](https://python-all.ru/3.9/library/asyncio-protocol.html#transports), так и [протоколы](https://python-all.ru/3.9/library/asyncio-protocol.html#protocols).1617Введение1819На самом высоком уровне транспорт отвечает за *то, как* передаются байты, тогда как протокол определяет, *какие* байты передавать (и в некоторой степени – когда).2021Другими словами: транспорт – это абстракция для сокета (или аналогичной точки ввода-вывода), а протокол – это абстракция для приложения с точки зрения транспорта.2223Ещё один взгляд: интерфейсы транспорта и протокола вместе определяют абстрактный интерфейс для использования сетевого ввода-вывода и межпроцессного ввода-вывода.2425Между объектами транспорта и протокола всегда существует отношение 1:1: протокол вызывает методы транспорта для отправки данных, а транспорт вызывает методы протокола, чтобы передать ему полученные данные.2627Большинство методов цикла событий, ориентированных на соединения (таких как [`loop.create_connection()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.create_connection)), обычно принимают аргумент *protocol\_factory*, используемый для создания объекта *Protocol* для принятого соединения, представленного объектом *Transport*. Такие методы обычно возвращают кортеж `(transport, protocol)`.2829Содержание3031Эта страница документации содержит следующие разделы:3233- Раздел [Transports](https://python-all.ru/3.9/library/asyncio-protocol.html#transports) описывает классы asyncio [`BaseTransport`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.BaseTransport), [`ReadTransport`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.ReadTransport), [`WriteTransport`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.WriteTransport), [`Transport`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.Transport), [`DatagramTransport`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.DatagramTransport) и [`SubprocessTransport`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.SubprocessTransport).34- Раздел [Protocols](https://python-all.ru/3.9/library/asyncio-protocol.html#protocols) описывает классы asyncio [`BaseProtocol`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.BaseProtocol), [`Protocol`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.Protocol), [`BufferedProtocol`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.BufferedProtocol), [`DatagramProtocol`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.DatagramProtocol) и [`SubprocessProtocol`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.SubprocessProtocol).35- Раздел [Examples](https://python-all.ru/3.9/library/asyncio-protocol.html#examples) показывает, как работать с транспортами, протоколами и низкоуровневыми API цикла событий.3637## Транспорты3839**Исходный код:** [Lib/asyncio/transports.py](https://python-all.ru/src/3.9/Lib/asyncio/transports.py)4041---4243Транспорты – это классы, предоставляемые [`asyncio`](https://python-all.ru/3.9/library/asyncio.html#module-asyncio) для абстракции различных видов каналов связи.4445Объекты транспорта всегда создаются [циклом событий asyncio](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio-event-loop).4647asyncio реализует транспорты для TCP, UDP, SSL и каналов подпроцессов. Доступные методы транспорта зависят от его типа.4849Классы транспортов [не потокобезопасны](https://python-all.ru/3.9/library/asyncio-dev.html#asyncio-multithreading).5051### Иерархия транспортов5253#### `class asyncio.BaseTransport`5455Базовый класс для всех транспортов. Содержит методы, общие для всех транспортов asyncio.5657#### `class asyncio.WriteTransport(BaseTransport)`5859Базовый транспорт для соединений только на запись.6061Экземпляры класса *WriteTransport* возвращаются из метода цикла событий [`loop.connect_write_pipe()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.connect_write_pipe), а также используются методами, связанными с подпроцессами, такими как [`loop.subprocess_exec()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.subprocess_exec).6263#### `class asyncio.ReadTransport(BaseTransport)`6465Базовый транспорт для соединений только на чтение.6667Экземпляры класса *ReadTransport* возвращаются из метода цикла событий [`loop.connect_read_pipe()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.connect_read_pipe), а также используются методами, связанными с подпроцессами, такими как [`loop.subprocess_exec()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.subprocess_exec).6869#### `class asyncio.Transport(WriteTransport, ReadTransport)`7071Интерфейс, представляющий двунаправленный транспорт, такой как TCP-соединение.7273Пользователь не создаёт транспорт напрямую; он вызывает вспомогательную функцию, передавая фабрику протокола и другие сведения, необходимые для создания транспорта и протокола.7475Экземпляры класса *транспорт* возвращаются или используются методами цикла событий, например [`loop.create_connection()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.create_connection), [`loop.create_unix_connection()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.create_unix_connection), [`loop.create_server()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.create_server), [`loop.sendfile()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.sendfile) и т.д.7677#### `class asyncio.DatagramTransport(BaseTransport)`7879Транспорт для дейтаграммных (UDP) соединений.8081Экземпляры класса *DatagramTransport* возвращаются из метода цикла событий [`loop.create_datagram_endpoint()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.create_datagram_endpoint).8283#### `class asyncio.SubprocessTransport(BaseTransport)`8485Абстракция, представляющая соединение между родительским и дочерним процессом ОС.8687Экземпляры класса *SubprocessTransport* возвращаются из методов цикла событий [`loop.subprocess_shell()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.subprocess_shell) и [`loop.subprocess_exec()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.subprocess_exec).8889### Базовый транспорт9091#### `BaseTransport.close()`9293Закрывает транспорт.9495Если у транспорта есть буфер для исходящих данных, буферизованные данные будут сброшены асинхронно. Новые данные приниматься не будут. После того как все буферизованные данные будут сброшены, метод [`protocol.connection_lost()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.BaseProtocol.connection_lost) протокола будет вызван с [`None`](https://python-all.ru/3.9/library/constants.html#None) в качестве аргумента.9697#### `BaseTransport.is_closing()`9899Возвращает `True`, если транспорт закрывается или уже закрыт.100101#### `BaseTransport.get_extra_info(name, default=None)`102103Возвращает информацию о транспорте или используемых им базовых ресурсах.104105*name* – строка, представляющая запрашиваемую часть информации, специфичной для транспорта.106107*default* – значение, возвращаемое, если информация недоступна, либо если транспорт не поддерживает её запрос с данной сторонней реализацией цикла событий или на текущей платформе.108109Например, следующий код пытается получить базовый объект сокета транспорта:110111```python112sock = transport.get_extra_info('socket')113if sock is not None:114    print(sock.getsockopt(...))115```116117Категории информации, которые можно запросить для некоторых транспортов:118119- сокет:120121  - `'peername'`: удалённый адрес, к которому подключён сокет, результат [`socket.socket.getpeername()`](https://python-all.ru/3.9/library/socket.html#socket.socket.getpeername) (`None` в случае ошибки)122  - `'socket'`: экземпляр [`socket.socket`](https://python-all.ru/3.9/library/socket.html#socket.socket)123  - `'sockname'`: собственный адрес сокета, результат [`socket.socket.getsockname()`](https://python-all.ru/3.9/library/socket.html#socket.socket.getsockname)124- SSL-сокет:125126  - `'compression'`: используемый алгоритм сжатия в виде строки, или `None`, если соединение не сжато; результат [`ssl.SSLSocket.compression()`](https://python-all.ru/3.9/library/ssl.html#ssl.SSLSocket.compression)127  - `'cipher'`: кортеж из трёх значений, содержащий название используемого шифра, версию протокола SSL, определяющую его использование, и количество используемых секретных бит; результат [`ssl.SSLSocket.cipher()`](https://python-all.ru/3.9/library/ssl.html#ssl.SSLSocket.cipher)128  - `'peercert'`: сертификат однорангового узла; результат [`ssl.SSLSocket.getpeercert()`](https://python-all.ru/3.9/library/ssl.html#ssl.SSLSocket.getpeercert)129  - `'sslcontext'`: экземпляр [`ssl.SSLContext`](https://python-all.ru/3.9/library/ssl.html#ssl.SSLContext)130  - `'ssl_object'`: экземпляр [`ssl.SSLObject`](https://python-all.ru/3.9/library/ssl.html#ssl.SSLObject) или [`ssl.SSLSocket`](https://python-all.ru/3.9/library/ssl.html#ssl.SSLSocket)131- канал:132133  - `'pipe'`: объект канала134- подпроцесс:135136  - `'subprocess'`: экземпляр [`subprocess.Popen`](https://python-all.ru/3.9/library/subprocess.html#subprocess.Popen)137138#### `BaseTransport.set_protocol(protocol)`139140Устанавливает новый протокол.141142Переключать протокол следует только при условии, что оба протокола документированы как поддерживающие переключение.143144#### `BaseTransport.get_protocol()`145146Возвращает текущий протокол.147148### Транспорты только для чтения149150#### `ReadTransport.is_reading()`151152Возвращает `True`, если транспорт получает новые данные.153154Добавлено в версии 3.7.155156#### `ReadTransport.pause_reading()`157158Приостанавливает приёмную сторону транспорта. Данные не будут передаваться методу [`protocol.data_received()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.Protocol.data_received) протокола до тех пор, пока не будет вызван [`resume_reading()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.ReadTransport.resume_reading).159160Изменено в версии 3.7: Метод идемпотентен, то есть его можно вызывать, когда транспорт уже приостановлен или закрыт.161162#### `ReadTransport.resume_reading()`163164Возобновляет приёмную сторону. Метод протокола [`protocol.data_received()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.Protocol.data_received) будет вызван снова, если для чтения доступны какие-либо данные.165166Изменено в версии 3.7: Метод идемпотентен, то есть его можно вызывать, когда транспорт уже читает.167168### Транспорты только для записи169170#### `WriteTransport.abort()`171172Закрывает транспорт немедленно, не дожидаясь ожидающих операций до завершения. Буферизованные данные будут потеряны. Новые данные приниматься не будут. Метод [`protocol.connection_lost()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.BaseProtocol.connection_lost) протокола в конечном итоге будет вызван с аргументом [`None`](https://python-all.ru/3.9/library/constants.html#None).173174#### `WriteTransport.can_write_eof()`175176Возвращает [`True`](https://python-all.ru/3.9/library/constants.html#True), если транспорт поддерживает [`write_eof()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.WriteTransport.write_eof), и [`False`](https://python-all.ru/3.9/library/constants.html#False) в противном случае.177178#### `WriteTransport.get_write_buffer_size()`179180Возвращает текущий размер выходного буфера, используемого транспортом.181182#### `WriteTransport.get_write_buffer_limits()`183184Get the *high* and *low* watermarks for write flow control. Return a tuple `(low, high)` where *low* and *high* are positive number of bytes.185186Используйте [`set_write_buffer_limits()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.WriteTransport.set_write_buffer_limits) для установки границ.187188Новое в версии 3.4.2.189190#### `WriteTransport.set_write_buffer_limits(high=None, low=None)`191192Устанавливает *верхнюю* и *нижнюю* границы для управления потоком записи.193194Эти два значения (измеряются в количестве байтов) управляют, когда методы протокола [`protocol.pause_writing()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.BaseProtocol.pause_writing) и [`protocol.resume_writing()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.BaseProtocol.resume_writing) вызываются. Если заданы, нижняя граница должна быть меньше или равна верхней. Ни *верхняя*, ни *нижняя* не могут быть отрицательными.195196[`pause_writing()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.BaseProtocol.pause_writing) вызывается, когда размер буфера становится больше или равен *верхнему* значению. Если запись была приостановлена, [`resume_writing()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.BaseProtocol.resume_writing) вызывается, когда размер буфера становится меньше или равен *нижнему* значению.197198Значения по умолчанию зависят от реализации. Если задан только верхний порог, нижний порог по умолчанию принимает зависящее от реализации значение, меньшее или равное верхнему. Установка *верхнего* порога в ноль приводит к тому, что *нижний* также становится нулевым, и [`pause_writing()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.BaseProtocol.pause_writing) будет вызываться всякий раз, когда буфер становится непустым. Установка *нижнего* порога в ноль приводит к тому, что [`resume_writing()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.BaseProtocol.resume_writing) будет вызываться только когда буфер опустеет. Использование нуля для любого порога в целом неоптимально, так как сокращает возможности для одновременного выполнения ввода-вывода и вычислений.199200[`get_write_buffer_limits()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.WriteTransport.get_write_buffer_limits) используется для получения ограничений.201202#### `WriteTransport.write(data)`203204Записывает несколько байт *данных* в транспорт.205206Этот метод не блокирует выполнение; он буферизует данные и обеспечивает их асинхронную отправку.207208#### `WriteTransport.writelines(list_of_data)`209210Записывает в транспорт список (или любой итерируемый объект) из байт данных. Функционально это эквивалентно вызову [`write()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.WriteTransport.write) для каждого элемента, полученного из итерируемого объекта, но может быть реализовано более эффективно.211212#### `WriteTransport.write_eof()`213214Закрывает записывающий конец транспорта после сброса всех буферизованных данных. Данные всё ещё могут приниматься.215216Этот метод может вызывать [`NotImplementedError`](https://python-all.ru/3.9/library/exceptions.html#NotImplementedError), если транспорт (например, SSL) не поддерживает полузакрытые соединения.217218### Дейтаграммные транспорты219220#### `DatagramTransport.sendto(data, addr=None)`221222Отправляет байты *данных* удаленному узлу, задаваемому *addr* (адрес назначения, зависящий от транспорта). Если *addr* равно [`None`](https://python-all.ru/3.9/library/constants.html#None), данные отправляются на адрес назначения, указанный при создании транспорта.223224Этот метод не блокирует выполнение; он буферизует данные и организует их асинхронную отправку.225226#### `DatagramTransport.abort()`227228Немедленно закрывает транспорт, не дожидаясь завершения ожидающих операций. Буферизованные данные будут потеряны. Приём данных прекратится. Метод [`protocol.connection_lost()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.BaseProtocol.connection_lost) протокола в конечном итоге будет вызван с [`None`](https://python-all.ru/3.9/library/constants.html#None) в качестве аргумента.229230### Транспорты подпроцессов231232#### `SubprocessTransport.get_pid()`233234Возвращает идентификатор процесса подпроцесса в виде целого числа.235236#### `SubprocessTransport.get_pipe_transport(fd)`237238Возвращает транспорт для канала связи, соответствующего целочисленному файловому дескриптору *fd*:239240- `0`: читаемый потоковый транспорт стандартного ввода (*stdin*) или [`None`](https://python-all.ru/3.9/library/constants.html#None), если подпроцесс был создан без `stdin=PIPE`241- `1`: записываемый потоковый транспорт стандартного вывода (*stdout*) или [`None`](https://python-all.ru/3.9/library/constants.html#None), если подпроцесс был создан без `stdout=PIPE`242- `2`: записываемый потоковый транспорт стандартного вывода ошибок (*stderr*) или [`None`](https://python-all.ru/3.9/library/constants.html#None), если подпроцесс был создан без `stderr=PIPE`243- другой *fd*: [`None`](https://python-all.ru/3.9/library/constants.html#None)244245#### `SubprocessTransport.get_returncode()`246247Возвращает код возврата подпроцесса в виде целого числа или [`None`](https://python-all.ru/3.9/library/constants.html#None), если подпроцесс ещё не завершился, что аналогично атрибуту [`subprocess.Popen.returncode`](https://python-all.ru/3.9/library/subprocess.html#subprocess.Popen.returncode).248249#### `SubprocessTransport.kill()`250251Завершает подпроцесс.252253В системах POSIX функция отправляет подпроцессу сигнал SIGKILL. В Windows этот метод является псевдонимом для [`terminate()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.SubprocessTransport.terminate).254255См. также [`subprocess.Popen.kill()`](https://python-all.ru/3.9/library/subprocess.html#subprocess.Popen.kill).256257#### `SubprocessTransport.send_signal(signal)`258259Отправляет подпроцессу номер *signal*, как в [`subprocess.Popen.send_signal()`](https://python-all.ru/3.9/library/subprocess.html#subprocess.Popen.send_signal).260261#### `SubprocessTransport.terminate()`262263Останавливает подпроцесс.264265На системах POSIX этот метод отправляет сигнал SIGTERM подпроцессу. В Windows вызывается функция Windows API TerminateProcess() для остановки подпроцесса.266267См. также [`subprocess.Popen.terminate()`](https://python-all.ru/3.9/library/subprocess.html#subprocess.Popen.terminate).268269#### `SubprocessTransport.close()`270271Завершает подпроцесс вызовом метода [`kill()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.SubprocessTransport.kill).272273Если подпроцесс ещё не завершён, закрывает транспорты каналов *stdin*, *stdout* и *stderr*.274275## Протоколы276277**Исходный код:** [Lib/asyncio/protocols.py](https://python-all.ru/src/3.9/Lib/asyncio/protocols.py)278279---280281asyncio предоставляет набор абстрактных базовых классов, которые следует использовать для реализации сетевых протоколов. Они предназначены для использования вместе с [транспортами](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio-transport).282283Подклассы абстрактных базовых классов протоколов могут реализовывать часть методов или все. Все эти методы – колбэки: они вызываются транспортами при определённых событиях, например, при получении данных. Метод базового протокола должен вызываться соответствующим транспортом.284285### Базовые протоколы286287#### `class asyncio.BaseProtocol`288289Базовый протокол, содержащий методы, общие для всех протоколов.290291#### `class asyncio.Protocol(BaseProtocol)`292293Базовый класс для реализации потоковых протоколов (TCP, сокеты Unix и т.д.).294295#### `class asyncio.BufferedProtocol(BaseProtocol)`296297Базовый класс для реализации потоковых протоколов с ручным управлением буфером приёма.298299#### `class asyncio.DatagramProtocol(BaseProtocol)`300301Базовый класс для реализации дейтаграммных протоколов (UDP).302303#### `class asyncio.SubprocessProtocol(BaseProtocol)`304305Базовый класс для реализации протоколов, взаимодействующих с дочерними процессами (однонаправленные каналы).306307### Базовый протокол308309Все протоколы asyncio могут реализовывать колбэки базового протокола.310311Колбэки соединения312313Колбэки соединения вызываются для всех протоколов ровно один раз при каждом успешном соединении. Все остальные колбэки протокола могут вызываться только между этими двумя методами.314315#### `BaseProtocol.connection_made(transport)`316317Вызывается при установлении соединения.318319Аргумент *transport* – это транспорт, представляющий соединение. Протокол отвечает за хранение ссылки на свой транспорт.320321#### `BaseProtocol.connection_lost(exc)`322323Вызывается при потере или закрытии соединения.324325The argument is either an exception object or [`None`](https://python-all.ru/3.9/library/constants.html#None). The latter means a regular EOF is received, or the connection was aborted or closed by this side of the connection.326327Колбэки управления потоком328329Транспорты могут вызывать колбэки управления потоком, чтобы приостановить или возобновить запись, выполняемую протоколом.330331Подробнее см. в документации метода [`set_write_buffer_limits()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.WriteTransport.set_write_buffer_limits) .332333#### `BaseProtocol.pause_writing()`334335Вызывается, когда буфер транспорта превышает верхнюю границу.336337#### `BaseProtocol.resume_writing()`338339Вызывается, когда буфер транспорта опускается ниже нижней границы.340341Если размер буфера равен верхней границе, [`pause_writing()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.BaseProtocol.pause_writing) не вызывается: размер буфера должен быть строго больше.342343И наоборот, [`resume_writing()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.BaseProtocol.resume_writing) вызывается, когда размер буфера равен нижней границе или меньше её. Эти граничные условия важны, чтобы всё работало ожидаемым образом, когда любая из границ равна нулю.344345### Потоковые протоколы346347Методы событий, такие как [`loop.create_server()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.create_server), [`loop.create_unix_server()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.create_unix_server), [`loop.create_connection()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.create_connection), [`loop.create_unix_connection()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.create_unix_connection), [`loop.connect_accepted_socket()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.connect_accepted_socket), [`loop.connect_read_pipe()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.connect_read_pipe) и [`loop.connect_write_pipe()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.connect_write_pipe), принимают фабрики, возвращающие потоковые протоколы.348349#### `Protocol.data_received(data)`350351Вызывается при получении данных. *data* – это непустой bytes объект, содержащий входящие данные.352353То, буферизуются ли данные, разбиваются на части или собираются заново, зависит от tранспорта. В общем случае не следует полагаться на конкретную семантику, а вместо этого делать парсинг общим и гибким. Однако данные всегда принимаются в правильном порядке.354355Метод может вызываться произвольное количество раз, пока соединение открыто.356357Однако [`protocol.eof_received()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.Protocol.eof_received) вызывается не более одного раза. После вызова *eof\_received()*, `data_received()` больше не вызывается.358359#### `Protocol.eof_received()`360361Вызывается, когда удалённая сторона сигнализирует, что больше не будет отправлять данные (например, вызовом [`transport.write_eof()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.WriteTransport.write_eof), если другая сторона также использует asyncio).362363Этот метод может вернуть ложное значение (включая `None`), и в этом случае транспорт закроется сам. И наоборот, если метод возвращает истинное значение, используемый протокол определяет, закрывать ли транспорт. Поскольку реализация по умолчанию возвращает `None`, она неявно закрывает соединение.364365Некоторые транспорты, включая SSL, не поддерживают полузакрытые соединения, и в этом случае возврат истинного значения из этого метода приведёт к закрытию соединения.366367Автомат состояний:368369```text370start -> connection_made371    [-> data_received]*372    [-> eof_received]?373-> connection_lost -> end374```375376### Буферизованные потоковые протоколы377378Добавлено в версии 3.7.379380Буферизованные протоколы могут использоваться с любым методом цикла событий, который поддерживает [потоковые протоколы](https://python-all.ru/3.9/library/asyncio-protocol.html#streaming-protocols).381382Реализации `BufferedProtocol` позволяют явное ручное выделение и управление буфером приёма. Циклы событий могут затем использовать буфер, предоставленный протоколом, чтобы избежать лишнего копирования данных. Это может привести к заметному повышению производительности для протоколов, которые получают большие объёмы данных. Сложные реализации протоколов могут значительно сократить количество выделений буфера.383384Следующие колбэки вызываются на экземплярах [`BufferedProtocol`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.BufferedProtocol) :385386#### `BufferedProtocol.get_buffer(sizehint)`387388Вызывается для выделения нового буфера приёма.389390*sizehint* – это рекомендуемый минимальный размер для возвращаемого буфера. Допускается возвращать буферы меньше или больше, чем предлагает *sizehint*. Если установлено -1, размер буфера может быть произвольным. Возвращать буфер нулевого размера – ошибка.391392`get_buffer()` должен возвращать объект, реализующий [буферный протокол](https://python-all.ru/3.9/c-api/buffer.html#bufferobjects).393394#### `BufferedProtocol.buffer_updated(nbytes)`395396Вызывается, когда буфер был обновлён полученными данными.397398*nbytes* – общее количество байтов, записанных в буфер.399400#### `BufferedProtocol.eof_received()`401402См. документацию метода [`protocol.eof_received()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.Protocol.eof_received).403404[`get_buffer()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.BufferedProtocol.get_buffer) может вызываться произвольное число раз во время соединения. Однако [`protocol.eof_received()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.Protocol.eof_received) вызывается не более одного раза, и, если он вызван, [`get_buffer()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.BufferedProtocol.get_buffer) и [`buffer_updated()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.BufferedProtocol.buffer_updated) не будут вызваны после него.405406Автомат состояний:407408```text409start -> connection_made410    [-> get_buffer411        [-> buffer_updated]?412    ]*413    [-> eof_received]?414-> connection_lost -> end415```416417### Протоколы дейтаграмм418419Экземпляры протокола дейтаграмм должны создаваться фабриками протоколов, передаваемыми методу [`loop.create_datagram_endpoint()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.create_datagram_endpoint).420421#### `DatagramProtocol.datagram_received(data, addr)`422423Вызывается при получении дейтаграммы. *data* – это байтовый объект, содержащий входящие данные. *addr* – адрес узла, отправляющего данные; точный формат зависит от транспорта.424425#### `DatagramProtocol.error_received(exc)`426427Вызывается, когда предыдущая операция отправки или получения вызывает исключение [`OSError`](https://python-all.ru/3.9/library/exceptions.html#OSError). *exc* – экземпляр [`OSError`](https://python-all.ru/3.9/library/exceptions.html#OSError).428429Этот метод вызывается в редких случаях, когда транспорт (например, UDP) обнаруживает, что дейтаграмма не может быть доставлена получателю. Однако во многих ситуациях недоставленные дейтаграммы молча отбрасываются.430431> **Примечание**432>433> В системах BSD (macOS, FreeBSD и т.д.) управление потоком не поддерживается для протоколов дейтаграмм, поскольку нет надёжного способа обнаружить ошибки отправки, вызванные записью слишком большого количества пакетов.434>435> Сокет всегда выглядит «готовым», а избыточные пакеты отбрасываются. Исключение [`OSError`](https://python-all.ru/3.9/library/exceptions.html#OSError) с `errno`, установленным в [`errno.ENOBUFS`](https://python-all.ru/3.9/library/errno.html#errno.ENOBUFS), может быть или не быть возбуждено; если оно возбуждено, оно будет передано в [`DatagramProtocol.error_received()`](https://python-all.ru/3.9/library/asyncio-protocol.html#asyncio.DatagramProtocol.error_received), но в остальных случаях игнорируется.436437### Протоколы подпроцессов438439Экземпляры протокола подпроцессов должны создаваться фабриками протоколов, передаваемыми методам [`loop.subprocess_exec()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.subprocess_exec) и [`loop.subprocess_shell()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.subprocess_shell).440441#### `SubprocessProtocol.pipe_data_received(fd, data)`442443Вызывается, когда дочерний процесс записывает данные в свой канал stdout или stderr.444445*fd* – целочисленный файловый дескриптор канала.446447*data* – непустой байтовый объект, содержащий полученные данные.448449#### `SubprocessProtocol.pipe_connection_lost(fd, exc)`450451Вызывается, когда один из каналов, связывающих с дочерним процессом, закрывается.452453*fd* – целочисленный файловый дескриптор, который был закрыт.454455#### `SubprocessProtocol.process_exited()`456457Вызывается, когда дочерний процесс завершился.458459## Примеры460461### TCP-эхо-сервер462463Создайте TCP-эхо-сервер с помощью метода [`loop.create_server()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.create_server), отправьте обратно полученные данные и закройте соединение:464465```python466import asyncio467468class EchoServerProtocol(asyncio.Protocol):469    def connection_made(self, transport):470        peername = transport.get_extra_info('peername')471        print('Connection from {}'.format(peername))472        self.transport = transport473474    def data_received(self, data):475        message = data.decode()476        print('Data received: {!r}'.format(message))477478        print('Send: {!r}'.format(message))479        self.transport.write(data)480481        print('Close the client socket')482        self.transport.close()483484async def main():485    # Получаем ссылку на цикл событий, так как планируем использовать486    # низкоуровневые API.487    loop = asyncio.get_running_loop()488489    server = await loop.create_server(490        lambda: EchoServerProtocol(),491        '127.0.0.1', 8888)492493    async with server:494        await server.serve_forever()495496asyncio.run(main())497```498499> **См. также**500>501> Пример [TCP-эхо-сервера с использованием потоков](https://python-all.ru/3.9/library/asyncio-stream.html#asyncio-tcp-echo-server-streams) использует высокоуровневую функцию [`asyncio.start_server()`](https://python-all.ru/3.9/library/asyncio-stream.html#asyncio.start_server).502503### TCP-эхо-клиент504505TCP-эхо-клиент, использующий метод [`loop.create_connection()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.create_connection), отправляет данные и ждёт, пока соединение не будет закрыто:506507```python508import asyncio509510class EchoClientProtocol(asyncio.Protocol):511    def __init__(self, message, on_con_lost):512        self.message = message513        self.on_con_lost = on_con_lost514515    def connection_made(self, transport):516        transport.write(self.message.encode())517        print('Data sent: {!r}'.format(self.message))518519    def data_received(self, data):520        print('Data received: {!r}'.format(data.decode()))521522    def connection_lost(self, exc):523        print('The server closed the connection')524        self.on_con_lost.set_result(True)525526async def main():527    # Получаем ссылку на цикл событий, так как планируем использовать528    # низкоуровневые API.529    loop = asyncio.get_running_loop()530531    on_con_lost = loop.create_future()532    message = 'Hello World!'533534    transport, protocol = await loop.create_connection(535        lambda: EchoClientProtocol(message, on_con_lost),536        '127.0.0.1', 8888)537538    # Ожидаем, пока протокол не сообщит, что соединение539    # потеряно, и закрываем транспорт.540    try:541        await on_con_lost542    finally:543        transport.close()544545asyncio.run(main())546```547548> **См. также**549>550> Пример [TCP-эхо-клиента с использованием потоков](https://python-all.ru/3.9/library/asyncio-stream.html#asyncio-tcp-echo-client-streams) использует высокоуровневую функцию [`asyncio.open_connection()`](https://python-all.ru/3.9/library/asyncio-stream.html#asyncio.open_connection).551552### UDP-эхо-сервер553554UDP-эхо-сервер, использующий метод [`loop.create_datagram_endpoint()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.create_datagram_endpoint), отправляет обратно полученные данные:555556```python557import asyncio558559class EchoServerProtocol:560    def connection_made(self, transport):561        self.transport = transport562563    def datagram_received(self, data, addr):564        message = data.decode()565        print('Received %r from %s' % (message, addr))566        print('Send %r to %s' % (message, addr))567        self.transport.sendto(data, addr)568569async def main():570    print("Starting UDP server")571572    # Получаем ссылку на цикл событий, так как планируем использовать573    # низкоуровневые API.574    loop = asyncio.get_running_loop()575576    # Будет создан один экземпляр протокола для обслуживания всех577    # запросов клиентов.578    transport, protocol = await loop.create_datagram_endpoint(579        lambda: EchoServerProtocol(),580        local_addr=('127.0.0.1', 9999))581582    try:583        await asyncio.sleep(3600)  # Обслуживать в течение 1 часа.584    finally:585        transport.close()586587asyncio.run(main())588```589590### UDP-эхо-клиент591592UDP-эхо-клиент с помощью метода [`loop.create_datagram_endpoint()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.create_datagram_endpoint) отправляет данные и закрывает транспорт при получении ответа:593594```python595import asyncio596597class EchoClientProtocol:598    def __init__(self, message, on_con_lost):599        self.message = message600        self.on_con_lost = on_con_lost601        self.transport = None602603    def connection_made(self, transport):604        self.transport = transport605        print('Send:', self.message)606        self.transport.sendto(self.message.encode())607608    def datagram_received(self, data, addr):609        print("Received:", data.decode())610611        print("Close the socket")612        self.transport.close()613614    def error_received(self, exc):615        print('Error received:', exc)616617    def connection_lost(self, exc):618        print("Connection closed")619        self.on_con_lost.set_result(True)620621async def main():622    # Получаем ссылку на цикл событий, так как планируем использовать623    # низкоуровневые API.624    loop = asyncio.get_running_loop()625626    on_con_lost = loop.create_future()627    message = "Hello World!"628629    transport, protocol = await loop.create_datagram_endpoint(630        lambda: EchoClientProtocol(message, on_con_lost),631        remote_addr=('127.0.0.1', 9999))632633    try:634        await on_con_lost635    finally:636        transport.close()637638asyncio.run(main())639```640641### Подключение существующих сокетов642643Ожидание получения данных сокетом с помощью метода [`loop.create_connection()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.create_connection) и протокола:644645```python646import asyncio647import socket648649class MyProtocol(asyncio.Protocol):650651    def __init__(self, on_con_lost):652        self.transport = None653        self.on_con_lost = on_con_lost654655    def connection_made(self, transport):656        self.transport = transport657658    def data_received(self, data):659        print("Received:", data.decode())660661        # Мы закончили: закрываем транспорт;662        # connection_lost() будет вызван автоматически.663        self.transport.close()664665    def connection_lost(self, exc):666        # Сокет был закрыт667        self.on_con_lost.set_result(True)668669async def main():670    # Получаем ссылку на цикл событий, так как планируем использовать671    # низкоуровневые API.672    loop = asyncio.get_running_loop()673    on_con_lost = loop.create_future()674675    # Создаём пару соединённых сокетов676    rsock, wsock = socket.socketpair()677678    # Регистрируем сокет для ожидания данных.679    transport, protocol = await loop.create_connection(680        lambda: MyProtocol(on_con_lost), sock=rsock)681682    # Имитируем приём данных из сети.683    loop.call_soon(wsock.send, 'abc'.encode())684685    try:686        await protocol.on_con_lost687    finally:688        transport.close()689        wsock.close()690691asyncio.run(main())692```693694> **См. также**695>696> В примере [наблюдения за файловым дескриптором на предмет событий чтения](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio-example-watch-fd) используется низкоуровневый метод [`loop.add_reader()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.add_reader) для регистрации FD.697>698> В примере [регистрации открытого сокета для ожидания данных с помощью потоков](https://python-all.ru/3.9/library/asyncio-stream.html#asyncio-example-create-connection-streams) используются высокоуровневые потоки , созданные функцией [`open_connection()`](https://python-all.ru/3.9/library/asyncio-stream.html#asyncio.open_connection) в корутине.699700### loop.subprocess\_exec() и SubprocessProtocol701702Пример протокола подпроцесса, используемого для получения вывода подпроцесса и ожидания его завершения.703704Подпроцесс создаётся методом [`loop.subprocess_exec()`](https://python-all.ru/3.9/library/asyncio-eventloop.html#asyncio.loop.subprocess_exec):705706```python707import asyncio708import sys709710class DateProtocol(asyncio.SubprocessProtocol):711    def __init__(self, exit_future):712        self.exit_future = exit_future713        self.output = bytearray()714715    def pipe_data_received(self, fd, data):716        self.output.extend(data)717718    def process_exited(self):719        self.exit_future.set_result(True)720721async def get_date():722    # Получаем ссылку на цикл событий, так как планируем использовать723    # низкоуровневые API.724    loop = asyncio.get_running_loop()725726    code = 'import datetime; print(datetime.datetime.now())'727    exit_future = asyncio.Future(loop=loop)728729    # Создаём подпроцесс, управляемый DateProtocol;730    # перенаправляем стандартный вывод в канал.731    transport, protocol = await loop.subprocess_exec(732        lambda: DateProtocol(exit_future),733        sys.executable, '-c', code,734        stdin=None, stderr=None)735736    # Ожидаем завершения подпроцесса с помощью метода process_exited()737    # протокола.738    await exit_future739740    # Закрываем канал stdout.741    transport.close()742743    # Читаем вывод, который был собран методом744    # pipe_data_received() протокола.745    data = bytes(protocol.output)746    return data.decode('ascii').rstrip()747748date = asyncio.run(get_date())749print(f"Current date: {date}")750```751752См. также [тот же пример](https://python-all.ru/3.9/library/asyncio-subprocess.html#asyncio-example-create-subprocess-exec) , написанный с использованием высокоуровневых API.753