depcycle 0.2.0__py3-none-any.whl

depcycle/__init__.py

@@ -0,0 +1,28 @@
+"""
+DepCycle - A dependency graph visualization tool for Python projects.
+
+DepCycle helps developers understand complex codebases by automatically 
+generating visual maps of module dependencies.
+"""
+
+__version__ = "0.2.0"
+
+from .cli import DepCycleCLI
+from .config import Config
+from .graph import DependencyGraph, ModuleNode, ModuleType
+from .parsing import Project, ASTParser
+from .rendering import IGraphVisualizer, GraphvizVisualizer, HtmlVisualizer
+
+__all__ = [
+    'DepCycleCLI',
+    'Config',
+    'DependencyGraph',
+    'ModuleNode',
+    'ModuleType',
+    'Project',
+    'ASTParser',
+    'IGraphVisualizer',
+    'GraphvizVisualizer',
+    'HtmlVisualizer',
+]
+

depcycle/__main__.py

@@ -0,0 +1,7 @@
+"""Entry point for running depcycle as a module: python -m depcycle"""
+
+from .cli import DepCycleCLI
+
+if __name__ == '__main__':
+    DepCycleCLI.main()
+

depcycle/cli.py

@@ -0,0 +1,213 @@
+"""
+this module contains the command-line interface logic for DepCycle.
+it defines the user-facing commands, parses arguments, and orchestrates
+the dependency analysis and visualization workflow.
+"""
+
+from pathlib import Path
+import argparse
+import sys
+
+from .config import Config
+from .parsing.project import Project
+from .parsing.ast_parser import ASTParser
+from .graph.dependency_graph import DependencyGraph
+from .rendering.interface import IGraphVisualizer
+from .rendering.visualizers import GraphvizVisualizer, HtmlVisualizer
+
+
+class DepCycleCLI:
+    """
+    The Conductor: Parses arguments and orchestrates the workflow.
+    
+    This class handles all command-line interaction, from parsing user
+    arguments to coordinating the analysis and visualization pipeline.
+    """
+    
+    @staticmethod
+    def main(args: list = None):
+        """
+        Main entry point for the DepCycle CLI.
+        
+        Parses command-line arguments, creates configuration, and runs
+        the dependency analysis workflow.
+        
+        Args:
+            args: Command-line arguments (defaults to sys.argv).
+        """
+        if args is None:
+            args = sys.argv[1:]
+        
+        # Parse arguments
+        parser = DepCycleCLI._create_parser()
+        parsed_args = parser.parse_args(args)
+        
+        # Validate arguments
+        if not parsed_args.project_path:
+            parser.error("Project path is required")
+        
+        # Build configuration
+        config = Config(
+            project_path=Path(parsed_args.project_path),
+            output_file=Path(parsed_args.output) if parsed_args.output else Path("dependencies.png"),
+            output_format=parsed_args.format,
+            exclude_patterns=parsed_args.exclude,
+            show_third_party=not parsed_args.no_third_party,
+            show_stdlib=not parsed_args.no_stdlib,
+            include_all=parsed_args.include_all
+        )
+        
+        # Validate project path
+        if not config.project_path.exists():
+            print(f"Error: Project path does not exist: {config.project_path}")
+            sys.exit(1)
+        
+        # Run the analysis
+        try:
+            DepCycleCLI.run(config)
+        except KeyboardInterrupt:
+            print("\nInterrupted by user")
+            sys.exit(1)
+        except Exception as e:
+            print(f"Error: {e}", file=sys.stderr)
+            sys.exit(1)
+    
+    @staticmethod
+    def run(config: Config):
+        """
+        Execute the dependency analysis and visualization workflow.
+        
+        This method orchestrates the entire process:
+        1. Discover Python files in the project
+        2. Parse imports using AST
+        3. Build the dependency graph
+        4. Render the visualization
+        
+        Args:
+            config: Configuration object containing all settings.
+        """
+        print(f"Analyzing project: {config.project_path}")
+        
+        # Step 1: Discover files
+        project = Project(config.project_path)
+        parser = ASTParser()
+        
+        # Step 2 & 3: Build graph
+        print("Building dependency graph...")
+        graph = DependencyGraph()
+        graph.build(project, parser, config)
+        
+        print(f"Found {len(graph)} modules")
+        
+        # Step 4: Detect cycles
+        cycles = graph.find_cycles()
+        if cycles:
+            print(f"\n⚠️  Warning: Found {len(cycles)} circular dependency cycles!")
+            for i, cycle in enumerate(cycles[:5], 1):  # Show first 5
+                cycle_names = [node.name for node in cycle]
+                print(f"  Cycle {i}: {' → '.join(cycle_names)}")
+            if len(cycles) > 5:
+                print(f"  ... and {len(cycles) - 5} more cycles")
+        else:
+            print("✓ No circular dependencies detected")
+        
+        # Step 5: Render visualization
+        print(f"\nGenerating {config.output_format.upper()} visualization...")
+        visualizer = DepCycleCLI._create_visualizer(config.output_format)
+        visualizer.render(graph, config)
+        
+        print(f"✓ Visualization saved to: {config.output_file}")
+    
+    @staticmethod
+    def _create_parser() -> argparse.ArgumentParser:
+        """
+        Create and configure the argument parser.
+        
+        Returns:
+            Configured ArgumentParser instance.
+        """
+        parser = argparse.ArgumentParser(
+            prog='depcycle',
+            description='Visualize Python project dependencies',
+            formatter_class=argparse.RawDescriptionHelpFormatter,
+            epilog="""
+Examples:
+  %(prog)s /path/to/project
+  %(prog)s /path/to/project -o output.png
+  %(prog)s /path/to/project --format svg --exclude tests
+  %(prog)s /path/to/project --no-third-party --no-stdlib
+  %(prog)s /path/to/project --include-all  # Include venv, __pycache__, etc.
+            """
+        )
+        
+        parser.add_argument(
+            'project_path',
+            nargs='?',
+            help='Path to the Python project to analyze'
+        )
+        
+        parser.add_argument(
+            '-o', '--output',
+            help='Output file path (default: dependencies.png)',
+            default=None
+        )
+        
+        parser.add_argument(
+            '-f', '--format',
+            choices=['png', 'svg', 'html'],
+            help='Output format (default: png)',
+            default='png'
+        )
+        
+        parser.add_argument(
+            '-e', '--exclude',
+            action='append',
+            help='Glob patterns to exclude (e.g., venv, tests/*.py). Can be specified multiple times.',
+            default=[]
+        )
+        
+        parser.add_argument(
+            '--no-third-party',
+            action='store_true',
+            help='Exclude third-party dependencies from the graph'
+        )
+        
+        parser.add_argument(
+            '--no-stdlib',
+            action='store_true',
+            help='Exclude standard library modules from the graph'
+        )
+        
+        parser.add_argument(
+            '--include-all',
+            action='store_true',
+            help='Include files normally excluded by default (venv, __pycache__, etc.)'
+        )
+        
+        return parser
+    
+    @staticmethod
+    def _create_visualizer(output_format: str) -> IGraphVisualizer:
+        """
+        Create the appropriate visualizer based on output format.
+        
+        Args:
+            output_format: Desired output format ('png', 'svg', 'html').
+        
+        Returns:
+            An instance of the appropriate visualizer.
+        
+        Raises:
+            ValueError: If the format is not supported.
+        """
+        if output_format in ['png', 'svg']:
+            return GraphvizVisualizer()
+        elif output_format == 'html':
+            return HtmlVisualizer()
+        else:
+            raise ValueError(f"Unsupported output format: {output_format}")
+
+
+# Entry point for running as a script
+if __name__ == '__main__':
+    DepCycleCLI.main()

depcycle/config.py

@@ -0,0 +1,89 @@
+"""Configuration class for DepCycle settings."""
+
+from pathlib import Path
+from typing import List, Optional
+
+# Default exclusion patterns that are automatically applied
+DEFAULT_EXCLUDE_PATTERNS = [
+    'venv',
+    '.venv',
+    'env',
+    '.env',
+    '__pycache__',
+    '*.pyc',
+    '*.pyo',
+    '*.pyd',
+    '.git',
+    '.hg',
+    '.svn',
+    'node_modules',
+    '.pytest_cache',
+    '.mypy_cache',
+    '.tox',
+    'dist',
+    'build',
+    '*.egg-info',
+    'migrations',  # Django/ORM migration directories
+]
+
+
+class Config:
+    """
+    Holds all configuration settings for a DepCycle run.
+    
+    This class encapsulates all the options that control how DepCycle
+    analyzes and visualizes a Python project.
+    
+    Attributes:
+        project_path (Path): Path to the project root directory.
+        output_file (Path): Path where the output visualization should be saved.
+        output_format (str): Format for the output ('png', 'svg', 'html').
+        exclude_patterns (List[str]): Glob patterns for files to exclude.
+        show_third_party (bool): Whether to include third-party modules.
+        show_stdlib (bool): Whether to include standard library modules.
+        include_all (bool): Whether to include files normally excluded by default patterns.
+    """
+    
+    def __init__(
+        self, 
+        project_path: Path, 
+        output_file: Path, 
+        output_format: str = "png", 
+        exclude_patterns: Optional[List[str]] = None, 
+        show_third_party: bool = True,
+        show_stdlib: bool = True,
+        include_all: bool = False
+    ):
+        self.project_path = project_path
+        self.output_file = output_file
+        self.output_format = output_format
+        self.show_third_party = show_third_party
+        self.show_stdlib = show_stdlib
+        self.include_all = include_all
+        
+        # Merge default exclusions with user-specified ones
+        user_patterns = exclude_patterns if exclude_patterns is not None else []
+        if include_all:
+            # If include_all is True, only use user-specified patterns
+            self.exclude_patterns = user_patterns
+        else:
+            # Merge defaults with user patterns, avoiding duplicates
+            self.exclude_patterns = list(DEFAULT_EXCLUDE_PATTERNS)
+            for pattern in user_patterns:
+                if pattern not in self.exclude_patterns:
+                    self.exclude_patterns.append(pattern)
+
+    def __repr__(self) -> str:
+        """Provides a developer-friendly string representation of the Config object."""
+        return (
+            f"{self.__class__.__name__}("
+            f"project_path={self.project_path!r}, "
+            f"output_file={self.output_file!r}, "
+            f"output_format={self.output_format!r}, "
+            f"exclude_patterns={self.exclude_patterns!r}, "
+            f"show_third_party={self.show_third_party!r}, "
+            f"show_stdlib={self.show_stdlib!r}, "
+            f"include_all={self.include_all!r}"
+            ")"
+        )
+

depcycle/graph/__init__.py

@@ -0,0 +1,7 @@
+"""Graph package containing the core dependency graph data structures."""
+
+from .module_node import ModuleNode, ModuleType
+from .dependency_graph import DependencyGraph
+
+__all__ = ["ModuleNode", "ModuleType", "DependencyGraph"]
+

depcycle/graph/dependency_graph.py

@@ -0,0 +1,341 @@
+"""DependencyGraph class representing the core graph data structure."""
+
+from pathlib import Path
+from typing import Dict, List, Set, Optional
+
+from .module_node import ModuleNode, ModuleType
+from ..parsing.project import Project
+from ..parsing.ast_parser import ASTParser
+from ..config import Config
+
+
+class DependencyGraph:
+    """
+    The Blueprint: The central data structure holding the dependency graph.
+    
+    This class orchestrates the process of building a dependency graph from
+    a Python project, resolving import relationships, and detecting cycles.
+    """
+    
+    def __init__(self):
+        """Initialize an empty dependency graph."""
+        self.nodes: Dict[str, ModuleNode] = {}
+        self._project_root: Optional[Path] = None
+    
+    def build(self, project: Project, parser: ASTParser, config: Config):
+        """
+        Build the dependency graph by scanning the project.
+        
+        This is the main orchestration method that:
+        1. Discovers all Python files in the project
+        2. Creates ModuleNode objects for each file
+        3. Extracts imports using the AST parser
+        4. Resolves dependencies between nodes
+        5. Classifies modules by type
+        
+        Args:
+            project: The Project instance containing the files to analyze.
+            parser: The ASTParser for extracting imports.
+            config: Configuration settings for filtering.
+        """
+        self._project_root = project.root_path
+        
+        # Step 1: Discover all Python files
+        python_files = project.get_python_files(config.exclude_patterns)
+        
+        # Step 2: Create nodes for each Python file
+        for file_path in python_files:
+            node = self._create_module_node(file_path, project.root_path)
+            self.nodes[node.name] = node
+            
+            # Extract imports using AST
+            raw_imports = parser.get_imports_from_file(file_path)
+            node.raw_imports = raw_imports
+        
+        # Step 3: Resolve dependencies
+        self._resolve_dependencies()
+        
+        # Step 4: Classify modules
+        self._classify_modules()
+        
+        # Step 5: Filter based on config
+        self._apply_filters(config)
+    
+    def _create_module_node(self, file_path: Path, project_root: Path) -> ModuleNode:
+        """
+        Create a ModuleNode from a file path.
+        
+        Args:
+            file_path: Absolute path to the Python file.
+            project_root: Root directory of the project.
+        
+        Returns:
+            A new ModuleNode instance.
+        """
+        # Convert absolute path to module name
+        # e.g., /project/src/app/models/user.py -> app.models.user
+        relative_path = file_path.relative_to(project_root)
+        
+        # Remove .py extension and convert path separators to dots
+        module_name = str(relative_path.with_suffix('')).replace('/', '.').replace('\\', '.')
+        
+        return ModuleNode(name=module_name, file_path=file_path, module_type=ModuleType.LOCAL)
+    
+    def _resolve_dependencies(self):
+        """
+        Resolve raw import strings to actual ModuleNode dependencies.
+        
+        For each node, this method tries to match its raw_imports to other
+        nodes in the graph. It handles both absolute and relative imports.
+        """
+        for node in self.nodes.values():
+            node.dependencies = set()
+            
+            for import_str in node.raw_imports:
+                # Try to resolve the import
+                dependency_node = self._resolve_import(import_str, node.name)
+                if dependency_node is not None:
+                    node.dependencies.add(dependency_node)
+    
+    def _resolve_import(self, import_str: str, current_module: str) -> Optional[ModuleNode]:
+        """
+        Resolve an import string to a ModuleNode if it exists in the graph.
+        
+        Handles various import patterns:
+        - Absolute imports: 'os' -> looks for 'os' in graph
+        - Relative imports: '.utils' -> resolves relative to current_module
+        - Dotted imports: 'app.models' -> tries to find exact or parent module
+        
+        Args:
+            import_str: The raw import string.
+            current_module: The module where this import appears.
+        
+        Returns:
+            The matching ModuleNode, or None if not found.
+        """
+        # Handle relative imports
+        if import_str.startswith('.'):
+            absolute_name = self._resolve_relative_import(import_str, current_module)
+            if absolute_name in self.nodes:
+                return self.nodes[absolute_name]
+            return None
+        
+        # Handle absolute imports - try exact match first
+        if import_str in self.nodes:
+            return self.nodes[import_str]
+        
+        # Try to find the parent module of the import
+        # e.g., 'os.path.join' -> look for 'os' or 'os.path' or 'os.path.join'
+        # e.g., 'config.Config' -> look for 'config'
+        for potential_module in self._get_import_variants(import_str):
+            if potential_module in self.nodes:
+                return self.nodes[potential_module]
+        
+        return None
+    
+    def _get_import_variants(self, import_str: str) -> List[str]:
+        """
+        Generate potential module names from an import string.
+        
+        When you have an import like 'os.path.join', we should try to match
+        against the full path, but also against parent modules like 'os.path' and 'os'.
+        However, we should NOT match partial strings incorrectly.
+        
+        Examples:
+            'config.Config' -> ['config.Config', 'config']
+            'os.path.join' -> ['os.path.join', 'os.path', 'os']
+            'sys' -> ['sys']
+        
+        Args:
+            import_str: The import string to generate variants for.
+        
+        Returns:
+            List of potential module names to try, in order of specificity.
+        """
+        variants = [import_str]  # Try the full import first
+        
+        # For dotted names, try progressively shorter prefixes
+        # Split on dots and build up variants
+        parts = import_str.split('.')
+        
+        # Generate variants: full -> parts[0].parts[1] -> parts[0]
+        for i in range(len(parts) - 1, 0, -1):
+            variant = '.'.join(parts[:i])
+            if variant not in variants:
+                variants.append(variant)
+        
+        return variants
+    
+    def _resolve_relative_import(self, relative_str: str, current_module: str) -> str:
+        """
+        Convert a relative import to an absolute module name.
+        
+        Args:
+            relative_str: The relative import (e.g., '.utils', '..models', '.TimeAccount.TimeAccount').
+            current_module: The module where this import appears.
+        
+        Returns:
+            The absolute module name.
+        """
+        # Count the number of leading dots
+        dots = 0
+        for char in relative_str:
+            if char == '.':
+                dots += 1
+            else:
+                break
+        
+        # Remove the dots to get the remaining path
+        remaining = relative_str[dots:]
+        
+        # Navigate up the module hierarchy
+        parts = current_module.split('.')
+        target_depth = len(parts) - dots
+        
+        if target_depth < 0:
+            return relative_str  # Can't resolve, return as-is
+        
+        # Build the absolute module name
+        result_parts = parts[:target_depth]
+        if remaining:
+            # Append the remaining path
+            result_parts.append(remaining)
+        
+        return '.'.join(result_parts)
+    
+    def _classify_modules(self):
+        """
+        Classify each module as LOCAL, THIRD_PARTY, or STDLIB.
+        
+        This is currently simplified - in a full implementation, you'd want
+        to check against standard library and installed packages.
+        """
+        # Python standard library modules (partial list)
+        stdlib_modules = {
+            'os', 'sys', 'pathlib', 'json', 'xml', 'csv', 'datetime',
+            'time', 'random', 'hashlib', 'uuid', 'collections', 'itertools',
+            'functools', 'operator', 'math', 'statistics', 're', 'string',
+            'io', 'pickle', 'copy', 'abc', 'enum', 'dataclasses', 'typing',
+            'inspect', 'ast', 'traceback', 'logging', 'argparse', 'getopt',
+            'socket', 'http', 'urllib', 'email', 'html', 'textwrap', 'pprint',
+            'subprocess', 'threading', 'multiprocessing', 'asyncio', 'queue',
+            'weakref', 'gc', 'contextlib', 'decorator', 'profile', 'cProfile',
+            'doctest', 'unittest', 'pdb', 'dis', 'compileall', 'py_compile',
+            'cmd', 'shlex', 'configparser', 'fileinput', 'locale', 'gettext',
+            'argparse', 'calendar', 'codecs', 'difflib', 'fnmatch', 'glob',
+            'linecache', 'shutil', 'tempfile', 'mmap', 'readline', 'rlcompleter',
+            'sqlite3', 'zlib', 'gzip', 'bz2', 'lzma', 'zipfile', 'tarfile',
+            'csv', 'configparser', 'netrc', 'xdrlib', 'plistlib', 'hashlib',
+            'hmac', 'secrets', 'base64', 'binascii', 'struct', 'codecs',
+            'unicodedata', 'stringprep', 'readline', 'rlcompleter', 'lib2to3'
+        }
+        
+        for node in self.nodes.values():
+            # Skip if already classified as LOCAL (from file path)
+            if node.module_type == ModuleType.LOCAL:
+                continue
+            
+            # Check if it's a standard library module
+            module_base = node.name.split('.')[0]
+            if module_base in stdlib_modules:
+                node.module_type = ModuleType.STDLIB
+            else:
+                # Assume third-party for now
+                # In production, you might check installed packages
+                node.module_type = ModuleType.THIRD_PARTY
+    
+    def _apply_filters(self, config: Config):
+        """
+        Apply filtering based on configuration options.
+        
+        Args:
+            config: Configuration settings.
+        """
+        if config.show_third_party and config.show_stdlib:
+            return  # Nothing to filter
+        
+        # Build set of modules to keep
+        keep_modules = set()
+        for node in self.nodes.values():
+            if node.module_type == ModuleType.LOCAL:
+                keep_modules.add(node.name)
+            elif node.module_type == ModuleType.THIRD_PARTY and config.show_third_party:
+                keep_modules.add(node.name)
+            elif node.module_type == ModuleType.STDLIB and config.show_stdlib:
+                keep_modules.add(node.name)
+        
+        # Remove filtered nodes
+        filtered_out = set(self.nodes.keys()) - keep_modules
+        for module_name in filtered_out:
+            del self.nodes[module_name]
+        
+        # Clean up dependencies pointing to removed nodes
+        for node in self.nodes.values():
+            node.dependencies = {
+                dep for dep in node.dependencies 
+                if dep.name in self.nodes
+            }
+    
+    def add_node(self, node: ModuleNode):
+        """
+        Add a node to the graph.
+        
+        Args:
+            node: The ModuleNode to add.
+        """
+        self.nodes[node.name] = node
+    
+    def find_cycles(self) -> List[List[ModuleNode]]:
+        """
+        Detect all cycles in the dependency graph.
+        
+        Uses Depth-First Search (DFS) to find strongly connected components
+        or cycles. Returns all circular dependencies found.
+        
+        Returns:
+            List of cycles, where each cycle is a list of ModuleNodes.
+        """
+        cycles = []
+        visited = set()
+        rec_stack = set()
+        path = []
+        
+        def dfs(node: ModuleNode):
+            """Recursive DFS helper for cycle detection."""
+            visited.add(node.name)
+            rec_stack.add(node.name)
+            path.append(node)
+            
+            for dependency in node.dependencies:
+                if dependency.name not in visited:
+                    if dfs(dependency):
+                        return True
+                elif dependency.name in rec_stack:
+                    # Found a cycle! Extract the cycle path
+                    cycle_start = path.index(dependency)
+                    cycles.append(path[cycle_start:] + [dependency])
+                    return True
+            
+            rec_stack.remove(node.name)
+            path.pop()
+            return False
+        
+        # Run DFS on all nodes
+        for node in self.nodes.values():
+            if node.name not in visited:
+                dfs(node)
+        
+        return cycles
+    
+    def __repr__(self) -> str:
+        """Provide a developer-friendly representation."""
+        return f"DependencyGraph(nodes={len(self.nodes)})"
+    
+    def __len__(self) -> int:
+        """Return the number of nodes in the graph."""
+        return len(self.nodes)
+    
+    def __iter__(self):
+        """Allow iteration over nodes."""
+        return iter(self.nodes.values())
+