archunitpython 1.0.1__py3-none-any.whl → 1.1.1__py3-none-any.whl

archunitpython/__init__.py

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: archunitpython
-Version: 1.0.1
+Version: 1.1.1
 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.dist-info → archunitpython-1.1.1.dist-info}/RECORD

@@ -1,4 +1,4 @@
-archunitpython/__init__.py,sha256=Y7boq0Xo0uyEXzfP30N_Jt1ij6Ofy8q8XzinC6E1crU,926
+archunitpython/__init__.py,sha256=0CNl66vkf6m597p2KMuJLP6D1CtgSfO1Y6VMxlMScWk,926
 archunitpython/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 archunitpython/common/__init__.py,sha256=u8jwbfALwIT_5ZqTrRchpZqkFHG5tTwM21LX5hR9ZSc,593
 archunitpython/common/pattern_matching.py,sha256=zhfglETSJfe5XPzueVflM14EKfllXuazqzd2XH5fuxw,2675
@@ -9,14 +9,14 @@ archunitpython/common/assertion/violation.py,sha256=TnMOykN3kPoGrSf1KcxBXYRfaxfX
 archunitpython/common/error/__init__.py,sha256=UWcdIKpGAJvo4WEGOVSaUjQQnKoPi8R496uDGXBWKsE,116
 archunitpython/common/error/errors.py,sha256=y7mcXoZPyK7uD2dMMO1qBt1y7KcIeGlRYiVeI6bjms4,249
 archunitpython/common/extraction/__init__.py,sha256=RkJOcxJoLYQxEagh3uWhjsUCprK3Nr3Bn3o7nmzk4_Q,284
-archunitpython/common/extraction/extract_graph.py,sha256=2guw1RA5CnXXR08x2UEzOtfUVfT3wLZcG8xNYIUtCrs,11114
+archunitpython/common/extraction/extract_graph.py,sha256=LNh3gohN3hkzoxBGrMOxqFUVPL3-oYiOU2W6Hja0Mbg,11979
 archunitpython/common/extraction/graph.py,sha256=Rk-0eDDOLoHvScO27J2JzXjyMq3e5eKtrHnFBh5B6SU,1052
 archunitpython/common/fluentapi/__init__.py,sha256=J7PDgqBXQOpXqCMCGRyFNil0dCulufmhfirzvYvh-gk,119
-archunitpython/common/fluentapi/checkable.py,sha256=bdbG8zRgi9pt0xh0LkPzUq5aN8geFlb60KEViAGZc1w,845
+archunitpython/common/fluentapi/checkable.py,sha256=6Tsxtycc27-LaeE6cTtQF6NfepFzhgmCrFJAosN_chs,892
 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
-archunitpython/common/projection/edge_projections.py,sha256=xyQQNh8NnACR9mDRauTmro1_IgZouyTwX7tUl4Zt2xI,1053
+archunitpython/common/projection/edge_projections.py,sha256=Mud8DL6Y8H66CObqyikKYAxdXMRENuAFRtwhCxpwxoU,1524
 archunitpython/common/projection/project_cycles.py,sha256=SA6eXzy599dJMvAOA6K1ONkOaFLiEXw8qixpgybtW-I,3105
 archunitpython/common/projection/project_edges.py,sha256=v7hDMSeghiLz0xHbG4BNF7jNQphcWobU7rgoiuw3fh4,1268
 archunitpython/common/projection/project_nodes.py,sha256=U6sLYvJd6NBgg39V0Ry7r_-57gdXaaXsbH-D12nipCg,1497
@@ -31,13 +31,14 @@ archunitpython/common/util/__init__.py,sha256=g-W8kWiVqwdohxm74J3yUonPkb_yDUJrp7
 archunitpython/common/util/declaration_detector.py,sha256=XgrpgaUIQa9MNFlnhVQz2X_uW7zCO9nrMbGa3tVFyPM,3407
 archunitpython/common/util/logger.py,sha256=QT6ir8caMXu4VQombe0NjaT2NUm58kFdlnps4T5ECCE,3348
 archunitpython/files/__init__.py,sha256=wgl8IOqTeQGpNISu-Q8b_j6rTn8aEgoz6t1S5j8z13g,108
-archunitpython/files/assertion/__init__.py,sha256=U2nJkByFzNHkDGaNXJaCef3ywrDaBLNf9biWNJ_9Yu8,814
+archunitpython/files/assertion/__init__.py,sha256=K2qiEFfmo6SCgxfOKNrPzYgT5ScKUaw2W2CrDa3jBTw,1068
 archunitpython/files/assertion/custom_file_logic.py,sha256=ygpc2NZghHBD-GTGrQW_dWzGZr_9DSvi0denC-cdwuo,3054
 archunitpython/files/assertion/cycle_free.py,sha256=Ib3tmVVErmTpORmRn_rZqOqY0gk54crN_d_IapeWqdI,738
+archunitpython/files/assertion/depend_on_external_modules.py,sha256=d16mK6lpr5MhxndigSZsGEOPF51UY0Gl5HddqP_MdXs,1949
 archunitpython/files/assertion/depend_on_files.py,sha256=B-zyFyXCt2ywCzO0BIH1lRGsre6PkAItv2ZfpM_u2Js,2132
 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=olBZQ6lVMjovMnCEQVzzE4QilvK6w4ojTgbW_nL01tw,14476
+archunitpython/files/fluentapi/files.py,sha256=uX__VDed_TLNiibK2pTMaPQ8RaCyyFf2ZClqdymvs98,17214
 archunitpython/metrics/__init__.py,sha256=HD72MWF0hCh2LzKfyk3mMJp2tf7TJebpwTtZ_kppjso,84
 archunitpython/metrics/assertion/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 archunitpython/metrics/assertion/metric_thresholds.py,sha256=dijCzOr5-dhkdK-QAE3DAkfiSBgknZlxtp-ZrBj_Dmk,1268
@@ -67,9 +68,9 @@ archunitpython/testing/__init__.py,sha256=MJm6CHGhBGFg1um2L20-GD2DEHKqg8SiUoI-sR
 archunitpython/testing/assertion.py,sha256=YTiNWHIQu4xlSqmlvqj1L-Z2Oo1Z-wOvN0VyZQB-CZE,1430
 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=jo6jWzy6-ia-Jc1wU_LA8NVjWMzIHbbrLe7H3ngY-vQ,3681
+archunitpython/testing/common/violation_factory.py,sha256=wrhsQoTmu70cmgXjjTIJNdXFeN9iQerQCZR4-vaAwuQ,4209
 archunitpython/testing/pytest_plugin/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-archunitpython-1.0.1.dist-info/METADATA,sha256=RN8jrD8bVkMWGVQ-2hMJxHSVJ2GZVXJG5O1WkPX8MWo,19832
-archunitpython-1.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-archunitpython-1.0.1.dist-info/licenses/LICENSE,sha256=kaQWfzfHk45CNIx4sIW7Uf1sNW5rmo6BpZ-R8GruuK0,1102
-archunitpython-1.0.1.dist-info/RECORD,,
+archunitpython-1.1.1.dist-info/METADATA,sha256=Qm_crmBhrWg9c5xdnwYxQrqbs3OsSWlMnpZcSIh4PtM,19810
+archunitpython-1.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+archunitpython-1.1.1.dist-info/licenses/LICENSE,sha256=kaQWfzfHk45CNIx4sIW7Uf1sNW5rmo6BpZ-R8GruuK0,1102
+archunitpython-1.1.1.dist-info/RECORD,,