"""The coupling rule, held by reading the imports. The boilerplate's test, with roledesk's two extra folders. `pipeline/`, `auth/` and `desk/` import nothing from `app/` and nothing from each other, except that `desk/` is built on `pipeline/`, as it is in news. `plugins/` imports `desk/` and nothing else, since a plugin is app-agnostic. `app/` imports all of them. That is what keeps each copied folder a copy that can be refreshed from its source, and it is the rule that breaks quietly, one convenient import at a time, until the folder is a port rather than a copy. `tests/test_architecture.py` holds `app/`'s own layers. Read with `ast` rather than grepped: a string containing the word `app`, or a line in a docstring showing what an app would write, is not an import, and a test that cannot tell the difference is a test people learn to work around. """ from __future__ import annotations import ast from pathlib import Path import pytest ROOT = Path(__file__).resolve().parent.parent #: The module folders and what each may not reach for. Listed rather than #: derived so that adding a folder is a decision, not an accident. FORBIDDEN = { "pipeline": ("app", "auth", "desk", "plugins"), "auth": ("app", "pipeline", "desk", "plugins"), "desk": ("app", "auth", "plugins"), "plugins": ("app", "pipeline", "auth"), } def imported_modules(source: str) -> set[str]: """Every top-level package name this file imports.""" found: set[str] = set() tree = ast.parse(source) for node in ast.walk(tree): if isinstance(node, ast.Import): found.update(alias.name.split(".")[0] for alias in node.names) elif isinstance(node, ast.ImportFrom): # A relative import stays inside the folder by construction. if node.level == 0 and node.module: found.add(node.module.split(".")[0]) return found def python_files(folder: str) -> list[Path]: root = ROOT / folder if not root.is_dir(): return [] return sorted(p for p in root.rglob("*.py") if "__pycache__" not in p.parts) CASES = [(folder, path) for folder in FORBIDDEN for path in python_files(folder)] @pytest.mark.parametrize( ("folder", "path"), CASES, ids=[str(path.relative_to(ROOT)).replace("\\", "/") for _, path in CASES]) def test_a_module_folder_imports_nothing_above_it(folder: str, path: Path): imported = imported_modules(path.read_text(encoding="utf-8")) for name in FORBIDDEN[folder]: assert name not in imported, ( f"{path.relative_to(ROOT)} imports {name!r}. " f"{folder}/ has to survive being copied on its own.") @pytest.mark.parametrize("folder", sorted(FORBIDDEN)) def test_the_folder_is_actually_there(folder: str): """A parametrised test over an empty list passes by saying nothing. So the rule is only proved for what exists, and this is what makes "it exists" a thing the suite checks rather than a thing somebody assumes -- the day a folder is moved or renamed, the coupling test would otherwise go quiet instead of red. """ assert python_files(folder), f"no {folder}/ to check"