Version 14 (modified by 18 years ago) (diff) | ,
---|
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:
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.
mgood has proposed using the 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 here.
If you have any issues, create a 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:
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:
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.
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: athomas
Attachments (2)
- tracrpc.png (94.4 KB) - added by 18 years ago.
-
trac_xml_rpc_example_java.zip (92.8 KB) - added by 16 years ago.
java interfaces and proxy class implementation (alpha example)
Download all attachments as: .zip