Changeset 1662

Timestamp:

06/07/07 12:49:19

Author:

fumanchu

Message:

New docstring for XMLRPCController.

Files:

• trunk/cherrypy/_cptools.py (modified) (1 diff)

trunk/cherrypy/_cptools.py

@@ -242 +242 @@
-
-class XMLRPCController(object):
+    """A Controller (page handler collection) for XML-RPC.
+    
+    To use it, have your controllers subclass this base class (it will
+    turn on the tool for you).
+    
+    You can also supply the following optional config entries:
+        
+        tools.xmlrpc.encoding: 'utf-8'
+        tools.xmlrpc.allow_none: 0
+    
+    XML-RPC is a rather discontinuous layer over HTTP; dispatching to the
+    appropriate handler must first be performed according to the URL, and
+    then a second dispatch step must take place according to the RPC method
+    specified in the request body. It also allows a superfluous "/RPC2"
+    prefix in the URL, supplies its own handler args in the body, and
+    requires a 200 OK "Fault" response instead of 404 when the desired
+    method is not found.
+    
+    Therefore, XML-RPC cannot be implemented for CherryPy via a Tool alone.
+    This Controller acts as the dispatch target for the first half (based
+    on the URL); it then reads the RPC method from the request body and
+    does its own second dispatch step based on that method. It also reads
+    body params, and returns a Fault on error.
+    
+    The XMLRPCDispatcher strips any /RPC2 prefix; if you aren't using /RPC2
+    in your URL's, you can safely skip turning on the XMLRPCDispatcher.
+    Otherwise, you need to use declare it in config:
+        
+        request.dispatch: cherrypy.dispatch.XMLRPCDispatcher()
+    """
-    
-    # Note we're hard-coding this into the 'tools' namespace. We could do