rest25/library/simplexmlrpcserver.rst => rest262/library/simplexmlrpcserver.rst
n1- 
2:mod:`SimpleXMLRPCServer` --- Basic XML-RPC server
3==================================================
4
5.. module:: SimpleXMLRPCServer
6   :synopsis: Basic XML-RPC server implementation.
7.. moduleauthor:: Brian Quinlan <brianq@activestate.com>
8.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
9
n9+.. note::
10+   The :mod:`SimpleXMLRPCServer` module has been merged into
11+   :mod:`xmlrpc.server` in Python 3.0.  The :term:`2to3` tool will automatically
12+   adapt imports when converting your sources to 3.0.
13+ 
10
11.. versionadded:: 2.2
12
n13-The :mod:`SimpleXMLRPCServer` module provides a basic server framework for XML-
n17+The :mod:`SimpleXMLRPCServer` module provides a basic server framework for
14-RPC servers written in Python.  Servers can either be free standing, using
18+XML-RPC servers written in Python.  Servers can either be free standing, using
15:class:`SimpleXMLRPCServer`, or embedded in a CGI environment, using
16:class:`CGIXMLRPCRequestHandler`.
17
18
n19-.. class:: SimpleXMLRPCServer(addr[, requestHandler[, logRequests[allow_none[, encoding]]]])
n23+.. class:: SimpleXMLRPCServer(addr[, requestHandler[, logRequests[allow_none[, encoding]]]])
20
21   Create a new server instance.  This class provides methods for registration of
22   functions that can be called by the XML-RPC protocol.  The *requestHandler*
23   parameter should be a factory for request handler instances; it defaults to
24   :class:`SimpleXMLRPCRequestHandler`.  The *addr* and *requestHandler* parameters
25   are passed to the :class:`SocketServer.TCPServer` constructor.  If *logRequests*
26   is true (the default), requests will be logged; setting this parameter to false
27   will turn off logging.   The *allow_none* and *encoding* parameters are passed
28   on to  :mod:`xmlrpclib` and control the XML-RPC responses that will be returned
n29-   from the server.
n33+   from the server. The *bind_and_activate* parameter controls whether
34+   :meth:`server_bind` and :meth:`server_activate` are called immediately by the
35+   constructor; it defaults to true. Setting it to false allows code to manipulate
36+   the *allow_reuse_address* class variable before the address is bound.
30
31   .. versionchanged:: 2.5
32      The *allow_none* and *encoding* parameters were added.
n40+ 
41+   .. versionchanged:: 2.6
42+      The *bind_and_activate* parameter was added.
33
34
35.. class:: CGIXMLRPCRequestHandler([allow_none[, encoding]])
36
37   Create a new instance to handle XML-RPC requests in a CGI environment.  The
38   *allow_none* and *encoding* parameters are passed on to  :mod:`xmlrpclib` and
39   control the XML-RPC responses that will be returned  from the server.
40
96      module's global variables and may allow intruders to execute arbitrary code on
97      your machine.  Only use this option on a secure, closed network.
98
99   .. versionchanged:: 2.3.5, 2.4.1
100      *allow_dotted_names* was added to plug a security hole; prior versions are
101      insecure.
102
103
n104-.. method:: XXX Class.register_introspection_functions()
n114+.. method:: SimpleXMLRPCServer.register_introspection_functions()
105
106   Registers the XML-RPC introspection functions ``system.listMethods``,
107   ``system.methodHelp`` and ``system.methodSignature``.
108
109   .. versionadded:: 2.3
110
111
n112-.. method:: XXX Class.register_multicall_functions()
n122+.. method:: SimpleXMLRPCServer.register_multicall_functions()
113
114   Registers the XML-RPC multicall function system.multicall.
115
116
n117-.. attribute:: SimpleXMLRPCServer.rpc_paths
n127+.. attribute:: SimpleXMLRPCRequestHandler.rpc_paths
118
119   An attribute value that must be a tuple listing valid path portions of the URL
120   for receiving XML-RPC requests.  Requests posted to other paths will result in a
121   404 "no such page" HTTP error.  If this tuple is empty, all paths will be
122   considered valid. The default value is ``('/', '/RPC2')``.
123
124   .. versionadded:: 2.5
125
n126-Example::
n136+.. _simplexmlrpcserver-example:
137+ 
138+SimpleXMLRPCServer Example
139+^^^^^^^^^^^^^^^^^^^^^^^^^^
140+Server code::
127
128   from SimpleXMLRPCServer import SimpleXMLRPCServer
n143+   from SimpleXMLRPCServer import SimpleXMLRPCRequestHandler
144+ 
145+   # Restrict to a particular path.
146+   class RequestHandler(SimpleXMLRPCRequestHandler):
147+       rpc_paths = ('/RPC2',)
129
130   # Create server
n131-   server = SimpleXMLRPCServer(("localhost", 8000))
n150+   server = SimpleXMLRPCServer(("localhost", 8000),
151+                               requestHandler=RequestHandler)
132   server.register_introspection_functions()
133
n134-   # Register pow() function; this will use the value of 
n154+   # Register pow() function; this will use the value of
135   # pow.__name__ as the name, which is just 'pow'.
136   server.register_function(pow)
137
138   # Register a function under a different name
139   def adder_function(x,y):
140       return x + y
141   server.register_function(adder_function, 'add')
142
n143-   # Register an instance; all the methods of the instance are 
n163+   # Register an instance; all the methods of the instance are
144   # published as XML-RPC methods (in this case, just 'div').
145   class MyFuncs:
n146-       def div(self, x, y): 
n166+       def div(self, x, y):
147           return x // y
148
149   server.register_instance(MyFuncs())
150
151   # Run the server's main loop
152   server.serve_forever()
153
n154-The following client code will call the methods made available by  the preceding
n174+The following client code will call the methods made available by the preceding
155server::
156
157   import xmlrpclib
158
n159-   s = xmlrpclib.Server('http://localhost:8000')
n179+   s = xmlrpclib.ServerProxy('http://localhost:8000')
160   print s.pow(2,3)  # Returns 2**3 = 8
161   print s.add(2,3)  # Returns 5
162   print s.div(5,2)  # Returns 5//2 = 2
163
164   # Print list of available methods
165   print s.system.listMethods()
166
167
168CGIXMLRPCRequestHandler
169-----------------------
170
171The :class:`CGIXMLRPCRequestHandler` class can be used to  handle XML-RPC
172requests sent to Python CGI scripts.
173
174
n175-.. method:: XXX Class.register_function(function[, name])
n195+.. method:: CGIXMLRPCRequestHandler.register_function(function[, name])
176
177   Register a function that can respond to XML-RPC requests. If  *name* is given,
178   it will be the method name associated with  function, otherwise
179   *function.__name__* will be used. *name* can be either a normal or Unicode
180   string, and may contain  characters not legal in Python identifiers, including
181   the period character.
182
183
n184-.. method:: XXX Class.register_instance(instance)
n204+.. method:: CGIXMLRPCRequestHandler.register_instance(instance)
185
186   Register an object which is used to expose method names  which have not been
187   registered using :meth:`register_function`. If  instance contains a
188   :meth:`_dispatch` method, it is called with the  requested method name and the
189   parameters from the  request; the return value is returned to the client as the
190   result. If instance does not have a :meth:`_dispatch` method, it is searched
191   for an attribute matching the name of the requested method; if  the requested
192   method name contains periods, each  component of the method name is searched for
193   individually,  with the effect that a simple hierarchical search is performed.
194   The value found from this search is then called with the  parameters from the
195   request, and the return value is passed  back to the client.
196
197
n198-.. method:: XXX Class.register_introspection_functions()
n218+.. method:: CGIXMLRPCRequestHandler.register_introspection_functions()
199
200   Register the XML-RPC introspection functions  ``system.listMethods``,
201   ``system.methodHelp`` and  ``system.methodSignature``.
202
203
n204-.. method:: XXX Class.register_multicall_functions()
n224+.. method:: CGIXMLRPCRequestHandler.register_multicall_functions()
205
206   Register the XML-RPC multicall function ``system.multicall``.
207
208
t209-.. method:: XXX Class.handle_request([request_text = None])
t229+.. method:: CGIXMLRPCRequestHandler.handle_request([request_text = None])
210
211   Handle a XML-RPC request. If *request_text* is given, it  should be the POST
212   data provided by the HTTP server,  otherwise the contents of stdin will be used.
213
214Example::
215
216   class MyFuncs:
217       def div(self, x, y) : return x // y
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op