archunitpython 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

archunitpython/__init__.py

@@ -1,6 +1,6 @@
 """ArchUnitPython - Architecture testing library for Python projects."""
 
-__version__ = "0.1.0"
+__version__ = "1.0.0"
 
 # 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.0.dist-info → archunitpython-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: archunitpython
-Version: 1.0.0
+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
@@ -33,6 +33,7 @@ Description-Content-Type: text/markdown
 # ArchUnitPython - Architecture Testing
 
 <div align="center" name="top">
+  <img align="center" src="assets/logo-rounded.png" width="150" height="150" alt="ArchUnitPython Logo">
 
 <!-- spacer -->
 <p></p>
@@ -46,7 +47,7 @@ Description-Content-Type: text/markdown
 
 Enforce architecture rules in Python projects. Check for dependency directions, detect circular dependencies, enforce coding standards and much more. Integrates with pytest and any other testing framework. Very simple setup and pipeline integration. Zero runtime dependencies.
 
-_The Python port of [ArchUnitTS](https://github.com/LukasNiessen/ArchUnitTS). Inspired by the amazing ArchUnit library but we are not affiliated with ArchUnit._
+_Inspired by the amazing ArchUnit library but we are not affiliated with ArchUnit._
 
 [Setup](#-setup) • [Use Cases](#-use-cases) • [Features](#-features) • [Contributing](CONTRIBUTING.md)
 
@@ -188,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
 
@@ -636,6 +637,12 @@ ArchUnitPython started as the Python port of [ArchUnitTS](https://github.com/Luk
 
 - **[LukasNiessen](https://github.com/LukasNiessen)** - Creator and main maintainer
 
+### Contributors
+
+<a href="https://github.com/LukasNiessen/ArchUnitPython/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=LukasNiessen/ArchUnitPython&max=1000&contributors=10" />
+</a>
+
 ### Questions
 
 Found a bug? Want to discuss features?
@@ -645,9 +652,13 @@ Found a bug? Want to discuss features?
 
 If ArchUnitPython helps your project, please consider:
 
-- Starring the repository
-- Suggesting new features
-- Contributing code or documentation
+- Starring the repository 💚
+- Suggesting new features 💭
+- Contributing code or documentation ⌨️
+
+### Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=LukasNiessen/ArchUnitPython&type=Date)](https://www.star-history.com/#LukasNiessen/ArchUnitPython&Date)
 
 ## 📄 License
 

{archunitpython-1.0.0.dist-info → archunitpython-1.1.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-archunitpython/__init__.py,sha256=nJX8sByWi06egyQQX_V0V6IzI5o2o6lZBQcdGi0x7H4,926
+archunitpython/__init__.py,sha256=Y7boq0Xo0uyEXzfP30N_Jt1ij6Ofy8q8XzinC6E1crU,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.0.dist-info/METADATA,sha256=VIpbbLCai-p68Ki0P9pAPvSlL0tDWraN9wR09FnxrZo,19399
-archunitpython-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-archunitpython-1.0.0.dist-info/licenses/LICENSE,sha256=kaQWfzfHk45CNIx4sIW7Uf1sNW5rmo6BpZ-R8GruuK0,1102
-archunitpython-1.0.0.dist-info/RECORD,,
+archunitpython-1.1.0.dist-info/METADATA,sha256=Zx-869M7EX16qfaZJEhmRchJb31X9tB_TyGn7WWmZuk,19810
+archunitpython-1.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+archunitpython-1.1.0.dist-info/licenses/LICENSE,sha256=kaQWfzfHk45CNIx4sIW7Uf1sNW5rmo6BpZ-R8GruuK0,1102
+archunitpython-1.1.0.dist-info/RECORD,,