changelog.rst (31533B)
1 Changelog 2 ========= 3 4 .. currentmodule:: websockets 5 6 .. _backwards-compatibility policy: 7 8 Backwards-compatibility policy 9 ------------------------------ 10 11 websockets is intended for production use. Therefore, stability is a goal. 12 13 websockets also aims at providing the best API for WebSocket in Python. 14 15 While we value stability, we value progress more. When an improvement requires 16 changing a public API, we make the change and document it in this changelog. 17 18 When possible with reasonable effort, we preserve backwards-compatibility for 19 five years after the release that introduced the change. 20 21 When a release contains backwards-incompatible API changes, the major version 22 is increased, else the minor version is increased. Patch versions are only for 23 fixing regressions shortly after a release. 24 25 Only documented APIs are public. Undocumented, private APIs may change without 26 notice. 27 28 12.0 29 ---- 30 31 *October 21, 2023* 32 33 Backwards-incompatible changes 34 .............................. 35 36 .. admonition:: websockets 12.0 requires Python ≥ 3.8. 37 :class: tip 38 39 websockets 11.0 is the last version supporting Python 3.7. 40 41 Improvements 42 ............ 43 44 * Made convenience imports from ``websockets`` compatible with static code 45 analysis tools such as auto-completion in an IDE or type checking with mypy_. 46 47 .. _mypy: https://github.com/python/mypy 48 49 * Accepted a plain :class:`int` where an :class:`~http.HTTPStatus` is expected. 50 51 * Added :class:`~frames.CloseCode`. 52 53 11.0.3 54 ------ 55 56 *May 7, 2023* 57 58 Bug fixes 59 ......... 60 61 * Fixed the :mod:`threading` implementation of servers on Windows. 62 63 11.0.2 64 ------ 65 66 *April 18, 2023* 67 68 Bug fixes 69 ......... 70 71 * Fixed a deadlock in the :mod:`threading` implementation when closing a 72 connection without reading all messages. 73 74 11.0.1 75 ------ 76 77 *April 6, 2023* 78 79 Bug fixes 80 ......... 81 82 * Restored the C extension in the source distribution. 83 84 11.0 85 ---- 86 87 *April 2, 2023* 88 89 Backwards-incompatible changes 90 .............................. 91 92 .. admonition:: The Sans-I/O implementation was moved. 93 :class: caution 94 95 Aliases provide compatibility for all previously public APIs according to 96 the `backwards-compatibility policy`_. 97 98 * The ``connection`` module was renamed to ``protocol``. 99 100 * The ``connection.Connection``, ``server.ServerConnection``, and 101 ``client.ClientConnection`` classes were renamed to ``protocol.Protocol``, 102 ``server.ServerProtocol``, and ``client.ClientProtocol``. 103 104 .. admonition:: Sans-I/O protocol constructors now use keyword-only arguments. 105 :class: caution 106 107 If you instantiate :class:`~server.ServerProtocol` or 108 :class:`~client.ClientProtocol` directly, make sure you are using keyword 109 arguments. 110 111 .. admonition:: Closing a connection without an empty close frame is OK. 112 :class: note 113 114 Receiving an empty close frame now results in 115 :exc:`~exceptions.ConnectionClosedOK` instead of 116 :exc:`~exceptions.ConnectionClosedError`. 117 118 As a consequence, calling ``WebSocket.close()`` without arguments in a 119 browser isn't reported as an error anymore. 120 121 .. admonition:: :func:`~server.serve` times out on the opening handshake after 10 seconds by default. 122 :class: note 123 124 You can adjust the timeout with the ``open_timeout`` parameter. Set it to 125 :obj:`None` to disable the timeout entirely. 126 127 New features 128 ............ 129 130 .. admonition:: websockets 11.0 introduces a implementation on top of :mod:`threading`. 131 :class: important 132 133 It may be more convenient if you don't need to manage many connections and 134 you're more comfortable with :mod:`threading` than :mod:`asyncio`. 135 136 It is particularly suited to client applications that establish only one 137 connection. It may be used for servers handling few connections. 138 139 See :func:`~sync.client.connect` and :func:`~sync.server.serve` for details. 140 141 * Added ``open_timeout`` to :func:`~server.serve`. 142 143 * Made it possible to close a server without closing existing connections. 144 145 * Added :attr:`~server.ServerProtocol.select_subprotocol` to customize 146 negotiation of subprotocols in the Sans-I/O layer. 147 148 Improvements 149 ............ 150 151 * Added platform-independent wheels. 152 153 * Improved error handling in :func:`~websockets.broadcast`. 154 155 * Set ``server_hostname`` automatically on TLS connections when providing a 156 ``sock`` argument to :func:`~sync.client.connect`. 157 158 10.4 159 ---- 160 161 *October 25, 2022* 162 163 New features 164 ............ 165 166 * Validated compatibility with Python 3.11. 167 168 * Added the :attr:`~legacy.protocol.WebSocketCommonProtocol.latency` property to 169 protocols. 170 171 * Changed :attr:`~legacy.protocol.WebSocketCommonProtocol.ping` to return the 172 latency of the connection. 173 174 * Supported overriding or removing the ``User-Agent`` header in clients and the 175 ``Server`` header in servers. 176 177 * Added deployment guides for more Platform as a Service providers. 178 179 Improvements 180 ............ 181 182 * Improved FAQ. 183 184 10.3 185 ---- 186 187 *April 17, 2022* 188 189 Backwards-incompatible changes 190 .............................. 191 192 .. admonition:: The ``exception`` attribute of :class:`~http11.Request` and :class:`~http11.Response` is deprecated. 193 :class: note 194 195 Use the ``handshake_exc`` attribute of :class:`~server.ServerProtocol` and 196 :class:`~client.ClientProtocol` instead. 197 198 See :doc:`../howto/sansio` for details. 199 200 Improvements 201 ............ 202 203 * Reduced noise in logs when :mod:`ssl` or :mod:`zlib` raise exceptions. 204 205 10.2 206 ---- 207 208 *February 21, 2022* 209 210 Improvements 211 ............ 212 213 * Made compression negotiation more lax for compatibility with Firefox. 214 215 * Improved FAQ and quick start guide. 216 217 Bug fixes 218 ......... 219 220 * Fixed backwards-incompatibility in 10.1 for connection handlers created with 221 :func:`functools.partial`. 222 223 * Avoided leaking open sockets when :func:`~client.connect` is canceled. 224 225 10.1 226 ---- 227 228 *November 14, 2021* 229 230 New features 231 ............ 232 233 * Added a tutorial. 234 235 * Made the second parameter of connection handlers optional. It will be 236 deprecated in the next major release. The request path is available in 237 the :attr:`~legacy.protocol.WebSocketCommonProtocol.path` attribute of 238 the first argument. 239 240 If you implemented the connection handler of a server as:: 241 242 async def handler(request, path): 243 ... 244 245 You should replace it by:: 246 247 async def handler(request): 248 path = request.path # if handler() uses the path argument 249 ... 250 251 * Added ``python -m websockets --version``. 252 253 Improvements 254 ............ 255 256 * Added wheels for Python 3.10, PyPy 3.7, and for more platforms. 257 258 * Reverted optimization of default compression settings for clients, mainly to 259 avoid triggering bugs in poorly implemented servers like `AWS API Gateway`_. 260 261 .. _AWS API Gateway: https://github.com/python-websockets/websockets/issues/1065 262 263 * Mirrored the entire :class:`~asyncio.Server` API 264 in :class:`~server.WebSocketServer`. 265 266 * Improved performance for large messages on ARM processors. 267 268 * Documented how to auto-reload on code changes in development. 269 270 Bug fixes 271 ......... 272 273 * Avoided half-closing TCP connections that are already closed. 274 275 10.0 276 ---- 277 278 *September 9, 2021* 279 280 Backwards-incompatible changes 281 .............................. 282 283 .. admonition:: websockets 10.0 requires Python ≥ 3.7. 284 :class: tip 285 286 websockets 9.1 is the last version supporting Python 3.6. 287 288 .. admonition:: The ``loop`` parameter is deprecated from all APIs. 289 :class: caution 290 291 This reflects a decision made in Python 3.8. See the release notes of 292 Python 3.10 for details. 293 294 The ``loop`` parameter is also removed 295 from :class:`~server.WebSocketServer`. This should be transparent. 296 297 .. admonition:: :func:`~client.connect` times out after 10 seconds by default. 298 :class: note 299 300 You can adjust the timeout with the ``open_timeout`` parameter. Set it to 301 :obj:`None` to disable the timeout entirely. 302 303 .. admonition:: The ``legacy_recv`` option is deprecated. 304 :class: note 305 306 See the release notes of websockets 3.0 for details. 307 308 .. admonition:: The signature of :exc:`~exceptions.ConnectionClosed` changed. 309 :class: note 310 311 If you raise :exc:`~exceptions.ConnectionClosed` or a subclass, rather 312 than catch them when websockets raises them, you must change your code. 313 314 .. admonition:: A ``msg`` parameter was added to :exc:`~exceptions.InvalidURI`. 315 :class: note 316 317 If you raise :exc:`~exceptions.InvalidURI`, rather than catch it when 318 websockets raises it, you must change your code. 319 320 New features 321 ............ 322 323 .. admonition:: websockets 10.0 introduces a `Sans-I/O API 324 <https://sans-io.readthedocs.io/>`_ for easier integration 325 in third-party libraries. 326 :class: important 327 328 If you're integrating websockets in a library, rather than just using it, 329 look at the :doc:`Sans-I/O integration guide <../howto/sansio>`. 330 331 * Added compatibility with Python 3.10. 332 333 * Added :func:`~websockets.broadcast` to send a message to many clients. 334 335 * Added support for reconnecting automatically by using 336 :func:`~client.connect` as an asynchronous iterator. 337 338 * Added ``open_timeout`` to :func:`~client.connect`. 339 340 * Documented how to integrate with `Django <https://www.djangoproject.com/>`_. 341 342 * Documented how to deploy websockets in production, with several options. 343 344 * Documented how to authenticate connections. 345 346 * Documented how to broadcast messages to many connections. 347 348 Improvements 349 ............ 350 351 * Improved logging. See the :doc:`logging guide <../topics/logging>`. 352 353 * Optimized default compression settings to reduce memory usage. 354 355 * Optimized processing of client-to-server messages when the C extension isn't 356 available. 357 358 * Supported relative redirects in :func:`~client.connect`. 359 360 * Handled TCP connection drops during the opening handshake. 361 362 * Made it easier to customize authentication with 363 :meth:`~auth.BasicAuthWebSocketServerProtocol.check_credentials`. 364 365 * Provided additional information in :exc:`~exceptions.ConnectionClosed` 366 exceptions. 367 368 * Clarified several exceptions or log messages. 369 370 * Restructured documentation. 371 372 * Improved API documentation. 373 374 * Extended FAQ. 375 376 Bug fixes 377 ......... 378 379 * Avoided a crash when receiving a ping while the connection is closing. 380 381 9.1 382 --- 383 384 *May 27, 2021* 385 386 Security fix 387 ............ 388 389 .. admonition:: websockets 9.1 fixes a security issue introduced in 8.0. 390 :class: important 391 392 Version 8.0 was vulnerable to timing attacks on HTTP Basic Auth passwords 393 (`CVE-2021-33880`_). 394 395 .. _CVE-2021-33880: https://nvd.nist.gov/vuln/detail/CVE-2021-33880 396 397 9.0.2 398 ----- 399 400 *May 15, 2021* 401 402 Bug fixes 403 ......... 404 405 * Restored compatibility of ``python -m websockets`` with Python < 3.9. 406 407 * Restored compatibility with mypy. 408 409 9.0.1 410 ----- 411 412 *May 2, 2021* 413 414 Bug fixes 415 ......... 416 417 * Fixed issues with the packaging of the 9.0 release. 418 419 9.0 420 --- 421 422 *May 1, 2021* 423 424 Backwards-incompatible changes 425 .............................. 426 427 .. admonition:: Several modules are moved or deprecated. 428 :class: caution 429 430 Aliases provide compatibility for all previously public APIs according to 431 the `backwards-compatibility policy`_ 432 433 * :class:`~datastructures.Headers` and 434 :exc:`~datastructures.MultipleValuesError` are moved from 435 ``websockets.http`` to :mod:`websockets.datastructures`. If you're using 436 them, you should adjust the import path. 437 438 * The ``client``, ``server``, ``protocol``, and ``auth`` modules were 439 moved from the ``websockets`` package to a ``websockets.legacy`` 440 sub-package. Despite the name, they're still fully supported. 441 442 * The ``framing``, ``handshake``, ``headers``, ``http``, and ``uri`` 443 modules in the ``websockets`` package are deprecated. These modules 444 provided low-level APIs for reuse by other projects, but they didn't 445 reach that goal. Keeping these APIs public makes it more difficult to 446 improve websockets. 447 448 These changes pave the path for a refactoring that should be a transparent 449 upgrade for most uses and facilitate integration by other projects. 450 451 .. admonition:: Convenience imports from ``websockets`` are performed lazily. 452 :class: note 453 454 While Python supports this, tools relying on static code analysis don't. 455 This breaks auto-completion in an IDE or type checking with mypy_. 456 457 .. _mypy: https://github.com/python/mypy 458 459 If you depend on such tools, use the real import paths, which can be found 460 in the API documentation, for example:: 461 462 from websockets.client import connect 463 from websockets.server import serve 464 465 New features 466 ............ 467 468 * Added compatibility with Python 3.9. 469 470 Improvements 471 ............ 472 473 * Added support for IRIs in addition to URIs. 474 475 * Added close codes 1012, 1013, and 1014. 476 477 * Raised an error when passing a :class:`dict` to 478 :meth:`~legacy.protocol.WebSocketCommonProtocol.send`. 479 480 * Improved error reporting. 481 482 Bug fixes 483 ......... 484 485 * Fixed sending fragmented, compressed messages. 486 487 * Fixed ``Host`` header sent when connecting to an IPv6 address. 488 489 * Fixed creating a client or a server with an existing Unix socket. 490 491 * Aligned maximum cookie size with popular web browsers. 492 493 * Ensured cancellation always propagates, even on Python versions where 494 :exc:`~asyncio.CancelledError` inherits :exc:`Exception`. 495 496 8.1 497 --- 498 499 *November 1, 2019* 500 501 New features 502 ............ 503 504 * Added compatibility with Python 3.8. 505 506 8.0.2 507 ----- 508 509 *July 31, 2019* 510 511 Bug fixes 512 ......... 513 514 * Restored the ability to pass a socket with the ``sock`` parameter of 515 :func:`~server.serve`. 516 517 * Removed an incorrect assertion when a connection drops. 518 519 8.0.1 520 ----- 521 522 *July 21, 2019* 523 524 Bug fixes 525 ......... 526 527 * Restored the ability to import ``WebSocketProtocolError`` from 528 ``websockets``. 529 530 8.0 531 --- 532 533 *July 7, 2019* 534 535 Backwards-incompatible changes 536 .............................. 537 538 .. admonition:: websockets 8.0 requires Python ≥ 3.6. 539 :class: tip 540 541 websockets 7.0 is the last version supporting Python 3.4 and 3.5. 542 543 .. admonition:: ``process_request`` is now expected to be a coroutine. 544 :class: note 545 546 If you're passing a ``process_request`` argument to 547 :func:`~server.serve` or :class:`~server.WebSocketServerProtocol`, or if 548 you're overriding 549 :meth:`~server.WebSocketServerProtocol.process_request` in a subclass, 550 define it with ``async def`` instead of ``def``. Previously, both were supported. 551 552 For backwards compatibility, functions are still accepted, but mixing 553 functions and coroutines won't work in some inheritance scenarios. 554 555 .. admonition:: ``max_queue`` must be :obj:`None` to disable the limit. 556 :class: note 557 558 If you were setting ``max_queue=0`` to make the queue of incoming messages 559 unbounded, change it to ``max_queue=None``. 560 561 .. admonition:: The ``host``, ``port``, and ``secure`` attributes 562 of :class:`~legacy.protocol.WebSocketCommonProtocol` are deprecated. 563 :class: note 564 565 Use :attr:`~legacy.protocol.WebSocketCommonProtocol.local_address` in 566 servers and 567 :attr:`~legacy.protocol.WebSocketCommonProtocol.remote_address` in clients 568 instead of ``host`` and ``port``. 569 570 .. admonition:: ``WebSocketProtocolError`` is renamed 571 to :exc:`~exceptions.ProtocolError`. 572 :class: note 573 574 An alias provides backwards compatibility. 575 576 .. admonition:: ``read_response()`` now returns the reason phrase. 577 :class: note 578 579 If you're using this low-level API, you must change your code. 580 581 New features 582 ............ 583 584 * Added :func:`~auth.basic_auth_protocol_factory` to enforce HTTP 585 Basic Auth on the server side. 586 587 * :func:`~client.connect` handles redirects from the server during the 588 handshake. 589 590 * :func:`~client.connect` supports overriding ``host`` and ``port``. 591 592 * Added :func:`~client.unix_connect` for connecting to Unix sockets. 593 594 * Added support for asynchronous generators 595 in :meth:`~legacy.protocol.WebSocketCommonProtocol.send` 596 to generate fragmented messages incrementally. 597 598 * Enabled readline in the interactive client. 599 600 * Added type hints (:pep:`484`). 601 602 * Added a FAQ to the documentation. 603 604 * Added documentation for extensions. 605 606 * Documented how to optimize memory usage. 607 608 Improvements 609 ............ 610 611 * :meth:`~legacy.protocol.WebSocketCommonProtocol.send`, 612 :meth:`~legacy.protocol.WebSocketCommonProtocol.ping`, and 613 :meth:`~legacy.protocol.WebSocketCommonProtocol.pong` support bytes-like 614 types :class:`bytearray` and :class:`memoryview` in addition to 615 :class:`bytes`. 616 617 * Added :exc:`~exceptions.ConnectionClosedOK` and 618 :exc:`~exceptions.ConnectionClosedError` subclasses of 619 :exc:`~exceptions.ConnectionClosed` to tell apart normal connection 620 termination from errors. 621 622 * Changed :meth:`WebSocketServer.close() 623 <server.WebSocketServer.close>` to perform a proper closing handshake 624 instead of failing the connection. 625 626 * Improved error messages when HTTP parsing fails. 627 628 * Improved API documentation. 629 630 Bug fixes 631 ......... 632 633 * Prevented spurious log messages about :exc:`~exceptions.ConnectionClosed` 634 exceptions in keepalive ping task. If you were using ``ping_timeout=None`` 635 as a workaround, you can remove it. 636 637 * Avoided a crash when a ``extra_headers`` callable returns :obj:`None`. 638 639 7.0 640 --- 641 642 *November 1, 2018* 643 644 Backwards-incompatible changes 645 .............................. 646 647 .. admonition:: Keepalive is enabled by default. 648 :class: important 649 650 websockets now sends Ping frames at regular intervals and closes the 651 connection if it doesn't receive a matching Pong frame. 652 See :class:`~legacy.protocol.WebSocketCommonProtocol` for details. 653 654 .. admonition:: Termination of connections by :meth:`WebSocketServer.close() 655 <server.WebSocketServer.close>` changes. 656 :class: caution 657 658 Previously, connections handlers were canceled. Now, connections are 659 closed with close code 1001 (going away). 660 661 From the perspective of the connection handler, this is the same as if the 662 remote endpoint was disconnecting. This removes the need to prepare for 663 :exc:`~asyncio.CancelledError` in connection handlers. 664 665 You can restore the previous behavior by adding the following line at the 666 beginning of connection handlers:: 667 668 def handler(websocket, path): 669 closed = asyncio.ensure_future(websocket.wait_closed()) 670 closed.add_done_callback(lambda task: task.cancel()) 671 672 .. admonition:: Calling :meth:`~legacy.protocol.WebSocketCommonProtocol.recv` 673 concurrently raises a :exc:`RuntimeError`. 674 :class: note 675 676 Concurrent calls lead to non-deterministic behavior because there are no 677 guarantees about which coroutine will receive which message. 678 679 .. admonition:: The ``timeout`` argument of :func:`~server.serve` 680 and :func:`~client.connect` is renamed to ``close_timeout`` . 681 :class: note 682 683 This prevents confusion with ``ping_timeout``. 684 685 For backwards compatibility, ``timeout`` is still supported. 686 687 .. admonition:: The ``origins`` argument of :func:`~server.serve` changes. 688 :class: note 689 690 Include :obj:`None` in the list rather than ``''`` to allow requests that 691 don't contain an Origin header. 692 693 .. admonition:: Pending pings aren't canceled when the connection is closed. 694 :class: note 695 696 A ping — as in ``ping = await websocket.ping()`` — for which no pong was 697 received yet used to be canceled when the connection is closed, so that 698 ``await ping`` raised :exc:`~asyncio.CancelledError`. 699 700 Now ``await ping`` raises :exc:`~exceptions.ConnectionClosed` like other 701 public APIs. 702 703 New features 704 ............ 705 706 * Added ``process_request`` and ``select_subprotocol`` arguments to 707 :func:`~server.serve` and 708 :class:`~server.WebSocketServerProtocol` to facilitate customization of 709 :meth:`~server.WebSocketServerProtocol.process_request` and 710 :meth:`~server.WebSocketServerProtocol.select_subprotocol`. 711 712 * Added support for sending fragmented messages. 713 714 * Added the :meth:`~legacy.protocol.WebSocketCommonProtocol.wait_closed` 715 method to protocols. 716 717 * Added an interactive client: ``python -m websockets <uri>``. 718 719 Improvements 720 ............ 721 722 * Improved handling of multiple HTTP headers with the same name. 723 724 * Improved error messages when a required HTTP header is missing. 725 726 Bug fixes 727 ......... 728 729 * Fixed a data loss bug in 730 :meth:`~legacy.protocol.WebSocketCommonProtocol.recv`: 731 canceling it at the wrong time could result in messages being dropped. 732 733 6.0 734 --- 735 736 *July 16, 2018* 737 738 Backwards-incompatible changes 739 .............................. 740 741 .. admonition:: The :class:`~datastructures.Headers` class is introduced and 742 several APIs are updated to use it. 743 :class: caution 744 745 * The ``request_headers`` argument 746 of :meth:`~server.WebSocketServerProtocol.process_request` is now 747 a :class:`~datastructures.Headers` instead of 748 an ``http.client.HTTPMessage``. 749 750 * The ``request_headers`` and ``response_headers`` attributes of 751 :class:`~legacy.protocol.WebSocketCommonProtocol` are now 752 :class:`~datastructures.Headers` instead of ``http.client.HTTPMessage``. 753 754 * The ``raw_request_headers`` and ``raw_response_headers`` attributes of 755 :class:`~legacy.protocol.WebSocketCommonProtocol` are removed. Use 756 :meth:`~datastructures.Headers.raw_items` instead. 757 758 * Functions defined in the ``handshake`` module now receive 759 :class:`~datastructures.Headers` in argument instead of ``get_header`` 760 or ``set_header`` functions. This affects libraries that rely on 761 low-level APIs. 762 763 * Functions defined in the ``http`` module now return HTTP headers as 764 :class:`~datastructures.Headers` instead of lists of ``(name, value)`` 765 pairs. 766 767 Since :class:`~datastructures.Headers` and ``http.client.HTTPMessage`` 768 provide similar APIs, much of the code dealing with HTTP headers won't 769 require changes. 770 771 New features 772 ............ 773 774 * Added compatibility with Python 3.7. 775 776 5.0.1 777 ----- 778 779 *May 24, 2018* 780 781 Bug fixes 782 ......... 783 784 * Fixed a regression in 5.0 that broke some invocations of 785 :func:`~server.serve` and :func:`~client.connect`. 786 787 5.0 788 --- 789 790 *May 22, 2018* 791 792 Security fix 793 ............ 794 795 .. admonition:: websockets 5.0 fixes a security issue introduced in 4.0. 796 :class: important 797 798 Version 4.0 was vulnerable to denial of service by memory exhaustion 799 because it didn't enforce ``max_size`` when decompressing compressed 800 messages (`CVE-2018-1000518`_). 801 802 .. _CVE-2018-1000518: https://nvd.nist.gov/vuln/detail/CVE-2018-1000518 803 804 Backwards-incompatible changes 805 .............................. 806 807 .. admonition:: A ``user_info`` field is added to the return value of 808 ``parse_uri`` and ``WebSocketURI``. 809 :class: note 810 811 If you're unpacking ``WebSocketURI`` into four variables, adjust your code 812 to account for that fifth field. 813 814 New features 815 ............ 816 817 * :func:`~client.connect` performs HTTP Basic Auth when the URI contains 818 credentials. 819 820 * :func:`~server.unix_serve` can be used as an asynchronous context 821 manager on Python ≥ 3.5.1. 822 823 * Added the :attr:`~legacy.protocol.WebSocketCommonProtocol.closed` property 824 to protocols. 825 826 * Added new examples in the documentation. 827 828 Improvements 829 ............ 830 831 * Iterating on incoming messages no longer raises an exception when the 832 connection terminates with close code 1001 (going away). 833 834 * A plain HTTP request now receives a 426 Upgrade Required response and 835 doesn't log a stack trace. 836 837 * If a :meth:`~legacy.protocol.WebSocketCommonProtocol.ping` doesn't receive a 838 pong, it's canceled when the connection is closed. 839 840 * Reported the cause of :exc:`~exceptions.ConnectionClosed` exceptions. 841 842 * Stopped logging stack traces when the TCP connection dies prematurely. 843 844 * Prevented writing to a closing TCP connection during unclean shutdowns. 845 846 * Made connection termination more robust to network congestion. 847 848 * Prevented processing of incoming frames after failing the connection. 849 850 * Updated documentation with new features from Python 3.6. 851 852 * Improved several sections of the documentation. 853 854 Bug fixes 855 ......... 856 857 * Prevented :exc:`TypeError` due to missing close code on connection close. 858 859 * Fixed a race condition in the closing handshake that raised 860 :exc:`~exceptions.InvalidState`. 861 862 4.0.1 863 ----- 864 865 *November 2, 2017* 866 867 Bug fixes 868 ......... 869 870 * Fixed issues with the packaging of the 4.0 release. 871 872 4.0 873 --- 874 875 *November 2, 2017* 876 877 Backwards-incompatible changes 878 .............................. 879 880 .. admonition:: websockets 4.0 requires Python ≥ 3.4. 881 :class: tip 882 883 websockets 3.4 is the last version supporting Python 3.3. 884 885 .. admonition:: Compression is enabled by default. 886 :class: important 887 888 In August 2017, Firefox and Chrome support the permessage-deflate 889 extension, but not Safari and IE. 890 891 Compression should improve performance but it increases RAM and CPU use. 892 893 If you want to disable compression, add ``compression=None`` when calling 894 :func:`~server.serve` or :func:`~client.connect`. 895 896 .. admonition:: The ``state_name`` attribute of protocols is deprecated. 897 :class: note 898 899 Use ``protocol.state.name`` instead of ``protocol.state_name``. 900 901 New features 902 ............ 903 904 * :class:`~legacy.protocol.WebSocketCommonProtocol` instances can be used as 905 asynchronous iterators on Python ≥ 3.6. They yield incoming messages. 906 907 * Added :func:`~server.unix_serve` for listening on Unix sockets. 908 909 * Added the :attr:`~server.WebSocketServer.sockets` attribute to the 910 return value of :func:`~server.serve`. 911 912 * Allowed ``extra_headers`` to override ``Server`` and ``User-Agent`` headers. 913 914 Improvements 915 ............ 916 917 * Reorganized and extended documentation. 918 919 * Rewrote connection termination to increase robustness in edge cases. 920 921 * Reduced verbosity of "Failing the WebSocket connection" logs. 922 923 Bug fixes 924 ......... 925 926 * Aborted connections if they don't close within the configured ``timeout``. 927 928 * Stopped leaking pending tasks when :meth:`~asyncio.Task.cancel` is called on 929 a connection while it's being closed. 930 931 3.4 932 --- 933 934 *August 20, 2017* 935 936 Backwards-incompatible changes 937 .............................. 938 939 .. admonition:: ``InvalidStatus`` is replaced 940 by :class:`~exceptions.InvalidStatusCode`. 941 :class: note 942 943 This exception is raised when :func:`~client.connect` receives an invalid 944 response status code from the server. 945 946 New features 947 ............ 948 949 * :func:`~server.serve` can be used as an asynchronous context manager 950 on Python ≥ 3.5.1. 951 952 * Added support for customizing handling of incoming connections with 953 :meth:`~server.WebSocketServerProtocol.process_request`. 954 955 * Made read and write buffer sizes configurable. 956 957 Improvements 958 ............ 959 960 * Renamed :func:`~server.serve` and :func:`~client.connect`'s 961 ``klass`` argument to ``create_protocol`` to reflect that it can also be a 962 callable. For backwards compatibility, ``klass`` is still supported. 963 964 * Rewrote HTTP handling for simplicity and performance. 965 966 * Added an optional C extension to speed up low-level operations. 967 968 Bug fixes 969 ......... 970 971 * Providing a ``sock`` argument to :func:`~client.connect` no longer 972 crashes. 973 974 3.3 975 --- 976 977 *March 29, 2017* 978 979 New features 980 ............ 981 982 * Ensured compatibility with Python 3.6. 983 984 Improvements 985 ............ 986 987 * Reduced noise in logs caused by connection resets. 988 989 Bug fixes 990 ......... 991 992 * Avoided crashing on concurrent writes on slow connections. 993 994 3.2 995 --- 996 997 *August 17, 2016* 998 999 New features 1000 ............ 1001 1002 * Added ``timeout``, ``max_size``, and ``max_queue`` arguments to 1003 :func:`~client.connect` and :func:`~server.serve`. 1004 1005 Improvements 1006 ............ 1007 1008 * Made server shutdown more robust. 1009 1010 3.1 1011 --- 1012 1013 *April 21, 2016* 1014 1015 New features 1016 ............ 1017 1018 * Added flow control for incoming data. 1019 1020 Bug fixes 1021 ......... 1022 1023 * Avoided a warning when closing a connection before the opening handshake. 1024 1025 3.0 1026 --- 1027 1028 *December 25, 2015* 1029 1030 Backwards-incompatible changes 1031 .............................. 1032 1033 .. admonition:: :meth:`~legacy.protocol.WebSocketCommonProtocol.recv` now 1034 raises an exception when the connection is closed. 1035 :class: caution 1036 1037 :meth:`~legacy.protocol.WebSocketCommonProtocol.recv` used to return 1038 :obj:`None` when the connection was closed. This required checking the 1039 return value of every call:: 1040 1041 message = await websocket.recv() 1042 if message is None: 1043 return 1044 1045 Now it raises a :exc:`~exceptions.ConnectionClosed` exception instead. 1046 This is more Pythonic. The previous code can be simplified to:: 1047 1048 message = await websocket.recv() 1049 1050 When implementing a server, there's no strong reason to handle such 1051 exceptions. Let them bubble up, terminate the handler coroutine, and the 1052 server will simply ignore them. 1053 1054 In order to avoid stranding projects built upon an earlier version, the 1055 previous behavior can be restored by passing ``legacy_recv=True`` to 1056 :func:`~server.serve`, :func:`~client.connect`, 1057 :class:`~server.WebSocketServerProtocol`, or 1058 :class:`~client.WebSocketClientProtocol`. 1059 1060 New features 1061 ............ 1062 1063 * :func:`~client.connect` can be used as an asynchronous context 1064 manager on Python ≥ 3.5.1. 1065 1066 * :meth:`~legacy.protocol.WebSocketCommonProtocol.ping` and 1067 :meth:`~legacy.protocol.WebSocketCommonProtocol.pong` support data passed as 1068 :class:`str` in addition to :class:`bytes`. 1069 1070 * Made ``state_name`` attribute on protocols a public API. 1071 1072 Improvements 1073 ............ 1074 1075 * Updated documentation with ``await`` and ``async`` syntax from Python 3.5. 1076 1077 * Worked around an :mod:`asyncio` bug affecting connection termination under 1078 load. 1079 1080 * Improved documentation. 1081 1082 2.7 1083 --- 1084 1085 *November 18, 2015* 1086 1087 New features 1088 ............ 1089 1090 * Added compatibility with Python 3.5. 1091 1092 Improvements 1093 ............ 1094 1095 * Refreshed documentation. 1096 1097 2.6 1098 --- 1099 1100 *August 18, 2015* 1101 1102 New features 1103 ............ 1104 1105 * Added ``local_address`` and ``remote_address`` attributes on protocols. 1106 1107 * Closed open connections with code 1001 when a server shuts down. 1108 1109 Bug fixes 1110 ......... 1111 1112 * Avoided TCP fragmentation of small frames. 1113 1114 2.5 1115 --- 1116 1117 *July 28, 2015* 1118 1119 New features 1120 ............ 1121 1122 * Provided access to handshake request and response HTTP headers. 1123 1124 * Allowed customizing handshake request and response HTTP headers. 1125 1126 * Added support for running on a non-default event loop. 1127 1128 Improvements 1129 ............ 1130 1131 * Improved documentation. 1132 1133 * Sent a 403 status code instead of 400 when request Origin isn't allowed. 1134 1135 * Clarified that the closing handshake can be initiated by the client. 1136 1137 * Set the close code and reason more consistently. 1138 1139 * Strengthened connection termination. 1140 1141 Bug fixes 1142 ......... 1143 1144 * Canceling :meth:`~legacy.protocol.WebSocketCommonProtocol.recv` no longer 1145 drops the next message. 1146 1147 2.4 1148 --- 1149 1150 *January 31, 2015* 1151 1152 New features 1153 ............ 1154 1155 * Added support for subprotocols. 1156 1157 * Added ``loop`` argument to :func:`~client.connect` and 1158 :func:`~server.serve`. 1159 1160 2.3 1161 --- 1162 1163 *November 3, 2014* 1164 1165 Improvements 1166 ............ 1167 1168 * Improved compliance of close codes. 1169 1170 2.2 1171 --- 1172 1173 *July 28, 2014* 1174 1175 New features 1176 ............ 1177 1178 * Added support for limiting message size. 1179 1180 2.1 1181 --- 1182 1183 *April 26, 2014* 1184 1185 New features 1186 ............ 1187 1188 * Added ``host``, ``port`` and ``secure`` attributes on protocols. 1189 1190 * Added support for providing and checking Origin_. 1191 1192 .. _Origin: https://www.rfc-editor.org/rfc/rfc6455.html#section-10.2 1193 1194 2.0 1195 --- 1196 1197 *February 16, 2014* 1198 1199 Backwards-incompatible changes 1200 .............................. 1201 1202 .. admonition:: :meth:`~legacy.protocol.WebSocketCommonProtocol.send`, 1203 :meth:`~legacy.protocol.WebSocketCommonProtocol.ping`, and 1204 :meth:`~legacy.protocol.WebSocketCommonProtocol.pong` are now coroutines. 1205 :class: caution 1206 1207 They used to be functions. 1208 1209 Instead of:: 1210 1211 websocket.send(message) 1212 1213 you must write:: 1214 1215 await websocket.send(message) 1216 1217 New features 1218 ............ 1219 1220 * Added flow control for outgoing data. 1221 1222 1.0 1223 --- 1224 1225 *November 14, 2013* 1226 1227 New features 1228 ............ 1229 1230 * Initial public release.