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.
  62
  63 When passing strings, characters special to XML such as \samp{<},
  64 \samp{>}, and \samp{\&} will be automatically escaped.  However, it's
  65 the caller's responsibility to ensure that the string is free of
  66 characters that aren't allowed in XML, such as the control characters
  67 with ASCII values between 0 and 31; failing to do this will result in
  68 an XML-RPC request that isn't well-formed XML.  If you have to pass
  69 arbitrary strings via XML-RPC, use the \class{Binary} wrapper class
  70 described below.
  71
  72 \class{Server} is retained as an alias for \class{ServerProxy} for backwards
  73 compatibility.  New code should use \class{ServerProxy}.
  74
  75 \end{classdesc}
  76
  77
  78 \begin{seealso}
  79   \seetitle[http://xmlrpc-c.sourceforge.net/xmlrpc-howto/xmlrpc-howto.html]
  80            {XML-RPC HOWTO}{A good description of XML operation and
  81             client software in several languages.  Contains pretty much
  82             everything an XML-RPC client developer needs to know.}
  83   \seetitle[http://xmlrpc-c.sourceforge.net/hacks.php]
  84            {XML-RPC-Hacks page}{Extensions for various open-source
  85             libraries to support instrospection and multicall.}
  86 \end{seealso}
  87
  88
  89 \subsection{ServerProxy Objects \label{serverproxy-objects}}
  90
  91 A \class{ServerProxy} instance has a method corresponding to
  92 each remote procedure call accepted by the XML-RPC server.  Calling
  93 the method performs an RPC, dispatched by both name and argument
  94 signature (e.g. the same method name can be overloaded with multiple
  95 argument signatures).  The RPC finishes by returning a value, which
  96 may be either returned data in a conformant type or a \class{Fault} or
  97 \class{ProtocolError} object indicating an error.
  98
  99 Servers that support the XML introspection API support some common
 100 methods grouped under the reserved \member{system} member:
 101
 102 \begin{methoddesc}{system.listMethods}{}
 103 This method returns a list of strings, one for each (non-system)
 104 method supported by the XML-RPC server.
 105 \end{methoddesc}
 106
 107 \begin{methoddesc}{system.methodSignature}{name}
 108 This method takes one parameter, the name of a method implemented by
 109 the XML-RPC server.It returns an array of possible signatures for this
 110 method. A signature is an array of types. The first of these types is
 111 the return type of the method, the rest are parameters.
 112
 113 Because multiple signatures (ie. overloading) is permitted, this method
 114 returns a list of signatures rather than a singleton.
 115
 116 Signatures themselves are restricted to the top level parameters
 117 expected by a method. For instance if a method expects one array of
 118 structs as a parameter, and it returns a string, its signature is
 119 simply "string, array". If it expects three integers and returns a
 120 string, its signature is "string, int, int, int".
 121
 122 If no signature is defined for the method, a non-array value is
 123 returned. In Python this means that the type of the returned
 124 value will be something other that list.
 125 \end{methoddesc}
 126
 127 \begin{methoddesc}{system.methodHelp}{name}
 128 This method takes one parameter, the name of a method implemented by
 129 the XML-RPC server.  It returns a documentation string describing the
 130 use of that method. If no such string is available, an empty string is
 131 returned. The documentation string may contain HTML markup.
 132 \end{methoddesc}
 133
 134 Introspection methods are currently supported by servers written in
 135 PHP, C and Microsoft .NET. Partial introspection support is included
 136 in recent updates to UserLand Frontier. Introspection support for
 137 Perl, Python and Java is available at the XML-RPC Hacks page.
 138
 139
 140 \subsection{Boolean Objects \label{boolean-objects}}
 141
 142 This class may be initialized from any Python value; the instance
 143 returned depends only on its truth value.  It supports various Python
 144 operators through \method{__cmp__()}, \method{__repr__()},
 145 \method{__int__()}, and \method{__nonzero__()} methods, all
 146 implemented in the obvious ways.
 147
 148 It also has the following method, supported mainly for internal use by
 149 the unmarshalling code:
 150
 151 \begin{methoddesc}{encode}{out}
 152 Write the XML-RPC encoding of this Boolean item to the out stream object.
 153 \end{methoddesc}
 154
 155
 156 \subsection{DateTime Objects \label{datetime-objects}}
 157
 158 This class may initialized from date in seconds since the epoch, a
 159 time tuple, or an ISO 8601 time/date string.  It has the following
 160 methods, supported mainly for internal use by the
 161 marshalling/unmarshalling code:
 162
 163 \begin{methoddesc}{decode}{string}
 164 Accept a string as the instance's new time value.
 165 \end{methoddesc}
 166
 167 \begin{methoddesc}{encode}{out}
 168 Write the XML-RPC encoding of this DateTime item to the out stream object.
 169 \end{methoddesc}
 170
 171 It also supports certain of Python's built-in operators through
 172 \method{_cmp__} and \method{__repr__} methods.
 173
 174
 175 \subsection{Binary Objects \label{binary-objects}}
 176
 177 This class may initialized from string data (which may include NULs).
 178 It has the following methods, supported mainly for internal use by the
 179 marshalling/unmarshalling code:
 180
 181 \begin{methoddesc}{decode}{string}
 182 Accept a base64 string and decode it as the instance's new data.
 183 \end{methoddesc}
 184
 185 \begin{methoddesc}{encode}{out}
 186 Write the XML-RPC base 64 encoding of this binary item to the out
 187 stream object.
 188 \end{methoddesc}
 189
 190 It also supports certain of Python's built-in operators through a
 191 \method{_cmp__} method.
 192
 193
 194 \subsection{Fault Objects \label{fault-objects}}
 195
 196 A \class{Fault} object encapsulates the content of an XML-RPC fault tag.
 197 Fault objects have the following members:
 198
 199 \begin{memberdesc}{faultCode}
 200 A string indicating the fault type.
 201 \end{memberdesc}
 202
 203 \begin{memberdesc}{faultString}
 204 A string containing a diagnostic message associated with the fault.
 205 \end{memberdesc}
 206
 207
 208 \subsection{ProtocolError Objects \label{protocol-error-objects}}
 209
 210 A \class{ProtocolError} object describes a protocol error in the
 211 underlying transport layer (such as a 404 `not found' error if the
 212 server named by the URI does not exist).  It has the following
 213 members:
 214
 215 \begin{memberdesc}{url}
 216 The URI or URL that triggered the error.
 217 \end{memberdesc}
 218
 219 \begin{memberdesc}{errcode}
 220 The error code.
 221 \end{memberdesc}
 222
 223 \begin{memberdesc}{errmsg}
 224 The error message or diagnostic string.
 225 \end{memberdesc}
 226
 227 \begin{memberdesc}{headers}
 228 A string containing the headers of the HTTP/HTTPS request that
 229 triggered the error.
 230 \end{memberdesc}
 231
 232
 233 \subsection{Convenience Functions}
 234
 235 \begin{funcdesc}{boolean}{value}
 236 Convert any Python value to one of the XML-RPC Boolean constants,
 237 \code{True} or \code{False}.
 238 \end{funcdesc}
 239
 240 \begin{funcdesc}{binary}{data}
 241 Trivially convert any Python string to a \class{Binary} object.
 242 \end{funcdesc}
 243
 244
 245 \subsection{Example of Client Usage \label{xmlrpc-client-example}}
 246
 247 \begin{verbatim}
 248 # simple test program (from the XML-RPC specification)
 249
 250 # server = ServerProxy("http://localhost:8000") # local server
 251 server = ServerProxy("http://betty.userland.com")
 252
 253 print server
 254
 255 try:
 256     print server.examples.getStateName(41)
 257 except Error, v:
 258     print "ERROR", v
 259 \end{verbatim}