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