python-jsonrpc-lib 0.3.1__tar.gz

python_jsonrpc_lib-0.3.1/.claude/skills/jsonrpc-lib/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: python-jsonrpc-lib
+description: Use when writing code that uses the python-jsonrpc-lib library — creating RPC methods, registering them, organizing with groups, handling errors, or adding context and middleware.
+user-invocable: false
+---
+
+# python-jsonrpc-lib usage guide
+
+## Always use Method classes
+
+**Never use the `@rpc.method` decorator** unless explicitly prototyping. It has no context, no middleware, no MethodGroup support, and is unsuitable for production. Default to `Method` subclasses:
+
+```python
+from dataclasses import dataclass
+from jsonrpc import JSONRPC, Method
+
+@dataclass
+class AddParams:
+    a: int
+    b: int
+
+@dataclass
+class AddResult:
+    sum: int
+
+class Add(Method):
+    def execute(self, params: AddParams) -> AddResult:
+        return AddResult(sum=params.a + params.b)
+
+rpc = JSONRPC(version='2.0')
+rpc.register('add', Add())
+
+response = rpc.handle('{"jsonrpc":"2.0","method":"add","params":{"a":1,"b":2},"id":1}')
+# '{"jsonrpc": "2.0", "result": {"sum": 3}, "id": 1}'
+```
+
+## execute() rules
+
+- `params` type **must be a dataclass** — never `dict`, `list`, or `TypedDict`
+- `params` is always the second parameter and must be named `params` exactly
+- Return type annotation is **required**
+- For structured return values, **prefer a dataclass** over returning a raw dict
+- Optional third parameter `context: ContextType` for per-request data
+
+```python
+# Wrong — TypeError at class definition time
+class Bad(Method):
+    def execute(self, params: dict) -> dict:
+        return {"result": params["x"]}
+
+# Wrong — no return type
+class AlsoBad(Method):
+    def execute(self, params: SomeParams):
+        return 42
+
+# Correct
+@dataclass
+class SomeParams:
+    x: int
+
+@dataclass
+class SomeResult:
+    value: int
+    label: str
+
+class Good(Method):
+    def execute(self, params: SomeParams) -> SomeResult:
+        return SomeResult(value=params.x * 2, label="doubled")
+```
+
+## MethodGroup — namespacing and middleware
+
+`MethodGroup()` takes no arguments. Name is set during registration.
+Always pass an **instance**, not a class.
+
+```python
+from jsonrpc import JSONRPC, Method, MethodGroup
+
+math = MethodGroup()
+math.register('add', Add())      # instance, not Add
+math.register('subtract', Sub())
+
+rpc = JSONRPC(version='2.0')
+rpc.register('math', math)
+# Available: "math.add", "math.subtract"
+
+# Nested groups
+admin = MethodGroup()
+users = MethodGroup()
+users.register('create', CreateUser())
+admin.register('users', users)
+rpc.register('admin', admin)
+# Available: "admin.users.create"
+```
+
+## Context — per-request data
+
+```python
+from dataclasses import dataclass
+from jsonrpc import JSONRPC, Method, JSONRPCError
+
+@dataclass
+class AuthContext:
+    user_id: int
+    is_admin: bool
+
+@dataclass
+class DeleteParams:
+    resource_id: int
+
+class DeleteResource(Method):
+    def execute(self, params: DeleteParams, context: AuthContext) -> str:
+        if not context.is_admin:
+            raise JSONRPCError("Forbidden", code=-32000)
+        return f"deleted {params.resource_id}"
+
+rpc = JSONRPC(version='2.0', context_type=AuthContext)
+rpc.register('delete', DeleteResource())
+
+ctx = AuthContext(user_id=42, is_admin=True)
+response = rpc.handle(json_string, context=ctx)
+```
+
+## Middleware via MethodGroup
+
+Override `execute_method()` to add cross-cutting behavior:
+
+```python
+import time
+from jsonrpc import MethodGroup
+
+class TimingGroup(MethodGroup):
+    def execute_method(self, method, params, context=None):
+        start = time.time()
+        result = super().execute_method(method, params, context)
+        print(f"{method.__class__.__name__}: {time.time() - start:.4f}s")
+        return result
+
+group = TimingGroup()
+group.register('add', Add())
+```
+
+## Async
+
+```python
+class AsyncFetch(Method):
+    async def execute(self, params: FetchParams) -> FetchResult:
+        data = await some_async_call(params.url)
+        return FetchResult(data=data)
+
+response = await rpc.handle_async(json_string)
+response = await rpc.handle_async(json_string, context=ctx)
+```
+
+## Errors
+
+Raise from inside `execute()` to return a JSON-RPC error response:
+
+```python
+from jsonrpc import JSONRPCError, ServerError
+
+raise JSONRPCError("Something failed")            # -32603 InternalError
+raise ServerError("Rate limit exceeded", code=-32029)  # implementation-defined
+```
+
+Error classes and their codes:
+
+| Code | Class |
+|------|-------|
+| -32700 | `ParseError` |
+| -32600 | `InvalidRequestError` |
+| -32601 | `MethodNotFoundError` |
+| -32602 | `InvalidParamsError` |
+| -32603 | `InternalError` |
+| -32001 | `InvalidResultError` |
+| -32000 to -32099 | `ServerError` |
+
+## OpenAPI generation
+
+```python
+from jsonrpc import JSONRPC, OpenAPIGenerator
+
+generator = OpenAPIGenerator(rpc, title='My API', version='1.0.0')
+spec = generator.generate()  # OpenAPI 3.0 dict
+```
+
+Docstrings on `execute()` become method descriptions. Dataclass fields become parameters. Optional fields (with defaults) are marked not-required automatically.
+
+## Common mistakes
+
+| Wrong | Right |
+|-------|-------|
+| `group.register(MyMethod)` | `group.register('name', MyMethod())` |
+| `MethodGroup(prefix='math')` | `MethodGroup()` — no arguments |
+| `params: dict` or `params: list` | `params: MyDataclass` |
+| No return type annotation | `-> MyResult:` required |
+| `rpc.handle(data_dict)` | `rpc.handle(json_string)` — JSON string only |
+| `def execute(self, data: Params)` | `def execute(self, params: Params)` — must be `params` |

python_jsonrpc_lib-0.3.1/.github/workflows/docs.yml

@@ -0,0 +1,19 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install mkdocs mkdocs-material
+      - run: mkdocs gh-deploy --force

python_jsonrpc_lib-0.3.1/.gitignore

@@ -0,0 +1,8 @@
+site
+htmlcov
+.venv
+.coverage
+.ruff_cache
+.idea
+.vscode
+__pycache__

python_jsonrpc_lib-0.3.1/LICENSE

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

python_jsonrpc_lib-0.3.1/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include src *.py
+include src/jsonrpc/py.typed

python_jsonrpc_lib-0.3.1/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: python-jsonrpc-lib
+Version: 0.3.1
+Summary: Simple, yet solid - Type-safe JSON-RPC 1.0/2.0 with OpenAPI support
+Project-URL: Homepage, https://github.com/uandysmith/python-jsonrpc-lib
+Project-URL: Documentation, https://uandysmith.github.io/python-jsonrpc-lib/
+Project-URL: Repository, https://github.com/uandysmith/python-jsonrpc-lib
+Project-URL: Issues, https://github.com/uandysmith/python-jsonrpc-lib/issues
+Author: Andy Smith
+License: MIT
+License-File: LICENSE
+Keywords: dataclass,json-rpc,jsonrpc,protocol,rpc,validation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: ruff>=0.15.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# python-jsonrpc-lib
+
+**Simple, yet solid.** JSON-RPC 1.0/2.0 for Python.
+
+JSON-RPC is a small protocol: a method name, some parameters, a result. python-jsonrpc-lib keeps it that way. You write ordinary Python functions and dataclasses; the library handles validation, routing, error responses, and API documentation. No framework lock-in, no external dependencies, no boilerplate.
+
+## Install
+
+```bash
+pip install python-jsonrpc-lib
+```
+
+## Quickstart
+
+Define methods as classes with typed parameters. The library validates inputs, routes calls, and builds responses automatically.
+
+```python
+from dataclasses import dataclass
+from jsonrpc import JSONRPC, Method, MethodGroup
+
+@dataclass
+class AddParams:
+    a: int
+    b: int
+
+class Add(Method):
+    def execute(self, params: AddParams) -> int:
+        return params.a + params.b
+
+@dataclass
+class GreetParams:
+    name: str
+    greeting: str = 'Hello'
+
+class Greet(Method):
+    def execute(self, params: GreetParams) -> str:
+        return f'{params.greeting}, {params.name}!'
+
+rpc = JSONRPC(version='2.0')
+rpc.register('add', Add())
+rpc.register('greet', Greet())
+
+response = rpc.handle('{"jsonrpc": "2.0", "method": "add", "params": {"a": 5, "b": 3}, "id": 1}')
+# '{"jsonrpc": "2.0", "result": 8, "id": 1}'
+```
+
+Pass in a JSON string, get a JSON string back. What carries it over the wire is up to you.
+
+If `a` is `"five"` instead of `5`, the caller receives a `-32602 Invalid params` error immediately — no exception handling on your end.
+
+The same `AddParams` dataclass drives validation, IDE autocomplete, and the OpenAPI schema.
+
+## Why python-jsonrpc-lib?
+
+- **Zero dependencies** — pure Python 3.11+. Nothing to pin, nothing to audit beyond the library itself.
+- **Type validation from dataclasses** — declare parameters as a dataclass, get automatic validation and clear error messages for free.
+- **OpenAPI docs auto-generated** — type hints and docstrings you already wrote become a full OpenAPI 3.0 spec. Point any Swagger-compatible UI at it and your API is self-documented.
+- **Transport-agnostic** — `rpc.handle(json_string)` returns a string. HTTP, WebSocket, TCP, message queue: your choice.
+- **Spec-compliant by default** — v1.0 and v2.0 rules enforced out of the box, configurable when you need to support legacy clients.
+
+## Namespacing and Middleware
+
+Use `MethodGroup` to organize methods into namespaces and add cross-cutting concerns:
+
+```python
+math = MethodGroup()
+math.register('add', Add())
+
+rpc = JSONRPC(version='2.0')
+rpc.register('math', math)
+
+# "math.add" is now available
+```
+
+## Quick Prototyping
+
+For scripts and throwaway code, the `@rpc.method` decorator registers functions directly (v2.0 only):
+
+```python
+rpc = JSONRPC(version='2.0')
+
+@rpc.method
+def add(a: int, b: int) -> int:
+    return a + b
+```
+
+For production use, prefer `Method` classes — they support context, middleware, and groups.
+
+## Documentation
+
+Full documentation with tutorials, integration guides, and API reference:
+
+- [Tutorial: Hello World](docs/tutorial/01-hello-world.md) — first method, explained
+- [Tutorial: Parameters](docs/tutorial/03-parameters.md) — dataclass validation in detail
+- [Tutorial: Context](docs/tutorial/05-context.md) — authentication and per-request data
+- [Tutorial: OpenAPI](docs/tutorial/07-openapi.md) — interactive API documentation
+- [Flask integration](docs/integrations/flask.md)
+- [FastAPI integration](docs/integrations/fastapi.md)
+- [Philosophy](docs/philosophy.md) — design decisions and trade-offs
+- [API Reference](docs/api-reference.md)
+
+## Claude Code Integration
+
+If you use [Claude Code](https://claude.ai/claude-code), a skill for this library is available. It gives Claude built-in knowledge of jsonrpc-lib's API: creating methods, registering them, organizing with groups, handling errors, and adding context and middleware — without having to look up docs.
+
+To use it, add the skill file to your project's `.claude/skills/` directory.
+
+## License
+
+MIT

python_jsonrpc_lib-0.3.1/README.md

@@ -0,0 +1,110 @@
+# python-jsonrpc-lib
+
+**Simple, yet solid.** JSON-RPC 1.0/2.0 for Python.
+
+JSON-RPC is a small protocol: a method name, some parameters, a result. python-jsonrpc-lib keeps it that way. You write ordinary Python functions and dataclasses; the library handles validation, routing, error responses, and API documentation. No framework lock-in, no external dependencies, no boilerplate.
+
+## Install
+
+```bash
+pip install python-jsonrpc-lib
+```
+
+## Quickstart
+
+Define methods as classes with typed parameters. The library validates inputs, routes calls, and builds responses automatically.
+
+```python
+from dataclasses import dataclass
+from jsonrpc import JSONRPC, Method, MethodGroup
+
+@dataclass
+class AddParams:
+    a: int
+    b: int
+
+class Add(Method):
+    def execute(self, params: AddParams) -> int:
+        return params.a + params.b
+
+@dataclass
+class GreetParams:
+    name: str
+    greeting: str = 'Hello'
+
+class Greet(Method):
+    def execute(self, params: GreetParams) -> str:
+        return f'{params.greeting}, {params.name}!'
+
+rpc = JSONRPC(version='2.0')
+rpc.register('add', Add())
+rpc.register('greet', Greet())
+
+response = rpc.handle('{"jsonrpc": "2.0", "method": "add", "params": {"a": 5, "b": 3}, "id": 1}')
+# '{"jsonrpc": "2.0", "result": 8, "id": 1}'
+```
+
+Pass in a JSON string, get a JSON string back. What carries it over the wire is up to you.
+
+If `a` is `"five"` instead of `5`, the caller receives a `-32602 Invalid params` error immediately — no exception handling on your end.
+
+The same `AddParams` dataclass drives validation, IDE autocomplete, and the OpenAPI schema.
+
+## Why python-jsonrpc-lib?
+
+- **Zero dependencies** — pure Python 3.11+. Nothing to pin, nothing to audit beyond the library itself.
+- **Type validation from dataclasses** — declare parameters as a dataclass, get automatic validation and clear error messages for free.
+- **OpenAPI docs auto-generated** — type hints and docstrings you already wrote become a full OpenAPI 3.0 spec. Point any Swagger-compatible UI at it and your API is self-documented.
+- **Transport-agnostic** — `rpc.handle(json_string)` returns a string. HTTP, WebSocket, TCP, message queue: your choice.
+- **Spec-compliant by default** — v1.0 and v2.0 rules enforced out of the box, configurable when you need to support legacy clients.
+
+## Namespacing and Middleware
+
+Use `MethodGroup` to organize methods into namespaces and add cross-cutting concerns:
+
+```python
+math = MethodGroup()
+math.register('add', Add())
+
+rpc = JSONRPC(version='2.0')
+rpc.register('math', math)
+
+# "math.add" is now available
+```
+
+## Quick Prototyping
+
+For scripts and throwaway code, the `@rpc.method` decorator registers functions directly (v2.0 only):
+
+```python
+rpc = JSONRPC(version='2.0')
+
+@rpc.method
+def add(a: int, b: int) -> int:
+    return a + b
+```
+
+For production use, prefer `Method` classes — they support context, middleware, and groups.
+
+## Documentation
+
+Full documentation with tutorials, integration guides, and API reference:
+
+- [Tutorial: Hello World](docs/tutorial/01-hello-world.md) — first method, explained
+- [Tutorial: Parameters](docs/tutorial/03-parameters.md) — dataclass validation in detail
+- [Tutorial: Context](docs/tutorial/05-context.md) — authentication and per-request data
+- [Tutorial: OpenAPI](docs/tutorial/07-openapi.md) — interactive API documentation
+- [Flask integration](docs/integrations/flask.md)
+- [FastAPI integration](docs/integrations/fastapi.md)
+- [Philosophy](docs/philosophy.md) — design decisions and trade-offs
+- [API Reference](docs/api-reference.md)
+
+## Claude Code Integration
+
+If you use [Claude Code](https://claude.ai/claude-code), a skill for this library is available. It gives Claude built-in knowledge of jsonrpc-lib's API: creating methods, registering them, organizing with groups, handling errors, and adding context and middleware — without having to look up docs.
+
+To use it, add the skill file to your project's `.claude/skills/` directory.
+
+## License
+
+MIT