python-constricter 0.4.3__py3-none-any.whl → 0.4.5__py3-none-any.whl

constricter/_version.py

@@ -1,3 +1,3 @@
 """The version this was built as, from its git tag (written by the build, not tracked)."""
 
-__version__ = "0.4.3"
+__version__ = "0.4.5"

constricter/cli/command.py

@@ -17,7 +17,7 @@ from constricter.cli import baseline, collecting, schedule
 from constricter.cli.lsp.protocol import HintError
 from constricter.cli.options import Mode, Options, Output
 from constricter.cli.paths import STDIN, python_files
-from constricter.cli.reading import encoding_of, read_text
+from constricter.cli.reading import READ_ERRORS, encoding_of, read_text
 from constricter.cli.report import Format, Result, fix_reasons, render, statistics
 from constricter.cli.rounds import checked_all, settled
 from constricter.cli.runs import Added, BaselineRun, CheckRun, CoverageRun, FileRun
@@ -31,8 +31,8 @@ from constricter.offences import (
     Edit,
     Offence,
 )
-from constricter.rules import parsed
 from constricter.rules.checker import Checked, Coverage, annotation_coverage, checked_source
+from constricter.source import parsed
 
 if TYPE_CHECKING:  # slow to import, and only needed for `--infer-with`
     from types import ModuleType
@@ -42,7 +42,6 @@ if TYPE_CHECKING:  # slow to import, and only needed for `--infer-with`
 EXIT_CLEAN: Final = 0
 EXIT_FOUND: Final = 1
 EXIT_ERROR: Final = 2
-_ALL: Final = 100  # percent
 
 
 def _source(raw: str, name: Path) -> tuple[str, list[notebook.Line]]:
@@ -199,11 +198,21 @@ def _read_checked(
     checked: Checked
     try:
         raw, checked = _checked(path, name, checks, outside)
-    except (OSError, ValueError, SyntaxError) as error:  # UnicodeDecodeError is a ValueError
-        return "", Checked([], Returns()), f"{name}: error: {error}"
+    except READ_ERRORS as error:
+        return "", Checked([], Returns()), _error(name, error)
     return raw, checked, ""
 
 
+def _error(name: Path, error: Exception) -> str:
+    """Say why a file couldn't be read or parsed.
+
+    Returns:
+      The message.
+
+    """
+    return f"{name}: error: {error}"
+
+
 def _results(raw: str, name: Path, offences: Sequence[Offence], options: Options) -> list[Result]:
     """Turn the offences in `raw`, the text of `name`, into the results to report.
 
@@ -326,8 +335,8 @@ def _cover_path(path: Path, _outside: Outside, options: Options) -> CoverageRun:
     name: Path = options.input.name(path)
     try:
         return CoverageRun(annotation_coverage(_source(read_text(path), name)[0], options.checks))
-    except (OSError, ValueError, SyntaxError) as error:
-        return CoverageRun(error=f"{name}: error: {error}")
+    except READ_ERRORS as error:
+        return CoverageRun(error=_error(name, error))
 
 
 def _check_all(options: Options) -> tuple[list[Path], list[FileRun]]:

constricter/cli/config.py

@@ -220,11 +220,13 @@ def _checkers(value: _Toml) -> list[str] | None:
     """Read `infer-with`: a checker, or a list of them, each one it knows.
 
     Returns:
-      Them, or `None` for anything else.
+      Them, each once in the order they're preferred, as `--infer-with` gives them; `None` for
+      anything else.
 
     """
     checkers: list[str] | None = [value] if isinstance(value, str) else _strings(value)
-    return checkers if checkers and all(checker in SERVERS for checker in checkers) else None
+    known: bool = bool(checkers) and all(checker in SERVERS for checker in checkers or ())
+    return list(dict.fromkeys(checkers)) if checkers and known else None
 
 
 def _levels(value: _Toml) -> dict[str, str] | None:
@@ -247,7 +249,7 @@ def _lists(value: _Toml, read: Callable[[_Toml], list[str] | None]) -> dict[str,
     return None if None in lists.values() else {key: list(item or []) for key, item in lists.items()}
 
 
-def _baseline(value: _Toml, root: Path) -> str | None:
+def _path(value: _Toml, root: Path) -> str | None:
     """Read a baseline's or a trace's path, relative to `root` (the pyproject.toml that names it).
 
     Returns:
@@ -302,8 +304,8 @@ def config_defaults(start: Path) -> dict[str, Default]:
         return {}
     readers: dict[str, Callable[[_Toml], Default | None]] = {
         **_READERS,
-        "baseline": partial(_baseline, root=path.parent),
-        "infer-from": partial(_baseline, root=path.parent),
+        "baseline": partial(_path, root=path.parent),
+        "infer-from": partial(_path, root=path.parent),
     }
     defaults: dict[str, Default] = {}
     key: str

constricter/cli/explain.py

@@ -15,6 +15,7 @@ from constricter.offences import (
     UNANNOTATED,
     UNANNOTATED_ATTRIBUTE,
     UNANNOTATED_MEMBER,
+    UNANNOTATED_PARAMETER,
     UNANNOTATED_RETURN,
     UNTYPED_TARGET,
     UNUSED_UNION_MEMBER,
@@ -95,6 +96,13 @@ _WHY: Final = {
         "returns nothing. Off unless selected by its full code (`--extend-select LVA014`): ruff's ANN201\n"
         "reports it too; this is for the fix."
     ),
+    UNANNOTATED_PARAMETER: (
+        "A parameter with no annotation leaves the function's body to whatever a type checker\n"
+        "infers of it. `--fix` writes what typed it from outside, a guess: what every call passes it,\n"
+        "the one class with every member the function reads of it, its pytest fixture's value, or\n"
+        "the one type the checked files annotate its name with. Off unless selected by its full code\n"
+        "(`--extend-select LVA015`): ruff's ANN001 reports it too; this is for the fix."
+    ),
 }
 
 

constricter/cli/lsp/connection.py

@@ -5,7 +5,6 @@ The files it has open, the hint requests sent and not yet answered, and what it
 
 import contextlib
 import itertools
-import json
 import os
 import queue
 import re
@@ -329,7 +328,7 @@ class Connection:
 
         """
         self.last += 1
-        self._send({"jsonrpc": "2.0", _ID: self.last, _METHOD: method, "params": params})
+        self._send({_ID: self.last, _METHOD: method, "params": params})
         return self.last
 
     def _collect(self, numbers: set[int], method: str) -> dict[int, _Json]:
@@ -444,7 +443,7 @@ class Connection:
     def _answer(self, message: _Object) -> None:
         """Answer one of the server's own requests: its settings, and nothing else it asks for."""
         method: str = str(message[_METHOD])
-        reply: _Object = {"jsonrpc": "2.0", _ID: message[_ID]}
+        reply: _Object = {_ID: message[_ID]}
         if method == _CONFIGURATION:
             items: list[_Json] = cast("list[_Json]", cast("_Object", message["params"])["items"])
             reply["result"] = [protocol.settings(cast("_Object", item).get("section")) for item in items]
@@ -456,22 +455,18 @@ class Connection:
 
     def notify(self, method: str, params: _Json) -> None:
         """Send a notification: no answer comes."""
-        self._send({"jsonrpc": "2.0", "method": method, "params": params})
+        self._send({"method": method, "params": params})
 
     def _send(self, message: _Object) -> None:
-        """Frame and send one message.
+        """Frame and send one message (see `protocol.write`).
 
         Raises:
           ExitedError: The server has exited.
 
         """
-        body: bytes = json.dumps(message).encode()
         with self.writing:  # one message at a time: the reader answers the server's own meanwhile
             try:
-                protocol.write(
-                    cast("IO[bytes]", self.process.stdin),
-                    f"Content-Length: {len(body)}\r\n\r\n".encode() + body,
-                )
+                protocol.write(cast("IO[bytes]", self.process.stdin), message)
             except (OSError, ValueError) as error:  # it has gone, or its input was closed to stop it
                 failure: str = f"{self.name} exited: {error}"
                 raise ExitedError(failure) from error

constricter/cli/lsp/edits.py

@@ -19,7 +19,7 @@ from urllib.request import url2pathname
 from constricter.cli.lsp.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
+from constricter.source 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

constricter/cli/lsp/guard.py

@@ -1,6 +1,6 @@
 """Run a type checker's language server for `--infer-with`, so it can't outlive constricter.
 
-  python .../constricter/cli/guard.py GRACE EXECUTABLE [ARGUMENT ...]
+  python .../constricter/cli/lsp/guard.py GRACE EXECUTABLE [ARGUMENT ...]
 
 It imports only the standard library, so it runs by its path whatever the Python can import.
 
@@ -65,20 +65,23 @@ def main(argv: Sequence[str], stdin: IO[bytes] | None = None, stdout: IO[bytes]
 
 def _pass_on(source: IO[bytes], target: IO[bytes]) -> None:
     """Pass the server's output on until it ends (or constricter's end of it has gone)."""
-    chunk: bytes
     with contextlib.suppress(OSError):
-        for chunk in iter(lambda: _read(source), b""):
-            _write(target, chunk)
+        _copied(source, target)
+
+
+def _copied(source: IO[bytes], target: IO[bytes]) -> None:
+    """Copy `source` to `target` until it ends, each chunk as it comes: the reader waits on it."""
+    chunk: bytes
+    for chunk in iter(lambda: _read(source), b""):
+        _write(target, chunk)
 
 
 def relay_to(source: IO[bytes], server: "subprocess.Popen[bytes]", grace: float) -> None:
     """Pass `source` on to the server's input; when it ends, end the server's, and give it `grace` seconds."""
     target: IO[bytes] = cast("IO[bytes]", server.stdin)
-    chunk: bytes
     # The server has gone (or this is exiting, its input closed): nothing more to pass on.
     with contextlib.suppress(OSError, ValueError):
-        for chunk in iter(lambda: _read(source), b""):
-            _write(target, chunk)
+        _copied(source, target)
     with contextlib.suppress(OSError):  # what's left for a server that has gone is dropped
         target.close()
     try:

constricter/cli/lsp/hints.py

@@ -94,11 +94,7 @@ class Session:
 
     def __exit__(self, *_details: object) -> None:
         """Shut every server down, at once."""
-        running: list[Connection]
-        if running := [server for checker in self.checkers for server in checker.servers]:
-            pool: ThreadPoolExecutor
-            with ThreadPoolExecutor(len(running)) as pool:
-                _ = list(pool.map(Connection.close, running))
+        _closed([server for checker in self.checkers for server in checker.servers])
 
     def hints(self, files: Mapping[Path, str]) -> dict[Path, tuple[Hints, ...]]:
         """Ask every checker for the variable-type hints in `files` (each path's current text).
@@ -306,7 +302,7 @@ class Checker:  # pylint: disable=too-many-instance-attributes
         batches: queue.SimpleQueue[dict[Path, str]] = queue.SimpleQueue()
         start: int
         for start in range(0, len(fresh), _BATCH):
-            batch: list[Path] = fresh[start:][:_BATCH]
+            batch: list[Path] = fresh[start : start + _BATCH]
             batches.put({path: files[path] for path in batch})
         return [partial(self._work, index, own.get(index, {}), batches) for index in range(len(self.servers))]
 
@@ -337,11 +333,7 @@ class Checker:  # pylint: disable=too-many-instance-attributes
             except HintError as failure:  # it has gone since its last answers: past its cap, say
                 if not self._restartable(failure):
                     raise
-                unanswered: dict[Path, str] = {
-                    path: text for sent, _ in pending for path, text in sent.items()
-                }
-                pending.clear()
-                found.update(self._alone(index, unanswered | batch))
+                found.update(self._requeued(index, pending, batch))
                 continue
             if len(pending) > 1:
                 found.update(self._answers(index, pending))
@@ -367,12 +359,21 @@ class Checker:  # pylint: disable=too-many-instance-attributes
         except HintError as failure:
             if not self._restartable(failure):
                 raise
-            unanswered: dict[Path, str] = {path: text for batch, _ in pending for path, text in batch.items()}
-            pending.clear()
-            return self._alone(index, unanswered)
+            return self._requeued(index, pending, {})
         del pending[0]
         return found
 
+    def _requeued(self, index: int, pending: list[Sent], more: Mapping[Path, str]) -> Found:
+        """Ask server `index`, which failed, about each pending file and each of `more` alone (see `_alone`).
+
+        Returns:
+          Their hints.
+
+        """
+        unanswered: dict[Path, str] = {path: text for batch, _ in pending for path, text in batch.items()}
+        pending.clear()
+        return self._alone(index, unanswered | dict(more))
+
     def _alone(self, index: int, files: Mapping[Path, str]) -> Found:
         """Restart server `index`, which hung or exited past its cap, and ask it about each of `files` alone.
 
@@ -410,10 +411,7 @@ class Checker:  # pylint: disable=too-many-instance-attributes
 
     def stop(self) -> None:
         """Shut its servers down, at once: the next round starts others, which open each file anew."""
-        pool: ThreadPoolExecutor
-        # None where its turn had no file to ask about (a round with none, or every one abandoned).
-        with ThreadPoolExecutor(max(1, len(self.servers))) as pool:
-            _ = list(pool.map(Connection.close, self.servers))
+        _closed(self.servers)
         self.servers.clear()
         self.assigned.clear()
 
@@ -496,3 +494,10 @@ def command(checker: str) -> list[str]:
         )
         raise HintError(message)
     return [found, *server.args]
+
+
+def _closed(servers: Sequence[Connection]) -> None:
+    """Shut `servers` down, at once: none where a turn had no file to ask about."""
+    pool: ThreadPoolExecutor
+    with ThreadPoolExecutor(max(1, len(servers))) as pool:
+        _ = list(pool.map(Connection.close, servers))

constricter/cli/lsp/protocol.py

@@ -15,6 +15,7 @@ Json: TypeAlias = dict[str, "Json"] | list["Json"] | str | int | float | bool |
 Object: TypeAlias = dict[str, Json]
 _HEADER_END: Final = b"\r\n"
 _LENGTH: Final = "content-length"
+_JSONRPC: Final = "2.0"  # the version every message names, first
 _TYPE_HINT: Final = 1  # `InlayHintKind.Type`
 # Only variable types: argument names and return types are hints too, but nothing here.
 _BASEDPYRIGHT_SECTION: Final = "basedpyright.analysis"
@@ -91,14 +92,7 @@ def executable(checker: str) -> str | None:
       Its path, or `None` if it isn't installed.
 
     """
-    name: str = SERVERS[checker].executable
-    found: list[str] = list(
-        dict.fromkeys(
-            path
-            for path in (shutil.which(name), shutil.which(name, path=str(Path(sys.executable).parent)))
-            if path is not None
-        ),
-    )
+    found: list[str] = _found(checker)
     return next((path for path in found if _runs(path)), found[0] if found else None)
 
 
@@ -106,11 +100,27 @@ def runs(checker: str) -> bool:
     """Check that `checker` is installed, and runs.
 
     Returns:
-      Whether it does.
+      Whether it does: any of its servers found runs.
 
     """
-    found: str | None = executable(checker)
-    return found is not None and _runs(found)
+    return any(_runs(path) for path in _found(checker))
+
+
+def _found(checker: str) -> list[str]:
+    """Find `checker`'s language servers: on `PATH`, then beside this Python.
+
+    Returns:
+      Their paths, each once.
+
+    """
+    name: str = SERVERS[checker].executable
+    return list(
+        dict.fromkeys(
+            path
+            for path in (shutil.which(name), shutil.which(name, path=str(Path(sys.executable).parent)))
+            if path is not None
+        ),
+    )
 
 
 def _runs(path: str) -> bool:
@@ -144,9 +154,10 @@ class ExitedError(HintError):
     """The type checker's server exited while it was being asked: past its heap's cap, say."""
 
 
-def write(stream: IO[bytes], data: bytes) -> None:
-    """Write `data` to `stream`, and flush it: the server reads it now."""
-    _ = stream.write(data)
+def write(stream: IO[bytes], sent: Object) -> None:
+    """Frame `sent` (see `message`), write it to `stream`, and flush it: the server reads it now."""
+    body: bytes = json.dumps({"jsonrpc": _JSONRPC, **sent}).encode()
+    _ = stream.write(f"Content-Length: {len(body)}\r\n\r\n".encode() + body)
     stream.flush()
 
 

constricter/cli/lsp/remembered.py

@@ -29,9 +29,7 @@ def _marker(checker: str, command: Sequence[str], named: str) -> Path:
       Its path in the cache.
 
     """
-    made: str = ""
-    with contextlib.suppress(OSError):
-        made = build(checker, Path(command[0]))
+    made: str = build(checker, Path(command[0]))
     key: str = "\0".join((checker, command[0], made, named))
     return cache_directory().with_name("hung") / hashlib.sha256(key.encode("utf-8", "replace")).hexdigest()
 
@@ -43,15 +41,17 @@ def build(checker: str, executable: Path) -> str:
 
     Returns:
       The distribution's folder's name, which holds its version; else the executable's size and when
-      it changed.
+      it changed; empty where neither can be read.
 
     """
     pattern: str
-    for pattern in _DISTRIBUTIONS:
-        found: list[Path]
-        if found := sorted(executable.parent.parent.glob(f"{pattern}/{checker}-*.dist-info")):
-            return found[0].name
-    return f"{executable.stat().st_size}:{executable.stat().st_mtime_ns}"
+    with contextlib.suppress(OSError):
+        for pattern in _DISTRIBUTIONS:
+            found: list[Path]
+            if found := sorted(executable.parent.parent.glob(f"{pattern}/{checker}-*.dist-info")):
+                return found[0].name
+        return f"{executable.stat().st_size}:{executable.stat().st_mtime_ns}"
+    return ""
 
 
 def hung(checker: str, command: Sequence[str], text: str, path: Path | None = None) -> bool:

constricter/cli/lsp/stored.py

@@ -24,7 +24,7 @@ from collections.abc import Iterable, Mapping, Sequence
 from pathlib import Path
 from typing import Final, TypeAlias, TypedDict, cast
 
-from constricter.cli.lsp import connection, protocol, remembered
+from constricter.cli.lsp import connection, edits, protocol, remembered
 from constricter.cli.lsp.connection import FileHints, Found
 from constricter.fix.core.known import Offered
 from constricter.fix.index.stubs.installed import cache_directory, search_path
@@ -56,11 +56,12 @@ def key(checker: str, command: Sequence[str], root: Path, files: Mapping[Path, s
       A digest of everything they rest on (see the module docstring).
 
     """
-    build: str = ""
-    with contextlib.suppress(OSError):
-        build = remembered.build(checker, Path(command[0]))
+    build: str = remembered.build(checker, Path(command[0]))
     texts: list[str] = [checker, *command, build, *(os.environ.get(name, "") for name in _VARIABLES)]
-    parts: list[bytes] = [Path(cast("str", code.__file__)).read_bytes() for code in (connection, protocol)]
+    # The code that asks and reads them, `edits` the one that writes what the store keeps.
+    parts: list[bytes] = [
+        Path(cast("str", code.__file__)).read_bytes() for code in (connection, protocol, edits)
+    ]
     asked: dict[str, str] = {_relative(path, root): text for path, text in files.items()}
     name: str
     for name in sorted(asked):

constricter/cli/options.py

@@ -7,10 +7,10 @@ from collections.abc import Callable, Sequence
 from dataclasses import dataclass, field
 from enum import Enum
 from pathlib import Path
-from typing import Final, cast
+from typing import Final, Self, cast
 
-from constricter import __version__
-from constricter.cli import baseline, traced
+from constricter import __version__, traced
+from constricter.cli import baseline
 from constricter.cli.config import (
     DEFAULT_BASELINE,
     config_defaults,
@@ -33,6 +33,7 @@ from constricter.offences import (
     OPT_IN,
     PLAIN_BASES,
     UNANNOTATED_ATTRIBUTE,
+    UNANNOTATED_PARAMETER,
     UNANNOTATED_RETURN,
     VAGUE,
     Checks,
@@ -637,7 +638,7 @@ class Options:  # pylint: disable=too-many-instance-attributes
     infer_in_turn: bool = False  # ask one checker at a time, not all at once (`--infer-in-turn`)
 
     @classmethod
-    def parse(cls, argv: Sequence[str] | None) -> "Options":
+    def parse(cls, argv: Sequence[str] | None) -> Self:
         """Parse `argv` over the defaults `pyproject.toml` sets; `--explain` prints and exits.
 
         Returns:
@@ -679,6 +680,7 @@ class Options:  # pylint: disable=too-many-instance-attributes
                 final=CAN_BE_FINAL in {*_select(args), *cast("list[str]", args.extend_select)},
                 attributes=UNANNOTATED_ATTRIBUTE in {*_select(args), *cast("list[str]", args.extend_select)},
                 returns=UNANNOTATED_RETURN in {*_select(args), *cast("list[str]", args.extend_select)},
+                parameters=UNANNOTATED_PARAMETER in {*_select(args), *cast("list[str]", args.extend_select)},
                 fixes=FixPolicy(
                     frozenset(cast("list[str]", args.fix_select)),
                     frozenset(cast("list[str]", args.fix_ignore)),
@@ -744,7 +746,10 @@ def _maximal(args: argparse.Namespace) -> argparse.Namespace:
         args.per_path_levels = {}
         args.all_scopes = True
         # LVA014 only selected by itself: it's ruff's ANN201 again, for its fix.
-        args.extend_select = [*cast("list[str]", args.extend_select), *sorted(OPT_IN - {UNANNOTATED_RETURN})]
+        args.extend_select = [
+            *cast("list[str]", args.extend_select),
+            *sorted(OPT_IN - {UNANNOTATED_RETURN, UNANNOTATED_PARAMETER}),
+        ]
     return args
 
 

constricter/cli/reading.py

@@ -4,10 +4,15 @@ import io
 import sys
 import tokenize
 from pathlib import Path
+from typing import Final
 
 from constricter import notebook
 from constricter.cli.paths import STDIN
 
+# What reading or parsing a file raises: UnicodeDecodeError is a ValueError; a bad encoding
+# declaration, a SyntaxError.
+READ_ERRORS: Final = (OSError, ValueError, SyntaxError)
+
 
 def encoding_of(path: Path, data: bytes) -> str:
     """Find the encoding of `path`, whose bytes are `data`: a notebook's is UTF-8 (it's JSON).

constricter/cli/report.py

@@ -166,12 +166,21 @@ def _sarif(results: Sequence[Result]) -> dict[str, _Json]:
     }
 
 
+def _located(r: Result) -> str:
+    """Say where `r` is: its path, its cell in a notebook, its line and its column (from 1).
+
+    Returns:
+      It.
+
+    """
+    cell: str = "" if r.offence.cell is None else f"cell {r.offence.cell}:"
+    return f"{r.path}:{cell}{r.offence.line}:{r.offence.col + 1}"
+
+
 def _text(results: Sequence[Result]) -> Iterator[str]:
     r: Result
     for r in results:
-        cell: str = "" if r.offence.cell is None else f"cell {r.offence.cell}:"
-        where: str = f"{r.path}:{cell}{r.offence.line}:{r.offence.col + 1}"
-        yield f"{where}: {r.severity}: {r.offence.code} {r.offence.message}"
+        yield f"{_located(r)}: {r.severity}: {r.offence.code} {r.offence.message}"
 
 
 def _full(results: Sequence[Result]) -> Iterator[str]:
@@ -186,8 +195,7 @@ def _full(results: Sequence[Result]) -> Iterator[str]:
     for r in results:
         yield from _text([r])
         source: str = r.source
-        # `col` counts UTF-8 bytes, as `ast` does; the caret goes under that many characters.
-        start: int = len(source.encode()[: r.offence.col].decode(errors="ignore"))
+        start: int = _column(r)  # the caret goes under the name's first character
         width: int = len(r.offence.name) if source[start:].startswith(r.offence.name) else 1
         number: str = str(r.offence.line)
         gutter: str = " " * len(number)
@@ -374,8 +382,7 @@ def fix_reasons(results: Sequence[Result]) -> Iterator[str]:
     r: Result
     for r in results:
         if r.offence.fix is not None:
-            cell: str = "" if r.offence.cell is None else f"cell {r.offence.cell}:"
-            where: str = f"{r.path}:{cell}{r.offence.line}:{r.offence.col + 1}"
+            where: str = _located(r)
             flag: str = "--likely" if r.offence.likely else "--unsafe-fixes"
             guess: str = f" (a guess: {flag})" if r.offence.unsafe and not r.fixed else ""
             kinds: str = ", ".join(sorted(r.offence.edit.kinds if r.offence.edit else ()))