Changes between Version 7 and Version 8 of XmlRpcPlugin


Ignore:
Timestamp:
Dec 23, 2005, 2:55:34 AM (9 years ago)
Author:
athomas
Comment:

Documented API somewhat

Legend:

Unmodified
Added
Removed
Modified
  • XmlRpcPlugin

    v7 v8  
     1[[PageOutline]]
    12= Trac XML-RPC Plugin =
    23
     
    910It also includes some exported functions for manipulating tickets, with plans to include interfaces to other parts of Trac's API.
    1011
    11 The browseable XML-RPC URI suffix is /RPC2, however most XML-RPC clients should use the authenticated URI suffix
     12The browsable XML-RPC URI suffix is /RPC2, however most XML-RPC clients should use the authenticated URI suffix
    1213/login/RPC2 as this is correctly authenticated by Trac.
    1314
    14 For example, for TracHacks the URI would be http://trac-hacks.swapoff.org/RPC2 or http://trac-hacks.swapoff.org/login/RPC2.
     15For example, for TracHacks the URIs would be http://trac-hacks.swapoff.org/RPC2 and http://trac-hacks.swapoff.org/login/RPC2.
     16
     17== API ==
     18
     19The API is quite basic, but has a few magic features to make life a bit easier for the general case.
     20
     21To export functions via the XML-RPC, a Trac component simply needs to implement the following interface:
     22
     23{{{
     24#!python
     25class IXMLRPCHandler(Interface):
     26    def get_xmlrpc_functions(): pass
     27}}}
     28
     29The {{{get_xmlrpc_functions()}}} method returns an iterable of tuples in the form:
     30
     31{{{
     32(permission, callable[, name[, description]])
     33}}}
     34
     35Where these fields are in the following form:
     36
     37||'''Field'''||'''Description'''||
     38||{{{permission}}}||The Trac permission required to be able to use this function. 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
     43See [[ref(API Usage)]] for an example.
    1544
    1645== Screenshot ==
     
    71100
    72101=== API Usage ===
    73 Export a "hello world' function:
     102Export a "hello world' function, as well as a less-than-safe function.
    74103
    75104{{{
     
    82111
    83112  def hello_world(self):
     113    """ Hello world! """
    84114    return "Hello world"
    85115
     116  def delete_whole_system(self, req):
     117    """ This is the safest function to export. """
     118    req.assert_permission('SANITY_CHECK')
     119    import os
     120    os.system("rm -rf /")
     121
    86122  def get_xmlrpc_functions(self):
    87     yield ('WIKI_VIEW', self.hello_world)
     123    yield ('WIKI_VIEW', self.hello_world, 'hello_world')
     124    yield ('WIKI_ADMIN', self.delete_whole_system)
    88125}}}
    89126
     127The method {{{hello_world()}}} is exported with the name "hello_world", as
     128opposed to the default of combining the current module name with the function
     129name.
     130
     131The {{{delete_whole_system()}}} method uses the optional {{{req}}} argument to
     132enforce extra permission requirements.
    90133
    91134== Author/Contributors ==
    92135
    93136'''Author:''' [wiki:athomas] [[BR]]
    94 '''Contributors:'''
    95137
    96138[[TagIt(plugin,athomas,alpha,0.9)]]