• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1:mod:`xmlrpclib` --- XML-RPC client access
2==========================================
3
4.. module:: xmlrpclib
5   :synopsis: XML-RPC client access.
6.. moduleauthor:: Fredrik Lundh <fredrik@pythonware.com>
7.. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
8
9.. note::
10   The :mod:`xmlrpclib` module has been renamed to :mod:`xmlrpc.client` in
11   Python 3.  The :term:`2to3` tool will automatically adapt imports when
12   converting your sources to Python 3.
13
14
15.. XXX Not everything is documented yet.  It might be good to describe
16   Marshaller, Unmarshaller, getparser, dumps, loads, and Transport.
17
18.. versionadded:: 2.2
19
20**Source code:** :source:`Lib/xmlrpclib.py`
21
22--------------
23
24XML-RPC is a Remote Procedure Call method that uses XML passed via HTTP(S) as a
25transport.  With it, a client can call methods with parameters on a remote
26server (the server is named by a URI) and get back structured data.  This module
27supports writing XML-RPC client code; it handles all the details of translating
28between conformable Python objects and XML on the wire.
29
30
31.. warning::
32
33   The :mod:`xmlrpclib` module is not secure against maliciously
34   constructed data.  If you need to parse untrusted or unauthenticated data see
35   :ref:`xml-vulnerabilities`.
36
37.. versionchanged:: 2.7.9
38
39   For HTTPS URIs, :mod:`xmlrpclib` now performs all the necessary certificate
40   and hostname checks by default.
41
42.. class:: ServerProxy(uri[, transport[, encoding[, verbose[, allow_none[, use_datetime[, context]]]]]])
43
44   A :class:`ServerProxy` instance is an object that manages communication with a
45   remote XML-RPC server.  The required first argument is a URI (Uniform Resource
46   Indicator), and will normally be the URL of the server.  The optional second
47   argument is a transport factory instance; by default it is an internal
48   :class:`SafeTransport` instance for https: URLs and an internal HTTP
49   :class:`Transport` instance otherwise.  The optional third argument is an
50   encoding, by default UTF-8. The optional fourth argument is a debugging flag.
51
52   The following parameters govern the use of the returned proxy instance.
53   If *allow_none* is true,  the Python constant ``None`` will be translated into
54   XML; the default behaviour is for ``None`` to raise a :exc:`TypeError`. This is
55   a commonly-used extension to the XML-RPC specification, but isn't supported by
56   all clients and servers; see `http://ontosys.com/xml-rpc/extensions.php
57   <https://web.archive.org/web/20130120074804/http://ontosys.com/xml-rpc/extensions.php>`_
58   for a description.
59   The *use_datetime* flag can be used to cause date/time values to
60   be presented as :class:`datetime.datetime` objects; this is false by default.
61   :class:`datetime.datetime` objects may be passed to calls.
62
63   Both the HTTP and HTTPS transports support the URL syntax extension for HTTP
64   Basic Authentication: ``http://user:pass@host:port/path``.  The ``user:pass``
65   portion will be base64-encoded as an HTTP 'Authorization' header, and sent to
66   the remote server as part of the connection process when invoking an XML-RPC
67   method.  You only need to use this if the remote server requires a Basic
68   Authentication user and password. If an HTTPS URL is provided, *context* may
69   be :class:`ssl.SSLContext` and configures the SSL settings of the underlying
70   HTTPS connection.
71
72   The returned instance is a proxy object with methods that can be used to invoke
73   corresponding RPC calls on the remote server.  If the remote server supports the
74   introspection API, the proxy can also be used to query the remote server for the
75   methods it supports (service discovery) and fetch other server-associated
76   metadata.
77
78   Types that are conformable (e.g. that can be marshalled through XML),
79   include the following (and except where noted, they are unmarshalled
80   as the same Python type):
81
82   .. tabularcolumns:: |l|L|
83
84   +----------------------+-------------------------------------------------------+
85   | XML-RPC type         | Python type                                           |
86   +======================+=======================================================+
87   | ``boolean``          | :class:`bool`                                         |
88   +----------------------+-------------------------------------------------------+
89   | ``int`` or ``i4``    | :class:`int` or :class:`long` in range from           |
90   |                      | -2147483648 to 2147483647.                            |
91   +----------------------+-------------------------------------------------------+
92   | ``double``           | :class:`float`                                        |
93   +----------------------+-------------------------------------------------------+
94   | ``string``           | :class:`str` or :class:`unicode`                      |
95   +----------------------+-------------------------------------------------------+
96   | ``array``            | :class:`list` or :class:`tuple` containing            |
97   |                      | conformable elements.  Arrays are returned as         |
98   |                      | :class:`lists <list>`.                                |
99   +----------------------+-------------------------------------------------------+
100   | ``struct``           | :class:`dict`.  Keys must be strings, values may be   |
101   |                      | any conformable type.  Objects of user-defined        |
102   |                      | classes can be passed in; only their                  |
103   |                      | :attr:`~object.__dict__` attribute is transmitted.    |
104   +----------------------+-------------------------------------------------------+
105   | ``dateTime.iso8601`` | :class:`DateTime` or :class:`datetime.datetime`.      |
106   |                      | Returned type depends on values of the *use_datetime* |
107   |                      | flags.                                                |
108   +----------------------+-------------------------------------------------------+
109   | ``base64``           | :class:`Binary`                                       |
110   +----------------------+-------------------------------------------------------+
111   | ``nil``              | The ``None`` constant.  Passing is allowed only if    |
112   |                      | *allow_none* is true.                                 |
113   +----------------------+-------------------------------------------------------+
114
115   This is the full set of data types supported by XML-RPC.  Method calls may also
116   raise a special :exc:`Fault` instance, used to signal XML-RPC server errors, or
117   :exc:`ProtocolError` used to signal an error in the HTTP/HTTPS transport layer.
118   Both :exc:`Fault` and :exc:`ProtocolError` derive from a base class called
119   :exc:`Error`.  Note that even though starting with Python 2.2 you can subclass
120   built-in types, the xmlrpclib module currently does not marshal instances of such
121   subclasses.
122
123   When passing strings, characters special to XML such as ``<``, ``>``, and ``&``
124   will be automatically escaped.  However, it's the caller's responsibility to
125   ensure that the string is free of characters that aren't allowed in XML, such as
126   the control characters with ASCII values between 0 and 31 (except, of course,
127   tab, newline and carriage return); failing to do this will result in an XML-RPC
128   request that isn't well-formed XML.  If you have to pass arbitrary strings via
129   XML-RPC, use the :class:`Binary` wrapper class described below.
130
131   :class:`Server` is retained as an alias for :class:`ServerProxy` for backwards
132   compatibility.  New code should use :class:`ServerProxy`.
133
134   .. versionchanged:: 2.5
135      The *use_datetime* flag was added.
136
137   .. versionchanged:: 2.6
138      Instances of :term:`new-style class`\es can be passed in if they have an
139      *__dict__* attribute and don't have a base class that is marshalled in a
140      special way.
141
142   .. versionchanged:: 2.7.9
143      Added the *context* argument.
144
145
146.. seealso::
147
148   `XML-RPC HOWTO <http://www.tldp.org/HOWTO/XML-RPC-HOWTO/index.html>`_
149      A good description of XML-RPC operation and client software in several languages.
150      Contains pretty much everything an XML-RPC client developer needs to know.
151
152   `XML-RPC Introspection <http://xmlrpc-c.sourceforge.net/introspection.html>`_
153      Describes the XML-RPC protocol extension for introspection.
154
155   `XML-RPC Specification <http://www.xmlrpc.com/spec>`_
156      The official specification.
157
158   `Unofficial XML-RPC Errata <http://effbot.org/zone/xmlrpc-errata.htm>`_
159      Fredrik Lundh's "unofficial errata, intended to clarify certain
160      details in the XML-RPC specification, as well as hint at
161      'best practices' to use when designing your own XML-RPC
162      implementations."
163
164.. _serverproxy-objects:
165
166ServerProxy Objects
167-------------------
168
169A :class:`ServerProxy` instance has a method corresponding to each remote
170procedure call accepted by the XML-RPC server.  Calling the method performs an
171RPC, dispatched by both name and argument signature (e.g. the same method name
172can be overloaded with multiple argument signatures).  The RPC finishes by
173returning a value, which may be either returned data in a conformant type or a
174:class:`Fault` or :class:`ProtocolError` object indicating an error.
175
176Servers that support the XML introspection API support some common methods
177grouped under the reserved :attr:`~ServerProxy.system` attribute:
178
179
180.. method:: ServerProxy.system.listMethods()
181
182   This method returns a list of strings, one for each (non-system) method
183   supported by the XML-RPC server.
184
185
186.. method:: ServerProxy.system.methodSignature(name)
187
188   This method takes one parameter, the name of a method implemented by the XML-RPC
189   server. It returns an array of possible signatures for this method. A signature
190   is an array of types. The first of these types is the return type of the method,
191   the rest are parameters.
192
193   Because multiple signatures (ie. overloading) is permitted, this method returns
194   a list of signatures rather than a singleton.
195
196   Signatures themselves are restricted to the top level parameters expected by a
197   method. For instance if a method expects one array of structs as a parameter,
198   and it returns a string, its signature is simply "string, array". If it expects
199   three integers and returns a string, its signature is "string, int, int, int".
200
201   If no signature is defined for the method, a non-array value is returned. In
202   Python this means that the type of the returned  value will be something other
203   than list.
204
205
206.. method:: ServerProxy.system.methodHelp(name)
207
208   This method takes one parameter, the name of a method implemented by the XML-RPC
209   server.  It returns a documentation string describing the use of that method. If
210   no such string is available, an empty string is returned. The documentation
211   string may contain HTML markup.
212
213
214.. _boolean-objects:
215
216Boolean Objects
217---------------
218
219This class may be initialized from any Python value; the instance returned
220depends only on its truth value.  It supports various Python operators through
221:meth:`__cmp__`, :meth:`__repr__`, :meth:`__int__`, and :meth:`__nonzero__`
222methods, all implemented in the obvious ways.
223
224It also has the following method, supported mainly for internal use by the
225unmarshalling code:
226
227
228.. method:: Boolean.encode(out)
229
230   Write the XML-RPC encoding of this Boolean item to the out stream object.
231
232A working example follows. The server code::
233
234   import xmlrpclib
235   from SimpleXMLRPCServer import SimpleXMLRPCServer
236
237   def is_even(n):
238       return n % 2 == 0
239
240   server = SimpleXMLRPCServer(("localhost", 8000))
241   print "Listening on port 8000..."
242   server.register_function(is_even, "is_even")
243   server.serve_forever()
244
245The client code for the preceding server::
246
247   import xmlrpclib
248
249   proxy = xmlrpclib.ServerProxy("http://localhost:8000/")
250   print "3 is even: %s" % str(proxy.is_even(3))
251   print "100 is even: %s" % str(proxy.is_even(100))
252
253.. _datetime-objects:
254
255DateTime Objects
256----------------
257
258.. class:: DateTime
259
260   This class may be initialized with seconds since the epoch, a time
261   tuple, an ISO 8601 time/date string, or a :class:`datetime.datetime`
262   instance.  It has the following methods, supported mainly for internal
263   use by the marshalling/unmarshalling code:
264
265
266   .. method:: decode(string)
267
268      Accept a string as the instance's new time value.
269
270
271   .. method:: encode(out)
272
273      Write the XML-RPC encoding of this :class:`DateTime` item to the *out* stream
274      object.
275
276   It also supports certain of Python's built-in operators through :meth:`__cmp__`
277   and :meth:`__repr__` methods.
278
279A working example follows. The server code::
280
281   import datetime
282   from SimpleXMLRPCServer import SimpleXMLRPCServer
283   import xmlrpclib
284
285   def today():
286       today = datetime.datetime.today()
287       return xmlrpclib.DateTime(today)
288
289   server = SimpleXMLRPCServer(("localhost", 8000))
290   print "Listening on port 8000..."
291   server.register_function(today, "today")
292   server.serve_forever()
293
294The client code for the preceding server::
295
296   import xmlrpclib
297   import datetime
298
299   proxy = xmlrpclib.ServerProxy("http://localhost:8000/")
300
301   today = proxy.today()
302   # convert the ISO8601 string to a datetime object
303   converted = datetime.datetime.strptime(today.value, "%Y%m%dT%H:%M:%S")
304   print "Today: %s" % converted.strftime("%d.%m.%Y, %H:%M")
305
306.. _binary-objects:
307
308Binary Objects
309--------------
310
311.. class:: Binary
312
313   This class may be initialized from string data (which may include NULs). The
314   primary access to the content of a :class:`Binary` object is provided by an
315   attribute:
316
317
318   .. attribute:: data
319
320      The binary data encapsulated by the :class:`Binary` instance.  The data is
321      provided as an 8-bit string.
322
323   :class:`Binary` objects have the following methods, supported mainly for
324   internal use by the marshalling/unmarshalling code:
325
326
327   .. method:: decode(string)
328
329      Accept a base64 string and decode it as the instance's new data.
330
331
332   .. method:: encode(out)
333
334      Write the XML-RPC base 64 encoding of this binary item to the *out* stream object.
335
336      The encoded data will have newlines every 76 characters as per
337      `RFC 2045 section 6.8 <https://tools.ietf.org/html/rfc2045#section-6.8>`_,
338      which was the de facto standard base64 specification when the
339      XML-RPC spec was written.
340
341   It also supports certain of Python's built-in operators through a
342   :meth:`__cmp__` method.
343
344Example usage of the binary objects.  We're going to transfer an image over
345XMLRPC::
346
347   from SimpleXMLRPCServer import SimpleXMLRPCServer
348   import xmlrpclib
349
350   def python_logo():
351        with open("python_logo.jpg", "rb") as handle:
352            return xmlrpclib.Binary(handle.read())
353
354   server = SimpleXMLRPCServer(("localhost", 8000))
355   print "Listening on port 8000..."
356   server.register_function(python_logo, 'python_logo')
357
358   server.serve_forever()
359
360The client gets the image and saves it to a file::
361
362   import xmlrpclib
363
364   proxy = xmlrpclib.ServerProxy("http://localhost:8000/")
365   with open("fetched_python_logo.jpg", "wb") as handle:
366       handle.write(proxy.python_logo().data)
367
368.. _fault-objects:
369
370Fault Objects
371-------------
372
373.. class:: Fault
374
375   A :class:`Fault` object encapsulates the content of an XML-RPC fault tag. Fault
376   objects have the following attributes:
377
378
379   .. attribute:: faultCode
380
381      A string indicating the fault type.
382
383
384   .. attribute:: faultString
385
386      A string containing a diagnostic message associated with the fault.
387
388In the following example we're going to intentionally cause a :exc:`Fault` by
389returning a complex type object.  The server code::
390
391   from SimpleXMLRPCServer import SimpleXMLRPCServer
392
393   # A marshalling error is going to occur because we're returning a
394   # complex number
395   def add(x, y):
396       return x+y+0j
397
398   server = SimpleXMLRPCServer(("localhost", 8000))
399   print "Listening on port 8000..."
400   server.register_function(add, 'add')
401
402   server.serve_forever()
403
404The client code for the preceding server::
405
406   import xmlrpclib
407
408   proxy = xmlrpclib.ServerProxy("http://localhost:8000/")
409   try:
410       proxy.add(2, 5)
411   except xmlrpclib.Fault as err:
412       print "A fault occurred"
413       print "Fault code: %d" % err.faultCode
414       print "Fault string: %s" % err.faultString
415
416
417
418.. _protocol-error-objects:
419
420ProtocolError Objects
421---------------------
422
423.. class:: ProtocolError
424
425   A :class:`ProtocolError` object describes a protocol error in the underlying
426   transport layer (such as a 404 'not found' error if the server named by the URI
427   does not exist).  It has the following attributes:
428
429
430   .. attribute:: url
431
432      The URI or URL that triggered the error.
433
434
435   .. attribute:: errcode
436
437      The error code.
438
439
440   .. attribute:: errmsg
441
442      The error message or diagnostic string.
443
444
445   .. attribute:: headers
446
447      A string containing the headers of the HTTP/HTTPS request that triggered the
448      error.
449
450In the following example we're going to intentionally cause a :exc:`ProtocolError`
451by providing a URI that doesn't point to an XMLRPC server::
452
453   import xmlrpclib
454
455   # create a ServerProxy with a URI that doesn't respond to XMLRPC requests
456   proxy = xmlrpclib.ServerProxy("http://www.google.com/")
457
458   try:
459       proxy.some_method()
460   except xmlrpclib.ProtocolError as err:
461       print "A protocol error occurred"
462       print "URL: %s" % err.url
463       print "HTTP/HTTPS headers: %s" % err.headers
464       print "Error code: %d" % err.errcode
465       print "Error message: %s" % err.errmsg
466
467MultiCall Objects
468-----------------
469
470.. versionadded:: 2.4
471
472The :class:`MultiCall` object provides a way to encapsulate multiple calls to a
473remote server into a single request [#]_.
474
475
476.. class:: MultiCall(server)
477
478   Create an object used to boxcar method calls. *server* is the eventual target of
479   the call. Calls can be made to the result object, but they will immediately
480   return ``None``, and only store the call name and parameters in the
481   :class:`MultiCall` object. Calling the object itself causes all stored calls to
482   be transmitted as a single ``system.multicall`` request. The result of this call
483   is a :term:`generator`; iterating over this generator yields the individual
484   results.
485
486A usage example of this class follows.  The server code ::
487
488   from SimpleXMLRPCServer import SimpleXMLRPCServer
489
490   def add(x,y):
491       return x+y
492
493   def subtract(x, y):
494       return x-y
495
496   def multiply(x, y):
497       return x*y
498
499   def divide(x, y):
500       return x/y
501
502   # A simple server with simple arithmetic functions
503   server = SimpleXMLRPCServer(("localhost", 8000))
504   print "Listening on port 8000..."
505   server.register_multicall_functions()
506   server.register_function(add, 'add')
507   server.register_function(subtract, 'subtract')
508   server.register_function(multiply, 'multiply')
509   server.register_function(divide, 'divide')
510   server.serve_forever()
511
512The client code for the preceding server::
513
514   import xmlrpclib
515
516   proxy = xmlrpclib.ServerProxy("http://localhost:8000/")
517   multicall = xmlrpclib.MultiCall(proxy)
518   multicall.add(7,3)
519   multicall.subtract(7,3)
520   multicall.multiply(7,3)
521   multicall.divide(7,3)
522   result = multicall()
523
524   print "7+3=%d, 7-3=%d, 7*3=%d, 7/3=%d" % tuple(result)
525
526
527Convenience Functions
528---------------------
529
530
531.. function:: boolean(value)
532
533   Convert any Python value to one of the XML-RPC Boolean constants, ``True`` or
534   ``False``.
535
536
537.. function:: dumps(params[, methodname[,  methodresponse[, encoding[, allow_none]]]])
538
539   Convert *params* into an XML-RPC request. or into a response if *methodresponse*
540   is true. *params* can be either a tuple of arguments or an instance of the
541   :exc:`Fault` exception class.  If *methodresponse* is true, only a single value
542   can be returned, meaning that *params* must be of length 1. *encoding*, if
543   supplied, is the encoding to use in the generated XML; the default is UTF-8.
544   Python's :const:`None` value cannot be used in standard XML-RPC; to allow using
545   it via an extension,  provide a true value for *allow_none*.
546
547
548.. function:: loads(data[, use_datetime])
549
550   Convert an XML-RPC request or response into Python objects, a ``(params,
551   methodname)``.  *params* is a tuple of argument; *methodname* is a string, or
552   ``None`` if no method name is present in the packet. If the XML-RPC packet
553   represents a fault condition, this function will raise a :exc:`Fault` exception.
554   The *use_datetime* flag can be used to cause date/time values to be presented as
555   :class:`datetime.datetime` objects; this is false by default.
556
557   .. versionchanged:: 2.5
558      The *use_datetime* flag was added.
559
560
561.. _xmlrpc-client-example:
562
563Example of Client Usage
564-----------------------
565
566::
567
568   # simple test program (from the XML-RPC specification)
569   from xmlrpclib import ServerProxy, Error
570
571   # server = ServerProxy("http://localhost:8000") # local server
572   server = ServerProxy("http://betty.userland.com")
573
574   print server
575
576   try:
577       print server.examples.getStateName(41)
578   except Error as v:
579       print "ERROR", v
580
581To access an XML-RPC server through a HTTP proxy, you need to define a custom
582transport.  The following example shows how:
583
584.. Example taken from http://lowlife.jp/nobonobo/wiki/xmlrpcwithproxy.html
585
586::
587
588   import xmlrpclib, httplib
589
590   class ProxiedTransport(xmlrpclib.Transport):
591       def set_proxy(self, proxy):
592           self.proxy = proxy
593
594       def make_connection(self, host):
595           self.realhost = host
596           h = httplib.HTTPConnection(self.proxy)
597           return h
598
599       def send_request(self, connection, handler, request_body):
600           connection.putrequest("POST", 'http://%s%s' % (self.realhost, handler))
601
602       def send_host(self, connection, host):
603           connection.putheader('Host', self.realhost)
604
605   p = ProxiedTransport()
606   p.set_proxy('proxy-server:8080')
607   server = xmlrpclib.ServerProxy('http://time.xmlrpc.com/RPC2', transport=p)
608   print server.currentTime.getCurrentTime()
609
610
611Example of Client and Server Usage
612----------------------------------
613
614See :ref:`simplexmlrpcserver-example`.
615
616
617.. rubric:: Footnotes
618
619.. [#] This approach has been first presented in `a discussion on xmlrpc.com
620   <https://web.archive.org/web/20060624230303/http://www.xmlrpc.com/discuss/msgReader$1208?mode=topic>`_.
621.. the link now points to webarchive since the one at
622.. http://www.xmlrpc.com/discuss/msgReader%241208 is broken (and webadmin
623.. doesn't reply)
624