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.
Use the includeme via pyramid.config.Configurator.include():
Once activated, the following happens:
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.
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 add_xmlrpc_endpoint() to handle traversal, which can assist in adding security to your RPC API.
Methods on your API are exposed by attaching views to an endpoint. Methods may be attached via the add_xmlrpc_method() which is a thin wrapper around Pyramid’s pyramid.config.Configurator.add_view() method.
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 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.
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.
Using Python’s xmlrpclib, it’s simple to instantiate a ServerProxy to call the function via an XML-RPC client.
1 2 3 4
>>> from xmlrpclib import ServerProxy >>> s = ServerProxy('http://localhost:6543/api/xmlrpc') >>> s.say_hello(name='Chris') Hello, Chris
Set up standard configurator registrations. Use via:
config = Configurator() config.include('pyramid_rpc.xmlrpc')
Once this function has been invoked, two new directives will be available on the configurator:
Add an endpoint for handling XML-RPC.
The name of the endpoint.
A default view mapper that will be passed as the mapper argument to each of the endpoint’s methods.
A XML-RPC method also accepts all of the arguments supplied to Pyramid’s add_route method.
Add a method to a XML-RPC endpoint.
The name of the endpoint.
The name of the method.
A XML-RPC method also accepts all of the arguments supplied to Pyramid’s add_view method.
A view mapper is registered by default which will match the request.rpc_args to parameters on the view. To override this behavior simply set the mapper argument to None or another view mapper.
An endpoint must be defined before methods may be added.
This decorator may be used with pyramid view callables to enable them to respond to XML-RPC method calls.
If method is not supplied, then the callable name will be used for the method name.
This is the lazy analog to the add_xmlrpc_method`() and accepts all of the same arguments.