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:
- The
pyramid_rpc.xmlrpc.add_xmlrpc_endpoint()
directive is added to theconfig
instance. - The
pyramid_rpc.xmlrpc.add_xmlrpc_method()
directive is added to theconfig
instance. - 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
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
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
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 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 add_xmlrpc_endpoint()
or the mapper
option when using xmlrpc_method()
or 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.
1 2 3 4 | >>> from xmlrpclib import ServerProxy
>>> s = ServerProxy('http://localhost:6543/api/xmlrpc')
>>> s.say_hello(name='Chris')
Hello, Chris
|
API¶
-
includeme
(config)[source]¶ 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_xmlrpc_endpoint
: Add an endpoint for handling XML-RPC.add_xmlrpc_method
: Add a method to a XML-RPC endpoint.
-
add_xmlrpc_endpoint
(config, name, *args, **kw)[source]¶ Add an endpoint for handling XML-RPC.
name
The name of the endpoint.default_mapper
A default view mapper that will be passed as themapper
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_xmlrpc_method
(config, view, **kw)[source]¶ Add a method to a XML-RPC endpoint.
endpoint
The name of the endpoint.method
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 themapper
argument to None or another view mapper.Note
An endpoint must be defined before methods may be added.
-
xmlrpc_method
(method=None, **kw)[source]¶ 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._depth
may be specified when wrappingxmlrpc_method
in another decorator. The value should reflect how many stack frames are between the wrapped target andxmlrpc_method
. Thus a decorator one level deep would pass in_depth=1
.This is the lazy analog to the
add_xmlrpc_method`()
and accepts all of the same arguments.