rpc-python-toolkit 0.1.0__py3-none-any.whl

rpc_python_toolkit/__init__.py

@@ -0,0 +1,19 @@
+from .client import RpcClient, RpcSafeClient
+from .endpoint import RpcEndpoint, RpcHttpResponse, RpcSafeEndpoint
+from .errors import RpcError, RpcRemoteError
+from .serialization import deserialize_value, serialize_value
+from .version import __version__
+
+__all__ = [
+    "__version__",
+    "deserialize_value",
+    "serialize_value",
+    "RpcClient",
+    "RpcEndpoint",
+    "RpcError",
+    "RpcHttpResponse",
+    "RpcRemoteError",
+    "RpcSafeClient",
+    "RpcSafeEndpoint",
+]
+

rpc_python_toolkit/client.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+from .errors import RpcError, RpcRemoteError
+from .serialization import deserialize_value, serialize_value
+
+
+class RpcClient:
+    def __init__(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        timeout: float = 30,
+        safe_enabled: bool = False,
+        require_safe_header: bool = True,
+    ):
+        self.url = url
+        self.headers = headers or {}
+        self.timeout = timeout
+        self.safe_enabled = safe_enabled
+        self.require_safe_header = require_safe_header
+        self._next_id = 1
+
+    def call(self, method: str, params: Any = None, *, request_id: Any = None) -> Any:
+        request = {
+            "jsonrpc": "2.0",
+            "method": method,
+            "id": self._make_id() if request_id is None else request_id,
+        }
+        if params is not None:
+            request["params"] = self._encode(params)
+
+        response = self._send(request, expect_response=True)
+        if "error" in response:
+            error = response["error"]
+            data = self._decode(error.get("data"), response.get("_safe_enabled", False))
+            raise RpcRemoteError(error.get("message", "RPC error"), error.get("code", -32603), data)
+
+        return self._decode(response.get("result"), response.get("_safe_enabled", False))
+
+    def notify(self, method: str, params: Any = None) -> None:
+        request = {
+            "jsonrpc": "2.0",
+            "method": method,
+        }
+        if params is not None:
+            request["params"] = self._encode(params)
+        self._send(request, expect_response=False)
+
+    def batch(self, requests: list[dict[str, Any]]) -> list[Any]:
+        payload = []
+        for item in requests:
+            request = {
+                "jsonrpc": "2.0",
+                "method": item["method"],
+            }
+            if "id" in item:
+                request["id"] = item["id"]
+            if "params" in item:
+                request["params"] = self._encode(item["params"])
+            payload.append(request)
+
+        response = self._send(payload, expect_response=True)
+        if not response:
+            return []
+
+        responses = response if isinstance(response, list) else [response]
+        results = []
+        for item in responses:
+            if "error" in item:
+                error = item["error"]
+                data = self._decode(error.get("data"), item.get("_safe_enabled", False))
+                raise RpcRemoteError(error.get("message", "RPC error"), error.get("code", -32603), data)
+            results.append(self._decode(item.get("result"), item.get("_safe_enabled", False)))
+        return results
+
+    def _send(self, payload: Any, *, expect_response: bool) -> Any:
+        body = json.dumps(payload, separators=(",", ":"), default=str).encode("utf-8")
+        headers = {
+            "content-type": "application/json",
+            **self.headers,
+        }
+
+        if self.safe_enabled:
+            headers["x-rpc-safe-enabled"] = "true"
+        else:
+            headers.setdefault("x-rpc-safe-enabled", "false")
+
+        request = urllib.request.Request(self.url, data=body, headers=headers, method="POST")
+
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                response_body = response.read().decode("utf-8")
+                server_safe_header = response.headers.get("X-RPC-Safe-Enabled")
+                status = response.status
+        except urllib.error.HTTPError as exc:
+            response_body = exc.read().decode("utf-8")
+            server_safe_header = exc.headers.get("X-RPC-Safe-Enabled")
+            status = exc.code
+
+        if status == 204 or response_body == "":
+            return [] if not expect_response else {}
+
+        if self.safe_enabled and self.require_safe_header and server_safe_header is None:
+            raise RpcError(
+                "RPC Compatibility Error: safe client expected X-RPC-Safe-Enabled response header",
+                -32603,
+            )
+
+        server_safe_enabled = str(server_safe_header).lower() == "true"
+        decoded = json.loads(response_body)
+        self._attach_safe_flag(decoded, server_safe_enabled)
+        return decoded
+
+    def _encode(self, value: Any) -> Any:
+        return serialize_value(value, safe_enabled=self.safe_enabled)
+
+    @staticmethod
+    def _decode(value: Any, safe_enabled: bool) -> Any:
+        return deserialize_value(value, safe_enabled=safe_enabled)
+
+    def _make_id(self) -> int:
+        request_id = self._next_id
+        self._next_id += 1
+        return request_id
+
+    @staticmethod
+    def _attach_safe_flag(value: Any, safe_enabled: bool) -> None:
+        if isinstance(value, list):
+            for item in value:
+                if isinstance(item, dict):
+                    item["_safe_enabled"] = safe_enabled
+        elif isinstance(value, dict):
+            value["_safe_enabled"] = safe_enabled
+
+
+class RpcSafeClient(RpcClient):
+    def __init__(self, url: str, **options: Any):
+        options.setdefault("safe_enabled", True)
+        options.setdefault("require_safe_header", True)
+        super().__init__(url, **options)

rpc_python_toolkit/endpoint.py

@@ -0,0 +1,314 @@
+from __future__ import annotations
+
+import inspect
+import json
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from .errors import RpcError
+from .protocol import has_id, make_response, validate_request_envelope
+from .serialization import deserialize_value, serialize_value
+from .validation import SchemaValidator
+from .version import __version__
+
+
+Handler = Callable[..., Any]
+
+
+@dataclass
+class RpcHttpResponse:
+    status: int
+    headers: dict[str, str]
+    body: Any | None = None
+
+
+@dataclass
+class MethodConfig:
+    handler: Handler
+    schema: dict[str, Any] | None = None
+    description: str = ""
+    expose_schema: bool = False
+
+
+class RpcEndpoint:
+    def __init__(
+        self,
+        context: Any = None,
+        *,
+        safe_enabled: bool = False,
+        strict_mode: bool = True,
+        enable_introspection: bool = False,
+        introspection_prefix: str = "__rpc",
+        max_serialization_depth: int = 100,
+        max_deserialization_depth: int = 100,
+    ):
+        self.context = context
+        self.methods: dict[str, MethodConfig] = {}
+        self.safe_enabled = safe_enabled
+        self.strict_mode = strict_mode
+        self.enable_introspection = enable_introspection
+        self.introspection_prefix = introspection_prefix
+        self.max_serialization_depth = max_serialization_depth
+        self.max_deserialization_depth = max_deserialization_depth
+        self.validator = SchemaValidator()
+
+        if self.enable_introspection:
+            self._register_introspection_methods()
+
+    def add_method(
+        self,
+        name: str,
+        handler: Handler,
+        *,
+        schema: dict[str, Any] | None = None,
+        description: str = "",
+        expose_schema: bool = False,
+    ) -> None:
+        if not isinstance(name, str) or not name:
+            raise ValueError("Method name must be a non-empty string")
+
+        self.methods[name] = MethodConfig(
+            handler=handler,
+            schema=schema,
+            description=description,
+            expose_schema=expose_schema,
+        )
+
+    def remove_method(self, name: str) -> None:
+        self.methods.pop(name, None)
+
+    def list_methods(self) -> list[str]:
+        return list(self.methods.keys())
+
+    def handle_request(self, payload: str | bytes | dict[str, Any] | list[Any], context: dict[str, Any] | None = None) -> str:
+        response = self.handle_payload(payload, context)
+        if response.status == 204 or response.body is None:
+            return ""
+        return json.dumps(response.body, separators=(",", ":"), default=str)
+
+    def handle_payload(
+        self,
+        payload: str | bytes | dict[str, Any] | list[Any],
+        context: dict[str, Any] | None = None,
+    ) -> RpcHttpResponse:
+        headers = {
+            "content-type": "application/json",
+            "x-rpc-safe-enabled": "true" if self.safe_enabled else "false",
+        }
+
+        try:
+            request = self._decode_payload(payload)
+        except Exception as exc:
+            return RpcHttpResponse(
+                200,
+                headers,
+                make_response(
+                    None,
+                    error={
+                        "code": -32700,
+                        "message": "Parse error",
+                        "data": {"message": str(exc)},
+                    },
+                ),
+            )
+
+        request_context = context or {}
+        try:
+            if isinstance(request, list):
+                return self._process_batch(request, request_context, headers)
+
+            result = self._process_single(request, request_context)
+            if result is None:
+                return RpcHttpResponse(204, headers)
+
+            return RpcHttpResponse(200, headers, result)
+        except RpcError as exc:
+            return RpcHttpResponse(200, headers, self._make_error_response(None, exc))
+        except Exception as exc:
+            return RpcHttpResponse(
+                200,
+                headers,
+                self._make_error_response(None, RpcError(str(exc), -32603)),
+            )
+
+    def serialize_bigints_and_dates(self, value: Any) -> Any:
+        return serialize_value(
+            value,
+            safe_enabled=self.safe_enabled,
+            max_depth=self.max_serialization_depth,
+        )
+
+    def deserialize_bigints_and_dates(self, value: Any, *, safe_enabled: bool | None = None) -> Any:
+        return deserialize_value(
+            value,
+            safe_enabled=self.safe_enabled if safe_enabled is None else safe_enabled,
+            max_depth=self.max_deserialization_depth,
+        )
+
+    def _process_batch(
+        self,
+        batch: list[Any],
+        context: dict[str, Any],
+        headers: dict[str, str],
+    ) -> RpcHttpResponse:
+        if not batch:
+            return RpcHttpResponse(
+                200,
+                headers,
+                make_response(None, error={"code": -32600, "message": "Invalid Request"}),
+            )
+
+        responses = []
+        for item in batch:
+            result = self._process_single(item, context)
+            if result is not None:
+                responses.append(result)
+
+        if not responses:
+            return RpcHttpResponse(204, headers)
+
+        return RpcHttpResponse(200, headers, responses)
+
+    def _process_single(self, request: Any, context: dict[str, Any]) -> dict[str, Any] | None:
+        try:
+            validate_request_envelope(request)
+            client_safe_enabled = self._client_safe_enabled(context)
+
+            if self.safe_enabled and self.strict_mode and not self._has_safe_header(context):
+                raise RpcError("Safe Mode requires X-RPC-Safe-Enabled header", -32600)
+
+            method_name = request["method"]
+            method = self.methods.get(method_name)
+            if method is None:
+                raise RpcError(f"Method not found: {method_name}", -32601)
+
+            params = request.get("params", {})
+            if client_safe_enabled:
+                params = self.deserialize_bigints_and_dates(params, safe_enabled=True)
+
+            self.validator.validate(params, method.schema)
+            result = self._execute_handler(method.handler, request, context, params)
+
+            if not has_id(request):
+                return None
+
+            return make_response(
+                request.get("id"),
+                result=self.serialize_bigints_and_dates(result),
+            )
+        except RpcError as exc:
+            if isinstance(request, dict) and not has_id(request):
+                return None
+            request_id = request.get("id") if isinstance(request, dict) else None
+            return self._make_error_response(request_id, exc)
+        except Exception as exc:
+            if isinstance(request, dict) and not has_id(request):
+                return None
+            request_id = request.get("id") if isinstance(request, dict) else None
+            return self._make_error_response(request_id, RpcError(str(exc), -32603))
+
+    def _make_error_response(self, request_id: Any, error: RpcError) -> dict[str, Any]:
+        body = {
+            "code": error.code,
+            "message": str(error),
+        }
+
+        if error.data is not None:
+            body["data"] = self.serialize_bigints_and_dates(error.data)
+
+        return make_response(request_id, error=body)
+
+    def _execute_handler(
+        self,
+        handler: Handler,
+        request: dict[str, Any],
+        context: dict[str, Any],
+        params: Any,
+    ) -> Any:
+        result = handler(request, self.context if self.context is not None else context, params)
+        if inspect.isawaitable(result):
+            raise RpcError("Async handlers require an async adapter", -32603)
+        return result
+
+    def _register_introspection_methods(self) -> None:
+        prefix = self.introspection_prefix
+
+        self.add_method(
+            f"{prefix}.listMethods",
+            lambda _request, _context, _params: [
+                name for name in self.methods if not name.startswith(f"{prefix}.")
+            ],
+        )
+        self.add_method(
+            f"{prefix}.version",
+            lambda _request, _context, _params: {
+                "toolkit": "rpc-python-toolkit",
+                "version": __version__,
+                "methodCount": len(
+                    [name for name in self.methods if not name.startswith(f"{prefix}.")]
+                ),
+            },
+        )
+        self.add_method(f"{prefix}.describe", self._describe_method)
+        self.add_method(
+            f"{prefix}.capabilities",
+            lambda _request, _context, _params: {
+                "jsonrpc": "2.0",
+                "batch": True,
+                "notifications": True,
+                "introspection": True,
+                "safeMode": self.safe_enabled,
+                "transport": "python-http",
+            },
+        )
+
+    def _describe_method(self, _request: dict[str, Any], _context: Any, params: Any) -> dict[str, Any]:
+        if not isinstance(params, dict) or not isinstance(params.get("method"), str):
+            raise RpcError("Invalid params: method name required", -32602)
+
+        method_name = params["method"]
+        if method_name.startswith(f"{self.introspection_prefix}."):
+            raise RpcError("Cannot describe introspection methods", -32601)
+
+        method = self.methods.get(method_name)
+        if method is None:
+            raise RpcError(f"Method not found: {method_name}", -32601)
+
+        return {
+            "name": method_name,
+            "description": method.description,
+            "schema": method.schema if method.expose_schema else None,
+        }
+
+    @staticmethod
+    def _decode_payload(payload: str | bytes | dict[str, Any] | list[Any]) -> Any:
+        if isinstance(payload, bytes):
+            payload = payload.decode("utf-8")
+
+        if isinstance(payload, str):
+            return json.loads(payload)
+
+        return payload
+
+    @staticmethod
+    def _normalized_headers(context: dict[str, Any]) -> dict[str, str]:
+        headers = context.get("headers", {}) or {}
+        return {str(key).lower(): str(value) for key, value in headers.items()}
+
+    def _has_safe_header(self, context: dict[str, Any]) -> bool:
+        headers = self._normalized_headers(context)
+        return "x-rpc-safe-enabled" in headers or "x-rpc-safe" in headers
+
+    def _client_safe_enabled(self, context: dict[str, Any]) -> bool:
+        headers = self._normalized_headers(context)
+        value = headers.get("x-rpc-safe-enabled", headers.get("x-rpc-safe"))
+        return str(value).lower() == "true"
+
+
+class RpcSafeEndpoint(RpcEndpoint):
+    def __init__(self, context: Any = None, **options: Any):
+        options.setdefault("safe_enabled", True)
+        options.setdefault("strict_mode", True)
+        super().__init__(context, **options)
+

rpc_python_toolkit/errors.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+
+class RpcError(Exception):
+    """JSON-RPC error with code and optional data."""
+
+    def __init__(self, message: str, code: int = -32603, data: object = None):
+        super().__init__(message)
+        self.code = code
+        self.data = data
+
+
+class RpcRemoteError(RpcError):
+    """Error returned by a remote JSON-RPC endpoint."""
+
+

rpc_python_toolkit/protocol.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .errors import RpcError
+
+
+def has_id(request: dict[str, Any]) -> bool:
+    return "id" in request
+
+
+def make_response(
+    request_id: Any,
+    *,
+    result: Any = None,
+    error: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    response = {"jsonrpc": "2.0", "id": request_id}
+    if error is not None:
+        response["error"] = error
+    else:
+        response["result"] = result
+    return response
+
+
+def validate_request_envelope(request: Any) -> None:
+    if not isinstance(request, dict):
+        raise RpcError("Invalid Request", -32600)
+
+    if request.get("jsonrpc") != "2.0":
+        raise RpcError("Invalid JSON-RPC version", -32600)
+
+    method = request.get("method")
+    if not isinstance(method, str) or not method:
+        raise RpcError("Method not specified or invalid", -32600)
+
+    if "params" in request and not isinstance(request["params"], (dict, list)):
+        raise RpcError("Invalid params", -32602)
+
+    if "id" in request and not isinstance(request["id"], (str, int, float, type(None))):
+        raise RpcError("Invalid request id", -32600)
+

rpc_python_toolkit/serialization.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+import datetime as _dt
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import is_dataclass, asdict
+from typing import Any
+
+JS_SAFE_INTEGER_MAX = 9007199254740991
+DEFAULT_MAX_DEPTH = 100
+_BIGINT_RE = re.compile(r"^-?\d+n$")
+_ISO_DATE_RE = re.compile(
+    r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$"
+)
+
+
+def serialize_value(
+    value: Any,
+    *,
+    safe_enabled: bool = False,
+    max_depth: int = DEFAULT_MAX_DEPTH,
+    _depth: int = 0,
+    _seen: set[int] | None = None,
+) -> Any:
+    """Recursively encode values using RPC Toolkit Safe Mode conventions."""
+
+    if _depth > max_depth:
+        raise ValueError("Serialization depth limit exceeded")
+
+    seen = _seen if _seen is not None else set()
+
+    if isinstance(value, _dt.datetime):
+        text = value.isoformat()
+        return f"D:{text}" if safe_enabled else text
+
+    if isinstance(value, _dt.date):
+        text = _dt.datetime.combine(value, _dt.time()).isoformat()
+        return f"D:{text}" if safe_enabled else text
+
+    if isinstance(value, bool) or value is None:
+        return value
+
+    if isinstance(value, int):
+        if abs(value) > JS_SAFE_INTEGER_MAX:
+            return f"{value}n"
+        return value
+
+    if isinstance(value, str):
+        return f"S:{value}" if safe_enabled else value
+
+    if isinstance(value, Mapping):
+        return _serialize_mapping(value, safe_enabled, max_depth, _depth, seen)
+
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        return _serialize_sequence(value, safe_enabled, max_depth, _depth, seen)
+
+    if is_dataclass(value) and not isinstance(value, type):
+        return serialize_value(
+            asdict(value),
+            safe_enabled=safe_enabled,
+            max_depth=max_depth,
+            _depth=_depth + 1,
+            _seen=seen,
+        )
+
+    return value
+
+
+def deserialize_value(
+    value: Any,
+    *,
+    safe_enabled: bool = False,
+    max_depth: int = DEFAULT_MAX_DEPTH,
+    _depth: int = 0,
+    _seen: set[int] | None = None,
+) -> Any:
+    """Recursively decode values using RPC Toolkit Safe Mode conventions."""
+
+    if _depth > max_depth:
+        raise ValueError("Deserialization depth limit exceeded")
+
+    seen = _seen if _seen is not None else set()
+
+    if isinstance(value, str):
+        if safe_enabled and value.startswith("S:"):
+            return value[2:]
+
+        if safe_enabled and value.startswith("D:"):
+            return _parse_datetime(value[2:], fallback=value)
+
+        if _BIGINT_RE.match(value):
+            return int(value[:-1])
+
+        if not safe_enabled and _ISO_DATE_RE.match(value):
+            return _parse_datetime(value, fallback=value)
+
+        return value
+
+    if isinstance(value, Mapping):
+        return _deserialize_mapping(value, safe_enabled, max_depth, _depth, seen)
+
+    if isinstance(value, list):
+        return _deserialize_sequence(value, safe_enabled, max_depth, _depth, seen)
+
+    return value
+
+
+def _serialize_mapping(
+    value: Mapping[Any, Any],
+    safe_enabled: bool,
+    max_depth: int,
+    depth: int,
+    seen: set[int],
+) -> dict[str, Any]:
+    marker = id(value)
+    if marker in seen:
+        raise ValueError("Circular reference detected during serialization")
+
+    seen.add(marker)
+    try:
+        return {
+            str(key): serialize_value(
+                item,
+                safe_enabled=safe_enabled,
+                max_depth=max_depth,
+                _depth=depth + 1,
+                _seen=seen,
+            )
+            for key, item in value.items()
+        }
+    finally:
+        seen.remove(marker)
+
+
+def _serialize_sequence(
+    value: Sequence[Any],
+    safe_enabled: bool,
+    max_depth: int,
+    depth: int,
+    seen: set[int],
+) -> list[Any]:
+    marker = id(value)
+    if marker in seen:
+        raise ValueError("Circular reference detected during serialization")
+
+    seen.add(marker)
+    try:
+        return [
+            serialize_value(
+                item,
+                safe_enabled=safe_enabled,
+                max_depth=max_depth,
+                _depth=depth + 1,
+                _seen=seen,
+            )
+            for item in value
+        ]
+    finally:
+        seen.remove(marker)
+
+
+def _deserialize_mapping(
+    value: Mapping[Any, Any],
+    safe_enabled: bool,
+    max_depth: int,
+    depth: int,
+    seen: set[int],
+) -> dict[str, Any]:
+    marker = id(value)
+    if marker in seen:
+        raise ValueError("Circular reference detected during deserialization")
+
+    seen.add(marker)
+    try:
+        return {
+            str(key): deserialize_value(
+                item,
+                safe_enabled=safe_enabled,
+                max_depth=max_depth,
+                _depth=depth + 1,
+                _seen=seen,
+            )
+            for key, item in value.items()
+        }
+    finally:
+        seen.remove(marker)
+
+
+def _deserialize_sequence(
+    value: list[Any],
+    safe_enabled: bool,
+    max_depth: int,
+    depth: int,
+    seen: set[int],
+) -> list[Any]:
+    marker = id(value)
+    if marker in seen:
+        raise ValueError("Circular reference detected during deserialization")
+
+    seen.add(marker)
+    try:
+        return [
+            deserialize_value(
+                item,
+                safe_enabled=safe_enabled,
+                max_depth=max_depth,
+                _depth=depth + 1,
+                _seen=seen,
+            )
+            for item in value
+        ]
+    finally:
+        seen.remove(marker)
+
+
+def _parse_datetime(value: str, *, fallback: str) -> _dt.datetime | str:
+    try:
+        normalized = value.replace("Z", "+00:00")
+        return _dt.datetime.fromisoformat(normalized)
+    except ValueError:
+        return fallback
+

rpc_python_toolkit/validation.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Any
+
+import jsonschema
+
+from .errors import RpcError
+
+
+class SchemaValidator:
+    def validate(self, params: Any, schema: dict[str, Any] | None) -> None:
+        if not schema:
+            return
+
+        try:
+            jsonschema.validate(instance=params, schema=schema)
+        except jsonschema.ValidationError as exc:
+            raise RpcError(
+                "Validation failed",
+                -32602,
+                {
+                    "message": exc.message,
+                    "path": list(exc.path),
+                },
+            ) from exc
+

rpc_python_toolkit/version.py

@@ -0,0 +1,2 @@
+__version__ = "0.1.0"
+

rpc_python_toolkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: rpc-python-toolkit
+Version: 0.1.0
+Summary: Framework-agnostic Python JSON-RPC 2.0 toolkit with Safe Mode interoperability.
+Author: Nicola Carpanese
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/n-car/rpc-python-toolkit
+Project-URL: Repository, https://github.com/n-car/rpc-python-toolkit
+Project-URL: Issues, https://github.com/n-car/rpc-python-toolkit/issues
+Keywords: json-rpc,json-rpc-2.0,rpc,python,http,client,server,safe-mode,iot,embedded
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema>=4.0.0
+Dynamic: license-file
+
+# RPC Python Toolkit
+
+Framework-agnostic JSON-RPC 2.0 toolkit for Python.
+
+Use this package when you need a small Python JSON-RPC 2.0 client/server core that can be embedded directly or adapted to HTTP frameworks. It follows the same protocol conventions used across the RPC Toolkit ecosystem.
+
+## Project Status
+
+Small early package with the core JSON-RPC behavior implemented.
+
+- Published on PyPI as `rpc-python-toolkit`.
+- Standard JSON-RPC 2.0 remains the default behavior.
+- Safe Mode follows the same `X-RPC-Safe-Enabled` and value marker conventions used by `rpc-express-toolkit`.
+- The public API may still change before a stable Python release.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install rpc-python-toolkit
+```
+
+For development snapshots, install from GitHub or from a local checkout:
+
+```bash
+pip install git+https://github.com/n-car/rpc-python-toolkit.git
+```
+
+For local development:
+
+```bash
+pip install -e .
+python -m unittest discover
+```
+
+## What Is Implemented
+
+- Framework-independent `RpcEndpoint`
+- Standard JSON-RPC calls, notifications, and batch requests
+- `RpcClient` and `RpcSafeClient` over HTTP using Python standard library
+- JSON Schema validation through `jsonschema`
+- Optional RPC Toolkit Safe Mode over HTTP headers
+- Method introspection with `__rpc.*` methods
+
+## What Is Not Implemented Yet
+
+- Built-in ASGI/WSGI adapters for FastAPI, Starlette, Flask, or Django
+- Async endpoint handlers
+- OpenRPC export
+- Built-in HTTP server adapters
+
+## Quick Start
+
+```python
+from rpc_python_toolkit import RpcEndpoint
+
+rpc = RpcEndpoint(enable_introspection=True)
+
+def test(request, context, params):
+    return {"ok": True, "params": params}
+
+rpc.add_method("test", test)
+
+response = rpc.handle_payload({
+    "jsonrpc": "2.0",
+    "method": "test",
+    "params": {"value": 123},
+    "id": 1,
+})
+
+print(response.body)
+```
+
+Result:
+
+```json
+{"jsonrpc": "2.0", "id": 1, "result": {"ok": true, "params": {"value": 123}}}
+```
+
+## HTTP Client
+
+```python
+from rpc_python_toolkit import RpcClient
+
+client = RpcClient("http://localhost:3000/api")
+result = client.call("test", {"value": 123})
+```
+
+## Safe Mode
+
+Use `RpcSafeEndpoint` and `RpcSafeClient` when both sides support RPC Toolkit Safe Mode:
+
+```python
+from rpc_python_toolkit import RpcSafeEndpoint, RpcSafeClient
+
+rpc = RpcSafeEndpoint()
+client = RpcSafeClient("http://localhost:3000/api")
+```
+
+Safe Mode enables `X-RPC-Safe-Enabled` negotiation and recursive value encoding/decoding:
+
+- strings are encoded as `S:<value>`
+- datetimes are encoded as `D:<iso-date>`
+- large integers are encoded as `<digits>n`
+
+Python exposes arbitrary precision integers as `int`. BigInt marker strings from other RPC Toolkit implementations are decoded to Python `int` values when they are real markers, while literal marker-like strings are protected by the `S:` prefix in Safe Mode.
+
+## Examples
+
+Runnable examples are available in [`examples/`](examples/):
+
+- [`basic_server.py`](examples/basic_server.py) - direct endpoint usage without an HTTP adapter.
+- [`basic_client.py`](examples/basic_client.py) - standard HTTP client call against an in-process endpoint.
+- [`schema_validation.py`](examples/schema_validation.py) - method schema validation and JSON-RPC error output.
+- [`safe_mode.py`](examples/safe_mode.py) - `RpcSafeClient` to `RpcSafeEndpoint` round-trip for strings, dates, and large integers.
+
+For local checkout usage:
+
+```bash
+PYTHONPATH=src python3 examples/basic_server.py
+PYTHONPATH=src python3 examples/basic_client.py
+PYTHONPATH=src python3 examples/schema_validation.py
+PYTHONPATH=src python3 examples/safe_mode.py
+```
+
+## Related Projects
+
+- [rpc-express-toolkit](https://github.com/n-car/rpc-express-toolkit)
+- [rpc-node-toolkit](https://github.com/n-car/rpc-node-toolkit)
+- [rpc-toolkit-js-client](https://github.com/n-car/rpc-toolkit-js-client)
+- [rpc-dotnet-toolkit](https://github.com/n-car/rpc-dotnet-toolkit)
+- [rpc-java-toolkit](https://github.com/n-car/rpc-java-toolkit)
+- [rpc-php-toolkit](https://github.com/n-car/rpc-php-toolkit)
+- [rpc-arduino-toolkit](https://github.com/n-car/rpc-arduino-toolkit)
+- [node-red-contrib-rpc-toolkit](https://github.com/n-car/node-red-contrib-rpc-toolkit)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

rpc_python_toolkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+rpc_python_toolkit/__init__.py,sha256=ph_tY5IvR-ihwa9ubr-vKWIhS4ru73RmHVbRjt-7YME,477
+rpc_python_toolkit/client.py,sha256=QD3vf8OSdDe42522nwWEy2gEyNAjNJzayezvqN6jP5A,5276
+rpc_python_toolkit/endpoint.py,sha256=vMizSI0lQH2HpocWyZS4238NE2wK2peQmkjSvYArVXo,10867
+rpc_python_toolkit/errors.py,sha256=en8mmO56IeT8OfRCTheMxNOUN09RpdLqR8X4BQTB6gk,374
+rpc_python_toolkit/protocol.py,sha256=MMQ1tF1waizZ0dlq3LZc_Dx9tVN00KFLaWh70wR9g7A,1145
+rpc_python_toolkit/serialization.py,sha256=gWI0UyxzNj-EATaBkSG9i-b-De-bH49igqBmzkfE9fM,5755
+rpc_python_toolkit/validation.py,sha256=MXibLokBpBq_mDo7yxZ_64S6Mc_S1LWPM6UYsdxTXZg,617
+rpc_python_toolkit/version.py,sha256=p4MxVO8ih2-hnh7INVBkrqMKBDGTkMso1LEbM6mx3jg,23
+rpc_python_toolkit-0.1.0.dist-info/licenses/LICENSE,sha256=-JOXJbeUglpNN6FaH-5OkUacdU1e8cXsttGJxO8EAAY,1074
+rpc_python_toolkit-0.1.0.dist-info/METADATA,sha256=6SM4BQFhVt9QUCPJmp3k20qKy5Zcugd0hEhYQPPkm08,5317
+rpc_python_toolkit-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+rpc_python_toolkit-0.1.0.dist-info/top_level.txt,sha256=KeHhMmqjDgfOlP13qPd9_FhW3vXFe2xTL3HzuDAqiv4,19
+rpc_python_toolkit-0.1.0.dist-info/RECORD,,

rpc_python_toolkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rpc_python_toolkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Nicola Carpanese
+
+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.
+

rpc_python_toolkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rpc_python_toolkit