maple.utils.logging.setup_logging

maple.utils.logging.setup_logging(level: str = 'INFO', log_file: Path | None = None, verbose: bool = False) → None

Configure the global logging system for MAPLE.

Sets up Python’s logging module with consistent formatting, handlers, and log levels. This should be called once at application startup, typically in the main entry point or CLI initialization.

Safe to call multiple times - subsequent calls are ignored to prevent duplicate handler registration and conflicting configurations.

The function configures: - Log message format (timestamp, level, message, optionally source location) - Console output handler (stdout) - Optional file output handler - Third-party library log level suppression

Verbose mode adds source location information (module:line) to each log message, useful for debugging but cluttering for normal operation.

Parameters:

• level – Logging level as string. Valid values: “DEBUG”, “INFO”, “WARNING”, “ERROR”, “CRITICAL”. Case-insensitive. Defaults to “INFO”.

• log_file – Optional path to write logs to a file. The parent directory will be created if it doesn’t exist. If None, only console logging is enabled.

• verbose – If True, includes source module and line number in log messages. If False, uses simpler format with just timestamp, level, and message. Defaults to False.