1
=========================
2
Interacting with the user
3
=========================
8
Processing Command Lines
9
------------------------
11
bzrlib has a standard framework for parsing command lines and calling
12
processing routines associated with various commands. See builtins.py
13
for numerous examples.
16
Standard Parameter Types
17
------------------------
19
There are some common requirements in the library: some parameters need to be
20
unicode safe, some need byte strings, and so on. At the moment we have
21
only codified one specific pattern: Parameters that need to be unicode
22
should be checked via ``bzrlib.osutils.safe_unicode``. This will coerce the
23
input into unicode in a consistent fashion, allowing trivial strings to be
24
used for programmer convenience, but not performing unpredictably in the
25
presence of different locales.
30
There are some operations, such as uncommitting, or breaking a lock, where
31
bzr may want to get confirmation from the user before proceeding.
32
However in some circumstances bzr should just go ahead without asking: if
33
it's being used from a noninteractive program, or if the user's asked to
34
never be asked for this particular confirmation or for any confirmations
37
We provide a special UIFactory method `confirm_action` to do this. It
38
takes a `confirmation_id` parameter that acts as a symbolic name for the
39
type of confirmation, so the user can configure them off. (This is not
40
implemented at present.) GUIs can have a "don't ask me again" option
41
keyed by the confirmation id.
43
Confirmation ids look like Python paths to the logical code that should
44
use them. (Because code may move or the check may for implementation
45
reasons be done elsewhere, they need not perfectly correspond to the place
46
they're used, and they should stay stable even when the code moves.)
48
``bzrlib.builtins.uncommit``
49
Before the ``uncommit`` command actually changes the branch.
51
``bzrlib.lockdir.break``
52
Before breaking a lock.
54
``bzrlib.msgeditor.unchanged``
55
Proceed even though the user made no changes to the template message.
57
Interactive confirmations can be overridden by using a
58
`ConfirmationUserInterfacePolicy` decorator as the default
65
(The strategy described here is what we want to get to, but it's not
66
consistently followed in the code at the moment.)
68
bzrlib is intended to be a generically reusable library. It shouldn't
69
write messages to stdout or stderr, because some programs that use it
70
might want to display that information through a GUI or some other
73
We can distinguish two types of output from the library:
75
1. Structured data representing the progress or result of an
76
operation. For example, for a commit command this will be a list
77
of the modified files and the finally committed revision number
80
These should be exposed either through the return code or by calls
81
to a callback parameter.
83
A special case of this is progress indicators for long-lived
84
operations, where the caller should pass a ProgressBar object.
86
2. Unstructured log/debug messages, mostly for the benefit of the
87
developers or users trying to debug problems. This should always
88
be sent through ``bzrlib.trace`` and Python ``logging``, so that
89
it can be redirected by the client.
91
The distinction between the two is a bit subjective, but in general if
92
there is any chance that a library would want to see something as
93
structured data, we should make it so.
95
The policy about how output is presented in the text-mode client
96
should be only in the command-line tool.
99
Progress and Activity Indications
100
---------------------------------
102
bzrlib has a way for code to display to the user that stuff is happening
103
during a long operation. There are two particular types: *activity* which
104
means that IO is happening on a Transport, and *progress* which means that
105
higher-level application work is occurring. Both are drawn together by
108
Transport objects are responsible for calling `report_transport_activity`
111
Progress uses a model/view pattern: application code acts on a
112
`ProgressTask` object, which notifies the UI when it needs to be
113
displayed. Progress tasks form a stack. To create a new progress task on
114
top of the stack, call `bzrlib.ui.ui_factory.nested_progress_bar()`, then
115
call `update()` on the returned ProgressTask. It can be updated with just
116
a text description, with a numeric count, or with a numeric count and
117
expected total count. If an expected total count is provided the view
118
can show the progress moving along towards the expected total.
120
The user should call `finish` on the `ProgressTask` when the logical
121
operation has finished, so it can be removed from the stack.
123
Progress tasks have a complex relationship with generators: it's a very
124
good place to use them, but because python2.4 does not allow ``finally``
125
blocks in generators it's hard to clean them up properly. In this case
126
it's probably better to have the code calling the generator allocate a
127
progress task for its use and then call `finalize` when it's done, which
128
will close it if it was not already closed. The generator should also
129
finish the progress task when it exits, because it may otherwise be a long
130
time until the finally block runs.
136
When filenames or similar variables are presented inline within a message,
137
they should be enclosed in double quotes (ascii 0x22, not chiral unicode
140
bzr: ERROR: No such file "asdf"
142
When we print just a list of filenames there should not be any quoting:
145
.. _bug 544297: https://bugs.launchpad.net/bugs/544297
147
https://wiki.ubuntu.com/UnitsPolicy provides a good explanation about
148
which unit should be used when. Roughly speaking, IEC standard applies
149
for base-2 units and SI standard applies for base-10 units:
151
* for network bandwidth and disk sizes, use base-10 (Mbits/s, kB/s, GB)
153
* for RAM sizes, use base-2 (GiB, TiB)
160
Bazaar has online help for various topics through ``bzr help COMMAND`` or
161
equivalently ``bzr command -h``. We also have help on command options,
162
and on other help topics. (See ``help_topics.py``.)
164
As for python docstrings, the first paragraph should be a single-sentence
165
synopsis of the command. These are user-visible and should be prefixed with
166
``__doc__ =`` so help works under ``python -OO`` with docstrings stripped.
168
The help for options should be one or more proper sentences, starting with
169
a capital letter and finishing with a full stop (period).
171
All help messages and documentation should have two spaces between
175
Handling Errors and Exceptions
176
==============================
178
Commands should return non-zero when they encounter circumstances that
179
the user should really pay attention to - which includes trivial shell
182
Recommended values are:
185
1. Conflicts in merge-like operations, or changes are present in
186
diff-like operations.
187
2. Unrepresentable diff changes (i.e. binary files that we cannot show
189
3. An error or exception has occurred.
190
4. An internal error occurred (one that shows a traceback.)
192
Errors are handled through Python exceptions. Exceptions should be defined
193
inside bzrlib.errors, so that we can see the whole tree at a glance.
195
We broadly classify errors as either being either internal or not,
196
depending on whether ``internal_error`` is set or not. If we think it's our
197
fault, we show a backtrace, an invitation to report the bug, and possibly
198
other details. This is the default for errors that aren't specifically
199
recognized as being caused by a user error. Otherwise we show a briefer
200
message, unless -Derror was given.
202
Many errors originate as "environmental errors" which are raised by Python
203
or builtin libraries -- for example IOError. These are treated as being
204
our fault, unless they're caught in a particular tight scope where we know
205
that they indicate a user errors. For example if the repository format
206
is not found, the user probably gave the wrong path or URL. But if one of
207
the files inside the repository is not found, then it's our fault --
208
either there's a bug in bzr, or something complicated has gone wrong in
209
the environment that means one internal file was deleted.
211
Many errors are defined in ``bzrlib/errors.py`` but it's OK for new errors
212
to be added near the place where they are used.
214
Exceptions are formatted for the user by conversion to a string
215
(eventually calling their ``__str__`` method.) As a convenience the
216
``._fmt`` member can be used as a template which will be mapped to the
217
error's instance dict.
219
New exception classes should be defined when callers might want to catch
220
that exception specifically, or when it needs a substantially different
223
#. If it is something that a caller can recover from, a custom exception
226
#. If it is a data consistency issue, using a builtin like
227
``ValueError``/``TypeError`` is reasonable.
229
#. If it is a programmer error (using an api incorrectly)
230
``AssertionError`` is reasonable.
232
#. Otherwise, use ``BzrError`` or ``InternalBzrError``.
234
Exception strings should start with a capital letter and should not have a
235
final fullstop. If long, they may contain newlines to break the text.
added
removed
doc/developers/ui.txt
