Metadata-Version: 2.4
Name: py-spy-tui
Version: 0.1.10
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Testing
Requires-Dist: py-spy>=0.4.2,<0.5
Summary: A friendly ratatui interface for py-spy
Author-email: Vadym Stupakov <vadim.stupakov@gmail.com>
License-Expression: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/Red-Eyed/py-spy-tui
Project-URL: Repository, https://github.com/Red-Eyed/py-spy-tui

# py-spy-tui

A Rust terminal UI for `py-spy`, packaged so users can install it with:

```bash
pip install py-spy-tui
py-spy-tui
```

`py-spy-tui` depends on the `py-spy` Python package, so installing the TUI also installs
the profiler binary on supported platforms.

## Current Features

- Groups Python processes by distributed training metadata, process tree, runtime prefix,
  working directory, and command fingerprint.
- Detects virtualenv, uv-managed Python, Conda, pyenv, and system runtimes.
- Shows PyTorch rank metadata when process environment is readable.
- Explains Linux rootless profiling setup before asking sudo to attach to a process.
- Uses `sudo -v` for authentication and never reads or stores a password.

## Usage

```bash
py-spy-tui
```

Non-interactive checks:

```bash
py-spy-tui --help
py-spy-tui --version
```

Keys:

- `Enter`: record the selected process or process group for 30 seconds.
- `d`: run `py-spy dump` for the selected process or process group.
- `t`: run live `py-spy top` for the selected process.
- `r`: refresh process groups.
- `Space`: expand or collapse a group.
- `j` / `k` or arrow keys: move selection.
- `PageUp` / `PageDown`: scroll output.
- `q`: quit.

When a group is selected, `py-spy-tui` runs one `py-spy` command per process. This is useful
for `torchrun` and distributed PyTorch training, where ranks are often sibling processes
rather than children of a single attach target.

Live top is available for one selected process at a time. For multiprocessing and torchrun/DDP
sibling ranks, use group recording.

## Reports

Every record run creates a recognizable report folder in the current directory:

```text
py-spy-report-<target-name>-<unix-timestamp>/
  raw/
    pid-1234.svg
    pid-1235.svg
  report.md
  report.json
```

The `raw/` folder keeps py-spy's original SVG records. `report.md` is written for humans,
and `report.json` is structured so you can pass the folder to an LLM and ask it to compare
hot frames, rank imbalance, blocking stacks, and data-loading stalls.

## Linux Rootless Profiling

Attaching to an existing process often requires elevated permissions on Linux. To allow
same-user profiling without sudo:

```bash
sudo sysctl kernel.yama.ptrace_scope=0
```

To keep that setting after reboot:

```bash
echo 'kernel.yama.ptrace_scope=0' | sudo tee /etc/sysctl.d/10-py-spy-tui.conf
sudo sysctl --system
```

This changes system-wide ptrace policy for same-user debugging. Use sudo from the TUI when
you prefer not to change the host setting.

## Build

Local full check:

```bash
just build-all
```

That runs formatting, tests, clippy, clears `dist/`, builds a wheel, and smoke-checks it.
It also runs `just verify-dist`, which fails unless `dist/` contains only wheels and includes
the required macOS and Linux manylinux x86_64/aarch64 wheel tags.

Build a local wheel:

```bash
just dist-local
```

Linux release wheels are built as manylinux wheels with Zig so they work on most supported
Linux distributions:

```bash
just dist-linux-x86_64
just dist-linux-aarch64
```

Check release artifacts without rebuilding:

```bash
just verify-dist
```

