uologging 0.3.0

Auto-Configuration solution for Python built-in logging.

uologging is a solution for configuring Python's built-in logging module.

Enable console logging

Simply call init_console_logging() for your package:

uologging.init_console_logging('mypackage')

Enable (Linux) syslog logging

Similarly, call init_syslog_logging() for your package:

uologging.init_syslog_logging('mypackage')

argparse 'verbosity flag'

For CLI tools, we provide an integration with argparse to set the logging verbosity. This integration enables the tool's user to add -vv for maximum logging verbosity.

-v will enable INFO messages, but not DEBUG.

The verbosity_flag can be gathered via argparse using add_verbosity_flag(parser):

import uologging
import argparse

parser = argparse.ArgumentParser()
uologging.add_verbosity_flag(parser)

args = parser.parse_args(['-vv'])
# args.verbosity_flag == 2

Now, simply call set_logging_verbosity() with args.verbosity_flag for your package:

uologging.set_logging_verbosity(args.verbosity_flag)

Alternately, if you are comfortable with argparse 'Parent parsers', you can integrate with argparse using use get_default_parser() as a parent parser.

# Alternate 'Parent parser' argparse integration
parser = argparse.ArgumentParser(parents=[
    uologging.get_default_parser(),
])

Example: Configuring console & syslog logging

Let's imagine you have a package "examplepkg" with a CLI tool in the "mytool" module.

# mytool.py
import argparse
import uologging

uologging.init_console_logging('examplepkg')
uologging.init_syslog_logging('examplepkg')

# Parse CLI arguments, '-vv' will result in maximum logging verbosity.
parser = argparse.ArgumentParser()
uologging.add_verbosity_flag(parser)
args = parser.parse_args()

uologging.set_logging_verbosity(args.verbosity_flag)

Default Log Level

Per Python logging suggestion: WARNING, ERROR, and CRITICAL messages are all logged by default. Meanwhile, INFO and DEBUG messages can be enabled by providing verbosity_flag of 1 or 2 to uologging.set_logging_verbosity().

Logging messages format

The formatting for log messages is specified in the (private) uologging._logging_format variable.

Here are a couple of lines showing what you can expect your logs to looks like:

(2021-12-23 16:40:47)[CRITICAL] examplepkg || Just kidding, this is a test!
(2021-12-23 16:40:47)[   ERROR] examplepkg.just.testing || This is a test from a child module!

logging Best Practices

Use the Python logging package per the following best practices:

1. logger = logging.getLogger(__name__) to get the logger for each module/script.
2. Then, use logger.debug(), logger.info(), logger.warning(), etc to add tracing to your Python modules/scripts.

Example

A trivial example demonstrating best practices:

# hello.py
import logging

logger = logging.getLogger(__name__)

def hello():
    logger.debug('About to say "hello!"')
    print('hello!')
    logger.debug('Said "hello!"')