Rev 5417: (mbp) split out ui-factory docs (Martin Pool) in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Fri Sep 10 07:09:32 BST 2010
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 5417 [merge]
revision-id: pqm at pqm.ubuntu.com-20100910060930-0ukm0h7txwadstll
parent: pqm at pqm.ubuntu.com-20100909055126-qwo256ldpnz7o0c4
parent: mbp at sourcefrog.net-20100903091412-1a40klgfg8c6k3xj
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Fri 2010-09-10 07:09:30 +0100
message:
(mbp) split out ui-factory docs (Martin Pool)
added:
doc/developers/ui.txt ui.txt-20100903090119-enuzuixmeqq0b2p0-1
modified:
doc/developers/HACKING.txt HACKING-20050805200004-2a5dc975d870f78c
doc/developers/index.txt index.txt-20070508041241-qznziunkg0nffhiw-1
=== modified file 'doc/developers/HACKING.txt'
--- a/doc/developers/HACKING.txt 2010-08-13 19:08:57 +0000
+++ b/doc/developers/HACKING.txt 2010-09-03 09:14:12 +0000
@@ -359,206 +359,6 @@
can't fix.
-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.
-
-
-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.
-
-
-
Documenting Changes
===================
=== modified file 'doc/developers/index.txt'
--- a/doc/developers/index.txt 2010-07-16 20:52:54 +0000
+++ b/doc/developers/index.txt 2010-09-03 09:14:12 +0000
@@ -36,6 +36,7 @@
:maxdepth: 1
transports
+ ui
Releasing and Packaging
=======================
=== added file 'doc/developers/ui.txt'
--- a/doc/developers/ui.txt 1970-01-01 00:00:00 +0000
+++ b/doc/developers/ui.txt 2010-09-03 09:14:12 +0000
@@ -0,0 +1,201 @@
+==========================================
+Bazaar Developer Guide to User Interaction
+==========================================
+
+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.
+
+
+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.
More information about the bazaar-commits
mailing list