rpc-python-toolkit 0.1.0__tar.gz

rpc_python_toolkit-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,140 @@
+# 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/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rpc-python-toolkit"
+version = "0.1.0"
+description = "Framework-agnostic Python JSON-RPC 2.0 toolkit with Safe Mode interoperability."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "Nicola Carpanese" }
+]
+keywords = [
+  "json-rpc",
+  "json-rpc-2.0",
+  "rpc",
+  "python",
+  "http",
+  "client",
+  "server",
+  "safe-mode",
+  "iot",
+  "embedded"
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Software Development :: Libraries"
+]
+dependencies = [
+  "jsonschema>=4.0.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/n-car/rpc-python-toolkit"
+Repository = "https://github.com/n-car/rpc-python-toolkit"
+Issues = "https://github.com/n-car/rpc-python-toolkit/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

rpc_python_toolkit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rpc_python_toolkit-0.1.0/src/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-0.1.0/src/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)