python-jsonrpc-lib 0.3.1__py3-none-any.whl

jsonrpc/response.py

@@ -0,0 +1,169 @@
+"""Response building and parsing for JSON-RPC protocol."""
+
+import json
+from dataclasses import asdict, is_dataclass
+from typing import Any
+
+from .errors import (
+    InvalidRequestError,
+    JSONRPCError,
+    ParseError,
+    RPCError,
+)
+from .types import ErrorResponse, Response, Version
+
+
+def _dataclass_to_dict(value: Any) -> Any:
+    """Convert dataclass instances to dicts recursively for JSON serialization.
+
+    Args:
+        value: Any value (dataclass, list, dict, or primitive)
+
+    Returns:
+        Value with all dataclasses converted to dicts
+    """
+    if is_dataclass(value) and not isinstance(value, type):
+        return asdict(value)
+
+    if isinstance(value, list):
+        return [_dataclass_to_dict(item) for item in value]
+
+    if isinstance(value, dict):
+        return {key: _dataclass_to_dict(val) for key, val in value.items()}
+
+    return value
+
+
+def build_response(
+    result: Any,
+    id: str | int,
+    version: Version = '2.0',
+) -> dict[str, Any]:
+    """Build a JSON-RPC success response dict.
+
+    Args:
+        result: Method result (can be dataclass, which will be converted to dict)
+        id: Request ID
+        version: Protocol version
+
+    Returns:
+        Response dict ready for JSON serialization
+    """
+    if version == '2.0':
+        return {
+            'jsonrpc': '2.0',
+            'result': result,
+            'id': id,
+        }
+    else:
+        # v1: always has both result and error fields
+        return {
+            'result': result,
+            'error': None,
+            'id': id,
+        }
+
+
+def build_error_response(
+    error: JSONRPCError | RPCError,
+    id: str | int | None,
+    version: Version = '2.0',
+) -> dict[str, Any]:
+    """Build a JSON-RPC error response dict.
+
+    Args:
+        error: Error object or exception
+        id: Request ID (can be None for parse errors)
+        version: Protocol version
+
+    Returns:
+        Error response dict ready for JSON serialization
+    """
+    error_dict = error.to_dict()
+
+    if version == '2.0':
+        return {
+            'jsonrpc': '2.0',
+            'error': error_dict,
+            'id': id,
+        }
+    else:
+        # v1: always has both result and error fields
+        return {
+            'result': None,
+            'error': error_dict,
+            'id': id,
+        }
+
+
+def parse_response(
+    data: str | bytes | dict[str, Any],
+) -> Response | ErrorResponse:
+    """Parse JSON-RPC response (for client-side usage).
+
+    Args:
+        data: JSON string, bytes, or already parsed dict
+
+    Returns:
+        Response or ErrorResponse object
+
+    Raises:
+        ParseError: If JSON is invalid
+        InvalidRequestError: If response structure is invalid
+    """
+    if isinstance(data, (str, bytes)):
+        try:
+            parsed = json.loads(data)
+        except json.JSONDecodeError as e:
+            raise ParseError(f'Invalid JSON: {e}') from e
+    else:
+        parsed = data
+
+    if not isinstance(parsed, dict):
+        raise InvalidRequestError(f'Response must be object, got {type(parsed).__name__}')
+
+    if 'jsonrpc' in parsed:
+        if parsed['jsonrpc'] != '2.0':
+            raise InvalidRequestError(f'Invalid jsonrpc version: {parsed["jsonrpc"]!r}')
+        version: Version = '2.0'
+    else:
+        version = '1.0'
+
+    response_id = parsed.get('id')
+
+    if 'error' in parsed and parsed['error'] is not None:
+        error_data = parsed['error']
+        if not isinstance(error_data, dict):
+            raise InvalidRequestError(f"Field 'error' must be object, got {type(error_data).__name__}")
+
+        code = error_data.get('code')
+        if not isinstance(code, int):
+            raise InvalidRequestError(f"Error 'code' must be integer, got {type(code).__name__}")
+
+        message = error_data.get('message', '')
+        if not isinstance(message, str):
+            raise InvalidRequestError(f"Error 'message' must be string, got {type(message).__name__}")
+
+        error = RPCError(
+            code=code,
+            message=message,
+            data=error_data.get('data'),
+        )
+
+        return ErrorResponse(
+            error=error,
+            id=response_id,
+            version=version,
+        )
+
+    if 'result' not in parsed:
+        raise InvalidRequestError("Response must have 'result' or 'error' field")
+
+    if response_id is None:
+        raise InvalidRequestError("Success response must have 'id' field")
+
+    return Response(
+        result=parsed['result'],
+        id=response_id,
+        version=version,
+    )

jsonrpc/types.py

@@ -0,0 +1,53 @@
+"""Core type definitions for JSON-RPC protocol."""
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from .errors import RPCError
+
+Version = Literal['1.0', '2.0']
+
+
+@dataclass
+class Request:
+    """JSON-RPC request object."""
+
+    method: str
+    params: list[Any] | dict[str, Any] | None
+    id: str | int | None
+    version: Version
+    id_was_present: bool = True
+
+    @property
+    def is_notification(self) -> bool:
+        """Check if this request is a notification (no response expected).
+
+        JSON-RPC 2.0: notification when id field is missing (not just null).
+        JSON-RPC 1.0: NO notifications - all requests get responses.
+
+        Note: v2.0 distinguishes:
+            - Missing id field → notification (no response)
+            - id=null → normal request (returns response with id=null)
+        """
+        if self.version == '2.0':
+            return not self.id_was_present
+        else:
+            return False
+
+
+@dataclass
+class Response:
+    """JSON-RPC success response object."""
+
+    result: Any
+    id: str | int
+    version: Version
+
+
+@dataclass
+class ErrorResponse:
+    """JSON-RPC error response object."""
+
+    error: RPCError
+    id: str | int | None
+    version: Version

jsonrpc/validation.py

@@ -0,0 +1,297 @@
+"""Type validation, conversion, and utility functions for JSON-RPC."""
+
+import types
+from dataclasses import MISSING, fields, is_dataclass
+from typing import (
+    Any,
+    Literal,
+    Union,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from .errors import InvalidParamsError, InvalidResultError
+
+MAX_NESTING_DEPTH = 64
+
+# Cache for dataclass introspection data: type_hints, field_list, field_names, required_fields
+_params_type_cache: dict[type, tuple[dict[str, Any], tuple[Any, ...], list[str], list[str]]] = {}
+
+
+def _get_params_type_info(params_type: type) -> tuple[dict[str, Any], tuple[Any, ...], list[str], list[str]]:
+    """Get cached introspection data for a params dataclass type."""
+    info = _params_type_cache.get(params_type)
+    if info is not None:
+        return info
+    type_hints = get_type_hints(params_type)
+    field_list = fields(params_type)
+    field_names = [f.name for f in field_list]
+    required_fields = [f.name for f in field_list if f.default is MISSING and f.default_factory is MISSING]
+    info = (type_hints, field_list, field_names, required_fields)
+    _params_type_cache[params_type] = info
+    return info
+
+
+def is_batch(data: Any) -> bool:
+    """Check if data represents a batch request.
+
+    Args:
+        data: Parsed JSON data
+
+    Returns:
+        True if data is a list (batch request)
+    """
+    return isinstance(data, list)
+
+
+def _type_name(t: type) -> str:
+    """Get human-readable name for a type."""
+    origin = get_origin(t)
+    if origin is Union:
+        args = get_args(t)
+        # Handle Optional (T | None)
+        if len(args) == 2 and type(None) in args:
+            other = args[0] if args[1] is type(None) else args[1]
+            return f'{_type_name(other)} | None'
+        return ' | '.join(_type_name(a) for a in args)
+    if origin is list:
+        args = get_args(t)
+        if args:
+            return f'list[{_type_name(args[0])}]'
+        return 'list'
+    if origin is dict:
+        args = get_args(t)
+        if args:
+            return f'dict[{_type_name(args[0])}, {_type_name(args[1])}]'
+        return 'dict'
+    if origin is Literal:
+        args = get_args(t)
+        return f'Literal{list(args)}'
+    if hasattr(t, '__name__'):
+        return t.__name__
+    return str(t)
+
+
+def _check_type(value: Any, expected_type: type) -> bool:
+    """Check if value matches expected type.
+
+    Args:
+        value: Value to check
+        expected_type: Expected type annotation
+
+    Returns:
+        True if value matches type, False otherwise
+    """
+    if value is None:
+        origin = get_origin(expected_type)
+        # Check for Union (typing.Union) or UnionType (T | None syntax)
+        if origin is Union or isinstance(expected_type, types.UnionType):
+            return type(None) in get_args(expected_type)
+        return expected_type is type(None)
+
+    origin = get_origin(expected_type)
+
+    if origin is Union or isinstance(expected_type, types.UnionType):
+        args = get_args(expected_type)
+        return any(_check_type(value, arg) for arg in args)
+
+    if origin is Literal:
+        return value in get_args(expected_type)
+
+    if origin is list:
+        if not isinstance(value, list):
+            return False
+        args = get_args(expected_type)
+        if args:
+            item_type = args[0]
+            return all(_check_type(item, item_type) for item in value)
+        return True
+
+    if origin is dict:
+        if not isinstance(value, dict):
+            return False
+        args = get_args(expected_type)
+        if args:
+            key_type, val_type = args
+            return all(_check_type(k, key_type) and _check_type(v, val_type) for k, v in value.items())
+        return True
+
+    if expected_type is Any:
+        return True
+
+    if expected_type is int:
+        # int should not match bool (bool is subclass of int)
+        return isinstance(value, int) and not isinstance(value, bool)
+    if expected_type is float:
+        # float accepts int values
+        return isinstance(value, (int, float)) and not isinstance(value, bool)
+    if expected_type is bool:
+        return isinstance(value, bool)
+    if expected_type is str:
+        return isinstance(value, str)
+
+    if is_dataclass(expected_type) and isinstance(expected_type, type):
+        # Accept both dict (named params) and list (positional params)
+        return isinstance(value, (dict, list))  # Will be converted
+
+    try:
+        return isinstance(value, expected_type)
+    except TypeError:
+        raise InvalidParamsError(
+            f"Cannot validate type '{_type_name(expected_type)}' for value of type '{type(value).__name__}'. "
+            f'Unsupported type annotation.'
+        )
+
+
+def validate_params(
+    params: list[Any] | dict[str, Any] | None,
+    params_type: type | None,
+    _depth: int = 0,
+) -> Any:
+    """Validate and convert params to dataclass instance.
+
+    Args:
+        params: Raw params from JSON-RPC request
+        params_type: Target dataclass type (or None for no-params methods)
+        _depth: Internal recursion depth counter (do not set manually)
+
+    Returns:
+        Validated dataclass instance, or None if params_type is None
+
+    Raises:
+        InvalidParamsError: With descriptive message on validation failure
+    """
+    if _depth > MAX_NESTING_DEPTH:
+        raise InvalidParamsError(f'Maximum nesting depth ({MAX_NESTING_DEPTH}) exceeded')
+
+    if params_type is None or params_type is type(None):
+        if params is not None and params != [] and params != {}:
+            raise InvalidParamsError(f'Method accepts no parameters, but received: {params}')
+        return None
+
+    if not is_dataclass(params_type):
+        raise InvalidParamsError(f'params_type must be a dataclass, got {type(params_type).__name__}')
+
+    type_hints, field_list, field_names, required_fields = _get_params_type_info(params_type)
+
+    if params is None:
+        if required_fields:
+            raise InvalidParamsError(f'Missing required parameters: {required_fields}')
+        return params_type()
+
+    if isinstance(params, list):
+        if len(params) > len(field_names):
+            raise InvalidParamsError(f'Too many positional parameters: expected {len(field_names)}, got {len(params)}')
+        params = dict(zip(field_names, params))
+
+    if not isinstance(params, dict):
+        raise InvalidParamsError(f'Parameters must be object or array, got {type(params).__name__}')
+
+    for field_name in params:
+        if field_name not in type_hints:
+            raise InvalidParamsError(f"Unknown parameter: '{field_name}'")
+
+    for field_name, value in params.items():
+        expected_type = type_hints[field_name]
+        if not _check_type(value, expected_type):
+            raise InvalidParamsError(
+                f"Parameter '{field_name}' expected type '{_type_name(expected_type)}', got '{type(value).__name__}'"
+            )
+
+    for f in field_list:
+        if f.name not in params:
+            if f.default is MISSING and f.default_factory is MISSING:
+                raise InvalidParamsError(f"Missing required parameter: '{f.name}'")
+
+    converted_params = {}
+    for field_name, value in params.items():
+        expected_type = type_hints[field_name]
+        converted_params[field_name] = _convert_value(value, expected_type, _depth=_depth)
+
+    return params_type(**converted_params)
+
+
+def _convert_value(value: Any, expected_type: type, _depth: int = 0) -> Any:
+    """Convert value to expected type, handling nested dataclasses."""
+    if value is None:
+        return None
+
+    origin = get_origin(expected_type)
+
+    if origin is Union or isinstance(expected_type, types.UnionType):
+        args = get_args(expected_type)
+        # Try non-None types first
+        for arg in args:
+            if arg is not type(None):
+                try:
+                    return _convert_value(value, arg, _depth=_depth)
+                except (TypeError, ValueError):
+                    continue
+        return value
+
+    if origin is list and isinstance(value, list):
+        args = get_args(expected_type)
+        if args:
+            item_type = args[0]
+            return [_convert_value(item, item_type, _depth=_depth) for item in value]
+        return value
+
+    if origin is dict and isinstance(value, dict):
+        args = get_args(expected_type)
+        if args and len(args) == 2:
+            val_type = args[1]
+            return {k: _convert_value(v, val_type, _depth=_depth) for k, v in value.items()}
+        return value
+
+    if is_dataclass(expected_type) and isinstance(expected_type, type):
+        if isinstance(value, (dict, list)):
+            # Recursively validate nested dataclass
+            return validate_params(value, expected_type, _depth=_depth + 1)
+
+    return value
+
+
+def validate_result_type(result: Any, result_type: type) -> None:
+    """Validate that result matches expected type.
+
+    Args:
+        result: Actual return value from execute()
+        result_type: Expected type (basic type or dataclass)
+
+    Raises:
+        InvalidResultError: If result doesn't match expected type
+    """
+    if not _check_type(result, result_type):
+        raise InvalidResultError(f"Expected return type '{_type_name(result_type)}', got '{type(result).__name__}'")
+
+
+def _unwrap_optional(type_hint: type) -> type:
+    """Unwrap Optional[T] or T | None to T.
+
+    For params, we want the actual type, not Optional wrapper.
+
+    Args:
+        type_hint: Type annotation that may be Optional
+
+    Returns:
+        Unwrapped type (T from Optional[T] or T | None)
+
+    Examples:
+        Optional[AddParams] -> AddParams
+        AddParams | None -> AddParams
+        AddParams -> AddParams
+        None -> type(None)
+    """
+    origin = get_origin(type_hint)
+
+    # Handle Union types (including T | None syntax)
+    if origin is Union or isinstance(type_hint, types.UnionType):
+        args = get_args(type_hint)
+
+        # If it's a 2-arg Union with None, return the non-None type
+        if len(args) == 2 and type(None) in args:
+            result: type = args[0] if args[1] is type(None) else args[1]
+            return result
+
+    return type_hint

python_jsonrpc_lib-0.3.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+jsonrpc/__init__.py,sha256=dzCKUITaRkigRAf_n84Ah_ffHgf9sGYK7Z2h9nB4-Dc,2106
+jsonrpc/errors.py,sha256=fJ1HBSKtvgSKmZym7-7BXZQfYfBhXtnRu0vXM07JKwI,3401
+jsonrpc/jsonrpc.py,sha256=Yd1mx6ftzAWV78zEKcXGXxlDje6BfignfCP8qGfltyQ,34432
+jsonrpc/method.py,sha256=aLGj3QkpckEoGQT5PPt6hgSHWKoLBQjwjMwZXkIWsdg,20245
+jsonrpc/openapi.py,sha256=gPnjNmcum7seZ_QtVWHaNsqQ3DYGHS1l46v461tRMcQ,16455
+jsonrpc/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+jsonrpc/request.py,sha256=ki9L0dv8H1Gxffp5OEAaWgsFHih1P476CC0OZdE33ms,5106
+jsonrpc/response.py,sha256=JPLD-xXo9SR0LtmHaa2dTn7Sp0L4H2ZvHI_eR578Uzw,4506
+jsonrpc/types.py,sha256=qk73MfkyyXMOOYmJAg6I45FZcFzDmgUQajj4eqbtiZU,1231
+jsonrpc/validation.py,sha256=zm2TAyTx8Hp3oJR77_7D9d-lRI1QD5BPlAnf3s2XCjw,10130
+python_jsonrpc_lib-0.3.1.dist-info/METADATA,sha256=merT9rsOAFkY70K8I99CH44x0E6q_oEHaXWBrEt7y-4,5326
+python_jsonrpc_lib-0.3.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+python_jsonrpc_lib-0.3.1.dist-info/licenses/LICENSE,sha256=NQXsc3PwCv4Fetw7R3qXdaoLue9xiSYf_dMAzKU2jYA,1063
+python_jsonrpc_lib-0.3.1.dist-info/RECORD,,

python_jsonrpc_lib-0.3.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any