Summary:  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 (seeResources 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 theServerProxy 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 namedcurrentTime.
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 itsvalue 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 aspseudo_object.foo, that allows
clients to treat it as a call to a methodfoo on a remote object namedpseudo_object. However, as far as XML-RPC protocol is concerned, this is just a method namedpseudo_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

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 specialFault object is used for exception handling.Boolean might be going away since Python 2.3 introduces a native
boolean typebool.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 corruptedby the remote server:

$ python stringecho.py

Freude, schnergtterfunken

This is because although Python supports Unicode strings, the remotesystem does not. XML-RPC oficially only specifies ASCII as a stringencoding, 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), aProtocolError exception object is raised rather than aFault object.

Back to top

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 theSimpleXMLRPCServer 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

Back to top

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

• Participate in the discussion forum.
• Start your exploration of XML-RPC on the official home page. Thespecification is also a very easy read.
• For reference, use the official Python docs for the XML-RPC client and server modules.
• UserLand provides a XML-RPC interface for Current Time.
• Browse Useful Information Company's XML-RPC page for more sampleXML-RPC services.
• If you plan to do significant work using the protocol, do read and bookmark Eric Kidd'sXML-RPC HOWTO.

• Read Using XML-RPC for web services: Getting started with XML-RPC in Perl, by Joe Johnston for an introduction to XML-RPC, and the follow-upXML-RPC
  Middleware.
• And if XML-RPC doesn't cut it for you, don't forget our recent coverage of SOAP libraries for Python:Part 1,Part
  2 andPart 3

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 develops4Suite, an open source platform for XML middleware. You can contact Mr.
Olson atmike.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 develops4Suite, 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 atuche@ogbuji.net.