click_logging_config
====================

Quick and easy logging parameters for click commands.


.. contents::

.. section-numbering::


Installation
------------

The ``click_logging_config`` package is available from PyPI. Installing
into a virtual environment is recommended.

.. code-block::

   python3 -m venv .venv; .venv/bin/pip install click_logging_config


Getting Started
---------------

Using ``click_logging_config`` is intended to be very simple. A single
decorator applied to your click command or group adds some click options
specifically for managing logging context.

.. code-block::

   import click
   import logging
   from click_logging import logging_parameters

   log = logging.getLogger(__name__)

   def do_something()
       pass

   @click.command()
   @click.option("--my-option", type=str)
   # NOTE: Empty braces are required for hard-coded click-logging-config defaults.
   @logging_parameters()
   def my_command(my_option: str) -> None:
       log.info("doing something")
       try:
           do_something(my_option)
       except Exception as e:
           log.critical(f"something bad happened, {str(e)}")
           raise


Application of the ``@logging_parameters`` decorator must be applied immediately
*above* your click command function and *below* any other click decorators such
as arguments and options.

Having applied the decorator your command now has the following options
available to it.

.. code-block::

     --log-console-enable / --log-console-disable
                           Enable or disable console logging.
                           [default: log-console-disable]
     --log-console-json-enable / --log-console-json-disable
                           Enable or disable console JSON logging.
                           [default: log-console-json-disable]
     --log-file-enable / --log-file-disable
                           Enable or disable file logging.
                           [default: log-file-enable]
     --log-file-json-enable / --log-file-json-disable
                           Enable or disable file JSON logging.
                           [default: log-file-json-enable]
     --log-file FILE        The log file to write to.  [default: this.log]
     --log-level [critical|error|warning|info|debug|notset]
                           Select logging level to apply to all enabled
                           log sinks.  [default: warning]

If you don't like the ``click-logging-config`` internal defaults for the options
you can define your own. The ``LoggingConfiguration`` class is derived from
``pydantic.BaseModel``, so one easy way to define your defaults is using a
dictionary. You only need to define values to want to change - any other value
will continue using the internal defaults.

.. code-block::

   import pathlib

   import click
   import logging
   from click_logging import logging_parameters, LoggingConfiguration

   log = logging.getLogger(__name__)

   MY_LOGGING_DEFAULTS = LoggingConfiguration.parse_obj(
       {
           "file_logging": {
               # NOTE: file path must be specified using pathlib.Path
               "log_file_path": pathlib.Path("some_other.log"),
           },
           "log_level": "info",
       }
   )

   def do_something()
       pass

   @click.command()
   @click.option("--my-option", type=str)
   @logging_parameters(MY_LOGGING_DEFAULTS)
   def my_command(my_option: str) -> None:
       log.info("doing something")
       try:
           do_something(my_option)
       except Exception as e:
           log.critical(f"something bad happened, {str(e)}")
           raise


Review the ``LoggingConfiguration`` `class definition <https://gitlab.com/ci-cd-devops/click_logging_config/-/blob/main/click_logging_config/_logging.py#L52>`_
to understand all the default configuration parameters available.
