Metadata-Version: 2.4
Name: profiler-cub
Version: 0.0.10
Summary: A beautiful profiler for Python projects with various options
Author-email: chaz <bright.lid5647@fastmail.com>
Requires-Python: >=3.12
Requires-Dist: funcy-bear>=0.0.25
Requires-Dist: lazy-bear>=0.0.11
Requires-Dist: rich>=14.2.0
Description-Content-Type: text/markdown

# Profiler Cub 🐻

[![pypi version](https://img.shields.io/pypi/v/profiler-cub.svg)](https://pypi.org/project/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

```bash
pip install profiler-cub
```

With [`uv`](https://docs.astral.sh/uv/):

```bash
uv tool install profiler-cub
```

## Quick Start

```python
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:

```python
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/`](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`](examples/README.md) for detailed usage.

## Documentation

For comprehensive documentation, see [`CLAUDE.md`](CLAUDE.md) which includes:

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

## Development

```bash
# 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.
