Welcome to ReflectRPC’s documentation!

This is the auto-generated API documentation of ReflectRPC. If you look for an introduction checkout the project README.

class reflectrpc.JsonEnumType(name, description, start=0)

Self-describing enum types

An enum is a list of named integers. Translation between integer value and string names is supported by this class as well as validation of integer and string values to check if they are valid values of an enum.

add_value(name, description)

Add a new value to the enum

Args:
name (str): String name of the value description (str): Description of this value
resolve_intvalue(intvalue)

Resolves an integer value to its string name

Args:
intvalue (int): Integer value to resolve
Returns:
str: Name of intvalue on success None: If intvalue is not a valid value for this enum
Raises:
ValueError: If intvalue is not an integer
resolve_name(name)

Resolves a string name to its integer value

Args:
name (str): String name of a value
Returns:
int: Integer value of name on success None: If name is not a valid value for this enum
Raises:
ValueError: If name is not a string
resolve_to_intvalue(value)

Resolves an integer value or string name to the corresponding integer value

Args:
value (int|str): Integer value or string name
Returns:
int: Integer value if value is a valid enum value None: If value is not a valid enum value
Raises:
ValueError: If value is neither interger or string
resolve_to_name(value)

Resolves an integer value or string name to the corresponding string name

Args:
value (int|str): Integer value or string name
Returns:
str: String name if value is a valid enum value None: If value is not a valid enum value
Raises:
ValueError: If value is neither interger or string
to_dict()

Convert the enum to a dictionary

Returns:
dict: Dictionary representing this enum type
validate(value)

Check if a string or integer value is a valid value for this enum

Args:
value (int|str): Value to check
Returns:
bool: True if value is valid, False if not
class reflectrpc.JsonHashType(name, description)

Self-describing named hashes

A named hash is a hash with a description of its members and their types

add_field(name, typ, description)

Add a new field to the named hash

Args:
name (str): Name of the field typ (str): Type of the field (JSON type or enum or named hash) description (str): Description of this field
Raises:
ValueError: If typ is not a valid type
to_dict()

Convert the named hash to a dictionary

Returns:
dict: Dictionary representing this enum type
exception reflectrpc.JsonRpcError(msg)

Generic JSON-RPC error class

All exceptions that are to be serialized and sent back to the user over JSON-RPC have to derive from this class. All exceptions not derived from this class will be suppressed for security reasons.

Example:

The JSON representation of this error looks like this:

{"name": "JsonRpcError", "message": "Your error message"}
to_dict()

Convert the error to a dictionary

Returns:
dict: Dictionary representing this error
exception reflectrpc.JsonRpcInternalError(msg)

JSON-RPC error class for internal errors

This error is used when the details of the error are to be hidden from the user for security reasons (e.g. when an exception is raised which is not derived from JsonRpcError).

Example:

The JSON representation of this error looks like this:

{"name": "InternalError", "message": "Your error message"}
exception reflectrpc.JsonRpcInvalidRequest(msg)

JSON-RPC error class for invalid requests

Example:

The JSON representation of this error looks like this:

{"name": "InvalidRequest", "message": "Your error message"}
exception reflectrpc.JsonRpcParamError(function_name, expected_count, real_count)

JSON-RPC error class for requests with wrong number of parameters

Example:

The JSON representation of this error looks like this:

{"name": "ParamError", "message": "Expected [expected_count] parameters for '[function_name]' but got [real_count]""}
exception reflectrpc.JsonRpcParamTypeError(function_name, param_name, expected_type, real_type)

JSON-RPC error class for requests with parameters of invalid type

Example:

The JSON representation of this error looks like this:

{"name": "TypeError", "message": "[function_name]: Expected value of type '[param_name]' for parameter '[expected_type]' but got value of type '[real_type]'"}
exception reflectrpc.JsonRpcTypeError(msg)

Generic JSON-RPC error class for requests with parameters of invalid type

Example:

The JSON representation of this error looks like this:

{"name": "TypeError", "message": "Your error message"}
class reflectrpc.RpcFunction(func, name, description, result_type, result_desc)

Description of a function exposed as Remote Procedure Call

add_param(typ, name, description)

Add a parameter to the function description

Args:
typ (str): Type of the parameter name (str): Name of the parameter description (str): Description of the parameter
Raises:
ValueError: If typ is not a valid type
to_dict()

Convert the function description to a dictionary

Returns:
dict: Dictionary representing this error
class reflectrpc.RpcProcessor

A JSON-RPC server that is capable of describing all of its RPC functions to the client

add_custom_type(custom_type)

Make a custom type (enum or named hash) known to the RpcProcessor

Args:
custom_type (JsonEnumType|JsonHashType): Enum or named hash
Raises:
ValueError: If custom_type is neither a JsonEnumType nor a JsonHashType or custom_type is already registered
add_function(func)

Add a new RPC function to the RpcProcessor

Args:
func (RpcFunction): Description object for the new function
Raises:
ValueError: If a function of this name is already registered or unknown types are referenced in func
call_function(rpcfunction, rpcinfo, *params)

Execute the actual function

Params:
rpcfunction (RpcFunction): RPC function object representing a function rpcinfo (dict): Additional information to pass to the function
check_named_hash(func, param, value, path)

Check if a value for a named hash is valid

check_param_type(func, param, value, path)

Check the type of a single parameter

Args:
value (any): Actual value that was passed by the caller path (str): Path to the variable in nested structures
check_request_types(func, params)

Check the types of the parameters passed by a JSON-RPC call

Args:
func (RpcFunction): Description of the called function params (list): Parameters passed in the request
Raises:
JsonRpcTypeError: If a parameter type is invalid JsonRpcParamTypeError: If a parameter type is invalid
describe_custom_types()

Describe the custom types exposed by this RPC service

Returns:
list: Description of all custom types registered to this RpcProcessor
describe_functions()

Describe the functions exposed by this RPC service

Returns:
list: Description of all functions registered to this RpcProcessor
describe_service()

Return the self-description of this RPC service

Returns:
dict: Description of this service
disable_named_hash_validation()

Disable validation of the fields of named hashes

enable_named_hash_validation()

Enable validation of the fields of named hashes

handle_error(e, reply)

Rewrite a reply dict for an exception caught during RPC function execution

Args:
e (Exception): The exception caught when executing an RPC function reply (dict): The reply we wanted to send to the client before the error occured
Returns:
dict: The modified reply dict now containing information about the error
process_request(message, rpcinfo=None)

Process a JSON-RPC request

Validates the JSON-RPC request and executes the RPC function in case the request is valid. Errors are reported to the user. Exceptions that are not derived from JsonRpcError are reported as internal errors with no further explanation for security reasons.

Args:

message (str): The JSON-RPC request sent by the client rpcinfo (dict): A dictionary used to pass additional information to

the RPC function (e.g. authentication information)
Returns:
dict: JSON-RPC reply for the client
set_description(name, description, version, custom_fields=None)

Set the description of this RPC service

Args:
name (str): Name of the service description (str): Description of the service version (str): Version of the service custom_fields (dict): A dict with user-defined fields
reflectrpc.validate_custom_type_name(name)

Check if a name is a valid name for a custom type

Args:
name (str): Name of the supposed custom type
Returns:
bool: True if valid, False if not
reflectrpc.validate_primitive_type_name(name)

Check if a name is a valid primitive type

Args:
name (str): Name of the supposed primitive type
Returns:
bool: True if valid, False if not
reflectrpc.validate_type_declaration(type_decl)

Check if a type delaration is valid

A type declaration can either declare a primitive value (e.g. int, float, string etc.), a custom type value (Enum or Named Hash) or a typed array containing a value of either a primitive type or a custom type (e.g. array<int>, array<{CustomType}>, ...)

Args:
type_decl (str): The type declaration to validate
Returns:
bool: True if valid, False if not
reflectrpc.validate_typed_array_declaration(type_decl)

Check if a type declaration is a valid typed array

Args:
type_decl (str): The type declaration supposed to declare a typed array
Returns:
bool: True if valid, False if not
exception reflectrpc.client.NetworkError(real_exception)

Encapsulates network errors to ease error handling for users

class reflectrpc.client.RpcClient(host, port)

Client for the JSON-RPC 1.0 protocol

build_rpc_call(method, *params)

Builds a JSON-RPC request dictionary

Args:
method (str): Name of the RPC method params (list): Parameters for the RPC method
Returns:
dict: Request dictionary
build_rpc_notify(method, *params)

Builds a JSON-RPC notify request dictionary

Args:
method (str): Name of the notify method params (list): Parameters for the notify method
Returns:
dict: Request dictionary
close_connection()

Force the connection to be closed

disable_auto_reconnect()

Disable automatic reconnect in case the connection was closed by the peer

enable_auto_reconnect()

Enable automatic reconnect in case the connection was closed by the peer

RpcClient tries to reconnect once, if it still doesn’t work it gives up and raises an exception

enable_client_auth(cert_file, key_file)

Enable TLS client authentication

Args:
cert_file (str): Path of a PEM file containing client cert key_file (str): Path of a PEM file containing the client key
enable_http(http_path=u'/rpc')

Use HTTP as transport protocol

Args:
http_path (str): The path to the RPC HTTP resource (e.g. /rpc)
enable_http_basic_auth(username, password)

Enable basic authentication for HTTP with username and password

You should use this authentication method only with TLS enabled because the password is not encrypted by basic HTTP authentication

Args:
username (str): Username to authenticate with password (str): Password to authenticate with (will not be encrypted)
enable_tls(ca_file, check_hostname=True)

Enable TLS on the connection

Args:
ca_file (str): Path to a CA file to validate the server certificate
is_connected()

Check if the client is connected to a server

rpc_call(method, *params)

Call a RPC function on the server

This function returns the server response or raises an error

Args:
method (str): The name of the RPC method to call on the server params (list): The parameters to pass to the RPC method
Returns:
JSON type: The value returned by the server
Raises:
RpcError: Generic exception to encapsulate all errors
rpc_call_raw(json_data, send_only=False)

Send a raw JSON request to the server

This method does not validate the input JSON. Also you have to make sure that if you send a request where the “id” parameter has the value “null” the parameter send_only must be True. Otherwise the client will block indefinitely because the server sees it as a notify request and does not send an answer.

If we are currently not connected with the server this method will call __connect() to create a connection.

Args:
json_data (str): The JSON that is sent to the server as is send_only (bool): Only send the request, don’t try to read a response
Returns:
str: The response string as returned by the server None: If send_only is True
Raises:
NetworkError: Any network error
rpc_notify(method, *params)

Call a RPC function on the server but tell it to send no response

Args:
method (str): The name of the RPC method to call on the server params (list): The parameters to pass to the RPC method
exception reflectrpc.client.RpcError(json)

JSON-RPC error object as received by the client

class reflectrpc.client.SocketReadIterator(socket, maxseconds)

Reads chunks of data from a blocking socket for a maximum of maxseconds

exception reflectrpc.client.TLSHostnameError(hostname, cert_hostname)

Exception for when the hostname of a server does not match the hostname in the certificate

class reflectrpc.simpleserver.JsonRpcServer(rpcprocessor, conn, rpcinfo=None)

Blocking socket implementation of AbstractJsonRpcServer

class reflectrpc.simpleserver.SimpleJsonRpcServer(rpcprocessor, host, port)

Simple JSON-RPC server for line-terminated messages

Not a production quality server, handles only one connection at a time.

run()

Start the server and listen on host:port

class reflectrpc.twistedserver.JsonRpcProtocol

Twisted protocol adapter

class reflectrpc.twistedserver.JsonRpcProtocolFactory(rpcprocessor, tls_client_auth_enabled)

Factory to create JsonRpcProtocol objects

protocol

alias of JsonRpcProtocol

class reflectrpc.twistedserver.TwistedJsonRpcServer(rpcprocessor, host, port)

JSON-RPC server for line-terminated messages based on Twisted

enable_client_auth(ca_file)

Enable TLS client authentication

The client needs to present a certificate that validates against our CA to be authenticated

Args:
ca_file (str): Path of a PEM file containing a CA cert to validate the client certs against
enable_http()

Enables HTTP as transport protocol

JSON-RPC requests are to be sent to ‘/rpc’ as HTTP POST requests with content type ‘application/json-rpc’. The server sends the reply in the response body.

enable_http_basic_auth(passwdCheckFunction)

Enables HTTP Basic Auth

Args:
passwdCheckFunction (callable): Takes a username and a password as
argument and checks if they are valid
enable_tls(pem_file)

Enable TLS authentication and encryption for this server

Args:
pem_file (str): Path of a PEM file containing server cert and key
enable_unix_socket_want_pid()

Enable the creation of a PID file in case you listen on a UNIX Domain Socket

run()

Start the server and listen on host:port

set_unix_socket_backlog(backlog)

Sets the number of client connections accepted in case we listen on a UNIX Domain Socket

Args:
backlog (int): Number of client connections allowed
set_unix_socket_mode(mode)

Sets the file permission mode used in case we listen on a UNIX Domain Socket

Args:
mode (int): UNIX file permission mode to protect the Domain Socket

Indices and tables