270 lines
10 KiB
TeX
270 lines
10 KiB
TeX
\section{\module{xmlrpclib} --- XML-RPC client access}
|
|
|
|
\declaremodule{standard}{xmlrpclib}
|
|
\modulesynopsis{XML-RPC client access.}
|
|
\moduleauthor{Fredrik Lundh}{effbot@telia.com}
|
|
\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
|
|
|
|
% Not everyting is documented yet. It might be good to describe
|
|
% Marshaller, Unmarshaller, getparser, dumps, loads, and Transport.
|
|
|
|
\versionadded{2.2}
|
|
|
|
XML-RPC is a Remote Procedure Call method that uses XML passed via
|
|
HTTP as a transport. With it, a client can call methods with
|
|
parameters on a remote server (the server is named by a URI) and get back
|
|
structured data. This module supports writing XML-RPC client code; it
|
|
handles all the details of translating between conformable Python
|
|
objects and XML on the wire.
|
|
|
|
\begin{classdesc}{ServerProxy}{uri\optional{, transport\optional{,
|
|
encoding\optional{, verbose}}}}
|
|
A \class{ServerProxy} instance is an object that manages communication
|
|
with a remote XML-RPC server. The required first argument is a URI
|
|
(Uniform Resource Indicator), and will normally be the URL of the
|
|
server. The optional second argument is a transport factory instance;
|
|
by default it is an internal \class{SafeTransport} instance for https:
|
|
URLs and an internal HTTP \class{Transport} instance otherwise. The
|
|
optional third argument is an encoding, by default UTF-8. The optional
|
|
fourth argument is a debugging flag.
|
|
|
|
The returned instance is a proxy object with methods that can be used
|
|
to invoke corresponding RPC calls on the remote server. If the remote
|
|
server supports the introspection API, the proxy can also be used to query
|
|
the remote server for the methods it supports (service discovery) and
|
|
fetch other server-associated metadata.
|
|
|
|
\class{ServerProxy} instance methods take Python basic types and objects as
|
|
arguments and return Python basic types and classes. Types that are
|
|
conformable (e.g. that can be marshalled through XML), include the
|
|
following (and except where noted, they are unmarshalled as the same
|
|
Python type):
|
|
|
|
\begin{tableii}{l|l}{constant}{Name}{Meaning}
|
|
\lineii{boolean}{The \constant{True} and \constant{False} constants}
|
|
\lineii{integers}{Pass in directly}
|
|
\lineii{floating-point numbers}{Pass in directly}
|
|
\lineii{strings}{Pass in directly}
|
|
\lineii{arrays}{Any Python sequence type containing conformable
|
|
elements. Arrays are returned as lists}
|
|
\lineii{structures}{A Python dictionary. Keys must be strings,
|
|
values may be any conformable type.}
|
|
\lineii{dates}{in seconds since the epoch; pass in an instance of the
|
|
\class{DateTime} wrapper class}
|
|
\lineii{binary data}{pass in an instance of the \class{Binary}
|
|
wrapper class}
|
|
\end{tableii}
|
|
|
|
This is the full set of data types supported by XML-RPC. Method calls
|
|
may also raise a special \exception{Fault} instance, used to signal
|
|
XML-RPC server errors, or \exception{ProtocolError} used to signal an
|
|
error in the HTTP/HTTPS transport layer. Note that even though starting
|
|
with Python 2.2 you can subclass builtin types, the xmlrpclib module
|
|
currently does not marshal instances of such subclasses.
|
|
|
|
When passing strings, characters special to XML such as \samp{<},
|
|
\samp{>}, and \samp{\&} will be automatically escaped. However, it's
|
|
the caller's responsibility to ensure that the string is free of
|
|
characters that aren't allowed in XML, such as the control characters
|
|
with ASCII values between 0 and 31; failing to do this will result in
|
|
an XML-RPC request that isn't well-formed XML. If you have to pass
|
|
arbitrary strings via XML-RPC, use the \class{Binary} wrapper class
|
|
described below.
|
|
|
|
\class{Server} is retained as an alias for \class{ServerProxy} for backwards
|
|
compatibility. New code should use \class{ServerProxy}.
|
|
|
|
\end{classdesc}
|
|
|
|
|
|
\begin{seealso}
|
|
\seetitle[http://xmlrpc-c.sourceforge.net/xmlrpc-howto/xmlrpc-howto.html]
|
|
{XML-RPC HOWTO}{A good description of XML operation and
|
|
client software in several languages. Contains pretty much
|
|
everything an XML-RPC client developer needs to know.}
|
|
\seetitle[http://xmlrpc-c.sourceforge.net/hacks.php]
|
|
{XML-RPC-Hacks page}{Extensions for various open-source
|
|
libraries to support instrospection and multicall.}
|
|
\end{seealso}
|
|
|
|
|
|
\subsection{ServerProxy Objects \label{serverproxy-objects}}
|
|
|
|
A \class{ServerProxy} instance has a method corresponding to
|
|
each remote procedure call accepted by the XML-RPC server. Calling
|
|
the method performs an RPC, dispatched by both name and argument
|
|
signature (e.g. the same method name can be overloaded with multiple
|
|
argument signatures). The RPC finishes by returning a value, which
|
|
may be either returned data in a conformant type or a \class{Fault} or
|
|
\class{ProtocolError} object indicating an error.
|
|
|
|
Servers that support the XML introspection API support some common
|
|
methods grouped under the reserved \member{system} member:
|
|
|
|
\begin{methoddesc}{system.listMethods}{}
|
|
This method returns a list of strings, one for each (non-system)
|
|
method supported by the XML-RPC server.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{system.methodSignature}{name}
|
|
This method takes one parameter, the name of a method implemented by
|
|
the XML-RPC server.It returns an array of possible signatures for this
|
|
method. A signature is an array of types. The first of these types is
|
|
the return type of the method, the rest are parameters.
|
|
|
|
Because multiple signatures (ie. overloading) is permitted, this method
|
|
returns a list of signatures rather than a singleton.
|
|
|
|
Signatures themselves are restricted to the top level parameters
|
|
expected by a method. For instance if a method expects one array of
|
|
structs as a parameter, and it returns a string, its signature is
|
|
simply "string, array". If it expects three integers and returns a
|
|
string, its signature is "string, int, int, int".
|
|
|
|
If no signature is defined for the method, a non-array value is
|
|
returned. In Python this means that the type of the returned
|
|
value will be something other that list.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{system.methodHelp}{name}
|
|
This method takes one parameter, the name of a method implemented by
|
|
the XML-RPC server. It returns a documentation string describing the
|
|
use of that method. If no such string is available, an empty string is
|
|
returned. The documentation string may contain HTML markup.
|
|
\end{methoddesc}
|
|
|
|
Introspection methods are currently supported by servers written in
|
|
PHP, C and Microsoft .NET. Partial introspection support is included
|
|
in recent updates to UserLand Frontier. Introspection support for
|
|
Perl, Python and Java is available at the XML-RPC Hacks page.
|
|
|
|
|
|
\subsection{Boolean Objects \label{boolean-objects}}
|
|
|
|
This class may be initialized from any Python value; the instance
|
|
returned depends only on its truth value. It supports various Python
|
|
operators through \method{__cmp__()}, \method{__repr__()},
|
|
\method{__int__()}, and \method{__nonzero__()} methods, all
|
|
implemented in the obvious ways.
|
|
|
|
It also has the following method, supported mainly for internal use by
|
|
the unmarshalling code:
|
|
|
|
\begin{methoddesc}{encode}{out}
|
|
Write the XML-RPC encoding of this Boolean item to the out stream object.
|
|
\end{methoddesc}
|
|
|
|
|
|
\subsection{DateTime Objects \label{datetime-objects}}
|
|
|
|
This class may initialized from date in seconds since the epoch, a
|
|
time tuple, or an ISO 8601 time/date string. It has the following
|
|
methods, supported mainly for internal use by the
|
|
marshalling/unmarshalling code:
|
|
|
|
\begin{methoddesc}{decode}{string}
|
|
Accept a string as the instance's new time value.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{encode}{out}
|
|
Write the XML-RPC encoding of this DateTime item to the out stream object.
|
|
\end{methoddesc}
|
|
|
|
It also supports certain of Python's built-in operators through
|
|
\method{_cmp__} and \method{__repr__} methods.
|
|
|
|
|
|
\subsection{Binary Objects \label{binary-objects}}
|
|
|
|
This class may initialized from string data (which may include NULs).
|
|
The primary acess to the content of a \class{Binary} object is
|
|
provided by an attribute:
|
|
|
|
\begin{memberdesc}[Binary]{data}
|
|
The binary data encapsulated by the \class{Binary} instance. The data
|
|
is provided as an 8-bit string.
|
|
\end{memberdesc}
|
|
|
|
\class{Binary} objects have the following methods, supported mainly
|
|
for internal use by the marshalling/unmarshalling code:
|
|
|
|
\begin{methoddesc}[Binary]{decode}{string}
|
|
Accept a base64 string and decode it as the instance's new data.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[Binary]{encode}{out}
|
|
Write the XML-RPC base 64 encoding of this binary item to the out
|
|
stream object.
|
|
\end{methoddesc}
|
|
|
|
It also supports certain of Python's built-in operators through a
|
|
\method{_cmp__()} method.
|
|
|
|
|
|
\subsection{Fault Objects \label{fault-objects}}
|
|
|
|
A \class{Fault} object encapsulates the content of an XML-RPC fault tag.
|
|
Fault objects have the following members:
|
|
|
|
\begin{memberdesc}{faultCode}
|
|
A string indicating the fault type.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{faultString}
|
|
A string containing a diagnostic message associated with the fault.
|
|
\end{memberdesc}
|
|
|
|
|
|
\subsection{ProtocolError Objects \label{protocol-error-objects}}
|
|
|
|
A \class{ProtocolError} object describes a protocol error in the
|
|
underlying transport layer (such as a 404 `not found' error if the
|
|
server named by the URI does not exist). It has the following
|
|
members:
|
|
|
|
\begin{memberdesc}{url}
|
|
The URI or URL that triggered the error.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{errcode}
|
|
The error code.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{errmsg}
|
|
The error message or diagnostic string.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{headers}
|
|
A string containing the headers of the HTTP/HTTPS request that
|
|
triggered the error.
|
|
\end{memberdesc}
|
|
|
|
|
|
\subsection{Convenience Functions}
|
|
|
|
\begin{funcdesc}{boolean}{value}
|
|
Convert any Python value to one of the XML-RPC Boolean constants,
|
|
\code{True} or \code{False}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{binary}{data}
|
|
Trivially convert any Python string to a \class{Binary} object.
|
|
\end{funcdesc}
|
|
|
|
|
|
\subsection{Example of Client Usage \label{xmlrpc-client-example}}
|
|
|
|
\begin{verbatim}
|
|
# simple test program (from the XML-RPC specification)
|
|
|
|
# server = ServerProxy("http://localhost:8000") # local server
|
|
server = ServerProxy("http://betty.userland.com")
|
|
|
|
print server
|
|
|
|
try:
|
|
print server.examples.getStateName(41)
|
|
except Error, v:
|
|
print "ERROR", v
|
|
\end{verbatim}
|