python-constricter 0.3.1__py3-none-any.whl → 0.3.2__py3-none-any.whl

constricter/__init__.py

@@ -25,7 +25,7 @@ from constricter.offences import (
 )
 from constricter.rules.checker import Coverage, annotation_coverage, check_source, check_tree
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"
 __all__ = [
     "COMMENT_TYPED_TARGET",
     "DEFAULT_CHECKS",

constricter/cli/command.py

@@ -23,8 +23,9 @@ from constricter.cli.protocol import HintError
 from constricter.cli.report import Format, Result, fix_reasons, render, statistics
 from constricter.cli.runs import BaselineRun, CheckRun, CoverageRun, FileRun
 from constricter.cli.workers import Workers
-from constricter.fix import callers, fixes, installed, project
-from constricter.fix.known import Callee, Hints, Outside, Returns
+from constricter.fix.core import fixes
+from constricter.fix.core.known import Callee, Hints, Outside, Returns
+from constricter.fix.index import callers, decorated, installed, plain, project
 from constricter.noqa import lines, unsuppressed
 from constricter.offences import (
     DEFAULT_CHECKS,
@@ -397,6 +398,11 @@ def _check_all(options: Options) -> tuple[list[Path], list[FileRun]]:
             for index, run in zip(again, redone, strict=True):
                 runs[index] = _merged(runs[index], run)
             again = [index for index, run in zip(again, redone, strict=True) if cast("CheckRun", run).fixed]
+        checker: str
+        path: Path
+        for checker, path in session.abandoned:
+            name: Path = options.input.name(path)
+            _ = sys.stderr.write(f"constricter: warning: {checker} hung on {name} twice: no hints for it\n")
     return names, runs
 
 
@@ -430,16 +436,40 @@ def _called_again(
     if not (again := [at for at, name in enumerate(names) if name in found and names.count(name) == 1]):
         return runs, modules
     calling: list[int] = _calling(runs, found, again)
-    modules = callers.with_parameters(modules, found)
-    which: list[int]
-    for which in (again, calling):
-        redone: list[FileRun]
-        redone, modules = _checked_all([paths[at] for at in which], check, options, session, modules)
-        at: int
-        run: FileRun
-        for at, run in zip(which, redone, strict=True):
-            runs[at] = _merged(runs[at], run) if options.mode is Mode.FIX else run
-    return runs, modules
+    before: project.Index = callers.with_parameters(modules, found)
+    modules = _checked_more(paths, runs, again, (check, options, session), before)
+    # A caller is checked again only if a function it imports now returns something else.
+    calling = [
+        at
+        for at in calling
+        if project.returned(modules, paths[at], {}) != project.returned(before, paths[at], {})
+    ]
+    return runs, _checked_more(paths, runs, calling, (check, options, session), modules)
+
+
+def _checked_more(
+    paths: Sequence[Path],
+    runs: list[FileRun],
+    which: Sequence[int],
+    how: "tuple[Callable[[Path, Outside], FileRun], Options, hints.Session | None]",
+    modules: project.Index,
+) -> project.Index:
+    """Check the files of `paths` at `which` again, knowing `modules`, into `runs`.
+
+    `how`: the check, the options and the type checkers' session. With `--fix` a file's rounds are
+    joined; otherwise the later one stands.
+
+    Returns:
+      The index, with what their functions now return.
+
+    """
+    redone: list[FileRun]
+    redone, modules = _checked_all([paths[at] for at in which], how[0], how[1], how[2], modules)
+    at: int
+    run: FileRun
+    for at, run in zip(which, redone, strict=True):
+        runs[at] = _merged(runs[at], run) if how[1].mode is Mode.FIX else run
+    return modules
 
 
 def _calling(
@@ -487,7 +517,10 @@ def _checked_all(
             modules = project.Index({}, []) if coverage else project.index(paths)
             collecting.indexed()
         if not coverage:
-            modules = installed.with_installed(modules, installed.search_path())
+            modules = plain.settled(
+                decorated.passed(installed.with_installed(modules, installed.search_path())),
+                options.checks.plain_bases,
+            )
         return schedule.checked(
             paths,
             check,

constricter/cli/config.py

@@ -1,11 +1,12 @@
 # SPDX-License-Identifier: MIT
 """The command's defaults, from the nearest `pyproject.toml`'s `[tool.constricter]` table."""
 
+import re
 import tomllib
 from collections.abc import Callable, Sequence
 from functools import partial
 from pathlib import Path
-from typing import TYPE_CHECKING, Final, TypeAlias
+from typing import TYPE_CHECKING, Final, TypeAlias, cast
 
 from constricter.cli.protocol import SERVERS
 from constricter.jsonc import is_int
@@ -30,6 +31,10 @@ def unknown_codes(codes: Sequence[str]) -> list[str]:
 
 
 DEFAULT_BASELINE: Final = "constricter-baseline.json"
+_MIN_PYTHON: Final = "min_python"
+_VERSION: Final = re.compile(r"\d+\.\d+")  # `min-python`'s: `3.11`
+# A lower bound among `requires-python`'s specifiers: `>=3.11`, `~=3.11`, `==3.11.*`, `>3.10`.
+_LOWER_BOUND: Final = re.compile(r"(?:>=|~=|==|>)\s*(\d+)(?:\.(\d+))?")
 
 
 def project_root(start: Path) -> Path:
@@ -58,36 +63,65 @@ def _pyproject(start: Path) -> Path | None:
     return None
 
 
-def _table(path: Path) -> dict[str, _Toml]:
-    """Return `path`'s `[tool.constricter]` table, or an empty one.
+def _document(path: Path) -> dict[str, _Toml]:
+    """Read `path`, a `pyproject.toml`.
 
     Returns:
-      The table's keys and values, as TOML parsed them.
+      Its tables, as TOML parsed them.
 
     Raises:
-      ValueError: The file isn't TOML, or `tool.constricter` isn't a table.
+      ValueError: The file isn't TOML.
 
     """
     file: BufferedReader
-    document: dict[str, _Toml]
-    message: str
     with path.open("rb") as file:
         try:
-            document = tomllib.load(file)
+            return tomllib.load(file)
         except tomllib.TOMLDecodeError as error:
-            message = f"{path}: {error}"
+            message: str = f"{path}: {error}"
             raise ValueError(message) from error
+
+
+def _table(path: Path, document: dict[str, _Toml]) -> dict[str, _Toml]:
+    """Return the `[tool.constricter]` table of `document` (`path`'s), or an empty one.
+
+    Returns:
+      The table's keys and values, as TOML parsed them.
+
+    Raises:
+      ValueError: `tool.constricter` isn't a table.
+
+    """
     table: dict[str, _Toml]
     match document.get("tool"):
         case {"constricter": dict() as table}:
             return table
         case {"constricter": _}:
-            message = f"{path}: [tool.constricter] isn't a table"
+            message: str = f"{path}: [tool.constricter] isn't a table"
             raise ValueError(message)
         case _:
             return {}
 
 
+def _required(document: dict[str, _Toml]) -> str | None:
+    """Read the oldest Python a project's `requires-python` allows: its highest lower bound.
+
+    Returns:
+      It (`3.11`, for `>=3.11,<4`), or `None` if the project doesn't say.
+
+    """
+    required: str
+    match document.get("project"):
+        case {"requires-python": str() as required}:
+            pass
+        case _:
+            return None
+    found: list[tuple[str, str]] = cast("list[tuple[str, str]]", _LOWER_BOUND.findall(required))
+    bounds: list[tuple[int, int]] = [(int(major), int(minor or 0)) for major, minor in found]
+    oldest: tuple[int, int] | None = max(bounds, default=None)
+    return None if oldest is None else f"{oldest[0]}.{oldest[1]}"
+
+
 def _level(value: _Toml) -> str | None:
     """Read a level's name or number as the options take it.
 
@@ -135,6 +169,16 @@ def _flag(value: _Toml) -> bool | None:
     return value if isinstance(value, bool) else None
 
 
+def _version(value: _Toml) -> str | None:
+    """Read `min-python`: a Python version, as text (`"3.11"`).
+
+    Returns:
+      It, or `None` for anything else.
+
+    """
+    return value if isinstance(value, str) and _VERSION.fullmatch(value) else None
+
+
 def _gigabytes(value: _Toml) -> float | None:
     """Read `infer-memory`: a positive number of gigabytes.
 
@@ -193,6 +237,7 @@ _READERS: dict[str, Callable[[_Toml], Default | None]] = {
     "level": _level,
     "nesting": partial(_whole, minimum=1),
     "max-length": partial(_whole, minimum=1),
+    "vague": partial(_whole, minimum=-1),
     "jobs": partial(_whole, minimum=0),
     "exclude": _strings,
     "select": _codes,
@@ -201,6 +246,7 @@ _READERS: dict[str, Callable[[_Toml], Default | None]] = {
     "fix-select": _fix_kinds,
     "fix-ignore": _fix_kinds,
     "unsafe-fix-select": _fix_kinds,
+    "fix-plain-bases": _strings,
     "type-comments": _flag,
     "all-scopes": _flag,
     "per-path-levels": _levels,
@@ -208,12 +254,15 @@ _READERS: dict[str, Callable[[_Toml], Default | None]] = {
     "narrower": partial(_lists, read=_strings),  # a type hierarchy: each type, and those it's narrower than
     "infer-with": _checkers,
     "infer-memory": _gigabytes,
+    "min-python": _version,
 }
 
 
 def config_defaults(start: Path) -> dict[str, Default]:
     """Return the option defaults in the nearest `pyproject.toml`'s `[tool.constricter]`.
 
+    And `min-python`'s from the project's `requires-python`, where the table doesn't set it.
+
     Returns:
       Each option's default, keyed by its `argparse` name (`type_comments`, not `type-comments`).
 
@@ -231,10 +280,14 @@ def config_defaults(start: Path) -> dict[str, Default]:
     defaults: dict[str, Default] = {}
     key: str
     value: _Toml
-    for key, value in _table(path).items():
+    document: dict[str, _Toml] = _document(path)
+    for key, value in _table(path, document).items():
         default: Default | None
         if key not in readers or (default := readers[key](value)) is None:
             message: str = f"{path}: [tool.constricter] has an invalid {key} = {value!r}"
             raise ValueError(message)
         defaults[key.replace("-", "_")] = default
+    required: str | None
+    if _MIN_PYTHON not in defaults and (required := _required(document)) is not None:
+        defaults[_MIN_PYTHON] = required
     return defaults

constricter/cli/edits.py

@@ -0,0 +1,188 @@
+# SPDX-License-Identifier: MIT
+"""`--infer-with`: what a hint's own edits would write (see `Offered`).
+
+An editor that accepts an inlay hint applies its `textEdits`: the annotation, spelled as the file can
+write it, and the imports its names take. An import comes as a statement to add
+(`from shapes import Shape`), or as names inserted into a `from` import the file has (`, Shape`).
+
+A hint with no edits (pyrefly's, for a loop's or an unpacking's names) may say where each class in
+its label is defined instead: the import is from the module that file is.
+"""
+
+import ast
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final, TypeAlias, cast
+from urllib.parse import urlsplit
+from urllib.request import url2pathname
+
+from constricter.cli.protocol import Json, Object
+from constricter.fix.core.known import Offered
+from constricter.fix.index.modules import SUFFIX, module_name
+from constricter.rules import parsed
+
+_Where: TypeAlias = tuple[int, int]  # a line (from 1) and a UTF-8 byte column, as `ast` counts
+_Locate: TypeAlias = Callable[[Object], _Where | None]  # a position's, or `None` past the file's end
+_SITE: Final = "site-packages"
+_BUNDLED: Final = "pyrefly_bundled_typeshed"  # how the folders pyrefly unpacks its stubs into start
+_STUBS: Final = "-stubs"  # a stub package's folder, after the package's name
+_PACKAGE: Final = "__init__"
+_BUILTINS: Final = "builtins"
+
+
+@dataclass
+class FromImports:
+    """A file's `from` imports (`found`), read from its `lines` when one is first looked for."""
+
+    lines: Sequence[str]
+    found: list[ast.ImportFrom] | None = None
+
+    def at(self, where: _Where) -> ast.ImportFrom | None:
+        """Find the `from` import `where` is in.
+
+        Returns:
+          It, or `None` (always, for a file that doesn't parse).
+
+        """
+        if self.found is None:
+            self.found = _from_imports(self.lines)
+        return next(
+            (
+                node
+                for node in self.found
+                if (node.lineno, node.col_offset)
+                <= where
+                <= (node.end_lineno or node.lineno, node.end_col_offset or 0)
+            ),
+            None,
+        )
+
+
+def _from_imports(lines: Sequence[str]) -> list[ast.ImportFrom]:
+    """Read a file's `from` imports, wherever they are.
+
+    Returns:
+      Them; none for a file that doesn't parse.
+
+    """
+    try:
+        tree: ast.Module = parsed.parse("\n".join(lines))
+    except (SyntaxError, ValueError):  # a null byte is a `ValueError` before Python 3.12
+        return []
+    return [node for node in ast.walk(tree) if isinstance(node, ast.ImportFrom)]
+
+
+def offered(hint: Object, label: str, locate: _Locate, existing: FromImports) -> Offered | None:
+    """Read what a variable-type hint (showing `label`) would write: its annotation and its imports.
+
+    Returns:
+      Them; `None` for a hint whose edits say no more than its label, one with an edit that is
+      neither, or one with no edits whose label doesn't say where a class in it is defined.
+
+    """
+    edits: list[Json]
+    if not (edits := cast("list[Json]", hint.get("textEdits") or [])):
+        located: tuple[str, ...] = _located(hint.get("label"))
+        return Offered(label, located) if located else None
+    text: str = ""
+    imports: list[str] = []
+    edit: Json
+    for edit in edits:
+        new: str = str(cast("Object", edit).get("newText", ""))
+        start: Object = cast("Object", cast("Object", cast("Object", edit)["range"])["start"])
+        if start == hint["position"] and new.startswith(":"):
+            text = new[1:].strip()
+            continue
+        found: list[str] | None
+        if (found := _imports(new.strip(), start, locate, existing)) is None:
+            return None
+        imports += found
+    return Offered(text, tuple(imports)) if text and (imports or text != label) else None
+
+
+def _located(label: Json) -> tuple[str, ...]:
+    """Read the imports a label's parts take: each class a part names, from the module its file is.
+
+    Returns:
+      A statement for each class whose defining file's module can be named, once; not a builtin's.
+
+    """
+    found: dict[str, None] = {}
+    part: Json
+    for part in label if isinstance(label, list) else []:
+        name: str = str(cast("Object", part).get("value", ""))
+        location: Json = cast("Object", part).get("location")
+        if location is None or not name.isidentifier():
+            continue
+        uri: str = str(cast("Object", location)["uri"])
+        module: str | None = _defined_in(Path(url2pathname(urlsplit(uri).path)))
+        if module and module != _BUILTINS:
+            found[f"from {module} import {name}"] = None
+    return tuple(found)
+
+
+def _defined_in(path: Path) -> str | None:
+    """Name the module a file is: an installed one, one of pyrefly's own stubs, or a project's.
+
+    Returns:
+      It, by the folders after `site-packages` or pyrefly's stubs' folder, else by its package
+      folders as the project index names it; `None` for a stub anywhere else, or no file at all.
+
+    """
+    if not path.name:  # a location that isn't a file's (`untitled:`)
+        return None
+    parts: tuple[str, ...] = path.with_suffix("").parts
+    index: int
+    part: str
+    for index, part in enumerate(parts[:-1]):
+        if part == _SITE or part.startswith(_BUNDLED):
+            after: int = index + 2
+            inside: list[str] = [parts[index + 1].removesuffix(_STUBS), *parts[after:]]
+            return ".".join(inside[:-1] if inside[-1] == _PACKAGE and len(inside) > 1 else inside)
+    return module_name(path) if path.suffix == SUFFIX else None
+
+
+def _imports(new: str, start: Object, locate: _Locate, existing: FromImports) -> list[str] | None:
+    """Read an edit that adds imports: whole statements, or names into a `from` import at `start`.
+
+    Returns:
+      Each name's import, as a statement of its own; `None` for any other edit.
+
+    """
+    try:
+        body: list[ast.stmt] = ast.parse(new).body
+    except SyntaxError:  # `, Shape`: names for an import the file has
+        body = []
+    if body and all(isinstance(stmt, ast.Import | ast.ImportFrom) for stmt in body):
+        return [statement for stmt in body for statement in _statements(stmt)]
+    where: _Where | None = locate(start)
+    node: ast.ImportFrom | None = None if where is None else existing.at(where)
+    names: list[str] = [name.strip() for name in new.split(",") if name.strip()]
+    if node is None or not names or not all(name.isidentifier() for name in names):
+        return None
+    return [f"from {_module(node)} import {name}" for name in names]
+
+
+def _statements(stmt: ast.stmt) -> list[str]:
+    """Write an import as one statement per name it binds.
+
+    Returns:
+      Them.
+
+    """
+    prefix: str = f"from {_module(stmt)} import " if isinstance(stmt, ast.ImportFrom) else "import "
+    return [
+        prefix + alias.name + (f" as {alias.asname}" if alias.asname else "")
+        for alias in cast("ast.Import | ast.ImportFrom", stmt).names
+    ]
+
+
+def _module(node: ast.ImportFrom) -> str:
+    """Write the module a `from` import names.
+
+    Returns:
+      It, a relative one with its dots.
+
+    """
+    return "." * node.level + (node.module or "")

constricter/cli/explain.py

@@ -43,7 +43,8 @@ _WHY: Final = {
     ),
     VAGUE_TYPE: (
         "`Any`, `object` and generics without their parameters (`list`, `dict`) say almost nothing\n"
-        "about the value. Name the real type: `list[str]`, a `TypedDict`, a union."
+        "about the value. Name the real type: `list[str]`, a `TypedDict`, a union. `vague` lets some\n"
+        "through: at 0 one inside a type that says the rest (`tuple[str, Any]`), at N N+1 or one alone."
     ),
     NESTED_TYPE: (
         "An annotation nested `nesting` deep (3 by default) is hard to read and to change. Name a part\n"