protocols.py
python
"""Абстрактный класс Protocol."""
__all__ = ['BaseProtocol', 'Protocol', 'DatagramProtocol',
'SubprocessProtocol']
class BaseProtocol:
"""Общий базовый класс для интерфейсов протокола.
Обычно пользователь реализует протоколы, производные от BaseProtocol,
такие как Protocol или ProcessProtocol.
Единственный случай, когда BaseProtocol следует реализовывать напрямую — это
транспорт только для записи, например канал записи (write pipe)
"""
def connection_made(self, transport):
"""Вызывается при установлении соединения.
Аргумент — это транспорт, представляющий соединение через канал.
Чтобы получать данные, ожидайте вызовов data_received().
Когда соединение закрыто, вызывается connection_lost().
"""
def connection_lost(self, exc):
"""Вызывается, когда соединение потеряно или закрыто.
Аргумент — объект исключения или None (последнее
означает, что получен обычный EOF или соединение было
прервано или закрыто).
"""
def pause_writing(self):
"""Вызывается, когда буфер транспорта превышает верхнюю отметку (high-water mark).
Вызовы pause и resume парные -- pause_writing() вызывается
один раз, когда буфер строго превышает верхнюю отметку
(даже если последующие записи ещё больше увеличивают размер буфера),
и в конечном итоге resume_writing() вызывается один раз, когда
размер буфера достигает нижней отметки (low-water mark).
Обратите внимание: если размер буфера равен верхней отметке,
pause_writing() не вызывается -- он должен быть строго больше.
И наоборот, resume_writing() вызывается, когда размер буфера
равен или меньше нижней отметки. Эти граничные условия
важны для обеспечения ожидаемого поведения, когда любая
отметка равна нулю.
ПРИМЕЧАНИЕ: Это единственный колбэк протокола, который не вызывается
через EventLoop.call_soon() -- если бы он вызывался, он бы не имел
эффекта, когда это наиболее необходимо (когда приложение продолжает
запись без уступки до тех пор, пока не будет вызван pause_writing()).
"""
def resume_writing(self):
"""Вызывается, когда буфер транспорта опускается ниже нижней отметки.
Подробнее см. в pause_writing().
"""
class Protocol(BaseProtocol):
"""Интерфейс для протокола потока данных.
Пользователь должен реализовать этот интерфейс. Он может наследовать от
этого класса, но это не обязательно. Реализации здесь ничего не делают
(они не вызывают исключений).
Когда пользователь хочет запросить транспорт, он передает фабрику
протоколов служебной функции (например, EventLoop.create_connection()).
Когда соединение успешно установлено, вызывается connection_made() с
подходящим объектом транспорта. Затем data_received() будет вызываться
0 или более раз с данными (bytes), полученными от транспорта;
наконец, connection_lost() будет вызван ровно один раз с объектом
исключения или None в качестве аргумента.
Конечный автомат вызовов:
start -> CM [-> DR*] [-> ER?] -> CL -> end
* CM: connection_made()
* DR: data_received()
* ER: eof_received()
* CL: connection_lost()
"""
def data_received(self, data):
"""Вызывается при получении некоторых данных.
Аргумент — объект bytes.
"""
def eof_received(self):
"""Вызывается, когда удаленная сторона вызывает write_eof() или эквивалент.
Если этот метод возвращает ложное значение (включая None), транспорт
закроет себя сам. Если он возвращает истинное значение, закрытие
транспорта оставляется на усмотрение протокола.
"""
class DatagramProtocol(BaseProtocol):
"""Интерфейс протокола дейтаграмм."""
def datagram_received(self, data, addr):
"""Вызывается при получении дейтаграммы."""
def error_received(self, exc):
"""Вызывается, когда операция отправки или получения вызывает OSError.
(За исключением BlockingIOError или InterruptedError.)
"""
class SubprocessProtocol(BaseProtocol):
"""Интерфейс протокола для вызовов подпроцессов."""
def pipe_data_received(self, fd, data):
"""Вызывается, когда подпроцесс записывает данные в канал stdout/stderr.
fd — целочисленный файловый дескриптор.
data — объект bytes.
"""
def pipe_connection_lost(self, fd, exc):
"""Вызывается, когда файловый дескриптор, связанный с дочерним процессом,
закрывается.
fd — целочисленный файловый дескриптор, который был закрыт.
"""
def process_exited(self):
"""Вызывается, когда подпроцесс завершился."""