click-logger 0.1.0
Configuares your logger configuration using click.
License: MIT

# Click-Logger

![GitHub Repo stars](https://img.shields.io/github/stars/rpkak/click-logger?label=GitHub%20stars&logo=github)
![PyPI - Downloads](https://img.shields.io/pypi/dm/click-logger?label=PyPI%20downloads&logo=pypi&logoColor=fff)

Click-Logger configurates your logger configuration using click.

## Simple example

foo.py:

```python
import logging

import click
import click_logger

logger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)


@click.command()
@click_logger.config(logger)
def foo():
    logger.debug('debug')
    logger.info('info')
    logger.warning('warn')
    logger.error('error')
    logger.critical('critical')


if __name__ == '__main__':
    foo()
```

Shell:

```bash
$ python foo.py
WARNING:__main__:warn
ERROR:__main__:error
CRITICAL:__main__:critical
$ python foo.py --verbose  # verbose
INFO:__main__:info
WARNING:__main__:warn
ERROR:__main__:error
CRITICAL:__main__:critical
$ python foo.py -vv  # double verbose
DEBUG:__main__:debug
INFO:__main__:info
WARNING:__main__:warn
ERROR:__main__:error
CRITICAL:__main__:critical
$ python foo.py --quiet  # quiet
CRITICAL:__main__:critical
```

## Installation

```bash
$ pip install git+https://github.com/rpkak/click-logger.git
```

## How it works


click-logger uses normal `click.option` decorators to create the `--verbose` and `--quiet` arg.

With these click-logger create a new `logging.Handler` instance which is optimized for click and
adds it to the `logging.Logger` instance you have to pass.

## Configuration

Because click-logger provides only one decorator function, every configuration is passed as arg
to this function.

### logger (type: `logging.Logger`, required):

The logger which can be modifiered by to cli.

### formatter (type: `str` or `logging.Formatter`, default: `logging.BASIC_FORMAT`):

The formatter which is used by the handler. If it is a string, a new formatter will be created
with this string.

### loglevel_mapping (type: `dict`, default: `click_logger.DEFAULT_LOGLEVEL_MAPPING`):

This is a dict, which keys are the logging levels of the logger (e.g. `logging.INFO`).

The values of the dict are either a tuple with two elements or a list with tuples with two elements each.

The first element is either a file to write to loggings to, `'out'` for stdout or `'err'` for stderr.

The second element is a number that describes which loggings will be written:

- If you use `-1`, the logs will be written every time. Even if you pass `--quiet`.
- If you use `0`, the logs will be written unless you pass `--quiet`.
- If you use any higher number `x`, the logs will be written if you pass `x` times `--verbose`.

  E.g. if you use `2`, the logs will be written if you pass `-vv`.

#### Examples:

`click_logger.DEFAULT_LOGLEVEL_MAPPING`:

```python
{
    logging.DEBUG: ('out', 2),     # Needs '-vv'
    logging.INFO: ('out', 1),      # Needs '-v'
    logging.WARNING: ('err', 0),   # Prevented by '-q'
    logging.ERROR: ('err', 0),     # Prevented by '-q'
    logging.CRITICAL: ('err', -1)  # Not prevented by '-q'
}
```

With logfile:

Same as `click_logger.DEFAULT_LOGLEVEL_MAPPING`, but writes every time everything to file.

```python
{
    logging.DEBUG: [('out', 2), (file, -1)],
    logging.INFO: [('out', 1), (file, -1)],
    logging.WARNING: [('err', 0), (file, -1)],
    logging.ERROR: [('err', 0), (file, -1)],
    logging.CRITICAL: [('err', -1), (file, -1)]
}
```

### verbose (type: `bool`, default: `True`)

Whether to enable the verbose flag or not.

### verbose_flags (type: `tuple` or `str`, default: `('--verbose', '-v')`)

The flags to enable verbose logging.

### verbose_help (type: `str`, default: `'Print verbose output.'`)

The message shown in `--help`.

### verbose_hidden (type: `bool`, default: `False`)

Whether verbose is shown in `--help`.

### verbose_envvar (type: `str` or `NoneType`, default: `None`)

Name of an enviroment variable which enables verbose logging without the flag.

#### Example:

in foo.py:

```python
@click_logger.config(logger, verbose_envvar='VERBOSE')
```

Shell:

```bash
$ VERBOSE=1 python foo.py 
INFO:__main__:info
WARNING:__main__:warn
ERROR:__main__:error
CRITICAL:__main__:critical
```

This only works with simple verbose.

### quiet (type: `bool`, default: `True`)

Whether to enable the quiet flag or not.

### quiet_flags (type: `tuple` or `str`, default: `('--quiet', '-q')`)

The flags to suppress logging.

### quiet_help (type: `str`, default: `'Suppress output.'`)

The message shown in `--help`.

### quiet_hidden (type: `bool`, default: `False`)

Whether quiet is shown in `--help`.

### quiet_envvar (type: `str` or `NoneType`, default: `None`)

Name of an enviroment variable which enables quiet logging without the flag.

#### Example:

in foo.py:

```python
@click_logger.config(logger, quiet_envvar='QUIET')
```

Shell:

```bash
$ QUIET=1 python foo.py
CRITICAL:__main__:critical
```