python-constricter 0.2.2__py3-none-any.whl

constricter/config.py

@@ -0,0 +1,177 @@
+# SPDX-License-Identifier: MIT
+"""The command's defaults, from the nearest `pyproject.toml`'s `[tool.constricter]` table."""
+
+import tomllib
+from collections.abc import Callable, Sequence
+from functools import partial
+from pathlib import Path
+from typing import TYPE_CHECKING, Final, TypeAlias
+
+from constricter.checker import LEVELS, MESSAGES
+
+if TYPE_CHECKING:
+    from datetime import date, datetime, time
+    from io import BufferedReader
+
+_Toml: TypeAlias = "str | int | float | bool | datetime | date | time | list[_Toml] | dict[str, _Toml]"
+Default: TypeAlias = str | int | bool | list[str] | dict[str, str] | dict[str, list[str]]
+
+
+def unknown_codes(codes: Sequence[str]) -> list[str]:
+    """Check `codes` (or code prefixes) against the known codes.
+
+    Returns:
+      Those that match none.
+
+    """
+    return [code for code in codes if not any(known.startswith(code.upper()) for known in MESSAGES)]
+
+
+DEFAULT_BASELINE: Final = "constricter-baseline.json"
+
+
+def project_root(start: Path) -> Path:
+    """Find the project's root.
+
+    Returns:
+      The directory of the nearest `pyproject.toml`, or `start` if there's none.
+
+    """
+    path: Path | None = _pyproject(start)
+    return start if path is None else path.parent
+
+
+def _pyproject(start: Path) -> Path | None:
+    """Find the nearest `pyproject.toml` in `start` or above it.
+
+    Returns:
+      Its path, or `None`.
+
+    """
+    directory: Path
+    path: Path
+    for directory in (start, *start.parents):
+        if (path := directory / "pyproject.toml").is_file():
+            return path
+    return None
+
+
+def _table(path: Path) -> dict[str, _Toml]:
+    """Return `path`'s `[tool.constricter]` table, or an empty one.
+
+    Returns:
+      The table's keys and values, as TOML parsed them.
+
+    Raises:
+      ValueError: The file isn't TOML, or `tool.constricter` isn't a table.
+
+    """
+    file: BufferedReader
+    document: dict[str, _Toml]
+    message: str
+    with path.open("rb") as file:
+        try:
+            document = tomllib.load(file)
+        except tomllib.TOMLDecodeError as error:
+            message = f"{path}: {error}"
+            raise ValueError(message) from error
+    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"
+            raise ValueError(message)
+        case _:
+            return {}
+
+
+def _level(value: _Toml) -> str | None:
+    """Read a level's name or number as the options take it.
+
+    Returns:
+      The level's name, or `None` if it isn't one.
+
+    """
+    text: str = str(value).lower()
+    return text if isinstance(value, str | int) and not isinstance(value, bool) and text in LEVELS else None
+
+
+def _whole(value: _Toml, minimum: int) -> int | None:
+    return value if isinstance(value, int) and not isinstance(value, bool) and value >= minimum else None
+
+
+def _strings(value: _Toml) -> list[str] | None:
+    return (
+        [str(item) for item in value]
+        if isinstance(value, list) and all(isinstance(item, str) for item in value)
+        else None
+    )
+
+
+def _codes(value: _Toml) -> list[str] | None:
+    codes: list[str] | None = _strings(value)
+    return None if codes is None or unknown_codes(codes) else [code.upper() for code in codes]
+
+
+def _flag(value: _Toml) -> bool | None:
+    return value if isinstance(value, bool) else None
+
+
+def _levels(value: _Toml) -> dict[str, str] | None:
+    if not isinstance(value, dict):
+        return None
+    levels: dict[str, str | None] = {glob: _level(level) for glob, level in value.items()}
+    return None if None in levels.values() else {glob: str(level) for glob, level in levels.items()}
+
+
+_BASELINE: Final = "baseline"
+
+
+def _ignores(value: _Toml) -> dict[str, list[str]] | None:
+    if not isinstance(value, dict):
+        return None
+    ignores: dict[str, list[str] | None] = {glob: _codes(codes) for glob, codes in value.items()}
+    return None if None in ignores.values() else {glob: list(codes or []) for glob, codes in ignores.items()}
+
+
+# Each key's reader: its option default, or `None` for a wrong value.
+_READERS: dict[str, Callable[[_Toml], Default | None]] = {
+    "level": _level,
+    "nesting": partial(_whole, minimum=1),
+    "jobs": partial(_whole, minimum=0),
+    "exclude": _strings,
+    "select": _codes,
+    "ignore": _codes,
+    "type-comments": _flag,
+    "all-scopes": _flag,
+    "per-path-levels": _levels,
+    "per-file-ignores": _ignores,
+    _BASELINE: lambda value: value if isinstance(value, str) and value else None,
+}
+
+
+def config_defaults(start: Path) -> dict[str, Default]:
+    """Return the option defaults in the nearest `pyproject.toml`'s `[tool.constricter]`.
+
+    Returns:
+      Each option's default, keyed by its `argparse` name (`type_comments`, not `type-comments`).
+
+    Raises:
+      ValueError: The file isn't TOML, or the table has an unknown key or a wrong value.
+
+    """
+    path: Path | None
+    if (path := _pyproject(start)) is None:
+        return {}
+    defaults: dict[str, Default] = {}
+    key: str
+    value: _Toml
+    for key, value in _table(path).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)
+        # A baseline path is relative to the pyproject.toml that names it.
+        defaults[key.replace("-", "_")] = str(path.parent / str(default)) if key == _BASELINE else default
+    return defaults

constricter/explain.py

@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: MIT
+"""Each code's rationale and fix, for `constricter --explain`."""
+
+from typing import Final
+
+from constricter.checker import (
+    COMMENT_TYPED_TARGET,
+    MESSAGES,
+    NESTED_TYPE,
+    UNANNOTATED,
+    UNANNOTATED_MEMBER,
+    UNTYPED_TARGET,
+    VAGUE_TYPE,
+    Level,
+    Offence,
+)
+
+_WHY: Final = {
+    UNANNOTATED: (
+        "A local's type should be written where it's first bound, not left to inference.\n"
+        "Annotate the binding (`count: int = 0`), or declare it first (`first: int`) when unpacking,\n"
+        "`:=` or `with ... as` binds it. `--fix` adds the annotation when the value decides it."
+    ),
+    UNTYPED_TARGET: (
+        "A `for` target or `match` capture binds a local with no annotation. Declare it before the\n"
+        "statement (`item: str`, then `for item in items:`)."
+    ),
+    COMMENT_TYPED_TARGET: (
+        "A `# type:` comment is the old, Python 2 form of an annotation, which some tools ignore.\n"
+        "Declare the variable before the loop instead."
+    ),
+    UNANNOTATED_MEMBER: (
+        "With `all-scopes`, module and class variables need annotating too (`LIMIT: int = 3`). In a\n"
+        "dataclass, use `ClassVar[T]`: a plain annotation there makes a field. Dunder names and enum\n"
+        "members are exempt."
+    ),
+    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."
+    ),
+    NESTED_TYPE: (
+        "An annotation nested `nesting` deep (5 by default) is hard to read and to change. Name a part\n"
+        "of it with an alias (`Row: TypeAlias = tuple[int, set[str]]`, then `dict[str, list[Row]]`)."
+    ),
+}
+
+
+def explain(code: str) -> str:
+    """Explain `code`.
+
+    Returns:
+      Its message, rationale and the levels that report it.
+
+    """
+    offence: Offence = Offence(1, 0, "name", code)
+    levels: list[str] = [
+        f"{level.name.lower()}: {'error' if offence.is_error(level) else 'warning'}"
+        for level in Level
+        if offence.is_reported(level)
+    ]
+    return f"{code}: {MESSAGES[code].format(name='`name`')}\n\n{_WHY[code]}\n\n{', '.join(levels)}\n"

constricter/fixes.py

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: MIT
+"""`--fix`: add the annotations offences offer, to a file's lines or a notebook cell's."""
+
+from collections.abc import Sequence
+
+from constricter.checker import Offence
+
+
+def apply(lines: Sequence[str], offences: Sequence[Offence]) -> list[str]:
+    """Return `lines` with each fixable offence's annotation added after its name.
+
+    Returns:
+      New lines; `lines` is left as it was. An offence's `line` indexes `lines` from 1.
+
+    """
+    text: list[str] = list(lines)
+    o: Offence
+    for o in sorted((o for o in offences if o.fix), key=lambda o: (o.line, o.col), reverse=True):
+        raw: bytes = text[o.line - 1].encode()
+        end: int = o.col + len(o.name.encode())  # `col` counts bytes, as `ast` does
+        text[o.line - 1] = (raw[:end] + f": {o.fix}".encode() + raw[end:]).decode()
+    return text

constricter/flake8_plugin.py

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: MIT
+"""The rules as a flake8 plugin (`LVA` prefix); reports the codes the level makes errors."""
+
+import argparse
+import ast
+from collections.abc import Iterator, Sequence
+from typing import TYPE_CHECKING, ClassVar, Final, cast, final
+
+from constricter import __version__
+from constricter.checker import LEVELS, NESTING, Checks, Level, Offence, check_source, check_tree
+
+if TYPE_CHECKING:
+    from flake8.options.manager import OptionManager
+
+_TYPE_COMMENT: Final = "type:"
+
+
+@final
+class ConstricterChecker:
+    """flake8's checker: one instance per file."""
+
+    name: str = "constricter"
+    version: str = __version__
+    level: ClassVar[Level] = Level.STRICT
+    type_comments: ClassVar[bool] = False
+    all_scopes: ClassVar[bool] = False
+    nesting: ClassVar[int] = NESTING
+
+    def __init__(self, tree: ast.Module, lines: Sequence[str]) -> None:
+        """Take the file flake8 parsed, and its lines."""
+        self.tree: ast.Module = tree
+        self.lines: Sequence[str] = lines
+
+    @classmethod
+    def add_options(cls, parser: "OptionManager") -> None:
+        """Register the options (flake8's plugin hook)."""
+        parser.add_option(
+            "--constricter-level",
+            choices=list(LEVELS),
+            default="strict",
+            parse_from_config=True,
+            help="which LVA codes are reported (default: strict)",
+        )
+        parser.add_option(
+            "--constricter-type-comments",
+            action="store_true",
+            parse_from_config=True,
+            help="count `x = 1  # type: int` as annotated",
+        )
+        parser.add_option(
+            "--constricter-all-scopes",
+            action="store_true",
+            parse_from_config=True,
+            help="also check module and class bodies (LVA004)",
+        )
+        parser.add_option(
+            "--constricter-nesting",
+            type=int,
+            default=NESTING,
+            parse_from_config=True,
+            help=f"report an annotation nested this deep (LVA006; default: {NESTING})",
+        )
+
+    @classmethod
+    def parse_options(cls, options: argparse.Namespace) -> None:
+        """Read the parsed options (flake8's plugin hook)."""
+        cls.level = LEVELS[cast("str", options.constricter_level)]
+        cls.type_comments = cast("bool", options.constricter_type_comments)
+        cls.all_scopes = cast("bool", options.constricter_all_scopes)
+        cls.nesting = cast("int", options.constricter_nesting)
+
+    def run(self) -> Iterator[tuple[int, int, str, type["ConstricterChecker"]]]:
+        """Check the file.
+
+        Yields:
+          flake8's `(line, col, message, type)` per error-level offence.
+
+        """
+        source: str = "".join(self.lines)
+        # flake8's tree has no `# type:` comments; reparse only when the file might have one.
+        checks: Checks = Checks(self.type_comments, self.all_scopes, self.nesting)
+        offences: list[Offence] = (
+            check_source(source, checks=checks)
+            if _TYPE_COMMENT in source
+            else check_tree(self.tree, checks, lines=self.lines)
+        )
+        o: Offence
+        for o in offences:
+            if o.is_error(self.level):
+                yield o.line, o.col, f"{o.code} {o.message}", type(self)

constricter/jsonc.py

@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: MIT
+"""JSON with comments (`//`, `/* */`) and trailing commas, for the files constricter reads.
+
+Comments and trailing commas become spaces (newlines kept), so every position the JSON parser reports
+is still the original file's. What constricter writes stays plain JSON.
+"""
+
+import json
+import re
+from typing import cast
+
+# A string (left alone), or a comment.
+_COMMENT: re.Pattern[str] = re.compile(r'"(?:\\.|[^"\\])*"|//[^\n]*|/\*.*?\*/', re.DOTALL)
+# A string (left alone), or a comma with only whitespace before the `]` or `}` it trails.
+_TRAILING: re.Pattern[str] = re.compile(r'"(?:\\.|[^"\\])*"|,(?=\s*[\]}])')
+
+
+def _blank(match: re.Match[str]) -> str:
+    text: str = match.group()
+    return text if text.startswith('"') else re.sub(r"[^\n]", " ", text)
+
+
+def loads(text: str | bytes) -> object:
+    """Parse JSON that may have comments and trailing commas.
+
+    Returns:
+      The value. Raises `ValueError` as `json.loads` does.
+
+    """
+    source: str = text.decode("utf-8") if isinstance(text, bytes) else text
+    return cast("object", json.loads(_TRAILING.sub(_blank, _COMMENT.sub(_blank, source))))

constricter/noqa.py

@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: MIT
+"""`# noqa` comments, read the same way by the CLI and the pylint plugin (flake8 reads its own)."""
+
+import io
+import re
+from collections.abc import Sequence
+
+from constricter.checker import Offence
+
+_NOQA: re.Pattern[str] = re.compile(
+    r"#\s*noqa(?::\s*(?P<codes>[A-Z]+[0-9]+(?:[,\s]+[A-Z]+[0-9]+)*))?",
+    re.IGNORECASE,
+)
+
+
+def lines(text: str) -> list[str]:
+    """Split `text` into lines as Python does (LF, CRLF or CR).
+
+    Returns:
+      The lines, each keeping its ending.
+
+    """
+    return io.StringIO(text, newline="").readlines()
+
+
+def suppressed(line: str, code: str) -> bool:
+    """Check `line` for a `# noqa` covering `code`: a bare one, or one naming it.
+
+    Returns:
+      Whether it has one.
+
+    """
+    match_: re.Match[str] | None
+    if (match_ := _NOQA.search(line)) is None:
+        return False
+    codes: str | None = match_.group("codes")
+    return codes is None or code in re.split(r"[,\s]+", codes.upper())
+
+
+def unsuppressed(offences: Sequence[Offence], source: Sequence[str]) -> list[Offence]:
+    """Apply the `# noqa` comments in `source`'s lines.
+
+    Returns:
+      The offences none on their line suppresses.
+
+    """
+    return [o for o in offences if not (o.line <= len(source) and suppressed(source[o.line - 1], o.code))]

constricter/notebook.py

@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: MIT
+"""Jupyter notebooks: their code cells, joined into one module, and where each line came from."""
+
+import json
+import re
+from collections.abc import Sequence
+from typing import Final, NamedTuple, TypeAlias, cast
+
+from constricter import fixes, jsonc
+from constricter.checker import Offence
+
+SUFFIX: Final = ".ipynb"
+_Json: TypeAlias = "str | int | float | bool | list[_Json] | dict[str, _Json] | None"
+# IPython syntax that isn't Python: line magics, shell escapes (`!ls`), and help (`obj?`, `?obj`).
+_MAGIC: re.Pattern[str] = re.compile(r"\s*([%!?]|[\w.]+\?{1,2}\s*$)")
+
+
+class Line(NamedTuple):
+    """Where a line of the joined module is in the notebook: its cell (from 1) and line in it."""
+
+    cell: int
+    line: int
+
+
+class Cell(NamedTuple):
+    """A cell `fix` changed: its number (from 1), and its lines before and after."""
+
+    number: int
+    old: list[str]
+    new: list[str]
+
+
+def _text(source: _Json) -> str:
+    """Join a cell's source, which a notebook keeps as a string or a list of lines.
+
+    Returns:
+      The source, as one string.
+
+    """
+    return "".join(str(part) for part in source) if isinstance(source, list) else str(source)
+
+
+def _cell_lines(source: _Json) -> list[str]:
+    """Split a cell into lines; IPython-only lines become blank.
+
+    Returns:
+      The lines, each ending in a newline.
+
+    """
+    lines: list[str] = _text(source).splitlines()
+    if lines and lines[0].lstrip().startswith("%%"):  # a cell magic: the whole cell isn't Python
+        return ["\n"] * len(lines)
+    return ["\n" if _MAGIC.match(line) else f"{line}\n" for line in lines]
+
+
+def parse(raw: str, name: str) -> tuple[str, list[Line]]:
+    """Return notebook JSON's code cells as one module, and where each of its lines came from.
+
+    Returns:
+      The module's source, and a `Line` for each of its lines.
+
+    Raises:
+      ValueError: It isn't a notebook (JSON with a `cells` list).
+
+    """
+    document: _Json = cast("_Json", jsonc.loads(raw))
+    cells: list[_Json]
+    match document:
+        case {"cells": list() as cells}:
+            pass
+        case _:
+            message: str = f"{name}: not a Jupyter notebook"
+            raise ValueError(message)
+    joined: list[str] = []
+    where: list[Line] = []
+    number: int
+    cell: _Json
+    source: _Json
+    for number, cell in enumerate(cells, start=1):
+        match cell:
+            case {"cell_type": "code", "source": source}:
+                lines: list[str] = _cell_lines(source)
+                joined += lines
+                where += [Line(number, line) for line in range(1, len(lines) + 1)]
+            case _:
+                pass
+    return "".join(joined), where
+
+
+def fix(raw: str, offences: Sequence[Offence]) -> tuple[str, list[Cell]]:
+    """Add each fixable offence's annotation in its cell of the notebook JSON `raw`.
+
+    Returns:
+      The notebook's new JSON (its indent, key order and final newline kept), and each changed
+      cell's number and old and new lines.
+
+    """
+    document: dict[str, _Json] = cast("dict[str, _Json]", jsonc.loads(raw))
+    cells: list[_Json] = cast("list[_Json]", document["cells"])
+    changed: list[Cell] = []
+    number: int
+    for number in sorted({o.cell for o in offences if o.fix and o.cell is not None}):
+        cell: dict[str, _Json] = cast("dict[str, _Json]", cells[number - 1])
+        source: _Json = cell["source"]
+        old: list[str] = _text(source).splitlines(keepends=True)
+        new: list[str] = fixes.apply(old, [o for o in offences if o.cell == number])
+        cell["source"] = list[_Json](new) if isinstance(source, list) else "".join(new)
+        changed.append(Cell(number, old, new))
+    indent: re.Match[str] | None = re.match(r"\{\r?\n( +)", raw)
+    text: str = json.dumps(document, indent=len(indent.group(1)) if indent else 1, ensure_ascii=False)
+    return text + ("\n" if raw.endswith("\n") else ""), changed