XML-RPC Service Introspection / Discovery

[Ross Peoples]

One of the nice things about SOAP is the WDSL that gives you information about the methods the service supports. I recently discovered that you can do the same thing with XML-RPC. The trick is to document your methods properly, like you should be doing anyways. Lets say I have the following controller:

@service.xmlrpc

@service.jsonrpc

def add(num1, num2):

    """

    Adds two numbers together.

    

    add(num1, num2) -> number

    

    Arguments:

    num1        First number

    num2        Second number

    

    Returns:

    The sum of the two numbers.

    

    Examples:

    add(2, 2) -> 4

    add(2.5, 2.5) -> 5.0

    """

    return num1 + num2

@service.xmlrpc

@service.jsonrpc

def concat(str1, str2, str3=''):

    """

    Concatenates two or three strings.

    

    concat(str1, str2, str3='') -> string

    

    Arguments:

    str1        First string

    str2        Second string

    str3        (Optional) Third string

    

    Returns:

    The concatenated string.

    

    Examples:

    concat('hello', ' world') -> 'hello world'

    concat('hello', ' world', ' !!!') -> 'hello world !!!

    """

    return str1 + str2 + str3

@service.xmlrpc

@service.jsonrpc

def date():

    """

    Returns the server's current date and time.

    """

    return datetime.datetime.now()

Now let's connect using xmlrpclib:

>>> import xmlrpclib

>>> x = xmlrpclib.ServerProxy('http://127.0.0.1:8000/rpc_test/default/call/xmlrpc')

Now, we could start calling the methods as usual, or we could do a little introspection to see what methods are available, and even get the docstrings of those methods:

>>> print x.system.listMethods()

['add', 'concat', 'date', 'system.listMethods', 'system.methodHelp', 'system.methodSignature']

>>> print x.system.methodHelp('concat')

Concatenates two or three strings.

concat(str1, str2, str3='') -> string

Arguments:

str1        First string

str2        Second string

str3        (Optional) Third string

Returns:

The concatenated string.

Examples:

concat('hello', ' world') -> 'hello world'

concat('hello', ' world', ' !!!') -> 'hello world !!!'

>>> x.concat('hello', 'web2py')

'helloweb2py'

Very cool! However, you will notice that there is another method in there: system.methodSignature(). This would show the signature of the method (i.e. concat(str1, str2, str3=''), however, it seems that web2py's XMLRPC server implementation (or SimpleXMLRPCServer.py) doesn't support this, as it returns 'signatures not supported' whenever you try to call this method.

I hope that someone finds this useful!

[Massimo Di Pierro]

Cool! This should go in the manual.

[Michele Comitini]

+1 Cool!

But we need to take the bad note too...

>> However, you will notice that there is another method in there:
>> system.methodSignature(). This would show the signature of the method (i.e.
>> concat(str1, str2, str3=''), however, it seems that web2py's XMLRPC server
>> implementation (or SimpleXMLRPCServer.py) doesn't support this, as it
>> returns 'signatures not supported' whenever you try to call this method.
>>

This has to be fixed?!

mic