Metadata-Version: 2.4
Name: step3
Version: 0.1.0
Summary: A small, focused Python profiler
License: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# step3: profit

A small, focused Python profiler built on `sys.monitoring` (Python 3.12+).

## Installation

```bash
uv tool install step3  # recommended
```

Or run without installing:

```bash
uvx --from step3 profit
```

Or with pip: `pip install step3`

## Usage

### `profit run` — profile a script

```bash
profit run script.py
```

Focus on specific functions:

```bash
profit run script.py -p mymod:func1 -p mymod:func2
```

Compare two functions side by side:

```bash
profit run script.py -b mymod:func_old -p mymod:func_new
```

Run a module:

```bash
profit run -m mypackage.module
```

Pass arguments to the script after `--`:

```bash
profit run script.py -- --script-arg value
```

#### Options

| Flag | Description |
|------|-------------|
| `-p TARGET` | Function to show (repeatable) |
| `-b TARGET` | Baseline function for comparison |
| `-m MODULE` | Run a module as a script |
| `--sort` | Sort by `cumulative`, `tottime`, or `calls` (default: `cumulative`) |
| `--limit N` | Max functions to show (default: 20) |

Targets use importable names: `mymod:MyClass.method` or `mymod.func`.

### `profit timeit` — profile a statement in a loop

```bash
profit timeit 'sum(range(1000))'
```

With setup code:

```bash
profit timeit 'f()' --setup 'from mymod import f'
```

Focus on specific functions:

```bash
profit timeit 'f()' --setup 'from mymod import f' -p mymod:f
```

#### Options

| Flag | Description |
|------|-------------|
| `--setup STMT` | Setup statement (default: `pass`) |
| `-n N` | Number of executions (default: auto) |
| `-p TARGET` | Function to show (repeatable) |
| `-b TARGET` | Baseline function for comparison |
| `--sort` | Sort by `cumulative`, `tottime`, or `calls` (default: `cumulative`) |
| `--limit N` | Max functions to show (default: 20) |

### Global options

| Flag | Description |
|------|-------------|
| `--no-color` | Disable colored output |

### Python API

**Context manager** — profile a block of code:

```python
from step3 import profit

with profit as p:
    do_work()

p.print_stats()
```

**Decorator** — profile a specific function:

```python
from step3 import profit

@profit
def my_func():
    ...

my_func()
profit.print_stats()
```

## Requirements

- Python 3.12+
