utils.logging module

Logging Utilities for WeakAuras Discord Bot

This module provides centralized logging configuration and utilities for the WeakAuras Discord bot. It handles environment-based logging levels, file and console output, and provides helper functions for consistent logging across all bot components.

Example

Setting up logging at bot startup:

from utils.logging import setup_logging
setup_logging("dev")  # or "prod"

Using the command logger decorator:

from utils.logging import log_command

@log_command
async def my_command(interaction: discord.Interaction, ...):
    # Command implementation
    pass

Getting a logger for a module:

from utils.logging import get_logger
logger = get_logger(__name__)
logger.info("Module initialized")

utils.logging.DEFAULT_LOG_FORMAT

Standard log message format

Type:

str

utils.logging.DEFAULT_DATE_FORMAT

Standard date format for logs

Type:

str

utils.logging.setup_logging(environment='dev', log_dir=None)

Setup centralized logging configuration for the bot.

Parameters:

• environment (str) – Environment name (“dev” or “prod”). Defaults to “dev”. - “dev”: DEBUG level with console + file output - “prod”: INFO level with file output only

• log_dir (Path | None) – Directory for log files. If None, uses ../../logs relative to this module.

Return type:

None

Note

This function should be called once during bot initialization. It configures the root logger and sets Discord.py logging levels.

utils.logging.get_logger(name)

Get a logger instance for the specified module.

Parameters:

name (str) – Logger name, typically __name__ from the calling module.

Returns:

Configured logger instance.

Return type:

logging.Logger

Example

>>> logger = get_logger(__name__)
>>> logger.info("Module initialized")

utils.logging.format_interaction_info(interaction)

Format Discord interaction information for logging.

Parameters:

interaction (discord.Interaction) – Discord interaction object.

Returns:

Formatted string with user and guild information.

Return type:

str

Example

>>> info = format_interaction_info(interaction)
>>> logger.info(f"Command executed: {info}")

utils.logging.log_command(func)

Decorator to automatically log slash command invocations.

This decorator logs command invocations with user and guild information, and logs success or failure of command execution.

Parameters:

func (TypeVar(F, bound= Callable[..., Any])) – The command function to decorate. Must be an async function that takes discord.Interaction as its first parameter.

Return type:

TypeVar(F, bound= Callable[..., Any])

Returns:

The decorated function with logging.

Example

>>> @log_command
... async def my_command(interaction: discord.Interaction, arg: str):
...     await interaction.response.send_message(f"Got: {arg}")

Note

The decorated function must be an async function and take discord.Interaction as its first parameter.

utils.logging.log_action(action, success_msg=None, failure_msg=None)

Decorator to log specific actions within functions.

Parameters:

• action (str) – Description of the action being performed.

• success_msg (str | None) – Message to log on success. If None, uses default.

• failure_msg (str | None) – Message to log on failure. If None, uses default.

Return type:

Callable[[TypeVar(F, bound= Callable[..., Any])], TypeVar(F, bound= Callable[..., Any])]

Returns:

Decorator function that logs the specified action.

Example

>>> @log_action("macro_creation", "Macro created successfully", "Failed to create macro")
... async def create_macro_internal(name: str, content: str):
...     # Implementation
...     pass