Logging convenience routines.

*Latest release 20200518*:
* Sweeping removal of cs.obj.O, universally supplanted by types.SimpleNamespace.
* Default to logging level TRACK if stderr is a tty instead of logging.INFO.
* New ifverbose function with leading `verbose` parameter: if None, log at INFO otherwise if true, log at TRACK, otherwise do not log.
* BREAKING: remove global logging_level and trace_level variables, put it all in the global loginfo.
* Make STATUS just below TRACK so that it is above INFO instead of below.
* New status() function for cs.upd messages.
* UpdHandler: treat status_level as special, going directly to Upd.out.
* Improved source line recitation on modern Python.
* Default level if sys.stderr.isatty() now STATUS, not TRACK.
* Some fixes for loginfo initialisation and setting cs.pfx.cmd.

The logging package is very useful, but a little painful to use.
This package provides low impact logging setup and some extremely
useful if unconventional context hooks for logging.

The default logging verbosity output format has different defaults
based on whether an output log file is a tty
and whether the environment variable $DEBUG is set, and to what.

On terminals warnings and errors get ANSI colouring.

A mode is available that uses cs.upd.

Some examples:
--------------

Program initialisation::

    from cs.logutils import setup_logging

    def main(argv):
      cmd = os.path.basename(argv.pop(0))
      setup_logging(cmd)

Basic logging from anywhere::

    from cs.logutils import info, warning, error
    [...]
    def some_function(...):
        [...]
        error("nastiness found! bad value=%r", bad_value)

## Function `add_logfile(filename, logger=None, mode='a', encoding=None, delay=False, format=None, no_prefix=False)`

Add a FileHandler logging to the specified `filename`;
return the chosen logger and the new handler.

Parameters:
* `logger`: if supplied and not None, add the FileHandler to that
  Logger, otherwise to the root Logger. If `logger` is a string, call
  `logging.getLogger(logger)` to obtain the logger.
* `mode`, `encoding` and `delay`: passed to the logging.FileHandler
  initialiser.
* `format`: used to override the handler's default format.
* `no_prefix`: if true, do not put the Pfx context onto the front of the message.

## Function `critical(*a, **kw)`

Emit a log at `logging.CRITICAL` `level` with the current Pfx prefix.

## Function `D(msg, *args)`

Print formatted debug string straight to `sys.stderr` if
`D_mode` is true, bypassing the logging modules entirely.
A quick'n'dirty debug tool.

## Function `debug(*a, **kw)`

Emit a log at `logging.DEBUG` `level` with the current Pfx prefix.

## Function `error(*a, **kw)`

Emit a log at `logging.ERROR` `level` with the current Pfx prefix.

## Function `exception(msg, *args)`

Emit an exception log with the current Pfx prefix.

## Function `ftrace(func)`

Decorator to trace a function if `__module__.DEBUG` is true.

## Function `ifdebug()`

Test the `loginfo.level` against `logging.DEBUG`.

## Function `ifverbose(*a, **kw)`

Conditionally log a message.
If verbose is `None`
then the caller has not indicated a specific verbosity
and we use the `track` function.
If verbose is true
then we use the `info` function.

## Function `infer_logging_level(env_debug=None, environ=None, verbose=None)`

Infer a logging level from the `env_debug`, which by default
comes from the environment variable `$DEBUG`.

Usually default to logging.WARNING, but if sys.stderr is a terminal,
default to TRACK.

Parse the environment variable $DEBUG as a comma separated
list of flags.

Examine the in sequence flags to affect the logging level:
* `numeric < 1`: `logging.WARNING`
* `numeric >= 1 and < 2`: `logging.INFO`
* `numeric >= 2`: `logging.DEBUG`
* `"DEBUG"`: `logging.DEBUG`
* `"STATUS"`: `STATUS`
* `"INFO"`: `logging.INFO`
* `"TRACK"`: `TRACK`
* `"WARNING"`: `logging.WARNING`
* `"ERROR"`: `logging.ERROR`

Return an object with the following attributes:
* `.level`: A logging level.
* `.flags`: All the words from $DEBUG as separated by commas and uppercased.
* `.module_names`: Module names to be debugged.
* `.function_names`: Functions to be traced in the for "module_name.func_name()".

## Function `info(*a, **kw)`

Emit a log at `logging.INFO` `level` with the current Pfx prefix.

## Function `log(*a, **kw)`

Emit a log at the specified `level` with the current Pfx prefix.

## Function `logException(exc_type, exc_value, exc_tb)`

Replacement for sys.excepthook that reports via the cs.logutils
logging wrappers.

## Class `LogTime`

LogTime is a content manager that logs the elapsed time of the enclosed
code. After the run, the field .elapsed contains the elapsed time in
seconds.

### Method `LogTime.__init__(self, tag, *args, **kwargs)`

Set up a LogTime.

Parameters:
* `tag`: label included at the start of the log entry
* `args`: optional array; if not empty `args` is applied to
  `tag` with `%`
* `level`: keyword argument specifying a log level for a
  default log entry, default `logging.INFO`
* `threshold`: keyword argument specifying minimum time to
  cause a log, default None (no minimum)
* `warning_level`: keyword argument specifying the log level
  for a warning log entry, default `logging.WARNING`
* `warning_threshold`: keyword argument specifying a time
  which raises the log level to `warning_level`

## Function `logTo(filename, logger=None, mode='a', encoding=None, delay=False, format=None, no_prefix=False)`

Add a FileHandler logging to the specified `filename`;
return the chosen logger and the new handler.

Parameters:
* `logger`: if supplied and not None, add the FileHandler to that
  Logger, otherwise to the root Logger. If `logger` is a string, call
  `logging.getLogger(logger)` to obtain the logger.
* `mode`, `encoding` and `delay`: passed to the logging.FileHandler
  initialiser.
* `format`: used to override the handler's default format.
* `no_prefix`: if true, do not put the Pfx context onto the front of the message.

## Class `NullHandler(logging.Handler,logging.Filterer)`

A Handler which discards its requests.

## Class `PfxFormatter(logging.Formatter)`

A Formatter subclass that has access to the program's cmd and `Pfx` state.

### Method `PfxFormatter.__init__(self, fmt=None, datefmt=None, cmd=None)`

Initialise the `PfxFormatter`.

Parameters:
* `fmt`: format template,
  default from `DEFAULT_PFX_FORMAT` `'%(asctime)s %(levelname)s %(pfx)s: %(message)s'`.
  Passed through to `Formatter.__init__`.
* `datefmt`:
  Passed through to `Formatter.__init__`.
* `cmd`: the "command prefix" made available to format strings.
  If not set, `cs.pfx.cmd` is presented.

## Function `setup_logging(cmd_name=None, main_log=None, format=None, level=None, flags=None, upd_mode=None, ansi_mode=None, trace_mode=None, module_names=None, function_names=None, verbose=None)`

Arrange basic logging setup for conventional UNIX command
line error messaging; return an object with informative attributes.
That object is also available as the global `cs.lgutils.loginfo`.

Parameters:
* `cmd_name`: program name, default from `basename(sys.argv[0])`.
  Side-effect: sets `cs.pfx.cmd` to this value.
* `main_log`: default logging system.
  If None, the main log will go to sys.stderr;
  if `main_log` is a string, is it used as a filename to
  open in append mode;
  otherwise main_log should be a stream suitable
  for use with `logging.StreamHandler()`.
  The resulting log handler is added to the `logging` root logger.
* `format`: the message format for `main_log`.
  If `None`, use `DEFAULT_PFX_FORMAT_TTY`
  when `main_log` is a tty or FIFO,
  otherwise `DEFAULT_PFX_FORMAT`.
* `level`: `main_log` logging level.
  If None, infer a level from the environment
  using `infer_logging_level()`.
* `flags`: a string containing debugging flags separated by commas.
  If `None`, infer the flags from the environment using
  `infer_logging_level()`.
  The following flags have meaning:
  `D`: set cs.logutils.D_mode to True;
  `TDUMP`: attach a signal handler to SIGHUP to do a thread stack dump;
  `TRACE`: enable various noisy tracing facilities;
  `UPD`, `NOUPD`: set the default for `upd_mode` to True or False respectively.
* `upd_mode`: a Boolean to activate cs.upd as the `main_log` method;
  if `None`, set it to `True` if `flags` contains 'UPD',
  otherwise to `False` if `flags` contains 'NOUPD',
  otherwise set it from `main_log.isatty()`.
  A true value causes the root logger to use `cs.upd` for logging.
* `ansi_mode`: if `None`, set it from `main_log.isatty()`.
  A true value causes the root logger to colour certain logging levels
  using ANSI terminal sequences (currently only if `cs.upd` is used).
* `trace_mode`: if `None`, set it according to the presence of
  'TRACE' in flags. Otherwise if `trace_mode` is true, set the
  global `loginfo.trace_level` to `loginfo.level`; otherwise it defaults
  to `logging.DEBUG`.
* `verbose`: if `None`, then if stderr is a tty then the log
  level is `INFO` otherwise `WARNING`. Otherwise, if `verbose` is
  true then the log level is `INFO` otherwise `WARNING`.

## Function `status(*a, **kw)`

Emit a log at `STATUS` `level` with the current Pfx prefix.

## Function `trace(*a, **kw)`

Emit a log message at `loginfo.trace_level` with the current Pfx prefix.

## Function `track(*a, **kw)`

Emit a log at `TRACK` `level` with the current Pfx prefix.

## Function `upd(*a, **kw)`

If we're using an `UpdHandler`,
update the status line otherwise write an info message.

Note that this calls `Upd.out` directly with `msg%args`
and thus does not include the current `Pfx` prefix.
You may well want to use the `status()` function instead.

## Class `UpdHandler(logging.StreamHandler,logging.Handler,logging.Filterer)`

A `StreamHandler` subclass whose `.emit` method
uses a `cs.upd.Upd` for transcription.

### Method `UpdHandler.__init__(self, strm=None, upd_level=None, ansi_mode=None)`

Initialise the `UpdHandler`.

Parameters:
* `strm`: the output stream, default `sys.stderr`.
* `upd_level`: the magic logging level which updates the status line
  via `Upd`. Default: `STATUS`.
* `ansi_mode`: if `None`, set from `strm.isatty()`.
  A true value causes the handler to colour certain logging levels
  using ANSI terminal sequences.

## Function `warning(*a, **kw)`

Emit a log at `logging.WARNING` `level` with the current Pfx prefix.

## Function `with_log(filename, **kw)`

Context manager to add a Logger to the output logs temporarily.

# Release Log



*Release 20200518*:
* Sweeping removal of cs.obj.O, universally supplanted by types.SimpleNamespace.
* Default to logging level TRACK if stderr is a tty instead of logging.INFO.
* New ifverbose function with leading `verbose` parameter: if None, log at INFO otherwise if true, log at TRACK, otherwise do not log.
* BREAKING: remove global logging_level and trace_level variables, put it all in the global loginfo.
* Make STATUS just below TRACK so that it is above INFO instead of below.
* New status() function for cs.upd messages.
* UpdHandler: treat status_level as special, going directly to Upd.out.
* Improved source line recitation on modern Python.
* Default level if sys.stderr.isatty() now STATUS, not TRACK.
* Some fixes for loginfo initialisation and setting cs.pfx.cmd.

*Release 20200229*:
* Update for new Upd.without context manager.
* setup_logging: default `upd_mode` to `main_log.isatty()`, was previously False.
* Drop UpdHandler.upd method, shadowed by instance attribute, never used.

*Release 20190923*:
* New `TRACK` constant equal to `logging.INFO+5` to provide a level higher than `INFO`
* (which seems unreasonably noisy) and lower than `WARNING`
* warning for tracking salient events.
* New `track()` function to match.

*Release 20190220*:
Improvements to upd_mode.

*Release 20190103*:
Documentation updates.

*Release 20190101*:
Bugfix for @contextmanager usage.

*Release 20171030*:
Assorted fixes from recent module reshuffle. Other small features and cleanups. Drop a couple of unused functions.

*Release 20160828*:
Use "install_requires" instead of "requires" in DISTINFO.

*Release 20160827*:
* Pfx: import __exit__ handler
* Preliminary per-module and per-function syntax accepted in $DEBUG envvar.
* Improvements to X(), add DP() and XP() prefixed flavours.
* status() function to update terminal status line.
* New X_via_tty global flag: directs X() to tty instead of sys.stderr.
* Assorted other minor improvements.

*Release 20150118*:
metadata updates

*Release 20150110*:
Initial PyPI release.
