Changes between Version 14 and Version 15 of XmlRpcPlugin


Ignore:
Timestamp:
Dec 27, 2005, 11:19:34 AM (18 years ago)
Author:
Alec Thomas
Comment:

Updated

Legend:

Unmodified
Added
Removed
Modified

  • XmlRpcPlugin

    v14 v15  
    1717== API ==
    1818
    19 The API is quite basic, but has a few magic features to make life a bit easier for the general case.
    20 
    21 To export functions via the XML-RPC, a Trac component simply needs to implement the following interface:
    22 
    23 {{{
    24 #!python
    25 class IXMLRPCHandler(Interface):
    26     def get_xmlrpc_functions(): pass
    27 }}}
    28 
    29 The {{{get_xmlrpc_functions()}}} method returns an iterable of tuples in the form:
    30 
    31 {{{
    32 (permission, callable[, name[, description]])
    33 }}}
    34 
    35 Where these fields are in the following form:
    36 
    37 ||'''Field'''||'''Description'''||
    38 ||{{{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}}}.||
    39 ||{{{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.||
    40 ||{{{name}}}||If not provided, the function will be exported with the name {{{__module__.__name__}}}.||
    41 ||{{{description}}}||If not provided, the functions DOC string will be used.||
    42 
    43 See [[ref(API Usage)]] for an example.
     19See the [source:xmlrpcplugin/0.9/tracrpc/api.py source] for API usage.
    4420
    4521== Todo ==
    4622
    47 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.
     23[http://www.jspwiki.org/Wiki.jsp?page=WikiRPCInterface2 WikiRPC API] is complete, mostly thanks to [wiki:mgood].
    4824
    49 [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.
     25Ticket API is also complete, with the following types exported: component, version, milestone, type, status, resolution, priority and severity.
    5026
    51 So the outstanding tasks are milestone, component, wiki, search, roadmap, timeline, user management (?), plugin management (?)...plus probably more.
     27So the outstanding tasks are search, roadmap, timeline, user management (?), plugin management (?)...plus probably more.
    5228
    5329== Installation ==
    … …  
    5935# python setup.py bdist_egg
    6036# cp dist/*.egg /srv/trac/env/plugins
     37}}}
     38
     39You will also probably need to enable the plugin in your environments trac.ini:
     40
     41{{{
     42[components]
     43tracrpc.* = enabled
    6144}}}
    6245
    … …  
    8265
    8366
    84 Obtain a list of XML-RPC exported functions available to my user:
     67Obtain and print a list of XML-RPC exported functions available to my user:
    8568
    8669{{{
    … …  
    8972
    9073server = xmlrpclib.ServerProxy("http://athomas:password@localhost/trac-dev/login/RPC2")
    91 print server.tracrpc.api.list_xmlrpc_functions()
     74for method in server.system.listMethods():
     75  print method
     76  print '\n'.join(['  ' + x for x in server.system.methodHelp(method).split('\n')])
     77  print
     78  print
    9279}}}
    9380
    94 List all tickets that are owned by athomas:
     81List all tickets that are owned by athomas, using the XML-RPC multicall system
     82to issue multiple RPC calls with one HTTP request:
    9583
    9684{{{
    … …  
    9987
    10088server = xmlrpclib.ServerProxy("http://athomas:password@localhost/trac-dev/login/RPC2")
    101 print server.tracrpc.ticket.query_tickets("owner=athomas")
     89tickets = server.ticket.query("owner=athomas")
     90print '\n'.join(map(str, server.system.multicall([{'methodName' : 'ticket.get', 'params' : [ticket]} for ticket in tickets])))
    10291}}}
    10392
    10493=== API Usage ===
    105 Export a "hello world' function, as well as a less-than-safe function.
    10694
    107 {{{
    108 #!python
    109 from tracrpc.api import IXMLRPCProvider
    110 from trac.core import Component, implements
    111 
    112 class HelloWorld(Component):
    113   implements(IXMLRPCProvider)
    114 
    115   def hello_world(self):
    116     """ Hello world! """
    117     return "Hello world"
    118 
    119   def delete_whole_system(self, req):
    120     """ This is the safest function to export. """
    121     req.assert_permission('SANITY_CHECK')
    122     import os
    123     os.system("rm -rf /")
    124 
    125   def get_xmlrpc_functions(self):
    126     yield ('WIKI_VIEW', self.hello_world, 'hello_world')
    127     yield ('WIKI_ADMIN', self.delete_whole_system)
    128 }}}
    129 
    130 The method {{{hello_world()}}} is exported with the name "hello_world", as
    131 opposed to the default of combining the current module name with the function
    132 name.
    133 
    134 The {{{delete_whole_system()}}} method uses the optional {{{req}}} argument to
    135 enforce extra permission requirements.
     95See the [source:xmlrpcplugin/0.9/tracrpc/api.py source] for details.
    13696
    13797== Screenshot ==