pytest-eo 0.5.1__py3-none-any.whl

pytest_eo/__init__.py

@@ -0,0 +1 @@
+"""pytest --eo: a strict style gate that aggregates ready-made tools."""

pytest_eo/angry_tests.py

@@ -0,0 +1,44 @@
+"""Rules of Angry Tests, which flake8 runs over the test files of pytest."""
+
+import ast
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import PurePath
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.extension import Extension
+from pytest_eo.final_assertion import FinalAssertion
+from pytest_eo.module_constants import ModuleConstants
+from pytest_eo.negative_messages import NegativeMessages
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class AngryTests(Extension):
+    """Tests that end with their only assertion and share no constants.
+
+    An assertion is a plain ``assert`` or a Hamcrest ``assert_that``; a test
+    that ends with ``pytest.raises`` makes its assertion there. Every
+    assertion carries a negative message, such as "x doesnt y".
+    """
+
+    tree: ast.Module  # noqa: PEO301 - flake8 passes it by this very name
+    filename: str  # noqa: PEO301 - flake8 passes it by this very name
+
+    @override
+    def run(self) -> Iterator[tuple[int, int, str, type[object]]]:
+        """Report the tests of a pytest test file that break a rule."""
+        if not any(
+            PurePath(self.filename).match(pattern)
+            for pattern in ("test_*.py", "*_test.py")
+        ):
+            return
+        for rule in (
+            FinalAssertion(self.tree),
+            ModuleConstants(self.tree),
+            NegativeMessages(self.tree),
+        ):
+            for line, column, text in rule.problems():
+                yield line, column, text, AngryTests

pytest_eo/assertion.py

@@ -0,0 +1,30 @@
+"""Whether a node asserts."""
+
+import ast
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.callee import Callee
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class Assertion(ast.NodeVisitor):  # noqa: ENC100 - a visitor holds no state, ast dispatches on the node
+    """Whether a node asserts, by a plain ``assert`` or by ``assert_that``."""
+
+    @override
+    def generic_visit(self, node: ast.AST) -> bool:
+        """Find no assertion in any other node."""
+        return False
+
+    @override
+    def visit_Assert(self, node: ast.Assert) -> bool:
+        """Find an assertion in a plain assert."""
+        return True
+
+    @override
+    def visit_Call(self, node: ast.Call) -> bool:
+        """Find an assertion in a call of ``assert_that``, qualified or not."""
+        return str(Callee().visit(node)).rsplit(".", 1)[-1] == "assert_that"

pytest_eo/assigned.py

@@ -0,0 +1,32 @@
+"""The attributes that one statement of a constructor sets."""
+
+import ast
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.owned import Owned
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class Assigned(ast.NodeVisitor):  # noqa: ENC100 - a visitor holds no state, ast dispatches on the node
+    """Names of the attributes of self that a statement assigns."""
+
+    @override
+    def generic_visit(self, node: ast.AST) -> tuple[str, ...]:
+        """Find no attribute in a statement that assigns nothing."""
+        return ()
+
+    @override
+    def visit_Assign(self, node: ast.Assign) -> tuple[str, ...]:
+        """Name the attributes of self among the targets of an assignment."""
+        return tuple(
+            name for target in node.targets for name in Owned().visit(target)
+        )
+
+    @override
+    def visit_AnnAssign(self, node: ast.AnnAssign) -> tuple[str, ...]:
+        """Name the attribute of self that an annotated assignment sets."""
+        return tuple(Owned().visit(node.target))

pytest_eo/blank_lines.py

@@ -0,0 +1,42 @@
+"""BOD100: a function body holds no blank lines."""
+
+import ast
+import tokenize
+from collections.abc import Iterator, Sequence
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.margin import Margin
+from pytest_eo.rule import Rule
+from pytest_eo.span import Span
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class BlankLines(Rule):
+    """Blank lines inside the functions of a module.
+
+    A blank line inside a string is a part of the string, and a blank line
+    next to a nested definition is what ``ruff format`` puts there, so
+    neither counts.
+    """
+
+    _tree: ast.Module
+    _tokens: Sequence[tokenize.TokenInfo]
+
+    @override
+    def problems(self) -> Iterator[tuple[int, int, str]]:
+        """Report every blank line from the first to the last row of a body."""
+        nodes = tuple(ast.walk(self._tree))
+        inside = {row for node in nodes for row in Span().visit(node)} - {
+            row for node in nodes for row in Margin().visit(node)
+        }
+        return (
+            (*token.start, "BOD100 function body must not hold blank lines")
+            for token in self._tokens
+            if token.type == tokenize.NL
+            and not token.line.strip()
+            and token.start[0] in inside
+        )

pytest_eo/bodies.py

@@ -0,0 +1,36 @@
+"""Function bodies, which flake8 checks in every file of the project."""
+
+import ast
+import tokenize
+from collections.abc import Iterator, Sequence
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.blank_lines import BlankLines
+from pytest_eo.extension import Extension
+from pytest_eo.inline_comments import InlineComments
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class Bodies(Extension):
+    """Function bodies packed tight, as Qulice asks of Java methods.
+
+    A blank line or a comment inside a body splits it into parts, and a
+    method of several parts does too much.
+    """
+
+    tree: ast.Module  # noqa: PEO301 - flake8 passes it by this very name
+    file_tokens: Sequence[tokenize.TokenInfo]  # noqa: PEO301 - flake8 passes it by this very name
+
+    @override
+    def run(self) -> Iterator[tuple[int, int, str, type[object]]]:
+        """Report every function body that breaks a rule."""
+        for rule in (
+            BlankLines(self.tree, self.file_tokens),
+            InlineComments(self.tree, self.file_tokens),
+        ):
+            for line, column, text in rule.problems():
+                yield line, column, text, Bodies

pytest_eo/bundled.py

@@ -0,0 +1,20 @@
+"""A configuration file shipped inside this package."""
+
+from dataclasses import dataclass
+from importlib import resources
+from typing import final
+
+from typing_extensions import override
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class Bundled:
+    """The path of a locked configuration that the gate hands to a tool."""
+
+    _name: str
+
+    @override
+    def __str__(self) -> str:
+        """Show the path of the file inside the installed package."""
+        return str(resources.files("pytest_eo") / "config" / self._name)

pytest_eo/callee.py

@@ -0,0 +1,23 @@
+"""The function a call goes to."""
+
+import ast
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class Callee(ast.NodeVisitor):  # noqa: ENC100 - a visitor holds no state, ast dispatches on the node
+    """The source of the function a call goes to; nothing for other nodes."""
+
+    @override
+    def generic_visit(self, node: ast.AST) -> str:
+        """Name nothing for a node that calls nothing."""
+        return ""
+
+    @override
+    def visit_Call(self, node: ast.Call) -> str:
+        """Name the function of a call as its source spells it."""
+        return ast.unparse(node.func)

pytest_eo/capacity.py

@@ -0,0 +1,50 @@
+"""ENC100: a class encapsulates one to four attributes."""
+
+import ast
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.fields import Fields
+
+_ALLOWED = range(1, 5)
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class Capacity(ast.NodeVisitor):  # noqa: ENC100 - a visitor holds no state, ast dispatches on the node
+    """A class with no attributes or more than four, and nothing for others.
+
+    A protocol is an interface, which holds no state, so it is left alone.
+    """
+
+    @override
+    def generic_visit(self, node: ast.AST) -> tuple[tuple[int, int, str], ...]:
+        """Find nothing to count in a node that isnt a class."""
+        return ()
+
+    @override
+    def visit_ClassDef(
+        self,
+        node: ast.ClassDef,
+    ) -> tuple[tuple[int, int, str], ...]:
+        """Count the attributes of a class and report a wrong number."""
+        count = len(
+            {name for item in node.body for name in Fields().visit(item)},
+        )
+        if count in _ALLOWED or any(
+            ast.unparse(base).split("[")[0].endswith("Protocol")
+            for base in node.bases
+        ):
+            return ()
+        return (
+            (
+                node.lineno,
+                node.col_offset,
+                (
+                    "ENC100 class must encapsulate one to four attributes, "
+                    f"not {count}"
+                ),
+            ),
+        )

pytest_eo/check.py

@@ -0,0 +1,17 @@
+"""One aggregated tool: a named source of violations."""
+
+from typing import Protocol
+
+from pytest_eo.violation import Violation
+
+
+class Check(Protocol):
+    """A named source of violations."""
+
+    def name(self) -> str:
+        """Short name shown in the pytest report."""
+        ...
+
+    def violations(self) -> tuple[Violation, ...]:
+        """Run the tool and return everything it complains about."""
+        ...

pytest_eo/command.py

@@ -0,0 +1,13 @@
+"""Something that runs and leaves an output behind."""
+
+from typing import Protocol
+
+from pytest_eo.printout import Printout
+
+
+class Command(Protocol):
+    """Something that can be run and leaves a :class:`Printout`."""
+
+    def run(self) -> Printout:
+        """Run it and return what it printed."""
+        ...

pytest_eo/comment.py

@@ -0,0 +1,42 @@
+"""One comment of a source file."""
+
+import re
+import tokenize
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+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 Comment(Remark):
+    """A comment of a file, read as the tokenizer gives it."""
+
+    _file: Path
+    _token: tokenize.TokenInfo
+
+    @override
+    def matches(
+        self,
+        pattern: re.Pattern[str],
+    ) -> Iterator[tuple[Place, re.Match[str]]]:
+        """Yield every match of the pattern, with its line and column."""
+        line, column = self._token.start
+        return (
+            (Place(str(self._file), line, column + match.start() + 1), match)
+            for match in pattern.finditer(self._token.string)
+        )
+
+    @override
+    def heading(
+        self,
+        pattern: re.Pattern[str],
+    ) -> Iterator[tuple[Place, re.Match[str]]]:
+        """Yield nothing, since a plain comment stands among the code."""
+        return iter(())

pytest_eo/comments.py

@@ -0,0 +1,42 @@
+"""The comments of a source file."""
+
+import io
+import tokenize
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.comment import Comment
+from pytest_eo.heading import Heading
+from pytest_eo.remark import Remark
+
+_SILENT = (tokenize.COMMENT, tokenize.NL, tokenize.NEWLINE, tokenize.ENCODING)
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class Comments(Iterable[Remark]):
+    """Every comment of a file, or none when the file cannot be tokenized."""
+
+    _file: Path
+
+    @override
+    def __iter__(self) -> Iterator[Remark]:
+        """Read the comments in order, telling the header from the rest."""
+        text = self._file.read_text(encoding="utf-8")
+        try:
+            tokens = tuple(
+                tokenize.generate_tokens(io.StringIO(text).readline),
+            )
+        except (tokenize.TokenError, SyntaxError):
+            return
+        code = next(
+            token.start for token in tokens if token.type not in _SILENT
+        )
+        for token in tokens:
+            if token.type == tokenize.COMMENT:
+                comment = Comment(self._file, token)
+                yield Heading(comment) if token.start < code else comment

pytest_eo/config/flake8.ini

@@ -0,0 +1,23 @@
+# Locked configuration: Elegant Objects rules from pyeo (eo-styleguide).
+# FIN100  class must be final
+# PEO101  __init__ contains only assignments
+# PEO102  @classmethod contains only a cls() call
+# PEO200  class must be frozen
+# PEO300  no class names ending in "er"
+# PEO301  no public attributes
+# PEO400  no static methods
+# PEO500  no @property, a getter in disguise
+# PEO601  no methods starting with "get"
+# PEO602  no getter methods
+# PEO700  no type introspection, casting, or reflection
+# OVR100  every public method is an @override of an interface method
+# FOC100  one public class per module (flake8-one-class)
+# NPM100  no private functions or methods (flake8-no-private-methods)
+# ENC100  a class encapsulates one to four attributes (pytest-eo itself)
+# BOD100  a function body holds no blank lines (pytest-eo itself)
+# BOD200  a function body holds no comments, except suppressions (pytest-eo itself)
+# TST100  a test ends with its only assertion (pytest-eo itself)
+# TST200  a test module shares no constants between its tests (pytest-eo itself)
+# TST300  every assertion carries a negative message (pytest-eo itself)
+[flake8]
+select = FIN100,PEO101,PEO102,PEO200,PEO300,PEO301,PEO400,PEO500,PEO601,PEO602,PEO700,OVR100,FOC100,NPM100,ENC100,BOD100,BOD200,TST100,TST200,TST300

pytest_eo/config/mypy.ini

@@ -0,0 +1,5 @@
+[mypy]
+strict = True
+warn_unreachable = True
+enable_error_code = explicit-override
+pretty = False

pytest_eo/config/ruff.toml

@@ -0,0 +1,43 @@
+# Locked configuration: projects cannot override it (only paths/excludes via [tool.eo]).
+target-version = "py311"
+line-length = 80
+
+[lint]
+preview = true
+select = ["ALL"]
+ignore = [
+    "incorrect-blank-line-before-class",         # conflicts with blank-line-before-class
+    "multi-line-summary-second-line",            # conflicts with multi-line-summary-first-line
+    "missing-trailing-comma",                    # conflicts with the formatter
+    "single-line-implicit-string-concatenation", # conflicts with the formatter
+    "missing-copyright-notice",                  # needs an author and a license: enable once the project picks them
+    "DOC",                                       # docstrings explain purpose, not returns and raises
+]
+
+# Codes checked by flake8: lets ruff accept them in "# noqa" comments.
+external = ["FIN", "PEO", "OVR", "FOC", "TST", "ENC", "BOD"]
+
+[lint.per-file-ignores]
+"tests/**" = [
+    "magic-value-comparison", # literals in expectations are fine
+    "D",                      # test names are the documentation
+]
+
+[lint.flake8-tidy-imports.banned-api]
+"unittest.mock".msg = "No mocks: write a Fake that implements the same interface."
+"mock".msg = "No mocks: write a Fake that implements the same interface."
+"pytest_mock".msg = "No mocks: write a Fake that implements the same interface."
+
+[lint.pylint]
+max-args = 4
+max-statements = 10
+max-branches = 4
+max-returns = 2
+max-nested-blocks = 2
+max-public-methods = 5
+
+[lint.mccabe]
+max-complexity = 5
+
+[lint.flake8-tidy-imports]
+ban-relative-imports = "all"

pytest_eo/edges.py

@@ -0,0 +1,28 @@
+"""The two rows that border a definition."""
+
+import ast
+from collections.abc import Iterable, Iterator, Sequence
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class Edges(Iterable[int]):
+    """The row above a definition and its decorators, and the row below it."""
+
+    _node: ast.stmt
+    _decorators: Sequence[ast.expr]
+
+    @override
+    def __iter__(self) -> Iterator[int]:
+        """Yield the row above the first decorator and the row past the end."""
+        yield (
+            min(
+                (self._node.lineno, *(item.lineno for item in self._decorators))
+            )
+            - 1
+        )
+        yield (self._node.end_lineno or self._node.lineno) + 1

pytest_eo/encapsulation.py

@@ -0,0 +1,30 @@
+"""Encapsulation, which flake8 runs over every file of the project."""
+
+import ast
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.capacity import Capacity
+from pytest_eo.extension import Extension
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class Encapsulation(Extension):
+    """Classes that encapsulate as little as possible, but something.
+
+    Elegant Objects asks for one to four attributes per class: fewer is a
+    bag of procedures, more is a class that does too much.
+    """
+
+    tree: ast.Module  # noqa: PEO301 - flake8 passes it by this very name
+
+    @override
+    def run(self) -> Iterator[tuple[int, int, str, type[object]]]:
+        """Report every class that holds no attributes or more than four."""
+        for node in ast.walk(self.tree):
+            for line, column, text in Capacity().visit(node):
+                yield line, column, text, Encapsulation

pytest_eo/ending.py

@@ -0,0 +1,30 @@
+"""Whether a statement ends a test with its assertion."""
+
+import ast
+from dataclasses import dataclass
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.assertion import Assertion
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class Ending(ast.NodeVisitor):  # noqa: ENC100 - a visitor holds no state, ast dispatches on the node
+    """Whether a statement is an assertion that may close a test."""
+
+    @override
+    def generic_visit(self, node: ast.AST) -> bool:
+        """Refuse any other statement as the end of a test."""
+        return False
+
+    @override
+    def visit_Assert(self, node: ast.Assert) -> bool:
+        """Accept a plain assert as the end of a test."""
+        return True
+
+    @override
+    def visit_Expr(self, node: ast.Expr) -> bool:
+        """Accept an expression that asserts, such as a matcher."""
+        return bool(Assertion().visit(node.value))

pytest_eo/eo_item.py

@@ -0,0 +1,41 @@
+"""A test item that passes when its tool reports nothing."""
+
+from pathlib import Path
+from typing import final
+
+import pytest
+from typing_extensions import override
+
+from pytest_eo.check import Check
+from pytest_eo.style_violations_error import StyleViolationsError
+
+
+@final
+class EoItem(pytest.Item):  # noqa: PEO200 - pytest.Item is mutable by design
+    """A test that passes when its tool reports nothing."""
+
+    def __init__(self, *, check: Check, **kwargs: object) -> None:
+        """Bind the item to one check; pytest requires the super() call."""
+        super().__init__(**kwargs)  # type: ignore[arg-type]  # noqa: PEO101 - pytest needs it
+        self._check = check  # noqa: PEO101 - flagged only because of super()
+
+    @override
+    def runtest(self) -> None:
+        """Run the tool; fail with its findings."""
+        found = self._check.violations()
+        if found:
+            raise StyleViolationsError(*found)
+
+    @override
+    def repr_failure(
+        self,
+        excinfo: pytest.ExceptionInfo[BaseException],
+        style: object = None,
+    ) -> str:
+        """Let the error show itself instead of a Python traceback."""
+        return str(excinfo.value)
+
+    @override
+    def reportinfo(self) -> tuple[Path, int, str]:
+        """Show ``eo::<tool>`` as the item location."""
+        return self.path, 0, f"eo::{self._check.name()}"

pytest_eo/eo_table.py

@@ -0,0 +1,29 @@
+"""The ``[tool.eo]`` table of a ``pyproject.toml``."""
+
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import final
+
+from typing_extensions import override
+
+from pytest_eo.table import Table
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class EoTable(Table):
+    """Settings read from ``[tool.eo]``; a missing file gives none."""
+
+    _file: Path
+
+    @override
+    def strings(self, key: str) -> tuple[str, ...]:
+        """Read the list under the key, empty unless the TOML has one."""
+        if not self._file.is_file():
+            return ()
+        tool = tomllib.loads(self._file.read_text(encoding="utf-8")).get("tool")
+        eo = tool.get("eo") if isinstance(tool, dict) else {}  # noqa: PEO700 - TOML gives untyped data
+        listed = eo.get(key) if isinstance(eo, dict) else ()  # noqa: PEO700 - TOML gives untyped data
+        entries = listed if isinstance(listed, list) else ()  # noqa: PEO700 - TOML gives untyped data
+        return tuple(str(item) for item in entries)

pytest_eo/excludes.py

@@ -0,0 +1,25 @@
+"""The paths a project leaves out of the check."""
+
+from collections.abc import Container
+from dataclasses import dataclass
+from fnmatch import fnmatch
+from typing import final
+
+from typing_extensions import override
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class Excludes(Container[str]):
+    """Glob patterns and directories that a project leaves unchecked."""
+
+    _patterns: tuple[str, ...]
+
+    @override
+    def __contains__(self, path: object) -> bool:
+        """Tell whether a POSIX path, relative to the root, is left out."""
+        return any(
+            fnmatch(str(path), pattern)
+            or str(path).startswith(pattern.rstrip("/") + "/")
+            for pattern in self._patterns
+        )