archunitpython 1.2.1__tar.gz → 1.4.0__tar.gz

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

@@ -11,8 +11,8 @@ 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 an `.archignore` or similar file, modeled after `.gitignore`, for files that should never be analyzed.
+- [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.4.0}/CHANGELOG.md

@@ -1,3 +1,23 @@
+# [1.4.0](https://github.com/LukasNiessen/ArchUnitPython/compare/v1.3.0...v1.4.0) (2026-07-18)
+
+
+### Bug Fixes
+
+* clarify metadata and exclude messages ([999bb68](https://github.com/LukasNiessen/ArchUnitPython/commit/999bb689594ff613b5f4445191509bcdaa9a514f))
+* harden archignore loading ([ae88c93](https://github.com/LukasNiessen/ArchUnitPython/commit/ae88c932ae2838cff0eabab687ac948f4920c3eb))
+
+
+### Features
+
+* support archignore exclusions ([c51c401](https://github.com/LukasNiessen/ArchUnitPython/commit/c51c40148425b08ce0257d75dd95c996d0505b00))
+
+# [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.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: archunitpython
-Version: 1.2.1
+Version: 1.4.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,43 @@ options = CheckOptions(
 violations = rule.check(options)
 ```
 
+### Excluding Files With `.archignore`
+
+Add a `.archignore` file to your project root to permanently exclude generated or
+irrelevant files from architecture checks and file-based metrics:
+
+```gitignore
+# Generated code
+generated/
+
+# Migration scripts
+migrations/*.py
+
+# A single root-level file
+/legacy_adapter.py
+```
+
+Patterns support comments, blank lines, glob syntax, root-relative paths, path
+patterns, and directory patterns with a trailing `/`.
+### 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 +468,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`](https://github.com/psf/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()
+```
+**Exported mermaid 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.4.0}/README.md

@@ -155,6 +155,43 @@ options = CheckOptions(
 violations = rule.check(options)
 ```
 
+### Excluding Files With `.archignore`
+
+Add a `.archignore` file to your project root to permanently exclude generated or
+irrelevant files from architecture checks and file-based metrics:
+
+```gitignore
+# Generated code
+generated/
+
+# Migration scripts
+migrations/*.py
+
+# A single root-level file
+/legacy_adapter.py
+```
+
+Patterns support comments, blank lines, glob syntax, root-relative paths, path
+patterns, and directory patterns with a trailing `/`.
+### 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 +435,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`](https://github.com/psf/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()
+```
+**Exported mermaid 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.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "archunitpython"
-version = "1.2.1"
+version = "1.4.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.4.0}/scripts/check_release_metadata.py

@@ -17,7 +17,7 @@ def read_project_version() -> str:
     content = PYPROJECT.read_text(encoding="utf-8")
     match = re.search(r'^version = "([^"]+)"$', content, re.MULTILINE)
     if match is None:
-        raise RuntimeError("Could not find project.version in pyproject.toml")
+        raise RuntimeError("Could not find [project].version in pyproject.toml")
     return match.group(1)
 
 

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

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

{archunitpython-1.2.1 → archunitpython-1.4.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.2.1 → archunitpython-1.4.0}/src/archunitpython/common/extraction/extract_graph.py

@@ -29,6 +29,8 @@ _DEFAULT_EXCLUDE = [
     "*.egg-info",
 ]
 
+_ARCHIGNORE_FILE = ".archignore"
+
 _IGNORE_DIRECTIVE_REGEX = re.compile(
     r"#\s*archunit(?::|-)\s*ignore"
     r"(?:\([^)]*\))?"
@@ -88,9 +90,7 @@ def extract_graph(
         project_path = os.getcwd()
 
     project_path = os.path.abspath(project_path)
-    excludes = (
-        list(set(exclude_patterns)) if exclude_patterns is not None else list(_DEFAULT_EXCLUDE)
-    )
+    excludes = _resolve_exclude_patterns(project_path, exclude_patterns)
     ignore_type_checking_imports = bool(options and options.ignore_type_checking_imports)
     cache_key = _build_cache_key(project_path, excludes, ignore_type_checking_imports)
 
@@ -122,6 +122,34 @@ def _build_cache_key(
     )
 
 
+def _resolve_exclude_patterns(
+    project_path: str,
+    exclude_patterns: list[str] | None,
+) -> list[str]:
+    """Resolve exclude patterns (explicit or defaults) plus any .archignore patterns."""
+    excludes = list(exclude_patterns) if exclude_patterns is not None else list(_DEFAULT_EXCLUDE)
+    excludes.extend(_load_archignore_patterns(project_path))
+    return excludes
+
+
+def _load_archignore_patterns(project_path: str) -> list[str]:
+    """Load .archignore patterns from a project root, if present."""
+    archignore_path = os.path.join(project_path, _ARCHIGNORE_FILE)
+    try:
+        with open(archignore_path, "r", encoding="utf-8", errors="replace") as f:
+            lines = f.readlines()
+    except OSError:
+        return []
+
+    patterns: list[str] = []
+    for line in lines:
+        pattern = line.strip()
+        if not pattern or pattern.startswith("#"):
+            continue
+        patterns.append(pattern)
+    return patterns
+
+
 def _extract_graph_uncached(
     project_path: str,
     exclude_patterns: list[str],
@@ -160,7 +188,7 @@ def _extract_graph_uncached(
             if resolved and resolved != _normalize(file_path):
                 # Check if the resolved path is in our project
                 if not is_external and resolved not in normalized_py_file_set:
-                    is_external = True
+                    continue
 
                 edges.append(
                     Edge(
@@ -182,25 +210,65 @@ def _normalize(path: str) -> str:
 def _find_python_files(root: str, exclude: list[str]) -> list[str]:
     """Recursively find all .py files, excluding specified patterns."""
     py_files: list[str] = []
+    root = os.path.abspath(root)
     for dirpath, dirnames, filenames in os.walk(root):
         # Filter out excluded directories in-place
-        dirnames[:] = [d for d in dirnames if not _should_exclude(d, exclude)]
+        dirnames[:] = [
+            d
+            for d in dirnames
+            if not _should_exclude_path(os.path.join(dirpath, d), root, exclude, is_dir=True)
+        ]
 
         for filename in filenames:
-            if filename.endswith(".py") and not _should_exclude(filename, exclude):
-                full_path = os.path.join(dirpath, filename)
+            full_path = os.path.join(dirpath, filename)
+            if filename.endswith(".py") and not _should_exclude_path(
+                full_path, root, exclude, is_dir=False
+            ):
                 py_files.append(os.path.abspath(full_path))
 
     return py_files
 
 
-def _should_exclude(name: str, patterns: list[str]) -> bool:
-    """Check if a name matches any exclude pattern."""
+def _should_exclude_path(
+    path: str,
+    root: str,
+    patterns: list[str],
+    *,
+    is_dir: bool,
+) -> bool:
+    """Check if a path matches any exclude pattern."""
     import fnmatch
 
-    for pattern in patterns:
-        if fnmatch.fnmatch(name, pattern):
+    rel_path = _normalize(os.path.relpath(path, root))
+    name = os.path.basename(path)
+
+    for raw_pattern in patterns:
+        pattern = raw_pattern.strip().replace("\\", "/")
+        if not pattern or pattern.startswith("#"):
+            continue
+
+        pattern = pattern.removeprefix("./")
+        anchored = pattern.startswith("/")
+        if anchored:
+            pattern = pattern[1:]
+
+        dir_only = pattern.endswith("/")
+        if dir_only:
+            pattern = pattern.rstrip("/")
+            if not is_dir:
+                continue
+
+        if not pattern:
+            continue
+
+        if "/" in pattern or anchored:
+            if fnmatch.fnmatch(rel_path, pattern):
+                return True
+            if is_dir and rel_path == pattern:
+                return True
+        elif fnmatch.fnmatch(name, pattern):
             return True
+
     return False
 
 

archunitpython-1.4.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.4.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.4.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.4.0}/src/archunitpython/metrics/extraction/extract_class_info.py

@@ -5,7 +5,10 @@ from __future__ import annotations
 import ast
 import os
 
-from archunitpython.common.extraction.extract_graph import _DEFAULT_EXCLUDE, _find_python_files
+from archunitpython.common.extraction.extract_graph import (
+    _find_python_files,
+    _resolve_exclude_patterns,
+)
 from archunitpython.metrics.common.types import (
     ClassInfo,
     EnhancedClassInfo,
@@ -33,7 +36,7 @@ def extract_class_info(
         project_path = os.getcwd()
 
     project_path = os.path.abspath(project_path)
-    excludes = exclude_patterns if exclude_patterns is not None else _DEFAULT_EXCLUDE
+    excludes = _resolve_exclude_patterns(project_path, exclude_patterns)
     py_files = _find_python_files(project_path, excludes)
 
     classes: list[ClassInfo] = []
@@ -53,7 +56,7 @@ def extract_enhanced_class_info(
         project_path = os.getcwd()
 
     project_path = os.path.abspath(project_path)
-    excludes = exclude_patterns if exclude_patterns is not None else _DEFAULT_EXCLUDE
+    excludes = _resolve_exclude_patterns(project_path, exclude_patterns)
     py_files = _find_python_files(project_path, excludes)
 
     results: list[FileAnalysisResult] = []