# 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)
## 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.7 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": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "websocket client server trio",
"author": "Mark E. Haase",
"author_email": "mehaase@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/dd/36/abad2385853077424a11b818d9fd8350d249d9e31d583cb9c11cd4c85eda/trio-websocket-0.11.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\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.7 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": "",
"summary": "WebSocket library for Trio",
"version": "0.11.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": "",
"digests": {
"blake2b_256": "48bea9ae5f50cad5b6f85bd2574c2c923730098530096e170c1ce7452394d7aa",
"md5": "8695c0aa11845c6fbf4b06b16bb6dc93",
"sha256": "520d046b0d030cf970b8b2b2e00c4c2245b3807853ecd44214acd33d74581638"
},
"downloads": -1,
"filename": "trio_websocket-0.11.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8695c0aa11845c6fbf4b06b16bb6dc93",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 17408,
"upload_time": "2023-09-26T23:24:56",
"upload_time_iso_8601": "2023-09-26T23:24:56.788137Z",
"url": "https://files.pythonhosted.org/packages/48/be/a9ae5f50cad5b6f85bd2574c2c923730098530096e170c1ce7452394d7aa/trio_websocket-0.11.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dd36abad2385853077424a11b818d9fd8350d249d9e31d583cb9c11cd4c85eda",
"md5": "3d9bb51b62f562dbdbc2ec067132c4a6",
"sha256": "18c11793647703c158b1f6e62de638acada927344d534e3c7628eedcb746839f"
},
"downloads": -1,
"filename": "trio-websocket-0.11.1.tar.gz",
"has_sig": false,
"md5_digest": "3d9bb51b62f562dbdbc2ec067132c4a6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 26511,
"upload_time": "2023-09-26T23:24:58",
"upload_time_iso_8601": "2023-09-26T23:24:58.753986Z",
"url": "https://files.pythonhosted.org/packages/dd/36/abad2385853077424a11b818d9fd8350d249d9e31d583cb9c11cd4c85eda/trio-websocket-0.11.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-26 23:24:58",
"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
