Fred Drake | e486e0d | 2001-09-28 22:02:21 +0000 | [diff] [blame] | 1 | \section{\module{SimpleXMLRPCServer} --- |
| 2 | Basic XML-RPC server} |
| 3 | |
| 4 | \declaremodule{standard}{SimpleXMLRPCServer} |
Fred Drake | 48704ee | 2001-11-28 07:32:53 +0000 | [diff] [blame] | 5 | \modulesynopsis{Basic XML-RPC server implementation.} |
Fred Drake | e486e0d | 2001-09-28 22:02:21 +0000 | [diff] [blame] | 6 | \moduleauthor{Brian Quinlan}{brianq@activestate.com} |
| 7 | \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
| 8 | |
| 9 | |
| 10 | The \module{SimpleXMLRPCServer} module provides a basic server |
Martin v. Löwis | d69663d | 2003-01-15 11:37:23 +0000 | [diff] [blame] | 11 | framework for XML-RPC servers written in Python. Servers can either |
| 12 | be free standing, using \class{SimpleXMLRPCServer}, or embedded in a |
| 13 | CGI environment, using \class{CGIXMLRPCRequestHandler}. |
Fred Drake | e486e0d | 2001-09-28 22:02:21 +0000 | [diff] [blame] | 14 | |
| 15 | \begin{classdesc}{SimpleXMLRPCServer}{addr\optional{, |
| 16 | requestHandler\optional{, logRequests}}} |
Martin v. Löwis | d69663d | 2003-01-15 11:37:23 +0000 | [diff] [blame] | 17 | |
Fred Drake | e486e0d | 2001-09-28 22:02:21 +0000 | [diff] [blame] | 18 | Create a new server instance. The \var{requestHandler} parameter |
| 19 | should be a factory for request handler instances; it defaults to |
| 20 | \class{SimpleXMLRPCRequestHandler}. The \var{addr} and |
| 21 | \var{requestHandler} parameters are passed to the |
| 22 | \class{\refmodule{SocketServer}.TCPServer} constructor. If |
| 23 | \var{logRequests} is true (the default), requests will be logged; |
| 24 | setting this parameter to false will turn off logging. This class |
| 25 | provides methods for registration of functions that can be called by |
| 26 | the XML-RPC protocol. |
| 27 | \end{classdesc} |
| 28 | |
Martin v. Löwis | d69663d | 2003-01-15 11:37:23 +0000 | [diff] [blame] | 29 | \begin{classdesc}{CGIXMLRPCRequestHandler}{} |
| 30 | Create a new instance to handle XML-RPC requests in a CGI |
| 31 | environment. \versionadded{2.3} |
| 32 | \end{classdesc} |
Fred Drake | e486e0d | 2001-09-28 22:02:21 +0000 | [diff] [blame] | 33 | |
| 34 | \begin{classdesc}{SimpleXMLRPCRequestHandler}{} |
| 35 | Create a new request handler instance. This request handler |
| 36 | supports \code{POST} requests and modifies logging so that the |
| 37 | \var{logRequests} parameter to the \class{SimpleXMLRPCServer} |
| 38 | constructor parameter is honored. |
| 39 | \end{classdesc} |
| 40 | |
| 41 | |
| 42 | \subsection{SimpleXMLRPCServer Objects \label{simple-xmlrpc-servers}} |
| 43 | |
Martin v. Löwis | d69663d | 2003-01-15 11:37:23 +0000 | [diff] [blame] | 44 | The \class{SimpleXMLRPCServer} class is based on |
| 45 | \class{SocketServer.TCPServer} and provides a means of creating |
| 46 | simple, stand alone XML-RPC servers. |
Fred Drake | e486e0d | 2001-09-28 22:02:21 +0000 | [diff] [blame] | 47 | |
| 48 | \begin{methoddesc}[SimpleXMLRPCServer]{register_function}{function\optional{, |
| 49 | name}} |
Martin v. Löwis | d69663d | 2003-01-15 11:37:23 +0000 | [diff] [blame] | 50 | Register a function that can respond to XML-RPC requests. If |
| 51 | \var{name} is given, it will be the method name associated with |
| 52 | \var{function}, otherwise \code{\var{function}.__name__} will be |
| 53 | used. \var{name} can be either a normal or Unicode string, and may |
| 54 | contain characters not legal in Python identifiers, including the |
| 55 | period character. |
Fred Drake | e486e0d | 2001-09-28 22:02:21 +0000 | [diff] [blame] | 56 | \end{methoddesc} |
| 57 | |
| 58 | \begin{methoddesc}[SimpleXMLRPCServer]{register_instance}{instance} |
| 59 | Register an object which is used to expose method names which have |
| 60 | not been registered using \method{register_function()}. If |
| 61 | \var{instance} contains a \method{_dispatch()} method, it is called |
| 62 | with the requested method name and the parameters from the request; |
| 63 | the return value is returned to the client as the result. If |
| 64 | \var{instance} does not have a \method{_dispatch()} method, it is |
| 65 | searched for an attribute matching the name of the requested method; |
| 66 | if the requested method name contains periods, each component of the |
| 67 | method name is searched for individually, with the effect that a |
| 68 | simple hierarchical search is performed. The value found from this |
| 69 | search is then called with the parameters from the request, and the |
| 70 | return value is passed back to the client. |
| 71 | \end{methoddesc} |
Martin v. Löwis | d69663d | 2003-01-15 11:37:23 +0000 | [diff] [blame] | 72 | |
| 73 | \begin{methoddesc}{register_introspection_functions}{} |
| 74 | Registers the XML-RPC introspection functions \code{system.listMethods}, |
| 75 | \code{system.methodHelp} and \code{system.methodSignature}. |
| 76 | \versionadded{2.3} |
| 77 | \end{methoddesc} |
| 78 | |
| 79 | \begin{methoddesc}{register_multicall_functions}{} |
| 80 | Registers the XML-RPC multicall function system.multicall. |
| 81 | \end{methoddesc} |
| 82 | |
| 83 | Example: |
| 84 | |
| 85 | \begin{verbatim} |
| 86 | class MyFuncs: |
| 87 | def div(self, x, y) : return div(x,y) |
| 88 | |
| 89 | |
| 90 | server = SimpleXMLRPCServer(("localhost", 8000)) |
| 91 | server.register_function(pow) |
| 92 | server.register_function(lambda x,y: x+y, 'add') |
| 93 | server.register_introspection_functions() |
| 94 | server.register_instance(MyFuncs()) |
| 95 | server.serve_forever() |
| 96 | \end{verbatim} |
| 97 | |
| 98 | \subsection{CGIXMLRPCRequestHandler} |
| 99 | |
| 100 | The \class{CGIXMLRPCRequestHandler} class can be used to |
| 101 | handle XML-RPC requests sent to Python CGI scripts. |
| 102 | |
| 103 | \begin{methoddesc}{register_function}{function\optional{, name}} |
| 104 | Register a function that can respond to XML-RPC requests. If |
Fred Drake | 42b567f | 2003-01-17 22:47:33 +0000 | [diff] [blame] | 105 | \var{name} is given, it will be the method name associated with |
Martin v. Löwis | d69663d | 2003-01-15 11:37:23 +0000 | [diff] [blame] | 106 | function, otherwise \var{function.__name__} will be used. \var{name} |
| 107 | can be either a normal or Unicode string, and may contain |
| 108 | characters not legal in Python identifiers, including the period |
| 109 | character. |
| 110 | \end{methoddesc} |
| 111 | |
| 112 | \begin{methoddesc}{register_instance}{instance} |
| 113 | Register an object which is used to expose method names |
| 114 | which have not been registered using \method{register_function()}. If |
| 115 | instance contains a \method{_dispatch()} method, it is called with the |
| 116 | requested method name and the parameters from the |
| 117 | request; the return value is returned to the client as the result. |
Fred Drake | 42b567f | 2003-01-17 22:47:33 +0000 | [diff] [blame] | 118 | If instance does not have a \method{_dispatch()} method, it is searched |
Martin v. Löwis | d69663d | 2003-01-15 11:37:23 +0000 | [diff] [blame] | 119 | for an attribute matching the name of the requested method; if |
| 120 | the requested method name contains periods, each |
| 121 | component of the method name is searched for individually, |
| 122 | with the effect that a simple hierarchical search is performed. |
| 123 | The value found from this search is then called with the |
| 124 | parameters from the request, and the return value is passed |
| 125 | back to the client. |
| 126 | \end{methoddesc} |
| 127 | |
| 128 | \begin{methoddesc}{register_introspection_functions}{} |
| 129 | Register the XML-RPC introspection functions |
| 130 | \code{system.listMethods}, \code{system.methodHelp} and |
| 131 | \code{system.methodSignature}. |
| 132 | \end{methoddesc} |
| 133 | |
| 134 | \begin{methoddesc}{register_multicall_functions}{} |
| 135 | Register the XML-RPC multicall function \code{system.multicall}. |
| 136 | \end{methoddesc} |
| 137 | |
| 138 | \begin{methoddesc}{handle_request}{\optional{request_text = None}} |
| 139 | Handle a XML-RPC request. If \var{request_text} is given, it |
| 140 | should be the POST data provided by the HTTP server, |
| 141 | otherwise the contents of stdin will be used. |
| 142 | \end{methoddesc} |
| 143 | |
| 144 | Example: |
| 145 | |
| 146 | \begin{verbatim} |
| 147 | class MyFuncs: |
| 148 | def div(self, x, y) : return div(x,y) |
| 149 | |
| 150 | |
| 151 | handler = CGIXMLRPCRequestHandler() |
| 152 | handler.register_function(pow) |
| 153 | handler.register_function(lambda x,y: x+y, 'add') |
| 154 | handler.register_introspection_functions() |
| 155 | handler.register_instance(MyFuncs()) |
| 156 | handler.handle_request() |
Fred Drake | 42b567f | 2003-01-17 22:47:33 +0000 | [diff] [blame] | 157 | \end{verbatim} |