websockets (16.0)
Installation
pip install --index-url About this package
An implementation of the WebSocket Protocol (RFC 6455 & 7692)
.. image:: logo/horizontal.svg :width: 480px :alt: websockets
|licence| |version| |pyversions| |tests| |docs| |openssf|
.. |licence| image:: https://img.shields.io/pypi/l/websockets.svg :target: https://pypi.python.org/pypi/websockets
.. |version| image:: https://img.shields.io/pypi/v/websockets.svg :target: https://pypi.python.org/pypi/websockets
.. |pyversions| image:: https://img.shields.io/pypi/pyversions/websockets.svg :target: https://pypi.python.org/pypi/websockets
.. |tests| image:: https://img.shields.io/github/checks-status/python-websockets/websockets/main?label=tests :target: https://github.com/python-websockets/websockets/actions/workflows/tests.yml
.. |docs| image:: https://img.shields.io/readthedocs/websockets.svg :target: https://websockets.readthedocs.io/
.. |openssf| image:: https://bestpractices.coreinfrastructure.org/projects/6475/badge :target: https://bestpractices.coreinfrastructure.org/projects/6475
What is websockets?
websockets is a library for building WebSocket_ servers and clients in Python with a focus on correctness, simplicity, robustness, and performance.
.. _WebSocket: https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API
Built on top of asyncio, Python's standard asynchronous I/O framework, the
default implementation provides an elegant coroutine-based API.
An implementation on top of threading and a Sans-I/O implementation are also
available.
Documentation is available on Read the Docs. <https://websockets.readthedocs.io/>_
.. copy-pasted because GitHub doesn't support the include directive
Here's an echo server with the asyncio API:
.. code:: python
#!/usr/bin/env python
import asyncio
from websockets.asyncio.server import serve
async def echo(websocket):
async for message in websocket:
await websocket.send(message)
async def main():
async with serve(echo, "localhost", 8765) as server:
await server.serve_forever()
asyncio.run(main())
Here's how a client sends and receives messages with the threading API:
.. code:: python
#!/usr/bin/env python
from websockets.sync.client import connect
def hello():
with connect("ws://localhost:8765") as websocket:
websocket.send("Hello world!")
message = websocket.recv()
print(f"Received: {message}")
hello()
Does that look good?
Get started with the tutorial! <https://websockets.readthedocs.io/en/stable/intro/index.html>_
Why should I use websockets?
The development of websockets is shaped by four principles:
-
Correctness:
websocketsis heavily tested for compliance with :rfc:6455. Continuous integration fails under 100% branch coverage. -
Simplicity: all you need to understand is
msg = await ws.recv()andawait ws.send(msg).websocketstakes care of managing connections so you can focus on your application. -
Robustness:
websocketsis built for production. For example, it was the only library tohandle backpressure correctly_ before the issue became widely known in the Python community. -
Performance: memory usage is optimized and configurable. A C extension accelerates expensive operations. It's pre-compiled for Linux, macOS and Windows and packaged in the wheel format for each system and Python version.
Documentation is a first class concern in the project. Head over to Read the Docs_ and see for yourself.
.. _Read the Docs: https://websockets.readthedocs.io/ .. _handle backpressure correctly: https://vorpus.org/blog/some-thoughts-on-asynchronous-api-design-in-a-post-asyncawait-world/#websocket-servers
Why shouldn't I use websockets?
-
If you prefer callbacks over coroutines:
websocketswas created to provide the best coroutine-based API to manage WebSocket connections in Python. Pick another library for a callback-based API. -
If you're looking for a mixed HTTP / WebSocket library:
websocketsaims at being an excellent implementation of :rfc:6455: The WebSocket Protocol and :rfc:7692: Compression Extensions for WebSocket. Its support for HTTP is minimal — just enough for an HTTP health check.If you want to do both in the same server, look at HTTP + WebSocket servers that build on top of
websocketsto support WebSocket connections, like uvicorn_ or Sanic_.
.. _uvicorn: https://www.uvicorn.org/ .. _Sanic: https://sanic.dev/en/
What else?
Bug reports, patches and suggestions are welcome!
To report a security vulnerability, please use the Tidelift security contact_. Tidelift will coordinate the fix and disclosure.
.. _Tidelift security contact: https://tidelift.com/security
For anything else, please open an issue_ or send a pull request_.
.. _issue: https://github.com/python-websockets/websockets/issues/new .. _pull request: https://github.com/python-websockets/websockets/compare/
Participants must uphold the Contributor Covenant code of conduct_.
.. _Contributor Covenant code of conduct: https://github.com/python-websockets/websockets/blob/main/CODE_OF_CONDUCT.md
websockets is released under the BSD license_.
.. _BSD license: https://github.com/python-websockets/websockets/blob/main/LICENSE