ezplog 1.5.3

Modern Python logging framework with Rich console output and loguru file logging, featuring advanced display capabilities, configuration management, and a simple typed API.

🚀 Ezpl

Ezpl is a modern Python logging framework with Rich console output and loguru file logging, featuring advanced display capabilities, configuration management, and a simple typed API suitable for professional and industrial applications.

📦 Installation

pip install ezpl

Or from source:

git clone https://github.com/neuraaak/ezplog.git
cd ezpl && pip install .

🚀 Quick Start

from ezpl import Ezpl

# Initialize
ezpl = Ezpl(log_file="app.log")
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: Beautiful formatting with colors, panels, tables, and progress bars
• ✅ File Logging: Structured logs with rotation, retention, and compression
• ✅ RichWizard: Advanced display capabilities (panels, tables, JSON, dynamic progress bars)
• ✅ Configuration Management: JSON config, environment variables, and runtime configuration
• ✅ CLI Tools: Command-line interface for logs, config, and statistics
• ✅ Full Type Hints: Complete typing support for IDEs and linters
• ✅ Robust Error Handling: Never crashes, even with problematic input

📚 Documentation

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

Section	Description
Getting Started	Installation, basic usage, and first steps
API Reference	Complete API documentation with examples
CLI Reference	Command-line interface guide
User Guides	Configuration, development, and testing guides
Examples	Practical examples and demonstrations

🧪 Testing

Comprehensive test suite with 377 tests covering unit, integration, and robustness scenarios — 65% code coverage.

Metric	Value
Total tests	377
Passing	377 (100%)
Coverage	65%
Test types	Unit, Integration, Robustness

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest tests/

# Run specific test types
python tests/run_tests.py --type unit
python tests/run_tests.py --type integration
python tests/run_tests.py --type robustness

# With coverage
python tests/run_tests.py --coverage

See Testing Guide for complete details.

🛠️ Development Setup

For contributors and developers:

# Install in development mode with all dependencies
pip install -e ".[dev]"

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

# Install Git hooks (auto-formatting, auto-tagging)
# Linux/macOS:
./.hooks/install.sh

# Windows:
.hooks\install.bat

# Or manually:
git config core.hooksPath .hooks

Git Hooks:

• pre-commit: Automatically formats code (black, isort, ruff) before commit
• post-commit: Automatically creates version tags after commit

See Development Guide and .hooks/README.md for detailed hook documentation.

🎨 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 ezpl import Ezpl, Printer, Logger

ezpl = Ezpl()
printer: Printer = ezpl.get_printer()
logger: Logger = ezpl.get_logger()

# Console methods
printer.info(), printer.success(), printer.warning(), printer.error()
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()

# Configuration
ezpl.set_level("DEBUG")
ezpl.configure(log_rotation="10 MB", log_retention="7 days")

🛡️ 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

---

Ezpl – Modern, typed, robust and beautiful logging for Python. 🚀