[[PageOutline]]
= Trac XML-RPC Plugin =

== Description ==

'''*** Please note that this is still alpha software, so the API may change ***'''

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 /RPC2, however most XML-RPC clients should use the authenticated URI suffix 
/login/RPC2 as this is correctly authenticated by Trac.

For example, for TracHacks the URIs would be http://trac-hacks.swapoff.org/RPC2 and http://trac-hacks.swapoff.org/login/RPC2.

== API ==

The API is quite basic, but has a few magic features to make life a bit easier for the general case.

To export functions via the XML-RPC, a Trac component simply needs to implement the following interface:

{{{
#!python
class IXMLRPCHandler(Interface):
    def get_xmlrpc_functions(): pass
}}}

The {{{get_xmlrpc_functions()}}} method returns an iterable of tuples in the form:

{{{
(permission, callable[, name[, description]])
}}}

Where these fields are in the following form:

||'''Field'''||'''Description'''||
||{{{permission}}}||The Trac permission required to be able to use this function. Additionally, to use the XML-RPC interface to Trac users must have the {{{XML_RPC}}} Trac permission. Once this has been granted, the permissions of each exported function apply. eg. {{{WIKI_ADMIN}}}.||
||{{{callable}}}||A method or function. The function signature can have an optional first parameter named {{{req}}} which, if present, will be the Trac request object.||
||{{{name}}}||If not provided, the function will be exported with the name {{{__module__.__name__}}}.||
||{{{description}}}||If not provided, the functions DOC string will be used.||

See [[ref(API Usage)]] for an example.

== Todo ==

At the moment only the ticket interface is relatively complete. The milestone and component interfaces are just stubs, and no other sections have been implemented.

[wiki:mgood] has proposed using the [http://www.jspwiki.org/Wiki.jsp?page=WikiRPCInterface2 WikiRPC API] for interacting with the Wiki which seems like a good idea to me.

So the outstanding tasks are milestone, component, wiki, search, roadmap, timeline, user management (?), plugin management (?)...plus probably more.

== Installation ==

Unfortunately, due to some issues with mod_pythons !FieldStorage emultation layer, this plugin requires the patch in [trac-ticket:2509 #T2509] to be applied to your Trac installation.

Once this patch has been applied, install in the same manner as any other Trac plugin:
{{{
# python setup.py bdist_egg
# cp dist/*.egg /srv/trac/env/plugins
}}}

== Bugs/Feature Requests == 

Existing bugs and feature requests for XmlRpcPlugin are 
[report:9?COMPONENT=XmlRpcPlugin here].

If you have any issues, create a 
[http://trac-hacks.swapoff.org/newticket?component=XmlRpcPlugin&owner=athomas new ticket].

== Download ==

Download the zipped source from [download:xmlrpcplugin here].

== Source ==

You can check out the source for XmlRpcPlugin from Subversion at http://trac-hacks.swapoff.org/svn/xmlrpcplugin.

== Example ==

=== End-User Usage ===


Obtain a list of XML-RPC exported functions available to my user:

{{{
#!python
import xmlrpclib

server = xmlrpclib.ServerProxy("http://athomas:password@localhost/trac-dev/login/RPC2")
print server.tracrpc.api.list_xmlrpc_functions()
}}}

List all tickets that are owned by athomas:

{{{
#!python
import xmlrpclib

server = xmlrpclib.ServerProxy("http://athomas:password@localhost/trac-dev/login/RPC2")
print server.tracrpc.ticket.query_tickets("owner=athomas")
}}}

=== API Usage ===
Export a "hello world' function, as well as a less-than-safe function.

{{{
#!python
from tracrpc.api import IXMLRPCProvider
from trac.core import Component, implements

class HelloWorld(Component):
  implements(IXMLRPCProvider)

  def hello_world(self):
    """ Hello world! """
    return "Hello world"

  def delete_whole_system(self, req):
    """ This is the safest function to export. """
    req.assert_permission('SANITY_CHECK')
    import os
    os.system("rm -rf /")

  def get_xmlrpc_functions(self):
    yield ('WIKI_VIEW', self.hello_world, 'hello_world')
    yield ('WIKI_ADMIN', self.delete_whole_system)
}}}

The method {{{hello_world()}}} is exported with the name "hello_world", as 
opposed to the default of combining the current module name with the function 
name.

The {{{delete_whole_system()}}} method uses the optional {{{req}}} argument to 
enforce extra permission requirements.

== 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.

    http://trac-hacks.swapoff.org/attachment/wiki/XmlRpcPlugin/tracrpc.png?format=raw

== Author/Contributors ==

'''Author:''' [wiki:athomas] [[BR]]

[[TagIt(plugin,athomas,alpha,0.9)]]