<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Fedora Client — python-fedora v0.3.25.1 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '0.3.25.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within python-fedora v0.3.25.1 documentation"
href="_static/opensearch.xml"/>
<link rel="top" title="python-fedora v0.3.25.1 documentation" href="index.html" />
<link rel="next" title="Existing Services" href="existing.html" />
<link rel="prev" title="Python Fedora Module Documentation" href="index.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="existing.html" title="Existing Services"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="Python Fedora Module Documentation"
accesskey="P">previous</a> |</li>
<li><a href="index.html">python-fedora v0.3.25.1 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="fedora-client">
<h1>Fedora Client<a class="headerlink" href="#fedora-client" title="Permalink to this headline">¶</a></h1>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Authors:</th><td class="field-body">Toshio Kuratomi
Luke Macken</td>
</tr>
<tr class="field"><th class="field-name">Date:</th><td class="field-body">28 May 2008</td>
</tr>
<tr class="field"><th class="field-name">For Version:</th><td class="field-body">0.3.x</td>
</tr>
</tbody>
</table>
<p>The client module allows you to easily code an application that talks to a
<a class="reference external" href="service.html">Fedora Service</a>. It handles the details of decoding the data sent from the
Service into a python data structure and raises an <a class="reference internal" href="#exceptions">Exception</a> if an error is
encountered.</p>
<div class="toctree-wrapper compound">
<ul class="simple">
</ul>
</div>
<div class="section" id="baseclient">
<h2>BaseClient<a class="headerlink" href="#baseclient" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference internal" href="api.html#fedora.client.BaseClient" title="fedora.client.BaseClient"><tt class="xref py py-class docutils literal"><span class="pre">BaseClient</span></tt></a> class is the basis of all your
interactions with the server. It is flexible enough to be used as is for
talking with a service but is really meant to be subclassed and have methods
written for it that do the things you specifically need to interact with the
<a class="reference external" href="service.html">Fedora Service</a> you care about. Authors of a <a class="reference external" href="service.html">Fedora Service</a> are
encouraged to provide their own subclasses of
<a class="reference internal" href="api.html#fedora.client.BaseClient" title="fedora.client.BaseClient"><tt class="xref py py-class docutils literal"><span class="pre">BaseClient</span></tt></a> that make it easier for other people to use
a particular Service out of the box.</p>
<div class="section" id="using-standalone">
<h3>Using Standalone<a class="headerlink" href="#using-standalone" title="Permalink to this headline">¶</a></h3>
<p>If you don’t want to subclass, you can use <a class="reference internal" href="api.html#fedora.client.BaseClient" title="fedora.client.BaseClient"><tt class="xref py py-class docutils literal"><span class="pre">BaseClient</span></tt></a>
as a utility class to talk to any <a class="reference external" href="service.html">Fedora Service</a>. There’s three steps to
this. First you import the <a class="reference internal" href="api.html#fedora.client.BaseClient" title="fedora.client.BaseClient"><tt class="xref py py-class docutils literal"><span class="pre">BaseClient</span></tt></a> and <a class="reference internal" href="#exceptions">Exceptions</a>
from the <tt class="docutils literal"><span class="pre">fedora.client</span></tt> module. Then you create a new
<a class="reference internal" href="api.html#fedora.client.BaseClient" title="fedora.client.BaseClient"><tt class="xref py py-class docutils literal"><span class="pre">BaseClient</span></tt></a> with the URL that points to the root of the
<a class="reference external" href="service.html">Fedora Service</a> you’re interacting with. Finally, you retrieve data from a
method on the server. Here’s some code that illustrates the process:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">fedora.client</span> <span class="kn">import</span> <span class="n">BaseClient</span><span class="p">,</span> <span class="n">AppError</span><span class="p">,</span> <span class="n">ServerError</span>
<span class="n">client</span> <span class="o">=</span> <span class="n">BaseClient</span><span class="p">(</span><span class="s">'https://admin.fedoraproject.org/pkgdb'</span><span class="p">)</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">collectionData</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">send_request</span><span class="p">(</span><span class="s">'/collections'</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="k">except</span> <span class="n">ServerError</span><span class="p">,</span> <span class="n">e</span><span class="p">:</span>
<span class="k">print</span> <span class="s">'</span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="n">e</span>
<span class="k">except</span> <span class="n">AppError</span><span class="p">,</span> <span class="n">e</span><span class="p">:</span>
<span class="k">print</span> <span class="s">'</span><span class="si">%s</span><span class="s">: </span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">e</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">e</span><span class="o">.</span><span class="n">message</span><span class="p">)</span>
<span class="k">for</span> <span class="n">collection</span> <span class="ow">in</span> <span class="n">collectionData</span><span class="p">[</span><span class="s">'collections'</span><span class="p">]:</span>
<span class="k">print</span> <span class="n">collection</span><span class="p">[</span><span class="s">'name'</span><span class="p">],</span> <span class="n">collection</span><span class="p">[</span><span class="s">'version'</span><span class="p">]</span>
</pre></div>
</div>
<div class="section" id="baseclient-constructor">
<h4>BaseClient Constructor<a class="headerlink" href="#baseclient-constructor" title="Permalink to this headline">¶</a></h4>
<p>In our example we only provide <tt class="docutils literal"><span class="pre">BaseClient()</span></tt> with the URL fragment it uses
as the base of all requests. There are several more optional parameters that
can be helpful.</p>
<p>If you need to make an authenticated request you can specify the username and
password to use when you construct your <a class="reference internal" href="api.html#fedora.client.BaseClient" title="fedora.client.BaseClient"><tt class="xref py py-class docutils literal"><span class="pre">BaseClient</span></tt></a>
using the <tt class="docutils literal"><span class="pre">username</span></tt> and <tt class="docutils literal"><span class="pre">password</span></tt> keyword arguments. If you do not use
these, authenticated requests will try to connect via a cookie that was saved
from previous runs of <a class="reference internal" href="api.html#fedora.client.BaseClient" title="fedora.client.BaseClient"><tt class="xref py py-class docutils literal"><span class="pre">BaseClient</span></tt></a>. If that fails as
well, <a class="reference internal" href="api.html#fedora.client.BaseClient" title="fedora.client.BaseClient"><tt class="xref py py-class docutils literal"><span class="pre">BaseClient</span></tt></a> will throw an <a class="reference internal" href="#exceptions">Exception</a> which you
can catch in order to prompt for a new username and password:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">fedora.client</span> <span class="kn">import</span> <span class="n">BaseClient</span><span class="p">,</span> <span class="n">AuthError</span>
<span class="kn">import</span> <span class="nn">getpass</span>
<span class="n">MAX_RETRIES</span> <span class="o">=</span> <span class="mi">5</span>
<span class="n">client</span> <span class="o">=</span> <span class="n">BaseClient</span><span class="p">(</span><span class="s">'https://admin.fedoraproject.org/pkgdb'</span><span class="p">,</span>
<span class="n">username</span><span class="o">=</span><span class="s">'foo'</span><span class="p">,</span> <span class="n">password</span><span class="o">=</span><span class="s">'bar'</span><span class="p">)</span>
<span class="c"># Note this is simplistic. It only prompts once for another password.</span>
<span class="c"># Your application may want to loop through this several times.</span>
<span class="k">while</span> <span class="p">(</span><span class="n">count</span> <span class="o"><</span> <span class="n">MAX_RETRIES</span><span class="p">):</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">collectionData</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">send_request</span><span class="p">(</span><span class="s">'/collections'</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">except</span> <span class="n">AuthError</span><span class="p">,</span> <span class="n">e</span><span class="p">:</span>
<span class="n">client</span><span class="o">.</span><span class="n">password</span> <span class="o">=</span> <span class="n">getpass</span><span class="o">.</span><span class="n">getpass</span><span class="p">(</span><span class="s">'Retype password for </span><span class="si">%s</span><span class="s">: '</span> <span class="o">%</span> <span class="n">username</span><span class="p">)</span>
<span class="k">else</span><span class="p">:</span>
<span class="c"># data retrieved or we had an error unrelated to username/password</span>
<span class="k">break</span>
<span class="n">count</span> <span class="o">=</span> <span class="n">count</span> <span class="o">+</span> <span class="mi">1</span>
</pre></div>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Note that although you can set the <tt class="docutils literal"><span class="pre">username</span></tt> and <tt class="docutils literal"><span class="pre">password</span></tt> as shown
above you do have to be careful in cases where your application is
multithreaded or simply processes requests for more than one user with the
same <a class="reference internal" href="api.html#fedora.client.BaseClient" title="fedora.client.BaseClient"><tt class="xref py py-class docutils literal"><span class="pre">BaseClient</span></tt></a>. In those cases, you can
accidentally overwrite the <tt class="docutils literal"><span class="pre">username</span></tt> and <tt class="docutils literal"><span class="pre">password</span></tt> between two
requests. To avoid this, make sure you instantiate a separate
<a class="reference internal" href="api.html#fedora.client.BaseClient" title="fedora.client.BaseClient"><tt class="xref py py-class docutils literal"><span class="pre">BaseClient</span></tt></a> for every thread of control or for
every request you handle or use <cite>ProxyClient</cite> instead.</p>
</div>
<p>The <tt class="docutils literal"><span class="pre">useragent</span></tt> parameter is useful for identifying in log files that your
script is calling the server rather than another. The default value is
<tt class="docutils literal"><span class="pre">Fedora</span> <span class="pre">BaseClient/VERSION</span></tt> where VERSION is the version of the
<a class="reference internal" href="api.html#fedora.client.BaseClient" title="fedora.client.BaseClient"><tt class="xref py py-class docutils literal"><span class="pre">BaseClient</span></tt></a> module. If you want to override this just
give another string to this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">client</span> <span class="o">=</span> <span class="n">BaseClient</span><span class="p">(</span><span class="s">'https://admin.fedoraproject.org/pkgdb'</span><span class="p">,</span>
<span class="n">useragent</span><span class="o">=</span><span class="s">'Package Database Client/1.0'</span><span class="p">)</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">debug</span></tt> parameter turns on a little extra output when running the
program. Set it to true if you’re having trouble and want to figure out what
is happening inside of the <a class="reference internal" href="api.html#fedora.client.BaseClient" title="fedora.client.BaseClient"><tt class="xref py py-class docutils literal"><span class="pre">BaseClient</span></tt></a> code.</p>
</div>
<div class="section" id="send-request">
<h4>send_request()<a class="headerlink" href="#send-request" title="Permalink to this headline">¶</a></h4>
<p><tt class="docutils literal"><span class="pre">send_request()</span></tt> is what does the heavy lifting of making a request of the
server, receiving the reply, and turning that into a python dictionary. The
usage is pretty straightforward.</p>
<p>The first argument to <tt class="docutils literal"><span class="pre">send_request()</span></tt> is <tt class="docutils literal"><span class="pre">method</span></tt>. It contains the name
of the method on the server. It also has any of the positional parameters
that the method expects (extra path information interpreted by the server for
those building non-<a class="reference external" href="http://www.turbogears.org/">TurboGears</a> applications).</p>
<p>The <tt class="docutils literal"><span class="pre">auth</span></tt> keyword argument is a boolean. If True, the session cookie for
the user is sent to the server. If this fails, the <tt class="docutils literal"><span class="pre">username</span></tt> and
<tt class="docutils literal"><span class="pre">password</span></tt> are sent. If that fails, an <a class="reference internal" href="#exceptions">Exception</a> is raised that you can
handle in your code.</p>
<p><tt class="docutils literal"><span class="pre">req_params</span></tt> contains a dictionary of additional keyword arguments for the
server method. These would be the names and values returned via a form if it
was a CGI. Note that parameters passed as extra path information should be
added to the <tt class="docutils literal"><span class="pre">method</span></tt> argument instead.</p>
<p>An example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">BaseClient</span>
<span class="n">client</span> <span class="o">=</span> <span class="n">BaseClient</span><span class="p">(</span><span class="s">'https://admin.fedoraproject.org/pkgdb/'</span><span class="p">)</span>
<span class="n">client</span><span class="o">.</span><span class="n">send_request</span><span class="p">(</span><span class="s">'/package/name/python-fedora'</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span>
<span class="n">req_params</span><span class="o">=</span><span class="p">{</span><span class="s">'collectionVersion'</span><span class="p">:</span> <span class="s">'9'</span><span class="p">,</span> <span class="s">'collectionName'</span><span class="p">:</span> <span class="s">'Fedora'</span><span class="p">})</span>
</pre></div>
</div>
<p>In this particular example, knowing how the server works, <tt class="docutils literal"><span class="pre">/packages/name/</span></tt>
defines the method that the server is going to invoke. <tt class="docutils literal"><span class="pre">python-fedora</span></tt> is a
positional parameter for the name of the package we’re looking up.
<tt class="docutils literal"><span class="pre">auth=False</span></tt> means that we’ll try to look at this method without having to
authenticate. The <tt class="docutils literal"><span class="pre">req_params</span></tt> sends two additional keyword arguments:
<tt class="docutils literal"><span class="pre">collectionName</span></tt> which specifies whether to filter on a single distro or
include Fedora, Fedora EPEL, Fedora OLPC, and Red Hat Linux in the output and
<tt class="docutils literal"><span class="pre">collectionVersion</span></tt> which specifies which version of the distribution to
output for.</p>
<p>The URL constructed by <a class="reference internal" href="api.html#fedora.client.BaseClient" title="fedora.client.BaseClient"><tt class="xref py py-class docutils literal"><span class="pre">BaseClient</span></tt></a> to the server could
be expressed as[#]_:</p>
<div class="highlight-python"><pre>https://admin.fedoraproject.org/pkgdb/package/name/python-fedora/?collectionName=Fedora&collectionVersion=9</pre>
</div>
<p>In previous releases of python-fedora, there would be one further query
parameter: <tt class="docutils literal"><span class="pre">tg_format=json</span></tt>. That parameter instructed the server to
return the information as JSON data instead of HTML. Although this is usually
still supported in the server, <a class="reference internal" href="api.html#fedora.client.BaseClient" title="fedora.client.BaseClient"><tt class="xref py py-class docutils literal"><span class="pre">BaseClient</span></tt></a> has
deprecated this method. Servers should be configured to use an <tt class="docutils literal"><span class="pre">Accept</span></tt>
header to get this information instead. See the <a class="reference external" href="service.html#selecting-json-output">JSON output</a> section of the
<a class="reference external" href="service.html">Fedora Service</a> documentation for more information about the server side.</p>
</div>
</div>
<div class="section" id="subclassing">
<h3>Subclassing<a class="headerlink" href="#subclassing" title="Permalink to this headline">¶</a></h3>
<p>Building a client using subclassing builds on the information you’ve already
seen inside of <a class="reference internal" href="api.html#fedora.client.BaseClient" title="fedora.client.BaseClient"><tt class="xref py py-class docutils literal"><span class="pre">BaseClient</span></tt></a>. You might want to use this
if you want to provide a module for third parties to access a particular
<a class="reference external" href="service.html">Fedora Service</a>. A subclass can provide a set of standard methods for
calling the server instead of forcing the user to remember the URLs used to
access the server directly.</p>
<p>Here’s an example that turns the previous calls into the basis of a python API
to the <a class="reference external" href="https://fedorahosted.org/packagedb">Fedora Package Database</a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">getpass</span>
<span class="kn">import</span> <span class="nn">sys</span>
<span class="kn">from</span> <span class="nn">fedora.client</span> <span class="kn">import</span> <span class="n">BaseClient</span><span class="p">,</span> <span class="n">AuthError</span>
<span class="k">class</span> <span class="nc">MyClient</span><span class="p">(</span><span class="n">BaseClient</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">baseURL</span><span class="o">=</span><span class="s">'https://admin.fedoraproject.org/pkgdb'</span><span class="p">,</span>
<span class="n">username</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">password</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
<span class="n">useragent</span><span class="o">=</span><span class="s">'Package Database Client/1.0'</span><span class="p">,</span> <span class="n">debug</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="nb">super</span><span class="p">(</span><span class="n">BaseClient</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="n">baseURL</span><span class="p">,</span> <span class="n">username</span><span class="p">,</span> <span class="n">password</span><span class="p">,</span>
<span class="n">useragent</span><span class="p">,</span> <span class="n">debug</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">collection_list</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">'''Return a list of collections.'''</span>
<span class="k">return</span> <span class="n">client</span><span class="o">.</span><span class="n">send_request</span><span class="p">(</span><span class="s">'/collection'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">package_owners</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">package</span><span class="p">,</span> <span class="n">collectionName</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
<span class="n">collectionVersion</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="sd">'''Return a mapping of release to owner for this package.'''</span>
<span class="n">pkgData</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">send_request</span><span class="p">(</span><span class="s">'/packages/name/</span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">package</span><span class="p">),</span>
<span class="p">{</span><span class="s">'collectionName'</span><span class="p">:</span> <span class="n">collectionName</span><span class="p">,</span>
<span class="s">'collectionVersion'</span><span class="p">:</span> <span class="n">collectionVersion</span><span class="p">})</span>
<span class="n">ownerMap</span> <span class="o">=</span> <span class="p">{}</span>
<span class="k">for</span> <span class="n">listing</span> <span class="ow">in</span> <span class="n">pkgData</span><span class="p">[</span><span class="s">'packageListings'</span><span class="p">]:</span>
<span class="n">ownerMap</span><span class="p">[</span><span class="s">'-'</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">listing</span><span class="p">[</span><span class="s">'collection'</span><span class="p">][</span><span class="s">'name'</span><span class="p">],</span>
<span class="n">listing</span><span class="p">[</span><span class="s">'collection'</span><span class="p">][</span><span class="s">'version'</span><span class="p">])]</span> <span class="o">=</span> \
<span class="n">listing</span><span class="p">[</span><span class="s">'owneruser'</span><span class="p">]</span>
<span class="k">return</span> <span class="n">ownerMap</span>
</pre></div>
</div>
<p>A few things to note:</p>
<ol class="arabic simple">
<li>In our constructor we list a default <tt class="docutils literal"><span class="pre">baseURL</span></tt> and <tt class="docutils literal"><span class="pre">useragent</span></tt>. This
is usually a good idea as we know the URL of the <a class="reference external" href="service.html">Fedora Service</a> we’re
connecting to and we want to know that people are using our specific API.</li>
<li>Sometimes we’ll want methods that are thin shells around the server methods
like <tt class="docutils literal"><span class="pre">collection_list()</span></tt>. Other times we’ll want to do more
post processing to get specific results as <tt class="docutils literal"><span class="pre">package_owners()</span></tt> does. Both
types of methods are valid if they fit the needs of your API. If you find
yourself writing more of the latter, though, you may want to consider
getting a new method implemented in the server that can return results more
appropriate to your needs as it could save processing on the server and
bandwidth downloading the data to get information that more closely matches
what you need.</li>
</ol>
<p>See <tt class="docutils literal"><span class="pre">pydoc</span> <span class="pre">fedora.accounts.fas2</span></tt> for a module that implements a standard
client API for the <a class="reference external" href="https://fedorahosted.org/fas/">Fedora Account System</a></p>
</div>
</div>
<div class="section" id="handling-errors">
<h2>Handling Errors<a class="headerlink" href="#handling-errors" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="api.html#fedora.client.BaseClient" title="fedora.client.BaseClient"><tt class="xref py py-class docutils literal"><span class="pre">BaseClient</span></tt></a> will throw a variety of errors that can be
caught to tell you what kind of error was generated.</p>
<div class="section" id="exceptions">
<h3>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name" colspan="2"><tt class="docutils literal"><span class="pre">FedoraServiceError</span></tt>:</th></tr>
<tr><td> </td><td class="field-body">The base of all exceptions raised by
<a class="reference internal" href="api.html#fedora.client.BaseClient" title="fedora.client.BaseClient"><tt class="xref py py-class docutils literal"><span class="pre">BaseClient</span></tt></a>. If your code needs to catch any of the
listed errors then you can catch that to do so.</td>
</tr>
<tr class="field"><th class="field-name"><tt class="docutils literal"><span class="pre">ServerError</span></tt>:</th><td class="field-body">Raised if there’s a problem communicating with the service.
For instance, if we receive an HTML response instead of JSON.</td>
</tr>
<tr class="field"><th class="field-name"><tt class="docutils literal"><span class="pre">AuthError</span></tt>:</th><td class="field-body">If something happens during authentication, like an invalid
usernsme or password, <tt class="docutils literal"><span class="pre">AuthError</span></tt> will be raised. You can catch this to
prompt the user for a new usernsme.</td>
</tr>
<tr class="field"><th class="field-name"><tt class="docutils literal"><span class="pre">AppError</span></tt>:</th><td class="field-body">If there is a <a class="reference external" href="service.html#ErrorHandling">server side error</a> when processing a request,
the <a class="reference external" href="service.html">Fedora Service</a> can alert the client of this by setting certain
flags in the response. <a class="reference internal" href="api.html#fedora.client.BaseClient" title="fedora.client.BaseClient"><tt class="xref py py-class docutils literal"><span class="pre">BaseClient</span></tt></a> will see these
flags and raise an AppError. The name of the error will be stored in
AppError’s <tt class="docutils literal"><span class="pre">name</span></tt> field. The error’s message will be stored in
<tt class="docutils literal"><span class="pre">message</span></tt>.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="example">
<h3>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h3>
<p>Here’s an example of the exceptions in action:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">fedora.client</span> <span class="kn">import</span> <span class="n">ServerError</span><span class="p">,</span> <span class="n">AuthError</span><span class="p">,</span> <span class="n">AppError</span><span class="p">,</span> <span class="n">BaseClient</span>
<span class="kn">import</span> <span class="nn">getpass</span>
<span class="n">MAXRETRIES</span> <span class="o">=</span> <span class="mi">5</span>
<span class="n">client</span> <span class="o">=</span> <span class="n">BaseClient</span><span class="p">(</span><span class="s">'https://admin.fedoraproject.org/pkgdb'</span><span class="p">)</span>
<span class="k">for</span> <span class="n">retry</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="n">MAXRETRIES</span><span class="p">):</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">collectionData</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">send_request</span><span class="p">(</span><span class="s">'/collections'</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">except</span> <span class="n">AuthError</span><span class="p">,</span> <span class="n">e</span><span class="p">:</span>
<span class="n">client</span><span class="o">.</span><span class="n">username</span> <span class="o">=</span> <span class="nb">raw_input</span><span class="p">(</span><span class="s">'Username: '</span><span class="p">)</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span>
<span class="n">client</span><span class="o">.</span><span class="n">password</span> <span class="o">=</span> <span class="n">getpass</span><span class="o">.</span><span class="n">getpass</span><span class="p">(</span><span class="s">'Password: '</span><span class="p">)</span>
<span class="k">continue</span>
<span class="k">except</span> <span class="n">ServerError</span><span class="p">,</span> <span class="n">e</span><span class="p">:</span>
<span class="k">print</span> <span class="s">'Error talking to the server: </span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="n">e</span>
<span class="k">break</span>
<span class="k">except</span> <span class="n">AppError</span><span class="p">,</span> <span class="n">e</span><span class="p">:</span>
<span class="k">print</span> <span class="s">'The server issued the following exception: </span><span class="si">%s</span><span class="s">: </span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span>
<span class="n">e</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">e</span><span class="o">.</span><span class="n">message</span><span class="p">)</span>
<span class="k">for</span> <span class="n">collection</span> <span class="ow">in</span> <span class="n">collectionData</span><span class="p">[</span><span class="s">'collections'</span><span class="p">]:</span>
<span class="k">print</span> <span class="n">collection</span><span class="p">[</span><span class="mi">0</span><span class="p">][</span><span class="s">'name'</span><span class="p">],</span> <span class="n">collection</span><span class="p">[</span><span class="mi">0</span><span class="p">][</span><span class="s">'version'</span><span class="p">]</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Fedora Client</a><ul>
<li><a class="reference internal" href="#baseclient">BaseClient</a><ul>
<li><a class="reference internal" href="#using-standalone">Using Standalone</a><ul>
<li><a class="reference internal" href="#baseclient-constructor">BaseClient Constructor</a></li>
<li><a class="reference internal" href="#send-request">send_request()</a></li>
</ul>
</li>
<li><a class="reference internal" href="#subclassing">Subclassing</a></li>
</ul>
</li>
<li><a class="reference internal" href="#handling-errors">Handling Errors</a><ul>
<li><a class="reference internal" href="#exceptions">Exceptions</a></li>
<li><a class="reference internal" href="#example">Example</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">Python Fedora Module Documentation</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="existing.html"
title="next chapter">Existing Services</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/client.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="existing.html" title="Existing Services"
>next</a> |</li>
<li class="right" >
<a href="index.html" title="Python Fedora Module Documentation"
>previous</a> |</li>
<li><a href="index.html">python-fedora v0.3.25.1 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2007-2011 Red Hat, Inc..
Last updated on Nov 02, 2011.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
762e4b4e451f9de4722602c03fda2c9b
>
files
>
218
