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.

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

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. The specification 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 sample XML-RPC services.
  
  
• If you plan to do significant work using the protocol, do read and bookmark Eric Kidd's XML-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-up XML-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 and Part 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 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 article

Comments

Back to top

Table of contents

• Clients
• XML-RPC servers
• Conclusion
• Resources
• About the authors
• Comments