Find file
Fetching contributors…
Cannot retrieve contributors at this time
302 lines (216 sloc) 10.1 KB
#!/usr/bin/env python
from setuptools import setup
except ImportError:
from distutils.core import setup
description="A simple JSON-RPC implementation for Django",
* Simple, pythonic API
* Support for Django authentication
* Supports JSON-RPC 1.0, 1.1, 1.2 and 2.0 Spec
* Proxy to test your JSON Service
* Run-time type checking
* Graphical JSON-RPC browser and web console
* Provides system.describe
**The basic API**
## myproj/myapp/
from jsonrpc import jsonrpc_method
def whats_the_time(request, name='Lester'):
return "Hello %s" % name
@jsonrpc_method('myapp.gimmeThat', authenticated=True)
def something_special(request, secret_data):
return {'sauce': ['authenticated', 'sauce']}
## myproj/
from django.conf.urls.defaults import *
from jsonrpc import jsonrpc_site
import myproj.myapp.views # you must import the views that need connected
urlpatterns = patterns('',
url(r'^json/browse/', 'jsonrpc.views.browse', name="jsonrpc_browser"), # for the graphical browser/web console only, omissible
url(r'^json/', jsonrpc_site.dispatch, name="jsonrpc_mountpoint"),
(r'^json/(?P<method>[a-zA-Z0-9.]+)$', jsonrpc_site.dispatch) # for HTTP GET only, also omissible
**To test your service**
You can test your service using the provided graphical browser and console,
available at http://YOUR_URL/json/browse/ (if using the url patterns from above)
or with the included ServiceProxy::
>>> from jsonrpc.proxy import ServiceProxy
>>> s = ServiceProxy('http://localhost:8080/json/')
>>> s.myapp.sayHello('Sam')
{u'error': None, u'id': u'jsonrpc', u'result': u'Hello Sam'}
>>> s.myapp.gimmeThat('username', 'password', 'test data')
{u'error': None, u'id': u'jsonrpc', u'result': {u'sauce': [u'authenticated', u'sauce']}}
Method Browser:
.. image::
We add the `jsonrpc_version` variable to the request object. It be either
'1.0', '1.1' or '2.0'. Arg.
Adding JSON-RPC to your application
**1. Install django-json-rpc**
git clone git://
cd django-json-rpc
python install
# Add 'jsonrpc' to your INSTALLED_APPS in your file
**2. Write JSON-RPC methods**
from jsonrpc import jsonrpc_method
def register_user(request, username, password):
u = User.objects.create_user(username, '', password)
return u.__dict__
@jsonrpc_method('app.change_password', authenticated=True)
def change_password(request, new_password):
return u.__dict__
**3. Add the JSON-RPC mountpoint and import your views**
from jsonrpc import jsonrpc_site
import app.views
urlpatterns = patterns('',
url(r'^json/$', jsonrpc_site.dispatch, name='jsonrpc_mountpoint'),
# ... among your other URLs
The jsonrpc_method decorator
Wraps a function turns it into a json-rpc method. Adds several attributes to
the function speific to the JSON-RPC machinery and adds it to the default
jsonrpc_site if one isn't provided. You must import the module containing these
functions in your
``jsonrpc.jsonrpc_method(name, authenticated=False, safe=False, validate=False)``
The name of your method. IE: `namespace.methodName` The method name
can include type information, like `ns.method(String, Array) -> Nil`.
Adds `username` and `password` arguments to the beginning of your
method if the user hasn't already been authenticated. These will
be used to authenticate the user against `django.contrib.authenticate`
If you use HTTP auth or other authentication middleware, `username`
and `password` will not be added, and this method will only check
against `request.user.is_authenticated`.
You may pass a callablle to replace `django.contrib.auth.authenticate`
as the authentication method. It must return either a User or `None`
and take the keyword arguments `username` and `password`.
Designates whether or not your method may be accessed by HTTP GET.
By default this is turned off.
Validates the arguments passed to your method based on type
information provided in the signature. Supply type information by
including types in your method declaration. Like so:
@jsonrpc_method('myapp.specialSauce(Array, String)', validate=True)
def special_sauce(self, ingredients, instructions):
return SpecialSauce(ingredients, instructions)
Calls to `myapp.specialSauce` will now check each arguments type
before calling `special_sauce`, throwing an `InvalidParamsError`
when it encounters a discrepancy. This can significantly reduce the
amount of code required to write JSON-RPC services.
Defines which site the jsonrpc method will be added to. Can be any
object that provides a `register(name, func)` method.
Using type checking on methods (Python 2.6 or greater)
When writing web services you often end up manually checking the
types of parameters passed. django-json-rpc provides a way to eliminate
much of that code by specifying the types in your method signature. As
specified in the JSON-RPC spec the available types are ``Object Array Number
Boolean String Nil`` and ``Any`` meaning any type::
@jsonrpc_method('app.addStrings(arg1=String, arg2=String) -> String', validate=True)
def add_strings(request, arg1, arg2):
return arg1 + arg2
However contrived this example, a lot of extra information about our
function is available. The ``system.describe`` method will automatically
be able to provide more information about the parameters and return type.
Provide ``validate=True`` to the ``jsonrpc_method`` decorator and you can be
guaranteed to receive two string objects when ``add_strings`` is called.
**Note:** Return type information is used only for reference, return value
types are not checked.
Types can be specified a number of ways, the following are all equivalent::
# using JSON types:
@jsonrpc_method('app.findSelection(query=Object, limit=Number)')
# using Python types:
@jsonrpc_method('app.findSelection(query=dict, limit=int)')
# with mixed keyword parameters
@jsonrpc_method('app.findSelection(dict, limit=int)')
# with no keyword parameters
@jsonrpc_method('app.findSelection(dict, int)')
# with a return value
@jsonrpc_method('app.findSelection(dict, int) -> list')
Using the browser
To access the browser simply add another entry to your ```` file, before
the json dispatch one. Make sure to include the name attribute of each url::
urlpatterns = patterns('',
url(r'^json/browse/$', 'jsonrpc.views.browse', name='jsonrpc_browser')
url(r'^json/', jsonrpc_site.dispatch, name="jsonrpc_mountpoint"),
Enabling HTTP-GET
JSON-RPC 1.1 includes support for methods which are accessible by HTTP GET
which it calls idempotent. Add the following to your ```` file to set
up the GET URL::
urlpatterns += patterns('',
(r'^json/(?P<method>[a-zA-Z0-9.-_]+)$', jsonrpc_site.dispatch),
Each method that you want to be accessible by HTTP GET must also be marked safe
in the method decorator::
@jsonrpc_method('app.trimTails(String)', safe=True)
def trim_tails(request, arg1):
return arg1[:5]
You can then call the method by loading ``/jsonrpc/app.trimTails?arg1=omgnowai``
Using authentication on methods
There is no specific support for authentication in the JSON-RPC spec beyond
whatever authentication the transport offers. To restrict access to methods
to registered users provide ``authenticated=True`` to the method decorator. Doing
so will add two arguments to the beginning of your method signature, ``username``
and ``password`` (and always in that order). By default, the credentials are
authenticated against the builtin ``User`` database but any method can be used::
@jsonrpc_method('app.thupertheecrit', authenticated=True)
def thupertheecrit(request, value):
p = request.user.get_profile()
p.theecrit = value
return p.__dict__
Using your own authentication method::
def mah_authenticate(username, password):
return CustomUserClass.authenticate(username, password)
@jsonrpc_method('app.thupertheecrit', authenticated=mah_authenticate)
def thupertheecrit(request, value):
request.user.theecrit = value
return request.user.__dict__
In case authentication is handled before your method is called, like in some
middleware, providing ``authenticated=True`` to the method decorator will only
check that ``request.user`` is authenticated and won't add any parameters to
the beginning of your method.
author="Samuel Sutch",
classifiers = [
'Development Status :: 5 - Production/Stable',
'Environment :: Web Environment',
'Intended Audience :: Developers',
'License :: OSI Approved :: MIT License',
'Operating System :: OS Independent',
'Programming Language :: Python',
'Topic :: Software Development :: Libraries :: Python Modules'],
zip_safe = False, # we include templates and tests
package_data={'jsonrpc': ['templates/*']})