pylogrouter

pylogrouter is a small library for routing log messages into multiple facilities (console, plain text file, HTML log) via a single API.

Why it exists:

• avoid duplicating print + file write + html write across a codebase;
• route one message to all outputs or only selected ones;
• get a readable HTML log for browser viewing (with syntax highlighting for key=value, quotes, numbers);
• keep it safe-by-default (escaping, limits, anti-flood, hardened log targets).

Repository: https://github.com/mykolarudenko/pylogrouter

Install from PyPI (pip)

pip install pylogrouter

Quick start

from pylogrouter import LoggerRouter

logger = LoggerRouter(logger_level="DEBUG", logger_color=True)

logger.add_log_file(
    log_handle="file_log",
    log_file_path="logs/app.log",
    rotate_on_start=True,
    rotations_to_keep=2,
)

logger.add_html_log_file(
    log_handle="html_dark",
    log_file_path="logs/app-dark.html",
    title="App Log (Dark)",
    html_theme=LoggerRouter.THEME_DARK,
    html_auto_refresh_enabled=True,
    html_auto_refresh_seconds=3,
    rotate_on_start=True,
    rotations_to_keep=0,
)

logger.info("Hello to all facilities.")
logger.warning("Only console + html", handles=[LoggerRouter.HANDLE_CONSOLE, "html_dark"])

Screenshots

Console output

Figure 1 — Console output from example.py mock stream (logger_color=True).

HTML output (dark theme)

Figure 2 — Browser view of the generated HTML log in dark theme (html_theme="dark").

HTML output (light theme)

Figure 3 — Browser view of the generated HTML log in light theme (html_theme="light").

Usage / API reference (short)

Singleton model

LoggerRouter is a singleton. Calling the constructor multiple times returns the same instance. The router is thread-safe for a single process and uses an internal queue + dedicated writer thread.

Facilities and handles

• Each output channel has a string handle.
• handles=None routes to all active facilities.
• handles=["console", "html_dark"] routes only to selected targets.

Levels and “nature”

• Convenience: logger.debug(...), logger.info(...), logger.warning(...), logger.error(...)
• Explicit: logger.log(message=..., level=..., nature=..., handles=...)

Plain file facility

• add_log_file(...) writes to a text file.
• Parent directories are created automatically.
• Rotation:
  • rotate_on_start=True with rotations_to_keep=N (startup rotation),
  • plus size-based rotation: if file exceeds plain_log_max_file_size_bytes, it rotates using rotations_to_keep.

HTML facility

• add_html_log_file(...) writes a streaming HTML log (open it in a browser).
• Options:
  • html_theme: "dark" or "light" (default: "dark"),
  • html_auto_refresh_enabled: enables <meta http-equiv="refresh"> (default: False),
  • html_auto_refresh_seconds: refresh interval when enabled (default: 10).

Mock stream

• logger.mock_logger_output() emits sample records (useful for previews).

Throttling / anti-flood

If log write rate becomes too high, extra writes in the window are dropped:

• max_writes_per_second (default: 200)
• throttle_window_seconds (default: 1)

Stats:

stats = logger.get_throttle_stats()
# {"dropped_total": ..., "dropped_by_handle": {...}}

Queue / lifecycle controls

• New constructor options:
  • queue_maxsize (default 10000)
  • enqueue_timeout_ms (default 50)
• New methods:
  • flush(timeout_seconds=5.0) -> bool
  • shutdown(timeout_seconds=5.0) -> bool
  • get_queue_stats() -> {"queued": ..., "dropped": ..., "written": ..., "queue_maxsize": ...}

Security model

• HTML log:

  1. strict escaping (escape_html_strict) for all user-controlled fragments;
  2. strict post-render allowlist validation of the produced HTML fragment.

  If validation fails, the row is blocked from being written; the logger reports a security incident to console diagnostics and continues.

• Hardened log targets:

  • symlink and special files are rejected for file/html targets.
  • shared file ownership across multiple processes is rejected (fail-fast). A single log file is intended to be owned by one process.

• Console output:

  • control characters (C0/C1) are normalized to avoid malicious ANSI/control sequences.

Safety limits (defaults; override in LoggerRouter(...))

• max_message_length: 32768
• max_message_lines: 500
• max_line_length: 4096
• max_log_handles_per_call: 64
• colorize_timeout_ms: 15 (if colorization exceeds budget, message is still published without syntax coloring)
• max_html_document_bytes: 10485760 (10 MiB)
• max_html_title_length: 256
• max_writes_per_second: 200
• throttle_window_seconds: 1
• plain_log_max_file_size_bytes: 209715200 (200 MiB)
• queue_maxsize: 10000
• enqueue_timeout_ms: 50

Runtime scope

This library is desktop-first and optimized for single-process runtime. For server multi-worker deployments, use separate files per worker or an external log aggregation pipeline.