Merge lp:~gz/bzr/support_OO_flag into lp:bzr

[Martin Packman]

Manually assign docstrings to command objects, so that they work with python -OO.

This is semi-automated change prepending `__doc__ = ` to the start of all docstrings that should be user, rather than just developer, visible. Therefore it's safe to run `python -OO bzr` which leads (with caveats) to smaller .pyo files on disk.

Bazaar is one of the few python projects that could actually benefit from stripping docstrings, it has lots, and startup time is very important. It's hard to measure cold startup on windows, but seems like a couple of tenths of a second win, though less than a tenth of a second for warm startup:

 C:\bzr\bzr\support_OO_flag>timeit \Python24\python.exe bzr version > nul

 Version Number: Windows NT 5.1 (Build 2600)
 Exit Time: 5:51 pm, Wednesday, March 31 2010
 Elapsed Time: 0:00:00.593
 Process Time: 0:00:00.546
 System Calls: 19835
 Context Switches: 4983
 Page Faults: 6681
 Bytes Read: 4436702
 Bytes Written: 2058
 Bytes Other: 124834

 C:\bzr\bzr\support_OO_flag>timeit \Python24\python.exe -OO bzr version > nul

 Version Number: Windows NT 5.1 (Build 2600)
 Exit Time: 5:51 pm, Wednesday, March 31 2010
 Elapsed Time: 0:00:00.562
 Process Time: 0:00:00.515
 System Calls: 18016
 Context Switches: 4862
 Page Faults: 6012
 Bytes Read: 3492931
 Bytes Written: 2058
 Bytes Other: 124268

The numbers vary a lot, but bytes read and page faults are that order of improvement.

Whether this is a useful change for improving startup time is another question. Distros don't install packages with docstring-stripped .pyo files, so likely only pre-built windows binary could benefit - and as that bundles plugins, only if those are modified too. Perhaps a worthy change even if don't want to distribute a docstring-less bzr, as it defends against someone else importing bzrlib when -OO and those files breaking help for normal usage.

If there's interest in landing this, there are a couple of things left. Needs NEWS, and probably a note in HACKING to say "add `__doc__ = ` to the start of docstrings you want the user to see". Later could look at doing the same thing to commands in plugins, then perhaps at creating the all-in-one installer without docstrings.

Some notes on the contents of the patch, as it's pretty big despite being trivial. It creates some long lines, but the help texts already have these anyway. I'm using the expression `__doc__ is None` as a backwards compatible version of `sys.flags.optimize == 2` in a few places, which is safe as the Bazaar code is quite consistent in supplying module docstrings. There are some mostly-obvious changes to tests. I had written a new blackbox test specifically to run with -OO, but better off just running selftest like that. When reinvoking python in bzrlib.tests.TestCase.start_bzr_subprocess should really propagate opt-ness, but doesn't matter much.

[Andrew Bennetts (spiv)]

I'm ambivalent. The benefit is pretty small, and likely to be even smaller as we improve the lazy loading of commands. On the other hand, the change is fairly small too, although superficially ugly.

Also, as you point out, the benefit cannot be realised until all the bundled plugins are updated like this as well. It would be nice to interoperate better with -OO code that uses bzrlib as a library... but I don't recall anyone ever complaining about that either.

As far as the implementation goes, this looks fine to me. The question is simply do we want to implement this?

Thanks very much for running the experiment, though! I had wondered what the benefit would be. How much size difference does it make, do you know?

review: Abstain

[John A Meinel (jameinel)]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Andrew Bennetts wrote:
> Review: Abstain
> I'm ambivalent. The benefit is pretty small, and likely to be even smaller as we improve the lazy loading of commands. On the other hand, the change is fairly small too, although superficially ugly.
>
> Also, as you point out, the benefit cannot be realised until all the bundled plugins are updated like this as well. It would be nice to interoperate better with -OO code that uses bzrlib as a library... but I don't recall anyone ever complaining about that either.
>
> As far as the implementation goes, this looks fine to me. The question is simply do we want to implement this?
>
> Thanks very much for running the experiment, though! I had wondered what the benefit would be. How much size difference does it make, do you know?

Well, we went this way for errors, though we did it using a new
attribute _fmt. Which I think actually went pretty well. We could even
do it compatibly with getattr(obj, '_fmt', None) else
deprecated(getattr(obj, '__doc__', None)), etc.

I think moving this way would be good. I think using something like _fmt
would be better than __doc__, if only to eliminate confusion. (And that
you can easily find out what bits aren't doing it the right way.)

John
=:->
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAku9QGcACgkQJdeBCYSNAAPPFACdGzxbNFzNOV5x/WdKXJvqLczF
fiAAnAgae2UQZao1XWHUelXKtrDJqYFL
=zzLa
-----END PGP SIGNATURE-----

[Robert Collins (lifeless)]

On Thu, 2010-04-08 at 02:36 +0000, John A Meinel wrote:
>
> I think moving this way would be good. I think using something like
> _fmt
> would be better than __doc__, if only to eliminate confusion. (And
> that
> you can easily find out what bits aren't doing it the right way.)

Well, you can find out easily with python -O0 too, so I don't think
thats really significant.

I love that pydoc shows the help at the moment, so I'd really rather not
see us use _fmt or something. It makes more sense with exceptions where
the API guide for the object doesn't correlate all that well with the
output we want from it.

-Rob

[Martin Packman (gz)]

> I'm ambivalent. The benefit is pretty small, and likely to be even smaller as
> we improve the lazy loading of commands. On the other hand, the change is
> fairly small too, although superficially ugly.

Yes, this and the lazy loading changes are orthogonal. Better laziness means less gain here, but likewise this will always be a win.

> Thanks very much for running the experiment, though! I had wondered what the
> benefit would be. How much size difference does it make, do you know?

Well, going on for a megabyte less read from disk in the `bzr version` example above. Overall:

 C:\bzr\bzr\dev>setup.py build_ext --allow-python-fallback install_lib -d %TEMP% -O2 2>nul>nul

 C:\bzr\bzr\dev>dir /S %TEMP%\bzrlib\*.py | grep -C1 Total

      Total Files Listed:
              719 File(s) 11,998,932 bytes

 C:\bzr\bzr\dev>dir /S %TEMP%\bzrlib\*.pyc | grep -C1 Total

      Total Files Listed:
              719 File(s) 10,010,178 bytes

 C:\bzr\bzr\dev>dir /S %TEMP%\bzrlib\*.pyo | grep -C1 Total

      Total Files Listed:
              719 File(s) 8,537,527 bytes

Most of the docstrings are in the lib not the tests which is why a lot of that saving is seen when running a command. Both kinds of compiled file compress to about 35% in a standard zip - bytecode compresses worse than text, but bytecode-and-text compresses no better than just bytecode.

> Well, we went this way for errors, though we did it using a new
> attribute _fmt. Which I think actually went pretty well. We could even
> do it compatibly with getattr(obj, '_fmt', None) else
> deprecated(getattr(obj, '__doc__', None)), etc.
>
> I think moving this way would be good. I think using something like _fmt
> would be better than __doc__, if only to eliminate confusion. (And that
> you can easily find out what bits aren't doing it the right way.)

Personally, I don't mind this kind of overloading of docstring function. Unlike with error format strings, the help text is still documentation. Sticking the __doc__ label at the front is ugly as Andrew says in some ways, but it also serves as a kind of @user_needs_to_see_this decorator. Reminder of the dual purpose and maybe the need to avoid "this command sucks and needs rewriting" notes.

[Martin Pool (mbp)]

I think that's kind of cool; given the pydoc point explicitly
assigning to __doc__ is probably the best tradeoff.

If we merge this, we should add a note to the developer guide about
why it is done this way, and ideally also add a test run to Babune
with -OO.
--
Martin <http://launchpad.net/~mbp/>

[Martin Packman (gz)]

Documentation added, put the news entry under 'Internals', move it to 'API Changes' or whatever on merge if that'd deemed more appropriate. The remaining step is to look at the installer creation stuff, see if there's a feasible benefit to be had. Can perhaps just strip bzrlib only to start, maybe Ian or someone can give me a hand working it out.

[Martin Pool (mbp)]

Ok, the documentation looks reasonable and I'm glad you thought of the case of plugins. Let's do it.

Ubuntu does have a small number of pyo files under /usr so perhaps it is possible to arrange for bzr to run with -OO and to then load precompiled stripped files.

review: Approve

[Robert Collins (lifeless)]

This looks good to go, except NEWS needs a fixup

[Martin Packman (gz)]

Is the fixup something I need to do prior to the normal merge?

I have a followup experimenting with using this in the windows packaging without messing with plugins that I'd like to see someone try. Interested to see how much it'll shrink the 17.2MB library.zip bundled currently.

[Robert Collins (lifeless)]

Someone needs to do it before it can be sent to PQM; in the
very-limited-awkward PQM access we had previously, it would go something
like this (and the person would be e.g. me/vila/poolie etc):

cd integration
bzr pull --overwrite [your branch]
bzr merge bzr.dev
fix-up-to-be-ready
bzr commit; bzr push; bzr pqm-submit -m ....

Now however, we can nearly push-button submit your branch, if you fix it up
and push; or we can do a similar but slightly more involved dance:

cd integration
bzr pull --overwrite [your branch]
bzr merge bzr.dev
fixup
bzr commit; bzr push; bzr lp-open; propose a new merge, copy your
description in, copy your commit message in, approve it;
$ feed-pqm bzr
m [set the commit message]
s [queues it]

We'll probably want a hydrazine command to clone a merge proposal and
update, for doing integration like this.

Easiest by far is if you update your branch to be ready-to-land.

[Martin Packman (gz)]

Thanks for the rundown, have merged trunk and updated.

[Robert Collins (lifeless)]

Sorry to be a pain, but are you aware that we keep each stanza of NEWS alphabetically sorted to ease merging? It looks like its not in alpha-order.

[Martin Packman (gz)]

Hgrf, no, either missed for forgotten about that edict. NEWS changed, will remember for the future.

[Robert Collins (lifeless)]

Thank you for that. There is one more thing you could start doing on new
proposals - fill in the 'comit message' field. We haven't been using it
previously, and we're not fully migrated yet, but I'll be adding it to the
general developers docs shortly.

[Martin Packman (gz)]

I messed up some logic that was causing failures that got blamed on <lp:~parthm/bzr/no-chown-if-bzrlog-exists> the last revision should resolve it.

[Vincent Ladeuil (vila)]

Unfortunately python -OO bzr selftest fails (see below), which is a bit weird.

bzr selftest: /home/vila/src/bzr/reviews/support_OO_flag/bzr
   /home/vila/src/bzr/reviews/support_OO_flag/bzrlib
   bzr-2.2.0dev1 python-2.6.4 Linux-2.6.31-20-generic-x86_64-with-Ubuntu-9.10-karmic

/home/vila/src/bzr/reviews/support_OO_flag/bzrlib/lazy_import.py:125: UserWarning: No help message set for <bzrlib.tests.test_commands.cmd_foo object at 0x93a8c10>
  return obj(*args, **kwargs)
/home/vila/src/bzr/reviews/support_OO_flag/bzrlib/commands.py:411: UserWarning: No help message set for <bzrlib.tests.test_commands.cmd_foo object at 0x939e450>
  warn("No help message set for %r" % self)
/home/vila/src/bzr/reviews/support_OO_flag/bzrlib/commands.py:411: UserWarning: No help message set for <bzrlib.tests.test_commands.cmd_test_extend_command_hook object at 0x9d1ba90>
  warn("No help message set for %r" % self)
/home/vila/src/bzr/reviews/support_OO_flag/bzrlib/commands.py:411: UserWarning: No help message set for <bzrlib.tests.test_commands.ACommand object at 0x938eb50>
  warn("No help message set for %r" % self)
/home/vila/src/bzr/reviews/support_OO_flag/bzrlib/commands.py:411: UserWarning: No help message set for <bzrlib.tests.test_commands.ACommand object at 0x9afdd10>
  warn("No help message set for %r" % self)
/home/vila/src/bzr/reviews/support_OO_flag/bzrlib/commands.py:411: UserWarning: No help message set for <bzrlib.tests.test_commands.ACommand object at 0x9afd6d0>
  warn("No help message set for %r" % self)
/home/vila/src/bzr/reviews/support_OO_flag/bzrlib/commands.py:411: UserWarning: No help message set for <bzrlib.tests.test_commands.ACommand object at 0x9afd290>
  warn("No help message set for %r" % self)
/home/vila/src/bzr/reviews/support_OO_flag/bzrlib/commands.py:411: UserWarning: No help message set for <bzrlib.tests.test_commands.ACommand object at 0x93a8d90>
  warn("No help message set for %r" % self)
/home/vila/src/bzr/reviews/support_OO_flag/bzrlib/commands.py:411: UserWarning: No help message set for <bzrlib.tests.test_commands.ACommand object at 0x93a8550>
  warn("No help message set for %r" % self)
/home/vila/src/bzr/reviews/support_OO_flag/bzrlib/commands.py:411: UserWarning: No help message set for <bzrlib.tests.test_commands.ACommand object at 0x93a8ad0>
  warn("No help message set for %r" % self)
/home/vila/src/bzr/reviews/support_OO_flag/bzrlib/commands.py:411: UserWarning: No help message set for <bzrlib.tests.test_commands.ACommand object at 0x9d4d150>
  warn("No help message set for %r" % self)
/home/vila/src/bzr/reviews/support_OO_flag/bzrlib/commands.py:411: UserWarning: No help message set for <bzrlib.tests.test_commands.ACommand object at 0x93a8450>
  warn("No help message set for %r" % self)
/home/vila/src/bzr/reviews/support_OO_flag/bzrlib/commands.py:411: UserWarning: No help message set for <bzrlib.tests.test_commands.ACommand object at 0x9d41210>
  warn("No help message set for %r" % self)
ERROR: test_commands.TestCommands.test_help_hidden
    Text attachment: log
------------

------------
Text attachment: traceback
------------
Traceback (most recent call last):
  File "/home/vila/lib/python/testtools/runtest.py", line...

review: Needs Fixing

[Martin Packman (gz)]

Urk, sorry Vincent, thanks for the report. These failures and the previous issue were due to poor workflow on my part. As selftest takes so long to run and has lots of spurious error output, I've been tending to only test a limited set of modules I know to have problems. Clearly this means I miss thing when it's a more involved changeset like this, apologies.

Anyway, I've fixed the failures you've identified and would be grateful if you tried again.

[Vincent Ladeuil (vila)]

>>>>> Martin [gz] writes:

    > Urk, sorry Vincent, thanks for the report.

No worries.

    > These failures and the previous issue were due to poor workflow on
    > my part. As selftest takes so long to run and has lots of spurious
    > error output, I've been tending to only test a limited set of
    > modules I know to have problems.

We all fall into this trap, repeatedly.

    > Clearly this means I miss thing when it's a more involved
    > changeset like this, apologies.

No need for that, really, that's why we have reviews and pqm (but in
that case, pqm would have failed to detect it though).

    > Anyway, I've fixed the failures you've identified and would be
    > grateful if you tried again.

Done. Works.

review: Approve

=== modified file 'NEWS'
--- NEWS	2010-04-22 13:32:23 +0000
+++ NEWS	2010-04-22 18:59:24 +0000
@@ -165,6 +165,19 @@
   Command is now transient and only exists for the duration of ``run()``.
   (Robert Collins)
 
+<<<<<<< TREE
+=======
+* Permit bzr to run under ``python -OO`` which reduces the size of bytecode
+  files loaded from disk. To ensure docstrings needed for help are never
+  stripped, the prefix ``__doc__ =`` should now be used.
+  (Martin <[e-mail]>)
+
+Testing
+*******
+
+* ``bzr selftest --parallel=subprocess`` now works correctly on win32.
+  (Gordon Tyler, #551332)
+>>>>>>> MERGE-SOURCE
 
 bzr 2.2.0b1
 ###########

=== modified file 'bzr'
--- bzr	2010-04-16 07:56:51 +0000
+++ bzr	2010-04-22 18:59:24 +0000
@@ -25,9 +25,6 @@
 # update this on each release
 _script_version = (2, 2, 0)
 
-if __doc__ is None:
-    print "bzr does not support python -OO."
-    sys.exit(2)
 try:
     version_info = sys.version_info
 except AttributeError:

=== modified file 'bzrlib/builtins.py'
--- bzrlib/builtins.py	2010-04-22 15:44:21 +0000
+++ bzrlib/builtins.py	2010-04-22 18:59:24 +0000
@@ -239,7 +239,7 @@
 # opens the branch?)
 
 class cmd_status(Command):
-    """Display status summary.
+    __doc__ = """Display status summary.
 
     This reports on versioned and unknown files, reporting them
     grouped by state.  Possible states are:
@@ -332,7 +332,7 @@
 
 
 class cmd_cat_revision(Command):
-    """Write out metadata for a revision.
+    __doc__ = """Write out metadata for a revision.
 
     The revision to print can either be specified by a specific
     revision identifier, or you can use --revision.
@@ -390,7 +390,7 @@
         
 
 class cmd_dump_btree(Command):
-    """Dump the contents of a btree index file to stdout.
+    __doc__ = """Dump the contents of a btree index file to stdout.
 
     PATH is a btree index file, it can be any URL. This includes things like
     .bzr/repository/pack-names, or .bzr/repository/indices/a34b3a...ca4a4.iix
@@ -471,7 +471,7 @@
 
 
 class cmd_remove_tree(Command):
-    """Remove the working tree from a given branch/checkout.
+    __doc__ = """Remove the working tree from a given branch/checkout.
 
     Since a lightweight checkout is little more than a working tree
     this will refuse to run against one.
@@ -514,7 +514,7 @@
 
 
 class cmd_revno(Command):
-    """Show current revision number.
+    __doc__ = """Show current revision number.
 
     This is equal to the number of revisions on this branch.
     """
@@ -550,7 +550,7 @@
 
 
 class cmd_revision_info(Command):
-    """Show revision number and revision id for a given revision identifier.
+    __doc__ = """Show revision number and revision id for a given revision identifier.
     """
     hidden = True
     takes_args = ['revision_info*']
@@ -612,7 +612,7 @@
 
 
 class cmd_add(Command):
-    """Add specified files or directories.
+    __doc__ = """Add specified files or directories.
 
     In non-recursive mode, all the named items are added, regardless
     of whether they were previously ignored.  A warning is given if
@@ -698,7 +698,7 @@
 
 
 class cmd_mkdir(Command):
-    """Create a new versioned directory.
+    __doc__ = """Create a new versioned directory.
 
     This is equivalent to creating the directory and then adding it.
     """
@@ -720,7 +720,7 @@
 
 
 class cmd_relpath(Command):
-    """Show path of a file relative to root"""
+    __doc__ = """Show path of a file relative to root"""
 
     takes_args = ['filename']
     hidden = True
@@ -735,7 +735,7 @@
 
 
 class cmd_inventory(Command):
-    """Show inventory of the current working copy or a revision.
+    __doc__ = """Show inventory of the current working copy or a revision.
 
     It is possible to limit the output to a particular entry
     type using the --kind option.  For example: --kind file.
@@ -796,7 +796,7 @@
 
 
 class cmd_mv(Command):
-    """Move or rename a file.
+    __doc__ = """Move or rename a file.
 
     :Usage:
         bzr mv OLDNAME NEWNAME
@@ -933,7 +933,7 @@
 
 
 class cmd_pull(Command):
-    """Turn this branch into a mirror of another branch.
+    __doc__ = """Turn this branch into a mirror of another branch.
 
     By default, this command only works on branches that have not diverged.
     Branches are considered diverged if the destination branch's most recent 
@@ -1060,7 +1060,7 @@
 
 
 class cmd_push(Command):
-    """Update a mirror of this branch.
+    __doc__ = """Update a mirror of this branch.
 
     The target branch will not have its working tree populated because this
     is both expensive, and is not supported on remote file systems.
@@ -1173,7 +1173,7 @@
 
 
 class cmd_branch(Command):
-    """Create a new branch that is a copy of an existing branch.
+    __doc__ = """Create a new branch that is a copy of an existing branch.
 
     If the TO_LOCATION is omitted, the last component of the FROM_LOCATION will
     be used.  In other words, "branch ../foo/bar" will attempt to create ./bar.
@@ -1286,7 +1286,7 @@
 
 
 class cmd_checkout(Command):
-    """Create a new checkout of an existing branch.
+    __doc__ = """Create a new checkout of an existing branch.
 
     If BRANCH_LOCATION is omitted, checkout will reconstitute a working tree for
     the branch found in '.'. This is useful if you have removed the working tree
@@ -1355,7 +1355,7 @@
 
 
 class cmd_renames(Command):
-    """Show list of renamed files.
+    __doc__ = """Show list of renamed files.
     """
     # TODO: Option to show renames between two historical versions.
 
@@ -1387,7 +1387,7 @@
 
 
 class cmd_update(Command):
-    """Update a tree to have the latest code committed to its branch.
+    __doc__ = """Update a tree to have the latest code committed to its branch.
 
     This will perform a merge into the working tree, and may generate
     conflicts. If you have any local changes, you will still
@@ -1473,7 +1473,7 @@
 
 
 class cmd_info(Command):
-    """Show information about a working tree, branch or repository.
+    __doc__ = """Show information about a working tree, branch or repository.
 
     This command will show all known locations and formats associated to the
     tree, branch or repository.
@@ -1517,7 +1517,7 @@
 
 
 class cmd_remove(Command):
-    """Remove files or directories.
+    __doc__ = """Remove files or directories.
 
     This makes bzr stop tracking changes to the specified files. bzr will delete
     them if they can easily be recovered using revert. If no options or
@@ -1571,7 +1571,7 @@
 
 
 class cmd_file_id(Command):
-    """Print file_id of a particular file or directory.
+    __doc__ = """Print file_id of a particular file or directory.
 
     The file_id is assigned when the file is first added and remains the
     same through all revisions where the file exists, even when it is
@@ -1593,7 +1593,7 @@
 
 
 class cmd_file_path(Command):
-    """Print path of file_ids to a file or directory.
+    __doc__ = """Print path of file_ids to a file or directory.
 
     This prints one line for each directory down to the target,
     starting at the branch root.
@@ -1615,7 +1615,7 @@
 
 
 class cmd_reconcile(Command):
-    """Reconcile bzr metadata in a branch.
+    __doc__ = """Reconcile bzr metadata in a branch.
 
     This can correct data mismatches that may have been caused by
     previous ghost operations or bzr upgrades. You should only
@@ -1643,7 +1643,7 @@
 
 
 class cmd_revision_history(Command):
-    """Display the list of revision ids on a branch."""
+    __doc__ = """Display the list of revision ids on a branch."""
 
     _see_also = ['log']
     takes_args = ['location?']
@@ -1659,7 +1659,7 @@
 
 
 class cmd_ancestry(Command):
-    """List all revisions merged into this branch."""
+    __doc__ = """List all revisions merged into this branch."""
 
     _see_also = ['log', 'revision-history']
     takes_args = ['location?']
@@ -1684,7 +1684,7 @@
 
 
 class cmd_init(Command):
-    """Make a directory into a versioned branch.
+    __doc__ = """Make a directory into a versioned branch.
 
     Use this to create an empty branch, or before importing an
     existing project.
@@ -1793,7 +1793,7 @@
 
 
 class cmd_init_repository(Command):
-    """Create a shared repository for branches to share storage space.
+    __doc__ = """Create a shared repository for branches to share storage space.
 
     New branches created under the repository directory will store their
     revisions in the repository, not in the branch directory.  For branches
@@ -1853,7 +1853,7 @@
 
 
 class cmd_diff(Command):
-    """Show differences in the working tree, between revisions or branches.
+    __doc__ = """Show differences in the working tree, between revisions or branches.
 
     If no arguments are given, all changes for the current tree are listed.
     If files are given, only the changes in those files are listed.
@@ -1994,7 +1994,7 @@
 
 
 class cmd_deleted(Command):
-    """List files deleted in the working tree.
+    __doc__ = """List files deleted in the working tree.
     """
     # TODO: Show files deleted since a previous revision, or
     # between two revisions.
@@ -2023,7 +2023,7 @@
 
 
 class cmd_modified(Command):
-    """List files modified in working tree.
+    __doc__ = """List files modified in working tree.
     """
 
     hidden = True
@@ -2046,7 +2046,7 @@
 
 
 class cmd_added(Command):
-    """List files added in working tree.
+    __doc__ = """List files added in working tree.
     """
 
     hidden = True
@@ -2082,7 +2082,7 @@
 
 
 class cmd_root(Command):
-    """Show the tree root directory.
+    __doc__ = """Show the tree root directory.
 
     The root is the nearest enclosing directory with a .bzr control
     directory."""
@@ -2112,7 +2112,7 @@
 
 
 class cmd_log(Command):
-    """Show historical log for a branch or subset of a branch.
+    __doc__ = """Show historical log for a branch or subset of a branch.
 
     log is bzr's default tool for exploring the history of a branch.
     The branch to use is taken from the first parameter. If no parameters
@@ -2483,7 +2483,7 @@
 
 
 class cmd_touching_revisions(Command):
-    """Return revision-ids which affected a particular file.
+    __doc__ = """Return revision-ids which affected a particular file.
 
     A more user-friendly interface is "bzr log FILE".
     """
@@ -2504,7 +2504,7 @@
 
 
 class cmd_ls(Command):
-    """List files in a tree.
+    __doc__ = """List files in a tree.
     """
 
     _see_also = ['status', 'cat']
@@ -2621,7 +2621,7 @@
 
 
 class cmd_unknowns(Command):
-    """List unknown files.
+    __doc__ = """List unknown files.
     """
 
     hidden = True
@@ -2634,7 +2634,7 @@
 
 
 class cmd_ignore(Command):
-    """Ignore specified files or patterns.
+    __doc__ = """Ignore specified files or patterns.
 
     See ``bzr help patterns`` for details on the syntax of patterns.
 
@@ -2736,7 +2736,7 @@
 
 
 class cmd_ignored(Command):
-    """List ignored files and the patterns that matched them.
+    __doc__ = """List ignored files and the patterns that matched them.
 
     List all the ignored files and the ignore pattern that caused the file to
     be ignored.
@@ -2763,7 +2763,7 @@
 
 
 class cmd_lookup_revision(Command):
-    """Lookup the revision-id from a revision-number
+    __doc__ = """Lookup the revision-id from a revision-number
 
     :Examples:
         bzr lookup-revision 33
@@ -2783,7 +2783,7 @@
 
 
 class cmd_export(Command):
-    """Export current or past revision to a destination directory or archive.
+    __doc__ = """Export current or past revision to a destination directory or archive.
 
     If no revision is specified this exports the last committed revision.
 
@@ -2846,7 +2846,7 @@
 
 
 class cmd_cat(Command):
-    """Write the contents of a file as of a given revision to standard output.
+    __doc__ = """Write the contents of a file as of a given revision to standard output.
 
     If no revision is nominated, the last revision is used.
 
@@ -2932,7 +2932,7 @@
 
 
 class cmd_local_time_offset(Command):
-    """Show the offset in seconds from GMT to local time."""
+    __doc__ = """Show the offset in seconds from GMT to local time."""
     hidden = True
     @display_command
     def run(self):
@@ -2941,7 +2941,7 @@
 
 
 class cmd_commit(Command):
-    """Commit changes into a new revision.
+    __doc__ = """Commit changes into a new revision.
 
     An explanatory message needs to be given for each commit. This is
     often done by using the --message option (getting the message from the
@@ -3207,7 +3207,7 @@
 
 
 class cmd_check(Command):
-    """Validate working tree structure, branch consistency and repository history.
+    __doc__ = """Validate working tree structure, branch consistency and repository history.
 
     This command checks various invariants about branch and repository storage
     to detect data corruption or bzr bugs.
@@ -3277,7 +3277,7 @@
 
 
 class cmd_upgrade(Command):
-    """Upgrade branch storage to current format.
+    __doc__ = """Upgrade branch storage to current format.
 
     The check command or bzr developers may sometimes advise you to run
     this command. When the default format has changed you may also be warned
@@ -3301,7 +3301,7 @@
 
 
 class cmd_whoami(Command):
-    """Show or set bzr user id.
+    __doc__ = """Show or set bzr user id.
 
     :Examples:
         Show the email of the current user::
@@ -3351,7 +3351,7 @@
 
 
 class cmd_nick(Command):
-    """Print or set the branch nickname.
+    __doc__ = """Print or set the branch nickname.
 
     If unset, the tree root directory name is used as the nickname.
     To print the current nickname, execute with no argument.
@@ -3375,7 +3375,7 @@
 
 
 class cmd_alias(Command):
-    """Set/unset and display aliases.
+    __doc__ = """Set/unset and display aliases.
 
     :Examples:
         Show the current aliases::
@@ -3445,7 +3445,7 @@
 
 
 class cmd_selftest(Command):
-    """Run internal test suite.
+    __doc__ = """Run internal test suite.
 
     If arguments are given, they are regular expressions that say which tests
     should run.  Tests matching any expression are run, and other tests are
@@ -3633,7 +3633,7 @@
 
 
 class cmd_version(Command):
-    """Show version of bzr."""
+    __doc__ = """Show version of bzr."""
 
     encoding_type = 'replace'
     takes_options = [
@@ -3650,7 +3650,7 @@
 
 
 class cmd_rocks(Command):
-    """Statement of optimism."""
+    __doc__ = """Statement of optimism."""
 
     hidden = True
 
@@ -3660,7 +3660,7 @@
 
 
 class cmd_find_merge_base(Command):
-    """Find and print a base revision for merging two branches."""
+    __doc__ = """Find and print a base revision for merging two branches."""
     # TODO: Options to specify revisions on either side, as if
     #       merging only part of the history.
     takes_args = ['branch', 'other']
@@ -3686,7 +3686,7 @@
 
 
 class cmd_merge(Command):
-    """Perform a three-way merge.
+    __doc__ = """Perform a three-way merge.
 
     The source of the merge can be specified either in the form of a branch,
     or in the form of a path to a file containing a merge directive generated
@@ -4047,7 +4047,7 @@
 
 
 class cmd_remerge(Command):
-    """Redo a merge.
+    __doc__ = """Redo a merge.
 
     Use this if you want to try a different merge technique while resolving
     conflicts.  Some merge techniques are better than others, and remerge
@@ -4142,7 +4142,7 @@
 
 
 class cmd_revert(Command):
-    """Revert files to a previous revision.
+    __doc__ = """Revert files to a previous revision.
 
     Giving a list of files will revert only those files.  Otherwise, all files
     will be reverted.  If the revision is not specified with '--revision', the
@@ -4214,7 +4214,7 @@
 
 
 class cmd_assert_fail(Command):
-    """Test reporting of assertion failures"""
+    __doc__ = """Test reporting of assertion failures"""
     # intended just for use in testing
 
     hidden = True
@@ -4224,7 +4224,7 @@
 
 
 class cmd_help(Command):
-    """Show help on a command or other topic.
+    __doc__ = """Show help on a command or other topic.
     """
 
     _see_also = ['topics']
@@ -4243,7 +4243,7 @@
 
 
 class cmd_shell_complete(Command):
-    """Show appropriate completions for context.
+    __doc__ = """Show appropriate completions for context.
 
     For a list of all available commands, say 'bzr shell-complete'.
     """
@@ -4258,7 +4258,7 @@
 
 
 class cmd_missing(Command):
-    """Show unmerged/unpulled revisions between two branches.
+    __doc__ = """Show unmerged/unpulled revisions between two branches.
 
     OTHER_BRANCH may be local or remote.
 
@@ -4431,7 +4431,7 @@
 
 
 class cmd_pack(Command):
-    """Compress the data within a repository.
+    __doc__ = """Compress the data within a repository.
 
     This operation compresses the data within a bazaar repository. As
     bazaar supports automatic packing of repository, this operation is
@@ -4466,7 +4466,7 @@
 
 
 class cmd_plugins(Command):
-    """List the installed plugins.
+    __doc__ = """List the installed plugins.
 
     This command displays the list of installed plugins including
     version of plugin and a short description of each.
@@ -4511,7 +4511,7 @@
 
 
 class cmd_testament(Command):
-    """Show testament (signing-form) of a revision."""
+    __doc__ = """Show testament (signing-form) of a revision."""
     takes_options = [
             'revision',
             Option('long', help='Produce long-format testament.'),
@@ -4543,7 +4543,7 @@
 
 
 class cmd_annotate(Command):
-    """Show the origin of each line in a file.
+    __doc__ = """Show the origin of each line in a file.
 
     This prints out the given file with an annotation on the left side
     indicating which revision, author and date introduced the change.
@@ -4596,7 +4596,7 @@
 
 
 class cmd_re_sign(Command):
-    """Create a digital signature for an existing revision."""
+    __doc__ = """Create a digital signature for an existing revision."""
     # TODO be able to replace existing ones.
 
     hidden = True # is this right ?
@@ -4662,7 +4662,7 @@
 
 
 class cmd_bind(Command):
-    """Convert the current branch into a checkout of the supplied branch.
+    __doc__ = """Convert the current branch into a checkout of the supplied branch.
 
     Once converted into a checkout, commits must succeed on the master branch
     before they will be applied to the local branch.
@@ -4702,7 +4702,7 @@
 
 
 class cmd_unbind(Command):
-    """Convert the current checkout into a regular branch.
+    __doc__ = """Convert the current checkout into a regular branch.
 
     After unbinding, the local branch is considered independent and subsequent
     commits will be local only.
@@ -4719,7 +4719,7 @@
 
 
 class cmd_uncommit(Command):
-    """Remove the last committed revision.
+    __doc__ = """Remove the last committed revision.
 
     --verbose will print out what is being removed.
     --dry-run will go through all the motions, but not actually
@@ -4827,7 +4827,7 @@
 
 
 class cmd_break_lock(Command):
-    """Break a dead lock on a repository, branch or working directory.
+    __doc__ = """Break a dead lock on a repository, branch or working directory.
 
     CAUTION: Locks should only be broken when you are sure that the process
     holding the lock has been stopped.
@@ -4852,7 +4852,7 @@
 
 
 class cmd_wait_until_signalled(Command):
-    """Test helper for test_start_and_stop_bzr_subprocess_send_signal.
+    __doc__ = """Test helper for test_start_and_stop_bzr_subprocess_send_signal.
 
     This just prints a line to signal when it is ready, then blocks on stdin.
     """
@@ -4866,7 +4866,7 @@
 
 
 class cmd_serve(Command):
-    """Run the bzr server."""
+    __doc__ = """Run the bzr server."""
 
     aliases = ['server']
 
@@ -4932,7 +4932,7 @@
 
 
 class cmd_join(Command):
-    """Combine a tree into its containing tree.
+    __doc__ = """Combine a tree into its containing tree.
 
     This command requires the target tree to be in a rich-root format.
 
@@ -4978,7 +4978,7 @@
 
 
 class cmd_split(Command):
-    """Split a subdirectory of a tree into a separate tree.
+    __doc__ = """Split a subdirectory of a tree into a separate tree.
 
     This command will produce a target tree in a format that supports
     rich roots, like 'rich-root' or 'rich-root-pack'.  These formats cannot be
@@ -5004,7 +5004,7 @@
 
 
 class cmd_merge_directive(Command):
-    """Generate a merge directive for auto-merge tools.
+    __doc__ = """Generate a merge directive for auto-merge tools.
 
     A directive requests a merge to be performed, and also provides all the
     information necessary to do so.  This means it must either include a
@@ -5103,7 +5103,7 @@
 
 
 class cmd_send(Command):
-    """Mail or create a merge-directive for submitting changes.
+    __doc__ = """Mail or create a merge-directive for submitting changes.
 
     A merge directive provides many things needed for requesting merges:
 
@@ -5220,7 +5220,7 @@
 
 
 class cmd_bundle_revisions(cmd_send):
-    """Create a merge-directive for submitting changes.
+    __doc__ = """Create a merge-directive for submitting changes.
 
     A merge directive provides many things needed for requesting merges:
 
@@ -5293,7 +5293,7 @@
 
 
 class cmd_tag(Command):
-    """Create, remove or modify a tag naming a revision.
+    __doc__ = """Create, remove or modify a tag naming a revision.
 
     Tags give human-meaningful names to revisions.  Commands that take a -r
     (--revision) option can be given -rtag:X, where X is any previously
@@ -5366,7 +5366,7 @@
 
 
 class cmd_tags(Command):
-    """List tags.
+    __doc__ = """List tags.
 
     This command shows a table of tag names and the revisions they reference.
     """
@@ -5440,7 +5440,7 @@
 
 
 class cmd_reconfigure(Command):
-    """Reconfigure the type of a bzr directory.
+    __doc__ = """Reconfigure the type of a bzr directory.
 
     A target configuration must be specified.
 
@@ -5531,7 +5531,7 @@
 
 
 class cmd_switch(Command):
-    """Set the branch of a checkout and update.
+    __doc__ = """Set the branch of a checkout and update.
 
     For lightweight checkouts, this changes the branch being referenced.
     For heavyweight checkouts, this checks that there are no local commits
@@ -5627,7 +5627,7 @@
 
 
 class cmd_view(Command):
-    """Manage filtered views.
+    __doc__ = """Manage filtered views.
 
     Views provide a mask over the tree so that users can focus on
     a subset of a tree when doing their work. After creating a view,
@@ -5781,7 +5781,7 @@
 
 
 class cmd_hooks(Command):
-    """Show hooks."""
+    __doc__ = """Show hooks."""
 
     hidden = True
 
@@ -5801,7 +5801,7 @@
 
 
 class cmd_remove_branch(Command):
-    """Remove a branch.
+    __doc__ = """Remove a branch.
 
     This will remove the branch from the specified location but 
     will keep any working tree or repository in place.
@@ -5826,7 +5826,7 @@
         
 
 class cmd_shelve(Command):
-    """Temporarily set aside some changes from the current tree.
+    __doc__ = """Temporarily set aside some changes from the current tree.
 
     Shelve allows you to temporarily put changes you've made "on the shelf",
     ie. out of the way, until a later time when you can bring them back from
@@ -5901,7 +5901,7 @@
 
 
 class cmd_unshelve(Command):
-    """Restore shelved changes.
+    __doc__ = """Restore shelved changes.
 
     By default, the most recently shelved changes are restored. However if you
     specify a shelf by id those changes will be restored instead.  This works
@@ -5933,7 +5933,7 @@
 
 
 class cmd_clean_tree(Command):
-    """Remove unwanted files from working tree.
+    __doc__ = """Remove unwanted files from working tree.
 
     By default, only unknown files, not ignored files, are deleted.  Versioned
     files are never deleted.
@@ -5967,7 +5967,7 @@
 
 
 class cmd_reference(Command):
-    """list, view and set branch locations for nested trees.
+    __doc__ = """list, view and set branch locations for nested trees.
 
     If no arguments are provided, lists the branch locations for nested trees.
     If one argument is provided, display the branch location for that tree.

=== modified file 'bzrlib/bundle/commands.py'
--- bzrlib/bundle/commands.py	2010-03-25 09:39:03 +0000
+++ bzrlib/bundle/commands.py	2010-04-22 18:59:24 +0000
@@ -41,7 +41,7 @@
 
 
 class cmd_bundle_info(Command):
-    """Output interesting stats about a bundle"""
+    __doc__ = """Output interesting stats about a bundle"""
 
     hidden = True
     takes_args = ['location']

=== modified file 'bzrlib/cmd_version_info.py'
--- bzrlib/cmd_version_info.py	2010-02-17 17:11:16 +0000
+++ bzrlib/cmd_version_info.py	2010-04-22 18:59:24 +0000
@@ -48,7 +48,7 @@
 
 
 class cmd_version_info(Command):
-    """Show version information about this tree.
+    __doc__ = """Show version information about this tree.
 
     You can use this command to add information about version into
     source code of an application. The output can be in one of the

=== modified file 'bzrlib/config.py'
--- bzrlib/config.py	2010-03-06 05:28:17 +0000
+++ bzrlib/config.py	2010-04-22 18:59:24 +0000
@@ -1407,7 +1407,7 @@
 
 
 class PlainTextCredentialStore(CredentialStore):
-    """Plain text credential store for the authentication.conf file."""
+    __doc__ = """Plain text credential store for the authentication.conf file"""
 
     def decode_password(self, credentials):
         """See CredentialStore.decode_password."""

=== modified file 'bzrlib/conflicts.py'
--- bzrlib/conflicts.py	2010-03-25 09:09:31 +0000
+++ bzrlib/conflicts.py	2010-04-22 18:59:24 +0000
@@ -46,7 +46,7 @@
 
 
 class cmd_conflicts(commands.Command):
-    """List files with conflicts.
+    __doc__ = """List files with conflicts.
 
     Merge will do its best to combine the changes in two branches, but there
     are some kinds of problems only a human can fix.  When it encounters those,
@@ -99,7 +99,7 @@
 
 
 class cmd_resolve(commands.Command):
-    """Mark a conflict as resolved.
+    __doc__ = """Mark a conflict as resolved.
 
     Merge will do its best to combine the changes in two branches, but there
     are some kinds of problems only a human can fix.  When it encounters those,

=== modified file 'bzrlib/foreign.py'
--- bzrlib/foreign.py	2010-04-12 16:54:35 +0000
+++ bzrlib/foreign.py	2010-04-22 18:59:24 +0000
@@ -259,7 +259,7 @@
 
 
 class cmd_dpush(Command):
-    """Push into a different VCS without any custom bzr metadata.
+    __doc__ = """Push into a different VCS without any custom bzr metadata.
 
     This will afterwards rebase the local branch on the remote
     branch unless the --no-rebase option is used, in which case 

=== modified file 'bzrlib/mail_client.py'
--- bzrlib/mail_client.py	2009-09-24 19:51:37 +0000
+++ bzrlib/mail_client.py	2010-04-22 18:59:24 +0000
@@ -89,7 +89,7 @@
 
 
 class Editor(MailClient):
-    """DIY mail client that uses commit message editor"""
+    __doc__ = """DIY mail client that uses commit message editor"""
 
     supports_body = True
 
@@ -230,13 +230,13 @@
 
 
 class ExternalMailClient(BodyExternalMailClient):
-    """An external mail client."""
+    __doc__ = """An external mail client."""
 
     supports_body = False
 
 
 class Evolution(BodyExternalMailClient):
-    """Evolution mail client."""
+    __doc__ = """Evolution mail client."""
 
     _client_commands = ['evolution']
 
@@ -258,7 +258,7 @@
 
 
 class Mutt(BodyExternalMailClient):
-    """Mutt mail client."""
+    __doc__ = """Mutt mail client."""
 
     _client_commands = ['mutt']
 
@@ -286,7 +286,7 @@
 
 
 class Thunderbird(BodyExternalMailClient):
-    """Mozilla Thunderbird (or Icedove)
+    __doc__ = """Mozilla Thunderbird (or Icedove)
 
     Note that Thunderbird 1.5 is buggy and does not support setting
     "to" simultaneously with including a attachment.
@@ -321,7 +321,7 @@
 
 
 class KMail(ExternalMailClient):
-    """KDE mail client."""
+    __doc__ = """KDE mail client."""
 
     _client_commands = ['kmail']
 
@@ -341,7 +341,7 @@
 
 
 class Claws(ExternalMailClient):
-    """Claws mail client."""
+    __doc__ = """Claws mail client."""
 
     supports_body = True
 
@@ -387,7 +387,7 @@
 
 
 class XDGEmail(BodyExternalMailClient):
-    """xdg-email attempts to invoke the user's preferred mail client"""
+    __doc__ = """xdg-email attempts to invoke the user's preferred mail client"""
 
     _client_commands = ['xdg-email']
 
@@ -409,7 +409,7 @@
 
 
 class EmacsMail(ExternalMailClient):
-    """Call emacsclient to have a mail buffer.
+    __doc__ = """Call emacsclient to have a mail buffer.
 
     This only work for emacs >= 22.1 due to recent -e/--eval support.
 
@@ -519,7 +519,7 @@
 
 
 class MAPIClient(BodyExternalMailClient):
-    """Default Windows mail client launched using MAPI."""
+    __doc__ = """Default Windows mail client launched using MAPI."""
 
     def _compose(self, prompt, to, subject, attach_path, mime_subtype,
                  extension, body=None):
@@ -540,7 +540,7 @@
 
 
 class MailApp(BodyExternalMailClient):
-    """Use MacOS X's Mail.app for sending email messages.
+    __doc__ = """Use MacOS X's Mail.app for sending email messages.
 
     Although it would be nice to use appscript, it's not installed
     with the shipped Python installations.  We instead build an
@@ -599,7 +599,7 @@
 
 
 class DefaultMail(MailClient):
-    """Default mail handling.  Tries XDGEmail (or MAPIClient on Windows),
+    __doc__ = """Default mail handling.  Tries XDGEmail (or MAPIClient on Windows),
     falls back to Editor"""
 
     supports_body = True

=== modified file 'bzrlib/plugins/launchpad/__init__.py'
--- bzrlib/plugins/launchpad/__init__.py	2010-02-23 07:43:11 +0000
+++ bzrlib/plugins/launchpad/__init__.py	2010-04-22 18:59:24 +0000
@@ -53,7 +53,7 @@
 
 
 class cmd_register_branch(Command):
-    """Register a branch with launchpad.net.
+    __doc__ = """Register a branch with launchpad.net.
 
     This command lists a bzr branch in the directory of branches on
     launchpad.net.  Registration allows the branch to be associated with
@@ -161,7 +161,7 @@
 
 
 class cmd_launchpad_open(Command):
-    """Open a Launchpad branch page in your web browser."""
+    __doc__ = """Open a Launchpad branch page in your web browser."""
 
     aliases = ['lp-open']
     takes_options = [
@@ -211,7 +211,7 @@
 
 
 class cmd_launchpad_login(Command):
-    """Show or set the Launchpad user ID.
+    __doc__ = """Show or set the Launchpad user ID.
 
     When communicating with Launchpad, some commands need to know your
     Launchpad user ID.  This command can be used to set or show the
@@ -267,7 +267,7 @@
 
 # XXX: cmd_launchpad_mirror is untested
 class cmd_launchpad_mirror(Command):
-    """Ask Launchpad to mirror a branch now."""
+    __doc__ = """Ask Launchpad to mirror a branch now."""
 
     aliases = ['lp-mirror']
     takes_args = ['location?']
@@ -286,7 +286,7 @@
 
 
 class cmd_lp_propose_merge(Command):
-    """Propose merging a branch on Launchpad.
+    __doc__ = """Propose merging a branch on Launchpad.
 
     This will open your usual editor to provide the initial comment.  When it
     has created the proposal, it will open it in your default web browser.

=== modified file 'bzrlib/plugins/netrc_credential_store/__init__.py'
--- bzrlib/plugins/netrc_credential_store/__init__.py	2009-04-10 18:56:00 +0000
+++ bzrlib/plugins/netrc_credential_store/__init__.py	2010-04-22 18:59:24 +0000
@@ -14,7 +14,7 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
-"""Use ~/.netrc as a credential store for authentication.conf."""
+__doc__ = """Use ~/.netrc as a credential store for authentication.conf."""
 
 # Since we are a built-in plugin we share the bzrlib version
 from bzrlib import version_info

=== modified file 'bzrlib/plugins/news_merge/__init__.py'
--- bzrlib/plugins/news_merge/__init__.py	2010-01-28 17:27:16 +0000
+++ bzrlib/plugins/news_merge/__init__.py	2010-04-22 18:59:24 +0000
@@ -14,7 +14,7 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
-"""Merge hook for bzr's NEWS file.
+__doc__ = """Merge hook for bzr's NEWS file.
 
 To enable this plugin, add a section to your branch.conf or location.conf
 like::

=== modified file 'bzrlib/sign_my_commits.py'
--- bzrlib/sign_my_commits.py	2009-03-23 14:59:43 +0000
+++ bzrlib/sign_my_commits.py	2010-04-22 18:59:24 +0000
@@ -30,7 +30,7 @@
 
 
 class cmd_sign_my_commits(Command):
-    """Sign all commits by a given committer.
+    __doc__ = """Sign all commits by a given committer.
 
     If location is not specified the local tree is used.
     If committer is not specified the default committer is used.

=== modified file 'bzrlib/tests/__init__.py'
--- bzrlib/tests/__init__.py	2010-04-22 15:44:21 +0000
+++ bzrlib/tests/__init__.py	2010-04-22 18:59:24 +0000
@@ -14,6 +14,7 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
+"""Testing framework extensions"""
 
 # TODO: Perhaps there should be an API to find out if bzr running under the
 # test suite -- some plugins might want to avoid making intrusive changes if
@@ -1312,6 +1313,14 @@
             f.close()
         self.assertEqualDiff(content, s)
 
+    def assertDocstring(self, expected_docstring, obj):
+        """Fail if obj does not have expected_docstring"""
+        if __doc__ is None:
+            # With -OO the docstring should be None instead
+            self.assertIs(obj.__doc__, None)
+        else:
+            self.assertEqual(expected_docstring, obj.__doc__)
+
     def failUnlessExists(self, path):
         """Fail unless path or paths, which may be abs or relative, exist."""
         if not isinstance(path, basestring):
@@ -3796,7 +3805,10 @@
 
 
 def _test_suite_modules_to_doctest():
-    """Return the list of modules to doctest."""   
+    """Return the list of modules to doctest."""
+    if __doc__ is None:
+        # GZ 2009-03-31: No docstrings with -OO so there's nothing to doctest
+        return []
     return [
         'bzrlib',
         'bzrlib.branchbuilder',

=== modified file 'bzrlib/tests/test_commands.py'
--- bzrlib/tests/test_commands.py	2010-03-25 09:39:03 +0000
+++ bzrlib/tests/test_commands.py	2010-04-22 18:59:24 +0000
@@ -65,7 +65,7 @@
     @staticmethod
     def get_command(options):
         class cmd_foo(commands.Command):
-            'Bar'
+            __doc__ = 'Bar'
 
             takes_options = options
 
@@ -120,38 +120,35 @@
 class TestSeeAlso(tests.TestCase):
     """Tests for the see also functional of Command."""
 
+    @staticmethod
+    def _get_command_with_see_also(see_also):
+        class ACommand(commands.Command):
+            __doc__ = """A sample command."""
+            _see_also = see_also
+        return ACommand()
+
     def test_default_subclass_no_see_also(self):
-        class ACommand(commands.Command):
-            """A sample command."""
-        command = ACommand()
+        command = self._get_command_with_see_also([])
         self.assertEqual([], command.get_see_also())
 
     def test__see_also(self):
         """When _see_also is defined, it sets the result of get_see_also()."""
-        class ACommand(commands.Command):
-            _see_also = ['bar', 'foo']
-        command = ACommand()
+        command = self._get_command_with_see_also(['bar', 'foo'])
         self.assertEqual(['bar', 'foo'], command.get_see_also())
 
     def test_deduplication(self):
         """Duplicates in _see_also are stripped out."""
-        class ACommand(commands.Command):
-            _see_also = ['foo', 'foo']
-        command = ACommand()
+        command = self._get_command_with_see_also(['foo', 'foo'])
         self.assertEqual(['foo'], command.get_see_also())
 
     def test_sorted(self):
         """_see_also is sorted by get_see_also."""
-        class ACommand(commands.Command):
-            _see_also = ['foo', 'bar']
-        command = ACommand()
+        command = self._get_command_with_see_also(['foo', 'bar'])
         self.assertEqual(['bar', 'foo'], command.get_see_also())
 
     def test_additional_terms(self):
         """Additional terms can be supplied and are deduped and sorted."""
-        class ACommand(commands.Command):
-            _see_also = ['foo', 'bar']
-        command = ACommand()
+        command = self._get_command_with_see_also(['foo', 'bar'])
         self.assertEqual(['bar', 'foo', 'gam'],
             command.get_see_also(['gam', 'bar', 'gam']))
 
@@ -212,7 +209,7 @@
             "extend_command", hook_calls.append, None)
         # create a command, should not fire
         class cmd_test_extend_command_hook(commands.Command):
-            """A sample command."""
+            __doc__ = """A sample command."""
         self.assertEqual([], hook_calls)
         # -- as a builtin
         # register the command class, should not fire
@@ -249,7 +246,7 @@
         commands.install_bzr_command_hooks()
         hook_calls = []
         class ACommand(commands.Command):
-            """A sample command."""
+            __doc__ = """A sample command."""
         def get_cmd(cmd_or_None, cmd_name):
             hook_calls.append(('called', cmd_or_None, cmd_name))
             if cmd_name in ('foo', 'info'):
@@ -280,7 +277,7 @@
         """Hook get_missing_command for testing."""
         self.hook_calls = []
         class ACommand(commands.Command):
-            """A sample command."""
+            __doc__ = """A sample command."""
         def get_missing_cmd(cmd_name):
             self.hook_calls.append(('called', cmd_name))
             if cmd_name in ('foo', 'info'):

=== modified file 'bzrlib/tests/test_decorators.py'
--- bzrlib/tests/test_decorators.py	2009-10-02 06:12:20 +0000
+++ bzrlib/tests/test_decorators.py	2010-04-22 18:59:24 +0000
@@ -167,14 +167,14 @@
         """@needs_read_lock exposes underlying name and doc."""
         sam = create_decorator_sample(None)
         self.assertEqual('frob', sam.frob.__name__)
-        self.assertEqual('Frob the sample object', sam.frob.__doc__)
+        self.assertDocstring('Frob the sample object', sam.frob)
 
     def test_write_lock_passthrough(self):
         """@needs_write_lock exposes underlying name and doc."""
         sam = create_decorator_sample(None)
         self.assertEqual('bank', sam.bank.__name__)
-        self.assertEqual('Bank the sample, but using bar and biz.',
-                         sam.bank.__doc__)
+        self.assertDocstring('Bank the sample, but using bar and biz.',
+                             sam.bank)
 
     def test_argument_passthrough(self):
         """Test that arguments get passed around properly."""
@@ -208,8 +208,8 @@
                          my_function.func_code.co_name)
         self.assertEqual('(foo, bar, baz=None, biz=1)',
                          self.get_formatted_args(my_function))
-        self.assertEqual('Just a function that supplies several arguments.',
-                         inspect.getdoc(my_function))
+        self.assertDocstring(
+            'Just a function that supplies several arguments.', my_function)
 
     def test__fast_needs_read_lock(self):
         """Test the output of _fast_needs_read_lock."""
@@ -222,8 +222,8 @@
         self.assertEqual('read_locked', my_function.func_code.co_name)
         self.assertEqual('(self, *args, **kwargs)',
                          self.get_formatted_args(my_function))
-        self.assertEqual('Just a function that supplies several arguments.',
-                         inspect.getdoc(my_function))
+        self.assertDocstring(
+            'Just a function that supplies several arguments.', my_function)
 
     def test__pretty_needs_write_lock(self):
         """Test that _pretty_needs_write_lock generates a nice wrapper."""
@@ -237,8 +237,8 @@
                          my_function.func_code.co_name)
         self.assertEqual('(foo, bar, baz=None, biz=1)',
                          self.get_formatted_args(my_function))
-        self.assertEqual('Just a function that supplies several arguments.',
-                         inspect.getdoc(my_function))
+        self.assertDocstring(
+            'Just a function that supplies several arguments.', my_function)
 
     def test__fast_needs_write_lock(self):
         """Test the output of _fast_needs_write_lock."""
@@ -251,8 +251,8 @@
         self.assertEqual('write_locked', my_function.func_code.co_name)
         self.assertEqual('(self, *args, **kwargs)',
                          self.get_formatted_args(my_function))
-        self.assertEqual('Just a function that supplies several arguments.',
-                         inspect.getdoc(my_function))
+        self.assertDocstring(
+            'Just a function that supplies several arguments.', my_function)
 
     def test_use_decorators(self):
         """Test that you can switch the type of the decorators."""

=== modified file 'bzrlib/tests/test_errors.py'
--- bzrlib/tests/test_errors.py	2010-02-17 17:11:16 +0000
+++ bzrlib/tests/test_errors.py	2010-04-22 18:59:24 +0000
@@ -670,7 +670,7 @@
 
 
 class ErrorWithNoFormat(errors.BzrError):
-    """This class has a docstring but no format string."""
+    __doc__ = """This class has a docstring but no format string."""
 
 
 class TestErrorFormatting(TestCase):

=== modified file 'bzrlib/tests/test_help.py'
--- bzrlib/tests/test_help.py	2009-06-15 10:22:08 +0000
+++ bzrlib/tests/test_help.py	2010-04-22 18:59:24 +0000
@@ -41,7 +41,7 @@
 
     def test_command_help_includes_see_also(self):
         class cmd_WithSeeAlso(commands.Command):
-            """A sample command."""
+            __doc__ = """A sample command."""
             _see_also = ['foo', 'bar']
         cmd = cmd_WithSeeAlso()
         helptext = cmd.get_help_text()
@@ -56,7 +56,7 @@
     def test_get_help_text(self):
         """Commands have a get_help_text method which returns their help."""
         class cmd_Demo(commands.Command):
-            """A sample command."""
+            __doc__ = """A sample command."""
         cmd = cmd_Demo()
         helptext = cmd.get_help_text()
         self.assertStartsWith(helptext,
@@ -67,7 +67,7 @@
 
     def test_command_with_additional_see_also(self):
         class cmd_WithSeeAlso(commands.Command):
-            """A sample command."""
+            __doc__ = """A sample command."""
             _see_also = ['foo', 'bar']
         cmd = cmd_WithSeeAlso()
         helptext = cmd.get_help_text(['gam'])
@@ -81,7 +81,7 @@
 
     def test_command_only_additional_see_also(self):
         class cmd_WithSeeAlso(commands.Command):
-            """A sample command."""
+            __doc__ = """A sample command."""
         cmd = cmd_WithSeeAlso()
         helptext = cmd.get_help_text(['gam'])
         self.assertEndsWith(
@@ -95,14 +95,14 @@
     def test_get_help_topic(self):
         """The help topic for a Command is its name()."""
         class cmd_foo_bar(commands.Command):
-            """A sample command."""
+            __doc__ = """A sample command."""
         cmd = cmd_foo_bar()
         self.assertEqual(cmd.name(), cmd.get_help_topic())
 
     def test_formatted_help_text(self):
         """Help text should be plain text by default."""
         class cmd_Demo(commands.Command):
-            """A sample command.
+            __doc__ = """A sample command.
 
             :Examples:
                 Example 1::
@@ -159,7 +159,7 @@
     def test_concise_help_text(self):
         """Concise help text excludes the descriptive sections."""
         class cmd_Demo(commands.Command):
-            """A sample command.
+            __doc__ = """A sample command.
  
             Blah blah blah.
 
@@ -206,7 +206,7 @@
     def test_help_custom_section_ordering(self):
         """Custom descriptive sections should remain in the order given."""
         class cmd_Demo(commands.Command):
-            """A sample command.
+            __doc__ = """A sample command.
  
             Blah blah blah.
 
@@ -252,7 +252,7 @@
     def test_help_text_custom_usage(self):
         """Help text may contain a custom usage section."""
         class cmd_Demo(commands.Command):
-            """A sample command.
+            __doc__ = """A sample command.
 
             :Usage:
                 cmd Demo [opts] args

=== modified file 'bzrlib/tests/test_plugins.py'
--- bzrlib/tests/test_plugins.py	2010-04-06 07:22:31 +0000
+++ bzrlib/tests/test_plugins.py	2010-04-22 18:59:24 +0000
@@ -473,7 +473,7 @@
         f.write("""\
 from bzrlib import commands
 class cmd_myplug(commands.Command):
-    '''Just a simple test plugin.'''
+    __doc__ = '''Just a simple test plugin.'''
     aliases = ['mplg']
     def run(self):
         print 'Hello from my plugin'
@@ -780,8 +780,8 @@
         self.overrideAttr(plugin, '_loaded', False)
         plugin.load_plugins(['.'])
         self.assertPluginKnown('test_foo')
-        self.assertEqual("This is the doc for test_foo",
-                         bzrlib.plugins.test_foo.__doc__)
+        self.assertDocstring("This is the doc for test_foo",
+                             bzrlib.plugins.test_foo)
 
     def test_not_loaded(self):
         self.warnings = []
@@ -816,8 +816,8 @@
 
     def assertTestFooLoadedFrom(self, path):
         self.assertPluginKnown('test_foo')
-        self.assertEqual('This is the doc for test_foo',
-                         bzrlib.plugins.test_foo.__doc__)
+        self.assertDocstring('This is the doc for test_foo',
+                             bzrlib.plugins.test_foo)
         self.assertEqual(path, bzrlib.plugins.test_foo.dir_source)
 
     def test_regular_load(self):

=== modified file 'bzrlib/tests/test_selftest.py'
--- bzrlib/tests/test_selftest.py	2010-04-18 08:51:37 +0000
+++ bzrlib/tests/test_selftest.py	2010-04-22 18:59:24 +0000
@@ -2773,6 +2773,10 @@
         # Test that a plausible list of modules to doctest is returned
         # by _test_suite_modules_to_doctest.
         test_list = tests._test_suite_modules_to_doctest()
+        if __doc__ is None:
+            # When docstrings are stripped, there are no modules to doctest
+            self.assertEqual([], test_list)
+            return
         self.assertSubset([
             'bzrlib.timestamp',
             ],
@@ -2795,6 +2799,8 @@
         self.overrideAttr(tests, '_test_suite_testmod_names', testmod_names)
         def doctests():
             calls.append("modules_to_doctest")
+            if __doc__ is None:
+                return []
             return ['bzrlib.timestamp']
         self.overrideAttr(tests, '_test_suite_modules_to_doctest', doctests)
         expected_test_list = [
@@ -2803,11 +2809,14 @@
             ('bzrlib.tests.per_transport.TransportTests'
              '.test_abspath(LocalTransport,LocalURLServer)'),
             'bzrlib.tests.test_selftest.TestTestSuite.test_test_suite',
-            # modules_to_doctest
-            'bzrlib.timestamp.format_highres_date',
             # plugins can't be tested that way since selftest may be run with
             # --no-plugins
             ]
+        if __doc__ is not None:
+            expected_test_list.extend([
+                # modules_to_doctest
+                'bzrlib.timestamp.format_highres_date',
+                ])
         suite = tests.test_suite()
         self.assertEqual(set(["testmod_names", "modules_to_doctest"]),
             set(calls))

=== modified file 'bzrlib/tests/test_symbol_versioning.py'
--- bzrlib/tests/test_symbol_versioning.py	2010-01-25 17:48:22 +0000
+++ bzrlib/tests/test_symbol_versioning.py	2010-04-22 18:59:24 +0000
@@ -179,6 +179,9 @@
     def check_deprecated_callable(self, expected_warning, expected_docstring,
                                   expected_name, expected_module,
                                   deprecated_callable):
+        if __doc__ is None:
+            # With -OO the docstring should just be the deprecated version
+            expected_docstring = expected_docstring.split('\n')[-2].lstrip()
         old_warning_method = symbol_versioning.warn
         try:
             symbol_versioning.set_warning_method(self.capture_warning)

=== modified file 'bzrlib/tests/test_workingtree.py'
--- bzrlib/tests/test_workingtree.py	2009-03-23 14:59:43 +0000
+++ bzrlib/tests/test_workingtree.py	2010-04-22 18:59:24 +0000
@@ -303,9 +303,9 @@
         self.assertEqual(
             'method_with_tree_write_lock',
             tree.method_with_tree_write_lock.__name__)
-        self.assertEqual(
+        self.assertDocstring(
             "A lock_tree_write decorated method that returns its arguments.",
-            tree.method_with_tree_write_lock.__doc__)
+            tree.method_with_tree_write_lock)
         args = (1, 2, 3)
         kwargs = {'a':'b'}
         result = tree.method_with_tree_write_lock(1,2,3, a='b')

=== modified file 'doc/developers/HACKING.txt'
--- doc/developers/HACKING.txt	2010-03-30 07:29:56 +0000
+++ doc/developers/HACKING.txt	2010-04-22 18:59:24 +0000
@@ -1053,7 +1053,8 @@
 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.
+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).

=== modified file 'doc/developers/plugin-api.txt'
--- doc/developers/plugin-api.txt	2010-02-23 03:18:56 +0000
+++ doc/developers/plugin-api.txt	2010-04-22 18:59:24 +0000
@@ -186,9 +186,8 @@
 short complete sentence summarizing the plugin.  The full docstring is
 shown by ``bzr help PLUGIN_NAME``.
 
-Remember that to be effective, the module docstring must be the first
-statement in the file.  It may come after comments but it must be before
-any import statements.
+This is a user-visible docstring so should be prefixed with ``__doc__ =``
+to ensure help works under ``python -OO`` with docstrings stripped.
 
 API version
 -----------