idgi 0.1.1

A command-line tool for exploring and visualizing large Python codebases

idgi

A command-line tool for exploring and visualizing large Python codebases.

Installation

Install with uv

uv add idgi

Install with pip

pip install idgi

Prerequisites

• Python 3.9 or higher

Optional: Graphviz for Visual Exports

For SVG/PNG export functionality, install Graphviz:

# macOS
brew install graphviz

# Ubuntu/Debian
sudo apt-get install graphviz

Install from Source (Development)

git clone https://github.com/kokkodev/idgi.git
cd idgi
uv sync

Getting Started

Once installed, you can start exploring any Python codebase:

# Analyze your project
idgi scan ./your_project

# Visualize dependencies
idgi graph --type imports ./your_project

# Search for specific code elements
idgi search "MyClass" ./your_project

Quick Start

1. Scan a Project

# Basic scan
idgi scan ./my_project

# Scan with exclusions
idgi scan ./my_project --exclude venv --exclude tests

2. Visualize Dependencies

# Show import dependencies as ASCII tree
idgi graph --type imports ./my_project

# Interactive exploration mode
idgi graph --type imports --interactive ./my_project

# Export to SVG (using graph command)
idgi graph --type imports --output dependencies.svg ./my_project

# Or use export command for multiple formats
idgi export --output ./graphs --format svg --types imports ./my_project

# Show class inheritance hierarchy
idgi graph --type inheritance --format hierarchy ./my_project

3. Search Code Elements

# Search for classes, functions, or modules
idgi search "DataLoader" ./my_project

# Limit results
idgi search "test" ./my_project --limit 20

4. Export Multiple Formats

# Export all graph types to multiple formats
idgi export ./my_project --output ./graphs --format svg --format json

# Export specific graph types
idgi export ./my_project --output ./graphs --types imports --types inheritance

Usage Guide

Commands

scan - Analyze Codebase Structure

Recursively scans a directory to analyze Python files and packages.

idgi scan [OPTIONS] DIRECTORY

Options:
  --exclude PATTERN          Exclude files/directories matching pattern
  --no-recursive             Don't scan recursively
  --show-packages            Show package breakdown
  --show-errors              Show parsing errors

Example Output:

┌──────────────────┬─────────┐
│ Metric           │ Count   │
├──────────────────┼─────────┤
│ Python files     │ 1,247   │
│ Total lines      │ 45,123  │
│ Packages         │ 23      │
│ Classes          │ 156     │
│ Functions        │ 489     │
│ Import statements│ 234     │
└──────────────────┴─────────┘

graph - Generate and Display Graphs

Creates various types of dependency and relationship graphs.

idgi graph [OPTIONS] DIRECTORY

Options:
  --type {imports,inheritance,calls,modules,classes,functions}
                             Type of graph to generate (default: imports)
  --format {tree,network,hierarchy}
                             Display format (default: network)
  --interactive, -i          Interactive exploration mode
  --output OUTPUT            Output file (exports to file instead of display)
  --max-nodes N              Maximum nodes to display
  --depth N                  Tree depth for tree format (default: 3)
  --stats                    Show graph statistics
  --exclude EXCLUDE          Patterns to exclude

Graph Types:

• imports: Module dependency graph showing import relationships
• inheritance: Class inheritance hierarchy
• calls: Function call relationships
• modules: High-level module overview
• classes: Class-focused relationship graph
• functions: Function and method relationships

search - Find Code Elements

Search for specific classes, functions, or modules by name.

idgi search [OPTIONS] TERM DIRECTORY

Options:
  --limit N                  Maximum results to show
  --exclude EXCLUDE          Patterns to exclude

export - Export Graphs to Files

Export multiple graph types to various file formats.

idgi export [OPTIONS] DIRECTORY

Options:
  --output DIR               Output directory (required)
  --format {svg,png,pdf,json,dot,gml,graphml}
                             Export formats (can be specified multiple times)
  --types {imports,inheritance,calls,modules,classes,functions}
                             Graph types to export
  --exclude EXCLUDE          Patterns to exclude

Supported Export Formats:

Format	Description	Use Case
SVG	Scalable Vector Graphics	Web display, documentation
PNG	Portable Network Graphics	Reports, presentations
PDF	Portable Document Format	Printing, formal documents
JSON	Structured data	Further analysis, web apps
DOT	Graphviz source	Custom styling, editing
GML	Graph Modeling Language	Academic research
GraphML	XML-based graph format	Tool interoperability

Interactive Mode

The interactive mode provides a terminal-based interface for exploring graphs:

idgi graph --type imports --interactive ./my_project

Interactive Commands:

Command	Alias	Description
show	s	Display current node details
neighbors	n	Show connected nodes
goto <node>	g	Navigate to specific node
back	b	Go back to previous node
search <term>	f	Search for nodes containing term
tree [depth]	t	Show tree view
path <target>	p	Find shortest path to target
bookmark <name>	bm	Manage bookmarks
stats		Display graph statistics
help	h	Show all commands

Filtering and Exclusions

idgi automatically excludes common directories and files that are typically not relevant for code analysis:

Default Exclusions:

• Python cache: __pycache__, *.pyc, *.pyo, *.pyd
• Virtual environments: venv, env, .venv, virtualenv
• Version control: .git, .svn, .hg
• IDE files: .vscode, .idea, *.swp
• Build artifacts: build, dist, *.egg-info

Custom Exclusions:

# Exclude additional patterns
idgi scan ./project --exclude tests --exclude "temp_*" --exclude docs

# Use regex patterns (wrap in forward slashes)
idgi scan ./project --exclude "/test.*\.py/"

Architecture Overview

idgi follows a modular architecture with clear separation of concerns:

idgi/
├── core/           # Core analysis functionality
│   ├── scanner.py  # Directory scanning and file discovery
│   ├── parser.py   # Python AST parsing
│   └── analyzer.py # High-level codebase analysis
├── graph/          # Graph generation and visualization
│   ├── builder.py  # NetworkX graph construction
│   ├── visualizer.py # ASCII and Graphviz rendering
│   └── interactive.py # Terminal-based exploration
├── export/         # Export functionality
│   └── formats.py  # Multi-format export support
├── utils/          # Utility modules
│   ├── filters.py  # Path filtering and exclusions
│   └── cache.py    # Performance caching
└── cli.py          # Command-line interface

Performance Tips:

# Use verbose output for debugging
idgi scan ./project --verbose

# Limit graph size for better performance
idgi graph --type imports --max-nodes 100 ./project

# Use exclusion patterns for focused analysis
idgi scan ./project --exclude tests --exclude docs

Examples

Analyzing a Django Project

# Scan Django project excluding common non-code directories
idgi scan ./myproject --exclude venv --exclude static --exclude media

# Show model inheritance hierarchy
idgi graph --type inheritance ./myproject --format hierarchy

# Find all views
idgi search "View" ./myproject --limit 30

# Export comprehensive analysis
idgi export ./myproject --output ./analysis \
  --format svg --format json --types imports --types inheritance --types calls

Large Codebase Analysis

# Scan with exclusions
idgi scan ./large_project --exclude "test_*"

# Interactive exploration starting with imports
idgi graph --type imports --interactive ./large_project --max-nodes 200

# Export key relationships only
idgi export ./large_project --output ./docs \
  --types imports --types modules --format svg

License

This project is licensed under the MIT License - see the LICENSE file for details.