Package: tgext.xmlrpc
== Welcome to the TurboGears XMLRPC Extension ==tgext.xmlrpc provides an easy method to allow XMLRPC calls to beperformed by your TurboGears application.== Installation ==1. Add it to your project. This is accomplished by modifying yoursetup.py. Add "tgext.xmlrpc" to your **install_requires** list.2. Run {{{python setup.py develop}}} in your project to get itinstalled.== Usage ==Usage is quite simple. Create a controller, decorate the XMLRPCmethods, and mount your controller somewhere. This can be done asfollows:{{{from tgext.xmlrpc import XmlRpcController, xmlrpcclass MyXmlRpcCenter(XmlRpcController):@xmlrpc([['int', 'int', 'int'], ['int', 'array']], helpstr="Adds numbers together")def addit(self, *p, **kw):return sum(p)}}}And then, in your controller, add the following line:{{{xmlrpc = MyXmlRpcCenter()}}}That's it, you now have a working XMLRPC interface on your system. Ifyou added it to your RootController, you may visithttp://localhost:8080/xmlrpc and get the help page. You may send anXMLRPC request to the method 'addit', and get the result.== The Details ===== xmlrpc Decorator  ===The xmlrpc decorator takes two parameters:* A list of lists of signatures* A help string that will be displayed on the index page, or whensystem.methodHelp is called for that methodNote that it matters that the signatures are a list of lists. Theelements of the list are nothing but strings identifying valid XMLRPCdata types. You can view a list of acceptable data types athttp://en.wikipedia.org/wiki/XML-RPCSo, examples of valid/invalid signatures:* {{{[['string', 'int']]}}} <-- valid, takes int, returns string* {{{['string', 'int']}}} <-- invalid, a list of two strings, not a list of lists=== xmlrpc methods ===You may write up your methods so that they function just like any otherTurboGears method. In fact, you can even be more strict, as a common idiom forTurboGears methods is to use something like this:{{{class MyXml(XmlRpcController):@xmlrpc([['string', 'string']])def mymethod(self, *p, **kw):pass}}}Notice the {{{*p, **kw}}} in the method signature. This is to prevent an uglyerror page being sent to users if they get the URL wrong. Since we are dealingwith programmatic interfaces, where the other end should be coded to expecterrors when data is not sent properly, we can make things much easier on thedeveloper:{{{class MyXml(XmlRpcController):@xmlrpc([['string', 'string']])def mymethod(self, instr, **kw):pass}}}=== XMLRPC Hierarchies ===You may set up a hierarchy of XmlRpcControllers. When you do, themethod names get separated by ".". This results in situations like thefollowing:{{{class SubXmlRpc(XmlRpcController):@xmlrpc([['string', 'array']])def joinit(self, *p, **kw):return " ".join(p)class MyXmlRpc(XmlRpcController):subproc = SubXmlRpc()@xmlrpc([['int', 'array']])def addit(self, *p, **kw):return sum(p)}}}When you mount MyXmlRpc somewhere, you will have the following twomethod names available to you:* addit* subproc.joinitWhen a call is made for "subproc.joinit", the XmlRpcController willdescend looking for the sub-controller, and then call the appropriatemethod there.=== To Do List ===* Add xmlrpcstruct decorator to allow xmlrpcsruct docs to be shown onsystem.methodHelp pages.