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. |
| 6 | .. moduleauthor:: Fredrik Lundh <fredrik@pythonware.com> |
| 7 | .. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com> |
| 8 | |
| 9 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 10 | .. XXX Not everything is documented yet. It might be good to describe |
Florent Xicluna | 6166519 | 2011-11-15 20:53:25 +0100 | [diff] [blame] | 11 | Marshaller, Unmarshaller, getparser and Transport. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 12 | |
Raymond Hettinger | 3029aff | 2011-02-10 08:09:36 +0000 | [diff] [blame] | 13 | **Source code:** :source:`Lib/xmlrpc/client.py` |
| 14 | |
| 15 | -------------- |
| 16 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 17 | XML-RPC is a Remote Procedure Call method that uses XML passed via HTTP 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 | |
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 | 4ffb075 | 2014-11-03 14:29:33 -0500 | [diff] [blame] | 30 | .. versionchanged:: 3.4.3 |
Benjamin Peterson | 77a75b3 | 2014-10-13 11:54:50 -0400 | [diff] [blame] | 31 | |
Benjamin Peterson | 4ffb075 | 2014-11-03 14:29:33 -0500 | [diff] [blame] | 32 | For https URIs, :mod:`xmlrpc.client` now performs all the necessary |
| 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. |
| 49 | If *allow_none* is true, the Python constant ``None`` will be translated into |
| 50 | XML; the default behaviour is for ``None`` to raise a :exc:`TypeError`. This is |
| 51 | a commonly-used extension to the XML-RPC specification, but isn't supported by |
| 52 | all clients and servers; see http://ontosys.com/xml-rpc/extensions.php for a |
Florent Xicluna | 6166519 | 2011-11-15 20:53:25 +0100 | [diff] [blame] | 53 | description. The *use_builtin_types* flag can be used to cause date/time values |
| 54 | to be presented as :class:`datetime.datetime` objects and binary data to be |
| 55 | presented as :class:`bytes` objects; this flag is false by default. |
| 56 | :class:`datetime.datetime` and :class:`bytes` objects may be passed to calls. |
| 57 | |
| 58 | The obsolete *use_datetime* flag is similar to *use_builtin_types* but it |
| 59 | applies only to date/time values. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 60 | |
| 61 | Both the HTTP and HTTPS transports support the URL syntax extension for HTTP |
| 62 | Basic Authentication: ``http://user:pass@host:port/path``. The ``user:pass`` |
| 63 | portion will be base64-encoded as an HTTP 'Authorization' header, and sent to |
| 64 | the remote server as part of the connection process when invoking an XML-RPC |
| 65 | method. You only need to use this if the remote server requires a Basic |
Benjamin Peterson | c1da3d1 | 2014-11-29 23:32:57 -0500 | [diff] [blame] | 66 | Authentication user and password. If an HTTPS url is provided, *context* may |
| 67 | be :class:`ssl.SSLContext` and configures the SSL settings of the underlying |
| 68 | HTTPS connection. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 69 | |
| 70 | The returned instance is a proxy object with methods that can be used to invoke |
| 71 | corresponding RPC calls on the remote server. If the remote server supports the |
| 72 | introspection API, the proxy can also be used to query the remote server for the |
| 73 | methods it supports (service discovery) and fetch other server-associated |
| 74 | metadata. |
| 75 | |
| 76 | :class:`ServerProxy` instance methods take Python basic types and objects as |
| 77 | arguments and return Python basic types and classes. Types that are conformable |
| 78 | (e.g. that can be marshalled through XML), include the following (and except |
| 79 | where noted, they are unmarshalled as the same Python type): |
| 80 | |
Georg Brandl | 44ea77b | 2013-03-28 13:28:44 +0100 | [diff] [blame] | 81 | .. tabularcolumns:: |l|L| |
| 82 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 83 | +---------------------------------+---------------------------------------------+ |
| 84 | | Name | Meaning | |
| 85 | +=================================+=============================================+ |
| 86 | | :const:`boolean` | The :const:`True` and :const:`False` | |
| 87 | | | constants | |
| 88 | +---------------------------------+---------------------------------------------+ |
| 89 | | :const:`integers` | Pass in directly | |
| 90 | +---------------------------------+---------------------------------------------+ |
| 91 | | :const:`floating-point numbers` | Pass in directly | |
| 92 | +---------------------------------+---------------------------------------------+ |
| 93 | | :const:`strings` | Pass in directly | |
| 94 | +---------------------------------+---------------------------------------------+ |
| 95 | | :const:`arrays` | Any Python sequence type containing | |
| 96 | | | conformable elements. Arrays are returned | |
| 97 | | | as lists | |
| 98 | +---------------------------------+---------------------------------------------+ |
| 99 | | :const:`structures` | A Python dictionary. Keys must be strings, | |
| 100 | | | values may be any conformable type. Objects | |
| 101 | | | of user-defined classes can be passed in; | |
| 102 | | | only their *__dict__* attribute is | |
| 103 | | | transmitted. | |
| 104 | +---------------------------------+---------------------------------------------+ |
Florent Xicluna | 6166519 | 2011-11-15 20:53:25 +0100 | [diff] [blame] | 105 | | :const:`dates` | In seconds since the epoch. Pass in an | |
| 106 | | | instance of the :class:`DateTime` class or | |
Christian Heimes | 05e8be1 | 2008-02-23 18:30:17 +0000 | [diff] [blame] | 107 | | | a :class:`datetime.datetime` instance. | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 108 | +---------------------------------+---------------------------------------------+ |
Florent Xicluna | 6166519 | 2011-11-15 20:53:25 +0100 | [diff] [blame] | 109 | | :const:`binary data` | Pass in an instance of the :class:`Binary` | |
| 110 | | | wrapper class or a :class:`bytes` instance. | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 111 | +---------------------------------+---------------------------------------------+ |
| 112 | |
| 113 | This is the full set of data types supported by XML-RPC. Method calls may also |
| 114 | raise a special :exc:`Fault` instance, used to signal XML-RPC server errors, or |
| 115 | :exc:`ProtocolError` used to signal an error in the HTTP/HTTPS transport layer. |
| 116 | Both :exc:`Fault` and :exc:`ProtocolError` derive from a base class called |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 117 | :exc:`Error`. Note that the xmlrpc client module currently does not marshal |
Georg Brandl | 22b3431 | 2009-07-26 14:54:51 +0000 | [diff] [blame] | 118 | instances of subclasses of built-in types. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 119 | |
| 120 | When passing strings, characters special to XML such as ``<``, ``>``, and ``&`` |
| 121 | will be automatically escaped. However, it's the caller's responsibility to |
| 122 | ensure that the string is free of characters that aren't allowed in XML, such as |
| 123 | the control characters with ASCII values between 0 and 31 (except, of course, |
| 124 | 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] | 125 | request that isn't well-formed XML. If you have to pass arbitrary bytes |
| 126 | via XML-RPC, use the :class:`bytes` class or the class:`Binary` wrapper class |
| 127 | described below. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 128 | |
| 129 | :class:`Server` is retained as an alias for :class:`ServerProxy` for backwards |
| 130 | compatibility. New code should use :class:`ServerProxy`. |
| 131 | |
Benjamin Peterson | c1da3d1 | 2014-11-29 23:32:57 -0500 | [diff] [blame] | 132 | .. versionchanged:: 3.4.3 |
| 133 | Added the *context* argument. |
| 134 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 135 | |
| 136 | .. seealso:: |
| 137 | |
| 138 | `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] | 139 | 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] | 140 | Contains pretty much everything an XML-RPC client developer needs to know. |
| 141 | |
Christian Heimes | a62da1d | 2008-01-12 19:39:10 +0000 | [diff] [blame] | 142 | `XML-RPC Introspection <http://xmlrpc-c.sourceforge.net/introspection.html>`_ |
| 143 | Describes the XML-RPC protocol extension for introspection. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 144 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 145 | `XML-RPC Specification <http://www.xmlrpc.com/spec>`_ |
| 146 | The official specification. |
| 147 | |
| 148 | `Unofficial XML-RPC Errata <http://effbot.org/zone/xmlrpc-errata.htm>`_ |
| 149 | Fredrik Lundh's "unofficial errata, intended to clarify certain |
| 150 | details in the XML-RPC specification, as well as hint at |
| 151 | 'best practices' to use when designing your own XML-RPC |
| 152 | implementations." |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 153 | |
| 154 | .. _serverproxy-objects: |
| 155 | |
| 156 | ServerProxy Objects |
| 157 | ------------------- |
| 158 | |
| 159 | A :class:`ServerProxy` instance has a method corresponding to each remote |
| 160 | procedure call accepted by the XML-RPC server. Calling the method performs an |
| 161 | RPC, dispatched by both name and argument signature (e.g. the same method name |
| 162 | can be overloaded with multiple argument signatures). The RPC finishes by |
| 163 | returning a value, which may be either returned data in a conformant type or a |
| 164 | :class:`Fault` or :class:`ProtocolError` object indicating an error. |
| 165 | |
| 166 | Servers that support the XML introspection API support some common methods |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 167 | grouped under the reserved :attr:`system` attribute: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 168 | |
| 169 | |
| 170 | .. method:: ServerProxy.system.listMethods() |
| 171 | |
| 172 | This method returns a list of strings, one for each (non-system) method |
| 173 | supported by the XML-RPC server. |
| 174 | |
| 175 | |
| 176 | .. method:: ServerProxy.system.methodSignature(name) |
| 177 | |
| 178 | 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] | 179 | 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] | 180 | is an array of types. The first of these types is the return type of the method, |
| 181 | the rest are parameters. |
| 182 | |
| 183 | Because multiple signatures (ie. overloading) is permitted, this method returns |
| 184 | a list of signatures rather than a singleton. |
| 185 | |
| 186 | Signatures themselves are restricted to the top level parameters expected by a |
| 187 | method. For instance if a method expects one array of structs as a parameter, |
| 188 | and it returns a string, its signature is simply "string, array". If it expects |
| 189 | three integers and returns a string, its signature is "string, int, int, int". |
| 190 | |
| 191 | If no signature is defined for the method, a non-array value is returned. In |
| 192 | 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] | 193 | than list. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 194 | |
| 195 | |
| 196 | .. method:: ServerProxy.system.methodHelp(name) |
| 197 | |
| 198 | This method takes one parameter, the name of a method implemented by the XML-RPC |
| 199 | server. It returns a documentation string describing the use of that method. If |
| 200 | no such string is available, an empty string is returned. The documentation |
| 201 | string may contain HTML markup. |
| 202 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 203 | |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 204 | A working example follows. The server code:: |
| 205 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 206 | from xmlrpc.server import SimpleXMLRPCServer |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 207 | |
| 208 | def is_even(n): |
| 209 | return n%2 == 0 |
| 210 | |
| 211 | server = SimpleXMLRPCServer(("localhost", 8000)) |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 212 | print("Listening on port 8000...") |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 213 | server.register_function(is_even, "is_even") |
| 214 | server.serve_forever() |
| 215 | |
| 216 | The client code for the preceding server:: |
| 217 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 218 | import xmlrpc.client |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 219 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 220 | proxy = xmlrpc.client.ServerProxy("http://localhost:8000/") |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 221 | print("3 is even: %s" % str(proxy.is_even(3))) |
| 222 | print("100 is even: %s" % str(proxy.is_even(100))) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 223 | |
| 224 | .. _datetime-objects: |
| 225 | |
| 226 | DateTime Objects |
| 227 | ---------------- |
| 228 | |
Christian Heimes | 05e8be1 | 2008-02-23 18:30:17 +0000 | [diff] [blame] | 229 | This class may be initialized with seconds since the epoch, a time |
| 230 | tuple, an ISO 8601 time/date string, or a :class:`datetime.datetime` |
| 231 | instance. It has the following methods, supported mainly for internal |
| 232 | use by the marshalling/unmarshalling code: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 233 | |
| 234 | |
| 235 | .. method:: DateTime.decode(string) |
| 236 | |
| 237 | Accept a string as the instance's new time value. |
| 238 | |
| 239 | |
| 240 | .. method:: DateTime.encode(out) |
| 241 | |
| 242 | Write the XML-RPC encoding of this :class:`DateTime` item to the *out* stream |
| 243 | object. |
| 244 | |
Georg Brandl | 05f5ab7 | 2008-09-24 09:11:47 +0000 | [diff] [blame] | 245 | It also supports certain of Python's built-in operators through rich comparison |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 246 | and :meth:`__repr__` methods. |
| 247 | |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 248 | A working example follows. The server code:: |
| 249 | |
| 250 | import datetime |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 251 | from xmlrpc.server import SimpleXMLRPCServer |
| 252 | import xmlrpc.client |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 253 | |
| 254 | def today(): |
| 255 | today = datetime.datetime.today() |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 256 | return xmlrpc.client.DateTime(today) |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 257 | |
| 258 | server = SimpleXMLRPCServer(("localhost", 8000)) |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 259 | print("Listening on port 8000...") |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 260 | server.register_function(today, "today") |
| 261 | server.serve_forever() |
| 262 | |
| 263 | The client code for the preceding server:: |
| 264 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 265 | import xmlrpc.client |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 266 | import datetime |
| 267 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 268 | proxy = xmlrpc.client.ServerProxy("http://localhost:8000/") |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 269 | |
| 270 | today = proxy.today() |
| 271 | # convert the ISO8601 string to a datetime object |
| 272 | converted = datetime.datetime.strptime(today.value, "%Y%m%dT%H:%M:%S") |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 273 | print("Today: %s" % converted.strftime("%d.%m.%Y, %H:%M")) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 274 | |
| 275 | .. _binary-objects: |
| 276 | |
| 277 | Binary Objects |
| 278 | -------------- |
| 279 | |
Florent Xicluna | 6166519 | 2011-11-15 20:53:25 +0100 | [diff] [blame] | 280 | This class may be initialized from bytes data (which may include NULs). The |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 281 | primary access to the content of a :class:`Binary` object is provided by an |
| 282 | attribute: |
| 283 | |
| 284 | |
| 285 | .. attribute:: Binary.data |
| 286 | |
| 287 | The binary data encapsulated by the :class:`Binary` instance. The data is |
Florent Xicluna | 6166519 | 2011-11-15 20:53:25 +0100 | [diff] [blame] | 288 | provided as a :class:`bytes` object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 289 | |
| 290 | :class:`Binary` objects have the following methods, supported mainly for |
| 291 | internal use by the marshalling/unmarshalling code: |
| 292 | |
| 293 | |
Florent Xicluna | 6166519 | 2011-11-15 20:53:25 +0100 | [diff] [blame] | 294 | .. method:: Binary.decode(bytes) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 295 | |
Florent Xicluna | 6166519 | 2011-11-15 20:53:25 +0100 | [diff] [blame] | 296 | 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] | 297 | |
| 298 | |
| 299 | .. method:: Binary.encode(out) |
| 300 | |
| 301 | Write the XML-RPC base 64 encoding of this binary item to the out stream object. |
| 302 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 303 | The encoded data will have newlines every 76 characters as per |
| 304 | `RFC 2045 section 6.8 <http://tools.ietf.org/html/rfc2045#section-6.8>`_, |
| 305 | which was the de facto standard base64 specification when the |
| 306 | XML-RPC spec was written. |
| 307 | |
Georg Brandl | 05f5ab7 | 2008-09-24 09:11:47 +0000 | [diff] [blame] | 308 | It also supports certain of Python's built-in operators through :meth:`__eq__` |
| 309 | and :meth:`__ne__` methods. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 310 | |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 311 | Example usage of the binary objects. We're going to transfer an image over |
| 312 | XMLRPC:: |
| 313 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 314 | from xmlrpc.server import SimpleXMLRPCServer |
| 315 | import xmlrpc.client |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 316 | |
| 317 | def python_logo(): |
Victor Stinner | 757db83 | 2010-01-30 02:16:55 +0000 | [diff] [blame] | 318 | with open("python_logo.jpg", "rb") as handle: |
| 319 | return xmlrpc.client.Binary(handle.read()) |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 320 | |
| 321 | server = SimpleXMLRPCServer(("localhost", 8000)) |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 322 | print("Listening on port 8000...") |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 323 | server.register_function(python_logo, 'python_logo') |
| 324 | |
| 325 | server.serve_forever() |
| 326 | |
| 327 | The client gets the image and saves it to a file:: |
| 328 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 329 | import xmlrpc.client |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 330 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 331 | proxy = xmlrpc.client.ServerProxy("http://localhost:8000/") |
Victor Stinner | 757db83 | 2010-01-30 02:16:55 +0000 | [diff] [blame] | 332 | with open("fetched_python_logo.jpg", "wb") as handle: |
| 333 | handle.write(proxy.python_logo().data) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 334 | |
| 335 | .. _fault-objects: |
| 336 | |
| 337 | Fault Objects |
| 338 | ------------- |
| 339 | |
| 340 | A :class:`Fault` object encapsulates the content of an XML-RPC fault tag. Fault |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 341 | objects have the following attributes: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 342 | |
| 343 | |
| 344 | .. attribute:: Fault.faultCode |
| 345 | |
| 346 | A string indicating the fault type. |
| 347 | |
| 348 | |
| 349 | .. attribute:: Fault.faultString |
| 350 | |
| 351 | A string containing a diagnostic message associated with the fault. |
| 352 | |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 353 | In the following example we're going to intentionally cause a :exc:`Fault` by |
| 354 | returning a complex type object. The server code:: |
| 355 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 356 | from xmlrpc.server import SimpleXMLRPCServer |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 357 | |
| 358 | # A marshalling error is going to occur because we're returning a |
| 359 | # complex number |
| 360 | def add(x,y): |
| 361 | return x+y+0j |
| 362 | |
| 363 | server = SimpleXMLRPCServer(("localhost", 8000)) |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 364 | print("Listening on port 8000...") |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 365 | server.register_function(add, 'add') |
| 366 | |
| 367 | server.serve_forever() |
| 368 | |
| 369 | The client code for the preceding server:: |
| 370 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 371 | import xmlrpc.client |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 372 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 373 | proxy = xmlrpc.client.ServerProxy("http://localhost:8000/") |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 374 | try: |
| 375 | proxy.add(2, 5) |
Georg Brandl | 0dedf45 | 2009-05-22 16:44:06 +0000 | [diff] [blame] | 376 | except xmlrpc.client.Fault as err: |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 377 | print("A fault occurred") |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 378 | print("Fault code: %d" % err.faultCode) |
| 379 | print("Fault string: %s" % err.faultString) |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 380 | |
| 381 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 382 | |
| 383 | .. _protocol-error-objects: |
| 384 | |
| 385 | ProtocolError Objects |
| 386 | --------------------- |
| 387 | |
| 388 | A :class:`ProtocolError` object describes a protocol error in the underlying |
| 389 | transport layer (such as a 404 'not found' error if the server named by the URI |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 390 | does not exist). It has the following attributes: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 391 | |
| 392 | |
| 393 | .. attribute:: ProtocolError.url |
| 394 | |
| 395 | The URI or URL that triggered the error. |
| 396 | |
| 397 | |
| 398 | .. attribute:: ProtocolError.errcode |
| 399 | |
| 400 | The error code. |
| 401 | |
| 402 | |
| 403 | .. attribute:: ProtocolError.errmsg |
| 404 | |
| 405 | The error message or diagnostic string. |
| 406 | |
| 407 | |
| 408 | .. attribute:: ProtocolError.headers |
| 409 | |
Guido van Rossum | 460add4 | 2007-08-23 02:13:35 +0000 | [diff] [blame] | 410 | A dict containing the headers of the HTTP/HTTPS request that triggered the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 411 | error. |
| 412 | |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 413 | In the following example we're going to intentionally cause a :exc:`ProtocolError` |
| 414 | by providing an invalid URI:: |
| 415 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 416 | import xmlrpc.client |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 417 | |
Benjamin Peterson | 5e55b3e | 2010-02-03 02:35:45 +0000 | [diff] [blame] | 418 | # create a ServerProxy with an URI that doesn't respond to XMLRPC requests |
| 419 | proxy = xmlrpc.client.ServerProxy("http://google.com/") |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 420 | |
| 421 | try: |
| 422 | proxy.some_method() |
Georg Brandl | 0dedf45 | 2009-05-22 16:44:06 +0000 | [diff] [blame] | 423 | except xmlrpc.client.ProtocolError as err: |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 424 | print("A protocol error occurred") |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 425 | print("URL: %s" % err.url) |
| 426 | print("HTTP/HTTPS headers: %s" % err.headers) |
| 427 | print("Error code: %d" % err.errcode) |
| 428 | print("Error message: %s" % err.errmsg) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 429 | |
| 430 | MultiCall Objects |
| 431 | ----------------- |
| 432 | |
Sandro Tosi | 9daf98d | 2011-08-20 17:05:56 +0200 | [diff] [blame] | 433 | The :class:`MultiCall` object provides a way to encapsulate multiple calls to a |
| 434 | remote server into a single request [#]_. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 435 | |
| 436 | |
| 437 | .. class:: MultiCall(server) |
| 438 | |
| 439 | Create an object used to boxcar method calls. *server* is the eventual target of |
| 440 | the call. Calls can be made to the result object, but they will immediately |
| 441 | return ``None``, and only store the call name and parameters in the |
| 442 | :class:`MultiCall` object. Calling the object itself causes all stored calls to |
| 443 | 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] | 444 | is a :term:`generator`; iterating over this generator yields the individual |
| 445 | results. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 446 | |
Andrew Kuchling | c3db373 | 2013-06-20 21:33:05 -0400 | [diff] [blame] | 447 | A usage example of this class follows. The server code:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 448 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 449 | from xmlrpc.server import SimpleXMLRPCServer |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 450 | |
Ezio Melotti | 79016e1 | 2013-08-08 15:45:56 +0300 | [diff] [blame] | 451 | def add(x, y): |
| 452 | return x + y |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 453 | |
| 454 | def subtract(x, y): |
Ezio Melotti | 79016e1 | 2013-08-08 15:45:56 +0300 | [diff] [blame] | 455 | return x - y |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 456 | |
| 457 | def multiply(x, y): |
Ezio Melotti | 79016e1 | 2013-08-08 15:45:56 +0300 | [diff] [blame] | 458 | return x * y |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 459 | |
| 460 | def divide(x, y): |
Andrew Kuchling | c3db373 | 2013-06-20 21:33:05 -0400 | [diff] [blame] | 461 | return x // y |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 462 | |
| 463 | # A simple server with simple arithmetic functions |
| 464 | server = SimpleXMLRPCServer(("localhost", 8000)) |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 465 | print("Listening on port 8000...") |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 466 | server.register_multicall_functions() |
| 467 | server.register_function(add, 'add') |
| 468 | server.register_function(subtract, 'subtract') |
| 469 | server.register_function(multiply, 'multiply') |
| 470 | server.register_function(divide, 'divide') |
| 471 | server.serve_forever() |
| 472 | |
| 473 | The client code for the preceding server:: |
| 474 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 475 | import xmlrpc.client |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 476 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 477 | proxy = xmlrpc.client.ServerProxy("http://localhost:8000/") |
| 478 | multicall = xmlrpc.client.MultiCall(proxy) |
Ezio Melotti | 79016e1 | 2013-08-08 15:45:56 +0300 | [diff] [blame] | 479 | multicall.add(7, 3) |
| 480 | multicall.subtract(7, 3) |
| 481 | multicall.multiply(7, 3) |
| 482 | multicall.divide(7, 3) |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 483 | result = multicall() |
| 484 | |
Ezio Melotti | 79016e1 | 2013-08-08 15:45:56 +0300 | [diff] [blame] | 485 | 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] | 486 | |
| 487 | |
| 488 | Convenience Functions |
| 489 | --------------------- |
| 490 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 491 | .. function:: dumps(params, methodname=None, methodresponse=None, encoding=None, allow_none=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 492 | |
| 493 | Convert *params* into an XML-RPC request. or into a response if *methodresponse* |
| 494 | is true. *params* can be either a tuple of arguments or an instance of the |
| 495 | :exc:`Fault` exception class. If *methodresponse* is true, only a single value |
| 496 | can be returned, meaning that *params* must be of length 1. *encoding*, if |
| 497 | supplied, is the encoding to use in the generated XML; the default is UTF-8. |
| 498 | Python's :const:`None` value cannot be used in standard XML-RPC; to allow using |
| 499 | it via an extension, provide a true value for *allow_none*. |
| 500 | |
| 501 | |
Florent Xicluna | 6166519 | 2011-11-15 20:53:25 +0100 | [diff] [blame] | 502 | .. function:: loads(data, use_datetime=False, use_builtin_types=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 503 | |
| 504 | Convert an XML-RPC request or response into Python objects, a ``(params, |
| 505 | methodname)``. *params* is a tuple of argument; *methodname* is a string, or |
| 506 | ``None`` if no method name is present in the packet. If the XML-RPC packet |
| 507 | represents a fault condition, this function will raise a :exc:`Fault` exception. |
Florent Xicluna | 6166519 | 2011-11-15 20:53:25 +0100 | [diff] [blame] | 508 | The *use_builtin_types* flag can be used to cause date/time values to be |
| 509 | presented as :class:`datetime.datetime` objects and binary data to be |
| 510 | presented as :class:`bytes` objects; this flag is false by default. |
| 511 | |
| 512 | The obsolete *use_datetime* flag is similar to *use_builtin_types* but it |
| 513 | applies only to date/time values. |
| 514 | |
| 515 | .. versionchanged:: 3.3 |
| 516 | The *use_builtin_types* flag was added. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 517 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 518 | |
| 519 | .. _xmlrpc-client-example: |
| 520 | |
| 521 | Example of Client Usage |
| 522 | ----------------------- |
| 523 | |
| 524 | :: |
| 525 | |
| 526 | # simple test program (from the XML-RPC specification) |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 527 | from xmlrpc.client import ServerProxy, Error |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 528 | |
| 529 | # server = ServerProxy("http://localhost:8000") # local server |
| 530 | server = ServerProxy("http://betty.userland.com") |
| 531 | |
Collin Winter | c79461b | 2007-09-01 23:34:30 +0000 | [diff] [blame] | 532 | print(server) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 533 | |
| 534 | try: |
Collin Winter | c79461b | 2007-09-01 23:34:30 +0000 | [diff] [blame] | 535 | print(server.examples.getStateName(41)) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 536 | except Error as v: |
Collin Winter | c79461b | 2007-09-01 23:34:30 +0000 | [diff] [blame] | 537 | print("ERROR", v) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 538 | |
| 539 | To access an XML-RPC server through a proxy, you need to define a custom |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 540 | transport. The following example shows how: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 541 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 542 | .. Example taken from http://lowlife.jp/nobonobo/wiki/xmlrpcwithproxy.html |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 543 | |
| 544 | :: |
| 545 | |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 546 | import xmlrpc.client, http.client |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 547 | |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 548 | class ProxiedTransport(xmlrpc.client.Transport): |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 549 | def set_proxy(self, proxy): |
| 550 | self.proxy = proxy |
| 551 | def make_connection(self, host): |
| 552 | self.realhost = host |
Georg Brandl | 06788c9 | 2009-01-03 21:31:47 +0000 | [diff] [blame] | 553 | h = http.client.HTTP(self.proxy) |
| 554 | return h |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 555 | def send_request(self, connection, handler, request_body): |
| 556 | connection.putrequest("POST", 'http://%s%s' % (self.realhost, handler)) |
| 557 | def send_host(self, connection, host): |
| 558 | connection.putheader('Host', self.realhost) |
| 559 | |
| 560 | p = ProxiedTransport() |
| 561 | p.set_proxy('proxy-server:8080') |
Georg Brandl | 38eceaa | 2008-05-26 11:14:17 +0000 | [diff] [blame] | 562 | server = xmlrpc.client.Server('http://time.xmlrpc.com/RPC2', transport=p) |
Collin Winter | c79461b | 2007-09-01 23:34:30 +0000 | [diff] [blame] | 563 | print(server.currentTime.getCurrentTime()) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 564 | |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 565 | |
| 566 | Example of Client and Server Usage |
| 567 | ---------------------------------- |
| 568 | |
| 569 | See :ref:`simplexmlrpcserver-example`. |
| 570 | |
| 571 | |
Sandro Tosi | 9daf98d | 2011-08-20 17:05:56 +0200 | [diff] [blame] | 572 | .. rubric:: Footnotes |
| 573 | |
| 574 | .. [#] This approach has been first presented in `a discussion on xmlrpc.com |
| 575 | <http://web.archive.org/web/20060624230303/http://www.xmlrpc.com/discuss/msgReader$1208?mode=topic>`_. |
| 576 | .. the link now points to webarchive since the one at |
| 577 | .. http://www.xmlrpc.com/discuss/msgReader%241208 is broken (and webadmin |
| 578 | .. doesn't reply) |