qq_lib.core.error_handlers

 1# Released under MIT License.
 2# Copyright (c) 2025-2026 Ladislav Bartos and Robert Vacha Lab
 3
 4"""
 5Error-handling utilities for qq operations.
 6
 7This module provides helper functions for processing and reporting errors
 8encountered during multi-item qq operations. Handlers distinguish between
 9unsuitable jobs, job-ID mismatches, general failures, and ignorable errors,
10and exit with appropriate qq exit codes when necessary.
11"""
12
13import sys
14from typing import NoReturn
15
16from qq_lib.core.command_runner import CommandRunner
17
18from .config import CFG
19from .error import QQNotSuitableError
20from .logger import get_logger
21
22logger = get_logger(__name__)
23
24
25def handle_not_suitable_error(
26    exception: Exception,
27    runner: CommandRunner,
28) -> None:
29    """Handle cases where a job is unsuitable for a qq operation."""
30    if runner.n_jobs == 1:
31        logger.error(exception)
32        sys.exit(CFG.exit_codes.default)
33
34    if runner.n_jobs > 1:
35        logger.info(exception)
36
37    if (
38        sum(
39            isinstance(x, QQNotSuitableError)
40            for x in runner.encountered_errors.values()
41        )
42        == runner.n_jobs
43    ):
44        logger.error("No suitable qq job.\n")
45        sys.exit(CFG.exit_codes.default)
46
47
48def handle_job_mismatch_error(
49    exception: Exception,
50    _runner: CommandRunner,
51) -> NoReturn:
52    """Handle cases where the provided job ID does not match the qq info file."""
53    logger.error(exception)
54    sys.exit(CFG.exit_codes.default)
55
56
57def handle_general_qq_error(
58    exception: Exception,
59    runner: CommandRunner,
60) -> None:
61    """Handle general qq errors that occur during a qq operation."""
62    logger.error(exception)
63
64    if runner.n_jobs == len(runner.encountered_errors):
65        sys.exit(CFG.exit_codes.default)
66
67
68def ignore_error(
69    _exception: Exception,
70    _runner: CommandRunner,
71) -> None:
72    """Ignore the error."""
73    pass