Changes between Version 14 and Version 15 of XmlRpcPlugin


Ignore:
Timestamp:
Dec 27, 2005 12:19:34 PM (9 years ago)
Author:
athomas
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 ==