<!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="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Interacting with the user — Bazaar 2.7.0 documentation</title>
<link rel="stylesheet" href="_static/classic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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>
<script type="text/javascript" src="_static/language_data.js"></script>
<link rel="shortcut icon" href="_static/bzr.ico"/>
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Releasing Bazaar" href="releasing.html" />
<link rel="prev" title="Developer guide to bzrlib transports" href="transports.html" />
<link rel="stylesheet" href="_static/bzr-doc.css" type="text/css" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="releasing.html" title="Releasing Bazaar"
accesskey="N">next</a></li>
<li class="right" >
<a href="transports.html" title="Developer guide to bzrlib transports"
accesskey="P">previous</a> |</li>
<li><a href="http://bazaar.canonical.com/">
<img src="_static/bzr icon 16.png" /> Home</a> | </li>
<a href="http://doc.bazaar.canonical.com/en/">Documentation</a> | </li>
<li class="nav-item nav-item-0"><a href="index.html">Developer Document Catalog (2.7.0)</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="interacting-with-the-user">
<h1>Interacting with the user<a class="headerlink" href="#interacting-with-the-user" title="Permalink to this headline">¶</a></h1>
<div class="section" id="getting-input">
<h2>Getting Input<a class="headerlink" href="#getting-input" title="Permalink to this headline">¶</a></h2>
<div class="section" id="processing-command-lines">
<h3>Processing Command Lines<a class="headerlink" href="#processing-command-lines" title="Permalink to this headline">¶</a></h3>
<p>bzrlib has a standard framework for parsing command lines and calling
processing routines associated with various commands. See builtins.py
for numerous examples.</p>
</div>
<div class="section" id="standard-parameter-types">
<h3>Standard Parameter Types<a class="headerlink" href="#standard-parameter-types" title="Permalink to this headline">¶</a></h3>
<p>There are some common requirements in the library: some parameters need to be
unicode safe, some need byte strings, and so on. At the moment we have
only codified one specific pattern: Parameters that need to be unicode
should be checked via <code class="docutils literal notranslate"><span class="pre">bzrlib.osutils.safe_unicode</span></code>. This will coerce the
input into unicode in a consistent fashion, allowing trivial strings to be
used for programmer convenience, but not performing unpredictably in the
presence of different locales.</p>
</div>
</div>
<div class="section" id="confirmation">
<h2>Confirmation<a class="headerlink" href="#confirmation" title="Permalink to this headline">¶</a></h2>
<p>There are some operations, such as uncommitting, or breaking a lock, where
bzr may want to get confirmation from the user before proceeding.
However in some circumstances bzr should just go ahead without asking: if
it’s being used from a noninteractive program, or if the user’s asked to
never be asked for this particular confirmation or for any confirmations
at all.</p>
<p>We provide a special UIFactory method <cite>confirm_action</cite> to do this. It
takes a <cite>confirmation_id</cite> parameter that acts as a symbolic name for the
type of confirmation, so the user can configure them off. (This is not
implemented at present.) GUIs can have a “don’t ask me again” option
keyed by the confirmation id.</p>
<p>Confirmation ids look like Python paths to the logical code that should
use them. (Because code may move or the check may for implementation
reasons be done elsewhere, they need not perfectly correspond to the place
they’re used, and they should stay stable even when the code moves.)</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">bzrlib.builtins.uncommit</span></code></dt>
<dd>Before the <code class="docutils literal notranslate"><span class="pre">uncommit</span></code> command actually changes the branch.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">bzrlib.lockdir.break</span></code></dt>
<dd>Before breaking a lock.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">bzrlib.msgeditor.unchanged</span></code></dt>
<dd>Proceed even though the user made no changes to the template message.</dd>
</dl>
<p>Interactive confirmations can be overridden by using a
<cite>ConfirmationUserInterfacePolicy</cite> decorator as the default
ui_factory.</p>
</div>
<div class="section" id="writing-output">
<h2>Writing Output<a class="headerlink" href="#writing-output" title="Permalink to this headline">¶</a></h2>
<p>(The strategy described here is what we want to get to, but it’s not
consistently followed in the code at the moment.)</p>
<p>bzrlib is intended to be a generically reusable library. It shouldn’t
write messages to stdout or stderr, because some programs that use it
might want to display that information through a GUI or some other
mechanism.</p>
<p>We can distinguish two types of output from the library:</p>
<blockquote>
<div><ol class="arabic">
<li><p class="first">Structured data representing the progress or result of an
operation. For example, for a commit command this will be a list
of the modified files and the finally committed revision number
and id.</p>
<p>These should be exposed either through the return code or by calls
to a callback parameter.</p>
<p>A special case of this is progress indicators for long-lived
operations, where the caller should pass a ProgressBar object.</p>
</li>
<li><p class="first">Unstructured log/debug messages, mostly for the benefit of the
developers or users trying to debug problems. This should always
be sent through <code class="docutils literal notranslate"><span class="pre">bzrlib.trace</span></code> and Python <code class="docutils literal notranslate"><span class="pre">logging</span></code>, so that
it can be redirected by the client.</p>
</li>
</ol>
</div></blockquote>
<p>The distinction between the two is a bit subjective, but in general if
there is any chance that a library would want to see something as
structured data, we should make it so.</p>
<p>The policy about how output is presented in the text-mode client
should be only in the command-line tool.</p>
<div class="section" id="progress-and-activity-indications">
<h3>Progress and Activity Indications<a class="headerlink" href="#progress-and-activity-indications" title="Permalink to this headline">¶</a></h3>
<p>bzrlib has a way for code to display to the user that stuff is happening
during a long operation. There are two particular types: <em>activity</em> which
means that IO is happening on a Transport, and <em>progress</em> which means that
higher-level application work is occurring. Both are drawn together by
the <cite>ui_factory</cite>.</p>
<p>Transport objects are responsible for calling <cite>report_transport_activity</cite>
when they do IO.</p>
<p>Progress uses a model/view pattern: application code acts on a
<cite>ProgressTask</cite> object, which notifies the UI when it needs to be
displayed. Progress tasks form a stack. To create a new progress task on
top of the stack, call <cite>bzrlib.ui.ui_factory.nested_progress_bar()</cite>, then
call <cite>update()</cite> on the returned ProgressTask. It can be updated with just
a text description, with a numeric count, or with a numeric count and
expected total count. If an expected total count is provided the view
can show the progress moving along towards the expected total.</p>
<p>The user should call <cite>finish</cite> on the <cite>ProgressTask</cite> when the logical
operation has finished, so it can be removed from the stack.</p>
<p>Progress tasks have a complex relationship with generators: it’s a very
good place to use them, but because python2.4 does not allow <code class="docutils literal notranslate"><span class="pre">finally</span></code>
blocks in generators it’s hard to clean them up properly. In this case
it’s probably better to have the code calling the generator allocate a
progress task for its use and then call <cite>finalize</cite> when it’s done, which
will close it if it was not already closed. The generator should also
finish the progress task when it exits, because it may otherwise be a long
time until the finally block runs.</p>
</div>
<div class="section" id="message-guidelines">
<h3>Message guidelines<a class="headerlink" href="#message-guidelines" title="Permalink to this headline">¶</a></h3>
<p>When filenames or similar variables are presented inline within a message,
they should be enclosed in double quotes (ascii 0x22, not chiral unicode
quotes):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">bzr</span><span class="p">:</span> <span class="n">ERROR</span><span class="p">:</span> <span class="n">No</span> <span class="n">such</span> <span class="n">file</span> <span class="s2">"asdf"</span>
</pre></div>
</div>
<p>When we print just a list of filenames there should not be any quoting:
see <a class="reference external" href="https://bugs.launchpad.net/bugs/544297">bug 544297</a>.</p>
<p><a class="reference external" href="https://wiki.ubuntu.com/UnitsPolicy">https://wiki.ubuntu.com/UnitsPolicy</a> provides a good explanation about
which unit should be used when. Roughly speaking, IEC standard applies
for base-2 units and SI standard applies for base-10 units:</p>
<ul class="simple">
<li>for network bandwidth and disk sizes, use base-10 (Mbits/s, kB/s, GB)</li>
<li>for RAM sizes, use base-2 (GiB, TiB)</li>
</ul>
</div>
</div>
<div class="section" id="displaying-help">
<h2>Displaying help<a class="headerlink" href="#displaying-help" title="Permalink to this headline">¶</a></h2>
<p>Bazaar has online help for various topics through <code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">help</span> <span class="pre">COMMAND</span></code> or
equivalently <code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">command</span> <span class="pre">-h</span></code>. We also have help on command options,
and on other help topics. (See <code class="docutils literal notranslate"><span class="pre">help_topics.py</span></code>.)</p>
<p>As for python docstrings, the first paragraph should be a single-sentence
synopsis of the command. These are user-visible and should be prefixed with
<code class="docutils literal notranslate"><span class="pre">__doc__</span> <span class="pre">=</span></code> so help works under <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-OO</span></code> with docstrings stripped.</p>
<p>The help for options should be one or more proper sentences, starting with
a capital letter and finishing with a full stop (period).</p>
<p>All help messages and documentation should have two spaces between
sentences.</p>
</div>
<div class="section" id="handling-errors-and-exceptions">
<h2>Handling Errors and Exceptions<a class="headerlink" href="#handling-errors-and-exceptions" title="Permalink to this headline">¶</a></h2>
<p>Commands should return non-zero when they encounter circumstances that
the user should really pay attention to - which includes trivial shell
pipelines.</p>
<p>Recommended values are:</p>
<blockquote>
<div><ol class="arabic simple" start="0">
<li>OK.</li>
<li>Conflicts in merge-like operations, or changes are present in
diff-like operations.</li>
<li>Unrepresentable diff changes (i.e. binary files that we cannot show
a diff of).</li>
<li>An error or exception has occurred.</li>
<li>An internal error occurred (one that shows a traceback.)</li>
</ol>
</div></blockquote>
<p>Errors are handled through Python exceptions. Exceptions should be defined
inside bzrlib.errors, so that we can see the whole tree at a glance.</p>
<p>We broadly classify errors as either being either internal or not,
depending on whether <code class="docutils literal notranslate"><span class="pre">internal_error</span></code> is set or not. If we think it’s our
fault, we show a backtrace, an invitation to report the bug, and possibly
other details. This is the default for errors that aren’t specifically
recognized as being caused by a user error. Otherwise we show a briefer
message, unless -Derror was given.</p>
<p>Many errors originate as “environmental errors” which are raised by Python
or builtin libraries – for example IOError. These are treated as being
our fault, unless they’re caught in a particular tight scope where we know
that they indicate a user errors. For example if the repository format
is not found, the user probably gave the wrong path or URL. But if one of
the files inside the repository is not found, then it’s our fault –
either there’s a bug in bzr, or something complicated has gone wrong in
the environment that means one internal file was deleted.</p>
<p>Many errors are defined in <code class="docutils literal notranslate"><span class="pre">bzrlib/errors.py</span></code> but it’s OK for new errors
to be added near the place where they are used.</p>
<p>Exceptions are formatted for the user by conversion to a string
(eventually calling their <code class="docutils literal notranslate"><span class="pre">__str__</span></code> method.) As a convenience the
<code class="docutils literal notranslate"><span class="pre">._fmt</span></code> member can be used as a template which will be mapped to the
error’s instance dict.</p>
<p>New exception classes should be defined when callers might want to catch
that exception specifically, or when it needs a substantially different
format string.</p>
<ol class="arabic simple">
<li>If it is something that a caller can recover from, a custom exception
is reasonable.</li>
<li>If it is a data consistency issue, using a builtin like
<code class="docutils literal notranslate"><span class="pre">ValueError</span></code>/<code class="docutils literal notranslate"><span class="pre">TypeError</span></code> is reasonable.</li>
<li>If it is a programmer error (using an api incorrectly)
<code class="docutils literal notranslate"><span class="pre">AssertionError</span></code> is reasonable.</li>
<li>Otherwise, use <code class="docutils literal notranslate"><span class="pre">BzrError</span></code> or <code class="docutils literal notranslate"><span class="pre">InternalBzrError</span></code>.</li>
</ol>
<p>Exception strings should start with a capital letter and should not have a
final fullstop. If long, they may contain newlines to break the text.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Interacting with the user</a><ul>
<li><a class="reference internal" href="#getting-input">Getting Input</a><ul>
<li><a class="reference internal" href="#processing-command-lines">Processing Command Lines</a></li>
<li><a class="reference internal" href="#standard-parameter-types">Standard Parameter Types</a></li>
</ul>
</li>
<li><a class="reference internal" href="#confirmation">Confirmation</a></li>
<li><a class="reference internal" href="#writing-output">Writing Output</a><ul>
<li><a class="reference internal" href="#progress-and-activity-indications">Progress and Activity Indications</a></li>
<li><a class="reference internal" href="#message-guidelines">Message guidelines</a></li>
</ul>
</li>
<li><a class="reference internal" href="#displaying-help">Displaying help</a></li>
<li><a class="reference internal" href="#handling-errors-and-exceptions">Handling Errors and Exceptions</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="transports.html"
title="previous chapter">Developer guide to bzrlib transports</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="releasing.html"
title="next chapter">Releasing Bazaar</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/ui.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="releasing.html" title="Releasing Bazaar"
>next</a></li>
<li class="right" >
<a href="transports.html" title="Developer guide to bzrlib transports"
>previous</a> |</li>
<li><a href="http://bazaar.canonical.com/">
<img src="_static/bzr icon 16.png" /> Home</a> | </li>
<a href="http://doc.bazaar.canonical.com/en/">Documentation</a> | </li>
<li class="nav-item nav-item-0"><a href="index.html">Developer Document Catalog (2.7.0)</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2009-2011 Canonical Ltd.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
</div>
</body>
</html>
