Part of bzrlib
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 |
Takes the same parameters as logging.info.
| Returns | None | |
Don't use this for exceptions, use report_exception instead.
| Parameters | stacklevel | The number of frames to show. None will show all frames. |
| fmt | The format string to pass to mutter. | |
| args | A list of substitution variables. |
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.
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.
| Returns | A memento from push_log_file for restoring the log state. | |
| Parameters | to_file | A file-like object to which messages will be sent. |
| Returns | A memento that should be passed to _pop_log_file to restore the previously active logging. | |
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.
Used for exceptions that occur internally and that may be interesting to developers but not to users. For example, errors loading plugins.
| Parameters | level | -ve for quiet, 0 for normal, +ve for verbose |
If unqualified_bzrlib_errors is True, errors specific to bzrlib will
also omit the module prefix.
This will show either a full traceback or a short message as appropriate.
| Returns | The appropriate exit code for this error. | |