pytest-eo 0.5.1__py3-none-any.whl

pytest_eo/extension.py

@@ -0,0 +1,12 @@
+"""A flake8 plugin, as this package sees one."""
+
+from collections.abc import Iterator
+from typing import Protocol
+
+
+class Extension(Protocol):
+    """A flake8 plugin: the problems of one parsed file."""
+
+    def run(self) -> Iterator[tuple[int, int, str, type[object]]]:
+        """Yield the line, column, message and plugin of every problem."""
+        ...

pytest_eo/fields.py

@@ -0,0 +1,40 @@
+"""The attributes that one statement of a class body declares."""
+
+import ast
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.assigned import Assigned
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class Fields(ast.NodeVisitor):  # noqa: ENC100 - a visitor holds no state, ast dispatches on the node
+    """Names of the instance attributes a statement of a class body declares.
+
+    An annotated name other than a ``ClassVar`` is a field, as dataclasses
+    read it, and so is every attribute of self that ``__init__`` sets.
+    """
+
+    @override
+    def generic_visit(self, node: ast.AST) -> tuple[str, ...]:
+        """Find no field in any other statement."""
+        return ()
+
+    @override
+    def visit_AnnAssign(self, node: ast.AnnAssign) -> tuple[str, ...]:
+        """Name an annotated field, unless it belongs to the class itself."""
+        if ast.unparse(node.annotation).split("[")[0].endswith("ClassVar"):
+            return ()
+        return (ast.unparse(node.target),)
+
+    @override
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> tuple[str, ...]:
+        """Name the attributes that the constructor sets, at any depth."""
+        if node.name != "__init__":
+            return ()
+        return tuple(
+            name for inner in ast.walk(node) for name in Assigned().visit(inner)
+        )

pytest_eo/files.py

@@ -0,0 +1,12 @@
+"""Python files that the gate reads itself."""
+
+from pathlib import Path
+from typing import Protocol
+
+
+class Files(Protocol):
+    """Python files of a project that the gate reads itself."""
+
+    def files(self) -> tuple[Path, ...]:
+        """Every file to read, in a stable order."""
+        ...

pytest_eo/final_assertion.py

@@ -0,0 +1,46 @@
+"""TST100: a test ends with its only assertion."""
+
+import ast
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.assertion import Assertion
+from pytest_eo.ending import Ending
+from pytest_eo.raising import Raising
+from pytest_eo.rule import Rule
+from pytest_eo.trial import Trial
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class FinalAssertion(Rule):
+    """Tests that end with their only assertion, or with ``pytest.raises``.
+
+    A test that ends with ``pytest.raises`` makes its assertion there, so it
+    may hold no other one.
+    """
+
+    _tree: ast.Module
+
+    @override
+    def problems(self) -> Iterator[tuple[int, int, str]]:
+        """Report every test that doesnt end with its only assertion."""
+        for test in (
+            found
+            for node in ast.walk(self._tree)
+            for found in Trial().visit(node)
+        ):
+            count = sum(Assertion().visit(inner) for inner in ast.walk(test))
+            last = test.body[-1]
+            if not (
+                (count == 1 and Ending().visit(last))
+                or (count == 0 and Raising().visit(last))
+            ):
+                yield (
+                    test.lineno,
+                    test.col_offset,
+                    "TST100 test must end with its only assertion",
+                )

pytest_eo/flake_check.py

@@ -0,0 +1,49 @@
+"""``flake8`` with pyeo as a source of violations."""
+
+import re
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.check import Check
+from pytest_eo.command import Command
+from pytest_eo.place import Place
+from pytest_eo.verified import Verified
+from pytest_eo.violation import Violation
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class FlakeCheck(Check):
+    """``flake8`` with pyeo: rules of Elegant Objects."""
+
+    _command: Command
+
+    @override
+    def name(self) -> str:
+        """Short name shown in the pytest report."""
+        return "flake8"
+
+    @override
+    def violations(self) -> tuple[Violation, ...]:
+        """Parse the default ``path:row:col: CODE text`` report of flake8."""
+        output = Verified(self._command, self.name(), (0, 1)).run()
+        pattern = re.compile(
+            r"^(?P<path>.+?):(?P<line>\d+):(?P<col>\d+): "
+            r"(?P<code>[A-Z]+\d+) (?P<msg>.+)$"
+        )
+        found = tuple(
+            Violation(
+                self.name(),
+                match["code"],
+                Place(match["path"], int(match["line"]), int(match["col"])),
+                match["msg"],
+            )
+            for match in (pattern.match(line) for line in output)
+            if match
+        )
+        if not found and output.exited((1,)):
+            reason = "flake8 failed without a report"
+            raise output.failure(reason)
+        return found

pytest_eo/heading.py

@@ -0,0 +1,35 @@
+"""A comment that stands above the first line of code."""
+
+import re
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.place import Place
+from pytest_eo.remark import Remark
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class Heading(Remark):
+    """A comment above all code, where some forms reach the whole file."""
+
+    _origin: Remark
+
+    @override
+    def matches(
+        self,
+        pattern: re.Pattern[str],
+    ) -> Iterator[tuple[Place, re.Match[str]]]:
+        """Yield the matches of the comment itself."""
+        return self._origin.matches(pattern)
+
+    @override
+    def heading(
+        self,
+        pattern: re.Pattern[str],
+    ) -> Iterator[tuple[Place, re.Match[str]]]:
+        """Yield the same matches, since this comment heads the file."""
+        return self._origin.matches(pattern)

pytest_eo/inline_comments.py

@@ -0,0 +1,44 @@
+"""BOD200: a function body holds no comments."""
+
+import ast
+import re
+import tokenize
+from collections.abc import Iterator, Sequence
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.rule import Rule
+from pytest_eo.span import Span
+
+_SUPPRESSION = re.compile(
+    r"#\s*(?:noqa\b|type:\s*ignore\b|ruff:|flake8:|mypy:)"
+)
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class InlineComments(Rule):
+    """Comments inside the functions of a module.
+
+    A suppression is a comment too, but ``eo::suppressions`` governs it, so
+    it doesnt count.
+    """
+
+    _tree: ast.Module
+    _tokens: Sequence[tokenize.TokenInfo]
+
+    @override
+    def problems(self) -> Iterator[tuple[int, int, str]]:
+        """Report every comment from the first to the last row of a body."""
+        inside = {
+            row for node in ast.walk(self._tree) for row in Span().visit(node)
+        }
+        return (
+            (*token.start, "BOD200 function body must not hold comments")
+            for token in self._tokens
+            if token.type == tokenize.COMMENT
+            and token.start[0] in inside
+            and not _SUPPRESSION.match(token.string)
+        )

pytest_eo/layout.py

@@ -0,0 +1,15 @@
+"""Which directories of a project the gate checks."""
+
+from typing import Protocol
+
+
+class Layout(Protocol):
+    """Which directories of a project to check and which to skip."""
+
+    def paths(self) -> tuple[str, ...]:
+        """Directories to check, relative to the project root."""
+        ...
+
+    def excludes(self) -> tuple[str, ...]:
+        """Glob patterns to skip."""
+        ...

pytest_eo/margin.py

@@ -0,0 +1,42 @@
+"""The rows right around a definition, where ruff format wants blank lines."""
+
+import ast
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.edges import Edges
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class Margin(ast.NodeVisitor):  # noqa: ENC100 - a visitor holds no state, ast dispatches on the node
+    """The rows that border a ``def`` or a ``class``, and none for others.
+
+    ``ruff format`` puts a blank line on both sides of a nested ``def`` or
+    ``class``, so a body may hold blank lines there and nowhere else.
+    """
+
+    @override
+    def generic_visit(self, node: ast.AST) -> tuple[int, ...]:
+        """Find no margins around a node that defines nothing."""
+        return ()
+
+    @override
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> tuple[int, ...]:
+        """Find the rows around a function."""
+        return tuple(Edges(node, node.decorator_list))
+
+    @override
+    def visit_AsyncFunctionDef(
+        self,
+        node: ast.AsyncFunctionDef,
+    ) -> tuple[int, ...]:
+        """Find the rows around a coroutine."""
+        return tuple(Edges(node, node.decorator_list))
+
+    @override
+    def visit_ClassDef(self, node: ast.ClassDef) -> tuple[int, ...]:
+        """Find the rows around a class."""
+        return tuple(Edges(node, node.decorator_list))

pytest_eo/message.py

@@ -0,0 +1,60 @@
+"""What an assertion says when it fails."""
+
+import ast
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.assertion import Assertion
+from pytest_eo.text import Text
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class Message(ast.NodeVisitor):  # noqa: ENC100 - a visitor holds no state, ast dispatches on the node
+    """The place and words of a failure message, and nothing for other nodes.
+
+    A plain ``assert`` speaks through its message; ``assert_that`` speaks
+    through its ``reason`` keyword or else its last argument.
+    """
+
+    @override
+    def generic_visit(self, node: ast.AST) -> tuple[tuple[int, int, str], ...]:
+        """Find no message in a node that asserts nothing."""
+        return ()
+
+    @override
+    def visit_Assert(
+        self, node: ast.Assert
+    ) -> tuple[tuple[int, int, str], ...]:
+        """Read the message of a plain assert, empty when it has none."""
+        return (
+            (
+                node.lineno,
+                node.col_offset,
+                Text().visit(node.msg or ast.Constant("")),
+            ),
+        )
+
+    @override
+    def visit_Call(self, node: ast.Call) -> tuple[tuple[int, int, str], ...]:
+        """Read the reason of a matcher, given by keyword or last."""
+        if not (node.args and Assertion().visit(node)):
+            return ()
+        return (
+            (
+                node.lineno,
+                node.col_offset,
+                Text().visit(
+                    next(
+                        (
+                            word.value
+                            for word in node.keywords
+                            if word.arg == "reason"
+                        ),
+                        node.args[-1],
+                    ),
+                ),
+            ),
+        )

pytest_eo/module_constants.py

@@ -0,0 +1,32 @@
+"""TST200: a test module shares no constants between its tests."""
+
+import ast
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.rule import Rule
+from pytest_eo.shared import Shared
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class ModuleConstants(Rule):
+    """Values a test module assigns for its tests to share."""
+
+    _tree: ast.Module
+
+    @override
+    def problems(self) -> Iterator[tuple[int, int, str]]:
+        """Report every module statement that shares a value."""
+        return (
+            (
+                statement.lineno,
+                statement.col_offset,
+                "TST200 test module must not share constants between its tests",
+            )
+            for statement in self._tree.body
+            if Shared().visit(statement)
+        )

pytest_eo/mypy_check.py

@@ -0,0 +1,43 @@
+"""``mypy --strict`` as a source of violations."""
+
+import json
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.check import Check
+from pytest_eo.command import Command
+from pytest_eo.place import Place
+from pytest_eo.verified import Verified
+from pytest_eo.violation import Violation
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class MypyCheck(Check):
+    """``mypy --strict`` with JSON output."""
+
+    _command: Command
+
+    @override
+    def name(self) -> str:
+        """Short name shown in the pytest report."""
+        return "mypy"
+
+    @override
+    def violations(self) -> tuple[Violation, ...]:
+        """Parse one JSON object per line, skipping notes."""
+        output = Verified(self._command, self.name(), (0, 1)).run()
+        lines = (line for line in output if line.startswith("{"))
+        items = (json.loads(line) for line in lines)
+        return tuple(
+            Violation(
+                self.name(),
+                item["code"] or "error",
+                Place(item["file"], item["line"], item["column"]),
+                item["message"],
+            )
+            for item in items
+            if item["severity"] == "error"
+        )

pytest_eo/narrow_suppressions.py

@@ -0,0 +1,72 @@
+"""The suppressions of one line, and what is wrong with them."""
+
+import re
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.remark import Remark
+from pytest_eo.violation import Violation
+
+_FORMS = (
+    (
+        re.compile(
+            r"#\s*noqa:\s*(?P<codes>[A-Z]+\d*(?:\s*,\s*[A-Z]+\d*)*)"
+            r"(?P<rest>[^#]*)",
+        ),
+        "# noqa: {}",
+    ),
+    (
+        re.compile(
+            r"#\s*ruff:\s*ignore\[(?P<codes>[\w-]+(?:\s*,\s*[\w-]+)*)\]"
+            r"(?P<rest>[^#]*)",
+        ),
+        "# ruff: ignore[{}]",
+    ),
+)
+_REASON = re.compile(r"^\s+-\s+\S")
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class NarrowSuppressions(Iterable[Violation]):
+    """Suppressions of one line that name a forbidden rule or give no reason.
+
+    It reads ``# noqa: CODE`` and ``# ruff: ignore[CODE-OR-NAME]``.
+    """
+
+    _tool: str
+    _comment: Remark
+    _forbidden: tuple[str, ...]
+
+    @override
+    def __iter__(self) -> Iterator[Violation]:
+        """Report every suppression of the comment that breaks a rule."""
+        for template, place, match in (
+            (template, place, match)
+            for form, template in _FORMS
+            for place, match in self._comment.matches(form)
+        ):
+            codes = tuple(code.strip() for code in match["codes"].split(","))
+            listed = template.format(", ".join(codes))
+            banned = tuple(
+                code for code in codes if code.startswith(self._forbidden)
+            )
+            if banned:
+                yield Violation(
+                    self._tool,
+                    "SUP002",
+                    place,
+                    f"{', '.join(banned)} cannot be suppressed: "
+                    "fix the code instead",
+                )
+            if not _REASON.match(match["rest"]):
+                yield Violation(
+                    self._tool,
+                    "SUP001",
+                    place,
+                    f"`{listed}` needs a reason: "
+                    f"write `{listed} - why the rule cannot hold here`",
+                )

pytest_eo/negative_messages.py

@@ -0,0 +1,40 @@
+"""TST300: every assertion explains its failure with a negation."""
+
+import ast
+import re
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.message import Message
+from pytest_eo.rule import Rule
+
+_NEGATION = re.compile(
+    r"\b(?:not|never|no|nothing|cannot|dont|doesnt|didnt|isnt|arent|wasnt"
+    r"|werent|wont|cant)\b",
+    re.IGNORECASE,
+)
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class NegativeMessages(Rule):
+    """Assertions whose message says what went wrong, such as "x doesnt y"."""
+
+    _tree: ast.Module
+
+    @override
+    def problems(self) -> Iterator[tuple[int, int, str]]:
+        """Report every assertion whose message holds no negation."""
+        return (
+            (
+                line,
+                column,
+                "TST300 assertion must explain its failure with a negation",
+            )
+            for node in ast.walk(self._tree)
+            for line, column, text in Message().visit(node)
+            if not _NEGATION.search(text)
+        )

pytest_eo/output.py

@@ -0,0 +1,37 @@
+"""What a finished tool printed and how it exited."""
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.printout import Printout
+from pytest_eo.tool_failed_error import ToolFailedError
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class Output(Printout):
+    """The streams and the exit status of a finished process."""
+
+    _stdout: str
+    _stderr: str
+    _status: int
+
+    @override
+    def __iter__(self) -> Iterator[str]:
+        """Read the lines of stdout, where tools print their reports."""
+        return iter(self._stdout.splitlines())
+
+    @override
+    def exited(self, statuses: tuple[int, ...]) -> bool:
+        """Tell whether the process exited with one of the statuses."""
+        return self._status in statuses
+
+    @override
+    def failure(self, reason: str) -> ToolFailedError:
+        """Build the error with the exit status and what went to stderr."""
+        return ToolFailedError(
+            f"{reason} (status {self._status}): {self._stderr.strip()}",
+        )

pytest_eo/owned.py

@@ -0,0 +1,28 @@
+"""The attributes of an object that an assignment sets on itself."""
+
+import ast
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class Owned(ast.NodeVisitor):  # noqa: ENC100 - a visitor holds no state, ast dispatches on the node
+    """Names of ``self.x`` in an assignment target, and nothing for others."""
+
+    @override
+    def generic_visit(self, node: ast.AST) -> tuple[str, ...]:
+        """Find no attribute of self in any other target."""
+        return ()
+
+    @override
+    def visit_Attribute(self, node: ast.Attribute) -> tuple[str, ...]:
+        """Name the attribute when it belongs to ``self``."""
+        return (node.attr,) if ast.unparse(node.value) == "self" else ()
+
+    @override
+    def visit_Tuple(self, node: ast.Tuple) -> tuple[str, ...]:
+        """Name the attributes of self among the targets of an unpacking."""
+        return tuple(name for item in node.elts for name in self.visit(item))

pytest_eo/place.py

@@ -0,0 +1,21 @@
+"""Where in the code a tool found something."""
+
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class Place:
+    """A file, a line and a column, as tools and editors point at code."""
+
+    _path: str
+    _line: int
+    _column: int
+
+    @override
+    def __str__(self) -> str:
+        """Render as ``path:line:col``."""
+        return f"{self._path}:{self._line}:{self._column}"