Metadata-Version: 2.4
Name: prettylogx
Version: 0.1.0
Summary: Beautiful, production-ready Python logging with colors and JSON output
Author-email: Rupesh Shinde <shinderupesh7896@gmail.com>
License-Expression: MIT
Keywords: logging,colorlog,json,structured-logging,pretty
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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: Topic :: System :: Logging
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

# prettylogx

**Beautiful, production-ready Python logging — zero external dependencies.**

prettylogx wraps Python's built-in `logging` module and gives you:

- Colored, human-readable logs for your terminal
- Structured JSON logs for production log shippers
- Automatic request ID tracing (per-thread)
- Clean exception / traceback output
- Custom log levels (`VERBOSE`, `SUCCESS`)
- A single function — `setup_logger()` — to set it all up

---

## Installation (local development)

```bash
# 1. Clone the repo
git clone https://github.com/yourusername/prettylogx.git
cd prettylogx

# 2. Create and activate a virtual environment
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS / Linux:
source .venv/bin/activate

# 3. Install in editable mode (changes to source take effect immediately)
pip install -e ".[dev]"
```

---

## Quick start

```python
from prettylogx import setup_logger

logger = setup_logger("my-app")

logger.info("Server started on port 8000")
logger.warning("Database response time is high")
logger.error("Payment failed for order #9921")
```

Terminal output:

```
2024-01-15 10:30:45 | INFO     | my-app | Server started on port 8000
2024-01-15 10:30:46 | WARNING  | my-app | Database response time is high
2024-01-15 10:30:47 | ERROR    | my-app | Payment failed for order #9921
```

Each level is printed in its own color (green / yellow / red / etc.).

---

## Colored logs (terminal)

```python
from prettylogx import setup_logger

logger = setup_logger(
    name="my-app",
    level="DEBUG",       # show all levels including DEBUG
    show_time=True,      # include timestamp (default: True)
    show_file=True,      # include filename:lineno
    use_colors=True,     # ANSI colors (default: True)
)

logger.debug("Connecting to DB")
logger.info("User logged in")
logger.warning("Rate limit at 80%")
logger.error("Auth token expired")
logger.critical("Service unreachable")
```

---

## JSON logs (production)

Switch to JSON output by passing `json_logs=True`. Every line is a
self-contained JSON object you can pipe to `jq` or ship to Datadog / Loki /
CloudWatch.

```python
from prettylogx import setup_logger

logger = setup_logger("api", json_logs=True)

logger.info("Request received")
logger.error("DB connection refused")
```

Output:

```json
{"timestamp": "2024-01-15T10:30:45Z", "level": "INFO", "logger": "api", "message": "Request received", "module": "app", "function": "handle", "line": 12}
{"timestamp": "2024-01-15T10:30:46Z", "level": "ERROR", "logger": "api", "message": "DB connection refused", "module": "app", "function": "connect", "line": 34}
```

---

## Request ID tracing

Track a single request across many log lines without passing the ID to every
function.

```python
from prettylogx import setup_logger, set_request_id, clear_request_id

logger = setup_logger("api")

# At the start of a request:
set_request_id("req-abc123")

logger.info("Validating input")     # → includes [req-abc123]
logger.info("Querying database")    # → includes [req-abc123]
logger.info("Returning response")   # → includes [req-abc123]

# At the end of the request:
clear_request_id()
```

Or pass it explicitly per call:

```python
logger.info("Order placed", extra={"request_id": "req-xyz"})
```

---

## Exception logging

```python
from prettylogx import setup_logger

logger = setup_logger("app")

try:
    result = 1 / 0
except ZeroDivisionError:
    logger.exception("Unexpected error in calculation")
```

The full traceback is captured and formatted cleanly below the log line.
In JSON mode it appears as the `"exception"` field.

---

## setup_logger() parameters

| Parameter   | Type       | Default   | Description                                      |
|-------------|------------|-----------|--------------------------------------------------|
| `name`      | `str`      | `"app"`   | Logger name shown in every log line              |
| `level`     | `str\|int` | `"INFO"`  | Minimum level: DEBUG / INFO / WARNING / ERROR / CRITICAL |
| `json_logs` | `bool`     | `False`   | `True` → JSON output, `False` → colored output  |
| `show_time` | `bool`     | `True`    | Include timestamp in colored output              |
| `show_file` | `bool`     | `False`   | Include `filename:lineno` in colored output      |
| `use_colors`| `bool`     | `True`    | `False` strips ANSI codes (e.g. for file output) |

---

## Why not just use the raw `logging` module?

| Feature                  | `logging` | prettylogx |
|--------------------------|:---------:|:----------:|
| Colored terminal output  | No        | Yes        |
| JSON / structured output | No        | Yes        |
| Request ID tracing       | Manual    | Built-in   |
| Zero-config setup        | No        | Yes        |
| No external dependencies | Yes       | Yes        |
| Works with existing code | —         | Yes        |

prettylogx is a thin wrapper — you can still use every standard `logging`
feature (handlers, filters, log levels) alongside it.

---

## Running locally

```bash
# Run examples
python examples/basic_usage.py
python examples/json_logs.py
python examples/request_id.py
python examples/exception_logging.py

# Run tests
pytest

# Run tests with coverage report
pytest --cov=prettylogx --cov-report=term-missing

# Build the distributable package
pip install build
python -m build
# → creates dist/prettylogx-0.1.0.tar.gz and dist/prettylogx-0.1.0-py3-none-any.whl
```

---

## Roadmap

- [ ] File handler support (write logs to a rotating file)
- [ ] Async support (`asyncio`-safe context variables via `contextvars`)
- [ ] Middleware helpers for FastAPI / Django / Flask
- [ ] Log sampling (emit only N% of DEBUG logs in production)
- [ ] PyPI publication
