Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 1 | \section{\module{xmlrpclib} --- XML-RPC client access} |
| 2 | |
| 3 | \declaremodule{standard}{xmlrpclib} |
| 4 | \modulesynopsis{XML-RPC client access.} |
Fredrik Lundh | e7c38d4 | 2002-10-19 20:22:56 +0000 | [diff] [blame] | 5 | \moduleauthor{Fredrik Lundh}{fredrik@pythonware.com} |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 6 | \sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com} |
| 7 | |
Fred Drake | b184ae8 | 2005-01-19 03:39:17 +0000 | [diff] [blame] | 8 | % Not everything is documented yet. It might be good to describe |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 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 | |
Skip Montanaro | dc8d407 | 2002-03-14 17:35:25 +0000 | [diff] [blame] | 20 | \begin{classdesc}{ServerProxy}{uri\optional{, transport\optional{, |
Andrew M. Kuchling | f8d0c07 | 2003-04-25 00:29:31 +0000 | [diff] [blame] | 21 | encoding\optional{, verbose\optional{, |
Skip Montanaro | 174dd22 | 2005-05-14 20:54:16 +0000 | [diff] [blame] | 22 | allow_none\optional{, use_datetime}}}}}} |
Skip Montanaro | dc8d407 | 2002-03-14 17:35:25 +0000 | [diff] [blame] | 23 | A \class{ServerProxy} instance is an object that manages communication |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 24 | with a remote XML-RPC server. The required first argument is a URI |
| 25 | (Uniform Resource Indicator), and will normally be the URL of the |
| 26 | server. The optional second argument is a transport factory instance; |
| 27 | by default it is an internal \class{SafeTransport} instance for https: |
| 28 | URLs and an internal HTTP \class{Transport} instance otherwise. The |
| 29 | optional third argument is an encoding, by default UTF-8. The optional |
Andrew M. Kuchling | f8d0c07 | 2003-04-25 00:29:31 +0000 | [diff] [blame] | 30 | fourth argument is a debugging flag. If \var{allow_none} is true, |
| 31 | the Python constant \code{None} will be translated into XML; the |
| 32 | default behaviour is for \code{None} to raise a \exception{TypeError}. |
| 33 | This is a commonly-used extension to the XML-RPC specification, but isn't |
| 34 | supported by all clients and servers; see |
Skip Montanaro | 3f8f666 | 2005-03-21 19:39:16 +0000 | [diff] [blame] | 35 | \url{http://ontosys.com/xml-rpc/extensions.php} for a description. |
Skip Montanaro | 174dd22 | 2005-05-14 20:54:16 +0000 | [diff] [blame] | 36 | The \var{use_datetime} flag can be used to cause date/time values to be |
| 37 | presented as \class{\refmodule{datetime}.datetime} objects; this is false |
| 38 | by default. \class{\refmodule{datetime}.datetime}, |
| 39 | \class{\refmodule{datetime}.date} and \class{\refmodule{datetime}.time} |
| 40 | objects may be passed to calls. \class{\refmodule{datetime}.date} objects |
| 41 | are converted with a time of ``00:00:00''. |
| 42 | \class{\refmodule{datetime}.time} objects are converted using today's date. |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 43 | |
Fredrik Lundh | 1303c7c | 2002-10-22 18:23:00 +0000 | [diff] [blame] | 44 | Both the HTTP and HTTPS transports support the URL syntax extension for |
Fredrik Lundh | 019bd4a | 2002-10-22 18:26:28 +0000 | [diff] [blame] | 45 | HTTP Basic Authentication: \code{http://user:pass@host:port/path}. The |
Fredrik Lundh | 1303c7c | 2002-10-22 18:23:00 +0000 | [diff] [blame] | 46 | \code{user:pass} portion will be base64-encoded as an HTTP `Authorization' |
| 47 | header, and sent to the remote server as part of the connection process |
| 48 | when invoking an XML-RPC method. You only need to use this if the |
| 49 | remote server requires a Basic Authentication user and password. |
| 50 | |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 51 | The returned instance is a proxy object with methods that can be used |
| 52 | to invoke corresponding RPC calls on the remote server. If the remote |
| 53 | server supports the introspection API, the proxy can also be used to query |
| 54 | the remote server for the methods it supports (service discovery) and |
| 55 | fetch other server-associated metadata. |
| 56 | |
Skip Montanaro | dc8d407 | 2002-03-14 17:35:25 +0000 | [diff] [blame] | 57 | \class{ServerProxy} instance methods take Python basic types and objects as |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 58 | arguments and return Python basic types and classes. Types that are |
| 59 | conformable (e.g. that can be marshalled through XML), include the |
| 60 | following (and except where noted, they are unmarshalled as the same |
| 61 | Python type): |
| 62 | |
| 63 | \begin{tableii}{l|l}{constant}{Name}{Meaning} |
Fred Drake | 5ddf7ad | 2001-07-12 23:39:24 +0000 | [diff] [blame] | 64 | \lineii{boolean}{The \constant{True} and \constant{False} constants} |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 65 | \lineii{integers}{Pass in directly} |
| 66 | \lineii{floating-point numbers}{Pass in directly} |
| 67 | \lineii{strings}{Pass in directly} |
| 68 | \lineii{arrays}{Any Python sequence type containing conformable |
Fred Drake | 5ddf7ad | 2001-07-12 23:39:24 +0000 | [diff] [blame] | 69 | elements. Arrays are returned as lists} |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 70 | \lineii{structures}{A Python dictionary. Keys must be strings, |
Fred Drake | 5ddf7ad | 2001-07-12 23:39:24 +0000 | [diff] [blame] | 71 | values may be any conformable type.} |
Skip Montanaro | 174dd22 | 2005-05-14 20:54:16 +0000 | [diff] [blame] | 72 | \lineii{dates}{in seconds since the epoch (pass in an instance of the |
| 73 | \class{DateTime} class) or a |
| 74 | \class{\refmodule{datetime}.datetime}, |
| 75 | \class{\refmodule{datetime}.date} or |
| 76 | \class{\refmodule{datetime}.time} instance} |
Fred Drake | 5ddf7ad | 2001-07-12 23:39:24 +0000 | [diff] [blame] | 77 | \lineii{binary data}{pass in an instance of the \class{Binary} |
| 78 | wrapper class} |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 79 | \end{tableii} |
| 80 | |
| 81 | This is the full set of data types supported by XML-RPC. Method calls |
Fred Drake | 5ddf7ad | 2001-07-12 23:39:24 +0000 | [diff] [blame] | 82 | may also raise a special \exception{Fault} instance, used to signal |
| 83 | XML-RPC server errors, or \exception{ProtocolError} used to signal an |
Skip Montanaro | 10acc8f | 2002-03-17 23:15:02 +0000 | [diff] [blame] | 84 | error in the HTTP/HTTPS transport layer. Note that even though starting |
| 85 | with Python 2.2 you can subclass builtin types, the xmlrpclib module |
| 86 | currently does not marshal instances of such subclasses. |
Andrew M. Kuchling | 10b3eac | 2002-03-08 17:46:02 +0000 | [diff] [blame] | 87 | |
| 88 | When passing strings, characters special to XML such as \samp{<}, |
| 89 | \samp{>}, and \samp{\&} will be automatically escaped. However, it's |
| 90 | the caller's responsibility to ensure that the string is free of |
| 91 | characters that aren't allowed in XML, such as the control characters |
| 92 | with ASCII values between 0 and 31; failing to do this will result in |
| 93 | an XML-RPC request that isn't well-formed XML. If you have to pass |
| 94 | arbitrary strings via XML-RPC, use the \class{Binary} wrapper class |
| 95 | described below. |
| 96 | |
Skip Montanaro | dc8d407 | 2002-03-14 17:35:25 +0000 | [diff] [blame] | 97 | \class{Server} is retained as an alias for \class{ServerProxy} for backwards |
| 98 | compatibility. New code should use \class{ServerProxy}. |
| 99 | |
Skip Montanaro | 174dd22 | 2005-05-14 20:54:16 +0000 | [diff] [blame] | 100 | \versionchanged[The \var{use_datetime} flag was added]{2.5} |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 101 | \end{classdesc} |
| 102 | |
Fred Drake | 5ddf7ad | 2001-07-12 23:39:24 +0000 | [diff] [blame] | 103 | |
| 104 | \begin{seealso} |
Fred Drake | 3f207b6 | 2005-11-29 12:40:58 +0000 | [diff] [blame] | 105 | \seetitle[http://www.tldp.org/HOWTO/XML-RPC-HOWTO/index.html] |
Fred Drake | 5ddf7ad | 2001-07-12 23:39:24 +0000 | [diff] [blame] | 106 | {XML-RPC HOWTO}{A good description of XML operation and |
| 107 | client software in several languages. Contains pretty much |
| 108 | everything an XML-RPC client developer needs to know.} |
| 109 | \seetitle[http://xmlrpc-c.sourceforge.net/hacks.php] |
Skip Montanaro | 174dd22 | 2005-05-14 20:54:16 +0000 | [diff] [blame] | 110 | {XML-RPC Hacks page}{Extensions for various open-source |
Raymond Hettinger | 6880431 | 2005-01-01 00:28:46 +0000 | [diff] [blame] | 111 | libraries to support introspection and multicall.} |
Fred Drake | 5ddf7ad | 2001-07-12 23:39:24 +0000 | [diff] [blame] | 112 | \end{seealso} |
| 113 | |
| 114 | |
Skip Montanaro | dc8d407 | 2002-03-14 17:35:25 +0000 | [diff] [blame] | 115 | \subsection{ServerProxy Objects \label{serverproxy-objects}} |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 116 | |
Skip Montanaro | dc8d407 | 2002-03-14 17:35:25 +0000 | [diff] [blame] | 117 | A \class{ServerProxy} instance has a method corresponding to |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 118 | each remote procedure call accepted by the XML-RPC server. Calling |
| 119 | the method performs an RPC, dispatched by both name and argument |
| 120 | signature (e.g. the same method name can be overloaded with multiple |
| 121 | argument signatures). The RPC finishes by returning a value, which |
| 122 | may be either returned data in a conformant type or a \class{Fault} or |
| 123 | \class{ProtocolError} object indicating an error. |
| 124 | |
| 125 | Servers that support the XML introspection API support some common |
| 126 | methods grouped under the reserved \member{system} member: |
| 127 | |
| 128 | \begin{methoddesc}{system.listMethods}{} |
| 129 | This method returns a list of strings, one for each (non-system) |
| 130 | method supported by the XML-RPC server. |
| 131 | \end{methoddesc} |
| 132 | |
Fred Drake | 4124a0b | 2001-07-14 02:46:01 +0000 | [diff] [blame] | 133 | \begin{methoddesc}{system.methodSignature}{name} |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 134 | This method takes one parameter, the name of a method implemented by |
| 135 | the XML-RPC server.It returns an array of possible signatures for this |
| 136 | method. A signature is an array of types. The first of these types is |
| 137 | the return type of the method, the rest are parameters. |
| 138 | |
| 139 | Because multiple signatures (ie. overloading) is permitted, this method |
| 140 | returns a list of signatures rather than a singleton. |
| 141 | |
| 142 | Signatures themselves are restricted to the top level parameters |
| 143 | expected by a method. For instance if a method expects one array of |
| 144 | structs as a parameter, and it returns a string, its signature is |
| 145 | simply "string, array". If it expects three integers and returns a |
| 146 | string, its signature is "string, int, int, int". |
| 147 | |
| 148 | If no signature is defined for the method, a non-array value is |
| 149 | returned. In Python this means that the type of the returned |
| 150 | value will be something other that list. |
| 151 | \end{methoddesc} |
| 152 | |
| 153 | \begin{methoddesc}{system.methodHelp}{name} |
| 154 | This method takes one parameter, the name of a method implemented by |
| 155 | the XML-RPC server. It returns a documentation string describing the |
| 156 | use of that method. If no such string is available, an empty string is |
| 157 | returned. The documentation string may contain HTML markup. |
| 158 | \end{methoddesc} |
| 159 | |
| 160 | Introspection methods are currently supported by servers written in |
| 161 | PHP, C and Microsoft .NET. Partial introspection support is included |
| 162 | in recent updates to UserLand Frontier. Introspection support for |
Skip Montanaro | 174dd22 | 2005-05-14 20:54:16 +0000 | [diff] [blame] | 163 | Perl, Python and Java is available at the \ulink{XML-RPC |
| 164 | Hacks}{http://xmlrpc-c.sourceforge.net/hacks.php} page. |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 165 | |
Fred Drake | 5ddf7ad | 2001-07-12 23:39:24 +0000 | [diff] [blame] | 166 | |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 167 | \subsection{Boolean Objects \label{boolean-objects}} |
| 168 | |
| 169 | This class may be initialized from any Python value; the instance |
Fred Drake | 5ddf7ad | 2001-07-12 23:39:24 +0000 | [diff] [blame] | 170 | returned depends only on its truth value. It supports various Python |
| 171 | operators through \method{__cmp__()}, \method{__repr__()}, |
| 172 | \method{__int__()}, and \method{__nonzero__()} methods, all |
| 173 | implemented in the obvious ways. |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 174 | |
| 175 | It also has the following method, supported mainly for internal use by |
| 176 | the unmarshalling code: |
| 177 | |
| 178 | \begin{methoddesc}{encode}{out} |
| 179 | Write the XML-RPC encoding of this Boolean item to the out stream object. |
| 180 | \end{methoddesc} |
| 181 | |
Fred Drake | 5ddf7ad | 2001-07-12 23:39:24 +0000 | [diff] [blame] | 182 | |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 183 | \subsection{DateTime Objects \label{datetime-objects}} |
| 184 | |
Skip Montanaro | 174dd22 | 2005-05-14 20:54:16 +0000 | [diff] [blame] | 185 | This class may be initialized with seconds since the epoch, a time tuple, an |
| 186 | ISO 8601 time/date string, or a {}\class{\refmodule{datetime}.datetime}, |
| 187 | {}\class{\refmodule{datetime}.date} or {}\class{\refmodule{datetime}.time} |
| 188 | instance. It has the following methods, supported mainly for internal use |
| 189 | by the marshalling/unmarshalling code: |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 190 | |
| 191 | \begin{methoddesc}{decode}{string} |
| 192 | Accept a string as the instance's new time value. |
| 193 | \end{methoddesc} |
| 194 | |
| 195 | \begin{methoddesc}{encode}{out} |
Skip Montanaro | 174dd22 | 2005-05-14 20:54:16 +0000 | [diff] [blame] | 196 | Write the XML-RPC encoding of this \class{DateTime} item to the |
| 197 | \var{out} stream object. |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 198 | \end{methoddesc} |
| 199 | |
| 200 | It also supports certain of Python's built-in operators through |
Skip Montanaro | 174dd22 | 2005-05-14 20:54:16 +0000 | [diff] [blame] | 201 | \method{__cmp__()} and \method{__repr__()} methods. |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 202 | |
Fred Drake | 5ddf7ad | 2001-07-12 23:39:24 +0000 | [diff] [blame] | 203 | |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 204 | \subsection{Binary Objects \label{binary-objects}} |
| 205 | |
| 206 | This class may initialized from string data (which may include NULs). |
Fred Drake | bb066cf | 2004-05-12 03:07:27 +0000 | [diff] [blame] | 207 | The primary access to the content of a \class{Binary} object is |
Fred Drake | 585775b | 2002-06-14 00:33:02 +0000 | [diff] [blame] | 208 | provided by an attribute: |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 209 | |
Fred Drake | 585775b | 2002-06-14 00:33:02 +0000 | [diff] [blame] | 210 | \begin{memberdesc}[Binary]{data} |
| 211 | The binary data encapsulated by the \class{Binary} instance. The data |
| 212 | is provided as an 8-bit string. |
| 213 | \end{memberdesc} |
| 214 | |
| 215 | \class{Binary} objects have the following methods, supported mainly |
| 216 | for internal use by the marshalling/unmarshalling code: |
| 217 | |
| 218 | \begin{methoddesc}[Binary]{decode}{string} |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 219 | Accept a base64 string and decode it as the instance's new data. |
| 220 | \end{methoddesc} |
| 221 | |
Fred Drake | 585775b | 2002-06-14 00:33:02 +0000 | [diff] [blame] | 222 | \begin{methoddesc}[Binary]{encode}{out} |
Fred Drake | 5ddf7ad | 2001-07-12 23:39:24 +0000 | [diff] [blame] | 223 | Write the XML-RPC base 64 encoding of this binary item to the out |
| 224 | stream object. |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 225 | \end{methoddesc} |
| 226 | |
| 227 | It also supports certain of Python's built-in operators through a |
Johannes Gijsbers | f4a70f3 | 2004-12-12 16:52:40 +0000 | [diff] [blame] | 228 | \method{__cmp__()} method. |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 229 | |
Fred Drake | 5ddf7ad | 2001-07-12 23:39:24 +0000 | [diff] [blame] | 230 | |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 231 | \subsection{Fault Objects \label{fault-objects}} |
| 232 | |
| 233 | A \class{Fault} object encapsulates the content of an XML-RPC fault tag. |
| 234 | Fault objects have the following members: |
| 235 | |
| 236 | \begin{memberdesc}{faultCode} |
| 237 | A string indicating the fault type. |
| 238 | \end{memberdesc} |
| 239 | |
| 240 | \begin{memberdesc}{faultString} |
| 241 | A string containing a diagnostic message associated with the fault. |
| 242 | \end{memberdesc} |
| 243 | |
Fred Drake | 5ddf7ad | 2001-07-12 23:39:24 +0000 | [diff] [blame] | 244 | |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 245 | \subsection{ProtocolError Objects \label{protocol-error-objects}} |
| 246 | |
| 247 | A \class{ProtocolError} object describes a protocol error in the |
| 248 | underlying transport layer (such as a 404 `not found' error if the |
| 249 | server named by the URI does not exist). It has the following |
| 250 | members: |
| 251 | |
| 252 | \begin{memberdesc}{url} |
Andrew M. Kuchling | 10b3eac | 2002-03-08 17:46:02 +0000 | [diff] [blame] | 253 | The URI or URL that triggered the error. |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 254 | \end{memberdesc} |
| 255 | |
| 256 | \begin{memberdesc}{errcode} |
| 257 | The error code. |
| 258 | \end{memberdesc} |
| 259 | |
| 260 | \begin{memberdesc}{errmsg} |
Andrew M. Kuchling | 10b3eac | 2002-03-08 17:46:02 +0000 | [diff] [blame] | 261 | The error message or diagnostic string. |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 262 | \end{memberdesc} |
| 263 | |
| 264 | \begin{memberdesc}{headers} |
| 265 | A string containing the headers of the HTTP/HTTPS request that |
| 266 | triggered the error. |
| 267 | \end{memberdesc} |
| 268 | |
Martin v. Löwis | 45394c2 | 2003-10-31 13:49:36 +0000 | [diff] [blame] | 269 | \subsection{MultiCall Objects} |
| 270 | |
| 271 | \versionadded{2.4} |
| 272 | |
Michael W. Hudson | 1baa248 | 2004-08-07 17:39:35 +0000 | [diff] [blame] | 273 | In \url{http://www.xmlrpc.com/discuss/msgReader\%241208}, an approach |
| 274 | is presented to encapsulate multiple calls to a remote server into a |
| 275 | single request. |
Martin v. Löwis | 45394c2 | 2003-10-31 13:49:36 +0000 | [diff] [blame] | 276 | |
| 277 | \begin{classdesc}{MultiCall}{server} |
| 278 | |
| 279 | Create an object used to boxcar method calls. \var{server} is the |
| 280 | eventual target of the call. Calls can be made to the result object, |
| 281 | but they will immediately return \var{None}, and only store the |
| 282 | call name and parameters in the \class{MultiCall} object. Calling |
| 283 | the object itself causes all stored calls to be transmitted as |
| 284 | a single \code{system.multicall} request. The result of this call |
| 285 | is a generator; iterating over this generator yields the individual |
| 286 | results. |
| 287 | |
| 288 | \end{classdesc} |
| 289 | |
| 290 | A usage example of this class is |
| 291 | |
| 292 | \begin{verbatim} |
| 293 | multicall = MultiCall(server_proxy) |
| 294 | multicall.add(2,3) |
| 295 | multicall.get_address("Guido") |
| 296 | add_result, address = multicall() |
| 297 | \end{verbatim} |
Fred Drake | 5ddf7ad | 2001-07-12 23:39:24 +0000 | [diff] [blame] | 298 | |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 299 | \subsection{Convenience Functions} |
| 300 | |
Fred Drake | d90f509 | 2001-10-01 21:05:30 +0000 | [diff] [blame] | 301 | \begin{funcdesc}{boolean}{value} |
| 302 | Convert any Python value to one of the XML-RPC Boolean constants, |
| 303 | \code{True} or \code{False}. |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 304 | \end{funcdesc} |
| 305 | |
| 306 | \begin{funcdesc}{binary}{data} |
| 307 | Trivially convert any Python string to a \class{Binary} object. |
| 308 | \end{funcdesc} |
| 309 | |
Andrew M. Kuchling | 38afcef | 2003-10-22 14:12:03 +0000 | [diff] [blame] | 310 | \begin{funcdesc}{dumps}{params\optional{, methodname\optional{, |
| 311 | methodresponse\optional{, encoding\optional{, |
| 312 | allow_none}}}}} |
Andrew M. Kuchling | 38afcef | 2003-10-22 14:12:03 +0000 | [diff] [blame] | 313 | Convert \var{params} into an XML-RPC request. |
| 314 | or into a response if \var{methodresponse} is true. |
| 315 | \var{params} can be either a tuple of arguments or an instance of the |
| 316 | \exception{Fault} exception class. If \var{methodresponse} is true, |
| 317 | only a single value can be returned, meaning that \var{params} must be of length 1. |
| 318 | \var{encoding}, if supplied, is the encoding to use in the generated |
| 319 | XML; the default is UTF-8. Python's \constant{None} value cannot be |
| 320 | used in standard XML-RPC; to allow using it via an extension, |
| 321 | provide a true value for \var{allow_none}. |
| 322 | \end{funcdesc} |
| 323 | |
Skip Montanaro | 174dd22 | 2005-05-14 20:54:16 +0000 | [diff] [blame] | 324 | \begin{funcdesc}{loads}{data\optional{, use_datetime}} |
Andrew M. Kuchling | 38afcef | 2003-10-22 14:12:03 +0000 | [diff] [blame] | 325 | Convert an XML-RPC request or response into Python objects, a |
| 326 | \code{(\var{params}, \var{methodname})}. \var{params} is a tuple of argument; \var{methodname} |
| 327 | is a string, or \code{None} if no method name is present in the packet. |
| 328 | If the XML-RPC packet represents a fault condition, this |
| 329 | function will raise a \exception{Fault} exception. |
Skip Montanaro | 174dd22 | 2005-05-14 20:54:16 +0000 | [diff] [blame] | 330 | The \var{use_datetime} flag can be used to cause date/time values to be |
| 331 | presented as \class{\refmodule{datetime}.datetime} objects; this is false |
| 332 | by default. |
| 333 | Note that even if you call an XML-RPC method with |
| 334 | \class{\refmodule{datetime}.date} or \class{\refmodule{datetime}.time} |
| 335 | objects, they are converted to \class{DateTime} objects internally, so only |
| 336 | {}\class{\refmodule{datetime}.datetime} objects will be returned. |
| 337 | |
| 338 | \versionchanged[The \var{use_datetime} flag was added]{2.5} |
Andrew M. Kuchling | 38afcef | 2003-10-22 14:12:03 +0000 | [diff] [blame] | 339 | \end{funcdesc} |
| 340 | |
| 341 | |
Fred Drake | 5ddf7ad | 2001-07-12 23:39:24 +0000 | [diff] [blame] | 342 | |
| 343 | \subsection{Example of Client Usage \label{xmlrpc-client-example}} |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 344 | |
| 345 | \begin{verbatim} |
Fred Drake | 5ddf7ad | 2001-07-12 23:39:24 +0000 | [diff] [blame] | 346 | # simple test program (from the XML-RPC specification) |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 347 | |
Skip Montanaro | dc8d407 | 2002-03-14 17:35:25 +0000 | [diff] [blame] | 348 | # server = ServerProxy("http://localhost:8000") # local server |
| 349 | server = ServerProxy("http://betty.userland.com") |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 350 | |
Fred Drake | 5ddf7ad | 2001-07-12 23:39:24 +0000 | [diff] [blame] | 351 | print server |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 352 | |
Fred Drake | 5ddf7ad | 2001-07-12 23:39:24 +0000 | [diff] [blame] | 353 | try: |
| 354 | print server.examples.getStateName(41) |
| 355 | except Error, v: |
| 356 | print "ERROR", v |
Eric S. Raymond | e304bb9 | 2001-07-12 02:39:45 +0000 | [diff] [blame] | 357 | \end{verbatim} |
Andrew M. Kuchling | 432be36 | 2005-12-08 14:54:20 +0000 | [diff] [blame] | 358 | |
| 359 | To access an XML-RPC server through a proxy, you need to define |
| 360 | a custom transport. The following example, |
| 361 | written by NoboNobo, % fill in original author's name if we ever learn it |
| 362 | shows how: |
| 363 | |
| 364 | % Example taken from http://lowlife.jp/nobonobo/wiki/xmlrpcwithproxy.html |
| 365 | \begin{verbatim} |
| 366 | import xmlrpclib, httplib |
| 367 | |
| 368 | class ProxiedTransport(xmlrpclib.Transport): |
| 369 | def set_proxy(self, proxy): |
| 370 | self.proxy = proxy |
| 371 | def make_connection(self, host): |
| 372 | self.realhost = host |
| 373 | h = httplib.HTTP(self.proxy) |
| 374 | return h |
| 375 | def send_request(self, connection, handler, request_body): |
| 376 | connection.putrequest("POST", 'http://%s%s' % (self.realhost, handler)) |
| 377 | def send_host(self, connection, host): |
| 378 | connection.putheader('Host', self.realhost) |
| 379 | |
| 380 | p = ProxiedTransport() |
| 381 | p.set_proxy('proxy-server:8080') |
| 382 | server = xmlrpclib.Server('http://time.xmlrpc.com/RPC2', transport=p) |
| 383 | print server.currentTime.getCurrentTime() |
| 384 | \end{verbatim} |