← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/trace.py

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2011-05-04 12:10:51 UTC
  • mfrom: (5819.1.4 777007-developer-doc)
  • Revision ID: pqm@pqm.ubuntu.com-20110504121051-aovlsmqiivjmc4fc
(jelmer) Small fixes to developer documentation. (Jonathan Riddell)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/trace.py
1
 
# Copyright (C) 2005, 2006 Canonical Ltd
 
1
# Copyright (C) 2005-2011 Canonical Ltd
2
2
#
3
3
# This program is free software; you can redistribute it and/or modify
4
4
# it under the terms of the GNU General Public License as published by
12
12
#
13
13
# You should have received a copy of the GNU General Public License
14
14
# along with this program; if not, write to the Free Software
15
 
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16
16
 
17
 
"""Messages and logging for bazaar-ng.
 
17
"""Messages and logging.
18
18
 
19
19
Messages are supplied by callers as a string-formatting template, plus values
20
20
to be inserted into it.  The actual %-formatting is deferred to the log
33
33
 
34
34
Output to stderr depends on the mode chosen by the user.  By default, messages
35
35
of info and above are sent out, which results in progress messages such as the
36
 
list of files processed by add and commit.  In quiet mode, only warnings and
37
 
above are shown.  In debug mode, stderr gets debug messages too.
 
36
list of files processed by add and commit.  In debug mode, stderr gets debug messages too.
38
37
 
39
38
Errors that terminate an operation are generally passed back as exceptions;
40
39
others may be just emitted as messages.
49
48
# FIXME: Unfortunately it turns out that python's logging module
50
49
# is quite expensive, even when the message is not printed by any handlers.
51
50
# We should perhaps change back to just simply doing it here.
 
51
#
 
52
# On the other hand, as of 1.2 we generally only call the mutter() statement
 
53
# if (according to debug_flags) we actually intend to write it.  So the
 
54
# increased cost of logging.py is not so bad, and we could standardize on
 
55
# that.
52
56
 
 
57
import codecs
 
58
import logging
53
59
import os
54
60
import sys
55
 
import re
 
61
import time
56
62
 
57
63
from bzrlib.lazy_import import lazy_import
58
64
lazy_import(globals(), """
 
65
from cStringIO import StringIO
59
66
import errno
60
 
import logging
 
67
import locale
 
68
import tempfile
 
69
import traceback
61
70
""")
62
71
 
63
72
import bzrlib
64
 
from bzrlib.symbol_versioning import (deprecated_function,
65
 
        zero_nine,
66
 
        )
 
73
 
 
74
from bzrlib.symbol_versioning import (
 
75
    deprecated_function,
 
76
    deprecated_in,
 
77
    )
67
78
 
68
79
lazy_import(globals(), """
69
 
from bzrlib import debug
 
80
from bzrlib import (
 
81
    debug,
 
82
    errors,
 
83
    osutils,
 
84
    ui,
 
85
    )
70
86
""")
71
87
 
72
 
_file_handler = None
73
 
_stderr_handler = None
74
 
_stderr_quiet = False
 
88
 
 
89
# global verbosity for bzrlib; controls the log level for stderr; 0=normal; <0
 
90
# is quiet; >0 is verbose.
 
91
_verbosity_level = 0
 
92
 
 
93
# File-like object where mutter/debug output is currently sent.  Can be
 
94
# changed by _push_log_file etc.  This is directly manipulated by some
 
95
# external code; maybe there should be functions to do that more precisely
 
96
# than push/pop_log_file.
75
97
_trace_file = None
76
 
_trace_depth = 0
77
 
_bzr_log_file = None
78
 
 
79
 
 
80
 
# configure convenient aliases for output routines
81
 
 
 
98
 
 
99
# Absolute path for ~/.bzr.log.  Not changed even if the log/trace output is
 
100
# redirected elsewhere.  Used to show the location in --version.
 
101
_bzr_log_filename = None
 
102
 
 
103
# The time the first message was written to the trace file, so that we can
 
104
# show relative times since startup.
 
105
_bzr_log_start_time = bzrlib._start_time
 
106
 
 
107
 
 
108
# held in a global for quick reference
82
109
_bzr_logger = logging.getLogger('bzr')
83
110
 
 
111
 
84
112
def note(*args, **kwargs):
 
113
    """Output a note to the user.
 
114
 
 
115
    Takes the same parameters as logging.info.
 
116
 
 
117
    :return: None
 
118
    """
85
119
    # FIXME note always emits utf-8, regardless of the terminal encoding
86
 
    import bzrlib.ui
87
 
    bzrlib.ui.ui_factory.clear_term()
 
120
    #
 
121
    # FIXME: clearing the ui and then going through the abstract logging
 
122
    # framework is whack; we should probably have a logging Handler that
 
123
    # deals with terminal output if needed.
 
124
    ui.ui_factory.clear_term()
88
125
    _bzr_logger.info(*args, **kwargs)
89
126
 
 
127
 
90
128
def warning(*args, **kwargs):
91
 
    import bzrlib.ui
92
 
    bzrlib.ui.ui_factory.clear_term()
 
129
    ui.ui_factory.clear_term()
93
130
    _bzr_logger.warning(*args, **kwargs)
94
131
 
95
 
info = note
96
 
log_error = _bzr_logger.error
97
 
error =     _bzr_logger.error
 
132
 
 
133
@deprecated_function(deprecated_in((2, 1, 0)))
 
134
def info(*args, **kwargs):
 
135
    """Deprecated: use trace.note instead."""
 
136
    note(*args, **kwargs)
 
137
 
 
138
 
 
139
@deprecated_function(deprecated_in((2, 1, 0)))
 
140
def log_error(*args, **kwargs):
 
141
    """Deprecated: use bzrlib.trace.show_error instead"""
 
142
    _bzr_logger.error(*args, **kwargs)
 
143
 
 
144
 
 
145
@deprecated_function(deprecated_in((2, 1, 0)))
 
146
def error(*args, **kwargs):
 
147
    """Deprecated: use bzrlib.trace.show_error instead"""
 
148
    _bzr_logger.error(*args, **kwargs)
 
149
 
 
150
 
 
151
def show_error(*args, **kwargs):
 
152
    """Show an error message to the user.
 
153
 
 
154
    Don't use this for exceptions, use report_exception instead.
 
155
    """
 
156
    _bzr_logger.error(*args, **kwargs)
98
157
 
99
158
 
100
159
def mutter(fmt, *args):
101
160
    if _trace_file is None:
102
161
        return
 
162
    # XXX: Don't check this every time; instead anyone who closes the file
 
163
    # ought to deregister it.  We can tolerate None.
103
164
    if (getattr(_trace_file, 'closed', None) is not None) and _trace_file.closed:
104
165
        return
105
166
 
118
179
        out = fmt % tuple(real_args)
119
180
    else:
120
181
        out = fmt
121
 
    out += '\n'
 
182
    now = time.time()
 
183
    timestamp = '%0.3f  ' % (now - _bzr_log_start_time,)
 
184
    out = timestamp + out + '\n'
122
185
    _trace_file.write(out)
123
 
    # TODO: jam 20051227 Consider flushing the trace file to help debugging
124
 
    #_trace_file.flush()
 
186
    # there's no explicit flushing; the file is typically line buffered.
 
187
 
 
188
 
 
189
def mutter_callsite(stacklevel, fmt, *args):
 
190
    """Perform a mutter of fmt and args, logging the call trace.
 
191
 
 
192
    :param stacklevel: The number of frames to show. None will show all
 
193
        frames.
 
194
    :param fmt: The format string to pass to mutter.
 
195
    :param args: A list of substitution variables.
 
196
    """
 
197
    outf = StringIO()
 
198
    if stacklevel is None:
 
199
        limit = None
 
200
    else:
 
201
        limit = stacklevel + 1
 
202
    traceback.print_stack(limit=limit, file=outf)
 
203
    formatted_lines = outf.getvalue().splitlines()
 
204
    formatted_stack = '\n'.join(formatted_lines[:-2])
 
205
    mutter(fmt + "\nCalled from:\n%s", *(args + (formatted_stack,)))
125
206
 
126
207
 
127
208
def _rollover_trace_maybe(trace_fname):
131
212
        if size <= 4 << 20:
132
213
            return
133
214
        old_fname = trace_fname + '.old'
134
 
        from osutils import rename
135
 
        rename(trace_fname, old_fname)
 
215
        osutils.rename(trace_fname, old_fname)
136
216
    except OSError:
137
217
        return
138
218
 
139
219
 
140
 
def open_tracefile(tracefilename='~/.bzr.log'):
141
 
    # Messages are always written to here, so that we have some
142
 
    # information if something goes wrong.  In a future version this
143
 
    # file will be removed on successful completion.
144
 
    global _file_handler, _bzr_log_file
145
 
    import codecs
146
 
 
147
 
    trace_fname = os.path.join(os.path.expanduser(tracefilename))
148
 
    _rollover_trace_maybe(trace_fname)
 
220
def _get_bzr_log_filename():
 
221
    bzr_log = os.environ.get('BZR_LOG')
 
222
    if bzr_log:
 
223
        return bzr_log
 
224
    home = os.environ.get('BZR_HOME')
 
225
    if home is None:
 
226
        if sys.platform == 'win32':
 
227
            from bzrlib import win32utils
 
228
            home = win32utils.get_home_location()
 
229
        else:
 
230
            home = os.path.expanduser('~')
 
231
    return os.path.join(home, '.bzr.log')
 
232
 
 
233
 
 
234
def _open_bzr_log():
 
235
    """Open the .bzr.log trace file.
 
236
 
 
237
    If the log is more than a particular length, the old file is renamed to
 
238
    .bzr.log.old and a new file is started.  Otherwise, we append to the
 
239
    existing file.
 
240
 
 
241
    This sets the global _bzr_log_filename.
 
242
    """
 
243
    global _bzr_log_filename
 
244
 
 
245
    def _open_or_create_log_file(filename):
 
246
        """Open existing log file, or create with ownership and permissions
 
247
 
 
248
        It inherits the ownership and permissions (masked by umask) from
 
249
        the containing directory to cope better with being run under sudo
 
250
        with $HOME still set to the user's homedir.
 
251
        """
 
252
        flags = os.O_WRONLY | os.O_APPEND | osutils.O_TEXT
 
253
        while True:
 
254
            try:
 
255
                fd = os.open(filename, flags)
 
256
                break
 
257
            except OSError, e:
 
258
                if e.errno != errno.ENOENT:
 
259
                    raise
 
260
            try:
 
261
                fd = os.open(filename, flags | os.O_CREAT | os.O_EXCL, 0666)
 
262
            except OSError, e:
 
263
                if e.errno != errno.EEXIST:
 
264
                    raise
 
265
            else:
 
266
                osutils.copy_ownership_from_path(filename)
 
267
                break
 
268
        return os.fdopen(fd, 'at', 0) # unbuffered
 
269
 
 
270
 
 
271
    _bzr_log_filename = _get_bzr_log_filename()
 
272
    _rollover_trace_maybe(_bzr_log_filename)
149
273
    try:
150
 
        LINE_BUFFERED = 1
151
 
        #tf = codecs.open(trace_fname, 'at', 'utf8', buffering=LINE_BUFFERED)
152
 
        tf = open(trace_fname, 'at', LINE_BUFFERED)
153
 
        _bzr_log_file = tf
154
 
        if tf.tell() == 0:
155
 
            tf.write("\nthis is a debug log for diagnosing/reporting problems in bzr\n")
156
 
            tf.write("you can delete or truncate this file, or include sections in\n")
157
 
            tf.write("bug reports to bazaar-ng@lists.canonical.com\n\n")
158
 
        _file_handler = logging.StreamHandler(tf)
159
 
        fmt = r'[%(process)5d] %(asctime)s.%(msecs)03d %(levelname)s: %(message)s'
160
 
        datefmt = r'%a %H:%M:%S'
161
 
        _file_handler.setFormatter(logging.Formatter(fmt, datefmt))
162
 
        _file_handler.setLevel(logging.DEBUG)
163
 
        logging.getLogger('').addHandler(_file_handler)
164
 
    except IOError, e:
165
 
        warning("failed to open trace file: %s" % (e))
166
 
 
167
 
 
168
 
@deprecated_function(zero_nine)
169
 
def log_exception(msg=None):
170
 
    """Log the last exception to stderr and the trace file.
171
 
 
172
 
    The exception string representation is used as the error
173
 
    summary, unless msg is given.
174
 
    """
175
 
    if msg:
176
 
        error(msg)
177
 
    log_exception_quietly()
 
274
        bzr_log_file = _open_or_create_log_file(_bzr_log_filename)
 
275
        bzr_log_file.write('\n')
 
276
        if bzr_log_file.tell() <= 2:
 
277
            bzr_log_file.write("this is a debug log for diagnosing/reporting problems in bzr\n")
 
278
            bzr_log_file.write("you can delete or truncate this file, or include sections in\n")
 
279
            bzr_log_file.write("bug reports to https://bugs.launchpad.net/bzr/+filebug\n\n")
 
280
 
 
281
        return bzr_log_file
 
282
 
 
283
    except EnvironmentError, e:
 
284
        # If we are failing to open the log, then most likely logging has not
 
285
        # been set up yet. So we just write to stderr rather than using
 
286
        # 'warning()'. If we using warning(), users get the unhelpful 'no
 
287
        # handlers registered for "bzr"' when something goes wrong on the
 
288
        # server. (bug #503886)
 
289
        sys.stderr.write("failed to open trace file: %s\n" % (e,))
 
290
    # TODO: What should happen if we fail to open the trace file?  Maybe the
 
291
    # objects should be pointed at /dev/null or the equivalent?  Currently
 
292
    # returns None which will cause failures later.
 
293
    return None
 
294
 
 
295
 
 
296
def enable_default_logging():
 
297
    """Configure default logging: messages to stderr and debug to .bzr.log
 
298
 
 
299
    This should only be called once per process.
 
300
 
 
301
    Non-command-line programs embedding bzrlib do not need to call this.  They
 
302
    can instead either pass a file to _push_log_file, or act directly on
 
303
    logging.getLogger("bzr").
 
304
 
 
305
    Output can be redirected away by calling _push_log_file.
 
306
 
 
307
    :return: A memento from push_log_file for restoring the log state.
 
308
    """
 
309
    start_time = osutils.format_local_date(_bzr_log_start_time,
 
310
                                           timezone='local')
 
311
    # create encoded wrapper around stderr
 
312
    bzr_log_file = _open_bzr_log()
 
313
    if bzr_log_file is not None:
 
314
        bzr_log_file.write(start_time.encode('utf-8') + '\n')
 
315
    memento = push_log_file(bzr_log_file,
 
316
        r'[%(process)5d] %(asctime)s.%(msecs)03d %(levelname)s: %(message)s',
 
317
        r'%Y-%m-%d %H:%M:%S')
 
318
    # after hooking output into bzr_log, we also need to attach a stderr
 
319
    # handler, writing only at level info and with encoding
 
320
    term_encoding = osutils.get_terminal_encoding()
 
321
    writer_factory = codecs.getwriter(term_encoding)
 
322
    encoded_stderr = writer_factory(sys.stderr, errors='replace')
 
323
    stderr_handler = logging.StreamHandler(encoded_stderr)
 
324
    stderr_handler.setLevel(logging.INFO)
 
325
    logging.getLogger('bzr').addHandler(stderr_handler)
 
326
    return memento
 
327
 
 
328
 
 
329
def push_log_file(to_file, log_format=None, date_format=None):
 
330
    """Intercept log and trace messages and send them to a file.
 
331
 
 
332
    :param to_file: A file-like object to which messages will be sent.
 
333
 
 
334
    :returns: A memento that should be passed to _pop_log_file to restore the
 
335
    previously active logging.
 
336
    """
 
337
    global _trace_file
 
338
    # make a new handler
 
339
    new_handler = logging.StreamHandler(to_file)
 
340
    new_handler.setLevel(logging.DEBUG)
 
341
    if log_format is None:
 
342
        log_format = '%(levelname)8s  %(message)s'
 
343
    new_handler.setFormatter(logging.Formatter(log_format, date_format))
 
344
    # save and remove any existing log handlers
 
345
    bzr_logger = logging.getLogger('bzr')
 
346
    old_handlers = bzr_logger.handlers[:]
 
347
    del bzr_logger.handlers[:]
 
348
    # set that as the default logger
 
349
    bzr_logger.addHandler(new_handler)
 
350
    bzr_logger.setLevel(logging.DEBUG)
 
351
    # TODO: check if any changes are needed to the root logger
 
352
    #
 
353
    # TODO: also probably need to save and restore the level on bzr_logger.
 
354
    # but maybe we can avoid setting the logger level altogether, and just set
 
355
    # the level on the handler?
 
356
    #
 
357
    # save the old trace file
 
358
    old_trace_file = _trace_file
 
359
    # send traces to the new one
 
360
    _trace_file = to_file
 
361
    result = new_handler, _trace_file
 
362
    return ('log_memento', old_handlers, new_handler, old_trace_file, to_file)
 
363
 
 
364
 
 
365
def pop_log_file((magic, old_handlers, new_handler, old_trace_file, new_trace_file)):
 
366
    """Undo changes to logging/tracing done by _push_log_file.
 
367
 
 
368
    This flushes, but does not close the trace file (so that anything that was
 
369
    in it is output.
 
370
 
 
371
    Takes the memento returned from _push_log_file."""
 
372
    global _trace_file
 
373
    _trace_file = old_trace_file
 
374
    bzr_logger = logging.getLogger('bzr')
 
375
    bzr_logger.removeHandler(new_handler)
 
376
    # must be closed, otherwise logging will try to close it at exit, and the
 
377
    # file will likely already be closed underneath.
 
378
    new_handler.close()
 
379
    bzr_logger.handlers = old_handlers
 
380
    if new_trace_file is not None:
 
381
        new_trace_file.flush()
178
382
 
179
383
 
180
384
def log_exception_quietly():
181
385
    """Log the last exception to the trace file only.
182
386
 
183
 
    Used for exceptions that occur internally and that may be 
184
 
    interesting to developers but not to users.  For example, 
 
387
    Used for exceptions that occur internally and that may be
 
388
    interesting to developers but not to users.  For example,
185
389
    errors loading plugins.
186
390
    """
187
 
    import traceback
188
391
    mutter(traceback.format_exc())
189
392
 
190
393
 
191
 
def enable_default_logging():
192
 
    """Configure default logging to stderr and .bzr.log"""
193
 
    # FIXME: if this is run twice, things get confused
194
 
    global _stderr_handler, _file_handler, _trace_file, _bzr_log_file
195
 
    _stderr_handler = logging.StreamHandler()
196
 
    logging.getLogger('').addHandler(_stderr_handler)
197
 
    _stderr_handler.setLevel(logging.INFO)
198
 
    if not _file_handler:
199
 
        open_tracefile()
200
 
    _trace_file = _bzr_log_file
201
 
    if _file_handler:
202
 
        _file_handler.setLevel(logging.DEBUG)
203
 
    _bzr_logger.setLevel(logging.DEBUG)
 
394
def set_verbosity_level(level):
 
395
    """Set the verbosity level.
 
396
 
 
397
    :param level: -ve for quiet, 0 for normal, +ve for verbose
 
398
    """
 
399
    global _verbosity_level
 
400
    _verbosity_level = level
 
401
    _update_logging_level(level < 0)
 
402
    ui.ui_factory.be_quiet(level < 0)
 
403
 
 
404
 
 
405
def get_verbosity_level():
 
406
    """Get the verbosity level.
 
407
 
 
408
    See set_verbosity_level() for values.
 
409
    """
 
410
    return _verbosity_level
204
411
 
205
412
 
206
413
def be_quiet(quiet=True):
207
 
    global _stderr_handler, _stderr_quiet
208
 
    
209
 
    _stderr_quiet = quiet
210
 
    if quiet:
211
 
        _stderr_handler.setLevel(logging.WARNING)
212
 
    else:
213
 
        _stderr_handler.setLevel(logging.INFO)
 
414
    if quiet:
 
415
        set_verbosity_level(-1)
 
416
    else:
 
417
        set_verbosity_level(0)
 
418
 
 
419
 
 
420
def _update_logging_level(quiet=True):
 
421
    """Hide INFO messages if quiet."""
 
422
    if quiet:
 
423
        _bzr_logger.setLevel(logging.WARNING)
 
424
    else:
 
425
        _bzr_logger.setLevel(logging.INFO)
214
426
 
215
427
 
216
428
def is_quiet():
217
 
    global _stderr_quiet
218
 
    return _stderr_quiet
219
 
 
220
 
 
221
 
def disable_default_logging():
222
 
    """Turn off default log handlers.
223
 
 
224
 
    This is intended to be used by the test framework, which doesn't
225
 
    want leakage from the code-under-test into the main logs.
226
 
    """
227
 
 
228
 
    l = logging.getLogger('')
229
 
    l.removeHandler(_stderr_handler)
230
 
    if _file_handler:
231
 
        l.removeHandler(_file_handler)
232
 
    _trace_file = None
233
 
 
234
 
 
235
 
def enable_test_log(to_file):
236
 
    """Redirect logging to a temporary file for a test
237
 
    
238
 
    returns an opaque reference that should be passed to disable_test_log
239
 
    after the test completes.
240
 
    """
241
 
    disable_default_logging()
242
 
    global _trace_file
243
 
    global _trace_depth
244
 
    hdlr = logging.StreamHandler(to_file)
245
 
    hdlr.setLevel(logging.DEBUG)
246
 
    hdlr.setFormatter(logging.Formatter('%(levelname)8s  %(message)s'))
247
 
    _bzr_logger.addHandler(hdlr)
248
 
    _bzr_logger.setLevel(logging.DEBUG)
249
 
    result = hdlr, _trace_file, _trace_depth
250
 
    _trace_file = to_file
251
 
    _trace_depth += 1
252
 
    return result
253
 
 
254
 
 
255
 
def disable_test_log((test_log_hdlr, old_trace_file, old_trace_depth)):
256
 
    _bzr_logger.removeHandler(test_log_hdlr)
257
 
    test_log_hdlr.close()
258
 
    global _trace_file
259
 
    global _trace_depth
260
 
    _trace_file = old_trace_file
261
 
    _trace_depth = old_trace_depth
262
 
    if not _trace_depth:
263
 
        enable_default_logging()
 
429
    """Is the verbosity level negative?"""
 
430
    return _verbosity_level < 0
 
431
 
 
432
 
 
433
def is_verbose():
 
434
    """Is the verbosity level positive?"""
 
435
    return _verbosity_level > 0
 
436
 
 
437
 
 
438
def debug_memory(message='', short=True):
 
439
    """Write out a memory dump."""
 
440
    if sys.platform == 'win32':
 
441
        from bzrlib import win32utils
 
442
        win32utils.debug_memory_win32api(message=message, short=short)
 
443
    else:
 
444
        _debug_memory_proc(message=message, short=short)
 
445
 
 
446
 
 
447
_short_fields = ('VmPeak', 'VmSize', 'VmRSS')
 
448
 
 
449
def _debug_memory_proc(message='', short=True):
 
450
    try:
 
451
        status_file = file('/proc/%s/status' % os.getpid(), 'rb')
 
452
    except IOError:
 
453
        return
 
454
    try:
 
455
        status = status_file.read()
 
456
    finally:
 
457
        status_file.close()
 
458
    if message:
 
459
        note(message)
 
460
    for line in status.splitlines():
 
461
        if not short:
 
462
            note(line)
 
463
        else:
 
464
            for field in _short_fields:
 
465
                if line.startswith(field):
 
466
                    note(line)
 
467
                    break
 
468
 
 
469
def _dump_memory_usage(err_file):
 
470
    try:
 
471
        try:
 
472
            fd, name = tempfile.mkstemp(prefix="bzr_memdump", suffix=".json")
 
473
            dump_file = os.fdopen(fd, 'w')
 
474
            from meliae import scanner
 
475
            scanner.dump_gc_objects(dump_file)
 
476
            err_file.write("Memory dumped to %s\n" % name)
 
477
        except ImportError:
 
478
            err_file.write("Dumping memory requires meliae module.\n")
 
479
            log_exception_quietly()
 
480
        except:
 
481
            err_file.write("Exception while dumping memory.\n")
 
482
            log_exception_quietly()
 
483
    finally:
 
484
        if dump_file is not None:
 
485
            dump_file.close()
 
486
        elif fd is not None:
 
487
            os.close(fd)
 
488
 
 
489
 
 
490
def _qualified_exception_name(eclass, unqualified_bzrlib_errors=False):
 
491
    """Give name of error class including module for non-builtin exceptions
 
492
 
 
493
    If `unqualified_bzrlib_errors` is True, errors specific to bzrlib will
 
494
    also omit the module prefix.
 
495
    """
 
496
    class_name = eclass.__name__
 
497
    module_name = eclass.__module__
 
498
    if module_name in ("exceptions", "__main__") or (
 
499
            unqualified_bzrlib_errors and module_name == "bzrlib.errors"):
 
500
        return class_name
 
501
    return "%s.%s" % (module_name, class_name)
264
502
 
265
503
 
266
504
def report_exception(exc_info, err_file):
267
 
    exc_type, exc_object, exc_tb = exc_info
 
505
    """Report an exception to err_file (typically stderr) and to .bzr.log.
 
506
 
 
507
    This will show either a full traceback or a short message as appropriate.
 
508
 
 
509
    :return: The appropriate exit code for this error.
 
510
    """
268
511
    # Log the full traceback to ~/.bzr.log
269
512
    log_exception_quietly()
 
513
    if 'error' in debug.debug_flags:
 
514
        print_exception(exc_info, err_file)
 
515
        return errors.EXIT_ERROR
 
516
    exc_type, exc_object, exc_tb = exc_info
270
517
    if (isinstance(exc_object, IOError)
271
518
        and getattr(exc_object, 'errno', None) == errno.EPIPE):
272
 
        print >>err_file, "bzr: broken pipe"
 
519
        err_file.write("bzr: broken pipe\n")
 
520
        return errors.EXIT_ERROR
273
521
    elif isinstance(exc_object, KeyboardInterrupt):
274
 
        print >>err_file, "bzr: interrupted"
 
522
        err_file.write("bzr: interrupted\n")
 
523
        return errors.EXIT_ERROR
 
524
    elif isinstance(exc_object, MemoryError):
 
525
        err_file.write("bzr: out of memory\n")
 
526
        if 'mem_dump' in debug.debug_flags:
 
527
            _dump_memory_usage(err_file)
 
528
        else:
 
529
            err_file.write("Use -Dmem_dump to dump memory to a file.\n")
 
530
        return errors.EXIT_ERROR
 
531
    elif isinstance(exc_object, ImportError) \
 
532
        and str(exc_object).startswith("No module named "):
 
533
        report_user_error(exc_info, err_file,
 
534
            'You may need to install this Python library separately.')
 
535
        return errors.EXIT_ERROR
275
536
    elif not getattr(exc_object, 'internal_error', True):
276
537
        report_user_error(exc_info, err_file)
277
 
    elif isinstance(exc_object, (OSError, IOError)):
 
538
        return errors.EXIT_ERROR
 
539
    elif isinstance(exc_object, (OSError, IOError)) or (
 
540
        # GZ 2010-05-20: Like (exc_type is pywintypes.error) but avoid import
 
541
        exc_type.__name__ == "error" and exc_type.__module__ == "pywintypes"):
278
542
        # Might be nice to catch all of these and show them as something more
279
543
        # specific, but there are too many cases at the moment.
280
544
        report_user_error(exc_info, err_file)
 
545
        return errors.EXIT_ERROR
281
546
    else:
282
547
        report_bug(exc_info, err_file)
 
548
        return errors.EXIT_INTERNAL_ERROR
 
549
 
 
550
 
 
551
def print_exception(exc_info, err_file):
 
552
    exc_type, exc_object, exc_tb = exc_info
 
553
    err_file.write("bzr: ERROR: %s.%s: %s\n" % (
 
554
        exc_type.__module__, exc_type.__name__, exc_object))
 
555
    err_file.write('\n')
 
556
    traceback.print_exception(exc_type, exc_object, exc_tb, file=err_file)
283
557
 
284
558
 
285
559
# TODO: Should these be specially encoding the output?
286
 
def report_user_error(exc_info, err_file):
 
560
def report_user_error(exc_info, err_file, advice=None):
287
561
    """Report to err_file an error that's not an internal error.
288
562
 
289
563
    These don't get a traceback unless -Derror was given.
 
564
 
 
565
    :param exc_info: 3-tuple from sys.exc_info()
 
566
    :param advice: Extra advice to the user to be printed following the
 
567
        exception.
290
568
    """
291
 
    if 'error' in debug.debug_flags:
292
 
        report_bug(exc_info, err_file)
293
 
        return
294
 
    print >>err_file, "bzr: ERROR:", str(exc_info[1])
 
569
    err_file.write("bzr: ERROR: %s\n" % (exc_info[1],))
 
570
    if advice:
 
571
        err_file.write("%s\n" % (advice,))
295
572
 
296
573
 
297
574
def report_bug(exc_info, err_file):
298
575
    """Report an exception that probably indicates a bug in bzr"""
299
 
    import traceback
300
 
    exc_type, exc_object, exc_tb = exc_info
301
 
    print >>err_file, "bzr: ERROR: %s.%s: %s" % (
302
 
        exc_type.__module__, exc_type.__name__, exc_object)
303
 
    print >>err_file
304
 
    traceback.print_exception(exc_type, exc_object, exc_tb, file=err_file)
305
 
    print >>err_file
306
 
    print >>err_file, 'bzr %s on python %s (%s)' % \
307
 
                       (bzrlib.__version__,
308
 
                        '.'.join(map(str, sys.version_info)),
309
 
                        sys.platform)
310
 
    print >>err_file, 'arguments: %r' % sys.argv
311
 
    print >>err_file
312
 
    print >>err_file, "** please send this report to bazaar-ng@lists.ubuntu.com"
 
576
    from bzrlib.crash import report_bug
 
577
    report_bug(exc_info, err_file)
 
578
 
 
579
 
 
580
def _flush_stdout_stderr():
 
581
    # called from the bzrlib library finalizer returned by bzrlib.initialize()
 
582
    try:
 
583
        sys.stdout.flush()
 
584
        sys.stderr.flush()
 
585
    except IOError, e:
 
586
        import errno
 
587
        if e.errno in [errno.EINVAL, errno.EPIPE]:
 
588
            pass
 
589
        else:
 
590
            raise
 
591
 
 
592
 
 
593
def _flush_trace():
 
594
    # called from the bzrlib library finalizer returned by bzrlib.initialize()
 
595
    global _trace_file
 
596
    if _trace_file:
 
597
        _trace_file.flush()
 
598
 
 
599
 
 
600
class Config(object):
 
601
    """Configuration of message tracing in bzrlib.
 
602
 
 
603
    This implements the context manager protocol and should manage any global
 
604
    variables still used. The default config used is DefaultConfig, but
 
605
    embedded uses of bzrlib may wish to use a custom manager.
 
606
    """
 
607
 
 
608
    def __enter__(self):
 
609
        return self # This is bound to the 'as' clause in a with statement.
 
610
 
 
611
    def __exit__(self, exc_type, exc_val, exc_tb):
 
612
        return False # propogate exceptions.
 
613
 
 
614
 
 
615
class DefaultConfig(Config):
 
616
    """A default configuration for tracing of messages in bzrlib.
 
617
 
 
618
    This implements the context manager protocol.
 
619
    """
 
620
 
 
621
    def __enter__(self):
 
622
        self._original_filename = _bzr_log_filename
 
623
        self._original_state = enable_default_logging()
 
624
        return self # This is bound to the 'as' clause in a with statement.
 
625
 
 
626
    def __exit__(self, exc_type, exc_val, exc_tb):
 
627
        pop_log_file(self._original_state)
 
628
        global _bzr_log_filename
 
629
        _bzr_log_filename = self._original_filename
 
630
        return False # propogate exceptions.