Metadata-Version: 2.4
Name: lucid-logger
Version: 0.1.0
Summary: Python logging library with color output, progress bars, and spinners
Author-email: Kevin Lago <kevinthelago@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Kevin-Lago/LucidLogger
Project-URL: Bug Tracker, https://github.com/Kevin-Lago/LucidLogger/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"

# LucidLogger

A Python library for standardized terminal logging with ANSI color support, progress bars, spinners, and timed rotating file output.

---

## Features

- Colored log output per level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
- Custom log levels with configurable colors
- Inline progress/loading bars that coexist with log output
- Indeterminate spinner for operations with unknown duration
- Auto-resizing progress bars based on terminal width
- Cross-platform (Windows CMD, PowerShell, Bash)
- Timed rotating file handler with dated filenames
- File logs strip ANSI — clean output for log aggregators

---

## Installation

```bash
pip install lucid-logger
```

---

## Quick Start

```python
from lucid_logger import get_logger

logger = get_logger("app")
logger.info("Server started")
logger.warning("High memory usage")
logger.error("Failed to connect")
```

`get_logger` creates a `LucidLogger` with a colored stream handler and a timed rotating file handler in one call.

### With a Progress Bar (wrap)

```python
from lucid_logger import get_logger, LucidLoadingBar

logger = get_logger("app")
bar = LucidLoadingBar(name="import")
logger.add_loading_bar(bar)

for item in bar.wrap(items, prefix="Importing"):
    process(item)
    logger.info(f"Processed {item}")
```

### With a Spinner

```python
from lucid_logger import get_logger, LucidSpinner

logger = get_logger("app")
spinner = LucidSpinner(name="fetch", prefix="Fetching data")
logger.add_spinner(spinner)

with spinner:
    result = requests.get(url)

logger.info("Fetch complete")
```

### Manual setup (advanced)

```python
from lucid_logger import LucidLogger

logger = LucidLogger(name="app", log_lowest_level=10, colored_logs=True)
logger.basic_config()
```

---

## API Reference

### `get_logger(name, ...)`

Factory function — the recommended way to create a logger.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `name` | `str` | — | Logger name |
| `level` | `int` | `logging.DEBUG` | Minimum log level |
| `colored` | `bool` | `True` | Enable ANSI color on stream output |
| `log_dir` | `str` | `'./logs/'` | Directory for rotating log files |
| `stream` | `bool` | `True` | Attach a stream handler to stdout |
| `file` | `bool` | `True` | Attach a rotating file handler |

---

### `LucidLogger`

Extends `logging.Logger`.

| Parameter | Type | Description |
|---|---|---|
| `name` | `str` | Logger name |
| `log_lowest_level` | `int` | Minimum log level (e.g. `10` = DEBUG) |
| `colored_logs` | `bool` | Enable ANSI color output |

**Methods:**

| Method | Description |
|---|---|
| `basic_config()` | Attach default stream and file handlers |
| `add_loading_bar(bar)` | Register a `LucidLoadingBar` with the stream handler |
| `get_loading_bar(name)` | Retrieve a registered bar by name |
| `add_spinner(spinner)` | Register a `LucidSpinner` with the stream handler |
| `add_logging_level(level_name, level_num, color)` | Register a custom log level with a color |

---

### `LucidLoadingBar`

A terminal progress bar that renders inline with log output.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `name` | `str` | — | Unique identifier |
| `iterable` | `iterable` | `None` | Collection to iterate over |
| `prefix` | `str` | `'Loading...'` | Label shown before the bar |
| `suffix` | `str` | `''` | Label shown after the bar |
| `colored_logs` | `bool` | `True` | Enable ANSI color |
| `fill` | `str` | `█` | Fill character |
| `decimals` | `int` | `1` | Decimal places on the percent |
| `length` | `int` | `100` | Bar width in characters |

**Methods:**

| Method | Description |
|---|---|
| `init_bar(iterable, prefix, total)` | Start the bar, auto-sizes to terminal width |
| `wrap(iterable, prefix)` | Iterate over `iterable` while auto-advancing the bar |
| `progress_bar()` | Advance progress by one step |
| `finish_loading()` | Mark the bar complete and clear it |
| `get_bar()` | Return the current formatted bar string |

---

### `LucidSpinner`

An indeterminate progress indicator that animates in place on a background thread. Log output from `LucidLogger` will pause the spinner frame, write the log line, then let the spinner resume — no interleaving.

Uses Unicode braille frames (`⠋ ⠙ ⠹ …`) where supported, falls back to ASCII (`| / - \`).

| Parameter | Type | Default | Description |
|---|---|---|---|
| `name` | `str` | — | Unique identifier |
| `prefix` | `str` | `''` | Label shown before the spinner frame |
| `colored_logs` | `bool` | `True` | Enable ANSI color |
| `color` | `str` | `grey` | ANSI escape string for the spinner color |
| `interval` | `float` | `0.1` | Seconds between frame advances |

**Methods:**

| Method | Description |
|---|---|
| `start()` | Begin animation on a daemon thread |
| `stop()` | Stop animation, clear the line, join the thread |
| `__enter__` / `__exit__` | Use as a context manager |

---

### `LucidStreamFormatter`

Custom `logging.Formatter` that injects ANSI color codes per log level.

Levels below `detailed_view_threshold` omit the filename/line number from the output to keep routine logs terse. Warnings and above include the source location.

---

### `LucidTimedRotatingFileHandler`

Extends `TimedRotatingFileHandler`. Rotates at midnight and names files by date (`YYYY-MM-DD.log`). Creates the log directory automatically if it does not exist.

| Parameter | Default | Description |
|---|---|---|
| `directory` | `'./logs/'` | Output directory |
| `when` | `'midnight'` | Rotation schedule |
| `file_extension` | `'log'` | File extension |

---

## Color Reference

Built-in named colors available for custom levels and bar/spinner segments:

| Name | Hex |
|---|---|
| `grey` | `#C8C8C8` |
| `white` | `#FFFFFF` |
| `red` | `#FF0000` |
| `yellow` | `#FFFF00` |
| `green` | `#009600` |
| `lime` | `#00FF00` |
| `cyan` | `#00FFFF` |
| `blue` | `#0000FF` |
| `purple` | `#000096` |

---

## Custom Log Levels

```python
from lucid_logger import get_logger, cyan

logger = get_logger("app")
logger.add_logging_level("TRACE", 5, cyan)
logger.trace("Entering request handler")
```

---

## Log Output Format

Stream (colored):
```
[MM/DD/YYYY HH:MM:SS][LEVEL] message
[MM/DD/YYYY HH:MM:SS][WARNING][filename.py:42] message
```

File (plain):
```
[MM/DD/YYYY HH:MM:SS][INFO] message
[MM/DD/YYYY HH:MM:SS][ERROR][filename.py:42] message
```

---

## License

MIT
