Quick Start Guide

Get up and running with Apathetic Python Logger in minutes.

Basic Usage

The simplest way to use Apathetic Python Logger is to register a logger name and get a logger instance:

from apathetic_logging import getLogger, registerLogger

# Register your logger
registerLogger("my_app")

# Get the logger instance
logger = getLogger()

# Start logging!
logger.info("Application started")
logger.debug("Debug information")
logger.warning("This is a warning")
logger.error("An error occurred")

Module-Level Convenience Functions

You can also use module-level convenience functions that log to the root logger:

import apathetic_logging

# Standard levels
apathetic_logging.debug("Debug message")
apathetic_logging.info("Info message")
apathetic_logging.warning("Warning message")
apathetic_logging.error("Error message")
apathetic_logging.critical("Critical message")

# Custom levels
apathetic_logging.trace("Trace message")
apathetic_logging.detail("Detail message")
apathetic_logging.brief("Brief message")

These functions automatically ensure the root logger is an apathetic logger and handle configuration if needed.

Log Levels

Apathetic Python Logger supports the following log levels (in order of verbosity):

Setting Log Levels

You can set the log level in several ways:

1. Environment Variable

export LOG_LEVEL=debug
python my_app.py

2. Programmatically

logger.setLevel("debug")  # Case-insensitive
logger.setLevel(logging.DEBUG)  # Or use logging constants

3. Using Context Manager

Temporarily change the log level for a specific block:

with logger.useLevel("debug"):
    logger.debug("This will be shown")
    logger.trace("This will also be shown if trace is enabled")

Colorized Output

Apathetic Python Logger automatically detects if your terminal supports colors and enables colorized output by default.

Color Detection

Colors are enabled when:

Colors are disabled when:

Manual Control

from apathetic_logging import ApatheticLogging

# Create logger with colors explicitly enabled/disabled
logger = ApatheticLogger("my_app", enable_color=True)

Tag Formatting

Log messages are automatically prefixed with tags:

Dual-Stream Handling

Apathetic Python Logger automatically routes log messages to the appropriate stream:

This ensures proper separation of output and error streams, which is important for CLI tools.

Advanced Features

Dynamic Log Levels

Log at different levels dynamically:

logger.logDynamic("warning", "This is a warning")
logger.logDynamic(logging.ERROR, "This is an error")

Conditional Exception Logging

Only show full tracebacks when debug mode is enabled:

try:
    risky_operation()
except Exception:
    logger.errorIfNotDebug("Operation failed")
    # Full traceback only shown if debug/trace is enabled

Temporary Level Changes

Use a context manager to temporarily change log levels:

# Only set level if it's more verbose (won't downgrade from trace to debug)
with logger.useLevel("debug", minimum=True):
    logger.debug("This will be shown")

Integration with CLI Tools

For command-line applications, you can integrate with argparse:

import argparse
from apathetic_logging import getLogger, registerLogger

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--log-level", default="info")
    args = parser.parse_args()
    
    registerLogger("my_cli")
    logger = getLogger()
    
    # Logger will automatically use args.log_level
    level = logger.determineLogLevel(args=args)
    logger.setLevel(level)
    
    logger.info("CLI tool started")

Drop-in Replacement for stdlib logging

Apathetic Python Logger can be used as a drop-in replacement for Python’s standard library logging module:

# Instead of: import logging
import apathetic_logging as logging

# Works just like stdlib logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("my_app")  # Note: getLogger is CamelCase in stdlib
logger.info("Hello, world!")
logger.debug("Debug message")
logger.warning("Warning message")

Note: When using getLogger(None), the logger name is auto-inferred from the calling module (improved behavior). To get the root logger, use getLogger("") instead. For stdlib-compatible behavior where getLogger(None) returns the root logger, enable Compatibility Mode.

Next Steps