Installation
============

Prerequisites
-------------

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

- `Python <http://www.python.org>`_ 2.4 - 2.6
- `Django <http://www.djangoproject.com>`_ 1.0+
- `Docutils <http://docutils.sourceforge.net>`_ (optional)

Source Install Method
---------------------
This is the preferred method for installing RPC4Django. It may require special privileges such as sudo.

::

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

Easy Install Method
-------------------
RPC4Django can be installed this way if setuptools is installed and easy_install is in your path. 
It may require special privileges such as sudo.

::

    $> easy_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    


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 <http://www.xmlrpc.com/spec>`_ for details). Since python is relatively loosely typed, all types are set to object by default.
	
        