Metadata-Version: 2.4
Name: basecmd
Version: 0.1.10
Summary: Logging boilerplate for the command line
Author: dnknth
License-Expression: MIT
Project-URL: Repository, https://github.com/dnknth/basecmd
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: ansicolors
Requires-Dist: python-decouple
Dynamic: license-file

# basecmd

Logging boilerplate for the command line.

Classes inheriting from `BaseCmd` get a `self.log` attribute — a standard
Python `logging.Logger` — pre-configured to `sys.stdout` with color support
when logging to a terminal.

## Quick start

```python
from basecmd import BaseCmd


class MyCmd(BaseCmd):
    "Demo command"

    def add_arguments(self):
        self.parser.add_argument("--foo", help="Custom option")

    def __call__(self):
        self.log.debug("options: %s", self.options)


if __name__ == "__main__":
    cmd = MyCmd()
    cmd()
```

Run with `-h` / `--help` to see the built-in logging options:

```
usage: __main__.py [-h] [-v {error,warning,info,debug}] [--log-file LOG_FILE]
                   [--foo FOO]
```

## CLI options

`BaseCmd` registers two logging options on the parser; subclasses add their own
via `add_arguments`:

| Flag | Description |
|---|---|
| `-v`, `--verbosity` | Logging verbosity: `error`, `warning`, `info`, `debug` |
| `--log-file` | Path to a log file; logs to stdout when unset |

After parsing, `self.options` holds the parsed arguments and `self.parser` the
`ArgumentParser` used to build them.

## Configuration

Defaults can be set via environment variables or a `.env` file. These are read
once when the module is imported, so set them before importing `BaseCmd`:

| Variable | Description | Default |
|---|---|---|
| `LOG_LEVEL` | Logging verbosity: `error`, `warning`, `info`, or `debug` | `info` |
| `LOG_FILE` | Path to a log file; stdout when unset | `None` (stdout) |
| `LOG_FORMAT` | Python `logging` format string | unset → `%(asctime).19s  %(message)s` |
