MessageRouter — Multi-Destination Logger Reference

MessageRouter is a structured logging and message-routing utility that routes messages to up to four destinations: the local terminal (origin), every server’s HungerBridge console (destination), every server’s in-game chat (broadcast), and a rotating date-stamped log file (filelog). The shorthand methods info(), warn(), and error() call origin and filelog only; call destination() and broadcast() directly when you need to reach those routes. Color and format transformations are applied per-destination using mapres map lists, so ANSI escape codes appear in the terminal, Minecraft color codes appear in chat, and plain stripped text is written to disk. Log files are created automatically in the log_path directory and named {name}_YYYY-MM-DD.log.

from hungerlib.messagerouter import MessageRouter

router = MessageRouter(
    name="bot",
    Servers=[mc_server],
    log_path="./logs",
)

router.info("Server is starting up")
router.warn("Memory usage above 80%")
router.error("Connection to database lost")

Constructor

MessageRouter(
    name: str,
    Servers: list,
    log_path: str,
    origin_maps      = [maps.ascii_colors],
    destination_maps = [maps.ascii_colors],
    broadcast_maps   = [maps.mc_colors],
    file_maps        = [maps.strip_colors],
    prefix_maps      = [maps.ascii_colors, maps.time],
    info_prefix  = "<white>[%hh%:%mm%:%ss%] [INFO]: ",
    warn_prefix  = "<yellow>[%hh%:%mm%:%ss%] [WARN]: ",
    error_prefix = "<red>[%hh%:%mm%:%ss%] [ERROR]: ",
)

name

str

required

Identifier for this router. Used as the Python logging.Logger name and as the prefix of log filenames: {name}_YYYY-MM-DD.log.

Servers

list

required

List of server objects (typically MinecraftServer instances) to route messages to. The router inspects each for a .bridge attribute (for destination) and a .sendBroadcast method (for broadcast), so plain GenericServer instances are silently skipped for those routes.

log_path

str

required

Filesystem path to the directory where log files will be written. Created automatically with mkdir(parents=True, exist_ok=True) if it does not exist.

origin_maps

list

default:"[maps.ascii_colors]"

List of mapres map objects applied when rendering text for the terminal (origin route). Defaults to ANSI color processing.

destination_maps

list

default:"[maps.ascii_colors]"

Map list applied when rendering text for the HungerBridge console (destination route).

broadcast_maps

list

default:"[maps.mc_colors]"

Map list applied when rendering text for in-game tellraw broadcasts. Defaults to Minecraft color code processing.

file_maps

list

default:"[maps.strip_colors]"

Map list applied before writing text to the log file. Defaults to stripping all color/format tokens so the file contains clean plain text.

prefix_maps

list

default:"[maps.ascii_colors, maps.time]"

Map list applied when rendering the timestamp and level prefix strings. Includes both ANSI color and time substitution.

info_prefix

str

default:"<white>[%hh%:%mm%:%ss%] [INFO]: "

Template string for the INFO-level prefix. %hh%, %mm%, and %ss% are substituted with the current time by the maps.time map resolver.

warn_prefix

str

default:"<yellow>[%hh%:%mm%:%ss%] [WARN]: "

Template string for the WARN-level prefix.

error_prefix

str

default:"<red>[%hh%:%mm%:%ss%] [ERROR]: "

Template string for the ERROR-level prefix.

Shorthand Methods

These are the primary methods for everyday use. Each one calls both origin (terminal print) and filelog (disk write) in a single call. They do not automatically call destination or broadcast — use the primitive routes directly for those.

`info()`

router.info(text: str, extra_maps=None, override_maps=None, **ctx) -> str

Logs a message at INFO level. Applies info_prefix and renders with origin_maps.

text

str

required

The message to log.

extra_maps

list | None

default:"None"

Additional map objects to append to the default map list for this call.

override_maps

list | None

default:"None"

If provided, replaces the default map list entirely for this call.

**ctx

any

Extra keyword arguments passed through to the MapResolver for template variable substitution.

Returns str — the fully rendered terminal string (prefix + message with ANSI codes applied).

`warn()`

router.warn(text: str, extra_maps=None, override_maps=None, **ctx) -> str

Logs a message at WARN level. Applies warn_prefix with a yellow color tag and renders with origin_maps.

text

str

required

The message to log.

extra_maps

list | None

default:"None"

Additional map objects to append to the default map list.

override_maps

list | None

default:"None"

Replaces the default map list if provided.

**ctx

any

Extra keyword arguments for template substitution.

Returns str — the fully rendered terminal string.

`error()`

router.error(text: str, extra_maps=None, override_maps=None, **ctx) -> str

Logs a message at ERROR level. Applies error_prefix with a red color tag and renders with origin_maps.

text

str

required

The message to log.

extra_maps

list | None

default:"None"

Additional map objects to append to the default map list.

override_maps

list | None

default:"None"

Replaces the default map list if provided.

**ctx

any

Extra keyword arguments for template substitution.

Returns str — the fully rendered terminal string.

Primitive Routes

Use these when you need fine-grained control over which destinations receive a message, or when combining routes manually.

`origin()`

router.origin(text: str, level: str = "info", extra_maps=None, override_maps=None, **ctx) -> str

Renders and prints a message to the terminal (stdout) with the appropriate level prefix and ANSI color codes.

text

str

required

The message body to render and print.

level

str

default:"info"

Log level controlling which prefix is prepended. Must be "info", "warn", or "error".

extra_maps

list | None

default:"None"

Extra map objects appended to the active map list for this call.

override_maps

list | None

default:"None"

Replaces origin_maps entirely if provided.

**ctx

any

Keyword arguments forwarded to the MapResolver for template substitution.

Returns str — the full rendered string that was printed (prefix + message). Raises InvalidLevelError if level is not "info", "warn", or "error".

`destination()`

router.destination(text: str, level: str = "info", extra_maps=None, override_maps=None, **ctx) -> str

Sends a log message to the HungerBridge console on every server in Servers that has a .bridge attribute. Uses destination_maps for rendering.

text

str

required

The message to send.

level

str

default:"info"

Log level forwarded to BridgeClient.log(message, level). Must be "info", "warn", or "error".

extra_maps

list | None

default:"None"

Extra map objects appended to destination_maps.

override_maps

list | None

default:"None"

Replaces destination_maps entirely if provided.

**ctx

any

Keyword arguments forwarded to the MapResolver.

Returns str — the rendered message string that was sent.

`broadcast()`

router.broadcast(text: str, extra_maps=None, override_maps=None, **ctx) -> str

Sends a tellraw-based broadcast to every server in Servers that has a .sendBroadcast method. Uses broadcast_maps (Minecraft color codes by default) for rendering.

text

str

required

The message to broadcast in-game.

extra_maps

list | None

default:"None"

Extra map objects appended to broadcast_maps.

override_maps

list | None

default:"None"

Replaces broadcast_maps entirely if provided.

**ctx

any

Keyword arguments forwarded to the MapResolver.

Returns str — the rendered message string that was broadcast.

`filelog()`

router.filelog(text: str, level: str = "info", extra_maps=None, override_maps=None, **ctx) -> str

Writes a message to the rotating date-stamped log file using Python’s logging module. Uses file_maps (strip colors by default) so the file contains clean plain text. The file is named {name}_YYYY-MM-DD.log and located in log_path.

text

str

required

The message to write to the log file.

level

str

default:"info"

Logging level. Must be "info", "warn", or "error". Maps to logger.info(), logger.warning(), and logger.error() respectively.

extra_maps

list | None

default:"None"

Extra map objects appended to file_maps.

override_maps

list | None

default:"None"

Replaces file_maps entirely if provided.

**ctx

any

Keyword arguments forwarded to the MapResolver.

Returns str — the stripped/rendered string that was written to the file.

Log File Format

Log files use the Python logging formatter pattern:

[%(asctime)s] [%(levelname)s] %(message)s

Example file: ./logs/bot_2024-07-15.log

[14:32:01] [INFO] Server is starting up
[14:32:45] [WARNING] Memory usage above 80%
[14:33:12] [ERROR] Connection to database lost

A new log file is created each day. The log_path directory is created automatically if it does not exist.

Classes

Panel API Modules

Utilities & Exceptions

MessageRouter — Multi-Destination Logger Reference

Constructor

Shorthand Methods

`info()`

`warn()`

`error()`

Primitive Routes

`origin()`

`destination()`

`broadcast()`

`filelog()`

Log File Format

Build docs developers (and LLMs) love

Classes

Panel API Modules

Utilities & Exceptions

Documentation Index

​Constructor

​Shorthand Methods

​info()

​warn()

​error()

​Primitive Routes

​origin()

​destination()

​broadcast()

​filelog()

​Log File Format

Build docs developers (and LLMs) love

Constructor

Shorthand Methods

`info()`

`warn()`

`error()`

Primitive Routes

`origin()`

`destination()`

`broadcast()`

`filelog()`

Log File Format