speedopy 0.3.0
Zero-dependency performance measurement decorators for Python
License: MIT
Requires Python: >=3.8
Keywords: performance, profiling, benchmark, decorator, timing, memory

# ⚡ speedopy

**Zero-dependency performance measurement decorators + CLI profiler for Python.**

Just import a decorator, slap it on your function, and instantly see beautiful, organized metrics in the terminal. No config, no setup, no external packages.

## Install

```bash
pip install speedopy
```

## 🚀 CLI Runner — Profile Any Script Instantly

Run **any** Python script and get a full performance report — no decorators needed:

```bash
python -m speedopy your_script.py
```

This collects **all 9 metrics at once** and prints a single organized, color-coded report:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ⚡  SPEEDOPY — Performance Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

┌──────────────────── ⏱  TIMING ───────────────────────┐
│ Real (wall-clock) time                       69.15 ms │
│ CPU time                                     62.50 ms │
│ Thread time                                  62.50 ms │
│ I/O wait (estimated)                          6.65 ms │
└────────────────────────────────────────────────────────┘

┌──────────────────── 🧠  MEMORY ──────────────────────┐
│ Current memory                              87.96 KB  │
│ Peak memory                                274.82 KB  │
└────────────────────────────────────────────────────────┘

┌─────────────────── ♻  GC & OBJECTS ──────────────────┐
│ GC objects collected                              11  │
│ GC runs during execution                          2  │
│ Net new objects                                 +81  │
└────────────────────────────────────────────────────────┘
```

## 🎯 Decorators

Each decorator shows its own neat box in the terminal:

| Decorator | What It Measures |
|---|---|
| `cpu_time` | CPU processing time (excludes I/O) |
| `real_time` | Wall-clock time |
| `memory_usage` | Current + peak memory (auto-formats B/KB/MB) |
| `thread_time` | CPU time for the current thread only |
| `call_count` | Number of times a function has been called |
| `function_profile` | Full cProfile report (top 10 calls) |
| `io_time` | Real time, CPU time, and I/O wait |
| `gc_stats` | Garbage collections triggered |
| `object_count` | Net new Python objects created |

## Usage

```python
from speedopy import cpu_time, memory_usage, io_time

@cpu_time
@memory_usage
@io_time
def process_data():
    data = [i ** 2 for i in range(1_000_000)]
    return sum(data)

process_data()
```

Output:
```
┌─────────── 💾  I/O TIME › process_data ───────────┐
│ Real time                              182.35 ms   │
├────────────────────────────────────────────────────┤
│ CPU time                               171.88 ms   │
├────────────────────────────────────────────────────┤
│ I/O wait                                10.47 ms   │
└────────────────────────────────────────────────────┘

┌──────────── 🧠  MEMORY › process_data ────────────┐
│ Current                                    472 B   │
├────────────────────────────────────────────────────┤
│ Peak                                      8.06 MB  │
└────────────────────────────────────────────────────┘

┌────────── ⏱  CPU TIME › process_data ─────────────┐
│ CPU time                               183.29 ms   │
└────────────────────────────────────────────────────┘
```

## Stack Multiple Decorators

```python
from speedopy import cpu_time, memory_usage, call_count

@call_count
@cpu_time
@memory_usage
def my_func():
    return sum(range(500_000))

my_func()
my_func()
```

## Requirements

- Python 3.8+
- No external dependencies

## License

MIT