<p align="center">
<img src="https://i.ibb.co/m8jL6Zd/RPC.png" alt="RPC" border="0" width="50%" />
</p>
#
# ⚡ FASTAPI Websocket RPC
RPC over Websockets made easy, robust, and production ready
<a href="https://github.com/permitio/fastapi_websocket_rpc/actions?query=workflow%3ATests" target="_blank">
<img src="https://github.com/permitio/fastapi_websocket_rpc/workflows/Tests/badge.svg" alt="Tests">
</a>
<a href="https://pypi.org/project/fastapi-websocket-rpc/" target="_blank">
<img src="https://img.shields.io/pypi/v/fastapi-websocket-rpc?color=%2331C654&label=PyPi%20package" alt="Package">
</a>
<a href="https://pepy.tech/project/fastapi-websocket-rpc" target="_blank">
<img src="https://static.pepy.tech/personalized-badge/fastapi-websocket-rpc?period=total&units=international_system&left_color=black&right_color=blue&left_text=Downloads" alt="Downloads">
</a>
A fast and durable bidirectional JSON RPC channel over Websockets.
The easiest way to create a live async channel between two nodes via Python (or other clients).
- Both server and clients can easily expose Python methods that can be called by the other side.
Method return values are sent back as RPC responses, which the other side can wait on.
- Remote methods are easily called via the ```.other.method()``` wrapper
- Connections are kept alive with a configurable retry mechanism (using Tenacity)
- As seen at <a href="https://www.youtube.com/watch?v=KP7tPeKhT3o" target="_blank">PyCon IL 2021</a> and <a href="https://www.youtube.com/watch?v=IuMZVWEUvGs" target="_blank">EuroPython 2021</a>
Supports and tested on Python >= 3.7
## Installation 🛠️
```
pip install fastapi_websocket_rpc
```
## RPC call example:
Say the server exposes an "add" method, e.g. :
```python
class RpcCalculator(RpcMethodsBase):
async def add(self, a, b):
return a + b
```
Calling it is as easy as calling the method under the client's "other" property:
```python
response = await client.other.add(a=1,b=2)
print(response.result) # 3
```
getting the response with the return value.
## Usage example:
### Server:
```python
import uvicorn
from fastapi import FastAPI
from fastapi_websocket_rpc import RpcMethodsBase, WebsocketRPCEndpoint
# Methods to expose to the clients
class ConcatServer(RpcMethodsBase):
async def concat(self, a="", b=""):
return a + b
# Init the FAST-API app
app = FastAPI()
# Create an endpoint and load it with the methods to expose
endpoint = WebsocketRPCEndpoint(ConcatServer())
# add the endpoint to the app
endpoint.register_route(app, "/ws")
# Start the server itself
uvicorn.run(app, host="0.0.0.0", port=9000)
```
### Client
```python
import asyncio
from fastapi_websocket_rpc import RpcMethodsBase, WebSocketRpcClient
async def run_client(uri):
async with WebSocketRpcClient(uri, RpcMethodsBase()) as client:
# call concat on the other side
response = await client.other.concat(a="hello", b=" world")
# print result
print(response.result) # will print "hello world"
# run the client until it completes interaction with server
asyncio.get_event_loop().run_until_complete(
run_client("ws://localhost:9000/ws")
)
```
See the [examples](/examples) and [tests](/tests) folders for more server and client examples
## Server calling client example:
- Clients can call ```client.other.method()```
- which is a shortcut for ```channel.other.method()```
- Servers also get the channel object and can call remote methods via ```channel.other.method()```
- See the [bidirectional call example](examples/bidirectional_server_example.py) for calling client from server and server events (e.g. ```on_connect```).
## What can I do with this?
Websockets are ideal to create bi-directional realtime connections over the web.
- Push updates
- Remote control mechanism
- Pub / Sub (see [fastapi_websocket_pubsub](https://github.com/permitio/fastapi_websocket_pubsub))
- Trigger events (see "tests/trigger_flow_test.py")
- Node negotiations (see "tests/advanced_rpc_test.py :: test_recursive_rpc_calls")
## Concepts
- [RpcChannel](fastapi_websocket_rpc/rpc_channel.py) - implements the RPC-protocol over the websocket
- Sending RpcRequests per method call
- Creating promises to track them (via unique call ids), and allow waiting for responses
- Executing methods on the remote side and serializing return values as
- Receiving RpcResponses and delivering them to waiting callers
- [RpcMethods](fastapi_websocket_rpc/rpc_methods.py) - classes passed to both client and server-endpoint inits to expose callable methods to the other side.
- Simply derive from RpcMethodsBase and add your own async methods
- Note currently only key-word arguments are supported
- Checkout RpcUtilityMethods for example methods, which are also useful debugging utilities
- Foundations:
- Based on [asyncio](https://docs.python.org/3/library/asyncio.html) for the power of Python coroutines
- Server Endpoint:
- Based on [FAST-API](https://github.com/tiangolo/fastapi): enjoy all the benefits of a full ASGI platform, including Async-io and dependency injections (for example to authenticate connections)
- Based on [Pydantic](https://pydantic-docs.helpmanual.io/): easily serialize structured data as part of RPC requests and responses (see 'tests/basic_rpc_test.py :: test_structured_response' for an example)
- Client :
- Based on [Tenacity](https://tenacity.readthedocs.io/en/latest/index.html): allowing configurable retries to keep to connection alive
- see WebSocketRpcClient.__init__'s retry_config
- Based on python [websockets](https://websockets.readthedocs.io/en/stable/intro.html) - a more comprehensive client than the one offered by Fast-api
## Logging
fastapi-websocket-rpc provides a helper logging module to control how it produces logs for you.
See [fastapi_websocket_rpc/logger.py](fastapi_websocket_rpc/logger.py).
Use ```logging_config.set_mode``` or the 'WS_RPC_LOGGING' environment variable to choose the logging method you prefer or override completely via default logging config.
example:
```python
# set RPC to log like UVICORN
from fastapi_websocket_rpc.logger import logging_config, LoggingModes
logging_config.set_mode(LoggingModes.UVICORN)
```
## HTTP(S) Proxy
By default, fastapi-websocket-rpc uses websockets module as websocket client handler. This does not support HTTP(S) Proxy, see https://github.com/python-websockets/websockets/issues/364 . If the ability to use a proxy is important to, another websocket client implementation can be used, e.g. websocket-client (https://websocket-client.readthedocs.io). Here is how to use it. Installation:
```
pip install websocket-client
```
Then use websocket_client_handler_cls parameter:
```python
import asyncio
from fastapi_websocket_rpc import RpcMethodsBase, WebSocketRpcClient, ProxyEnabledWebSocketClientHandler
async def run_client(uri):
async with WebSocketRpcClient(uri, RpcMethodsBase(), websocket_client_handler_cls = ProxyEnabledWebSocketClientHandler) as client:
```
Just set standard environment variables (lowercase and uppercase works): http_proxy, https_proxy, and no_proxy before running python script.
## Pull requests - welcome!
- Please include tests for new features
Raw data
{
"_id": null,
"home_page": "https://github.com/permitio/fastapi_websocket_rpc",
"name": "fastapi-websocket-rpc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Or Weis",
"author_email": "or@permit.io",
"download_url": "https://files.pythonhosted.org/packages/7a/00/c25c985c5c28f485eefefeec3794c06cc095522608b6e5f98bd811c9ecda/fastapi_websocket_rpc-0.1.27.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n<img src=\"https://i.ibb.co/m8jL6Zd/RPC.png\" alt=\"RPC\" border=\"0\" width=\"50%\" />\n</p>\n\n#\n\n# \u26a1 FASTAPI Websocket RPC\nRPC over Websockets made easy, robust, and production ready\n\n<a href=\"https://github.com/permitio/fastapi_websocket_rpc/actions?query=workflow%3ATests\" target=\"_blank\">\n <img src=\"https://github.com/permitio/fastapi_websocket_rpc/workflows/Tests/badge.svg\" alt=\"Tests\">\n</a>\n\n<a href=\"https://pypi.org/project/fastapi-websocket-rpc/\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/v/fastapi-websocket-rpc?color=%2331C654&label=PyPi%20package\" alt=\"Package\">\n</a>\n\n<a href=\"https://pepy.tech/project/fastapi-websocket-rpc\" target=\"_blank\">\n <img src=\"https://static.pepy.tech/personalized-badge/fastapi-websocket-rpc?period=total&units=international_system&left_color=black&right_color=blue&left_text=Downloads\" alt=\"Downloads\">\n</a>\n\nA fast and durable bidirectional JSON RPC channel over Websockets.\nThe easiest way to create a live async channel between two nodes via Python (or other clients).\n\n- Both server and clients can easily expose Python methods that can be called by the other side.\nMethod return values are sent back as RPC responses, which the other side can wait on.\n- Remote methods are easily called via the ```.other.method()``` wrapper \n- Connections are kept alive with a configurable retry mechanism (using Tenacity)\n\n- As seen at <a href=\"https://www.youtube.com/watch?v=KP7tPeKhT3o\" target=\"_blank\">PyCon IL 2021</a> and <a href=\"https://www.youtube.com/watch?v=IuMZVWEUvGs\" target=\"_blank\">EuroPython 2021</a>\n\n\nSupports and tested on Python >= 3.7 \n## Installation \ud83d\udee0\ufe0f\n```\npip install fastapi_websocket_rpc\n```\n\n\n## RPC call example:\n\nSay the server exposes an \"add\" method, e.g. :\n```python\nclass RpcCalculator(RpcMethodsBase):\n async def add(self, a, b):\n return a + b\n```\nCalling it is as easy as calling the method under the client's \"other\" property:\n```python\nresponse = await client.other.add(a=1,b=2)\nprint(response.result) # 3\n```\ngetting the response with the return value.\n\n\n\n\n## Usage example:\n\n### Server:\n```python\nimport uvicorn\nfrom fastapi import FastAPI\nfrom fastapi_websocket_rpc import RpcMethodsBase, WebsocketRPCEndpoint\n\n# Methods to expose to the clients\nclass ConcatServer(RpcMethodsBase):\n async def concat(self, a=\"\", b=\"\"):\n return a + b\n \n# Init the FAST-API app\napp = FastAPI()\n# Create an endpoint and load it with the methods to expose\nendpoint = WebsocketRPCEndpoint(ConcatServer())\n# add the endpoint to the app\nendpoint.register_route(app, \"/ws\")\n\n# Start the server itself\nuvicorn.run(app, host=\"0.0.0.0\", port=9000)\n```\n### Client\n```python\nimport asyncio\nfrom fastapi_websocket_rpc import RpcMethodsBase, WebSocketRpcClient\n\nasync def run_client(uri):\n async with WebSocketRpcClient(uri, RpcMethodsBase()) as client:\n # call concat on the other side\n response = await client.other.concat(a=\"hello\", b=\" world\")\n # print result\n print(response.result) # will print \"hello world\"\n\n# run the client until it completes interaction with server\nasyncio.get_event_loop().run_until_complete(\n run_client(\"ws://localhost:9000/ws\")\n)\n```\n\nSee the [examples](/examples) and [tests](/tests) folders for more server and client examples\n\n\n## Server calling client example:\n- Clients can call ```client.other.method()``` \n - which is a shortcut for ```channel.other.method()```\n- Servers also get the channel object and can call remote methods via ```channel.other.method()```\n- See the [bidirectional call example](examples/bidirectional_server_example.py) for calling client from server and server events (e.g. ```on_connect```).\n\n\n## What can I do with this?\nWebsockets are ideal to create bi-directional realtime connections over the web.\n - Push updates\n - Remote control mechanism\n - Pub / Sub (see [fastapi_websocket_pubsub](https://github.com/permitio/fastapi_websocket_pubsub))\n - Trigger events (see \"tests/trigger_flow_test.py\")\n - Node negotiations (see \"tests/advanced_rpc_test.py :: test_recursive_rpc_calls\")\n\n\n## Concepts\n- [RpcChannel](fastapi_websocket_rpc/rpc_channel.py) - implements the RPC-protocol over the websocket\n - Sending RpcRequests per method call \n - Creating promises to track them (via unique call ids), and allow waiting for responses \n - Executing methods on the remote side and serializing return values as \n - Receiving RpcResponses and delivering them to waiting callers\n- [RpcMethods](fastapi_websocket_rpc/rpc_methods.py) - classes passed to both client and server-endpoint inits to expose callable methods to the other side.\n - Simply derive from RpcMethodsBase and add your own async methods\n - Note currently only key-word arguments are supported\n - Checkout RpcUtilityMethods for example methods, which are also useful debugging utilities\n\n\n- Foundations:\n\n - Based on [asyncio](https://docs.python.org/3/library/asyncio.html) for the power of Python coroutines\n\n - Server Endpoint:\n - Based on [FAST-API](https://github.com/tiangolo/fastapi): enjoy all the benefits of a full ASGI platform, including Async-io and dependency injections (for example to authenticate connections)\n\n - Based on [Pydantic](https://pydantic-docs.helpmanual.io/): easily serialize structured data as part of RPC requests and responses (see 'tests/basic_rpc_test.py :: test_structured_response' for an example)\n\n - Client :\n - Based on [Tenacity](https://tenacity.readthedocs.io/en/latest/index.html): allowing configurable retries to keep to connection alive\n - see WebSocketRpcClient.__init__'s retry_config \n - Based on python [websockets](https://websockets.readthedocs.io/en/stable/intro.html) - a more comprehensive client than the one offered by Fast-api\n\n## Logging \nfastapi-websocket-rpc provides a helper logging module to control how it produces logs for you.\nSee [fastapi_websocket_rpc/logger.py](fastapi_websocket_rpc/logger.py).\nUse ```logging_config.set_mode``` or the 'WS_RPC_LOGGING' environment variable to choose the logging method you prefer or override completely via default logging config.\n\nexample:\n```python\n# set RPC to log like UVICORN\nfrom fastapi_websocket_rpc.logger import logging_config, LoggingModes\nlogging_config.set_mode(LoggingModes.UVICORN)\n```\n\n## HTTP(S) Proxy\nBy default, fastapi-websocket-rpc uses websockets module as websocket client handler. This does not support HTTP(S) Proxy, see https://github.com/python-websockets/websockets/issues/364 . If the ability to use a proxy is important to, another websocket client implementation can be used, e.g. websocket-client (https://websocket-client.readthedocs.io). Here is how to use it. Installation:\n\n```\npip install websocket-client\n```\n\nThen use websocket_client_handler_cls parameter:\n\n```python\nimport asyncio\nfrom fastapi_websocket_rpc import RpcMethodsBase, WebSocketRpcClient, ProxyEnabledWebSocketClientHandler\n\nasync def run_client(uri):\n async with WebSocketRpcClient(uri, RpcMethodsBase(), websocket_client_handler_cls = ProxyEnabledWebSocketClientHandler) as client:\n```\n\nJust set standard environment variables (lowercase and uppercase works): http_proxy, https_proxy, and no_proxy before running python script.\n\n\n## Pull requests - welcome!\n- Please include tests for new features \n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A fast and durable bidirectional JSON RPC channel over Websockets and FastApi.",
"version": "0.1.27",
"project_urls": {
"Homepage": "https://github.com/permitio/fastapi_websocket_rpc"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "31ef129927e2a3df402fafcc0df4f5c5e6bbd1f22245bf4b07df68a170663642",
"md5": "d6921acd777e6ac7119a30e73362bf3f",
"sha256": "b3786cbb76128a22ec2ffde19cac263569fc507974f6651493b8548c4288cc63"
},
"downloads": -1,
"filename": "fastapi_websocket_rpc-0.1.27-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d6921acd777e6ac7119a30e73362bf3f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 21591,
"upload_time": "2024-08-29T13:25:38",
"upload_time_iso_8601": "2024-08-29T13:25:38.650539Z",
"url": "https://files.pythonhosted.org/packages/31/ef/129927e2a3df402fafcc0df4f5c5e6bbd1f22245bf4b07df68a170663642/fastapi_websocket_rpc-0.1.27-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7a00c25c985c5c28f485eefefeec3794c06cc095522608b6e5f98bd811c9ecda",
"md5": "e388b28f88f6242a161dd7fcc1ca43fc",
"sha256": "62463f0d6b42b9b3afde124e25dac51d5fd3ddc7cf59d7a49c5b9a5e87a36ab5"
},
"downloads": -1,
"filename": "fastapi_websocket_rpc-0.1.27.tar.gz",
"has_sig": false,
"md5_digest": "e388b28f88f6242a161dd7fcc1ca43fc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 20968,
"upload_time": "2024-08-29T13:25:40",
"upload_time_iso_8601": "2024-08-29T13:25:40.152361Z",
"url": "https://files.pythonhosted.org/packages/7a/00/c25c985c5c28f485eefefeec3794c06cc095522608b6e5f98bd811c9ecda/fastapi_websocket_rpc-0.1.27.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-29 13:25:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "permitio",
"github_project": "fastapi_websocket_rpc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "fastapi",
"specs": [
[
">=",
"0.78.0"
],
[
"<",
"1"
]
]
},
{
"name": "packaging",
"specs": [
[
">=",
"20.4"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"1.9.1"
]
]
},
{
"name": "uvicorn",
"specs": [
[
"<",
"1"
],
[
">=",
"0.17.6"
]
]
},
{
"name": "websockets",
"specs": [
[
">=",
"10.3"
]
]
},
{
"name": "tenacity",
"specs": [
[
">=",
"8.0.1"
],
[
"<",
"9"
]
]
}
],
"lcname": "fastapi-websocket-rpc"
}
JSON
