| 1 |
.. currentmodule:: asyncio |
| 2 |
|
| 3 |
|
| 4 |
.. _asyncio-transports-protocols: |
| 5 |
|
| 6 |
|
| 7 |
======================== |
| 8 |
Transports and Protocols |
| 9 |
======================== |
| 10 |
|
| 11 |
.. rubric:: Preface |
| 12 |
|
| 13 |
Transports and Protocols are used by the **low-level** event loop |
| 14 |
APIs such as :meth:`loop.create_connection`. They use |
| 15 |
callback-based programming style and enable high-performance |
| 16 |
implementations of network or IPC protocols (e.g. HTTP). |
| 17 |
|
| 18 |
Essentially, transports and protocols should only be used in |
| 19 |
libraries and frameworks and never in high-level asyncio |
| 20 |
applications. |
| 21 |
|
| 22 |
This documentation page covers both `Transports`_ and `Protocols`_. |
| 23 |
|
| 24 |
.. rubric:: Introduction |
| 25 |
|
| 26 |
At the highest level, the transport is concerned with *how* bytes |
| 27 |
are transmitted, while the protocol determines *which* bytes to |
| 28 |
transmit (and to some extent when). |
| 29 |
|
| 30 |
A different way of saying the same thing: a transport is an |
| 31 |
abstraction for a socket (or similar I/O endpoint) while a protocol |
| 32 |
is an abstraction for an application, from the transport's point |
| 33 |
of view. |
| 34 |
|
| 35 |
Yet another view is the transport and protocol interfaces |
| 36 |
together define an abstract interface for using network I/O and |
| 37 |
interprocess I/O. |
| 38 |
|
| 39 |
There is always a 1:1 relationship between transport and protocol |
| 40 |
objects: the protocol calls transport methods to send data, |
| 41 |
while the transport calls protocol methods to pass it data that |
| 42 |
has been received. |
| 43 |
|
| 44 |
Most of connection oriented event loop methods |
| 45 |
(such as :meth:`loop.create_connection`) usually accept a |
| 46 |
*protocol_factory* argument used to create a *Protocol* object |
| 47 |
for an accepted connection, represented by a *Transport* object. |
| 48 |
Such methods usually return a tuple of ``(transport, protocol)``. |
| 49 |
|
| 50 |
.. rubric:: Contents |
| 51 |
|
| 52 |
This documentation page contains the following sections: |
| 53 |
|
| 54 |
* The `Transports`_ section documents asyncio :class:`BaseTransport`, |
| 55 |
:class:`ReadTransport`, :class:`WriteTransport`, :class:`Transport`, |
| 56 |
:class:`DatagramTransport`, and :class:`SubprocessTransport` |
| 57 |
classes. |
| 58 |
|
| 59 |
* The `Protocols`_ section documents asyncio :class:`BaseProtocol`, |
| 60 |
:class:`Protocol`, :class:`BufferedProtocol`, |
| 61 |
:class:`DatagramProtocol`, and :class:`SubprocessProtocol` classes. |
| 62 |
|
| 63 |
* The `Examples`_ section showcases how to work with transports, |
| 64 |
protocols, and low-level event loop APIs. |
| 65 |
|
| 66 |
|
| 67 |
.. _asyncio-transport: |
| 68 |
|
| 69 |
Transports |
| 70 |
========== |
| 71 |
|
| 72 |
**Source code:** :source:`Lib/asyncio/transports.py` |
| 73 |
|
| 74 |
---------------------------------------------------- |
| 75 |
|
| 76 |
Transports are classes provided by :mod:`asyncio` in order to abstract |
| 77 |
various kinds of communication channels. |
| 78 |
|
| 79 |
Transport objects are always instantiated by an |
| 80 |
:ref:`asyncio event loop <asyncio-event-loop>`. |
| 81 |
|
| 82 |
asyncio implements transports for TCP, UDP, SSL, and subprocess pipes. |
| 83 |
The methods available on a transport depend on the transport's kind. |
| 84 |
|
| 85 |
The transport classes are :ref:`not thread safe <asyncio-multithreading>`. |
| 86 |
|
| 87 |
|
| 88 |
Transports Hierarchy |
| 89 |
-------------------- |
| 90 |
|
| 91 |
.. class:: BaseTransport |
| 92 |
|
| 93 |
Base class for all transports. Contains methods that all |
| 94 |
asyncio transports share. |
| 95 |
|
| 96 |
.. class:: WriteTransport(BaseTransport) |
| 97 |
|
| 98 |
A base transport for write-only connections. |
| 99 |
|
| 100 |
Instances of the *WriteTransport* class are returned from |
| 101 |
the :meth:`loop.connect_write_pipe` event loop method and |
| 102 |
are also used by subprocess-related methods like |
| 103 |
:meth:`loop.subprocess_exec`. |
| 104 |
|
| 105 |
.. class:: ReadTransport(BaseTransport) |
| 106 |
|
| 107 |
A base transport for read-only connections. |
| 108 |
|
| 109 |
Instances of the *ReadTransport* class are returned from |
| 110 |
the :meth:`loop.connect_read_pipe` event loop method and |
| 111 |
are also used by subprocess-related methods like |
| 112 |
:meth:`loop.subprocess_exec`. |
| 113 |
|
| 114 |
.. class:: Transport(WriteTransport, ReadTransport) |
| 115 |
|
| 116 |
Interface representing a bidirectional transport, such as a |
| 117 |
TCP connection. |
| 118 |
|
| 119 |
The user does not instantiate a transport directly; they call a |
| 120 |
utility function, passing it a protocol factory and other |
| 121 |
information necessary to create the transport and protocol. |
| 122 |
|
| 123 |
Instances of the *Transport* class are returned from or used by |
| 124 |
event loop methods like :meth:`loop.create_connection`, |
| 125 |
:meth:`loop.create_unix_connection`, |
| 126 |
:meth:`loop.create_server`, :meth:`loop.sendfile`, etc. |
| 127 |
|
| 128 |
|
| 129 |
.. class:: DatagramTransport(BaseTransport) |
| 130 |
|
| 131 |
A transport for datagram (UDP) connections. |
| 132 |
|
| 133 |
Instances of the *DatagramTransport* class are returned from |
| 134 |
the :meth:`loop.create_datagram_endpoint` event loop method. |
| 135 |
|
| 136 |
|
| 137 |
.. class:: SubprocessTransport(BaseTransport) |
| 138 |
|
| 139 |
An abstraction to represent a connection between a parent and its |
| 140 |
child OS process. |
| 141 |
|
| 142 |
Instances of the *SubprocessTransport* class are returned from |
| 143 |
event loop methods :meth:`loop.subprocess_shell` and |
| 144 |
:meth:`loop.subprocess_exec`. |
| 145 |
|
| 146 |
|
| 147 |
Base Transport |
| 148 |
-------------- |
| 149 |
|
| 150 |
.. method:: BaseTransport.close() |
| 151 |
|
| 152 |
Close the transport. |
| 153 |
|
| 154 |
If the transport has a buffer for outgoing |
| 155 |
data, buffered data will be flushed asynchronously. No more data |
| 156 |
will be received. After all buffered data is flushed, the |
| 157 |
protocol's :meth:`protocol.connection_lost() |
| 158 |
<BaseProtocol.connection_lost>` method will be called with |
| 159 |
:const:`None` as its argument. The transport should not be |
| 160 |
used once it is closed. |
| 161 |
|
| 162 |
.. method:: BaseTransport.is_closing() |
| 163 |
|
| 164 |
Return ``True`` if the transport is closing or is closed. |
| 165 |
|
| 166 |
.. method:: BaseTransport.get_extra_info(name, default=None) |
| 167 |
|
| 168 |
Return information about the transport or underlying resources |
| 169 |
it uses. |
| 170 |
|
| 171 |
*name* is a string representing the piece of transport-specific |
| 172 |
information to get. |
| 173 |
|
| 174 |
*default* is the value to return if the information is not |
| 175 |
available, or if the transport does not support querying it |
| 176 |
with the given third-party event loop implementation or on the |
| 177 |
current platform. |
| 178 |
|
| 179 |
For example, the following code attempts to get the underlying |
| 180 |
socket object of the transport:: |
| 181 |
|
| 182 |
sock = transport.get_extra_info('socket') |
| 183 |
if sock is not None: |
| 184 |
print(sock.getsockopt(...)) |
| 185 |
|
| 186 |
Categories of information that can be queried on some transports: |
| 187 |
|
| 188 |
* socket: |
| 189 |
|
| 190 |
- ``'peername'``: the remote address to which the socket is |
| 191 |
connected, result of :meth:`socket.socket.getpeername` |
| 192 |
(``None`` on error) |
| 193 |
|
| 194 |
- ``'socket'``: :class:`socket.socket` instance |
| 195 |
|
| 196 |
- ``'sockname'``: the socket's own address, |
| 197 |
result of :meth:`socket.socket.getsockname` |
| 198 |
|
| 199 |
* SSL socket: |
| 200 |
|
| 201 |
- ``'compression'``: the compression algorithm being used as a |
| 202 |
string, or ``None`` if the connection isn't compressed; result |
| 203 |
of :meth:`ssl.SSLSocket.compression` |
| 204 |
|
| 205 |
- ``'cipher'``: a three-value tuple containing the name of the |
| 206 |
cipher being used, the version of the SSL protocol that defines |
| 207 |
its use, and the number of secret bits being used; result of |
| 208 |
:meth:`ssl.SSLSocket.cipher` |
| 209 |
|
| 210 |
- ``'peercert'``: peer certificate; result of |
| 211 |
:meth:`ssl.SSLSocket.getpeercert` |
| 212 |
|
| 213 |
- ``'sslcontext'``: :class:`ssl.SSLContext` instance |
| 214 |
|
| 215 |
- ``'ssl_object'``: :class:`ssl.SSLObject` or |
| 216 |
:class:`ssl.SSLSocket` instance |
| 217 |
|
| 218 |
* pipe: |
| 219 |
|
| 220 |
- ``'pipe'``: pipe object |
| 221 |
|
| 222 |
* subprocess: |
| 223 |
|
| 224 |
- ``'subprocess'``: :class:`subprocess.Popen` instance |
| 225 |
|
| 226 |
.. method:: BaseTransport.set_protocol(protocol) |
| 227 |
|
| 228 |
Set a new protocol. |
| 229 |
|
| 230 |
Switching protocol should only be done when both |
| 231 |
protocols are documented to support the switch. |
| 232 |
|
| 233 |
.. method:: BaseTransport.get_protocol() |
| 234 |
|
| 235 |
Return the current protocol. |
| 236 |
|
| 237 |
|
| 238 |
Read-only Transports |
| 239 |
-------------------- |
| 240 |
|
| 241 |
.. method:: ReadTransport.is_reading() |
| 242 |
|
| 243 |
Return ``True`` if the transport is receiving new data. |
| 244 |
|
| 245 |
.. versionadded:: 3.7 |
| 246 |
|
| 247 |
.. method:: ReadTransport.pause_reading() |
| 248 |
|
| 249 |
Pause the receiving end of the transport. No data will be passed to |
| 250 |
the protocol's :meth:`protocol.data_received() <Protocol.data_received>` |
| 251 |
method until :meth:`resume_reading` is called. |
| 252 |
|
| 253 |
.. versionchanged:: 3.7 |
| 254 |
The method is idempotent, i.e. it can be called when the |
| 255 |
transport is already paused or closed. |
| 256 |
|
| 257 |
.. method:: ReadTransport.resume_reading() |
| 258 |
|
| 259 |
Resume the receiving end. The protocol's |
| 260 |
:meth:`protocol.data_received() <Protocol.data_received>` method |
| 261 |
will be called once again if some data is available for reading. |
| 262 |
|
| 263 |
.. versionchanged:: 3.7 |
| 264 |
The method is idempotent, i.e. it can be called when the |
| 265 |
transport is already reading. |
| 266 |
|
| 267 |
|
| 268 |
Write-only Transports |
| 269 |
--------------------- |
| 270 |
|
| 271 |
.. method:: WriteTransport.abort() |
| 272 |
|
| 273 |
Close the transport immediately, without waiting for pending operations |
| 274 |
to complete. Buffered data will be lost. No more data will be received. |
| 275 |
The protocol's :meth:`protocol.connection_lost() |
| 276 |
<BaseProtocol.connection_lost>` method will eventually be |
| 277 |
called with :const:`None` as its argument. |
| 278 |
|
| 279 |
.. method:: WriteTransport.can_write_eof() |
| 280 |
|
| 281 |
Return :const:`True` if the transport supports |
| 282 |
:meth:`~WriteTransport.write_eof`, :const:`False` if not. |
| 283 |
|
| 284 |
.. method:: WriteTransport.get_write_buffer_size() |
| 285 |
|
| 286 |
Return the current size of the output buffer used by the transport. |
| 287 |
|
| 288 |
.. method:: WriteTransport.get_write_buffer_limits() |
| 289 |
|
| 290 |
Get the *high* and *low* watermarks for write flow control. Return a |
| 291 |
tuple ``(low, high)`` where *low* and *high* are positive number of |
| 292 |
bytes. |
| 293 |
|
| 294 |
Use :meth:`set_write_buffer_limits` to set the limits. |
| 295 |
|
| 296 |
.. versionadded:: 3.4.2 |
| 297 |
|
| 298 |
.. method:: WriteTransport.set_write_buffer_limits(high=None, low=None) |
| 299 |
|
| 300 |
Set the *high* and *low* watermarks for write flow control. |
| 301 |
|
| 302 |
These two values (measured in number of |
| 303 |
bytes) control when the protocol's |
| 304 |
:meth:`protocol.pause_writing() <BaseProtocol.pause_writing>` |
| 305 |
and :meth:`protocol.resume_writing() <BaseProtocol.resume_writing>` |
| 306 |
methods are called. If specified, the low watermark must be less |
| 307 |
than or equal to the high watermark. Neither *high* nor *low* |
| 308 |
can be negative. |
| 309 |
|
| 310 |
:meth:`~BaseProtocol.pause_writing` is called when the buffer size |
| 311 |
becomes greater than or equal to the *high* value. If writing has |
| 312 |
been paused, :meth:`~BaseProtocol.resume_writing` is called when |
| 313 |
the buffer size becomes less than or equal to the *low* value. |
| 314 |
|
| 315 |
The defaults are implementation-specific. If only the |
| 316 |
high watermark is given, the low watermark defaults to an |
| 317 |
implementation-specific value less than or equal to the |
| 318 |
high watermark. Setting *high* to zero forces *low* to zero as |
| 319 |
well, and causes :meth:`~BaseProtocol.pause_writing` to be called |
| 320 |
whenever the buffer becomes non-empty. Setting *low* to zero causes |
| 321 |
:meth:`~BaseProtocol.resume_writing` to be called only once the |
| 322 |
buffer is empty. Use of zero for either limit is generally |
| 323 |
sub-optimal as it reduces opportunities for doing I/O and |
| 324 |
computation concurrently. |
| 325 |
|
| 326 |
Use :meth:`~WriteTransport.get_write_buffer_limits` |
| 327 |
to get the limits. |
| 328 |
|
| 329 |
.. method:: WriteTransport.write(data) |
| 330 |
|
| 331 |
Write some *data* bytes to the transport. |
| 332 |
|
| 333 |
This method does not block; it buffers the data and arranges for it |
| 334 |
to be sent out asynchronously. |
| 335 |
|
| 336 |
.. method:: WriteTransport.writelines(list_of_data) |
| 337 |
|
| 338 |
Write a list (or any iterable) of data bytes to the transport. |
| 339 |
This is functionally equivalent to calling :meth:`write` on each |
| 340 |
element yielded by the iterable, but may be implemented more |
| 341 |
efficiently. |
| 342 |
|
| 343 |
.. method:: WriteTransport.write_eof() |
| 344 |
|
| 345 |
Close the write end of the transport after flushing all buffered data. |
| 346 |
Data may still be received. |
| 347 |
|
| 348 |
This method can raise :exc:`NotImplementedError` if the transport |
| 349 |
(e.g. SSL) doesn't support half-closed connections. |
| 350 |
|
| 351 |
|
| 352 |
Datagram Transports |
| 353 |
------------------- |
| 354 |
|
| 355 |
.. method:: DatagramTransport.sendto(data, addr=None) |
| 356 |
|
| 357 |
Send the *data* bytes to the remote peer given by *addr* (a |
| 358 |
transport-dependent target address). If *addr* is :const:`None`, |
| 359 |
the data is sent to the target address given on transport |
| 360 |
creation. |
| 361 |
|
| 362 |
This method does not block; it buffers the data and arranges |
| 363 |
for it to be sent out asynchronously. |
| 364 |
|
| 365 |
.. versionchanged:: 3.13 |
| 366 |
This method can be called with an empty bytes object to send a |
| 367 |
zero-length datagram. The buffer size calculation used for flow |
| 368 |
control is also updated to account for the datagram header. |
| 369 |
|
| 370 |
.. method:: DatagramTransport.abort() |
| 371 |
|
| 372 |
Close the transport immediately, without waiting for pending |
| 373 |
operations to complete. Buffered data will be lost. |
| 374 |
No more data will be received. The protocol's |
| 375 |
:meth:`protocol.connection_lost() <BaseProtocol.connection_lost>` |
| 376 |
method will eventually be called with :const:`None` as its argument. |
| 377 |
|
| 378 |
|
| 379 |
.. _asyncio-subprocess-transports: |
| 380 |
|
| 381 |
Subprocess Transports |
| 382 |
--------------------- |
| 383 |
|
| 384 |
.. method:: SubprocessTransport.get_pid() |
| 385 |
|
| 386 |
Return the subprocess process id as an integer. |
| 387 |
|
| 388 |
.. method:: SubprocessTransport.get_pipe_transport(fd) |
| 389 |
|
| 390 |
Return the transport for the communication pipe corresponding to the |
| 391 |
integer file descriptor *fd*: |
| 392 |
|
| 393 |
* ``0``: writable streaming transport of the standard input (*stdin*), |
| 394 |
or :const:`None` if the subprocess was not created with ``stdin=PIPE`` |
| 395 |
* ``1``: readable streaming transport of the standard output (*stdout*), |
| 396 |
or :const:`None` if the subprocess was not created with ``stdout=PIPE`` |
| 397 |
* ``2``: readable streaming transport of the standard error (*stderr*), |
| 398 |
or :const:`None` if the subprocess was not created with ``stderr=PIPE`` |
| 399 |
* other *fd*: :const:`None` |
| 400 |
|
| 401 |
.. method:: SubprocessTransport.get_returncode() |
| 402 |
|
| 403 |
Return the subprocess return code as an integer or :const:`None` |
| 404 |
if it hasn't returned, which is similar to the |
| 405 |
:attr:`subprocess.Popen.returncode` attribute. |
| 406 |
|
| 407 |
.. method:: SubprocessTransport.kill() |
| 408 |
|
| 409 |
Kill the subprocess. |
| 410 |
|
| 411 |
On POSIX systems, the function sends SIGKILL to the subprocess. |
| 412 |
On Windows, this method is an alias for :meth:`terminate`. |
| 413 |
|
| 414 |
See also :meth:`subprocess.Popen.kill`. |
| 415 |
|
| 416 |
.. method:: SubprocessTransport.send_signal(signal) |
| 417 |
|
| 418 |
Send the *signal* number to the subprocess, as in |
| 419 |
:meth:`subprocess.Popen.send_signal`. |
| 420 |
|
| 421 |
.. method:: SubprocessTransport.terminate() |
| 422 |
|
| 423 |
Stop the subprocess. |
| 424 |
|
| 425 |
On POSIX systems, this method sends :py:const:`~signal.SIGTERM` to the subprocess. |
| 426 |
On Windows, the Windows API function :c:func:`!TerminateProcess` is called to |
| 427 |
stop the subprocess. |
| 428 |
|
| 429 |
See also :meth:`subprocess.Popen.terminate`. |
| 430 |
|
| 431 |
.. method:: SubprocessTransport.close() |
| 432 |
|
| 433 |
Kill the subprocess by calling the :meth:`kill` method. |
| 434 |
|
| 435 |
If the subprocess hasn't returned yet, and close transports of |
| 436 |
*stdin*, *stdout*, and *stderr* pipes. |
| 437 |
|
| 438 |
|
| 439 |
.. _asyncio-protocol: |
| 440 |
|
| 441 |
Protocols |
| 442 |
========= |
| 443 |
|
| 444 |
**Source code:** :source:`Lib/asyncio/protocols.py` |
| 445 |
|
| 446 |
--------------------------------------------------- |
| 447 |
|
| 448 |
asyncio provides a set of abstract base classes that should be used |
| 449 |
to implement network protocols. Those classes are meant to be used |
| 450 |
together with :ref:`transports <asyncio-transport>`. |
| 451 |
|
| 452 |
Subclasses of abstract base protocol classes may implement some or |
| 453 |
all methods. All these methods are callbacks: they are called by |
| 454 |
transports on certain events, for example when some data is received. |
| 455 |
A base protocol method should be called by the corresponding transport. |
| 456 |
|
| 457 |
|
| 458 |
Base Protocols |
| 459 |
-------------- |
| 460 |
|
| 461 |
.. class:: BaseProtocol |
| 462 |
|
| 463 |
Base protocol with methods that all protocols share. |
| 464 |
|
| 465 |
.. class:: Protocol(BaseProtocol) |
| 466 |
|
| 467 |
The base class for implementing streaming protocols |
| 468 |
(TCP, Unix sockets, etc). |
| 469 |
|
| 470 |
.. class:: BufferedProtocol(BaseProtocol) |
| 471 |
|
| 472 |
A base class for implementing streaming protocols with manual |
| 473 |
control of the receive buffer. |
| 474 |
|
| 475 |
.. class:: DatagramProtocol(BaseProtocol) |
| 476 |
|
| 477 |
The base class for implementing datagram (UDP) protocols. |
| 478 |
|
| 479 |
.. class:: SubprocessProtocol(BaseProtocol) |
| 480 |
|
| 481 |
The base class for implementing protocols communicating with child |
| 482 |
processes (unidirectional pipes). |
| 483 |
|
| 484 |
|
| 485 |
Base Protocol |
| 486 |
------------- |
| 487 |
|
| 488 |
All asyncio protocols can implement Base Protocol callbacks. |
| 489 |
|
| 490 |
.. rubric:: Connection Callbacks |
| 491 |
|
| 492 |
Connection callbacks are called on all protocols, exactly once per |
| 493 |
a successful connection. All other protocol callbacks can only be |
| 494 |
called between those two methods. |
| 495 |
|
| 496 |
.. method:: BaseProtocol.connection_made(transport) |
| 497 |
|
| 498 |
Called when a connection is made. |
| 499 |
|
| 500 |
The *transport* argument is the transport representing the |
| 501 |
connection. The protocol is responsible for storing the reference |
| 502 |
to its transport. |
| 503 |
|
| 504 |
.. method:: BaseProtocol.connection_lost(exc) |
| 505 |
|
| 506 |
Called when the connection is lost or closed. |
| 507 |
|
| 508 |
The argument is either an exception object or :const:`None`. |
| 509 |
The latter means a regular EOF is received, or the connection was |
| 510 |
aborted or closed by this side of the connection. |
| 511 |
|
| 512 |
|
| 513 |
.. rubric:: Flow Control Callbacks |
| 514 |
|
| 515 |
Flow control callbacks can be called by transports to pause or |
| 516 |
resume writing performed by the protocol. |
| 517 |
|
| 518 |
See the documentation of the :meth:`~WriteTransport.set_write_buffer_limits` |
| 519 |
method for more details. |
| 520 |
|
| 521 |
.. method:: BaseProtocol.pause_writing() |
| 522 |
|
| 523 |
Called when the transport's buffer goes over the high watermark. |
| 524 |
|
| 525 |
.. method:: BaseProtocol.resume_writing() |
| 526 |
|
| 527 |
Called when the transport's buffer drains below the low watermark. |
| 528 |
|
| 529 |
If the buffer size equals the high watermark, |
| 530 |
:meth:`~BaseProtocol.pause_writing` is not called: the buffer size must |
| 531 |
go strictly over. |
| 532 |
|
| 533 |
Conversely, :meth:`~BaseProtocol.resume_writing` is called when the |
| 534 |
buffer size is equal or lower than the low watermark. These end |
| 535 |
conditions are important to ensure that things go as expected when |
| 536 |
either mark is zero. |
| 537 |
|
| 538 |
|
| 539 |
Streaming Protocols |
| 540 |
------------------- |
| 541 |
|
| 542 |
Event methods, such as :meth:`loop.create_server`, |
| 543 |
:meth:`loop.create_unix_server`, :meth:`loop.create_connection`, |
| 544 |
:meth:`loop.create_unix_connection`, :meth:`loop.connect_accepted_socket`, |
| 545 |
:meth:`loop.connect_read_pipe`, and :meth:`loop.connect_write_pipe` |
| 546 |
accept factories that return streaming protocols. |
| 547 |
|
| 548 |
.. method:: Protocol.data_received(data) |
| 549 |
|
| 550 |
Called when some data is received. *data* is a non-empty bytes |
| 551 |
object containing the incoming data. |
| 552 |
|
| 553 |
Whether the data is buffered, chunked or reassembled depends on |
| 554 |
the transport. In general, you shouldn't rely on specific semantics |
| 555 |
and instead make your parsing generic and flexible. However, |
| 556 |
data is always received in the correct order. |
| 557 |
|
| 558 |
The method can be called an arbitrary number of times while |
| 559 |
a connection is open. |
| 560 |
|
| 561 |
However, :meth:`protocol.eof_received() <Protocol.eof_received>` |
| 562 |
is called at most once. Once ``eof_received()`` is called, |
| 563 |
``data_received()`` is not called anymore. |
| 564 |
|
| 565 |
.. method:: Protocol.eof_received() |
| 566 |
|
| 567 |
Called when the other end signals it won't send any more data |
| 568 |
(for example by calling :meth:`transport.write_eof() |
| 569 |
<WriteTransport.write_eof>`, if the other end also uses |
| 570 |
asyncio). |
| 571 |
|
| 572 |
This method may return a false value (including ``None``), in which case |
| 573 |
the transport will close itself. Conversely, if this method returns a |
| 574 |
true value, the protocol used determines whether to close the transport. |
| 575 |
Since the default implementation returns ``None``, it implicitly closes the |
| 576 |
connection. |
| 577 |
|
| 578 |
Some transports, including SSL, don't support half-closed connections, |
| 579 |
in which case returning true from this method will result in the connection |
| 580 |
being closed. |
| 581 |
|
| 582 |
|
| 583 |
State machine: |
| 584 |
|
| 585 |
.. code-block:: none |
| 586 |
|
| 587 |
start -> connection_made |
| 588 |
[-> data_received]* |
| 589 |
[-> eof_received]? |
| 590 |
-> connection_lost -> end |
| 591 |
|
| 592 |
|
| 593 |
Buffered Streaming Protocols |
| 594 |
---------------------------- |
| 595 |
|
| 596 |
.. versionadded:: 3.7 |
| 597 |
|
| 598 |
Buffered Protocols can be used with any event loop method |
| 599 |
that supports `Streaming Protocols`_. |
| 600 |
|
| 601 |
``BufferedProtocol`` implementations allow explicit manual allocation |
| 602 |
and control of the receive buffer. Event loops can then use the buffer |
| 603 |
provided by the protocol to avoid unnecessary data copies. This |
| 604 |
can result in noticeable performance improvement for protocols that |
| 605 |
receive big amounts of data. Sophisticated protocol implementations |
| 606 |
can significantly reduce the number of buffer allocations. |
| 607 |
|
| 608 |
The following callbacks are called on :class:`BufferedProtocol` |
| 609 |
instances: |
| 610 |
|
| 611 |
.. method:: BufferedProtocol.get_buffer(sizehint) |
| 612 |
|
| 613 |
Called to allocate a new receive buffer. |
| 614 |
|
| 615 |
*sizehint* is the recommended minimum size for the returned |
| 616 |
buffer. It is acceptable to return smaller or larger buffers |
| 617 |
than what *sizehint* suggests. When set to -1, the buffer size |
| 618 |
can be arbitrary. It is an error to return a buffer with a zero size. |
| 619 |
|
| 620 |
``get_buffer()`` must return an object implementing the |
| 621 |
:ref:`buffer protocol <bufferobjects>`. |
| 622 |
|
| 623 |
.. method:: BufferedProtocol.buffer_updated(nbytes) |
| 624 |
|
| 625 |
Called when the buffer was updated with the received data. |
| 626 |
|
| 627 |
*nbytes* is the total number of bytes that were written to the buffer. |
| 628 |
|
| 629 |
.. method:: BufferedProtocol.eof_received() |
| 630 |
|
| 631 |
See the documentation of the :meth:`protocol.eof_received() |
| 632 |
<Protocol.eof_received>` method. |
| 633 |
|
| 634 |
|
| 635 |
:meth:`~BufferedProtocol.get_buffer` can be called an arbitrary number |
| 636 |
of times during a connection. However, :meth:`protocol.eof_received() |
| 637 |
<Protocol.eof_received>` is called at most once |
| 638 |
and, if called, :meth:`~BufferedProtocol.get_buffer` and |
| 639 |
:meth:`~BufferedProtocol.buffer_updated` won't be called after it. |
| 640 |
|
| 641 |
State machine: |
| 642 |
|
| 643 |
.. code-block:: none |
| 644 |
|
| 645 |
start -> connection_made |
| 646 |
[-> get_buffer |
| 647 |
[-> buffer_updated]? |
| 648 |
]* |
| 649 |
[-> eof_received]? |
| 650 |
-> connection_lost -> end |
| 651 |
|
| 652 |
|
| 653 |
Datagram Protocols |
| 654 |
------------------ |
| 655 |
|
| 656 |
Datagram Protocol instances should be constructed by protocol |
| 657 |
factories passed to the :meth:`loop.create_datagram_endpoint` method. |
| 658 |
|
| 659 |
.. method:: DatagramProtocol.datagram_received(data, addr) |
| 660 |
|
| 661 |
Called when a datagram is received. *data* is a bytes object containing |
| 662 |
the incoming data. *addr* is the address of the peer sending the data; |
| 663 |
the exact format depends on the transport. |
| 664 |
|
| 665 |
.. method:: DatagramProtocol.error_received(exc) |
| 666 |
|
| 667 |
Called when a previous send or receive operation raises an |
| 668 |
:class:`OSError`. *exc* is the :class:`OSError` instance. |
| 669 |
|
| 670 |
This method is called in rare conditions, when the transport (e.g. UDP) |
| 671 |
detects that a datagram could not be delivered to its recipient. |
| 672 |
In many conditions though, undeliverable datagrams will be silently |
| 673 |
dropped. |
| 674 |
|
| 675 |
.. note:: |
| 676 |
|
| 677 |
On BSD systems (macOS, FreeBSD, etc.) flow control is not supported |
| 678 |
for datagram protocols, because there is no reliable way to detect send |
| 679 |
failures caused by writing too many packets. |
| 680 |
|
| 681 |
The socket always appears 'ready' and excess packets are dropped. An |
| 682 |
:class:`OSError` with ``errno`` set to :const:`errno.ENOBUFS` may |
| 683 |
or may not be raised; if it is raised, it will be reported to |
| 684 |
:meth:`DatagramProtocol.error_received` but otherwise ignored. |
| 685 |
|
| 686 |
|
| 687 |
.. _asyncio-subprocess-protocols: |
| 688 |
|
| 689 |
Subprocess Protocols |
| 690 |
-------------------- |
| 691 |
|
| 692 |
Subprocess Protocol instances should be constructed by protocol |
| 693 |
factories passed to the :meth:`loop.subprocess_exec` and |
| 694 |
:meth:`loop.subprocess_shell` methods. |
| 695 |
|
| 696 |
.. method:: SubprocessProtocol.pipe_data_received(fd, data) |
| 697 |
|
| 698 |
Called when the child process writes data into its stdout or stderr |
| 699 |
pipe. |
| 700 |
|
| 701 |
*fd* is the integer file descriptor of the pipe. |
| 702 |
|
| 703 |
*data* is a non-empty bytes object containing the received data. |
| 704 |
|
| 705 |
.. method:: SubprocessProtocol.pipe_connection_lost(fd, exc) |
| 706 |
|
| 707 |
Called when one of the pipes communicating with the child process |
| 708 |
is closed. |
| 709 |
|
| 710 |
*fd* is the integer file descriptor that was closed. |
| 711 |
|
| 712 |
.. method:: SubprocessProtocol.process_exited() |
| 713 |
|
| 714 |
Called when the child process has exited. |
| 715 |
|
| 716 |
It can be called before :meth:`~SubprocessProtocol.pipe_data_received` and |
| 717 |
:meth:`~SubprocessProtocol.pipe_connection_lost` methods. |
| 718 |
|
| 719 |
|
| 720 |
Examples |
| 721 |
======== |
| 722 |
|
| 723 |
.. _asyncio_example_tcp_echo_server_protocol: |
| 724 |
|
| 725 |
TCP Echo Server |
| 726 |
--------------- |
| 727 |
|
| 728 |
Create a TCP echo server using the :meth:`loop.create_server` method, send back |
| 729 |
received data, and close the connection:: |
| 730 |
|
| 731 |
import asyncio |
| 732 |
|
| 733 |
|
| 734 |
class EchoServerProtocol(asyncio.Protocol): |
| 735 |
def connection_made(self, transport): |
| 736 |
peername = transport.get_extra_info('peername') |
| 737 |
print('Connection from {}'.format(peername)) |
| 738 |
self.transport = transport |
| 739 |
|
| 740 |
def data_received(self, data): |
| 741 |
message = data.decode() |
| 742 |
print('Data received: {!r}'.format(message)) |
| 743 |
|
| 744 |
print('Send: {!r}'.format(message)) |
| 745 |
self.transport.write(data) |
| 746 |
|
| 747 |
print('Close the client socket') |
| 748 |
self.transport.close() |
| 749 |
|
| 750 |
|
| 751 |
async def main(): |
| 752 |
# Get a reference to the event loop as we plan to use |
| 753 |
# low-level APIs. |
| 754 |
loop = asyncio.get_running_loop() |
| 755 |
|
| 756 |
server = await loop.create_server( |
| 757 |
EchoServerProtocol, |
| 758 |
'127.0.0.1', 8888) |
| 759 |
|
| 760 |
async with server: |
| 761 |
await server.serve_forever() |
| 762 |
|
| 763 |
|
| 764 |
asyncio.run(main()) |
| 765 |
|
| 766 |
|
| 767 |
.. seealso:: |
| 768 |
|
| 769 |
The :ref:`TCP echo server using streams <asyncio-tcp-echo-server-streams>` |
| 770 |
example uses the high-level :func:`asyncio.start_server` function. |
| 771 |
|
| 772 |
.. _asyncio_example_tcp_echo_client_protocol: |
| 773 |
|
| 774 |
TCP Echo Client |
| 775 |
--------------- |
| 776 |
|
| 777 |
A TCP echo client using the :meth:`loop.create_connection` method, sends |
| 778 |
data, and waits until the connection is closed:: |
| 779 |
|
| 780 |
import asyncio |
| 781 |
|
| 782 |
|
| 783 |
class EchoClientProtocol(asyncio.Protocol): |
| 784 |
def __init__(self, message, on_con_lost): |
| 785 |
self.message = message |
| 786 |
self.on_con_lost = on_con_lost |
| 787 |
|
| 788 |
def connection_made(self, transport): |
| 789 |
transport.write(self.message.encode()) |
| 790 |
print('Data sent: {!r}'.format(self.message)) |
| 791 |
|
| 792 |
def data_received(self, data): |
| 793 |
print('Data received: {!r}'.format(data.decode())) |
| 794 |
|
| 795 |
def connection_lost(self, exc): |
| 796 |
print('The server closed the connection') |
| 797 |
self.on_con_lost.set_result(True) |
| 798 |
|
| 799 |
|
| 800 |
async def main(): |
| 801 |
# Get a reference to the event loop as we plan to use |
| 802 |
# low-level APIs. |
| 803 |
loop = asyncio.get_running_loop() |
| 804 |
|
| 805 |
on_con_lost = loop.create_future() |
| 806 |
message = 'Hello World!' |
| 807 |
|
| 808 |
transport, protocol = await loop.create_connection( |
| 809 |
lambda: EchoClientProtocol(message, on_con_lost), |
| 810 |
'127.0.0.1', 8888) |
| 811 |
|
| 812 |
# Wait until the protocol signals that the connection |
| 813 |
# is lost and close the transport. |
| 814 |
try: |
| 815 |
await on_con_lost |
| 816 |
finally: |
| 817 |
transport.close() |
| 818 |
|
| 819 |
|
| 820 |
asyncio.run(main()) |
| 821 |
|
| 822 |
|
| 823 |
.. seealso:: |
| 824 |
|
| 825 |
The :ref:`TCP echo client using streams <asyncio-tcp-echo-client-streams>` |
| 826 |
example uses the high-level :func:`asyncio.open_connection` function. |
| 827 |
|
| 828 |
|
| 829 |
.. _asyncio-udp-echo-server-protocol: |
| 830 |
|
| 831 |
UDP Echo Server |
| 832 |
--------------- |
| 833 |
|
| 834 |
A UDP echo server, using the :meth:`loop.create_datagram_endpoint` |
| 835 |
method, sends back received data:: |
| 836 |
|
| 837 |
import asyncio |
| 838 |
|
| 839 |
|
| 840 |
class EchoServerProtocol: |
| 841 |
def connection_made(self, transport): |
| 842 |
self.transport = transport |
| 843 |
|
| 844 |
def datagram_received(self, data, addr): |
| 845 |
message = data.decode() |
| 846 |
print('Received %r from %s' % (message, addr)) |
| 847 |
print('Send %r to %s' % (message, addr)) |
| 848 |
self.transport.sendto(data, addr) |
| 849 |
|
| 850 |
|
| 851 |
async def main(): |
| 852 |
print("Starting UDP server") |
| 853 |
|
| 854 |
# Get a reference to the event loop as we plan to use |
| 855 |
# low-level APIs. |
| 856 |
loop = asyncio.get_running_loop() |
| 857 |
|
| 858 |
# One protocol instance will be created to serve all |
| 859 |
# client requests. |
| 860 |
transport, protocol = await loop.create_datagram_endpoint( |
| 861 |
EchoServerProtocol, |
| 862 |
local_addr=('127.0.0.1', 9999)) |
| 863 |
|
| 864 |
try: |
| 865 |
await asyncio.sleep(3600) # Serve for 1 hour. |
| 866 |
finally: |
| 867 |
transport.close() |
| 868 |
|
| 869 |
|
| 870 |
asyncio.run(main()) |
| 871 |
|
| 872 |
|
| 873 |
.. _asyncio-udp-echo-client-protocol: |
| 874 |
|
| 875 |
UDP Echo Client |
| 876 |
--------------- |
| 877 |
|
| 878 |
A UDP echo client, using the :meth:`loop.create_datagram_endpoint` |
| 879 |
method, sends data and closes the transport when it receives the answer:: |
| 880 |
|
| 881 |
import asyncio |
| 882 |
|
| 883 |
|
| 884 |
class EchoClientProtocol: |
| 885 |
def __init__(self, message, on_con_lost): |
| 886 |
self.message = message |
| 887 |
self.on_con_lost = on_con_lost |
| 888 |
self.transport = None |
| 889 |
|
| 890 |
def connection_made(self, transport): |
| 891 |
self.transport = transport |
| 892 |
print('Send:', self.message) |
| 893 |
self.transport.sendto(self.message.encode()) |
| 894 |
|
| 895 |
def datagram_received(self, data, addr): |
| 896 |
print("Received:", data.decode()) |
| 897 |
|
| 898 |
print("Close the socket") |
| 899 |
self.transport.close() |
| 900 |
|
| 901 |
def error_received(self, exc): |
| 902 |
print('Error received:', exc) |
| 903 |
|
| 904 |
def connection_lost(self, exc): |
| 905 |
print("Connection closed") |
| 906 |
self.on_con_lost.set_result(True) |
| 907 |
|
| 908 |
|
| 909 |
async def main(): |
| 910 |
# Get a reference to the event loop as we plan to use |
| 911 |
# low-level APIs. |
| 912 |
loop = asyncio.get_running_loop() |
| 913 |
|
| 914 |
on_con_lost = loop.create_future() |
| 915 |
message = "Hello World!" |
| 916 |
|
| 917 |
transport, protocol = await loop.create_datagram_endpoint( |
| 918 |
lambda: EchoClientProtocol(message, on_con_lost), |
| 919 |
remote_addr=('127.0.0.1', 9999)) |
| 920 |
|
| 921 |
try: |
| 922 |
await on_con_lost |
| 923 |
finally: |
| 924 |
transport.close() |
| 925 |
|
| 926 |
|
| 927 |
asyncio.run(main()) |
| 928 |
|
| 929 |
|
| 930 |
.. _asyncio_example_create_connection: |
| 931 |
|
| 932 |
Connecting Existing Sockets |
| 933 |
--------------------------- |
| 934 |
|
| 935 |
Wait until a socket receives data using the |
| 936 |
:meth:`loop.create_connection` method with a protocol:: |
| 937 |
|
| 938 |
import asyncio |
| 939 |
import socket |
| 940 |
|
| 941 |
|
| 942 |
class MyProtocol(asyncio.Protocol): |
| 943 |
|
| 944 |
def __init__(self, on_con_lost): |
| 945 |
self.transport = None |
| 946 |
self.on_con_lost = on_con_lost |
| 947 |
|
| 948 |
def connection_made(self, transport): |
| 949 |
self.transport = transport |
| 950 |
|
| 951 |
def data_received(self, data): |
| 952 |
print("Received:", data.decode()) |
| 953 |
|
| 954 |
# We are done: close the transport; |
| 955 |
# connection_lost() will be called automatically. |
| 956 |
self.transport.close() |
| 957 |
|
| 958 |
def connection_lost(self, exc): |
| 959 |
# The socket has been closed |
| 960 |
self.on_con_lost.set_result(True) |
| 961 |
|
| 962 |
|
| 963 |
async def main(): |
| 964 |
# Get a reference to the event loop as we plan to use |
| 965 |
# low-level APIs. |
| 966 |
loop = asyncio.get_running_loop() |
| 967 |
on_con_lost = loop.create_future() |
| 968 |
|
| 969 |
# Create a pair of connected sockets |
| 970 |
rsock, wsock = socket.socketpair() |
| 971 |
|
| 972 |
# Register the socket to wait for data. |
| 973 |
transport, protocol = await loop.create_connection( |
| 974 |
lambda: MyProtocol(on_con_lost), sock=rsock) |
| 975 |
|
| 976 |
# Simulate the reception of data from the network. |
| 977 |
loop.call_soon(wsock.send, 'abc'.encode()) |
| 978 |
|
| 979 |
try: |
| 980 |
await protocol.on_con_lost |
| 981 |
finally: |
| 982 |
transport.close() |
| 983 |
wsock.close() |
| 984 |
|
| 985 |
asyncio.run(main()) |
| 986 |
|
| 987 |
.. seealso:: |
| 988 |
|
| 989 |
The :ref:`watch a file descriptor for read events |
| 990 |
<asyncio_example_watch_fd>` example uses the low-level |
| 991 |
:meth:`loop.add_reader` method to register an FD. |
| 992 |
|
| 993 |
The :ref:`register an open socket to wait for data using streams |
| 994 |
<asyncio_example_create_connection-streams>` example uses high-level streams |
| 995 |
created by the :func:`open_connection` function in a coroutine. |
| 996 |
|
| 997 |
.. _asyncio_example_subprocess_proto: |
| 998 |
|
| 999 |
loop.subprocess_exec() and SubprocessProtocol |
| 1000 |
--------------------------------------------- |
| 1001 |
|
| 1002 |
An example of a subprocess protocol used to get the output of a |
| 1003 |
subprocess and to wait for the subprocess exit. |
| 1004 |
|
| 1005 |
The subprocess is created by the :meth:`loop.subprocess_exec` method:: |
| 1006 |
|
| 1007 |
import asyncio |
| 1008 |
import sys |
| 1009 |
|
| 1010 |
class DateProtocol(asyncio.SubprocessProtocol): |
| 1011 |
def __init__(self, exit_future): |
| 1012 |
self.exit_future = exit_future |
| 1013 |
self.output = bytearray() |
| 1014 |
self.pipe_closed = False |
| 1015 |
self.exited = False |
| 1016 |
|
| 1017 |
def pipe_connection_lost(self, fd, exc): |
| 1018 |
self.pipe_closed = True |
| 1019 |
self.check_for_exit() |
| 1020 |
|
| 1021 |
def pipe_data_received(self, fd, data): |
| 1022 |
self.output.extend(data) |
| 1023 |
|
| 1024 |
def process_exited(self): |
| 1025 |
self.exited = True |
| 1026 |
# process_exited() method can be called before |
| 1027 |
# pipe_connection_lost() method: wait until both methods are |
| 1028 |
# called. |
| 1029 |
self.check_for_exit() |
| 1030 |
|
| 1031 |
def check_for_exit(self): |
| 1032 |
if self.pipe_closed and self.exited: |
| 1033 |
self.exit_future.set_result(True) |
| 1034 |
|
| 1035 |
async def get_date(): |
| 1036 |
# Get a reference to the event loop as we plan to use |
| 1037 |
# low-level APIs. |
| 1038 |
loop = asyncio.get_running_loop() |
| 1039 |
|
| 1040 |
code = 'import datetime as dt; print(dt.datetime.now())' |
| 1041 |
exit_future = asyncio.Future(loop=loop) |
| 1042 |
|
| 1043 |
# Create the subprocess controlled by DateProtocol; |
| 1044 |
# redirect the standard output into a pipe. |
| 1045 |
transport, protocol = await loop.subprocess_exec( |
| 1046 |
lambda: DateProtocol(exit_future), |
| 1047 |
sys.executable, '-c', code, |
| 1048 |
stdin=None, stderr=None) |
| 1049 |
|
| 1050 |
# Wait for the subprocess exit using the process_exited() |
| 1051 |
# method of the protocol. |
| 1052 |
await exit_future |
| 1053 |
|
| 1054 |
# Close the stdout pipe. |
| 1055 |
transport.close() |
| 1056 |
|
| 1057 |
# Read the output which was collected by the |
| 1058 |
# pipe_data_received() method of the protocol. |
| 1059 |
data = bytes(protocol.output) |
| 1060 |
return data.decode('ascii').rstrip() |
| 1061 |
|
| 1062 |
date = asyncio.run(get_date()) |
| 1063 |
print(f"Current date: {date}") |
| 1064 |
|
| 1065 |
See also the :ref:`same example <asyncio_example_create_subprocess_exec>` |
| 1066 |
written using high-level APIs. |