Python code coverage for Lib/asyncio/protocols.py

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