diff options
Diffstat (limited to 'Doc/lib/libxmlrpclib.tex')
| -rw-r--r-- | Doc/lib/libxmlrpclib.tex | 391 |
1 files changed, 0 insertions, 391 deletions
diff --git a/Doc/lib/libxmlrpclib.tex b/Doc/lib/libxmlrpclib.tex deleted file mode 100644 index fdd4e72..0000000 --- a/Doc/lib/libxmlrpclib.tex +++ /dev/null @@ -1,391 +0,0 @@ -\section{\module{xmlrpclib} --- XML-RPC client access} - -\declaremodule{standard}{xmlrpclib} -\modulesynopsis{XML-RPC client access.} -\moduleauthor{Fredrik Lundh}{fredrik@pythonware.com} -\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com} - -% Not everything 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\optional{, - allow_none\optional{, use_datetime}}}}}} -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. If \var{allow_none} is true, -the Python constant \code{None} will be translated into XML; the -default behaviour is for \code{None} to raise a \exception{TypeError}. -This is a commonly-used extension to the XML-RPC specification, but isn't -supported by all clients and servers; see -\url{http://ontosys.com/xml-rpc/extensions.php} for a description. -The \var{use_datetime} flag can be used to cause date/time values to be -presented as \class{\refmodule{datetime}.datetime} objects; this is false -by default. \class{\refmodule{datetime}.datetime}, -\class{\refmodule{datetime}.date} and \class{\refmodule{datetime}.time} -objects may be passed to calls. \class{\refmodule{datetime}.date} objects -are converted with a time of ``00:00:00''. -\class{\refmodule{datetime}.time} objects are converted using today's date. - -Both the HTTP and HTTPS transports support the URL syntax extension for -HTTP Basic Authentication: \code{http://user:pass@host:port/path}. The -\code{user:pass} portion will be base64-encoded as an HTTP `Authorization' -header, and sent to the remote server as part of the connection process -when invoking an XML-RPC method. You only need to use this if the -remote server requires a Basic Authentication user and password. - -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. Objects - of user-defined classes can be passed in; - only their \var{__dict__} attribute is - transmitted.} - \lineii{dates}{in seconds since the epoch (pass in an instance of the - \class{DateTime} class) or a - \class{\refmodule{datetime}.datetime}, - \class{\refmodule{datetime}.date} or - \class{\refmodule{datetime}.time} instance} - \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. Both \exception{Fault} and -\exception{ProtocolError} derive from a base class called -\exception{Error}. 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 (except, of course, tab, newline and -carriage return); 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}. - -\versionchanged[The \var{use_datetime} flag was added]{2.5} - -\versionchanged[Instances of new-style classes can be passed in -if they have an \var{__dict__} attribute and don't have a base class -that is marshalled in a special way]{2.6} -\end{classdesc} - - -\begin{seealso} - \seetitle[http://www.tldp.org/HOWTO/XML-RPC-HOWTO/index.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 introspection 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}[ServerProxy]{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}[ServerProxy]{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}[ServerProxy]{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 \ulink{XML-RPC -Hacks}{http://xmlrpc-c.sourceforge.net/hacks.php} 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}[Boolean]{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 be initialized with seconds since the epoch, a time tuple, an -ISO 8601 time/date string, or a {}\class{\refmodule{datetime}.datetime}, -{}\class{\refmodule{datetime}.date} or {}\class{\refmodule{datetime}.time} -instance. It has the following methods, supported mainly for internal use -by the marshalling/unmarshalling code: - -\begin{methoddesc}[DateTime]{decode}{string} -Accept a string as the instance's new time value. -\end{methoddesc} - -\begin{methoddesc}[DateTime]{encode}{out} -Write the XML-RPC encoding of this \class{DateTime} item to the -\var{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 be initialized from string data (which may include NULs). -The primary access 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}[Fault]{faultCode} -A string indicating the fault type. -\end{memberdesc} - -\begin{memberdesc}[Fault]{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}[ProtocolError]{url} -The URI or URL that triggered the error. -\end{memberdesc} - -\begin{memberdesc}[ProtocolError]{errcode} -The error code. -\end{memberdesc} - -\begin{memberdesc}[ProtocolError]{errmsg} -The error message or diagnostic string. -\end{memberdesc} - -\begin{memberdesc}[ProtocolError]{headers} -A string containing the headers of the HTTP/HTTPS request that -triggered the error. -\end{memberdesc} - -\subsection{MultiCall Objects} - -\versionadded{2.4} - -In \url{http://www.xmlrpc.com/discuss/msgReader\%241208}, an approach -is presented to encapsulate multiple calls to a remote server into a -single request. - -\begin{classdesc}{MultiCall}{server} - -Create an object used to boxcar method calls. \var{server} is the -eventual target of the call. Calls can be made to the result object, -but they will immediately return \code{None}, and only store the -call name and parameters in the \class{MultiCall} object. Calling -the object itself causes all stored calls to be transmitted as -a single \code{system.multicall} request. The result of this call -is a generator; iterating over this generator yields the individual -results. - -\end{classdesc} - -A usage example of this class is - -\begin{verbatim} -multicall = MultiCall(server_proxy) -multicall.add(2,3) -multicall.get_address("Guido") -add_result, address = multicall() -\end{verbatim} - -\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}{dumps}{params\optional{, methodname\optional{, - methodresponse\optional{, encoding\optional{, - allow_none}}}}} -Convert \var{params} into an XML-RPC request. -or into a response if \var{methodresponse} is true. -\var{params} can be either a tuple of arguments or an instance of the -\exception{Fault} exception class. If \var{methodresponse} is true, -only a single value can be returned, meaning that \var{params} must be of length 1. -\var{encoding}, if supplied, is the encoding to use in the generated -XML; the default is UTF-8. Python's \constant{None} value cannot be -used in standard XML-RPC; to allow using it via an extension, -provide a true value for \var{allow_none}. -\end{funcdesc} - -\begin{funcdesc}{loads}{data\optional{, use_datetime}} -Convert an XML-RPC request or response into Python objects, a -\code{(\var{params}, \var{methodname})}. \var{params} is a tuple of argument; \var{methodname} -is a string, or \code{None} if no method name is present in the packet. -If the XML-RPC packet represents a fault condition, this -function will raise a \exception{Fault} exception. -The \var{use_datetime} flag can be used to cause date/time values to be -presented as \class{\refmodule{datetime}.datetime} objects; this is false -by default. -Note that even if you call an XML-RPC method with -\class{\refmodule{datetime}.date} or \class{\refmodule{datetime}.time} -objects, they are converted to \class{DateTime} objects internally, so only -{}\class{\refmodule{datetime}.datetime} objects will be returned. - -\versionchanged[The \var{use_datetime} flag was added]{2.5} -\end{funcdesc} - - - -\subsection{Example of Client Usage \label{xmlrpc-client-example}} - -\begin{verbatim} -# simple test program (from the XML-RPC specification) -from xmlrpclib import ServerProxy, Error - -# 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} - -To access an XML-RPC server through a proxy, you need to define -a custom transport. The following example, -written by NoboNobo, % fill in original author's name if we ever learn it -shows how: - -% Example taken from http://lowlife.jp/nobonobo/wiki/xmlrpcwithproxy.html -\begin{verbatim} -import xmlrpclib, httplib - -class ProxiedTransport(xmlrpclib.Transport): - def set_proxy(self, proxy): - self.proxy = proxy - def make_connection(self, host): - self.realhost = host - h = httplib.HTTP(self.proxy) - return h - def send_request(self, connection, handler, request_body): - connection.putrequest("POST", 'http://%s%s' % (self.realhost, handler)) - def send_host(self, connection, host): - connection.putheader('Host', self.realhost) - -p = ProxiedTransport() -p.set_proxy('proxy-server:8080') -server = xmlrpclib.Server('http://time.xmlrpc.com/RPC2', transport=p) -print server.currentTime.getCurrentTime() -\end{verbatim} |