[[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/1.0/++ (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`, but most XML-RPC clients should use the authenticated URL suffix `/login/rpc` as this with 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. 
 * [http://www.jspwiki.org/Wiki.jsp?page=WikiRPCInterface2 WikiRPC API] is complete, mostly thanks to [wiki:mgood]. 

Protocol and method documentation for the latest version of the plugin can be found [/rpc here].
 
== 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 (if you do install by this method, 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.):
{{{#!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/1.0/++
$ #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.~~

The recommended approach to make it work is to add the following configuration in TracIni

{{{#!ini

[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 [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].

For enhanced compatibility with [wiki:bloodhound Apache™ Bloodhound]>=0.6 download ''BloodhoundRPC'' fork from [https://bitbucket.org/olemis/bloodhound-rpc this repository] and check out `bloodhound_rpc` branch.

== 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 '<realm'". 

{{{
#!python
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):
        import urllib2

        url='https://'+host+handler
        if verbose or self.verbose:
            print "ProxyTransport URL: [%s]"%url

        request = urllib2.Request(url)
        request.add_data(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 [/raw-attachment/wiki/XmlRpcPlugin/trac_xml_rpc_example_java.zip this example zip file] 

==== Related issues #rpc-java-issues

[[TicketQuery(component=XmlRpcPlugin, keywords=~java)]]

=== Using from Ruby ===

See XmlRpcPlugin/Ruby.

=== API Usage ===
 	 
See the [source:xmlrpcplugin/0.10/tracrpc/api.py source] for details. 
	 	 
== Screenshot == 
 	 
Accessing the RPC handler through a browser (at `/rpc` or `/login/rpc`) will provide the documentation of protocols and available methods. 
 	 
    [[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]]