archunitpython 1.3.0__tar.gz → 1.5.0__tar.gz

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

@@ -11,9 +11,9 @@ 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.
+- [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.
+- [x] 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.
 
 ## P1 - Python Import Semantics

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

@@ -1,3 +1,23 @@
+# [1.5.0](https://github.com/LukasNiessen/ArchUnitPython/compare/v1.4.0...v1.5.0) (2026-07-18)
+
+
+### Features
+
+* load common rules from config ([c7c968a](https://github.com/LukasNiessen/ArchUnitPython/commit/c7c968af20e929f7e7a2372275eaa7e26cb38e5f))
+
+# [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)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: archunitpython
-Version: 1.3.0
+Version: 1.5.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,60 @@ 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 `/`.
+
+### Loading Common Rules From Config
+
+For straightforward shared rules, you can load a JSON config file and still run
+the resulting rules in your normal test suite:
+
+```json
+{
+  "project_path": "src",
+  "rules": [
+    {
+      "name": "controllers must not use services directly",
+      "type": "forbidden_dependency",
+      "source": "**/controllers/**",
+      "target": "**/services/**"
+    },
+    {
+      "name": "source files have no cycles",
+      "type": "no_cycles"
+    }
+  ]
+}
+```
+
+```python
+from archunitpython import assert_passes, rules_from_config
+
+def test_configured_architecture_rules():
+    for rule in rules_from_config("archunitpython.json"):
+        assert_passes(rule)
+```
+
+Supported rule types are `no_cycles`, `forbidden_dependency`, and
+`forbidden_external_dependency`. The fluent Python API remains the primary and
+most flexible interface.
+
 ### Explaining Rules With `.because(...)`
 
 Attach a rationale to a rule so failing assertions explain why the rule exists:
@@ -450,7 +504,7 @@ 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**
+**Using [`requests`](https://github.com/psf/requests) library repo for example**
 
 ```python
 from archunitpython import project_graph
@@ -463,7 +517,7 @@ def test_export_dependency_graph_reports():
 if __name__ == "__main__":
     test_export_dependency_graph_reports()
 ```
-**Rendered mermain diagram**
+**Exported mermaid diagram**
 ``` mermaid
 flowchart LR
   n0["__init__.py"]

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

@@ -155,6 +155,60 @@ 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 `/`.
+
+### Loading Common Rules From Config
+
+For straightforward shared rules, you can load a JSON config file and still run
+the resulting rules in your normal test suite:
+
+```json
+{
+  "project_path": "src",
+  "rules": [
+    {
+      "name": "controllers must not use services directly",
+      "type": "forbidden_dependency",
+      "source": "**/controllers/**",
+      "target": "**/services/**"
+    },
+    {
+      "name": "source files have no cycles",
+      "type": "no_cycles"
+    }
+  ]
+}
+```
+
+```python
+from archunitpython import assert_passes, rules_from_config
+
+def test_configured_architecture_rules():
+    for rule in rules_from_config("archunitpython.json"):
+        assert_passes(rule)
+```
+
+Supported rule types are `no_cycles`, `forbidden_dependency`, and
+`forbidden_external_dependency`. The fluent Python API remains the primary and
+most flexible interface.
+
 ### Explaining Rules With `.because(...)`
 
 Attach a rationale to a rule so failing assertions explain why the rule exists:
@@ -417,7 +471,7 @@ 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**
+**Using [`requests`](https://github.com/psf/requests) library repo for example**
 
 ```python
 from archunitpython import project_graph
@@ -430,7 +484,7 @@ def test_export_dependency_graph_reports():
 if __name__ == "__main__":
     test_export_dependency_graph_reports()
 ```
-**Rendered mermain diagram**
+**Exported mermaid diagram**
 ``` mermaid
 flowchart LR
   n0["__init__.py"]

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

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

{archunitpython-1.3.0 → archunitpython-1.5.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.3.0 → archunitpython-1.5.0}/src/archunitpython/__init__.py

@@ -1,6 +1,6 @@
 """ArchUnitPython - Architecture testing library for Python projects."""
 
-__version__ = "1.3.0"
+__version__ = "1.5.0"
 
 # Files API
 # Common
@@ -12,6 +12,7 @@ from archunitpython.common import (
     Violation,
 )
 from archunitpython.common.extraction import clear_graph_cache, extract_graph
+from archunitpython.config import ConfiguredRule, rules_from_config
 from archunitpython.files import files, project_files
 from archunitpython.graph import dependency_graph, project_graph
 from archunitpython.layers import layers, project_layers
@@ -35,6 +36,9 @@ __all__ = [
     # Layers
     "project_layers",
     "layers",
+    # Config
+    "rules_from_config",
+    "ConfiguredRule",
     # Slices
     "project_slices",
     # Metrics

{archunitpython-1.3.0 → archunitpython-1.5.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.5.0/src/archunitpython/config/__init__.py

@@ -0,0 +1,5 @@
+"""Configuration-file support for common architecture rules."""
+
+from archunitpython.config.loader import ConfiguredRule, rules_from_config
+
+__all__ = ["ConfiguredRule", "rules_from_config"]

archunitpython-1.5.0/src/archunitpython/config/loader.py

@@ -0,0 +1,119 @@
+"""Load common architecture rules from a JSON configuration file."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from archunitpython.common.assertion.violation import Violation
+from archunitpython.common.error.errors import UserError
+from archunitpython.common.fluentapi.checkable import Checkable, CheckOptions
+from archunitpython.files.fluentapi.files import project_files
+
+
+@dataclass(frozen=True)
+class ConfiguredRule:
+    """A named rule loaded from a configuration file."""
+
+    name: str
+    rule: Checkable
+
+    def check(self, options: CheckOptions | None = None) -> list[Violation]:
+        """Run the configured rule."""
+        return self.rule.check(options)
+
+
+def rules_from_config(config_path: str) -> list[ConfiguredRule]:
+    """Load common architecture rules from a JSON config file.
+
+    The fluent Python API remains the primary interface. Config files provide a
+    lightweight way to share straightforward rules across projects or teams.
+    """
+    path = Path(config_path)
+    try:
+        raw_config = json.loads(path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise UserError(f"Could not read config file: {config_path}") from exc
+    except json.JSONDecodeError as exc:
+        raise UserError(f"Invalid JSON config file: {config_path}") from exc
+
+    if not isinstance(raw_config, dict):
+        raise UserError("Architecture config must be a JSON object.")
+
+    project_path = _optional_string(raw_config, "project_path") or os.getcwd()
+    rules = raw_config.get("rules")
+    if not isinstance(rules, list):
+        raise UserError("Architecture config must define a 'rules' list.")
+
+    base_dir = str(path.parent if path.parent != Path("") else Path.cwd())
+    resolved_project_path = _resolve_project_path(base_dir, project_path)
+
+    return [_build_rule(resolved_project_path, item, index) for index, item in enumerate(rules, 1)]
+
+
+def _build_rule(project_path: str, item: Any, index: int) -> ConfiguredRule:
+    if not isinstance(item, dict):
+        raise UserError(f"Rule #{index} must be a JSON object.")
+
+    rule_type = _required_string(item, "type", index)
+    name = _optional_string(item, "name") or f"{rule_type} rule #{index}"
+    rule: Checkable
+    if rule_type == "no_cycles":
+        subject = _optional_string(item, "subject")
+        builder = project_files(project_path)
+        if subject is not None:
+            rule = builder.in_path(subject).should().have_no_cycles()
+        else:
+            rule = builder.should().have_no_cycles()
+    elif rule_type == "forbidden_dependency":
+        source = _required_string(item, "source", index)
+        target = _required_string(item, "target", index)
+        rule = (
+            project_files(project_path)
+            .in_path(source)
+            .should_not()
+            .depend_on_files()
+            .in_path(target)
+        )
+    elif rule_type == "forbidden_external_dependency":
+        source = _required_string(item, "source", index)
+        module = _required_string(item, "module", index)
+        rule = (
+            project_files(project_path)
+            .in_path(source)
+            .should_not()
+            .depend_on_external_modules()
+            .matching(module)
+        )
+    else:
+        raise UserError(
+            f"Unsupported rule type '{rule_type}'. Supported types: "
+            "no_cycles, forbidden_dependency, forbidden_external_dependency."
+        )
+
+    return ConfiguredRule(name=name, rule=rule)
+
+
+def _resolve_project_path(base_dir: str, project_path: str) -> str:
+    if os.path.isabs(project_path):
+        return project_path
+    return os.path.abspath(os.path.join(base_dir, project_path))
+
+
+def _required_string(rule: dict[str, Any], key: str, index: int) -> str:
+    value = rule.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise UserError(f"Rule #{index} must define a non-empty string '{key}'.")
+    return value
+
+
+def _optional_string(rule: dict[str, Any], key: str) -> str | None:
+    value = rule.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value.strip():
+        raise UserError(f"Config value '{key}' must be a non-empty string.")
+    return value

{archunitpython-1.3.0 → archunitpython-1.5.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] = []

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

@@ -251,13 +251,13 @@ class FileMetricCondition(RuleRationaleMixin):
         import os
 
         from archunitpython.common.extraction.extract_graph import (
-            _DEFAULT_EXCLUDE,
             _find_python_files,
+            _resolve_exclude_patterns,
         )
 
         project = self._project_path or os.getcwd()
         project = os.path.abspath(project)
-        files = _find_python_files(project, _DEFAULT_EXCLUDE)
+        files = _find_python_files(project, _resolve_exclude_patterns(project, None))
         violations: list[Violation] = []
 
         for file_path in files:

{archunitpython-1.3.0 → archunitpython-1.5.0}/tests/common/test_declaration_detector.py

@@ -1,13 +1,13 @@
 """Tests for declaration detection utilities."""
 
+import ast
+
 from archunitpython.common.util.declaration_detector import (
-    DeclarationCounts,
     count_declarations,
     is_abstract_class,
     is_abstract_method,
     is_protocol_class,
 )
-import ast
 
 
 class TestIsAbstractClass:

{archunitpython-1.3.0 → archunitpython-1.5.0}/tests/common/test_extract_graph.py

@@ -11,6 +11,7 @@ from archunitpython.common.extraction.extract_graph import (
     _extract_imports,
     _find_python_files,
     _normalize,
+    _resolve_exclude_patterns,
     clear_graph_cache,
     extract_graph,
 )
@@ -164,6 +165,73 @@ class TestExtractGraph:
         assert len(edges_with_kinds) > 0
 
 
+class TestArchignore:
+    def setup_method(self):
+        clear_graph_cache()
+        self._temp_dir = Path(__file__).resolve().parent / ".tmp" / f"project_{uuid4().hex}"
+        self._temp_dir.mkdir(parents=True)
+
+    def teardown_method(self):
+        shutil.rmtree(self._temp_dir, ignore_errors=True)
+
+    def _write(self, relative_path: str, content: str = "") -> None:
+        path = self._temp_dir / relative_path
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+
+    def test_archignore_excludes_files_and_directories(self):
+        self._write(
+            ".archignore",
+            "\n".join(
+                [
+                    "# Ignore generated architecture-test inputs",
+                    "ignored.py",
+                    "generated/",
+                    "nested/*.py",
+                    "/root_ignored.py",
+                ]
+            ),
+        )
+        self._write("keep.py")
+        self._write("ignored.py")
+        self._write("root_ignored.py")
+        self._write("generated/generated.py")
+        self._write("nested/ignored_nested.py")
+
+        excludes = _resolve_exclude_patterns(str(self._temp_dir), ["__pycache__"])
+        files = _find_python_files(str(self._temp_dir), excludes)
+        relative_files = {
+            Path(file_path).relative_to(self._temp_dir).as_posix()
+            for file_path in files
+        }
+
+        assert relative_files == {"keep.py"}
+
+    def test_archignore_ignored_files_are_not_dependency_targets(self):
+        self._write(".archignore", "ignored.py\n")
+        self._write("keep.py", "import ignored\n")
+        self._write("ignored.py", "VALUE = 1\n")
+
+        graph = extract_graph(str(self._temp_dir))
+        targets = {edge.target for edge in graph}
+
+        ignored_path = _normalize(str((self._temp_dir / "ignored.py").resolve()))
+        assert ignored_path not in targets
+
+    def test_archignore_with_invalid_utf8_bytes_does_not_abort_extraction(self):
+        (self._temp_dir / ".archignore").write_bytes(b"ignored.py\n\xff\n")
+        self._write("keep.py")
+        self._write("ignored.py")
+
+        graph = extract_graph(str(self._temp_dir))
+        sources = {edge.source for edge in graph}
+
+        keep_path = _normalize(str((self._temp_dir / "keep.py").resolve()))
+        ignored_path = _normalize(str((self._temp_dir / "ignored.py").resolve()))
+        assert keep_path in sources
+        assert ignored_path not in sources
+
+
 class TestTypeCheckingImportHandling:
     def setup_method(self):
         clear_graph_cache()

{archunitpython-1.3.0 → archunitpython-1.5.0}/tests/common/test_logger.py

@@ -1,9 +1,5 @@
 """Tests for the logging system."""
 
-import os
-import shutil
-from pathlib import Path
-
 from archunitpython.common.logging.types import LoggingOptions
 from archunitpython.common.util.logger import CheckLogger
 

archunitpython-1.5.0/tests/config/__init__.py

@@ -0,0 +1 @@
+"""Tests for configuration-file rule loading."""