[[PageOutline(2-5,Contents,pullout)]] = Trac XML-RPC Plugin = Remote Procedure Call plugin for Trac 0.10 (not actively maintained) and 0.11. == Description == This plugin allows Trac plugins to export select parts of their interface via XML-RPC. It also includes some exported functions for manipulating tickets, with plans to include interfaces to other parts of Trac's API. The browsable XML-RPC URI suffix is /xmlrpc, however most XML-RPC clients should use the authenticated URL suffix /login/xmlrpc as this is correctly authenticated by Trac. '''Note''': if you do want to use /xmlrpc and unauthenticated access, you must grant the XML_RPC permission to the 'anonymous' user. [http://www.jspwiki.org/Wiki.jsp?page=WikiRPCInterface2 WikiRPC API] is complete, mostly thanks to [wiki:mgood]. Ticket API is also complete, with the following types exported: component, version, milestone, type, status, resolution, priority and severity. For example, for TracHacks the URIs are http://trac-hacks.org/xmlrpc and http://trac-hacks.org/login/xmlrpc (must be authenticated). == 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 is recommended. Install in the same manner as any other Trac plugin: {{{ # 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): {{{ $ easy_install -Z -U http://trac-hacks.org/svn/xmlrpcplugin/trunk # 0.11 $ #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`: {{{ [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 {{{ [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 can be found at a [http://bitbucket.org/osimons/trac-rpc/ repository hosted by Bitbucket]. Work in progress is developed using [http://hgbook.red-bean.com/read/managing-change-with-mercurial-queues.html Mercurial Queues] and is publicly available at the [http://bitbucket.org/osimons/trac-rpc-mq/changeset/852ab5767c42/ patches repository]. == Example == === 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 ' true # this is the default anyway # get all the tickets # NOTE: the results here are cached, so you can call it as often as you want without producing traffic more than once. # use ":cached_results => false" to get the latest version trac.tickets.get_all :include_closed => true # get a single ticket ticket = trac.tickets.get 5 # print the data puts "Title: #{ticket.summary}" puts "Description: #{ticket.description}" puts "Milestone: #{ticket.milestone}" puts "Status: #{ticket.status}" puts "Type: #{ticket.type}" puts "Priority: #{ticket.priority}" # get a list of all wiki pages trac.wiki.list # download one page trac.wiki.get_html "SomeRandomPageName" # HTML version trac.wiki.get_raw "AnotherRandomPageName" # trac syntax version (e.g. for editing) # for previews use trac.wiki.raw_to_html "content of a page in [wiki:WikiFormatting Trac syntax] as a ''String''" # to post a page use trac.wiki.put "NameOfThePage", "content in Trac syntax" # list the attachments of a wiki page trac.wiki.attachments "NameOfThePage" # save an attachment File.new("my_cool_document","w") do |f| f.write trac.wiki.get_attachment "NameOfThePage", "my_cool_document.pdf" end }}} Also see the included Documentation in trac4r/doc If you need to do a custom query do {{{ #!ruby trac.query("system.getAPIVersion") }}} The first argument is the method name, all other arguments are directly passed to XMLRPC. For this example of cause you could do `trac.api_version` instead ;) If you have any problems with trac4r you can email me: niklas.cathor (eat) gmail dot com ==== xmlrpc Example ==== An example using XML-RPC directly with Ruby to append to a wiki page: {{{ #!ruby require 'xmlrpc/client' user = "username" password = "password" page_name = "SandBoxRPC" new_content = "\n\nMy new content" new_comment = "Adding new content from ruby" server = XMLRPC::Client.new2("https://#{user}:#{password}@trac.server.com/trac/login/xmlrpc") content = server.call("wiki.getPage", page_name) + new_content server.call("wiki.putPage", page_name, content, {"comment" => new_comment}) }}} === API Usage === See the [source:xmlrpcplugin/0.10/tracrpc/api.py source] for details. == Screenshot == If the HTTP request to this URI is not XML, the XmlRpcPlugin will list all exported functions that the current user has permission to use. [[Image(tracrpc.png)]] == Change Log == [[ChangeLog(/xmlrpcplugin, 5)]] == Author/Contributors == '''Authors and contributors:''' [wiki:athomas], [wiki:mgood], [wiki:osimons], [wiki:olemis Olemis Lang] [[BR]] '''Maintainer:''' [wiki:osimons] [[BR]]