=========================
Interacting with the user
=========================

Getting Input
=============

Processing Command Lines
------------------------

bzrlib has a standard framework for parsing command lines and calling
processing routines associated with various commands. See builtins.py
for numerous examples.


Standard Parameter Types
------------------------

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 ``bzrlib.osutils.safe_unicode``. 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.

Confirmation
============

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.

We provide a special UIFactory method `confirm_action` to do this.  It
takes a `confirmation_id` 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.

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.)

``bzrlib.builtins.uncommit``
    Before the ``uncommit`` command actually changes the branch.

``bzrlib.lockdir.break``
    Before breaking a lock.

``bzrlib.msgeditor.unchanged``
    Proceed even though the user made no changes to the template message.

Interactive confirmations can be overridden by using a
`ConfirmationUserInterfacePolicy` decorator as the default
ui_factory.


Writing Output
==============

(The strategy described here is what we want to get to, but it's not
consistently followed in the code at the moment.)

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.

We can distinguish two types of output from the library:

 1. 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.

    These should be exposed either through the return code or by calls
    to a callback parameter.

    A special case of this is progress indicators for long-lived
    operations, where the caller should pass a ProgressBar object.

 2. Unstructured log/debug messages, mostly for the benefit of the
    developers or users trying to debug problems.  This should always
    be sent through ``bzrlib.trace`` and Python ``logging``, so that
    it can be redirected by the client.

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.

The policy about how output is presented in the text-mode client
should be only in the command-line tool.


Progress and Activity Indications
---------------------------------

bzrlib has a way for code to display to the user that stuff is happening
during a long operation.  There are two particular types: *activity* which
means that IO is happening on a Transport, and *progress* which means that
higher-level application work is occurring.  Both are drawn together by
the `ui_factory`.

Transport objects are responsible for calling `report_transport_activity`
when they do IO.

Progress uses a model/view pattern: application code acts on a
`ProgressTask` 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 `bzrlib.ui.ui_factory.nested_progress_bar()`, then
call `update()` 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.

The user should call `finish` on the `ProgressTask` when the logical
operation has finished, so it can be removed from the stack.

Progress tasks have a complex relationship with generators: it's a very
good place to use them, but because python2.4 does not allow ``finally``
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 `finalize` 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.


Message guidelines
------------------

When filenames or similar variables are presented inline within a message,
they should be enclosed in double quotes (ascii 0x22, not chiral unicode
quotes)::

  bzr: ERROR: No such file "asdf"

When we print just a list of filenames there should not be any quoting:
see `bug 544297`_.

.. _bug 544297: https://bugs.launchpad.net/bugs/544297

https://wiki.ubuntu.com/UnitsPolicy 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:

* for network bandwidth and disk sizes, use base-10 (Mbits/s, kB/s, GB)

* for RAM sizes, use base-2 (GiB, TiB)



Displaying help
===============

Bazaar has online help for various topics through ``bzr help COMMAND`` or
equivalently ``bzr command -h``.  We also have help on command options,
and on other help topics.  (See ``help_topics.py``.)

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
``__doc__ =`` so help works under ``python -OO`` with docstrings stripped.

The help for options should be one or more proper sentences, starting with
a capital letter and finishing with a full stop (period).

All help messages and documentation should have two spaces between
sentences.


Handling Errors and Exceptions
==============================

Commands should return non-zero when they encounter circumstances that
the user should really pay attention to - which includes trivial shell
pipelines.

Recommended values are:

    0. OK.
    1. Conflicts in merge-like operations, or changes are present in
       diff-like operations.
    2. Unrepresentable diff changes (i.e. binary files that we cannot show
       a diff of).
    3. An error or exception has occurred.
    4. An internal error occurred (one that shows a traceback.)

Errors are handled through Python exceptions. Exceptions should be defined
inside bzrlib.errors, so that we can see the whole tree at a glance.

We broadly classify errors as either being either internal or not,
depending on whether ``internal_error`` 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.

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.

Many errors are defined in ``bzrlib/errors.py`` but it's OK for new errors
to be added near the place where they are used.

Exceptions are formatted for the user by conversion to a string
(eventually calling their ``__str__`` method.)  As a convenience the
``._fmt`` member can be used as a template which will be mapped to the
error's instance dict.

New exception classes should be defined when callers might want to catch
that exception specifically, or when it needs a substantially different
format string.

#. If it is something that a caller can recover from, a custom exception
   is reasonable.

#. If it is a data consistency issue, using a builtin like
   ``ValueError``/``TypeError`` is reasonable.

#. If it is a programmer error (using an api incorrectly)
   ``AssertionError`` is reasonable.

#. Otherwise, use ``BzrError`` or ``InternalBzrError``.

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.