python-constricter 0.4.1__cp313-cp313-win32.whl

constricter/fix/index/offers.py

@@ -0,0 +1,252 @@
+# SPDX-License-Identifier: MIT
+"""`--infer-with`: what a hint may name that the file doesn't bind where its annotations run.
+
+A hint is text, and a name in it may not be a type: basedpyright shows a value that is a module by
+the module's name, and a generic class without its arguments when it doesn't know them. So a name
+is taken only for a class or a type alias the index of checked files and installed packages
+defines: `own`, for what the file imports under `if TYPE_CHECKING:`; `vetted`, for what a hint's
+edits would import (the standard library's are `hinted`'s to judge, by its tables).
+"""
+
+import ast
+import re
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Final, NamedTuple, TypeAlias, cast
+
+from constricter.empty import Empty
+from constricter.fix.core.known import Guarded, Hints, Offered, Origin
+from constricter.fix.index import project
+from constricter.fix.index.modules import SUFFIX
+from constricter.fix.index.origins import absolute
+from constricter.fix.libraries import stdlib
+
+_PACKAGE: Final = "__init__"
+_STDLIB: Final = sys.stdlib_module_names
+_Defined: TypeAlias = tuple[str, str]  # where the index defines a class: its module, and its name there
+
+
+class Own(NamedTuple):
+    """The classes and aliases a file imports for type checking alone (`guarded`), and the generic ones."""
+
+    # A plain `dict`, not a `MappingProxyType`: the CLI's worker processes are sent it, pickled.
+    guarded: Mapping[str, Guarded] = Empty()
+    generics: frozenset[str] = frozenset()
+
+
+def own(catalog: project.Index, path: Path) -> Own:
+    """Find the classes the file at `path` imports under a top-level `if` (`if TYPE_CHECKING:`) alone.
+
+    Returns:
+      Those the index or the standard library's tables define; none for a file `catalog` doesn't have.
+
+    """
+    target: project.Module | None
+    if path.suffix != SUFFIX or (target := catalog.modules.get(project.module_name(path))) is None:
+        return Own()
+    found: dict[str, Guarded] = {}
+    generics: set[str] = set()
+    name: str
+    origin: Origin
+    for name, origin in target.guarded.items():
+        generic: bool | None = _class(catalog, origin)
+        if generic is not None and name not in target.names:
+            found[name] = Guarded(origin, None)
+            if generic:
+                generics.add(name)
+    return Own(found, frozenset(generics))
+
+
+def vetted(catalog: project.Index, path: Path, hints: tuple[Hints, ...]) -> tuple[Hints, ...]:
+    """Drop the edits of the file at `path`'s hints that import what isn't a class, or a generic one bare.
+
+    Returns:
+      The hints, without them: such a hint is judged by what it shows alone.
+
+    """
+    if not any(found.offered for found in hints):
+        return hints
+    module: tuple[str, bool] = (project.module_name(path), path.stem == _PACKAGE)
+    target: project.Module | None = catalog.modules.get(module[0])
+    checking: Mapping[str, Origin] = Empty() if target is None else target.guarded
+    found: dict[str, _Defined | None] = {name: _defined(catalog, origin) for name, origin in checking.items()}
+    guarded: dict[str, _Defined] = {name: defined for name, defined in found.items() if defined is not None}
+    return tuple(
+        _shared(
+            catalog,
+            module,
+            found._replace(
+                offered={
+                    where: offered
+                    for where, offered in found.offered.items()
+                    if _sound(catalog, module, offered, found.types.get(where, ""))
+                },
+            ),
+            guarded,
+        )
+        for found in hints
+    )
+
+
+def _shared(
+    catalog: project.Index,
+    module: tuple[str, bool],
+    found: Hints,
+    guarded: Mapping[str, _Defined],
+) -> Hints:
+    """Import one class by one statement in all of a file's hints' edits, the first's, as it's written once.
+
+    A checker's edits may import a class by any module that re-exports it (`pint`'s `Unit`, then
+    `pint.registry`'s): the first made the second's an import of a name taken, and its fix waited
+    for a second pass, which reads the name as the file's. A hint whose edits import another class
+    by a name the file imports for type checking (`guarded`, each where it's defined) is
+    dropped: judged by what it shows, it would be taken for that one. Only a class the index
+    defines: it doesn't follow the standard library's re-exports (`typing`'s `Callable`).
+
+    Returns:
+      The hints so.
+
+    """
+    first: dict[str, tuple[_Defined, str]] = {}  # each name's class, and its statement
+    types: dict[tuple[int, int], str] = dict(found.types)
+    offered: dict[tuple[int, int], Offered] = {}
+    where: tuple[int, int]
+    each: Offered
+    for where, each in sorted(found.offered.items()):
+        statements: list[str] = []
+        statement: str
+        for statement in each.imports:
+            name: str
+            origin: Origin
+            name, origin = _bound(module, statement)
+            defined: _Defined | None
+            if (defined := _defined(catalog, origin)) is None:
+                statements.append(statement)
+                continue
+            if name in guarded and guarded[name] != defined:
+                break
+            was: tuple[_Defined, str] = first.setdefault(name, (defined, statement))
+            statements.append(was[1] if was[0] == defined else statement)
+        else:
+            offered[where] = each._replace(imports=tuple(statements))
+            continue
+        _ = types.pop(where, None)
+    return found._replace(types=types, offered=offered)
+
+
+def imported(path: Path, hints: tuple[Hints, ...]) -> dict[str, Guarded]:
+    """Find what the file at `path`'s vetted hints' edits import for type checking alone.
+
+    For `linked.same`: a class an edit imports (`DataFrame`, from `pandas.core.frame`) is a spelling
+    of it beside the file's own (`pd.DataFrame`) in the pass that writes the import, as in the next.
+
+    Returns:
+      Each name one statement binds in every edit, with it.
+
+    """
+    module: tuple[str, bool] = (project.module_name(path), path.stem == _PACKAGE)
+    found: dict[str, Guarded] = {}
+    clashing: set[str] = set()
+    statement: str
+    for statement in {
+        statement for each in hints for offered in each.offered.values() for statement in offered.imports
+    }:
+        name: str
+        origin: Origin
+        name, origin = _bound(module, statement)
+        if name in found:
+            clashing.add(name)
+        found[name] = Guarded(origin, statement)
+    return {name: guarded for name, guarded in found.items() if name not in clashing}
+
+
+def _bound(module: tuple[str, bool], statement: str) -> tuple[str, Origin]:
+    """Read what a `from` import of a hint's edits binds, from the hinted file's `module`.
+
+    Returns:
+      The name it binds, and what that is.
+
+    """
+    node: ast.ImportFrom = cast("ast.ImportFrom", ast.parse(statement).body[0])
+    alias: ast.alias = node.names[0]
+    return alias.asname or alias.name, (
+        absolute(module[0], node.module, node.level, is_package=module[1]),
+        alias.name,
+    )
+
+
+def _defined(catalog: project.Index, origin: Origin) -> _Defined | None:
+    """Find where the index defines a class or a type alias, through re-exports.
+
+    Returns:
+      Its module and its name there; `None` where it doesn't.
+
+    """
+    kind: str
+    for kind in (project.CLASS, project.ALIAS):
+        found: tuple[project.Module, str] | None
+        if (found := project.definition(catalog.modules, origin, kind)) is not None:
+            return found[0].name, found[1]
+    return None
+
+
+def _sound(catalog: project.Index, module: tuple[str, bool], offered: Offered, shown: str) -> bool:
+    """Check that each import of a hint's edits names a class, and no generic one written bare.
+
+    `module`: the hinted file's module name, and whether it's a package's `__init__`; `shown`: what
+    the hint shows, which may write a class bare that its edit's spelling doesn't.
+
+    Returns:
+      Whether they do; an `import m`, which names no class, never does, nor an import from an
+      installed package's private module (`numpy._core`), which its next release may move.
+
+    """
+    statement: str
+    for statement in offered.imports:
+        try:
+            node: ast.stmt = ast.parse(statement).body[0]
+        except SyntaxError:  # from a file no import can name (`v3.0.0.c.py`)
+            return False
+        if not isinstance(node, ast.ImportFrom):
+            return False
+        alias: ast.alias = node.names[0]
+        origin: Origin = (absolute(module[0], node.module, node.level, is_package=module[1]), alias.name)
+        if origin[0].partition(".")[0] in _STDLIB:
+            continue
+        lone: re.Pattern[str] = re.compile(rf"(?<![\w.]){re.escape(alias.asname or alias.name)}(?![\w\[])")
+        generic: bool | None = _class(catalog, origin)
+        bare: bool = bool(generic and (lone.search(offered.text) or lone.search(shown)))
+        if generic is None or bare or _private(catalog, origin[0]):
+            return False
+    return True
+
+
+def _private(catalog: project.Index, name: str) -> bool:
+    """Check whether module `name` is an installed package's private one.
+
+    Returns:
+      Whether it is.
+
+    """
+    module: project.Module | None = catalog.modules.get(name)
+    return module is not None and module.installed and any(part.startswith("_") for part in name.split("."))
+
+
+def _class(catalog: project.Index, origin: Origin) -> bool | None:
+    """Find whether `origin` is a class or a type alias: an indexed module's (through re-exports).
+
+    Or a class of the standard library's.
+
+    Returns:
+      Whether it's generic, missing its arguments written bare; `None` if it's neither, to anyone's
+      knowledge.
+
+    """
+    defined: tuple[project.Module, str] | None
+    if (defined := project.definition(catalog.modules, origin, project.CLASS)) is not None:
+        return defined[1] in defined[0].generics
+    if (defined := project.definition(catalog.modules, origin, project.ALIAS)) is not None:
+        return defined[0].aliases[defined[1]]
+    path: str = f"{origin[0]}.{origin[1]}"
+    return stdlib.needs_arguments(path) if stdlib.defines_class(path) else None

constricter/fix/index/order.py

@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: MIT
+"""The order the CLI checks files in: each after those whose unannotated functions it calls.
+
+So their `return`s are known when it's checked (see `project.returned`); files calling each other's
+functions (a cycle in the graph `linked.needs` gives) form one component.
+"""
+
+from collections.abc import Iterator, Mapping, Sequence
+from pathlib import Path
+from typing import Final, NamedTuple, TypeAlias
+
+from constricter.fix.index import awaits, fixtures, linked, loose, managed, project
+from constricter.fix.index.project import Index
+
+_SUFFIX: Final = ".py"
+_Visit: TypeAlias = tuple[str, Iterator[str]]  # a module in the graph, and its callees still to visit
+
+
+class Plan(NamedTuple):
+    """The order to check files in (see `plan`), and the module each one's `returned` goes to."""
+
+    components: list[list[int]]  # files importing each other, by their index in the paths; callees first
+    after: list[frozenset[int]]  # the components each one's files import unannotated functions from
+    names: dict[int, str]  # each file's module name, if it's the only file with it
+
+
+def plan(catalog: Index, paths: Sequence[Path]) -> Plan:
+    """Order the files in `paths` for checking: each after the files whose unannotated functions it calls.
+
+    Those it imports and calls (through re-exports, or an imported module), so their `return`s are known
+    when it's checked (see `returned`); files calling each other's (a cycle) are one component. A
+    file `catalog` doesn't have, or one of several with the same module name, is one on its own.
+
+    Returns:
+      The components, callees first, and what each comes after; and each file's module.
+
+    """
+    names: list[str | None] = [
+        project.module_name(path) if path.suffix == _SUFFIX else None for path in paths
+    ]
+    counts: dict[str | None, int] = {}
+    name: str | None
+    for name in names:
+        counts[name] = counts.get(name, 0) + 1
+    unique: dict[str, int] = {
+        name: at
+        for at, name in enumerate(names)
+        if name is not None and counts[name] == 1 and name in catalog.modules
+    }
+    graph: dict[str, list[str]] = {
+        name: sorted(
+            (
+                linked.needs(catalog, catalog.modules[name])
+                | loose.needs(catalog, catalog.modules[name])
+                | managed.needs(catalog, catalog.modules[name])
+                | awaits.needs(catalog, catalog.modules[name])
+                | fixtures.needed(catalog, name)
+            )
+            & unique.keys(),
+        )
+        for name in sorted(unique)
+    }
+    components: list[list[int]] = []
+    after: list[frozenset[int]] = []
+    component: dict[str, int] = {}
+    members: frozenset[str]
+    for members in _Components(graph):  # callees' components first
+        member: str
+        for member in members:
+            component[member] = len(components)
+        after.append(
+            frozenset(
+                component[callee] for member in members for callee in graph[member] if callee not in members
+            ),
+        )
+        components.append(sorted(unique[member] for member in members))
+    at: int
+    for at in sorted(set(range(len(paths))) - set(unique.values())):
+        components.append([at])
+        after.append(frozenset())
+    return Plan(components, after, {at: name for name, at in unique.items()})
+
+
+class _Components:
+    """A graph's strongly connected components (Tarjan's, with a stack of its own: chains can be long)."""
+
+    def __init__(self, graph: Mapping[str, Sequence[str]]) -> None:
+        """Start on `graph`: each node's successors."""
+        self.graph: Mapping[str, Sequence[str]] = graph
+        self.order: dict[str, int] = {}  # each node visited, and when
+        self.low: dict[str, int] = {}  # the earliest node on the stack each node reaches
+        self.stack: list[str] = []
+        self.on_stack: set[str] = set()
+
+    def __iter__(self) -> Iterator[frozenset[str]]:
+        """Find the components.
+
+        Yields:
+          Each component, after every component it reaches.
+
+        """
+        start: str
+        for start in self.graph:
+            yield from self.reached(start)
+
+    def reached(self, start: str) -> Iterator[frozenset[str]]:
+        """Visit what `start` reaches that isn't visited yet (nothing, if it's been visited itself).
+
+        Yields:
+          Each component it completes.
+
+        """
+        if start in self.order:
+            return
+        # Each entry: a node, and its successors still to visit; `None` at the bottom ends it.
+        waiting: list[_Visit | None] = [None, self._visit(start)]
+        entry: _Visit
+        for entry in iter(waiting.pop, None):
+            node: str = entry[0]
+            successor: str | None
+            if (successor := next(entry[1], None)) is not None:
+                waiting.append(entry)
+                if successor not in self.order:
+                    waiting.append(self._visit(successor))
+                elif successor in self.on_stack:
+                    self.low[node] = min(self.low[node], self.order[successor])
+                continue
+            parent: _Visit | None
+            if (parent := waiting[-1]) is not None:
+                self.low[parent[0]] = min(self.low[parent[0]], self.low[node])
+            if self.low[node] == self.order[node]:
+                yield self._popped(node)
+
+    def _visit(self, node: str) -> _Visit:
+        """Put `node` on the stack.
+
+        Returns:
+          It, and its successors to visit.
+
+        """
+        self.order[node] = self.low[node] = len(self.order)
+        self.stack.append(node)
+        self.on_stack.add(node)
+        return node, iter(self.graph[node])
+
+    def _popped(self, node: str) -> frozenset[str]:
+        """Take `node`'s component off the stack: `node` and what's above it.
+
+        Returns:
+          The component.
+
+        """
+        members: list[str] = [*iter(self.stack.pop, node), node]
+        self.on_stack.difference_update(members)
+        return frozenset(members)

constricter/fix/index/origins.py

@@ -0,0 +1,238 @@
+# SPDX-License-Identifier: MIT
+"""Where each of a checked module's top-level names comes from (`Origin`), for `modules.read`.
+
+What it imports, under a top-level `if` or `try` too, and what it binds itself.
+"""
+
+import ast
+from collections.abc import Iterator, Mapping
+from typing import Final, cast
+
+from constricter.fix.core.known import Origin
+
+_PYTEST: Final = "pytest"
+_IMPORTORSKIP: Final = "importorskip"
+_MODNAME: Final = "modname"  # its parameter
+
+
+def absolute(name: str, module: str | None, level: int, *, is_package: bool) -> str:
+    """Resolve `from <.level><module> import ...` in module `name`.
+
+    Returns:
+      The absolute module name.
+
+    """
+    if not level:
+        return module or ""
+    package: list[str] = name.split(".") if is_package else name.split(".")[:-1]
+    base: list[str] = package[: len(package) - (level - 1)] if level > 1 else package
+    return ".".join([*base, *([module] if module else [])])
+
+
+def origins_of(tree: ast.Module, name: str, *, is_package: bool) -> dict[str, Origin]:
+    """Map module `name`'s top-level names (the last binding wins).
+
+    Returns:
+      What each refers to.
+
+    """
+    names: dict[str, Origin] = {}
+    stmt: ast.stmt
+    for stmt in tree.body:
+        match stmt:
+            case ast.Import() | ast.ImportFrom():
+                names.update(_imported(stmt, name, is_package=is_package))
+            case _:
+                names.update((bound, (name, bound)) for bound in _bound(stmt))
+    return names
+
+
+def _imported(stmt: ast.Import | ast.ImportFrom, name: str, *, is_package: bool) -> dict[str, Origin]:
+    """Map the names one import in module `name` binds.
+
+    Returns:
+      What each refers to.
+
+    """
+    names: dict[str, Origin] = {}
+    alias: ast.alias
+    if isinstance(stmt, ast.Import):
+        for alias in stmt.names:
+            if alias.asname:
+                names[alias.asname] = (alias.name, None)
+            else:  # `import a.b` binds `a`
+                names[alias.name.split(".")[0]] = (alias.name.split(".")[0], None)
+        return names
+    for alias in stmt.names:
+        names[alias.asname or alias.name] = (
+            absolute(name, stmt.module, stmt.level, is_package=is_package),
+            alias.name,
+        )
+    return names
+
+
+def guarded_origins(tree: ast.Module, name: str, *, is_package: bool) -> dict[str, Origin]:
+    """Map the names module `name` imports under a top-level `if` or `try` (`if TYPE_CHECKING:`).
+
+    Not what it binds at run time (`origins_of`): a type variable imported only for the checker is a type
+    variable all the same. Not a name two of them bind to different things (one in each branch of an
+    `if`): which it is, another file can't say.
+
+    Returns:
+      What each refers to.
+
+    """
+    found: dict[str, Origin] = {}
+    either: set[str] = set()
+    node: ast.AST
+    bound: str
+    origin: Origin
+    for node in (
+        n for stmt in tree.body if isinstance(stmt, ast.If | ast.Try | ast.TryStar) for n in ast.walk(stmt)
+    ):
+        if isinstance(node, ast.Import | ast.ImportFrom):
+            for bound, origin in _imported(node, name, is_package=is_package).items():
+                if found.setdefault(bound, origin) != origin:
+                    either.add(bound)
+    return {bound: origin for bound, origin in found.items() if bound not in either}
+
+
+def skipped(tree: ast.Module, names: Mapping[str, Origin]) -> dict[str, Origin]:
+    """Map each name the module binds to `pytest.importorskip("mod")` to that module, as an import binds it.
+
+    Wherever it's bound, in a function too: the name is the module (`import mod as name`) when every
+    binding of it in the module is such a call for that one module. `names`: the module's top-level
+    names (`origins_of`), which say how it imports `pytest`.
+
+    Returns:
+      Each such name, mapped to the module's origin.
+
+    """
+    found: dict[str, set[str]] = {}
+    calls: set[int] = set()
+    node: ast.AST
+    for node in ast.walk(tree):
+        target: str
+        stored: ast.Name
+        call: ast.Call
+        module: str | None
+        match node:
+            case ast.Assign(targets=[ast.Name(id=target) as stored], value=ast.Call() as call) if (
+                module := _skipped_module(call, names)
+            ) is not None:
+                found.setdefault(target, set()).add(module)
+                calls.add(id(stored))
+            case _:
+                pass
+    if not found:
+        return {}
+    others: set[str] = set(_bindings(tree, calls))
+    stmt: ast.Import | ast.ImportFrom
+    for stmt in (each for each in ast.walk(tree) if isinstance(each, ast.Import | ast.ImportFrom)):
+        alias: ast.alias
+        for alias in stmt.names:
+            bound: str = alias.asname or alias.name.partition(".")[0]
+            # `import mod` (or `import mod.sub as name`) binds the module it skips for: no other binding.
+            same: bool = isinstance(stmt, ast.Import) and found.get(bound) == {
+                alias.name if alias.asname else bound,
+            }
+            if not same:
+                others.add(bound)
+    return {
+        target: (next(iter(modules)), None)
+        for target, modules in found.items()
+        if len(modules) == 1 and target not in others
+    }
+
+
+def _bindings(tree: ast.Module, skipping: set[int]) -> Iterator[str]:
+    """Walk every name the module binds anywhere but by the `importorskip` calls (`skipping`, their targets).
+
+    Yields:
+      Each name: a store, a parameter, a definition or an `except`'s.
+
+    """
+    node: ast.AST
+    for node in ast.walk(tree):
+        match node:
+            case ast.Name(ctx=ast.Store() | ast.Del()) if id(node) not in skipping:
+                yield node.id
+            case ast.arg():
+                yield node.arg
+            case ast.FunctionDef() | ast.AsyncFunctionDef() | ast.ClassDef():
+                yield node.name
+            case ast.ExceptHandler(name=str()) | ast.MatchAs(name=str()) | ast.MatchStar(name=str()):
+                yield cast("str", node.name)
+            case _:
+                pass
+
+
+def _skipped_module(call: ast.Call, names: Mapping[str, Origin]) -> str | None:
+    """Find the module `pytest.importorskip(...)` imports: its first argument, a literal.
+
+    Returns:
+      Its name, or `None` for any other call, or a name that isn't a literal.
+
+    """
+    func: ast.expr = call.func
+    owner: str
+    attr: str
+    bound: str
+    origin: Origin | None
+    match func:
+        case ast.Attribute(value=ast.Name(id=owner), attr=attr) if attr == _IMPORTORSKIP:
+            origin = None if names.get(owner) != (_PYTEST, None) else (_PYTEST, _IMPORTORSKIP)
+        case ast.Name(id=bound):
+            origin = names.get(bound)
+        case _:
+            origin = None
+    if origin != (_PYTEST, _IMPORTORSKIP):
+        return None
+    named: list[ast.expr] = [*call.args[:1], *(k.value for k in call.keywords if k.arg == _MODNAME)]
+    module: str
+    match named:
+        case [ast.Constant(value=str() as module)] if all(part.isidentifier() for part in module.split(".")):
+            return module
+        case _:
+            return None
+
+
+def starred(tree: ast.Module, name: str, *, is_package: bool) -> tuple[str, ...]:
+    """List the modules module `name` imports everything from (`from .main import *`), in order.
+
+    At its top level, or under a top-level `if` or `try` (pydantic's `__init__`, for type checking).
+
+    Returns:
+      Their absolute names.
+
+    """
+    nodes: Iterator[ast.AST] = (
+        node
+        for stmt in tree.body
+        for node in (ast.walk(stmt) if isinstance(stmt, ast.If | ast.Try | ast.TryStar) else (stmt,))
+    )
+    return tuple(
+        absolute(name, node.module, node.level, is_package=is_package)
+        for node in nodes
+        if isinstance(node, ast.ImportFrom) and [alias.name for alias in node.names] == ["*"]
+    )
+
+
+def _bound(stmt: ast.stmt) -> Iterator[str]:
+    """Walk a top-level statement other than an import.
+
+    Yields:
+      Each name it binds.
+
+    """
+    node: ast.AST
+    match stmt:
+        case ast.FunctionDef() | ast.AsyncFunctionDef() | ast.ClassDef():
+            yield stmt.name
+        case ast.Assign() | ast.AnnAssign() | ast.AugAssign():
+            targets: list[ast.expr] = stmt.targets if isinstance(stmt, ast.Assign) else [stmt.target]
+            for node in (n for target in targets for n in ast.walk(target)):
+                if isinstance(node, ast.Name):
+                    yield node.id
+        case _:
+            pass