ezplog 1.2.0__tar.gz

ezplog-1.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Neuraaak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ezplog-1.2.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: ezplog
+Version: 1.2.0
+Summary: Modern Python logging framework with Rich console output and loguru file logging, featuring advanced display capabilities, configuration management, and a simple typed API.
+Author: Neuraaak
+Maintainer: Neuraaak
+License: MIT
+Project-URL: Homepage, https://github.com/neuraaak/ezpl
+Project-URL: Repository, https://github.com/neuraaak/ezpl
+Keywords: logging,rich,loguru,console,file,framework,cli
+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: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: loguru>=0.7.2
+Requires-Dist: rich>=13.0.0
+Requires-Dist: click>=8.0.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Requires-Dist: bandit>=1.7.0; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Requires-Dist: pytest-mock>=3.10.0; extra == "test"
+Requires-Dist: pytest-xdist>=3.0.0; extra == "test"
+Dynamic: license-file
+
+# 🚀 Ezpl
+
+[![Python](https://img.shields.io/badge/Python-3.10%2B-blue?style=for-the-badge&logo=python)](https://www.python.org/)
+[![Platform](https://img.shields.io/badge/OS-Independent-lightgray?style=for-the-badge)](https://pypi.org/project/ezpl/)
+[![Version](https://img.shields.io/badge/Version-1.2.0-orange?style=for-the-badge)](https://github.com/neuraaak/ezpl)
+[![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](LICENSE)
+[![Status](https://img.shields.io/badge/Status-Production%20Ready-success?style=for-the-badge)](https://github.com/neuraaak/ezpl)
+[![Tests](https://img.shields.io/badge/Tests-200%2B%20passing-success?style=for-the-badge)](https://github.com/neuraaak/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
+
+```bash
+pip install ezpl
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/neuraaak/ezpl.git
+cd ezpl && pip install .
+```
+
+## 🚀 Quick Start
+
+```python
+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 API Documentation](docs/api/API_DOCUMENTATION.md)** – Full API reference with examples
+- **[📋 API Summary](docs/api/SUMMARY.md)** – Quick API overview
+- **[🖥️ CLI Documentation](docs/cli/CLI_DOCUMENTATION.md)** – Command-line interface guide
+- **[⚙️ Configuration Guide](docs/cli/CONFIG_GUIDE.md)** – Configuration management
+- **[💡 Examples](docs/examples/EXAMPLES.md)** – Usage examples and demonstrations
+- **[🧪 Test Documentation](docs/tests/TEST_DOCUMENTATION.md)** – Complete test suite documentation
+- **[📊 Test Summary](docs/tests/SUMMARY.md)** – Quick test overview
+
+## 🧪 Testing
+
+Comprehensive test suite with 200+ test cases covering unit, integration, and robustness scenarios.
+
+```bash
+# 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 **[Test Documentation](docs/tests/TEST_DOCUMENTATION.md)** for complete details.
+
+## 🛠️ Development Setup
+
+For contributors and developers:
+
+```bash
+# 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 **[.hooks/README.md](.hooks/README.md)** for detailed hook documentation.
+
+## 🎨 Main Components
+
+- **`Ezpl`**: Singleton main class for centralized logging management
+- **`Printer`** (ConsolePrinterWrapper): Rich-based console output with pattern format
+- **`FileLogger`**: 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
+
+```python
+from ezpl import Ezpl, Printer
+from loguru import 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](LICENSE) file for details.
+
+## 🔗 Links
+
+- **Repository**: [https://github.com/neuraaak/ezpl](https://github.com/neuraaak/ezpl)
+- **Issues**: [GitHub Issues](https://github.com/neuraaak/ezpl/issues)
+- **Documentation**: [Complete API Docs](docs/api/API_DOCUMENTATION.md)
+
+---
+
+**Ezpl** – Modern, typed, robust and beautiful logging for Python. 🚀

ezplog-1.2.0/README.md

@@ -0,0 +1,178 @@
+# 🚀 Ezpl
+
+[![Python](https://img.shields.io/badge/Python-3.10%2B-blue?style=for-the-badge&logo=python)](https://www.python.org/)
+[![Platform](https://img.shields.io/badge/OS-Independent-lightgray?style=for-the-badge)](https://pypi.org/project/ezpl/)
+[![Version](https://img.shields.io/badge/Version-1.2.0-orange?style=for-the-badge)](https://github.com/neuraaak/ezpl)
+[![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](LICENSE)
+[![Status](https://img.shields.io/badge/Status-Production%20Ready-success?style=for-the-badge)](https://github.com/neuraaak/ezpl)
+[![Tests](https://img.shields.io/badge/Tests-200%2B%20passing-success?style=for-the-badge)](https://github.com/neuraaak/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
+
+```bash
+pip install ezpl
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/neuraaak/ezpl.git
+cd ezpl && pip install .
+```
+
+## 🚀 Quick Start
+
+```python
+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 API Documentation](docs/api/API_DOCUMENTATION.md)** – Full API reference with examples
+- **[📋 API Summary](docs/api/SUMMARY.md)** – Quick API overview
+- **[🖥️ CLI Documentation](docs/cli/CLI_DOCUMENTATION.md)** – Command-line interface guide
+- **[⚙️ Configuration Guide](docs/cli/CONFIG_GUIDE.md)** – Configuration management
+- **[💡 Examples](docs/examples/EXAMPLES.md)** – Usage examples and demonstrations
+- **[🧪 Test Documentation](docs/tests/TEST_DOCUMENTATION.md)** – Complete test suite documentation
+- **[📊 Test Summary](docs/tests/SUMMARY.md)** – Quick test overview
+
+## 🧪 Testing
+
+Comprehensive test suite with 200+ test cases covering unit, integration, and robustness scenarios.
+
+```bash
+# 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 **[Test Documentation](docs/tests/TEST_DOCUMENTATION.md)** for complete details.
+
+## 🛠️ Development Setup
+
+For contributors and developers:
+
+```bash
+# 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 **[.hooks/README.md](.hooks/README.md)** for detailed hook documentation.
+
+## 🎨 Main Components
+
+- **`Ezpl`**: Singleton main class for centralized logging management
+- **`Printer`** (ConsolePrinterWrapper): Rich-based console output with pattern format
+- **`FileLogger`**: 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
+
+```python
+from ezpl import Ezpl, Printer
+from loguru import 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](LICENSE) file for details.
+
+## 🔗 Links
+
+- **Repository**: [https://github.com/neuraaak/ezpl](https://github.com/neuraaak/ezpl)
+- **Issues**: [GitHub Issues](https://github.com/neuraaak/ezpl/issues)
+- **Documentation**: [Complete API Docs](docs/api/API_DOCUMENTATION.md)
+
+---
+
+**Ezpl** – Modern, typed, robust and beautiful logging for Python. 🚀

ezplog-1.2.0/ezpl/__init__.py

@@ -0,0 +1,184 @@
+"""
+Ezpl - Modern Python logging framework.
+
+Ezpl is a modern Python library for advanced log management, using **Rich**
+for console output and **loguru** for file logging, with a simple and typed API,
+suitable for professional and industrial applications.
+
+**Main Features:**
+    - Singleton pattern for global logging instance
+    - Rich-based console output with colors and formatting
+    - Loguru-based file logging with rotation support
+    - Contextual indentation management
+    - Pattern-based logging (SUCCESS, ERROR, WARN, TIP, etc.)
+    - JSON display support
+    - Robust error handling
+
+**Quick Start:**
+    >>> from ezpl import Ezpl
+    >>> ezpl = Ezpl()
+    >>> printer = ezpl.get_printer()
+    >>> logger = ezpl.get_logger()
+    >>> printer.info("Hello, Ezpl!")
+    >>> logger.info("Logged to file")
+"""
+
+from __future__ import annotations
+
+import sys
+
+# =============================================================================
+# META INFORMATIONS
+# =============================================================================
+
+__version__ = "1.2.0"
+__author__ = "Neuraaak"
+__maintainer__ = "Neuraaak"
+__license__ = "MIT"
+__description__ = "A module for easier logging"
+__keywords__ = ["logging", "rich", "loguru", "console", "file"]
+__url__ = "https://github.com/neuraaak/ezpl"
+__repository__ = "https://github.com/neuraaak/ezpl"
+__python_requires__ = ">=3.10"
+
+# =============================================================================
+# PYTHON VERSION CHECK
+# =============================================================================
+
+if sys.version_info < (3, 10):
+    raise RuntimeError(
+        f"ezpl {__version__} requires Python 3.10 or higher. "
+        f"Current version: {sys.version}"
+    )
+
+# =============================================================================
+# IMPORTS
+# =============================================================================
+
+# ------------------------------------------------
+# CORE CONFIG & EXCEPTIONS
+# ------------------------------------------------
+from .config import ConfigurationManager
+from .core.exceptions import (
+    ConfigurationError,
+    EzplError,
+    FileOperationError,
+    HandlerError,
+    InitializationError,
+    LoggingError,
+    ValidationError,
+)
+
+# ------------------------------------------------
+# MAIN CLASS & HANDLERS
+# ------------------------------------------------
+from .ezpl import Ezpl
+from .handlers import ConsolePrinter, EzLogger, EzPrinter, FileLogger, RichWizard
+from .handlers.console import ConsolePrinterWrapper
+
+# ------------------------------------------------
+# TYPES
+# ------------------------------------------------
+from .types import (
+    PATTERN_COLORS,
+    LogLevel,
+    Pattern,
+    get_pattern_color,
+    get_pattern_color_by_name,
+)
+
+# =============================================================================
+# TYPE ALIASES
+# =============================================================================
+
+# Canonical type aliases for users.
+# They mirror the internal EzPrinter / EzLogger types.
+
+# ------------------------------------------------
+# PRINTER TYPE ALIAS
+# ------------------------------------------------
+Printer = EzPrinter
+"""Type alias for EzPrinter (console printer handler).
+Use this type when you want to annotate a variable that represents a printer.
+
+Example:
+    >>> from ezpl import Ezpl, Printer
+    >>> ezpl = Ezpl()
+    >>> printer: Printer = ezpl.get_printer()
+    >>> printer.info("Hello!")
+    >>> printer.success("Done!")
+    >>> printer.print_json({"key": "value"})
+"""
+
+# ------------------------------------------------
+# LOGGER TYPE ALIAS
+# ------------------------------------------------
+Logger = EzLogger
+"""Type alias for EzLogger (file logger handler).
+Use this type when you want to annotate a variable that represents a logger.
+
+Example:
+    >>> from ezpl import Ezpl, Logger
+    >>> ezpl = Ezpl()
+    >>> logger: Logger = ezpl.get_logger()
+    >>> logger.info("Logged to file")
+"""
+
+# =============================================================================
+# MODULE EXPORTS
+# =============================================================================
+
+__all__ = [
+    # ------------------------------------------------
+    # MAIN CLASS EXPORTS
+    # ------------------------------------------------
+    "Ezpl",
+    # ------------------------------------------------
+    # HANDLER CLASS EXPORTS
+    # ------------------------------------------------
+    "EzPrinter",
+    "EzLogger",
+    "Logger",
+    "ConsolePrinter",
+    "FileLogger",
+    "ConsolePrinterWrapper",
+    "RichWizard",
+    # ------------------------------------------------
+    # CONFIGURATION EXPORTS
+    # ------------------------------------------------
+    "ConfigurationManager",
+    # ------------------------------------------------
+    # TYPE ALIASES EXPORTS
+    # ------------------------------------------------
+    "Printer",
+    # ------------------------------------------------
+    # TYPE & PATTERN EXPORTS
+    # ------------------------------------------------
+    "LogLevel",
+    "Pattern",
+    "PATTERN_COLORS",
+    "get_pattern_color",
+    "get_pattern_color_by_name",
+    # ------------------------------------------------
+    # EXCEPTION EXPORTS
+    # ------------------------------------------------
+    "EzplError",
+    "ConfigurationError",
+    "LoggingError",
+    "ValidationError",
+    "InitializationError",
+    "FileOperationError",
+    "HandlerError",
+    # ------------------------------------------------
+    # METADATA EXPORTS
+    # ------------------------------------------------
+    "__version__",
+    "__author__",
+    "__maintainer__",
+    "__license__",
+    "__description__",
+    "__keywords__",
+    "__url__",
+    "__repository__",
+    "__python_requires__",
+]

ezplog-1.2.0/ezpl/cli/__init__.py

@@ -0,0 +1,26 @@
+"""
+CLI module for Ezpl logging framework.
+
+This module provides the command-line interface for managing Ezpl
+configuration, viewing logs, and performing various operations.
+"""
+
+# =============================================================================
+# IMPORTS
+# =============================================================================
+
+# ------------------------------------------------
+# CLI ENTRY POINT
+# ------------------------------------------------
+from .main import cli
+
+# =============================================================================
+# MODULE EXPORTS
+# =============================================================================
+
+__all__ = [
+    # ------------------------------------------------
+    # CLI PUBLIC API
+    # ------------------------------------------------
+    "cli",
+]

ezplog-1.2.0/ezpl/cli/commands/__init__.py

@@ -0,0 +1,31 @@
+"""
+CLI Commands module for Ezpl logging framework.
+
+This module contains all CLI command implementations.
+"""
+
+# =============================================================================
+# IMPORTS
+# =============================================================================
+
+# ------------------------------------------------
+# COMMAND GROUP IMPORTS
+# ------------------------------------------------
+from .config import config_group
+from .info import info_command
+from .logs import logs_group
+from .version import version_command
+
+# =============================================================================
+# MODULE EXPORTS
+# =============================================================================
+
+__all__ = [
+    # ------------------------------------------------
+    # CLI COMMAND GROUPS
+    # ------------------------------------------------
+    "logs_group",
+    "config_group",
+    "version_command",
+    "info_command",
+]