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