 | Level: Introductory Mike Olson (mike.olson@fourthought.com), Principal Consultant, Fourthought, Inc.
Uche Ogbuji (uche@ogbuji.net), Principal Consultant, Fourthought, Inc.
19 Sep 2002 XML-RPC is a simple, lightweight Web services technology that predates SOAP. In this installment of the Python Web services developer, Mike Olson and Uche Ogbuji examine the XML-RPC facilities in Python.
XML-RPC is the granddaddy of XML Web services. It is a simple specification for remote procedure calls (RPC) that uses HTTP as the transport protocol and an XML vocabulary as the message payload. It has become very popular because of its simplicity (the full specification is less than ten printed pages), and most languages now have standard or readily available XML-RPC implementations. This includes Python, which started bundling xmlrpclib, an XML-RPC implementation by Fredrik Lundh, in version 2.2. Joe Johnston's IBM developerWorks article "Using XML-RPC for Web services" (see Resources) covers the basics of XML-RPC in the first three sections. Start there if you need to review the basic technology. In this article, we will focus on using the Python implementation. You must have Python 2.2. to run the examples in this article. Also, in the last article, we looked at the relative performance of XML-RPC, SOAP, and other distributed programming technologies. You may want to read that before making major decisions to deploy XML-RPC.
Clients
Writing a Python XML-RPC client is very easy. The module xmlrpclib has all the needed machinery. In order to invoke a remote XML-RPC object, you create a proxy object which forwards requests to the server using XML-RPC. The proxy object looks and feels just like a regular Python object, and your requests are simple function calls. Listing 1 (currtime.py) uses XML-RPC to get the current time from the UserLand server (see Resources for more information about this service).
import xmlrpclib
#Port 80 is the default
server = xmlrpclib.ServerProxy("http://time.xmlrpc.com")
currentTimeObj = server.currentTime
currtime = currentTimeObj.getCurrentTime()
print currtime
print currtime.value
|
What is actually being proxied is the server, which is set up by initializing an instance of the ServerProxy class. We pass in the full URL of the remote server (you must include the URL scheme "http://"). Port 80 is the default, as usual. If the remote server were instead listening on port 8080, we would use "http://time.xmlrpc.com:8080". The server proxy has all the actual remote objects they host as regular attributes, and in this way we get a handle to the remote object named currentTime. Now we can simply call the method on this proxy object, which returns the current time. The response is of a special XML-RPC type called a DateTime. To get a plain string representation of this object, we use its value attribute.
One important clarification: the idea of distinct proxy objects within the server is really an illusion. XML-RPC allows method names to have periods in them, and it is a common convention to use method names such as pseudo_object.foo, that allows clients to treat it as a call to a method foo on a remote object named pseudo_object. However, as far as XML-RPC protocol is concerned, this is just a method named pseudo_object.foo defined on the remote server. You'll see later on why this distinction is important.
The result of running the script:
$ python currtime.py
<DateTime 20020808T10:43:06 at 81dd0ec>
20020808T10:43:06
|
Special types
DataType, as we've seen, is one special type used in Python's XML-RPC implementation based on the specification. It must be used for input and output to XML-RPC systems if they require such types. In other words, if a remote function takes a DateTime argument, you cannot send it a string such as "20020808T10:43:06". You would first construct an instance of the DateTime class. For instance:
datetime_arg = xmlrpclib.DateTime("20020808T10:43:06")
remote_obj.method(datetime_arg)
|
There are a few other such special types. Boolean and Binary are basic data types, and the special Fault object is used for exception handling. Boolean might be going away since Python 2.3 introduces a native boolean type bool. Binary is distinct from strings in that it does not restrict what bytes can be transmitted. The other XML-RPC types are represented by native Python objects, with lists and tuples standing in for arrays and dictionaries for structures. One important warning is about character encodings. A much-criticized limitation of XML-RPC is that it only supports the transmission of ASCII strings (or binary buffers). It offers no character encoding support at all. Listing 2 tries to use Useful Inc's sample string echo service (which simply takes a string and returns the same string).
import xmlrpclib
server = xmlrpclib.ServerProxy("http://xmlrpc.usefulinc.com/demo/server.php")
eg_obj = server.examples
result = eg_obj.stringecho(u"Freude, schönergötterfunken")
print unicode(result)
|
However, if you run it, you will find that the string has been corrupted
by the remote server:
$ python stringecho.py
Freude, schnergtterfunken
|
This is because although Python supports Unicode strings, the remote
system does not. XML-RPC oficially only specifies ASCII as a string
encoding, a well-known and unfortunate limitation.
The first attractive solution to encode to UTF-8, unfortunately, will not work since UTF-8 does not "fit" into the 7-bit ASCII range. One could use is to use UTF-7, which does fit into ASCII range, but this is a less common and more verbose encoding. To use UTF-7, replace the relevant line with:
result = eg_obj.stringecho(u"Freude,schönergötterfunken".encode("utf-7"))
|
resulting in:
$ python stringecho.py
Freude, sch+APY-ne g+APY-tterfunken
|
This is unfortunate because it distorts the value being sent remotely, and requires an out-of-band understanding between the parties that strings being passed are in UTF-7 encoding. If this sort of communication can be established between the parties, the server could also accept binary objects rather than strings, which means that UTF-8 could be used. But this is just hacking around a glaring fault in the protocol itself, and perhaps a good reason to consider SOAP, which is properly internationalized.
Handling faults
When the server needs to signal an error, it does so using an XML-RPC fault. This is interpreted in Python using a special exception object which gives a fault code and descriptive string. Listing 3 (getstate.py) uses an XML-RPC service for returning a state name according to a number passed in which represents the index of the state in alphabetic order. We purposefully use a bogus value of -1 which causes the server to raise a fault:
import xmlrpclib
server = xmlrpclib.ServerProxy("http://xmlrpc.usefulinc.com/demo/server.php")
eg_obj = server.examples
try:
result = eg_obj.getStateName(-1)
except xmlrpclib.Fault, fault:
print fault.faultCode
print fault.faultString
|
Which results in:
$ python getstate.py
800
I don't have a state for the index '-1'
|
If it is the XML-RPC machinery rather than the service itself that encounters a problem (for instance, you give it a URL that cannot be reached), a ProtocolError exception object is raised rather than a Fault object.
XML-RPC servers
Python also comes with SimpleXMLRPCServer, a module for implementing XML-RPC servers. You can register functions or instances with an instance of the SimpleXMLRPCServer class in the module of the same name, in order to expose XML-RPC services. The most straightforward way is to just write an instance with methods that do what you need, and then register this instance. However, in this case, method names cannot have periods, and so the trickery we discussed above to make things appear as if there are multiple objects represented by the server is unavailable. The effect of this will become clear soon, but first of all, let us create a calendar server such as the one we've been using to demonstrate SOAP servers. Listing 4 (calserver.py) is the XML-RPC calendar server implementation:
import calendar, SimpleXMLRPCServer
#The server object
class Calendar:
def getMonth(self, year, month):
return calendar.month(year, month)
def getYear(self, year):
return calendar.calendar(year)
calendar_object = Calendar()
server = SimpleXMLRPCServer.SimpleXMLRPCServer(("localhost", 8888))
server.register_instance(calendar_object)
#Go into the main listener loop
print "Listening on port 8888"
server.serve_forever()
|
The class Calendar implements the methods we wish to expose. They take numbers and return strings. We create an instance of this object and then an instance of the XML-RPC server class, with which we register the calendar instance. This now makes the methods getMonth and getYear available on the server. Remember that Python is dynamically typed, and that you will want to add type-checking code to the methods in most cases. Of course Python's rich expressiveness makes this a breeze, and also means that you can easily do more sophisticated type checking than most languages allow. In the main code, we create a server object, giving it a tuple representing the listening address and port. The address can be a host name or IP address. Finally, we put this server into its main loop, which is only broken when an operating system signal interrupts it, such as when the user presses CTRL-C. Open up a separate console and run the server script.
To test the server, we write a simple client in Listing 5 (calclient.py):
import xmlrpclib
server = xmlrpclib.ServerProxy("http://localhost:8888")
month = server.getMonth(2002, 8)
print month
|
And here you can see the effect of our not having a period in the method names. Rather than first of all obtaining a pseudo-object from the server (which really just represents an abstraction of the part of the method name before the period), we simply call the method on the server proxy itself. The resulting output is:
$ python calclient.py
August 2002
Mo Tu We Th Fr Sa Su
1 2 3 4
5 6 7 8 9 10 11
12 13 14 15 16 17 18
19 20 21 22 23 24 25
26 27 28 29 30 31
|
Conclusion
XML-RPC is simpler than SOAP, and is very popular in open-source projects. It is an essential toolkit for any language or framework to offer these days, and so Python's new XML-RPC modules are a welcome addition. However, it does have its weaknesses, chief of which is its support for character encodings, which shows an appalling bias towards English which seems out of place in these days when the importance of internationalization is well understood.
In the next installment we shall examine Python tools for another Web services interface that has gained widespread popularity: RDF site summary (RSS).
Resources
About the authors | 
| |
Mike Olson is a consultant and co-founder of Fourthought Inc., a software vendor and consultancy specializing in XML solutions for enterprise knowledge management applications. Fourthought develops 4Suite, an open source platform for XML middleware.
You can contact Mr. Olson at mike.olson@fourthought.com. |
| 
| | Uche Ogbuji is a consultant and co-founder of Fourthought Inc., a software vendor and consultancy specializing in XML solutions for enterprise knowledge management applications. Fourthought develops 4Suite, open source platforms for XML middleware.
Mr. Ogbuji is a Computer Engineer and writer born in Nigeria, living and working in Boulder, Colorado, USA. You can contact Mr. Ogbuji at uche@ogbuji.net. |
Rate this page
| |
