Metadata-Version: 2.4
Name: which-profiler
Version: 0.1.0
Summary: Which Python profiler fits your workload? Filter by focus, attach mode, and more; get a runnable command.
Project-URL: Homepage, https://ep2026.europython.eu/session/uvx-which-profiler-which-profiler-when/
Project-URL: Repository, https://github.com/jstriebel/which-profiler
Project-URL: Issues, https://github.com/jstriebel/which-profiler/issues
Author-email: Jonathan Striebel <jonathan.striebel@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,europython,performance,profiler,profiling
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: System :: Benchmark
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: typer>=0.15
Description-Content-Type: text/markdown

# which-profiler

Which Python profiler fits your workload? Filter by focus, attach mode, and
more; get a runnable command.

## What it does

A **filtered catalog**: describe your workload (what you care about, attach
vs launch, target Python) and `which-profiler` narrows the options and
**ranks the profilers by measured overhead**. Each entry prints a
copy-paste-runnable `uv`-based command & useful information.

## Install

```bash
uvx which-profiler            # run without installing
uv tool install which-profiler
```

Only runtime dependency is `typer`. Runs on Python 3.10+.

## Usage

```bash
which-profiler                          # interactive: one question, ranked catalog
which-profiler --nosy                   # interactive: also asks attach/python/native/view/rate
which-profiler --all                    # full landscape (incompatible tools tagged, not hidden)
which-profiler --focus time --python 3.15
which-profiler pytest                   # bare console-command target
which-profiler python -m my_module      # same, python-invocation form
which-profiler --focus memory -- script.py --arg   # script target after --
which-profiler --pid 12345              # attach-capable tools only
which-profiler --tool py-spy pytest     # exactly this tool (py-spy or py_spy both work)
which-profiler --focus time --view flamegraph --run pytest   # build + run top pick
which-profiler --focus time --json      # machine-readable, no prompts
```

## The talk

Come see **"uvx which-profiler: Which Profiler, When?"** at EuroPython 2026:

EuroPython 2026, Kraków

📍 **Room S2**

📅 **Wednesday, 15 July 2026**

🕐 **15:25**

👉 https://ep2026.europython.eu/session/uvx-which-profiler-which-profiler-when/

## Potential profilers to include in the future

- [line_profiler](https://github.com/pyutils/line_profiler)
- [Austin](https://github.com/P403n1x87/austin)
- [Yappi](https://github.com/sumerc/yappi)
- [Fil](https://github.com/pythonspeed/filprofiler)
- [Guppy3](https://github.com/zhuyifei1999/guppy3)

## Development

Setup via [mise](https://mise.jdx.dev):
```bash
mise run install
```

```bash
mise run fix
mise run check
mise run test       # uv run pytest in dev venv (.venv, pinned to .python-version)
mise run test-all   # full matrix: root tests on 3.10-3.15 + examples tests on 3.14
```

`test-all` runs `scripts/test-matrix.sh`, which tests each supported Python in
its own isolated venv under `.venvs/py<version>/` (gitignored) so the shared
dev `.venv` is never resynced to a different interpreter. It prints a
`python -> pass/fail/skip` summary table at the end; 3.15 (still prerelease)
degrades a dependency-install failure to a recorded skip instead of a hard
failure.

## Where the numbers come from

Overhead ranking is based on a benchmark from 2026-07-13:
ThinkPad X1 Carbon Gen5, all samplers forced to 100 Hz for
parity, median-of-7 repeats, over a tight numeric loop and a call-dense
workload. The CLI (and `--json`) only show the coarse category
(negligible/low/moderate/high); reproducible scripts and further measurements
will come later.
