Skip to content

API Reference

Complete API reference for Ezpl logging framework.

Overview

The Ezpl API is organized into several key components, each serving a specific purpose in the logging ecosystem.

Quick Reference

Component Description Documentation
Ezpl Main singleton class Core logging management
EzPrinter Console output Rich-formatted console logging
EzLogger File logging Loguru-based file logging
RichWizard Advanced display Panels, tables, JSON, progress bars
ConfigurationManager Configuration Centralized config management
Types & Enums LogLevel, Pattern Type definitions and enums
Exceptions Error handling Custom exception hierarchy

Main Components

Core Classes

  • Ezpl - The main singleton class that manages the logging system
  • EzPrinter (alias: Printer) - Console output handler with Rich formatting
  • EzLogger (alias: Logger) - File logging handler with loguru
  • RichWizard - Advanced Rich display capabilities

Configuration & Types

  • ConfigurationManager - Manages configuration from multiple sources
  • LogLevel - Enum for log levels (DEBUG, INFO, SUCCESS, WARNING, ERROR, CRITICAL)
  • Pattern - Enum for contextual patterns (SUCCESS, ERROR, WARN, TIP, etc.)

Error Handling

Type System

Ezpl provides comprehensive type hints for better IDE support:

from ezpl import Ezpl, Printer, Logger, LogLevel, Pattern
from typing import TYPE_CHECKING

# Full type annotations
ezpl: Ezpl = Ezpl()
printer: Printer = ezpl.get_printer()
logger: Logger = ezpl.get_logger()

# Enum types
level: LogLevel = LogLevel.INFO
pattern: Pattern = Pattern.SUCCESS

API Design Principles

Singleton Pattern

The Ezpl class follows the singleton pattern with thread-safe double-checked locking:

  • Only one instance exists across the application
  • Configuration set at the root level propagates to all modules
  • Thread-safe initialization

Type Safety

  • Full type hints throughout the codebase
  • Type aliases for better readability (Printer, Logger)
  • Protocol-based interfaces for extensibility

Configuration Priority

Configuration follows a clear priority order:

  1. Direct arguments to Ezpl()
  2. Environment variables (EZPL_* prefix)
  3. Configuration file (~/.ezpl/config.json)
  4. Default values

Exception Safety

  • Never crashes, even with invalid input
  • Automatic type conversion and sanitization
  • Custom exception hierarchy for precise error handling
  • Graceful fallbacks for all error cases

Quick Start Examples

Basic Usage

from ezpl import Ezpl

# Initialize
ezpl = Ezpl(log_file="app.log")
printer = ezpl.get_printer()
logger = ezpl.get_logger()

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

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

Advanced Features

from ezpl import Ezpl

ezpl = Ezpl()
printer = ezpl.get_printer()

# Pattern-based logging
printer.tip("Pro tip: Use type hints!")
printer.system("System message")
printer.install("Installing package...")

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

Configuration

from ezpl import Ezpl

# Direct configuration
ezpl = Ezpl(
    log_file="app.log",
    log_level="DEBUG",
    log_rotation="10 MB",
    log_retention="7 days",
    log_compression="zip"
)

# Runtime reconfiguration
ezpl.configure(
    printer_level="INFO",
    logger_level="DEBUG"
)

# Reload from file and environment
ezpl.reload_config()

Detailed Documentation

Select a component from the navigation menu or the table above to view detailed documentation with:

  • Complete method signatures
  • Parameter descriptions
  • Return types
  • Usage examples
  • Best practices

Auto-Generated API Documentation

For auto-generated API documentation from source code docstrings:

Module Description
Ezpl Main singleton class
EzPrinter Console output handler
EzLogger File logging handler
RichWizard Advanced display features
Configuration Configuration management
Types & Enums Type definitions
Exceptions Exception hierarchy

Or browse the Full Reference Index.

Need Help?