python-constricter 0.4.1__cp313-cp313-win32.whl

constricter/rules/tables.py

@@ -0,0 +1,169 @@
+# SPDX-License-Identifier: MIT
+"""A module's own tables `--fix` reads, read once for the cross-file index and the check."""
+
+import ast
+from collections import Counter
+from collections.abc import Mapping
+from typing import Final, NamedTuple
+
+from constricter.fix.core.imports import rebound_names, taken_names
+from constricter.fix.core.inherited import Lineage, lineage
+from constricter.fix.core.signatures import AWAIT
+from constricter.fix.values.targets import aliased_unions, named_tuples
+from constricter.rules import walked
+from constricter.rules.declarations import (
+    class_methods,
+    classes,
+    held,
+    held_class_methods,
+    method_returns,
+    partial_method_returns,
+    partial_returns,
+    returns,
+    self_returns,
+)
+from constricter.rules.decorators import Held, Pass, passes
+from constricter.rules.syntax import import_bindings
+
+_NEW_TYPES: Final = frozenset({"typing.NewType", "typing_extensions.NewType"})
+
+
+class Tables(NamedTuple):
+    """A module's own tables (see `returns`, `classes`, `method_returns`, `class_methods`).
+
+    Its functions' declared returns (a `NewType` bound nowhere else returning itself: `Ref(name)` is
+    a `Ref`), and its classes' attributes and methods' returns (their classmethods' and
+    staticmethods' too, which an instance has as well; an `async` method's as what awaiting its call
+    gives, its name after `signatures.AWAIT`), the attributes each takes from the module's
+    other classes included (see `Lineage`); `held`, the functions other modules'
+    decorators may give back, and `passes`, its own such decorators; `sides`, its classes'
+    classmethods' and staticmethods' returns, those each takes from the module's other classes
+    included (see `Lineage`), and `held_sides`, those other modules' decorators may give back;
+    `side_calls`, `sides` as called on the class (see `_side_calls`). `partial` and
+    `partial_methods`: its functions' and methods' returns that are tuples with a vague part.
+    `tuples`: its named tuples, each with the tuple unpacking one gives (see `named_tuples`).
+    `unions`: its type aliases of a union, each with the union (see `aliased_unions`).
+    """
+
+    returns: dict[str, str]
+    classes: dict[str, dict[str, str]]
+    methods: dict[str, dict[str, str]]
+    held: dict[str, Held]
+    passes: dict[str, Pass]
+    sides: dict[str, dict[str, str]]
+    held_sides: dict[str, dict[str, Held]]
+    side_calls: dict[str, str]
+    partial: dict[str, str]
+    partial_methods: dict[str, dict[str, str]]
+    order: Lineage  # its classes' ancestry, as far as the module alone sees
+    tuples: dict[str, str]
+    unions: dict[str, str]
+
+
+def module_tables(tree: ast.Module) -> Tables:
+    """Read the module's own tables, once for the cross-file index and the check (see `parsed.keep`).
+
+    Returns:
+      Them.
+
+    """
+    own: dict[str, dict[str, str]] = class_methods(tree)
+    order: Lineage = lineage(tree, self_returns(tree), frozenset())
+    sides: dict[str, dict[str, str]] = order.flattened(own)
+    awaited: dict[str, dict[str, str]] = method_returns(tree, awaited=True)
+    made: list[str] = _new_types(tree)
+    rebound: frozenset[str] = frozenset(rebound_names(tree)) if made else frozenset()
+    return Tables(
+        {**returns(tree), **{name: name for name in made if name not in rebound}},
+        order.flattened(classes(tree)),
+        {
+            owner: {
+                **own.get(owner, {}),
+                **methods,
+                **{AWAIT + name: each for name, each in awaited[owner].items()},
+            }
+            for owner, methods in method_returns(tree).items()
+        },
+        held(tree),
+        passes(tree),
+        sides,
+        held_class_methods(tree),
+        _side_calls(tree, sides),
+        partial_returns(tree),
+        partial_method_returns(tree),
+        order,
+        named_tuples(tree),
+        aliased_unions(tree),
+    )
+
+
+def _side_calls(tree: ast.Module, sides: Mapping[str, Mapping[str, str]]) -> dict[str, str]:
+    """Spell the calls to the module's classes' classmethods and staticmethods on the class itself.
+
+    `Box.make()`, for a top-level class defined once whose name nothing in the module binds as a
+    value (see `imports.taken_names`): there, the name is the class.
+
+    Returns:
+      Each call's name as written (`Box.make`), and its declared return.
+
+    """
+    if not any(sides.values()):  # most modules: no class-side method declares a return
+        return {}
+    values: frozenset[str] = taken_names(tree)[1]
+    counts: Counter[str] = Counter(node.name for node in walked.classes(tree))
+    return {
+        f"{stmt.name}.{name}": annotation
+        for stmt in tree.body
+        if isinstance(stmt, ast.ClassDef) and counts[stmt.name] == 1 and stmt.name not in values
+        for name, annotation in sides.get(stmt.name, {}).items()
+    }
+
+
+def _new_types(tree: ast.Module) -> list[str]:
+    """Name the module's `NewType`s: `Ref = NewType("Ref", str)`, at its top level.
+
+    By `typing`'s or `typing_extensions`' `NewType`, however it's imported.
+
+    Returns:
+      Them.
+
+    """
+    made: list[tuple[str, ast.Name | ast.Attribute]] = []
+    stmt: ast.stmt
+    name: str
+    func: ast.expr
+    text: str
+    for stmt in tree.body:
+        match stmt:
+            case ast.Assign(
+                targets=[ast.Name(id=name)],
+                value=ast.Call(
+                    func=ast.Name() | ast.Attribute() as func,
+                    args=[ast.Constant(value=str() as text), _],
+                ),
+            ) if text == name:
+                made.append((name, func))
+            case _:
+                pass
+    if not made:  # most modules
+        return []
+    bound: dict[str, str] = {name: origin for name, origin, _ in import_bindings(tree.body)}
+    return [name for name, func in made if _origin(func, bound) in _NEW_TYPES]
+
+
+def _origin(func: ast.Name | ast.Attribute, bound: Mapping[str, str]) -> str | None:
+    """Resolve a callee one or two names long through the module's imports (`bound`).
+
+    Returns:
+      Its dotted origin (`typing.NewType`), or `None`.
+
+    """
+    name: str
+    attr: str
+    match func:
+        case ast.Name(id=name):
+            return bound.get(name)
+        case ast.Attribute(value=ast.Name(id=name), attr=attr) if name in bound:
+            return f"{bound[name]}.{attr}"
+        case _:
+            return None

constricter/rules/walked.py

@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: MIT
+"""One walk of a whole module, shared by every pass over all of it (importing nothing of constricter's)."""
+
+import ast
+from collections.abc import Sequence
+from typing import Final, TypeAlias, cast
+from weakref import WeakKeyDictionary
+
+_CTX: Final = "ctx"
+# What a node's field holds, as far as the walk cares: a node, a list (of nodes, or of names), or else.
+_Value: TypeAlias = ast.AST | list[ast.AST | str] | str | int | None
+
+
+_Walk: TypeAlias = dict[type[ast.AST], list[ast.AST]]  # a module's nodes, by their type
+# Each node class's fields, but its `ctx` (only ever `Load`, `Store` or `Del`: no pass looks at them).
+_FIELDS: dict[type[ast.AST], tuple[str, ...]] = {}
+
+
+# Each module's walk, for as long as its tree lives: the cross-file index's walk of a file is the
+# check's too, when the index kept its tree (`parsed.keep`), however many files came between.
+_WALKS: Final[WeakKeyDictionary[ast.Module, "_Walk"]] = WeakKeyDictionary()
+
+
+def _by_type(tree: ast.Module) -> dict[type[ast.AST], list[ast.AST]]:
+    """Walk a whole module once, sorting its nodes by type, for every pass that looks at all of it.
+
+    `ast.walk` was most of a check's time (on the standard library, 57%), eight passes each walking
+    every module whole. This walk is `ast.walk`'s, breadth first, without its per-node generators:
+    a generation of nodes at a time, and each class's fields looked up once.
+
+    Returns:
+      Each type's nodes, in `ast.walk`'s order (all but the `Load`, `Store` and `Del` markers).
+
+    """
+    found: dict[type[ast.AST], list[ast.AST]] | None
+    if (found := _WALKS.get(tree)) is not None:
+        return found
+    found = _WALKS[tree] = {}
+    # A generation at a time (a breadth-first queue's order): each built from the one before.
+    # `None` at the bottom ends it: a generation with no children adds none to follow it.
+    generations: list[list[ast.AST] | None] = [None, [tree]]
+    generation: list[ast.AST]
+    for generation in iter(generations.pop, None):
+        following: list[ast.AST] = []
+        node: ast.AST
+        for node in generation:
+            kind: type[ast.AST] = type(node)
+            found.setdefault(kind, []).append(node)
+            field: str
+            for field in _fields_of(kind):
+                value: _Value = cast("_Value", getattr(node, field, None))
+                if isinstance(value, list):
+                    # A list, not a generator: none's resumed for each item (and it's inlined, 3.12+).
+                    following.extend([item for item in value if isinstance(item, ast.AST)])
+                elif isinstance(value, ast.AST):
+                    following.append(value)
+        if following:
+            generations.append(following)
+    return found
+
+
+def of_type(tree: ast.Module, *kinds: type[ast.AST]) -> Sequence[ast.AST]:
+    """Find a module's nodes of `kinds`: a pass that wants only those needn't look at every node.
+
+    Returns:
+      Them, each kind's in `ast.walk`'s order, the kinds one after another.
+
+    """
+    table: dict[type[ast.AST], list[ast.AST]] = _by_type(tree)
+    return [node for kind in kinds for node in table.get(kind, [])]
+
+
+def classes(tree: ast.Module) -> Sequence[ast.ClassDef]:
+    """Find every class a module defines, however deep.
+
+    Returns:
+      Them, in `ast.walk`'s order.
+
+    """
+    return cast("list[ast.ClassDef]", _by_type(tree).get(ast.ClassDef, []))
+
+
+def children(node: ast.AST) -> list[ast.AST]:
+    """List a node's children, as `ast.iter_child_nodes` does but for their `ctx`, and without its generator.
+
+    Returns:
+      Them, in their fields' order.
+
+    """
+    found: list[ast.AST] = []
+    field: str
+    for field in _fields_of(type(node)):
+        value: _Value = cast("_Value", getattr(node, field, None))
+        if isinstance(value, list):
+            found.extend([item for item in value if isinstance(item, ast.AST)])
+        elif isinstance(value, ast.AST):
+            found.append(value)
+    return found
+
+
+def walk(node: ast.AST) -> list[ast.AST]:
+    """List a node and everything under it (but `ctx` markers), for a pass that needn't their order.
+
+    Returns:
+      Them, depth first (not `ast.walk`'s breadth first order).
+
+    """
+    found: list[ast.AST] = []
+    waiting: list[ast.AST | None] = [None, node]  # `None` at its bottom ends it
+    item: ast.AST
+    for item in iter(waiting.pop, None):
+        found.append(item)
+        waiting.extend(children(item))
+    return found
+
+
+def _fields_of(kind: type[ast.AST]) -> tuple[str, ...]:
+    """Name a node class's fields but its `ctx`, worked out once per class.
+
+    Returns:
+      Them.
+
+    """
+    fields: tuple[str, ...] | None
+    if (fields := _FIELDS.get(kind)) is None:
+        fields = _FIELDS[kind] = tuple(field for field in kind._fields if field != _CTX)
+    return fields

constricter/rules/widened.py

@@ -0,0 +1,322 @@
+# SPDX-License-Identifier: MIT
+"""Wider types than a value's own, written only where `fix-widen` asks, each line marked (`MARK`).
+
+A marked annotation is `--fix`'s own: it isn't LVA005, `--coverage` counts it apart, and a later
+`--fix` replaces it once the value's type is known.
+"""
+
+import ast
+import re
+from collections import Counter
+from collections.abc import Collection, Mapping, Sequence
+from functools import lru_cache
+from typing import Final, NamedTuple
+
+from constricter.fix.core.known import ImportPlan, Inference
+from constricter.fix.values import fills
+from constricter.offences import (
+    EMPTY_CONTAINERS,
+    MARK,
+    MIXED_CONTAINERS,
+    UNKNOWN_CALLS,
+    UNTYPED_CALLS,
+    UNTYPED_PARAMETERS,
+)
+from constricter.rules.annotations import dotted, node_name
+from constricter.rules.syntax import FUNCTION_DEFS, FunctionDef
+from constricter.rules.walked import children, classes, walk
+
+ANY: Final = "typing.Any"
+_RECEIVERS: Final = frozenset({"self", "cls"})
+# The decorators that leave a method's call its own `return`s.
+_BINDERS: Final = frozenset({"staticmethod", "classmethod"})
+# The mark, ending its line, with the space before it: what a replaced widening's fix deletes.
+_MARKED: Final = re.compile(rf"[ \t]*{re.escape(MARK)}(?=[ \t]*[\r\n]*$)")
+
+
+def marks(lines: Sequence[str]) -> dict[int, tuple[int, int]]:
+    """Find the lines a widening marked.
+
+    Returns:
+      Each one's number (from 1), and the mark's columns in it (UTF-8 bytes, as `ast` counts).
+
+    """
+    found: dict[int, tuple[int, int]] = {}
+    number: int
+    line: str
+    for number, line in enumerate(lines, 1):
+        marked: re.Match[str] | None
+        if (marked := _MARKED.search(line) if MARK in line else None) is not None:
+            start: int = len(line[: marked.start()].encode())
+            found[number] = (start, start + len(marked.group().encode()))
+    return found
+
+
+@lru_cache(maxsize=64)  # asked of each of a function's assignments with no fix
+def untyped_parameters(function: FunctionDef) -> frozenset[str]:
+    """Name a function's parameters nothing types: no annotation, no default, never bound again.
+
+    A checker takes each for anything, wherever it's read. Not `*args` or `**kwargs`, nor a
+    method's `self` or `cls`, which is its class's.
+
+    Returns:
+      Them.
+
+    """
+    args: ast.arguments = function.args
+    positional: list[ast.arg] = [*args.posonlyargs, *args.args]
+    plain: int = len(positional) - len(args.defaults)
+    defaulted: set[str] = {arg.arg for arg in positional[plain:]}
+    defaulted.update(
+        arg.arg for arg, default in zip(args.kwonlyargs, args.kw_defaults, strict=True) if default
+    )
+    rebound: set[str] = {
+        node.id
+        for node in walk(function)
+        if isinstance(node, ast.Name) and not isinstance(node.ctx, ast.Load)
+    }
+    return frozenset(
+        arg.arg
+        for arg in (*positional, *args.kwonlyargs)
+        if arg.annotation is None and arg.arg not in defaulted | rebound | _RECEIVERS
+    )
+
+
+def wider(
+    function: FunctionDef | None,
+    bound: tuple[ast.Name, ast.expr],
+    typed: Collection[str],
+    plan: ImportPlan | None,
+) -> Inference | None:
+    """Type a name `bound` to what comes of an untyped parameter of `function` as `Any`.
+
+    A copy of it (`x = param`), or its method's call (`y = param.read()`), all on the name's line
+    (the mark ends it); not one of `typed`, which something gives a type after all. What every
+    checker takes it for already.
+
+    Returns:
+      The inference, or `None`: also where the module (`plan`) can't name `Any`.
+
+    """
+    target: ast.Name
+    value: ast.expr
+    target, value = bound
+    if function is None or plan is None or value.end_lineno != target.lineno:
+        return None
+    name: str
+    match value:
+        case ast.Name(id=name) | ast.Call(func=ast.Attribute(value=ast.Name(id=name))) if (
+            name in untyped_parameters(function) and name not in typed
+        ):
+            spelled: str | None = plan.spell(ANY)
+            reason: str = f"what comes of `{name}`, a parameter no annotation types"
+            return None if spelled is None else Inference(spelled, reason, frozenset({UNTYPED_PARAMETERS}))
+        case _:
+            return None
+
+
+def container(value: ast.expr, plan: ImportPlan, kinds: Collection[str]) -> Inference | None:
+    """Type a container whose elements aren't known with `Any` for them: `list[Any]`, `dict[str, Any]`.
+
+    An empty one nothing in sight fills (`[]`, `dict()`: kind `empty-containers`), or a display
+    whose elements' types differ or aren't known (`[1, "a"]`, `(x, y)`: `mixed-containers`); a dict
+    display's keys are `str` where each is a string. Only the kinds among `kinds`.
+
+    Returns:
+      The inference, or `None`: for any other value, or where the module (`plan`) can't name `Any`.
+
+    """
+    empty: str | None = fills.empty(value)
+    kind: str = EMPTY_CONTAINERS if empty is not None else MIXED_CONTAINERS
+    spelled: str | None
+    if (spelled := plan.spell(ANY) if kind in kinds else None) is None:
+        return None
+    keys: list[ast.expr | None]
+    annotation: str | None
+    match value:
+        case ast.List(elts=[_, *_]):
+            annotation = f"list[{spelled}]"
+        case ast.Set():
+            annotation = f"set[{spelled}]"
+        case ast.Tuple(elts=[_, *_]):
+            annotation = f"tuple[{spelled}, ...]"
+        case ast.Dict(keys=keys) if keys:
+            texts: bool = all(isinstance(key, ast.Constant) and isinstance(key.value, str) for key in keys)
+            annotation = f"dict[{'str' if texts else spelled}, {spelled}]"
+        case _:
+            annotation = {"list": f"list[{spelled}]", "set": f"set[{spelled}]"}.get(
+                empty or "",
+                f"dict[{spelled}, {spelled}]" if empty else None,
+            )
+    if annotation is None:
+        return None
+    reason: str = "an empty container nothing fills" if empty else "a display of mixed or unknown elements"
+    return Inference(annotation, reason, frozenset({kind}))
+
+
+class Own(NamedTuple):
+    """A module's functions and classes a call may name, each defined once: what `called` looks through.
+
+    `functions`: its top-level functions, by name; `classes`: its classes, anywhere, by name.
+    """
+
+    functions: Mapping[str, FunctionDef]
+    classes: Mapping[str, ast.ClassDef]
+
+
+class Caller(NamedTuple):
+    """The function a call is in: its class, where it reads a method's `self`, and the names it binds.
+
+    `untyped`: the other checked files' functions its module calls that declare no return, as it
+    spells them (see `Outside.untyped`).
+    """
+
+    owner: str | None
+    bound: Collection[str]
+    untyped: Collection[str] = ()
+
+
+@lru_cache(maxsize=2)  # asked of each scope of a module in turn
+def own(tree: ast.Module) -> Own:
+    """Read a module's `Own`.
+
+    Returns:
+      It.
+
+    """
+    defined: list[FunctionDef | ast.ClassDef] = [
+        *(stmt for stmt in tree.body if isinstance(stmt, FUNCTION_DEFS)),
+        *classes(tree),
+    ]
+    count: Counter[str] = Counter(node.name for node in defined)
+    once: list[FunctionDef | ast.ClassDef] = [node for node in defined if count[node.name] == 1]
+    return Own(
+        {node.name: node for node in once if isinstance(node, FUNCTION_DEFS)},
+        {node.name: node for node in once if isinstance(node, ast.ClassDef)},
+    )
+
+
+def _method(found: Own, owner: str, name: str) -> FunctionDef | None:
+    """Find the method a class's instance takes by `name`: its own, or the first of its bases'.
+
+    Returns:
+      Its definition, or `None`: where a class on the way isn't the module's, or binds the name
+      more than once (overloads, a property's setter) or otherwise than by a `def`.
+
+    """
+    waiting: list[str | None] = [
+        None,
+        owner,
+    ]  # each class still to look in, the next one last; `None` ends it
+    current: str
+    for current in iter(waiting.pop, None):
+        node: ast.ClassDef | None
+        if (node := found.classes.get(current)) is None:
+            return None
+        bound: list[ast.AST]
+        if bound := _bindings(node, name):
+            method: ast.AST = bound[0]
+            return method if len(bound) == 1 and isinstance(method, FUNCTION_DEFS) else None
+        bases: list[str] = [base.id for base in node.bases if isinstance(base, ast.Name)]
+        if len(bases) != len(node.bases):
+            return None
+        waiting.extend(reversed(bases))
+    return None
+
+
+def _bindings(node: ast.ClassDef, name: str) -> list[ast.AST]:
+    """Find what binds `name` in a class's body: not in its methods' bodies, nor a nested class's.
+
+    Returns:
+      Each `def`, class and store of it.
+
+    """
+    found: list[ast.AST] = []
+    waiting: list[ast.AST | None] = [None, *node.body]  # each node still to read; `None` ends it
+    child: ast.AST
+    for child in iter(waiting.pop, None):
+        if isinstance(child, (*FUNCTION_DEFS, ast.ClassDef)):
+            found.extend([child] if child.name == name else [])
+        elif isinstance(child, ast.Name):
+            found.extend([child] if child.id == name and isinstance(child.ctx, ast.Store) else [])
+        else:
+            waiting.extend(children(child))
+    return found
+
+
+def _undeclared(function: FunctionDef, *, awaited: bool) -> bool:
+    """Check whether a function's call is one a checker reading no body takes for anything.
+
+    Returns:
+      Whether it declares no return, by an annotation or a type comment, is decorated at most as a
+      static or class method, and is an `async def` just where its call is `awaited`.
+
+    """
+    return (
+        function.returns is None
+        and not function.type_comment
+        and isinstance(function, ast.AsyncFunctionDef) == awaited
+        and all(node_name(decorator) in _BINDERS for decorator in function.decorator_list)
+    )
+
+
+def _imported(func: ast.expr, caller: Caller) -> bool:
+    """Check whether a call's function is another checked file's that declares no return.
+
+    Returns:
+      Whether `func` spells one of `caller.untyped`, through no name its function binds.
+
+    """
+    spelled: str | None = dotted(func)
+    return spelled is not None and spelled in caller.untyped and spelled.partition(".")[0] not in caller.bound
+
+
+def called(
+    value: ast.expr,
+    caller: Caller,
+    found: Own,
+    plan: ImportPlan,
+    kinds: Collection[str],
+) -> Inference | None:
+    """Type a call of no known type as `Any`, awaited or not.
+
+    Kind `untyped-calls` where it calls a function that declares no return, which a checker
+    reading no body takes for anything already: a top-level function of the module's by its name,
+    a method of `caller`'s class (or of its bases in the module) on `self` or `cls`, or another
+    checked file's function (`caller.untyped`), not awaited. Kind `unknown-calls` for any other.
+    Only the kinds among `kinds`.
+
+    Returns:
+      The inference, or `None`: for any other value, or where the module (`plan`) can't name `Any`.
+
+    """
+    awaited: bool = isinstance(value, ast.Await)
+    call: ast.expr = value.value if isinstance(value, ast.Await) else value
+    if not isinstance(call, ast.Call):
+        return None
+    callee: FunctionDef | None = None
+    name: str
+    receiver: str
+    owner: str
+    match call.func, caller.owner:
+        case ast.Name(id=name), _ if name not in caller.bound:
+            callee = found.functions.get(name)
+        case ast.Attribute(value=ast.Name(id=receiver), attr=name), str() as owner if receiver in _RECEIVERS:
+            callee = _method(found, owner, name)
+        case _:
+            pass
+    untyped: bool = (
+        (not awaited and _imported(call.func, caller))
+        if callee is None
+        else _undeclared(callee, awaited=awaited)
+    )
+    kind: str = UNTYPED_CALLS if untyped else UNKNOWN_CALLS
+    spelled: str | None
+    if (spelled := plan.spell(ANY) if kind in kinds else None) is None:
+        return None
+    reason: str = (
+        f"a call of `{ast.unparse(call.func)}`, which declares no return"
+        if untyped
+        else "a call of no known type"
+    )
+    return Inference(spelled, reason, frozenset({kind}))