python-constricter 0.2.2__py3-none-any.whl

constricter/project.py

@@ -0,0 +1,229 @@
+# SPDX-License-Identifier: MIT
+"""Cross-module `--fix`: the return types of the functions other checked files define.
+
+`index` reads every file once for its module name, its top-level functions' declared return types
+(as `annotations.returns` picks them), and what each top-level name refers to. `calls` then gives a
+file the return type of each function it imports (`from m import f`, `import m as a` then `a.f()`),
+but only where every name in that type means the same thing in the file as where it was written:
+otherwise the fix would name something undefined, or something else.
+"""
+
+import ast
+import builtins
+import itertools
+from collections.abc import Iterator, Mapping, Sequence
+from pathlib import Path
+from typing import Final, NamedTuple, TypeAlias
+
+from constricter.annotations import returns
+
+_BUILTINS: Final = frozenset(dir(builtins))
+_PACKAGE: Final = "__init__"
+_SUFFIX: Final = ".py"
+_HOPS: Final = 5  # how many re-exports (`from .util import f` in an `__init__`) to follow
+# What a name refers to: a module and an attribute of it (`None`: the module itself).
+Origin: TypeAlias = tuple[str, str | None]
+
+
+class Module(NamedTuple):
+    """What one file offers and uses: its name, functions' return types, and names' origins."""
+
+    name: str
+    returns: dict[str, str]
+    names: dict[str, Origin]
+
+
+def module_name(path: Path) -> str:
+    """Name `path`'s module: its package folders (those with an `__init__.py`), then it.
+
+    Returns:
+      The dotted module name.
+
+    """
+    packages: list[Path] = list(
+        itertools.takewhile(
+            lambda folder: (folder / f"{_PACKAGE}{_SUFFIX}").is_file(),
+            path.resolve().parents,
+        ),
+    )
+    return ".".join(
+        [*(folder.name for folder in reversed(packages)), *([] if path.stem == _PACKAGE else [path.stem])],
+    )
+
+
+def _absolute(name: str, module: str | None, level: int, *, is_package: bool) -> str:
+    """Resolve `from <.level><module> import ...` in module `name`.
+
+    Returns:
+      The absolute module name.
+
+    """
+    if not level:
+        return module or ""
+    package: list[str] = name.split(".") if is_package else name.split(".")[:-1]
+    base: list[str] = package[: len(package) - (level - 1)] if level > 1 else package
+    return ".".join([*base, *([module] if module else [])])
+
+
+def _names(tree: ast.Module, name: str, *, is_package: bool) -> dict[str, Origin]:
+    """Map module `name`'s top-level names (the last binding wins).
+
+    Returns:
+      What each refers to.
+
+    """
+    names: dict[str, Origin] = {}
+    stmt: ast.stmt
+    alias: ast.alias
+    module: str | None
+    level: int
+    for stmt in tree.body:
+        match stmt:
+            case ast.Import():
+                for alias in stmt.names:
+                    if alias.asname:
+                        names[alias.asname] = (alias.name, None)
+                    else:  # `import a.b` binds `a`
+                        names[alias.name.split(".")[0]] = (alias.name.split(".")[0], None)
+            case ast.ImportFrom(module=module, level=level):
+                for alias in stmt.names:
+                    names[alias.asname or alias.name] = (
+                        _absolute(name, module, level, is_package=is_package),
+                        alias.name,
+                    )
+            case _:
+                names.update((bound, (name, bound)) for bound in _bound(stmt))
+    return names
+
+
+def _bound(stmt: ast.stmt) -> Iterator[str]:
+    """Walk a top-level statement other than an import.
+
+    Yields:
+      Each name it binds.
+
+    """
+    node: ast.AST
+    match stmt:
+        case ast.FunctionDef() | ast.AsyncFunctionDef() | ast.ClassDef():
+            yield stmt.name
+        case ast.Assign() | ast.AnnAssign() | ast.AugAssign():
+            targets: list[ast.expr] = stmt.targets if isinstance(stmt, ast.Assign) else [stmt.target]
+            for node in (n for target in targets for n in ast.walk(target)):
+                if isinstance(node, ast.Name):
+                    yield node.id
+        case _:
+            pass
+
+
+def index(paths: Sequence[Path]) -> dict[str, Module]:
+    """Read each `.py` file in `paths` (one that can't be read or parsed is left out).
+
+    Returns:
+      Each module's name, mapped to what it offers and uses.
+
+    """
+    modules: dict[str, Module] = {}
+    path: Path
+    for path in paths:
+        if path.suffix != _SUFFIX or not path.is_file():
+            continue
+        try:
+            tree: ast.Module = ast.parse(path.read_bytes(), str(path))
+        except (OSError, SyntaxError, ValueError):
+            continue
+        name: str = module_name(path)
+        modules[name] = Module(name, returns(tree), _names(tree, name, is_package=path.stem == _PACKAGE))
+    return modules
+
+
+def _origin(module: Module, name: str) -> Origin | None:
+    if name in module.names:
+        return module.names[name]
+    return ("builtins", name) if name in _BUILTINS else None
+
+
+def _roots(annotation: str) -> set[str]:
+    """Find the names an annotation (maybe a string one) starts from.
+
+    Returns:
+      The names: `m.Row` gives `m`.
+
+    """
+    tree: ast.expr = ast.parse(annotation, mode="eval").body
+    if isinstance(tree, ast.Constant) and isinstance(tree.value, str):
+        tree = ast.parse(tree.value, mode="eval").body
+    return {node.id for node in ast.walk(tree) if isinstance(node, ast.Name)}
+
+
+def _function(modules: Mapping[str, Module], origin: Origin, hops: int = _HOPS) -> tuple[Module, str] | None:
+    """Follow `origin` (through re-exports) to the module that defines it.
+
+    Returns:
+      That module and the function's name, or `None`.
+
+    """
+    module: Module | None = modules.get(origin[0])
+    attribute: str | None = origin[1]
+    if module is None or attribute is None or not hops:
+        return None
+    if attribute in module.returns:
+        return module, attribute
+    onward: Origin | None = module.names.get(attribute)
+    return _function(modules, onward, hops - 1) if onward and onward[0] != module.name else None
+
+
+def calls(modules: Mapping[str, Module], path: Path) -> dict[str, str]:
+    """Return, for the file at `path`, the return type of each function it imports whose type it can name.
+
+    Returns:
+      Each call's name as written (`helper`, `u.helper`, `pkg.util.helper`), mapped to its type; nothing
+      for a file `modules` doesn't have (a notebook, standard input).
+
+    """
+    name: str = module_name(path)
+    target: Module | None
+    if path.suffix != _SUFFIX or (target := modules.get(name)) is None:
+        return {}
+    found: dict[str, str] = {}
+    local: str
+    origin: Origin
+    for local, origin in target.names.items():
+        if origin[1] is not None and origin[0] != name:
+            _add(found, modules, target, local, origin)
+        elif origin[1] is None:  # a module: `u.f()`, or `pkg.util.f()` after `import pkg.util`
+            other: Module
+            for other in modules.values():
+                if other.name == origin[0] or other.name.startswith(f"{origin[0]}."):
+                    prefix: str = local + other.name.removeprefix(origin[0])
+                    function: str
+                    for function in other.returns:
+                        _add(found, modules, target, f"{prefix}.{function}", (other.name, function))
+    return found
+
+
+def _add(
+    found: dict[str, str],
+    modules: Mapping[str, Module],
+    target: Module,
+    key: str,
+    origin: Origin,
+) -> None:
+    """Record `key`'s return type in `found` if every name in it means the same in `target`."""
+    defined: tuple[Module, str] | None
+    if (defined := _function(modules, origin)) is None:
+        return
+    annotation: str = defined[0].returns[defined[1]]
+    if all(_same(target, defined[0], root) for root in _roots(annotation)):
+        found[key] = annotation
+
+
+def _same(target: Module, defined: Module, name: str) -> bool:
+    """Compare what `name` refers to in both modules.
+
+    Returns:
+      Whether it's something, and the same thing.
+
+    """
+    origin: Origin | None = _origin(target, name)
+    return origin is not None and origin == _origin(defined, name)

constricter/pylint_plugin.py

@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: MIT
+"""The rules as a pylint plugin (C9101-C9106); reports the codes the level makes errors."""
+
+from typing import IO, TYPE_CHECKING, NamedTuple, cast, final
+
+from astroid import nodes
+from pylint.checkers import BaseRawFileChecker
+from pylint.lint import PyLinter
+from pylint.typing import Options
+
+from constricter.checker import (
+    COMMENT_TYPED_TARGET,
+    LEVELS,
+    MESSAGES,
+    NESTED_TYPE,
+    NESTING,
+    UNANNOTATED,
+    UNANNOTATED_MEMBER,
+    UNTYPED_TARGET,
+    VAGUE_TYPE,
+    Checks,
+    Level,
+    Offence,
+    check_source,
+)
+from constricter.noqa import lines, unsuppressed
+
+if TYPE_CHECKING:
+    from typing_extensions import override  # `typing.override` is 3.12+
+else:
+
+    def override(func: object) -> object:
+        """Mark an override (for type checkers only).
+
+        Returns:
+          `func`, unchanged.
+
+        """
+        return func
+
+
+class Message(NamedTuple):
+    """A code's pylint message id and symbol."""
+
+    msg_id: str
+    symbol: str
+
+
+SYMBOLS: dict[str, Message] = {
+    UNANNOTATED: Message("C9101", "unannotated-local-variable"),
+    UNTYPED_TARGET: Message("C9102", "untyped-for-or-match-variable"),
+    COMMENT_TYPED_TARGET: Message("C9103", "comment-typed-for-variable"),
+    UNANNOTATED_MEMBER: Message("C9104", "unannotated-module-or-class-variable"),
+    VAGUE_TYPE: Message("C9105", "vague-annotation"),
+    NESTED_TYPE: Message("C9106", "deeply-nested-annotation"),
+}
+
+
+@final
+class ConstricterChecker(BaseRawFileChecker):
+    """pylint's checker, run once per module on its raw source."""
+
+    name: str = "constricter"
+    options: Options = (
+        (
+            "constricter-level",
+            {
+                "default": "strict",
+                "type": "choice",
+                "choices": list(LEVELS),
+                "metavar": "<level>",
+                "help": "Which codes are reported.",
+            },
+        ),
+        (
+            "constricter-type-comments",
+            {"default": False, "type": "yn", "metavar": "<y or n>", "help": "Count `# type:` comments."},
+        ),
+        (
+            "constricter-all-scopes",
+            {"default": False, "type": "yn", "metavar": "<y or n>", "help": "Check module and class bodies."},
+        ),
+        (
+            "constricter-nesting",
+            {
+                "default": NESTING,
+                "type": "int",
+                "metavar": "<n>",
+                "help": "Report an annotation nested this deep.",
+            },
+        ),
+    )
+
+    def __init__(self, linter: PyLinter) -> None:
+        """Register the messages with `linter`."""
+        super().__init__(linter)
+        self.msgs = {
+            message.msg_id: (MESSAGES[code].format(name="%r"), message.symbol, f"See constricter's {code}.")
+            for code, message in SYMBOLS.items()
+        }
+
+    @override
+    def process_module(self, node: nodes.Module) -> None:
+        """Report the module's error-level offences."""
+        opened: IO[bytes] | None
+        if (opened := node.stream()) is None:  # no file behind the module
+            return
+        stream: IO[bytes]
+        with opened as stream:
+            source: bytes = stream.read()
+        level: Level = LEVELS[cast("str", self.linter.config.constricter_level)]
+        checks: Checks = Checks(
+            type_comments=cast("bool", self.linter.config.constricter_type_comments),
+            all_scopes=cast("bool", self.linter.config.constricter_all_scopes),
+            nesting=cast("int", self.linter.config.constricter_nesting),
+        )
+        text: str = source.decode("utf-8")
+        offences: list[Offence] = check_source(text, node.file or "<unknown>", checks)
+        o: Offence
+        for o in unsuppressed(offences, lines(text)):  # suppression comments, as the CLI reads them
+            if o.is_error(level):
+                self.add_message(SYMBOLS[o.code].symbol, line=o.line, col_offset=o.col, args=(o.name,))
+
+
+def register(linter: PyLinter) -> None:
+    """Register the checker (pylint's plugin hook)."""
+    linter.register_checker(ConstricterChecker(linter))

constricter/report.py

@@ -0,0 +1,252 @@
+# SPDX-License-Identifier: MIT
+"""The command's output: text, JSON, GitHub workflow commands, SARIF, and statistics."""
+
+import hashlib
+import json
+from collections import Counter
+from collections.abc import Callable, Iterator, Sequence
+from enum import StrEnum
+from html import escape
+from pathlib import Path
+from typing import Final, NamedTuple, TypeAlias
+
+from constricter import __version__
+from constricter.checker import MESSAGES, Level, Offence
+
+_URL: Final = "https://github.com/ivylikethevine/python-constricter"
+_Json: TypeAlias = "str | int | bool | list[_Json] | dict[str, _Json]"
+
+
+class Format(StrEnum):
+    """The `--format` choices."""
+
+    TEXT = "text"
+    JSON = "json"
+    GITHUB = "github"
+    SARIF = "sarif"
+    GITLAB = "gitlab"
+    JUNIT = "junit"
+    RDJSON = "rdjson"
+
+
+class Result(NamedTuple):
+    """One reported offence, in its file, at the level that applies to that file."""
+
+    path: Path
+    offence: Offence
+    level: Level
+
+    @property
+    def severity(self) -> str:
+        """`error` or `warning`, at the result's level."""
+        return "error" if self.offence.is_error(self.level) else "warning"
+
+    @property
+    def message(self) -> str:
+        """The offence's message; in a notebook, with its cell and line first."""
+        o: Offence = self.offence
+        return o.message if o.cell is None else f"cell {o.cell}, line {o.line}: {o.message}"
+
+
+def _github_escape(text: str, *, prop: bool = False) -> str:
+    text = text.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+    return text.replace(":", "%3A").replace(",", "%2C") if prop else text
+
+
+def _where(result: Result) -> dict[str, _Json]:
+    """Locate `result` for SARIF.
+
+    Returns:
+      Its physical location; a notebook's is the file, as its cells have no file lines.
+
+    """
+    where: dict[str, _Json] = {"artifactLocation": {"uri": result.path.as_posix()}}
+    if result.offence.cell is None:
+        where["region"] = {"startLine": result.offence.line, "startColumn": result.offence.col + 1}
+    return where
+
+
+def _sarif(results: Sequence[Result]) -> dict[str, _Json]:
+    rules: list[_Json] = [
+        {"id": code, "shortDescription": {"text": message.format(name="`name`")}}
+        for code, message in MESSAGES.items()
+    ]
+    findings: list[_Json] = [
+        {
+            "ruleId": r.offence.code,
+            "level": r.severity,
+            "message": {"text": r.message},
+            "locations": [{"physicalLocation": _where(r)}],
+        }
+        for r in results
+    ]
+    driver: dict[str, _Json] = {
+        "name": "constricter",
+        "version": __version__,
+        "informationUri": _URL,
+        "rules": rules,
+    }
+    return {
+        "version": "2.1.0",
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "runs": [{"tool": {"driver": driver}, "results": findings}],
+    }
+
+
+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}"
+
+
+def _json(results: Sequence[Result]) -> Iterator[str]:
+    yield json.dumps(
+        [
+            {
+                "path": str(r.path),
+                "line": r.offence.line,
+                "column": r.offence.col + 1,
+                "code": r.offence.code,
+                "severity": r.severity,
+                "message": r.offence.message,
+                "cell": r.offence.cell,
+            }
+            for r in results
+        ],
+        indent=2,
+    )
+
+
+def _github(results: Sequence[Result]) -> Iterator[str]:
+    r: Result
+    for r in results:
+        location: str = f"file={_github_escape(str(r.path), prop=True)}"
+        if r.offence.cell is None:  # a notebook's cells have no file lines to point at
+            location += f",line={r.offence.line},col={r.offence.col + 1}"
+        yield f"::{r.severity} {location},title={r.offence.code}::{_github_escape(r.message)}"
+
+
+def _gitlab(results: Sequence[Result]) -> Iterator[str]:
+    """Render GitLab's Code Quality report (Code Climate JSON).
+
+    Yields:
+      Its lines; a fingerprint survives lines moving.
+
+    """
+    seen: Counter[tuple[Path, str, str]] = Counter()
+    issues: list[_Json] = []
+    r: Result
+    for r in results:
+        key: tuple[Path, str, str] = (r.path, r.offence.code, r.offence.name)
+        seen[key] += 1
+        fingerprint: str = hashlib.sha256(
+            f"{r.path.as_posix()}:{key[1]}:{key[2]}:{seen[key]}".encode(),
+        ).hexdigest()
+        issues.append(
+            {
+                "description": f"{r.offence.code} {r.message}",
+                "check_name": r.offence.code,
+                "fingerprint": fingerprint,
+                "severity": "major" if r.offence.is_error(r.level) else "minor",
+                "location": {"path": r.path.as_posix(), "lines": {"begin": r.offence.line}},
+            },
+        )
+    yield json.dumps(issues, indent=2)
+
+
+def _junit(results: Sequence[Result]) -> Iterator[str]:
+    """Render a JUnit XML report.
+
+    Yields:
+      Its lines: a test suite per file with offences, a failed test case per offence.
+
+    """
+    by_file: dict[Path, list[Result]] = {}
+    r: Result
+    for r in results:
+        by_file.setdefault(r.path, []).append(r)
+    yield "<?xml version='1.0' encoding='utf-8'?>"
+    yield f'<testsuites name="constricter" tests="{len(results)}" failures="{len(results)}">'
+    path: Path
+    found: list[Result]
+    for path, found in by_file.items():
+        yield f'  <testsuite name={_quoted(str(path))} tests="{len(found)}" failures="{len(found)}">'
+        for r in found:
+            name: str = _quoted(f"{r.offence.code} {r.offence.name}")
+            where: str = escape(f"{path}:{r.offence.line}:{r.offence.col + 1}")
+            yield f"    <testcase name={name} classname={_quoted(str(path))}>"
+            yield f"      <failure message={_quoted(r.message)} type={_quoted(r.severity)}>{where}</failure>"
+            yield "    </testcase>"
+        yield "  </testsuite>"
+    yield "</testsuites>"
+
+
+def _quoted(text: str) -> str:
+    """Quote `text` for XML.
+
+    Returns:
+      It as a double-quoted attribute value.
+
+    """
+    return f'"{escape(text, quote=True)}"'
+
+
+def _rdjson(results: Sequence[Result]) -> Iterator[str]:
+    """Render reviewdog's Diagnostic JSON; a certain fix is a suggestion.
+
+    Yields:
+      Its lines (columns count UTF-8 bytes).
+
+    """
+    diagnostics: list[_Json] = []
+    r: Result
+    for r in results:
+        o: Offence = r.offence
+        start: dict[str, _Json] = {"line": o.line, "column": o.col + 1}
+        diagnostic: dict[str, _Json] = {
+            "message": r.message,
+            "location": {"path": r.path.as_posix(), "range": {"start": start}},
+            "severity": r.severity.upper(),
+            "code": {"value": o.code},
+        }
+        if o.fix and not o.unsafe and o.cell is None:
+            end: dict[str, _Json] = {"line": o.line, "column": o.col + len(o.name.encode()) + 1}
+            diagnostic["suggestions"] = [{"range": {"start": end, "end": end}, "text": f": {o.fix}"}]
+        diagnostics.append(diagnostic)
+    yield json.dumps({"source": {"name": "constricter", "url": _URL}, "diagnostics": diagnostics}, indent=2)
+
+
+_RENDERERS: dict[Format, Callable[[Sequence[Result]], Iterator[str]]] = {
+    Format.TEXT: _text,
+    Format.JSON: _json,
+    Format.GITHUB: _github,
+    Format.SARIF: lambda results: iter([json.dumps(_sarif(results), indent=2)]),
+    Format.GITLAB: _gitlab,
+    Format.JUNIT: _junit,
+    Format.RDJSON: _rdjson,
+}
+
+
+def render(fmt: Format, results: Sequence[Result]) -> Iterator[str]:
+    """Render `results` in format `fmt`.
+
+    Returns:
+      The output lines.
+
+    """
+    return _RENDERERS[fmt](results)
+
+
+def statistics(results: Sequence[Result]) -> Iterator[str]:
+    """Count the results per code and severity.
+
+    Yields:
+      A line each: how many, the code, and the severity.
+
+    """
+    key: tuple[str, str]
+    count: int
+    for key, count in Counter((r.offence.code, r.severity) for r in results).most_common():
+        yield f"{count:>5}  {key[0]}  {key[1]}"