README.rst (6340B)
1 .. image:: logo/horizontal.svg 2 :width: 480px 3 :alt: websockets 4 5 |licence| |version| |pyversions| |tests| |docs| |openssf| 6 7 .. |licence| image:: https://img.shields.io/pypi/l/websockets.svg 8 :target: https://pypi.python.org/pypi/websockets 9 10 .. |version| image:: https://img.shields.io/pypi/v/websockets.svg 11 :target: https://pypi.python.org/pypi/websockets 12 13 .. |pyversions| image:: https://img.shields.io/pypi/pyversions/websockets.svg 14 :target: https://pypi.python.org/pypi/websockets 15 16 .. |tests| image:: https://img.shields.io/github/checks-status/python-websockets/websockets/main?label=tests 17 :target: https://github.com/python-websockets/websockets/actions/workflows/tests.yml 18 19 .. |docs| image:: https://img.shields.io/readthedocs/websockets.svg 20 :target: https://websockets.readthedocs.io/ 21 22 .. |openssf| image:: https://bestpractices.coreinfrastructure.org/projects/6475/badge 23 :target: https://bestpractices.coreinfrastructure.org/projects/6475 24 25 What is ``websockets``? 26 ----------------------- 27 28 websockets is a library for building WebSocket_ servers and clients in Python 29 with a focus on correctness, simplicity, robustness, and performance. 30 31 .. _WebSocket: https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API 32 33 Built on top of ``asyncio``, Python's standard asynchronous I/O framework, the 34 default implementation provides an elegant coroutine-based API. 35 36 An implementation on top of ``threading`` and a Sans-I/O implementation are also 37 available. 38 39 `Documentation is available on Read the Docs. <https://websockets.readthedocs.io/>`_ 40 41 .. copy-pasted because GitHub doesn't support the include directive 42 43 Here's an echo server with the ``asyncio`` API: 44 45 .. code:: python 46 47 #!/usr/bin/env python 48 49 import asyncio 50 from websockets.server import serve 51 52 async def echo(websocket): 53 async for message in websocket: 54 await websocket.send(message) 55 56 async def main(): 57 async with serve(echo, "localhost", 8765): 58 await asyncio.Future() # run forever 59 60 asyncio.run(main()) 61 62 Here's how a client sends and receives messages with the ``threading`` API: 63 64 .. code:: python 65 66 #!/usr/bin/env python 67 68 from websockets.sync.client import connect 69 70 def hello(): 71 with connect("ws://localhost:8765") as websocket: 72 websocket.send("Hello world!") 73 message = websocket.recv() 74 print(f"Received: {message}") 75 76 hello() 77 78 79 Does that look good? 80 81 `Get started with the tutorial! <https://websockets.readthedocs.io/en/stable/intro/index.html>`_ 82 83 .. raw:: html 84 85 <hr> 86 <img align="left" height="150" width="150" src="https://raw.githubusercontent.com/python-websockets/websockets/main/logo/tidelift.png"> 87 <h3 align="center"><i>websockets for enterprise</i></h3> 88 <p align="center"><i>Available as part of the Tidelift Subscription</i></p> 89 <p align="center"><i>The maintainers of websockets and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. <a href="https://tidelift.com/subscription/pkg/pypi-websockets?utm_source=pypi-websockets&utm_medium=referral&utm_campaign=readme">Learn more.</a></i></p> 90 <hr> 91 <p>(If you contribute to <code>websockets</code> and would like to become an official support provider, <a href="https://fractalideas.com/">let me know</a>.)</p> 92 93 Why should I use ``websockets``? 94 -------------------------------- 95 96 The development of ``websockets`` is shaped by four principles: 97 98 1. **Correctness**: ``websockets`` is heavily tested for compliance with 99 :rfc:`6455`. Continuous integration fails under 100% branch coverage. 100 101 2. **Simplicity**: all you need to understand is ``msg = await ws.recv()`` and 102 ``await ws.send(msg)``. ``websockets`` takes care of managing connections 103 so you can focus on your application. 104 105 3. **Robustness**: ``websockets`` is built for production. For example, it was 106 the only library to `handle backpressure correctly`_ before the issue 107 became widely known in the Python community. 108 109 4. **Performance**: memory usage is optimized and configurable. A C extension 110 accelerates expensive operations. It's pre-compiled for Linux, macOS and 111 Windows and packaged in the wheel format for each system and Python version. 112 113 Documentation is a first class concern in the project. Head over to `Read the 114 Docs`_ and see for yourself. 115 116 .. _Read the Docs: https://websockets.readthedocs.io/ 117 .. _handle backpressure correctly: https://vorpus.org/blog/some-thoughts-on-asynchronous-api-design-in-a-post-asyncawait-world/#websocket-servers 118 119 Why shouldn't I use ``websockets``? 120 ----------------------------------- 121 122 * If you prefer callbacks over coroutines: ``websockets`` was created to 123 provide the best coroutine-based API to manage WebSocket connections in 124 Python. Pick another library for a callback-based API. 125 126 * If you're looking for a mixed HTTP / WebSocket library: ``websockets`` aims 127 at being an excellent implementation of :rfc:`6455`: The WebSocket Protocol 128 and :rfc:`7692`: Compression Extensions for WebSocket. Its support for HTTP 129 is minimal — just enough for an HTTP health check. 130 131 If you want to do both in the same server, look at HTTP frameworks that 132 build on top of ``websockets`` to support WebSocket connections, like 133 Sanic_. 134 135 .. _Sanic: https://sanicframework.org/en/ 136 137 What else? 138 ---------- 139 140 Bug reports, patches and suggestions are welcome! 141 142 To report a security vulnerability, please use the `Tidelift security 143 contact`_. Tidelift will coordinate the fix and disclosure. 144 145 .. _Tidelift security contact: https://tidelift.com/security 146 147 For anything else, please open an issue_ or send a `pull request`_. 148 149 .. _issue: https://github.com/python-websockets/websockets/issues/new 150 .. _pull request: https://github.com/python-websockets/websockets/compare/ 151 152 Participants must uphold the `Contributor Covenant code of conduct`_. 153 154 .. _Contributor Covenant code of conduct: https://github.com/python-websockets/websockets/blob/main/CODE_OF_CONDUCT.md 155 156 ``websockets`` is released under the `BSD license`_. 157 158 .. _BSD license: https://github.com/python-websockets/websockets/blob/main/LICENSE