Doc/lib/libxmlrpclib.tex

   1 \section{\module{xmlrpclib} --- XML-RPC client access}
   2
   3 \declaremodule{standard}{xmlrpclib}
   4 \modulesynopsis{XML-RPC client access.}
   5 \moduleauthor{Fredrik Lundh}{fredrik@pythonware.com}
   6 \sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
   7
   8 % Not everything is documented yet.  It might be good to describe
   9 % Marshaller, Unmarshaller, getparser, dumps, loads, and Transport.
  10
  11 \versionadded{2.2}
  12
  13 XML-RPC is a Remote Procedure Call method that uses XML passed via
  14 HTTP as a transport.  With it, a client can call methods with
  15 parameters on a remote server (the server is named by a URI) and get back
  16 structured data.  This module supports writing XML-RPC client code; it
  17 handles all the details of translating between conformable Python
  18 objects and XML on the wire.
  19
  20 \begin{classdesc}{ServerProxy}{uri\optional{, transport\optional{,
  21                                encoding\optional{, verbose\optional{,
  22                                allow_none\optional{, use_datetime}}}}}}
  23 A \class{ServerProxy} instance is an object that manages communication
  24 with a remote XML-RPC server.  The required first argument is a URI
  25 (Uniform Resource Indicator), and will normally be the URL of the
  26 server.  The optional second argument is a transport factory instance;
  27 by default it is an internal \class{SafeTransport} instance for https:
  28 URLs and an internal HTTP \class{Transport} instance otherwise.  The
  29 optional third argument is an encoding, by default UTF-8. The optional
  30 fourth argument is a debugging flag.  If \var{allow_none} is true,
  31 the Python constant \code{None} will be translated into XML; the
  32 default behaviour is for \code{None} to raise a \exception{TypeError}.
  33 This is a commonly-used extension to the XML-RPC specification, but isn't
  34 supported by all clients and servers; see
  35 \url{http://ontosys.com/xml-rpc/extensions.php} for a description.
  36 The \var{use_datetime} flag can be used to cause date/time values to be
  37 presented as \class{\refmodule{datetime}.datetime} objects; this is false
  38 by default.  \class{\refmodule{datetime}.datetime},
  39 \class{\refmodule{datetime}.date} and \class{\refmodule{datetime}.time}
  40 objects may be passed to calls.  \class{\refmodule{datetime}.date} objects
  41 are converted with a time of ``00:00:00''.
  42 \class{\refmodule{datetime}.time} objects are converted using today's date.
  43
  44 Both the HTTP and HTTPS transports support the URL syntax extension for
  45 HTTP Basic Authentication: \code{http://user:pass@host:port/path}.  The
  46 \code{user:pass} portion will be base64-encoded as an HTTP `Authorization'
  47 header, and sent to the remote server as part of the connection process
  48 when invoking an XML-RPC method.  You only need to use this if the
  49 remote server requires a Basic Authentication user and password.
  50
  51 The returned instance is a proxy object with methods that can be used
  52 to invoke corresponding RPC calls on the remote server.  If the remote
  53 server supports the introspection API, the proxy can also be used to query
  54 the remote server for the methods it supports (service discovery) and
  55 fetch other server-associated metadata.
  56
  57 \class{ServerProxy} instance methods take Python basic types and objects as
  58 arguments and return Python basic types and classes.  Types that are
  59 conformable (e.g. that can be marshalled through XML), include the
  60 following (and except where noted, they are unmarshalled as the same
  61 Python type):
  62
  63 \begin{tableii}{l|l}{constant}{Name}{Meaning}
  64   \lineii{boolean}{The \constant{True} and \constant{False} constants}
  65   \lineii{integers}{Pass in directly}
  66   \lineii{floating-point numbers}{Pass in directly}
  67   \lineii{strings}{Pass in directly}
  68   \lineii{arrays}{Any Python sequence type containing conformable
  69                   elements. Arrays are returned as lists}
  70   \lineii{structures}{A Python dictionary. Keys must be strings,
  71                       values may be any conformable type. Objects
  72                       of user-defined classes can be passed in;
  73                       only their \var{__dict__} attribute is
  74                       transmitted.}
  75   \lineii{dates}{in seconds since the epoch (pass in an instance of the
  76                  \class{DateTime} class) or a
  77                  \class{\refmodule{datetime}.datetime},
  78                  \class{\refmodule{datetime}.date} or
  79                  \class{\refmodule{datetime}.time} instance}
  80   \lineii{binary data}{pass in an instance of the \class{Binary}
  81                        wrapper class}
  82 \end{tableii}
  83
  84 This is the full set of data types supported by XML-RPC.  Method calls
  85 may also raise a special \exception{Fault} instance, used to signal
  86 XML-RPC server errors, or \exception{ProtocolError} used to signal an
  87 error in the HTTP/HTTPS transport layer.  Both \exception{Fault} and
  88 \exception{ProtocolError} derive from a base class called
  89 \exception{Error}.  Note that even though starting with Python 2.2 you
  90 can subclass builtin types, the xmlrpclib module currently does not
  91 marshal instances of such subclasses.
  92
  93 When passing strings, characters special to XML such as \samp{<},
  94 \samp{>}, and \samp{\&} will be automatically escaped.  However, it's
  95 the caller's responsibility to ensure that the string is free of
  96 characters that aren't allowed in XML, such as the control characters
  97 with ASCII values between 0 and 31; failing to do this will result in
  98 an XML-RPC request that isn't well-formed XML.  If you have to pass
  99 arbitrary strings via XML-RPC, use the \class{Binary} wrapper class
 100 described below.
 101
 102 \class{Server} is retained as an alias for \class{ServerProxy} for backwards
 103 compatibility.  New code should use \class{ServerProxy}.
 104
 105 \versionchanged[The \var{use_datetime} flag was added]{2.5}
 106
 107 \versionchanged[Instances of new-style classes can be passed in
 108 if they have an \var{__dict__} attribute and don't have a base class
 109 that is marshalled in a special way]{2.6}
 110 \end{classdesc}
 111
 112
 113 \begin{seealso}
 114   \seetitle[http://www.tldp.org/HOWTO/XML-RPC-HOWTO/index.html]
 115            {XML-RPC HOWTO}{A good description of XML operation and
 116             client software in several languages.  Contains pretty much
 117             everything an XML-RPC client developer needs to know.}
 118   \seetitle[http://xmlrpc-c.sourceforge.net/hacks.php]
 119            {XML-RPC Hacks page}{Extensions for various open-source
 120             libraries to support introspection and multicall.}
 121 \end{seealso}
 122
 123
 124 \subsection{ServerProxy Objects \label{serverproxy-objects}}
 125
 126 A \class{ServerProxy} instance has a method corresponding to
 127 each remote procedure call accepted by the XML-RPC server.  Calling
 128 the method performs an RPC, dispatched by both name and argument
 129 signature (e.g. the same method name can be overloaded with multiple
 130 argument signatures).  The RPC finishes by returning a value, which
 131 may be either returned data in a conformant type or a \class{Fault} or
 132 \class{ProtocolError} object indicating an error.
 133
 134 Servers that support the XML introspection API support some common
 135 methods grouped under the reserved \member{system} member:
 136
 137 \begin{methoddesc}{system.listMethods}{}
 138 This method returns a list of strings, one for each (non-system)
 139 method supported by the XML-RPC server.
 140 \end{methoddesc}
 141
 142 \begin{methoddesc}{system.methodSignature}{name}
 143 This method takes one parameter, the name of a method implemented by
 144 the XML-RPC server.It returns an array of possible signatures for this
 145 method. A signature is an array of types. The first of these types is
 146 the return type of the method, the rest are parameters.
 147
 148 Because multiple signatures (ie. overloading) is permitted, this method
 149 returns a list of signatures rather than a singleton.
 150
 151 Signatures themselves are restricted to the top level parameters
 152 expected by a method. For instance if a method expects one array of
 153 structs as a parameter, and it returns a string, its signature is
 154 simply "string, array". If it expects three integers and returns a
 155 string, its signature is "string, int, int, int".
 156
 157 If no signature is defined for the method, a non-array value is
 158 returned. In Python this means that the type of the returned
 159 value will be something other that list.
 160 \end{methoddesc}
 161
 162 \begin{methoddesc}{system.methodHelp}{name}
 163 This method takes one parameter, the name of a method implemented by
 164 the XML-RPC server.  It returns a documentation string describing the
 165 use of that method. If no such string is available, an empty string is
 166 returned. The documentation string may contain HTML markup.
 167 \end{methoddesc}
 168
 169 Introspection methods are currently supported by servers written in
 170 PHP, C and Microsoft .NET. Partial introspection support is included
 171 in recent updates to UserLand Frontier. Introspection support for
 172 Perl, Python and Java is available at the \ulink{XML-RPC
 173 Hacks}{http://xmlrpc-c.sourceforge.net/hacks.php} page.
 174
 175
 176 \subsection{Boolean Objects \label{boolean-objects}}
 177
 178 This class may be initialized from any Python value; the instance
 179 returned depends only on its truth value.  It supports various Python
 180 operators through \method{__cmp__()}, \method{__repr__()},
 181 \method{__int__()}, and \method{__nonzero__()} methods, all
 182 implemented in the obvious ways.
 183
 184 It also has the following method, supported mainly for internal use by
 185 the unmarshalling code:
 186
 187 \begin{methoddesc}{encode}{out}
 188 Write the XML-RPC encoding of this Boolean item to the out stream object.
 189 \end{methoddesc}
 190
 191
 192 \subsection{DateTime Objects \label{datetime-objects}}
 193
 194 This class may be initialized with seconds since the epoch, a time tuple, an
 195 ISO 8601 time/date string, or a {}\class{\refmodule{datetime}.datetime},
 196 {}\class{\refmodule{datetime}.date} or {}\class{\refmodule{datetime}.time}
 197 instance.  It has the following methods, supported mainly for internal use
 198 by the marshalling/unmarshalling code:
 199
 200 \begin{methoddesc}{decode}{string}
 201 Accept a string as the instance's new time value.
 202 \end{methoddesc}
 203
 204 \begin{methoddesc}{encode}{out}
 205 Write the XML-RPC encoding of this \class{DateTime} item to the
 206 \var{out} stream object.
 207 \end{methoddesc}
 208
 209 It also supports certain of Python's built-in operators through
 210 \method{__cmp__()} and \method{__repr__()} methods.
 211
 212
 213 \subsection{Binary Objects \label{binary-objects}}
 214
 215 This class may be initialized from string data (which may include NULs).
 216 The primary access to the content of a \class{Binary} object is
 217 provided by an attribute:
 218
 219 \begin{memberdesc}[Binary]{data}
 220 The binary data encapsulated by the \class{Binary} instance.  The data
 221 is provided as an 8-bit string.
 222 \end{memberdesc}
 223
 224 \class{Binary} objects have the following methods, supported mainly
 225 for internal use by the marshalling/unmarshalling code:
 226
 227 \begin{methoddesc}[Binary]{decode}{string}
 228 Accept a base64 string and decode it as the instance's new data.
 229 \end{methoddesc}
 230
 231 \begin{methoddesc}[Binary]{encode}{out}
 232 Write the XML-RPC base 64 encoding of this binary item to the out
 233 stream object.
 234 \end{methoddesc}
 235
 236 It also supports certain of Python's built-in operators through a
 237 \method{__cmp__()} method.
 238
 239
 240 \subsection{Fault Objects \label{fault-objects}}
 241
 242 A \class{Fault} object encapsulates the content of an XML-RPC fault tag.
 243 Fault objects have the following members:
 244
 245 \begin{memberdesc}{faultCode}
 246 A string indicating the fault type.
 247 \end{memberdesc}
 248
 249 \begin{memberdesc}{faultString}
 250 A string containing a diagnostic message associated with the fault.
 251 \end{memberdesc}
 252
 253
 254 \subsection{ProtocolError Objects \label{protocol-error-objects}}
 255
 256 A \class{ProtocolError} object describes a protocol error in the
 257 underlying transport layer (such as a 404 `not found' error if the
 258 server named by the URI does not exist).  It has the following
 259 members:
 260
 261 \begin{memberdesc}{url}
 262 The URI or URL that triggered the error.
 263 \end{memberdesc}
 264
 265 \begin{memberdesc}{errcode}
 266 The error code.
 267 \end{memberdesc}
 268
 269 \begin{memberdesc}{errmsg}
 270 The error message or diagnostic string.
 271 \end{memberdesc}
 272
 273 \begin{memberdesc}{headers}
 274 A string containing the headers of the HTTP/HTTPS request that
 275 triggered the error.
 276 \end{memberdesc}
 277
 278 \subsection{MultiCall Objects}
 279
 280 \versionadded{2.4}
 281
 282 In \url{http://www.xmlrpc.com/discuss/msgReader\%241208}, an approach
 283 is presented to encapsulate multiple calls to a remote server into a
 284 single request.
 285
 286 \begin{classdesc}{MultiCall}{server}
 287
 288 Create an object used to boxcar method calls. \var{server} is the
 289 eventual target of the call. Calls can be made to the result object,
 290 but they will immediately return \var{None}, and only store the
 291 call name and parameters in the \class{MultiCall} object. Calling
 292 the object itself causes all stored calls to be transmitted as
 293 a single \code{system.multicall} request. The result of this call
 294 is a generator; iterating over this generator yields the individual
 295 results.
 296
 297 \end{classdesc}
 298
 299 A usage example of this class is
 300
 301 \begin{verbatim}
 302 multicall = MultiCall(server_proxy)
 303 multicall.add(2,3)
 304 multicall.get_address("Guido")
 305 add_result, address = multicall()
 306 \end{verbatim}
 307
 308 \subsection{Convenience Functions}
 309
 310 \begin{funcdesc}{boolean}{value}
 311 Convert any Python value to one of the XML-RPC Boolean constants,
 312 \code{True} or \code{False}.
 313 \end{funcdesc}
 314
 315 \begin{funcdesc}{dumps}{params\optional{, methodname\optional{,
 316                         methodresponse\optional{, encoding\optional{,
 317                         allow_none}}}}}
 318 Convert \var{params} into an XML-RPC request.
 319 or into a response if \var{methodresponse} is true.
 320 \var{params} can be either a tuple of arguments or an instance of the
 321 \exception{Fault} exception class.  If \var{methodresponse} is true,
 322 only a single value can be returned, meaning that \var{params} must be of length 1.
 323 \var{encoding}, if supplied, is the encoding to use in the generated
 324 XML; the default is UTF-8.  Python's \constant{None} value cannot be
 325 used in standard XML-RPC; to allow using it via an extension,
 326 provide a true value for \var{allow_none}.
 327 \end{funcdesc}
 328
 329 \begin{funcdesc}{loads}{data\optional{, use_datetime}}
 330 Convert an XML-RPC request or response into Python objects, a
 331 \code{(\var{params}, \var{methodname})}.  \var{params} is a tuple of argument; \var{methodname}
 332 is a string, or \code{None} if no method name is present in the packet.
 333 If the XML-RPC packet represents a fault condition, this
 334 function will raise a \exception{Fault} exception.
 335 The \var{use_datetime} flag can be used to cause date/time values to be
 336 presented as \class{\refmodule{datetime}.datetime} objects; this is false
 337 by default.
 338 Note that even if you call an XML-RPC method with
 339 \class{\refmodule{datetime}.date} or \class{\refmodule{datetime}.time}
 340 objects, they are converted to \class{DateTime} objects internally, so only
 341 {}\class{\refmodule{datetime}.datetime} objects will be returned.
 342
 343 \versionchanged[The \var{use_datetime} flag was added]{2.5}
 344 \end{funcdesc}
 345
 346
 347
 348 \subsection{Example of Client Usage \label{xmlrpc-client-example}}
 349
 350 \begin{verbatim}
 351 # simple test program (from the XML-RPC specification)
 352 from xmlrpclib import ServerProxy, Error
 353
 354 # server = ServerProxy("http://localhost:8000") # local server
 355 server = ServerProxy("http://betty.userland.com")
 356
 357 print server
 358
 359 try:
 360     print server.examples.getStateName(41)
 361 except Error, v:
 362     print "ERROR", v
 363 \end{verbatim}
 364
 365 To access an XML-RPC server through a proxy, you need to define
 366 a custom transport.  The following example,
 367 written by NoboNobo, % fill in original author's name if we ever learn it
 368 shows how:
 369
 370 % Example taken from http://lowlife.jp/nobonobo/wiki/xmlrpcwithproxy.html
 371 \begin{verbatim}
 372 import xmlrpclib, httplib
 373
 374 class ProxiedTransport(xmlrpclib.Transport):
 375     def set_proxy(self, proxy):
 376         self.proxy = proxy
 377     def make_connection(self, host):
 378         self.realhost = host
 379         h = httplib.HTTP(self.proxy)
 380         return h
 381     def send_request(self, connection, handler, request_body):
 382         connection.putrequest("POST", 'http://%s%s' % (self.realhost, handler))
 383     def send_host(self, connection, host):
 384         connection.putheader('Host', self.realhost)
 385
 386 p = ProxiedTransport()
 387 p.set_proxy('proxy-server:8080')
 388 server = xmlrpclib.Server('http://time.xmlrpc.com/RPC2', transport=p)
 389 print server.currentTime.getCurrentTime()
 390 \end{verbatim}