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}{effbot@telia.com}
   6 \sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
   7
   8 % Not everyting 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}}}}
  22 A \class{ServerProxy} instance is an object that manages communication
  23 with a remote XML-RPC server.  The required first argument is a URI
  24 (Uniform Resource Indicator), and will normally be the URL of the
  25 server.  The optional second argument is a transport factory instance;
  26 by default it is an internal \class{SafeTransport} instance for https:
  27 URLs and an internal HTTP \class{Transport} instance otherwise.  The
  28 optional third argument is an encoding, by default UTF-8. The optional
  29 fourth argument is a debugging flag.
  30
  31 The returned instance is a proxy object with methods that can be used
  32 to invoke corresponding RPC calls on the remote server.  If the remote
  33 server supports the introspection API, the proxy can also be used to query
  34 the remote server for the methods it supports (service discovery) and
  35 fetch other server-associated metadata.
  36
  37 \class{ServerProxy} instance methods take Python basic types and objects as
  38 arguments and return Python basic types and classes.  Types that are
  39 conformable (e.g. that can be marshalled through XML), include the
  40 following (and except where noted, they are unmarshalled as the same
  41 Python type):
  42
  43 \begin{tableii}{l|l}{constant}{Name}{Meaning}
  44   \lineii{boolean}{The \constant{True} and \constant{False} constants}
  45   \lineii{integers}{Pass in directly}
  46   \lineii{floating-point numbers}{Pass in directly}
  47   \lineii{strings}{Pass in directly}
  48   \lineii{arrays}{Any Python sequence type containing conformable
  49                   elements. Arrays are returned as lists}
  50   \lineii{structures}{A Python dictionary. Keys must be strings,
  51                       values may be any conformable type.}
  52   \lineii{dates}{in seconds since the epoch; pass in an instance of the
  53                  \class{DateTime} wrapper class}
  54   \lineii{binary data}{pass in an instance of the \class{Binary}
  55                        wrapper class}
  56 \end{tableii}
  57
  58 This is the full set of data types supported by XML-RPC.  Method calls
  59 may also raise a special \exception{Fault} instance, used to signal
  60 XML-RPC server errors, or \exception{ProtocolError} used to signal an
  61 error in the HTTP/HTTPS transport layer.  Note that even though starting
  62 with Python 2.2 you can subclass builtin types, the xmlrpclib module
  63 currently does not marshal instances of such subclasses.
  64
  65 When passing strings, characters special to XML such as \samp{<},
  66 \samp{>}, and \samp{\&} will be automatically escaped.  However, it's
  67 the caller's responsibility to ensure that the string is free of
  68 characters that aren't allowed in XML, such as the control characters
  69 with ASCII values between 0 and 31; failing to do this will result in
  70 an XML-RPC request that isn't well-formed XML.  If you have to pass
  71 arbitrary strings via XML-RPC, use the \class{Binary} wrapper class
  72 described below.
  73
  74 \class{Server} is retained as an alias for \class{ServerProxy} for backwards
  75 compatibility.  New code should use \class{ServerProxy}.
  76
  77 \end{classdesc}
  78
  79
  80 \begin{seealso}
  81   \seetitle[http://xmlrpc-c.sourceforge.net/xmlrpc-howto/xmlrpc-howto.html]
  82            {XML-RPC HOWTO}{A good description of XML operation and
  83             client software in several languages.  Contains pretty much
  84             everything an XML-RPC client developer needs to know.}
  85   \seetitle[http://xmlrpc-c.sourceforge.net/hacks.php]
  86            {XML-RPC-Hacks page}{Extensions for various open-source
  87             libraries to support instrospection and multicall.}
  88 \end{seealso}
  89
  90
  91 \subsection{ServerProxy Objects \label{serverproxy-objects}}
  92
  93 A \class{ServerProxy} instance has a method corresponding to
  94 each remote procedure call accepted by the XML-RPC server.  Calling
  95 the method performs an RPC, dispatched by both name and argument
  96 signature (e.g. the same method name can be overloaded with multiple
  97 argument signatures).  The RPC finishes by returning a value, which
  98 may be either returned data in a conformant type or a \class{Fault} or
  99 \class{ProtocolError} object indicating an error.
 100
 101 Servers that support the XML introspection API support some common
 102 methods grouped under the reserved \member{system} member:
 103
 104 \begin{methoddesc}{system.listMethods}{}
 105 This method returns a list of strings, one for each (non-system)
 106 method supported by the XML-RPC server.
 107 \end{methoddesc}
 108
 109 \begin{methoddesc}{system.methodSignature}{name}
 110 This method takes one parameter, the name of a method implemented by
 111 the XML-RPC server.It returns an array of possible signatures for this
 112 method. A signature is an array of types. The first of these types is
 113 the return type of the method, the rest are parameters.
 114
 115 Because multiple signatures (ie. overloading) is permitted, this method
 116 returns a list of signatures rather than a singleton.
 117
 118 Signatures themselves are restricted to the top level parameters
 119 expected by a method. For instance if a method expects one array of
 120 structs as a parameter, and it returns a string, its signature is
 121 simply "string, array". If it expects three integers and returns a
 122 string, its signature is "string, int, int, int".
 123
 124 If no signature is defined for the method, a non-array value is
 125 returned. In Python this means that the type of the returned
 126 value will be something other that list.
 127 \end{methoddesc}
 128
 129 \begin{methoddesc}{system.methodHelp}{name}
 130 This method takes one parameter, the name of a method implemented by
 131 the XML-RPC server.  It returns a documentation string describing the
 132 use of that method. If no such string is available, an empty string is
 133 returned. The documentation string may contain HTML markup.
 134 \end{methoddesc}
 135
 136 Introspection methods are currently supported by servers written in
 137 PHP, C and Microsoft .NET. Partial introspection support is included
 138 in recent updates to UserLand Frontier. Introspection support for
 139 Perl, Python and Java is available at the XML-RPC Hacks page.
 140
 141
 142 \subsection{Boolean Objects \label{boolean-objects}}
 143
 144 This class may be initialized from any Python value; the instance
 145 returned depends only on its truth value.  It supports various Python
 146 operators through \method{__cmp__()}, \method{__repr__()},
 147 \method{__int__()}, and \method{__nonzero__()} methods, all
 148 implemented in the obvious ways.
 149
 150 It also has the following method, supported mainly for internal use by
 151 the unmarshalling code:
 152
 153 \begin{methoddesc}{encode}{out}
 154 Write the XML-RPC encoding of this Boolean item to the out stream object.
 155 \end{methoddesc}
 156
 157
 158 \subsection{DateTime Objects \label{datetime-objects}}
 159
 160 This class may initialized from date in seconds since the epoch, a
 161 time tuple, or an ISO 8601 time/date string.  It has the following
 162 methods, supported mainly for internal use by the
 163 marshalling/unmarshalling code:
 164
 165 \begin{methoddesc}{decode}{string}
 166 Accept a string as the instance's new time value.
 167 \end{methoddesc}
 168
 169 \begin{methoddesc}{encode}{out}
 170 Write the XML-RPC encoding of this DateTime item to the out stream object.
 171 \end{methoddesc}
 172
 173 It also supports certain of Python's built-in operators through
 174 \method{_cmp__} and \method{__repr__} methods.
 175
 176
 177 \subsection{Binary Objects \label{binary-objects}}
 178
 179 This class may initialized from string data (which may include NULs).
 180 The primary acess to the content of a \class{Binary} object is
 181 provided by an attribute:
 182
 183 \begin{memberdesc}[Binary]{data}
 184 The binary data encapsulated by the \class{Binary} instance.  The data
 185 is provided as an 8-bit string.
 186 \end{memberdesc}
 187
 188 \class{Binary} objects have the following methods, supported mainly
 189 for internal use by the marshalling/unmarshalling code:
 190
 191 \begin{methoddesc}[Binary]{decode}{string}
 192 Accept a base64 string and decode it as the instance's new data.
 193 \end{methoddesc}
 194
 195 \begin{methoddesc}[Binary]{encode}{out}
 196 Write the XML-RPC base 64 encoding of this binary item to the out
 197 stream object.
 198 \end{methoddesc}
 199
 200 It also supports certain of Python's built-in operators through a
 201 \method{_cmp__()} method.
 202
 203
 204 \subsection{Fault Objects \label{fault-objects}}
 205
 206 A \class{Fault} object encapsulates the content of an XML-RPC fault tag.
 207 Fault objects have the following members:
 208
 209 \begin{memberdesc}{faultCode}
 210 A string indicating the fault type.
 211 \end{memberdesc}
 212
 213 \begin{memberdesc}{faultString}
 214 A string containing a diagnostic message associated with the fault.
 215 \end{memberdesc}
 216
 217
 218 \subsection{ProtocolError Objects \label{protocol-error-objects}}
 219
 220 A \class{ProtocolError} object describes a protocol error in the
 221 underlying transport layer (such as a 404 `not found' error if the
 222 server named by the URI does not exist).  It has the following
 223 members:
 224
 225 \begin{memberdesc}{url}
 226 The URI or URL that triggered the error.
 227 \end{memberdesc}
 228
 229 \begin{memberdesc}{errcode}
 230 The error code.
 231 \end{memberdesc}
 232
 233 \begin{memberdesc}{errmsg}
 234 The error message or diagnostic string.
 235 \end{memberdesc}
 236
 237 \begin{memberdesc}{headers}
 238 A string containing the headers of the HTTP/HTTPS request that
 239 triggered the error.
 240 \end{memberdesc}
 241
 242
 243 \subsection{Convenience Functions}
 244
 245 \begin{funcdesc}{boolean}{value}
 246 Convert any Python value to one of the XML-RPC Boolean constants,
 247 \code{True} or \code{False}.
 248 \end{funcdesc}
 249
 250 \begin{funcdesc}{binary}{data}
 251 Trivially convert any Python string to a \class{Binary} object.
 252 \end{funcdesc}
 253
 254
 255 \subsection{Example of Client Usage \label{xmlrpc-client-example}}
 256
 257 \begin{verbatim}
 258 # simple test program (from the XML-RPC specification)
 259
 260 # server = ServerProxy("http://localhost:8000") # local server
 261 server = ServerProxy("http://betty.userland.com")
 262
 263 print server
 264
 265 try:
 266     print server.examples.getStateName(41)
 267 except Error, v:
 268     print "ERROR", v
 269 \end{verbatim}