Skip to content

Latest commit

 

History

History
169 lines (110 loc) · 4.71 KB

xmlrpc.rst

File metadata and controls

169 lines (110 loc) · 4.71 KB
Raw

XML-RPC

XML-RPC allows you to expose one or more methods at a particular URL. pyramid_rpc uses a view lookup pattern like that in pyramid allowing the XML-RPC methods to be located with the rest of your views, or in other packages.

Setup

Use the includeme via pyramid.config.Configurator.include:

config.include('pyramid_rpc.xmlrpc')

Once activated, the following happens:

  1. The pyramid_rpc.xmlrpc.add_xmlrpc_endpoint directive is added to the config instance.
  2. The pyramid_rpc.xmlrpc.add_xmlrpc_method directive is added to the config instance.
  3. An exception view is registered for xmlrpclib.Fault exceptions.

Usage

After including the pyramid_rpc.xmlrpc package in your project, you can add an endpoint for handling incoming requests. After that, attach several methods to the endpoint to handle specific functions within your api.

Adding a XML-RPC Endpoint

An endpoint is added via the ~pyramid_rpc.xmlrpc.add_xmlrpc_endpoint directive on the config instance.

Example:

config = Configurator()
config.include('pyramid_rpc.xmlrpc')
config.add_xmlrpc_endpoint('api', '/api/xmlrpc')

It is possible to add multiple endpoints as well as pass extra arguments to ~pyramid_rpc.xmlrpc.add_xmlrpc_endpoint to handle traversal, which can assist in adding security to your RPC API.

Exposing XML-RPC Methods

Methods on your API are exposed by attaching views to an endpoint. Methods may be attached via the ~pyramid_rpc.xmlrpc.add_xmlrpc_method which is a thin wrapper around Pyramid's pyramid.config.Configurator.add_view method.

Example:

def say_hello(request, name):
    return 'Hello, ' + name

config.add_xmlrpc_method(say_hello, endpoint='api', method='say_hello')

If you prefer, you can use the ~pyramid_rpc.xmlrpc.xmlrpc_method view decorator to declare your methods closer to your actual code. Remember when using this lazy configuration technique, it's always necessary to call pyramid.config.Configurator.scan from within your setup code.

from pyramid_rpc.xmlrpc import xmlrpc_method

@xmlrpc_method(endpoint='api')
def say_hello(request, name):
    return 'Hello, ' + name

config.scan()

To set the RPC method to something other than the name of the view, specify the method parameter:

from pyramid_rpc.xmlrpc import xmlrpc_method

@xmlrpc_method(method='say_hello', endpoint='api')
def say_hello_view(request, name):
    return 'Hello, ' + name

config.scan()

Because methods are a thin layer around Pyramid's views, it is possible to add extra view predicates to the method, as well as permission requirements.

Custom Renderers

By default, responses are rendered using the Python standard library's xmlrpclib.dumps. This can be changed the same way any renderer is changed in Pyramid. See the Pyramid Renderers chapter for extra details.

In addition, the built in renderer allows configuration by passing keyword arguments to it. As an example, let's update an endpoint to allow marshalling None objects.

from pyramid_rpc.xmlrpc import XMLRPCRenderer

config.add_renderer('myxmlrpc', XMLRPCRenderer(allow_none=True))
config.add_xmlrpc_endpoint('api', '/api', default_renderer='myxmlrpc')

View Mappers

A view mapper is registered for XML-RPC methods by default which will match the arguments from request.rpc_args to the parameters of the view. Optional arguments are allowed and an error will be returned if too many or too few arguments are supplied to the view.

This default view mapper may be overridden by setting the default_mapper option on ~pyramid_rpc.xmlrpc.add_xmlrpc_endpoint or the mapper option when using ~pyramid_rpc.xmlrpc.xmlrpc_method or ~pyramid_rpc.xmlrpc.add_xmlrpc_method.

Call Example

Using Python's xmlrpclib, it's simple to instantiate a ServerProxy to call the function via an XML-RPC client.

>>> from xmlrpclib import ServerProxy
>>> s = ServerProxy('http://localhost:6543/api/xmlrpc')
>>> s.say_hello(name='Chris')
Hello, Chris

API

pyramid_rpc.xmlrpc

includeme

add_xmlrpc_endpoint

add_xmlrpc_method

xmlrpc_method