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