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()
, thenview_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 anxmlrpclib.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 oftext/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.