1:mod:`xmlrpc.client` --- XML-RPC client access
2==============================================
3
4.. module:: xmlrpc.client
5   :synopsis: XML-RPC client access.
6
7.. moduleauthor:: Fredrik Lundh <fredrik@pythonware.com>
8.. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
9
10**Source code:** :source:`Lib/xmlrpc/client.py`
11
12.. XXX Not everything is documented yet.  It might be good to describe
13   Marshaller, Unmarshaller, getparser and Transport.
14
15--------------
16
17XML-RPC is a Remote Procedure Call method that uses XML passed via HTTP(S) as a
18transport.  With it, a client can call methods with parameters on a remote
19server (the server is named by a URI) and get back structured data.  This module
20supports writing XML-RPC client code; it handles all the details of translating
21between conformable Python objects and XML on the wire.
22
23
24.. warning::
25
26   The :mod:`xmlrpc.client` module is not secure against maliciously
27   constructed data.  If you need to parse untrusted or unauthenticated data see
28   :ref:`xml-vulnerabilities`.
29
30.. versionchanged:: 3.5
31
32   For HTTPS URIs, :mod:`xmlrpc.client` now performs all the necessary
33   certificate and hostname checks by default.
34
35.. class:: ServerProxy(uri, transport=None, encoding=None, verbose=False, \
36                       allow_none=False, use_datetime=False, \
37                       use_builtin_types=False, *, headers=(), context=None)
38
39   A :class:`ServerProxy` instance is an object that manages communication with a
40   remote XML-RPC server.  The required first argument is a URI (Uniform Resource
41   Indicator), and will normally be the URL of the server.  The optional second
42   argument is a transport factory instance; by default it is an internal
43   :class:`SafeTransport` instance for https: URLs and an internal HTTP
44   :class:`Transport` instance otherwise.  The optional third argument is an
45   encoding, by default UTF-8. The optional fourth argument is a debugging flag.
46
47   The following parameters govern the use of the returned proxy instance.
48   If *allow_none* is true,  the Python constant ``None`` will be translated into
49   XML; the default behaviour is for ``None`` to raise a :exc:`TypeError`. This is
50   a commonly-used extension to the XML-RPC specification, but isn't supported by
51   all clients and servers; see `http://ontosys.com/xml-rpc/extensions.php
52   <https://web.archive.org/web/20130120074804/http://ontosys.com/xml-rpc/extensions.php>`_
53   for a description.
54   The *use_builtin_types* flag can be used to cause date/time values
55   to be presented as :class:`datetime.datetime` objects and binary data to be
56   presented as :class:`bytes` objects; this flag is false by default.
57   :class:`datetime.datetime`, :class:`bytes` and :class:`bytearray` objects
58   may be passed to calls.
59   The *headers* parameter is an optional sequence of HTTP headers to send with
60   each request, expressed as a sequence of 2-tuples representing the header
61   name and value. (e.g. `[('Header-Name', 'value')]`).
62   The obsolete *use_datetime* flag is similar to *use_builtin_types* but it
63   applies only to date/time values.
64
65.. versionchanged:: 3.3
66    The *use_builtin_types* flag was added.
67
68.. versionchanged:: 3.8
69    The *headers* parameter was added.
70
71   Both the HTTP and HTTPS transports support the URL syntax extension for HTTP
72   Basic Authentication: ``http://user:pass@host:port/path``.  The  ``user:pass``
73   portion will be base64-encoded as an HTTP 'Authorization' header, and sent to
74   the remote server as part of the connection process when invoking an XML-RPC
75   method.  You only need to use this if the remote server requires a Basic
76   Authentication user and password. If an HTTPS URL is provided, *context* may
77   be :class:`ssl.SSLContext` and configures the SSL settings of the underlying
78   HTTPS connection.
79
80   The returned instance is a proxy object with methods that can be used to invoke
81   corresponding RPC calls on the remote server.  If the remote server supports the
82   introspection API, the proxy can also be used to query the remote server for the
83   methods it supports (service discovery) and fetch other server-associated
84   metadata.
85
86   Types that are conformable (e.g. that can be marshalled through XML),
87   include the following (and except where noted, they are unmarshalled
88   as the same Python type):
89
90   .. tabularcolumns:: |l|L|
91
92   +----------------------+-------------------------------------------------------+
93   | XML-RPC type         | Python type                                           |
94   +======================+=======================================================+
95   | ``boolean``          | :class:`bool`                                         |
96   +----------------------+-------------------------------------------------------+
97   | ``int``, ``i1``,     | :class:`int` in range from -2147483648 to 2147483647. |
98   | ``i2``,  ``i4``,     | Values get the ``<int>`` tag.                         |
99   | ``i8`` or            |                                                       |
100   | ``biginteger``       |                                                       |
101   +----------------------+-------------------------------------------------------+
102   | ``double`` or        | :class:`float`.  Values get the ``<double>`` tag.     |
103   | ``float``            |                                                       |
104   +----------------------+-------------------------------------------------------+
105   | ``string``           | :class:`str`                                          |
106   +----------------------+-------------------------------------------------------+
107   | ``array``            | :class:`list` or :class:`tuple` containing            |
108   |                      | conformable elements.  Arrays are returned as         |
109   |                      | :class:`lists <list>`.                                |
110   +----------------------+-------------------------------------------------------+
111   | ``struct``           | :class:`dict`.  Keys must be strings, values may be   |
112   |                      | any conformable type.  Objects of user-defined        |
113   |                      | classes can be passed in; only their                  |
114   |                      | :attr:`~object.__dict__` attribute is transmitted.    |
115   +----------------------+-------------------------------------------------------+
116   | ``dateTime.iso8601`` | :class:`DateTime` or :class:`datetime.datetime`.      |
117   |                      | Returned type depends on values of                    |
118   |                      | *use_builtin_types* and *use_datetime* flags.         |
119   +----------------------+-------------------------------------------------------+
120   | ``base64``           | :class:`Binary`, :class:`bytes` or                    |
121   |                      | :class:`bytearray`.  Returned type depends on the     |
122   |                      | value of the *use_builtin_types* flag.                |
123   +----------------------+-------------------------------------------------------+
124   | ``nil``              | The ``None`` constant.  Passing is allowed only if    |
125   |                      | *allow_none* is true.                                 |
126   +----------------------+-------------------------------------------------------+
127   | ``bigdecimal``       | :class:`decimal.Decimal`.  Returned type only.        |
128   +----------------------+-------------------------------------------------------+
129
130   This is the full set of data types supported by XML-RPC.  Method calls may also
131   raise a special :exc:`Fault` instance, used to signal XML-RPC server errors, or
132   :exc:`ProtocolError` used to signal an error in the HTTP/HTTPS transport layer.
133   Both :exc:`Fault` and :exc:`ProtocolError` derive from a base class called
134   :exc:`Error`.  Note that the xmlrpc client module currently does not marshal
135   instances of subclasses of built-in types.
136
137   When passing strings, characters special to XML such as ``<``, ``>``, and ``&``
138   will be automatically escaped.  However, it's the caller's responsibility to
139   ensure that the string is free of characters that aren't allowed in XML, such as
140   the control characters with ASCII values between 0 and 31 (except, of course,
141   tab, newline and carriage return); failing to do this will result in an XML-RPC
142   request that isn't well-formed XML.  If you have to pass arbitrary bytes
143   via XML-RPC, use :class:`bytes` or :class:`bytearray` classes or the
144   :class:`Binary` wrapper class described below.
145
146   :class:`Server` is retained as an alias for :class:`ServerProxy` for backwards
147   compatibility.  New code should use :class:`ServerProxy`.
148
149   .. versionchanged:: 3.5
150      Added the *context* argument.
151
152   .. versionchanged:: 3.6
153      Added support of type tags with prefixes (e.g. ``ex:nil``).
154      Added support of unmarshalling additional types used by Apache XML-RPC
155      implementation for numerics: ``i1``, ``i2``, ``i8``, ``biginteger``,
156      ``float`` and ``bigdecimal``.
157      See http://ws.apache.org/xmlrpc/types.html for a description.
158
159
160.. seealso::
161
162   `XML-RPC HOWTO <http://www.tldp.org/HOWTO/XML-RPC-HOWTO/index.html>`_
163      A good description of XML-RPC operation and client software in several languages.
164      Contains pretty much everything an XML-RPC client developer needs to know.
165
166   `XML-RPC Introspection <http://xmlrpc-c.sourceforge.net/introspection.html>`_
167      Describes the XML-RPC protocol extension for introspection.
168
169   `XML-RPC Specification <http://xmlrpc.scripting.com/spec.html>`_
170      The official specification.
171
172   `Unofficial XML-RPC Errata <http://effbot.org/zone/xmlrpc-errata.htm>`_
173      Fredrik Lundh's "unofficial errata, intended to clarify certain
174      details in the XML-RPC specification, as well as hint at
175      'best practices' to use when designing your own XML-RPC
176      implementations."
177
178.. _serverproxy-objects:
179
180ServerProxy Objects
181-------------------
182
183A :class:`ServerProxy` instance has a method corresponding to each remote
184procedure call accepted by the XML-RPC server.  Calling the method performs an
185RPC, dispatched by both name and argument signature (e.g. the same method name
186can be overloaded with multiple argument signatures).  The RPC finishes by
187returning a value, which may be either returned data in a conformant type or a
188:class:`Fault` or :class:`ProtocolError` object indicating an error.
189
190Servers that support the XML introspection API support some common methods
191grouped under the reserved :attr:`~ServerProxy.system` attribute:
192
193
194.. method:: ServerProxy.system.listMethods()
195
196   This method returns a list of strings, one for each (non-system) method
197   supported by the XML-RPC server.
198
199
200.. method:: ServerProxy.system.methodSignature(name)
201
202   This method takes one parameter, the name of a method implemented by the XML-RPC
203   server. It returns an array of possible signatures for this method. A signature
204   is an array of types. The first of these types is the return type of the method,
205   the rest are parameters.
206
207   Because multiple signatures (ie. overloading) is permitted, this method returns
208   a list of signatures rather than a singleton.
209
210   Signatures themselves are restricted to the top level parameters expected by a
211   method. For instance if a method expects one array of structs as a parameter,
212   and it returns a string, its signature is simply "string, array". If it expects
213   three integers and returns a string, its signature is "string, int, int, int".
214
215   If no signature is defined for the method, a non-array value is returned. In
216   Python this means that the type of the returned  value will be something other
217   than list.
218
219
220.. method:: ServerProxy.system.methodHelp(name)
221
222   This method takes one parameter, the name of a method implemented by the XML-RPC
223   server.  It returns a documentation string describing the use of that method. If
224   no such string is available, an empty string is returned. The documentation
225   string may contain HTML markup.
226
227.. versionchanged:: 3.5
228
229   Instances of :class:`ServerProxy` support the :term:`context manager` protocol
230   for closing the underlying transport.
231
232
233A working example follows. The server code::
234
235   from xmlrpc.server 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 xmlrpc.client
248
249   with xmlrpc.client.ServerProxy("http://localhost:8000/") as proxy:
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 rich comparison
277   and :meth:`__repr__` methods.
278
279A working example follows. The server code::
280
281   import datetime
282   from xmlrpc.server import SimpleXMLRPCServer
283   import xmlrpc.client
284
285   def today():
286       today = datetime.datetime.today()
287       return xmlrpc.client.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 xmlrpc.client
297   import datetime
298
299   proxy = xmlrpc.client.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 bytes 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 a :class:`bytes` object.
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(bytes)
328
329      Accept a base64 :class:`bytes` object 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:`RFC 2045 section 6.8 <2045#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 :meth:`__eq__`
342   and :meth:`__ne__` methods.
343
344Example usage of the binary objects.  We're going to transfer an image over
345XMLRPC::
346
347   from xmlrpc.server import SimpleXMLRPCServer
348   import xmlrpc.client
349
350   def python_logo():
351       with open("python_logo.jpg", "rb") as handle:
352           return xmlrpc.client.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 xmlrpc.client
363
364   proxy = xmlrpc.client.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      An int 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 xmlrpc.server 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 xmlrpc.client
407
408   proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")
409   try:
410       proxy.add(2, 5)
411   except xmlrpc.client.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 dict 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 an invalid URI::
452
453   import xmlrpc.client
454
455   # create a ServerProxy with a URI that doesn't respond to XMLRPC requests
456   proxy = xmlrpc.client.ServerProxy("http://google.com/")
457
458   try:
459       proxy.some_method()
460   except xmlrpc.client.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
470The :class:`MultiCall` object provides a way to encapsulate multiple calls to a
471remote server into a single request [#]_.
472
473
474.. class:: MultiCall(server)
475
476   Create an object used to boxcar method calls. *server* is the eventual target of
477   the call. Calls can be made to the result object, but they will immediately
478   return ``None``, and only store the call name and parameters in the
479   :class:`MultiCall` object. Calling the object itself causes all stored calls to
480   be transmitted as a single ``system.multicall`` request. The result of this call
481   is a :term:`generator`; iterating over this generator yields the individual
482   results.
483
484A usage example of this class follows.  The server code::
485
486   from xmlrpc.server import SimpleXMLRPCServer
487
488   def add(x, y):
489       return x + y
490
491   def subtract(x, y):
492       return x - y
493
494   def multiply(x, y):
495       return x * y
496
497   def divide(x, y):
498       return x // y
499
500   # A simple server with simple arithmetic functions
501   server = SimpleXMLRPCServer(("localhost", 8000))
502   print("Listening on port 8000...")
503   server.register_multicall_functions()
504   server.register_function(add, 'add')
505   server.register_function(subtract, 'subtract')
506   server.register_function(multiply, 'multiply')
507   server.register_function(divide, 'divide')
508   server.serve_forever()
509
510The client code for the preceding server::
511
512   import xmlrpc.client
513
514   proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")
515   multicall = xmlrpc.client.MultiCall(proxy)
516   multicall.add(7, 3)
517   multicall.subtract(7, 3)
518   multicall.multiply(7, 3)
519   multicall.divide(7, 3)
520   result = multicall()
521
522   print("7+3=%d, 7-3=%d, 7*3=%d, 7//3=%d" % tuple(result))
523
524
525Convenience Functions
526---------------------
527
528.. function:: dumps(params, methodname=None, methodresponse=None, encoding=None, allow_none=False)
529
530   Convert *params* into an XML-RPC request. or into a response if *methodresponse*
531   is true. *params* can be either a tuple of arguments or an instance of the
532   :exc:`Fault` exception class.  If *methodresponse* is true, only a single value
533   can be returned, meaning that *params* must be of length 1. *encoding*, if
534   supplied, is the encoding to use in the generated XML; the default is UTF-8.
535   Python's :const:`None` value cannot be used in standard XML-RPC; to allow using
536   it via an extension,  provide a true value for *allow_none*.
537
538
539.. function:: loads(data, use_datetime=False, use_builtin_types=False)
540
541   Convert an XML-RPC request or response into Python objects, a ``(params,
542   methodname)``.  *params* is a tuple of argument; *methodname* is a string, or
543   ``None`` if no method name is present in the packet. If the XML-RPC packet
544   represents a fault condition, this function will raise a :exc:`Fault` exception.
545   The *use_builtin_types* flag can be used to cause date/time values to be
546   presented as :class:`datetime.datetime` objects and binary data to be
547   presented as :class:`bytes` objects; this flag is false by default.
548
549   The obsolete *use_datetime* flag is similar to *use_builtin_types* but it
550   applies only to date/time values.
551
552   .. versionchanged:: 3.3
553      The *use_builtin_types* flag was added.
554
555
556.. _xmlrpc-client-example:
557
558Example of Client Usage
559-----------------------
560
561::
562
563   # simple test program (from the XML-RPC specification)
564   from xmlrpc.client import ServerProxy, Error
565
566   # server = ServerProxy("http://localhost:8000") # local server
567   with ServerProxy("http://betty.userland.com") as proxy:
568
569       print(proxy)
570
571       try:
572           print(proxy.examples.getStateName(41))
573       except Error as v:
574           print("ERROR", v)
575
576To access an XML-RPC server through a HTTP proxy, you need to define a custom
577transport.  The following example shows how::
578
579   import http.client
580   import xmlrpc.client
581
582   class ProxiedTransport(xmlrpc.client.Transport):
583
584       def set_proxy(self, host, port=None, headers=None):
585           self.proxy = host, port
586           self.proxy_headers = headers
587
588       def make_connection(self, host):
589           connection = http.client.HTTPConnection(*self.proxy)
590           connection.set_tunnel(host, headers=self.proxy_headers)
591           self._connection = host, connection
592           return connection
593
594   transport = ProxiedTransport()
595   transport.set_proxy('proxy-server', 8080)
596   server = xmlrpc.client.ServerProxy('http://betty.userland.com', transport=transport)
597   print(server.examples.getStateName(41))
598
599
600Example of Client and Server Usage
601----------------------------------
602
603See :ref:`simplexmlrpcserver-example`.
604
605
606.. rubric:: Footnotes
607
608.. [#] This approach has been first presented in `a discussion on xmlrpc.com
609   <https://web.archive.org/web/20060624230303/http://www.xmlrpc.com/discuss/msgReader$1208?mode=topic>`_.
610.. the link now points to webarchive since the one at
611.. http://www.xmlrpc.com/discuss/msgReader%241208 is broken (and webadmin
612.. doesn't reply)
613