aizenx 0.1.3

Stylish console logger with colors, spinner, and progress

aizenx

A stylish, production-ready Python console & file logger with colors, spinners, progress bars, and more.

---

Installation

# Without colors (zero dependencies)
pip install aizenx

# With color support (recommended)
pip install aizenx[colors]

---

Quick Start

from aizenx import log

log.info("Application started")
log.success("Connected to database", "postgres://localhost/mydb")
log.warning("Cache miss rate is high", "redis")
log.error("Request failed", "api.example.com")
log.critical("Out of memory!")

---

Features

Feature	Description
9 log levels	DEBUG, INFO, SUCCESS, WARNING, ERROR, CRITICAL, WAIT, DONE, INPUT
Level filtering	Only emit records at or above a configured minimum level
File logging	Auto-rotating log files via RotatingFileHandler
JSON mode	Structured JSON output for log aggregators (ELK, Loki, etc.)
Webhook alerts	HTTP POST to a URL when ERROR/CRITICAL events fire
Thread safety	All console writes go through a threading.Lock
Spinner	Animated spinner context manager for long operations
Progress bar	ASCII in-place progress bar
Banners & headers	Styled section breaks and title blocks
Interactive prompts	input(), confirm(), choice() with consistent styling
Colorama optional	Works without colorama – no crash, just no ANSI colors

---

Usage Examples

Basic logging

from aizenx import log

log.debug("Cache lookup", "users:42")
log.info("Server listening on :8080")
log.success("Payment processed", "order_9921")
log.warning("Retrying in 5 s", "smtp.mailer")
log.error("DB write failed", "orders_table")
log.critical("Filesystem full!")

Custom Logger instance

from aizenx import Logger

log = Logger(
    level="INFO",           # filter out DEBUG records
    log_file="app.log",     # write to rotating file
    use_colors=True,        # False for plain text
    show_timestamp=True,
    show_level=True,
    json_mode=False,        # True → every line is a JSON object
    max_bytes=10_000_000,   # 10 MB per log file
    backup_count=5,
    webhook_url="https://hooks.slack.com/...",  # optional
    webhook_level="ERROR",  # minimum level to trigger webhook
)

log.success("Logger configured", "app")

JSON mode (for log aggregators)

from aizenx import Logger

log = Logger(json_mode=True)
log.info("user login", "auth")
# → {"timestamp": "2024-01-15T10:23:45.123456", "level": "INFO", "message": "user login", "context": "auth"}

Spinner (async indicator)

from aizenx import log
import time

with log.spinner("Fetching data from API", "github"):
    time.sleep(2)           # your blocking work here
# → spinner animates, then prints SUCCESS line on exit

Progress bar

from aizenx import log
import time

for i in range(101):
    log.progress(i, 100, "Uploading")
    time.sleep(0.02)

Banners and headers

log.header("MY APP", "v2.0.1 — production")
log.section("Database migrations")
log.banner(["Status: ONLINE", "Uptime: 3d 4h 12m"])

Interactive prompts

name = log.input("Enter your username")
if log.confirm("Enable verbose mode?", default=False):
    log.info("Verbose mode ON")

idx = log.choice("Select environment", ["development", "staging", "production"], default=2)

Webhook alerts

log = Logger(
    webhook_url="https://hooks.slack.com/services/T.../B.../xxx",
    webhook_level="ERROR",   # fires for ERROR and CRITICAL
)
log.error("Payment gateway timeout", "stripe")
# → silently POSTs JSON payload in a background thread

---

API Reference

Logger(...) constructor

Parameter	Type	Default	Description
level	str	"DEBUG"	Minimum log level to emit
log_file	str | None	None	Path to rotating log file
use_colors	bool	True	Enable ANSI colors (requires colorama)
show_timestamp	bool	True	Prepend HH:MM:SS.mmm to each line
show_level	bool	True	Show level badge
json_mode	bool	False	Output structured JSON instead of text
max_bytes	int	5_242_880	Max log file size before rotation
backup_count	int	3	Number of backup files to keep
webhook_url	str | None	None	HTTP endpoint for alert POSTs
webhook_level	str	"ERROR"	Minimum level to fire webhook

Level priority (for filtering)

DEBUG(10) < INFO(20) = SUCCESS(25) < WARNING(30) < ERROR(40) < CRITICAL(50)

---

License

MIT © aizenx contributors