Edit File: special_methods_checker.py
# 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 """Special methods checker and helper function's module.""" from __future__ import annotations from collections.abc import Callable import astroid from astroid import bases, nodes, util from astroid.context import InferenceContext from astroid.typing import InferenceResult from pylint.checkers import BaseChecker from pylint.checkers.utils import ( PYMETHODS, SPECIAL_METHODS_PARAMS, decorated_with, is_function_body_ellipsis, only_required_for_messages, safe_infer, ) from pylint.lint.pylinter import PyLinter NEXT_METHOD = "__next__" def _safe_infer_call_result( node: nodes.FunctionDef, caller: nodes.FunctionDef, context: InferenceContext | None = None, ) -> InferenceResult | None: """Safely infer the return value of a function. Returns None if inference failed or if there is some ambiguity (more than one node has been inferred). Otherwise, returns inferred value. """ try: inferit = node.infer_call_result(caller, context=context) value = next(inferit) except astroid.InferenceError: return None # inference failed except StopIteration: return None # no values inferred try: next(inferit) return None # there is ambiguity on the inferred node except astroid.InferenceError: return None # there is some kind of ambiguity except StopIteration: return value class SpecialMethodsChecker(BaseChecker): """Checker which verifies that special methods are implemented correctly. """ name = "classes" msgs = { "E0301": ( "__iter__ returns non-iterator", "non-iterator-returned", "Used when an __iter__ method returns something which is not an " f"iterable (i.e. has no `{NEXT_METHOD}` method)", { "old_names": [ ("W0234", "old-non-iterator-returned-1"), ("E0234", "old-non-iterator-returned-2"), ] }, ), "E0302": ( "The special method %r expects %s param(s), %d %s given", "unexpected-special-method-signature", "Emitted when a special method was defined with an " "invalid number of parameters. If it has too few or " "too many, it might not work at all.", {"old_names": [("E0235", "bad-context-manager")]}, ), "E0303": ( "__len__ does not return non-negative integer", "invalid-length-returned", "Used when a __len__ method returns something which is not a " "non-negative integer", ), "E0304": ( "__bool__ does not return bool", "invalid-bool-returned", "Used when a __bool__ method returns something which is not a bool", ), "E0305": ( "__index__ does not return int", "invalid-index-returned", "Used when an __index__ method returns something which is not " "an integer", ), "E0306": ( "__repr__ does not return str", "invalid-repr-returned", "Used when a __repr__ method returns something which is not a string", ), "E0307": ( "__str__ does not return str", "invalid-str-returned", "Used when a __str__ method returns something which is not a string", ), "E0308": ( "__bytes__ does not return bytes", "invalid-bytes-returned", "Used when a __bytes__ method returns something which is not bytes", ), "E0309": ( "__hash__ does not return int", "invalid-hash-returned", "Used when a __hash__ method returns something which is not an integer", ), "E0310": ( "__length_hint__ does not return non-negative integer", "invalid-length-hint-returned", "Used when a __length_hint__ method returns something which is not a " "non-negative integer", ), "E0311": ( "__format__ does not return str", "invalid-format-returned", "Used when a __format__ method returns something which is not a string", ), "E0312": ( "__getnewargs__ does not return a tuple", "invalid-getnewargs-returned", "Used when a __getnewargs__ method returns something which is not " "a tuple", ), "E0313": ( "__getnewargs_ex__ does not return a tuple containing (tuple, dict)", "invalid-getnewargs-ex-returned", "Used when a __getnewargs_ex__ method returns something which is not " "of the form tuple(tuple, dict)", ), } def __init__(self, linter: PyLinter) -> None: super().__init__(linter) self._protocol_map: dict[ str, Callable[[nodes.FunctionDef, InferenceResult], None] ] = { "__iter__": self._check_iter, "__len__": self._check_len, "__bool__": self._check_bool, "__index__": self._check_index, "__repr__": self._check_repr, "__str__": self._check_str, "__bytes__": self._check_bytes, "__hash__": self._check_hash, "__length_hint__": self._check_length_hint, "__format__": self._check_format, "__getnewargs__": self._check_getnewargs, "__getnewargs_ex__": self._check_getnewargs_ex, } @only_required_for_messages( "unexpected-special-method-signature", "non-iterator-returned", "invalid-length-returned", "invalid-bool-returned", "invalid-index-returned", "invalid-repr-returned", "invalid-str-returned", "invalid-bytes-returned", "invalid-hash-returned", "invalid-length-hint-returned", "invalid-format-returned", "invalid-getnewargs-returned", "invalid-getnewargs-ex-returned", ) def visit_functiondef(self, node: nodes.FunctionDef) -> None: if not node.is_method(): return inferred = _safe_infer_call_result(node, node) # Only want to check types that we are able to infer if ( inferred and node.name in self._protocol_map and not is_function_body_ellipsis(node) ): self._protocol_map[node.name](node, inferred) if node.name in PYMETHODS: self._check_unexpected_method_signature(node) visit_asyncfunctiondef = visit_functiondef def _check_unexpected_method_signature(self, node: nodes.FunctionDef) -> None: expected_params = SPECIAL_METHODS_PARAMS[node.name] if expected_params is None: # This can support a variable number of parameters. return if not node.args.args and not node.args.vararg: # Method has no parameter, will be caught # by no-method-argument. return if decorated_with(node, ["builtins.staticmethod"]): # We expect to not take in consideration self. all_args = node.args.args else: all_args = node.args.args[1:] mandatory = len(all_args) - len(node.args.defaults) optional = len(node.args.defaults) current_params = mandatory + optional emit = False # If we don't know we choose a false negative if isinstance(expected_params, tuple): # The expected number of parameters can be any value from this # tuple, although the user should implement the method # to take all of them in consideration. emit = mandatory not in expected_params # mypy thinks that expected_params has type tuple[int, int] | int | None # But at this point it must be 'tuple[int, int]' because of the type check expected_params = f"between {expected_params[0]} or {expected_params[1]}" # type: ignore[assignment] else: # If the number of mandatory parameters doesn't # suffice, the expected parameters for this # function will be deduced from the optional # parameters. rest = expected_params - mandatory if rest == 0: emit = False elif rest < 0: emit = True elif rest > 0: emit = not ((optional - rest) >= 0 or node.args.vararg) if emit: verb = "was" if current_params <= 1 else "were" self.add_message( "unexpected-special-method-signature", args=(node.name, expected_params, current_params, verb), node=node, ) @staticmethod def _is_wrapped_type(node: InferenceResult, type_: str) -> bool: return ( isinstance(node, bases.Instance) and node.name == type_ and not isinstance(node, nodes.Const) ) @staticmethod def _is_int(node: InferenceResult) -> bool: if SpecialMethodsChecker._is_wrapped_type(node, "int"): return True return isinstance(node, nodes.Const) and isinstance(node.value, int) @staticmethod def _is_str(node: InferenceResult) -> bool: if SpecialMethodsChecker._is_wrapped_type(node, "str"): return True return isinstance(node, nodes.Const) and isinstance(node.value, str) @staticmethod def _is_bool(node: InferenceResult) -> bool: if SpecialMethodsChecker._is_wrapped_type(node, "bool"): return True return isinstance(node, nodes.Const) and isinstance(node.value, bool) @staticmethod def _is_bytes(node: InferenceResult) -> bool: if SpecialMethodsChecker._is_wrapped_type(node, "bytes"): return True return isinstance(node, nodes.Const) and isinstance(node.value, bytes) @staticmethod def _is_tuple(node: InferenceResult) -> bool: if SpecialMethodsChecker._is_wrapped_type(node, "tuple"): return True return isinstance(node, nodes.Const) and isinstance(node.value, tuple) @staticmethod def _is_dict(node: InferenceResult) -> bool: if SpecialMethodsChecker._is_wrapped_type(node, "dict"): return True return isinstance(node, nodes.Const) and isinstance(node.value, dict) @staticmethod def _is_iterator(node: InferenceResult) -> bool: if isinstance(node, bases.Generator): # Generators can be iterated. return True if isinstance(node, nodes.ComprehensionScope): # Comprehensions can be iterated. return True if isinstance(node, bases.Instance): try: node.local_attr(NEXT_METHOD) return True except astroid.NotFoundError: pass elif isinstance(node, nodes.ClassDef): metaclass = node.metaclass() if metaclass and isinstance(metaclass, nodes.ClassDef): try: metaclass.local_attr(NEXT_METHOD) return True except astroid.NotFoundError: pass return False def _check_iter(self, node: nodes.FunctionDef, inferred: InferenceResult) -> None: if not self._is_iterator(inferred): self.add_message("non-iterator-returned", node=node) def _check_len(self, node: nodes.FunctionDef, inferred: InferenceResult) -> None: if not self._is_int(inferred): self.add_message("invalid-length-returned", node=node) elif isinstance(inferred, nodes.Const) and inferred.value < 0: self.add_message("invalid-length-returned", node=node) def _check_bool(self, node: nodes.FunctionDef, inferred: InferenceResult) -> None: if not self._is_bool(inferred): self.add_message("invalid-bool-returned", node=node) def _check_index(self, node: nodes.FunctionDef, inferred: InferenceResult) -> None: if not self._is_int(inferred): self.add_message("invalid-index-returned", node=node) def _check_repr(self, node: nodes.FunctionDef, inferred: InferenceResult) -> None: if not self._is_str(inferred): self.add_message("invalid-repr-returned", node=node) def _check_str(self, node: nodes.FunctionDef, inferred: InferenceResult) -> None: if not self._is_str(inferred): self.add_message("invalid-str-returned", node=node) def _check_bytes(self, node: nodes.FunctionDef, inferred: InferenceResult) -> None: if not self._is_bytes(inferred): self.add_message("invalid-bytes-returned", node=node) def _check_hash(self, node: nodes.FunctionDef, inferred: InferenceResult) -> None: if not self._is_int(inferred): self.add_message("invalid-hash-returned", node=node) def _check_length_hint( self, node: nodes.FunctionDef, inferred: InferenceResult ) -> None: if not self._is_int(inferred): self.add_message("invalid-length-hint-returned", node=node) elif isinstance(inferred, nodes.Const) and inferred.value < 0: self.add_message("invalid-length-hint-returned", node=node) def _check_format(self, node: nodes.FunctionDef, inferred: InferenceResult) -> None: if not self._is_str(inferred): self.add_message("invalid-format-returned", node=node) def _check_getnewargs( self, node: nodes.FunctionDef, inferred: InferenceResult ) -> None: if not self._is_tuple(inferred): self.add_message("invalid-getnewargs-returned", node=node) def _check_getnewargs_ex( self, node: nodes.FunctionDef, inferred: InferenceResult ) -> None: if not self._is_tuple(inferred): self.add_message("invalid-getnewargs-ex-returned", node=node) return if not isinstance(inferred, nodes.Tuple): # If it's not an astroid.Tuple we can't analyze it further return found_error = False if len(inferred.elts) != 2: found_error = True else: for arg, check in ( (inferred.elts[0], self._is_tuple), (inferred.elts[1], self._is_dict), ): if isinstance(arg, nodes.Call): arg = safe_infer(arg) if arg and not isinstance(arg, util.UninferableBase): if not check(arg): found_error = True break if found_error: self.add_message("invalid-getnewargs-ex-returned", node=node)