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
-