xmlrpc.client.rst 22.6 KB
Newer Older
1 2
:mod:`xmlrpc.client` --- XML-RPC client access
==============================================
3

4
.. module:: xmlrpc.client
5
   :synopsis: XML-RPC client access.
6

7 8 9
.. moduleauthor:: Fredrik Lundh <fredrik@pythonware.com>
.. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>

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
--------------

17
XML-RPC is a Remote Procedure Call method that uses XML passed via HTTP(S) as a
18 19 20 21 22 23
transport.  With it, a client can call methods with parameters on a remote
server (the server is named by a URI) and get back structured data.  This module
supports writing XML-RPC client code; it handles all the details of translating
between conformable Python objects and XML on the wire.


24 25 26 27 28 29
.. warning::

   The :mod:`xmlrpc.client` module is not secure against maliciously
   constructed data.  If you need to parse untrusted or unauthenticated data see
   :ref:`xml-vulnerabilities`.

Benjamin Peterson's avatar
Benjamin Peterson committed
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 36
.. class:: ServerProxy(uri, transport=None, encoding=None, verbose=False, \
                       allow_none=False, use_datetime=False, \
37
                       use_builtin_types=False, *, context=None)
38 39 40

   .. versionchanged:: 3.3
      The *use_builtin_types* flag was added.
41 42 43 44 45 46 47 48

   A :class:`ServerProxy` instance is an object that manages communication with a
   remote XML-RPC server.  The required first argument is a URI (Uniform Resource
   Indicator), and will normally be the URL of the server.  The optional second
   argument is a transport factory instance; by default it is an internal
   :class:`SafeTransport` instance for https: URLs and an internal HTTP
   :class:`Transport` instance otherwise.  The optional third argument is an
   encoding, by default UTF-8. The optional fourth argument is a debugging flag.
49 50

   The following parameters govern the use of the returned proxy instance.
51 52 53
   If *allow_none* is true,  the Python constant ``None`` will be translated into
   XML; the default behaviour is for ``None`` to raise a :exc:`TypeError`. This is
   a commonly-used extension to the XML-RPC specification, but isn't supported by
54
   all clients and servers; see `http://ontosys.com/xml-rpc/extensions.php
55
   <https://web.archive.org/web/20130120074804/http://ontosys.com/xml-rpc/extensions.php>`_
56 57
   for a description.
   The *use_builtin_types* flag can be used to cause date/time values
58 59
   to be presented as :class:`datetime.datetime` objects and binary data to be
   presented as :class:`bytes` objects; this flag is false by default.
60 61
   :class:`datetime.datetime`, :class:`bytes` and :class:`bytearray` objects
   may be passed to calls.
62 63
   The obsolete *use_datetime* flag is similar to *use_builtin_types* but it
   applies only to date/time values.
64 65 66 67 68 69

   Both the HTTP and HTTPS transports support the URL syntax extension for HTTP
   Basic Authentication: ``http://user:pass@host:port/path``.  The  ``user:pass``
   portion will be base64-encoded as an HTTP 'Authorization' header, and sent to
   the remote server as part of the connection process when invoking an XML-RPC
   method.  You only need to use this if the remote server requires a Basic
70
   Authentication user and password. If an HTTPS URL is provided, *context* may
71 72
   be :class:`ssl.SSLContext` and configures the SSL settings of the underlying
   HTTPS connection.
73 74 75 76 77 78 79

   The returned instance is a proxy object with methods that can be used to invoke
   corresponding RPC calls on the remote server.  If the remote server supports the
   introspection API, the proxy can also be used to query the remote server for the
   methods it supports (service discovery) and fetch other server-associated
   metadata.

80 81 82
   Types that are conformable (e.g. that can be marshalled through XML),
   include the following (and except where noted, they are unmarshalled
   as the same Python type):
83

84 85
   .. tabularcolumns:: |l|L|

86 87 88 89 90
   +----------------------+-------------------------------------------------------+
   | XML-RPC type         | Python type                                           |
   +======================+=======================================================+
   | ``boolean``          | :class:`bool`                                         |
   +----------------------+-------------------------------------------------------+
91 92 93 94
   | ``int``, ``i1``,     | :class:`int` in range from -2147483648 to 2147483647. |
   | ``i2``,  ``i4``,     | Values get the ``<int>`` tag.                         |
   | ``i8`` or            |                                                       |
   | ``biginteger``       |                                                       |
95
   +----------------------+-------------------------------------------------------+
96 97
   | ``double`` or        | :class:`float`.  Values get the ``<double>`` tag.     |
   | ``float``            |                                                       |
98 99 100 101 102
   +----------------------+-------------------------------------------------------+
   | ``string``           | :class:`str`                                          |
   +----------------------+-------------------------------------------------------+
   | ``array``            | :class:`list` or :class:`tuple` containing            |
   |                      | conformable elements.  Arrays are returned as         |
103
   |                      | :class:`lists <list>`.                                |
104 105 106
   +----------------------+-------------------------------------------------------+
   | ``struct``           | :class:`dict`.  Keys must be strings, values may be   |
   |                      | any conformable type.  Objects of user-defined        |
107 108
   |                      | classes can be passed in; only their                  |
   |                      | :attr:`~object.__dict__` attribute is transmitted.    |
109 110 111 112 113 114 115 116 117 118 119 120
   +----------------------+-------------------------------------------------------+
   | ``dateTime.iso8601`` | :class:`DateTime` or :class:`datetime.datetime`.      |
   |                      | Returned type depends on values of                    |
   |                      | *use_builtin_types* and *use_datetime* flags.         |
   +----------------------+-------------------------------------------------------+
   | ``base64``           | :class:`Binary`, :class:`bytes` or                    |
   |                      | :class:`bytearray`.  Returned type depends on the     |
   |                      | value of the *use_builtin_types* flag.                |
   +----------------------+-------------------------------------------------------+
   | ``nil``              | The ``None`` constant.  Passing is allowed only if    |
   |                      | *allow_none* is true.                                 |
   +----------------------+-------------------------------------------------------+
121 122
   | ``bigdecimal``       | :class:`decimal.Decimal`.  Returned type only.        |
   +----------------------+-------------------------------------------------------+
123 124 125 126 127

   This is the full set of data types supported by XML-RPC.  Method calls may also
   raise a special :exc:`Fault` instance, used to signal XML-RPC server errors, or
   :exc:`ProtocolError` used to signal an error in the HTTP/HTTPS transport layer.
   Both :exc:`Fault` and :exc:`ProtocolError` derive from a base class called
128
   :exc:`Error`.  Note that the xmlrpc client module currently does not marshal
129
   instances of subclasses of built-in types.
130 131 132 133 134 135

   When passing strings, characters special to XML such as ``<``, ``>``, and ``&``
   will be automatically escaped.  However, it's the caller's responsibility to
   ensure that the string is free of characters that aren't allowed in XML, such as
   the control characters with ASCII values between 0 and 31 (except, of course,
   tab, newline and carriage return); failing to do this will result in an XML-RPC
136
   request that isn't well-formed XML.  If you have to pass arbitrary bytes
137 138
   via XML-RPC, use :class:`bytes` or :class:`bytearray` classes or the
   :class:`Binary` wrapper class described below.
139 140 141 142

   :class:`Server` is retained as an alias for :class:`ServerProxy` for backwards
   compatibility.  New code should use :class:`ServerProxy`.

Benjamin Peterson's avatar
Benjamin Peterson committed
143
   .. versionchanged:: 3.5
144 145
      Added the *context* argument.

146
   .. versionchanged:: 3.6
147
      Added support of type tags with prefixes (e.g. ``ex:nil``).
148 149 150 151 152
      Added support of unmarsalling additional types used by Apache XML-RPC
      implementation for numerics: ``i1``, ``i2``, ``i8``, ``biginteger``,
      ``float`` and ``bigdecimal``.
      See http://ws.apache.org/xmlrpc/types.html for a description.

153 154 155 156

.. seealso::

   `XML-RPC HOWTO <http://www.tldp.org/HOWTO/XML-RPC-HOWTO/index.html>`_
157
      A good description of XML-RPC operation and client software in several languages.
158 159
      Contains pretty much everything an XML-RPC client developer needs to know.

160 161
   `XML-RPC Introspection <http://xmlrpc-c.sourceforge.net/introspection.html>`_
      Describes the XML-RPC protocol extension for introspection.
162

163
   `XML-RPC Specification <http://xmlrpc.scripting.com/spec.html>`_
Christian Heimes's avatar
Christian Heimes committed
164 165 166 167 168 169 170
      The official specification.

   `Unofficial XML-RPC Errata <http://effbot.org/zone/xmlrpc-errata.htm>`_
      Fredrik Lundh's "unofficial errata, intended to clarify certain
      details in the XML-RPC specification, as well as hint at
      'best practices' to use when designing your own XML-RPC
      implementations."
171 172 173 174 175 176 177 178 179 180 181 182 183 184

.. _serverproxy-objects:

ServerProxy Objects
-------------------

A :class:`ServerProxy` instance has a method corresponding to each remote
procedure call accepted by the XML-RPC server.  Calling the method performs an
RPC, dispatched by both name and argument signature (e.g. the same method name
can be overloaded with multiple argument signatures).  The RPC finishes by
returning a value, which may be either returned data in a conformant type or a
:class:`Fault` or :class:`ProtocolError` object indicating an error.

Servers that support the XML introspection API support some common methods
185
grouped under the reserved :attr:`~ServerProxy.system` attribute:
186 187 188 189 190 191 192 193 194 195 196


.. method:: ServerProxy.system.listMethods()

   This method returns a list of strings, one for each (non-system) method
   supported by the XML-RPC server.


.. method:: ServerProxy.system.methodSignature(name)

   This method takes one parameter, the name of a method implemented by the XML-RPC
197
   server. It returns an array of possible signatures for this method. A signature
198 199 200 201 202 203 204 205 206 207 208 209 210
   is an array of types. The first of these types is the return type of the method,
   the rest are parameters.

   Because multiple signatures (ie. overloading) is permitted, this method returns
   a list of signatures rather than a singleton.

   Signatures themselves are restricted to the top level parameters expected by a
   method. For instance if a method expects one array of structs as a parameter,
   and it returns a string, its signature is simply "string, array". If it expects
   three integers and returns a string, its signature is "string, int, int, int".

   If no signature is defined for the method, a non-array value is returned. In
   Python this means that the type of the returned  value will be something other
211
   than list.
212 213 214 215 216 217 218 219 220


.. method:: ServerProxy.system.methodHelp(name)

   This method takes one parameter, the name of a method implemented by the XML-RPC
   server.  It returns a documentation string describing the use of that method. If
   no such string is available, an empty string is returned. The documentation
   string may contain HTML markup.

221 222 223 224 225
.. versionchanged:: 3.5

   Instances of :class:`ServerProxy` support the :term:`context manager` protocol
   for closing the underlying transport.

226

227 228
A working example follows. The server code::

229
   from xmlrpc.server import SimpleXMLRPCServer
230 231

   def is_even(n):
232
       return n % 2 == 0
233 234

   server = SimpleXMLRPCServer(("localhost", 8000))
235
   print("Listening on port 8000...")
236 237 238 239 240
   server.register_function(is_even, "is_even")
   server.serve_forever()

The client code for the preceding server::

241
   import xmlrpc.client
242

243 244 245
   with xmlrpc.client.ServerProxy("http://localhost:8000/") as proxy:
       print("3 is even: %s" % str(proxy.is_even(3)))
       print("100 is even: %s" % str(proxy.is_even(100)))
246 247 248 249 250 251

.. _datetime-objects:

DateTime Objects
----------------

252 253 254 255 256 257
.. class:: DateTime

   This class may be initialized with seconds since the epoch, a time
   tuple, an ISO 8601 time/date string, or a :class:`datetime.datetime`
   instance.  It has the following methods, supported mainly for internal
   use by the marshalling/unmarshalling code:
258 259


260
   .. method:: decode(string)
261

262
      Accept a string as the instance's new time value.
263 264


265
   .. method:: encode(out)
266

267 268
      Write the XML-RPC encoding of this :class:`DateTime` item to the *out* stream
      object.
269

270 271
   It also supports certain of Python's built-in operators through rich comparison
   and :meth:`__repr__` methods.
272

273 274 275
A working example follows. The server code::

   import datetime
276 277
   from xmlrpc.server import SimpleXMLRPCServer
   import xmlrpc.client
278 279 280

   def today():
       today = datetime.datetime.today()
281
       return xmlrpc.client.DateTime(today)
282 283

   server = SimpleXMLRPCServer(("localhost", 8000))
284
   print("Listening on port 8000...")
285 286 287 288 289
   server.register_function(today, "today")
   server.serve_forever()

The client code for the preceding server::

290
   import xmlrpc.client
291 292
   import datetime

293
   proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")
294 295 296 297

   today = proxy.today()
   # convert the ISO8601 string to a datetime object
   converted = datetime.datetime.strptime(today.value, "%Y%m%dT%H:%M:%S")
298
   print("Today: %s" % converted.strftime("%d.%m.%Y, %H:%M"))
299 300 301 302 303 304

.. _binary-objects:

Binary Objects
--------------

305
.. class:: Binary
306

307 308 309
   This class may be initialized from bytes data (which may include NULs). The
   primary access to the content of a :class:`Binary` object is provided by an
   attribute:
310 311


312
   .. attribute:: data
313

314 315
      The binary data encapsulated by the :class:`Binary` instance.  The data is
      provided as a :class:`bytes` object.
316

317 318
   :class:`Binary` objects have the following methods, supported mainly for
   internal use by the marshalling/unmarshalling code:
319 320


321
   .. method:: decode(bytes)
322

323
      Accept a base64 :class:`bytes` object and decode it as the instance's new data.
324 325


326
   .. method:: encode(out)
327

328
      Write the XML-RPC base 64 encoding of this binary item to the *out* stream object.
Christian Heimes's avatar
Christian Heimes committed
329

330
      The encoded data will have newlines every 76 characters as per
331
      `RFC 2045 section 6.8 <https://tools.ietf.org/html/rfc2045#section-6.8>`_,
332 333 334 335 336
      which was the de facto standard base64 specification when the
      XML-RPC spec was written.

   It also supports certain of Python's built-in operators through :meth:`__eq__`
   and :meth:`__ne__` methods.
337

338 339 340
Example usage of the binary objects.  We're going to transfer an image over
XMLRPC::

341 342
   from xmlrpc.server import SimpleXMLRPCServer
   import xmlrpc.client
343 344

   def python_logo():
345 346
       with open("python_logo.jpg", "rb") as handle:
           return xmlrpc.client.Binary(handle.read())
347 348

   server = SimpleXMLRPCServer(("localhost", 8000))
349
   print("Listening on port 8000...")
350 351 352 353 354 355
   server.register_function(python_logo, 'python_logo')

   server.serve_forever()

The client gets the image and saves it to a file::

356
   import xmlrpc.client
357

358
   proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")
359 360
   with open("fetched_python_logo.jpg", "wb") as handle:
       handle.write(proxy.python_logo().data)
361 362 363 364 365 366

.. _fault-objects:

Fault Objects
-------------

367 368 369 370
.. class:: Fault

   A :class:`Fault` object encapsulates the content of an XML-RPC fault tag. Fault
   objects have the following attributes:
371 372


373
   .. attribute:: faultCode
374

375
      A string indicating the fault type.
376 377


378
   .. attribute:: faultString
379

380
      A string containing a diagnostic message associated with the fault.
381

382 383 384
In the following example we're going to intentionally cause a :exc:`Fault` by
returning a complex type object.  The server code::

385
   from xmlrpc.server import SimpleXMLRPCServer
386 387 388

   # A marshalling error is going to occur because we're returning a
   # complex number
389
   def add(x, y):
390 391 392
       return x+y+0j

   server = SimpleXMLRPCServer(("localhost", 8000))
393
   print("Listening on port 8000...")
394 395 396 397 398 399
   server.register_function(add, 'add')

   server.serve_forever()

The client code for the preceding server::

400
   import xmlrpc.client
401

402
   proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")
403 404
   try:
       proxy.add(2, 5)
405
   except xmlrpc.client.Fault as err:
Georg Brandl's avatar
Georg Brandl committed
406
       print("A fault occurred")
407 408
       print("Fault code: %d" % err.faultCode)
       print("Fault string: %s" % err.faultString)
409 410


411 412 413 414 415 416

.. _protocol-error-objects:

ProtocolError Objects
---------------------

417 418 419 420 421
.. class:: ProtocolError

   A :class:`ProtocolError` object describes a protocol error in the underlying
   transport layer (such as a 404 'not found' error if the server named by the URI
   does not exist).  It has the following attributes:
422 423


424
   .. attribute:: url
425

426
      The URI or URL that triggered the error.
427 428


429
   .. attribute:: errcode
430

431
      The error code.
432 433


434
   .. attribute:: errmsg
435

436
      The error message or diagnostic string.
437 438


439
   .. attribute:: headers
440

441 442
      A dict containing the headers of the HTTP/HTTPS request that triggered the
      error.
443

444 445 446
In the following example we're going to intentionally cause a :exc:`ProtocolError`
by providing an invalid URI::

447
   import xmlrpc.client
448

449
   # create a ServerProxy with a URI that doesn't respond to XMLRPC requests
Benjamin Peterson's avatar
Benjamin Peterson committed
450
   proxy = xmlrpc.client.ServerProxy("http://google.com/")
451 452 453

   try:
       proxy.some_method()
454
   except xmlrpc.client.ProtocolError as err:
Georg Brandl's avatar
Georg Brandl committed
455
       print("A protocol error occurred")
456 457 458 459
       print("URL: %s" % err.url)
       print("HTTP/HTTPS headers: %s" % err.headers)
       print("Error code: %d" % err.errcode)
       print("Error message: %s" % err.errmsg)
460 461 462 463

MultiCall Objects
-----------------

464 465
The :class:`MultiCall` object provides a way to encapsulate multiple calls to a
remote server into a single request [#]_.
466 467 468 469 470 471 472 473 474


.. class:: MultiCall(server)

   Create an object used to boxcar method calls. *server* is the eventual target of
   the call. Calls can be made to the result object, but they will immediately
   return ``None``, and only store the call name and parameters in the
   :class:`MultiCall` object. Calling the object itself causes all stored calls to
   be transmitted as a single ``system.multicall`` request. The result of this call
475 476
   is a :term:`generator`; iterating over this generator yields the individual
   results.
477

478
A usage example of this class follows.  The server code::
479

480
   from xmlrpc.server import SimpleXMLRPCServer
481

482 483
   def add(x, y):
       return x + y
484

485
   def subtract(x, y):
486
       return x - y
487 488

   def multiply(x, y):
489
       return x * y
490 491

   def divide(x, y):
492
       return x // y
493 494 495

   # A simple server with simple arithmetic functions
   server = SimpleXMLRPCServer(("localhost", 8000))
496
   print("Listening on port 8000...")
497 498 499 500 501 502 503 504 505
   server.register_multicall_functions()
   server.register_function(add, 'add')
   server.register_function(subtract, 'subtract')
   server.register_function(multiply, 'multiply')
   server.register_function(divide, 'divide')
   server.serve_forever()

The client code for the preceding server::

506
   import xmlrpc.client
507

508 509
   proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")
   multicall = xmlrpc.client.MultiCall(proxy)
510 511 512 513
   multicall.add(7, 3)
   multicall.subtract(7, 3)
   multicall.multiply(7, 3)
   multicall.divide(7, 3)
514 515
   result = multicall()

516
   print("7+3=%d, 7-3=%d, 7*3=%d, 7//3=%d" % tuple(result))
517 518 519 520 521


Convenience Functions
---------------------

522
.. function:: dumps(params, methodname=None, methodresponse=None, encoding=None, allow_none=False)
523 524 525 526 527 528 529 530 531 532

   Convert *params* into an XML-RPC request. or into a response if *methodresponse*
   is true. *params* can be either a tuple of arguments or an instance of the
   :exc:`Fault` exception class.  If *methodresponse* is true, only a single value
   can be returned, meaning that *params* must be of length 1. *encoding*, if
   supplied, is the encoding to use in the generated XML; the default is UTF-8.
   Python's :const:`None` value cannot be used in standard XML-RPC; to allow using
   it via an extension,  provide a true value for *allow_none*.


533
.. function:: loads(data, use_datetime=False, use_builtin_types=False)
534 535 536 537 538

   Convert an XML-RPC request or response into Python objects, a ``(params,
   methodname)``.  *params* is a tuple of argument; *methodname* is a string, or
   ``None`` if no method name is present in the packet. If the XML-RPC packet
   represents a fault condition, this function will raise a :exc:`Fault` exception.
539 540 541 542 543 544 545 546 547
   The *use_builtin_types* flag can be used to cause date/time values to be
   presented as :class:`datetime.datetime` objects and binary data to be
   presented as :class:`bytes` objects; this flag is false by default.

   The obsolete *use_datetime* flag is similar to *use_builtin_types* but it
   applies only to date/time values.

   .. versionchanged:: 3.3
      The *use_builtin_types* flag was added.
548 549 550 551 552 553 554 555 556 557


.. _xmlrpc-client-example:

Example of Client Usage
-----------------------

::

   # simple test program (from the XML-RPC specification)
558
   from xmlrpc.client import ServerProxy, Error
559 560

   # server = ServerProxy("http://localhost:8000") # local server
561
   with ServerProxy("http://betty.userland.com") as proxy:
562

563
       print(proxy)
564

565 566 567 568
       try:
           print(proxy.examples.getStateName(41))
       except Error as v:
           print("ERROR", v)
569

570
To access an XML-RPC server through a HTTP proxy, you need to define a custom
571
transport.  The following example shows how::
572

573 574
   import http.client
   import xmlrpc.client
575

576
   class ProxiedTransport(xmlrpc.client.Transport):
577

578 579 580
       def set_proxy(self, host, port=None, headers=None):
           self.proxy = host, port
           self.proxy_headers = headers
581

582 583 584 585 586 587 588 589 590 591
       def make_connection(self, host):
           connection = http.client.HTTPConnection(*self.proxy)
           connection.set_tunnel(host, headers=self.proxy_headers)
           self._connection = host, connection
           return connection

   transport = ProxiedTransport()
   transport.set_proxy('proxy-server', 8080)
   server = xmlrpc.client.ServerProxy('http://betty.userland.com', transport=transport)
   print(server.examples.getStateName(41))
592

593 594 595 596 597 598 599

Example of Client and Server Usage
----------------------------------

See :ref:`simplexmlrpcserver-example`.


600 601 602
.. rubric:: Footnotes

.. [#] This approach has been first presented in `a discussion on xmlrpc.com
603
   <https://web.archive.org/web/20060624230303/http://www.xmlrpc.com/discuss/msgReader$1208?mode=topic>`_.
604 605 606
.. the link now points to webarchive since the one at
.. http://www.xmlrpc.com/discuss/msgReader%241208 is broken (and webadmin
.. doesn't reply)