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!"')
