API Documentation

Optional Settings

The following optional settings can go into settings.py to change the functionality of RPC4Django

RPC4DJANGO_LOG_REQUESTS_RESPONSES

By default RPC4Django will log (using the python logging module) all requests and responses. This can be disabled by setting this to False.

RPC4DJANGO_RESTRICT_INTROSPECTION

By default RPC4Django registers the standard XMLRPC and JSONRPC introspection functions. This can be disabled by setting this to True.

RPC4DJANGO_RESTRICT_JSONRPC

If True, RPC4Django will never serve a JSONRPC request. Instead, either XMLRPC will be tried or status code 404 will be returned. Defaults to False.

RPC4DJANGO_RESTRICT_XMLRPC

If True, RPC4Django will never serve an XMLRPC request. Instead, either JSONRPC will be tried or status code 404 will be returned. Defaults to False.

RPC4DJANGO_RESTRICT_METHOD_SUMMARY

If True, status code 404 will be returned instead of serving the method summary as a response to a GET request. Defaults to False.

RPC4DJANGO_RESTRICT_RPCTEST

If True, the method summary will not allow testing via JSONRPC from the generated method summary page. Defaults to False

RPC4DJANGO_RESTRICT_REST

If True, RPC4Django does not attempt to convert any of the method summary docstrings to restructured text. Defaults to False.

RPC4DJANGO_RESTRICT_OOTB_AUTH

If False, enables out of the box authentication via the RPC methods system.login and system.logout. Out of the box authentication should NOT be considered secure when used without SSL or TLS. Defaults to True.

RPC4DJANGO_HTTP_ACCESS_CREDENTIALS

If True, RPC4Django will respond to OPTIONS requests with the HTTP header Access-Control-Allow-Credentials set to the given value. This pertains to allowing cross site requests with cookies. See the Mozilla documentation on requests with credentials for more details. Defaults to False.

RPC4DJANGO_HTTP_ACCESS_ALLOW_ORIGIN

RPC4Django will respond to OPTIONS requests with the HTTP header Access-Control-Allow-Origin set to the given value. This pertains to allowing cross site requests. See the Mozilla documentation on preflighted requests for more details. Defaults to the empty string.

RPC4DJANGO_JSON_ENCODER

Subclass of rpc4django.jsonrpcdispatcher.json.JSONEncoder or string pointing to the subclass. It can be used to serialize objects that can’t otherwise be serialized. Defaults to django.core.serializers.json.DjangoJSONEncoder.

Views

The main entry point for RPC4Django. Usually, the user simply puts serve_rpc_request into urls.py

urlpatterns = patterns('',
    # rpc4django will need to be in your Python path
    (r'^RPC2$', 'rpc4django.views.serve_rpc_request'),
)

rpc4django.views.check_request_permission(request, request_format='xml')

Checks whether this user has permission to call a particular method This method does not check method call validity. That is done later

Parameters

• request - a django HttpRequest object
• request_format - the request type: ‘json’ or ‘xml’

Returns False if permission is denied and True otherwise

rpc4django.views.is_xmlrpc_request(request)

Determines whether this request should be served by XMLRPC or JSONRPC

Returns True if this is an XML request and false for JSON

1. If there is no post data, display documentation
2. content-type = text/xml or application/xml => XMLRPC
3. content-type contains json or javascript => JSONRPC
4. Try to parse as xml. Successful parse => XMLRPC
5. JSONRPC

rpc4django.views.serve_rpc_request(*args, **kwargs)

Handles rpc calls based on the content type of the request or returns the method documentation page if the request was a GET.

Parameters

request

the Django HttpRequest object

RPC dispatcher

This module contains the classes necessary to handle both JSONRPC and XMLRPC requests. It also contains a decorator to mark methods as rpc methods.

class rpc4django.rpcdispatcher.RPCDispatcher(url='', apps=[], restrict_introspection=False, restrict_ootb_auth=True, json_encoder=None)

Keeps track of the methods available to be called and then dispatches method calls to either the XMLRPCDispatcher or the JSONRPCDispatcher

Disables RPC introspection methods (eg. system.list_methods() if restrict_introspection is set to True. Disables out of the box authentication if restrict_ootb_auth is True.

Attributes

url

The URL that handles RPC requests (eg. /RPC2) This is needed by system.describe.

rpcmethods

A list of RPCMethod instances available to be called by the dispatcher

xmlrpcdispatcher

An instance of XMLRPCDispatcher where XMLRPC calls are dispatched to using xmldispatch()

jsonrpcdispatcher

An instance of JSONRPCDispatcher where JSONRPC calls are dispatched to using jsondispatch()

get_method_name(raw_post_data, request_format='xml')

Gets the name of the method to be called given the post data and the format of the data

jsondispatch(raw_post_data, **kwargs)

Sends the post data to rpc4django.jsonrpcdispatcher.JSONRPCDispatcher.dispatch()

list_methods()

Returns a list of RPCMethod objects supported by the server

register_method(method, name=None, signature=None, helpmsg=None)

Instantiates an RPCMethod object and adds it to rpcmethods so that it can be called by RPC requests

Parameters

method

A callable Python method that the dispatcher will delegate to when requested via RPC

name

The name to make the method availabe. None signifies to use the method’s actual name

signature

The signature of the method. See rpc4django.rpcdispatcher.rpcmethod()

helpmsg

The “help” message displayed by introspection functions asking about the method

register_rpcmethods(apps)

Scans the installed apps for methods with the rpcmethod decorator Adds these methods to the list of methods callable via RPC

system_describe()

Returns a simple method description of the methods supported

system_listmethods()

Returns a list of supported methods

system_login(username, password, **kwargs)

Authorizes a user to enable sending protected RPC requests

system_logout(**kwargs)

Deauthorizes a user

system_methodhelp(method_name)

Returns documentation for a specified method

system_methodsignature(method_name)

Returns the signature for a specified method

xmldispatch(raw_post_data, **kwargs)

Sends the post data to rpc4django.xmlrpcdispatcher.XMLRPCDispatcher.dispatch()

class rpc4django.rpcdispatcher.RPCMethod(method, name=None, signature=None, docstring=None)

A method available to be called via the rpc dispatcher

Attributes

method

The underlying Python method to call when this method is invoked

help

Help message (usually the docstring) printed by the introspection functions when detail about a method is requested

name

name of the method by which it can be called

signature

See rpc4django.rpcdispatcher.rpcmethod()

permission

Any Django permissions required to call this method

login_required

The method can only be called by a logged in user

get_params()

Returns a list of dictionaries containing name and type of the params

eg. [{‘name’: ‘arg1’, ‘rpctype’: ‘int’},

{‘name’: ‘arg2’, ‘rpctype’: ‘int’}]

get_returnvalue()

Returns the return value which is the first element of the signature

get_stub()

Returns JSON for a JSONRPC request for this method

This is used to generate the introspection method output

rpc4django.rpcdispatcher.rpcmethod(**kwargs)

Accepts keyword based arguments that describe the method’s rpc aspects

Parameters

name

the name of the method to make available via RPC. Defaults to the method’s actual name

signature

the signature of the method that will be returned by calls to the XMLRPC introspection method system.methodSignature. It is of the form: [return_value, arg1, arg2, arg3, ...]. All of the types should be XMLRPC types (eg. struct, int, array, etc. - see the XMLRPC spec for details).

permission

the Django permission required to execute this method

login_required

the method requires a user to be logged in

Examples

@rpcmethod()
@rpcmethod(name='myns.myFuncName', signature=['int','int'])
@rpcmethod(permission='add_group')
@rpcmethod(login_required=True)

XMLRPC dispatcher

Implements an XMLRPC dispatcher

class rpc4django.xmlrpcdispatcher.XMLRPCDispatcher

Encodes and decodes XMLRPC messages, dispatches to the requested method and returns any responses or errors in encoded XML.

Subclasses SimpleXMLRPCDispatcher so that it can also pass the Django HttpRequest object from the underlying RPC request

dispatch(data, **kwargs)

Extracts the xml marshaled parameters and method name and calls the underlying method and returns either an xml marshaled response or an XMLRPC fault

Although very similar to the superclass’ _marshaled_dispatch, this method has a different name due to the different parameters it takes from the superclass method.

JSONRPC dispatcher

This module implements a JSON 1.0 compatible dispatcher

see http://json-rpc.org/wiki/specification

class rpc4django.jsonrpcdispatcher.JSONRPCDispatcher(json_encoder=None)

This class can be used encode and decode jsonrpc messages, dispatch the requested method with the passed parameters, and return any response or error.

dispatch(json_data, **kwargs)

Verifies that the passed json encoded string is in the correct form according to the json-rpc spec and calls the appropriate Python method

Checks

1. that the string encodes into a javascript Object (dictionary)
2. that ‘method’ and ‘params’ are present
3. ‘method’ must be a javascript String type
4. ‘params’ must be a javascript Array type

Returns the JSON encoded response

register_function(method, external_name)

Registers a method with the jsonrpc dispatcher.

This method can be called later via the dispatch method.

Template tags

Creates a template tag that can handle restructured text (reST)

rpc4django.templatetags.rpctags.resttext(text)

Returns text in reST format or plain text if resttext fails to import docutils or fails for any other reason

If RPC4DJANGO_RESTRICT_REST is True, just return text