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