Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 1 | :mod:`xmlrpc.client` --- XML-RPC client access |
| 2 | ============================================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 4 | .. module:: xmlrpc.client |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 5 | :synopsis: XML-RPC client access. |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 6 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | .. moduleauthor:: Fredrik Lundh <fredrik@pythonware.com> |
| 8 | .. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com> |
| 9 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 10 | **Source code:** :source:`Lib/xmlrpc/client.py` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 11 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 12 | .. XXX Not everything is documented yet. It might be good to describe |
Florent Xicluna | 6166519 | 2011-11-15 20:53:25 +0100 | [diff] [blame] | 13 | Marshaller, Unmarshaller, getparser and Transport. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 14 | |
Raymond Hettinger | 3029aff | 2011-02-10 08:09:36 +0000 | [diff] [blame] | 15 | -------------- |
| 16 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 17 | XML-RPC is a Remote Procedure Call method that uses XML passed via HTTP(S) as a |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Christian Heimes | 7380a67 | 2013-03-26 17:35:55 +0100 | [diff] [blame] | 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 | |
Benjamin Peterson | e39bba2 | 2014-11-29 23:34:30 -0500 | [diff] [blame] | 30 | .. versionchanged:: 3.5 |
Benjamin Peterson | 77a75b3 | 2014-10-13 11:54:50 -0400 | [diff] [blame] | 31 | |
Martin Panter | fe289c0 | 2016-05-28 02:20:39 +0000 | [diff] [blame] | 32 | For HTTPS URIs, :mod:`xmlrpc.client` now performs all the necessary |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 33 | certificate and hostname checks by default. |
Christian Heimes | 7380a67 | 2013-03-26 17:35:55 +0100 | [diff] [blame] | 34 | |
Florent Xicluna | 6166519 | 2011-11-15 20:53:25 +0100 | [diff] [blame] | 35 | .. class:: ServerProxy(uri, transport=None, encoding=None, verbose=False, \ |
| 36 | allow_none=False, use_datetime=False, \ |
Benjamin Peterson | b7138e2 | 2014-11-29 23:38:17 -0500 | [diff] [blame] | 37 | use_builtin_types=False, *, context=None) |
Florent Xicluna | 6166519 | 2011-11-15 20:53:25 +0100 | [diff] [blame] | 38 | |
| 39 | .. versionchanged:: 3.3 |
| 40 | The *use_builtin_types* flag was added. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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. |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 49 | |
| 50 | The following parameters govern the use of the returned proxy instance. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 54 | all clients and servers; see `http://ontosys.com/xml-rpc/extensions.php |
Serhiy Storchaka | 64099ea | 2016-05-07 10:05:02 +0300 | [diff] [blame] | 55 | <https://web.archive.org/web/20130120074804/http://ontosys.com/xml-rpc/extensions.php>`_ |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 56 | for a description. |
| 57 | The *use_builtin_types* flag can be used to cause date/time values |
Florent Xicluna | 6166519 | 2011-11-15 20:53:25 +0100 | [diff] [blame] | 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. |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 60 | :class:`datetime.datetime`, :class:`bytes` and :class:`bytearray` objects |
| 61 | may be passed to calls. |
Florent Xicluna | 6166519 | 2011-11-15 20:53:25 +0100 | [diff] [blame] | 62 | The obsolete *use_datetime* flag is similar to *use_builtin_types* but it |
| 63 | applies only to date/time values. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Martin Panter | fe289c0 | 2016-05-28 02:20:39 +0000 | [diff] [blame] | 70 | Authentication user and password. If an HTTPS URL is provided, *context* may |
Benjamin Peterson | c1da3d1 | 2014-11-29 23:32:57 -0500 | [diff] [blame] | 71 | be :class:`ssl.SSLContext` and configures the SSL settings of the underlying |
| 72 | HTTPS connection. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 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): |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 83 | |
Georg Brandl | 44ea77b | 2013-03-28 13:28:44 +0100 | [diff] [blame] | 84 | .. tabularcolumns:: |l|L| |
| 85 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 86 | +----------------------+-------------------------------------------------------+ |
| 87 | | XML-RPC type | Python type | |
| 88 | +======================+=======================================================+ |
| 89 | | ``boolean`` | :class:`bool` | |
| 90 | +----------------------+-------------------------------------------------------+ |
Serhiy Storchaka | 352601c | 2016-09-11 11:23:38 +0300 | [diff] [blame] | 91 | | ``int``, ``i1``, | :class:`int` in range from -2147483648 to 2147483647. | |
| 92 | | ``i2``, ``i4``, | Values get the ``<int>`` tag. | |
| 93 | | ``i8`` or | | |
| 94 | | ``biginteger`` | | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 95 | +----------------------+-------------------------------------------------------+ |
Serhiy Storchaka | 352601c | 2016-09-11 11:23:38 +0300 | [diff] [blame] | 96 | | ``double`` or | :class:`float`. Values get the ``<double>`` tag. | |
| 97 | | ``float`` | | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 98 | +----------------------+-------------------------------------------------------+ |
| 99 | | ``string`` | :class:`str` | |
| 100 | +----------------------+-------------------------------------------------------+ |
| 101 | | ``array`` | :class:`list` or :class:`tuple` containing | |
| 102 | | | conformable elements. Arrays are returned as | |
Serhiy Storchaka | 64099ea | 2016-05-07 10:05:02 +0300 | [diff] [blame] | 103 | | | :class:`lists <list>`. | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 104 | +----------------------+-------------------------------------------------------+ |
| 105 | | ``struct`` | :class:`dict`. Keys must be strings, values may be | |
| 106 | | | any conformable type. Objects of user-defined | |
Serhiy Storchaka | 64099ea | 2016-05-07 10:05:02 +0300 | [diff] [blame] | 107 | | | classes can be passed in; only their | |
| 108 | | | :attr:`~object.__dict__` attribute is transmitted. | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 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 | +----------------------+-------------------------------------------------------+ |
Serhiy Storchaka | 352601c | 2016-09-11 11:23:38 +0300 | [diff] [blame] | 121 | | ``bigdecimal`` | :class:`decimal.Decimal`. Returned type only. | |
| 122 | +----------------------+-------------------------------------------------------+ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 128 | :exc:`Error`. Note that the xmlrpc client module currently does not marshal |
Georg Brandl | 22b3431 | 2009-07-26 14:54:51 +0000 | [diff] [blame] | 129 | instances of subclasses of built-in types. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Florent Xicluna | 6166519 | 2011-11-15 20:53:25 +0100 | [diff] [blame] | 136 | request that isn't well-formed XML. If you have to pass arbitrary bytes |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 137 | via XML-RPC, use :class:`bytes` or :class:`bytearray` classes or the |
| 138 | :class:`Binary` wrapper class described below. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 139 | |
| 140 | :class:`Server` is retained as an alias for :class:`ServerProxy` for backwards |
| 141 | compatibility. New code should use :class:`ServerProxy`. |
| 142 | |
Benjamin Peterson | e39bba2 | 2014-11-29 23:34:30 -0500 | [diff] [blame] | 143 | .. versionchanged:: 3.5 |
Benjamin Peterson | c1da3d1 | 2014-11-29 23:32:57 -0500 | [diff] [blame] | 144 | Added the *context* argument. |
| 145 | |
Serhiy Storchaka | 352601c | 2016-09-11 11:23:38 +0300 | [diff] [blame] | 146 | .. versionchanged:: 3.6 |
Serhiy Storchaka | b7e3535 | 2016-09-11 16:47:59 +0300 | [diff] [blame] | 147 | Added support of type tags with prefixes (e.g. ``ex:nil``). |
Xtreak | c151f78 | 2018-06-16 10:38:31 +0530 | [diff] [blame] | 148 | Added support of unmarshalling additional types used by Apache XML-RPC |
Serhiy Storchaka | 352601c | 2016-09-11 11:23:38 +0300 | [diff] [blame] | 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 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 153 | |
| 154 | .. seealso:: |
| 155 | |
| 156 | `XML-RPC HOWTO <http://www.tldp.org/HOWTO/XML-RPC-HOWTO/index.html>`_ |
Christian Heimes | a62da1d | 2008-01-12 19:39:10 +0000 | [diff] [blame] | 157 | A good description of XML-RPC operation and client software in several languages. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 158 | Contains pretty much everything an XML-RPC client developer needs to know. |
| 159 | |
Christian Heimes | a62da1d | 2008-01-12 19:39:10 +0000 | [diff] [blame] | 160 | `XML-RPC Introspection <http://xmlrpc-c.sourceforge.net/introspection.html>`_ |
| 161 | Describes the XML-RPC protocol extension for introspection. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 162 | |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame] | 163 | `XML-RPC Specification <http://xmlrpc.scripting.com/spec.html>`_ |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 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." |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 171 | |
| 172 | .. _serverproxy-objects: |
| 173 | |
| 174 | ServerProxy Objects |
| 175 | ------------------- |
| 176 | |
| 177 | A :class:`ServerProxy` instance has a method corresponding to each remote |
| 178 | procedure call accepted by the XML-RPC server. Calling the method performs an |
| 179 | RPC, dispatched by both name and argument signature (e.g. the same method name |
| 180 | can be overloaded with multiple argument signatures). The RPC finishes by |
| 181 | returning 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 | |
| 184 | Servers that support the XML introspection API support some common methods |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 185 | grouped under the reserved :attr:`~ServerProxy.system` attribute: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Georg Brandl | 9460648 | 2009-05-04 20:46:44 +0000 | [diff] [blame] | 197 | server. It returns an array of possible signatures for this method. A signature |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Georg Brandl | 9460648 | 2009-05-04 20:46:44 +0000 | [diff] [blame] | 211 | than list. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Brett Cannon | 33a4000 | 2014-03-21 11:24:40 -0400 | [diff] [blame] | 221 | .. versionchanged:: 3.5 |
| 222 | |
| 223 | Instances of :class:`ServerProxy` support the :term:`context manager` protocol |
| 224 | for closing the underlying transport. |
| 225 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 226 | |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 227 | A working example follows. The server code:: |
| 228 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 229 | from xmlrpc.server import SimpleXMLRPCServer |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 230 | |
| 231 | def is_even(n): |
Serhiy Storchaka | dba9039 | 2016-05-10 12:01:23 +0300 | [diff] [blame] | 232 | return n % 2 == 0 |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 233 | |
| 234 | server = SimpleXMLRPCServer(("localhost", 8000)) |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 235 | print("Listening on port 8000...") |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 236 | server.register_function(is_even, "is_even") |
| 237 | server.serve_forever() |
| 238 | |
| 239 | The client code for the preceding server:: |
| 240 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 241 | import xmlrpc.client |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 242 | |
Brett Cannon | 33a4000 | 2014-03-21 11:24:40 -0400 | [diff] [blame] | 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))) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 246 | |
| 247 | .. _datetime-objects: |
| 248 | |
| 249 | DateTime Objects |
| 250 | ---------------- |
| 251 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 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: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 258 | |
| 259 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 260 | .. method:: decode(string) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 261 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 262 | Accept a string as the instance's new time value. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 263 | |
| 264 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 265 | .. method:: encode(out) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 266 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 267 | Write the XML-RPC encoding of this :class:`DateTime` item to the *out* stream |
| 268 | object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 269 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 270 | It also supports certain of Python's built-in operators through rich comparison |
| 271 | and :meth:`__repr__` methods. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 272 | |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 273 | A working example follows. The server code:: |
| 274 | |
| 275 | import datetime |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 276 | from xmlrpc.server import SimpleXMLRPCServer |
| 277 | import xmlrpc.client |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 278 | |
| 279 | def today(): |
| 280 | today = datetime.datetime.today() |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 281 | return xmlrpc.client.DateTime(today) |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 282 | |
| 283 | server = SimpleXMLRPCServer(("localhost", 8000)) |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 284 | print("Listening on port 8000...") |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 285 | server.register_function(today, "today") |
| 286 | server.serve_forever() |
| 287 | |
| 288 | The client code for the preceding server:: |
| 289 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 290 | import xmlrpc.client |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 291 | import datetime |
| 292 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 293 | proxy = xmlrpc.client.ServerProxy("http://localhost:8000/") |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 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") |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 298 | print("Today: %s" % converted.strftime("%d.%m.%Y, %H:%M")) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 299 | |
| 300 | .. _binary-objects: |
| 301 | |
| 302 | Binary Objects |
| 303 | -------------- |
| 304 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 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: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 310 | |
| 311 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 312 | .. attribute:: data |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 313 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 314 | The binary data encapsulated by the :class:`Binary` instance. The data is |
| 315 | provided as a :class:`bytes` object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 316 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 317 | :class:`Binary` objects have the following methods, supported mainly for |
| 318 | internal use by the marshalling/unmarshalling code: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 319 | |
| 320 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 321 | .. method:: decode(bytes) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 322 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 323 | Accept a base64 :class:`bytes` object and decode it as the instance's new data. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 324 | |
| 325 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 326 | .. method:: encode(out) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 327 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 328 | Write the XML-RPC base 64 encoding of this binary item to the *out* stream object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 329 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 330 | The encoded data will have newlines every 76 characters as per |
Serhiy Storchaka | 0a36ac1 | 2018-05-31 07:39:00 +0300 | [diff] [blame] | 331 | :rfc:`RFC 2045 section 6.8 <2045#section-6.8>`, |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 332 | which was the de facto standard base64 specification when the |
| 333 | XML-RPC spec was written. |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 334 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 335 | It also supports certain of Python's built-in operators through :meth:`__eq__` |
| 336 | and :meth:`__ne__` methods. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 337 | |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 338 | Example usage of the binary objects. We're going to transfer an image over |
| 339 | XMLRPC:: |
| 340 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 341 | from xmlrpc.server import SimpleXMLRPCServer |
| 342 | import xmlrpc.client |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 343 | |
| 344 | def python_logo(): |
Victor Stinner | 757db83 | 2010-01-30 02:16:55 +0000 | [diff] [blame] | 345 | with open("python_logo.jpg", "rb") as handle: |
| 346 | return xmlrpc.client.Binary(handle.read()) |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 347 | |
| 348 | server = SimpleXMLRPCServer(("localhost", 8000)) |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 349 | print("Listening on port 8000...") |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 350 | server.register_function(python_logo, 'python_logo') |
| 351 | |
| 352 | server.serve_forever() |
| 353 | |
| 354 | The client gets the image and saves it to a file:: |
| 355 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 356 | import xmlrpc.client |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 357 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 358 | proxy = xmlrpc.client.ServerProxy("http://localhost:8000/") |
Victor Stinner | 757db83 | 2010-01-30 02:16:55 +0000 | [diff] [blame] | 359 | with open("fetched_python_logo.jpg", "wb") as handle: |
| 360 | handle.write(proxy.python_logo().data) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 361 | |
| 362 | .. _fault-objects: |
| 363 | |
| 364 | Fault Objects |
| 365 | ------------- |
| 366 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 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: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 371 | |
| 372 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 373 | .. attribute:: faultCode |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 374 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 375 | A string indicating the fault type. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 376 | |
| 377 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 378 | .. attribute:: faultString |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 379 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 380 | A string containing a diagnostic message associated with the fault. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 381 | |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 382 | In the following example we're going to intentionally cause a :exc:`Fault` by |
| 383 | returning a complex type object. The server code:: |
| 384 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 385 | from xmlrpc.server import SimpleXMLRPCServer |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 386 | |
| 387 | # A marshalling error is going to occur because we're returning a |
| 388 | # complex number |
Serhiy Storchaka | dba9039 | 2016-05-10 12:01:23 +0300 | [diff] [blame] | 389 | def add(x, y): |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 390 | return x+y+0j |
| 391 | |
| 392 | server = SimpleXMLRPCServer(("localhost", 8000)) |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 393 | print("Listening on port 8000...") |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 394 | server.register_function(add, 'add') |
| 395 | |
| 396 | server.serve_forever() |
| 397 | |
| 398 | The client code for the preceding server:: |
| 399 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 400 | import xmlrpc.client |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 401 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 402 | proxy = xmlrpc.client.ServerProxy("http://localhost:8000/") |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 403 | try: |
| 404 | proxy.add(2, 5) |
Georg Brandl | 0dedf45 | 2009-05-22 16:44:06 +0000 | [diff] [blame] | 405 | except xmlrpc.client.Fault as err: |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 406 | print("A fault occurred") |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 407 | print("Fault code: %d" % err.faultCode) |
| 408 | print("Fault string: %s" % err.faultString) |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 409 | |
| 410 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 411 | |
| 412 | .. _protocol-error-objects: |
| 413 | |
| 414 | ProtocolError Objects |
| 415 | --------------------- |
| 416 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 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: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 422 | |
| 423 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 424 | .. attribute:: url |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 425 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 426 | The URI or URL that triggered the error. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 427 | |
| 428 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 429 | .. attribute:: errcode |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 430 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 431 | The error code. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 432 | |
| 433 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 434 | .. attribute:: errmsg |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 435 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 436 | The error message or diagnostic string. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 437 | |
| 438 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 439 | .. attribute:: headers |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 440 | |
Serhiy Storchaka | da7880a | 2016-05-07 08:44:15 +0300 | [diff] [blame] | 441 | A dict containing the headers of the HTTP/HTTPS request that triggered the |
| 442 | error. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 443 | |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 444 | In the following example we're going to intentionally cause a :exc:`ProtocolError` |
| 445 | by providing an invalid URI:: |
| 446 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 447 | import xmlrpc.client |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 448 | |
Martin Panter | 6245cb3 | 2016-04-15 02:14:19 +0000 | [diff] [blame] | 449 | # create a ServerProxy with a URI that doesn't respond to XMLRPC requests |
Benjamin Peterson | 5e55b3e | 2010-02-03 02:35:45 +0000 | [diff] [blame] | 450 | proxy = xmlrpc.client.ServerProxy("http://google.com/") |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 451 | |
| 452 | try: |
| 453 | proxy.some_method() |
Georg Brandl | 0dedf45 | 2009-05-22 16:44:06 +0000 | [diff] [blame] | 454 | except xmlrpc.client.ProtocolError as err: |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 455 | print("A protocol error occurred") |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 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) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 460 | |
| 461 | MultiCall Objects |
| 462 | ----------------- |
| 463 | |
Sandro Tosi | 9daf98d | 2011-08-20 17:05:56 +0200 | [diff] [blame] | 464 | The :class:`MultiCall` object provides a way to encapsulate multiple calls to a |
| 465 | remote server into a single request [#]_. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 475 | is a :term:`generator`; iterating over this generator yields the individual |
| 476 | results. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 477 | |
Andrew Kuchling | c3db373 | 2013-06-20 21:33:05 -0400 | [diff] [blame] | 478 | A usage example of this class follows. The server code:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 479 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 480 | from xmlrpc.server import SimpleXMLRPCServer |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 481 | |
Ezio Melotti | 79016e1 | 2013-08-08 15:45:56 +0300 | [diff] [blame] | 482 | def add(x, y): |
| 483 | return x + y |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 484 | |
| 485 | def subtract(x, y): |
Ezio Melotti | 79016e1 | 2013-08-08 15:45:56 +0300 | [diff] [blame] | 486 | return x - y |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 487 | |
| 488 | def multiply(x, y): |
Ezio Melotti | 79016e1 | 2013-08-08 15:45:56 +0300 | [diff] [blame] | 489 | return x * y |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 490 | |
| 491 | def divide(x, y): |
Andrew Kuchling | c3db373 | 2013-06-20 21:33:05 -0400 | [diff] [blame] | 492 | return x // y |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 493 | |
| 494 | # A simple server with simple arithmetic functions |
| 495 | server = SimpleXMLRPCServer(("localhost", 8000)) |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 496 | print("Listening on port 8000...") |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 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 | |
| 504 | The client code for the preceding server:: |
| 505 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 506 | import xmlrpc.client |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 507 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 508 | proxy = xmlrpc.client.ServerProxy("http://localhost:8000/") |
| 509 | multicall = xmlrpc.client.MultiCall(proxy) |
Ezio Melotti | 79016e1 | 2013-08-08 15:45:56 +0300 | [diff] [blame] | 510 | multicall.add(7, 3) |
| 511 | multicall.subtract(7, 3) |
| 512 | multicall.multiply(7, 3) |
| 513 | multicall.divide(7, 3) |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 514 | result = multicall() |
| 515 | |
Ezio Melotti | 79016e1 | 2013-08-08 15:45:56 +0300 | [diff] [blame] | 516 | print("7+3=%d, 7-3=%d, 7*3=%d, 7//3=%d" % tuple(result)) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 517 | |
| 518 | |
| 519 | Convenience Functions |
| 520 | --------------------- |
| 521 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 522 | .. function:: dumps(params, methodname=None, methodresponse=None, encoding=None, allow_none=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Florent Xicluna | 6166519 | 2011-11-15 20:53:25 +0100 | [diff] [blame] | 533 | .. function:: loads(data, use_datetime=False, use_builtin_types=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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. |
Florent Xicluna | 6166519 | 2011-11-15 20:53:25 +0100 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 548 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 549 | |
| 550 | .. _xmlrpc-client-example: |
| 551 | |
| 552 | Example of Client Usage |
| 553 | ----------------------- |
| 554 | |
| 555 | :: |
| 556 | |
| 557 | # simple test program (from the XML-RPC specification) |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 558 | from xmlrpc.client import ServerProxy, Error |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 559 | |
| 560 | # server = ServerProxy("http://localhost:8000") # local server |
Brett Cannon | 33a4000 | 2014-03-21 11:24:40 -0400 | [diff] [blame] | 561 | with ServerProxy("http://betty.userland.com") as proxy: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 562 | |
Brett Cannon | 33a4000 | 2014-03-21 11:24:40 -0400 | [diff] [blame] | 563 | print(proxy) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 564 | |
Brett Cannon | 33a4000 | 2014-03-21 11:24:40 -0400 | [diff] [blame] | 565 | try: |
| 566 | print(proxy.examples.getStateName(41)) |
| 567 | except Error as v: |
| 568 | print("ERROR", v) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 569 | |
Martin Panter | 1c5e715 | 2016-02-22 09:04:22 +0000 | [diff] [blame] | 570 | To access an XML-RPC server through a HTTP proxy, you need to define a custom |
Berker Peksag | 0aa7887 | 2016-10-09 18:18:21 +0300 | [diff] [blame] | 571 | transport. The following example shows how:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 572 | |
Berker Peksag | 0aa7887 | 2016-10-09 18:18:21 +0300 | [diff] [blame] | 573 | import http.client |
| 574 | import xmlrpc.client |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 575 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 576 | class ProxiedTransport(xmlrpc.client.Transport): |
Berker Peksag | 0aa7887 | 2016-10-09 18:18:21 +0300 | [diff] [blame] | 577 | |
| 578 | def set_proxy(self, host, port=None, headers=None): |
| 579 | self.proxy = host, port |
| 580 | self.proxy_headers = headers |
Serhiy Storchaka | dba9039 | 2016-05-10 12:01:23 +0300 | [diff] [blame] | 581 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 582 | def make_connection(self, host): |
Berker Peksag | 0aa7887 | 2016-10-09 18:18:21 +0300 | [diff] [blame] | 583 | connection = http.client.HTTPConnection(*self.proxy) |
| 584 | connection.set_tunnel(host, headers=self.proxy_headers) |
| 585 | self._connection = host, connection |
| 586 | return connection |
Serhiy Storchaka | dba9039 | 2016-05-10 12:01:23 +0300 | [diff] [blame] | 587 | |
Berker Peksag | 0aa7887 | 2016-10-09 18:18:21 +0300 | [diff] [blame] | 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)) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 592 | |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 593 | |
| 594 | Example of Client and Server Usage |
| 595 | ---------------------------------- |
| 596 | |
| 597 | See :ref:`simplexmlrpcserver-example`. |
| 598 | |
| 599 | |
Sandro Tosi | 9daf98d | 2011-08-20 17:05:56 +0200 | [diff] [blame] | 600 | .. rubric:: Footnotes |
| 601 | |
| 602 | .. [#] This approach has been first presented in `a discussion on xmlrpc.com |
Serhiy Storchaka | 6dff020 | 2016-05-07 10:49:07 +0300 | [diff] [blame] | 603 | <https://web.archive.org/web/20060624230303/http://www.xmlrpc.com/discuss/msgReader$1208?mode=topic>`_. |
Sandro Tosi | 9daf98d | 2011-08-20 17:05:56 +0200 | [diff] [blame] | 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) |