Metadata-Version: 2.4
Name: ptop3
Version: 0.1.4
Summary: TUI process monitor that groups processes by application
License: MIT
Project-URL: Homepage, https://github.com/spazyCZ/ptop3
Project-URL: Repository, https://github.com/spazyCZ/ptop3
Project-URL: Changelog, https://github.com/spazyCZ/ptop3/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/spazyCZ/ptop3/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psutil>=5.9
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: bump-my-version; extra == "dev"
Dynamic: license-file

# ptop3

[![PyPI version](https://img.shields.io/pypi/v/ptop3.svg)](https://pypi.org/project/ptop3/)
[![Python versions](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13-blue)](https://pypi.org/project/ptop3/)
[![CI](https://github.com/spazyCZ/ptop3/actions/workflows/ci.yml/badge.svg)](https://github.com/spazyCZ/ptop3/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

An htop-like TUI process monitor that groups processes by application.

## Screenshots

![Group view](https://raw.githubusercontent.com/spazyCZ/ptop3/main/assets/printscreen_main.png)
*Main group view — processes grouped by application*

![Detail view](https://raw.githubusercontent.com/spazyCZ/ptop3/main/assets/Screenshot_group.png)
*Detail view — individual processes for a selected group*

![Tree view](https://raw.githubusercontent.com/spazyCZ/ptop3/main/assets/Screenshot_group_tree.png)
*Tree view — process hierarchy within a group*

## Features

- Groups processes by application name with smart alias resolution
- Colored header with memory, swap, load-average badges
- Sort by memory, CPU, RSS, swap, I/O, or count
- Regex filter across app name, process name, and cmdline
- Process tree view within a selected application group
- Kill signals (SIGTERM / SIGKILL) for individual processes or entire groups
- `w` key: clean swap by cycling swapoff/swapon (passwordless sudo)
- `d` key: drop kernel caches (passwordless sudo)
- Alerts for high CPU, memory, swap, disk usage, and zombie processes
- Lite mode (`--lite`) for lower overhead on busy systems

## Installation

```bash
pip install ptop3
```

## Quick Start

```bash
ptop3                 # interactive TUI
python -m ptop3       # same via module
ptop3 --once          # print one-shot table and exit
ptop3 --filter python # filter to python processes
```

## Sudo Setup

The `w` (swap-clean) and `d` (drop-caches) keys require root. Configure passwordless sudo once:

```bash
sudo ptop3 --init-subscripts
```

Or manually:

```bash
sudo visudo -f /etc/sudoers.d/ptop3
# Add:
# YOUR_USER ALL=(root) NOPASSWD: /path/to/ptop3-drop-caches
# YOUR_USER ALL=(root) NOPASSWD: /path/to/ptop3-swap-clean
```

Check sudo status:

```bash
ptop3 --check-sudo
```

## CLI Reference

| Flag | Default | Description |
|------|---------|-------------|
| `--once` | off | Print one-shot table and exit |
| `-f/--filter REGEX` | — | Filter by app/name/cmdline |
| `-s/--sort KEY` | `mem` | Sort key: mem, cpu, rss, swap, io, count |
| `-n/--top N` | 15 | Rows to show in `--once` mode |
| `--refresh SECS` | 2.0 | Refresh interval |
| `--lite` | off | Lite mode: skip cmdline/IO for tiny procs |
| `--check-sudo` | — | Check sudo config for subscripts |
| `--init-subscripts` | — | Write /etc/sudoers.d/ptop3 |

## Key Bindings

| Key | Action |
|-----|--------|
| `↑/↓` or `j/k` | Move selection |
| `PgUp/PgDn` | Page up/down |
| `Home/End` | Jump to first/last |
| `Enter` or `l` | Expand group to detail view |
| `h` | Back to group view |
| `t` | Toggle process tree (detail view) |
| `s` | Cycle sort key |
| `f` | Enter filter regex |
| `r` | Reset filter |
| `+/-` | Increase/decrease refresh interval |
| `k/K` | Send SIGTERM/SIGKILL to selected |
| `g` | Kill whole group (SIGTERM) |
| `w` | Run swap-clean |
| `d` | Drop caches |
| `q` or `Ctrl-C` | Quit |

## Subscripts

The privileged subscripts can also be run directly:

```bash
ptop3-drop-caches --help
ptop3-drop-caches --level 1 --dry-run

ptop3-swap-clean --help
ptop3-swap-clean --safety-mb 256 --dry-run
```

## Development

```bash
git clone https://github.com/spazyCZ/ptop3
cd ptop3
pip install -e ".[dev]"
pytest
ruff check ptop3/
```

## Branching Strategy

```
feature/xyz  ──PR──►  test  ──PR──►  main  ──tag v*.*.*──►  release
```

| Branch | Purpose |
|--------|---------|
| `feature/*` | Development — branch from `test`, PR back to `test` |
| `test` | Staging — CI gate + auto-publish to TestPyPI on merge |
| `main` | Production — only accepts PRs from `test`; tagged releases publish to PyPI |

## CI / CD

| Workflow | Trigger | Action |
|----------|---------|--------|
| CI | push / PR to `test` or `main` | ruff + pytest × Python 3.10–3.13 + Codecov |
| Claude Code Review | PR opened / updated | Automated code review |
| Claude Quality Gate | PR to `test` or `main` | Test coverage · changelog · security agents |
| Publish to TestPyPI | merge to `test` | Build + publish (skips existing versions) |
| Release | push tag `v*.*.*` | CI → GitHub Release with auto release notes |
| Publish to PyPI | **manual** (`workflow_dispatch`) | CI → publish to production PyPI |

### Release Process

1. Merge all feature PRs into `test` and verify on TestPyPI:
   ```bash
   pip install -i https://test.pypi.org/simple/ ptop3
   ```
2. Bump the version (run on `test`):
   ```bash
   bump-my-version bump patch   # or minor / major
   git push origin test
   ```
3. Open a PR from `test` → `main` and merge once CI is green.
4. Tag the release on `main`:
   ```bash
   git tag v0.x.y
   git push origin v0.x.y
   ```
   This creates the GitHub Release automatically.
5. Publish to PyPI manually: **Actions → Publish to PyPI → Run workflow** — enter the tag.
