Dependency Graph Visualizer in Python

This tutorial demonstrates how to visualize the import dependency graph of a Python codebase using kit. kit’s DependencyAnalyzer leverages Python’s Abstract Syntax Tree (AST) parsing for robust analysis and can output the graph in DOT format, which you can render with Graphviz to generate visual diagrams. This feature is currently only for Python code.

Note

To directly generate an image (e.g., PNG, SVG) without manually handling DOT files, you can use the analyzer.visualize_dependencies() method, provided you have both the graphviz Python package and the Graphviz system executables installed.

Step 1: Generate the Dependency Graph in DOT Format

The kit.Repository object provides access to a DependencyAnalyzer which can build and export the dependency graph.

from kit import Repository

def generate_dot_dependency_graph(repo_path: str) -> str:
    """
    Initializes a Repository, gets its DependencyAnalyzer,
    and exports the dependency graph in DOT format.
    """
    repo = Repository(repo_path)
    analyzer = repo.get_dependency_analyzer()

    # The build_dependency_graph() method is called implicitly by export_dependency_graph
    # if the graph hasn't been built yet.
    dot_output = analyzer.export_dependency_graph(output_format='dot')

    # Ensure dot_output is a string. export_dependency_graph returns the content
    # when output_path is None.
    if not isinstance(dot_output, str):
        # This case should ideally not happen if output_format='dot' and output_path=None
        # based on typical implementations, but good to be defensive.
        raise TypeError(f"Expected DOT output as string, got {type(dot_output)}")

    return dot_output

This function generate_dot_dependency_graph:

1. Initializes the Repository for the given repo_path.
2. Gets a DependencyAnalyzer instance from the repository.
3. Calls analyzer.export_dependency_graph(output_format='dot') to get the graph data as a DOT formatted string.

Step 2: Command-Line Interface

Add CLI arguments for the repository path and an optional output file for the DOT content.

import argparse

# Assume generate_dot_dependency_graph function from Step 1 is defined above

def main() -> None:
    parser = argparse.ArgumentParser(description="Dependency graph visualizer using kit.")
    parser.add_argument("--repo", required=True, help="Path to the code repository")
    parser.add_argument("--output", help="Output DOT file (default: stdout)")
    args = parser.parse_args()

    try:
        dot_content = generate_dot_dependency_graph(args.repo)
        if args.output:
            with open(args.output, "w") as f:
                f.write(dot_content)
            print(f"Dependency graph (DOT format) written to {args.output}")
        else:
            print(dot_content)
    except Exception as e:
        print(f"An error occurred: {e}")
        # For more detailed debugging, you might want to print the traceback
        # import traceback
        # traceback.print_exc()

if __name__ == "__main__":
    main()

Step 3: Running the Script

Run the visualizer script from your terminal. Provide the path to the repository and optionally an output file name for the DOT data.

python your_script_name.py --repo /path/to/your/python_project --output project_deps.dot

Replace your_script_name.py with the actual name of your Python file containing the code from Steps 1 and 2.

Step 4: Rendering the Graph

To visualize the generated DOT file, you need Graphviz installed on your system. Use the dot command-line tool:

dot -Tpng project_deps.dot -o project_deps.png

This will create a PNG image (project_deps.png) of your codebase’s import relationships.

Extending the Visualizer

kit’s DependencyAnalyzer offers more than just DOT export:

• Direct Visualization: Use analyzer.visualize_dependencies(output_path="graph_image_prefix", format="png") to directly save an image (requires the graphviz Python library).
• Other Export Formats: Export to JSON, GraphML, or an adjacency list using analyzer.export_dependency_graph(output_format=...).
• Cycle Detection: Use analyzer.find_cycles() to identify circular dependencies.
• Querying the Graph: Programmatically explore dependencies with analyzer.get_module_dependencies() and analyzer.get_dependents().
• Reports: Generate a comprehensive JSON report with analyzer.generate_dependency_report().

Conclusion

Visualizing dependencies helps you understand, refactor, and document complex codebases. With kit’s DependencyAnalyzer and tools like Graphviz, you can gain valuable insights into your Python project’s structure.