sevaht_utility.log_utility

Opinionated logging setup and helpers.

Provides a console-plus-optional-rotating-file logging configuration (configure_logging(), configure_logging_custom()), argparse integration (add_log_arguments()), a context manager to silence the console temporarily (suppress_console_logging()), and a decorator that logs and re-raises uncaught exceptions (log_exceptions()).

class sevaht_utility.log_utility.LogFileOptions(path: 'Path', *, max_kb: 'int', backup_count: 'int', level: 'int' = 10, encoding: 'str' = 'utf-8', append: 'bool' = True)

Bases: object

sevaht_utility.log_utility.configure_logging_custom(console_level: int, log_file_options: LogFileOptions | None = None) → None

Install a console handler and an optional rotating file handler.

Replaces the root logger’s handlers. The console handler honors console_level and drops records flagged file_only; when log_file_options is given, a file handler captures everything at its own level with timestamps.

Parameters:

• console_level – Minimum level shown on the console.

• log_file_options – File logging configuration, or None for console-only.

sevaht_utility.log_utility.add_log_arguments(parser: argparse.ArgumentParser) → None

Add standard logging options to an argument parser.

Adds --log-file and a mutually exclusive verbosity group (-v/--verbose, -q/--quiet, --debug) writing to the console_level and log_file destinations consumed by configure_logging().

Parameters:

parser – The parser (or subparser) to extend.

sevaht_utility.log_utility.configure_logging(args: argparse.Namespace, *, max_kb: int = 512, backup_count: int = 1, append: bool = True) → None

Configure logging from parsed add_log_arguments() options.

The console level comes from args.console_level (default WARNING); when args.log_file is set, a rotating file handler is added.

Parameters:

• args – Parsed arguments containing console_level and log_file.

• max_kb – Max size per log file in KiB before rotation; 0 disables rotation.

• backup_count – Number of rotated backups to keep; 0 keeps none.

• append – Whether to append to an existing log file rather than truncate.

sevaht_utility.log_utility.suppress_console_logging() → Iterator[None]

Temporarily remove logging handlers that write to the terminal.

This affects only StreamHandlers whose stream is sys.stdout or sys.stderr. Other handlers (file, syslog, HTTP, custom streams) remain intact.

All removed handlers are restored after the context exits.

sevaht_utility.log_utility.log_exceptions(*, logger: logging.Logger | None = None, message: str = 'uncaught exception', file_only: bool = True) → Callable[[Callable[P, R]], Callable[P, R]]

Decorate a callable to log any exception it raises, then re-raise.

The exception is logged with a traceback; the call still propagates it.

Parameters:

• logger – Logger to use; defaults to one named for the wrapped function’s module.

• message – Message logged alongside the traceback.

• file_only – Tag the record so configure_logging_custom()’s console handler suppresses it (file handlers still receive it).

Returns:

A decorator that wraps a function while preserving its signature.