python-constricter 0.3.1__tar.gz → 0.3.2__tar.gz

{python_constricter-0.3.1 → python_constricter-0.3.2}/.gitignore

@@ -17,5 +17,31 @@ stdlib_tables/partial.json
 # Claude Code's agent worktrees: other checkouts of this repository.
 .claude/worktrees/
 
+# Claude Code's sandbox bind-mounts /dev/null over these denied paths while a
+# session runs; none is a file of this repo
+/.bash_profile
+/.bashrc
+/.gitconfig
+/.gitmodules
+/.idea
+/.mcp.json
+/.profile
+/.ripgreprc
+/.zprofile
+/.zshrc
+/.claude/agents
+/.claude/commands
+/.claude/hooks
+/.claude/launch.json
+/.claude/loop.md
+/.claude/output-styles
+/.claude/routines
+/.claude/scheduled_tasks.json
+/.claude/settings.json
+/.claude/settings.local.json
+/.claude/skills
+/.claude/workflows
+/.claude/.cc-writes
+
 # Backups merge tools leave next to a conflicted file.
 *.orig

{python_constricter-0.3.1 → python_constricter-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-constricter
-Version: 0.3.1
+Version: 0.3.2
 Import-Name: constricter
 Summary: Lint rules: every local variable is typed where it's first bound. A flake8 plugin, a pylint plugin and a standalone CLI.
 Author: Ivy Duggan
@@ -97,7 +97,7 @@ class bodies too. Statements are read in source order, and only a name's first b
 | `LVA002` | an untyped `for` target or `match` capture                                                | `name: T` first (or a type comment)            |
 | `LVA003` | a `for` target typed only by `# type: T`                                                  | `name: T` first                                |
 | `LVA004` | with `all-scopes`: the same as `LVA001`, in a module or class body                        | `name: T = ...` (`ClassVar[T]` in a dataclass) |
-| `LVA005` | an annotation with `Any`, `object` or a generic without its parameters                    | name the real type                             |
+| `LVA005` | an annotation with `Any`, `object` or a generic without its parameters, past `vague`      | name the real type                             |
 | `LVA006` | an annotation nested `nesting` deep (3 by default)                                        | a `type` alias for a part of it                |
 | `LVA007` | a name annotated again with the type it already has, in the same block                    | drop the second annotation                     |
 | `LVA008` | with every value the name ever holds known: an annotation that could narrow to them       | narrow it (`total: int`)                       |
@@ -109,7 +109,10 @@ class bodies too. Statements are read in source order, and only a name's first b
 Exempt: comprehensions, `except ... as`, imports, `def`/`class`, `type` aliases, parameters,
 `global`/`nonlocal`, and `_`; in module and class bodies, dunder names (`__all__`, `__slots__`) and
 enum members (a base imported from `enum`, however it's aliased, or else whose name ends in `Enum`
-or `Flag`).
+or `Flag`). And what makes a type, not a value, which an annotation would turn into a variable to a
+type checker: `T = TypeVar("T")`, a `ParamSpec`, a `TypeVarTuple`, a `NewType`, and a functional
+`NamedTuple`, `TypedDict`, `Enum` or `collections.namedtuple`, however `typing`,
+`typing_extensions`, `enum` or `collections` is imported.
 
 A `# type:` comment (`x = 1  # type: int`, `with f() as x:  # type: T`) counts as an annotation with
 `type-comments`, or automatically in a module written to run on Python 2: one that imports
@@ -174,16 +177,19 @@ Options:
 | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------- | --------------------------------- |
 | level            | `--level`                                                                                                                                                                    | `level`                                         | `--constricter-level`           | `constricter-level`               |
 | strictest        | `--max`: `--level=suffocate` for every path, `--all-scopes`, and the opt-in `LVA012`                                                                                         | —                                               | —                               | —                                 |
-| every fix        | `--max-fix`: `--max`, `--fix --unsafe-fixes`, and `--infer-with` each of basedpyright and ty that's installed and runs                                                       | —                                               | —                               | —                                 |
+| every fix        | `--max-fix`: `--max`, `--fix --unsafe-fixes`, and `--infer-with` each of basedpyright, ty and pyrefly that's installed and runs                                              | —                                               | —                               | —                                 |
 | type comments    | `--type-comments`                                                                                                                                                            | `type-comments`                                 | `--constricter-type-comments`   | `constricter-type-comments = yes` |
 | all scopes       | `--all-scopes`                                                                                                                                                               | `all-scopes`                                    | `--constricter-all-scopes`      | `constricter-all-scopes = yes`    |
 | nesting          | `--nesting N`                                                                                                                                                                | `nesting`                                       | `--constricter-nesting`         | `constricter-nesting`             |
 | max length       | `--max-length N` (LVA011)                                                                                                                                                    | `max-length`                                    | `--constricter-max-length`      | `constricter-max-length`          |
+| vague            | `--vague LEVEL` (LVA005, and the fixes offered): -1 none (the default), 0 one `Any` inside a type that says the rest (`tuple[str, Any]`), N from 1 N + 1, or one alone       | `vague`                                         | `--constricter-vague`           | `constricter-vague`               |
+| min python       | `--min-python VERSION` (the oldest Python the code runs on, whose syntax `--fix` writes; default: `requires-python`'s)                                                       | `min-python`                                    | -                               | -                                 |
 | type hierarchy   | -                                                                                                                                                                            | `narrower` (a table)                            | `--constricter-narrower`        | `constricter-narrower`            |
 | fix              | `--fix` (`--unsafe-fixes` for guesses), `--diff` to preview                                                                                                                  | -                                               | -                               | -                                 |
-| infer with       | `--infer-with CHECKERS` (`basedpyright`, `ty`, both: inferred types, as guesses)                                                                                             | `infer-with`                                    | -                               | -                                 |
+| infer with       | `--infer-with CHECKERS` (`basedpyright`, `ty`, `pyrefly`, several: inferred types, as guesses)                                                                               | `infer-with`                                    | -                               | -                                 |
 | show fixes       | `--show-fixes` (each fix and how it was decided, text)                                                                                                                       | -                                               | -                               | -                                 |
 | fix levels       | `--fix-select`, `--fix-ignore`, `--unsafe-fix-select` (mechanisms: [docs/FIXES.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/FIXES.md#fix-levels)) | `fix-select`, `fix-ignore`, `unsafe-fix-select` | -                               | -                                 |
+| fix plain bases  | `--fix-plain-bases BASES` (frameworks' classes whose subclasses' bodies `--fix` annotates; django's are built in)                                                            | `fix-plain-bases`                               | -                               | -                                 |
 | select           | `--select CODES` (codes or prefixes)                                                                                                                                         | `select`                                        | flake8's own `select`           | pylint's own `enable`             |
 | extend select    | `--extend-select CODES` (also report these; an opt-in code by its full code)                                                                                                 | `extend-select`                                 | flake8's own `extend-select`    | pylint's own `enable`             |
 | ignore           | `--ignore CODES`                                                                                                                                                             | `ignore`                                        | flake8's own `extend-ignore`    | pylint's own `disable`            |
@@ -212,6 +218,8 @@ type-comments = false
 all-scopes = true
 nesting = 3
 max-length = 4
+vague = -1 # the default: no `Any`; 0 lets `dict[str, Any]` through, 1 `Any` itself
+min-python = "3.11" # the default: your `requires-python`'s lower bound
 jobs = 0
 baseline = "constricter-baseline.json" # the default; relative to this pyproject.toml
 
@@ -237,8 +245,8 @@ return type or whose `return`s agree (in another checked file too), a copy, subs
 method call of a local whose type is known, and values computed from those; a loop's target or an
 unpacking's names get a declaration on the line before. `--unsafe-fixes` adds guesses, and
 `--show-fixes` lists each fix and how its value decided it. `--infer-with basedpyright` (or `ty`, or
-`basedpyright,ty`, installed alongside) asks those type checkers for what `--fix` can't type itself,
-as guesses. The full list is in
+`pyrefly`, or several: `basedpyright,ty`; each installed alongside) asks those type checkers for
+what `--fix` can't type itself, as guesses. The full list is in
 [docs/FIXES.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/FIXES.md).
 
 ### Installing and running
@@ -264,7 +272,7 @@ pre-commit, after ruff's hooks (or `constricter-fix`, which runs `--fix` first):
 
 ```yaml
 - repo: https://github.com/ivylikethevine/python-constricter
-  rev: v0.3.1
+  rev: v0.3.2
   hooks:
     - id: constricter
 ```

{python_constricter-0.3.1 → python_constricter-0.3.2}/README.md

@@ -70,7 +70,7 @@ class bodies too. Statements are read in source order, and only a name's first b
 | `LVA002` | an untyped `for` target or `match` capture                                                | `name: T` first (or a type comment)            |
 | `LVA003` | a `for` target typed only by `# type: T`                                                  | `name: T` first                                |
 | `LVA004` | with `all-scopes`: the same as `LVA001`, in a module or class body                        | `name: T = ...` (`ClassVar[T]` in a dataclass) |
-| `LVA005` | an annotation with `Any`, `object` or a generic without its parameters                    | name the real type                             |
+| `LVA005` | an annotation with `Any`, `object` or a generic without its parameters, past `vague`      | name the real type                             |
 | `LVA006` | an annotation nested `nesting` deep (3 by default)                                        | a `type` alias for a part of it                |
 | `LVA007` | a name annotated again with the type it already has, in the same block                    | drop the second annotation                     |
 | `LVA008` | with every value the name ever holds known: an annotation that could narrow to them       | narrow it (`total: int`)                       |
@@ -82,7 +82,10 @@ class bodies too. Statements are read in source order, and only a name's first b
 Exempt: comprehensions, `except ... as`, imports, `def`/`class`, `type` aliases, parameters,
 `global`/`nonlocal`, and `_`; in module and class bodies, dunder names (`__all__`, `__slots__`) and
 enum members (a base imported from `enum`, however it's aliased, or else whose name ends in `Enum`
-or `Flag`).
+or `Flag`). And what makes a type, not a value, which an annotation would turn into a variable to a
+type checker: `T = TypeVar("T")`, a `ParamSpec`, a `TypeVarTuple`, a `NewType`, and a functional
+`NamedTuple`, `TypedDict`, `Enum` or `collections.namedtuple`, however `typing`,
+`typing_extensions`, `enum` or `collections` is imported.
 
 A `# type:` comment (`x = 1  # type: int`, `with f() as x:  # type: T`) counts as an annotation with
 `type-comments`, or automatically in a module written to run on Python 2: one that imports
@@ -147,16 +150,19 @@ Options:
 | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------- | --------------------------------- |
 | level            | `--level`                                                                                                                                                                    | `level`                                         | `--constricter-level`           | `constricter-level`               |
 | strictest        | `--max`: `--level=suffocate` for every path, `--all-scopes`, and the opt-in `LVA012`                                                                                         | —                                               | —                               | —                                 |
-| every fix        | `--max-fix`: `--max`, `--fix --unsafe-fixes`, and `--infer-with` each of basedpyright and ty that's installed and runs                                                       | —                                               | —                               | —                                 |
+| every fix        | `--max-fix`: `--max`, `--fix --unsafe-fixes`, and `--infer-with` each of basedpyright, ty and pyrefly that's installed and runs                                              | —                                               | —                               | —                                 |
 | type comments    | `--type-comments`                                                                                                                                                            | `type-comments`                                 | `--constricter-type-comments`   | `constricter-type-comments = yes` |
 | all scopes       | `--all-scopes`                                                                                                                                                               | `all-scopes`                                    | `--constricter-all-scopes`      | `constricter-all-scopes = yes`    |
 | nesting          | `--nesting N`                                                                                                                                                                | `nesting`                                       | `--constricter-nesting`         | `constricter-nesting`             |
 | max length       | `--max-length N` (LVA011)                                                                                                                                                    | `max-length`                                    | `--constricter-max-length`      | `constricter-max-length`          |
+| vague            | `--vague LEVEL` (LVA005, and the fixes offered): -1 none (the default), 0 one `Any` inside a type that says the rest (`tuple[str, Any]`), N from 1 N + 1, or one alone       | `vague`                                         | `--constricter-vague`           | `constricter-vague`               |
+| min python       | `--min-python VERSION` (the oldest Python the code runs on, whose syntax `--fix` writes; default: `requires-python`'s)                                                       | `min-python`                                    | -                               | -                                 |
 | type hierarchy   | -                                                                                                                                                                            | `narrower` (a table)                            | `--constricter-narrower`        | `constricter-narrower`            |
 | fix              | `--fix` (`--unsafe-fixes` for guesses), `--diff` to preview                                                                                                                  | -                                               | -                               | -                                 |
-| infer with       | `--infer-with CHECKERS` (`basedpyright`, `ty`, both: inferred types, as guesses)                                                                                             | `infer-with`                                    | -                               | -                                 |
+| infer with       | `--infer-with CHECKERS` (`basedpyright`, `ty`, `pyrefly`, several: inferred types, as guesses)                                                                               | `infer-with`                                    | -                               | -                                 |
 | show fixes       | `--show-fixes` (each fix and how it was decided, text)                                                                                                                       | -                                               | -                               | -                                 |
 | fix levels       | `--fix-select`, `--fix-ignore`, `--unsafe-fix-select` (mechanisms: [docs/FIXES.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/FIXES.md#fix-levels)) | `fix-select`, `fix-ignore`, `unsafe-fix-select` | -                               | -                                 |
+| fix plain bases  | `--fix-plain-bases BASES` (frameworks' classes whose subclasses' bodies `--fix` annotates; django's are built in)                                                            | `fix-plain-bases`                               | -                               | -                                 |
 | select           | `--select CODES` (codes or prefixes)                                                                                                                                         | `select`                                        | flake8's own `select`           | pylint's own `enable`             |
 | extend select    | `--extend-select CODES` (also report these; an opt-in code by its full code)                                                                                                 | `extend-select`                                 | flake8's own `extend-select`    | pylint's own `enable`             |
 | ignore           | `--ignore CODES`                                                                                                                                                             | `ignore`                                        | flake8's own `extend-ignore`    | pylint's own `disable`            |
@@ -185,6 +191,8 @@ type-comments = false
 all-scopes = true
 nesting = 3
 max-length = 4
+vague = -1 # the default: no `Any`; 0 lets `dict[str, Any]` through, 1 `Any` itself
+min-python = "3.11" # the default: your `requires-python`'s lower bound
 jobs = 0
 baseline = "constricter-baseline.json" # the default; relative to this pyproject.toml
 
@@ -210,8 +218,8 @@ return type or whose `return`s agree (in another checked file too), a copy, subs
 method call of a local whose type is known, and values computed from those; a loop's target or an
 unpacking's names get a declaration on the line before. `--unsafe-fixes` adds guesses, and
 `--show-fixes` lists each fix and how its value decided it. `--infer-with basedpyright` (or `ty`, or
-`basedpyright,ty`, installed alongside) asks those type checkers for what `--fix` can't type itself,
-as guesses. The full list is in
+`pyrefly`, or several: `basedpyright,ty`; each installed alongside) asks those type checkers for
+what `--fix` can't type itself, as guesses. The full list is in
 [docs/FIXES.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/FIXES.md).
 
 ### Installing and running
@@ -237,7 +245,7 @@ pre-commit, after ruff's hooks (or `constricter-fix`, which runs `--fix` first):
 
 ```yaml
 - repo: https://github.com/ivylikethevine/python-constricter
-  rev: v0.3.1
+  rev: v0.3.2
   hooks:
     - id: constricter
 ```

{python_constricter-0.3.1 → python_constricter-0.3.2}/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",

{python_constricter-0.3.1 → python_constricter-0.3.2}/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,

{python_constricter-0.3.1 → python_constricter-0.3.2}/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

python_constricter-0.3.2/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 "")

{python_constricter-0.3.1 → python_constricter-0.3.2}/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"