Changes between Version 7 and Version 8 of XmlRpcPlugin

Timestamp:

Dec 23, 2005, 1:55:34 AM (18 years ago)

Author:

Alec Thomas

Comment:

Documented API somewhat

XmlRpcPlugin

@@ +1 @@
+[[PageOutline]]
 = Trac XML-RPC Plugin =
 
@@ -9 +10 @@
 It also includes some exported functions for manipulating tickets, with plans to include interfaces to other parts of Trac's API.
 
-The browseable XML-RPC URI suffix is /RPC2, however most XML-RPC clients should use the authenticated URI suffix 
+The browsable XML-RPC URI suffix is /RPC2, however most XML-RPC clients should use the authenticated URI suffix 
 /login/RPC2 as this is correctly authenticated by Trac.
 
-For example, for TracHacks the URI would be http://trac-hacks.swapoff.org/RPC2 or http://trac-hacks.swapoff.org/login/RPC2.
+For example, for TracHacks the URIs would be http://trac-hacks.swapoff.org/RPC2 and http://trac-hacks.swapoff.org/login/RPC2.
+
+== API ==
+
+The API is quite basic, but has a few magic features to make life a bit easier for the general case.
+
+To export functions via the XML-RPC, a Trac component simply needs to implement the following interface:
+
+{{{
+#!python
+class IXMLRPCHandler(Interface):
+    def get_xmlrpc_functions(): pass
+}}}
+
+The {{{get_xmlrpc_functions()}}} method returns an iterable of tuples in the form:
+
+{{{
+(permission, callable[, name[, description]])
+}}}
+
+Where these fields are in the following form:
+
+||'''Field'''||'''Description'''||
+||{{{permission}}}||The Trac permission required to be able to use this function. eg. {{{WIKI_ADMIN}}}.||
+||{{{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.||
+||{{{name}}}||If not provided, the function will be exported with the name {{{__module__.__name__}}}.||
+||{{{description}}||If not provided, the functions DOC string will be used.||
+
+See [[ref(API Usage)]] for an example.
 
 == Screenshot ==
@@ -71 +100 @@
 
 === API Usage ===
-Export a "hello world' function:
+Export a "hello world' function, as well as a less-than-safe function.
 
 {{{
@@ -82 +111 @@
 
   def hello_world(self):
+    """ Hello world! """
     return "Hello world"
 
+  def delete_whole_system(self, req):
+    """ This is the safest function to export. """
+    req.assert_permission('SANITY_CHECK')
+    import os
+    os.system("rm -rf /")
+
   def get_xmlrpc_functions(self):
-    yield ('WIKI_VIEW', self.hello_world)
+    yield ('WIKI_VIEW', self.hello_world, 'hello_world')
+    yield ('WIKI_ADMIN', self.delete_whole_system)
 }}}
 
+The method {{{hello_world()}}} is exported with the name "hello_world", as 
+opposed to the default of combining the current module name with the function 
+name.
+
+The {{{delete_whole_system()}}} method uses the optional {{{req}}} argument to 
+enforce extra permission requirements.
 
 == Author/Contributors ==
 
 '''Author:''' [wiki:athomas] [[BR]]
-'''Contributors:'''
 
 [[TagIt(plugin,athomas,alpha,0.9)]]