jsonrpcserver 5.0.10__py3-none-any.whl

jsonrpcserver/__init__.py

@@ -0,0 +1,42 @@
+"""Process incoming JSON-RPC requests in Python.
+
+Write methods with @method, then pass each request string to dispatch, or to
+async_dispatch in an asyncio server. Documentation:
+https://bensynapse.github.io/jsonrpcserver/
+"""
+
+# __all__ also tells type checkers that these names are re-exported.
+__all__ = [
+    "Error",
+    "InvalidParams",
+    "JsonRpcError",
+    "Result",
+    "Success",
+    "async_dispatch",
+    "async_dispatch_to_response",
+    "async_dispatch_to_serializable",
+    "dispatch",
+    "dispatch_to_response",
+    "dispatch_to_serializable",
+    "method",
+    "serve",
+]
+
+
+from .async_main import (
+    dispatch as async_dispatch,
+)
+from .async_main import (
+    dispatch_to_response as async_dispatch_to_response,
+)
+from .async_main import (
+    dispatch_to_serializable as async_dispatch_to_serializable,
+)
+from .exceptions import JsonRpcError
+from .main import dispatch, dispatch_to_response, dispatch_to_serializable
+from .methods import method
+from .result import Error, InvalidParams, Result, Success
+from .server import serve
+
+__version__ = "5.0.10"
+"""The version of jsonrpcserver, as a string. Added in 5.0.10."""

jsonrpcserver/async_dispatcher.py

@@ -0,0 +1,187 @@
+"""Async version of dispatcher.py"""
+
+import asyncio
+import logging
+from functools import partial
+from inspect import isawaitable
+from itertools import starmap
+from typing import Any, Callable, Optional, Tuple, cast
+
+from oslash.either import Left
+
+from .dispatcher import (
+    NORESPONSE,
+    BatchTooLargeResponse,
+    Deserialized,
+    InvalidResultError,
+    create_request,
+    deserialize_request,
+    exception_data,
+    extract_args,
+    extract_kwargs,
+    extract_list,
+    get_method,
+    log_invalid_result,
+    member_id,
+    not_notification,
+    to_response,
+    validate_args,
+    validate_request,
+    validate_result,
+)
+from .exceptions import JsonRpcError
+from .methods import AnyMethod, MethodsArgument
+
+# Importable from here in 5.0.9. The "as" form marks a re-export.
+from .methods import Method as Method
+from .methods import Methods as Methods
+from .request import Request
+from .response import InvalidRequestResponse, Response, ServerErrorResponse
+from .result import ErrorResult, InternalErrorResult, Result
+from .utils import identity, make_list, unwrap
+
+logger = logging.getLogger(__name__)
+
+
+async def call(
+    request: Request, context: Any, method: AnyMethod, debug: bool = False
+) -> Result:
+    try:
+        result = method(*extract_args(request, context), **extract_kwargs(request))
+        # Plain (sync) methods work too. Their result is used as it is.
+        if isawaitable(result):
+            result = await result
+        validate_result(result)
+    except JsonRpcError as exc:
+        return Left(ErrorResult(code=exc.code, message=exc.message, data=exc.data))
+    except InvalidResultError as exc:
+        log_invalid_result(request.method, exc, logger)
+        return Left(InternalErrorResult(exception_data(exc, debug)))
+    except Exception as exc:
+        # Other error inside method - Internal error
+        logger.exception("Method %r raised an exception", request.method)
+        return Left(InternalErrorResult(exception_data(exc, debug)))
+    # validate_result has checked it.
+    return cast(Result, result)
+
+
+async def dispatch_request(
+    methods: MethodsArgument, context: Any, request: Request, debug: bool = False
+) -> Tuple[Request, Result]:
+    method = get_method(methods, request.method).bind(
+        partial(validate_args, request, context)
+    )
+    if isinstance(method, Left):
+        return request, cast(Result, method)
+    return request, await call(request, context, unwrap(method), debug=debug)
+
+
+async def dispatch_deserialized(
+    methods: MethodsArgument,
+    context: Any,
+    post_process: Callable[[Response], Any],
+    deserialized: Deserialized,
+    debug: bool = False,
+) -> Any:
+    results = await asyncio.gather(
+        *(
+            dispatch_request(methods, context, r, debug=debug)
+            for r in map(create_request, make_list(deserialized))
+        )
+    )
+    return extract_list(
+        isinstance(deserialized, list),
+        map(
+            post_process,
+            starmap(to_response, filter(not_notification, results)),
+        ),
+    )
+
+
+async def dispatch_single(
+    validator: Callable[[Deserialized], object],
+    methods: MethodsArgument,
+    context: Any,
+    deserialized: Deserialized,
+    debug: bool = False,
+) -> Optional[Response]:
+    """Validate and dispatch one member of a batch."""
+    if isinstance(deserialized, list):
+        return Left(InvalidRequestResponse("The request failed schema validation"))
+    result = validate_request(validator, deserialized)
+    if isinstance(result, Left):
+        return Left(result._error)
+    return cast(
+        Optional[Response],
+        await dispatch_deserialized(
+            methods, context, identity, unwrap(result), debug=debug
+        ),
+    )
+
+
+async def dispatch_member(
+    validator: Callable[[Deserialized], object],
+    methods: MethodsArgument,
+    context: Any,
+    post_process: Callable[[Response], Any],
+    member: Any,
+    debug: bool = False,
+) -> Any:
+    """Dispatch one member of a batch, keeping any failure inside that member.
+
+    Returns: The post-processed response, or NORESPONSE for a notification.
+    """
+    response: Optional[Response]
+    try:
+        response = await dispatch_single(
+            validator, methods, context, member, debug=debug
+        )
+    except Exception as exc:
+        logger.exception("Error while dispatching a member of a batch")
+        response = Left(
+            ServerErrorResponse(exception_data(exc, debug), member_id(member))
+        )
+    return NORESPONSE if response is None else post_process(response)
+
+
+async def dispatch_to_response_pure(
+    *,
+    deserializer: Callable[[str], Deserialized],
+    validator: Callable[[Deserialized], object],
+    methods: MethodsArgument,
+    context: Any,
+    post_process: Callable[[Response], Any],
+    request: str,
+    debug: bool = False,
+    max_batch_size: Optional[int] = None,
+) -> Any:
+    try:
+        parsed = deserialize_request(deserializer, request)
+        if isinstance(parsed, Left):
+            return post_process(Left(parsed._error))
+        deserialized = unwrap(parsed)
+        if isinstance(deserialized, list) and deserialized:
+            if max_batch_size is not None and len(deserialized) > max_batch_size:
+                return post_process(
+                    Left(BatchTooLargeResponse(len(deserialized), max_batch_size))
+                )
+            responses = await asyncio.gather(
+                *(
+                    dispatch_member(
+                        validator, methods, context, post_process, member, debug=debug
+                    )
+                    for member in deserialized
+                )
+            )
+            return extract_list(
+                True, [response for response in responses if response is not NORESPONSE]
+            )
+        validated = validate_request(validator, deserialized)
+        if isinstance(validated, Left):
+            return post_process(Left(validated._error))
+        return await dispatch_deserialized(
+            methods, context, post_process, unwrap(validated), debug=debug
+        )
+    except Exception as exc:
+        logger.exception("Error while dispatching the request")
+        return post_process(Left(ServerErrorResponse(exception_data(exc, debug), None)))

jsonrpcserver/async_main.py

@@ -0,0 +1,180 @@
+"""The async dispatch functions, for asyncio servers.
+
+They take the same arguments as the functions in main.py, and are imported from
+the package as async_dispatch, async_dispatch_to_serializable and
+async_dispatch_to_response. Methods can be async functions or plain ones. The
+requests in a batch run concurrently.
+"""
+
+from typing import Any, Callable, Dict, Iterable, List, Optional, Union, cast
+
+from .async_dispatcher import dispatch_to_response_pure
+from .dispatcher import Deserialized, check_max_batch_size
+from .main import (
+    default_deserializer,
+    default_serializer,
+    default_validator,
+    serialize,
+)
+
+# 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_serializable
+from .sentinels import NOCONTEXT
+from .utils import identity
+
+
+async def dispatch_to_response(
+    request: str,
+    methods: Optional[MethodsArgument] = None,
+    *,
+    context: Any = NOCONTEXT,
+    deserializer: Callable[[str], Deserialized] = default_deserializer,
+    validator: Callable[[Deserialized], object] = default_validator,
+    post_process: Callable[[Response], Any] = identity,
+    debug: bool = False,
+    max_batch_size: Optional[int] = None,
+) -> Union[Response, Iterable[Response], None]:
+    """Dispatch a request and give the response as Response objects. Async.
+
+    The async version of `dispatch_to_response`, imported from the package as
+    `async_dispatch_to_response`. It takes the same arguments.
+
+    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`.
+        post_process: 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`. Every request in a
+            batch runs at the same time, so a limit matters even more here.
+
+    Returns:
+        A Response for a single request, a list of Responses for a batch, or None
+            if there's nothing to send back. The type hint says Iterable for a
+            batch, but it's a list.
+
+    Raises:
+        ValueError: If `max_batch_size` isn't None or a positive int.
+    """
+    check_max_batch_size(max_batch_size)
+    response = await 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, Iterable[Response], None], response)
+
+
+async 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. Async.
+
+    The async version of `dispatch_to_serializable`, imported from the package as
+    `async_dispatch_to_serializable`.
+
+    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.
+    """
+    return cast(
+        Union[Dict[str, Any], List[Dict[str, Any]], None],
+        await dispatch_to_response(
+            request,
+            methods,
+            context=context,
+            deserializer=deserializer,
+            validator=validator,
+            debug=debug,
+            max_batch_size=max_batch_size,
+            post_process=to_serializable,
+        ),
+    )
+
+
+async 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]], None]], str
+    ] = default_serializer,
+) -> str:
+    """Dispatch a request and give the response as a JSON string. Async.
+
+    This is `async_dispatch`, the async version of `dispatch`. Methods can be async
+    functions or plain ones (plain ones work from 5.0.10). A plain method runs on
+    the event loop, so a slow one holds up every other request.
+
+    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 same as for `dispatch`.
+
+    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:
+        >>> import asyncio
+        >>> from jsonrpcserver import Result, Success, async_dispatch
+        >>> async def ping() -> Result:
+        ...     return Success("pong")
+        >>> request = '{"jsonrpc": "2.0", "method": "ping", "id": 1}'
+        >>> asyncio.run(async_dispatch(request, {"ping": ping}))
+        '{"jsonrpc": "2.0", "result": "pong", "id": 1}'
+    """
+    response = await dispatch_to_serializable(
+        request,
+        methods,
+        context=context,
+        deserializer=deserializer,
+        validator=validator,
+        debug=debug,
+        max_batch_size=max_batch_size,
+    )
+    return "" if response is None else serialize(serializer, response, debug)
+
+
+dispatch = dispatch_to_json
+"""Another name for `dispatch_to_json`. The package exports it as `async_dispatch`."""

jsonrpcserver/codes.py

@@ -0,0 +1,20 @@
+"""The error codes jsonrpcserver sends.
+
+The first five are defined by the spec:
+https://www.jsonrpc.org/specification#error_object
+"""
+
+ERROR_PARSE_ERROR = -32700
+"""The request isn't valid JSON (or the deserializer raised)."""
+ERROR_INVALID_REQUEST = -32600
+"""The JSON isn't a valid request object, or a batch is empty or too big."""
+ERROR_METHOD_NOT_FOUND = -32601
+"""No method has that name."""
+ERROR_INVALID_PARAMS = -32602
+"""The params don't fit the method's signature, or the method said they're invalid."""
+ERROR_INTERNAL_ERROR = -32603
+"""The method raised, returned something other than a Result, or its result
+could not be serialized.
+"""
+ERROR_SERVER_ERROR = -32000
+"""Something failed in jsonrpcserver itself, outside any method."""