Trac XML-RPC Plugin

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, but most XML-RPC clients should use the authenticated URL suffix /login/rpc as this will provide authenticated requests through 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.
• The ​WikiRPC API is complete, mostly thanks to mgood.

Protocol and method documentation for the latest version of the plugin can be found here.

Accessing the RPC handler through a browser (at /rpc or /login/rpc) will provide the documentation of protocols and available methods:

Todo

Outstanding tasks are roadmap, timeline, user management, for example get a (filtered) user list to assign a task in ​mylyn, plugin management.

Bugs/Feature Requests

Existing bugs and feature requests for XmlRpcPlugin are here.

If you have any issues, create a new ticket.

defect	154 / 164
enhancement	31 / 46
task	8 / 8

Download

Download the zipped source from here.

The plugin is also available on ​PyPI.

Source

Check out XmlRpcPlugin using Subversion from here or browse the source​ with Trac.

Work in progress is developed using ​Mercurial Queues.

Simple Installation

Perform the following commands in your Trac project's directory:

pip install svn+https://trac-hacks.org/svn/xmlrpcplugin/trunk
trac-admin . config set components tracrpc.* enabled
trac-admin . permission add authenticated XML_RPC 

Note that sudo may be necessary, so if easy_install fails, try sudo pip install instead of pip install.

RPC should work for all authenticated users.

Advanced Installation Notes

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:

python setup.py bdist_egg 
cp dist/*.egg /srv/trac/env/plugins 

Make sure the egg-file in dist/-folder does not contain any letters before you copy. Else, if for example the egg file is TracXMLRPC-1.1.2.post0-py2.7.egg, you will have an error that post0 is not an int, when you connect via XML-RPC from Eclipse, just rename the egg-file to TracXMLRPC-1.1.2-py2.7.egg and you will be fine.

If you want it to be installed for all Trac environments, then depending on the version of Trac you are running:

pip install svn+https://trac-hacks.org/svn/xmlrpcplugin/trunk  # 0.12+
pip install svn+https://trac-hacks.org/svn/xmlrpcplugin/0.11  # 0.11
pip install svn+https://trac-hacks.org/svn/xmlrpcplugin/0.10  # 0.10
pip install /path/to/unpacked/download/version 

The same command can be run later to refresh the installation.

You will also need to enable the plugin in your trac.ini file:

[components] 
tracrpc.* = enabled 

Troubleshooting

Problems when AccountManagerPlugin is enabled

If you have the AccountManagerPlugin enabled and you followed their advice/example to disable the standard login module as follows:

[components] 
trac.web.auth.LoginModule = disabled 

then the /login/xmlrpc URL for authorized access will not work as expected. Every access will look like anonymous access. The recommended approach to make it work is to add the following configuration in TracIni:

[account-manager]
environ_auth_overwrite = false

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 ​TracInstall. Use Python 2.5 if you want to run Trac with mod_python.

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:

try:
    from xmlrpc import client as xmlrpclib
except ImportError:
    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.

try:
    from xmlrpc import client as xmlrpclib
except ImportError:
    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:

try:
    from xmlrpc import client as xmlrpclib
except ImportError:
    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 ​WikiRPC:

try:
    from xmlrpc import client as xmlrpclib
except ImportError:
    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:

try:
    from xmlrpc import client as xmlrpclib
except ImportError:
    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 are connecting to. This shows up in the login box "server says '<realm'":

try:
    from xmlrpc import client as xmlrpclib
except ImportError:
    import xmlrpclib 
    import urllib2
else:
    from urllib import request as urllib2

class HTTPSDigestTransport(xmlrpclib.SafeTransport):
    """
    Transport that uses urllib2 so that we can do Digest authentication.
    
    Based upon code at http://bytes.com/topic/python/answers/509382-solution-xml-rpc-over-proxy
    """

    def __init__(self, username, pw, realm, verbose = None, use_datetime=0):
        self.__username = username
        self.__pw = pw
        self.__realm = realm
        self.verbose = verbose
        self._use_datetime = use_datetime

    def request(self, host, handler, request_body, verbose):
        url = 'https://'+host+handler
        if verbose or self.verbose:
            print "ProxyTransport URL: [%s]"%url

        request = urllib2.Request(url, request_body)
        # Note: 'Host' and 'Content-Length' are added automatically
        request.add_header("User-Agent", self.user_agent)
        request.add_header("Content-Type", "text/xml") # Important

        # setup digest authentication
        authhandler = urllib2.HTTPDigestAuthHandler()
        authhandler.add_password(self.__realm, url, self.__username, self.__pw)
        opener = urllib2.build_opener(authhandler)

        # proxy_handler = urllib2.ProxyHandler()
        # opener = urllib2.build_opener(proxy_handler)
        f = opener.open(request)
        return(self.parse_response(f))

digestTransport = HTTPSDigestTransport("username", "password", "realm")
server = xmlrpclib.ServerProxy("https://host/login/xmlrpc", transport=digestTransport)

Using from C#

See XmlRpcPlugin/DotNet.

Using from Java

See this example zip file.

Related issues

#5370

Examples of using Java

#11108

Problem with the api's library(int id, int when=0)

Using from Ruby

See XmlRpcPlugin/Ruby.

API Usage

See the source​ for details.

Recent Changes

18657 by jun66j5 on 2024-09-07 09:39:09

XmlRpcPlugin: ignore them rather than raising an error when non existing fields used on inserting and updating a ticket

18643 by jun66j5 on 2024-06-07 15:38:52

XmlRpcPlugin: add __str__ method to _CompositeRpcError for Python 3

18639 by jun66j5 on 2024-05-16 06:29:19

XmlRpcPlugin: make compile_catalog command invoked before build command

(more)

Author/Contributors

Authors and contributors: athomas, mgood, osimons, Olemis Lang
Maintainer: osimons