Debian Codegraph @

Doc/library/xmlrpc.client.rst

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