\n\n\n---\n\nEasy WebSocket component for API Star and Uvicorn.\n\n* [Features](#features)\n* [Install](#install)\n* [Examples](#examples)\n * [Uvicorn](#uvicorn)\n* [Issues](#issues)\n\n---\n\n## Features\n\n### It's Easy to use\n\nSimply use it like any other component on a route handler that will accept WebSocket\nconnections\n\n```python\n# With WebSocketAutoHook in event_hooks is the easiest usage,\n# but see the Issues below about using WebSocketAutoHook\nasync def ws_handler(ws: WebSocket):\n inbound_msg = await ws.recv()\n ...\n await ws.send(outbound_msg)\n\n# Without the WebSocketAutoHook\nasync def ws_handler(ws: WebSocket):\n await ws.connect()\n inbound_msg = await ws.recv()\n ...\n await ws.send(outbound_msg)\n await ws.close()\n```\n\n### Auto connecting and closing event hook.\n\nWhen used with the `WebSocketAutoHook` the WebSocket will be connected before the handler\nis called. When the handler returns or is ended due to error the WebSocket will be automatically\nclosed. See the [Issues](#issues) below concerning `WebSocketAutoHook`.\n\n## Install\n\n pip install apistar-websocket\n\nor for [Pipenv](https://docs.pipenv.org/) users\n\n pipenv install apistar-websocket\n\n\n## Examples\n\nHere's a basic example of sending 100 numbers to the connected client and waiting\nfor a return message after each send. The WebSocket is connected and closed for us\nby the `WebSocketAutoHook`.\n\n```python\nimport json\nfrom apistar import ASyncApp, Route\nfrom websocket import WebSocket, WebSocketComponent, WebSocketAutoHook\n\n\nasync def welcome_ws(path: str, ws: WebSocket):\n \"\"\"\n A WebSocket endpoint used to play a terrible game of data ping pong.\n \"\"\"\n for i in range(100):\n await ws.send(\n json.dumps({\n \"msg\": f\"{path} is nice\",\n \"count\": i,\n })\n )\n\n # We'll pretend we're playing ping pong\n msg = await ws.receive()\n\nroutes = [\n Route('/{+path}', 'GET', handler=welcome_ws, name='welcome_ws'),\n]\n\nevent_hooks = [WebSocketAutoHook]\ncomponents = [WebSocketComponent()]\n\napp = ASyncApp(\n routes=routes,\n components=components,\n event_hooks=event_hooks,\n)\n\n\nif __name__ == '__main__':\n main()\n```\n\nSame example as above, but without using the `WebSocketAutoHook`. Here the handler\nmust manage the WebSocket connection itself and run as a standalone `Route` to prevent\nAPI Star from sending responses to the client.\n```python\nimport json\nfrom apistar import ASyncApp, Route\nfrom websocket import WebSocket, WebSocketComponent\n\n\nasync def welcome_ws(path: str, ws: WebSocket):\n \"\"\"\n A WebSocket endpoint used to subscribe to a stream of data.\n \"\"\"\n\n # finish the connection\n await.connect()\n\n for i in range(100):\n await ws.send(\n json.dumps({\n \"msg\": f\"{path} is nice\",\n \"count\": i,\n })\n )\n\n # We'll pretend we're playing ping pong\n msg = await ws.receive()\n\n # close the connection\n await ws.close()\n\n# Must run the route standalone to prevent the attempt at an HTTP Response being sent\nroutes = [\n Route('/{+path}', 'GET', handler=welcome_ws, name='welcome_ws', standalone=True),\n]\n\ncomponents = [WebSocketComponent()]\n\napp = ASyncApp(\n routes=routes,\n components=components,\n)\n\n\nif __name__ == '__main__':\n main()\n```\n\n## Uvicorn\nYou have to run your API Star with Uvicorn for `apistar-websocket` to work.\n\nTo run you app with debug on and automatically reloading the app on file changes,\ngreat for development, use:\n\n uvicorn --log-level DEBUG --reload app:app\n\nFor a production environment start from the command:\n\n uvicorn app:app\n\nAnd adjust as needed, see `uvicorn --help` for more options.\n\n## Issues\n\nThe cleanest way to use the component is without the `WebSocketAutoHook` and as a standalone\nroute with the handler connecting and closing the WebSocket. This is because when a handler is\n_not_ used as a standalone route, the default, API Star will send an HTTP response after a handler\nhas finished. While this needed for regular HTTP requests, it is not for\nWebSocket connections as they are already closed. You can use the `WebSocketAutoHook`\nand your handlers will function as you expect.\nBut to prevent API Star from sending the HTTP response\n`WebSocketAutoHook` will raise an exception after closing the WebSocket to prevent the HTTP\nresponse causing an error condition in API Star.",
"description_content_type": "text/markdown",
"docs_url": null,
"download_url": "",
"downloads": {
"last_day": -1,
"last_month": -1,
"last_week": -1
},
"home_page": "https://github.com/jeffbuttars/apistar-websocket",
"keywords": "",
"license": "Apache License 2.0",
"maintainer": "",
"maintainer_email": "",
"name": "apistar-websocket",
"package_url": "https://pypi.org/project/apistar-websocket/",
"platform": "",
"project_url": "https://pypi.org/project/apistar-websocket/",
"project_urls": {
"Homepage": "https://github.com/jeffbuttars/apistar-websocket"
},
"release_url": "https://pypi.org/project/apistar-websocket/0.1.2/",
"requires_dist": null,
"requires_python": "",
"summary": "WebSocket Component for API Star",
"version": "0.1.2"
},
"last_serial": 3915067,
"releases": {
"0.1.0": [
{
"comment_text": "",
"digests": {
"md5": "ce12a050eb043a3281b88b2414fafe3f",
"sha256": "e5f2af041510dfe8823a3beeb62040e458c8de68d1e91298db38e7ba032464e5"
},
"downloads": -1,
"filename": "apistar-websocket-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "ce12a050eb043a3281b88b2414fafe3f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 3484,
"upload_time": "2018-05-30T02:36:44",
"url": "https://files.pythonhosted.org/packages/26/f5/2d076eb492edef0a87a764eb01dad47fc65e0b23dff36189b47d5bc0e87a/apistar-websocket-0.1.0.tar.gz"
}
],
"0.1.1": [
{
"comment_text": "",
"digests": {
"md5": "1af712bb01308e71f50e75efdcc5d70c",
"sha256": "36d72d77698861d125f2065c8a579154a189acb703a57523a23ab44e77651642"
},
"downloads": -1,
"filename": "apistar-websocket-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "1af712bb01308e71f50e75efdcc5d70c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6044,
"upload_time": "2018-05-30T02:47:27",
"url": "https://files.pythonhosted.org/packages/3c/67/58ccff609a958eedf36cc461b92a67003ace97caa1426e90fa521388d0ba/apistar-websocket-0.1.1.tar.gz"
}
],
"0.1.2": [
{
"comment_text": "",
"digests": {
"md5": "7c77c2e625b17a006ad513e64345236a",
"sha256": "272bdcd598f54faa0677be6c889e3d2dda34a6b5b80a95444d95d56745dffe97"
},
"downloads": -1,
"filename": "apistar-websocket-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "7c77c2e625b17a006ad513e64345236a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5987,
"upload_time": "2018-05-30T23:12:19",
"url": "https://files.pythonhosted.org/packages/39/fe/653919c332c9de2296dcd8fb835924e0d7ece0fa608b64bf360bb0cb3d71/apistar-websocket-0.1.2.tar.gz"
}
]
},
"urls": [
{
"comment_text": "",
"digests": {
"md5": "7c77c2e625b17a006ad513e64345236a",
"sha256": "272bdcd598f54faa0677be6c889e3d2dda34a6b5b80a95444d95d56745dffe97"
},
"downloads": -1,
"filename": "apistar-websocket-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "7c77c2e625b17a006ad513e64345236a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5987,
"upload_time": "2018-05-30T23:12:19",
"url": "https://files.pythonhosted.org/packages/39/fe/653919c332c9de2296dcd8fb835924e0d7ece0fa608b64bf360bb0cb3d71/apistar-websocket-0.1.2.tar.gz"
}
]
}
![\"PyPI](\"https://badge.fury.io/py/apistar-websocket.svg\"){kind=icon}
\n \n