python-constricter 0.4.1__cp313-cp313-win32.whl

constricter/__init__.py

@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: MIT
+"""Every local variable typed where it's first bound."""
+
+from constricter._version import __version__  # written by the build, from the git tag
+from constricter.offences import (
+    COMMENT_TYPED_TARGET,
+    DEFAULT_CHECKS,
+    FIX_KINDS,
+    LEVELS,
+    LONG_TUPLE,
+    MAX_LENGTH,
+    MISMATCHED_TYPE,
+    NARROWABLE_TYPE,
+    NESTED_TYPE,
+    NESTING,
+    REDUNDANT_TYPE,
+    UNANNOTATED,
+    UNANNOTATED_MEMBER,
+    UNTYPED_TARGET,
+    UNUSED_UNION_MEMBER,
+    VAGUE_TYPE,
+    Checks,
+    FixPolicy,
+    Level,
+    Offence,
+)
+from constricter.rules.checker import Coverage, annotation_coverage, check_source, check_tree
+
+__all__ = [
+    "COMMENT_TYPED_TARGET",
+    "DEFAULT_CHECKS",
+    "FIX_KINDS",
+    "LEVELS",
+    "LONG_TUPLE",
+    "MAX_LENGTH",
+    "MISMATCHED_TYPE",
+    "NARROWABLE_TYPE",
+    "NESTED_TYPE",
+    "NESTING",
+    "REDUNDANT_TYPE",
+    "UNANNOTATED",
+    "UNANNOTATED_MEMBER",
+    "UNTYPED_TARGET",
+    "UNUSED_UNION_MEMBER",
+    "VAGUE_TYPE",
+    "Checks",
+    "Coverage",
+    "FixPolicy",
+    "Level",
+    "Offence",
+    "__version__",
+    "annotation_coverage",
+    "check_source",
+    "check_tree",
+]

constricter/__main__.py

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: MIT
+"""`python -m constricter`, and the `constricter` script."""
+
+import contextlib
+import os
+import sys
+
+from constricter.cli.command import main
+
+
+def run() -> None:
+    """Run the command, and leave with its status at once.
+
+    Not by the interpreter's own exit, which frees every parsed file and the index an object at a
+    time: a fifth of a check of a thousand files. What the command wrote is flushed first; nothing
+    else waits on the exit (its workers have ended, its output file is closed).
+    """
+    status: int = main()
+    with contextlib.suppress(OSError, ValueError):  # a reader that left, a stream closed already
+        _ = sys.stdout.flush()
+        _ = sys.stderr.flush()
+    os._exit(status)
+
+
+if __name__ == "__main__":  # not when `--jobs` workers import it
+    run()

constricter/_version.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: MIT
+"""The version this was built as, from its git tag (written by the build, not tracked)."""
+
+__version__ = "0.4.1"

constricter/cli/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: MIT
+"""The `constricter` command (`command.main`): its options, the files it checks, and how it reports."""

constricter/cli/baseline.py

@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: MIT
+"""Baseline files: the offences a codebase already has, so only new ones are reported.
+
+An entry is a file, a code and a variable name, with how many times it occurs; line numbers aren't
+kept, so a baseline survives code moving around. Paths are relative to the baseline file.
+"""
+
+import json
+import os
+from collections import Counter
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Final, TypeAlias, cast
+
+from constricter import jsonc
+from constricter.offences import Offence
+
+VERSION: Final = 1
+Entries: TypeAlias = dict[str, dict[str, int]]  # file -> "CODE name" -> count
+_Json: TypeAlias = "str | int | float | bool | list[_Json] | dict[str, _Json] | None"
+
+
+def key(path: Path, baseline: Path) -> str:
+    """Make `path` relative to the baseline at `baseline`.
+
+    Returns:
+      `path` as the baseline records it: relative to it, with `/`.
+
+    """
+    return Path(os.path.relpath(path.resolve(), baseline.resolve().parent)).as_posix()
+
+
+def _entry(offence: Offence) -> str:
+    return f"{offence.code} {offence.name}"
+
+
+def read(baseline: Path) -> Entries:
+    """Return the entries in the baseline file `baseline`.
+
+    Returns:
+      Each file's count of each `CODE name` entry.
+
+    Raises:
+      ValueError: It can't be read, or isn't a baseline.
+
+    """
+    message: str
+    document: _Json
+    try:
+        document = cast("_Json", jsonc.loads(baseline.read_bytes()))
+    except (OSError, ValueError) as error:
+        message = f"{baseline}: can't read the baseline ({error}); create it with --write-baseline"
+        raise ValueError(message) from error
+    files: dict[str, _Json]
+    entries: Entries = {}
+    match document:
+        case {"version": 1, "offences": dict() as files}:
+            path: str
+            counts: _Json
+            for path, counts in files.items():
+                if not isinstance(counts, dict) or not all(jsonc.is_int(n) for n in counts.values()):
+                    break
+                entries[path] = {entry: n for entry, n in counts.items() if isinstance(n, int)}
+            else:
+                return entries
+        case _:
+            pass
+    message = f"{baseline}: not a constricter baseline (version {VERSION})"
+    raise ValueError(message)
+
+
+def write(baseline: Path, found: Mapping[str, Sequence[Offence]]) -> int:
+    """Write every offence in `found` (keyed as `key` makes them) to `baseline`.
+
+    Returns:
+      How many it wrote.
+
+    """
+    files: Entries = {
+        path: dict(sorted(Counter(_entry(o) for o in offences).items()))
+        for path, offences in sorted(found.items())
+        if offences
+    }
+    _ = baseline.write_text(
+        json.dumps({"version": VERSION, "offences": files}, indent=2) + "\n",
+        encoding="utf-8",
+        newline="\n",
+    )
+    return sum(len(offences) for offences in found.values())
+
+
+def remaining(offences: Sequence[Offence], counts: Mapping[str, int]) -> tuple[list[Offence], int]:
+    """Match one file's offences against the baseline's `counts` for it.
+
+    Returns:
+      The offences it doesn't cover, and how many it does.
+
+    """
+    left: Counter[str] = Counter(counts)
+    kept: list[Offence] = []
+    o: Offence
+    for o in offences:
+        if left[_entry(o)] > 0:
+            left[_entry(o)] -= 1
+        else:
+            kept.append(o)
+    return kept, len(offences) - len(kept)

constricter/cli/collecting.py

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: MIT
+"""The garbage collector, as the command runs it: by hand, once per file checked.
+
+A check keeps every file's tree (see `parsed`), and allocates a great deal for each file, little of it
+cyclic. Left to itself, the collector looked through the kept trees again and again as the check
+allocated: a third of the standard library's check (34s, 21s without). So while the command runs,
+it's off: what indexing built is frozen (never looked through again), and after each file, only
+what's been allocated since (the young generations) is collected, which bounds what a cycle can hold.
+Not on a free-threaded build, whose collector has no generations: each collection there looks through
+everything, and one after every file made a check several times as long. Its cycles wait for the run's
+end (a check of pandas held 2.9 GB so, to 2.7 GB).
+"""
+
+import contextlib
+import gc
+import sysconfig
+from collections.abc import Generator
+from typing import Final
+
+_YOUNG: Final = 1  # the generations collected after each file: 0 and 1, never the frozen or the old
+_FREEZES: Final = hasattr(gc, "freeze")  # PyPy's collector has no freezing
+# Whether the collector has generations: a free-threaded build's has none, its GIL on or off.
+_YOUNGER: Final = not sysconfig.get_config_var("Py_GIL_DISABLED")
+
+
+@contextlib.contextmanager
+def by_hand() -> Generator[None]:
+    """Turn automatic collection off for the command's run, and back as it was after.
+
+    Yields:
+      Nothing: the run.
+
+    """
+    was: bool = gc.isenabled()
+    gc.disable()
+    try:
+        yield
+    finally:
+        if _FREEZES:
+            gc.unfreeze()
+        if was:
+            gc.enable()
+
+
+def indexed() -> None:
+    """Freeze what indexing built (the kept trees, the index): it lives until the check takes it."""
+    if _FREEZES:
+        gc.freeze()
+
+
+def sweep() -> None:
+    """Collect what the file just checked left behind (see the module docstring)."""
+    if _YOUNGER:
+        _ = gc.collect(_YOUNG)