Documentation for pyramid_xmlrpc

XML-RPC support for the pyramid web framework.

pyramid_xmlrpc Installation

pyramid_xmlrpc is a package that ships outside the main pyramid distribution. To install the package, use easy_install:

easy_install pyramid_xmlrpc

Or obtain the packge via http://github.com/Pylons/pyramid_xmlrpc and use setup.py install.

pyramid_xmlrpc Usage

XML-RPC allows you to expose one or more methods at a particular URL. pyramid_xmlrpc has a simple usage pattern for exposing a single method at a particular url, and a more complicated one for when you want to expose multiple methods at a particular URL.

Exposing a single method

Create a function in the form below. The function will be meant to be called with positional parameters from an XML-RPC request.

1
2
def say_hello(context, name):
    return 'Hello, %s' % name

Then add the xmlrpc_view() decorator to the function.

1
2
3
4
5
from pyramid_xmlrpc import xmlrpc_view

@xmlrpc_view
def say_hello(context, name):
    return 'Hello, %s' % name

Then configure your application registry to point to the say_hello view.

Using imperative code in your application’s startup configuration:

1
2
from mypackage import say_hello
config.add_view(say_hello, name='say_hello')

Using ZCML:

1
2
3
4
5
<view
  name="say_hello"
  view=".views.say_hello"
  for="*"
  />

Or using a view_config decorator:

1
2
3
4
5
6
7
from pyramid_xmlrpc import xmlrpc_view
from pyramid.view import view_config

@view_config(name='say_hello')
@xmlrpc_view
def say_hello(context, name):
    return 'Hello, %s' % name

Then call the function via an XML-RPC client. Note that any XML-RPC methodName will be ignored; you must point the client directly at the view URL; traversal doesn’t work from there.

1
2
3
4
>>> from xmlrpclib import ServerProxy
>>> s = ServerProxy('http://localhost:6543/say_hello')
>>> s('Chris')
Hello, Chris

Exposing multiple methods

If you have multiple methods to expose at a particular url, you should group them together in a class. Think of this class in the same way as you would when you implement a normal pyramid view as a class rather than a function.

The methods of the class will be those exposed as methods to XML-RPC. Not that XML-RPC only supports positional parameters.

To make this view class handle incoming XML-RPC requests, you simply need to subclass the XMLRPCView class. XMLRPCView provides a __call__() method, so make sure that your class doesn’t provide one!

For example:

1
2
3
4
5
6
7
8
9
from pyramid_xmlrpc import XMLRPCView

class MyXMLRPCStuff(XMLRPCView):

   def say_hello(self, name):
       return 'Hello, %s' % name

   def say_goobye(self):
       return 'Goodbye, cruel world'

This class can then be registered with pyramid as a normal view.

Using imperative code in your application’s startup configuration:

1
2
from mypackage import MyXMLRPCStuff
config.add_view(MyXMLRPCStuff, name='RPC2')

Via ZCML:

1
2
3
4
5
<view
  name="RPC2"
  view=".views.MyXMLRPCStuff"
  for="*"
  />

The methods exposed by this view can now be used by any XML-RPC client:

1
2
3
4
5
6
>>> from xmlrpclib import ServerProxy
>>> s = ServerProxy('http://localhost:6543/RPC2')
>>> s.say_hello('Chris')
Hello, Chris
>>> s.say_goodbye()
Goodbye, cruel world

API Documentation for pyramid_xmlrpc

pyramid_xmlrpc.xmlrpc_view(wrapped)

This decorator turns functions which accept params and return Python structures into functions suitable for use as Pyramid views that speak XML-RPC. The decorated function must accept a context argument and zero or more positional arguments (conventionally named *params).

E.g.:

from pyramid_xmlrpc import xmlrpc_view

@xmlrpc_view
def say(context, what):
    if what == 'hello'
        return {'say':'Hello!'}
    else:
        return {'say':'Goodbye!'}

Equates to:

from pyramid_xmlrpc import parse_xmlrpc_request
from pyramid_xmlrpc import xmlrpc_response

def say_view(context, request):
    params, method = parse_xmlrpc_request(request)
    return say(context, *params)

def say(context, what):
    if what == 'hello'
        return {'say':'Hello!'}
    else:
        return {'say':'Goodbye!'}

Note that if you use view_config, you must decorate your view function in the following order for it to be recognized by the convention machinery as a view:

from pyramid.view import view_config
from pyramid_xmlrpc import xmlrpc_view

@view_config(name='say')
@xmlrpc_view
def say(context, what):
    if what == 'hello'
        return {'say':'Hello!'}
    else:
        return {'say':'Goodbye!'}

In other words do not decorate it in xmlrpc_view(), then view_config; it won’t work.

class pyramid_xmlrpc.XMLRPCView(context, request)

A base class for a view that serves multiple methods by XML-RPC.

Subclass and add your methods as described in the documentation.

__call__()

This method de-serializes the XML-RPC request and dispatches the resulting method call to the correct method on the XMLRPCView subclass instance.

Warning

Do not override this method in any subclass if you want XML-RPC to continute to work!

pyramid_xmlrpc.xmlrpc_marshal(data)

Marshal a Python data structure into an XML document suitable for use as an XML-RPC response and return the document. If data is an xmlrpclib.Fault instance, it will be marshalled into a suitable XML-RPC fault response.

pyramid_xmlrpc.xmlrpc_response(data)

Marshal a Python data structure into a webob Response object with a body that is an XML document suitable for use as an XML-RPC response with a content-type of text/xml and return the response.

pyramid_xmlrpc.parse_xmlrpc_request(request)

Deserialize the body of a request from an XML-RPC request document into a set of params and return a two-tuple. The first element in the tuple is the method params as a sequence, the second element in the tuple is the method name.

Indices and tables