API Reference


Error classes for typedjsonrpc.

exception typedjsonrpc.errors.Error(data=None)[source]

Base class for all errors.

New in version 0.1.0.


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.


Returns the status code for the matching error code.

New in version 0.4.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

Describes the method.

Return type:dict[str, object]

Returns the docstring for this method.

Return type:str

The parameters for this method in a JSON-compatible format

Return type:list[dict[str, str]]

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.

  • 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:


Parameter Checker

Logic for checking parameter declarations and parameter types.

typedjsonrpc.parameter_checker.check_return_type(value, expected_type, strict_floats)[source]

Checks that the given return value has the correct type.

  • value (object) – Value returned by the method
  • expected_type (type) – Expected return type
  • strict_floats (bool) – If False, treat integers as floats
typedjsonrpc.parameter_checker.check_type_declaration(parameter_names, parameter_types)[source]

Checks that exactly the given parameter names have declared types.

  • 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, strict_floats)[source]

Checks that the given parameters have the correct types.

  • parameters (dict[str, object]) – List of (name, value) pairs of the given parameters
  • parameter_types (dict[str, type]) – Parameter type by name.
  • strict_floats (bool) – If False, treat integers as floats
typedjsonrpc.parameter_checker.validate_params_match(method, parameters)[source]

Validates that the given parameters are exactly the method’s declared parameters.

  • method (function) – The method to be called
  • parameters (dict[str, object] | list[object]) – The parameters to use in the call


Logic for storing and calling jsonrpc methods.

class typedjsonrpc.registry.Registry(debug=False, strict_floats=True)[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, strict_floats=True)[source]
  • debug (bool) – If True, the registry records tracebacks for debugging purposes
  • strict_floats (bool) – If True, the registry does not allow ints as float parameters

Changed in version 0.4.0: Added strict_floats option


Returns a description of all the methods in the registry.

Return type:dict[str, object]

New in version 0.1.0.


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


>>> registry = Registry()
>>> @registry.method(returns=int, x=int, y=int)
... def add(x, y):
...     return x + y
  • 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.

  • 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.


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.

Changed in version 0.4.0: Now returns HTTP status codes

__init__(registry, endpoint='/api')[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.


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.


Security vulnerability

This should never be used in production because users have arbitrary shell access in debug mode.

__init__(app, **kwargs)[source]
  • 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.

  • 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:


New in version 0.1.0.

handle_debug(environ, start_response, traceback_id)[source]

Handles the debug endpoint for inspecting previous errors.

  • 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.