Metadata-Version: 2.1
Name: cs.logutils
Version: 20200518
Summary: Logging convenience routines.
Home-page: https://bitbucket.org/cameron_simpson/css/commits/all
Author: Cameron Simpson
Author-email: cs@cskk.id.au
License: GNU General Public License v3 or later (GPLv3+)
Description: 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.
Keywords: python2,python3
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Description-Content-Type: text/markdown
