Ezplog

ezplog is a modern Python logging framework combining Rich console rendering and loguru file logging with an explicit app/lib compatibility model.

📦 Installation

# With uv (recommended)
uv add ezplog

# With pip
pip install ezplog

Or from source:

git clone https://github.com/neuraaak/ezplog.git
cd ezplog

uv pip install -e .   # uv
pip install -e .      # pip

🚀 Quick Start

from ezplog import Ezpl

# Initialize once in the application entrypoint
ezpl = Ezpl(log_file="app.log", hook_logger=True, hook_printer=True)
printer = ezpl.get_printer()
logger = ezpl.get_logger()

# Console output (Rich formatting)
printer.info("Information message")
printer.success("Operation completed!")
printer.warning("Warning message")

# File logging (loguru)
logger.info("Logged to file")

# Advanced features
printer.wizard.success_panel("Success", "Operation completed")
printer.wizard.table([{"Name": "Alice", "Age": 30}], title="Users")

🎯 Key Features

• ✅ Singleton Pattern: One global instance for the whole application
• ✅ Rich Console Output: Colors, panels, tables, JSON, and progress bars
• ✅ File Logging: Rotation, retention, and compression via loguru
• ✅ Explicit Compatibility Hooks: Fine control between app mode and lib mode
• ✅ Configuration Management: Arguments, environment variables, file, and runtime updates
• ✅ CLI Tools: Commands for logs and configuration
• ✅ Full Type Hints: Complete typing support for IDEs and linters
• ✅ Robust Fallbacks: Safe behavior even with problematic message objects

📚 Documentation

Complete documentation is available at neuraaak.github.io/ezplog

🧪 Testing

Comprehensive test suite covering unit, integration, and robustness scenarios. Coverage is generated automatically in documentation workflows.

# Install dev dependencies
uv sync --extra dev

# Run all tests
uv run pytest tests/

# Run specific test types
uv run pytest tests/unit/
uv run pytest tests/integration/
uv run pytest tests/robustness/

# With coverage
uv run pytest --cov=src/ezplog --cov-report=term --cov-report=html

See Testing Guide for complete details.

🛠️ Development Setup

For contributors and developers:

# Install in development mode with all dependencies
uv sync --extra dev --extra docs --extra test

# Install pre-commit hooks (code formatting, linting)
uv run pre-commit install

# Run quality checks
uv run ruff check src tests
uv run ty check

Source code uses a src/ layout (src/ezplog).

Git Hooks:

• pre-commit: Automatically formats and lints code before commit

See Development Guide for full details.

🎨 Main Components

• Ezpl: Singleton main class for centralized logging management
• EzPrinter (alias: Printer): Rich-based console output with pattern format
• EzLogger (alias: Logger): loguru-based file logging with rotation support
• RichWizard: Advanced Rich display (panels, tables, JSON, progress bars)
• ConfigurationManager: Centralized configuration management

📦 Dependencies

• rich>=13.0.0 – Beautiful console output and formatting
• loguru>=0.7.2 – Modern and powerful file logging
• click>=8.0.0 – CLI framework

🔧 Quick API Reference

from ezplog import Ezpl, Printer, Logger

ezpl = Ezpl(hook_logger=True, hook_printer=True)
printer: Printer = ezpl.get_printer()
logger: Logger = ezpl.get_logger()

# Console methods
printer.info(), printer.success(), printer.warning(), printer.error()
printer.trace(), printer.exception()
printer.tip(), printer.system(), printer.install()  # Pattern methods
printer.wizard.panel(), printer.wizard.table(), printer.wizard.json()

# File logging
logger.info(), logger.debug(), logger.warning(), logger.error()
logger.trace(), logger.exception()

# Configuration
ezpl.set_level("DEBUG")
ezpl.configure(log_rotation="10 MB", log_retention="7 days")
ezpl.set_compatibility_hooks(hook_logger=True, logger_names=["vendor.payment"])

💻 CLI Usage

The ezpl command provides tools for log inspection and configuration management.

# View recent log entries
ezpl logs view --lines 50

# Search for errors across log files
ezpl logs search --pattern "error|exception" --level ERROR

# Export logs to JSON
ezpl logs export --format json --output logs.json

# Read or update configuration
ezpl config get --show-env
ezpl config set log-level DEBUG

# Open the documentation site
ezpl docs

See the CLI Reference for the full command and option listing.

🛡️ Robustness

Ezpl is designed to never crash, even with problematic input:

• Automatic string conversion for non-string messages
• Robust error handling in formatters
• Safe handling of special characters and Unicode
• Graceful fallbacks for all error cases

📝 License

MIT License – See LICENSE file for details.

🔗 Links

• Documentation: https://neuraaak.github.io/ezplog/
• Repository: https://github.com/neuraaak/ezplog
• PyPI: https://pypi.org/project/ezplog/
• Issues: GitHub Issues

ezplog - Modern, typed, robust and beautiful logging for Python.