API Reference¶
Errors¶
Error classes for typedjsonrpc.
-
exception
typedjsonrpc.errors.
Error
(data=None)[source]¶ Base class for all errors.
New in version 0.1.0.
-
exception
typedjsonrpc.errors.
InternalError
(data=None)[source]¶ Internal JSON-RPC error.
New in version 0.1.0.
-
static
from_error
(exc_info, json_encoder, debug_url=None)[source]¶ Wraps another Exception in an InternalError.
Parameters: exc_info ((type, object, traceback)) – The exception info for the wrapped exception Return type: InternalError New in version 0.1.0.
Changed in version 0.2.0: Stringifies non-JSON-serializable objects
-
static
-
exception
typedjsonrpc.errors.
InvalidParamsError
(data=None)[source]¶ Invalid method parameter(s).
New in version 0.1.0.
-
exception
typedjsonrpc.errors.
InvalidRequestError
(data=None)[source]¶ The JSON sent is not a valid request object.
New in version 0.1.0.
-
exception
typedjsonrpc.errors.
InvalidReturnTypeError
(data=None)[source]¶ Return type does not match expected type.
New in version 0.1.0.
-
exception
typedjsonrpc.errors.
MethodNotFoundError
(data=None)[source]¶ The method does not exist.
New in version 0.1.0.
Method Info¶
Data structures for wrapping methods and information about them.
-
class
typedjsonrpc.method_info.
MethodInfo
[source]¶ An object wrapping a method and information about it.
Attribute name: Name of the function Attribute method: The function being described Attribute signature: A description of the types this method takes as parameters and returns -
params
¶ The parameters for this method in a JSON-compatible format
Return type: list[dict[str, str]]
-
returns
¶ The return type for this method in a JSON-compatible format.
This handles the special case of
None
which allowstype(None)
also.Return type: str | None
-
-
class
typedjsonrpc.method_info.
MethodSignature
[source]¶ Represents the types which a function takes as input and output.
Attribute parameter_types: A list of tuples mapping strings to type with a specified order Attribute return_type: The type which the function returns -
static
create
(parameter_names, parameter_types, return_type)[source]¶ Returns a signature object ensuring order of parameter names and types.
Parameters: - parameter_names (list[str]) – A list of ordered parameter names
- parameter_types (dict[str, type]) – A dictionary of parameter names to types
- return_type (type) – The type the function returns
Return type:
-
static
Parameter Checker¶
Logic for checking parameter declarations and parameter types.
-
typedjsonrpc.parameter_checker.
check_return_type
(value, expected_type)[source]¶ Checks that the given return value has the correct type.
Parameters:
-
typedjsonrpc.parameter_checker.
check_type_declaration
(parameter_names, parameter_types)[source]¶ Checks that exactly the given parameter names have declared types.
Parameters: - parameter_names (list[str]) – The names of the parameters in the method declaration
- parameter_types (dict[str, type]) – Parameter type by name
-
typedjsonrpc.parameter_checker.
check_types
(parameters, parameter_types)[source]¶ Checks that the given parameters have the correct types.
Parameters: - parameters (dict[str, object]) – List of (name, value) pairs of the given parameters
- parameter_types (dict[str, type]) – Parameter type by name.
-
typedjsonrpc.parameter_checker.
validate_params_match
(method, parameters)[source]¶ Validates that the given parameters are exactly the method’s declared parameters.
Parameters: - method (function) – The method to be called
- parameters (dict[str, object] | list[object]) – The parameters to use in the call
Registry¶
Logic for storing and calling jsonrpc methods.
-
class
typedjsonrpc.registry.
Registry
(debug=False)[source]¶ The registry for storing and calling jsonrpc methods.
Attribute debug: Debug option which enables recording of tracebacks Attribute tracebacks: Tracebacks for debugging New in version 0.1.0.
-
__init__
(debug=False)[source]¶ Parameters: debug (bool) – If True, the registry records tracebacks for debugging purposes
-
describe
()[source]¶ Returns a description of all the methods in the registry.
Returns: Description Return type: dict[str, object] New in version 0.1.0.
-
dispatch
(request)[source]¶ Takes a request and dispatches its data to a jsonrpc method.
Parameters: request (werkzeug.wrappers.Request) – a werkzeug request with json data Returns: json output of the corresponding method Return type: str New in version 0.1.0.
-
json_decoder
= <json.decoder.JSONDecoder object>¶ The JSON decoder to use. Defaults to
json.JSONDecoder
New in version 0.1.0.
Changed in version 0.2.0: Changed from class to instance
-
json_encoder
= <json.encoder.JSONEncoder object>¶ The JSON encoder to use. Defaults to
json.JSONEncoder
New in version 0.1.0.
Changed in version 0.2.0: Changed from class to instance
-
method
(returns, **parameter_types)[source]¶ Syntactic sugar for registering a method
Example:
>>> registry = Registry() >>> @registry.method(returns=int, x=int, y=int) ... def add(x, y): ... return x + y
Parameters: - returns (type) – The method’s return type
- parameter_types (dict[str, type]) – The types of the method’s parameters
New in version 0.1.0.
-
register
(name, method, method_signature=None)[source]¶ Registers a method with a given name and signature.
Parameters: - name (str) – The name used to register the method
- method (function) – The method to register
- method_signature (MethodSignature | None) – The method signature for the given function
New in version 0.1.0.
-
Server¶
Contains the Werkzeug server for debugging and WSGI compatibility.
-
class
typedjsonrpc.server.
Server
(registry, endpoint='/api')[source]¶ A basic WSGI-compatible server for typedjsonrpc endpoints.
Attribute registry: The registry for this server New in version 0.1.0.
-
__init__
(registry, endpoint='/api')[source]¶ Parameters: - registry (typedjsonrpc.registry.Registry) – The JSON-RPC registry to use
- endpoint (str) – The endpoint to publish JSON-RPC endpoints. Default “/api”.
-
register_before_first_request
(func)[source]¶ Registers a function to be called once before the first served request.
Parameters: func (() -> object) – Function called New in version 0.1.0.
-
run
(host, port, **options)[source]¶ For debugging purposes, you can run this as a standalone server.
Warning
Security vulnerability
This uses
DebuggedJsonRpcApplication
to assist debugging. If you want to use this in production, you should runServer
as a standard WSGI app with uWSGI or another similar WSGI server.New in version 0.1.0.
-
-
class
typedjsonrpc.server.
DebuggedJsonRpcApplication
(app, **kwargs)[source]¶ A JSON-RPC-specific debugged application.
This differs from DebuggedApplication since the normal debugger assumes you are hitting the endpoint from a web browser.
A returned response will be JSON of the form:
{"traceback_id": <id>}
which you can use to hit the endpointhttp://<host>:<port>/debug/<traceback_id>
.New in version 0.1.0.
Warning
Security vulnerability
This should never be used in production because users have arbitrary shell access in debug mode.
-
__init__
(app, **kwargs)[source]¶ Parameters: - app (typedjsonrpc.server.Server) – The wsgi application to be debugged
- kwargs – The arguments to pass to the DebuggedApplication
-
debug_application
(environ, start_response)[source]¶ Run the application and preserve the traceback frames.
Parameters: - environ (dict[str, object]) – The environment which is passed into the wsgi application
- start_response ((str, list[(str, str)]) -> None) – The start_response function of the wsgi application
Return type: generator[str]
New in version 0.1.0.
-
handle_debug
(environ, start_response, traceback_id)[source]¶ Handles the debug endpoint for inspecting previous errors.
Parameters: - environ (dict[str, object]) – The environment which is passed into the wsgi application
- start_response ((str, list[(str, str)]) -> NoneType) – The start_response function of the wsgi application
- traceback_id (int) – The id of the traceback to inspect
New in version 0.1.0.
-
-
typedjsonrpc.server.
current_request
= <LocalProxy unbound>¶ A thread-local which stores the current request object when dispatching requests for
Server
.Stores a
werkzeug.wrappers.Request
.New in version 0.2.0.