.local/lib/python2.7/site-packages/trollius/protocols.py

   1 """Abstract Protocol class."""
   2
   3 __all__ = ['BaseProtocol', 'Protocol', 'DatagramProtocol',
   4            'SubprocessProtocol']
   5
   6
   7 class BaseProtocol(object):
   8     """Common base class for protocol interfaces.
   9
  10     Usually user implements protocols that derived from BaseProtocol
  11     like Protocol or ProcessProtocol.
  12
  13     The only case when BaseProtocol should be implemented directly is
  14     write-only transport like write pipe
  15     """
  16
  17     def connection_made(self, transport):
  18         """Called when a connection is made.
  19
  20         The argument is the transport representing the pipe connection.
  21         To receive data, wait for data_received() calls.
  22         When the connection is closed, connection_lost() is called.
  23         """
  24
  25     def connection_lost(self, exc):
  26         """Called when the connection is lost or closed.
  27
  28         The argument is an exception object or None (the latter
  29         meaning a regular EOF is received or the connection was
  30         aborted or closed).
  31         """
  32
  33     def pause_writing(self):
  34         """Called when the transport's buffer goes over the high-water mark.
  35
  36         Pause and resume calls are paired -- pause_writing() is called
  37         once when the buffer goes strictly over the high-water mark
  38         (even if subsequent writes increases the buffer size even
  39         more), and eventually resume_writing() is called once when the
  40         buffer size reaches the low-water mark.
  41
  42         Note that if the buffer size equals the high-water mark,
  43         pause_writing() is not called -- it must go strictly over.
  44         Conversely, resume_writing() is called when the buffer size is
  45         equal or lower than the low-water mark.  These end conditions
  46         are important to ensure that things go as expected when either
  47         mark is zero.
  48
  49         NOTE: This is the only Protocol callback that is not called
  50         through EventLoop.call_soon() -- if it were, it would have no
  51         effect when it's most needed (when the app keeps writing
  52         without yielding until pause_writing() is called).
  53         """
  54
  55     def resume_writing(self):
  56         """Called when the transport's buffer drains below the low-water mark.
  57
  58         See pause_writing() for details.
  59         """
  60
  61
  62 class Protocol(BaseProtocol):
  63     """Interface for stream protocol.
  64
  65     The user should implement this interface.  They can inherit from
  66     this class but don't need to.  The implementations here do
  67     nothing (they don't raise exceptions).
  68
  69     When the user wants to requests a transport, they pass a protocol
  70     factory to a utility function (e.g., EventLoop.create_connection()).
  71
  72     When the connection is made successfully, connection_made() is
  73     called with a suitable transport object.  Then data_received()
  74     will be called 0 or more times with data (bytes) received from the
  75     transport; finally, connection_lost() will be called exactly once
  76     with either an exception object or None as an argument.
  77
  78     State machine of calls:
  79
  80       start -> CM [-> DR*] [-> ER?] -> CL -> end
  81
  82     * CM: connection_made()
  83     * DR: data_received()
  84     * ER: eof_received()
  85     * CL: connection_lost()
  86     """
  87
  88     def data_received(self, data):
  89         """Called when some data is received.
  90
  91         The argument is a bytes object.
  92         """
  93
  94     def eof_received(self):
  95         """Called when the other end calls write_eof() or equivalent.
  96
  97         If this returns a false value (including None), the transport
  98         will close itself.  If it returns a true value, closing the
  99         transport is up to the protocol.
 100         """
 101
 102
 103 class DatagramProtocol(BaseProtocol):
 104     """Interface for datagram protocol."""
 105
 106     def datagram_received(self, data, addr):
 107         """Called when some datagram is received."""
 108
 109     def error_received(self, exc):
 110         """Called when a send or receive operation raises an OSError.
 111
 112         (Other than BlockingIOError or InterruptedError.)
 113         """
 114
 115
 116 class SubprocessProtocol(BaseProtocol):
 117     """Interface for protocol for subprocess calls."""
 118
 119     def pipe_data_received(self, fd, data):
 120         """Called when the subprocess writes data into stdout/stderr pipe.
 121
 122         fd is int file descriptor.
 123         data is bytes object.
 124         """
 125
 126     def pipe_connection_lost(self, fd, exc):
 127         """Called when a file descriptor associated with the child process is
 128         closed.
 129
 130         fd is the int file descriptor that was closed.
 131         """
 132
 133     def process_exited(self):
 134         """Called when subprocess has exited."""