# Trio WebSocket
This library implements both server and client aspects of the [the WebSocket
protocol](https://tools.ietf.org/html/rfc6455), striving for safety,
correctness, and ergonomics. It is based on the [wsproto
project](https://wsproto.readthedocs.io/en/latest/), which is a
[Sans-IO](https://sans-io.readthedocs.io/) state machine that implements the
majority of the WebSocket protocol, including framing, codecs, and events. This
library handles I/O using [the Trio
framework](https://trio.readthedocs.io/en/latest/). This library passes the
[Autobahn Test Suite](https://github.com/crossbario/autobahn-testsuite).
This README contains a brief introduction to the project. Full documentation [is
available here](https://trio-websocket.readthedocs.io).
[](https://pypi.org/project/trio-websocket/)
[](https://github.com/python-trio/trio-websocket/actions/workflows/ci.yml)
[](https://trio-websocket.readthedocs.io)
[](https://gitter.im/python-trio/general)
## Status
**This project is on life-support maintenance.** If you're interested in helping to maintain and contribute, please reach out on [Gitter](https://gitter.im/python-trio/general) or contribute in issues and pull requests.
## Alternatives
If you happen to only need a server, using Quart via the [quart-trio](https://github.com/pgjones/quart-trio)
extension may suffice. While trio-websocket is more flexible, Quart covers
both HTTP and WebSocket within a single framework, and serving both from the
same port is straightforward. There has yet to be a performance comparison.
## Installation
This library requires Python 3.8 or greater. To install from PyPI:
pip install trio-websocket
## Client Example
This example demonstrates how to open a WebSocket URL:
```python
import trio
from sys import stderr
from trio_websocket import open_websocket_url
async def main():
try:
async with open_websocket_url('wss://echo.websocket.org') as ws:
await ws.send_message('hello world!')
message = await ws.get_message()
print('Received message: %s' % message)
except OSError as ose:
print('Connection attempt failed: %s' % ose, file=stderr)
trio.run(main)
```
The WebSocket context manager connects automatically before entering the block
and disconnects automatically before exiting the block. The full API offers a
lot of flexibility and additional options.
## Server Example
A WebSocket server requires a bind address, a port, and a coroutine to handle
incoming connections. This example demonstrates an "echo server" that replies to
each incoming message with an identical outgoing message.
```python
import trio
from trio_websocket import serve_websocket, ConnectionClosed
async def echo_server(request):
ws = await request.accept()
while True:
try:
message = await ws.get_message()
await ws.send_message(message)
except ConnectionClosed:
break
async def main():
await serve_websocket(echo_server, '127.0.0.1', 8000, ssl_context=None)
trio.run(main)
```
The server's handler ``echo_server(…)`` receives a connection request object.
This object can be used to inspect the client's request and modify the
handshake, then it can be exchanged for an actual WebSocket object ``ws``.
Again, the full API offers a lot of flexibility and additional options.
Raw data
{
"_id": null,
"home_page": "https://github.com/python-trio/trio-websocket",
"name": "trio-websocket",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "websocket client server trio",
"author": "Mark E. Haase",
"author_email": "mehaase@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/8d/ba/ab932f5f520565caf948ccadade04f82daa33272b9629b7bc71fd1bb1a63/trio_websocket-0.12.1.tar.gz",
"platform": null,
"description": "# Trio WebSocket\n\nThis library implements both server and client aspects of the [the WebSocket\nprotocol](https://tools.ietf.org/html/rfc6455), striving for safety,\ncorrectness, and ergonomics. It is based on the [wsproto\nproject](https://wsproto.readthedocs.io/en/latest/), which is a\n[Sans-IO](https://sans-io.readthedocs.io/) state machine that implements the\nmajority of the WebSocket protocol, including framing, codecs, and events. This\nlibrary handles I/O using [the Trio\nframework](https://trio.readthedocs.io/en/latest/). This library passes the\n[Autobahn Test Suite](https://github.com/crossbario/autobahn-testsuite).\n\nThis README contains a brief introduction to the project. Full documentation [is\navailable here](https://trio-websocket.readthedocs.io).\n\n[](https://pypi.org/project/trio-websocket/)\n\n[](https://github.com/python-trio/trio-websocket/actions/workflows/ci.yml)\n[](https://trio-websocket.readthedocs.io)\n[](https://gitter.im/python-trio/general)\n\n## Status\n**This project is on life-support maintenance.** If you're interested in helping to maintain and contribute, please reach out on [Gitter](https://gitter.im/python-trio/general) or contribute in issues and pull requests.\n\n## Alternatives\n\nIf you happen to only need a server, using Quart via the [quart-trio](https://github.com/pgjones/quart-trio)\nextension may suffice. While trio-websocket is more flexible, Quart covers\nboth HTTP and WebSocket within a single framework, and serving both from the\nsame port is straightforward. There has yet to be a performance comparison.\n\n## Installation\n\nThis library requires Python 3.8 or greater. To install from PyPI:\n\n pip install trio-websocket\n\n## Client Example\n\nThis example demonstrates how to open a WebSocket URL:\n\n```python\nimport trio\nfrom sys import stderr\nfrom trio_websocket import open_websocket_url\n\n\nasync def main():\n try:\n async with open_websocket_url('wss://echo.websocket.org') as ws:\n await ws.send_message('hello world!')\n message = await ws.get_message()\n print('Received message: %s' % message)\n except OSError as ose:\n print('Connection attempt failed: %s' % ose, file=stderr)\n\ntrio.run(main)\n```\n\nThe WebSocket context manager connects automatically before entering the block\nand disconnects automatically before exiting the block. The full API offers a\nlot of flexibility and additional options.\n\n## Server Example\n\nA WebSocket server requires a bind address, a port, and a coroutine to handle\nincoming connections. This example demonstrates an \"echo server\" that replies to\neach incoming message with an identical outgoing message.\n\n```python\nimport trio\nfrom trio_websocket import serve_websocket, ConnectionClosed\n\nasync def echo_server(request):\n ws = await request.accept()\n while True:\n try:\n message = await ws.get_message()\n await ws.send_message(message)\n except ConnectionClosed:\n break\n\nasync def main():\n await serve_websocket(echo_server, '127.0.0.1', 8000, ssl_context=None)\n\ntrio.run(main)\n```\n\nThe server's handler ``echo_server(\u2026)`` receives a connection request object.\nThis object can be used to inspect the client's request and modify the\nhandshake, then it can be exchanged for an actual WebSocket object ``ws``.\nAgain, the full API offers a lot of flexibility and additional options.\n",
"bugtrack_url": null,
"license": null,
"summary": "WebSocket library for Trio",
"version": "0.12.1",
"project_urls": {
"Bug Reports": "https://github.com/python-trio/trio-websocket/issues",
"Homepage": "https://github.com/python-trio/trio-websocket",
"Source": "https://github.com/python-trio/trio-websocket"
},
"split_keywords": [
"websocket",
"client",
"server",
"trio"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d3b9b07ec357ba125ad26e1c07781b9d7f0414af85ad76e0d73617ddb5ce041c",
"md5": "5058b216350fa40c46fca8403858692f",
"sha256": "608ec746bb287e5d5a66baf483e41194193c5cf05ffaad6240e7d1fcd80d1e6f"
},
"downloads": -1,
"filename": "trio_websocket-0.12.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5058b216350fa40c46fca8403858692f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 21216,
"upload_time": "2025-02-17T21:13:30",
"upload_time_iso_8601": "2025-02-17T21:13:30.286235Z",
"url": "https://files.pythonhosted.org/packages/d3/b9/b07ec357ba125ad26e1c07781b9d7f0414af85ad76e0d73617ddb5ce041c/trio_websocket-0.12.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8dbaab932f5f520565caf948ccadade04f82daa33272b9629b7bc71fd1bb1a63",
"md5": "073028afe0f6a22c947e98cecccc2a96",
"sha256": "d55ccd4d3eae27c494f3fdae14823317839bdcb8214d1173eacc4d42c69fc91b"
},
"downloads": -1,
"filename": "trio_websocket-0.12.1.tar.gz",
"has_sig": false,
"md5_digest": "073028afe0f6a22c947e98cecccc2a96",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 33547,
"upload_time": "2025-02-17T21:13:32",
"upload_time_iso_8601": "2025-02-17T21:13:32.306192Z",
"url": "https://files.pythonhosted.org/packages/8d/ba/ab932f5f520565caf948ccadade04f82daa33272b9629b7bc71fd1bb1a63/trio_websocket-0.12.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-17 21:13:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "python-trio",
"github_project": "trio-websocket",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "trio-websocket"
}
JSON
