Write and register remote procedures

Django-modern-rpc will automatically register RPC methods at startup. To ensure this automatic registration is performed quickly, you must provide the list of python modules where your remote methods are declared.

In settings.py, add the variable MODERNRPC_METHODS_MODULES to define this list. In our example, the only defined RPC method is add(), declared in myproject/rpc_app/rpc_methods.py.

MODERNRPC_METHODS_MODULES = [
    'rpc_app.rpc_methods'
]

When django-modern-rpc application will be loaded, it’s AppConfig.ready() method is executed. The automatic registration is performed at this step.

Decorate your RPC methods

Decorator usage is simple. You only need to add @rpc_method decorator before any method you want to provide via RPC calls.

# In myproject/rpc_app/rpc_methods.py
from modernrpc.core import rpc_method

@rpc_method()
def add(a, b):
    return a + b

Configure the registration

If you decorate your methods with @rpc_method without specifying argument, the registered method will be available for all entry points, for any XML-RPC or JSON-RPC call and will have the name of the corresponding function.

You can also change this behavior by setting arguments to the decorator:

name = None

Can be used to override the external name of a RPC method. This is the only way to define dotted names for RPC methods, since python syntax does not allows such names in functions definitions. Example:

@rpc_method(name='math.additioner')
def add(a, b):
    return a + b
protocol = ALL

Set the protocol argument to modernrpc.handlers.JSONRPC or modernrpc.handlers.XMLRPC to ensure a method will be available only via the corresponding protocol. Example:

@rpc_method(protocol=modernrpc.handlers.JSONRPC)
def add(a, b):
    return a + b
entry_point = ALL

Set the entry_point argument to one or more str value to ensure the method will be available only via calls to corresponding entry point name. Fore more information, please check the documentation about multiple entry points declaration. Example:

@rpc_method(entry_point='apiV2')
def add(a, b):
    return a + b

Access request, protocol and other info from a RPC method

If you need to access some environment from your RPC method, simply adds **kwargs in function parameters. When the function will be executed, a dict will be passed as argument, providing the following information:

  • Current HTTP request, as proper Django HttpRequest instance
  • Current protocol (JSON-RPC or XML-RPC)
  • Current entry point name
  • Current handler instance

See the example to see how to access these values:

from modernrpc.core import REQUEST_KEY, ENTRY_POINT_KEY, PROTOCOL_KEY, HANDLER_KEY
from modernrpc.core import rpc_method

@rpc_method
def content_type_printer(**kwargs):

    # Get the current request
    request = kwargs.get(REQUEST_KEY)

    # Other available objects are:
    # protocol = kwargs.get(PROTOCOL_KEY)
    # entry_point = kwargs.get(ENTRY_POINT_KEY)
    # handler = kwargs.get(HANDLER_KEY)

    # Return the content-type of the current request
    return request.META.get('Content-Type', '')