RPC4Django Documentation

Overview

License

RPC4Django is licensed under the BSD license.

Copyright (c) 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

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

$> easy_install rpc4django

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

Configuration

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 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.

Additional Information and Settings

Planned Features

• Authenticated view that ties in with Django's auth system
• Testing an RPC method directly from the documentation (like XMLRPC for PHP)
• Fix some failing unit tests on older python versions

Changelog

Version 0.1.1 (11 July 2009)

• Improved documentation by integrating reST
• Allowed reST markup in rpcmethod docstrings
• Fix easy_install problems related to django templates
• Tested version compatibility
• Allowed analyzing post data when content-type cannot tell whether the data is XML or JSON

Version 0.1.0 (6 July 2009)

• First version of RPC4Django