Handlers API Reference

Handlers for the LogEverything library.

This module provides specialized log handlers for different output formats and destinations.

class logeverything.handlers.handlers.AdaptiveColumnManager(max_name_width=30)

Bases: object

Global manager for adaptive column widths across all formatters.

This ensures consistent visual alignment across all loggers regardless of their name lengths, while maintaining responsive design that adapts when loggers are created or destroyed. Includes smart truncation to prevent terminal wrapping issues.

get_current_name_width()

Get the current maximum name width.

Return type:

int

get_display_name(logger_name)

Get the display name for a logger, with smart truncation if needed.

Parameters:

logger_name (str) – The original logger name

Return type:

str

Returns:

The name to display, potentially truncated with ellipsis

register_formatter(formatter)

Register a formatter to receive column width updates.

Return type:

None

remove_logger_name(logger_name)

Remove a logger name and potentially resize if it was the longest. Note: This is optional/advanced - for now we’ll keep it simple and not shrink.

Return type:

None

set_max_width(max_width)

Set the absolute maximum width for logger names.

Return type:

None

update_logger_name(logger_name)

Update the maximum name width if this logger name is longer.

Return type:

None

class logeverything.handlers.handlers.ConsoleHandler(stream=None, use_colors=True, color_messages=False, level=0, colored=None)

Bases: StreamHandler

Enhanced console handler with color support and formatting.

COLORS = {'CRITICAL': '\x1b[95m', 'DEBUG': '\x1b[94m', 'ERROR': '\x1b[91m', 'INFO': '\x1b[92m', 'RESET': '\x1b[0m', 'WARNING': '\x1b[93m'}

__init__(stream=None, use_colors=True, color_messages=False, level=0, colored=None)

Initialize the ConsoleHandler.

Parameters:

• stream (Optional[TextIO]) – The output stream (default: sys.stderr)

• use_colors (bool) – Whether to use ANSI color codes for log level indicators

• color_messages (bool) – Whether to apply colors to message text (default: False)

• level (Union[int, str]) – Logging level (default: logging.NOTSET)

• colored (Optional[bool]) – Alias for use_colors, for API compatibility (deprecated)

emit(record)

Emit a log record with optional color formatting.

Parameters:

record (LogRecord) – The log record to emit

Return type:

None

class logeverything.handlers.handlers.EnhancedConsoleHandler(stream=None, use_colors=True, color_messages=False, use_symbols=True, use_indent=True, align_columns=True, color_theme='default', ascii_only=False, level=0)

Bases: ConsoleHandler

Console handler with enhanced formatting and color options.

__init__(stream=None, use_colors=True, color_messages=False, use_symbols=True, use_indent=True, align_columns=True, color_theme='default', ascii_only=False, level=0)

Initialize the EnhancedConsoleHandler.

Parameters:

• stream (Optional[TextIO]) – Output stream

• use_colors (bool) – Whether to use colors for level indicators

• color_messages (bool) – Whether to apply colors to message text (default: False)

• use_symbols (bool) – Whether to use Unicode symbols

• use_indent (bool) – Whether to use indent visualization

• align_columns (bool) – Whether to align columns

• color_theme (str) – Color theme name (‘default’, ‘pastel’, ‘bold’, ‘monochrome’)

• ascii_only (bool) – Whether to use only ASCII characters (no Unicode)

• level (Union[int, str]) – Logging level

class logeverything.handlers.handlers.FileHandler(filename, mode='a', encoding='utf-8', max_size=None, backup_count=5, compress=False, level=0)

Bases: FileHandler

Enhanced file handler with rotation support.

__init__(filename, mode='a', encoding='utf-8', max_size=None, backup_count=5, compress=False, level=0)

Initialize the FileHandler.

Parameters:

• filename (str) – Path to the log file

• mode (str) – File open mode (‘a’ for append, ‘w’ for write)

• encoding (Optional[str]) – File encoding (defaults to ‘utf-8’ for Unicode compatibility, preventing Windows cp1252 codec errors with visual formatting)

• max_size (Optional[int]) – Maximum file size in bytes before rotation (None for no rotation)

• backup_count (int) – Number of backup files to keep

• compress (bool) – If True, gzip the most recent rotated file in a background thread.

• level (Union[int, str]) – Logging level (default: logging.NOTSET)

emit(record)

Emit a log record with file rotation if needed.

Parameters:

record (LogRecord) – The log record to emit

Return type:

None

class logeverything.handlers.handlers.FormattedFileHandler(filename, mode='a', encoding='utf-8', pretty=True, use_symbols=True, use_indent=True, align_columns=True, compact_mode=True, compact_threshold=5, level=0, max_size=None, backup_count=5)

Bases: FileHandler

File handler with enhanced formatting for improved readability.

__init__(filename, mode='a', encoding='utf-8', pretty=True, use_symbols=True, use_indent=True, align_columns=True, compact_mode=True, compact_threshold=5, level=0, max_size=None, backup_count=5)

Initialize the FormattedFileHandler.

Parameters:

• filename (str) – Path to the log file

• mode (str) – File open mode (‘a’ for append, ‘w’ for write)

• encoding (Optional[str]) – File encoding (default: utf-8 for Unicode support)

• pretty (bool) – Whether to use enhanced formatting

• use_symbols (bool) – Whether to use Unicode symbols for log levels

• use_indent (bool) – Whether to use indent visualization

• align_columns (bool) – Whether to align columns

• compact_mode (bool) – Whether to use compact mode for deep hierarchies

• compact_threshold (int) – Depth at which to start compact mode

• level (Union[int, str]) – Logging level

• max_size (Optional[int]) – Maximum file size in bytes before rotation (None for no rotation)

• backup_count (int) – Number of backup files to keep

emit(record)

Emit a log record with file rotation if needed.

Parameters:

record (LogRecord) – The log record to emit

Return type:

None

class logeverything.handlers.handlers.JSONHandler(filename, mode='a', encoding=None, flatten=False, indent=None, level=0)

Bases: Handler

Log handler that outputs logs as JSON objects.

__init__(filename, mode='a', encoding=None, flatten=False, indent=None, level=0)

Initialize the JSONHandler.

Parameters:

• filename (str) – Path to the JSON log file

• mode (str) – File open mode (‘a’ for append, ‘w’ for write)

• encoding (Optional[str]) – File encoding (defaults to ‘utf-8’)

• flatten (bool) – Whether to flatten the output (one JSON object per line)

• indent (Optional[int]) – JSON indentation level (None for no pretty-printing)

• level (Union[int, str]) – Logging level (default: logging.NOTSET)

close()

Close the handler and its file handle.

Return type:

None

emit(record)

Emit a log record as JSON.

Parameters:

record (LogRecord) – The log record to emit

Return type:

None

file_handle: IO[str] | None

class logeverything.handlers.handlers.JSONLineFormatter(include_extras=True, source=None)

Bases: Formatter

Formatter that outputs each log record as a single JSON object.

Attach this to any handler (including rotation handlers) to produce dashboard-compatible JSON Lines output. The field layout matches JSONHandler so the dashboard can read the files directly.

Parameters:

• include_extras (bool) – Include extra record attributes in an extra dict.

• source (Optional[str]) – Optional service/source tag written into every record.

format(record)

Return a JSON string for record (no trailing newline).

The handler is responsible for appending the line terminator.

Return type:

str

class logeverything.handlers.handlers.PrettyFormatter(fmt=None, datefmt=None, style='%', use_colors=False, color_messages=False, use_symbols=True, use_monospace_symbols=False, use_indent=True, align_columns=True, column_widths=None, compact_mode=True, compact_threshold=5)

Bases: Formatter

Enhanced formatter that creates visually appealing logs with Unicode symbols.

Default format string - pipe encapsulation handles level width consistently.

COLORS = {'BOLD': '\x1b[1m', 'CRITICAL': '\x1b[95m', 'DEBUG': '\x1b[94m', 'ERROR': '\x1b[91m', 'INFO': '\x1b[92m', 'RESET': '\x1b[0m', 'UNDERLINE': '\x1b[4m', 'WARNING': '\x1b[93m'}

COMPACT_SYMBOL = '⋯'

COMPACT_THRESHOLD = 5

CONTINUE_CHAR = '├──'

DEFAULT_DATE_FORMAT = '%Y-%m-%d %H:%M:%S'

DEFAULT_FORMAT = '%(asctime)s | %(levelname)s | %(name)s | %(message)s'

ENTRY_CHAR = '┌─►'

EXIT_CHAR = '└─◄'

INDENT_CHAR = '│'

LEVEL_SYMBOLS = {'CRITICAL': '🔥', 'DEBUG': '🔍', 'ERROR': '❌', 'EXCEPTION': '💥', 'INFO': 'ℹ️', 'WARNING': '⚠️'}

LEVEL_SYMBOLS_MONOSPACE = {'CRITICAL': '[C]', 'DEBUG': '[D]', 'ERROR': '[E]', 'EXCEPTION': '[X]', 'INFO': '[I]', 'WARNING': '[W]'}

TREE_BRANCH = '├─'

TREE_INDENT = '  '

TREE_LAST_BRANCH = '└─'

TREE_SPACE = '  '

TREE_VERTICAL = '│ '

__init__(fmt=None, datefmt=None, style='%', use_colors=False, color_messages=False, use_symbols=True, use_monospace_symbols=False, use_indent=True, align_columns=True, column_widths=None, compact_mode=True, compact_threshold=5)

Initialize the PrettyFormatter.

Parameters:

• fmt (Optional[str]) – Format string (default: class default format)

• datefmt (Optional[str]) – Date format string (default: class default date format)

• style (Literal['%', '{', '$']) – Format string style (‘%’, ‘{’, or ‘$’)

• use_colors (bool) – Whether to use ANSI color codes

• use_symbols (bool) – Whether to use Unicode symbols for log levels

• use_monospace_symbols (bool) – Whether to use monospace symbols for perfect alignment

• use_indent (bool) – Whether to use indent visualization

• align_columns (bool) – Whether to align columns

• column_widths (Optional[Dict[str, int]]) – Custom column widths for alignment

• compact_mode (bool) – Whether to use compact mode for deep hierarchies

• compact_threshold (int) – Depth at which to start compact mode

format(record)

Format the log record with enhanced hierarchical visual elements.

Modifies the record in-place and restores original values after formatting to avoid the overhead of makeLogRecord(record.__dict__) copy.

Parameters:

record (LogRecord) – The log record to format

Return type:

str

Returns:

Formatted log record string with improved tree structure

formatTime(record, datefmt=None)

Cache-optimized formatTime — same-second records reuse the formatted string.

Parameters:

• record (LogRecord) – The log record

• datefmt (Optional[str]) – Optional date format string

Return type:

str

Returns:

Formatted time string

class logeverything.handlers.handlers.TimedRotatingFileHandler(filename, when='midnight', interval=1, retention_days=30, compress=False, encoding='utf-8', level=0)

Bases: FileHandler

File handler with time-based rotation and optional gzip compression.

Rotates log files at time boundaries (midnight, hourly, or weekly) and optionally compresses rotated files with gzip.

Parameters:

• filename (str) – Path to the log file.

• when (str) – Rotation interval type – "midnight", "hourly", or "weekly".

• interval (int) – Multiplier for when (currently unused, reserved for future use).

• retention_days (int) – Delete rotated files older than this many days.

• compress (bool) – If True, gzip rotated files in a background thread.

• encoding (Optional[str]) – File encoding.

• level (Union[int, str]) – Logging level.

WHEN_MAP = {'hourly': '%Y-%m-%d-%H', 'midnight': '%Y-%m-%d', 'weekly': '%Y-%W'}

doRollover()

Perform the file rollover, compressing and cleaning up as configured.

Return type:

None

emit(record)

Emit a record, performing a rollover first if one is due.

Parameters:

record (LogRecord) – The log record to emit.

Return type:

None

shouldRollover(record)

Check whether the current record should trigger a rollover.

Parameters:

record (LogRecord) – The log record being emitted.

Return type:

bool

Returns:

True if a rollover is due.

logeverything.handlers.handlers.get_adaptive_column_manager()

Get the global adaptive column manager instance.

Return type:

AdaptiveColumnManager

logeverything.handlers.handlers.get_current_name_column_width()

Get the current adaptive name column width.

Return type:

int

logeverything.handlers.handlers.get_display_name(logger_name)

Get the display version of a logger name (potentially truncated).

Parameters:

logger_name (str) – The original logger name

Return type:

str

Returns:

The display name with smart truncation if needed

logeverything.handlers.handlers.register_logger_name(name)

Register a logger name with the adaptive column manager.

This is a convenience function for external code to register logger names without having to import the manager directly.

Return type:

None

logeverything.handlers.handlers.set_max_logger_name_width(max_width)

Set the maximum width for logger names to prevent terminal wrapping.

Names longer than this will be truncated with smart ellipsis.

Parameters:

max_width (int) – Maximum character width for logger names

Return type:

None