# Licensed under the GPL: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
# For details: https://github.com/PyCQA/pylint/blob/main/LICENSE
# Copyright (c) https://github.com/PyCQA/pylint/blob/main/CONTRIBUTORS.txt

"""Checks for various exception related errors."""

from __future__ import annotations

import builtins
import inspect
import warnings
from collections.abc import Generator
from typing import TYPE_CHECKING, Any

import astroid
from astroid import nodes, objects, util
from astroid.context import InferenceContext
from astroid.typing import InferenceResult, SuccessfulInferenceResult

from pylint import checkers
from pylint.checkers import utils
from pylint.interfaces import HIGH, INFERENCE
from pylint.typing import MessageDefinitionTuple

if TYPE_CHECKING:
    from pylint.lint import PyLinter


def _builtin_exceptions() -> set[str]:
    def predicate(obj: Any) -> bool:
        return isinstance(obj, type) and issubclass(obj, BaseException)

    members = inspect.getmembers(builtins, predicate)
    return {exc.__name__ for (_, exc) in members}


def _annotated_unpack_infer(
    stmt: nodes.NodeNG, context: InferenceContext | None = None
) -> Generator[tuple[nodes.NodeNG, SuccessfulInferenceResult], None, None]:
    """Recursively generate nodes inferred by the given statement.

    If the inferred value is a list or a tuple, recurse on the elements.
    Returns an iterator which yields tuples in the format
    ('original node', 'inferred node').
    """
    if isinstance(stmt, (nodes.List, nodes.Tuple)):
        for elt in stmt.elts:
            inferred = utils.safe_infer(elt)
            if inferred and not isinstance(inferred, util.UninferableBase):
                yield elt, inferred
        return
    for inferred in stmt.infer(context):
        if isinstance(inferred, util.UninferableBase):
            continue
        yield stmt, inferred


def _is_raising(body: list[nodes.NodeNG]) -> bool:
    """Return whether the given statement node raises an exception."""
    return any(isinstance(node, nodes.Raise) for node in body)


MSGS: dict[str, MessageDefinitionTuple] = {
    "E0701": (
        "Bad except clauses order (%s)",
        "bad-except-order",
        "Used when except clauses are not in the correct order (from the "
        "more specific to the more generic). If you don't fix the order, "
        "some exceptions may not be caught by the most specific handler.",
    ),
    "E0702": (
        "Raising %s while only classes or instances are allowed",
        "raising-bad-type",
        "Used when something which is neither a class nor an instance "
        "is raised (i.e. a `TypeError` will be raised).",
    ),
    "E0704": (
        "The raise statement is not inside an except clause",
        "misplaced-bare-raise",
        "Used when a bare raise is not used inside an except clause. "
        "This generates an error, since there are no active exceptions "
        "to be reraised. An exception to this rule is represented by "
        "a bare raise inside a finally clause, which might work, as long "
        "as an exception is raised inside the try block, but it is "
        "nevertheless a code smell that must not be relied upon.",
    ),
    "E0705": (
        "Exception cause set to something which is not an exception, nor None",
        "bad-exception-cause",
        'Used when using the syntax "raise ... from ...", '
        "where the exception cause is not an exception, "
        "nor None.",
        {"old_names": [("E0703", "bad-exception-context")]},
    ),
    "E0710": (
        "Raising a new style class which doesn't inherit from BaseException",
        "raising-non-exception",
        "Used when a new style class which doesn't inherit from "
        "BaseException is raised.",
    ),
    "E0711": (
        "NotImplemented raised - should raise NotImplementedError",
        "notimplemented-raised",
        "Used when NotImplemented is raised instead of NotImplementedError",
    ),
    "E0712": (
        "Catching an exception which doesn't inherit from Exception: %s",
        "catching-non-exception",
        "Used when a class which doesn't inherit from "
        "Exception is used as an exception in an except clause.",
    ),
    "W0702": (
        "No exception type(s) specified",
        "bare-except",
        "A bare ``except:`` clause will catch ``SystemExit`` and "
        "``KeyboardInterrupt`` exceptions, making it harder to interrupt a program "
        "with ``Control-C``, and can disguise other problems. If you want to catch "
        "all exceptions that signal program errors, use ``except Exception:`` (bare "
        "except is equivalent to ``except BaseException:``).",
    ),
    "W0718": (
        "Catching too general exception %s",
        "broad-exception-caught",
        "If you use a naked ``except Exception:`` clause, you might end up catching "
        "exceptions other than the ones you expect to catch. This can hide bugs or "
        "make it harder to debug programs when unrelated errors are hidden.",
        {"old_names": [("W0703", "broad-except")]},
    ),
    "W0705": (
        "Catching previously caught exception type %s",
        "duplicate-except",
        "Used when an except catches a type that was already caught by "
        "a previous handler.",
    ),
    "W0706": (
        "The except handler raises immediately",
        "try-except-raise",
        "Used when an except handler uses raise as its first or only "
        "operator. This is useless because it raises back the exception "
        "immediately. Remove the raise operator or the entire "
        "try-except-raise block!",
    ),
    "W0707": (
        "Consider explicitly re-raising using %s'%s from %s'",
        "raise-missing-from",
        "Python's exception chaining shows the traceback of the current exception, "
        "but also of the original exception. When you raise a new exception after "
        "another exception was caught it's likely that the second exception is a "
        "friendly re-wrapping of the first exception. In such cases `raise from` "
        "provides a better link between the two tracebacks in the final error.",
    ),
    "W0711": (
        'Exception to catch is the result of a binary "%s" operation',
        "binary-op-exception",
        "Used when the exception to catch is of the form "
        '"except A or B:".  If intending to catch multiple, '
        'rewrite as "except (A, B):"',
    ),
    "W0715": (
        "Exception arguments suggest string formatting might be intended",
        "raising-format-tuple",
        "Used when passing multiple arguments to an exception "
        "constructor, the first of them a string literal containing what "
        "appears to be placeholders intended for formatting",
    ),
    "W0716": (
        "Invalid exception operation. %s",
        "wrong-exception-operation",
        "Used when an operation is done against an exception, but the operation "
        "is not valid for the exception in question. Usually emitted when having "
        "binary operations between exceptions in except handlers.",
    ),
    "W0719": (
        "Raising too general exception: %s",
        "broad-exception-raised",
        "Raising exceptions that are too generic force you to catch exceptions "
        "generically too. It will force you to use a naked ``except Exception:`` "
        "clause. You might then end up catching exceptions other than the ones "
        "you expect to catch. This can hide bugs or make it harder to debug programs "
        "when unrelated errors are hidden.",
    ),
}


class BaseVisitor:
    """Base class for visitors defined in this module."""

    def __init__(self, checker: ExceptionsChecker, node: nodes.Raise) -> None:
        self._checker = checker
        self._node = node

    def visit(self, node: SuccessfulInferenceResult) -> None:
        name = node.__class__.__name__.lower()
        dispatch_meth = getattr(self, "visit_" + name, None)
        if dispatch_meth:
            dispatch_meth(node)
        else:
            self.visit_default(node)

    def visit_default(self, _: nodes.NodeNG) -> None:
        """Default implementation for all the nodes."""


class ExceptionRaiseRefVisitor(BaseVisitor):
    """Visit references (anything that is not an AST leaf)."""

    def visit_name(self, node: nodes.Name) -> None:
        if node.name == "NotImplemented":
            self._checker.add_message(
                "notimplemented-raised", node=self._node, confidence=HIGH
            )
            return

        try:
            exceptions = list(_annotated_unpack_infer(node))
        except astroid.InferenceError:
            return

        for _, exception in exceptions:
            if isinstance(
                exception, nodes.ClassDef
            ) and self._checker._is_overgeneral_exception(exception):
                self._checker.add_message(
                    "broad-exception-raised",
                    args=exception.name,
                    node=self._node,
                    confidence=INFERENCE,
                )

    def visit_call(self, node: nodes.Call) -> None:
        if isinstance(node.func, nodes.Name):
            self.visit_name(node.func)
        if (
            len(node.args) > 1
            and isinstance(node.args[0], nodes.Const)
            and isinstance(node.args[0].value, str)
        ):
            msg = node.args[0].value
            if "%" in msg or ("{" in msg and "}" in msg):
                self._checker.add_message(
                    "raising-format-tuple", node=self._node, confidence=HIGH
                )


class ExceptionRaiseLeafVisitor(BaseVisitor):
    """Visitor for handling leaf kinds of a raise value."""

    def visit_const(self, node: nodes.Const) -> None:
        self._checker.add_message(
            "raising-bad-type",
            node=self._node,
            args=node.value.__class__.__name__,
            confidence=INFERENCE,
        )

    def visit_instance(self, instance: objects.ExceptionInstance) -> None:
        cls = instance._proxied
        self.visit_classdef(cls)

    # Exception instances have a particular class type
    visit_exceptioninstance = visit_instance

    def visit_classdef(self, node: nodes.ClassDef) -> None:
        if not utils.inherit_from_std_ex(node) and utils.has_known_bases(node):
            if node.newstyle:
                self._checker.add_message(
                    "raising-non-exception",
                    node=self._node,
                    confidence=INFERENCE,
                )

    def visit_tuple(self, _: nodes.Tuple) -> None:
        self._checker.add_message(
            "raising-bad-type",
            node=self._node,
            args="tuple",
            confidence=INFERENCE,
        )

    def visit_default(self, node: nodes.NodeNG) -> None:
        name = getattr(node, "name", node.__class__.__name__)
        self._checker.add_message(
            "raising-bad-type",
            node=self._node,
            args=name,
            confidence=INFERENCE,
        )


class ExceptionsChecker(checkers.BaseChecker):
    """Exception related checks."""

    name = "exceptions"
    msgs = MSGS
    options = (
        (
            "overgeneral-exceptions",
            {
                "default": ("builtins.BaseException", "builtins.Exception"),
                "type": "csv",
                "metavar": "<comma-separated class names>",
                "help": "Exceptions that will emit a warning when caught.",
            },
        ),
    )

    def open(self) -> None:
        self._builtin_exceptions = _builtin_exceptions()
        for exc_name in self.linter.config.overgeneral_exceptions:
            if "." not in exc_name:
                warnings.warn_explicit(
                    "Specifying exception names in the overgeneral-exceptions option"
                    " without module name is deprecated and support for it"
                    " will be removed in pylint 3.0."
                    f" Use fully qualified name (maybe 'builtins.{exc_name}' ?) instead.",
                    category=UserWarning,
                    filename="pylint: Command line or configuration file",
                    lineno=1,
                    module="pylint",
                )
        super().open()

    @utils.only_required_for_messages(
        "misplaced-bare-raise",
        "raising-bad-type",
        "raising-non-exception",
        "notimplemented-raised",
        "bad-exception-cause",
        "raising-format-tuple",
        "raise-missing-from",
        "broad-exception-raised",
    )
    def visit_raise(self, node: nodes.Raise) -> None:
        if node.exc is None:
            self._check_misplaced_bare_raise(node)
            return

        if node.cause is None:
            self._check_raise_missing_from(node)
        else:
            self._check_bad_exception_cause(node)

        expr = node.exc
        ExceptionRaiseRefVisitor(self, node).visit(expr)

        inferred = utils.safe_infer(expr)
        if inferred is None or isinstance(inferred, util.UninferableBase):
            return
        ExceptionRaiseLeafVisitor(self, node).visit(inferred)

    def _check_misplaced_bare_raise(self, node: nodes.Raise) -> None:
        # Filter out if it's present in __exit__.
        scope = node.scope()
        if (
            isinstance(scope, nodes.FunctionDef)
            and scope.is_method()
            and scope.name == "__exit__"
        ):
            return

        current = node
        # Stop when a new scope is generated or when the raise
        # statement is found inside a TryFinally.
        ignores = (nodes.ExceptHandler, nodes.FunctionDef)
        while current and not isinstance(current.parent, ignores):
            current = current.parent

        expected = (nodes.ExceptHandler,)
        if not current or not isinstance(current.parent, expected):
            self.add_message("misplaced-bare-raise", node=node, confidence=HIGH)

    def _check_bad_exception_cause(self, node: nodes.Raise) -> None:
        """Verify that the exception cause is properly set.

        An exception cause can be only `None` or an exception.
        """
        cause = utils.safe_infer(node.cause)
        if cause is None or isinstance(cause, util.UninferableBase):
            return

        if isinstance(cause, nodes.Const):
            if cause.value is not None:
                self.add_message("bad-exception-cause", node=node, confidence=INFERENCE)
        elif not isinstance(cause, nodes.ClassDef) and not utils.inherit_from_std_ex(
            cause
        ):
            self.add_message("bad-exception-cause", node=node, confidence=INFERENCE)

    def _check_raise_missing_from(self, node: nodes.Raise) -> None:
        if node.exc is None:
            # This is a plain `raise`, raising the previously-caught exception. No need for a
            # cause.
            return
        # We'd like to check whether we're inside an `except` clause:
        containing_except_node = utils.find_except_wrapper_node_in_scope(node)
        if not containing_except_node:
            return
        # We found a surrounding `except`! We're almost done proving there's a
        # `raise-missing-from` here. The only thing we need to protect against is that maybe
        # the `raise` is raising the exception that was caught, possibly with some shenanigans
        # like `exc.with_traceback(whatever)`. We won't analyze these, we'll just assume
        # there's a violation on two simple cases: `raise SomeException(whatever)` and `raise
        # SomeException`.
        if containing_except_node.name is None:
            # The `except` doesn't have an `as exception:` part, meaning there's no way that
            # the `raise` is raising the same exception.
            class_of_old_error = "Exception"
            if isinstance(containing_except_node.type, (nodes.Name, nodes.Tuple)):
                # 'except ZeroDivisionError' or 'except (ZeroDivisionError, ValueError)'
                class_of_old_error = containing_except_node.type.as_string()
            self.add_message(
                "raise-missing-from",
                node=node,
                args=(
                    f"'except {class_of_old_error} as exc' and ",
                    node.as_string(),
                    "exc",
                ),
                confidence=HIGH,
            )
        elif (
            isinstance(node.exc, nodes.Call)
            and isinstance(node.exc.func, nodes.Name)
            or isinstance(node.exc, nodes.Name)
            and node.exc.name != containing_except_node.name.name
        ):
            # We have a `raise SomeException(whatever)` or a `raise SomeException`
            self.add_message(
                "raise-missing-from",
                node=node,
                args=("", node.as_string(), containing_except_node.name.name),
                confidence=HIGH,
            )

    def _check_catching_non_exception(
        self,
        handler: nodes.ExceptHandler,
        exc: SuccessfulInferenceResult,
        part: nodes.NodeNG,
    ) -> None:
        if isinstance(exc, nodes.Tuple):
            # Check if it is a tuple of exceptions.
            inferred = [utils.safe_infer(elt) for elt in exc.elts]
            if any(isinstance(node, util.UninferableBase) for node in inferred):
                # Don't emit if we don't know every component.
                return
            if all(
                node
                and (utils.inherit_from_std_ex(node) or not utils.has_known_bases(node))
                for node in inferred
            ):
                return

        if not isinstance(exc, nodes.ClassDef):
            # Don't emit the warning if the inferred stmt
            # is None, but the exception handler is something else,
            # maybe it was redefined.
            if isinstance(exc, nodes.Const) and exc.value is None:
                if (
                    isinstance(handler.type, nodes.Const) and handler.type.value is None
                ) or handler.type.parent_of(exc):
                    # If the exception handler catches None or
                    # the exception component, which is None, is
                    # defined by the entire exception handler, then
                    # emit a warning.
                    self.add_message(
                        "catching-non-exception",
                        node=handler.type,
                        args=(part.as_string(),),
                    )
            else:
                self.add_message(
                    "catching-non-exception",
                    node=handler.type,
                    args=(part.as_string(),),
                )
            return

        if (
            not utils.inherit_from_std_ex(exc)
            and exc.name not in self._builtin_exceptions
        ):
            if utils.has_known_bases(exc):
                self.add_message(
                    "catching-non-exception", node=handler.type, args=(exc.name,)
                )

    def _check_try_except_raise(self, node: nodes.TryExcept) -> None:
        def gather_exceptions_from_handler(
            handler: nodes.ExceptHandler,
        ) -> list[InferenceResult] | None:
            exceptions: list[InferenceResult] = []
            if handler.type:
                exceptions_in_handler = utils.safe_infer(handler.type)
                if isinstance(exceptions_in_handler, nodes.Tuple):
                    exceptions = list(
                        {
                            exception
                            for exception in exceptions_in_handler.elts
                            if isinstance(exception, (nodes.Name, nodes.Attribute))
                        }
                    )
                elif exceptions_in_handler:
                    exceptions = [exceptions_in_handler]
                else:
                    # Break when we cannot infer anything reliably.
                    return None
            return exceptions

        bare_raise = False
        handler_having_bare_raise = None
        exceptions_in_bare_handler: list[InferenceResult] | None = []
        for handler in node.handlers:
            if bare_raise:
                # check that subsequent handler is not parent of handler which had bare raise.
                # since utils.safe_infer can fail for bare except, check it before.
                # also break early if bare except is followed by bare except.

                excs_in_current_handler = gather_exceptions_from_handler(handler)
                if not excs_in_current_handler:
                    break
                if exceptions_in_bare_handler is None:
                    # It can be `None` when the inference failed
                    break
                for exc_in_current_handler in excs_in_current_handler:
                    inferred_current = utils.safe_infer(exc_in_current_handler)
                    if any(
                        utils.is_subclass_of(utils.safe_infer(e), inferred_current)
                        for e in exceptions_in_bare_handler
                    ):
                        bare_raise = False
                        break

            # `raise` as the first operator inside the except handler
            if _is_raising([handler.body[0]]):
                # flags when there is a bare raise
                if handler.body[0].exc is None:
                    bare_raise = True
                    handler_having_bare_raise = handler
                    exceptions_in_bare_handler = gather_exceptions_from_handler(handler)
        else:
            if bare_raise:
                self.add_message("try-except-raise", node=handler_having_bare_raise)

    @utils.only_required_for_messages("wrong-exception-operation")
    def visit_binop(self, node: nodes.BinOp) -> None:
        if isinstance(node.parent, nodes.ExceptHandler):
            # except (V | A)
            suggestion = f"Did you mean '({node.left.as_string()}, {node.right.as_string()})' instead?"
            self.add_message("wrong-exception-operation", node=node, args=(suggestion,))

    @utils.only_required_for_messages("wrong-exception-operation")
    def visit_compare(self, node: nodes.Compare) -> None:
        if isinstance(node.parent, nodes.ExceptHandler):
            # except (V < A)
            suggestion = (
                f"Did you mean '({node.left.as_string()}, "
                f"{', '.join(o.as_string() for _, o in node.ops)})' instead?"
            )
            self.add_message("wrong-exception-operation", node=node, args=(suggestion,))

    @utils.only_required_for_messages(
        "bare-except",
        "broad-exception-caught",
        "try-except-raise",
        "binary-op-exception",
        "bad-except-order",
        "catching-non-exception",
        "duplicate-except",
    )
    def visit_tryexcept(self, node: nodes.TryExcept) -> None:
        """Check for empty except."""
        self._check_try_except_raise(node)
        exceptions_classes: list[Any] = []
        nb_handlers = len(node.handlers)
        for index, handler in enumerate(node.handlers):
            if handler.type is None:
                if not _is_raising(handler.body):
                    self.add_message("bare-except", node=handler, confidence=HIGH)

                # check if an "except:" is followed by some other
                # except
                if index < (nb_handlers - 1):
                    msg = "empty except clause should always appear last"
                    self.add_message(
                        "bad-except-order", node=node, args=msg, confidence=HIGH
                    )

            elif isinstance(handler.type, nodes.BoolOp):
                self.add_message(
                    "binary-op-exception",
                    node=handler,
                    args=handler.type.op,
                    confidence=HIGH,
                )
            else:
                try:
                    exceptions = list(_annotated_unpack_infer(handler.type))
                except astroid.InferenceError:
                    continue

                for part, exception in exceptions:
                    if isinstance(
                        exception, astroid.Instance
                    ) and utils.inherit_from_std_ex(exception):
                        exception = exception._proxied

                    self._check_catching_non_exception(handler, exception, part)

                    if not isinstance(exception, nodes.ClassDef):
                        continue

                    exc_ancestors = [
                        anc
                        for anc in exception.ancestors()
                        if isinstance(anc, nodes.ClassDef)
                    ]

                    for previous_exc in exceptions_classes:
                        if previous_exc in exc_ancestors:
                            msg = f"{previous_exc.name} is an ancestor class of {exception.name}"
                            self.add_message(
                                "bad-except-order",
                                node=handler.type,
                                args=msg,
                                confidence=INFERENCE,
                            )
                    if self._is_overgeneral_exception(exception) and not _is_raising(
                        handler.body
                    ):
                        self.add_message(
                            "broad-exception-caught",
                            args=exception.name,
                            node=handler.type,
                            confidence=INFERENCE,
                        )

                    if exception in exceptions_classes:
                        self.add_message(
                            "duplicate-except",
                            args=exception.name,
                            node=handler.type,
                            confidence=INFERENCE,
                        )

                exceptions_classes += [exc for _, exc in exceptions]

    def _is_overgeneral_exception(self, exception: nodes.ClassDef) -> bool:
        return (
            exception.qname() in self.linter.config.overgeneral_exceptions
            # TODO: 3.0: not a qualified name, deprecated
            or "." not in exception.name
            and exception.name in self.linter.config.overgeneral_exceptions
            and exception.root().name == utils.EXCEPTIONS_MODULE
        )


def register(linter: PyLinter) -> None:
    linter.register_checker(ExceptionsChecker(linter))