jsonrpcserver 5.0.10__py3-none-any.whl

jsonrpcserver/result.py

@@ -0,0 +1,150 @@
+"""What a method returns: Success, Error or InvalidParams.
+
+A Result is the "result" or "error" part of a JSON-RPC response object
+(https://www.jsonrpc.org/specification#response_object). The library adds the
+"jsonrpc" and "id" parts.
+"""
+
+from typing import Any, NamedTuple
+
+from oslash.either import Either, Left, Right
+
+from .codes import ERROR_INTERNAL_ERROR, ERROR_INVALID_PARAMS, ERROR_METHOD_NOT_FOUND
+from .sentinels import NODATA
+from .utils import warn_if_invalid_error
+
+# pylint: disable=missing-class-docstring,missing-function-docstring,invalid-name
+
+
+class SuccessResult(NamedTuple):
+    """The value inside the Result that `Success` returns."""
+
+    result: Any = None
+
+    def __repr__(self) -> str:
+        return f"SuccessResult({self.result!r})"
+
+
+class ErrorResult(NamedTuple):
+    """The value inside the Result that `Error` and `InvalidParams` return.
+
+    `data` is `NODATA` when there's no data, so it's left out of the response.
+    """
+
+    code: int
+    message: str
+    data: Any = NODATA  # The spec says this value may be omitted
+
+    def __repr__(self) -> str:
+        return (
+            f"ErrorResult(code={self.code!r}, message={self.message!r}, "
+            f"data={self.data!r})"
+        )
+
+
+# Union of the two valid result types. oslash's Either takes the success type
+# first, then the error type.
+Result = Either[SuccessResult, ErrorResult]
+"""The return type of a method: what `Success`, `Error` and `InvalidParams` give.
+
+It's an oslash `Either`: a `Right` holding a `SuccessResult`, or a `Left` holding an
+`ErrorResult`. Use it as the return annotation of your methods. You don't need to
+look inside it.
+"""
+
+
+# Helpers
+
+
+def MethodNotFoundResult(data: Any) -> ErrorResult:
+    return ErrorResult(ERROR_METHOD_NOT_FOUND, "Method not found", data)
+
+
+def InternalErrorResult(data: Any) -> ErrorResult:
+    return ErrorResult(ERROR_INTERNAL_ERROR, "Internal error", data)
+
+
+def InvalidParamsResult(data: Any = NODATA) -> ErrorResult:
+    return ErrorResult(ERROR_INVALID_PARAMS, "Invalid params", data)
+
+
+# Helpers (the public functions)
+
+
+def Success(result: Any = None) -> Result:
+    """A successful result. Return it from a method.
+
+    Args:
+        result: The value for the response's `result` member. It can be anything
+            the serializer handles. The default, None, is sent as `null`.
+
+    Returns:
+        A Result holding the value.
+
+    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}'
+    """
+    return Right(SuccessResult(result))
+
+
+def Error(code: int, message: str, data: Any = NODATA) -> Result:
+    """An error result. Return it from a method to send an error response.
+
+    It's sent as it is, whatever `debug` is, so don't put secrets in it.
+
+    Args:
+        code: The error code, an integer. The spec reserves -32768 to -32000 for
+            its own errors, so pick other numbers for yours.
+        message: A short description of the error, as a string.
+        data: Extra information for the client, such as details of what went
+            wrong. If it isn't given, the response has no `data` member.
+
+    Returns:
+        A Result holding the error.
+
+    Warns:
+        UserWarning: If `code` isn't an int or `message` isn't a str. The error is
+            still sent as given. New in 5.0.10.
+
+    Example:
+        >>> from jsonrpcserver import Error, Result, dispatch_to_serializable
+        >>> def fail() -> Result:
+        ...     return Error(1, "It failed", {"reason": "example"})
+        >>> request = '{"jsonrpc": "2.0", "method": "fail", "id": 1}'
+        >>> dispatch_to_serializable(request, {"fail": fail})["error"]
+        {'code': 1, 'message': 'It failed', 'data': {'reason': 'example'}}
+    """
+    warn_if_invalid_error(code, message, stacklevel=2)
+    return Left(ErrorResult(code, message, data))
+
+
+def InvalidParams(data: Any = NODATA) -> Result:
+    """An Invalid params error: `Error(-32602, "Invalid params", data)`.
+
+    Return it when the arguments have the right shape but a bad value.
+    jsonrpcserver already sends this error when the arguments don't fit the
+    method's signature.
+
+    Args:
+        data: What was wrong, for the client. If it isn't given, the response has no
+            `data` member.
+
+    Returns:
+        A Result holding the error.
+
+    Example:
+        >>> from jsonrpcserver import InvalidParams, Result, Success
+        >>> from jsonrpcserver import dispatch_to_serializable
+        >>> def rate(stars: int) -> Result:
+        ...     if stars not in range(1, 6):
+        ...         return InvalidParams("Stars must be 1 to 5")
+        ...     return Success()
+        >>> request = '{"jsonrpc": "2.0", "method": "rate", "params": [6], "id": 1}'
+        >>> dispatch_to_serializable(request, {"rate": rate})["error"]
+        {'code': -32602, 'message': 'Invalid params', 'data': 'Stars must be 1 to 5'}
+    """
+    return Left(InvalidParamsResult(data))

jsonrpcserver/sentinels.py

@@ -0,0 +1,28 @@
+"""Sentinels - these are used to indicate no data is present.
+
+We can't use None, because None may be a valid piece of data.
+"""
+
+import sys
+
+
+class Sentinel:
+    """Use this class to create a unique object.
+
+    Has a nicer repr than `object()`.
+    """
+
+    # pylint: disable=too-few-public-methods
+    def __init__(self, name: str):
+        self.name = name
+
+    def __repr__(self) -> str:
+        return f"<{sys.intern(str(self.name)).rsplit('.', 1)[-1]}>"
+
+
+NOCONTEXT = Sentinel("NoContext")
+"""The default for `context`: don't pass a context to methods."""
+NODATA = Sentinel("NoData")
+"""The default for `data` in `Error` and `JsonRpcError`: leave `data` out."""
+NOID = Sentinel("NoId")
+"""The id of a notification, which has none."""

jsonrpcserver/server.py

@@ -0,0 +1,115 @@
+"""A development server for trying out methods, built on Python's http.server.
+
+It's meant for trying things out. For production, put dispatch behind a real web
+server or framework.
+"""
+
+import json
+import logging
+import sys
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any
+
+from .main import dispatch
+from .response import ParseErrorResponse, to_error_dict
+
+logger = logging.getLogger(__name__)
+
+
+class RequestHandler(BaseHTTPRequestHandler):
+    """Handle HTTP requests"""
+
+    def log_message(self, format: str, *args: Any) -> None:
+        """Log through the logging module instead of writing to sys.stderr.
+
+        sys.stderr is None in some environments, such as a PyInstaller app built with
+        --noconsole. Writing to it there raised an exception that dropped every
+        connection without a response (#269).
+        """
+        logger.info("%s - %s", self.address_string(), format % args)
+
+    def do_POST(self) -> None:
+        """Handle POST request"""
+        try:
+            length = int(self.headers["Content-Length"])
+        except TypeError:
+            self.send_error(411, "Content-Length required")
+            return
+        except ValueError:
+            self.send_error(400, "Invalid Content-Length")
+            return
+        if length < 0:
+            self.send_error(400, "Invalid Content-Length")
+            return
+        body = self.rfile.read(length)
+        try:
+            request = body.decode("utf-8")
+        except UnicodeDecodeError as exc:
+            response = json.dumps(to_error_dict(ParseErrorResponse(str(exc))))
+        else:
+            response = dispatch(request)
+        if response:
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(response.encode())))
+            self.end_headers()
+            self.wfile.write(response.encode())
+        else:
+            # A notification, or a batch of only notifications. There's nothing to send.
+            self.send_response(204)
+            self.end_headers()
+
+
+def listening_message(name: str, port: int) -> str:
+    """The line serve() shows when it starts."""
+    if name in ("", "0.0.0.0"):
+        return (
+            f" * Listening on port {port} on every network interface. This is a "
+            'development server. Use serve("localhost", ...) to accept only local '
+            "connections."
+        )
+    return f" * Listening on http://{name}:{port}/. This is a development server."
+
+
+def serve(name: str = "", port: int = 5000) -> None:
+    """Serve the methods registered with `@method` over HTTP. For development only.
+
+    It answers POST requests on any path with `dispatch`, sends 204 No Content for a
+    notification, and runs each request in its own thread. It runs until the process
+    is stopped, for example with Ctrl+C.
+
+    When it starts, it logs where it's listening on the `jsonrpcserver.server`
+    logger. If logging isn't configured, it writes that line to stderr instead
+    (new in 5.0.10). Each request is logged at INFO level.
+
+    It has no TLS, no authentication and no request size limit, and it doesn't pass
+    `max_batch_size`. Put `dispatch` behind a real web server or framework in
+    production.
+
+    Args:
+        name: The host name or address to listen on. The default, "", listens on
+            every network interface, so other machines can connect. Pass "localhost"
+            to accept only local connections.
+        port: The port to listen on.
+
+    Example:
+        ```python
+        from jsonrpcserver import Result, Success, method, serve
+
+        @method
+        def ping() -> Result:
+            return Success("pong")
+
+        serve("localhost", 8000)
+        ```
+    """
+    httpd = ThreadingHTTPServer((name, port), RequestHandler)
+    try:
+        message = listening_message(name, port)
+        logger.info("%s", message)
+        if not logger.hasHandlers() and sys.stderr is not None:
+            # logging isn't configured, so the line above went nowhere.
+            print(message, file=sys.stderr, flush=True)
+        httpd.serve_forever()
+    finally:
+        httpd.server_close()

jsonrpcserver/utils.py

@@ -0,0 +1,51 @@
+"""Utility functions"""
+
+import warnings
+from functools import reduce
+from typing import Any, Callable, List, TypeVar, cast
+
+from oslash.either import Either, Right
+
+T = TypeVar("T")
+
+# pylint: disable=invalid-name
+
+
+def identity(x: Any) -> Any:
+    """Returns the argument."""
+    return x
+
+
+def compose(*funcs: Callable[..., Any]) -> Callable[..., Any]:
+    """Compose two or more functions producing a single composite function."""
+    return reduce(lambda f, g: lambda *a, **kw: f(g(*a, **kw)), funcs)
+
+
+def make_list(x: Any) -> List[Any]:
+    """Puts a value into a list if it's not already."""
+    # pyright can't tell the element type of a list narrowed from Any.
+    return x if isinstance(x, list) else [x]  # pyright: ignore[reportUnknownVariableType]
+
+
+def warn_if_invalid_error(code: Any, message: Any, stacklevel: int) -> None:
+    """Warn if an error's code or message breaks the JSON-RPC spec.
+
+    The spec says code MUST be an integer and message SHOULD be a string. These used to
+    be sent as given, which some clients can't parse. It's a warning, not an error,
+    so existing code keeps working.
+    """
+    if isinstance(code, bool) or not isinstance(code, int):
+        warnings.warn(
+            f"JSON-RPC error codes must be integers, not {code!r}",
+            stacklevel=stacklevel + 1,
+        )
+    if not isinstance(message, str):
+        warnings.warn(
+            f"JSON-RPC error messages should be strings, not {message!r}",
+            stacklevel=stacklevel + 1,
+        )
+
+
+def unwrap(either: Either[T, Any]) -> T:
+    """The value inside a Right. Only call this once you know it isn't a Left."""
+    return cast("Right[T, Any]", either)._value

jsonrpcserver-5.0.10.dist-info/METADATA

@@ -0,0 +1,163 @@
+Metadata-Version: 2.5
+Name: jsonrpcserver
+Version: 5.0.10
+Summary: Process incoming JSON-RPC 2.0 requests in Python
+Keywords: json-rpc,jsonrpc,json-rpc-2.0,rpc,server
+Author-email: Beau Barker <beau@explodinglabs.com>
+Maintainer-email: Synapse Research <ben@synapsereality.io>
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-Expression: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+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: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+License-File: LICENSE
+Requires-Dist: jsonschema<5
+Requires-Dist: oslash<1
+Requires-Dist: hypothesis ; extra == "test"
+Requires-Dist: pytest ; extra == "test"
+Requires-Dist: pytest-asyncio ; extra == "test"
+Requires-Dist: pytest-cov ; extra == "test"
+Project-URL: Changelog, https://bensynapse.github.io/jsonrpcserver/changelog/
+Project-URL: Documentation, https://bensynapse.github.io/jsonrpcserver/
+Project-URL: Homepage, https://bensynapse.github.io/jsonrpcserver/
+Project-URL: Issues, https://github.com/bensynapse/jsonrpcserver/issues
+Project-URL: Repository, https://github.com/bensynapse/jsonrpcserver
+Provides-Extra: test
+Import-Name: jsonrpcserver
+
+<p align="center">
+  <a href="https://pypi.org/project/jsonrpcserver/"><img src="https://img.shields.io/pypi/v/jsonrpcserver.svg" alt="PyPI version" /></a>
+  <a href="https://github.com/bensynapse/jsonrpcserver/actions/workflows/ci.yml"><img src="https://github.com/bensynapse/jsonrpcserver/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://bensynapse.github.io/jsonrpcserver/#install"><img src="https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue" alt="Python 3.8 to 3.14" /></a>
+  <a href="https://pypistats.org/packages/jsonrpcserver"><img src="https://img.shields.io/pypi/dm/jsonrpcserver" alt="Downloads per month" /></a>
+  <a href="https://github.com/bensynapse/jsonrpcserver/blob/main/LICENSE"><img src="https://img.shields.io/github/license/bensynapse/jsonrpcserver" alt="License: MIT" /></a>
+</p>
+
+<p align="center">
+  <img alt="jsonrpcserver" src="https://raw.githubusercontent.com/bensynapse/jsonrpcserver/main/logo.png" />
+</p>
+
+<p align="center">
+  <i>Process incoming JSON-RPC 2.0 requests in Python</i>
+</p>
+
+<p align="center">
+  <a href="https://bensynapse.github.io/jsonrpcserver/">Documentation</a> |
+  <a href="https://bensynapse.github.io/jsonrpcserver/reference/">API reference</a> |
+  <a href="https://bensynapse.github.io/jsonrpcserver/examples/">Examples</a> |
+  <a href="https://bensynapse.github.io/jsonrpcserver/changelog/">Changelog</a> |
+  <a href="https://bensynapse.github.io/jsonrpcserver/migration/">Migration</a>
+</p>
+
+jsonrpcserver takes a [JSON-RPC 2.0](https://www.jsonrpc.org/specification)
+request, calls your Python function and gives you the response to send back.
+It leaves the networking to you, so it fits into whatever server you already
+have.
+
+## Features
+
+- Works with any framework or transport. The docs have tested examples for
+  http.server, Flask, Werkzeug, Django, FastAPI, aiohttp, Sanic, Tornado,
+  websockets, ZeroMQ and Socket.IO.
+- Sync and async: `dispatch` and `async_dispatch`. With `async_dispatch`, the
+  requests in a batch run concurrently.
+- Follows the spec for batches, notifications and errors, and checks each
+  request's params against your function's signature.
+- Keeps exception messages out of responses and in your logs, and limits
+  batch size with `max_batch_size` (from 5.0.10).
+- Typed: ships `py.typed`, and `@method` keeps your functions' signatures for
+  mypy and pyright.
+- Safe to call from several threads, and tested on Python 3.8 to 3.14,
+  including free-threaded 3.14t.
+
+## Install
+
+```sh
+pip install jsonrpcserver
+```
+
+If you're on 5.0.9 or older, upgrade: those versions send exception messages
+to clients. The
+[changelog](https://bensynapse.github.io/jsonrpcserver/changelog/) lists what
+changed in 5.0.10.
+
+## Quickstart
+
+Save this as `server.py` and run it with `python server.py`:
+
+<!-- skip: it runs forever. docs/examples/check_examples.py runs the same file. -->
+```python
+from jsonrpcserver import Result, Success, method, serve
+
+
+@method
+def ping() -> Result:
+    return Success("pong")
+
+
+if __name__ == "__main__":
+    serve("localhost", 8000)
+```
+
+Then send it a request from another terminal:
+
+```sh
+curl -s -H 'Content-Type: application/json' -d '{"jsonrpc": "2.0", "method": "ping", "id": 1}' http://localhost:8000/
+```
+
+Output:
+
+```text
+{"jsonrpc": "2.0", "result": "pong", "id": 1}
+```
+
+`serve()` is a small server for trying things out. In your own framework,
+pass the request body to `dispatch` and send back the string it returns. The
+[examples](https://bensynapse.github.io/jsonrpcserver/examples/) show how.
+
+## Security
+
+Before you put a server on the internet, pass `max_batch_size` to `dispatch`
+and limit the request body size in your framework. Run 5.0.10 or later. The
+[Security page](https://bensynapse.github.io/jsonrpcserver/security/)
+explains why.
+
+## Documentation
+
+- [Documentation](https://bensynapse.github.io/jsonrpcserver/): guides,
+  framework examples and the
+  [API reference](https://bensynapse.github.io/jsonrpcserver/reference/).
+- [Migrating from 4.x](https://bensynapse.github.io/jsonrpcserver/migration/):
+  methods must now return `Success(value)`. A 4.x method that returns a plain
+  value still runs, but the client gets an Internal error.
+- [Contributing](https://github.com/bensynapse/jsonrpcserver/blob/main/CONTRIBUTING.md)
+  and the
+  [security policy](https://github.com/bensynapse/jsonrpcserver/blob/main/SECURITY.md).
+- [License](https://github.com/bensynapse/jsonrpcserver/blob/main/LICENSE): MIT.
+
+## See also
+
+[jsonrpcclient](https://bensynapse.github.io/jsonrpcclient/)
+([GitHub](https://github.com/bensynapse/jsonrpcclient)) creates JSON-RPC
+requests and parses the responses in Python. It's the client-side companion
+to this library, and its quickstart talks to the server above.
+
+## Credits
+
+Created by Beau Barker. Maintained by [Synapse Research](https://synapsereality.io).
+

jsonrpcserver-5.0.10.dist-info/RECORD

@@ -0,0 +1,20 @@
+jsonrpcserver/__init__.py,sha256=I0vyGlCzULRQfDmNYgSTEq75mh5d74raO6ulAEcPpE0,1143
+jsonrpcserver/async_dispatcher.py,sha256=fGm58YijUQ4De1FJHSvVQz7pcKhBbQRTRL3CmZxZ-qA,6254
+jsonrpcserver/async_main.py,sha256=l91jnWHcxR7pCLsOkOaEtRrSSEcR8Wn360JnNK_7K1U,6698
+jsonrpcserver/codes.py,sha256=chdfOcuTHbv-rVRe27aehsr-y2x4Opax0p7wSDJlCiw,748
+jsonrpcserver/dispatcher.py,sha256=-9JCmFjMS6_TZOf9Mgob-P6a2J5GhOh0LfWTGvwCYTA,16947
+jsonrpcserver/exceptions.py,sha256=7I2krzLJOrifighXVXxl9exwgajLgy6dJqAyrCkZZcM,1439
+jsonrpcserver/main.py,sha256=HjeQChWFqw4RLd0NjurUCEtjJq8VqFdO1mro1EgvNTw,11907
+jsonrpcserver/methods.py,sha256=hiEzP5x5Liw8VhemqFz9lRuJoJk9Xq9vHKkhYT-bzxU,3142
+jsonrpcserver/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+jsonrpcserver/request-schema.json,sha256=JY5j2q8hU6hbJBdyv7I932YDw5AjuMmw-v3KUDVyvTc,1277
+jsonrpcserver/request.py,sha256=R2bChmGSDH3gYD2JdegQbzpZjdop_wOqLWSQzZqm9nE,398
+jsonrpcserver/response.py,sha256=IWIxpObs4l07IdMezlMNHFX0S0lF4EwTaS3H8UK8tpo,6053
+jsonrpcserver/result.py,sha256=wp3iwsB1Jnq0mCs0seghm4SJnQ9Y3aomuAGbHpSux3k,5129
+jsonrpcserver/sentinels.py,sha256=fwL9_C57DhuQkxp2pW9T4fi0IcH6nCHHyfaaNcjBXSU,741
+jsonrpcserver/server.py,sha256=gnpEY1YhCyiJh6EwooSdlEWq8vfyHkjXz-WFcjqfVw4,4210
+jsonrpcserver/utils.py,sha256=aGXOeAmNZNSertL3d87mgWAt4vX48EfTL-E636mWR5o,1683
+jsonrpcserver-5.0.10.dist-info/licenses/LICENSE,sha256=_FwZBYAN8tqi6GIMUwE3E9UUG06-g-gEjYUrCr7c2Gg,1106
+jsonrpcserver-5.0.10.dist-info/WHEEL,sha256=rLJE8OLPBZbz7tqxs1yD-wA-ADa1Ec5PuYU-Y_PNWDI,81
+jsonrpcserver-5.0.10.dist-info/METADATA,sha256=u9ZXOJ5upoDzx9MMRjHt_RjzsTEmuk1Ytzrp4uLebyo,6830
+jsonrpcserver-5.0.10.dist-info/RECORD,,

jsonrpcserver-5.0.10.dist-info/WHEEL

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

jsonrpcserver-5.0.10.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Beau Barker (beau at explodinglabs.com)
+
+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.