fastapi-ws-rpc 0.1.0__tar.gz

fastapi_ws_rpc-0.1.0/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) <2020> <Or Weis, Asaf Cohen>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+and associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+The above copyright notice and this permission notice
+shall be included in all copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

fastapi_ws_rpc-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.1
+Name: fastapi_ws_rpc
+Version: 0.1.0
+Summary: A fast and durable bidirectional JSON RPC channel over Websockets and FastApi.
+Home-page: https://github.com/permitio/fastapi_websocket_rpc
+License: MIT
+Keywords: fastapi,websockets,rpc,json,bidirectional
+Author: Or Weis
+Author-email: or@permit.io
+Requires-Python: >=3.7
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI
+Requires-Dist: fastapi (>=0.78.0,<1)
+Requires-Dist: packaging (>=20.4)
+Requires-Dist: pydantic (>=1.9.1)
+Requires-Dist: tenacity (>=8.0.1,<9)
+Requires-Dist: uvicorn (>=0.17.6,<1)
+Requires-Dist: websockets (>=10.3,<11)
+Description-Content-Type: text/markdown
+
+<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_ws_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_ws_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_ws_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_ws_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_ws_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_ws_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_ws_rpc.logger import logging_config, LoggingModes
+
+logging_config.set_mode(LoggingModes.UVICORN)
+```
+
+## Pull requests - welcome!
+- Please include tests for new features
+

fastapi_ws_rpc-0.1.0/README.md

@@ -0,0 +1,165 @@
+<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_ws_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_ws_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_ws_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_ws_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_ws_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_ws_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_ws_rpc.logger import logging_config, LoggingModes
+
+logging_config.set_mode(LoggingModes.UVICORN)
+```
+
+## Pull requests - welcome!
+- Please include tests for new features

fastapi_ws_rpc-0.1.0/fastapi_ws_rpc/__init__.py

@@ -0,0 +1,11 @@
+from fastapi_ws_rpc.rpc_methods import RpcMethodsBase
+from fastapi_ws_rpc.schemas import WebSocketFrameType
+from fastapi_ws_rpc.websocket_rpc_client import WebSocketRpcClient
+from fastapi_ws_rpc.websocket_rpc_endpoint import WebsocketRPCEndpoint
+
+__all__ = [
+    "RpcMethodsBase",
+    "WebSocketRpcClient",
+    "WebsocketRPCEndpoint",
+    "WebSocketFrameType",
+]

fastapi_ws_rpc-0.1.0/fastapi_ws_rpc/connection_manager.py

@@ -0,0 +1,15 @@
+from typing import List
+
+from fastapi import WebSocket
+
+
+class ConnectionManager:
+    def __init__(self):
+        self.active_connections: List[WebSocket] = []
+
+    async def connect(self, websocket: WebSocket):
+        await websocket.accept()
+        self.active_connections.append(websocket)
+
+    def disconnect(self, websocket: WebSocket):
+        self.active_connections.remove(websocket)

fastapi_ws_rpc-0.1.0/fastapi_ws_rpc/logger.py

@@ -0,0 +1,113 @@
+import logging
+import os
+from enum import Enum
+from logging.config import dictConfig
+from typing import NewType
+
+ENV_VAR = "WS_RPC_LOGGING"
+
+
+class LoggingModes(Enum):
+    # don't produce logs
+    NO_LOGS = 0
+    # Log alongside uvicorn
+    UVICORN = 1
+    # Simple log calls (no config)
+    SIMPLE = 2
+    # log via the loguru module
+    LOGURU = 3
+
+
+LoggingMode = NewType("LoggingMode", LoggingModes)
+
+
+class LoggingConfig:
+    def __init__(self) -> None:
+        self._mode = None
+
+    config_template = {
+        "version": 1,
+        "disable_existing_loggers": True,
+        "formatters": {
+            "default": {
+                "()": "uvicorn.logging.DefaultFormatter",
+                "fmt": "%(levelprefix)s %(asctime)s %(message)s",
+                "datefmt": "%Y-%m-%d %H:%M:%S",
+            },
+        },
+        "handlers": {
+            "default": {
+                "formatter": "default",
+                "class": "logging.StreamHandler",
+            },
+        },
+        "loggers": {},
+    }
+
+    UVICORN_LOGGERS = {
+        "uvicorn.error": {
+            "propagate": False,
+            "handlers": ["default"],
+        },
+        "fastapi_ws_rpc": {
+            "handlers": ["default"],
+            "propagate": False,
+            "level": logging.INFO,
+        },
+    }
+
+    def get_mode(self):
+        # if no one set the mode - set default from ENV or hardcoded default
+        if self._mode is None:
+            mode = LoggingModes.__members__.get(
+                os.environ.get(ENV_VAR, "").upper(), LoggingModes.SIMPLE
+            )
+            self.set_mode(mode)
+        return self._mode
+
+    def set_mode(self, mode: LoggingMode = LoggingModes.UVICORN, level=logging.INFO):
+        """
+        Configure logging. this method calls 'logging.config.dictConfig()' to enable
+        quick setup of logging. Call this method before starting the app.
+        For more advanced cases use 'logging.config' directly (loggers used by this
+        library are all nested under "fastapi_ws_rpc" logger name)
+
+        Args:
+            mode (LoggingMode, optional): The mode to set logging to. Defaults to
+            LoggingModes.UVICORN.
+        """
+        self._mode = mode
+        logging_config = self.config_template.copy()
+        # add logs beside uvicorn
+        if mode == LoggingModes.UVICORN:
+            logging_config["loggers"] = self.UVICORN_LOGGERS.copy()
+            logging_config["loggers"]["fastapi_ws_rpc"]["level"] = level
+            dictConfig(logging_config)
+        elif mode == LoggingModes.SIMPLE:
+            pass
+        elif mode == LoggingModes.LOGURU:
+            pass
+        # no logs
+        else:
+            logging_config["loggers"] = {}
+            dictConfig(logging_config)
+
+
+# Singelton for logging configuration
+logging_config = LoggingConfig()
+
+
+def get_logger(name):
+    """
+    Get a logger object to log with.
+    Called by inner modules for logging.
+    """
+    mode = logging_config.get_mode()
+    # logging through loguru
+    if mode == LoggingModes.LOGURU:
+        from loguru import logger
+    else:
+        # regular python logging
+        logger = logging.getLogger(f"fastapi_ws_rpc.{name}")
+
+    return logger