Metadata-Version: 2.1
Name: uologging
Version: 0.5.0
Summary: Auto-Configuration solution for Python built-in logging.
Home-page: UNKNOWN
Author: University of Oregon
Author-email: ntsjenkins@uoregon.edu
License: MIT
Description: uologging is a solution for configuring Python's built-in logging module.
        
        ## Enable console logging
        
        Simply call init_console_logging() within your package:
        
            uologging.init_console_logging()
        
        ## Enable (Linux) syslog logging
        
        Similarly, call init_syslog_logging():
        
            uologging.init_syslog_logging()
        
        ## 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()
            uologging.init_syslog_logging()
            
            # 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!
        
        ## Tracing a function
        
        There is a simple `trace` decorator you can use in your python modules to log the 'execution time' of any of your functions.
        
        > The trace decorator has DEBUG severity.
        > Call `set_verbosity_flag(2)` to see the trace messages in your logs.
        
            # hello.py
            import logging
            import uologging
        
            logger = logging.getLogger(__name__)
        
            @uologging.trace(logger)
            def hello():
                print('hello!')
        
        Expect the following messages to be logged:
        
            2022-01-07 15:40:09 DEBUG    [performance.py:33] Starting: example.hello:hello((),{})
            hello!
            2022-01-07 15:40:09 DEBUG    [performance.py:37] Finished: example.hello:hello((),{})
            2022-01-07 15:40:09 DEBUG    [performance.py:38] example.hello:hello((),{}) execution time: 0.00 sec
        
        > TODO: It would be nice to fix the "`[performance.py:33]`" information being printed, and instead print the actual traced function's definition location.
        
        ## `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!"')
        
Keywords: NTS,UO,Logging,Tracing
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: System :: Logging
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Description-Content-Type: text/markdown
