xmlrpcserver - a simple and complete XML-RPC server module for python

xmlrpcserver includes compliance to and announcement of the following de-facto standards:

• XML-RPC
• system.getCapabilities
• Fault Code Interoperability

Here is a completely operational example for usage as CGI:

#!/usr/bin/env python

import sys
from xmlrpcserver import XmlRpcServer

def testmethod(meta, argument1, argument2):
    print (meta, argument1, argument2)
    return [1, 2, 3, 4]

server = XmlRpcServer()
server.register('test.test', testmethod)

# read the request, perform the call and send the response
sys.stdout.write("Content-type: text/xml\n\n")
server.execute()

In addition to the possibility of registering single methods you may also register whole classes.

xmlrpcserver also includes a handy standalone HTTP server, XmlRpcHTTPServer, derived from both BaseHTTPServer.HTTPServer and XmlRpcServer. Additional connection data is provided with the metadata dictionary.

Table of Contents

• Overview
• Table of Contents
• About XML-RPC and this modules
• Prerequisites
• Installation
• Usage
  • obtaining an XmlRpcServer instance
  • registering methods
  • processing a request
  • method arguments
  • the metadata dictionary
  • method return value
  • Fault and exception handling
  • internal methods
  • further tweaking
  • XmlRpcHTTPServer
• Acknowledgements
• Contact the author
• Download
• License
• Changelog

XML-RPC is a Remote Procedure Calling protocol that works over the Internet.

An XML-RPC message is an HTTP-POST request. The body of the request is in XML. A procedure executes on the server and the value it returns is also formatted in XML.

Procedure parameters can be scalars, numbers, strings, dates, etc.; and can also be complex record and list structures.

The Python standard distribution already includes a handy module named xmlrpclib which implements the general parts of the XML-RPC specification and an XML-RPC client. Part of those general parts are convenience functions and classes to marshall and unmarshall XML-RPC requests and responses which may also be used to implement an XML-RPC server. Doing so is pretty easy for small tasks, however, if you want to do it right, you'll quickly find yourself reimplementing things like method dispatching, fault and exception handling and even standard methods over and over again.

While implementing a small XML-RPC server using xmlrpclib for another project, that small server quickly evolved into a more powerful and simple to use generic XML-RPC server which, in the meantime also being used in other projects, allowed me to instantiate a new server in just one line, register methods to it in no time and serving requests as CGI or in Web Applications without noticeable code overhead.

So, I eventually decided that it may be useful for others, as it reduces implementation of new custom XML-RPC servers to virtually no time and started to clean up the code, document it, package it and release it online. Well, here's the result, and I hope you find it useful and like working with it. Even if you don't, you can still contact me according to the Contact section of this document for bug reports, improvement and feature requests, patches, flames or pie. I especially like the "pie" part.

Prerequisites

xmlrpcserver is completely written in Python, with no additional code in C or any other language. It currently uses the Python modules sys, xmlrpclib, StringIO and BaseHTTPServer, all of which are Python standard modules and thus available with the Python standard distribution.

No additional modules or software is needed.

Installaton

import xmlrpcserver

obtaining an XmlRpcServer instance

XmlRpcServer is the class containing the actual XML-RPC server, which reads a request from a stream, unmarshalls the request using xmlrpclib and dispatches the call to a method priorly registered to this server. After the call finished, it sends out the marshalled response consisting of either the return value of the called method if it succeeded or a XML-RPC Fault if the method raised a Fault or any exception.

The constructor of XmlRpcServer is called with the following arguments:

    XmlRpcServer(rpcmethods={}, rpcclasses={})

    from xmlrpcserver import XmlRpcServer

    server = XmlRpcServer()

    register(methodname, method)

    def myfunction (meta, argument1, argument2):
        print (meta, argument1, argument2)
        return 'success!'

    server.register('myclass.mymember', myfunction)

    class myexampleclass:
        def method1 (self, meta, oneargument, anotherone):
            print (meta, oneargument, anotherone)
            return 0

        def method2 (self, meta, *args)
            sys.exit(0)

    myinstance = myexampleclass()
    server.register_class('myclass', myinstance)

Registered methods or classes may be unregistered at any time using unregister(methodname) or unregister_class(classname).

processing a request

If no exception (other than an xmlrpclib.Fault) occured, execute() returns a tuple of the form (rpccall, params, result, meta) which consists of the complete method name (including class and all dots) of the request, its parameters, the result (which may also be a xmlrpclib.Fault) and the supplied meta data. This is useful for logging purposes.

execute() arguments

  execute (request=sys.stdin, response=sys.stdout, meta=None)

If you want to use strings for request and response, you can do so by using the StringIO module which wraps strings in streams.

request is the stream where the incoming XML request document is read from. No seek is performed, prior to reading, so the current position of the stream must point to the beginning of the document (this is already fine for CGIs, their stdin should only contain that document).

response is the stream where every response gets written to, again as an appropriate XML document. It may be the same stream as request, but doesn't have to.

meta is a dictionary consisting of additional metadata you might want to provide. It can be left empty or 'None', server metadata will still be filled in. The whole subject of metadata is subscribed later.

execute() returns after exactly one XML-RPC request has been processed, specifically: after processing one incoming request from the 'request' stream, calling the method if possible and sending out the response to the 'response' stream. If you want to serve several requests consecutively, you have to loop yourself.

execute() return value

example: CGI usage

Almost, because prior to sending content, the webserver requires you to at least send a "Content-type" header, possibly along with other headers you might want to send.

However, once you called execute() the only possible output following from that point on can and will be an XML document. So you can hardwire the "Content-type" header by doing this prior to execute():

      sys.stdout.write("Content-type: text/xml\n\n")

      #!/usr/bin/env python

      import sys
      from xmlrpc import XmlRpcServer

      server = XmlRpcServer()

      # you might want to register methods here

      sys.stdout.write("Content-type: text/xml\n\n")
      server.execute()

• the first argument is always a dictionary containing metadata
• starting with the second argument, all arguments included in the originating XML-RPC request are given "as is", or more specifically as they have been unmarshalled by xmlrpclib.

    myfunction({...}, 'hello server!', [9, 8, 7])

This also means that your callable which you map your XML-RPC method to should be defined to accept the right number of arguments. Failure to do so will result in Python throwing a TypeError exception which is catched by XmlRpcServer, reported to the calling client as a XML-RPC Fault (-32500, application error) and then rethrowed to your application (see the section about exceptions and faults for details).

However, if you'd like your method to be called with a variable number of arguments, you can of course just use default arguments or python's syntax for arbitrary argument lists to get them wrapped up in a tuple. Since xmlrpcserver translates XML-RPCs to ordinary calls, everything is just like you would do it without XML-RPC:

    def withdefaultargs (meta, mandatoryarg, optionalarg=1234):
        ...
    def completelyvariable (meta, *variableargs):
        ...

Simple examples:

    return 42
    return 'hello, XML!'
    return [12, 'foo', None, (2, 3)]
    return
    return {'key': 12, 'anotherkey': [1,2,3]}

2. Your function explicitly generates an XML-RPC Fault, by raising an xmlrpclib.Fault exception with appropriate error code and description.

In this case, your function didn't return any value, because it left its execution flow by raising an exception instead of returning. However, no return value is needed, because the generated Fault is being taken and passed to the client as XML-RPC Fault response. Your Fault code and description are not modified in any way.

After the response is sent into the stream, the whole call is considered "completed" and no further exception or processing is being performed, exactly the same state that would result from a normal function return.

XmlRpcServer itself only generates codes specified in the Specification for Fault Code Interoperability, but your code may generate any other code and description and it will be passed to the client untouched. In fact this is the preferred method, since the interoperability Fault codes are mostly specified for server errors. However, in some cases it may perfectly make sense to, for example, creating a Fault with code -32602 which means "invalid method parameters".

3. Your function or anything within it raises some other exception unrelated to xmlrpclib.Fault. xmlrpcserver doesn't want to mask out possibly fatal exceptions while at the same time it would like to automatically inform the client that the call resulted in an uncatched exception. However, xmlrpcserver has no means to differentiate between fatal or non-fatal exceptions. So, this is what happens:

XmlRpcServer catches the exception. It then immediately proceeds to send out an XML-RPC Fault with code -32500 (meaning 'application error'). After the response it sent, XmlRpcServer does NOT continue like it would with a normal call return or a catched XML-RPC Fault.

Instead, it reraises the exception to the originating caller of the XmlRpcServer.execute() method. The reraised exception is now free to be catched by your application where you may still choose to ignore it (for example, because it's a TypeError which very often just means that the client called a method with an incorrect number of arguments, thus not being your problem).

internal methods

Supported and reported capabilities are listed in the Overview of this document.

system.listMethods()

system.methodHelp(methodname)

Fault -32601 ('non-existing method') is raised in case that the supplied method name isn't registered.

further tweaking

self.systemerrors

self.capabilities

You may change it for adding new capabilities or removing any capabilities you feel the server shouldn't announce. (If you want to disable the whole system.getCapabilities() method, just unregister() it)

XmlRpcHTTPServer

Thanks to my friends who supported me during development by suggestions or testing.

Contact the author

http://www.julien-oster.de/projects/xmlrpcserver/dist

License

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

Changelog