Metadata-Version: 2.4
Name: liplog
Version: 0.3.0
Summary: Python helpers to create a log file in the script folder and display it in the terminal
Author: Robert Lippert
License-Expression: MIT
Project-URL: Homepage, https://github.com/R0g3rT/liplog
Project-URL: Repository, https://github.com/R0g3rT/liplog
Project-URL: Issues, https://github.com/R0g3rT/liplog/issues
Keywords: log,logging,terminal,file,liplog
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Liplog

A simple Python logging package that writes a log file next to your script while also printing messages to the console.

## Language

- [README German](README-de.md)

## Features

- Log folder and timestamped log file are created automatically on the first log entry
- Colored console output in real time
- Custom levels `RUN` and `SUCCESS`
- No changes to the root logger, so your own `logging` setup stays untouched

## Requirements

- Python 3.9 or newer

## Installation

Install from PyPI:

```bash
python -m pip install liplog
```

Install directly from GitHub:

```bash
python -m pip install git+https://github.com/R0g3rT/liplog.git
```

Update:

```bash
python -m pip install --upgrade liplog
```

Uninstall:

```bash
python -m pip uninstall liplog
```

## Usage

```python
from liplog import write_log

write_log("Script started", "RUN")
write_log("Ticket loaded")  # default level: INFO
write_log("Important warning", "WARNING")
write_log("An error occurred", "ERROR")
write_log("Done", "SUCCESS")
```

Sample output:

```text
[2026-09-14 12:00:00] [RUN] Script started
[2026-09-14 12:00:00] [INFO] Ticket loaded
[2026-09-14 12:00:01] [WARNING] Important warning
[2026-09-14 12:00:02] [ERROR] An error occurred
[2026-09-14 12:00:03] [SUCCESS] Done
```

Custom log file name (optional, call before the first `write_log`):

```python
from liplog import setup_logging, write_log

log_file = setup_logging("monthly-report")
write_log(f"Logging to {log_file}")
```

## Supported Log Levels

| Level      | Console color |
|------------|---------------|
| `DEBUG`    | default       |
| `RUN`      | blue          |
| `INFO`     | default       |
| `SUCCESS`  | green         |
| `WARNING`  | yellow        |
| `ERROR`    | red           |
| `CRITICAL` | magenta       |

Levels are case-insensitive. An unknown level (e.g. a typo) raises a `ValueError`.

## Note

The log file is saved in `logs/<script>/` next to the script that was executed, named `<script>-YYYY-MM-DD_HH-MM.log`.
With `setup_logging("name")` only the file name changes: `logs/<script>/name-YYYY-MM-DD_HH-MM.log`.

```text
mailbot.py
logs/
└── mailbot/
    ├── mailbot-2026-11-04_08-30.log
    └── monthly-report-2026-11-04_08-31.log
```

Console output goes to stdout.

## Changes in 0.3.0

- Log files are stored per script in `logs/<script>/` (previously directly in `logs/`)
- `DEBUG` messages are logged
- Console output goes to stdout (previously stderr)

## Changes in 0.2.0

- Nothing is created on import; folder and file are created on the first log entry
- `RUN` and `SUCCESS` are real log levels (15 and 25)
- Unknown levels raise `ValueError` instead of being logged as `INFO`
- `setup_logging` is exported; `retries` and `delay_ms` were removed from `write_log`
- Requires Python 3.9 or newer
