Python code coverage for Lib/asyncio/transports.py

#	count	content
1	n/a	"""Abstract Transport class."""
2	n/a
3	n/a	from asyncio import compat
4	n/a
5	n/a	__all__ = ['BaseTransport', 'ReadTransport', 'WriteTransport',
6	n/a	'Transport', 'DatagramTransport', 'SubprocessTransport',
7	n/a	]
8	n/a
9	n/a
10	n/a	class BaseTransport:
11	n/a	"""Base class for transports."""
12	n/a
13	n/a	def __init__(self, extra=None):
14	n/a	if extra is None:
15	n/a	extra = {}
16	n/a	self._extra = extra
17	n/a
18	n/a	def get_extra_info(self, name, default=None):
19	n/a	"""Get optional transport information."""
20	n/a	return self._extra.get(name, default)
21	n/a
22	n/a	def is_closing(self):
23	n/a	"""Return True if the transport is closing or closed."""
24	n/a	raise NotImplementedError
25	n/a
26	n/a	def close(self):
27	n/a	"""Close the transport.
28	n/a
29	n/a	Buffered data will be flushed asynchronously. No more data
30	n/a	will be received. After all buffered data is flushed, the
31	n/a	protocol's connection_lost() method will (eventually) called
32	n/a	with None as its argument.
33	n/a	"""
34	n/a	raise NotImplementedError
35	n/a
36	n/a	def set_protocol(self, protocol):
37	n/a	"""Set a new protocol."""
38	n/a	raise NotImplementedError
39	n/a
40	n/a	def get_protocol(self):
41	n/a	"""Return the current protocol."""
42	n/a	raise NotImplementedError
43	n/a
44	n/a
45	n/a	class ReadTransport(BaseTransport):
46	n/a	"""Interface for read-only transports."""
47	n/a
48	n/a	def pause_reading(self):
49	n/a	"""Pause the receiving end.
50	n/a
51	n/a	No data will be passed to the protocol's data_received()
52	n/a	method until resume_reading() is called.
53	n/a	"""
54	n/a	raise NotImplementedError
55	n/a
56	n/a	def resume_reading(self):
57	n/a	"""Resume the receiving end.
58	n/a
59	n/a	Data received will once again be passed to the protocol's
60	n/a	data_received() method.
61	n/a	"""
62	n/a	raise NotImplementedError
63	n/a
64	n/a
65	n/a	class WriteTransport(BaseTransport):
66	n/a	"""Interface for write-only transports."""
67	n/a
68	n/a	def set_write_buffer_limits(self, high=None, low=None):
69	n/a	"""Set the high- and low-water limits for write flow control.
70	n/a
71	n/a	These two values control when to call the protocol's
72	n/a	pause_writing() and resume_writing() methods. If specified,
73	n/a	the low-water limit must be less than or equal to the
74	n/a	high-water limit. Neither value can be negative.
75	n/a
76	n/a	The defaults are implementation-specific. If only the
77	n/a	high-water limit is given, the low-water limit defaults to an
78	n/a	implementation-specific value less than or equal to the
79	n/a	high-water limit. Setting high to zero forces low to zero as
80	n/a	well, and causes pause_writing() to be called whenever the
81	n/a	buffer becomes non-empty. Setting low to zero causes
82	n/a	resume_writing() to be called only once the buffer is empty.
83	n/a	Use of zero for either limit is generally sub-optimal as it
84	n/a	reduces opportunities for doing I/O and computation
85	n/a	concurrently.
86	n/a	"""
87	n/a	raise NotImplementedError
88	n/a
89	n/a	def get_write_buffer_size(self):
90	n/a	"""Return the current size of the write buffer."""
91	n/a	raise NotImplementedError
92	n/a
93	n/a	def write(self, data):
94	n/a	"""Write some data bytes to the transport.
95	n/a
96	n/a	This does not block; it buffers the data and arranges for it
97	n/a	to be sent out asynchronously.
98	n/a	"""
99	n/a	raise NotImplementedError
100	n/a
101	n/a	def writelines(self, list_of_data):
102	n/a	"""Write a list (or any iterable) of data bytes to the transport.
103	n/a
104	n/a	The default implementation concatenates the arguments and
105	n/a	calls write() on the result.
106	n/a	"""
107	n/a	data = compat.flatten_list_bytes(list_of_data)
108	n/a	self.write(data)
109	n/a
110	n/a	def write_eof(self):
111	n/a	"""Close the write end after flushing buffered data.
112	n/a
113	n/a	(This is like typing ^D into a UNIX program reading from stdin.)
114	n/a
115	n/a	Data may still be received.
116	n/a	"""
117	n/a	raise NotImplementedError
118	n/a
119	n/a	def can_write_eof(self):
120	n/a	"""Return True if this transport supports write_eof(), False if not."""
121	n/a	raise NotImplementedError
122	n/a
123	n/a	def abort(self):
124	n/a	"""Close the transport immediately.
125	n/a
126	n/a	Buffered data will be lost. No more data will be received.
127	n/a	The protocol's connection_lost() method will (eventually) be
128	n/a	called with None as its argument.
129	n/a	"""
130	n/a	raise NotImplementedError
131	n/a
132	n/a
133	n/a	class Transport(ReadTransport, WriteTransport):
134	n/a	"""Interface representing a bidirectional transport.
135	n/a
136	n/a	There may be several implementations, but typically, the user does
137	n/a	not implement new transports; rather, the platform provides some
138	n/a	useful transports that are implemented using the platform's best
139	n/a	practices.
140	n/a
141	n/a	The user never instantiates a transport directly; they call a
142	n/a	utility function, passing it a protocol factory and other
143	n/a	information necessary to create the transport and protocol. (E.g.
144	n/a	EventLoop.create_connection() or EventLoop.create_server().)
145	n/a
146	n/a	The utility function will asynchronously create a transport and a
147	n/a	protocol and hook them up by calling the protocol's
148	n/a	connection_made() method, passing it the transport.
149	n/a
150	n/a	The implementation here raises NotImplemented for every method
151	n/a	except writelines(), which calls write() in a loop.
152	n/a	"""
153	n/a
154	n/a
155	n/a	class DatagramTransport(BaseTransport):
156	n/a	"""Interface for datagram (UDP) transports."""
157	n/a
158	n/a	def sendto(self, data, addr=None):
159	n/a	"""Send data to the transport.
160	n/a
161	n/a	This does not block; it buffers the data and arranges for it
162	n/a	to be sent out asynchronously.
163	n/a	addr is target socket address.
164	n/a	If addr is None use target address pointed on transport creation.
165	n/a	"""
166	n/a	raise NotImplementedError
167	n/a
168	n/a	def abort(self):
169	n/a	"""Close the transport immediately.
170	n/a
171	n/a	Buffered data will be lost. No more data will be received.
172	n/a	The protocol's connection_lost() method will (eventually) be
173	n/a	called with None as its argument.
174	n/a	"""
175	n/a	raise NotImplementedError
176	n/a
177	n/a
178	n/a	class SubprocessTransport(BaseTransport):
179	n/a
180	n/a	def get_pid(self):
181	n/a	"""Get subprocess id."""
182	n/a	raise NotImplementedError
183	n/a
184	n/a	def get_returncode(self):
185	n/a	"""Get subprocess returncode.
186	n/a
187	n/a	See also
188	n/a	http://docs.python.org/3/library/subprocess#subprocess.Popen.returncode
189	n/a	"""
190	n/a	raise NotImplementedError
191	n/a
192	n/a	def get_pipe_transport(self, fd):
193	n/a	"""Get transport for pipe with number fd."""
194	n/a	raise NotImplementedError
195	n/a
196	n/a	def send_signal(self, signal):
197	n/a	"""Send signal to subprocess.
198	n/a
199	n/a	See also:
200	n/a	docs.python.org/3/library/subprocess#subprocess.Popen.send_signal
201	n/a	"""
202	n/a	raise NotImplementedError
203	n/a
204	n/a	def terminate(self):
205	n/a	"""Stop the subprocess.
206	n/a
207	n/a	Alias for close() method.
208	n/a
209	n/a	On Posix OSs the method sends SIGTERM to the subprocess.
210	n/a	On Windows the Win32 API function TerminateProcess()
211	n/a	is called to stop the subprocess.
212	n/a
213	n/a	See also:
214	n/a	http://docs.python.org/3/library/subprocess#subprocess.Popen.terminate
215	n/a	"""
216	n/a	raise NotImplementedError
217	n/a
218	n/a	def kill(self):
219	n/a	"""Kill the subprocess.
220	n/a
221	n/a	On Posix OSs the function sends SIGKILL to the subprocess.
222	n/a	On Windows kill() is an alias for terminate().
223	n/a
224	n/a	See also:
225	n/a	http://docs.python.org/3/library/subprocess#subprocess.Popen.kill
226	n/a	"""
227	n/a	raise NotImplementedError
228	n/a
229	n/a
230	n/a	class _FlowControlMixin(Transport):
231	n/a	"""All the logic for (write) flow control in a mix-in base class.
232	n/a
233	n/a	The subclass must implement get_write_buffer_size(). It must call
234	n/a	_maybe_pause_protocol() whenever the write buffer size increases,
235	n/a	and _maybe_resume_protocol() whenever it decreases. It may also
236	n/a	override set_write_buffer_limits() (e.g. to specify different
237	n/a	defaults).
238	n/a
239	n/a	The subclass constructor must call super().__init__(extra). This
240	n/a	will call set_write_buffer_limits().
241	n/a
242	n/a	The user may call set_write_buffer_limits() and
243	n/a	get_write_buffer_size(), and their protocol's pause_writing() and
244	n/a	resume_writing() may be called.
245	n/a	"""
246	n/a
247	n/a	def __init__(self, extra=None, loop=None):
248	n/a	super().__init__(extra)
249	n/a	assert loop is not None
250	n/a	self._loop = loop
251	n/a	self._protocol_paused = False
252	n/a	self._set_write_buffer_limits()
253	n/a
254	n/a	def _maybe_pause_protocol(self):
255	n/a	size = self.get_write_buffer_size()
256	n/a	if size <= self._high_water:
257	n/a	return
258	n/a	if not self._protocol_paused:
259	n/a	self._protocol_paused = True
260	n/a	try:
261	n/a	self._protocol.pause_writing()
262	n/a	except Exception as exc:
263	n/a	self._loop.call_exception_handler({
264	n/a	'message': 'protocol.pause_writing() failed',
265	n/a	'exception': exc,
266	n/a	'transport': self,
267	n/a	'protocol': self._protocol,
268	n/a	})
269	n/a
270	n/a	def _maybe_resume_protocol(self):
271	n/a	if (self._protocol_paused and
272	n/a	self.get_write_buffer_size() <= self._low_water):
273	n/a	self._protocol_paused = False
274	n/a	try:
275	n/a	self._protocol.resume_writing()
276	n/a	except Exception as exc:
277	n/a	self._loop.call_exception_handler({
278	n/a	'message': 'protocol.resume_writing() failed',
279	n/a	'exception': exc,
280	n/a	'transport': self,
281	n/a	'protocol': self._protocol,
282	n/a	})
283	n/a
284	n/a	def get_write_buffer_limits(self):
285	n/a	return (self._low_water, self._high_water)
286	n/a
287	n/a	def _set_write_buffer_limits(self, high=None, low=None):
288	n/a	if high is None:
289	n/a	if low is None:
290	n/a	high = 64*1024
291	n/a	else:
292	n/a	high = 4*low
293	n/a	if low is None:
294	n/a	low = high // 4
295	n/a	if not high >= low >= 0:
296	n/a	raise ValueError('high (%r) must be >= low (%r) must be >= 0' %
297	n/a	(high, low))
298	n/a	self._high_water = high
299	n/a	self._low_water = low
300	n/a
301	n/a	def set_write_buffer_limits(self, high=None, low=None):
302	n/a	self._set_write_buffer_limits(high=high, low=low)
303	n/a	self._maybe_pause_protocol()
304	n/a
305	n/a	def get_write_buffer_size(self):
306	n/a	raise NotImplementedError