jsonrpcserver 5.0.10__py3-none-any.whl

jsonrpcserver/main.py

@@ -0,0 +1,308 @@
+"""The dispatch functions.
+
+All three take a JSON-RPC request string, call the methods and give the response.
+They differ only in the form of the response:
+
+- dispatch_to_response gives Response objects, or None for a notification.
+- dispatch_to_serializable gives a dict or a list of dicts, or None for a
+  notification.
+- dispatch_to_json, also called dispatch, gives a JSON string, or an empty string
+  for a notification.
+"""
+
+import json
+import logging
+import pkgutil
+from typing import Any, Callable, Dict, List, Optional, Union, cast
+
+from jsonschema.validators import validator_for
+
+from .codes import ERROR_INTERNAL_ERROR
+from .dispatcher import (
+    Deserialized,
+    check_max_batch_size,
+    dispatch_to_response_pure,
+    exception_data,
+)
+
+# Importable from here in 5.0.9. The "as" form marks a re-export.
+from .methods import Methods as Methods
+from .methods import MethodsArgument, global_methods
+from .response import (
+    Response,
+    to_dict,
+)
+from .response import (
+    # Importable from here in 5.0.9. The "as" form marks it as a re-export.
+    to_serializable_one as to_serializable_one,
+)
+from .sentinels import NOCONTEXT, NODATA
+from .utils import identity
+
+logger = logging.getLogger(__name__)
+
+default_deserializer = json.loads
+
+
+def default_serializer(response: Any) -> str:
+    """json.dumps, but NaN and Infinity raise ValueError instead of producing output
+    that isn't valid JSON.
+    """
+    return json.dumps(response, allow_nan=False)
+
+
+def serialize_one(
+    serializer: Callable[[Any], str], response: Dict[str, Any], debug: bool
+) -> str:
+    """Serialize one response. If that fails, serialize an Internal error for the same
+    request instead, so the client still gets a valid JSON-RPC response.
+    """
+    try:
+        return serializer(response)
+    except Exception as exc:
+        logger.exception(
+            "Could not serialize the response for request id %r", response.get("id")
+        )
+        data = exception_data(exc, debug)
+        error: Dict[str, Any] = {
+            "jsonrpc": "2.0",
+            "error": {
+                "code": ERROR_INTERNAL_ERROR,
+                "message": "Internal error",
+                **({} if data is NODATA else {"data": data}),
+            },
+            "id": response.get("id"),
+        }
+        try:
+            return serializer(error)
+        except Exception:
+            # The id itself can't be serialized (for example it was 1e400, which
+            # json.loads reads as infinity).
+            error["id"] = None
+            return json.dumps(error)
+
+
+def serialize(
+    serializer: Callable[[Any], str],
+    response: Union[Dict[str, Any], List[Dict[str, Any]]],
+    debug: bool,
+) -> str:
+    """Serialize a response or batch of responses.
+
+    A response that can't be serialized becomes an Internal error response. In a batch,
+    the other responses are kept.
+    """
+    try:
+        return serializer(response)
+    except Exception:
+        if isinstance(response, list):
+            return (
+                "["
+                + ", ".join(serialize_one(serializer, r, debug) for r in response)
+                + "]"
+            )
+        return serialize_one(serializer, response, debug)
+
+
+# Prepare the jsonschema validator. This is global so it loads only once, not every
+# time dispatch is called.
+# pkgutil.get_data works on every supported Python, and inside zip files and frozen
+# apps. importlib.resources.read_text is deprecated on 3.11 and 3.12.
+schema = json.loads(
+    pkgutil.get_data(__name__.rpartition(".")[0], "request-schema.json") or b""
+)
+klass = validator_for(schema)
+klass.check_schema(schema)
+default_validator = klass(schema).validate
+
+
+def dispatch_to_response(
+    request: str,
+    methods: Optional[MethodsArgument] = None,
+    *,
+    context: Any = NOCONTEXT,
+    deserializer: Callable[[str], Deserialized] = json.loads,
+    validator: Callable[[Deserialized], object] = default_validator,
+    post_process: Callable[[Response], Any] = identity,
+    debug: bool = False,
+    max_batch_size: Optional[int] = None,
+) -> Union[Response, List[Response], None]:
+    """Dispatch a request and give the response as Response objects.
+
+    Most code wants `dispatch` (a JSON string) or `dispatch_to_serializable` (dicts)
+    instead. Use this one to inspect or change responses before they're serialized.
+
+    Each Response is an oslash `Right` holding a `SuccessResponse`, or a `Left`
+    holding an `ErrorResponse`. oslash has no public way to read them, so check
+    `isinstance(response, Left)` and read `response._error` or `response._value`.
+    These attributes are stable for all of 5.x. Printing a Response raises
+    `TypeError`, because of a bug in oslash; print `to_dict(response)` instead.
+
+    Args:
+        request: The JSON-RPC request string.
+        methods: The methods requests can call, as a dict (or any mapping) of names
+            to functions. The default is the dict that `@method` fills in,
+            `jsonrpcserver.methods.global_methods`.
+        context: If given, it's passed as the first argument to every method. The
+            client can't see or set it.
+        deserializer: The function that parses the request string. The default is
+            `json.loads`. If it raises, the client gets a -32700 Parse error whose
+            `data` is the exception message.
+        validator: The function that checks a parsed request against the JSON-RPC
+            spec. It should raise an exception, of any kind, if the request is
+            invalid. In a batch it's called once for each request (new in 5.0.10).
+            The default checks against a JSON schema. `lambda _: None` turns
+            validation off.
+        post_process: A function applied to each Response before it's returned.
+        debug: If True, the error response for an exception a method doesn't catch
+            includes the exception message in `data`. The default leaves `data`
+            out, because exception messages can contain passwords, file paths and
+            other details a client shouldn't see. The exception is logged either
+            way. New in 5.0.10.
+        max_batch_size: The most requests a batch may hold. A bigger batch gets a
+            single -32600 Invalid request response, and none of it is run. The
+            default, None, means no limit. A server open to the internet should set
+            one, such as 100. New in 5.0.10.
+
+    Returns:
+        A Response for a single request, a list of Responses for a batch, or None
+            if there's nothing to send back (a notification, or a batch of only
+            notifications). With `post_process`, whatever it returns for each.
+
+    Raises:
+        ValueError: If `max_batch_size` isn't None or a positive int. Requests never
+            raise: a bad request or a failing method gives an error response.
+    """
+    check_max_batch_size(max_batch_size)
+    response = dispatch_to_response_pure(
+        deserializer=deserializer,
+        validator=validator,
+        post_process=post_process,
+        context=context,
+        methods=global_methods if methods is None else methods,
+        request=request,
+        debug=debug,
+        max_batch_size=max_batch_size,
+    )
+    return cast(Union[Response, List[Response], None], response)
+
+
+def dispatch_to_serializable(
+    request: str,
+    methods: Optional[MethodsArgument] = None,
+    *,
+    context: Any = NOCONTEXT,
+    deserializer: Callable[[str], Deserialized] = default_deserializer,
+    validator: Callable[[Deserialized], object] = default_validator,
+    debug: bool = False,
+    max_batch_size: Optional[int] = None,
+) -> Union[Dict[str, Any], List[Dict[str, Any]], None]:
+    """Dispatch a request and give the response as a dict.
+
+    Use it when your framework serializes the response itself, such as a Django
+    `JsonResponse`, or when you want to inspect it.
+
+    Args:
+        request: The JSON-RPC request string.
+        methods: The same as for `dispatch_to_response`.
+        context: The same as for `dispatch_to_response`.
+        deserializer: The same as for `dispatch_to_response`.
+        validator: The same as for `dispatch_to_response`.
+        debug: The same as for `dispatch_to_response`.
+        max_batch_size: The same as for `dispatch_to_response`.
+
+    Returns:
+        The response as a dict, a list of dicts for a batch, or None if there's
+            nothing to send back.
+
+    Raises:
+        ValueError: If `max_batch_size` isn't None or a positive int.
+
+    Example:
+        >>> from jsonrpcserver import Result, Success, dispatch_to_serializable
+        >>> def ping() -> Result:
+        ...     return Success("pong")
+        >>> dispatch_to_serializable(
+        ...     '{"jsonrpc": "2.0", "method": "ping", "id": 1}', methods={"ping": ping}
+        ... )
+        {'jsonrpc': '2.0', 'result': 'pong', 'id': 1}
+    """
+    return cast(
+        Union[Dict[str, Any], List[Dict[str, Any]], None],
+        dispatch_to_response(
+            request,
+            methods,
+            context=context,
+            deserializer=deserializer,
+            validator=validator,
+            debug=debug,
+            max_batch_size=max_batch_size,
+            post_process=to_dict,
+        ),
+    )
+
+
+def dispatch_to_json(
+    request: str,
+    methods: Optional[MethodsArgument] = None,
+    *,
+    context: Any = NOCONTEXT,
+    deserializer: Callable[[str], Deserialized] = default_deserializer,
+    validator: Callable[[Deserialized], object] = default_validator,
+    debug: bool = False,
+    max_batch_size: Optional[int] = None,
+    serializer: Callable[
+        [Union[Dict[str, Any], List[Dict[str, Any]], str]], str
+    ] = default_serializer,
+) -> str:
+    """Dispatch a request and give the response as a JSON string.
+
+    This is `dispatch`, the function most code uses. Send the string back to the
+    client. An empty string means there's nothing to send back: the request was a
+    notification, or a batch of only notifications. Over HTTP, send status 204 with
+    no body for that.
+
+    Args:
+        request: The JSON-RPC request string.
+        methods: The same as for `dispatch_to_response`.
+        context: The same as for `dispatch_to_response`.
+        deserializer: The same as for `dispatch_to_response`.
+        validator: The same as for `dispatch_to_response`.
+        debug: The same as for `dispatch_to_response`.
+        max_batch_size: The same as for `dispatch_to_response`.
+        serializer: The function that turns the response into a string. The
+            default is `json.dumps` with `allow_nan=False`, so a result holding NaN
+            or Infinity gives an Internal error instead of invalid JSON (new in
+            5.0.10). If the serializer raises for a response, say because the
+            method returned a `datetime`, that response becomes an Internal error
+            and the rest of a batch is sent as usual.
+
+    Returns:
+        The response as a JSON string, or "" if there's nothing to send back.
+
+    Raises:
+        ValueError: If `max_batch_size` isn't None or a positive int.
+
+    Example:
+        >>> from jsonrpcserver import Result, Success, dispatch
+        >>> def ping() -> Result:
+        ...     return Success("pong")
+        >>> dispatch('{"jsonrpc": "2.0", "method": "ping", "id": 1}', {"ping": ping})
+        '{"jsonrpc": "2.0", "result": "pong", "id": 1}'
+    """
+    response = dispatch_to_serializable(
+        request,
+        methods,
+        context=context,
+        deserializer=deserializer,
+        validator=validator,
+        debug=debug,
+        max_batch_size=max_batch_size,
+    )
+    # Better to respond with the empty string instead of json "null", because "null" is
+    # an invalid JSON-RPC response.
+    return "" if response is None else serialize(serializer, response, debug)
+
+
+dispatch = dispatch_to_json
+"""Another name for `dispatch_to_json`, and the one most code uses."""

jsonrpcserver/methods.py

@@ -0,0 +1,91 @@
+"""Methods: the functions a JSON-RPC request can call.
+
+The dispatch functions look methods up in a dict of names to functions. The @method
+decorator adds a function to global_methods, the dict they use by default. To use
+your own dict instead, pass it as the methods argument:
+
+    dispatch(request)  # the functions registered with @method
+    dispatch(request, methods={"ping": ping})  # only the functions in this dict
+
+Either way, a method returns Success(...) or Error(...), not a plain value.
+
+A request's params are either a list (positional arguments) or an object (named
+arguments), not both. That's a JSON-RPC rule.
+"""
+
+import warnings
+from typing import Any, Callable, Dict, Mapping, Optional, TypeVar, overload
+
+from .result import Result
+
+Method = Callable[..., Result]
+Methods = Dict[str, Method]
+# Async methods return a coroutine rather than a Result, so the dispatch functions
+# accept any callable. They check what comes back at run time.
+AnyMethod = Callable[..., Any]
+# What the dispatch functions accept for their methods argument. Any mapping will do.
+MethodsArgument = Mapping[str, AnyMethod]
+
+global_methods: Dict[str, AnyMethod] = {}
+"""The methods registered with `@method`, as a dict of names to functions.
+
+The dispatch functions use it when they're called without `methods`. It's shared by
+the whole process, so every module that uses `@method` adds to it.
+"""
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@overload
+def method(f: F, name: Optional[str] = None) -> F: ...
+
+
+@overload
+def method(f: None = None, name: Optional[str] = None) -> Callable[[F], F]: ...
+
+
+def method(f: Optional[F] = None, name: Optional[str] = None) -> Any:
+    """Register a function as a JSON-RPC method.
+
+    The function is added to `global_methods`, which the dispatch functions use when
+    they're called without `methods`. It's returned unchanged, so you can still call
+    it yourself, and type checkers see its real signature (from 5.0.10). A method
+    with the same name as an earlier one replaces it, without a warning.
+
+    Use it with or without arguments:
+
+    ```python
+    @method
+    def ping() -> Result:
+        return Success("pong")
+
+    @method(name="sum")
+    def add(a: int, b: int) -> Result:
+        return Success(a + b)
+    ```
+
+    Args:
+        f: The function. Leave it out to pass `name`.
+        name: The name requests use to call the method. The default is the
+            function's name.
+
+    Returns:
+        The function itself, or, when called with only `name`, a decorator.
+
+    Warns:
+        UserWarning: If the name starts with "rpc.". The JSON-RPC spec reserves those
+            names. New in 5.0.10.
+    """
+
+    def decorator(func: F) -> F:
+        method_name = func.__name__ if name is None else name
+        if method_name.startswith("rpc."):
+            warnings.warn(
+                f"Method names starting with 'rpc.' are reserved by the JSON-RPC spec "
+                f"({method_name!r})",
+                stacklevel=3 if callable(f) else 2,
+            )
+        global_methods[method_name] = func
+        return func
+
+    return decorator(f) if callable(f) else decorator

jsonrpcserver/request-schema.json

@@ -0,0 +1,39 @@
+{
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "description": "A JSON RPC 2.0 request",
+    "oneOf": [
+        {
+            "description": "An individual request",
+            "$ref": "#/definitions/request"
+        },
+        {
+            "description": "An array of requests",
+            "type": "array",
+            "items": { "$ref": "#/definitions/request" },
+            "minItems": 1
+        }
+    ],
+    "definitions": {
+        "request": {
+            "type": "object",
+            "required": [ "jsonrpc", "method" ],
+            "properties": {
+                "jsonrpc": { "enum": [ "2.0" ] },
+                "method": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": [ "string", "number", "null" ],
+                    "note": [
+                        "While allowed, null should be avoided: http://www.jsonrpc.org/specification#id1",
+                        "While allowed, a number with a fractional part should be avoided: http://www.jsonrpc.org/specification#id2"
+                    ]
+                },
+                "params": {
+                    "type": [ "array", "object" ]
+                }
+            },
+            "additionalProperties": false
+        }
+    }
+}

jsonrpcserver/request.py

@@ -0,0 +1,15 @@
+"""A simple namedtuple to hold a request.
+
+After parsing a request string, we put the (dict) requests into these Request
+namedtuples, simply because they're nicer to work with.
+"""
+
+from typing import Any, Dict, List, NamedTuple, Union
+
+
+class Request(NamedTuple):
+    """JSON-RPC Request"""
+
+    method: str
+    params: Union[List[Any], Dict[str, Any]]
+    id: Any  # Use NOID for a Notification.

jsonrpcserver/response.py

@@ -0,0 +1,170 @@
+"""Responses: what dispatch_to_response gives, and how to turn them into dicts.
+
+A Response is a Result plus the request's id
+(https://www.jsonrpc.org/specification#response_object).
+"""
+
+import warnings
+from typing import Any, Dict, List, NamedTuple, Type, Union, cast
+
+from oslash.either import Either, Left, Right
+
+from .codes import (
+    ERROR_INVALID_REQUEST,
+    ERROR_METHOD_NOT_FOUND,
+    ERROR_PARSE_ERROR,
+    ERROR_SERVER_ERROR,
+)
+from .sentinels import NODATA
+
+Deserialized = Union[Dict[str, Any], List[Dict[str, Any]]]
+
+
+class SuccessResponse(NamedTuple):
+    """A successful response: the method's result and the request's id."""
+
+    result: Any
+    id: Any
+
+
+class ErrorResponse(NamedTuple):
+    """An error response: the error's code, message and data, and the request's id.
+
+    `data` is `NODATA` when there's no data, so it's left out of the response. `id`
+    is None when the request couldn't be read, as the spec requires.
+    """
+
+    code: int
+    message: str
+    data: Any
+    id: Any
+
+
+# oslash's Either takes the success type first, then the error type.
+Response = Either[SuccessResponse, ErrorResponse]
+"""What `dispatch_to_response` gives for each request.
+
+An oslash `Either`: a `Right` holding a `SuccessResponse`, or a `Left` holding an
+`ErrorResponse`. To read one, check `isinstance(response, Left)`, then read
+`response._error` (an `ErrorResponse`) or `response._value` (a `SuccessResponse`).
+oslash has no public accessor, but these attributes are stable for all of 5.x. Or turn
+it into a dict with `to_dict`.
+"""
+ResponseType = Type[Response]
+"""Deprecated: use `Response`. Kept so code written for 5.0.9 keeps working."""
+
+
+def ParseErrorResponse(data: Any) -> ErrorResponse:  # pylint: disable=invalid-name
+    """An ErrorResponse with most attributes already populated.
+
+    From the spec: "This (id) member is REQUIRED. It MUST be the same as the value of
+    the id member in the Request Object.  If there was an error in detecting the id in
+    the Request object (e.g. Parse error/Invalid Request), it MUST be Null."
+    """
+    return ErrorResponse(ERROR_PARSE_ERROR, "Parse error", data, None)
+
+
+def InvalidRequestResponse(data: Any) -> ErrorResponse:  # pylint: disable=invalid-name
+    """An ErrorResponse with most attributes already populated.
+
+    From the spec: "This (id) member is REQUIRED. It MUST be the same as the value of
+    the id member in the Request Object.  If there was an error in detecting the id in
+    the Request object (e.g. Parse error/Invalid Request), it MUST be Null."
+    """
+    return ErrorResponse(ERROR_INVALID_REQUEST, "Invalid request", data, None)
+
+
+def MethodNotFoundResponse(data: Any, id: Any) -> ErrorResponse:
+    """An ErrorResponse with some attributes already populated."""
+    # pylint: disable=invalid-name,redefined-builtin
+    return ErrorResponse(ERROR_METHOD_NOT_FOUND, "Method not found", data, id)
+
+
+def ServerErrorResponse(data: Any, id: Any) -> ErrorResponse:
+    """An ErrorResponse with some attributes already populated."""
+    # pylint: disable=invalid-name,redefined-builtin
+    return ErrorResponse(ERROR_SERVER_ERROR, "Server error", data, id)
+
+
+def to_error_dict(response: ErrorResponse) -> Dict[str, Any]:
+    """Turn an ErrorResponse into a JSON-RPC response dict, leaving out missing data."""
+    return {
+        "jsonrpc": "2.0",
+        "error": {
+            "code": response.code,
+            "message": response.message,
+            # "data" may be omitted.
+            **({"data": response.data} if response.data is not NODATA else {}),
+        },
+        "id": response.id,
+    }
+
+
+def to_success_dict(response: SuccessResponse) -> Dict[str, Any]:
+    """Turn a SuccessResponse into a JSON-RPC response dict."""
+    return {"jsonrpc": "2.0", "result": response.result, "id": response.id}
+
+
+def to_dict(response: Response) -> Dict[str, Any]:
+    """Turn a Response into a JSON-RPC response dict.
+
+    Args:
+        response: A Response from `dispatch_to_response`.
+
+    Returns:
+        The response as a dict, ready for `json.dumps`.
+
+    Example:
+        >>> from jsonrpcserver import Result, Success, dispatch_to_response
+        >>> def ping() -> Result:
+        ...     return Success("pong")
+        >>> request = '{"jsonrpc": "2.0", "method": "ping", "id": 1}'
+        >>> to_dict(dispatch_to_response(request, {"ping": ping}))
+        {'jsonrpc': '2.0', 'result': 'pong', 'id': 1}
+    """
+    if isinstance(response, Left):
+        return to_error_dict(response._error)
+    success = cast("Right[SuccessResponse, ErrorResponse]", response)
+    return to_success_dict(success._value)
+
+
+def to_serializable(
+    response: Union[Response, List[Response], None],
+) -> Union[Deserialized, None]:
+    """Turn a Response, a list of them or None into a dict, a list of dicts or None."""
+    if response is None:
+        return None
+    if isinstance(response, List):
+        return [to_dict(r) for r in response]
+    return to_dict(response)
+
+
+# The names used in 5.0.9. They were renamed before 5.0.10, and are kept so code that
+# imports them keeps working. They will be removed in 6.0.
+
+
+def _deprecated(old: str, new: str) -> None:
+    warnings.warn(
+        f"jsonrpcserver.response.{old} is deprecated and will be removed in 6.0. "
+        f"Use {new} instead.",
+        DeprecationWarning,
+        stacklevel=3,
+    )
+
+
+def serialize_error(response: ErrorResponse) -> Dict[str, Any]:
+    """Deprecated: use `to_error_dict`. Warns with DeprecationWarning (5.0.10)."""
+    _deprecated("serialize_error", "to_error_dict")
+    return to_error_dict(response)
+
+
+def serialize_success(response: SuccessResponse) -> Dict[str, Any]:
+    """Deprecated: use `to_success_dict`. Warns with DeprecationWarning (5.0.10)."""
+    _deprecated("serialize_success", "to_success_dict")
+    return to_success_dict(response)
+
+
+def to_serializable_one(response: Response) -> Dict[str, Any]:
+    """Deprecated: use `to_dict`. Warns with DeprecationWarning (5.0.10)."""
+    _deprecated("to_serializable_one", "to_dict")
+    return to_dict(response)