You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Profile the memory usage of a Python script using memray and visualize a temporal flamegraph in the browser. Use when the user wants to investigate memory consumption, find leaks, or understand allocation patterns.
4
+
compatibility: Requires the pixi profiling environment (pixi run -e profiling). Supports Linux and macOS.
5
+
allowed-tools: Bash(pixi run -e profiling memray-run:*) Bash(pixi run -e profiling memray-flame:*) Bash(open:*) Bash(xdg-open:*) Bash(python -m webbrowser:*)
6
+
---
7
+
8
+
## Steps
9
+
10
+
1. Ask the user which script to profile (full or relative path).
11
+
12
+
2. Run the script under memray:
13
+
14
+
```bash
15
+
pixi run -e profiling memray-run script.py
16
+
```
17
+
18
+
This produces a binary file named `memray-script.py.<pid>.bin`in the current directory.
19
+
20
+
3. Generate the flamegraph HTML report from the `.bin` file:
21
+
22
+
```bash
23
+
pixi run -e profiling memray-flame memray-script.py.<pid>.bin
24
+
```
25
+
26
+
Replace `<pid>` with the actual PID shown in the filename. This writes `memray-flamegraph-script.py.<pid>.html`.
description: Profile Python import time using profimp and open a waterfall HTML report. Use when investigating slow startup or wanting to identify which imports are most expensive.
4
+
compatibility: Requires profimp (available as a pixi dependency). macOS or Linux.
description: Profile the execution time of a Python script using py-spy and visualize the result with speedscope. Use when the user wants to benchmark performance, find slow code paths, or profile CPU time.
4
+
compatibility: Requires the pixi profiling environment (pixi run -e profiling). Speedscope must be installed separately (npm install -g speedscope). sudo is required on macOS.
5
+
allowed-tools: Bash(pixi run -e profiling pyspy:*) Bash(pixi run -e profiling speedscope:*) Bash(sudo pixi run -e profiling pyspy:*)
6
+
---
7
+
8
+
## Steps
9
+
10
+
1. Ask the user which script to profile (full or relative path).
11
+
12
+
2. Run py-spy to record the profile. The output is always written to `profile.speedscope.json` in the current directory.
13
+
14
+
**Linux** (no sudo needed):
15
+
16
+
```bash
17
+
pixi run -e profiling pyspy script.py
18
+
```
19
+
20
+
**macOS** (sudo required — py-spy needs to attach to the process):
21
+
22
+
```bash
23
+
sudo pixi run -e profiling pyspy script.py
24
+
```
25
+
26
+
If sudo fails to find the pixi environment, use absolute paths:
27
+
28
+
```bash
29
+
sudo /path/to/.pixi/envs/profiling/bin/py-spy record --gil \
Running all the benchmarks is usually not needed. You run the benchmark using `asv run`. See the [asv documentation](https://asv.readthedocs.io/en/stable/commands.html#asv-run) for interesting arguments, like selecting the benchmarks you're interested in by providing a regex pattern `-b` or `--bench` that links to a function or class method e.g. the option `-b timeraw_import_inspect` selects the function `timeraw_import_inspect` in `benchmarks/spatialdata_benchmark.py`. You can run the benchmark in your current environment with `--python=same`. Some example benchmarks:
17
+
Running all the benchmarks is usually not needed. You run the benchmark using `asv run`. See the [asv documentation](https://asv.readthedocs.io/en/stable/commands.html#asv-run) for interesting arguments, like selecting the benchmarks you're interested in by providing a regex pattern `-b` or `--bench` that links to a function or class method. You can run the benchmark in your current environment with `--python=same`. Some example benchmarks:
18
18
19
-
Importing the SpatialData library can take around 4 seconds:
19
+
### Import time benchmarks
20
+
21
+
Import benchmarks live in `benchmarks/benchmark_imports.py`. Each `timeraw_*` function returns a Python code snippet that asv runs in a fresh interpreter (cold import, empty module cache):
22
+
23
+
Run all import benchmarks in your current environment:
20
24
21
25
```
22
-
PYTHONWARNINGS="ignore" asv run --python=same --show-stderr -b timeraw_import_inspect
asv run --python=same --show-stderr -b timeraw_import_spatialdata
33
+
```
34
+
35
+
### Comparing the current branch against `main`
36
+
37
+
The simplest way is `asv continuous`, which builds both commits, runs the benchmarks, and prints the comparison in one shot:
38
+
39
+
```bash
40
+
asv continuous --show-stderr -v -b timeraw main faster-import
30
41
```
31
42
43
+
Replace `faster-import` with any branch name or commit hash. The `-v` flag prints per-sample timings; drop it for a shorter summary.
44
+
45
+
Alternatively, collect results separately and compare afterwards:
46
+
47
+
```bash
48
+
# 1. Collect results for the tip of main and the tip of your branch
49
+
asv run --show-stderr -b timeraw main
50
+
asv run --show-stderr -b timeraw HEAD
51
+
52
+
# 2. Print a side-by-side comparison
53
+
asv compare main HEAD
54
+
```
55
+
56
+
Both approaches build isolated environments from scratch. If you prefer to skip the rebuild and reuse your current environment (faster, less accurate):
57
+
58
+
```bash
59
+
asv run --python=same --show-stderr -b timeraw HEAD
60
+
61
+
git stash && git checkout main
62
+
asv run --python=same --show-stderr -b timeraw HEAD
63
+
git checkout - && git stash pop
64
+
65
+
asv compare main HEAD
66
+
```
67
+
68
+
### Querying benchmarks
69
+
32
70
Querying using a bounding box without a spatial index is highly impacted by large amounts of points (transcripts), more than table rows (cells).
33
71
34
72
```
35
-
$ PYTHONWARNINGS="ignore" asv run --python=same --show-stderr -b time_query_bounding_box
73
+
$ asv run --python=same --show-stderr -b time_query_bounding_box
0 commit comments