From 458120dd40db6b4df55a4e96b650e16798ef06a0 Mon Sep 17 00:00:00 2001 From: cinap_lenrek Date: Tue, 3 May 2011 11:25:13 +0000 Subject: add hg and python --- sys/src/cmd/python/Doc/lib/libxmlrpclib.tex | 383 ++++++++++++++++++++++++++++ 1 file changed, 383 insertions(+) create mode 100644 sys/src/cmd/python/Doc/lib/libxmlrpclib.tex (limited to 'sys/src/cmd/python/Doc/lib/libxmlrpclib.tex') diff --git a/sys/src/cmd/python/Doc/lib/libxmlrpclib.tex b/sys/src/cmd/python/Doc/lib/libxmlrpclib.tex new file mode 100644 index 000000000..3645b824d --- /dev/null +++ b/sys/src/cmd/python/Doc/lib/libxmlrpclib.tex @@ -0,0 +1,383 @@ +\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.} + \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; 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} +\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}{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 \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}{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}{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 \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}{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{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 \var{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} -- cgit v1.2.3