1Changelog 2--------- 3 4.. currentmodule:: websockets 5 68.2 7... 8 9*In development* 10 118.1 12... 13 14* Added compatibility with Python 3.8. 15 168.0.2 17..... 18 19* Restored the ability to pass a socket with the ``sock`` parameter of 20 :func:`~server.serve`. 21 22* Removed an incorrect assertion when a connection drops. 23 248.0.1 25..... 26 27* Restored the ability to import ``WebSocketProtocolError`` from 28 ``websockets``. 29 308.0 31... 32 33.. warning:: 34 35 **Version 8.0 drops compatibility with Python 3.4 and 3.5.** 36 37.. note:: 38 39 **Version 8.0 expects** ``process_request`` **to be a coroutine.** 40 41 Previously, it could be a function or a coroutine. 42 43 If you're passing a ``process_request`` argument to :func:`~server.serve` 44 or :class:`~server.WebSocketServerProtocol`, or if you're overriding 45 :meth:`~protocol.WebSocketServerProtocol.process_request` in a subclass, 46 define it with ``async def`` instead of ``def``. 47 48 For backwards compatibility, functions are still mostly supported, but 49 mixing functions and coroutines won't work in some inheritance scenarios. 50 51.. note:: 52 53 **Version 8.0 changes the behavior of the** ``max_queue`` **parameter.** 54 55 If you were setting ``max_queue=0`` to make the queue of incoming messages 56 unbounded, change it to ``max_queue=None``. 57 58.. note:: 59 60 **Version 8.0 deprecates the** ``host`` **,** ``port`` **, and** ``secure`` 61 **attributes of** :class:`~protocol.WebSocketCommonProtocol`. 62 63 Use :attr:`~protocol.WebSocketCommonProtocol.local_address` in servers and 64 :attr:`~protocol.WebSocketCommonProtocol.remote_address` in clients 65 instead of ``host`` and ``port``. 66 67.. note:: 68 69 **Version 8.0 renames the** ``WebSocketProtocolError`` **exception** 70 to :exc:`ProtocolError` **.** 71 72 A ``WebSocketProtocolError`` alias provides backwards compatibility. 73 74.. note:: 75 76 **Version 8.0 adds the reason phrase to the return type of the low-level 77 API** :func:`~http.read_response` **.** 78 79Also: 80 81* :meth:`~protocol.WebSocketCommonProtocol.send`, 82 :meth:`~protocol.WebSocketCommonProtocol.ping`, and 83 :meth:`~protocol.WebSocketCommonProtocol.pong` support bytes-like types 84 :class:`bytearray` and :class:`memoryview` in addition to :class:`bytes`. 85 86* Added :exc:`~exceptions.ConnectionClosedOK` and 87 :exc:`~exceptions.ConnectionClosedError` subclasses of 88 :exc:`~exceptions.ConnectionClosed` to tell apart normal connection 89 termination from errors. 90 91* Added :func:`~auth.basic_auth_protocol_factory` to enforce HTTP Basic Auth 92 on the server side. 93 94* :func:`~client.connect` handles redirects from the server during the 95 handshake. 96 97* :func:`~client.connect` supports overriding ``host`` and ``port``. 98 99* Added :func:`~client.unix_connect` for connecting to Unix sockets. 100 101* Improved support for sending fragmented messages by accepting asynchronous 102 iterators in :meth:`~protocol.WebSocketCommonProtocol.send`. 103 104* Prevented spurious log messages about :exc:`~exceptions.ConnectionClosed` 105 exceptions in keepalive ping task. If you were using ``ping_timeout=None`` 106 as a workaround, you can remove it. 107 108* Changed :meth:`WebSocketServer.close() <server.WebSocketServer.close>` to 109 perform a proper closing handshake instead of failing the connection. 110 111* Avoided a crash when a ``extra_headers`` callable returns ``None``. 112 113* Improved error messages when HTTP parsing fails. 114 115* Enabled readline in the interactive client. 116 117* Added type hints (:pep:`484`). 118 119* Added a FAQ to the documentation. 120 121* Added documentation for extensions. 122 123* Documented how to optimize memory usage. 124 125* Improved API documentation. 126 1277.0 128... 129 130.. warning:: 131 132 **Version 7.0 renames the** ``timeout`` **argument of** 133 :func:`~server.serve()` **and** :func:`~client.connect` **to** 134 ``close_timeout`` **.** 135 136 This prevents confusion with ``ping_timeout``. 137 138 For backwards compatibility, ``timeout`` is still supported. 139 140.. warning:: 141 142 **Version 7.0 changes how a server terminates connections when it's 143 closed with** :meth:`~server.WebSocketServer.close` **.** 144 145 Previously, connections handlers were canceled. Now, connections are 146 closed with close code 1001 (going away). From the perspective of the 147 connection handler, this is the same as if the remote endpoint was 148 disconnecting. This removes the need to prepare for 149 :exc:`~asyncio.CancelledError` in connection handlers. 150 151 You can restore the previous behavior by adding the following line at the 152 beginning of connection handlers:: 153 154 def handler(websocket, path): 155 closed = asyncio.ensure_future(websocket.wait_closed()) 156 closed.add_done_callback(lambda task: task.cancel()) 157 158.. note:: 159 160 **Version 7.0 changes how a** :meth:`~protocol.WebSocketCommonProtocol.ping` 161 **that hasn't received a pong yet behaves when the connection is closed.** 162 163 The ping — as in ``ping = await websocket.ping()`` — used to be canceled 164 when the connection is closed, so that ``await ping`` raised 165 :exc:`~asyncio.CancelledError`. Now ``await ping`` raises 166 :exc:`~exceptions.ConnectionClosed` like other public APIs. 167 168.. note:: 169 170 **Version 7.0 raises a** :exc:`RuntimeError` **exception if two coroutines 171 call** :meth:`~protocol.WebSocketCommonProtocol.recv` **concurrently.** 172 173 Concurrent calls lead to non-deterministic behavior because there are no 174 guarantees about which coroutine will receive which message. 175 176Also: 177 178* ``websockets`` sends Ping frames at regular intervals and closes the 179 connection if it doesn't receive a matching Pong frame. See 180 :class:`~protocol.WebSocketCommonProtocol` for details. 181 182* Added ``process_request`` and ``select_subprotocol`` arguments to 183 :func:`~server.serve` and :class:`~server.WebSocketServerProtocol` to 184 customize :meth:`~server.WebSocketServerProtocol.process_request` and 185 :meth:`~server.WebSocketServerProtocol.select_subprotocol` without 186 subclassing :class:`~server.WebSocketServerProtocol`. 187 188* Added support for sending fragmented messages. 189 190* Added the :meth:`~protocol.WebSocketCommonProtocol.wait_closed` method to 191 protocols. 192 193* Added an interactive client: ``python -m websockets <uri>``. 194 195* Changed the ``origins`` argument to represent the lack of an origin with 196 ``None`` rather than ``''``. 197 198* Fixed a data loss bug in :meth:`~protocol.WebSocketCommonProtocol.recv`: 199 canceling it at the wrong time could result in messages being dropped. 200 201* Improved handling of multiple HTTP headers with the same name. 202 203* Improved error messages when a required HTTP header is missing. 204 2056.0 206... 207 208.. warning:: 209 210 **Version 6.0 introduces the** :class:`~http.Headers` **class for managing 211 HTTP headers and changes several public APIs:** 212 213 * :meth:`~server.WebSocketServerProtocol.process_request` now receives a 214 :class:`~http.Headers` instead of a :class:`~http.client.HTTPMessage` in 215 the ``request_headers`` argument. 216 217 * The :attr:`~protocol.WebSocketCommonProtocol.request_headers` and 218 :attr:`~protocol.WebSocketCommonProtocol.response_headers` attributes of 219 :class:`~protocol.WebSocketCommonProtocol` are :class:`~http.Headers` 220 instead of :class:`~http.client.HTTPMessage`. 221 222 * The :attr:`~protocol.WebSocketCommonProtocol.raw_request_headers` and 223 :attr:`~protocol.WebSocketCommonProtocol.raw_response_headers` 224 attributes of :class:`~protocol.WebSocketCommonProtocol` are removed. 225 Use :meth:`~http.Headers.raw_items` instead. 226 227 * Functions defined in the :mod:`~handshake` module now receive 228 :class:`~http.Headers` in argument instead of ``get_header`` or 229 ``set_header`` functions. This affects libraries that rely on 230 low-level APIs. 231 232 * Functions defined in the :mod:`~http` module now return HTTP headers as 233 :class:`~http.Headers` instead of lists of ``(name, value)`` pairs. 234 235 Since :class:`~http.Headers` and :class:`~http.client.HTTPMessage` provide 236 similar APIs, this change won't affect most of the code dealing with HTTP 237 headers. 238 239 240Also: 241 242* Added compatibility with Python 3.7. 243 2445.0.1 245..... 246 247* Fixed a regression in the 5.0 release that broke some invocations of 248 :func:`~server.serve()` and :func:`~client.connect`. 249 2505.0 251... 252 253.. note:: 254 255 **Version 5.0 fixes a security issue introduced in version 4.0.** 256 257 Version 4.0 was vulnerable to denial of service by memory exhaustion 258 because it didn't enforce ``max_size`` when decompressing compressed 259 messages (`CVE-2018-1000518`_). 260 261 .. _CVE-2018-1000518: https://nvd.nist.gov/vuln/detail/CVE-2018-1000518 262 263.. note:: 264 265 **Version 5.0 adds a** ``user_info`` **field to the return value of** 266 :func:`~uri.parse_uri` **and** :class:`~uri.WebSocketURI` **.** 267 268 If you're unpacking :class:`~exceptions.WebSocketURI` into four variables, 269 adjust your code to account for that fifth field. 270 271Also: 272 273* :func:`~client.connect` performs HTTP Basic Auth when the URI contains 274 credentials. 275 276* Iterating on incoming messages no longer raises an exception when the 277 connection terminates with close code 1001 (going away). 278 279* A plain HTTP request now receives a 426 Upgrade Required response and 280 doesn't log a stack trace. 281 282* :func:`~server.unix_serve` can be used as an asynchronous context manager on 283 Python ≥ 3.5.1. 284 285* Added the :attr:`~protocol.WebSocketCommonProtocol.closed` property to 286 protocols. 287 288* If a :meth:`~protocol.WebSocketCommonProtocol.ping` doesn't receive a pong, 289 it's canceled when the connection is closed. 290 291* Reported the cause of :exc:`~exceptions.ConnectionClosed` exceptions. 292 293* Added new examples in the documentation. 294 295* Updated documentation with new features from Python 3.6. 296 297* Improved several other sections of the documentation. 298 299* Fixed missing close code, which caused :exc:`TypeError` on connection close. 300 301* Fixed a race condition in the closing handshake that raised 302 :exc:`~exceptions.InvalidState`. 303 304* Stopped logging stack traces when the TCP connection dies prematurely. 305 306* Prevented writing to a closing TCP connection during unclean shutdowns. 307 308* Made connection termination more robust to network congestion. 309 310* Prevented processing of incoming frames after failing the connection. 311 3124.0.1 313..... 314 315* Fixed issues with the packaging of the 4.0 release. 316 3174.0 318... 319 320.. warning:: 321 322 **Version 4.0 enables compression with the permessage-deflate extension.** 323 324 In August 2017, Firefox and Chrome support it, but not Safari and IE. 325 326 Compression should improve performance but it increases RAM and CPU use. 327 328 If you want to disable compression, add ``compression=None`` when calling 329 :func:`~server.serve()` or :func:`~client.connect`. 330 331.. warning:: 332 333 **Version 4.0 drops compatibility with Python 3.3.** 334 335.. note:: 336 337 **Version 4.0 removes the** ``state_name`` **attribute of protocols.** 338 339 Use ``protocol.state.name`` instead of ``protocol.state_name``. 340 341Also: 342 343* :class:`~protocol.WebSocketCommonProtocol` instances can be used as 344 asynchronous iterators on Python ≥ 3.6. They yield incoming messages. 345 346* Added :func:`~server.unix_serve` for listening on Unix sockets. 347 348* Added the :attr:`~server.WebSocketServer.sockets` attribute to the return 349 value of :func:`~server.serve`. 350 351* Reorganized and extended documentation. 352 353* Aborted connections if they don't close within the configured ``timeout``. 354 355* Rewrote connection termination to increase robustness in edge cases. 356 357* Stopped leaking pending tasks when :meth:`~asyncio.Task.cancel` is called on 358 a connection while it's being closed. 359 360* Reduced verbosity of "Failing the WebSocket connection" logs. 361 362* Allowed ``extra_headers`` to override ``Server`` and ``User-Agent`` headers. 363 3643.4 365... 366 367* Renamed :func:`~server.serve()` and :func:`~client.connect`'s ``klass`` 368 argument to ``create_protocol`` to reflect that it can also be a callable. 369 For backwards compatibility, ``klass`` is still supported. 370 371* :func:`~server.serve` can be used as an asynchronous context manager on 372 Python ≥ 3.5.1. 373 374* Added support for customizing handling of incoming connections with 375 :meth:`~server.WebSocketServerProtocol.process_request`. 376 377* Made read and write buffer sizes configurable. 378 379* Rewrote HTTP handling for simplicity and performance. 380 381* Added an optional C extension to speed up low-level operations. 382 383* An invalid response status code during :func:`~client.connect` now raises 384 :class:`~exceptions.InvalidStatusCode` with a ``code`` attribute. 385 386* Providing a ``sock`` argument to :func:`~client.connect` no longer 387 crashes. 388 3893.3 390... 391 392* Ensured compatibility with Python 3.6. 393 394* Reduced noise in logs caused by connection resets. 395 396* Avoided crashing on concurrent writes on slow connections. 397 3983.2 399... 400 401* Added ``timeout``, ``max_size``, and ``max_queue`` arguments to 402 :func:`~client.connect()` and :func:`~server.serve`. 403 404* Made server shutdown more robust. 405 4063.1 407... 408 409* Avoided a warning when closing a connection before the opening handshake. 410 411* Added flow control for incoming data. 412 4133.0 414... 415 416.. warning:: 417 418 **Version 3.0 introduces a backwards-incompatible change in the** 419 :meth:`~protocol.WebSocketCommonProtocol.recv` **API.** 420 421 **If you're upgrading from 2.x or earlier, please read this carefully.** 422 423 :meth:`~protocol.WebSocketCommonProtocol.recv` used to return ``None`` 424 when the connection was closed. This required checking the return value of 425 every call:: 426 427 message = await websocket.recv() 428 if message is None: 429 return 430 431 Now it raises a :exc:`~exceptions.ConnectionClosed` exception instead. 432 This is more Pythonic. The previous code can be simplified to:: 433 434 message = await websocket.recv() 435 436 When implementing a server, which is the more popular use case, there's no 437 strong reason to handle such exceptions. Let them bubble up, terminate the 438 handler coroutine, and the server will simply ignore them. 439 440 In order to avoid stranding projects built upon an earlier version, the 441 previous behavior can be restored by passing ``legacy_recv=True`` to 442 :func:`~server.serve`, :func:`~client.connect`, 443 :class:`~server.WebSocketServerProtocol`, or 444 :class:`~client.WebSocketClientProtocol`. ``legacy_recv`` isn't documented 445 in their signatures but isn't scheduled for deprecation either. 446 447Also: 448 449* :func:`~client.connect` can be used as an asynchronous context manager on 450 Python ≥ 3.5.1. 451 452* Updated documentation with ``await`` and ``async`` syntax from Python 3.5. 453 454* :meth:`~protocol.WebSocketCommonProtocol.ping` and 455 :meth:`~protocol.WebSocketCommonProtocol.pong` support data passed as 456 :class:`str` in addition to :class:`bytes`. 457 458* Worked around an asyncio bug affecting connection termination under load. 459 460* Made ``state_name`` attribute on protocols a public API. 461 462* Improved documentation. 463 4642.7 465... 466 467* Added compatibility with Python 3.5. 468 469* Refreshed documentation. 470 4712.6 472... 473 474* Added ``local_address`` and ``remote_address`` attributes on protocols. 475 476* Closed open connections with code 1001 when a server shuts down. 477 478* Avoided TCP fragmentation of small frames. 479 4802.5 481... 482 483* Improved documentation. 484 485* Provided access to handshake request and response HTTP headers. 486 487* Allowed customizing handshake request and response HTTP headers. 488 489* Supported running on a non-default event loop. 490 491* Returned a 403 status code instead of 400 when the request Origin isn't 492 allowed. 493 494* Canceling :meth:`~protocol.WebSocketCommonProtocol.recv` no longer drops 495 the next message. 496 497* Clarified that the closing handshake can be initiated by the client. 498 499* Set the close code and reason more consistently. 500 501* Strengthened connection termination by simplifying the implementation. 502 503* Improved tests, added tox configuration, and enforced 100% branch coverage. 504 5052.4 506... 507 508* Added support for subprotocols. 509 510* Supported non-default event loop. 511 512* Added ``loop`` argument to :func:`~client.connect` and 513 :func:`~server.serve`. 514 5152.3 516... 517 518* Improved compliance of close codes. 519 5202.2 521... 522 523* Added support for limiting message size. 524 5252.1 526... 527 528* Added ``host``, ``port`` and ``secure`` attributes on protocols. 529 530* Added support for providing and checking Origin_. 531 532.. _Origin: https://tools.ietf.org/html/rfc6455#section-10.2 533 5342.0 535... 536 537.. warning:: 538 539 **Version 2.0 introduces a backwards-incompatible change in the** 540 :meth:`~protocol.WebSocketCommonProtocol.send`, 541 :meth:`~protocol.WebSocketCommonProtocol.ping`, and 542 :meth:`~protocol.WebSocketCommonProtocol.pong` **APIs.** 543 544 **If you're upgrading from 1.x or earlier, please read this carefully.** 545 546 These APIs used to be functions. Now they're coroutines. 547 548 Instead of:: 549 550 websocket.send(message) 551 552 you must now write:: 553 554 await websocket.send(message) 555 556Also: 557 558* Added flow control for outgoing data. 559 5601.0 561... 562 563* Initial public release. 564