django-jsonrpc-framework 0.1.0__tar.gz

django_jsonrpc_framework-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv
+.pytest_cache
+.ruff_cache
+.mypy_cache
+__pycache__
+*/__pycache__/*
+.cursor
+dist/
+build/
+*.egg-info/

django_jsonrpc_framework-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: django-jsonrpc-framework
+Version: 0.1.0
+Summary: Django jsonrpc implementation
+Classifier: Framework :: Django
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.13
+Requires-Dist: django>=6.0.5
+Requires-Dist: pydantic>=2.13.4
+Description-Content-Type: text/markdown
+
+# Django jsonrpc implementation
+
+## Advantages
+
+- Complete support jsonrpc 2.0 (Request, Notificatin, Batch)
+- Auto generation openrpc.json 1.3.2 version
+- Auto generation OpenRPC documentation (like swagger)
+- Async support
+
+## Create methods
+
+We provide several methods creating methods. 
+
+- Using `method_` prefix
+- Using `jsonrpc_method` decorator
+- Rename existing func to new name
+
+``` python
+
+from jsonrpc_framework import BaseController
+from jsonrpc_framework.controller.decor import jsonrpc_method
+
+class EchoController(BaseController):
+    
+    def method_echo_hello(self, name: str) -> str:
+        return f"hello {name}"
+
+    @jsonrpc_method
+    def echo_goodbye(self, name: str) -> str:
+        return f"goodbye {name}"
+
+    @jsonrpc_method("echo_see_you")
+    def wrong_name(self, name) -> str:
+        return "See you fron echo_see_you method"
+
+```
+
+## Adding several controllers to one controller
+
+``` python
+from jsonrpc_framework import RouteController
+
+class PrintController(BaseController):
+
+    async def method_print_hello(self, name) -> None:
+        print(f"hello {name}")
+
+    @jsonrpc_method
+    async def print_goodbye(self, name) -> None:
+        print(f"goodbye {name}")
+ 
+
+route = RouteController(
+    'jsonrpc',
+    controllers=[
+        PrintController,
+        EchoController,
+    ]
+    
+)
+```
+
+## Generation openrpc.json and OpenRpc documentation
+
+``` python
+from jsonrpc_framework.controller.openrpc.collectors import OpenRpcCollector
+
+collector = OpenRpcCollector(
+    PrintController,
+    EchoController,
+    title='My mini API'
+)
+
+
+urlpatterns = [
+    path('echorpc', EchoController,as_view),
+    path('jsonrpc', route.as_view()),
+    path('openrpc.json', OpenRpcJsonView.as_view(collector=collector)),
+    path('docs', OpenRpcDocView.as_view()),
+]
+
+```
+
+### Openrpc.json example
+
+![OpenRPC docs](docs/docs/openrpcjson.png)
+
+## Openrpc doc example
+
+![OpenRPC docs](docs/docs/docs.png)

django_jsonrpc_framework-0.1.0/README.md

@@ -0,0 +1,90 @@
+# Django jsonrpc implementation
+
+## Advantages
+
+- Complete support jsonrpc 2.0 (Request, Notificatin, Batch)
+- Auto generation openrpc.json 1.3.2 version
+- Auto generation OpenRPC documentation (like swagger)
+- Async support
+
+## Create methods
+
+We provide several methods creating methods. 
+
+- Using `method_` prefix
+- Using `jsonrpc_method` decorator
+- Rename existing func to new name
+
+``` python
+
+from jsonrpc_framework import BaseController
+from jsonrpc_framework.controller.decor import jsonrpc_method
+
+class EchoController(BaseController):
+    
+    def method_echo_hello(self, name: str) -> str:
+        return f"hello {name}"
+
+    @jsonrpc_method
+    def echo_goodbye(self, name: str) -> str:
+        return f"goodbye {name}"
+
+    @jsonrpc_method("echo_see_you")
+    def wrong_name(self, name) -> str:
+        return "See you fron echo_see_you method"
+
+```
+
+## Adding several controllers to one controller
+
+``` python
+from jsonrpc_framework import RouteController
+
+class PrintController(BaseController):
+
+    async def method_print_hello(self, name) -> None:
+        print(f"hello {name}")
+
+    @jsonrpc_method
+    async def print_goodbye(self, name) -> None:
+        print(f"goodbye {name}")
+ 
+
+route = RouteController(
+    'jsonrpc',
+    controllers=[
+        PrintController,
+        EchoController,
+    ]
+    
+)
+```
+
+## Generation openrpc.json and OpenRpc documentation
+
+``` python
+from jsonrpc_framework.controller.openrpc.collectors import OpenRpcCollector
+
+collector = OpenRpcCollector(
+    PrintController,
+    EchoController,
+    title='My mini API'
+)
+
+
+urlpatterns = [
+    path('echorpc', EchoController,as_view),
+    path('jsonrpc', route.as_view()),
+    path('openrpc.json', OpenRpcJsonView.as_view(collector=collector)),
+    path('docs', OpenRpcDocView.as_view()),
+]
+
+```
+
+### Openrpc.json example
+
+![OpenRPC docs](docs/docs/openrpcjson.png)
+
+## Openrpc doc example
+
+![OpenRPC docs](docs/docs/docs.png)

django_jsonrpc_framework-0.1.0/jsonrpc_framework/__init__.py

@@ -0,0 +1,8 @@
+from .controller import BaseController, RouteController
+from .controller.decor import jsonrpc_method
+
+__all__ = [
+    "BaseController",
+    "RouteController",
+    "jsonrpc_method",
+]

django_jsonrpc_framework-0.1.0/jsonrpc_framework/controller/__init__.py

@@ -0,0 +1,7 @@
+from ._base import BaseController
+from ._route import RouteController
+
+__all__ = [
+    "BaseController",
+    "RouteController",
+]

django_jsonrpc_framework-0.1.0/jsonrpc_framework/controller/_base.py

@@ -0,0 +1,103 @@
+import logging
+from typing import Any
+from collections.abc import Callable
+
+from django.views import View
+from django.http import HttpRequest, HttpResponse
+
+from jsonrpc_framework.logic.dispatcher import RpcDispatcher
+from jsonrpc_framework.logic.validator import RequestValidator, RequestType, BatchType
+from jsonrpc_framework.logic.responser import ResponseBuilder
+
+from jsonrpc_framework.core.error import RpcError
+from jsonrpc_framework.core.models import MethodType
+
+
+
+logger = logging.getLogger("django.server")
+
+
+class BaseController(View):
+    http_method_names = ["post"]
+    path: str = "jsonrpc"
+
+    registry: dict[MethodType, Callable[..., Any]]
+
+    dispatcher: RpcDispatcher
+    validator: RequestValidator
+    response_builder: ResponseBuilder
+
+
+    def __init__(self, *args: tuple[Any], **kwargs: dict[str, Any]):
+        super().__init__(*args, **kwargs)
+
+        self.registry = self._collect_declared_methods()
+
+        self.dispatcher = RpcDispatcher()
+        self.validator = RequestValidator()
+        self.response_builder = ResponseBuilder()
+
+
+    def _collect_declared_methods(self) -> dict[MethodType, Callable[..., Any]]:
+        registry: dict[MethodType, Callable[..., Any]] = {}
+
+        for name, value in vars(self.__class__).items():
+            if not callable(value):
+                continue
+
+            rpc_name = getattr(value, "__rpc_method_name__", None)
+
+            if rpc_name is not None:
+                method_name = rpc_name
+            elif name.startswith("method_"):
+                method_name = name.replace("method_", "")
+            else:
+                continue
+
+            if method_name in registry:
+                raise ValueError(f"Method {method_name} already registered in {self.__class__.__name__}")
+
+            registry[method_name] = getattr(self, name)
+
+        return registry
+
+    async def post(
+        self,
+        request: HttpRequest,
+        *args: tuple[Any],
+        **kwargs: dict[str, Any],
+    ) -> HttpResponse:
+        body = self.validator.validate_body(request.body)
+
+        result = await self.dispatcher.dispatch(body, registry=self.registry)
+        self._log_jsonrpc_methods(request, body)
+
+        return self.response_builder.build_response(result)
+
+    def _log_jsonrpc_methods(
+        self,
+        request: HttpRequest,
+        body: RequestType | BatchType | RpcError,
+    ) -> None:
+        methods = self._extract_method_names(body)
+
+        if methods:
+            logger.info(f"JSONRPC {request.path} {methods}")
+
+    def _extract_method_names(
+        self,
+        body: RequestType | BatchType | RpcError,
+    ) -> list[str] | str:
+        if isinstance(body, RpcError):
+            return []
+
+        if isinstance(body, list):
+            methods: list[str] = []
+
+            for item in body:
+                if isinstance(item, RpcError):
+                    continue
+                methods.append(item.method)
+            return methods
+
+        return body.method

django_jsonrpc_framework-0.1.0/jsonrpc_framework/controller/_route.py

@@ -0,0 +1,71 @@
+from collections import defaultdict
+from collections.abc import Callable
+from typing import Any
+
+
+from jsonrpc_framework.controller._base import BaseController
+
+class RouteController(BaseController):
+    """The conroller that collects BaseControllers to merge 
+    their methods into a single controller.
+
+    Args:
+        path: The path to use in urlconfig.
+        controllers: The list of BaseControllers to merge.
+    """
+    controllers: list[type[BaseController] | BaseController] = []
+
+    def __init__(
+        self,
+        path: str,
+        controllers: list[type[BaseController] | BaseController],
+    ):
+        super().__init__()
+        self.path = path
+        self.controllers = controllers
+
+        merged_registry: dict[str, Callable[..., Any]] = {}
+        key_sources: dict[str, list[str]] = defaultdict(list)
+
+        for raw_controller in controllers:
+
+            controller = (
+                raw_controller()
+                if isinstance(raw_controller, type)
+                else raw_controller
+            )
+
+            if not isinstance(controller, BaseController):
+                raise TypeError(
+                    "Each controller must be a BaseController instance or subclass"
+                )
+
+            controller_name = controller.__class__.__name__
+            for method_name, callback in controller.registry.items():
+                key_sources[method_name].append(controller_name)
+                if method_name in merged_registry:
+                    continue
+                merged_registry[method_name] = callback
+
+        conflicts = {
+            method_name: names
+            for method_name, names in key_sources.items()
+            if len(names) > 1
+        }
+        if conflicts:
+            details = "; ".join(
+                f"{method!r} -> {sources}"
+                for method, sources in sorted(conflicts.items())
+            )
+            raise ValueError(f"Duplicate JSON-RPC methods detected: {details}")
+
+        self.registry = merged_registry
+
+
+    def as_view(self, **initkwargs: Any) -> Any: # type: ignore[override]
+        return BaseController.as_view.__func__( # type: ignore[attr-defined]
+            self.__class__,
+            path=self.path,
+            controllers=self.controllers,
+            **initkwargs,
+        )

django_jsonrpc_framework-0.1.0/jsonrpc_framework/controller/decor.py

@@ -0,0 +1,81 @@
+from collections.abc import Callable
+from functools import wraps
+from typing import Any
+
+
+def _decorate[R, **P](
+    func: Callable[P, R],
+    rpc_name: str,
+    summary: str | None = None,
+    description: str | None = None,
+    tags: list[str] | None = None,
+) -> Callable[P, R]:
+    # Keep an explicit RPC alias on the callable, because class attribute
+    # names are used during registry collection and cannot be renamed here.
+    setattr(func, "__rpc_method_name__", rpc_name)
+    setattr(func, "__rpc_method_summary__", summary)
+    setattr(func, "__rpc_method_description__", description)
+    setattr(func, "__rpc_method_tags__", tags)
+
+    @wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        return func(*args, **kwargs)
+
+    setattr(wrapper, "__rpc_method_name__", rpc_name)
+    setattr(wrapper, "__rpc_method_summary__", summary)
+    setattr(wrapper, "__rpc_method_description__", description)
+    setattr(wrapper, "__rpc_method_tags__", tags)
+
+    return wrapper
+
+
+def simple_decorator[R, **P](
+    func: Callable[P, R],
+) -> Callable[P, R]:
+    return _decorate(
+        func,
+        rpc_name=func.__name__,
+        description=func.__doc__,
+    )
+
+
+def parametrized_decorator[R, **P](
+    func: Callable[P, R],
+    *,
+    name: str | None = None,
+    summary: str | None = None,
+    description: str | None = None,
+    tags: list[str] | None = None,
+) -> Callable[P, R]:
+    rpc_name = name if isinstance(name, str) else func.__name__
+    return _decorate(
+        func,
+        rpc_name,
+        summary,
+        description,
+        tags,
+    )
+
+
+def jsonrpc_method(
+    name_or_func: str | Callable[..., Any] | None = None,
+    *,
+    summary: str | None = None,
+    description: str | None = None,
+    tags: list[str] | None = None,
+) -> Callable[..., Any]:
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        return parametrized_decorator(
+            func,
+            name=name_or_func if isinstance(name_or_func, str) else None,
+            summary=summary,
+            description=description,
+            tags=tags,
+        )
+
+    if callable(name_or_func):
+        return simple_decorator(
+            name_or_func,
+        )
+
+    return decorator

django_jsonrpc_framework-0.1.0/jsonrpc_framework/controller/openrpc/_openrpc.py

@@ -0,0 +1,101 @@
+from pathlib import Path
+from typing import Callable, override, Any
+
+from django.views.generic.base import TemplateView
+from django.conf import settings
+from django.http import HttpRequest, HttpResponse, HttpResponseBase
+from django.http.response import FileResponse
+
+from django.views import View
+
+from jsonrpc_framework.controller.openrpc.collectors import OpenRpcCollector
+
+class OpenRpcJsonView(View):
+
+    http_method_names = ["get"]
+    path = "openrpc.json"
+    collector: OpenRpcCollector = OpenRpcCollector()
+
+    def __init__(
+        self,
+        *args: tuple[Any],
+        **kwargs: dict[str, Any]
+    ):
+        super().__init__(*args, **kwargs)
+
+    def get(self, request: HttpRequest, *args: tuple[Any], **kwargs: dict[str, Any]) -> HttpResponse | FileResponse:
+        file_path = getattr(
+            settings, "DJANGO_JSONRPC_DOCS", {}
+            ).get("FILE_PATH", None)
+
+        if file_path is not None and Path(file_path).exists():
+            return FileResponse(
+                Path(file_path).open("rb"),
+                filename=Path(file_path).name,
+            )
+
+        if not self.collector.is_collected:
+            self.collector.collect()
+
+        document = self.collector.build_document()
+
+        return HttpResponse(
+            content=document,
+            content_type="application/json; charset=utf-8",
+        )
+
+    @classmethod
+    @override
+    def as_view(
+        cls,
+        *,
+        collector: OpenRpcCollector | None = None,
+        **initkwargs: Any,
+    ) -> Callable[..., HttpResponseBase]:
+        return super().as_view(collector=collector, **initkwargs)
+
+
+
+class OpenRpcDocView(TemplateView):
+    template_name = "openrpc_docs.html"
+
+    def get_context_data(self, **kwargs: Any) -> dict[str, Any]:
+        ctx = super().get_context_data(**kwargs)
+
+        docs_cfg = getattr(settings, "DJANGO_JSONRPC_DOCS", {})
+
+        schema_path = docs_cfg.get("SCHEMA_PATH", "/openrpc.json")
+        schema_url = self.request.build_absolute_uri(schema_path)
+
+        ctx.update(
+            {
+                "openrpc_schema_url": schema_url,
+                "page_title": docs_cfg.get("TITLE", "OpenRPC Docs"),
+                "docs_react_css_url": docs_cfg.get(
+                    "DOCS_REACT_CSS_URL",
+                    "https://cdn.jsdelivr.net/npm/@open-rpc/docs-react@2.1.1/dist/docs-react.css",
+                ),
+                "esm_react_url": docs_cfg.get(
+                    "ESM_REACT_URL",
+                    "https://esm.sh/react@18.3.1",
+                ),
+                "esm_react_dom_url": docs_cfg.get(
+                    "ESM_REACT_DOM_URL",
+                    "https://esm.sh/react-dom@18.3.1/client?deps=react@18.3.1",
+                ),
+                "esm_openrpc_docs_url": docs_cfg.get(
+                    "ESM_OPENRPC_DOCS_URL",
+                    "https://esm.sh/@open-rpc/docs-react@2.1.1?deps=react@18.3.1,react-dom@18.3.1",
+                ),
+                "esm_mui_styles_url": docs_cfg.get(
+                    "ESM_MUI_STYLES_URL",
+                    "https://esm.sh/@mui/material@6.3.1/styles?deps=react@18.3.1,react-dom@18.3.1",
+                ),
+                "esm_mui_css_baseline_url": docs_cfg.get(
+                    "ESM_MUI_CSS_BASELINE_URL",
+                    "https://esm.sh/@mui/material@6.3.1/CssBaseline?deps=react@18.3.1,react-dom@18.3.1",
+                ),
+                "openrpc_theme_mode": docs_cfg.get("THEME_MODE", "dark"),
+            }
+        )
+        return ctx

django_jsonrpc_framework-0.1.0/jsonrpc_framework/controller/openrpc/collectors/__init__.py

@@ -0,0 +1,5 @@
+from ._main_collector import OpenRpcCollector
+
+__all__ = [
+    "OpenRpcCollector",
+]

django_jsonrpc_framework-0.1.0/jsonrpc_framework/controller/openrpc/collectors/_main_collector.py

@@ -0,0 +1,57 @@
+
+from jsonrpc_framework.controller._base import BaseController
+from jsonrpc_framework.openrpc.builder.builder import OpenRpcBuilder
+from jsonrpc_framework.openrpc.document.info import OpenRpcContact, OpenRpcLicense
+
+from jsonrpc_framework.controller.openrpc.collectors._method_collector import MethodsCollector
+
+type ControllerType = type[BaseController] | BaseController
+
+class OpenRpcCollector:
+
+    controllers: tuple[type[BaseController] | BaseController, ...]
+    builder: OpenRpcBuilder
+    is_collected: bool
+
+    method_collector: MethodsCollector
+
+    def __init__(
+        self,
+        *controllers: ControllerType,
+        title: str = "Django-jsonrpc API",
+        version: str = "1.0.0",
+        description: str | None = None,
+        terms_of_service: str | None = None,
+        contact: OpenRpcContact | None = None,
+        license: OpenRpcLicense | None = None,
+    ):
+        self.controllers = controllers
+    
+        self.method_collector = MethodsCollector()
+        self.builder = OpenRpcBuilder(
+            title=title,
+            version=version,
+            description=description,
+            terms_of_service=terms_of_service,
+            contact=contact,
+            license=license,
+        )
+        self.is_collected = False
+
+    def collect(self) -> None:
+        for controller in self.controllers:
+            if isinstance(controller, type):
+                controller = controller()
+
+            self.method_collector.collect(controller)
+
+        for method in self.method_collector.methods:
+            self.builder.add_method(method)
+
+        self.builder.add_components(self.method_collector.components)
+        self.is_collected = True
+
+
+    def build_document(self) -> str:
+
+        return self.builder.build_json()