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.

as_error_object()[source]¶: Turns the error into an error object.

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

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.

exception typedjsonrpc.errors.ParseError(data=None)[source]¶: Invalid JSON was received by the server / JSON could not be parsed.

New in version 0.1.0.

exception typedjsonrpc.errors.ServerError(data=None)[source]¶: Something else went wrong.

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 method:
Attribute name:	Name of the function
	The function being described
Attribute signature:
	A description of the types this method takes as parameters and returns

describe()[source]¶

Describes the method.

Returns:	Description
Return type:	dict[str, object]

description¶

Returns the docstring for this method.

Return type:	str

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 allows type(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:	MethodSignature

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:	value (object) – Value returned by the method expected_type (type) – Expected return type

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 run Server as a standard WSGI app with uWSGI or another similar WSGI server.

New in version 0.1.0.

wsgi_app(environ, start_response)[source]¶: A basic WSGI app

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 endpoint http://<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.