# PyDepTree
[](https://badge.fury.io/py/pydeptree)
[](https://pypi.org/project/pydeptree/)
[](https://opensource.org/licenses/MIT)
A powerful Python dependency analyzer that visualizes module dependencies in your Python projects as a beautiful tree structure. Built with Rich for colorful terminal output.
## 🎬 See PyDepTree in Action
<details>
<summary>📸 View Individual Screenshots</summary>
### Basic CLI
### Enhanced CLI with File Metrics
### Advanced CLI with All Features
### Advanced CLI with Dependency Analysis
</details>
## 🚀 Three Powerful Versions
<details>
<summary>Compare Features Across Versions</summary>
| Feature | Basic CLI | Enhanced CLI | Advanced CLI |
|---------|-----------|--------------|--------------|
| Dependency Tree | ✅ | ✅ | ✅ |
| Configurable Depth | ✅ | ✅ | ✅ |
| Import Preview | ✅ | ✅ | ✅ |
| **Directory Input** | ✅ | ✅ | ✅ |
| Flexible Import Display | ❌ | ❌ | ✅ (inline/below/both) |
| File Type Colors | ❌ | ✅ | ✅ (+ Config) |
| File Metrics | ❌ | ✅ | ✅ |
| Lint Checking | ❌ | ✅ | ✅ |
| **Detailed Lint Reports** | ❌ | ❌ | ✅ (errors/warnings) |
| **Lint Rule Statistics** | ❌ | ❌ | ✅ |
| Summary Tables | ❌ | ✅ | ✅ |
| Search/Grep | ❌ | ❌ | ✅ |
| Complexity Analysis | ❌ | ❌ | ✅ |
| TODO Detection | ❌ | ❌ | ✅ |
| Git Integration | ❌ | ❌ | ✅ |
| Requirements.txt Gen | ❌ | ❌ | ✅ |
| Dependency Analysis | ❌ | ❌ | ✅ |
</details>
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Quick Start Examples](#quick-start-examples)
- [Demo and Sample Project](#demo-and-sample-project)
- [Command Line Options](#command-line-options)
- [Understanding the Metrics](#understanding-the-metrics)
- [Requirements Generation](#requirements-generation)
- [How It Works](#how-it-works)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#acknowledgments)
## Features
### Core Features
- 🎯 **Smart Import Detection**: Uses AST parsing to accurately find all imports
- 🌳 **Beautiful Tree Visualization**: Rich-powered colorful dependency trees
- 🔍 **Configurable Depth**: Control how deep to analyze dependencies
- 🚀 **Fast & Efficient**: Skips standard library and external packages
- 🎨 **Import Preview**: See actual import statements with `--show-code`
- 📊 **Progress Tracking**: Real-time progress for large codebases
- 🔄 **Circular Dependency Detection**: Identifies and handles circular imports
### Enhanced Features ✨
- 🎨 **Color-coded File Types**: Models (📊), Services (🌐), Utils (🔧), Tests (🧪), Main (🚀), Config (⚙️)
- 📈 **File Statistics**: Size, line count, and import count badges for each file
- 🔍 **Lint Integration**: Automatic error/warning detection using ruff (when available)
- 📊 **Summary Tables**: Aggregate statistics by file type with quality metrics
- 🎯 **Enhanced Visualization**: Rich terminal output with progress indicators and legends
### Advanced Features 🚀 (v0.3.0+)
- 🔎 **Search/Grep Integration**: Search for classes, functions, imports, or any text pattern
- 📐 **Complexity Metrics**: Cyclomatic complexity analysis with visual indicators
- 📍 **Flexible Import Display**: Show imports inline in tree, below tree, or both locations
- 📌 **TODO/FIXME Detection**: Automatically finds and displays TODO comments
- 🏗️ **Code Structure Metrics**: Function and class counts per file
- 🔄 **Git Integration**: Shows file modification status in version control
- 📄 **Requirements Generation**: Automatically generate requirements.txt from detected dependencies
- ⚙️ **Config File Detection** (v0.3.12+): Automatically detects and categorizes Python configuration files
- 📁 **Directory Input Support** (v0.3.19+): Analyze entire projects by passing a directory path
- 🔍 **Detailed Lint Reporting** (v0.3.19+): Show specific lint errors and warnings with file locations
- 📊 **Lint Rule Statistics** (v0.3.19+): Comprehensive statistics table showing lint issues by rule type
## Installation
### Using pip
```bash
pip install pydeptree
```
### Using pipx (recommended)
`pipx` installs CLI tools in isolated environments, preventing dependency conflicts.
#### If you already have pipx:
```bash
pipx install pydeptree
```
#### If you need to install pipx:
**macOS:**
```bash
# Option 1: Using Homebrew (recommended)
brew install pipx
# Option 2: Using pip
pip install pipx
pipx ensurepath
source ~/.zshrc # or restart your terminal
```
**Windows:**
```bash
# Using pip
pip install pipx
pipx ensurepath
# Restart your command prompt/PowerShell
```
**Linux:**
```bash
# Ubuntu/Debian
sudo apt install pipx
# Or using pip
pip install pipx
pipx ensurepath
source ~/.bashrc # or restart your terminal
```
## 📦 Demo Files and Sample Project
If you installed PyDepTree via pip or pipx and want to run the demo scripts, download the demo package:
```bash
# Download the demos.zip file
curl -L https://github.com/TFaucheux/pydeptree/raw/main/demos.zip -o demos.zip
# Extract the demos
unzip demos.zip
```
The demos package includes:
- **demos/** - Directory containing all demo scripts:
- **demo_basic.py** - Demonstrates basic dependency tree visualization
- **demo_enhanced.py** - Shows enhanced features with file metrics and lint checking
- **demo_advanced.py** - Showcases all advanced features including search, git integration, and complexity analysis
- **demo_run_all.py** - Runs all demos sequentially for a complete overview
- **sample_project/** - A realistic Python project with intentional code issues for demonstration
After extracting, run the demos:
```bash
cd demos
python demo_basic.py
python demo_enhanced.py
python demo_advanced.py
python demo_run_all.py
# Or analyze the sample project
cd ..
pydeptree sample_project/main.py
```
Then install PyDepTree:
```bash
pipx install pydeptree
```
### From source
```bash
git clone https://github.com/tfaucheux/pydeptree.git
cd pydeptree
pip install -e .
```
## 🎬 Try the Interactive Demos
```bash
# Run all demos (basic → enhanced → advanced)
python demos/demo_run_all.py
# Or run individual demos
python demos/demo_basic.py # Core dependency analysis features
python demos/demo_enhanced.py # File types, statistics, lint checking
python demos/demo_advanced.py # Search, complexity, TODOs, and more
```
**Perfect for:**
- 🚀 **New users**: See all features in action with realistic examples
- 📚 **Learning**: Understand what each CLI version offers
- 🧪 **Testing**: Verify installation works correctly
- 🎯 **Evaluation**: Decide which features you need
Each demo creates temporary sample projects, so they work with pip, pipx, or source installations.
## Usage
### Basic Usage
Analyze a Python file and see its direct dependencies:
```bash
pydeptree myapp.py
```
Or analyze an entire project by passing a directory:
```bash
pydeptree sample_project --depth 2
```
### Enhanced Usage
Use the enhanced CLI for additional features:
```bash
pydeptree-enhanced myapp.py --depth 2
pydeptree-enhanced sample_project --depth 2 # Directory input
```
The enhanced version provides color-coded file types, lint checking, and detailed statistics.
### Advanced Usage (v0.3.19+)
Use the advanced CLI for search, complexity analysis, and comprehensive lint reporting:
```bash
pydeptree-advanced myapp.py --search "APIClient" --search-type class
pydeptree-advanced sample_project --depth 2 # Analyze entire project
```
The advanced version includes all enhanced features plus search capabilities, complexity metrics, TODO detection, git integration, detailed lint reporting, and lint rule statistics.
### Advanced Options
```bash
# Analyze dependencies up to 3 levels deep
pydeptree myapp.py --depth 3
# Show import statements from each file
pydeptree myapp.py --show-code
# Specify a custom project root
pydeptree myapp.py --project-root /path/to/project
```
## Quick Start Examples
### Basic Usage
```bash
# Analyze a Python file with the original CLI
pydeptree myapp.py
# Use the enhanced version with additional features
pydeptree-enhanced myapp.py --depth 2
```
### Enhanced Features Examples
```bash
# Disable lint checking
pydeptree-enhanced myapp.py --no-check-lint
# Disable statistics table
pydeptree-enhanced myapp.py --no-show-stats
# Show detailed import statements
pydeptree-enhanced myapp.py --show-code --depth 3
```
### Advanced Features Examples
```bash
# Analyze entire project directory
pydeptree-advanced sample_project --depth 2
# Search for a specific class
pydeptree-advanced myapp.py --search "UserModel" --search-type class
# Search for functions containing 'validate'
pydeptree-advanced myapp.py --search "validate" --search-type function --depth 3
# Find all TODO comments
pydeptree-advanced myapp.py --search "TODO|FIXME|HACK" --depth 2
# Show detailed lint errors and warnings with file locations
pydeptree-advanced sample_project --show-errors --show-warnings
# Disable lint rule statistics (enabled by default)
pydeptree-advanced sample_project --no-show-lint-stats
# Minimal output with just file structure
pydeptree-advanced myapp.py --no-show-metrics --no-check-lint --no-show-stats
# Focus on complexity issues
pydeptree-advanced myapp.py --no-show-todos --no-check-git
# Generate requirements.txt from dependencies (with safety features)
pydeptree-advanced myapp.py --generate-requirements --depth 3
# Generate requirements without versions
pydeptree-advanced myapp.py --generate-requirements --no-versions --no-interactive
# Generate requirements to specific file
pydeptree-advanced myapp.py -R -o my-requirements.txt
# Show detailed dependency analysis like johnnydep
pydeptree-advanced myapp.py --generate-requirements --analyze-deps
# Deep dependency analysis
pydeptree-advanced myapp.py --analyze-deps --dep-depth 3
```
## Advanced CLI Output Examples
### Basic Advanced Analysis with Complexity and Metrics
```bash
pydeptree-advanced sample_project/main.py --depth 2
```
*Shows complexity metrics (C:4), function/class counts [0c/1f], lint warnings (W:5), file statistics, and comprehensive analysis with color-coded file types.*
### Requirements Generation with Safety Features
```bash
pydeptree-advanced sample_project/main.py --generate-requirements --no-interactive
```
*Demonstrates the safe requirements.txt generation feature with automatic backup protection and comprehensive dependency analysis.*
### Import Statement Display Options
The `--show-code` flag offers flexible ways to display import statements:
#### Inline Display (`--show-code=inline`)
Shows import statements directly in the dependency tree:
```bash
pydeptree-advanced myapp.py --show-code=inline
```
Example output:
```
🚀 main.py
├── 🌐 services/api.py
│ ├── 📊 models/response.py
│ ├── └─ from models.response import APIResponse, ErrorResponse
│ └── 🔧 utils/http.py
└── └─ from utils.http import HTTPClient, HTTPError
```
#### Below Display (`--show-code=below`)
Traditional display showing imports after the tree (default):
```bash
pydeptree-advanced myapp.py --show-code=below
# or simply:
pydeptree-advanced myapp.py --show-code
```
#### Both Locations (`--show-code=both`)
Displays imports both inline and at the bottom:
```bash
pydeptree-advanced myapp.py --show-code=both
```
### Testing the Enhanced Features
```bash
# Run the interactive demo
python demo_enhanced.py
# Try on the sample project (contains intentional lint errors for demo)
pydeptree-enhanced sample_project/main.py --depth 2
# Try the advanced features
pydeptree-advanced sample_project/main.py --search "validate" --search-type function
# Compare all three CLIs
pydeptree sample_project/main.py --depth 2 # Basic
pydeptree-enhanced sample_project/main.py --depth 2 # Enhanced
pydeptree-advanced sample_project/main.py --depth 2 # Advanced
```
## Demo and Sample Project
PyDepTree includes a comprehensive sample project to demonstrate its enhanced features.
**⚠️ Note about Sample Project**: The `sample_project/` directory contains **intentional code quality issues** (linting errors, warnings, and code smells) to demonstrate the enhanced PyDepTree's lint checking capabilities. These are not bugs but deliberate examples that showcase how the tool can help identify code quality problems in real projects.
The sample project includes realistic examples of:
- Missing imports and type hints
- Unused variables
- Long lines exceeding style guidelines
- Inefficient code patterns
- Complex conditions that could be simplified
This allows you to see how PyDepTree Enhanced detects and reports these issues with color-coded badges and summary statistics.
## Command Line Options
### Basic CLI (`pydeptree`)
- `FILE_OR_DIRECTORY`: Path to the Python file or directory to analyze (required)
- `-d, --depth INTEGER`: Maximum depth to traverse (default: 1)
- `-r, --project-root PATH`: Project root directory (default: file's parent or input directory)
- `-c, --show-code`: Display import statements from each file
- `--help`: Show help message and exit
### Enhanced CLI (`pydeptree-enhanced`)
All basic options plus:
- `-l, --check-lint / --no-check-lint`: Enable/disable lint checking (default: enabled)
- `-s, --show-stats / --no-show-stats`: Show/hide statistics summary table (default: enabled)
### Advanced CLI (`pydeptree-advanced`)
All enhanced options plus:
- `-c, --show-code [below|inline|both]`: Display import statements with flexible positioning
- `below`: Show imports after the tree (default, backward compatible)
- `inline`: Show imports directly in the tree structure
- `both`: Show imports in both locations
- `-S, --search TEXT`: Search for text/pattern in files
- `--search-type [text|class|function|import]`: Type of search to perform (default: text)
- `--show-todos / --no-show-todos`: Show/hide TODO comments (default: enabled)
- `--check-git / --no-check-git`: Show/hide git status (default: enabled)
- `--show-metrics / --no-show-metrics`: Show/hide inline metrics like size, complexity (default: enabled)
- `--show-errors`: Show detailed lint errors with file names and line numbers
- `--show-warnings`: Show detailed lint warnings with file names and line numbers
- `--show-lint-stats / --no-show-lint-stats`: Show/hide lint rule statistics summary (default: enabled)
- `-R, --generate-requirements`: Generate requirements.txt from detected dependencies
- `-o, --requirements-output PATH`: Output path for requirements.txt (default: auto-generated)
- `--no-versions`: Generate requirements.txt without version numbers
- `--no-interactive`: Don't prompt for confirmation when requirements.txt exists
- `--analyze-deps`: Show detailed dependency analysis like johnnydep
- `--dep-depth INTEGER`: Maximum depth for dependency analysis (default: 2)
## Understanding the Metrics
### Inline Metrics (Advanced CLI)
- **Size**: File size (B/KB/MB)
- **Lines**: Total line count (e.g., `31L`)
- **Imports**: Number of import statements (e.g., `5↓`)
- **Complexity**: Cyclomatic complexity (e.g., `C:12`)
- `C:1-5` (green/dim): Simple, easy to test
- `C:6-10` (yellow): Moderate complexity
- `C:11+` (red): High complexity, consider refactoring
- **Structure**: Class/function count (e.g., `[2c/5f]` = 2 classes, 5 functions)
- **Lint Issues**:
- `E:n` (red): Number of errors
- `W:n` (yellow): Number of warnings
- **TODOs**: Number of TODO/FIXME comments (e.g., `📌3`)
- **Git Status**: `[M]` modified, `[A]` added, `[D]` deleted
- **Search Matches**: Number of search results (e.g., `🔍5`)
### Summary Table Columns
- **Type**: File category with icon
- **Count**: Number of files in category
- **Total/Avg Lines**: Code volume metrics
- **Functions/Classes**: Total count per category
- **Avg Complexity**: Average cyclomatic complexity
- **TODOs**: Total TODO comments found
- **Errors/Warnings**: Lint issue counts
- **Matches**: Search result counts (when searching)
### File Type Detection
PyDepTree automatically categorizes Python files by analyzing their paths and names:
- **📊 Models**: Files in `/models/` directories or containing 'model' in the name
- **🌐 Services**: Files in `/services/` directories or containing 'service', 'api', 'client' in the name
- **🔧 Utils**: Files in `/utils/` directories or containing 'util', 'helper' in the name
- **🧪 Tests**: Files in `/tests/` directories or starting with 'test_'
- **🚀 Main**: Files named 'main.py' or '__main__.py'
- **⚙️ Config**: Files like 'config.py', 'settings.py', 'env.py', or in `/config/` directories
- **📄 Other**: Files that don't match the above patterns
### Directory Input Support (v0.3.19+)
PyDepTree can analyze entire projects by accepting directory paths:
```bash
# Automatically finds entry point (main.py, app.py, etc.)
pydeptree-advanced sample_project --depth 2
# Entry point detection priority:
# 1. main.py
# 2. __main__.py
# 3. app.py
# 4. run.py
# 5. start.py
# 6. index.py
# 7. __init__.py
# 8. First Python file found
```
When analyzing directories, PyDepTree automatically:
- Finds the most appropriate entry point file
- Sets the project root to the input directory
- Shows which entry point was selected
- Handles error cases gracefully (no Python files found)
### Advanced Lint Analysis (v0.3.19+)
PyDepTree now provides comprehensive lint analysis powered by ruff:
#### Lint Rule Statistics
Get project-wide statistics showing all lint issues by rule type:
```bash
pydeptree-advanced sample_project --show-lint-stats # Default: enabled
```
Example output:
```
Lint Issues by Rule
╭──────────┬──────────────┬──────────┬──────────────────────────────────╮
│ Count │ Rule │ Fixable │ Description │
├──────────┼──────────────┼──────────┼──────────────────────────────────┤
│ 35 │ W293 │ ✓ │ blank-line-with-whitespace │
│ 10 │ W292 │ ✓ │ missing-newline-at-end-of-file │
│ 6 │ I001 │ ✓ │ unsorted-imports │
│ 5 │ B904 │ ✗ │ raise-without-from-inside-except │
╰──────────┴──────────────┴──────────┴──────────────────────────────────╯
Total issues: 67
```
#### Detailed Error and Warning Reports
Show specific lint issues with exact file locations:
```bash
# Show detailed errors with file:line:column locations
pydeptree-advanced sample_project --show-errors
# Show detailed warnings with file:line:column locations
pydeptree-advanced sample_project --show-warnings
# Show both errors and warnings
pydeptree-advanced sample_project --show-errors --show-warnings
```
Example output:
```
Detailed Lint Errors:
• sample_project/validators.py:25:13 - E722: bare-except
• sample_project/http.py:45:1 - E501: line-too-long
Total: 3 errors
Detailed Lint Warnings:
• sample_project/main.py:5:1 - W293: blank-line-with-whitespace
• sample_project/api.py:22:1 - I001: unsorted-imports
Total: 31 warnings
```
#### Lint Control Options
```bash
# Disable lint rule statistics (keep file-level lint summary)
pydeptree-advanced sample_project --no-show-lint-stats
# Disable all lint checking
pydeptree-advanced sample_project --no-check-lint
# Show only detailed errors/warnings (no statistics table)
pydeptree-advanced sample_project --show-errors --no-show-lint-stats
```
## Requirements Generation
PyDepTree can automatically generate `requirements.txt` files from your project's external dependencies:
```bash
# Generate requirements.txt with versions
pydeptree-advanced myapp.py --generate-requirements
# Generate without versions
pydeptree-advanced myapp.py --generate-requirements --no-versions
# Specify output file
pydeptree-advanced myapp.py -R -o my-deps.txt
```
### Features:
- **Smart Detection**: Automatically identifies external packages (excludes stdlib and project modules)
- **Version Detection**: Attempts to detect installed package versions
- **File References**: Shows which files use each dependency
- **Advanced Safety Features**: Comprehensive protection against overwriting existing files:
- **Interactive Prompts**: When requirements.txt exists, choose from: overwrite, backup_and_overwrite, save_as_new, or cancel
- **Automatic Backups**: Creates timestamped backups (e.g., requirements.20250122_143021.backup)
- **Change Preview**: Shows first 5 lines of current vs new content before overwriting
- **Safe Non-Interactive Mode**: Auto-generates numbered filenames (requirements_1.txt, requirements_2.txt, etc.)
- **Rich Display**: Beautiful table showing dependencies with versions and usage
- **Dependency Tree Analysis**: Like johnnydep, shows transitive dependencies with descriptions
- **Package Summaries**: Displays what each package does
### Basic Example Output:
```
Found 2 external dependencies:
┏━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Package ┃ Version ┃ Used In ┃
┡━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│ requests │ 2.32.4 │ http.py │
│ yaml │ Not found │ config.py │
└──────────┴───────────┴─────────────────────┘
✓ Requirements file written to: requirements_1.txt
```
### Enhanced Dependency Analysis (--analyze-deps):
```
Package Dependency Analysis:
📦 Dependencies
├── requests (2.32.4)
│ ├── Python HTTP for Humans.
│ ├── certifi (2025.7.14)
│ │ └── Python package for providing Mozilla's CA Bundle.
│ ├── charset_normalizer (3.4.2)
│ │ └── The Real First Universal Charset Detector.
│ ├── idna (3.10)
│ │ └── Internationalized Domain Names in Applications (IDNA)
│ └── urllib3 (2.5.0)
│ └── HTTP library with thread-safe connection pooling.
└── yaml (not installed)
Package Summary:
Package Summary
certifi (2025.7.14) Python package for providing Mozilla's CA Bundle.
charset_normalizer (3.4.2) The Real First Universal Charset Detector...
idna (3.10) Internationalized Domain Names in Applications
requests (2.32.4) Python HTTP for Humans.
urllib3 (2.5.0) HTTP library with thread-safe connection pooling.
yaml (not installed) No description available
✓ Requirements file written to: requirements_1.txt
```
## How It Works
PyDepTree uses Python's built-in AST (Abstract Syntax Tree) module to parse Python files and extract import statements. It then:
1. Identifies which imports are part of your project (vs external libraries)
2. Recursively analyzes imported modules up to the specified depth
3. Builds a dependency graph while detecting circular imports
4. Renders a beautiful tree visualization using Rich
The Advanced CLI adds:
5. AST-based complexity analysis and code structure metrics
6. Pattern matching for search functionality
7. Git integration for version control awareness
8. Comment parsing for TODO detection
## Development
### Setup Development Environment
```bash
# Clone the repository
git clone https://github.com/tfaucheux/pydeptree.git
cd pydeptree
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode with dev dependencies
pip install -e ".[dev]"
```
### Running Tests
```bash
# Run all tests (33 tests total: 5 basic + 28 enhanced)
pytest
# Run with coverage report (should show ~85% coverage)
pytest --cov=pydeptree --cov-report=term-missing
# Run only enhanced CLI tests
pytest tests/test_cli_enhanced.py
# Run linting (Note: sample_project/ contains intentional errors for demo purposes)
ruff check pydeptree/ # Check only the main package code (clean)
ruff check . # Check everything (will show demo errors)
black --check .
mypy pydeptree
```
**Note**: The `sample_project/` directory contains intentional linting errors for demonstration purposes. When running linting tools on the entire project, you'll see these demo errors alongside any real issues in the main codebase.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- Built with [Click](https://click.palletsprojects.com/) for CLI
- Beautiful output powered by [Rich](https://github.com/Textualize/rich)
- Inspired by various dependency analysis tools in the Python ecosystem
Raw data
{
"_id": null,
"home_page": null,
"name": "pydeptree",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "Todd Faucheux <tfaucheux@gmail.com>",
"keywords": "dependency, analysis, tree, ast, development, python, import, dependency-tree, dependency-graph, module-analysis, code-analysis, static-analysis, visualization, cli, terminal, deptree, requirements",
"author": "Todd Faucheux",
"author_email": "Todd Faucheux <tfaucheux@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f9/03/58622db751c5ff9e6b01de8cbcd142ae5b3ac34343381121c3d264d61232/pydeptree-0.3.20.tar.gz",
"platform": null,
"description": "# PyDepTree\n\n[](https://badge.fury.io/py/pydeptree)\n[](https://pypi.org/project/pydeptree/)\n[](https://opensource.org/licenses/MIT)\n\nA powerful Python dependency analyzer that visualizes module dependencies in your Python projects as a beautiful tree structure. Built with Rich for colorful terminal output.\n\n## \ud83c\udfac See PyDepTree in Action\n\n\n\n<details>\n<summary>\ud83d\udcf8 View Individual Screenshots</summary>\n\n### Basic CLI\n\n\n### Enhanced CLI with File Metrics\n\n\n### Advanced CLI with All Features\n\n\n### Advanced CLI with Dependency Analysis\n\n\n</details>\n\n## \ud83d\ude80 Three Powerful Versions\n\n<details>\n<summary>Compare Features Across Versions</summary>\n\n| Feature | Basic CLI | Enhanced CLI | Advanced CLI |\n|---------|-----------|--------------|--------------|\n| Dependency Tree | \u2705 | \u2705 | \u2705 |\n| Configurable Depth | \u2705 | \u2705 | \u2705 |\n| Import Preview | \u2705 | \u2705 | \u2705 |\n| **Directory Input** | \u2705 | \u2705 | \u2705 |\n| Flexible Import Display | \u274c | \u274c | \u2705 (inline/below/both) |\n| File Type Colors | \u274c | \u2705 | \u2705 (+ Config) |\n| File Metrics | \u274c | \u2705 | \u2705 |\n| Lint Checking | \u274c | \u2705 | \u2705 |\n| **Detailed Lint Reports** | \u274c | \u274c | \u2705 (errors/warnings) |\n| **Lint Rule Statistics** | \u274c | \u274c | \u2705 |\n| Summary Tables | \u274c | \u2705 | \u2705 |\n| Search/Grep | \u274c | \u274c | \u2705 |\n| Complexity Analysis | \u274c | \u274c | \u2705 |\n| TODO Detection | \u274c | \u274c | \u2705 |\n| Git Integration | \u274c | \u274c | \u2705 |\n| Requirements.txt Gen | \u274c | \u274c | \u2705 |\n| Dependency Analysis | \u274c | \u274c | \u2705 |\n\n</details>\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Quick Start Examples](#quick-start-examples)\n- [Demo and Sample Project](#demo-and-sample-project)\n- [Command Line Options](#command-line-options)\n- [Understanding the Metrics](#understanding-the-metrics)\n- [Requirements Generation](#requirements-generation)\n- [How It Works](#how-it-works)\n- [Development](#development)\n- [Contributing](#contributing)\n- [License](#license)\n- [Acknowledgments](#acknowledgments)\n\n## Features\n\n### Core Features\n- \ud83c\udfaf **Smart Import Detection**: Uses AST parsing to accurately find all imports\n- \ud83c\udf33 **Beautiful Tree Visualization**: Rich-powered colorful dependency trees \n- \ud83d\udd0d **Configurable Depth**: Control how deep to analyze dependencies\n- \ud83d\ude80 **Fast & Efficient**: Skips standard library and external packages\n- \ud83c\udfa8 **Import Preview**: See actual import statements with `--show-code`\n- \ud83d\udcca **Progress Tracking**: Real-time progress for large codebases\n- \ud83d\udd04 **Circular Dependency Detection**: Identifies and handles circular imports\n\n### Enhanced Features \u2728\n- \ud83c\udfa8 **Color-coded File Types**: Models (\ud83d\udcca), Services (\ud83c\udf10), Utils (\ud83d\udd27), Tests (\ud83e\uddea), Main (\ud83d\ude80), Config (\u2699\ufe0f)\n- \ud83d\udcc8 **File Statistics**: Size, line count, and import count badges for each file\n- \ud83d\udd0d **Lint Integration**: Automatic error/warning detection using ruff (when available)\n- \ud83d\udcca **Summary Tables**: Aggregate statistics by file type with quality metrics\n- \ud83c\udfaf **Enhanced Visualization**: Rich terminal output with progress indicators and legends\n\n### Advanced Features \ud83d\ude80 (v0.3.0+)\n- \ud83d\udd0e **Search/Grep Integration**: Search for classes, functions, imports, or any text pattern\n- \ud83d\udcd0 **Complexity Metrics**: Cyclomatic complexity analysis with visual indicators\n- \ud83d\udccd **Flexible Import Display**: Show imports inline in tree, below tree, or both locations\n- \ud83d\udccc **TODO/FIXME Detection**: Automatically finds and displays TODO comments\n- \ud83c\udfd7\ufe0f **Code Structure Metrics**: Function and class counts per file\n- \ud83d\udd04 **Git Integration**: Shows file modification status in version control\n- \ud83d\udcc4 **Requirements Generation**: Automatically generate requirements.txt from detected dependencies\n- \u2699\ufe0f **Config File Detection** (v0.3.12+): Automatically detects and categorizes Python configuration files\n- \ud83d\udcc1 **Directory Input Support** (v0.3.19+): Analyze entire projects by passing a directory path\n- \ud83d\udd0d **Detailed Lint Reporting** (v0.3.19+): Show specific lint errors and warnings with file locations\n- \ud83d\udcca **Lint Rule Statistics** (v0.3.19+): Comprehensive statistics table showing lint issues by rule type\n\n## Installation\n\n### Using pip\n\n```bash\npip install pydeptree\n```\n\n### Using pipx (recommended)\n\n`pipx` installs CLI tools in isolated environments, preventing dependency conflicts.\n\n#### If you already have pipx:\n```bash\npipx install pydeptree\n```\n\n#### If you need to install pipx:\n\n**macOS:**\n\n```bash\n# Option 1: Using Homebrew (recommended)\nbrew install pipx\n\n# Option 2: Using pip\npip install pipx\npipx ensurepath\nsource ~/.zshrc # or restart your terminal\n```\n\n**Windows:**\n\n```bash\n# Using pip\npip install pipx\npipx ensurepath\n# Restart your command prompt/PowerShell\n```\n\n**Linux:**\n```bash\n# Ubuntu/Debian\nsudo apt install pipx\n\n# Or using pip\npip install pipx\npipx ensurepath\nsource ~/.bashrc # or restart your terminal\n```\n\n## \ud83d\udce6 Demo Files and Sample Project\n\nIf you installed PyDepTree via pip or pipx and want to run the demo scripts, download the demo package:\n\n```bash\n# Download the demos.zip file\ncurl -L https://github.com/TFaucheux/pydeptree/raw/main/demos.zip -o demos.zip\n\n# Extract the demos\nunzip demos.zip\n```\n\nThe demos package includes:\n\n- **demos/** - Directory containing all demo scripts:\n - **demo_basic.py** - Demonstrates basic dependency tree visualization\n - **demo_enhanced.py** - Shows enhanced features with file metrics and lint checking\n - **demo_advanced.py** - Showcases all advanced features including search, git integration, and complexity analysis\n - **demo_run_all.py** - Runs all demos sequentially for a complete overview\n- **sample_project/** - A realistic Python project with intentional code issues for demonstration\n\nAfter extracting, run the demos:\n```bash\ncd demos\npython demo_basic.py\npython demo_enhanced.py\npython demo_advanced.py\npython demo_run_all.py\n\n# Or analyze the sample project\ncd ..\npydeptree sample_project/main.py\n```\n\nThen install PyDepTree:\n```bash\npipx install pydeptree\n```\n\n### From source\n\n```bash\ngit clone https://github.com/tfaucheux/pydeptree.git\ncd pydeptree\npip install -e .\n```\n\n## \ud83c\udfac Try the Interactive Demos\n\n```bash\n# Run all demos (basic \u2192 enhanced \u2192 advanced)\npython demos/demo_run_all.py\n\n# Or run individual demos\npython demos/demo_basic.py # Core dependency analysis features\npython demos/demo_enhanced.py # File types, statistics, lint checking \npython demos/demo_advanced.py # Search, complexity, TODOs, and more\n```\n\n**Perfect for:**\n- \ud83d\ude80 **New users**: See all features in action with realistic examples\n- \ud83d\udcda **Learning**: Understand what each CLI version offers\n- \ud83e\uddea **Testing**: Verify installation works correctly\n- \ud83c\udfaf **Evaluation**: Decide which features you need\n\nEach demo creates temporary sample projects, so they work with pip, pipx, or source installations.\n\n## Usage\n\n### Basic Usage\n\nAnalyze a Python file and see its direct dependencies:\n\n```bash\npydeptree myapp.py\n```\n\nOr analyze an entire project by passing a directory:\n\n```bash\npydeptree sample_project --depth 2\n```\n\n### Enhanced Usage\n\nUse the enhanced CLI for additional features:\n\n```bash\npydeptree-enhanced myapp.py --depth 2\npydeptree-enhanced sample_project --depth 2 # Directory input\n```\n\nThe enhanced version provides color-coded file types, lint checking, and detailed statistics.\n\n### Advanced Usage (v0.3.19+)\n\nUse the advanced CLI for search, complexity analysis, and comprehensive lint reporting:\n\n```bash\npydeptree-advanced myapp.py --search \"APIClient\" --search-type class\npydeptree-advanced sample_project --depth 2 # Analyze entire project\n```\n\nThe advanced version includes all enhanced features plus search capabilities, complexity metrics, TODO detection, git integration, detailed lint reporting, and lint rule statistics.\n\n### Advanced Options\n\n```bash\n# Analyze dependencies up to 3 levels deep\npydeptree myapp.py --depth 3\n\n# Show import statements from each file \npydeptree myapp.py --show-code\n\n# Specify a custom project root\npydeptree myapp.py --project-root /path/to/project\n```\n\n## Quick Start Examples\n\n### Basic Usage\n```bash\n# Analyze a Python file with the original CLI\npydeptree myapp.py\n\n# Use the enhanced version with additional features\npydeptree-enhanced myapp.py --depth 2\n```\n\n### Enhanced Features Examples\n```bash\n# Disable lint checking\npydeptree-enhanced myapp.py --no-check-lint\n\n# Disable statistics table\npydeptree-enhanced myapp.py --no-show-stats\n\n# Show detailed import statements\npydeptree-enhanced myapp.py --show-code --depth 3\n```\n\n### Advanced Features Examples\n```bash\n# Analyze entire project directory\npydeptree-advanced sample_project --depth 2\n\n# Search for a specific class\npydeptree-advanced myapp.py --search \"UserModel\" --search-type class\n\n# Search for functions containing 'validate'\npydeptree-advanced myapp.py --search \"validate\" --search-type function --depth 3\n\n# Find all TODO comments\npydeptree-advanced myapp.py --search \"TODO|FIXME|HACK\" --depth 2\n\n# Show detailed lint errors and warnings with file locations\npydeptree-advanced sample_project --show-errors --show-warnings\n\n# Disable lint rule statistics (enabled by default)\npydeptree-advanced sample_project --no-show-lint-stats\n\n# Minimal output with just file structure\npydeptree-advanced myapp.py --no-show-metrics --no-check-lint --no-show-stats\n\n# Focus on complexity issues\npydeptree-advanced myapp.py --no-show-todos --no-check-git\n\n# Generate requirements.txt from dependencies (with safety features)\npydeptree-advanced myapp.py --generate-requirements --depth 3\n\n# Generate requirements without versions\npydeptree-advanced myapp.py --generate-requirements --no-versions --no-interactive\n\n# Generate requirements to specific file\npydeptree-advanced myapp.py -R -o my-requirements.txt\n\n# Show detailed dependency analysis like johnnydep\npydeptree-advanced myapp.py --generate-requirements --analyze-deps\n\n# Deep dependency analysis\npydeptree-advanced myapp.py --analyze-deps --dep-depth 3\n```\n\n## Advanced CLI Output Examples \n\n### Basic Advanced Analysis with Complexity and Metrics\n\n```bash\npydeptree-advanced sample_project/main.py --depth 2\n```\n*Shows complexity metrics (C:4), function/class counts [0c/1f], lint warnings (W:5), file statistics, and comprehensive analysis with color-coded file types.*\n\n### Requirements Generation with Safety Features\n\n```bash\npydeptree-advanced sample_project/main.py --generate-requirements --no-interactive\n```\n*Demonstrates the safe requirements.txt generation feature with automatic backup protection and comprehensive dependency analysis.*\n\n### Import Statement Display Options\n\nThe `--show-code` flag offers flexible ways to display import statements:\n\n#### Inline Display (`--show-code=inline`)\nShows import statements directly in the dependency tree:\n\n```bash\npydeptree-advanced myapp.py --show-code=inline\n```\n\nExample output:\n```\n\ud83d\ude80 main.py\n\u251c\u2500\u2500 \ud83c\udf10 services/api.py\n\u2502 \u251c\u2500\u2500 \ud83d\udcca models/response.py\n\u2502 \u251c\u2500\u2500 \u2514\u2500 from models.response import APIResponse, ErrorResponse\n\u2502 \u2514\u2500\u2500 \ud83d\udd27 utils/http.py\n\u2514\u2500\u2500 \u2514\u2500 from utils.http import HTTPClient, HTTPError\n```\n\n#### Below Display (`--show-code=below`)\nTraditional display showing imports after the tree (default):\n\n```bash\npydeptree-advanced myapp.py --show-code=below\n# or simply:\npydeptree-advanced myapp.py --show-code\n```\n\n#### Both Locations (`--show-code=both`)\nDisplays imports both inline and at the bottom:\n\n```bash\npydeptree-advanced myapp.py --show-code=both\n```\n\n### Testing the Enhanced Features\n```bash\n# Run the interactive demo\npython demo_enhanced.py\n\n# Try on the sample project (contains intentional lint errors for demo)\npydeptree-enhanced sample_project/main.py --depth 2\n\n# Try the advanced features\npydeptree-advanced sample_project/main.py --search \"validate\" --search-type function\n\n# Compare all three CLIs\npydeptree sample_project/main.py --depth 2 # Basic\npydeptree-enhanced sample_project/main.py --depth 2 # Enhanced\npydeptree-advanced sample_project/main.py --depth 2 # Advanced\n```\n\n## Demo and Sample Project\n\nPyDepTree includes a comprehensive sample project to demonstrate its enhanced features.\n\n**\u26a0\ufe0f Note about Sample Project**: The `sample_project/` directory contains **intentional code quality issues** (linting errors, warnings, and code smells) to demonstrate the enhanced PyDepTree's lint checking capabilities. These are not bugs but deliberate examples that showcase how the tool can help identify code quality problems in real projects.\n\nThe sample project includes realistic examples of:\n- Missing imports and type hints\n- Unused variables\n- Long lines exceeding style guidelines \n- Inefficient code patterns\n- Complex conditions that could be simplified\n\nThis allows you to see how PyDepTree Enhanced detects and reports these issues with color-coded badges and summary statistics.\n\n## Command Line Options\n\n### Basic CLI (`pydeptree`)\n- `FILE_OR_DIRECTORY`: Path to the Python file or directory to analyze (required)\n- `-d, --depth INTEGER`: Maximum depth to traverse (default: 1)\n- `-r, --project-root PATH`: Project root directory (default: file's parent or input directory)\n- `-c, --show-code`: Display import statements from each file\n- `--help`: Show help message and exit\n\n### Enhanced CLI (`pydeptree-enhanced`)\nAll basic options plus:\n- `-l, --check-lint / --no-check-lint`: Enable/disable lint checking (default: enabled)\n- `-s, --show-stats / --no-show-stats`: Show/hide statistics summary table (default: enabled)\n\n### Advanced CLI (`pydeptree-advanced`)\nAll enhanced options plus:\n- `-c, --show-code [below|inline|both]`: Display import statements with flexible positioning\n - `below`: Show imports after the tree (default, backward compatible)\n - `inline`: Show imports directly in the tree structure\n - `both`: Show imports in both locations\n- `-S, --search TEXT`: Search for text/pattern in files\n- `--search-type [text|class|function|import]`: Type of search to perform (default: text)\n- `--show-todos / --no-show-todos`: Show/hide TODO comments (default: enabled)\n- `--check-git / --no-check-git`: Show/hide git status (default: enabled)\n- `--show-metrics / --no-show-metrics`: Show/hide inline metrics like size, complexity (default: enabled)\n- `--show-errors`: Show detailed lint errors with file names and line numbers\n- `--show-warnings`: Show detailed lint warnings with file names and line numbers\n- `--show-lint-stats / --no-show-lint-stats`: Show/hide lint rule statistics summary (default: enabled)\n- `-R, --generate-requirements`: Generate requirements.txt from detected dependencies\n- `-o, --requirements-output PATH`: Output path for requirements.txt (default: auto-generated)\n- `--no-versions`: Generate requirements.txt without version numbers\n- `--no-interactive`: Don't prompt for confirmation when requirements.txt exists\n- `--analyze-deps`: Show detailed dependency analysis like johnnydep\n- `--dep-depth INTEGER`: Maximum depth for dependency analysis (default: 2)\n\n## Understanding the Metrics\n\n### Inline Metrics (Advanced CLI)\n- **Size**: File size (B/KB/MB)\n- **Lines**: Total line count (e.g., `31L`)\n- **Imports**: Number of import statements (e.g., `5\u2193`)\n- **Complexity**: Cyclomatic complexity (e.g., `C:12`)\n - `C:1-5` (green/dim): Simple, easy to test\n - `C:6-10` (yellow): Moderate complexity\n - `C:11+` (red): High complexity, consider refactoring\n- **Structure**: Class/function count (e.g., `[2c/5f]` = 2 classes, 5 functions)\n- **Lint Issues**: \n - `E:n` (red): Number of errors\n - `W:n` (yellow): Number of warnings\n- **TODOs**: Number of TODO/FIXME comments (e.g., `\ud83d\udccc3`)\n- **Git Status**: `[M]` modified, `[A]` added, `[D]` deleted\n- **Search Matches**: Number of search results (e.g., `\ud83d\udd0d5`)\n\n### Summary Table Columns\n- **Type**: File category with icon\n- **Count**: Number of files in category\n- **Total/Avg Lines**: Code volume metrics\n- **Functions/Classes**: Total count per category\n- **Avg Complexity**: Average cyclomatic complexity\n- **TODOs**: Total TODO comments found\n- **Errors/Warnings**: Lint issue counts\n- **Matches**: Search result counts (when searching)\n\n### File Type Detection\nPyDepTree automatically categorizes Python files by analyzing their paths and names:\n\n- **\ud83d\udcca Models**: Files in `/models/` directories or containing 'model' in the name\n- **\ud83c\udf10 Services**: Files in `/services/` directories or containing 'service', 'api', 'client' in the name \n- **\ud83d\udd27 Utils**: Files in `/utils/` directories or containing 'util', 'helper' in the name\n- **\ud83e\uddea Tests**: Files in `/tests/` directories or starting with 'test_'\n- **\ud83d\ude80 Main**: Files named 'main.py' or '__main__.py'\n- **\u2699\ufe0f Config**: Files like 'config.py', 'settings.py', 'env.py', or in `/config/` directories\n- **\ud83d\udcc4 Other**: Files that don't match the above patterns\n\n### Directory Input Support (v0.3.19+)\nPyDepTree can analyze entire projects by accepting directory paths:\n\n```bash\n# Automatically finds entry point (main.py, app.py, etc.)\npydeptree-advanced sample_project --depth 2\n\n# Entry point detection priority:\n# 1. main.py\n# 2. __main__.py \n# 3. app.py\n# 4. run.py\n# 5. start.py\n# 6. index.py\n# 7. __init__.py\n# 8. First Python file found\n```\n\nWhen analyzing directories, PyDepTree automatically:\n- Finds the most appropriate entry point file\n- Sets the project root to the input directory\n- Shows which entry point was selected\n- Handles error cases gracefully (no Python files found)\n\n### Advanced Lint Analysis (v0.3.19+)\nPyDepTree now provides comprehensive lint analysis powered by ruff:\n\n#### Lint Rule Statistics\nGet project-wide statistics showing all lint issues by rule type:\n\n```bash\npydeptree-advanced sample_project --show-lint-stats # Default: enabled\n```\n\nExample output:\n```\n Lint Issues by Rule \n\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 Count \u2502 Rule \u2502 Fixable \u2502 Description \u2502\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 35 \u2502 W293 \u2502 \u2713 \u2502 blank-line-with-whitespace \u2502\n\u2502 10 \u2502 W292 \u2502 \u2713 \u2502 missing-newline-at-end-of-file \u2502\n\u2502 6 \u2502 I001 \u2502 \u2713 \u2502 unsorted-imports \u2502\n\u2502 5 \u2502 B904 \u2502 \u2717 \u2502 raise-without-from-inside-except \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n\nTotal issues: 67\n```\n\n#### Detailed Error and Warning Reports\nShow specific lint issues with exact file locations:\n\n```bash\n# Show detailed errors with file:line:column locations\npydeptree-advanced sample_project --show-errors\n\n# Show detailed warnings with file:line:column locations \npydeptree-advanced sample_project --show-warnings\n\n# Show both errors and warnings\npydeptree-advanced sample_project --show-errors --show-warnings\n```\n\nExample output:\n```\nDetailed Lint Errors:\n \u2022 sample_project/validators.py:25:13 - E722: bare-except\n \u2022 sample_project/http.py:45:1 - E501: line-too-long\n \n Total: 3 errors\n\nDetailed Lint Warnings: \n \u2022 sample_project/main.py:5:1 - W293: blank-line-with-whitespace\n \u2022 sample_project/api.py:22:1 - I001: unsorted-imports\n \n Total: 31 warnings\n```\n\n#### Lint Control Options\n```bash\n# Disable lint rule statistics (keep file-level lint summary)\npydeptree-advanced sample_project --no-show-lint-stats\n\n# Disable all lint checking\npydeptree-advanced sample_project --no-check-lint\n\n# Show only detailed errors/warnings (no statistics table)\npydeptree-advanced sample_project --show-errors --no-show-lint-stats\n```\n\n## Requirements Generation\n\nPyDepTree can automatically generate `requirements.txt` files from your project's external dependencies:\n\n```bash\n# Generate requirements.txt with versions\npydeptree-advanced myapp.py --generate-requirements\n\n# Generate without versions\npydeptree-advanced myapp.py --generate-requirements --no-versions\n\n# Specify output file\npydeptree-advanced myapp.py -R -o my-deps.txt\n```\n\n### Features:\n- **Smart Detection**: Automatically identifies external packages (excludes stdlib and project modules)\n- **Version Detection**: Attempts to detect installed package versions\n- **File References**: Shows which files use each dependency\n- **Advanced Safety Features**: Comprehensive protection against overwriting existing files:\n - **Interactive Prompts**: When requirements.txt exists, choose from: overwrite, backup_and_overwrite, save_as_new, or cancel\n - **Automatic Backups**: Creates timestamped backups (e.g., requirements.20250122_143021.backup)\n - **Change Preview**: Shows first 5 lines of current vs new content before overwriting\n - **Safe Non-Interactive Mode**: Auto-generates numbered filenames (requirements_1.txt, requirements_2.txt, etc.)\n- **Rich Display**: Beautiful table showing dependencies with versions and usage\n- **Dependency Tree Analysis**: Like johnnydep, shows transitive dependencies with descriptions\n- **Package Summaries**: Displays what each package does\n\n### Basic Example Output:\n```\nFound 2 external dependencies:\n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503 Package \u2503 Version \u2503 Used In \u2503\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502 requests \u2502 2.32.4 \u2502 http.py \u2502\n\u2502 yaml \u2502 Not found \u2502 config.py \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\n\u2713 Requirements file written to: requirements_1.txt\n```\n\n### Enhanced Dependency Analysis (--analyze-deps):\n```\nPackage Dependency Analysis:\n\ud83d\udce6 Dependencies\n\u251c\u2500\u2500 requests (2.32.4)\n\u2502 \u251c\u2500\u2500 Python HTTP for Humans.\n\u2502 \u251c\u2500\u2500 certifi (2025.7.14)\n\u2502 \u2502 \u2514\u2500\u2500 Python package for providing Mozilla's CA Bundle.\n\u2502 \u251c\u2500\u2500 charset_normalizer (3.4.2)\n\u2502 \u2502 \u2514\u2500\u2500 The Real First Universal Charset Detector.\n\u2502 \u251c\u2500\u2500 idna (3.10)\n\u2502 \u2502 \u2514\u2500\u2500 Internationalized Domain Names in Applications (IDNA)\n\u2502 \u2514\u2500\u2500 urllib3 (2.5.0)\n\u2502 \u2514\u2500\u2500 HTTP library with thread-safe connection pooling.\n\u2514\u2500\u2500 yaml (not installed)\n\nPackage Summary:\n Package Summary \n certifi (2025.7.14) Python package for providing Mozilla's CA Bundle. \n charset_normalizer (3.4.2) The Real First Universal Charset Detector... \n idna (3.10) Internationalized Domain Names in Applications \n requests (2.32.4) Python HTTP for Humans. \n urllib3 (2.5.0) HTTP library with thread-safe connection pooling. \n yaml (not installed) No description available \n\n\u2713 Requirements file written to: requirements_1.txt\n```\n\n## How It Works\n\nPyDepTree uses Python's built-in AST (Abstract Syntax Tree) module to parse Python files and extract import statements. It then:\n\n1. Identifies which imports are part of your project (vs external libraries)\n2. Recursively analyzes imported modules up to the specified depth\n3. Builds a dependency graph while detecting circular imports\n4. Renders a beautiful tree visualization using Rich\n\nThe Advanced CLI adds:\n5. AST-based complexity analysis and code structure metrics\n6. Pattern matching for search functionality\n7. Git integration for version control awareness\n8. Comment parsing for TODO detection\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/tfaucheux/pydeptree.git\ncd pydeptree\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install in development mode with dev dependencies\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\n# Run all tests (33 tests total: 5 basic + 28 enhanced)\npytest\n\n# Run with coverage report (should show ~85% coverage)\npytest --cov=pydeptree --cov-report=term-missing\n\n# Run only enhanced CLI tests\npytest tests/test_cli_enhanced.py\n\n# Run linting (Note: sample_project/ contains intentional errors for demo purposes)\nruff check pydeptree/ # Check only the main package code (clean)\nruff check . # Check everything (will show demo errors)\nblack --check .\nmypy pydeptree\n```\n\n**Note**: The `sample_project/` directory contains intentional linting errors for demonstration purposes. When running linting tools on the entire project, you'll see these demo errors alongside any real issues in the main codebase.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built with [Click](https://click.palletsprojects.com/) for CLI\n- Beautiful output powered by [Rich](https://github.com/Textualize/rich)\n- Inspired by various dependency analysis tools in the Python ecosystem\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python dependency tree analyzer with rich terminal output, and code quality features.",
"version": "0.3.20",
"project_urls": {
"Bug Tracker": "https://github.com/tfaucheux/pydeptree/issues",
"Changelog": "https://github.com/tfaucheux/pydeptree/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/tfaucheux/pydeptree#readme",
"Homepage": "https://github.com/tfaucheux/pydeptree",
"Repository": "https://github.com/tfaucheux/pydeptree.git"
},
"split_keywords": [
"dependency",
" analysis",
" tree",
" ast",
" development",
" python",
" import",
" dependency-tree",
" dependency-graph",
" module-analysis",
" code-analysis",
" static-analysis",
" visualization",
" cli",
" terminal",
" deptree",
" requirements"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1cf89b2bd56af952dff62ffcb4cd9aba66a956231da6cee8f30edec8b1b19f3f",
"md5": "f4e0606d412027fbfb720f4967f2140a",
"sha256": "2036a0805c8b2f2998a81e4c7b8bb3ebb1f9f513bc06666c6542077069c8f9b1"
},
"downloads": -1,
"filename": "pydeptree-0.3.20-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f4e0606d412027fbfb720f4967f2140a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 35903,
"upload_time": "2025-07-25T14:34:41",
"upload_time_iso_8601": "2025-07-25T14:34:41.454658Z",
"url": "https://files.pythonhosted.org/packages/1c/f8/9b2bd56af952dff62ffcb4cd9aba66a956231da6cee8f30edec8b1b19f3f/pydeptree-0.3.20-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f90358622db751c5ff9e6b01de8cbcd142ae5b3ac34343381121c3d264d61232",
"md5": "cc441fa89b49020250ce9dbd7951a16d",
"sha256": "0c300c12a2ec38e03844170207dc1cf73cadb6763a945b61b458f632dd726239"
},
"downloads": -1,
"filename": "pydeptree-0.3.20.tar.gz",
"has_sig": false,
"md5_digest": "cc441fa89b49020250ce9dbd7951a16d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 53711,
"upload_time": "2025-07-25T14:34:42",
"upload_time_iso_8601": "2025-07-25T14:34:42.400830Z",
"url": "https://files.pythonhosted.org/packages/f9/03/58622db751c5ff9e6b01de8cbcd142ae5b3ac34343381121c3d264d61232/pydeptree-0.3.20.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 14:34:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tfaucheux",
"github_project": "pydeptree",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pydeptree"
}
JSON
