python-constricter 0.2.2__py3-none-any.whl → 0.2.3__py3-none-any.whl

constricter/__init__.py

@@ -7,6 +7,7 @@ from constricter.checker import (
     LEVELS,
     NESTED_TYPE,
     NESTING,
+    REDUNDANT_TYPE,
     UNANNOTATED,
     UNANNOTATED_MEMBER,
     UNTYPED_TARGET,
@@ -20,13 +21,14 @@ from constricter.checker import (
     check_tree,
 )
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 __all__ = [
     "COMMENT_TYPED_TARGET",
     "DEFAULT_CHECKS",
     "LEVELS",
     "NESTED_TYPE",
     "NESTING",
+    "REDUNDANT_TYPE",
     "UNANNOTATED",
     "UNANNOTATED_MEMBER",
     "UNTYPED_TARGET",

constricter/annotations.py

@@ -3,7 +3,8 @@
 
 import ast
 import re
-from collections.abc import Mapping, Sequence
+from collections.abc import Iterator, Mapping, Sequence
+from functools import lru_cache
 from typing import TYPE_CHECKING, Final, cast
 
 if TYPE_CHECKING:
@@ -75,11 +76,226 @@ _FACTORIES: Final = frozenset(
 )
 _NUMBERS: Final = (int, float, complex)
 _TYPE_VARS: Final = frozenset({"TypeVar", "ParamSpec", "TypeVarTuple"})
+# Builtins whose return type is fixed by the language, whatever their argument: safe to infer, not
+# a guess (unlike a capitalised call, which could really be a generic class or a factory function).
+_BUILTIN_RETURNS: Final = {
+    "bool": "bool",
+    "bytes": "bytes",
+    "callable": "bool",
+    "chr": "str",
+    "complex": "complex",
+    "float": "float",
+    "hasattr": "bool",
+    "hash": "int",
+    "id": "int",
+    "int": "int",
+    "isinstance": "bool",
+    "issubclass": "bool",
+    "len": "int",
+    "ord": "int",
+    "repr": "str",
+    "str": "str",
+}
+# Modules `_FACTORIES`' names are imported from (so an aliased or re-exported import is still found).
+_FACTORY_MODULES: Final = frozenset({"enum", "typing", "typing_extensions"})
+# `str`/`bytes` methods whose return type is fixed by the language, whatever their arguments: safe
+# to infer for a call on an already-typed local, not a guess.
+_STR_METHODS: Final = {
+    "capitalize": "str",
+    "casefold": "str",
+    "center": "str",
+    "count": "int",
+    "encode": "bytes",
+    "endswith": "bool",
+    "expandtabs": "str",
+    "find": "int",
+    "format": "str",
+    "format_map": "str",
+    "index": "int",
+    "isalnum": "bool",
+    "isalpha": "bool",
+    "isascii": "bool",
+    "isdecimal": "bool",
+    "isdigit": "bool",
+    "isidentifier": "bool",
+    "islower": "bool",
+    "isnumeric": "bool",
+    "isprintable": "bool",
+    "isspace": "bool",
+    "istitle": "bool",
+    "isupper": "bool",
+    "join": "str",
+    "ljust": "str",
+    "lower": "str",
+    "lstrip": "str",
+    "removeprefix": "str",
+    "removesuffix": "str",
+    "replace": "str",
+    "rfind": "int",
+    "rindex": "int",
+    "rjust": "str",
+    "rsplit": "list[str]",
+    "rstrip": "str",
+    "split": "list[str]",
+    "splitlines": "list[str]",
+    "startswith": "bool",
+    "strip": "str",
+    "swapcase": "str",
+    "title": "str",
+    "translate": "str",
+    "upper": "str",
+    "zfill": "str",
+}
+_BYTES_METHODS: Final = {
+    "capitalize": "bytes",
+    "center": "bytes",
+    "count": "int",
+    "decode": "str",
+    "endswith": "bool",
+    "expandtabs": "bytes",
+    "find": "int",
+    "hex": "str",
+    "index": "int",
+    "isalnum": "bool",
+    "isalpha": "bool",
+    "isascii": "bool",
+    "isdigit": "bool",
+    "islower": "bool",
+    "isspace": "bool",
+    "istitle": "bool",
+    "isupper": "bool",
+    "join": "bytes",
+    "ljust": "bytes",
+    "lower": "bytes",
+    "lstrip": "bytes",
+    "removeprefix": "bytes",
+    "removesuffix": "bytes",
+    "replace": "bytes",
+    "rfind": "int",
+    "rindex": "int",
+    "rjust": "bytes",
+    "rsplit": "list[bytes]",
+    "rstrip": "bytes",
+    "split": "list[bytes]",
+    "splitlines": "list[bytes]",
+    "startswith": "bool",
+    "strip": "bytes",
+    "swapcase": "bytes",
+    "title": "bytes",
+    "translate": "bytes",
+    "upper": "bytes",
+    "zfill": "bytes",
+}
+_METHOD_RETURNS: Final = {"str": _STR_METHODS, "bytes": _BYTES_METHODS}
+
+
+def _method_return(receiver: str, method: str) -> str | None:
+    """Look up `method`'s return type on a receiver whose own type is `receiver`, as text.
 
+    Returns:
+      The annotation as source text, or `None` if `receiver` isn't `str`/`bytes`, or `method` isn't
+      one of `_METHOD_RETURNS`'.
+
+    """
+    return _METHOD_RETURNS.get(receiver, {}).get(method)
+
+
+def imported_from(tree: ast.Module, modules: frozenset[str]) -> frozenset[str]:
+    """Find the top-level names this module imports (`from module import name`) from one of `modules`.
+
+    Only absolute imports are resolved; a relative one (`from . import x`) names no module here.
+
+    Returns:
+      Those names, as they're bound here (their alias, if importing gave them one).
+
+    """
+    names: set[str] = set()
+    stmt: ast.stmt
+    module: str
+    for stmt in tree.body:
+        match stmt:
+            case ast.ImportFrom(module=str() as module, level=0) if module in modules:
+                names.update(alias.asname or alias.name for alias in stmt.names)
+            case _:
+                pass
+    return frozenset(names)
+
+
+def factories(tree: ast.Module) -> frozenset[str]:
+    """Find names this module imports that are known to build a class or special form.
+
+    Not an instance of what they're named (`Enum`, `NamedTuple`, `TypeVar`, ... from `enum`,
+    `typing` or `typing_extensions`), however they're aliased.
+
+    Returns:
+      Those names, as they're bound here.
+
+    """
+    return imported_from(tree, _FACTORY_MODULES)
+
+
+def classes(tree: ast.Module) -> dict[str, dict[str, str]]:
+    """Map each class defined in the module to its annotated attributes.
+
+    A class-body annotation (`class C: x: int`) and a `self.x: int = ...` annotated assignment
+    anywhere in one of its methods both count; a name that names more than one class in the module
+    (however unlikely) gets the last one's attributes.
+
+    Returns:
+      Each class's name, mapped to its attributes' names and annotation text.
+
+    """
+    found: dict[str, dict[str, str]] = {}
+    node: ast.AST
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            found[node.name] = _attributes(node)
+    return found
+
+
+def _attributes(node: ast.ClassDef) -> dict[str, str]:
+    attrs: dict[str, str] = {}
+    stmt: ast.stmt
+    name: str
+    annotation: ast.expr
+    for stmt in node.body:
+        match stmt:
+            case ast.AnnAssign(target=ast.Name(id=name), annotation=annotation):
+                attrs[name] = ast.unparse(annotation)
+            case ast.FunctionDef() | ast.AsyncFunctionDef():
+                attrs.update(_self_attributes(stmt))
+            case _:
+                pass
+    return attrs
 
+
+def _self_attributes(func: ast.FunctionDef | ast.AsyncFunctionDef) -> Iterator[tuple[str, str]]:
+    """Find `self.attr: T = ...` annotated assignments anywhere in a method's body.
+
+    Yields:
+      Each attribute's name and annotation text.
+
+    """
+    node: ast.AST
+    name: str
+    annotation: ast.expr
+    for node in ast.walk(func):
+        match node:
+            case ast.AnnAssign(
+                target=ast.Attribute(value=ast.Name(id="self"), attr=name),
+                annotation=annotation,
+            ):
+                yield name, ast.unparse(annotation)
+            case _:
+                pass
+
+
+@lru_cache(maxsize=256)
 def _parsed(annotation: ast.expr) -> ast.expr:
     """Unwrap a string annotation.
 
+    `is_vague` and `depth` both call this on the same annotation; cached so it's parsed once.
+
     Returns:
       Its parsed expression, or the annotation itself if it isn't a string.
 
@@ -92,7 +308,13 @@ def _parsed(annotation: ast.expr) -> ast.expr:
     return annotation
 
 
-def _name(node: ast.AST) -> str:
+def node_name(node: ast.AST) -> str:
+    """Read a `Name`'s or `Attribute`'s simple name.
+
+    Returns:
+      It, or `""` if `node` is neither.
+
+    """
     name: str
     match node:
         case ast.Name(id=name) | ast.Attribute(attr=name):
@@ -112,7 +334,7 @@ def is_vague(annotation: ast.expr) -> bool:
     subscripted: set[int] = {id(node.value) for node in ast.walk(root) if isinstance(node, ast.Subscript)}
     node: ast.AST
     for node in ast.walk(root):
-        name: str = _name(node)
+        name: str = node_name(node)
         if name in _VAGUE or (name in _GENERICS and id(node) not in subscripted):
             return True
     return False
@@ -160,7 +382,7 @@ def returns(tree: ast.Module) -> dict[str, str]:
     for stmt in tree.body:
         match stmt:
             case ast.Assign(targets=[ast.Name(id=name)], value=ast.Call(func=func)) if (
-                _name(func) in _TYPE_VARS
+                node_name(func) in _TYPE_VARS
             ):
                 type_vars.add(name)
             case ast.FunctionDef(name=name) | ast.AsyncFunctionDef(name=name):
@@ -196,17 +418,56 @@ def _words(annotation: str) -> list[str]:
     return [word for word in re.split(r"\W+", annotation) if word]
 
 
-def inferred(value: ast.expr, calls: Mapping[str, str]) -> str | None:
+def inferred(
+    value: ast.expr,
+    calls: Mapping[str, str],
+    known_factories: frozenset[str],
+    declared: Mapping[str, str],
+    known_classes: Mapping[str, Mapping[str, str]],
+) -> str | None:
     """Return the annotation `value` makes unambiguous, given the module's function `calls`.
 
     A literal's type (containers too, when their elements agree), a call to a module function that
-    declares its return type, or a class it constructs.
+    declares its return type, a class it constructs, or (`declared`) another local this scope
+    already gave a type: a plain copy, a subscript of a known container, or (`known_classes`, see
+    `classes`) an attribute of a class defined in this module. `known_factories` (see `factories`)
+    are calls that build a class or special form rather than an instance of it, so they're never
+    guessed to construct one.
 
     Returns:
       The annotation as source text, or `None` if the value doesn't decide one.
 
     """
-    return _scalar(value) or _container(value, calls) or _called(value, calls)
+    if isinstance(value, ast.Name) and value.id in declared:
+        return declared[value.id]
+    found: str | None
+    if (
+        isinstance(value, ast.Subscript)
+        and isinstance(value.value, ast.Name)
+        and value.value.id in declared
+        and (found := _subscripted(declared[value.value.id], value)) is not None
+    ):
+        return found
+    if (
+        isinstance(value, ast.Attribute)
+        and isinstance(value.value, ast.Name)
+        and value.value.id in declared
+        and (found := known_classes.get(declared[value.value.id], {}).get(value.attr)) is not None
+    ):
+        return found
+    if (
+        isinstance(value, ast.Call)
+        and isinstance(value.func, ast.Attribute)
+        and isinstance(value.func.value, ast.Name)
+        and value.func.value.id in declared
+        and (found := _method_return(declared[value.func.value.id], value.func.attr)) is not None
+    ):
+        return found
+    return (
+        _scalar(value)
+        or _container(value, calls, known_factories, declared, known_classes)
+        or _called(value, calls, known_factories)
+    )
 
 
 def _scalar(value: ast.expr) -> str | None:
@@ -219,72 +480,174 @@ def _scalar(value: ast.expr) -> str | None:
             _NUMBERS,
         ) and not isinstance(constant, bool):
             return type(constant).__name__
+        case ast.UnaryOp(op=ast.Not()):  # `not x` always yields a real `bool`, unlike a comparison
+            return "bool"
         case ast.JoinedStr():
             return "str"
         case _:
             return None
 
 
-def _container(value: ast.expr, calls: Mapping[str, str]) -> str | None:
+def _container(
+    value: ast.expr,
+    calls: Mapping[str, str],
+    known_factories: frozenset[str],
+    declared: Mapping[str, str],
+    known_classes: Mapping[str, Mapping[str, str]],
+) -> str | None:
     elements: list[ast.expr]
     keys: list[ast.expr | None]
     values: list[ast.expr]
     parts: list[str | None]
     match value:
         case ast.List(elts=elements) | ast.Set(elts=elements) if elements:
-            element: str | None = _uniform(elements, calls)
+            element: str | None = _uniform(elements, calls, known_factories, declared, known_classes)
             return f"{'list' if isinstance(value, ast.List) else 'set'}[{element}]" if element else None
         case ast.Tuple(elts=elements) if elements:
-            parts = [inferred(element, calls) for element in elements]
+            parts = [
+                inferred(element, calls, known_factories, declared, known_classes) for element in elements
+            ]
             return None if None in parts else f"tuple[{', '.join(str(part) for part in parts)}]"
         case ast.Dict(keys=keys, values=values) if keys and None not in keys:
-            key: str | None = _uniform([k for k in keys if k is not None], calls)
-            item: str | None = _uniform(values, calls)
+            present: list[ast.expr] = [k for k in keys if k is not None]
+            key: str | None = _uniform(present, calls, known_factories, declared, known_classes)
+            item: str | None = _uniform(values, calls, known_factories, declared, known_classes)
             return f"dict[{key}, {item}]" if key and item else None
         case _:
             return None
 
 
-def _uniform(elements: Sequence[ast.expr], calls: Mapping[str, str]) -> str | None:
+def _uniform(
+    elements: Sequence[ast.expr],
+    calls: Mapping[str, str],
+    known_factories: frozenset[str],
+    declared: Mapping[str, str],
+    known_classes: Mapping[str, Mapping[str, str]],
+) -> str | None:
     """Find the one type every element has.
 
     Returns:
       That type, or `None` if they differ or any is unknown.
 
     """
-    types: set[str | None] = {inferred(element, calls) for element in elements}
+    types: set[str | None] = {
+        inferred(element, calls, known_factories, declared, known_classes) for element in elements
+    }
     return next(iter(types)) if len(types) == 1 else None
 
 
-def _called(value: ast.expr, calls: Mapping[str, str]) -> str | None:
+def _subscripted(container: str, node: ast.Subscript) -> str | None:
+    """Infer `container[...]`'s type, given `container`'s own type as text.
+
+    A slice (`x[1:2]`) of a `list`, `str` or `bytes` is the same type as `container` itself; a plain
+    index into one is its element type, as is any index into a `dict` (its value type) or a
+    homogeneous `tuple[T, ...]`. A fixed-length `tuple[T1, T2]`'s element only varies with the index,
+    which isn't worth resolving.
+
+    Returns:
+      The annotation as source text, or `None` if the subscript doesn't decide one.
+
+    """
+    # `container` is always `ast.unparse`'s own output (an annotation, or an earlier `inferred`),
+    # never user text, so it's always valid Python to parse back.
+    root: ast.expr = ast.parse(container, mode="eval").body
+    sliced: bool = isinstance(node.slice, ast.Slice)
+    element: ast.expr
+    last: ast.expr
+    match root:
+        case ast.Name(id="str" | "bytes"):
+            return container
+        case ast.Subscript(value=ast.Name(id="list" | "List"), slice=element):
+            return container if sliced else ast.unparse(element)
+        case ast.Subscript(
+            value=ast.Name(id="dict" | "Dict"),
+            slice=ast.Tuple(elts=[_, element]),
+        ) if not sliced:
+            return ast.unparse(element)
+        case ast.Subscript(
+            value=ast.Name(id="tuple" | "Tuple"),
+            slice=ast.Tuple(elts=[element, last]),
+        ) if not sliced and isinstance(last, ast.Constant) and last.value is Ellipsis:
+            return ast.unparse(element)
+        case _:
+            return None
+
+
+def _called(value: ast.expr, calls: Mapping[str, str], known_factories: frozenset[str]) -> str | None:
     func: ast.expr
+    name: str
     match value:
         case ast.Call(func=ast.Name() | ast.Attribute() as func) if ast.unparse(func) in calls:
             return calls[ast.unparse(func)]
-        case ast.Call(func=ast.Name() | ast.Attribute() as func) if _constructs(_name(func)):
+        case ast.Call(func=ast.Name(id=name)) if name in _BUILTIN_RETURNS:
+            return _BUILTIN_RETURNS[name]
+        case ast.Call(func=ast.Name() | ast.Attribute() as func) if _constructs(
+            node_name(func),
+            known_factories,
+        ):
             return ast.unparse(func)
         case _:
             return None
 
 
-def guessed(value: ast.expr, calls: Mapping[str, str]) -> bool:
+def guessed(
+    value: ast.expr,
+    calls: Mapping[str, str],
+    guesses: frozenset[str],
+    declared: Mapping[str, str],
+) -> bool:
     """Whether `inferred`'s annotation for `value` is a guess (`--unsafe-fixes`): it calls a class.
 
     A capitalised call may construct a generic class (`Box(1)` is really `Box[int]`) or be a factory
-    function; literals and calls to module functions with a declared return type are certain.
+    function; literals, calls to a module function, a fixed-return builtin (`len`, `isinstance`,
+    ...) or a fixed-return `str`/`bytes` method (`_method_return`) on an already-typed local, and
+    another local this scope already typed, are certain. Copying a local `inferred` itself only
+    guessed (`guesses`) is no more certain than the guess it copies.
 
     Returns:
-      Whether any call in `value` is to something other than such a module function.
+      Whether any call in `value` is to something other than such a certain callee, or any name in
+      it copies such a guess.
 
     """
-    return any(isinstance(node, ast.Call) and ast.unparse(node.func) not in calls for node in ast.walk(value))
+    return any(_is_guess(node, calls, guesses, declared) for node in ast.walk(value))
 
 
-def _constructs(name: str) -> bool:
+def _is_guess(
+    node: ast.AST,
+    calls: Mapping[str, str],
+    guesses: frozenset[str],
+    declared: Mapping[str, str],
+) -> bool:
+    name: str
+    func: ast.expr
+    receiver: str
+    method: str
+    match node:
+        case ast.Call(func=ast.Name(id=name)) if name in _BUILTIN_RETURNS:
+            return False
+        case ast.Call(func=ast.Attribute(value=ast.Name(id=receiver), attr=method)) if (
+            receiver in declared and _method_return(declared[receiver], method) is not None
+        ):
+            return False
+        case ast.Call(func=func):
+            return ast.unparse(func) not in calls
+        case ast.Name(id=name):
+            return name in guesses
+        case _:
+            return False
+
+
+def _constructs(name: str, known_factories: frozenset[str]) -> bool:
     """Check whether a call to `name` constructs a class, by its capitalised name.
 
     Returns:
-      Whether it does, and is worth annotating.
+      Whether it does, and is worth annotating: `name` isn't a known factory, by import
+      (`known_factories`) or by its bare name (`_FACTORIES`, for one imported some other way).
 
     """
-    return name[:1].isupper() and name not in _FACTORIES and name not in _GENERICS
+    return (
+        name[:1].isupper()
+        and name not in known_factories
+        and name not in _FACTORIES
+        and name not in _GENERICS
+    )

constricter/baseline.py

@@ -58,7 +58,7 @@ def read(baseline: Path) -> Entries:
             path: str
             counts: _Json
             for path, counts in files.items():
-                if not isinstance(counts, dict) or not all(_is_count(n) for n in counts.values()):
+                if not isinstance(counts, dict) or not all(jsonc.is_int(n) for n in counts.values()):
                     break
                 entries[path] = {entry: n for entry, n in counts.items() if isinstance(n, int)}
             else:
@@ -69,10 +69,6 @@ def read(baseline: Path) -> Entries:
     raise ValueError(message)
 
 
-def _is_count(value: _Json) -> bool:
-    return isinstance(value, int) and not isinstance(value, bool)
-
-
 def write(baseline: Path, found: Mapping[str, Sequence[Offence]]) -> int:
     """Write every offence in `found` (keyed as `key` makes them) to `baseline`.