Raw Paste

Implementing Web Services with Quixote ====================================== This document will show you how to implement Web services using Quixote. An XML-RPC Service ------------------ XML-RPC is the simplest protocol commonly used to expose a Web service. In XML-RPC, there are a few basic data types such as integers, floats, strings, and dates, and a few aggregate types such as arrays and structs. The xmlrpclib module, part of the Python 2.2 standard library and available separately from http://www.pythonware.com/products/xmlrpc/, converts between Python's standard data types and the XML-RPC data types. ============== ===================== XML-RPC Type Python Type or Class -------------- --------------------- <int> int <double> float <string> string <array> list <struct> dict <boolean> xmlrpclib.Boolean <base64> xmlrpclib.Binary <dateTime> xmlrpclib.DateTime ============== ===================== Making XML-RPC Calls -------------------- Making an XML-RPC call using xmlrpclib is easy. An XML-RPC server lives at a particular URL, so the first step is to create an xmlrpclib.ServerProxy object pointing at that URL. :: >>> import xmlrpclib >>> s = xmlrpclib.ServerProxy( 'http://www.stuffeddog.com/speller/speller-rpc.cgi') Now you can simply make a call to the spell-checking service offered by this server:: >>> s.speller.spellCheck('my speling isnt gud', {}) [{'word': 'speling', 'suggestions': ['apeling', 'spelding', 'spelling', 'sperling', 'spewing', 'spiling'], 'location': 4}, {'word': 'isnt', 'suggestions': [``isn't'', 'ist'], 'location': 12}] >>> This call results in the following XML being sent:: <?xml version='1.0'?> <methodCall> <methodName>speller.spellCheck</methodName> <params> <param> <value><string>my speling isnt gud</string></value> </param> <param> <value><struct></struct></value> </param> </params> </methodCall> Writing a Quixote Service ------------------------- In the quixote.util module, Quixote provides a function, ``xmlrpc(request, func)``, that processes the body of an XML-RPC request. ``request`` is the HTTPRequest object that Quixote passes to every function it invokes. ``func`` is a user-supplied function that receives the name of the XML-RPC method being called and a tuple containing the method's parameters. If there's a bug in the function you supply and it raises an exception, the ``xmlrpc()`` function will catch the exception and return a ``Fault`` to the remote caller. Here's an example of implementing a simple XML-RPC handler with a single method, ``get_time()``, that simply returns the current time. The first task is to expose a URL for accessing the service. :: from quixote.directory import Directory from quixote.util import xmlrpc from quixote import get_request class RPCDirectory(Directory): _q_exports = ['rpc'] def rpc (self): return xmlrpc(get_request(), rpc_process) def rpc_process (meth, params): ... When the above code is placed in the __init__.py file for the Python package corresponding to your Quixote application, it exposes the URL ``http://<hostname>/rpc`` as the access point for the XML-RPC service. Next, we need to fill in the contents of the ``rpc_process()`` function:: import time def rpc_process (meth, params): if meth == 'get_time': # params is ignored now = time.gmtime(time.time()) return xmlrpclib.DateTime(now) else: raise RuntimeError, "Unknown XML-RPC method: %r" % meth ``rpc_process()`` receives the method name and the parameters, and its job is to run the right code for the method, returning a result that will be marshalled into XML-RPC. The body of ``rpc_process()`` will therefore usually be an ``if`` statement that checks the name of the method, and calls another function to do the actual work. In this case, ``get_time()`` is very simple so the two lines of code it requires are simply included in the body of ``rpc_process()``. If the method name doesn't belong to a supported method, execution will fall through to the ``else`` clause, which will raise a RuntimeError exception. Quixote's ``xmlrpc()`` will catch this exception and report it to the caller as an XML-RPC fault, with the error code set to 1. As you add additional XML-RPC services, the ``if`` statement in ``rpc_process()`` will grow more branches. You might be tempted to pass the method name to ``getattr()`` to select a method from a module or class. That would work, too, and avoids having a continually growing set of branches, but you should be careful with this and be sure that there are no private methods that a remote caller could access. I generally prefer to have the ``if... elif... elif... else`` blocks, for three reasons: 1) adding another branch isn't much work, 2) it's explicit about the supported method names, and 3) there won't be any security holes in doing so. An alternative approach is to have a dictionary mapping method names to the corresponding functions and restrict the legal method names to the keys of this dictionary:: def echo (*params): # Just returns the parameters it's passed return params def get_time (): now = time.gmtime(time.time()) return xmlrpclib.DateTime(now) methods = {'echo' : echo, 'get_time' : get_time} def rpc_process (meth, params): func = methods.get[meth] if methods.has_key(meth): # params is ignored now = time.gmtime(time.time()) return xmlrpclib.DateTime(now) else: raise RuntimeError, "Unknown XML-RPC method: %r" % meth This approach works nicely when there are many methods and the ``if...elif...else`` statement would be unworkably long.

---

Login or Register to edit or fork this paste. It's free.