python-constricter 0.4.1__cp314-cp314-win_amd64.whl

constricter/rules/scoped.py

@@ -0,0 +1,232 @@
+# SPDX-License-Identifier: MIT
+"""What a scope (`constricter.rules.scope.Scope`) is checked with, and what it holds as it's checked.
+
+Its module's `Settings` (and the parameters' types given from outside, `Seeded`); its `Kind` of
+body; its plain bindings (`Assignments`), which LVA012 and `--fix` read; and what `--fix` has typed
+in it so far (`Inferred`), late fixes included (`Late`).
+"""
+
+import ast
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import NamedTuple, TypeAlias
+
+from constricter.empty import Empty
+from constricter.fix.core.known import Hints, Inference, Known, Passed, Typed
+from constricter.fix.values import aliased
+from constricter.fix.values.doubts import (
+    Facts,
+)
+from constricter.offences import (
+    Checks,
+)
+from constricter.rules.flow import Hierarchy, members
+from constricter.rules.quoted import parsed as unquoted
+from constricter.rules.quoted import unqualified
+from constricter.rules.rebinding import REBOUND
+from constricter.rules.syntax import FunctionDef, Start
+
+
+@dataclass(frozen=True)
+class Settings:
+    """One module's options, and its source lines (to place a `**rest` capture)."""
+
+    # The checks asked for (a module written for Python 2 counts its `# type:` comments whatever they say).
+    checks: Checks
+    lines: Sequence[str]
+    known: Known  # what the module declares that `--fix` infers types from
+    hierarchy: Hierarchy  # which types are narrower than which, for value flow
+    owners: dict[int, str]  # each method's class, by `id()`, to type its `self`, for `--fix`
+    # Where each of the module's `:=` starts, in source order: most modules have none, and needn't be
+    # looked through for one; a statement's part without one needn't be either.
+    walruses: tuple[Start, ...]
+    # Type checkers' types, for what `--fix` can't type (`--infer-with`): each checker's, in order.
+    hints: tuple[Hints, ...] = ()
+    facts: Facts = field(default_factory=Facts)  # what a type checker sees otherwise (see `doubts`)
+    parameters: "Seeded | None" = None  # what its functions' parameters are given from outside them
+
+
+class Seeded(NamedTuple):
+    """The types a module's functions' unannotated parameters are given from outside them: guesses.
+
+    `callers`: what every call passes each parameter of its top-level functions, by `id()` (see
+    `constricter.fix.index.callers`); `fixtures`: the pytest fixtures its tests can take, each one's
+    value's type (see `constricter.fix.index.fixtures`). And `module`: the names the module binds
+    once, at its top level, each with its type there, which every function reads it as. `marked`:
+    what a class's `parametrize` gives each of its methods, by `id()` (see `calls.marked`).
+    """
+
+    callers: Mapping[int, Mapping[str, Passed]] = Empty()
+    fixtures: Mapping[str, Passed] = Empty()
+    module: Mapping[str, Passed] = Empty()
+    marked: Mapping[int, Mapping[str, Passed]] = Empty()
+
+
+class Kind(NamedTuple):
+    """What kind of body a scope is: the code its unannotated names get, and whether `--fix` fixes it."""
+
+    unannotated: str  # LVA001 in a function, LVA004 in a module or class body
+    # A class body isn't: annotating a dataclass's variable makes it a field. Only a plain class's
+    # variable typed by its value is fixed there (see `constricter.fix.values.classvars`).
+    fixable: bool
+    function: FunctionDef | None = None  # a function's own: its body, its returns
+    owner: str | None = None  # a class body's: its class
+
+    def body(self) -> Sequence[ast.stmt]:
+        """Find the function's body.
+
+        Returns:
+          It, or nothing for a module or class body's scope.
+
+        """
+        return () if self.function is None else self.function.body
+
+
+# A name's first plain assignment: its target, its value, and the value's inferred type, if any.
+Plain: TypeAlias = tuple[ast.Name, ast.expr, Inference | None]
+Bare: TypeAlias = tuple[ast.AnnAssign, Inference | None]
+# One plain assignment: where, and whether it's in a loop's body.
+Placed: TypeAlias = tuple[tuple[int, int], bool]
+
+
+@dataclass
+class Assignments:
+    """A scope's plain `name = value` (or `name: T = value`) bindings, for LVA012 and `--fix`.
+
+    `chained`: where the statement starts that first binds a name it can't annotate (`a = b = 0`,
+    a loop's, an unpacking's, a `with`'s): a fix made late (`optional`, `filled`) declares it there.
+    """
+
+    found: dict[str, list[Placed]] = field(default_factory=dict[str, list[Placed]])  # each name's
+    looping: int = 0  # how many loops deep the statement being visited is
+    empty: dict[str, str] = field(default_factory=dict[str, str])  # names first bound empty: their kind
+    chained: dict[str, tuple[int, int]] = field(default_factory=dict[str, tuple[int, int]])
+    widened: set[str] = field(default_factory=set[str])  # the names a marked line annotates (see `widened`)
+    # Each name `late.widens` may offer a wider type: its target, its value (what a loop's, an
+    # unpacking's or a `with`'s is taken from: then in `chained` too), and the type `--fix` infers.
+    plain: dict[str, "Plain"] = field(default_factory=dict[str, "Plain"])
+    # Each marked declaration with no value (`x: Any`, before a loop), and what its name is bound to.
+    bare: dict[str, "Bare"] = field(default_factory=dict[str, "Bare"])
+
+
+# A name typed late: its type, and what that rests on if it's a guess (`FIX_KINDS`).
+Late: TypeAlias = tuple[str, frozenset[str]]
+
+
+@dataclass
+class Inferred:
+    """What `--fix` knows of a scope's names so far."""
+
+    types: Typed = field(default_factory=Typed)  # each known type, for `x = y`'s
+    guesses: set[str] = field(default_factory=set[str])  # `types` from an unsafe fix: copies are too
+    # Each guess's guessing mechanisms (`FIX_KINDS`), for `unsafe-fix-select` to trust or not.
+    origins: dict[str, frozenset[str]] = field(default_factory=dict[str, frozenset[str]])
+    returns: list[ast.expr | None] = field(default_factory=list[ast.expr | None])  # its `return`s' values
+    # Its `self.x = value` assignments: each attribute, and its value.
+    assigned: list[tuple[str, ast.expr]] = field(default_factory=list[tuple[str, ast.expr]])
+    # Names typed only once the whole scope was seen (a container filled later, `None` rebound): the
+    # type, and what it rests on if a guess; and those it was checked again knowing.
+    late: dict[str, Late] = field(default_factory=dict[str, "Late"])
+    seeded: dict[str, Late] = field(default_factory=dict[str, "Late"])
+    # The names declared type aliases (`X: TypeAlias = ...`): `TypeAlias` isn't their values' type.
+    aliases: set[str] = field(default_factory=set[str])
+    unions: Mapping[str, str] = field(default_factory=dict[str, str])  # see `Indirect.unions`
+
+    def members(self, annotation: str) -> frozenset[str]:
+        """Split a type into its union's members, an alias of a union read as the union it names.
+
+        Returns:
+          Them; none for a type that can't be read.
+
+        """
+        return members(self.unions.get(annotation, annotation)) or frozenset()
+
+    def declare(self, name: str, annotation: ast.expr, held: str | None = None) -> None:
+        """Record the type `name` is annotated with: its own from here on, or an alias's declaration.
+
+        A `Final[T]`'s or a `ClassVar[T]`'s is `T`, and a bare one's its value's (`held`, if known).
+        """
+        text: str | None = unqualified(unquoted(annotation)) or held
+        if aliased.declares(annotation):
+            self.aliases.add(name)
+        elif text:
+            _ = self.types.setdefault(name, text)
+
+    def learn(
+        self,
+        name: str,
+        annotation: str,
+        origins: frozenset[str] | None,
+        *,
+        again: bool = False,
+    ) -> None:
+        """Record `name`'s type, the first time it's typed; `origins`: what it rests on, if it's a guess.
+
+        `again`: whether it was bound before, to a value of no known type, which it may still hold
+        (another branch's): its type is then a guess, resting on `rebound`.
+        """
+        if name in self.types:
+            return
+        self.types[name] = annotation
+        if origins is None and again:
+            origins = frozenset({REBOUND})
+        if origins is not None:
+            self.guess(name, origins)
+
+    def guess(self, name: str, origins: frozenset[str]) -> None:
+        """Take what's inferred from `name` from here on for a guess, resting on `origins`."""
+        self.guesses.add(name)
+        self.origins[name] = origins
+
+    def rebound(self, name: str, typed: str | None, guess: Late | None = None) -> None:
+        """Record `name` bound again, to a value of type `typed` (`None`: unknown).
+
+        A type checker narrows a name to what it's assigned: from here on it's `typed`, if known. That's
+        certain for a member of a declared union (`int | None`, then `1`), which every checker narrows;
+        otherwise (mypy narrows nothing else, and an unknown value may be anything) what's inferred
+        from it is a guess, resting on `rebound`. `guess`: the value's type where it's only a guess
+        (`config = config or Config()`), and what that rests on: the name's from here on, as one. A
+        union bound to a value of no known type is narrowed to that: the name has no type until its
+        branch ends.
+        """
+        current: str | None = self.types.get(name)
+        self.types.hold(name, None)
+        if current is None or typed == current:
+            return
+        if typed is None and guess is not None:
+            self.types[name] = guess[0]
+            self.guess(name, self.origins.get(name, frozenset()) | guess[1])
+            return
+        union: frozenset[str] = self.members(current)
+        if typed is None and len(union) > 1:
+            self.types.forget(name)  # its type again past a branch (see `rejoined`), as a guess
+        if typed is not None:
+            self.types[name] = typed
+            if typed in union and len(union) > 1:
+                return
+        if name not in self.guesses:
+            self.guess(name, frozenset({REBOUND}))
+
+    def rejoined(self, before: Mapping[str, str], untyped: frozenset[str]) -> None:
+        """Take each name a branch (`if`, a loop, `try`, `match`) retyped back to its type `before` it.
+
+        The branch may not have run: past it, a name is what it was, or what the branch made it. That's
+        its type before, certainly, if that's a union the branch's type is a member of (`int | None`,
+        narrowed to `int` inside `if`); otherwise `rebound` already made it a guess, as it is where
+        the branch left it no type. One of `untyped`, bound before the branch or in an arm of it to a
+        value of no known type, may still hold it: it has none past it.
+        """
+        name: str
+        annotation: str
+        for name, annotation in before.items():
+            if name not in self.types and name not in self.guesses:
+                self.guess(name, frozenset({REBOUND}))
+            self.types[name] = annotation
+        for name in self.types.keys() & untyped:
+            self.forget(name)
+
+    def forget(self, name: str) -> None:
+        """Take `name` for a value of no known type from here on."""
+        self.types.forget(name)
+        self.guesses.discard(name)
+        _ = self.origins.pop(name, None)

constricter/rules/scoping.py

@@ -0,0 +1,346 @@
+# SPDX-License-Identifier: MIT
+"""A module's scopes, built for a check: each function's and class body's, their statements visited.
+
+What each binds and declares, in order, and which of them a check already finished.
+"""
+
+import ast
+from collections.abc import Mapping, Sequence
+from typing import Final, cast
+
+from constricter.fix.core import imports
+from constricter.fix.core.known import (
+    Passed,
+)
+from constricter.fix.values import ordered, returned
+from constricter.offences import (
+    UNANNOTATED,
+    UNANNOTATED_MEMBER,
+)
+from constricter.rules import binding, late, recorded
+from constricter.rules.annotations import node_name
+from constricter.rules.calls import seed_parameters, unshadowed
+from constricter.rules.declarations import (
+    imported_from,
+)
+from constricter.rules.narrowing import module_names
+from constricter.rules.quoted import written
+from constricter.rules.scope import Scope
+from constricter.rules.scoped import Kind, Late, Seeded, Settings
+from constricter.rules.syntax import (
+    BRANCHING,
+    FunctionDef,
+    Start,
+    arm_ends,
+    child_statements,
+    collect_functions,
+    expressions,
+    has_within,
+    target_names,
+)
+from constricter.rules.walked import classes
+
+# The node class of `type X = ...` statements, by name: Python 3.11's `ast` has no `TypeAlias`.
+_TYPE_ALIAS: Final = "TypeAlias"
+_CLASSMETHOD: Final = "classmethod"
+
+
+# Enum members mustn't be annotated: a base imported from here is one, however it's aliased.
+_ENUM_MODULES: Final = frozenset({"enum"})
+# The conventional name of an instance method's first parameter: typed as its class, for `--fix`.
+_SELF: Final = "self"
+
+
+def bound_once(tree: ast.Module, settings: Settings) -> dict[str, Passed]:
+    """Type the names the module binds once, anywhere in it, at its top level: what its functions read.
+
+    `LIMIT = 10` is an `int` in every function, and `NAMES: Final = ["a"]` a `list[str]`: a name bound
+    once means the same thing throughout (see `imports.rebound_names`), and a type checker takes its
+    one value's type for its own. As the module's body types it, before its functions are checked.
+
+    Returns:
+      Each such name's type, and what it rests on if it's a guess.
+
+    """
+    scope: Scope = _body_scope(tree.body, settings, Kind(UNANNOTATED_MEMBER, fixable=True))
+    rebound: Mapping[str, list[Start]] = imports.rebound_names(tree)
+    return {
+        name: (held, scope.inferred.origins.get(name, frozenset()))
+        for name, held in scope.inferred.types.items()
+        if name not in rebound
+    }
+
+
+def module_scopes(tree: ast.Module, settings: Settings, table: returned.Table | None = None) -> list["Scope"]:
+    """Collect the scopes to check.
+
+    With a `table` (see `returned.Table`), the functions are checked callees first, each one's
+    return type recorded as soon as it's checked: a caller checked later knows it the first time.
+
+    Returns:
+      Every function's scope, and with `all_scopes` every module and class body's.
+
+    """
+    functions: list[FunctionDef] = []
+    collect_functions(tree.body, functions)
+    if table is not None:
+        functions = ordered.in_call_order(tree, functions)
+    scopes: list[Scope] = _function_scopes(functions, settings, table)
+    if settings.checks.all_scopes:
+        scopes += body_scopes(tree, settings)
+    return scopes
+
+
+def body_scopes(tree: ast.Module, settings: Settings) -> list["Scope"]:
+    """Collect the module and class bodies (LVA004).
+
+    Returns:
+      Their scopes, but for an enum's.
+
+    """
+    imported: frozenset[str] = imported_from(tree, _ENUM_MODULES)
+    # A class body isn't fixed: annotating a dataclass's variable makes it a field. A plain class's
+    # variable typed by its value is (see `Scope.assign`).
+    return [
+        _body_scope(tree.body, settings, Kind(UNANNOTATED_MEMBER, fixable=True)),
+        *(
+            _body_scope(node.body, settings, Kind(UNANNOTATED_MEMBER, fixable=False, owner=node.name))
+            for node in classes(tree)
+            if not _is_enum(node, imported)
+        ),
+    ]
+
+
+def _body_scope(body: list[ast.stmt], settings: Settings, kind: Kind) -> "Scope":
+    """Check one module's or class's body.
+
+    Returns:
+      Its scope.
+
+    """
+    scope: Scope = Scope({"_"}, [], settings, kind)
+    stmt: ast.stmt
+    for stmt in body:
+        _visit(scope, stmt)
+    return scope
+
+
+def _is_enum(node: ast.ClassDef, imported: frozenset[str]) -> bool:
+    """Check whether a base is an enum: enum members mustn't be annotated.
+
+    Returns:
+      Whether a base is imported from `enum` (`imported`, however it's aliased), or else its name
+      ends in `Enum` or `Flag` (for one imported some other way).
+
+    """
+    return any(
+        node_name(base) in imported or node_name(base).endswith(("Enum", "Flag")) for base in node.bases
+    )
+
+
+def _function_scopes(
+    functions: list[FunctionDef],
+    settings: Settings,
+    table: returned.Table | None = None,
+) -> list["Scope"]:
+    """Check `functions` and every function defined inside them (recording each in `table`).
+
+    Returns:
+      Their scopes.
+
+    """
+    scopes: list[Scope] = []
+    func: FunctionDef
+    for func in functions:
+        nested: list[FunctionDef] = []
+        scope: Scope = function_scope(func, nested, settings)
+        scopes.append(scope)
+        if table is not None:
+            finish(table.module, [scope])
+            # Its returns are typed as it's checked; but one with late types (`None` rebound, ...) is
+            # checked again knowing them (`_returned`), and until then nothing's recorded: a caller
+            # would take its type too soon (`int`, for `None` rebound to `int`: `int | None`).
+            settled: bool = not scope.inferred.late.keys() - scope.inferred.seeded.keys()
+            table.checked(
+                func,
+                recorded.returns(scope, func, table.module) if settled else [],
+                (recorded.assigned(scope), recorded.used(scope, func, table.module)) if settled else ([], []),
+            )
+        scopes += _function_scopes(nested, scope.settings, table)
+    return scopes
+
+
+def function_scope(
+    func: FunctionDef,
+    functions: list[FunctionDef],
+    settings: Settings,
+    seed: Mapping[str, Late] | None = None,
+) -> "Scope":
+    """Check one function; functions defined in it are collected into `functions`.
+
+    `seed`: names already known to be typed late (see `Inferred.late`), known from the start.
+
+    Returns:
+      Its scope.
+
+    """
+    settings = unshadowed(settings, func)
+    args: ast.arguments = func.args
+    named: tuple[ast.arg, ...] = (*args.posonlyargs, *args.args, *args.kwonlyargs)
+    params: set[str] = {a.arg for a in named}
+    params.update(extra.arg for extra in (args.vararg, args.kwarg) if extra is not None)
+    # `_` is a discard.
+    scope: Scope = Scope(
+        params | {"_"},
+        functions,
+        settings,
+        Kind(UNANNOTATED, fixable=True, function=func),
+    )
+    # A copy of a plain, annotated parameter (`*args`/`**kwargs` aren't the type they're annotated
+    # with) can be typed the same way, the moment it's assigned.
+    scope.inferred.types.taking(
+        {arg.arg: written(arg.annotation) for arg in named if arg.annotation is not None},
+    )
+    # A method's `self` is its class's instance; so is the `self` a function defined in it reads.
+    owner: str | None = settings.owners.get(id(func))
+    if owner is not None and (_SELF not in params or [arg.arg for arg in named[:1]] == [_SELF]):
+        _ = scope.inferred.types.setdefault(_SELF, owner)
+    # A classmethod's first parameter is its class (`type[C]`), whatever it's called.
+    if owner is not None and named and [node_name(d) for d in func.decorator_list] == [_CLASSMETHOD]:
+        _ = scope.inferred.types.setdefault(named[0].arg, f"type[{owner}]")
+    seed_parameters(scope, func, named)
+    # What the module's top level binds once, the function reads as it's typed there.
+    name: str
+    passed: Passed
+    for name, passed in (settings.parameters or Seeded()).module.items():
+        scope.inferred.learn(name, passed[0], passed[1] or None)
+    arg: ast.arg
+    for arg in named:
+        # A parameter holds whatever its callers pass: its declared type, as far as value flow knows.
+        if arg.annotation is not None:
+            scope.lifetime(arg.arg).declare(ast.unparse(arg.annotation), (arg.lineno, arg.col_offset))
+        scope.lifetime(arg.arg).bind(
+            (arg.lineno, arg.col_offset),
+            None if arg.annotation is None else ast.unparse(arg.annotation),
+        )
+    scope.opaque(extra.arg for extra in (args.vararg, args.kwarg) if extra is not None)
+    typed: Late
+    for name, typed in (seed or {}).items():
+        scope.inferred.seeded[name] = typed
+        scope.inferred.learn(name, typed[0], typed[1] or None)
+    stmt: ast.stmt
+    for stmt in func.body:
+        _visit(scope, stmt)
+    return scope
+
+
+def _visit(scope: Scope, stmt: ast.stmt, head: ast.stmt | None = None) -> None:
+    """Bind the names `stmt` binds, as Python would, then visit its nested statements.
+
+    `head`: for an `elif`, the `if` it belongs to, which a declaration of its `:=`'s goes before.
+    """
+    part: ast.AST
+    walruses: tuple[Start, ...]
+    if walruses := scope.settings.walruses:  # most modules have no `:=`: none of their parts need a look
+        for part in expressions(stmt):
+            if has_within(walruses, part):  # a `:=` in it
+                binding.walruses(scope, part, head or stmt)
+    _declare(scope, stmt)
+    binding.bind(scope, stmt)
+    if isinstance(stmt, ast.Return):
+        scope.inferred.returns.append(stmt.value)
+    elif isinstance(stmt, ast.Assign):
+        scope.inferred.assigned.extend(
+            (target.attr, stmt.value)
+            for target in stmt.targets
+            if isinstance(target, ast.Attribute)
+            and isinstance(target.value, ast.Name)
+            and target.value.id == _SELF
+        )
+    # A loop's body runs again and again (not its `else`), for LVA012.
+    body: set[int] = (
+        {id(s) for s in stmt.body} if isinstance(stmt, ast.For | ast.AsyncFor | ast.While) else set()
+    )
+    before: dict[str, str] | None = dict(scope.inferred.types) if isinstance(stmt, BRANCHING) else None
+    # What has no known type before it, or where one of its arms ends: it may still, past it.
+    untyped: set[str] = set() if before is None else scope.declared - scope.inferred.types.keys()
+    ends: frozenset[int] = frozenset() if before is None else arm_ends(stmt)
+    child: ast.stmt
+    for child in child_statements(stmt):
+        scope.assignments.looping += id(child) in body
+        _visit(scope, child, (head or stmt) if _is_elif(stmt, child) else None)
+        scope.assignments.looping -= id(child) in body
+        if before is not None and id(child) in ends:
+            untyped |= scope.declared - scope.inferred.types.keys() - before.keys()
+    if before is not None:
+        scope.inferred.rejoined(before, frozenset(untyped))
+
+
+def _is_elif(stmt: ast.stmt, child: ast.stmt) -> bool:
+    """Check whether `child` is `stmt`'s `elif`: an `if`'s only `else` statement, an `if` at its own column.
+
+    Returns:
+      Whether it is.
+
+    """
+    return (
+        isinstance(stmt, ast.If)
+        and isinstance(child, ast.If)
+        and stmt.orelse == [child]
+        and child.col_offset == stmt.col_offset
+    )
+
+
+def _declare(scope: Scope, stmt: ast.stmt) -> None:
+    """Bind the names `stmt` binds that need no annotation, or carry their own."""
+    aliases: list[ast.alias]
+    names: list[str]
+    handlers: list[ast.ExceptHandler]
+    target: ast.Name
+    match stmt:
+        case ast.FunctionDef() | ast.AsyncFunctionDef():
+            scope.declared.add(stmt.name)
+            scope.opaque([stmt.name])
+            scope.nested.append(stmt)  # its body is its own scope
+        case ast.ClassDef():
+            scope.declared.add(stmt.name)
+            scope.opaque([stmt.name])
+            collect_functions(stmt.body, scope.nested)  # methods of a class defined in a function
+        case ast.Import(names=aliases) | ast.ImportFrom(names=aliases):
+            names = [(alias.asname or alias.name).split(".")[0] for alias in aliases]
+            scope.declared.update(names)
+            scope.opaque(names)
+        case ast.Global(names=names) | ast.Nonlocal(names=names):
+            scope.declared.update(names)
+        case ast.AnnAssign(target=ast.Name() as target):
+            binding.annotated(scope, stmt, target)
+        case _ if type(stmt).__name__ == _TYPE_ALIAS:
+            alias: ast.expr = cast("ast.expr", next(ast.iter_child_nodes(stmt)))  # its first field, the name
+            scope.declared.update(name.id for name in target_names(alias))
+        case ast.Try(handlers=handlers) | ast.TryStar(handlers=handlers):
+            names = [handler.name for handler in handlers if handler.name]
+            scope.declared.update(names)
+            scope.opaque(names)
+        case _:
+            pass
+
+
+def finish(tree: ast.Module, scopes: Sequence[Scope]) -> None:
+    """Finish `scopes` for their late fixes (`None` rebound, filled containers, shadowed types).
+
+    Those need the names written out of sight marked first. Safe to run again: marking is
+    idempotent, and no fix redoes one it made.
+    """
+    scope: Scope
+    for scope in scopes:
+        scope.mark_escaped(module_names(tree)[0])
+        late.optionals(scope)
+        late.rebinds(scope)
+        late.extended(scope)
+        late.fills(scope)
+        late.lambdas(scope)
+        late.widens(scope, tree)
+        binding.redeclared(scope)
+        late.shadowed(scope)
+        late.excused(scope)
+        late.unchecked(scope, tree)