chronilog 0.1.1

A clean, customizable logging package with rich formatting, diagnostics, and rotating file output.

🪵 Chronilog

Chronilog is a clean, configurable, and developer-friendly logging package for Python. It provides rich terminal output, rotating file logging, diagnostics, and full environment-based customization — all in a zero-hassle API.

Designed for real-world projects that need stability, structure, and style in their logs.

---

🚀 Features

• ✅ ChroniLog(name) — powerful, configurable logger instance
• 🎨 Rich console output with emoji support
• 📁 Rotating file logs (configurable via .env or .toml)
• ⚙️ Environment + TOML-based configuration layering
• 🧪 Built-in diagnostics system (print_diagnostics())
• 🔄 Optional JSON logging
• 🧰 Developer-first: testable, extensible, and production-ready

---

📦 Installation

pip install -e .

Clone this repo and install it locally in editable mode during development.

🧠 Basic Usage

from chronilog import ChroniLog

log = ChroniLog("my_app")

log.info("🚀 App started")
log.warning("⚠️ Something might be wrong...")
log.error("❌ An error occurred!")

---

⚙️ Configuration Options

Chronilog supports config from 3 layers:

.env file

.chronilog.toml file

Built-in defaults

🔧 Example .env

CHRONILOG_LOG_PATH=logs/my_app.log
CHRONILOG_LOG_LEVEL=DEBUG
CHRONILOG_LOG_MAX_MB=5
CHRONILOG_LOG_BACKUP_COUNT=3
CHRONILOG_JSON=0

---

🧪 Diagnostic Mode

from chronilog.diagnostics import print_diagnostics

print_diagnostics()

You’ll get a Rich-powered terminal table showing logger status and any setup issues.

---

✨ Customizing ChroniLog

You can override behavior with optional arguments:

from chronilog import ChroniLog
from chronilog.core.formatter import PlainFormatter

log = ChroniLog(
    name="myapp",
    level=logging.INFO,
    file_formatter=PlainFormatter(),
    use_cache=False
)

---

🔎 Parameters

Argument	Type	Description
name	str	Logger name (typically __name__)
level	int (optional)	Custom log level (logging.DEBUG, etc)
console_formatter	Formatter	Optional override for console formatter
file_formatter	Formatter	Optional override for file formatter
use_cache	bool	Whether to reuse existing logger by name

📁 Default Log Paths

Automatically chooses safe OS-specific defaults:

• 🪟 Windows → %LOCALAPPDATA%/chronilog/logs/

• 🍎 macOS → ~/Library/Logs/chronilog/

• 🐧 Linux → ~/.local/share/chronilog/logs/

🧪 Example Project Structure

myapp/
├── main.py
├── .env
├── logs/
│   └── chronilog.log
└── requirements.txt

---

🧪 Example: test_app.py

from chronilog import ChroniLog

log = ChroniLog("test_app")

log.info("🚀 Startup")
log.debug("🔧 Debugging")
log.warning("⚠️ Warning issued")
log.error("❌ Error occurred")
log.critical("🔥 Critical failure")

---

🧪 Testing

pytest tests/

Or run the built-in usage script:

python examples/usage.py

---

📜 License

MIT License — free to use, modify, and contribute.

💡 Coming Soon

chronilog diagnostics CLI tool

JSON log viewer + filter

Async logging support

Release to PyPI (pip install chronilog)

---

🙌 Credits

Built with ❤️ by [Brandon McKinney]

Inspired by clean logging practices at scale.