824
824
should be only in the command-line tool.
827
Progress and Activity Indications
828
---------------------------------
830
bzrlib has a way for code to display to the user that stuff is happening
831
during a long operation. There are two particular types: *activity* which
832
means that IO is happening on a Transport, and *progress* which means that
833
higher-level application work is occurring. Both are drawn together by
836
Transport objects are responsible for calling `report_transport_activity`
839
Progress uses a model/view pattern: application code acts on a
840
`ProgressTask` object, which notifies the UI when it needs to be
841
displayed. Progress tasks form a stack. To create a new progress task on
842
top of the stack, call `bzrlib.ui.ui_factory.nested_progress_bar()`, then
843
call `update()` on the returned ProgressTask. It can be updated with just
844
a text description, with a numeric count, or with a numeric count and
845
expected total count. If an expected total count is provided the view
846
can show the progress moving along towards the expected total.
848
The user should call `finish` on the `ProgressTask` when the logical
849
operation has finished, so it can be removed from the stack.
851
Progress tasks have a complex relatioship with generators: it's a very
852
good place to use them, but because python2.4 does not allow ``finally``
853
blocks in generators it's hard to clean them up properly. In this case
854
it's probably better to have the code calling the generator allocate a
855
progress task for its use and then call `finalize` when it's done, which
856
will close it if it was not already closed. The generator should also
857
finish the progress task when it exits, because it may otherwise be a long
858
time until the finally block runs.
added
removed
doc/developers/HACKING.txt
