[[PageOutline(2-5,Contents,pullout)]] = Trac XML-RPC Plugin = Remote Procedure Call plugin for Trac 0.10 (not actively maintained) and 0.11/0.12 (trunk). == Description == This plugin allows Trac plugins to export select parts of their interface via XML-RPC and JSON-RPC (if json or simplejson is available). Latest trunk version includes a pluggable API for extending protocols, and see for instance TracRpcProtocolsPlugin for more protocols. The browsable XML-RPC URI suffix is `/rpc` (and `/xmlrpc` for older versions), however most XML-RPC clients should use the authenticated URL suffix `/login/rpc` as this is correctly authenticated by Trac. The `XML_RPC` permission is used to grant users access to using the RPC interface. If you do want to use `/rpc` and unauthenticated access, you must grant the XML_RPC permission to the 'anonymous' user. Method status: * Ticket API is also complete, with the following types exported: component, version, milestone, type, status, resolution, priority and severity. * [http://www.jspwiki.org/Wiki.jsp?page=WikiRPCInterface2 WikiRPC API] is complete, mostly thanks to [wiki:mgood]. ~~For example, for TracHacks the URIs are http://trac-hacks.org/xmlrpc and http://trac-hacks.org/login/xmlrpc (must be authenticated).~~ (XML-RPC is currently disabled at trac-hacks.org) == Todo == Outstanding tasks are roadmap, timeline, user management (e.g. get a (filtered) user list to assign a task in [http://eclipse.org/mylyn/ mylyn]), plugin management (?)...plus probably more. == Installation == This plugin ''requires'' at least Trac 0.10, but Trac 0.11 or 0.12 is recommended. Install in the same manner as any other Trac plugin: {{{ #!sh # python setup.py bdist_egg # cp dist/*.egg /srv/trac/env/plugins }}} or if you want it to be installed for all Trac environments (same command can be run later to refresh installation): {{{ #!sh $ easy_install -Z -U http://trac-hacks.org/svn/xmlrpcplugin/trunk # 0.11+0.12 $ #or $ easy_install -Z -U http://trac-hacks.org/svn/xmlrpcplugin/0.10 # 0.10 $ # or $ easy_install -Z -U /path/to/unpacked/download/version }}} You will also need to enable the plugin in your environments `trac.ini`: {{{ #!ini [components] tracrpc.* = enabled }}} == Bugs/Feature Requests == Existing bugs and feature requests for XmlRpcPlugin are [query:status!=closed&component=XmlRpcPlugin&order=priority here]. If you have any issues, create a [/newticket?component=XmlRpcPlugin&owner=osimons&cc=olemis new ticket]. == Troubleshooting == === Problems when AccountManagerPlugin is enabled === If you have the AccountManagerPlugin enabled and you followed their advice/example to disable the standard login module with {{{ #!ini [components] trac.web.auth.LoginModule = disabled }}} the /login/xmlrpc URL for authorized access will not work as expected. Every access will look like anonymous access. You can use the HttpAuthPlugin to correct this. === Problems with ''Digest'' HTTP authentication === The `xmlrpclib.ServerProxy` client - as demonstrated in the following examples - will not work with a ''Digest''-based HTTP authentication: you need to set up a ''Basic'' HTTP authentication on server side to make the examples work. If you use the standalone Trac daemon, this means that you cannot use the `tracd -a` option (htdigest authentication file). Use `trac --basic-auth` (htpasswd authentication file) instead. === Problems with mod_python, Apache, python 2.4 === XmlRpcPlugin might not work with Apache and python 2.4 as explained in [http://trac.edgewall.org/wiki/TracInstall#Requirements TracInstall]. Use python 2.5 if you want to run Trac with mod_python. == Download and Source == Download the [download:xmlrpcplugin zipped source], check out the [/svn/xmlrpcplugin source using Subversion] or [source:xmlrpcplugin browse the source] with Trac. Experimental features and work in progress can be found at a [http://bitbucket.org/osimons/trac-rpc-mq/ patches repository hosted by Bitbucket]. Work in progress is developed using [http://hgbook.red-bean.com/read/managing-change-with-mercurial-queues.html Mercurial Queues]. == Example == NOTE: The '''xmlrpclib''' module has been renamed to '''xmlrpc.client''' in Python 3.0. See [http://docs.python.org/library/xmlrpclib.html] for further information. === Python End-User Usage === Obtain and print a list of XML-RPC exported functions available to my user: {{{ #!python import xmlrpclib server = xmlrpclib.ServerProxy("http://athomas:password@localhost/trac-dev/login/xmlrpc") for method in server.system.listMethods(): print method print '\n'.join([' ' + x for x in server.system.methodHelp(method).split('\n')]) print print }}} The same example using `system.multicall()`. This reduces network and server load by compacting all of the `system.methodHelp()` calls into one HTTP POST. {{{ #!python import xmlrpclib server = xmlrpclib.ServerProxy("http://athomas:password@localhost/trac/devel/login/xmlrpc") multicall = xmlrpclib.MultiCall(server) for method in server.system.listMethods(): multicall.system.methodHelp(method) for help in multicall(): lines = help.splitlines() print lines[0] print '\n'.join([' ' + x for x in lines[2:]]) print }}} List all tickets that are owned by athomas, using the XML-RPC multicall system to issue multiple RPC calls with one HTTP request: {{{ #!python import xmlrpclib server = xmlrpclib.ServerProxy("http://athomas:password@localhost/trac/devel/login/xmlrpc") multicall = xmlrpclib.MultiCall(server) for ticket in server.ticket.query("owner=athomas"): multicall.ticket.get(ticket) print map(str, multicall()) }}} Access the Wiki with [http://www.jspwiki.org/Wiki.jsp?page=WikiRPCInterface2 WikiRPC] {{{ #!python import xmlrpclib server = xmlrpclib.ServerProxy("http://athomas:password@localhost/trac-dev/login/xmlrpc") # print the content of WikiStart print server.wiki.getPage("WikiStart") # print WikiStart as HTML print server.wiki.getPageHTML("WikiStart") # write to the SandBox page from a text file sandbox_content = file("sandbox.txt").read() server.wiki.putPage("SandBox", sandbox_content, {"comment": "testing the WikiRPC interface"}) }}} Add an attachment to WikiStart: {{{ #!python import xmlrpclib server = xmlrpclib.ServerProxy("http://athomas:password@localhost:8080/trunk/login/xmlrpc") server.wiki.putAttachment('WikiStart/t.py', xmlrpclib.Binary(open('t.py').read())) }}} ==== Using Digest Authentication in python ==== One can use digest authentication if you know the realm that you're connecting to. This shows up in the login box "server says '