1. Behavior and Context

All custom exceptions derive from LoggerError:

• LoggerConfigError
• LoggerFileError
• LoggerDependencyError

This allows both broad and narrow exception handling strategies.

2. Purpose

• Typed Failure Signals: Differentiate config, file, and dependency failures.
• Cleaner Call Sites: Catch package-specific errors with a single base type.
• Consistent API Contract: Shared error vocabulary across modules.

3. High-Level API & Examples

Example 1: Catch Any Logging Error

from jazzmine.logging import BaseLogger, LoggerError

try:
    logger = BaseLogger("missing-config.yml")
    logger.resolve_config()
except LoggerError as exc:
    print("logging setup failed:", exc)

Example 2: Handle Dependency Failure Separately

from jazzmine.logging import BaseLogger, LoggerDependencyError

try:
    logger = BaseLogger({
        "name": "service",
        "level": "INFO",
        "json": True,
        "sinks": [{"type": "sentry", "dsn": "..."}],
    })
    logger.resolve_config()
    # sink.initialize() occurs during start_async_workers
except LoggerDependencyError as exc:
    print("optional package missing:", exc)

4. Detailed Class Functionality

class LoggerError(Exception)

Base class for all logging subsystem errors.

class LoggerConfigError(LoggerError)

Raised for invalid configuration shape, unsupported sink types, or parsing issues.

class LoggerFileError(LoggerError)

Raised for file-related failures, such as missing config files or invalid log file targets.

class LoggerDependencyError(LoggerError)

Raised when optional runtime dependencies (for example requests, aiohttp, boto3) are required but unavailable.

5. Error Handling

This module only defines exception classes; raising behavior is implemented in other modules.

6. Remarks

• Prefer catching LoggerError at service boundaries and more specific subclasses in setup internals.
• Keep new exception types in this module to preserve a centralized error taxonomy.