archunitpython 1.1.2__py3-none-any.whl → 1.2.1__py3-none-any.whl

archunitpython/__init__.py

@@ -1,6 +1,6 @@
 """ArchUnitPython - Architecture testing library for Python projects."""
 
-__version__ = "1.1.2"
+__version__ = "1.2.1"
 
 # Files API
 # Common
@@ -13,6 +13,8 @@ from archunitpython.common import (
 )
 from archunitpython.common.extraction import clear_graph_cache, extract_graph
 from archunitpython.files import files, project_files
+from archunitpython.graph import dependency_graph, project_graph
+from archunitpython.layers import layers, project_layers
 
 # Metrics API
 from archunitpython.metrics import metrics
@@ -27,6 +29,12 @@ __all__ = [
     # Files
     "project_files",
     "files",
+    # Graph
+    "project_graph",
+    "dependency_graph",
+    # Layers
+    "project_layers",
+    "layers",
     # Slices
     "project_slices",
     # Metrics

archunitpython/common/extraction/extract_graph.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 import ast
 import os
+import re
+from dataclasses import dataclass
 
 from archunitpython.common.extraction.graph import Edge, Graph, ImportKind
 from archunitpython.common.fluentapi.checkable import CheckOptions
@@ -27,6 +29,34 @@ _DEFAULT_EXCLUDE = [
     "*.egg-info",
 ]
 
+_IGNORE_DIRECTIVE_REGEX = re.compile(
+    r"#\s*archunit(?::|-)\s*ignore"
+    r"(?:\([^)]*\))?"
+    r"(?P<modules>(?:\s+[\w.]+)*)\s*$"
+)
+
+
+@dataclass(frozen=True)
+class _LocatedImport:
+    module_name: str
+    import_kind: ImportKind
+    line_number: int
+
+
+@dataclass(frozen=True)
+class _IgnoreDirective:
+    line_number: int
+    modules: tuple[str, ...] = ()
+
+    def matches(self, import_: _LocatedImport) -> bool:
+        if not self.modules:
+            return True
+        return any(
+            import_.module_name == module
+            or import_.module_name.startswith(f"{module}.")
+            for module in self.modules
+        )
+
 
 def clear_graph_cache(options: CheckOptions | None = None) -> None:
     """Clear the cached dependency graphs."""
@@ -61,12 +91,8 @@ def extract_graph(
     excludes = (
         list(set(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
-    )
+    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)
@@ -107,6 +133,7 @@ def _extract_graph_uncached(
 
     edges: list[Edge] = []
     py_files_set = set(py_files)
+    normalized_py_file_set = {_normalize(f) for f in py_files_set}
 
     for file_path in py_files:
         # Add self-referencing edge (ensures the file appears as a node)
@@ -118,9 +145,10 @@ def _extract_graph_uncached(
             )
         )
 
-        # Extract and resolve imports
-        imports = _extract_imports(file_path)
-        for module_name, import_kind in imports:
+        imports = _extract_located_imports(file_path)
+        for located_import in imports:
+            module_name = located_import.module_name
+            import_kind = located_import.import_kind
             if (
                 ignore_type_checking_imports
                 and import_kind == ImportKind.TYPE_IMPORT
@@ -131,9 +159,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 {
-                    _normalize(f) for f in py_files_set
-                }:
+                if not is_external and resolved not in normalized_py_file_set:
                     is_external = True
 
                 edges.append(
@@ -158,11 +184,7 @@ def _find_python_files(root: str, exclude: list[str]) -> list[str]:
     py_files: list[str] = []
     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(d, exclude)]
 
         for filename in filenames:
             if filename.endswith(".py") and not _should_exclude(filename, exclude):
@@ -187,6 +209,14 @@ def _extract_imports(file_path: str) -> list[tuple[str, ImportKind]]:
 
     Returns list of (module_name, import_kind) tuples.
     """
+    return [
+        (import_.module_name, import_.import_kind)
+        for import_ in _extract_located_imports(file_path)
+    ]
+
+
+def _extract_located_imports(file_path: str) -> list[_LocatedImport]:
+    """Parse a Python file and extract imports with line numbers."""
     try:
         with open(file_path, "r", encoding="utf-8", errors="replace") as f:
             source = f.read()
@@ -198,7 +228,8 @@ def _extract_imports(file_path: str) -> list[tuple[str, ImportKind]]:
     except SyntaxError:
         return []
 
-    imports: list[tuple[str, ImportKind]] = []
+    imports: list[_LocatedImport] = []
+    ignore_directives = _find_ignore_directives(source)
     type_checking_ranges = _find_type_checking_ranges(tree)
 
     for node in ast.walk(tree):
@@ -206,7 +237,7 @@ def _extract_imports(file_path: str) -> list[tuple[str, ImportKind]]:
             is_type = _in_type_checking(node, type_checking_ranges)
             kind = ImportKind.TYPE_IMPORT if is_type else ImportKind.IMPORT
             for alias in node.names:
-                imports.append((alias.name, kind))
+                imports.append(_LocatedImport(alias.name, kind, node.lineno))
 
         elif isinstance(node, ast.ImportFrom):
             is_type = _in_type_checking(node, type_checking_ranges)
@@ -215,13 +246,79 @@ def _extract_imports(file_path: str) -> list[tuple[str, ImportKind]]:
                 kind = ImportKind.TYPE_IMPORT if is_type else ImportKind.RELATIVE_IMPORT
                 module = node.module or ""
                 dots = "." * node.level
-                imports.append((f"{dots}{module}", kind))
+                imports.append(_LocatedImport(f"{dots}{module}", kind, node.lineno))
             else:
                 kind = ImportKind.TYPE_IMPORT if is_type else ImportKind.FROM_IMPORT
                 if node.module:
-                    imports.append((node.module, kind))
+                    imports.append(_LocatedImport(node.module, kind, node.lineno))
+
+        elif isinstance(node, ast.Call):
+            is_type = _in_type_checking(node, type_checking_ranges)
+            kind = ImportKind.TYPE_IMPORT if is_type else ImportKind.DYNAMIC_IMPORT
+            for module_name in _extract_dynamic_import_names(node):
+                imports.append(_LocatedImport(module_name, kind, node.lineno))
+
+    return [
+        import_
+        for import_ in imports
+        if not _is_ignored_import(import_, ignore_directives)
+    ]
+
 
-    return imports
+def _find_ignore_directives(source: str) -> dict[int, _IgnoreDirective]:
+    """Find architecture-ignore directives.
+
+    Supports inline directives on an import line and standalone directives that
+    apply to the following line, for example:
+
+    - from x import y  # archunit: ignore
+    - # archunit: ignore
+      from x import y
+    """
+    directives: dict[int, _IgnoreDirective] = {}
+    for index, line in enumerate(source.splitlines(), start=1):
+        match = _IGNORE_DIRECTIVE_REGEX.search(line)
+        if match is None:
+            continue
+
+        modules = tuple(match.group("modules").split())
+        target_line = index + 1 if line.strip().startswith("#") else index
+        directives[target_line] = _IgnoreDirective(target_line, modules)
+    return directives
+
+
+def _is_ignored_import(
+    import_: _LocatedImport,
+    directives: dict[int, _IgnoreDirective],
+) -> bool:
+    directive = directives.get(import_.line_number)
+    return directive is not None and directive.matches(import_)
+
+
+def _extract_dynamic_import_names(node: ast.Call) -> list[str]:
+    """Extract literal module names from common dynamic import calls."""
+    if not node.args:
+        return []
+
+    first_arg = node.args[0]
+    if not isinstance(first_arg, ast.Constant) or not isinstance(first_arg.value, str):
+        return []
+
+    if isinstance(node.func, ast.Name) and node.func.id in {
+        "__import__",
+        "import_module",
+    }:
+        return [first_arg.value]
+
+    if (
+        isinstance(node.func, ast.Attribute)
+        and node.func.attr == "import_module"
+        and isinstance(node.func.value, ast.Name)
+        and node.func.value.id == "importlib"
+    ):
+        return [first_arg.value]
+
+    return []
 
 
 def _find_type_checking_ranges(tree: ast.Module) -> list[tuple[int, int]]:
@@ -242,18 +339,14 @@ def _find_type_checking_ranges(tree: ast.Module) -> list[tuple[int, int]]:
             if is_type_checking and node.body:
                 start = node.body[0].lineno
                 end = max(
-                    getattr(n, "end_lineno", n.lineno)
-                    for n in node.body
-                    if hasattr(n, "lineno")
+                    getattr(n, "end_lineno", n.lineno) for n in node.body if hasattr(n, "lineno")
                 )
                 ranges.append((start, end))
 
-    return ranges
+    return sorted(ranges, key=lambda ele: ele[0])
 
 
-def _in_type_checking(
-    node: ast.AST, ranges: list[tuple[int, int]]
-) -> bool:
+def _in_type_checking(node: ast.AST, ranges: list[tuple[int, int]]) -> bool:
     """Check if a node is inside a TYPE_CHECKING block."""
     if not hasattr(node, "lineno"):
         return False

archunitpython/common/pattern_matching.py

@@ -50,9 +50,7 @@ def matches_pattern(file_path: str, filter_: Filter) -> bool:
     return bool(filter_.regexp.search(target_string))
 
 
-def matches_pattern_classname(
-    class_name: str, file_path: str, filter_: Filter
-) -> bool:
+def matches_pattern_classname(class_name: str, file_path: str, filter_: Filter) -> bool:
     """Check if a class/file matches a filter, supporting classname target."""
     target = filter_.options.target
 

archunitpython/common/projection/cycles/johnsons_apsp.py

@@ -53,13 +53,9 @@ class JohnsonsAPSP:
         if self._is_part_of_current_start_cycle(current_node):
             self._unblock(current_node)
         else:
-            for neighbour in CycleUtils.get_outgoing_neighbours(
-                current_node, self._graph
-            ):
+            for neighbour in CycleUtils.get_outgoing_neighbours(current_node, self._graph):
                 if self._is_blocked(neighbour):
-                    self._blocked_map.append(
-                        _BlockedBy(blocked=current_node, by=neighbour)
-                    )
+                    self._blocked_map.append(_BlockedBy(blocked=current_node, by=neighbour))
 
     def _unblock(self, node: NumberNode) -> None:
         self._blocked = [n for n in self._blocked if n is not node]
@@ -74,9 +70,8 @@ class JohnsonsAPSP:
         if self._start is None:
             return False
         for cycle in self._cycles:
-            if (
-                cycle[0].from_node == self._start.node
-                and any(e.from_node == current_node.node for e in cycle)
+            if cycle[0].from_node == self._start.node and any(
+                e.from_node == current_node.node for e in cycle
             ):
                 return True
         return False

archunitpython/common/projection/cycles/tarjan_scc.py

@@ -18,9 +18,7 @@ class _Vertex:
 class TarjanSCC:
     """Tarjan's algorithm for finding strongly connected components."""
 
-    def find_strongly_connected_components(
-        self, edges: list[NumberEdge]
-    ) -> list[list[NumberEdge]]:
+    def find_strongly_connected_components(self, edges: list[NumberEdge]) -> list[list[NumberEdge]]:
         """Find all strongly connected components in the graph.
 
         Returns a list of edge lists, where each inner list contains
@@ -78,9 +76,7 @@ class TarjanSCC:
             if scc_vertices:
                 scc_ids = {v.id for v in scc_vertices}
                 scc_edges = [
-                    e
-                    for e in self._edges
-                    if e.from_node in scc_ids and e.to_node in scc_ids
+                    e for e in self._edges if e.from_node in scc_ids and e.to_node in scc_ids
                 ]
                 if scc_edges:
                     self._sccs.append(scc_edges)

archunitpython/common/projection/project_cycles.py

@@ -72,8 +72,7 @@ class _CycleProcessor:
                     (
                         se
                         for se in self._source_edges
-                        if se.source_label == source_label
-                        and se.target_label == target_label
+                        if se.source_label == source_label and se.target_label == target_label
                     ),
                     None,
                 )

archunitpython/common/util/logger.py

@@ -44,9 +44,7 @@ class CheckLogger:
 
         mode = "a" if options.append_to_log_file else "w"
         self._file_handler = logging.FileHandler(str(log_path), mode=mode)
-        self._file_handler.setFormatter(
-            logging.Formatter("[%(levelname)s] %(message)s")
-        )
+        self._file_handler.setFormatter(logging.Formatter("[%(levelname)s] %(message)s"))
         self._logger.addHandler(self._file_handler)
 
     def _log(self, level: str, options: LoggingOptions | None, message: str) -> None:

archunitpython/files/assertion/custom_file_logic.py

@@ -83,9 +83,7 @@ def gather_custom_file_violations(
 
     for node in nodes:
         # Check if node matches all pre-filters
-        if pre_filters and not all(
-            matches_pattern(node.label, f) for f in pre_filters
-        ):
+        if pre_filters and not all(matches_pattern(node.label, f) for f in pre_filters):
             continue
 
         file_info = _build_file_info(node.label)
@@ -94,14 +92,10 @@ def gather_custom_file_violations(
         if is_negated:
             # shouldNot: violation if condition IS True
             if result:
-                violations.append(
-                    CustomFileViolation(message=message, file_info=file_info)
-                )
+                violations.append(CustomFileViolation(message=message, file_info=file_info))
         else:
             # should: violation if condition is NOT True
             if not result:
-                violations.append(
-                    CustomFileViolation(message=message, file_info=file_info)
-                )
+                violations.append(CustomFileViolation(message=message, file_info=file_info))
 
     return violations

archunitpython/files/assertion/depend_on_external_modules.py

@@ -34,8 +34,7 @@ def gather_depend_on_external_module_violations(
 
     for edge in edges:
         source_matches = all(
-            matches_pattern(edge.source_label, filter_)
-            for filter_ in subject_filters
+            matches_pattern(edge.source_label, filter_) for filter_ in subject_filters
         )
         if not source_matches:
             continue
@@ -49,16 +48,12 @@ def gather_depend_on_external_module_violations(
         if is_negated:
             if target_matches:
                 violations.append(
-                    ViolatingExternalModuleDependency(
-                        dependency=edge, is_negated=True
-                    )
+                    ViolatingExternalModuleDependency(dependency=edge, is_negated=True)
                 )
         else:
             if not target_matches:
                 violations.append(
-                    ViolatingExternalModuleDependency(
-                        dependency=edge, is_negated=False
-                    )
+                    ViolatingExternalModuleDependency(dependency=edge, is_negated=False)
                 )
 
     return violations

archunitpython/files/assertion/depend_on_files.py

@@ -41,27 +41,19 @@ def gather_depend_on_file_violations(
     violations: list[Violation] = []
 
     for edge in edges:
-        source_matches = all(
-            matches_pattern(edge.source_label, f) for f in subject_filters
-        )
+        source_matches = all(matches_pattern(edge.source_label, f) for f in subject_filters)
         if not source_matches:
             continue
 
-        target_matches = all(
-            matches_pattern(edge.target_label, f) for f in object_filters
-        )
+        target_matches = all(matches_pattern(edge.target_label, f) for f in object_filters)
 
         if is_negated:
             # shouldNot: violation if dependency EXISTS
             if target_matches:
-                violations.append(
-                    ViolatingFileDependency(dependency=edge, is_negated=True)
-                )
+                violations.append(ViolatingFileDependency(dependency=edge, is_negated=True))
         else:
             # should: violation if dependency does NOT match
             if not target_matches:
-                violations.append(
-                    ViolatingFileDependency(dependency=edge, is_negated=False)
-                )
+                violations.append(ViolatingFileDependency(dependency=edge, is_negated=False))
 
     return violations

archunitpython/files/fluentapi/files.py

@@ -76,15 +76,11 @@ class FileConditionBuilder:
 
     def should(self) -> "PositiveMatchPatternFileConditionBuilder":
         """Begin positive assertion (files SHOULD ...)."""
-        return PositiveMatchPatternFileConditionBuilder(
-            self._project_path, list(self._filters)
-        )
+        return PositiveMatchPatternFileConditionBuilder(self._project_path, list(self._filters))
 
     def should_not(self) -> "NegatedMatchPatternFileConditionBuilder":
         """Begin negative assertion (files SHOULD NOT ...)."""
-        return NegatedMatchPatternFileConditionBuilder(
-            self._project_path, list(self._filters)
-        )
+        return NegatedMatchPatternFileConditionBuilder(self._project_path, list(self._filters))
 
 
 class FilesShouldCondition:
@@ -111,15 +107,11 @@ class FilesShouldCondition:
 
     def should(self) -> "PositiveMatchPatternFileConditionBuilder":
         """Begin positive assertion (files SHOULD ...)."""
-        return PositiveMatchPatternFileConditionBuilder(
-            self._project_path, list(self._filters)
-        )
+        return PositiveMatchPatternFileConditionBuilder(self._project_path, list(self._filters))
 
     def should_not(self) -> "NegatedMatchPatternFileConditionBuilder":
         """Begin negative assertion (files SHOULD NOT ...)."""
-        return NegatedMatchPatternFileConditionBuilder(
-            self._project_path, list(self._filters)
-        )
+        return NegatedMatchPatternFileConditionBuilder(self._project_path, list(self._filters))
 
 
 class PositiveMatchPatternFileConditionBuilder:
@@ -135,9 +127,7 @@ class PositiveMatchPatternFileConditionBuilder:
 
     def depend_on_files(self) -> "DependOnFileConditionBuilder":
         """Begin dependency assertion - files SHOULD depend on ..."""
-        return DependOnFileConditionBuilder(
-            self._project_path, self._filters, is_negated=False
-        )
+        return DependOnFileConditionBuilder(self._project_path, self._filters, is_negated=False)
 
     def depend_on_external_modules(
         self,
@@ -192,9 +182,7 @@ class NegatedMatchPatternFileConditionBuilder:
 
     def depend_on_files(self) -> "DependOnFileConditionBuilder":
         """Begin dependency assertion - files SHOULD NOT depend on ..."""
-        return DependOnFileConditionBuilder(
-            self._project_path, self._filters, is_negated=True
-        )
+        return DependOnFileConditionBuilder(self._project_path, self._filters, is_negated=True)
 
     def depend_on_external_modules(
         self,
@@ -243,9 +231,7 @@ class NegatedMatchPatternFileConditionBuilder:
 class DependOnFileConditionBuilder:
     """Configure dependency target patterns."""
 
-    def __init__(
-        self, project_path: str | None, filters: list[Filter], is_negated: bool
-    ) -> None:
+    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
@@ -285,9 +271,7 @@ class DependOnFileConditionBuilder:
 class DependOnExternalModuleConditionBuilder:
     """Configure external module dependency target patterns."""
 
-    def __init__(
-        self, project_path: str | None, filters: list[Filter], is_negated: bool
-    ) -> None:
+    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
@@ -447,9 +431,7 @@ class MatchPatternFileCondition:
         if empty is not None:
             return empty
 
-        return gather_regex_matching_violations(
-            nodes, self._check_filters, self._is_negated
-        )
+        return gather_regex_matching_violations(nodes, self._check_filters, self._is_negated)
 
 
 class CustomFileCheckableCondition:

archunitpython/graph/__init__.py

@@ -0,0 +1,35 @@
+"""Dependency graph reports."""
+
+from archunitpython.graph.graph_reporter import (
+    DEFAULT_TITLE,
+    FolderDepthCollapse,
+    GraphCollapseStrategy,
+    GraphQueryOptions,
+    GraphReportEdge,
+    GraphReporter,
+    GraphReportFormat,
+    GraphReportNode,
+    GraphReportSnapshot,
+    GraphReportSummary,
+    PatternCollapse,
+    ProjectGraphBuilder,
+    dependency_graph,
+    project_graph,
+)
+
+__all__ = [
+    "DEFAULT_TITLE",
+    "FolderDepthCollapse",
+    "GraphCollapseStrategy",
+    "GraphQueryOptions",
+    "GraphReportEdge",
+    "GraphReportFormat",
+    "GraphReportNode",
+    "GraphReportSnapshot",
+    "GraphReportSummary",
+    "GraphReporter",
+    "PatternCollapse",
+    "ProjectGraphBuilder",
+    "dependency_graph",
+    "project_graph",
+]