b.trace : module documentation

Part of bzrlib

Messages and logging.

Messages are supplied by callers as a string-formatting template, plus values to be inserted into it. The actual %-formatting is deferred to the log library so that it doesn't need to be done for messages that won't be emitted.

Messages are classified by severity levels: critical, error, warning, info, and debug.

They can be sent to two places: to stderr, and to ~/.bzr.log. For purposes such as running the test suite, they can also be redirected away from both of those two places to another location.

~/.bzr.log gets all messages, and full tracebacks for uncaught exceptions. This trace file is always in UTF-8, regardless of the user's default encoding, so that we can always rely on writing any message.

Output to stderr depends on the mode chosen by the user. By default, messages of info and above are sent out, which results in progress messages such as the list of files processed by add and commit. In debug mode, stderr gets debug messages too.

Errors that terminate an operation are generally passed back as exceptions; others may be just emitted as messages.

Exceptions are reported in a brief form to stderr so as not to look scary. BzrErrors are required to be able to format themselves into a properly explanatory message. This is not true for builtin exceptions such as KeyError, which typically just str to "0". They're printed in a different form.

Function note Output a note to the user.
Function warning Undocumented
Function show_error Show an error message to the user.
Function mutter Undocumented
Function mutter_callsite Perform a mutter of fmt and args, logging the call trace.
Function enable_default_logging Configure default logging: messages to stderr and debug to .bzr.log
Function push_log_file Intercept log and trace messages and send them to a file.
Function pop_log_file Undo changes to logging/tracing done by _push_log_file.
Function log_exception_quietly Log the last exception to the trace file only.
Function set_verbosity_level Set the verbosity level.
Function get_verbosity_level Get the verbosity level.
Function be_quiet Undocumented
Function is_quiet Is the verbosity level negative?
Function is_verbose Is the verbosity level positive?
Function debug_memory Write out a memory dump.
Function report_exception Report an exception to err_file (typically stderr) and to .bzr.log.
Function print_exception Undocumented
Function report_user_error Report to err_file an error that's not an internal error.
Function report_bug Report an exception that probably indicates a bug in bzr
Class Config Configuration of message tracing in bzrlib.
Class DefaultConfig A default configuration for tracing of messages in bzrlib.
Function _rollover_trace_maybe Undocumented
Function _get_bzr_log_filename Undocumented
Function _open_bzr_log Open the .bzr.log trace file.
Function _update_logging_level Hide INFO messages if quiet.
Function _debug_memory_proc Undocumented
Function _dump_memory_usage Undocumented
Function _qualified_exception_name Give name of error class including module for non-builtin exceptions
Function _flush_stdout_stderr Undocumented
Function _flush_trace Undocumented
def note(*args, **kwargs):
Output a note to the user.

Takes the same parameters as logging.info.

ReturnsNone
def warning(*args, **kwargs):
Undocumented
def show_error(*args, **kwargs):
Show an error message to the user.

Don't use this for exceptions, use report_exception instead.

def mutter(fmt, *args):
Undocumented
def mutter_callsite(stacklevel, fmt, *args):
Perform a mutter of fmt and args, logging the call trace.
ParametersstacklevelThe number of frames to show. None will show all frames.
fmtThe format string to pass to mutter.
argsA list of substitution variables.
def _rollover_trace_maybe(trace_fname):
Undocumented
def _get_bzr_log_filename():
Undocumented
def _open_bzr_log():
Open the .bzr.log trace file.

If the log is more than a particular length, the old file is renamed to .bzr.log.old and a new file is started. Otherwise, we append to the existing file.

This sets the global _bzr_log_filename.

def enable_default_logging():
Configure default logging: messages to stderr and debug to .bzr.log

This should only be called once per process.

Non-command-line programs embedding bzrlib do not need to call this. They can instead either pass a file to _push_log_file, or act directly on logging.getLogger("bzr").

Output can be redirected away by calling _push_log_file.

ReturnsA memento from push_log_file for restoring the log state.
def push_log_file(to_file, log_format=None, date_format=None):
Intercept log and trace messages and send them to a file.
Parametersto_fileA file-like object to which messages will be sent.
ReturnsA memento that should be passed to _pop_log_file to restore the previously active logging.
def pop_log_file((magic, old_handlers, new_handler, old_trace_file, new_trace_file)):
Undo changes to logging/tracing done by _push_log_file.

This flushes, but does not close the trace file (so that anything that was in it is output.

Takes the memento returned from _push_log_file.

def log_exception_quietly():
Log the last exception to the trace file only.

Used for exceptions that occur internally and that may be interesting to developers but not to users. For example, errors loading plugins.

def set_verbosity_level(level):
Set the verbosity level.
Parameterslevel-ve for quiet, 0 for normal, +ve for verbose
def get_verbosity_level():
Get the verbosity level.

See set_verbosity_level() for values.

def be_quiet(quiet=True):
Undocumented
def _update_logging_level(quiet=True):
Hide INFO messages if quiet.
def is_quiet():
Is the verbosity level negative?
def is_verbose():
Is the verbosity level positive?
def debug_memory(message='', short=True):
Write out a memory dump.
def _debug_memory_proc(message='', short=True):
Undocumented
def _dump_memory_usage(err_file):
Undocumented
def _qualified_exception_name(eclass, unqualified_bzrlib_errors=False):
Give name of error class including module for non-builtin exceptions

If unqualified_bzrlib_errors is True, errors specific to bzrlib will also omit the module prefix.

def report_exception(exc_info, err_file):
Report an exception to err_file (typically stderr) and to .bzr.log.

This will show either a full traceback or a short message as appropriate.

ReturnsThe appropriate exit code for this error.
def print_exception(exc_info, err_file):
Undocumented
def report_user_error(exc_info, err_file, advice=None):
Report to err_file an error that's not an internal error.

These don't get a traceback unless -Derror was given.

Parametersexc_info3-tuple from sys.exc_info()
adviceExtra advice to the user to be printed following the exception.
def report_bug(exc_info, err_file):
Report an exception that probably indicates a bug in bzr
def _flush_stdout_stderr():
Undocumented
def _flush_trace():
Undocumented
API Documentation for Bazaar, generated by pydoctor at 2019-07-17 00:29:20.