tornadorpc 0.1.1

TornadoRPC is a an implementation of both JSON-RPC and XML-RPC handlers for the Tornado framework.

[](https://travis-ci.org/joshmarshall/tornadorpc)
TORNADO-RPC
===========
This library is an implementation of both the JSON-RPC and the
XML-RPC specification (server-side) for the Tornado web framework.
It supports the basic features of both, as well as the MultiCall /
Batch support for both specifications. The JSON-RPC handler supports
both the original 1.0 specification, as well as the new (proposed)
2.0 spec, which includes batch submission, keyword arguments, etc.

Asynchronous request support has been added for methods which require
the use of asynchronous libraries (like Tornado's AsyncHTTPClient
library.)

TornadoRPC is licensed under the Apache License, Version 2.0
(http://www.apache.org/licenses/LICENSE-2.0.html).

Mailing List
------------
If you have any questions, issues, or just use the library please feel
free to send a message to the mailing list at:

http://groups.google.com/group/tornadorpc

Installation
------------
To install:

python setup.py build
sudo python setup.py install

To use this module, you'll need Tornado installed, which you can
get at this address:

http://www.tornadoweb.org/

If you want to use the JSON-RPC handler, you'll also need
jsonrpclib, which you can grab at:

http://github.com/joshmarshall/jsonrpclib/

The jsonrpclib library requires one of the JSON libraries. It looks
first for cjson, then for the built-in JSON library (with default
Python 2.6+ distributions), and finally the simplejson library.

Overview
--------
This library is an implementation of both the JSON-RPC and the XML-RPC
specification (server-side) for the Tornado web framework. It supports
the basic features of both, as well as the MultiCall / Batch support for
both specifications. The JSON-RPC handler supports both the original 1.0
specification, as well as the new (proposed) 2.0 spec, which includes batch
submission, keyword arguments, etc.

There is also a base library that other RPC protocols could use to quickly
get tied into Tornado.

Requirements
------------
The library obviously requires Tornado, which you can get at
Tornado's website (http://www.tornadoweb.org). After installing Tornado
(instructions included with the Tornado distribution) you should be able
to use the XML-RPC handler without any other libraries.

The JSON-RPC handler requires my jsonrpclib library, which you can get
at http://github.com/joshmarshall/jsonrpclib . It also requires a JSON
library, although any distribution of Python past 2.5 should have it by
default. (Note: Some Linuxes only include a base Python install. On Ubuntu,
for instance, you may need to run `sudo apt-get install python-json` or
`sudo apt-get python-cjson` to get one of the libraries.)

Usage
-----
The library is designed to be mostly transparent in usage. You simply
extend the XML/JSON RPCHandler class from either the tornadorpc.xml or
the tornado.json library, resepectively, and pass that handler in to
the Tornado framework just like any other handler.

For any synchronous (normal) operation, you can just return the value
you want sent to the client. However, if you use any asynchronous
library (like Tornado's AsyncHTTPClient) you will want to call
self.result(RESULT) in your callback. See the Asynchronous section
below for examples.

XML-RPC Example
---------------
To set up a simple XML RPC server, this is all you need:

from tornadorpc.xml import XMLRPCHandler
from tornadorpc import private, start_server

class Handler(XMLRPCHandler):

def add(self, x, y):
return x+y

def ping(self, obj):
return obj

@private
def private(self):
#should not get called
return False

start_server(Handler, port=8080)

The `@private` decorator is a way to ensure that it cannot be called
externally. You can also create methods that start with an underscore `_`
character, and they will be private by default. The `start_server` function
is just an easy wrap around the default Tornado setup -- you can use these
handlers just like you would any other Tornado RequestHandler.

JSON-RPC Example
----------------
A JSON-RPC server would be started with the exact same syntax, replacing
XMLRPCHandler with JSONRPCHandler. Here is an example of the JSON-RPC
client with "dot-attribute" support:

from tornadorpc.json import JSONRPCHandler
from tornadorpc import private, start_server

class Tree(object):

def power(self, base, power, modulo=None):
result = pow(base, power, modulo)
return result

def _private(self):
# Won't be callable
return False

class Handler(JSONRPCHandler):

tree = Tree()

def add(self, x, y):
return x+y

def ping(self, obj):
return obj

start_server(Handler, port=8080)

To use this, you should be able to use either the JSON-RPC official
implementation, or the jsonrpclib library (which you'd need for this to
work anyway.) One of the benefits of the jsonrpclib is designed to be a
parallel implementation to the xmlrpclib, so syntax should be very similar
and it should be easy to experiment with existing apps.

An example of client usage would be:

from jsonrpclib import Server
server = Server('http://localhost:8080')
result = server.tree.power(2, 6)
# result should equal 64

Asynchronous Example
--------------------
To indicate that a request is asynchronous, simply use the "async"
decorator, and call "self.result(RESULT)" in your callback. Please note
that this will only work in the RPCHandler methods, not in any sub-tree
methods since they do not have access to the handler's result() method.

Here is an example that uses Tornado's AsyncHTTPClient with a callback:

from tornadorpc import async
from tornadorpc.xml import XMLRPCHandler
from tornado.httpclient import AsyncHTTPClient

class Handler(XMLRPCHandler):

@async
def external(self, url):
client = AsyncHTTPClient()
client.fetch(url, self._handle_response)

def _handle_response(self, response):
# The underscore will make it private automatically
# You could also use @private if you wished
# This returns the status code of the request
self.result(response.code)

Debugging
---------
There is a `config` object that is available -- it will be expanded as time
goes by. Currently, it supports two options: `verbose` and `short_errors`,
both of which default to True. The `verbose` setting just specifies whether
you want to print out results to the terminal (automatically on, you'll
probably want to turn that off for production, WSGI deployment, etc.) and
the `short_errors` option determines whether to print just the last few
lines of the traceback (if set to True, default) or print the full traceback.
Once the logging mechanism is in place, the `short_errors` configuration
element will apply to that as well.

The default error look something similar to this:

JSON-RPC SERVER AT http://localhost:8484
---------------
ERROR IN messup
---------------
Traceback (most recent call last):
File "test.py", line 20, in messup
return doesntexist['bad_key']
NameError: global name 'doesntexist' is not defined

To change the configuration, look over the following:

import tornadorpc
tornadorpc.config.verbose = False
tornadorpc.config.short_errors = False
# or...
from tornadorpc import config
config.verbose = False
config.short_errors = False

Tests
-----
To run some basic tests, enter the following in the same directory that
this README is in:

python run_tests.py

This will test a few basic utilites and the XMLRPC system. If you wish
to test the JSONRPC system, run the following:

python run_tests.py --json

TODO
----
* Add unit tests
* Add logging mechanism
* Add proper HTTP codes for failures
* Optimize