Metadata-Version: 2.4
Name: py-spy-tui
Version: 0.1.2
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.
- `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.

## 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.

Build a local wheel:

```bash
uv build --wheel
```

Linux release wheels should be built as musllinux so they do not require the target machine's
glibc version:

```bash
just dist-linux-x86_64-musl
```

