Find the Largest Files Consuming Disk Space with a Beautiful Terminal Report in Python

import os
import sys
from pathlib import Path

def get_largest_files(directory: str, count: int = 10) -> list:
    """
    Scan the given directory and return the largest files.
    
    Args:
        directory: Path to the directory to scan
        count: Number of largest files to return
        
    Returns:
        List of tuples (file_path, size_in_bytes)
    """
    files_with_sizes = []
    root_path = Path(directory)
    
    if not root_path.exists() or not root_path.is_dir():
        print(f"Error: '{directory}' is not a valid directory.")
        return []
    
    for file_path in root_path.rglob('*'):
        if file_path.is_file():
            try:
                size = file_path.stat().st_size
                files_with_sizes.append((file_path, size))
            except (OSError, PermissionError):
                continue
    
    files_with_sizes.sort(key=lambda x: x[1], reverse=True)
    return files_with_sizes[:count]

def format_size(size_bytes: int) -> str:
    """Convert bytes to human readable format."""
    for unit in ['B', 'KB', 'MB', 'GB', 'TB']:
        if size_bytes < 1024:
            return f"{size_bytes:.2f} {unit}"
        size_bytes /= 1024
    return f"{size_bytes:.2f} PB"

def print_report(files: list) -> None:
    """Print a beautiful terminal report of largest files."""
    if not files:
        print("No files found.")
        return
    
    print("\n" + "=" * 70)
    print("🔍 LARGEST FILES REPORT")
    print("=" * 70)
    
    for i, (file_path, size) in enumerate(files, 1):
        size_str = format_size(size)
        relative_path = file_path
        try:
            relative_path = file_path.relative_to(Path.cwd())
        except ValueError:
            pass
        print(f"  {i:>2}. {size_str:>9}  {relative_path}")
    
    print("=" * 70)
    total_size = sum(size for _, size in files)
    print(f"  Total of top {len(files)} files: {format_size(total_size)}")
    print("=" * 70 + "\n")

if __name__ == "__main__":
    # Default: scan current directory, show top 10 largest files
    target_dir = sys.argv[1] if len(sys.argv) > 1 else "."
    top_n = int(sys.argv[2]) if len(sys.argv) > 2 else 10
    
    largest_files = get_largest_files(target_dir, top_n)
    print_report(largest_files)