archunitpython 1.0.1__tar.gz → 1.1.0__tar.gz

{archunitpython-1.0.1 → archunitpython-1.1.0}/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [1.1.0](https://github.com/LukasNiessen/ArchUnitPython/compare/v1.0.1...v1.1.0) (2026-04-26)
+
+
+### Bug Fixes
+
+* linting errors ([bae7613](https://github.com/LukasNiessen/ArchUnitPython/commit/bae761376817a858a622f2320da3a4596823c891))
+
+
+### Features
+
+* add external dependencies and TYPE_CHECKING ([02b8d01](https://github.com/LukasNiessen/ArchUnitPython/commit/02b8d01b37752e5ddd815ab5c10b36f26814f438))
+
 ## [1.0.1](https://github.com/LukasNiessen/ArchUnitPython/compare/v1.0.0...v1.0.1) (2026-04-02)
 
 

{archunitpython-1.0.1 → archunitpython-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: archunitpython
-Version: 1.0.1
+Version: 1.1.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
@@ -189,7 +189,7 @@ Ensure services/modules don't have forbidden cross-dependencies.
 
 Here is a repository with a fully functioning example that uses ArchUnitPython to ensure architectural rules:
 
-- **[RAG Pipeline Example](https://github.com/LukasNiessen/ArchUnitPython-Example-RAG)**: A mock AI/RAG pipeline with layered architecture and intentional violations demonstrating ArchUnitPython catching real problems
+- **[RAG Pipeline Test Showcase](https://github.com/LukasNiessen/ArchUnitPython-TestRepo-RAG)**: A test showcase demonstrating ArchUnitPython's architecture testing capabilities on a RAG pipeline
 
 ## 🐣 Features
 

{archunitpython-1.0.1 → archunitpython-1.1.0}/README.md

@@ -157,7 +157,7 @@ Ensure services/modules don't have forbidden cross-dependencies.
 
 Here is a repository with a fully functioning example that uses ArchUnitPython to ensure architectural rules:
 
-- **[RAG Pipeline Example](https://github.com/LukasNiessen/ArchUnitPython-Example-RAG)**: A mock AI/RAG pipeline with layered architecture and intentional violations demonstrating ArchUnitPython catching real problems
+- **[RAG Pipeline Test Showcase](https://github.com/LukasNiessen/ArchUnitPython-TestRepo-RAG)**: A test showcase demonstrating ArchUnitPython's architecture testing capabilities on a RAG pipeline
 
 ## 🐣 Features
 

{archunitpython-1.0.1 → archunitpython-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "archunitpython"
-version = "1.0.1"
+version = "1.1.0"
 description = "Architecture testing library for Python projects. Enforce dependency rules, detect cycles, validate metrics."
 readme = "README.md"
 license = "MIT"
@@ -67,13 +67,13 @@ python_classes = ["Test*"]
 python_functions = ["test_*"]
 
 [tool.mypy]
-python_version = "1.0.1"
+python_version = "1.1.0"
 strict = true
 warn_return_any = true
 warn_unused_configs = true
 
 [tool.ruff]
-target-version = "1.0.1"
+target-version = "1.1.0"
 line-length = 100
 
 [tool.ruff.lint]

{archunitpython-1.0.1 → archunitpython-1.1.0}/src/archunitpython/common/extraction/extract_graph.py

@@ -8,7 +8,9 @@ import os
 from archunitpython.common.extraction.graph import Edge, Graph, ImportKind
 from archunitpython.common.fluentapi.checkable import CheckOptions
 
-_graph_cache: dict[str, Graph] = {}
+GraphCacheKey = tuple[str, tuple[str, ...], bool]
+
+_graph_cache: dict[GraphCacheKey, Graph] = {}
 
 _DEFAULT_EXCLUDE = [
     "__pycache__",
@@ -56,7 +58,13 @@ def extract_graph(
         project_path = os.getcwd()
 
     project_path = os.path.abspath(project_path)
-    cache_key = project_path
+    excludes = list(exclude_patterns) if exclude_patterns is not None else list(_DEFAULT_EXCLUDE)
+    ignore_type_checking_imports = bool(
+        options and options.ignore_type_checking_imports
+    )
+    cache_key = _build_cache_key(
+        project_path, excludes, ignore_type_checking_imports
+    )
 
     if options and options.clear_cache:
         _graph_cache.pop(cache_key, None)
@@ -64,18 +72,36 @@ def extract_graph(
     if cache_key in _graph_cache:
         return _graph_cache[cache_key]
 
-    result = _extract_graph_uncached(project_path, exclude_patterns)
+    result = _extract_graph_uncached(
+        project_path,
+        excludes,
+        ignore_type_checking_imports=ignore_type_checking_imports,
+    )
     _graph_cache[cache_key] = result
     return result
 
 
+def _build_cache_key(
+    project_path: str,
+    exclude_patterns: list[str],
+    ignore_type_checking_imports: bool,
+) -> GraphCacheKey:
+    """Build a stable cache key for graph extraction options."""
+    return (
+        project_path,
+        tuple(sorted(exclude_patterns)),
+        ignore_type_checking_imports,
+    )
+
+
 def _extract_graph_uncached(
     project_path: str,
-    exclude_patterns: list[str] | None = None,
+    exclude_patterns: list[str],
+    *,
+    ignore_type_checking_imports: bool = False,
 ) -> Graph:
     """Extract graph without caching."""
-    excludes = exclude_patterns if exclude_patterns is not None else _DEFAULT_EXCLUDE
-    py_files = _find_python_files(project_path, excludes)
+    py_files = _find_python_files(project_path, exclude_patterns)
 
     edges: list[Edge] = []
     py_files_set = set(py_files)
@@ -93,6 +119,11 @@ def _extract_graph_uncached(
         # Extract and resolve imports
         imports = _extract_imports(file_path)
         for module_name, import_kind in imports:
+            if (
+                ignore_type_checking_imports
+                and import_kind == ImportKind.TYPE_IMPORT
+            ):
+                continue
             resolved, is_external = _resolve_import(
                 module_name, file_path, project_path, import_kind
             )

{archunitpython-1.0.1 → archunitpython-1.1.0}/src/archunitpython/common/fluentapi/checkable.py

@@ -16,6 +16,7 @@ class CheckOptions:
     allow_empty_tests: bool = False
     logging: LoggingOptions | None = None
     clear_cache: bool = False
+    ignore_type_checking_imports: bool = False
 
 
 class Checkable(Protocol):

{archunitpython-1.0.1 → archunitpython-1.1.0}/src/archunitpython/common/projection/edge_projections.py

@@ -34,3 +34,20 @@ def per_edge() -> MapFunction:
         return MappedEdge(source_label=edge.source, target_label=edge.target)
 
     return mapper
+
+
+def per_external_edge() -> MapFunction:
+    """Create a mapper that only passes external edges.
+
+    Self-referencing edges are filtered out, though they are not expected for
+    external imports.
+    """
+
+    def mapper(edge: Edge) -> MappedEdge | None:
+        if not edge.external:
+            return None
+        if edge.source == edge.target:
+            return None
+        return MappedEdge(source_label=edge.source, target_label=edge.target)
+
+    return mapper

{archunitpython-1.0.1 → archunitpython-1.1.0}/src/archunitpython/files/assertion/__init__.py

@@ -5,6 +5,10 @@ from archunitpython.files.assertion.custom_file_logic import (
     gather_custom_file_violations,
 )
 from archunitpython.files.assertion.cycle_free import ViolatingCycle, gather_cycle_violations
+from archunitpython.files.assertion.depend_on_external_modules import (
+    ViolatingExternalModuleDependency,
+    gather_depend_on_external_module_violations,
+)
 from archunitpython.files.assertion.depend_on_files import (
     ViolatingFileDependency,
     gather_depend_on_file_violations,
@@ -20,9 +24,11 @@ __all__ = [
     "FileInfo",
     "ViolatingCycle",
     "ViolatingFileDependency",
+    "ViolatingExternalModuleDependency",
     "ViolatingNode",
     "gather_custom_file_violations",
     "gather_cycle_violations",
     "gather_depend_on_file_violations",
+    "gather_depend_on_external_module_violations",
     "gather_regex_matching_violations",
 ]

archunitpython-1.1.0/src/archunitpython/files/assertion/depend_on_external_modules.py

@@ -0,0 +1,64 @@
+"""Violation gathering for external module dependency rules."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from archunitpython.common.assertion.violation import Violation
+from archunitpython.common.pattern_matching import matches_pattern
+from archunitpython.common.projection.types import ProjectedEdge
+from archunitpython.common.types import Filter
+
+
+@dataclass
+class ViolatingExternalModuleDependency(Violation):
+    """An external module dependency that violates a rule."""
+
+    dependency: ProjectedEdge
+    is_negated: bool = False
+
+
+def gather_depend_on_external_module_violations(
+    edges: list[ProjectedEdge],
+    subject_filters: list[Filter],
+    module_filters: list[Filter],
+    is_negated: bool,
+) -> list[Violation]:
+    """Check if files depend on forbidden/allowed external modules.
+
+    Subject filters use AND semantics. Module filters use OR semantics, which
+    makes it possible to express useful allowlists or blocklists for external
+    module names.
+    """
+    violations: list[Violation] = []
+
+    for edge in edges:
+        source_matches = all(
+            matches_pattern(edge.source_label, filter_)
+            for filter_ in subject_filters
+        )
+        if not source_matches:
+            continue
+
+        target_matches = (
+            any(matches_pattern(edge.target_label, filter_) for filter_ in module_filters)
+            if module_filters
+            else False
+        )
+
+        if is_negated:
+            if target_matches:
+                violations.append(
+                    ViolatingExternalModuleDependency(
+                        dependency=edge, is_negated=True
+                    )
+                )
+        else:
+            if not target_matches:
+                violations.append(
+                    ViolatingExternalModuleDependency(
+                        dependency=edge, is_negated=False
+                    )
+                )
+
+    return violations

{archunitpython-1.0.1 → archunitpython-1.1.0}/src/archunitpython/files/fluentapi/files.py

@@ -16,7 +16,10 @@ from archunitpython.common.assertion.violation import EmptyTestViolation, Violat
 from archunitpython.common.extraction.extract_graph import extract_graph
 from archunitpython.common.fluentapi.checkable import CheckOptions
 from archunitpython.common.pattern_matching import matches_all_patterns
-from archunitpython.common.projection.edge_projections import per_internal_edge
+from archunitpython.common.projection.edge_projections import (
+    per_external_edge,
+    per_internal_edge,
+)
 from archunitpython.common.projection.project_cycles import project_cycles
 from archunitpython.common.projection.project_edges import project_edges
 from archunitpython.common.projection.project_nodes import project_to_nodes
@@ -28,6 +31,9 @@ from archunitpython.files.assertion.custom_file_logic import (
     gather_custom_file_violations,
 )
 from archunitpython.files.assertion.cycle_free import gather_cycle_violations
+from archunitpython.files.assertion.depend_on_external_modules import (
+    gather_depend_on_external_module_violations,
+)
 from archunitpython.files.assertion.depend_on_files import gather_depend_on_file_violations
 from archunitpython.files.assertion.matching_files import gather_regex_matching_violations
 
@@ -133,6 +139,14 @@ class PositiveMatchPatternFileConditionBuilder:
             self._project_path, self._filters, is_negated=False
         )
 
+    def depend_on_external_modules(
+        self,
+    ) -> "DependOnExternalModuleConditionBuilder":
+        """Begin external dependency assertion for module names."""
+        return DependOnExternalModuleConditionBuilder(
+            self._project_path, self._filters, is_negated=False
+        )
+
     def be_in_folder(self, folder: Pattern) -> "MatchPatternFileCondition":
         """Assert that files are in a certain folder."""
         return MatchPatternFileCondition(
@@ -182,6 +196,14 @@ class NegatedMatchPatternFileConditionBuilder:
             self._project_path, self._filters, is_negated=True
         )
 
+    def depend_on_external_modules(
+        self,
+    ) -> "DependOnExternalModuleConditionBuilder":
+        """Begin negative external dependency assertion for module names."""
+        return DependOnExternalModuleConditionBuilder(
+            self._project_path, self._filters, is_negated=True
+        )
+
     def be_in_folder(self, folder: Pattern) -> "MatchPatternFileCondition":
         """Assert that files are NOT in a certain folder."""
         return MatchPatternFileCondition(
@@ -260,6 +282,31 @@ class DependOnFileConditionBuilder:
         )
 
 
+class DependOnExternalModuleConditionBuilder:
+    """Configure external module dependency target patterns."""
+
+    def __init__(
+        self, project_path: str | None, filters: list[Filter], is_negated: bool
+    ) -> None:
+        self._project_path = project_path
+        self._filters = filters
+        self._is_negated = is_negated
+        self._module_filters: list[Filter] = []
+
+    def matching(self, module_name: Pattern) -> "DependOnExternalModuleCondition":
+        """Target external modules by dotted module name pattern.
+
+        Multiple calls are combined with OR semantics.
+        """
+        self._module_filters.append(RegexFactory.path_matcher(module_name))
+        return DependOnExternalModuleCondition(
+            self._project_path,
+            self._filters,
+            list(self._module_filters),
+            self._is_negated,
+        )
+
+
 def _get_filtered_nodes(
     project_path: str | None,
     filters: list[Filter],
@@ -346,6 +393,38 @@ class DependOnFileCondition:
         )
 
 
+class DependOnExternalModuleCondition:
+    """Checkable that verifies external module dependency rules."""
+
+    def __init__(
+        self,
+        project_path: str | None,
+        subject_filters: list[Filter],
+        module_filters: list[Filter],
+        is_negated: bool,
+    ) -> None:
+        self._project_path = project_path
+        self._subject_filters = subject_filters
+        self._module_filters = module_filters
+        self._is_negated = is_negated
+
+    def matching(self, module_name: Pattern) -> "DependOnExternalModuleCondition":
+        """Add another external module pattern using OR semantics."""
+        self._module_filters.append(RegexFactory.path_matcher(module_name))
+        return self
+
+    def check(self, options: CheckOptions | None = None) -> list[Violation]:
+        graph = extract_graph(self._project_path, options=options)
+        edges = project_edges(graph, per_external_edge())
+
+        return gather_depend_on_external_module_violations(
+            edges,
+            self._subject_filters,
+            self._module_filters,
+            self._is_negated,
+        )
+
+
 class MatchPatternFileCondition:
     """Checkable that verifies files match/don't match patterns."""
 

{archunitpython-1.0.1 → archunitpython-1.1.0}/src/archunitpython/testing/common/violation_factory.py

@@ -7,6 +7,9 @@ from dataclasses import dataclass
 from archunitpython.common.assertion.violation import EmptyTestViolation, Violation
 from archunitpython.files.assertion.custom_file_logic import CustomFileViolation
 from archunitpython.files.assertion.cycle_free import ViolatingCycle
+from archunitpython.files.assertion.depend_on_external_modules import (
+    ViolatingExternalModuleDependency,
+)
 from archunitpython.files.assertion.depend_on_files import ViolatingFileDependency
 from archunitpython.files.assertion.matching_files import ViolatingNode
 from archunitpython.metrics.assertion.metric_thresholds import (
@@ -52,6 +55,15 @@ class ViolationFactory:
                 f"'{edge.target_label}'",
             )
 
+        if isinstance(violation, ViolatingExternalModuleDependency):
+            edge = violation.dependency
+            return TestViolation(
+                message="External module dependency violation",
+                details=f"'{edge.source_label}' "
+                f"{'depends on' if violation.is_negated else 'does not depend on'} "
+                f"external module '{edge.target_label}'",
+            )
+
         if isinstance(violation, ViolatingCycle):
             cycle_str = " -> ".join(
                 e.source_label for e in violation.cycle

{archunitpython-1.0.1 → archunitpython-1.1.0}/tests/common/test_core_types.py

@@ -101,6 +101,7 @@ class TestCheckOptions:
         assert opts.allow_empty_tests is False
         assert opts.logging is None
         assert opts.clear_cache is False
+        assert opts.ignore_type_checking_imports is False
 
     def test_custom(self):
         logging = LoggingOptions(enabled=True, level="debug")
@@ -108,12 +109,14 @@ class TestCheckOptions:
             allow_empty_tests=True,
             logging=logging,
             clear_cache=True,
+            ignore_type_checking_imports=True,
         )
         assert opts.allow_empty_tests is True
         assert opts.logging is not None
         assert opts.logging.enabled is True
         assert opts.logging.level == "debug"
         assert opts.clear_cache is True
+        assert opts.ignore_type_checking_imports is True
 
 
 class TestLoggingOptions:

{archunitpython-1.0.1 → archunitpython-1.1.0}/tests/common/test_extract_graph.py

@@ -1,6 +1,9 @@
 """Tests for graph extraction."""
 
 import os
+import shutil
+from pathlib import Path
+from uuid import uuid4
 
 import pytest
 
@@ -12,6 +15,7 @@ from archunitpython.common.extraction.extract_graph import (
     extract_graph,
 )
 from archunitpython.common.extraction.graph import Edge, ImportKind
+from archunitpython.common.fluentapi.checkable import CheckOptions
 
 FIXTURES_DIR = os.path.join(os.path.dirname(os.path.dirname(__file__)), "fixtures")
 SAMPLE_PROJECT = os.path.join(FIXTURES_DIR, "sample_project")
@@ -116,8 +120,6 @@ class TestExtractGraph:
         assert graph1 is graph2  # Same object reference (cached)
 
     def test_cache_clear(self):
-        from archunitpython.common.fluentapi.checkable import CheckOptions
-
         graph1 = extract_graph(SAMPLE_PROJECT)
         graph2 = extract_graph(
             SAMPLE_PROJECT, options=CheckOptions(clear_cache=True)
@@ -130,6 +132,100 @@ class TestExtractGraph:
         assert len(edges_with_kinds) > 0
 
 
+class TestTypeCheckingImportHandling:
+    def setup_method(self):
+        clear_graph_cache()
+
+    def _build_type_checking_project(self) -> str:
+        temp_root = Path(__file__).resolve().parent / ".tmp"
+        temp_root.mkdir(exist_ok=True)
+        project_root = temp_root / f"project_{uuid4().hex}"
+        project_root.mkdir()
+
+        package_dir = project_root / "sample_project"
+        package_dir.mkdir(parents=True, exist_ok=True)
+
+        (package_dir / "__init__.py").write_text("", encoding="utf-8")
+        (package_dir / "models.py").write_text(
+            "class User:\n    pass\n",
+            encoding="utf-8",
+        )
+        (package_dir / "service.py").write_text(
+            "\n".join(
+                [
+                    "from typing import TYPE_CHECKING",
+                    "",
+                    "if TYPE_CHECKING:",
+                    "    from sample_project.models import User",
+                    "",
+                    "def get_user() -> str:",
+                    '    return "ok"',
+                    "",
+                ]
+            ),
+            encoding="utf-8",
+        )
+        self._temp_dir = project_root
+        return str(project_root)
+
+    def teardown_method(self):
+        temp_dir = getattr(self, "_temp_dir", None)
+        if temp_dir is not None:
+            shutil.rmtree(temp_dir, ignore_errors=True)
+
+    def test_type_checking_imports_included_by_default(self):
+        project_root = self._build_type_checking_project()
+
+        graph = extract_graph(project_root)
+        models_path = os.path.abspath(
+            os.path.join(project_root, "sample_project", "models.py")
+        ).replace("\\", "/")
+        service_path = os.path.abspath(
+            os.path.join(project_root, "sample_project", "service.py")
+        ).replace("\\", "/")
+
+        edges = [
+            edge
+            for edge in graph
+            if edge.source == service_path and edge.target == models_path
+        ]
+        assert len(edges) == 1
+        assert ImportKind.TYPE_IMPORT in edges[0].import_kinds
+
+    def test_type_checking_imports_can_be_ignored(self):
+        project_root = self._build_type_checking_project()
+
+        graph = extract_graph(
+            project_root,
+            options=CheckOptions(ignore_type_checking_imports=True),
+        )
+        models_path = os.path.abspath(
+            os.path.join(project_root, "sample_project", "models.py")
+        ).replace("\\", "/")
+        service_path = os.path.abspath(
+            os.path.join(project_root, "sample_project", "service.py")
+        ).replace("\\", "/")
+
+        edges = [
+            edge
+            for edge in graph
+            if edge.source == service_path and edge.target == models_path
+        ]
+        assert edges == []
+
+    def test_cache_key_includes_type_checking_option(self):
+        project_root = self._build_type_checking_project()
+
+        default_graph = extract_graph(project_root)
+        filtered_graph = extract_graph(
+            project_root,
+            options=CheckOptions(ignore_type_checking_imports=True),
+        )
+
+        assert default_graph is not filtered_graph
+        assert len(default_graph) > len(filtered_graph)
+
+
 class TestEdgeModel:
     def test_edge_frozen(self):
         edge = Edge(source="a.py", target="b.py", external=False)

{archunitpython-1.0.1 → archunitpython-1.1.0}/tests/common/test_projection.py

@@ -1,7 +1,11 @@
 """Tests for graph projection functions."""
 
 from archunitpython.common.extraction.graph import Edge, ImportKind
-from archunitpython.common.projection.edge_projections import per_edge, per_internal_edge
+from archunitpython.common.projection.edge_projections import (
+    per_edge,
+    per_external_edge,
+    per_internal_edge,
+)
 from archunitpython.common.projection.project_edges import project_edges
 from archunitpython.common.projection.project_nodes import project_to_nodes
 from archunitpython.common.projection.types import MappedEdge
@@ -149,3 +153,20 @@ class TestPerEdge:
         mapper = per_edge()
         result = mapper(_make_edge("a", "b"))
         assert result is not None
+
+
+class TestPerExternalEdge:
+    def test_filters_internal(self):
+        mapper = per_external_edge()
+        assert mapper(_make_edge("a", "b")) is None
+
+    def test_filters_self_edge(self):
+        mapper = per_external_edge()
+        assert mapper(_make_edge("a", "a", external=True)) is None
+
+    def test_passes_external(self):
+        mapper = per_external_edge()
+        result = mapper(_make_edge("a.py", "json", external=True))
+        assert result is not None
+        assert result.source_label == "a.py"
+        assert result.target_label == "json"