python-constricter 0.4.1__cp313-cp313-win32.whl

constricter/empty.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: MIT
+"""An empty mapping nothing can change: a record's default, where a `{}` is a dict every record shares."""
+
+from collections.abc import Iterator, Mapping
+from typing import NoReturn, TypeVar
+
+from constricter.overrides import override
+
+_K = TypeVar("_K")
+_V = TypeVar("_V")
+
+
+class Empty(Mapping[_K, _V]):
+    """A mapping of nothing, read-only, equal to `{}`, and pickled as itself: workers are sent records."""
+
+    __slots__: tuple[()] = ()
+
+    @override
+    def __getitem__(self, key: _K) -> NoReturn:
+        """Find nothing.
+
+        Raises:
+          KeyError: always.
+
+        """
+        raise KeyError(key)
+
+    @override
+    def __iter__(self) -> Iterator[_K]:
+        """Yield nothing.
+
+        Returns:
+          An empty iterator.
+
+        """
+        return iter(())
+
+    @override
+    def __len__(self) -> int:
+        """Count nothing.
+
+        Returns:
+          0.
+
+        """
+        return 0
+
+    @override
+    def __reduce__(self) -> "tuple[type[Empty[_K, _V]], tuple[()]]":
+        """Pickle as a new empty mapping.
+
+        Returns:
+          How.
+
+        """
+        return Empty, ()
+
+    @override
+    def __repr__(self) -> str:
+        """Write it as it's made.
+
+        Returns:
+          `Empty()`.
+
+        """
+        return "Empty()"

constricter/fix/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: MIT
+"""`--fix`: what a value makes its annotation, and adding it to the source."""

constricter/fix/core/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: MIT
+"""What every part of `--fix` shares: what it knows and infers, how a module names a type, writing a fix."""

constricter/fix/core/asked.py

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: MIT
+"""What a value was inferred to be, kept until its scope types another name.
+
+A statement's value is asked for its type, then for whether that's a guess, then as a part of the
+next value (a `with` statement's manager, three times): `asked` answers again what `keep` was told,
+for the same value (by `id`), the same scope's types (`Typed`) unchanged since, and the same number
+of imports the module's plan has added or guarded (an import `--fix` adds can resolve a name the
+next time).
+"""
+
+import ast
+from collections.abc import Mapping
+from typing import Final, TypeAlias
+
+from constricter.fix.core.known import ImportPlan, Inference, Known, Typed
+
+# What was asked: the value and the scope's types (by `id`), how often those had changed, and how
+# many imports the module's plan had added or guarded.
+_Asked: TypeAlias = tuple[int, int, int, int]
+# Its answer, with what was asked kept alive beside it: an `id` is only theirs while they live.
+_Answered: TypeAlias = tuple[ast.expr, Known, Typed, Inference | None]
+_ANSWERS: Final[dict[_Asked, _Answered]] = {}
+_KEPT: Final = 2048  # then all are dropped: a few functions' worth
+
+
+def _key(value: ast.expr, known: Known, declared: Typed) -> _Asked:
+    plan: ImportPlan | None = known.names.plan
+    return (
+        id(value),
+        id(declared),
+        declared.version,
+        0 if plan is None else len(plan.added) + len(plan.guarded),
+    )
+
+
+def asked(value: ast.expr, known: Known, declared: Mapping[str, str]) -> tuple[Inference | None] | None:
+    """Find what `value` was inferred to be, if it was asked before with nothing changed since.
+
+    Returns:
+      The inference (or `None`, for no type), in a tuple; `None` if it's yet to be worked out.
+
+    """
+    held: _Answered | None = (
+        _ANSWERS.get(_key(value, known, declared)) if isinstance(declared, Typed) else None
+    )
+    if held is None or held[0] is not value or held[1] is not known or held[2] is not declared:
+        return None
+    return (held[3],)
+
+
+def keep(value: ast.expr, known: Known, declared: Mapping[str, str], found: Inference | None) -> None:
+    """Keep what `value` was inferred to be, for a scope's own types (any other mapping may change unseen)."""
+    if isinstance(declared, Typed):
+        if len(_ANSWERS) >= _KEPT:
+            _ANSWERS.clear()
+        _ANSWERS[_key(value, known, declared)] = (value, known, declared, found)

constricter/fix/core/fixes.py

@@ -0,0 +1,317 @@
+# SPDX-License-Identifier: MIT
+"""`--fix`: write the annotations offences offer, to a file's lines or a notebook cell's."""
+
+import contextlib
+import re
+import unicodedata
+from collections.abc import Sequence
+from operator import itemgetter
+from typing import Final, NamedTuple, TypeAlias
+
+from constricter.offences import MARK, WIDEN_KINDS, Edit, Fix, Offence
+
+_HEADER: Final = 2  # a file's shebang and coding lines come first, if it has them
+# The last lines `_missing` read, stripped each way (see there): the lines, their count, and the set.
+_Present: TypeAlias = tuple[Sequence[str], int, frozenset[str]]
+_PRESENT: Final[dict[str | None, _Present]] = {}
+_HEADER_LINE: Final = re.compile(r"#!|#.*coding[:=]")
+_IDENTIFIER: Final = re.compile(r"\w+")
+_NORMAL: Final = "NFKC"  # how Python normalises an identifier: `ast` has a full-width `w` as `w`
+# Lines to insert, and the number of lines before them.
+_Run: TypeAlias = tuple[int, list[str]]
+# What orders the edits: a line, what's made there first (`_IMPORTS`, then an edit in the line,
+# then a `_DECLARATION` before it), and an edit's own line and column.
+_Place: TypeAlias = tuple[int, int, int, int]
+# An edit's place, and its offence (`None`: a run of imports).
+_Placed: TypeAlias = tuple[_Place, Offence | None]
+_IMPORTS: Final = 2
+_INLINE: Final = 1
+_DECLARATION: Final = 0
+
+
+class Replacement(NamedTuple):
+    """One fix as a text edit on `line` (from 1): after `prefix`, `deleted` becomes `text`.
+
+    A declaration inserts a whole line before its statement's: `prefix` and `deleted` are empty.
+    """
+
+    line: int
+    prefix: str  # the line's text before the edit
+    deleted: str
+    text: str
+
+    @property
+    def columns(self) -> tuple[int, int]:
+        """Where the edit starts and ends, in characters from 0."""
+        return len(self.prefix), len(self.prefix) + len(self.deleted)
+
+    @property
+    def byte_columns(self) -> tuple[int, int]:
+        """Where the edit starts and ends, in UTF-8 bytes from 0."""
+        start: int = len(self.prefix.encode())
+        return start, start + len(self.deleted.encode())
+
+
+def replacement(lines: Sequence[str], offence: Offence) -> Replacement | None:
+    """Turn `offence`'s edit into a text edit on `lines` (indexed from 1 by its line).
+
+    An `Edit.ANNOTATE` adds `: T` after the name; an `Edit.REPLACE` writes over the annotation
+    between its span's columns on the offence's line (an empty annotation deletes it); an
+    `Edit.DECLARE` inserts `name: T` on a line of its own before the statement its span names, at
+    that statement's indentation. A declaration's `drop` is a second edit: see `dropped`.
+
+    Returns:
+      The edit; none without a fix, or when its columns don't land on UTF-8 character boundaries in
+      its line (rare: `ast`'s column and a re-encoded line's bytes can disagree for some non-ASCII
+      source), rather than splitting a multi-byte character and corrupting the line.
+
+    """
+    fix: Fix | None
+    if (fix := offence.edit) is None:
+        return None
+    with contextlib.suppress(UnicodeDecodeError, IndexError):
+        if fix.edit is Edit.DECLARE:
+            statement: str = lines[fix.span[0] - 1]
+            indent: str = statement[: len(statement) - len(statement.lstrip())]
+            ending: str = statement.removeprefix(statement.rstrip("\r\n")) or "\n"
+            mark: str = f"  {MARK}" if fix.kinds & WIDEN_KINDS else ""
+            return Replacement(fix.span[0], "", "", f"{indent}{offence.name}: {fix.annotation}{mark}{ending}")
+        raw: bytes = lines[offence.line - 1].encode()
+        start: int = fix.span[0] if fix.edit is Edit.REPLACE else _name_end(raw, offence)
+        end: int = fix.span[1] if fix.edit is Edit.REPLACE else start
+        written: str = fix.annotation if fix.edit is Edit.REPLACE else f": {fix.annotation}"
+        return Replacement(offence.line, raw[:start].decode(), raw[start:end].decode(), written)
+    return None
+
+
+def _name_end(raw: bytes, offence: Offence) -> int:
+    """Find where the offence's name ends in its line `raw`, as the source spells it.
+
+    The source may spell it longer than `ast` has it, which normalises an identifier (a full-width
+    `w` is `w`).
+
+    Returns:
+      The column after it.
+
+    Raises:
+      IndexError: The line doesn't have the name there.
+
+    """
+    rest: str = raw[offence.col :].decode()
+    if rest.startswith(offence.name):
+        return offence.col + len(offence.name.encode())
+    spelled: re.Match[str] | None = _IDENTIFIER.match(rest)
+    if spelled is None or unicodedata.normalize(_NORMAL, spelled.group()) != offence.name:
+        raise IndexError(offence.col)
+    return offence.col + len(spelled.group().encode())
+
+
+def dropped(lines: Sequence[str], offence: Offence) -> Replacement | None:
+    """Turn a fix's `drop` into a text edit: deleting those columns of its statement's line.
+
+    A declaration's statement is the one it goes before; a replaced annotation's ends on the fix's
+    `mark` line (the offence's own, if none).
+
+    Returns:
+      The edit, or none without one (or with columns that don't land on characters, as
+      `replacement`'s).
+
+    """
+    fix: Fix | None = offence.edit
+    if fix is None or fix.drop is None:
+        return None
+    with contextlib.suppress(UnicodeDecodeError, IndexError):
+        line: int = fix.span[0] if fix.edit is Edit.DECLARE else fix.mark or offence.line
+        raw: bytes = lines[line - 1].encode()
+        start: int
+        end: int
+        start, end = fix.drop
+        return Replacement(line, raw[:start].decode(), raw[start:end].decode(), "")
+    return None
+
+
+def marked(lines: Sequence[str], offence: Offence) -> Replacement | None:
+    """Turn a widening's mark into a text edit: `MARK` at the end of its statement's last line.
+
+    Returns:
+      The edit, or none for any other fix, or a declaration (whose own line `replacement` marks).
+
+    """
+    fix: Fix | None = offence.edit
+    if fix is None or fix.edit is not Edit.ANNOTATE or not fix.kinds & WIDEN_KINDS:
+        return None
+    line: int = fix.mark or offence.line
+    return Replacement(line, lines[line - 1].rstrip("\r\n"), "", f"  {MARK}")
+
+
+def replacements(lines: Sequence[str], offence: Offence) -> tuple[Replacement, ...]:
+    """Turn `offence`'s fix into its text edits: `replacement`'s, `dropped`'s, `marked`'s, then its imports'.
+
+    Returns:
+      Them; none without a fix.
+
+    """
+    edits: list[Replacement | None] = [
+        replacement(lines, offence),
+        dropped(lines, offence),
+        marked(lines, offence),
+    ]
+    line: int
+    added: list[str]
+    for line, added in _imported(lines, [offence]):
+        edits.append(Replacement(line + 1, "", "", "".join(added)))
+    return tuple(edit for edit in edits if edit is not None)
+
+
+def inserted(lines: Sequence[str], offences: Sequence[Offence]) -> list[int]:
+    """Find where `apply` adds lines to `lines`: each declaration, and the imports the fixes need.
+
+    Returns:
+      For each line it adds, the line (from 1) it goes before, sorted.
+
+    """
+    found: list[int] = [
+        o.edit.span[0] for o in offences if o.edit is not None and o.edit.edit is Edit.DECLARE
+    ]
+    line: int
+    added: list[str]
+    for line, added in _imported(lines, offences):
+        found.extend([line + 1] * len(added))
+    return sorted(found)
+
+
+def _imported(lines: Sequence[str], offences: Sequence[Offence]) -> list["_Run"]:
+    """Place the imports `offences`' fixes need that `lines` doesn't have yet, each once.
+
+    Those for type checking alone go at the end of the body of the module's `if TYPE_CHECKING:`,
+    or, with none, in a new one after the others.
+
+    Returns:
+      Each run of lines to insert, with the number of lines before it, the last run first.
+
+    """
+    fixes: list[Fix]
+    if not (fixes := [o.edit for o in offences if o.edit and (o.edit.imports or o.edit.guarded)]):
+        return []
+    ending: str = _ending(lines)
+    statements: list[str] = _missing(lines, sorted({s for fix in fixes for s in fix.imports}), "\r\n")
+    guarded: list[str] = _missing(lines, sorted({s for fix in fixes for s in fix.guarded}), None)
+    line: int = _import_line(lines, next((fix.after for fix in fixes if fix.imports), fixes[0].after))
+    runs: list[_Run] = []
+    block: tuple[int, int] = fixes[0].block
+    if guarded and block != (0, 0):
+        indent: str = lines[block[0] - 1][: len(lines[block[0] - 1]) - len(lines[block[0] - 1].lstrip())]
+        runs.append((block[1], [f"{indent}{statement}{ending}" for statement in guarded]))
+    elif guarded:
+        guard: str = next(fix.guard for fix in fixes if fix.guarded)
+        statements += [f"if {guard}:", *(f"    {statement}" for statement in guarded)]
+    if statements:
+        runs.append((line, [f"{statement}{ending}" for statement in statements]))
+    return runs
+
+
+def _missing(lines: Sequence[str], statements: Sequence[str], stripped: str | None) -> list[str]:
+    """Find the import statements `lines` doesn't have yet, as a line of their own.
+
+    `stripped`: what a line may have around the statement: its line ending alone, for an import
+    that must run (an indented one is some block's, or a string's text, and may not), or any
+    whitespace (`None`), for one under `if TYPE_CHECKING:`.
+
+    Returns:
+      Them, in order.
+
+    """
+    if not statements:  # most fixes add none: the file's lines needn't be read for them
+        return []
+    # A file's fixes are asked one at a time, of the same lines: stripped once for them all.
+    held: _Present | None = _PRESENT.get(stripped)
+    if held is None or held[0] is not lines or held[1] != len(lines):
+        held = _PRESENT[stripped] = (
+            lines,
+            len(lines),
+            frozenset(line.rstrip(stripped) if stripped else line.strip() for line in lines),
+        )
+    return [statement for statement in statements if statement not in held[2]]
+
+
+def _import_line(lines: Sequence[str], after: int) -> int:
+    """Place added imports after line `after` (from 1), or at the top below a shebang or coding line.
+
+    Returns:
+      The number of lines before them.
+
+    """
+    if after:
+        return after
+    header: Sequence[str] = lines[:_HEADER]
+    return next((index for index, line in enumerate(header) if not _HEADER_LINE.match(line)), len(header))
+
+
+def _ending(lines: Sequence[str]) -> str:
+    """Find the file's line ending, from its first line.
+
+    Returns:
+      It (a newline for an empty file).
+
+    """
+    return next((line.removeprefix(line.rstrip("\r\n")) for line in lines[:1]), "") or "\n"
+
+
+def apply(lines: Sequence[str], offences: Sequence[Offence]) -> list[str]:
+    """Return `lines` with each fixable offence's edit made (see `replacement`).
+
+    The drops go first: each deletes the end of a statement's line (its type comment), so moves no
+    other edit, and one statement's is made once however many of its names declare. The rest, and
+    the imports the fixes need (each once, see `_imported`), are made from the last to the first, so
+    no edit moves one still to be made: on one line, the edits in it before the declarations that
+    go before it (`y: int`, then `x: int = f(y := 3)`), which keep their names' order; one
+    `replacement` can't make is left unmade.
+
+    Returns:
+      New lines; `lines` is left as it was. An offence's `line` indexes `lines` from 1.
+
+    """
+    text: list[str] = list(lines)
+    o: Offence
+    edit: Replacement | None
+    mark: Replacement | None
+    drops: dict[tuple[int, int, int], Replacement] = {}
+    for o in offences:
+        if (edit := dropped(text, o)) is not None:
+            drops[edit.line, *edit.byte_columns] = edit
+    for edit in (drops[key] for key in sorted(drops, reverse=True)):
+        kept: int = edit.columns[1]
+        text[edit.line - 1] = edit.prefix + text[edit.line - 1][kept:]
+    # Each run of imports goes after its line: before any edit on that line, in this order.
+    runs: dict[_Place, list[str]] = {(line, _IMPORTS, 0, 0): run for line, run in _imported(text, offences)}
+    edits: list[_Placed] = [(_position(o), o) for o in offences if o.edit]
+    placed: _Place
+    fixed: Offence | None
+    for placed, fixed in sorted([*edits, *((key, None) for key in runs)], key=itemgetter(0), reverse=True):
+        if fixed is None:
+            after: int = placed[0]
+            text[after:after] = runs[placed]
+        elif (edit := replacement(text, fixed)) is None:
+            continue
+        elif fixed.edit and fixed.edit.edit is Edit.DECLARE:
+            text.insert(edit.line - 1, edit.text)  # a declaration: a line of its own
+        else:
+            end: int = edit.columns[1]
+            text[edit.line - 1] = edit.prefix + edit.text + text[edit.line - 1][end:]
+            if (mark := marked(text, fixed)) is not None:
+                ending: str = text[mark.line - 1].removeprefix(mark.prefix)
+                text[mark.line - 1] = mark.prefix + mark.text + ending
+    return text
+
+
+def _position(offence: Offence) -> _Place:
+    """Place an offence's edit in the file, to order the edits by (see `_Place`).
+
+    Returns:
+      Its place: a declaration's line is the statement's it goes before.
+
+    """
+    fix: Fix | None = offence.edit
+    if fix is not None and fix.edit is Edit.DECLARE:
+        return fix.span[0], _DECLARATION, offence.line, offence.col
+    return offence.line, _INLINE, offence.line, offence.col