Profiler Cub 🐻

A beautiful Python code profiling library with rich terminal visualizations. Profile your code, categorize by layers, analyze dependencies, and get gorgeous color-coded performance reports.

Features

• 🎨 Beautiful Rich Visualizations - Color-coded tables with performance gradients
• 📊 Layer-based Categorization - Organize code into logical layers (Core, API, Database, etc.)
• 🔍 Dependency Analysis - See exactly how much time external libraries consume
• ⏱️ Import vs Runtime Tracking - Separate module load time from execution time
• 🎯 Filtering & Sorting - Multiple sort modes and threshold filtering
• 🔄 Multiple Iterations - Run workloads multiple times for stable measurements

Installation

pip install profiler-cub

With uv:

uv tool install profiler-cub

Quick Start

from pathlib import Path
from profiler_cub.core import CodeProfiler
from profiler_cub.display import display_all
from funcy_bear.tools.gradient import ColorGradient

# Create profiler
profiler = CodeProfiler(
    pkg_name="my_package",
    threshold_ms=0.5,  # Filter functions below 0.5ms
)

# Profile your code
def my_workload():
    # Your code here
    pass

profiler.run(my_workload, stats_file=Path("profile.stats"))

# Display beautiful results
gradient = ColorGradient(start_color="#00ff00", end_color="#ff0000")
display_all(profiler, color_gradient=gradient)

Layer-Based Profiling

Organize your code into logical layers for better insights:

profiler = CodeProfiler(
    pkg_name="my_app",
    module_map={
        "Database": {"db/", "models/"},
        "API": {"api/", "routes/"},
        "Core": {"core/", "engine/"},
    }
)

The profiler will categorize each function by its filepath and show aggregated stats per layer.

Examples

Check out the examples/ directory for complete examples:

• simple_example.py - Minimal setup, get started quickly
• profile_example.py - Full-featured with CLI args, setup/teardown, iterations

See examples/README.md for detailed usage.

Documentation

For comprehensive documentation, see CLAUDE.md which includes:

• Complete architecture overview
• All configuration options
• Key concepts (layers, sort modes, thresholds, etc.)
• Real-world usage patterns

Development

# Install dependencies
uv sync

# Run tests
nox -s tests

# Run linting
nox -s ruff_fix

# Run type checking
nox -s pyright

License

MIT

Credits

Created by Bear 🐻 with love for performance analysis.