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, *, context=None) 38 39 .. versionchanged:: 3.3 40 The *use_builtin_types* flag was added. 41 42 A :class:`ServerProxy` instance is an object that manages communication with a 43 remote XML-RPC server. The required first argument is a URI (Uniform Resource 44 Indicator), and will normally be the URL of the server. The optional second 45 argument is a transport factory instance; by default it is an internal 46 :class:`SafeTransport` instance for https: URLs and an internal HTTP 47 :class:`Transport` instance otherwise. The optional third argument is an 48 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 If *allow_none* is true, the Python constant ``None`` will be translated into 52 XML; the default behaviour is for ``None`` to raise a :exc:`TypeError`. This is 53 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 for a description. 57 The *use_builtin_types* flag can be used to cause date/time values 58 to be presented as :class:`datetime.datetime` objects and binary data to be 59 presented as :class:`bytes` objects; this flag is false by default. 60 :class:`datetime.datetime`, :class:`bytes` and :class:`bytearray` objects 61 may be passed to calls. 62 The obsolete *use_datetime* flag is similar to *use_builtin_types* but it 63 applies only to date/time values. 64 65 Both the HTTP and HTTPS transports support the URL syntax extension for HTTP 66 Basic Authentication: ``http://user:pass@host:port/path``. The ``user:pass`` 67 portion will be base64-encoded as an HTTP 'Authorization' header, and sent to 68 the remote server as part of the connection process when invoking an XML-RPC 69 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 be :class:`ssl.SSLContext` and configures the SSL settings of the underlying 72 HTTPS connection. 73 74 The returned instance is a proxy object with methods that can be used to invoke 75 corresponding RPC calls on the remote server. If the remote server supports the 76 introspection API, the proxy can also be used to query the remote server for the 77 methods it supports (service discovery) and fetch other server-associated 78 metadata. 79 80 Types that are conformable (e.g. that can be marshalled through XML), 81 include the following (and except where noted, they are unmarshalled 82 as the same Python type): 83 84 .. tabularcolumns:: |l|L| 85 86 +----------------------+-------------------------------------------------------+ 87 | XML-RPC type | Python type | 88 +======================+=======================================================+ 89 | ``boolean`` | :class:`bool` | 90 +----------------------+-------------------------------------------------------+ 91 | ``int``, ``i1``, | :class:`int` in range from -2147483648 to 2147483647. | 92 | ``i2``, ``i4``, | Values get the ``<int>`` tag. | 93 | ``i8`` or | | 94 | ``biginteger`` | | 95 +----------------------+-------------------------------------------------------+ 96 | ``double`` or | :class:`float`. Values get the ``<double>`` tag. | 97 | ``float`` | | 98 +----------------------+-------------------------------------------------------+ 99 | ``string`` | :class:`str` | 100 +----------------------+-------------------------------------------------------+ 101 | ``array`` | :class:`list` or :class:`tuple` containing | 102 | | conformable elements. Arrays are returned as | 103 | | :class:`lists <list>`. | 104 +----------------------+-------------------------------------------------------+ 105 | ``struct`` | :class:`dict`. Keys must be strings, values may be | 106 | | any conformable type. Objects of user-defined | 107 | | classes can be passed in; only their | 108 | | :attr:`~object.__dict__` attribute is transmitted. | 109 +----------------------+-------------------------------------------------------+ 110 | ``dateTime.iso8601`` | :class:`DateTime` or :class:`datetime.datetime`. | 111 | | Returned type depends on values of | 112 | | *use_builtin_types* and *use_datetime* flags. | 113 +----------------------+-------------------------------------------------------+ 114 | ``base64`` | :class:`Binary`, :class:`bytes` or | 115 | | :class:`bytearray`. Returned type depends on the | 116 | | value of the *use_builtin_types* flag. | 117 +----------------------+-------------------------------------------------------+ 118 | ``nil`` | The ``None`` constant. Passing is allowed only if | 119 | | *allow_none* is true. | 120 +----------------------+-------------------------------------------------------+ 121 | ``bigdecimal`` | :class:`decimal.Decimal`. Returned type only. | 122 +----------------------+-------------------------------------------------------+ 123 124 This is the full set of data types supported by XML-RPC. Method calls may also 125 raise a special :exc:`Fault` instance, used to signal XML-RPC server errors, or 126 :exc:`ProtocolError` used to signal an error in the HTTP/HTTPS transport layer. 127 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 When passing strings, characters special to XML such as ``<``, ``>``, and ``&`` 132 will be automatically escaped. However, it's the caller's responsibility to 133 ensure that the string is free of characters that aren't allowed in XML, such as 134 the control characters with ASCII values between 0 and 31 (except, of course, 135 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 via XML-RPC, use :class:`bytes` or :class:`bytearray` classes or the 138 :class:`Binary` wrapper class described below. 139 140 :class:`Server` is retained as an alias for :class:`ServerProxy` for backwards 141 compatibility. New code should use :class:`ServerProxy`. 142 143 .. versionchanged:: 3.5 144 Added the *context* argument. 145 146 .. versionchanged:: 3.6 147 Added support of type tags with prefixes (e.g. ``ex:nil``). 148 Added support of unmarshalling additional types used by Apache XML-RPC 149 implementation for numerics: ``i1``, ``i2``, ``i8``, ``biginteger``, 150 ``float`` and ``bigdecimal``. 151 See http://ws.apache.org/xmlrpc/types.html for a description. 152 153 154.. seealso:: 155 156 `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 Contains pretty much everything an XML-RPC client developer needs to know. 159 160 `XML-RPC Introspection <http://xmlrpc-c.sourceforge.net/introspection.html>`_ 161 Describes the XML-RPC protocol extension for introspection. 162 163 `XML-RPC Specification <http://xmlrpc.scripting.com/spec.html>`_ 164 The official specification. 165 166 `Unofficial XML-RPC Errata <http://effbot.org/zone/xmlrpc-errata.htm>`_ 167 Fredrik Lundh's "unofficial errata, intended to clarify certain 168 details in the XML-RPC specification, as well as hint at 169 'best practices' to use when designing your own XML-RPC 170 implementations." 171 172.. _serverproxy-objects: 173 174ServerProxy Objects 175------------------- 176 177A :class:`ServerProxy` instance has a method corresponding to each remote 178procedure call accepted by the XML-RPC server. Calling the method performs an 179RPC, dispatched by both name and argument signature (e.g. the same method name 180can be overloaded with multiple argument signatures). The RPC finishes by 181returning a value, which may be either returned data in a conformant type or a 182:class:`Fault` or :class:`ProtocolError` object indicating an error. 183 184Servers that support the XML introspection API support some common methods 185grouped under the reserved :attr:`~ServerProxy.system` attribute: 186 187 188.. method:: ServerProxy.system.listMethods() 189 190 This method returns a list of strings, one for each (non-system) method 191 supported by the XML-RPC server. 192 193 194.. method:: ServerProxy.system.methodSignature(name) 195 196 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 is an array of types. The first of these types is the return type of the method, 199 the rest are parameters. 200 201 Because multiple signatures (ie. overloading) is permitted, this method returns 202 a list of signatures rather than a singleton. 203 204 Signatures themselves are restricted to the top level parameters expected by a 205 method. For instance if a method expects one array of structs as a parameter, 206 and it returns a string, its signature is simply "string, array". If it expects 207 three integers and returns a string, its signature is "string, int, int, int". 208 209 If no signature is defined for the method, a non-array value is returned. In 210 Python this means that the type of the returned value will be something other 211 than list. 212 213 214.. method:: ServerProxy.system.methodHelp(name) 215 216 This method takes one parameter, the name of a method implemented by the XML-RPC 217 server. It returns a documentation string describing the use of that method. If 218 no such string is available, an empty string is returned. The documentation 219 string may contain HTML markup. 220 221.. versionchanged:: 3.5 222 223 Instances of :class:`ServerProxy` support the :term:`context manager` protocol 224 for closing the underlying transport. 225 226 227A working example follows. The server code:: 228 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 server.register_function(is_even, "is_even") 237 server.serve_forever() 238 239The client code for the preceding server:: 240 241 import xmlrpc.client 242 243 with xmlrpc.client.ServerProxy("http://localhost:8000/") as proxy: 244 print("3 is even: %s" % str(proxy.is_even(3))) 245 print("100 is even: %s" % str(proxy.is_even(100))) 246 247.. _datetime-objects: 248 249DateTime Objects 250---------------- 251 252.. class:: DateTime 253 254 This class may be initialized with seconds since the epoch, a time 255 tuple, an ISO 8601 time/date string, or a :class:`datetime.datetime` 256 instance. It has the following methods, supported mainly for internal 257 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 Write the XML-RPC encoding of this :class:`DateTime` item to the *out* stream 268 object. 269 270 It also supports certain of Python's built-in operators through rich comparison 271 and :meth:`__repr__` methods. 272 273A working example follows. The server code:: 274 275 import datetime 276 from xmlrpc.server import SimpleXMLRPCServer 277 import xmlrpc.client 278 279 def today(): 280 today = datetime.datetime.today() 281 return xmlrpc.client.DateTime(today) 282 283 server = SimpleXMLRPCServer(("localhost", 8000)) 284 print("Listening on port 8000...") 285 server.register_function(today, "today") 286 server.serve_forever() 287 288The client code for the preceding server:: 289 290 import xmlrpc.client 291 import datetime 292 293 proxy = xmlrpc.client.ServerProxy("http://localhost:8000/") 294 295 today = proxy.today() 296 # convert the ISO8601 string to a datetime object 297 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.. _binary-objects: 301 302Binary Objects 303-------------- 304 305.. class:: Binary 306 307 This class may be initialized from bytes data (which may include NULs). The 308 primary access to the content of a :class:`Binary` object is provided by an 309 attribute: 310 311 312 .. attribute:: data 313 314 The binary data encapsulated by the :class:`Binary` instance. The data is 315 provided as a :class:`bytes` object. 316 317 :class:`Binary` objects have the following methods, supported mainly for 318 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. 329 330 The encoded data will have newlines every 76 characters as per 331 :rfc:`RFC 2045 section 6.8 <2045#section-6.8>`, 332 which was the de facto standard base64 specification when the 333 XML-RPC spec was written. 334 335 It also supports certain of Python's built-in operators through :meth:`__eq__` 336 and :meth:`__ne__` methods. 337 338Example usage of the binary objects. We're going to transfer an image over 339XMLRPC:: 340 341 from xmlrpc.server import SimpleXMLRPCServer 342 import xmlrpc.client 343 344 def python_logo(): 345 with open("python_logo.jpg", "rb") as handle: 346 return xmlrpc.client.Binary(handle.read()) 347 348 server = SimpleXMLRPCServer(("localhost", 8000)) 349 print("Listening on port 8000...") 350 server.register_function(python_logo, 'python_logo') 351 352 server.serve_forever() 353 354The client gets the image and saves it to a file:: 355 356 import xmlrpc.client 357 358 proxy = xmlrpc.client.ServerProxy("http://localhost:8000/") 359 with open("fetched_python_logo.jpg", "wb") as handle: 360 handle.write(proxy.python_logo().data) 361 362.. _fault-objects: 363 364Fault Objects 365------------- 366 367.. class:: Fault 368 369 A :class:`Fault` object encapsulates the content of an XML-RPC fault tag. Fault 370 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 382In the following example we're going to intentionally cause a :exc:`Fault` by 383returning a complex type object. The server code:: 384 385 from xmlrpc.server import SimpleXMLRPCServer 386 387 # A marshalling error is going to occur because we're returning a 388 # complex number 389 def add(x, y): 390 return x+y+0j 391 392 server = SimpleXMLRPCServer(("localhost", 8000)) 393 print("Listening on port 8000...") 394 server.register_function(add, 'add') 395 396 server.serve_forever() 397 398The client code for the preceding server:: 399 400 import xmlrpc.client 401 402 proxy = xmlrpc.client.ServerProxy("http://localhost:8000/") 403 try: 404 proxy.add(2, 5) 405 except xmlrpc.client.Fault as err: 406 print("A fault occurred") 407 print("Fault code: %d" % err.faultCode) 408 print("Fault string: %s" % err.faultString) 409 410 411 412.. _protocol-error-objects: 413 414ProtocolError Objects 415--------------------- 416 417.. class:: ProtocolError 418 419 A :class:`ProtocolError` object describes a protocol error in the underlying 420 transport layer (such as a 404 'not found' error if the server named by the URI 421 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 A dict containing the headers of the HTTP/HTTPS request that triggered the 442 error. 443 444In the following example we're going to intentionally cause a :exc:`ProtocolError` 445by providing an invalid URI:: 446 447 import xmlrpc.client 448 449 # create a ServerProxy with a URI that doesn't respond to XMLRPC requests 450 proxy = xmlrpc.client.ServerProxy("http://google.com/") 451 452 try: 453 proxy.some_method() 454 except xmlrpc.client.ProtocolError as err: 455 print("A protocol error occurred") 456 print("URL: %s" % err.url) 457 print("HTTP/HTTPS headers: %s" % err.headers) 458 print("Error code: %d" % err.errcode) 459 print("Error message: %s" % err.errmsg) 460 461MultiCall Objects 462----------------- 463 464The :class:`MultiCall` object provides a way to encapsulate multiple calls to a 465remote server into a single request [#]_. 466 467 468.. class:: MultiCall(server) 469 470 Create an object used to boxcar method calls. *server* is the eventual target of 471 the call. Calls can be made to the result object, but they will immediately 472 return ``None``, and only store the call name and parameters in the 473 :class:`MultiCall` object. Calling the object itself causes all stored calls to 474 be transmitted as a single ``system.multicall`` request. The result of this call 475 is a :term:`generator`; iterating over this generator yields the individual 476 results. 477 478A usage example of this class follows. The server code:: 479 480 from xmlrpc.server import SimpleXMLRPCServer 481 482 def add(x, y): 483 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 # A simple server with simple arithmetic functions 495 server = SimpleXMLRPCServer(("localhost", 8000)) 496 print("Listening on port 8000...") 497 server.register_multicall_functions() 498 server.register_function(add, 'add') 499 server.register_function(subtract, 'subtract') 500 server.register_function(multiply, 'multiply') 501 server.register_function(divide, 'divide') 502 server.serve_forever() 503 504The client code for the preceding server:: 505 506 import xmlrpc.client 507 508 proxy = xmlrpc.client.ServerProxy("http://localhost:8000/") 509 multicall = xmlrpc.client.MultiCall(proxy) 510 multicall.add(7, 3) 511 multicall.subtract(7, 3) 512 multicall.multiply(7, 3) 513 multicall.divide(7, 3) 514 result = multicall() 515 516 print("7+3=%d, 7-3=%d, 7*3=%d, 7//3=%d" % tuple(result)) 517 518 519Convenience Functions 520--------------------- 521 522.. function:: dumps(params, methodname=None, methodresponse=None, encoding=None, allow_none=False) 523 524 Convert *params* into an XML-RPC request. or into a response if *methodresponse* 525 is true. *params* can be either a tuple of arguments or an instance of the 526 :exc:`Fault` exception class. If *methodresponse* is true, only a single value 527 can be returned, meaning that *params* must be of length 1. *encoding*, if 528 supplied, is the encoding to use in the generated XML; the default is UTF-8. 529 Python's :const:`None` value cannot be used in standard XML-RPC; to allow using 530 it via an extension, provide a true value for *allow_none*. 531 532 533.. function:: loads(data, use_datetime=False, use_builtin_types=False) 534 535 Convert an XML-RPC request or response into Python objects, a ``(params, 536 methodname)``. *params* is a tuple of argument; *methodname* is a string, or 537 ``None`` if no method name is present in the packet. If the XML-RPC packet 538 represents a fault condition, this function will raise a :exc:`Fault` exception. 539 The *use_builtin_types* flag can be used to cause date/time values to be 540 presented as :class:`datetime.datetime` objects and binary data to be 541 presented as :class:`bytes` objects; this flag is false by default. 542 543 The obsolete *use_datetime* flag is similar to *use_builtin_types* but it 544 applies only to date/time values. 545 546 .. versionchanged:: 3.3 547 The *use_builtin_types* flag was added. 548 549 550.. _xmlrpc-client-example: 551 552Example of Client Usage 553----------------------- 554 555:: 556 557 # 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 try: 566 print(proxy.examples.getStateName(41)) 567 except Error as v: 568 print("ERROR", v) 569 570To access an XML-RPC server through a HTTP proxy, you need to define a custom 571transport. The following example shows how:: 572 573 import http.client 574 import xmlrpc.client 575 576 class ProxiedTransport(xmlrpc.client.Transport): 577 578 def set_proxy(self, host, port=None, headers=None): 579 self.proxy = host, port 580 self.proxy_headers = headers 581 582 def make_connection(self, host): 583 connection = http.client.HTTPConnection(*self.proxy) 584 connection.set_tunnel(host, headers=self.proxy_headers) 585 self._connection = host, connection 586 return connection 587 588 transport = ProxiedTransport() 589 transport.set_proxy('proxy-server', 8080) 590 server = xmlrpc.client.ServerProxy('http://betty.userland.com', transport=transport) 591 print(server.examples.getStateName(41)) 592 593 594Example of Client and Server Usage 595---------------------------------- 596 597See :ref:`simplexmlrpcserver-example`. 598 599 600.. rubric:: Footnotes 601 602.. [#] 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.. the link now points to webarchive since the one at 605.. http://www.xmlrpc.com/discuss/msgReader%241208 is broken (and webadmin 606.. doesn't reply) 607
