archunitpython 1.1.2__py3-none-any.whl → 1.2.0__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.0"
 
 # 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."""
@@ -119,8 +149,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
@@ -187,6 +219,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 +238,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 +247,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 +256,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)
+    ]
+
+
+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 []
 
-    return imports
+    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]]:

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",
+]