| single |
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.
`_
.. 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!
`_
Why should I use websockets?
--------------------------------
The development of websockets is shaped by four principles:
1. **Correctness**: websockets is heavily tested for compliance with
:rfc:`6455`. Continuous integration fails under 100% branch coverage.
2. **Simplicity**: all you need to understand is ``msg = await ws.recv()
and
await ws.send(msg)``. websockets takes care of managing connections
so you can focus on your application.
3. **Robustness**: websockets is built for production. For example, it was
the only library to `handle backpressure correctly`_ before the issue
became widely known in the Python community.
4. **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: websockets was created to
provide the best coroutine-based API to manage WebSocket connections in
|