python-constricter 0.4.1__cp313-cp313-win32.whl

constricter/plugins/flake8.py

@@ -0,0 +1,133 @@
+# 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.offences import LEVELS, MAX_LENGTH, NESTING, OPT_IN, VAGUE, Checks, Level, Offence
+from constricter.rules.checker import check_source, check_tree
+from constricter.rules.flow import Narrower, parse_narrower
+
+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
+    max_length: ClassVar[int] = MAX_LENGTH
+    vague: ClassVar[int] = VAGUE
+    narrower: ClassVar[tuple[Narrower, ...]] = ()
+    can_be_final: ClassVar[bool] = False  # report LVA012
+
+    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})",
+        )
+        parser.add_option(
+            "--constricter-max-length",
+            type=int,
+            default=MAX_LENGTH,
+            parse_from_config=True,
+            help=f"report a fixed-length tuple annotation listing more types (LVA011; default: {MAX_LENGTH})",
+        )
+        parser.add_option(
+            "--constricter-vague",
+            type=int,
+            default=VAGUE,
+            parse_from_config=True,
+            help=f"how vague an annotation may be before it's LVA005 (default: {VAGUE}, none)",
+        )
+        parser.add_option(
+            "--constricter-narrower",
+            default="",
+            parse_from_config=True,
+            help="your own type hierarchy for LVA008-LVA010, as `B=A, C=A, int=` (B is narrower than A)",
+        )
+
+    @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)
+        cls.max_length = cast("int", options.constricter_max_length)
+        cls.vague = cast("int", options.constricter_vague)
+        cls.narrower = parse_narrower(cast("str", options.constricter_narrower))
+        # An opt-in code only when `select` or `extend-select` names it in full, as the CLI does.
+        chosen: list[str] = [
+            *(cast("list[str] | None", getattr(options, "select", None)) or []),
+            *(cast("list[str] | None", getattr(options, "extend_select", None)) or []),
+        ]
+        cls.can_be_final = bool(OPT_IN & set(chosen))
+
+    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(
+            type_comments=self.type_comments,
+            all_scopes=self.all_scopes,
+            nesting=self.nesting,
+            max_length=self.max_length,
+            vague=self.vague,
+            narrower=self.narrower,
+            final=self.can_be_final,
+        )
+        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/plugins/pylint.py

@@ -0,0 +1,186 @@
+# SPDX-License-Identifier: MIT
+"""The rules as a pylint plugin (C9101-C9112); reports the codes the level makes errors."""
+
+from typing import IO, NamedTuple, Protocol, cast, final
+
+from pylint.checkers import BaseRawFileChecker
+from pylint.lint import PyLinter
+from pylint.typing import MessageDefinitionTuple, Options
+
+from constricter.jsonc import as_text
+from constricter.noqa import lines, unsuppressed
+from constricter.offences import (
+    CAN_BE_FINAL,
+    COMMENT_TYPED_TARGET,
+    LEVELS,
+    LONG_TUPLE,
+    MAX_LENGTH,
+    MESSAGES,
+    MISMATCHED_TYPE,
+    NARROWABLE_TYPE,
+    NESTED_TYPE,
+    NESTING,
+    OPT_IN,
+    REDUNDANT_TYPE,
+    UNANNOTATED,
+    UNANNOTATED_MEMBER,
+    UNTYPED_TARGET,
+    UNUSED_UNION_MEMBER,
+    VAGUE,
+    VAGUE_TYPE,
+    Checks,
+    Level,
+    Offence,
+)
+from constricter.overrides import override
+from constricter.rules.checker import check_source
+from constricter.rules.flow import parse_narrower
+
+
+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"),
+    REDUNDANT_TYPE: Message("C9107", "redundant-annotation"),
+    NARROWABLE_TYPE: Message("C9108", "narrowable-annotation"),
+    MISMATCHED_TYPE: Message("C9109", "mismatched-value-type"),
+    UNUSED_UNION_MEMBER: Message("C9110", "unused-union-member"),
+    LONG_TUPLE: Message("C9111", "long-tuple-annotation"),
+    CAN_BE_FINAL: Message("C9112", "could-be-final"),
+}
+
+
+class _Module(Protocol):  # pylint: disable=too-few-public-methods
+    """What the checker reads of a module astroid parsed: the file behind it, and its bytes.
+
+    astroid declares no types (no `py.typed`): naming its `Module` would leave the checker's
+    signature unknown to a type checker reading this package.
+    """
+
+    file: str | None
+
+    def stream(self) -> IO[bytes] | None:
+        """Open the module's bytes, or nothing where no file backs it."""
+        ...
+
+
+@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.",
+            },
+        ),
+        (
+            "constricter-max-length",
+            {
+                "default": MAX_LENGTH,
+                "type": "int",
+                "metavar": "<n>",
+                "help": "Report a fixed-length tuple annotation listing more than this many types.",
+            },
+        ),
+        (
+            "constricter-vague",
+            {
+                "default": VAGUE,
+                "type": "int",
+                "metavar": "<n>",
+                "help": "How vague an annotation may be before it's LVA005 (-1: none).",
+            },
+        ),
+        (
+            "constricter-narrower",
+            {
+                "default": "",
+                "type": "string",
+                "metavar": "<B=A, ...>",
+                "help": "Your own type hierarchy (LVA008-LVA010): B=A, B narrower than A.",
+            },
+        ),
+    )
+
+    msgs: dict[str, MessageDefinitionTuple]
+
+    def __init__(self, linter: PyLinter) -> None:
+        """Register the messages with `linter`."""
+        super().__init__(linter)
+        # An opt-in code's message is off until enabled (`enable = could-be-final`).
+        self.msgs = {
+            message.msg_id: (
+                MESSAGES[code].format(name="%r", detail="%s"),
+                message.symbol,
+                f"See constricter's {code}.",
+                {"default_enabled": code not in OPT_IN},
+            )
+            for code, message in SYMBOLS.items()
+        }
+
+    @override
+    def process_module(self, node: _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),
+            max_length=cast("int", self.linter.config.constricter_max_length),
+            vague=cast("int", self.linter.config.constricter_vague),
+            narrower=parse_narrower(cast("str", self.linter.config.constricter_narrower)),
+            final=self.linter.is_message_enabled(SYMBOLS[CAN_BE_FINAL].symbol),
+        )
+        text: str = as_text(source)
+        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):
+                # A message names the variable, then (LVA009's) its `detail`, as `msgs` spells them.
+                args: tuple[str, ...] = (o.name, o.detail) if o.detail else (o.name,)
+                self.add_message(SYMBOLS[o.code].symbol, line=o.line, col_offset=o.col, args=args)
+
+
+def register(linter: PyLinter) -> None:
+    """Register the checker (pylint's plugin hook)."""
+    linter.register_checker(ConstricterChecker(linter))