diff options
Diffstat (limited to 'Doc/lib/libsimplexmlrpc.tex')
| -rw-r--r-- | Doc/lib/libsimplexmlrpc.tex | 235 |
1 files changed, 0 insertions, 235 deletions
diff --git a/Doc/lib/libsimplexmlrpc.tex b/Doc/lib/libsimplexmlrpc.tex deleted file mode 100644 index 235905e..0000000 --- a/Doc/lib/libsimplexmlrpc.tex +++ /dev/null @@ -1,235 +0,0 @@ -\section{\module{SimpleXMLRPCServer} --- - Basic XML-RPC server} - -\declaremodule{standard}{SimpleXMLRPCServer} -\modulesynopsis{Basic XML-RPC server implementation.} -\moduleauthor{Brian Quinlan}{brianq@activestate.com} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - -\versionadded{2.2} - -The \module{SimpleXMLRPCServer} module provides a basic server -framework for XML-RPC servers written in Python. Servers can either -be free standing, using \class{SimpleXMLRPCServer}, or embedded in a -CGI environment, using \class{CGIXMLRPCRequestHandler}. - -\begin{classdesc}{SimpleXMLRPCServer}{addr\optional{, - requestHandler\optional{, - logRequests\optional{, - allow_none\optional{, - encoding}}}}} - - Create a new server instance. This class - provides methods for registration of functions that can be called by - the XML-RPC protocol. The \var{requestHandler} parameter - should be a factory for request handler instances; it defaults to - \class{SimpleXMLRPCRequestHandler}. The \var{addr} and - \var{requestHandler} parameters are passed to the - \class{\refmodule{SocketServer}.TCPServer} constructor. If - \var{logRequests} is true (the default), requests will be logged; - setting this parameter to false will turn off logging. - The \var{allow_none} and \var{encoding} parameters are passed on to - \module{xmlrpclib} and control the XML-RPC responses that will be returned - from the server. The \var{bind_and_activate} parameter controls whether - \method{server_bind()} and \method{server_activate()} are called immediately - by the constructor; it defaults to true. Setting it to false allows code to - manipulate the \var{allow_reuse_address} class variable before the address - is bound. - \versionchanged[The \var{allow_none} and \var{encoding} parameters were added]{2.5} - \versionchanged[The \var{bind_and_activate} parameter was added]{2.6} -\end{classdesc} - -\begin{classdesc}{CGIXMLRPCRequestHandler}{\optional{allow_none\optional{, encoding}}} - Create a new instance to handle XML-RPC requests in a CGI - environment. - The \var{allow_none} and \var{encoding} parameters are passed on to - \module{xmlrpclib} and control the XML-RPC responses that will be returned - from the server. - \versionadded{2.3} - \versionchanged[The \var{allow_none} and \var{encoding} parameters were added]{2.5} -\end{classdesc} - -\begin{classdesc}{SimpleXMLRPCRequestHandler}{} - Create a new request handler instance. This request handler - supports \code{POST} requests and modifies logging so that the - \var{logRequests} parameter to the \class{SimpleXMLRPCServer} - constructor parameter is honored. -\end{classdesc} - - -\subsection{SimpleXMLRPCServer Objects \label{simple-xmlrpc-servers}} - -The \class{SimpleXMLRPCServer} class is based on -\class{SocketServer.TCPServer} and provides a means of creating -simple, stand alone XML-RPC servers. - -\begin{methoddesc}[SimpleXMLRPCServer]{register_function}{function\optional{, - name}} - Register a function that can respond to XML-RPC requests. If - \var{name} is given, it will be the method name associated with - \var{function}, otherwise \code{\var{function}.__name__} will be - used. \var{name} can be either a normal or Unicode string, and may - contain characters not legal in Python identifiers, including the - period character. -\end{methoddesc} - -\begin{methoddesc}[SimpleXMLRPCServer]{register_instance}{instance\optional{, - allow_dotted_names}} - Register an object which is used to expose method names which have - not been registered using \method{register_function()}. If - \var{instance} contains a \method{_dispatch()} method, it is called - with the requested method name and the parameters from the request. Its - API is \code{def \method{_dispatch}(self, method, params)} (note that - \var{params} does not represent a variable argument list). If it calls an - underlying function to perform its task, that function is called as - \code{func(*params)}, expanding the parameter list. - The return value from \method{_dispatch()} is returned to the client as - the result. If - \var{instance} does not have a \method{_dispatch()} method, it is - searched for an attribute matching the name of the requested method. - - If the optional \var{allow_dotted_names} argument is true and the - instance does not have a \method{_dispatch()} method, then - if the requested method name contains periods, each component of the - method name is searched for individually, with the effect that a - simple hierarchical search is performed. The value found from this - search is then called with the parameters from the request, and the - return value is passed back to the client. - - \begin{notice}[warning] - Enabling the \var{allow_dotted_names} option allows intruders to access - your module's global variables and may allow intruders to execute - arbitrary code on your machine. Only use this option on a secure, - closed network. - \end{notice} - - \versionchanged[\var{allow_dotted_names} was added to plug a security hole; - prior versions are insecure]{2.3.5, 2.4.1} - -\end{methoddesc} - -\begin{methoddesc}[SimpleXMLRPCServer]{register_introspection_functions}{} - Registers the XML-RPC introspection functions \code{system.listMethods}, - \code{system.methodHelp} and \code{system.methodSignature}. - \versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[SimpleXMLRPCServer]{register_multicall_functions}{} - Registers the XML-RPC multicall function system.multicall. -\end{methoddesc} - -\begin{memberdesc}[SimpleXMLRPCServer]{rpc_paths} -An attribute value that must be a tuple listing valid path portions of -the URL for receiving XML-RPC requests. Requests posted to other -paths will result in a 404 ``no such page'' HTTP error. If this -tuple is empty, all paths will be considered valid. -The default value is \code{('/', '/RPC2')}. - \versionadded{2.5} -\end{memberdesc} - -Example: - -\begin{verbatim} -from SimpleXMLRPCServer import SimpleXMLRPCServer - -# Create server -server = SimpleXMLRPCServer(("localhost", 8000)) -server.register_introspection_functions() - -# Register pow() function; this will use the value of -# pow.__name__ as the name, which is just 'pow'. -server.register_function(pow) - -# Register a function under a different name -def adder_function(x,y): - return x + y -server.register_function(adder_function, 'add') - -# Register an instance; all the methods of the instance are -# published as XML-RPC methods (in this case, just 'div'). -class MyFuncs: - def div(self, x, y): - return x // y - -server.register_instance(MyFuncs()) - -# Run the server's main loop -server.serve_forever() -\end{verbatim} - -The following client code will call the methods made available by -the preceding server: - -\begin{verbatim} -import xmlrpclib - -s = xmlrpclib.Server('http://localhost:8000') -print s.pow(2,3) # Returns 2**3 = 8 -print s.add(2,3) # Returns 5 -print s.div(5,2) # Returns 5//2 = 2 - -# Print list of available methods -print s.system.listMethods() -\end{verbatim} - - -\subsection{CGIXMLRPCRequestHandler} - -The \class{CGIXMLRPCRequestHandler} class can be used to -handle XML-RPC requests sent to Python CGI scripts. - -\begin{methoddesc}[CGIXMLRPCRequestHandler]{register_function}{function\optional{, name}} -Register a function that can respond to XML-RPC requests. If -\var{name} is given, it will be the method name associated with -function, otherwise \var{function.__name__} will be used. \var{name} -can be either a normal or Unicode string, and may contain -characters not legal in Python identifiers, including the period -character. -\end{methoddesc} - -\begin{methoddesc}[CGIXMLRPCRequestHandler]{register_instance}{instance} -Register an object which is used to expose method names -which have not been registered using \method{register_function()}. If -instance contains a \method{_dispatch()} method, it is called with the -requested method name and the parameters from the -request; the return value is returned to the client as the result. -If instance does not have a \method{_dispatch()} method, it is searched -for an attribute matching the name of the requested method; if -the requested method name contains periods, each -component of the method name is searched for individually, -with the effect that a simple hierarchical search is performed. -The value found from this search is then called with the -parameters from the request, and the return value is passed -back to the client. -\end{methoddesc} - -\begin{methoddesc}[CGIXMLRPCRequestHandler]{register_introspection_functions}{} -Register the XML-RPC introspection functions -\code{system.listMethods}, \code{system.methodHelp} and -\code{system.methodSignature}. -\end{methoddesc} - -\begin{methoddesc}[CGIXMLRPCRequestHandler]{register_multicall_functions}{} -Register the XML-RPC multicall function \code{system.multicall}. -\end{methoddesc} - -\begin{methoddesc}[CGIXMLRPCRequestHandler]{handle_request}{\optional{request_text = None}} -Handle a XML-RPC request. If \var{request_text} is given, it -should be the POST data provided by the HTTP server, -otherwise the contents of stdin will be used. -\end{methoddesc} - -Example: - -\begin{verbatim} -class MyFuncs: - def div(self, x, y) : return x // y - - -handler = CGIXMLRPCRequestHandler() -handler.register_function(pow) -handler.register_function(lambda x,y: x+y, 'add') -handler.register_introspection_functions() -handler.register_instance(MyFuncs()) -handler.handle_request() -\end{verbatim} |