/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to bzrlib/__init__.py

  • Committer: Robert Collins
  • Date: 2010-06-21 03:55:08 UTC
  • mto: This revision was merged to the branch mainline in revision 5310.
  • Revision ID: robertc@robertcollins.net-20100621035508-wrcgnqv227ftxhs8
Write up some doc about bzrlib.initialize.

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/__init__.py
 
1
# Copyright (C) 2005-2010 Canonical Ltd
 
2
#
 
3
# This program is free software; you can redistribute it and/or modify
 
4
# it under the terms of the GNU General Public License as published by
 
5
# the Free Software Foundation; either version 2 of the License, or
 
6
# (at your option) any later version.
 
7
#
 
8
# This program is distributed in the hope that it will be useful,
 
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
 
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
11
# GNU General Public License for more details.
 
12
#
 
13
# You should have received a copy of the GNU General Public License
 
14
# along with this program; if not, write to the Free Software
 
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
16
 
 
17
"""All of bzr.
 
18
 
 
19
Developer documentation is available at
 
20
http://doc.bazaar.canonical.com/bzr.dev/developers/
 
21
 
 
22
The project website is at http://bazaar.canonical.com/
 
23
 
 
24
Some particularly interesting things in bzrlib are:
 
25
 
 
26
 * bzrlib.initialize -- setup the library for use
 
27
 * bzrlib.plugin.load_plugins -- load all installed plugins
 
28
 * bzrlib.branch.Branch.open -- open a branch
 
29
 * bzrlib.workingtree.WorkingTree.open -- open a working tree
 
30
 
 
31
We hope you enjoy this library.
 
32
"""
 
33
 
 
34
import time
 
35
 
 
36
# Keep track of when bzrlib was first imported, so that we can give rough
 
37
# timestamps relative to program start in the log file kept by bzrlib.trace.
 
38
_start_time = time.time()
 
39
 
 
40
import sys
 
41
if getattr(sys, '_bzr_lazy_regex', False):
 
42
    # The 'bzr' executable sets _bzr_lazy_regex.  We install the lazy regex
 
43
    # hack as soon as possible so that as much of the standard library can
 
44
    # benefit, including the 'string' module.
 
45
    del sys._bzr_lazy_regex
 
46
    import bzrlib.lazy_regex
 
47
    bzrlib.lazy_regex.install_lazy_compile()
 
48
 
 
49
 
 
50
IGNORE_FILENAME = ".bzrignore"
 
51
 
 
52
 
 
53
__copyright__ = "Copyright 2005-2010 Canonical Ltd."
 
54
 
 
55
# same format as sys.version_info: "A tuple containing the five components of
 
56
# the version number: major, minor, micro, releaselevel, and serial. All
 
57
# values except releaselevel are integers; the release level is 'alpha',
 
58
# 'beta', 'candidate', or 'final'. The version_info value corresponding to the
 
59
# Python version 2.0 is (2, 0, 0, 'final', 0)."  Additionally we use a
 
60
# releaselevel of 'dev' for unreleased under-development code.
 
61
 
 
62
version_info = (2, 2, 0, 'beta', 3)
 
63
 
 
64
# API compatibility version
 
65
api_minimum_version = (2, 2, 0)
 
66
 
 
67
 
 
68
def _format_version_tuple(version_info):
 
69
    """Turn a version number 2, 3 or 5-tuple into a short string.
 
70
 
 
71
    This format matches <http://docs.python.org/dist/meta-data.html>
 
72
    and the typical presentation used in Python output.
 
73
 
 
74
    This also checks that the version is reasonable: the sub-release must be
 
75
    zero for final releases.
 
76
 
 
77
    >>> print _format_version_tuple((1, 0, 0, 'final', 0))
 
78
    1.0.0
 
79
    >>> print _format_version_tuple((1, 2, 0, 'dev', 0))
 
80
    1.2.0dev
 
81
    >>> print bzrlib._format_version_tuple((1, 2, 0, 'dev', 1))
 
82
    1.2.0dev1
 
83
    >>> print _format_version_tuple((1, 1, 1, 'candidate', 2))
 
84
    1.1.1rc2
 
85
    >>> print bzrlib._format_version_tuple((2, 1, 0, 'beta', 1))
 
86
    2.1b1
 
87
    >>> print _format_version_tuple((1, 4, 0))
 
88
    1.4.0
 
89
    >>> print _format_version_tuple((1, 4))
 
90
    1.4
 
91
    >>> print bzrlib._format_version_tuple((2, 1, 0, 'final', 1))
 
92
    Traceback (most recent call last):
 
93
    ...
 
94
    ValueError: version_info (2, 1, 0, 'final', 1) not valid
 
95
    >>> print _format_version_tuple((1, 4, 0, 'wibble', 0))
 
96
    Traceback (most recent call last):
 
97
    ...
 
98
    ValueError: version_info (1, 4, 0, 'wibble', 0) not valid
 
99
    """
 
100
    if len(version_info) == 2:
 
101
        main_version = '%d.%d' % version_info[:2]
 
102
    else:
 
103
        main_version = '%d.%d.%d' % version_info[:3]
 
104
    if len(version_info) <= 3:
 
105
        return main_version
 
106
 
 
107
    release_type = version_info[3]
 
108
    sub = version_info[4]
 
109
 
 
110
    # check they're consistent
 
111
    if release_type == 'final' and sub == 0:
 
112
        sub_string = ''
 
113
    elif release_type == 'dev' and sub == 0:
 
114
        sub_string = 'dev'
 
115
    elif release_type == 'dev':
 
116
        sub_string = 'dev' + str(sub)
 
117
    elif release_type in ('alpha', 'beta'):
 
118
        if version_info[2] == 0:
 
119
            main_version = '%d.%d' % version_info[:2]
 
120
        sub_string = release_type[0] + str(sub)
 
121
    elif release_type == 'candidate':
 
122
        sub_string = 'rc' + str(sub)
 
123
    else:
 
124
        raise ValueError("version_info %r not valid" % (version_info,))
 
125
 
 
126
    return main_version + sub_string
 
127
 
 
128
 
 
129
__version__ = _format_version_tuple(version_info)
 
130
version_string = __version__
 
131
 
 
132
# bzr has various bits of global state that are slowly being eliminated.
 
133
# This variable is intended to permit any new state-like things to be attached
 
134
# to a BzrLibraryState object rather than getting new global variables that
 
135
# need to be hunted down. Accessing the current BzrLibraryState through this
 
136
# variable is not encouraged: it is better to pass it around as part of the
 
137
# context of an operation than to look it up directly, but when that is too
 
138
# hard, it is better to use this variable than to make a branch new global
 
139
# variable.
 
140
# If using this variable my looking it up (because it can't be easily obtained)
 
141
# it is important to store the reference you get, rather than looking it up
 
142
# repeatedly; that way your code will behave properly in the bzrlib test suite
 
143
# and from programs that do use multiple library contexts.
 
144
global_state = None
 
145
 
 
146
 
 
147
class BzrLibraryState(object):
 
148
    """The state about how bzrlib has been configured.
 
149
    
 
150
    :ivar saved_state: The bzrlib.global_state at the time __enter__ was
 
151
        called.
 
152
    :ivar cleanups: An ObjectWithCleanups which can be used for cleanups that
 
153
        should occur when the use of bzrlib is completed. This is initialised
 
154
        in __enter__ and executed in __exit__.
 
155
    """
 
156
 
 
157
    def __init__(self, setup_ui=True, stdin=None, stdout=None, stderr=None):
 
158
        """Create library start for normal use of bzrlib.
 
159
 
 
160
        Most applications that embed bzrlib, including bzr itself, should just
 
161
        call bzrlib.initialize(), but it is possible to use the state class
 
162
        directly.
 
163
 
 
164
        More options may be added in future so callers should use named
 
165
        arguments.
 
166
 
 
167
        BzrLibraryState implements the Python 2.5 Context Manager protocol, and
 
168
        can be used with the with statement. Upon __enter__ the global
 
169
        variables in use by bzr are set, and they are cleared on __exit__.
 
170
 
 
171
        :param setup_ui: If true (default) use a terminal UI; otherwise 
 
172
            some other ui_factory must be assigned to `bzrlib.ui.ui_factory` by
 
173
            the caller.
 
174
        :param stdin, stdout, stderr: If provided, use these for terminal IO;
 
175
            otherwise use the files in `sys`.
 
176
        """
 
177
        self.setup_ui = setup_ui
 
178
        self.stdin = stdin
 
179
        self.stdout = stdout
 
180
        self.stderr = stderr
 
181
 
 
182
    def __enter__(self):
 
183
        # NB: This function tweaks so much global state it's hard to test it in
 
184
        # isolation within the same interpreter.  It's not reached on normal
 
185
        # in-process run_bzr calls.  If it's broken, we expect that
 
186
        # TestRunBzrSubprocess may fail.
 
187
        if version_info[3] == 'final':
 
188
            from bzrlib.symbol_versioning import suppress_deprecation_warnings
 
189
            suppress_deprecation_warnings(override=True)
 
190
 
 
191
        import bzrlib.cleanup
 
192
        import bzrlib.trace
 
193
        self.cleanups = bzrlib.cleanup.ObjectWithCleanups()
 
194
        bzrlib.trace.enable_default_logging()
 
195
 
 
196
        if self.setup_ui:
 
197
            import bzrlib.ui
 
198
            stdin = self.stdin or sys.stdin
 
199
            stdout = self.stdout or sys.stdout
 
200
            stderr = self.stderr or sys.stderr
 
201
            bzrlib.ui.ui_factory = bzrlib.ui.make_ui_for_terminal(
 
202
                stdin, stdout, stderr)
 
203
        global global_state
 
204
        self.saved_state = global_state
 
205
        global_state = self
 
206
 
 
207
    def __exit__(self, exc_type, exc_val, exc_tb):
 
208
        self.cleanups.cleanup_now()
 
209
        import bzrlib.ui
 
210
        bzrlib.trace._flush_stdout_stderr()
 
211
        bzrlib.trace._flush_trace()
 
212
        import bzrlib.osutils
 
213
        bzrlib.osutils.report_extension_load_failures()
 
214
        bzrlib.ui.ui_factory.__exit__(None, None, None)
 
215
        bzrlib.ui.ui_factory = None
 
216
        global global_state
 
217
        global_state = self.saved_state
 
218
        return False # propogate exceptions.
 
219
 
 
220
 
 
221
def initialize(setup_ui=True, stdin=None, stdout=None, stderr=None):
 
222
    """Set up everything needed for normal use of bzrlib.
 
223
 
 
224
    Most applications that embed bzrlib, including bzr itself, should call
 
225
    this function to initialize various subsystems.  
 
226
 
 
227
    More options may be added in future so callers should use named arguments.
 
228
 
 
229
    :param setup_ui: If true (default) use a terminal UI; otherwise 
 
230
        some other ui_factory must be assigned to `bzrlib.ui.ui_factory` by
 
231
        the caller.
 
232
    :param stdin, stdout, stderr: If provided, use these for terminal IO;
 
233
        otherwise use the files in `sys`.
 
234
    :return: A context manager for the use of bzrlib. The __enter__ method of
 
235
        this context needs to be alled before it takes effect, and the __exit__
 
236
        should be called by the caller before exiting their process or
 
237
        otherwise stopping use of bzrlib. Advanced callers can use
 
238
        BzrLibraryState directly.
 
239
    """
 
240
    return BzrLibraryState(setup_ui=setup_ui, stdin=stdin,
 
241
        stdout=stdout, stderr=stderr)
 
242
 
 
243
 
 
244
def test_suite():
 
245
    import tests
 
246
    return tests.test_suite()