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