RPC4Django Documentation

Version 0.1.0
July 6, 2009

1. Overview
2. License
3. Installation
4. Configuration
5. Planned Features
6. Change Log

Overview

Website

http://www.davidfischer.name/rpc4django

Contributors

• David Fischer

Features

RPC4Django is an XMLRPC and JSONRPC server for Django powered projects. Simply plug it into any existing Django project and you can make your methods available via XMLRPC and JSONRPC. In addition, it can display nice documentation about the methods it makes available in a more customizable way than DocXMLRPCServer.

• Detects request type (JSONRPC or XMLRPC) based on content type
• Easy identification of RPC methods via a decorator
• Pure python and requires no external modules except Django
• Customizable RPC method documentation
• 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

License

RPC4Django is licensed under the new BSD license.

Copyright © 2009, David Fischer
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of rpc4django nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY David Fischer ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL David Fischer BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Installation

Requirements

RPC4Django is written in pure python and should run on any platform where python and Django run. It requires no other external modules. It is tested on python2.5 and python2.6 using Django1.0.2-final on Mac OS 10.5.

Easy Install Method

$> easy_install rpc4django

Source Method

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

No Install Method

This method installs RPC4Django only for one specific django project but does not require any special system access. You are free to bundle and distribute RPC4Django with your project provided you adhere to the terms of the license.

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

Verifying The Package

A set of unit tests is included in rpc4django/tests.py. If these all pass, there should be no issues with rpc4django.

$> python rpc4django/tests.py

The unit tests can also be run on a live django project using:

$> python manage.py test rpc4django

Configuration

Adding To Your Django Project

After installation, there are only three steps to adding RPC4Django to your project.

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.

   Here's an example from the application "testapp":

   # 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 @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 two 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.

Customizing Method Documentation

By default, RPC4Django serves an HTML method summary when a GET request comes to the configured url pattern (by default r'^RPC2$'). A GET request does not contain an RPC payload. This HTML method summary can be customized (or even disabled -- see Optional Features below).

The documentation is served from a template in the templates/ directory. This template is rpc4django/rpcmethod_summary.html and can be customized in a similar way to the django admin.

Optional Features

There are some optional features that can configure the way in which RPC4Django handles requests. All of these settings should be placed in settings.py and are specific to a Django project.

• 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_DOCUMENTATION=True|False (default False)
  If RPC4DJANGO_RESTRICT_DOCUMENTATION=True, status code 404 will be returned instead of serving the method summary as a response to a GET request.

Planned Features

If you are interested in a particular feature either listed here or otherwise, please send me an email.

• Authenticated view that ties in with Django's auth system
• Testing an RPC method directly from the documentation (like XMLRPC for PHP)

Change Log

Version 0.1.0 (July 6, 2009)

• First version of RPC4Django