Detect Circular Imports Across Python Projects Automatically

import ast
import sys
from pathlib import Path
from collections import defaultdict, deque

def find_imports(filepath):
    """Return set of module names imported by a Python file."""
    imports = set()
    try:
        with open(filepath) as f:
            tree = ast.parse(f.read())
    except (SyntaxError, UnicodeDecodeError):
        return imports
    for node in ast.walk(tree):
        if isinstance(node, ast.Import):
            for alias in node.names:
                imports.add(alias.name.split('.')[0])
        elif isinstance(node, ast.ImportFrom):
            if node.module:
                imports.add(node.module.split('.')[0])
    return imports

def detect_circular_imports(root_dir):
    """Detect circular imports in all .py files under root_dir."""
    root = Path(root_dir)
    files = list(root.rglob("*.py"))
    module_graph = defaultdict(set)
    for f in files:
        module_name = f.stem
        for imp in find_imports(f):
            module_graph[module_name].add(imp)
    visited = set()
    stack = set()
    cycles = []
    def dfs(node, path):
        visited.add(node)
        stack.add(node)
        for neighbor in module_graph.get(node, set()):
            if neighbor not in visited:
                if dfs(neighbor, path + [neighbor]):
                    return True
            elif neighbor in stack:
                cycle = path[path.index(neighbor):]
                cycles.append(cycle + [neighbor])
                return True
        stack.discard(node)
        return False
    for module in list(module_graph.keys()):
        if module not in visited:
            dfs(module, [module])
    return cycles

if __name__ == "__main__":
    if len(sys.argv) > 1:
        root_path = sys.argv[1]
    else:
        root_path = "."  # default current directory
    cycles = detect_circular_imports(root_path)
    if cycles:
        for cycle in cycles:
            print(" -> ".join(cycle))
    else:
        print("No circular imports detected.")