archunitpython 1.2.1__py3-none-any.whl → 1.3.0__py3-none-any.whl

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/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/common/fluentapi/__init__.py

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

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/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/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/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/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.dist-info → archunitpython-1.3.0.dist-info}/METADATA

@@ -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.dist-info → archunitpython-1.3.0.dist-info}/RECORD

@@ -1,6 +1,6 @@
-archunitpython/__init__.py,sha256=w__UDj9GojwOMtYX5eSZCpd4WYiIKjWGJ6c-8nRlPSI,1154
+archunitpython/__init__.py,sha256=alLY-bGp-tUtdb8BRV0r8K-qIZKkWYnJ5K-mTDnFOrQ,1154
 archunitpython/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-archunitpython/common/__init__.py,sha256=u8jwbfALwIT_5ZqTrRchpZqkFHG5tTwM21LX5hR9ZSc,593
+archunitpython/common/__init__.py,sha256=TKL39Z0kBpWqMH99jU4LsDSUZ5lQ_rcAJfLnmUTDTOI,656
 archunitpython/common/pattern_matching.py,sha256=HMAfo8GsooHvA4d2IxCi3btrYTdwfOQXw4bDNr117P0,2669
 archunitpython/common/regex_factory.py,sha256=UtlElM0Uty3SuD7tPZeoDnpbFipFUuYDpWfuV-Xq4c4,2459
 archunitpython/common/types.py,sha256=aA6hxCvmOy7_q74pE0sDRILNB8KxmHx9G4j5ql87mWs,755
@@ -11,8 +11,8 @@ archunitpython/common/error/errors.py,sha256=y7mcXoZPyK7uD2dMMO1qBt1y7KcIeGlRYiV
 archunitpython/common/extraction/__init__.py,sha256=RkJOcxJoLYQxEagh3uWhjsUCprK3Nr3Bn3o7nmzk4_Q,284
 archunitpython/common/extraction/extract_graph.py,sha256=HIfAZLZiv4Zbi1Nm8jmNnnu8ggn0wQXunBlZP_QK1x8,15254
 archunitpython/common/extraction/graph.py,sha256=Rk-0eDDOLoHvScO27J2JzXjyMq3e5eKtrHnFBh5B6SU,1052
-archunitpython/common/fluentapi/__init__.py,sha256=J7PDgqBXQOpXqCMCGRyFNil0dCulufmhfirzvYvh-gk,119
-archunitpython/common/fluentapi/checkable.py,sha256=6Tsxtycc27-LaeE6cTtQF6NfepFzhgmCrFJAosN_chs,892
+archunitpython/common/fluentapi/__init__.py,sha256=LeS7qS2p9-FqqBhDL8xRPex__W5Qk0UWfcpl7nVVLfI,178
+archunitpython/common/fluentapi/checkable.py,sha256=BJFYibVhHLMFlnWdISPCIL3DYI1_3JN2-1jEQOaVaGE,1547
 archunitpython/common/logging/__init__.py,sha256=u3-2_jYmiyoQ-C534SmQXvR1L9h3lbJqA9Yt1Nmv9HA,115
 archunitpython/common/logging/types.py,sha256=wUriZeaUawA3JoBfJVLC6lIMglbLG955nXWdJGwxW4I,425
 archunitpython/common/projection/__init__.py,sha256=-Sx-b80b2N3ap3ahAcLUCXqYYK3ccgTDpV-K1jSOSYQ,797
@@ -38,7 +38,7 @@ archunitpython/files/assertion/depend_on_external_modules.py,sha256=BXGpN-301YOc
 archunitpython/files/assertion/depend_on_files.py,sha256=EGMtDD8KT09BJQwOEMoKj-yTQfY3KLLYWN5SM1BCmpY,2012
 archunitpython/files/assertion/matching_files.py,sha256=qNbvU2o_MM6rzM-YUdJZzkltVbenWGC0u5kLH7su6CA,2003
 archunitpython/files/fluentapi/__init__.py,sha256=wgl8IOqTeQGpNISu-Q8b_j6rTn8aEgoz6t1S5j8z13g,108
-archunitpython/files/fluentapi/files.py,sha256=MsXY-763W9wVrtU50mDs_cuaErWRHk1MehbbAit4Je8,17032
+archunitpython/files/fluentapi/files.py,sha256=oZG0lWV6p0AiGANdoZfYd51H8zY-J4eTSPRTRPBYhs0,17152
 archunitpython/graph/__init__.py,sha256=vm1jMOoN35IIU7YDs59qPtf_F82YV-QrEGfXhozAOek,756
 archunitpython/graph/graph_reporter.py,sha256=D_KH01CM7TzeMFB6o5NIQfLVJq0rvKZn9l7WumXV6lo,25598
 archunitpython/layers/__init__.py,sha256=DCRxqLhluTxTaT9ZM2MbfAdJVgqcOO9jtkZHzBbeLOw,164
@@ -59,25 +59,25 @@ archunitpython/metrics/extraction/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeR
 archunitpython/metrics/extraction/extract_class_info.py,sha256=IFokUFwNaExmPtKnHW5hgnYWodRtBM3cWhXBGb7lcjs,7751
 archunitpython/metrics/fluentapi/__init__.py,sha256=HD72MWF0hCh2LzKfyk3mMJp2tf7TJebpwTtZ_kppjso,84
 archunitpython/metrics/fluentapi/export_utils.py,sha256=1r-zTQAUqn_agp4_lhbcffdzfdASNY3LebYvKAG9kcQ,2333
-archunitpython/metrics/fluentapi/metrics.py,sha256=tvaMctIJAjqHhGT62u5LbZImJFCGIsoJ3Z6cdiY6zTs,19198
+archunitpython/metrics/fluentapi/metrics.py,sha256=EaH1seQKppXyx7DiPz1D-S1YYRt48OBWqdKn47BQhoA,19338
 archunitpython/metrics/projection/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 archunitpython/slices/__init__.py,sha256=tb8MoZiEqIdmWy7uyhmEtMNm5Fxjuw6atSvDsD131DE,96
 archunitpython/slices/assertion/__init__.py,sha256=MRwV3d69ljAJ7hFYdxI6UDNC8U4Dm1ImeuLUVKEC9To,280
 archunitpython/slices/assertion/admissible_edges.py,sha256=-3o5mGtl81i5I_572x3Z4ZDfqPCyFqjGd7Dg8GRSKhY,3119
 archunitpython/slices/fluentapi/__init__.py,sha256=tb8MoZiEqIdmWy7uyhmEtMNm5Fxjuw6atSvDsD131DE,96
-archunitpython/slices/fluentapi/slices.py,sha256=5Q6HbUqzz3xSyeeI3iLqMYRX-LXbu5xOc806MWqqYro,7103
+archunitpython/slices/fluentapi/slices.py,sha256=vNoyqmleTDTjnf2i35i2nte-Ycjm-oapfgaf3AhN0QI,7163
 archunitpython/slices/projection/__init__.py,sha256=tVgcK4gw-bqhUq98vU7_iPE0NEhOPUr7vr1-p7JI1A4,237
 archunitpython/slices/projection/slicing_projections.py,sha256=BHBkuVG80mqzT7N4FlCCfY5U_NvlXmAgTmHf_SPTXVM,4215
 archunitpython/slices/uml/__init__.py,sha256=GQFA5WBKfi_YElWiNWNm9c9IM-VaW83_Cg6kpwkzxkw,196
 archunitpython/slices/uml/export_diagram.py,sha256=FeBRV8Vt8LuhLqEbg5JzZOmEk2i49JPkozMcI5r335g,818
 archunitpython/slices/uml/generate_rules.py,sha256=D9vvqDzHAM0F80z4u5yBalEqIiNfJJ5HGXP0fVlSzHw,2136
 archunitpython/testing/__init__.py,sha256=MJm6CHGhBGFg1um2L20-GD2DEHKqg8SiUoI-sRsoXQk,128
-archunitpython/testing/assertion.py,sha256=YTiNWHIQu4xlSqmlvqj1L-Z2Oo1Z-wOvN0VyZQB-CZE,1430
+archunitpython/testing/assertion.py,sha256=7cXlNwBklIGAyUJlPGFGAw97xZ9UgpkZvoO_QBdqm1c,1637
 archunitpython/testing/common/__init__.py,sha256=Wc4bC-N4t6giChKjj6wuTGKkb39thcYS_xKWG9paYeY,220
 archunitpython/testing/common/color_utils.py,sha256=2I8Z1SZfWhhgudMgmXY6PPydGxGl35cK_To-GXnSyJg,1226
 archunitpython/testing/common/violation_factory.py,sha256=yWlvv2U7u-7KoTMfp1QCeJXxTLpPEagKqDHZmPSyrlk,4677
 archunitpython/testing/pytest_plugin/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-archunitpython-1.2.1.dist-info/METADATA,sha256=0kFzgCIGfYVHduyDa7U4njL_cGzoMoThpd255uf_Eh8,28498
-archunitpython-1.2.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-archunitpython-1.2.1.dist-info/licenses/LICENSE,sha256=kaQWfzfHk45CNIx4sIW7Uf1sNW5rmo6BpZ-R8GruuK0,1102
-archunitpython-1.2.1.dist-info/RECORD,,
+archunitpython-1.3.0.dist-info/METADATA,sha256=79jbCuDyAMQr3aY3A_fesygIwS8hF8ceYaPRzJvUmrU,30275
+archunitpython-1.3.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+archunitpython-1.3.0.dist-info/licenses/LICENSE,sha256=kaQWfzfHk45CNIx4sIW7Uf1sNW5rmo6BpZ-R8GruuK0,1102
+archunitpython-1.3.0.dist-info/RECORD,,