Initial commit of OpenSPARC T2 design and verification files.
[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / lib / module-xmlrpclib.html
CommitLineData
86530b38
AT
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3<head>
4<link rel="STYLESHEET" href="lib.css" type='text/css' />
5<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
6<link rel='start' href='../index.html' title='Python Documentation Index' />
7<link rel="first" href="lib.html" title='Python Library Reference' />
8<link rel='contents' href='contents.html' title="Contents" />
9<link rel='index' href='genindex.html' title='Index' />
10<link rel='last' href='about.html' title='About this document...' />
11<link rel='help' href='about.html' title='About this document...' />
12<link rel="next" href="module-SimpleXMLRPCServer.html" />
13<link rel="prev" href="module-Cookie.html" />
14<link rel="parent" href="internet.html" />
15<link rel="next" href="serverproxy-objects.html" />
16<meta name='aesop' content='information' />
17<title>11.22 xmlrpclib -- XML-RPC client access</title>
18</head>
19<body>
20<DIV CLASS="navigation">
21<div id='top-navigation-panel' xml:id='top-navigation-panel'>
22<table align="center" width="100%" cellpadding="0" cellspacing="2">
23<tr>
24<td class='online-navigation'><a rel="prev" title="11.21.3 Example"
25 href="cookie-example.html"><img src='../icons/previous.png'
26 border='0' height='32' alt='Previous Page' width='32' /></A></td>
27<td class='online-navigation'><a rel="parent" title="11. Internet Protocols and"
28 href="internet.html"><img src='../icons/up.png'
29 border='0' height='32' alt='Up One Level' width='32' /></A></td>
30<td class='online-navigation'><a rel="next" title="11.22.1 ServerProxy Objects"
31 href="serverproxy-objects.html"><img src='../icons/next.png'
32 border='0' height='32' alt='Next Page' width='32' /></A></td>
33<td align="center" width="100%">Python Library Reference</td>
34<td class='online-navigation'><a rel="contents" title="Table of Contents"
35 href="contents.html"><img src='../icons/contents.png'
36 border='0' height='32' alt='Contents' width='32' /></A></td>
37<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
38 border='0' height='32' alt='Module Index' width='32' /></a></td>
39<td class='online-navigation'><a rel="index" title="Index"
40 href="genindex.html"><img src='../icons/index.png'
41 border='0' height='32' alt='Index' width='32' /></A></td>
42</tr></table>
43<div class='online-navigation'>
44<b class="navlabel">Previous:</b>
45<a class="sectref" rel="prev" href="cookie-example.html">11.21.3 Example</A>
46<b class="navlabel">Up:</b>
47<a class="sectref" rel="parent" href="internet.html">11. Internet Protocols and</A>
48<b class="navlabel">Next:</b>
49<a class="sectref" rel="next" href="serverproxy-objects.html">11.22.1 ServerProxy Objects</A>
50</div>
51<hr /></div>
52</DIV>
53<!--End of Navigation Panel-->
54
55<H1><A NAME="SECTION00132200000000000000000">
5611.22 <tt class="module">xmlrpclib</tt> -- XML-RPC client access</A>
57</H1>
58
59<P>
60<A NAME="module-xmlrpclib"></A>
61
62<P>
63
64<span class="versionnote">New in version 2.2.</span>
65
66<P>
67XML-RPC is a Remote Procedure Call method that uses XML passed via
68HTTP as a transport. With it, a client can call methods with
69parameters on a remote server (the server is named by a URI) and get back
70structured data. This module supports writing XML-RPC client code; it
71handles all the details of translating between conformable Python
72objects and XML on the wire.
73
74<P>
75<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
76 <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-3698' xml:id='l2h-3698' class="class">ServerProxy</tt></b>(</nobr></td>
77 <td><var>uri</var><big>[</big><var>, transport</var><big>[</big><var>,
78 encoding</var><big>[</big><var>, verbose</var><big>[</big><var>,
79 allow_none</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
80<dd>
81A <tt class="class">ServerProxy</tt> instance is an object that manages communication
82with a remote XML-RPC server. The required first argument is a URI
83(Uniform Resource Indicator), and will normally be the URL of the
84server. The optional second argument is a transport factory instance;
85by default it is an internal <tt class="class">SafeTransport</tt> instance for https:
86URLs and an internal HTTP <tt class="class">Transport</tt> instance otherwise. The
87optional third argument is an encoding, by default UTF-8. The optional
88fourth argument is a debugging flag. If <var>allow_none</var> is true,
89the Python constant <code>None</code> will be translated into XML; the
90default behaviour is for <code>None</code> to raise a <tt class="exception">TypeError</tt>.
91This is a commonly-used extension to the XML-RPC specification, but isn't
92supported by all clients and servers; see
93<a class="url" href="http://ontosys.com/xml-rpc/extensions.php">http://ontosys.com/xml-rpc/extensions.php</a> for a description.
94
95<P>
96Both the HTTP and HTTPS transports support the URL syntax extension for
97HTTP Basic Authentication: <code>http://user:pass@host:port/path</code>. The
98<code>user:pass</code> portion will be base64-encoded as an HTTP `Authorization'
99header, and sent to the remote server as part of the connection process
100when invoking an XML-RPC method. You only need to use this if the
101remote server requires a Basic Authentication user and password.
102
103<P>
104The returned instance is a proxy object with methods that can be used
105to invoke corresponding RPC calls on the remote server. If the remote
106server supports the introspection API, the proxy can also be used to query
107the remote server for the methods it supports (service discovery) and
108fetch other server-associated metadata.
109
110<P>
111<tt class="class">ServerProxy</tt> instance methods take Python basic types and objects as
112arguments and return Python basic types and classes. Types that are
113conformable (e.g. that can be marshalled through XML), include the
114following (and except where noted, they are unmarshalled as the same
115Python type):
116
117<P>
118<div class="center"><table class="realtable">
119 <thead>
120 <tr>
121 <th class="left" >Name</th>
122 <th class="left" >Meaning</th>
123 </tr>
124 </thead>
125 <tbody>
126 <tr><td class="left" valign="baseline"><tt class="constant">boolean</tt></td>
127 <td class="left" >The <tt class="constant">True</tt> and <tt class="constant">False</tt> constants</td></tr>
128 <tr><td class="left" valign="baseline"><tt class="constant">integers</tt></td>
129 <td class="left" >Pass in directly</td></tr>
130 <tr><td class="left" valign="baseline"><tt class="constant">floating-point numbers</tt></td>
131 <td class="left" >Pass in directly</td></tr>
132 <tr><td class="left" valign="baseline"><tt class="constant">strings</tt></td>
133 <td class="left" >Pass in directly</td></tr>
134 <tr><td class="left" valign="baseline"><tt class="constant">arrays</tt></td>
135 <td class="left" >Any Python sequence type containing conformable
136 elements. Arrays are returned as lists</td></tr>
137 <tr><td class="left" valign="baseline"><tt class="constant">structures</tt></td>
138 <td class="left" >A Python dictionary. Keys must be strings,
139 values may be any conformable type.</td></tr>
140 <tr><td class="left" valign="baseline"><tt class="constant">dates</tt></td>
141 <td class="left" >in seconds since the epoch; pass in an instance of the
142 <tt class="class">DateTime</tt> wrapper class</td></tr>
143 <tr><td class="left" valign="baseline"><tt class="constant">binary data</tt></td>
144 <td class="left" >pass in an instance of the <tt class="class">Binary</tt>
145 wrapper class</td></tr></tbody>
146</table></div>
147
148<P>
149This is the full set of data types supported by XML-RPC. Method calls
150may also raise a special <tt class="exception">Fault</tt> instance, used to signal
151XML-RPC server errors, or <tt class="exception">ProtocolError</tt> used to signal an
152error in the HTTP/HTTPS transport layer. Note that even though starting
153with Python 2.2 you can subclass builtin types, the xmlrpclib module
154currently does not marshal instances of such subclasses.
155
156<P>
157When passing strings, characters special to XML such as "<tt class="samp">&lt;</tt>",
158"<tt class="samp">&gt;</tt>", and "<tt class="samp">&amp;</tt>" will be automatically escaped. However, it's
159the caller's responsibility to ensure that the string is free of
160characters that aren't allowed in XML, such as the control characters
161with ASCII values between 0 and 31; failing to do this will result in
162an XML-RPC request that isn't well-formed XML. If you have to pass
163arbitrary strings via XML-RPC, use the <tt class="class">Binary</tt> wrapper class
164described below.
165
166<P>
167<tt class="class">Server</tt> is retained as an alias for <tt class="class">ServerProxy</tt> for backwards
168compatibility. New code should use <tt class="class">ServerProxy</tt>.
169
170<P>
171</dl>
172
173<P>
174<div class="seealso">
175 <p class="heading">See Also:</p>
176
177 <dl compact="compact" class="seetitle">
178 <dt><em class="citetitle"><a href="http://xmlrpc-c.sourceforge.net/xmlrpc-howto/xmlrpc-howto.html"
179 >XML-RPC HOWTO</a></em></dt>
180 <dd>A good description of XML operation and
181 client software in several languages. Contains pretty much
182 everything an XML-RPC client developer needs to know.</dd>
183 </dl>
184 <dl compact="compact" class="seetitle">
185 <dt><em class="citetitle"><a href="http://xmlrpc-c.sourceforge.net/hacks.php"
186 >XML-RPC-Hacks page</a></em></dt>
187 <dd>Extensions for various open-source
188 libraries to support introspection and multicall.</dd>
189 </dl>
190</div>
191
192<P>
193
194<p><br /></p><hr class='online-navigation' />
195<div class='online-navigation'>
196<!--Table of Child-Links-->
197<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
198
199<UL CLASS="ChildLinks">
200<LI><A href="serverproxy-objects.html">11.22.1 ServerProxy Objects</a>
201<LI><A href="boolean-objects.html">11.22.2 Boolean Objects</a>
202<LI><A href="datetime-objects.html">11.22.3 DateTime Objects</a>
203<LI><A href="binary-objects.html">11.22.4 Binary Objects</a>
204<LI><A href="fault-objects.html">11.22.5 Fault Objects</a>
205<LI><A href="protocol-error-objects.html">11.22.6 ProtocolError Objects</a>
206<LI><A href="node559.html">11.22.7 MultiCall Objects</a>
207<LI><A href="node560.html">11.22.8 Convenience Functions</a>
208<LI><A href="xmlrpc-client-example.html">11.22.9 Example of Client Usage</a>
209</ul>
210<!--End of Table of Child-Links-->
211</div>
212
213<DIV CLASS="navigation">
214<div class='online-navigation'>
215<p></p><hr />
216<table align="center" width="100%" cellpadding="0" cellspacing="2">
217<tr>
218<td class='online-navigation'><a rel="prev" title="11.21.3 Example"
219 href="cookie-example.html"><img src='../icons/previous.png'
220 border='0' height='32' alt='Previous Page' width='32' /></A></td>
221<td class='online-navigation'><a rel="parent" title="11. Internet Protocols and"
222 href="internet.html"><img src='../icons/up.png'
223 border='0' height='32' alt='Up One Level' width='32' /></A></td>
224<td class='online-navigation'><a rel="next" title="11.22.1 ServerProxy Objects"
225 href="serverproxy-objects.html"><img src='../icons/next.png'
226 border='0' height='32' alt='Next Page' width='32' /></A></td>
227<td align="center" width="100%">Python Library Reference</td>
228<td class='online-navigation'><a rel="contents" title="Table of Contents"
229 href="contents.html"><img src='../icons/contents.png'
230 border='0' height='32' alt='Contents' width='32' /></A></td>
231<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
232 border='0' height='32' alt='Module Index' width='32' /></a></td>
233<td class='online-navigation'><a rel="index" title="Index"
234 href="genindex.html"><img src='../icons/index.png'
235 border='0' height='32' alt='Index' width='32' /></A></td>
236</tr></table>
237<div class='online-navigation'>
238<b class="navlabel">Previous:</b>
239<a class="sectref" rel="prev" href="cookie-example.html">11.21.3 Example</A>
240<b class="navlabel">Up:</b>
241<a class="sectref" rel="parent" href="internet.html">11. Internet Protocols and</A>
242<b class="navlabel">Next:</b>
243<a class="sectref" rel="next" href="serverproxy-objects.html">11.22.1 ServerProxy Objects</A>
244</div>
245</div>
246<hr />
247<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
248</DIV>
249<!--End of Navigation Panel-->
250<ADDRESS>
251See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
252</ADDRESS>
253</BODY>
254</HTML>