archunitpython 1.0.0__py3-none-any.whl

archunitpython/__init__.py

@@ -0,0 +1,45 @@
+"""ArchUnitPython - Architecture testing library for Python projects."""
+
+__version__ = "0.1.0"
+
+# Files API
+# Common
+from archunitpython.common import (
+    CheckOptions,
+    EmptyTestViolation,
+    TechnicalError,
+    UserError,
+    Violation,
+)
+from archunitpython.common.extraction import clear_graph_cache, extract_graph
+from archunitpython.files import files, project_files
+
+# Metrics API
+from archunitpython.metrics import metrics
+
+# Slices API
+from archunitpython.slices import project_slices
+
+# Testing
+from archunitpython.testing import assert_passes, format_violations
+
+__all__ = [
+    # Files
+    "project_files",
+    "files",
+    # Slices
+    "project_slices",
+    # Metrics
+    "metrics",
+    # Testing
+    "assert_passes",
+    "format_violations",
+    # Common
+    "Violation",
+    "EmptyTestViolation",
+    "CheckOptions",
+    "TechnicalError",
+    "UserError",
+    "extract_graph",
+    "clear_graph_cache",
+]

archunitpython/common/__init__.py

@@ -0,0 +1,18 @@
+from archunitpython.common.assertion.violation import EmptyTestViolation, Violation
+from archunitpython.common.error.errors import TechnicalError, UserError
+from archunitpython.common.fluentapi.checkable import Checkable, CheckOptions
+from archunitpython.common.logging.types import LoggingOptions
+from archunitpython.common.types import Filter, Pattern, PatternMatchingOptions
+
+__all__ = [
+    "Violation",
+    "EmptyTestViolation",
+    "TechnicalError",
+    "UserError",
+    "Checkable",
+    "CheckOptions",
+    "LoggingOptions",
+    "Pattern",
+    "Filter",
+    "PatternMatchingOptions",
+]

archunitpython/common/assertion/__init__.py

@@ -0,0 +1,3 @@
+from archunitpython.common.assertion.violation import EmptyTestViolation, Violation
+
+__all__ = ["Violation", "EmptyTestViolation"]

archunitpython/common/assertion/violation.py

@@ -0,0 +1,21 @@
+"""Base violation types for architecture rule checks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+class Violation:
+    """Base class for all architecture violations."""
+
+    pass
+
+
+@dataclass
+class EmptyTestViolation(Violation):
+    """Violation raised when no files match the specified filter patterns."""
+
+    filters: list[Any]
+    message: str
+    is_negated: bool = False

archunitpython/common/error/__init__.py

@@ -0,0 +1,3 @@
+from archunitpython.common.error.errors import TechnicalError, UserError
+
+__all__ = ["TechnicalError", "UserError"]

archunitpython/common/error/errors.py

@@ -0,0 +1,13 @@
+"""Error types for ArchUnitPython."""
+
+
+class TechnicalError(Exception):
+    """Error caused by technical issues (file system, configuration, etc.)."""
+
+    pass
+
+
+class UserError(Exception):
+    """Error caused by incorrect API usage."""
+
+    pass

archunitpython/common/extraction/__init__.py

@@ -0,0 +1,13 @@
+from archunitpython.common.extraction.extract_graph import (
+    clear_graph_cache,
+    extract_graph,
+)
+from archunitpython.common.extraction.graph import Edge, Graph, ImportKind
+
+__all__ = [
+    "Edge",
+    "Graph",
+    "ImportKind",
+    "extract_graph",
+    "clear_graph_cache",
+]

archunitpython/common/extraction/extract_graph.py

@@ -0,0 +1,345 @@
+"""Extract dependency graph from Python projects using AST analysis."""
+
+from __future__ import annotations
+
+import ast
+import os
+
+from archunitpython.common.extraction.graph import Edge, Graph, ImportKind
+from archunitpython.common.fluentapi.checkable import CheckOptions
+
+_graph_cache: dict[str, Graph] = {}
+
+_DEFAULT_EXCLUDE = [
+    "__pycache__",
+    ".venv",
+    "venv",
+    ".env",
+    "node_modules",
+    ".git",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    "dist",
+    "build",
+    "*.egg-info",
+]
+
+
+def clear_graph_cache(options: CheckOptions | None = None) -> None:
+    """Clear the cached dependency graphs."""
+    _graph_cache.clear()
+
+
+def extract_graph(
+    project_path: str | None = None,
+    *,
+    exclude_patterns: list[str] | None = None,
+    options: CheckOptions | None = None,
+) -> Graph:
+    """Extract a dependency graph from a Python project.
+
+    Scans all .py files in the project directory, parses their imports,
+    and resolves them to build a list of Edge objects.
+
+    Args:
+        project_path: Root directory of the project to analyze.
+            Defaults to current working directory.
+        exclude_patterns: Directory/file names to exclude.
+            Defaults to common non-source directories.
+        options: Check options (supports clear_cache).
+
+    Returns:
+        List of Edge objects representing import relationships.
+    """
+    if project_path is None:
+        project_path = os.getcwd()
+
+    project_path = os.path.abspath(project_path)
+    cache_key = project_path
+
+    if options and options.clear_cache:
+        _graph_cache.pop(cache_key, None)
+
+    if cache_key in _graph_cache:
+        return _graph_cache[cache_key]
+
+    result = _extract_graph_uncached(project_path, exclude_patterns)
+    _graph_cache[cache_key] = result
+    return result
+
+
+def _extract_graph_uncached(
+    project_path: str,
+    exclude_patterns: list[str] | None = None,
+) -> 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)
+
+    edges: list[Edge] = []
+    py_files_set = set(py_files)
+
+    for file_path in py_files:
+        # Add self-referencing edge (ensures the file appears as a node)
+        edges.append(
+            Edge(
+                source=_normalize(file_path),
+                target=_normalize(file_path),
+                external=False,
+            )
+        )
+
+        # Extract and resolve imports
+        imports = _extract_imports(file_path)
+        for module_name, import_kind in imports:
+            resolved, is_external = _resolve_import(
+                module_name, file_path, project_path, import_kind
+            )
+            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
+                }:
+                    is_external = True
+
+                edges.append(
+                    Edge(
+                        source=_normalize(file_path),
+                        target=resolved,
+                        external=is_external,
+                        import_kinds=(import_kind,),
+                    )
+                )
+
+    return _merge_edges(edges)
+
+
+def _normalize(path: str) -> str:
+    """Normalize a file path to use forward slashes."""
+    return path.replace("\\", "/")
+
+
+def _find_python_files(root: str, exclude: list[str]) -> list[str]:
+    """Recursively find all .py files, excluding specified patterns."""
+    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)
+        ]
+
+        for filename in filenames:
+            if filename.endswith(".py") and not _should_exclude(filename, exclude):
+                full_path = os.path.join(dirpath, filename)
+                py_files.append(os.path.abspath(full_path))
+
+    return py_files
+
+
+def _should_exclude(name: str, patterns: list[str]) -> bool:
+    """Check if a name matches any exclude pattern."""
+    import fnmatch
+
+    for pattern in patterns:
+        if fnmatch.fnmatch(name, pattern):
+            return True
+    return False
+
+
+def _extract_imports(file_path: str) -> list[tuple[str, ImportKind]]:
+    """Parse a Python file and extract all import statements.
+
+    Returns list of (module_name, import_kind) tuples.
+    """
+    try:
+        with open(file_path, "r", encoding="utf-8", errors="replace") as f:
+            source = f.read()
+    except (OSError, IOError):
+        return []
+
+    try:
+        tree = ast.parse(source, filename=file_path)
+    except SyntaxError:
+        return []
+
+    imports: list[tuple[str, ImportKind]] = []
+    type_checking_ranges = _find_type_checking_ranges(tree)
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            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))
+
+        elif isinstance(node, ast.ImportFrom):
+            is_type = _in_type_checking(node, type_checking_ranges)
+            if node.level and node.level > 0:
+                # Relative import
+                kind = ImportKind.TYPE_IMPORT if is_type else ImportKind.RELATIVE_IMPORT
+                module = node.module or ""
+                dots = "." * node.level
+                imports.append((f"{dots}{module}", kind))
+            else:
+                kind = ImportKind.TYPE_IMPORT if is_type else ImportKind.FROM_IMPORT
+                if node.module:
+                    imports.append((node.module, kind))
+
+    return imports
+
+
+def _find_type_checking_ranges(tree: ast.Module) -> list[tuple[int, int]]:
+    """Find line ranges of TYPE_CHECKING blocks."""
+    ranges: list[tuple[int, int]] = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.If):
+            # Check for `if TYPE_CHECKING:` pattern
+            test = node.test
+            is_type_checking = False
+
+            if isinstance(test, ast.Name) and test.id == "TYPE_CHECKING":
+                is_type_checking = True
+            elif isinstance(test, ast.Attribute) and test.attr == "TYPE_CHECKING":
+                is_type_checking = True
+
+            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")
+                )
+                ranges.append((start, end))
+
+    return ranges
+
+
+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
+    lineno = node.lineno
+    return any(start <= lineno <= end for start, end in ranges)
+
+
+def _resolve_import(
+    import_name: str,
+    source_file: str,
+    project_root: str,
+    kind: ImportKind,
+) -> tuple[str, bool]:
+    """Resolve an import name to an absolute file path.
+
+    Returns (resolved_path, is_external).
+    The path is normalized with forward slashes.
+    """
+    if kind in (ImportKind.RELATIVE_IMPORT, ImportKind.TYPE_IMPORT) and import_name.startswith("."):
+        # Relative import
+        return _resolve_relative_import(import_name, source_file, project_root)
+
+    # Absolute import: try to resolve within the project
+    return _resolve_absolute_import(import_name, project_root)
+
+
+def _resolve_relative_import(
+    import_name: str,
+    source_file: str,
+    project_root: str,
+) -> tuple[str, bool]:
+    """Resolve a relative import (starts with dots)."""
+    # Count dots
+    dots = 0
+    for ch in import_name:
+        if ch == ".":
+            dots += 1
+        else:
+            break
+
+    module_part = import_name[dots:]
+
+    # Navigate up from the source file's directory
+    source_dir = os.path.dirname(os.path.abspath(source_file))
+    for _ in range(dots - 1):  # -1 because first dot = current package
+        source_dir = os.path.dirname(source_dir)
+
+    if module_part:
+        parts = module_part.split(".")
+        candidate_base = os.path.join(source_dir, *parts)
+    else:
+        candidate_base = source_dir
+
+    # Try file.py first, then package/__init__.py
+    for candidate in [
+        candidate_base + ".py",
+        os.path.join(candidate_base, "__init__.py"),
+    ]:
+        if os.path.isfile(candidate):
+            return _normalize(os.path.abspath(candidate)), False
+
+    return _normalize(candidate_base + ".py"), True
+
+
+def _resolve_absolute_import(
+    import_name: str,
+    project_root: str,
+) -> tuple[str, bool]:
+    """Resolve an absolute import within the project."""
+    parts = import_name.split(".")
+
+    # Try resolving from the project root and also from parent directory
+    # (the parent handles the case where project_root is itself a package
+    # and imports use the package name as prefix)
+    search_roots = [project_root]
+    parent = os.path.dirname(project_root)
+    if parent and parent != project_root:
+        search_roots.append(parent)
+
+    for root in search_roots:
+        for i in range(len(parts), 0, -1):
+            path_parts = parts[:i]
+            candidate_base = os.path.join(root, *path_parts)
+
+            # Try as a module file
+            candidate_file = candidate_base + ".py"
+            if os.path.isfile(candidate_file):
+                resolved = _normalize(os.path.abspath(candidate_file))
+                # Only count as internal if it's inside the project root
+                is_internal = resolved.startswith(_normalize(os.path.abspath(project_root)))
+                return resolved, not is_internal
+
+            # Try as a package
+            candidate_init = os.path.join(candidate_base, "__init__.py")
+            if os.path.isfile(candidate_init):
+                resolved = _normalize(os.path.abspath(candidate_init))
+                is_internal = resolved.startswith(_normalize(os.path.abspath(project_root)))
+                return resolved, not is_internal
+
+    # Not found in project → external
+    return import_name, True
+
+
+def _merge_edges(edges: list[Edge]) -> list[Edge]:
+    """Merge edges with same source and target, combining import kinds."""
+    edge_map: dict[tuple[str, str], Edge] = {}
+
+    for edge in edges:
+        key = (edge.source, edge.target)
+        if key in edge_map:
+            existing = edge_map[key]
+            combined_kinds = set(existing.import_kinds) | set(edge.import_kinds)
+            edge_map[key] = Edge(
+                source=edge.source,
+                target=edge.target,
+                external=edge.external,
+                import_kinds=tuple(sorted(combined_kinds, key=lambda k: k.value)),
+            )
+        else:
+            edge_map[key] = edge
+
+    return list(edge_map.values())

archunitpython/common/extraction/graph.py

@@ -0,0 +1,39 @@
+"""Graph model for dependency analysis."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class ImportKind(Enum):
+    """Types of Python import statements."""
+
+    IMPORT = "import"  # import foo
+    FROM_IMPORT = "from_import"  # from foo import bar
+    RELATIVE_IMPORT = "relative"  # from . import bar / from ..foo import bar
+    DYNAMIC_IMPORT = "dynamic"  # __import__('foo') / importlib.import_module()
+    TYPE_IMPORT = "type"  # inside TYPE_CHECKING block
+
+
+@dataclass(frozen=True)
+class Edge:
+    """A dependency edge between two files.
+
+    Represents an import relationship: source imports target.
+    """
+
+    source: str
+    """Absolute path of the importing file."""
+
+    target: str
+    """Absolute path of the imported file (or module name if external)."""
+
+    external: bool
+    """True if the target is an external dependency (not part of the project)."""
+
+    import_kinds: tuple[ImportKind, ...] = ()
+    """The types of import statements creating this edge."""
+
+
+Graph = list[Edge]

archunitpython/common/fluentapi/__init__.py

@@ -0,0 +1,3 @@
+from archunitpython.common.fluentapi.checkable import Checkable, CheckOptions
+
+__all__ = ["Checkable", "CheckOptions"]

archunitpython/common/fluentapi/checkable.py

@@ -0,0 +1,28 @@
+"""Checkable protocol and CheckOptions for architecture rule execution."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from archunitpython.common.assertion.violation import Violation
+from archunitpython.common.logging.types import LoggingOptions
+
+
+@dataclass(frozen=True)
+class CheckOptions:
+    """Options for controlling rule check execution."""
+
+    allow_empty_tests: bool = False
+    logging: LoggingOptions | None = None
+    clear_cache: bool = False
+
+
+class Checkable(Protocol):
+    """Protocol for any architecture rule that can be checked.
+
+    All fluent API chains ultimately produce a Checkable whose check()
+    method executes the rule and returns a list of violations (empty = pass).
+    """
+
+    def check(self, options: CheckOptions | None = None) -> list[Violation]: ...

archunitpython/common/logging/__init__.py

@@ -0,0 +1,3 @@
+from archunitpython.common.logging.types import LoggingOptions, LogLevel
+
+__all__ = ["LoggingOptions", "LogLevel"]

archunitpython/common/logging/types.py

@@ -0,0 +1,18 @@
+"""Logging configuration types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+LogLevel = Literal["debug", "info", "warn", "error"]
+
+
+@dataclass(frozen=True)
+class LoggingOptions:
+    """Options for controlling logging during architecture checks."""
+
+    enabled: bool = False
+    level: LogLevel = "info"
+    log_file: bool = False
+    append_to_log_file: bool = False

archunitpython/common/pattern_matching.py

@@ -0,0 +1,80 @@
+"""Pattern matching functions for file paths and class names."""
+
+from __future__ import annotations
+
+from archunitpython.common.types import Filter
+
+
+def normalize_path(path: str) -> str:
+    """Normalize a file path by converting backslashes to forward slashes."""
+    return path.replace("\\", "/")
+
+
+def extract_filename(file_path: str) -> str:
+    """Extract the filename from a file path."""
+    normalized = normalize_path(file_path)
+    parts = normalized.split("/")
+    return parts[-1] if parts else file_path
+
+
+def path_without_filename(file_path: str) -> str:
+    """Extract the directory portion of a file path (without the filename)."""
+    normalized = normalize_path(file_path)
+    parts = normalized.split("/")
+    if len(parts) > 1:
+        parts.pop()
+        return "/".join(parts)
+    return ""
+
+
+def matches_pattern(file_path: str, filter_: Filter) -> bool:
+    """Check if a file path matches a single filter.
+
+    The filter's target option determines which part of the path is tested:
+    - 'filename': only the filename
+    - 'path': the full normalized path
+    - 'path-no-filename': the directory portion only
+    - 'classname': not applicable for file paths (always uses full path)
+    """
+    target = filter_.options.target
+
+    if target == "filename":
+        target_string = extract_filename(file_path)
+    elif target == "path":
+        target_string = normalize_path(file_path)
+    elif target == "path-no-filename":
+        target_string = path_without_filename(file_path)
+    else:
+        target_string = normalize_path(file_path)
+
+    return bool(filter_.regexp.search(target_string))
+
+
+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
+
+    if target == "classname":
+        target_string = class_name
+    elif target == "filename":
+        target_string = extract_filename(file_path)
+    elif target == "path":
+        target_string = normalize_path(file_path)
+    elif target == "path-no-filename":
+        target_string = path_without_filename(file_path)
+    else:
+        target_string = normalize_path(file_path)
+
+    return bool(filter_.regexp.search(target_string))
+
+
+def matches_all_patterns(file_path: str, filters: list[Filter]) -> bool:
+    """Check if a file path matches ALL filters (AND logic)."""
+    return all(matches_pattern(file_path, f) for f in filters)
+
+
+def matches_any_pattern(file_path: str, filters: list[Filter]) -> bool:
+    """Check if a file path matches ANY filter (OR logic)."""
+    return any(matches_pattern(file_path, f) for f in filters)

archunitpython/common/projection/__init__.py

@@ -0,0 +1,30 @@
+from archunitpython.common.projection.edge_projections import per_edge, per_internal_edge
+from archunitpython.common.projection.project_cycles import (
+    ProjectedCycles,
+    project_cycles,
+    project_internal_cycles,
+)
+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 (
+    MapFunction,
+    MappedEdge,
+    ProjectedEdge,
+    ProjectedGraph,
+    ProjectedNode,
+)
+
+__all__ = [
+    "MapFunction",
+    "MappedEdge",
+    "ProjectedCycles",
+    "ProjectedEdge",
+    "ProjectedGraph",
+    "ProjectedNode",
+    "per_edge",
+    "per_internal_edge",
+    "project_cycles",
+    "project_edges",
+    "project_internal_cycles",
+    "project_to_nodes",
+]

archunitpython/common/projection/cycles/__init__.py

@@ -0,0 +1,4 @@
+from archunitpython.common.projection.cycles.cycles import calculate_cycles
+from archunitpython.common.projection.cycles.model import NumberEdge, NumberNode
+
+__all__ = ["NumberEdge", "NumberNode", "calculate_cycles"]