# logkaren

> A beautiful, colorful Python logging library by [karenhoyoshi](https://karenhoyoshi.asia)

[![PyPI version](https://img.shields.io/pypi/v/logkaren)](https://pypi.org/project/logkaren)
[![Python](https://img.shields.io/pypi/pyversions/logkaren)](https://pypi.org/project/logkaren)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## Installation

```bash
pip install logkaren
```

---

## Quick Start

```python
from logkaren import Logger, Loader, Home, LogLevel

# Default ColorLogger
log = Logger()
log.info("Server started on port 8080")
log.success("User logged in successfully")
log.warning("Disk usage above 80%")
log.error("Connection refused")
log.debug("Variable x = 42")

# With timing
import time
start = time.time()
time.sleep(0.5)
end = time.time()
log.success("Task done", start=start, end=end)

# Ask user input
name = log.question("What is your name? ")

# Critical — pauses and exits
log.critical("Fatal error occurred", exit_code=1)
```

---

## Logger Styles

### Style 1 — ColorLogger (default)

```python
log = Logger()           # or Logger(style=1)
```

Colorful output with pink prefix, magenta timestamps, and colored log levels.

### Style 2 — SimpleLogger

```python
log = Logger(style=2)
```

Clean minimal output — great for production or CI environments.

---

## Constructor Options

```python
Logger(
    style=1,                          # 1 = ColorLogger, 2 = SimpleLogger
    prefix="karenhoyoshi.asia",       # Custom prefix shown in brackets
    github_repository="github.com/karenhoyoshi/myproject",  # Shown on startup
    level=LogLevel.DEBUG,             # Minimum log level to display
    log_file="logs/app.log",          # Optional file to save logs
)
```

### Log Levels

| Level      | Value | Description                          |
|------------|-------|--------------------------------------|
| `DEBUG`    | 1     | Detailed debug information           |
| `INFO`     | 2     | General information                  |
| `WARNING`  | 3     | Something unexpected but non-fatal   |
| `SUCCESS`  | 4     | Operation completed successfully     |
| `FAILURE`  | 5     | Operation failed                     |
| `CRITICAL` | 6     | Fatal error — exits the program      |

```python
from logkaren import Logger, LogLevel

# Only show WARNING and above
log = Logger(level=LogLevel.WARNING)
```

---

## Loader

Animated terminal spinner for long-running tasks.

```python
from logkaren import Loader
import time

# As context manager (recommended)
with Loader(desc="Fetching data from API", end="Done fetching!"):
    time.sleep(3)

# Manual control
loader = Loader(desc="Processing files")
loader.start()
time.sleep(2)
loader.stop()
```

**Options:**

| Param     | Default              | Description                           |
|-----------|----------------------|---------------------------------------|
| `prefix`  | `karenhoyoshi.asia`  | Prefix shown in the spinner           |
| `desc`    | `Loading...`         | Description text next to the spinner  |
| `end`     | `\r`                 | Message shown when done (or `\r`)     |
| `timeout` | `0.1`                | Speed of animation (seconds per frame)|

---

## Home Screen

Display a styled ASCII banner at startup.

```python
from logkaren import Home

Home(
    title="MYAPP",
    subtitle="The coolest tool ever",
    credits="by karenhoyoshi",
    adinfo1="v2.0.0",
    adinfo2="github.com/karenhoyoshi/myapp",
    clear=True,   # Clear terminal before displaying
).display()
```

> Requires `pyfiglet` for the big ASCII title font (installed automatically).

---

## Logging to File

```python
log = Logger(log_file="logs/app.log")
log.info("This will be saved to file too")
```

ANSI color codes are automatically stripped from file output.

---

## License

MIT © [karenhoyoshi](https://karenhoyoshi.asia)
