RPC4Django Documentation

Features

• Detects request type (JSONRPC or XMLRPC) based on content
• Easy identification of RPC methods via a decorator
• Pure python and requires no external modules except Django
• Customizable RPC method documentation including reST
• Supports XMLRPC and JSONRPC introspection
• Supports method signatures (unlike SimpleXMLRPCServer)
• Easy installation and integration with existing Django projects
• Licensed for inclusion in open source and commercial software
• Ties in with Django's authentication and authorization

Project Website & More

Contributors

• David Fischer

Prerequisites

RPC4Django has been tested on Mac OS, Linux and Windows.

• Python 2.4 - 2.6
• Django 1.0+ (tested through 1.2.0 alpha)
• Docutils (optional)

Source Install Method

This is the preferred method for installing RPC4Django.

$> tar xvfz rpc4django-x.y.z.tar.gz
$> cd rpc4django-x.y.z
$> python setup.py install

Easy Install Method

$> easy_install rpc4django

Pip Install Method

$> pip install rpc4django

No Installation Method

This method installs RPC4Django only for one specific django project but does not require any special system access.

$> tar xvfz rpc4django-x.y.z.tar.gz
$> cd rpc4django-x.y.z
$> cp -r rpc4django YOUR_DJANGO_PROJECT_DIRECTORY

Usual Setup

1. First, you need to add new url pattern to your root urls.py file. This file should be the one pointed to by ROOT_URLCONF in settings.py. You can replace r'^RPC2$' with anything you like.

   # urls.py
   #...
   urlpatterns = patterns('',
       # if installed via no install method
       #(r'^RPC2$', 'YOURPROJECT.rpc4django.views.serve_rpc_request'),
   
       # if installed via source or easy_install
       (r'^RPC2$', 'rpc4django.views.serve_rpc_request'),
   )
   

2. Second, add RPC4Django to the list of installed applications in your settings.py.

   # settings.py
   #...
   INSTALLED_APPS = (
       # if installed via no install
       #'YOURPROJECT.rpc4django',
   
       # if installed via source or easy_install
       'rpc4django',
   )
   

3. Lastly, you need to let RPC4Django know which methods to make available. This is done with the decorator @rpcmethod. RPC4Django imports all the apps in INSTALLED_APPS and makes any methods importable via __init__.py with the @rpcmethod decorator available as RPC methods. You can always write your RPC methods in another module and simply import it in __init__.py.

   # testapp/__init__.py
   from rpc4django import rpcmethod
   
   # This imports another method to be made available as an RPC method
   # This method should also have the @rpcmethod decorator
   # from mymodule import myrpcmethod
   
   # The doc string supports reST if docutils is installed
   @rpcmethod(name='mynamespace.add', signature=['int', 'int', 'int'])
   def add(a, b):
       '''Adds two numbers together
       >>> add(1, 2)
       3
       '''
   
       return a+b
   

   The decorator @rpcmethod accepts three optional parameters:

   • name - is the name under which the method will be made externally available. It defaults to the method's real name.
   • signature - is the signature of the method and 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). Since python is relatively loosely typed, all types are set to object by default.
   • permission - the Django permission required to execute this method [new in 0.1.5]

Remotely Calling Methods

from xmlrpclib import ServerProxy
s = ServerProxy('http://localhost:8000')
s.system.listMethods()

from jsonrpc import ServiceProxy
s = ServiceProxy('http://localhost:8000')
s.rpc4django.mytestmethod(1,2,3)

Running the Unit Tests

The unit tests can be run using manage.py

$> python manage.py test rpc4django

How RPC4Django Handles Requests

• If the request is a GET request, return an HTML method summary
• A POST request with content-type header set to text/xml or application/xml will be processed as XMLRPC
• A POST request with content-type header containing json or javascript will be processed as JSONRPC
• Try to parse the POST data as xml. If it parses successfully, process it as XMLRPC
• Process it as JSONRPC

Method Summary

• The method summary displays docstrings, signatures, and names from methods marked with the @rpcmethod decorator.
• The method summary allows testing of methods via JSONRPC (unless it is disabled)
• The summary is served (unless it is disabled) from a template rpc4django/rpcmethod_summary.html and can be customized in a similar way to the django admin.
• The method summary supports reST in docstrings if the docutils library is installed. Plain text is used otherwise. ReST warnings and errors are not reported in the output.

Optional Settings

These are settings that can go in your project's settings.py:

RPC4DJANGO_LOG_REQUESTS_RESPONSES=True|False (default True)

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

RPC4DJANGO_RESTRICT_INTROSPECTION=True|False (default False)

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

RPC4DJANGO_RESTRICT_JSONRPC=True|False (default False)

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

RPC4DJANGO_RESTRICT_XMLRPC=True|False (default False)

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

RPC4DJANGO_RESTRICT_METHOD_SUMMARY=True|False (default False)

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

RPC4DJANGO_RESTRICT_RPCTEST=True|False (default False)

If RPC4DJANGO_RESTRICT_RPCTEST=True, the method summary will not allow testing via JSONRPC.

RPC4DJANGO_RESTRICT_REST=True|False (default False) [new in 0.1.4]

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

Authentication

RPC4Django can be used with authenticated HTTP(s) requests and Django's authentication and authorization. [new in 0.1.5, requires Django 1.1+] It uses RemoteUserMiddleware or another derived middleware which is only built-in to Django 1.1 and higher. It is possible to use it with Django versions prior to 1.1, but it would require the RemoteUserMiddleware and the RemoteUserBackend to be added manually.

MIDDLEWARE_CLASSES = (
    # ...
    # Must be enabled for RPC4Django authenticated method calls
    'django.contrib.auth.middleware.AuthenticationMiddleware',

    # Required for RPC4Django authenticated method calls
    # Requires Django 1.1+
    'django.contrib.auth.middleware.RemoteUserMiddleware',
)

# Required for RPC4Django authenticated method calls
# Requires Django 1.1+
AUTHENTICATION_BACKENDS = (
    'django.contrib.auth.backends.RemoteUserBackend',
)

from rpc4django import rpcmethod

@rpcmethod(name='rpc4django.secret', signature=['string'], permission='auth.add_group')
def secret():
    return "Successfully called a protected method"

from xmlrpclib import ServerProxy
s = ServerProxy('https://username:password@example.com')
s.rpc4django.secret()