patch-linter 1.0.0__py3-none-any.whl

patch_linter/__init__.py

@@ -0,0 +1,6 @@
+"""Forbid unittest.mock.patch and pytest monkeypatch in test code."""
+
+__version__ = "1.0.0"
+
+CODE = "PATCH001"
+MESSAGE = "Patch usage in tests"

patch_linter/checker.py

@@ -0,0 +1,208 @@
+"""AST checker for forbidden patch / monkeypatch usage."""
+
+from __future__ import annotations
+
+import ast
+import re
+import sys
+from pathlib import Path
+
+from patch_linter import CODE, MESSAGE
+from patch_linter.imports import (
+    MONKEYPATCH_METHODS,
+    ImportBindings,
+    collect_imports,
+)
+from patch_linter.models import Issue
+
+SKIP_DIRS = frozenset({"__pycache__", ".venv", "venv", ".git", ".tox", ".mypy_cache", ".ruff_cache"})
+
+# flake8/ruff style: ``# noqa`` or ``# noqa: PATCH001,E501``
+_NOQA_RE = re.compile(
+    r"#\s*noqa\b(?::\s*(.*))?",
+    re.IGNORECASE,
+)
+_CODE_SPLIT_RE = re.compile(r"[,\s]+")
+
+
+def line_has_noqa(line: str, code: str = CODE) -> bool:
+    match = _NOQA_RE.search(line)
+    if not match:
+        return False
+    codes = match.group(1)
+    if codes is None or codes.strip() == "":
+        return True
+    return code.upper() in {c.strip().upper() for c in _CODE_SPLIT_RE.split(codes) if c.strip()}
+
+
+def analyze_source(
+    source: str,
+    filepath: Path,
+    *,
+    tree: ast.AST | None = None,
+) -> list[Issue]:
+    """Analyze Python source; return issues (empty on parse failure)."""
+    lines = source.splitlines()
+    if tree is None:
+        try:
+            tree = ast.parse(source, filename=str(filepath))
+        except SyntaxError as exc:
+            print(
+                f"Warning: skipping {filepath.resolve()}: syntax error: {exc}",
+                file=sys.stderr,
+            )
+            return []
+
+    bindings = collect_imports(tree)
+    visitor = PatchVisitor(bindings=bindings, filepath=filepath, lines=lines)
+    visitor.visit(tree)
+    return visitor.issues
+
+
+def analyze_file(filepath: Path) -> list[Issue]:
+    path = filepath.resolve()
+    try:
+        content = path.read_text(encoding="utf-8")
+    except UnicodeDecodeError as exc:
+        print(f"Warning: skipping {path}: decode error: {exc}", file=sys.stderr)
+        return []
+    return analyze_source(content, path)
+
+
+def iter_python_files(root: Path) -> list[Path]:
+    root = root.resolve()
+    if root.is_file():
+        return [root] if root.suffix == ".py" else []
+
+    files: list[Path] = []
+    for path in root.rglob("*.py"):
+        if any(part in SKIP_DIRS for part in path.parts):
+            continue
+        files.append(path)
+    return sorted(files)
+
+
+def analyze_paths(paths: list[Path]) -> list[Issue]:
+    issues: list[Issue] = []
+    for raw in paths:
+        path = Path(raw)
+        if not path.exists():
+            print(f"Warning: path does not exist: {path}", file=sys.stderr)
+            continue
+        for file in iter_python_files(path):
+            issues.extend(analyze_file(file))
+    return issues
+
+
+class PatchVisitor(ast.NodeVisitor):
+    def __init__(
+        self,
+        bindings: ImportBindings,
+        filepath: Path,
+        lines: list[str],
+    ) -> None:
+        self.bindings = bindings
+        self.filepath = filepath
+        self.lines = lines
+        self.issues: list[Issue] = []
+        # Names that refer to a MonkeyPatch fixture / instance
+        self._monkey_names: set[str] = {"monkeypatch"}
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self._visit_function(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        self._visit_function(node)
+
+    def _visit_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        # Pytest injects the fixture by parameter name ``monkeypatch``.
+        for arg in _iter_args(node.args):
+            if arg.arg == "monkeypatch":
+                self._monkey_names.add("monkeypatch")
+        self.generic_visit(node)
+
+    def visit_Assign(self, node: ast.Assign) -> None:
+        if self._is_monkeypatch_ctor(node.value):
+            for target in node.targets:
+                if isinstance(target, ast.Name):
+                    self._monkey_names.add(target.id)
+        self.generic_visit(node)
+
+    def visit_AnnAssign(self, node: ast.AnnAssign) -> None:
+        if node.value is not None and self._is_monkeypatch_ctor(node.value):
+            if isinstance(node.target, ast.Name):
+                self._monkey_names.add(node.target.id)
+        self.generic_visit(node)
+
+    def visit_With(self, node: ast.With) -> None:
+        self._visit_with(node)
+
+    def visit_AsyncWith(self, node: ast.AsyncWith) -> None:
+        self._visit_with(node)
+
+    def _visit_with(self, node: ast.With | ast.AsyncWith) -> None:
+        for item in node.items:
+            if self._is_monkeypatch_ctor(item.context_expr) and item.optional_vars is not None:
+                if isinstance(item.optional_vars, ast.Name):
+                    self._monkey_names.add(item.optional_vars.id)
+            # ``with monkeypatch.context() as m`` — context() is itself flagged
+            if (
+                isinstance(item.context_expr, ast.Call)
+                and self._is_monkeypatch_method_call(item.context_expr)
+                and item.optional_vars is not None
+                and isinstance(item.optional_vars, ast.Name)
+            ):
+                self._monkey_names.add(item.optional_vars.id)
+        self.generic_visit(node)
+
+    def visit_Call(self, node: ast.Call) -> None:
+        if self.bindings.is_patch_call_func(node.func):
+            self._maybe_add_issue(node)
+        elif self._is_monkeypatch_method_call(node):
+            self._maybe_add_issue(node)
+        self.generic_visit(node)
+
+    def _is_monkeypatch_ctor(self, node: ast.AST) -> bool:
+        return isinstance(node, ast.Call) and self.bindings.is_monkeypatch_class(node.func)
+
+    def _is_monkeypatch_method_call(self, node: ast.Call) -> bool:
+        func = node.func
+        if not isinstance(func, ast.Attribute):
+            return False
+        if func.attr not in MONKEYPATCH_METHODS:
+            return False
+        return self._is_monkeypatch_receiver(func.value)
+
+    def _is_monkeypatch_receiver(self, node: ast.AST) -> bool:
+        if isinstance(node, ast.Name):
+            return node.id in self._monkey_names
+        # MonkeyPatch().setattr(...)
+        if isinstance(node, ast.Call) and self.bindings.is_monkeypatch_class(node.func):
+            return True
+        return False
+
+    def _maybe_add_issue(self, node: ast.AST) -> None:
+        line_num = getattr(node, "lineno", 1)
+        col = getattr(node, "col_offset", 0) + 1
+        code_line = self.lines[line_num - 1] if 0 < line_num <= len(self.lines) else ""
+        if line_has_noqa(code_line):
+            return
+        self.issues.append(
+            Issue(
+                filepath=self.filepath,
+                line_num=line_num,
+                col=col,
+                message=f"{CODE} {MESSAGE}",
+                code_line=code_line.strip(),
+            )
+        )
+
+
+def _iter_args(args: ast.arguments):
+    yield from args.posonlyargs
+    yield from args.args
+    yield from args.kwonlyargs
+    if args.vararg is not None:
+        yield args.vararg
+    if args.kwarg is not None:
+        yield args.kwarg

patch_linter/cli.py

@@ -0,0 +1,36 @@
+"""Command-line entry point for patch-linter."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from patch_linter.checker import analyze_paths
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        description="Forbid unittest.mock.patch and pytest monkeypatch in tests",
+    )
+    parser.add_argument(
+        "paths",
+        nargs="+",
+        type=Path,
+        help="Test files or directories to analyze",
+    )
+    args = parser.parse_args(argv)
+
+    issues = analyze_paths(list(args.paths))
+    for issue in issues:
+        print(issue.format(), file=sys.stderr)
+
+    if issues:
+        print(f"Found {len(issues)} patch usage problem(s).", file=sys.stderr)
+        sys.exit(1)
+
+    print("All checks have been successful!")
+
+
+if __name__ == "__main__":
+    main()

patch_linter/flake8_plugin.py

@@ -0,0 +1,52 @@
+"""Flake8 plugin for patch-linter."""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Generator
+from pathlib import Path
+from typing import Any
+
+from patch_linter import __version__
+from patch_linter.checker import analyze_source
+
+
+class PatchLinter:
+    """Flake8 extension that reports PATCH001 for patch / monkeypatch usage."""
+
+    name = "patch-linter"
+    version = __version__
+
+    def __init__(
+        self,
+        tree: ast.AST,
+        filename: str = "stdin",
+        lines: list[str] | None = None,
+    ) -> None:
+        self.tree = tree
+        self.filename = filename
+        self.lines = lines
+
+    def run(self) -> Generator[tuple[int, int, str, type[Any]], None, None]:
+        if self.filename in {"stdin", "-", ""}:
+            return
+
+        path = Path(self.filename)
+        source: str | None = None
+        if self.lines is not None:
+            source = "\n".join(self.lines)
+            if self.lines and not source.endswith("\n"):
+                # Preserve last line without forcing an extra blank for AST
+                pass
+        else:
+            try:
+                source = path.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                return
+
+        if source is None:
+            return
+
+        for issue in analyze_source(source, path, tree=self.tree):
+            # Flake8 column is 0-based; our Issue.col is 1-based for CLI links.
+            yield issue.line_num, max(issue.col - 1, 0), issue.message, type(self)

patch_linter/imports.py

@@ -0,0 +1,107 @@
+"""Resolve import aliases for unittest.mock.patch and pytest.MonkeyPatch."""
+
+from __future__ import annotations
+
+import ast
+
+ModulePath = tuple[str, ...]
+
+PATCH_PATH: ModulePath = ("unittest", "mock", "patch")
+MONKEYPATCH_CLASS_PATH: ModulePath = ("pytest", "MonkeyPatch")
+
+PATCH_API_ATTRS = frozenset({"object", "dict", "multiple", "stopall"})
+
+MONKEYPATCH_METHODS = frozenset(
+    {
+        "setattr",
+        "delattr",
+        "setitem",
+        "delitem",
+        "setenv",
+        "delenv",
+        "syspath_prepend",
+        "chdir",
+        "context",
+        "undo",
+    }
+)
+
+
+class ImportBindings:
+    """Maps local names to dotted import paths."""
+
+    def __init__(self) -> None:
+        self._names: dict[str, ModulePath] = {}
+
+    def bind(self, name: str, path: ModulePath) -> None:
+        self._names[name] = path
+
+    def get(self, name: str) -> ModulePath | None:
+        return self._names.get(name)
+
+    def resolve(self, node: ast.AST) -> ModulePath | None:
+        """Resolve Name / Attribute chain to a module path, if known."""
+        parts = _attr_parts(node)
+        if not parts:
+            return None
+
+        head = self._names.get(parts[0])
+        if head is None:
+            # Bare ``unittest.mock.patch`` without import of ``unittest`` still
+            # works if the full chain is written out and unittest is a real
+            # top-level name we treat as itself when present as Name.
+            if parts[0] in {"unittest", "pytest"}:
+                return tuple(parts)
+            return None
+        return head + tuple(parts[1:])
+
+    def is_patch_root(self, node: ast.AST) -> bool:
+        return self.resolve(node) == PATCH_PATH
+
+    def is_patch_call_func(self, node: ast.AST) -> bool:
+        """True if ``node`` is patch(...) or patch.object/dict/multiple/stopall."""
+        if self.is_patch_root(node):
+            return True
+        if isinstance(node, ast.Attribute) and node.attr in PATCH_API_ATTRS:
+            return self.is_patch_root(node.value)
+        return False
+
+    def is_monkeypatch_class(self, node: ast.AST) -> bool:
+        return self.resolve(node) == MONKEYPATCH_CLASS_PATH
+
+
+def collect_imports(tree: ast.AST) -> ImportBindings:
+    bindings = ImportBindings()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                local = alias.asname or alias.name.split(".", 1)[0]
+                path = tuple(alias.name.split("."))
+                # ``import unittest.mock as um`` → um = (unittest, mock)
+                # ``import unittest`` → unittest = (unittest,)
+                if alias.asname:
+                    bindings.bind(alias.asname, path)
+                else:
+                    # Only bind the top-level name for ``import a.b.c``
+                    bindings.bind(local, (path[0],))
+        elif isinstance(node, ast.ImportFrom):
+            if node.module is None:
+                continue
+            base = tuple(node.module.split("."))
+            for alias in node.names:
+                if alias.name == "*":
+                    continue
+                local = alias.asname or alias.name
+                bindings.bind(local, base + (alias.name,))
+    return bindings
+
+
+def _attr_parts(node: ast.AST) -> list[str] | None:
+    if isinstance(node, ast.Name):
+        return [node.id]
+    if isinstance(node, ast.Attribute):
+        parent = _attr_parts(node.value)
+        if parent is None:
+            return None
+        return parent + [node.attr]
+    return None

patch_linter/models.py

@@ -0,0 +1,20 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Issue:
+    """A single patch-usage finding."""
+
+    filepath: Path
+    line_num: int
+    col: int
+    message: str
+    code_line: str
+
+    def format(self) -> str:
+        """GCC/flake8-style line that IDEs treat as a clickable link."""
+        path = self.filepath.resolve()
+        return (
+            f"{path}:{self.line_num}:{self.col}: {self.message}: {self.code_line}"
+        )

patch_linter-1.0.0.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.5
+Name: patch-linter
+Version: 1.0.0
+Summary: Static analyzer that forbids unittest.mock.patch and pytest monkeypatch in tests
+Project-URL: Homepage, https://github.com/pavelmaksimov/patch-linter
+Project-URL: Bug Tracker, https://github.com/pavelmaksimov/patch-linter/issues
+Author-email: Pavel Maksimov <vur21@yandex.ru>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Provides-Extra: flake8
+Requires-Dist: flake8>=7.2.0; extra == 'flake8'
+Description-Content-Type: text/markdown
+
+# Patch Linter
+
+Static analyzer that forbids **`unittest.mock.patch`** and **pytest `monkeypatch`**
+mutations in tests. Prefer real dependency injection over patching.
+
+## Why
+
+Patching reaches into other modules and couples tests to implementation details.
+Refactoring becomes harder, and failures become brittle. Inject dependencies
+(fakes, stubs, or test doubles passed as arguments) instead.
+
+## What is reported
+
+| Pattern | Example |
+|---|---|
+| `unittest.mock.patch` | `@patch(...)`, `with patch(...)` |
+| Import aliases | `from unittest.mock import patch as p` → `p(...)` |
+| Via module | `mock.patch(...)`, `unittest.mock.patch(...)` |
+| Patch helpers | `patch.object` / `patch.dict` / `patch.multiple` / `patch.stopall` |
+| pytest monkeypatch | `monkeypatch.setattr(...)`, `setenv`, `delattr`, … |
+
+Not reported (by design): `mocker` (pytest-mock), bare `Mock` / `MagicMock`,
+freezegun, your own functions named `patch`, HTTP `client.patch(...)`.
+
+Code: **`PATCH001`**.
+
+## Installation
+
+```bash
+pip install patch-linter
+# optional flake8 plugin:
+pip install "patch-linter[flake8]"
+```
+
+## Usage
+
+### CLI
+
+```bash
+patch-linter tests/
+patch-linter tests/unit tests/test_foo.py
+```
+
+Output (clickable in Cursor / VS Code / PyCharm):
+
+```text
+/abs/path/to/tests/test_foo.py:12:5: PATCH001 Patch usage in tests: @patch('module.function')
+```
+
+Exit code `1` if problems are found.
+
+### Flake8
+
+```bash
+flake8 --select=PATCH tests/
+```
+
+### Suppress a line
+
+```python
+@patch("module.function")  # noqa: PATCH001
+def test_legacy(mock_fn):
+    ...
+```
+
+Bare `# noqa` also suppresses the finding on that line.
+
+## Correct approaches
+
+```python
+def process_data(repository):
+    return repository.get_all()
+
+
+def test_process_data():
+    class FakeRepo:
+        def get_all(self):
+            return [1, 2, 3]
+
+    assert process_data(FakeRepo()) == [1, 2, 3]
+```
+
+## License
+
+MIT

patch_linter-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+patch_linter/__init__.py,sha256=H-z98M0cMUhBOC1VKplvnWPopE8Hu1v9F99njnGc6mY,145
+patch_linter/checker.py,sha256=0yObUkeCt8xSdV4MP6brjnkqCmr9m4j5nwwT_P7Wf0U,6957
+patch_linter/cli.py,sha256=ZuNgre2rHgAqk3lbErxcVo_r4g6_QCoJgtBUGQzt5ss,857
+patch_linter/flake8_plugin.py,sha256=BoZNvHrDFnVXMd0WSkS79Ht5MgIaEwEH0J8tnYJ_yZk,1528
+patch_linter/imports.py,sha256=w8rFK9t_YA7GNljnZ996FI5oqsXmALQo4REmeZUwSmk,3530
+patch_linter/models.py,sha256=rKlU343jlgJpB1y4XEoGXlW1Bc08CsyisF9UWWLk3mo,477
+patch_linter-1.0.0.dist-info/METADATA,sha256=1O8KFRBHf9UUEQ2BDkxVCkreEbHr8j77OxZMvFP8fIs,2408
+patch_linter-1.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+patch_linter-1.0.0.dist-info/entry_points.txt,sha256=CdqqTsw__yIkWAmplFrMSE-6SWk42Bxh2NtCjyRKfIQ,122
+patch_linter-1.0.0.dist-info/licenses/LICENSE,sha256=tcS4tHHeWpiuqS_GdzKZMsWS-385Zjvsoz7OACq-UGQ,1071
+patch_linter-1.0.0.dist-info/RECORD,,

patch_linter-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

patch_linter-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+patch-linter = patch_linter.cli:main
+
+[flake8.extension]
+PATCH = patch_linter.flake8_plugin:PatchLinter

patch_linter-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pavel Maksimov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.