Rev 5231: Write up some doc about bzrlib.initialize. in http://bazaar.launchpad.net/~lifeless/bzr/fix-terminal-spew
Robert Collins
robertc at robertcollins.net
Mon Jun 21 04:55:10 BST 2010
At http://bazaar.launchpad.net/~lifeless/bzr/fix-terminal-spew
------------------------------------------------------------
revno: 5231
revision-id: robertc at robertcollins.net-20100621035508-wrcgnqv227ftxhs8
parent: robertc at robertcollins.net-20100621032345-7gnasqnirc299s4k
committer: Robert Collins <robertc at robertcollins.net>
branch nick: fix-terminal-spew
timestamp: Mon 2010-06-21 15:55:08 +1200
message:
Write up some doc about bzrlib.initialize.
=== modified file 'bzr'
--- a/bzr 2010-06-21 01:30:45 +0000
+++ b/bzr 2010-06-21 03:55:08 +0000
@@ -136,6 +136,7 @@
if __name__ == '__main__':
library_state = bzrlib.initialize()
+ library_state.__enter__()
try:
exit_val = bzrlib.commands.main()
if profiling:
=== modified file 'bzrlib/__init__.py'
--- a/bzrlib/__init__.py 2010-06-21 03:23:45 +0000
+++ b/bzrlib/__init__.py 2010-06-21 03:55:08 +0000
@@ -14,7 +14,22 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
-"""bzr library"""
+"""All of bzr.
+
+Developer documentation is available at
+http://doc.bazaar.canonical.com/bzr.dev/developers/
+
+The project website is at http://bazaar.canonical.com/
+
+Some particularly interesting things in bzrlib are:
+
+ * bzrlib.initialize -- setup the library for use
+ * bzrlib.plugin.load_plugins -- load all installed plugins
+ * bzrlib.branch.Branch.open -- open a branch
+ * bzrlib.workingtree.WorkingTree.open -- open a working tree
+
+We hope you enjoy this library.
+"""
import time
@@ -134,6 +149,9 @@
:ivar saved_state: The bzrlib.global_state at the time __enter__ was
called.
+ :ivar cleanups: An ObjectWithCleanups which can be used for cleanups that
+ should occur when the use of bzrlib is completed. This is initialised
+ in __enter__ and executed in __exit__.
"""
def __init__(self, setup_ui=True, stdin=None, stdout=None, stderr=None):
@@ -147,7 +165,7 @@
arguments.
BzrLibraryState implements the Python 2.5 Context Manager protocol, and
- can be used with the with statement. Upon __entry__ the global
+ can be used with the with statement. Upon __enter__ 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
@@ -170,7 +188,9 @@
from bzrlib.symbol_versioning import suppress_deprecation_warnings
suppress_deprecation_warnings(override=True)
+ import bzrlib.cleanup
import bzrlib.trace
+ self.cleanups = bzrlib.cleanup.ObjectWithCleanups()
bzrlib.trace.enable_default_logging()
if self.setup_ui:
@@ -185,6 +205,7 @@
global_state = self
def __exit__(self, exc_type, exc_val, exc_tb):
+ self.cleanups.cleanup_now()
import bzrlib.ui
bzrlib.trace._flush_stdout_stderr()
bzrlib.trace._flush_trace()
@@ -211,16 +232,13 @@
: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.
+ this context needs to be alled before it takes effect, and the __exit__
+ should be called by the caller before exiting their process or
+ otherwise stopping use of bzrlib. Advanced callers can use
+ BzrLibraryState directly.
"""
- # TODO: mention this in a guide to embedding bzrlib
- library_state = BzrLibraryState(setup_ui=setup_ui, stdin=stdin,
+ return BzrLibraryState(setup_ui=setup_ui, stdin=stdin,
stdout=stdout, stderr=stderr)
- library_state.__enter__()
- return library_state
def test_suite():
=== modified file 'bzrlib/smart/medium.py'
--- a/bzrlib/smart/medium.py 2010-06-16 07:45:53 +0000
+++ b/bzrlib/smart/medium.py 2010-06-21 03:55:08 +0000
@@ -28,9 +28,9 @@
import sys
import urllib
+import bzrlib
from bzrlib.lazy_import import lazy_import
lazy_import(globals(), """
-import atexit
import socket
import thread
import weakref
@@ -494,16 +494,16 @@
class _DebugCounter(object):
"""An object that counts the HPSS calls made to each client medium.
- When a medium is garbage-collected, or failing that when atexit functions
- are run, the total number of calls made on that medium are reported via
- trace.note.
+ When a medium is garbage-collected, or failing that when
+ bzrlib.global_state exits, the total number of calls made on that medium
+ are reported via trace.note.
"""
def __init__(self):
self.counts = weakref.WeakKeyDictionary()
client._SmartClient.hooks.install_named_hook(
'call', self.increment_call_count, 'hpss call counter')
- atexit.register(self.flush_all)
+ bzrlib.global_state.cleanups.addCleanup(self.flush_all)
def track(self, medium):
"""Start tracking calls made to a medium.
=== modified file 'doc/developers/overview.txt'
--- a/doc/developers/overview.txt 2010-05-23 20:44:49 +0000
+++ b/doc/developers/overview.txt 2010-06-21 03:55:08 +0000
@@ -13,6 +13,38 @@
to the Bazaar mailing list.
+Using bzrlib
+############
+
+Within bzr
+==========
+
+When using bzrlib within the ``bzr`` program (for instance as a bzr
+plugin), bzrlib's global state is already available for use.
+
+From outside bzr
+================
+
+To use bzrlib outside of ``bzr`` some global state needs to be setup.
+bzrlib needs ways to handle user input, passwords, a place to emit
+progress bars, logging setup appropriately for your program. The easiest
+way to set all this up in the same fashion ``bzr`` does is to call
+``bzrlib.initialize``. This returns a context manager within which bzrlib
+functions will work correctly. See the pydoc for ``bzrlib.initialize`` for
+more information. In Python 2.4 the ``with`` keyword is not supported and
+so you need to use the context manager manually::
+
+ # This sets up your ~/.bzr.log, ui factory and so on and so forth. It is
+ # not safe to use as a doctest.
+ library_state = bzrlib.initialize()
+ library_state.__enter__()
+ try:
+ pass
+ # do stuff here
+ finally:
+ library_state.__exit__(None, None, None)
+
+
Core classes
############
More information about the bazaar-commits
mailing list