Metadata-Version: 2.5
Name: sootra
Version: 1.0.4
Summary: Sootra - Tracking your heartbeat with colors. Fast, colorful, structured JSON logging with async Request-ID tracing for Python & FastAPI.
Author-email: Dev Raj Khadka <devrajkhadka941@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ansi-color,fastapi,json-logging,logging,request-id,sootra,starlette,structured-logging,tracing
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: System :: Logging
Requires-Python: >=3.10
Requires-Dist: starlette>=0.27.0
Description-Content-Type: text/markdown

# Sootra 🧵✨

[![PyPI Version](https://img.shields.io/pypi/v/sootra.svg)](https://pypi.org/project/sootra/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)

> **Sootra v1.0.4 (Codename: AAYU)** — *Tracking your heartbeat with colors.*  
> A modern, high-performance logging & tracing library for **Python, FastAPI, Django, Flask, & Scripts** with **ANSI color formatting**, **custom levels (`SUCCESS`, `TRACE`)**, **structured JSON lines output**, and **automatic async `Request-ID` context tracing**.

---

## ✨ Features

- 🎨 **Rich ANSI Color Formatting:** Beautiful colored console logs (Cyan for `DEBUG`, Blue for `INFO`, Green for `SUCCESS`, Yellow for `WARNING`, Red for `ERROR`).
- 🟢 **Custom `SUCCESS` Level (Level 25):** Highlight successful operations in green (`logger.success("Payment verified")`).
- 🔍 **Async Request-ID Tracing:** Automatically propagates `request_id` across async tasks via `ContextVar` without passing `extra={}` everywhere.
- 📦 **Structured JSON Output:** Formats logs as newline-delimited JSON with ISO UTC timestamps and full exception traces for Datadog, Loki, CloudWatch, and Elasticsearch.
- ⚡ **FastAPI & ASGI Middlewares:** Built-in `add_sootra_middlewares(app)` to log request latency and status codes.
- 🔄 **Cached & Zero Boilerplate:** Import `from sootra import logger` and start logging immediately anywhere in Python.

---

## 🚀 Installation

```bash
# Using pip
pip install sootra

# Using uv
uv add sootra
```

---

## 💡 Quickstart (FastAPI)

```python
from fastapi import FastAPI
from sootra import add_sootra_middlewares, logger

app = FastAPI(title="My API")

# 1. Enable automatic Request-ID and HTTP Access Logging
add_sootra_middlewares(app)

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    # Logs with colored level and automatic [req=UUID] trace!
    logger.info(f"Looking up user {user_id}")
    
    # Custom green SUCCESS log
    logger.success(f"User {user_id} found")
    
    return {"id": user_id, "name": "Alex"}
```

**Terminal Output (HTTP Request):**
```text
2026-08-15 19:30:00 INFO    [app]    [req=9b1d7f82-a0e2-45a1] Looking up user 42
2026-08-15 19:30:00 SUCCESS [app]    [req=9b1d7f82-a0e2-45a1] User 42 found
2026-08-15 19:30:00 INFO    [access] [req=9b1d7f82-a0e2-45a1] GET /users/42 - 200 (1.45ms)
```

**Terminal Output (Startup / CLI / Pure Python - Clean without `[req=-]`):**
```text
2026-08-15 19:30:00 INFO    [app] Starting Server
```

---

## 🐍 Universal Python Usage (Django, Flask, Celery, Scripts)

Sootra works seamlessly anywhere in pure Python without needing FastAPI:

```python
# script.py or celery_worker.py
from sootra import logger

logger.info("Processing daily transactions...")
logger.success("Processed 10,000 orders successfully!")
```

---

## 🛠️ Log Levels & Methods

| Level | Method | Console Color | Use Case |
| :--- | :--- | :--- | :--- |
| **`TRACE`** (5) | `logger.trace(...)` | Gray / Dim | Low-level internal execution details |
| **`DEBUG`** (10) | `logger.debug(...)` | Cyan | Development debugging & diagnostic info |
| **`INFO`** (20) | `logger.info(...)` | Blue | Standard system events |
| **`SUCCESS`** (25) | `logger.success(...)` | **Green** | Successful milestone / business operation |
| **`WARNING`** (30) | `logger.warning(...)` | Yellow | Recoverable anomalies or deprecated usage |
| **`ERROR`** (40) | `logger.error(...)` | Red | Errors and failures |
| **`CRITICAL`** (50) | `logger.critical(...)` | Magenta | Critical system failures |
| **`EXCEPTION`** (40) | `logger.exception(...)`| Red + Traceback | Catches and logs active Python exception |

---

## 📦 Dual Stream: Console Colors + Structured JSON Files

By setting `log_file="logs/app.log"` or the environment variable `LOG_FILE_PATH="logs/app.log"`:
* **Console:** Pretty ANSI colored logs for developers in the terminal.
* **File:** Machine-readable JSON Lines for production log aggregation (Datadog/Loki):

```python
from sootra import configure_logger

logger = configure_logger(
    name="my_service",
    log_file="logs/app.log", # Saves structured JSON
)
```

**File JSON format (`logs/app.log`):**
```json
{
  "timestamp": "2026-08-15T19:30:00.123456+00:00",
  "level": "SUCCESS",
  "logger": "my_service",
  "request_id": "9b1d7f82-a0e2-45a1",
  "message": "Payment verified"
}
```

---

## 🏷️ Version Metadata

```python
import sootra

print(sootra.__version__)   # "1.0.4"
print(sootra.__codename__)  # "AAYU"
```

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).
