[Python-Dev] Using logging in the stdlib and its unit tests

[Nick Coghlan]

On Sat, Dec 11, 2010 at 3:06 PM, Nick Coghlan <ncoghlan at gmail.com> wrote:
> Basically, as of 3.2, the correct "default" use is likely to be:
>
> print() for information you want to appear on stdout by default
> (especially in scripts)
> logging.debug() and .info() for additional debugging information that
> should be silenced by default
>
> warnings.warn() for actual programmatic warnings that should obey
> warning filter rules (logging can hook the warnings display mechanism)
> logging.warn() for warnings that should never raise an exception and
> should be emitted every time they are encountered
>
> raise an exception for normal error reporting
> logging.error(), .critical() and .exception() for error reporting that
> cannot raise an exception for some reason (e.g. long running processes
> that are simply recording that an exception occurred)

This could actually make a reasonably good basic for a "task oriented"
subsection of the logging documentation. Something like:

===============
Task: Display console output for ordinary usage of a command line
script or program
Tool: Use print()

Task: Report events that occur during normal operation of a program
(e.g. for status monitoring or fault investigation)
Tool: Use logging.info() (or logging.debug() for especially voluminous
or expensive to calculate output)

Task: Issue a warning regarding a particular runtime event
Tool: Use warnings.warn() in library code if the issue is avoidable
and the client application should be modified to eliminate the
warning.
Use logging.warn() if there is nothing the client application can do
about the situation, but the event should still be noted

Task: Report an error regarding a particular runtime event
Tool: Raise an exception

Task: Report suppression of an error without raising an exception
(e.g. error handler in a long-running server process)
Tool: Use logging.error(), logging.exception(), or logging.critical()
as appropriate to the specific error and application domain

Note: all references to the root level logging functions in the above
recommendations also cover direct invocation of the corresponding
methods on specific logger instances.
===============

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia