archunitpython 1.2.1__tar.gz → 1.3.0__tar.gz

{archunitpython-1.2.1 → archunitpython-1.3.0}/BACKLOG.md

@@ -12,7 +12,7 @@ This backlog collects product and maintenance ideas from project research.
 ## P1 - Adoption Workflow
 
 - Add an `.archignore` or similar file, modeled after `.gitignore`, for files that should never be analyzed.
-- Add a `.because(...)` API so rules can carry user-facing rationale into failure messages and generated architecture documentation.
+- [x] Add a `.because(...)` API so rules can carry user-facing rationale into failure messages and generated architecture documentation.
 - Add configuration-file support for common rules, while keeping the fluent Python API as the primary interface.
 - Add support for monorepo and multi-package Python projects.
 

{archunitpython-1.2.1 → archunitpython-1.3.0}/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.3.0](https://github.com/LukasNiessen/ArchUnitPython/compare/v1.2.1...v1.3.0) (2026-07-05)
+
+
+### Features
+
+* add because rule rationales ([491c666](https://github.com/LukasNiessen/ArchUnitPython/commit/491c666f1f8a6ef2f5ccd782a4e4c79ed39321f6))
+
 ## [1.2.1](https://github.com/LukasNiessen/ArchUnitPython/compare/v1.2.0...v1.2.1) (2026-06-28)
 
 

{archunitpython-1.2.1 → archunitpython-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: archunitpython
-Version: 1.2.1
+Version: 1.3.0
 Summary: Architecture testing library for Python projects. Enforce dependency rules, detect cycles, validate metrics.
 Project-URL: Homepage, https://github.com/LukasNiessen/ArchUnitPython
 Project-URL: Repository, https://github.com/LukasNiessen/ArchUnitPython.git
@@ -188,6 +188,25 @@ options = CheckOptions(
 violations = rule.check(options)
 ```
 
+### Explaining Rules With `.because(...)`
+
+Attach a rationale to a rule so failing assertions explain why the rule exists:
+
+```python
+rule = (
+    project_files("src/")
+    .in_folder("**/controllers/**")
+    .should_not()
+    .depend_on_files()
+    .in_folder("**/database/**")
+    .because("controllers should stay thin and delegate persistence")
+)
+
+assert_passes(rule)
+```
+
+When the rule fails, the rationale is included in the assertion message.
+
 ## 🐹 Use Cases
 
 Here is an overview of common use cases.
@@ -431,21 +450,113 @@ def test_no_forbidden_dependency():
 
 Generate dependency graph reports in multiple formats and narrow them to the part of the codebase you want to inspect.
 
+**Using `requests` library repo for example**
+
 ```python
 from archunitpython import project_graph
 
 def test_export_dependency_graph_reports():
-    graph = project_graph("src/").titled("Application Architecture")
-
-    graph.collapse_to_folder_depth(2).export_as_mermaid(
-        "reports/dependencies.mmd"
-    )
-
-    graph.focus_on("**/domain/**", 1).export_as_html(
-        "reports/domain-dependencies.html"
-    )
-
-    assert graph.snapshot().summary.node_count >= 0
+    graph = project_graph("src/requests").titled("Application Architecture")
+
+    graph.collapse_to_folder_depth(2).export_as_mermaid("reports/dependencies.md")
+
+if __name__ == "__main__":
+    test_export_dependency_graph_reports()
+```
+**Rendered mermain diagram**
+``` mermaid
+flowchart LR
+  n0["__init__.py"]
+  n1["__version__.py"]
+  n2["_internal_utils.py"]
+  n3["_types.py"]
+  n4["adapters.py"]
+  n5["api.py"]
+  n6["auth.py"]
+  n7["certs.py"]
+  n8["compat.py"]
+  n9["cookies.py"]
+  n10["exceptions.py"]
+  n11["help.py"]
+  n12["hooks.py"]
+  n13["models.py"]
+  n14["packages.py"]
+  n15["sessions.py"]
+  n16["status_codes.py"]
+  n17["structures.py"]
+  n18["utils.py"]
+  n0 --> n1
+  n0 --> n5
+  n0 --> n10
+  n0 --> n13
+  n0 --> n15
+  n0 --> n16
+  n2 --> n8
+  n3 --> n6
+  n3 --> n9
+  n3 --> n13
+  n3 --> n17
+  n4 --> n0
+  n4 --> n3
+  n4 --> n6
+  n4 --> n8
+  n4 --> n9
+  n4 --> n10
+  n4 --> n13
+  n4 --> n17
+  n4 --> n18
+  n5 --> n0
+  n5 --> n13
+  n6 --> n2
+  n6 --> n8
+  n6 --> n9
+  n6 --> n13
+  n6 --> n18
+  n9 --> n2
+  n9 --> n3
+  n9 --> n8
+  n9 --> n13
+  n10 --> n8
+  n10 --> n13
+  n11 --> n0
+  n12 --> n0
+  n12 --> n13
+  n13 --> n0
+  n13 --> n2
+  n13 --> n4
+  n13 --> n6
+  n13 --> n8
+  n13 --> n9
+  n13 --> n10
+  n13 --> n12
+  n13 --> n16
+  n13 --> n17
+  n13 --> n18
+  n14 --> n8
+  n15 --> n0
+  n15 --> n2
+  n15 --> n3
+  n15 --> n4
+  n15 --> n6
+  n15 --> n8
+  n15 --> n9
+  n15 --> n10
+  n15 --> n12
+  n15 --> n13
+  n15 --> n16
+  n15 --> n17
+  n15 --> n18
+  n16 --> n17
+  n17 --> n8
+  n18 --> n0
+  n18 --> n1
+  n18 --> n2
+  n18 --> n3
+  n18 --> n8
+  n18 --> n9
+  n18 --> n10
+  n18 --> n13
+  n18 --> n17
 ```
 
 Supported formats:

{archunitpython-1.2.1 → archunitpython-1.3.0}/README.md

@@ -155,6 +155,25 @@ options = CheckOptions(
 violations = rule.check(options)
 ```
 
+### Explaining Rules With `.because(...)`
+
+Attach a rationale to a rule so failing assertions explain why the rule exists:
+
+```python
+rule = (
+    project_files("src/")
+    .in_folder("**/controllers/**")
+    .should_not()
+    .depend_on_files()
+    .in_folder("**/database/**")
+    .because("controllers should stay thin and delegate persistence")
+)
+
+assert_passes(rule)
+```
+
+When the rule fails, the rationale is included in the assertion message.
+
 ## 🐹 Use Cases
 
 Here is an overview of common use cases.
@@ -398,21 +417,113 @@ def test_no_forbidden_dependency():
 
 Generate dependency graph reports in multiple formats and narrow them to the part of the codebase you want to inspect.
 
+**Using `requests` library repo for example**
+
 ```python
 from archunitpython import project_graph
 
 def test_export_dependency_graph_reports():
-    graph = project_graph("src/").titled("Application Architecture")
-
-    graph.collapse_to_folder_depth(2).export_as_mermaid(
-        "reports/dependencies.mmd"
-    )
-
-    graph.focus_on("**/domain/**", 1).export_as_html(
-        "reports/domain-dependencies.html"
-    )
-
-    assert graph.snapshot().summary.node_count >= 0
+    graph = project_graph("src/requests").titled("Application Architecture")
+
+    graph.collapse_to_folder_depth(2).export_as_mermaid("reports/dependencies.md")
+
+if __name__ == "__main__":
+    test_export_dependency_graph_reports()
+```
+**Rendered mermain diagram**
+``` mermaid
+flowchart LR
+  n0["__init__.py"]
+  n1["__version__.py"]
+  n2["_internal_utils.py"]
+  n3["_types.py"]
+  n4["adapters.py"]
+  n5["api.py"]
+  n6["auth.py"]
+  n7["certs.py"]
+  n8["compat.py"]
+  n9["cookies.py"]
+  n10["exceptions.py"]
+  n11["help.py"]
+  n12["hooks.py"]
+  n13["models.py"]
+  n14["packages.py"]
+  n15["sessions.py"]
+  n16["status_codes.py"]
+  n17["structures.py"]
+  n18["utils.py"]
+  n0 --> n1
+  n0 --> n5
+  n0 --> n10
+  n0 --> n13
+  n0 --> n15
+  n0 --> n16
+  n2 --> n8
+  n3 --> n6
+  n3 --> n9
+  n3 --> n13
+  n3 --> n17
+  n4 --> n0
+  n4 --> n3
+  n4 --> n6
+  n4 --> n8
+  n4 --> n9
+  n4 --> n10
+  n4 --> n13
+  n4 --> n17
+  n4 --> n18
+  n5 --> n0
+  n5 --> n13
+  n6 --> n2
+  n6 --> n8
+  n6 --> n9
+  n6 --> n13
+  n6 --> n18
+  n9 --> n2
+  n9 --> n3
+  n9 --> n8
+  n9 --> n13
+  n10 --> n8
+  n10 --> n13
+  n11 --> n0
+  n12 --> n0
+  n12 --> n13
+  n13 --> n0
+  n13 --> n2
+  n13 --> n4
+  n13 --> n6
+  n13 --> n8
+  n13 --> n9
+  n13 --> n10
+  n13 --> n12
+  n13 --> n16
+  n13 --> n17
+  n13 --> n18
+  n14 --> n8
+  n15 --> n0
+  n15 --> n2
+  n15 --> n3
+  n15 --> n4
+  n15 --> n6
+  n15 --> n8
+  n15 --> n9
+  n15 --> n10
+  n15 --> n12
+  n15 --> n13
+  n15 --> n16
+  n15 --> n17
+  n15 --> n18
+  n16 --> n17
+  n17 --> n8
+  n18 --> n0
+  n18 --> n1
+  n18 --> n2
+  n18 --> n3
+  n18 --> n8
+  n18 --> n9
+  n18 --> n10
+  n18 --> n13
+  n18 --> n17
 ```
 
 Supported formats:

{archunitpython-1.2.1 → archunitpython-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "archunitpython"
-version = "1.2.1"
+version = "1.3.0"
 description = "Architecture testing library for Python projects. Enforce dependency rules, detect cycles, validate metrics."
 readme = "README.md"
 license = "MIT"

{archunitpython-1.2.1 → archunitpython-1.3.0}/src/archunitpython/__init__.py

@@ -1,6 +1,6 @@
 """ArchUnitPython - Architecture testing library for Python projects."""
 
-__version__ = "1.2.1"
+__version__ = "1.3.0"
 
 # Files API
 # Common

{archunitpython-1.2.1 → archunitpython-1.3.0}/src/archunitpython/common/__init__.py

@@ -1,6 +1,10 @@
 from archunitpython.common.assertion.violation import EmptyTestViolation, Violation
 from archunitpython.common.error.errors import TechnicalError, UserError
-from archunitpython.common.fluentapi.checkable import Checkable, CheckOptions
+from archunitpython.common.fluentapi.checkable import (
+    Checkable,
+    CheckOptions,
+    RuleRationaleMixin,
+)
 from archunitpython.common.logging.types import LoggingOptions
 from archunitpython.common.types import Filter, Pattern, PatternMatchingOptions
 
@@ -11,6 +15,7 @@ __all__ = [
     "UserError",
     "Checkable",
     "CheckOptions",
+    "RuleRationaleMixin",
     "LoggingOptions",
     "Pattern",
     "Filter",

archunitpython-1.3.0/src/archunitpython/common/fluentapi/__init__.py

@@ -0,0 +1,7 @@
+from archunitpython.common.fluentapi.checkable import (
+    Checkable,
+    CheckOptions,
+    RuleRationaleMixin,
+)
+
+__all__ = ["Checkable", "CheckOptions", "RuleRationaleMixin"]

{archunitpython-1.2.1 → archunitpython-1.3.0}/src/archunitpython/common/fluentapi/checkable.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Protocol
+from typing import Protocol, TypeVar
 
 from archunitpython.common.assertion.violation import Violation
 from archunitpython.common.logging.types import LoggingOptions
@@ -19,6 +19,28 @@ class CheckOptions:
     ignore_type_checking_imports: bool = False
 
 
+T = TypeVar("T", bound="RuleRationaleMixin")
+
+
+class RuleRationaleMixin:
+    """Mixin for checkable rules that can carry a human-readable rationale."""
+
+    _because_reason: str | None = None
+
+    def because(self: T, reason: str) -> T:
+        """Attach a rationale explaining why the rule exists."""
+        reason = reason.strip()
+        if not reason:
+            raise ValueError("Rule rationale must not be empty.")
+        self._because_reason = reason
+        return self
+
+    @property
+    def because_reason(self) -> str | None:
+        """Return the rationale attached with because(), if any."""
+        return self._because_reason
+
+
 class Checkable(Protocol):
     """Protocol for any architecture rule that can be checked.
 

{archunitpython-1.2.1 → archunitpython-1.3.0}/src/archunitpython/files/fluentapi/files.py

@@ -14,7 +14,7 @@ from collections.abc import Sequence
 
 from archunitpython.common.assertion.violation import EmptyTestViolation, Violation
 from archunitpython.common.extraction.extract_graph import extract_graph
-from archunitpython.common.fluentapi.checkable import CheckOptions
+from archunitpython.common.fluentapi.checkable import CheckOptions, RuleRationaleMixin
 from archunitpython.common.pattern_matching import matches_all_patterns
 from archunitpython.common.projection.edge_projections import (
     per_external_edge,
@@ -322,7 +322,7 @@ def _check_empty_test(
     return None
 
 
-class CycleFreeFileCondition:
+class CycleFreeFileCondition(RuleRationaleMixin):
     """Checkable that verifies no cycles exist among filtered files."""
 
     def __init__(self, project_path: str | None, filters: list[Filter]) -> None:
@@ -350,7 +350,7 @@ class CycleFreeFileCondition:
         return gather_cycle_violations(cycles)
 
 
-class DependOnFileCondition:
+class DependOnFileCondition(RuleRationaleMixin):
     """Checkable that verifies file dependency rules."""
 
     def __init__(
@@ -377,7 +377,7 @@ class DependOnFileCondition:
         )
 
 
-class DependOnExternalModuleCondition:
+class DependOnExternalModuleCondition(RuleRationaleMixin):
     """Checkable that verifies external module dependency rules."""
 
     def __init__(
@@ -409,7 +409,7 @@ class DependOnExternalModuleCondition:
         )
 
 
-class MatchPatternFileCondition:
+class MatchPatternFileCondition(RuleRationaleMixin):
     """Checkable that verifies files match/don't match patterns."""
 
     def __init__(
@@ -434,7 +434,7 @@ class MatchPatternFileCondition:
         return gather_regex_matching_violations(nodes, self._check_filters, self._is_negated)
 
 
-class CustomFileCheckableCondition:
+class CustomFileCheckableCondition(RuleRationaleMixin):
     """Checkable that evaluates a custom condition on files."""
 
     def __init__(

{archunitpython-1.2.1 → archunitpython-1.3.0}/src/archunitpython/metrics/fluentapi/metrics.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 from typing import Any, Callable
 
 from archunitpython.common.assertion.violation import Violation
-from archunitpython.common.fluentapi.checkable import CheckOptions
+from archunitpython.common.fluentapi.checkable import CheckOptions, RuleRationaleMixin
 from archunitpython.common.pattern_matching import matches_pattern_classname
 from archunitpython.common.regex_factory import RegexFactory
 from archunitpython.common.types import Filter, Pattern
@@ -170,7 +170,7 @@ class ClassMetricThresholdBuilder:
         )
 
 
-class ClassMetricCondition:
+class ClassMetricCondition(RuleRationaleMixin):
     """Checkable that verifies a class-level metric threshold."""
 
     def __init__(
@@ -230,7 +230,7 @@ class FileMetricThresholdBuilder:
         )
 
 
-class FileMetricCondition:
+class FileMetricCondition(RuleRationaleMixin):
     """Checkable that verifies a file-level metric threshold."""
 
     def __init__(
@@ -364,7 +364,7 @@ class DistanceThresholdBuilder:
         )
 
 
-class DistanceCondition:
+class DistanceCondition(RuleRationaleMixin):
     """Checkable for distance metric thresholds."""
 
     def __init__(
@@ -404,7 +404,7 @@ class DistanceCondition:
         return violations
 
 
-class ZoneCondition:
+class ZoneCondition(RuleRationaleMixin):
     """Checkable for zone detection (pain/uselessness)."""
 
     def __init__(self, project_path: str | None, filters: list[Filter], zone_type: str) -> None:
@@ -485,7 +485,7 @@ class CustomMetricsBuilder:
         )
 
 
-class CustomMetricCondition:
+class CustomMetricCondition(RuleRationaleMixin):
     """Checkable for custom metric thresholds."""
 
     def __init__(
@@ -525,7 +525,7 @@ class CustomMetricCondition:
         return violations
 
 
-class CustomAssertionCondition:
+class CustomAssertionCondition(RuleRationaleMixin):
     """Checkable for custom metric assertions."""
 
     def __init__(

{archunitpython-1.2.1 → archunitpython-1.3.0}/src/archunitpython/slices/fluentapi/slices.py

@@ -14,7 +14,7 @@ import re
 
 from archunitpython.common.assertion.violation import Violation
 from archunitpython.common.extraction.extract_graph import extract_graph
-from archunitpython.common.fluentapi.checkable import CheckOptions
+from archunitpython.common.fluentapi.checkable import CheckOptions, RuleRationaleMixin
 from archunitpython.common.projection.project_edges import project_edges
 from archunitpython.common.projection.types import MapFunction
 from archunitpython.slices.assertion.admissible_edges import (
@@ -140,7 +140,7 @@ class NegativeConditionBuilder:
         )
 
 
-class PositiveSliceCondition:
+class PositiveSliceCondition(RuleRationaleMixin):
     """Checkable that verifies slices adhere to a diagram."""
 
     def __init__(
@@ -176,7 +176,7 @@ class PositiveSliceCondition:
         return identity()
 
 
-class NegativeSliceCondition:
+class NegativeSliceCondition(RuleRationaleMixin):
     """Checkable that verifies a specific dependency does NOT exist."""
 
     def __init__(

{archunitpython-1.2.1 → archunitpython-1.3.0}/src/archunitpython/testing/assertion.py

@@ -7,7 +7,11 @@ from archunitpython.common.fluentapi.checkable import Checkable, CheckOptions
 from archunitpython.testing.common.violation_factory import ViolationFactory
 
 
-def format_violations(violations: list[Violation]) -> str:
+def format_violations(
+    violations: list[Violation],
+    *,
+    because: str | None = None,
+) -> str:
     """Format violations into a human-readable string.
 
     Args:
@@ -19,7 +23,10 @@ def format_violations(violations: list[Violation]) -> str:
     if not violations:
         return "No violations found."
 
-    lines = [f"Found {len(violations)} architecture violation(s):", ""]
+    lines = [f"Found {len(violations)} architecture violation(s):"]
+    if because:
+        lines.extend(["", f"Because: {because}"])
+    lines.append("")
     for i, violation in enumerate(violations, 1):
         tv = ViolationFactory.from_violation(violation)
         lines.append(f"  {i}. {tv.message}")
@@ -44,4 +51,5 @@ def assert_passes(
     """
     violations = checkable.check(options)
     if violations:
-        raise AssertionError(format_violations(violations))
+        because = getattr(checkable, "because_reason", None)
+        raise AssertionError(format_violations(violations, because=because))

{archunitpython-1.2.1 → archunitpython-1.3.0}/tests/files/test_files_fluentapi.py

@@ -5,6 +5,8 @@ import shutil
 from pathlib import Path
 from uuid import uuid4
 
+import pytest
+
 from archunitpython.common.assertion.violation import EmptyTestViolation
 from archunitpython.common.extraction.extract_graph import clear_graph_cache
 from archunitpython.files.assertion.custom_file_logic import CustomFileViolation
@@ -223,6 +225,23 @@ class TestMethodChaining:
         cycle_violations = [v for v in violations if isinstance(v, ViolatingCycle)]
         assert len(cycle_violations) == 0
 
+    def test_because_adds_rule_rationale(self):
+        rule = (
+            project_files(FIXTURES_DIR)
+            .in_folder("**/services*")
+            .should()
+            .have_no_cycles()
+            .because("service cycles are hard to refactor")
+        )
+
+        assert rule.because_reason == "service cycles are hard to refactor"
+
+    def test_because_rejects_empty_rationale(self):
+        rule = project_files(FIXTURES_DIR).should().have_no_cycles()
+
+        with pytest.raises(ValueError, match="must not be empty"):
+            rule.because("  ")
+
 
 class TestTypeCheckingImports:
     def setup_method(self):

{archunitpython-1.2.1 → archunitpython-1.3.0}/tests/integration/test_e2e.py

@@ -83,6 +83,19 @@ class TestAssertPasses:
         with pytest.raises(AssertionError, match="architecture violation"):
             assert_passes(rule)
 
+    def test_failing_rule_includes_because_rationale(self):
+        rule = (
+            project_files(FIXTURES_DIR)
+            .in_folder("**/controllers*")
+            .should_not()
+            .depend_on_files()
+            .in_folder("**/services*")
+            .because("controllers should stay thin")
+        )
+
+        with pytest.raises(AssertionError, match="Because: controllers should stay thin"):
+            assert_passes(rule)
+
 
 class TestFormatViolations:
     def test_no_violations(self):
@@ -102,6 +115,18 @@ class TestFormatViolations:
         assert "1 architecture violation" in result
         assert "Circular dependency" in result
 
+    def test_with_because_rationale(self):
+        from archunitpython.common.projection.types import ProjectedEdge
+
+        violation = ViolatingCycle(
+            cycle=[
+                ProjectedEdge(source_label="a.py", target_label="b.py"),
+                ProjectedEdge(source_label="b.py", target_label="a.py"),
+            ]
+        )
+        result = format_violations([violation], because="cycles make changes risky")
+        assert "Because: cycles make changes risky" in result
+
 
 class TestSelfTesting:
     """ArchUnitPython tests its own architecture."""

archunitpython-1.2.1/src/archunitpython/common/fluentapi/__init__.py

@@ -1,3 +0,0 @@
-from archunitpython.common.fluentapi.checkable import Checkable, CheckOptions
-
-__all__ = ["Checkable", "CheckOptions"]