Rev 5229: Document bzrlib.initialize a little better, and explicitly propogate exceptions in the new __exit__ methods. in http://bazaar.launchpad.net/~lifeless/bzr/fix-terminal-spew

[Robert Collins]

At http://bazaar.launchpad.net/~lifeless/bzr/fix-terminal-spew

------------------------------------------------------------
revno: 5229
revision-id: robertc at robertcollins.net-20100621031555-y1oi1twlxt2qqjue
parent: robertc at robertcollins.net-20100621013045-s59nfjps3rkcn53j
committer: Robert Collins <robertc at robertcollins.net>
branch nick: fix-terminal-spew
timestamp: Mon 2010-06-21 15:15:55 +1200
message:
  Document bzrlib.initialize a little better, and explicitly propogate exceptions in the new __exit__ methods.
=== modified file 'bzrlib/__init__.py'
--- a/bzrlib/__init__.py	2010-06-21 01:30:45 +0000
+++ b/bzrlib/__init__.py	2010-06-21 03:15:55 +0000
@@ -126,10 +126,16 @@
     def __init__(self, setup_ui=True, stdin=None, stdout=None, stderr=None):
         """Create library start for normal use of bzrlib.
 
-        Most applications that embed bzrlib, including bzr itself, should just call
-        bzrlib.initialize(), but it is possible to use the state class directly.
-
-        More options may be added in future so callers should use named arguments.
+        Most applications that embed bzrlib, including bzr itself, should just
+        call bzrlib.initialize(), but it is possible to use the state class
+        directly.
+
+        More options may be added in future so callers should use named
+        arguments.
+
+        BzrLibraryState implements the Python 2.5 Context Manager protocol, and
+        can be used with the with statement. Upon __entry__ the global
+        variables in use by bzr are set, and they are cleared on __exit__.
 
         :param setup_ui: If true (default) use a terminal UI; otherwise 
             some other ui_factory must be assigned to `bzrlib.ui.ui_factory` by
@@ -170,6 +176,7 @@
         bzrlib.osutils.report_extension_load_failures()
         bzrlib.ui.ui_factory.__exit__(None, None, None)
         bzrlib.ui.ui_factory = None
+        return False # propogate exceptions.
 
 
 def initialize(setup_ui=True, stdin=None, stdout=None, stderr=None):
@@ -185,6 +192,11 @@
         the caller.
     :param stdin, stdout, stderr: If provided, use these for terminal IO;
         otherwise use the files in `sys`.
+    :return: A context manager for the use of bzrlib. The __enter__ method of
+        this context has already been called, the __exit__ should be called
+        by the caller before exiting their process or otherwise stopping use
+        of bzrlib. Advanced callers, or callers wanting to use the 'with'
+        statement in Python 2.5 and above, should use BzrLibraryState directly.
     """
     # TODO: mention this in a guide to embedding bzrlib
     library_state = BzrLibraryState(setup_ui=setup_ui, stdin=stdin,

=== modified file 'bzrlib/trace.py'
--- a/bzrlib/trace.py	2010-06-21 01:30:45 +0000
+++ b/bzrlib/trace.py	2010-06-21 03:15:55 +0000
@@ -374,7 +374,7 @@
     _trace_file = old_trace_file
     bzr_logger = logging.getLogger('bzr')
     bzr_logger.removeHandler(new_handler)
-    # must be closed, otherwise logging will try to close it atexit, and the
+    # must be closed, otherwise logging will try to close it at exit, and the
     # file will likely already be closed underneath.
     new_handler.close()
     bzr_logger.handlers = old_handlers

=== modified file 'bzrlib/ui/__init__.py'
--- a/bzrlib/ui/__init__.py	2010-06-21 00:58:22 +0000
+++ b/bzrlib/ui/__init__.py	2010-06-21 03:15:55 +0000
@@ -140,6 +140,7 @@
         self.clear_term() is needed when the UIFactory is finished with.
         """
         self.clear_term()
+        return False # propogate exceptions.
 
     def be_quiet(self, state):
         """Tell the UI to be more quiet, or not.