procclean 1.2.0__tar.gz

procclean-1.2.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: procclean
+Version: 1.2.0
+Summary: Interactive TUI for exploring and cleaning up processes - find orphans, memory hogs, and kill them
+Keywords: cleanup,kill,memory,orphan,process,terminal,tui
+Author: Kaj Kowalski
+Author-email: Kaj Kowalski <info@kajkowalski.nl>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Dist: psutil>=7.2.1
+Requires-Dist: tabulate>=0.9.0
+Requires-Dist: textual>=7.0.0
+Requires-Python: >=3.14
+Project-URL: Homepage, https://procclean.kjanat.com
+Project-URL: Repository, https://github.com/kjanat/procclean
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="logo/procclean-transparent.svg" alt="procclean" width="500">
+</p>
+
+<p align="center">
+  <em>Interactive TUI for exploring and cleaning up processes - find orphans, memory hogs, and kill them.</em>
+</p>
+
+<p align="center">
+  <a href="https://github.com/kjanat/procclean/blob/master/LICENSE"><img src="https://img.shields.io/github/license/kjanat/procclean" alt="License"></a>
+  <a href="https://github.com/kjanat/procclean/releases"><img src="https://img.shields.io/github/v/release/kjanat/procclean" alt="Release"></a>
+  <img src="https://img.shields.io/badge/python-3.14%2B-blue" alt="Python 3.14+">
+  <img src="https://img.shields.io/badge/platform-linux-lightgrey" alt="Linux">
+</p>
+
+## Features
+
+- **Memory overview** - Real-time total/used/free/swap display
+- **Multiple views** - All processes, Orphaned, Process Groups, High Memory
+  (>500MB)
+- **Orphan detection** - Finds processes whose parent died (PPID=1)
+- **Tmux awareness** - Won't flag tmux processes as orphan candidates
+- **Batch operations** - Select multiple processes and kill them at once
+- **Process grouping** - Find duplicate/similar processes consuming resources
+- **CLI mode** - Scriptable commands with JSON/CSV/Markdown output
+
+## Installation
+
+```bash
+uv tool install git+https://github.com/kjanat/procclean
+```
+
+Or run directly:
+
+```bash
+uvx git+https://github.com/kjanat/procclean
+```
+
+## Usage
+
+### TUI Mode (default)
+
+```bash
+procclean
+```
+
+### CLI Commands
+
+```bash
+procclean list                      # List processes (table)
+procclean list -f json|csv|md       # Different output formats
+procclean list -s mem|cpu|pid|name|cwd  # Sort by field
+procclean list -o                   # Orphans only
+procclean list -m                   # High memory only
+procclean list -k                   # Killable orphans only
+procclean list --cwd                # Filter by current directory
+procclean list --cwd /path/to/dir   # Filter by specific cwd
+
+procclean groups                    # Show process groups
+
+procclean kill <PID> [PID...]       # Kill process(es)
+procclean kill -f <PID>             # Force kill (SIGKILL)
+procclean kill --cwd /path -y       # Kill all in cwd (skip confirm)
+procclean kill -k -y                # Kill all killable orphans
+procclean kill -k --preview         # Preview what would be killed
+
+procclean mem                       # Show memory summary
+```
+
+## TUI Keybindings
+
+| Key     | Action                  |
+| ------- | ----------------------- |
+| `q`     | Quit                    |
+| `r`     | Refresh                 |
+| `k`     | Kill selected (SIGTERM) |
+| `K`     | Force kill (SIGKILL)    |
+| `o`     | Show orphans            |
+| `a`     | Show all                |
+| `g`     | Show groups             |
+| `w`     | Filter by selected cwd  |
+| `W`     | Clear cwd filter        |
+| `Space` | Toggle selection        |
+| `s`     | Select all visible      |
+| `c`     | Clear selection         |
+| `1`     | Sort by memory          |
+| `2`     | Sort by CPU             |
+| `3`     | Sort by PID             |
+| `4`     | Sort by name            |
+| `5`     | Sort by cwd             |
+| `!`     | Reverse sort order      |
+
+## Views
+
+- **All Processes** - All user processes sorted by memory usage
+- **Orphaned** - Processes with PPID=1 (parent died)
+- **Process Groups** - Similar processes grouped together
+- **High Memory** - Processes using >500MB RAM
+
+## Output Formats
+
+CLI supports multiple output formats via `-f`:
+
+- `table` - Human-readable table (default)
+- `json` - JSON array for scripting
+- `csv` - CSV for spreadsheets
+- `md` - Markdown table
+
+## Requirements
+
+- Python 3.14+
+- Linux (uses `/proc` filesystem)
+
+## Development
+
+```bash
+git clone https://github.com/kjanat/procclean
+cd procclean
+uv sync
+uv run pre-commit install
+```
+
+Run tests:
+
+```bash
+uv run pytest
+```
+
+## License
+
+[MIT][license]
+
+<!--link definitions-->
+
+[license]: https://github.com/kjanat/procclean/blob/master/LICENSE "MIT License"
+
+<!--markdownlint-disable-file MD033 MD041-->

procclean-1.2.0/README.md

@@ -0,0 +1,137 @@
+<p align="center">
+  <img src="logo/procclean-transparent.svg" alt="procclean" width="500">
+</p>
+
+<p align="center">
+  <em>Interactive TUI for exploring and cleaning up processes - find orphans, memory hogs, and kill them.</em>
+</p>
+
+<p align="center">
+  <a href="https://github.com/kjanat/procclean/blob/master/LICENSE"><img src="https://img.shields.io/github/license/kjanat/procclean" alt="License"></a>
+  <a href="https://github.com/kjanat/procclean/releases"><img src="https://img.shields.io/github/v/release/kjanat/procclean" alt="Release"></a>
+  <img src="https://img.shields.io/badge/python-3.14%2B-blue" alt="Python 3.14+">
+  <img src="https://img.shields.io/badge/platform-linux-lightgrey" alt="Linux">
+</p>
+
+## Features
+
+- **Memory overview** - Real-time total/used/free/swap display
+- **Multiple views** - All processes, Orphaned, Process Groups, High Memory
+  (>500MB)
+- **Orphan detection** - Finds processes whose parent died (PPID=1)
+- **Tmux awareness** - Won't flag tmux processes as orphan candidates
+- **Batch operations** - Select multiple processes and kill them at once
+- **Process grouping** - Find duplicate/similar processes consuming resources
+- **CLI mode** - Scriptable commands with JSON/CSV/Markdown output
+
+## Installation
+
+```bash
+uv tool install git+https://github.com/kjanat/procclean
+```
+
+Or run directly:
+
+```bash
+uvx git+https://github.com/kjanat/procclean
+```
+
+## Usage
+
+### TUI Mode (default)
+
+```bash
+procclean
+```
+
+### CLI Commands
+
+```bash
+procclean list                      # List processes (table)
+procclean list -f json|csv|md       # Different output formats
+procclean list -s mem|cpu|pid|name|cwd  # Sort by field
+procclean list -o                   # Orphans only
+procclean list -m                   # High memory only
+procclean list -k                   # Killable orphans only
+procclean list --cwd                # Filter by current directory
+procclean list --cwd /path/to/dir   # Filter by specific cwd
+
+procclean groups                    # Show process groups
+
+procclean kill <PID> [PID...]       # Kill process(es)
+procclean kill -f <PID>             # Force kill (SIGKILL)
+procclean kill --cwd /path -y       # Kill all in cwd (skip confirm)
+procclean kill -k -y                # Kill all killable orphans
+procclean kill -k --preview         # Preview what would be killed
+
+procclean mem                       # Show memory summary
+```
+
+## TUI Keybindings
+
+| Key     | Action                  |
+| ------- | ----------------------- |
+| `q`     | Quit                    |
+| `r`     | Refresh                 |
+| `k`     | Kill selected (SIGTERM) |
+| `K`     | Force kill (SIGKILL)    |
+| `o`     | Show orphans            |
+| `a`     | Show all                |
+| `g`     | Show groups             |
+| `w`     | Filter by selected cwd  |
+| `W`     | Clear cwd filter        |
+| `Space` | Toggle selection        |
+| `s`     | Select all visible      |
+| `c`     | Clear selection         |
+| `1`     | Sort by memory          |
+| `2`     | Sort by CPU             |
+| `3`     | Sort by PID             |
+| `4`     | Sort by name            |
+| `5`     | Sort by cwd             |
+| `!`     | Reverse sort order      |
+
+## Views
+
+- **All Processes** - All user processes sorted by memory usage
+- **Orphaned** - Processes with PPID=1 (parent died)
+- **Process Groups** - Similar processes grouped together
+- **High Memory** - Processes using >500MB RAM
+
+## Output Formats
+
+CLI supports multiple output formats via `-f`:
+
+- `table` - Human-readable table (default)
+- `json` - JSON array for scripting
+- `csv` - CSV for spreadsheets
+- `md` - Markdown table
+
+## Requirements
+
+- Python 3.14+
+- Linux (uses `/proc` filesystem)
+
+## Development
+
+```bash
+git clone https://github.com/kjanat/procclean
+cd procclean
+uv sync
+uv run pre-commit install
+```
+
+Run tests:
+
+```bash
+uv run pytest
+```
+
+## License
+
+[MIT][license]
+
+<!--link definitions-->
+
+[license]: https://github.com/kjanat/procclean/blob/master/LICENSE "MIT License"
+
+<!--markdownlint-disable-file MD033 MD041-->

procclean-1.2.0/pyproject.toml

@@ -0,0 +1,89 @@
+#:schema https://json.schemastore.org/pyproject.json
+#:tombi schema.strict = true
+
+[project]
+name = "procclean"
+version = "1.2.0"
+description = "Interactive TUI for exploring and cleaning up processes - find orphans, memory hogs, and kill them"
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+authors = [{ name = "Kaj Kowalski", email = "info@kajkowalski.nl" }]
+keywords = ["cleanup", "kill", "memory", "orphan", "process", "terminal", "tui"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: System Administrators",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: System :: Monitoring",
+  "Topic :: System :: Systems Administration",
+  "Topic :: Utilities",
+]
+dependencies = [
+  "psutil>=7.2.1",
+  "tabulate>=0.9.0",
+  "textual>=7.0.0",
+]
+
+[project.urls]
+Homepage = "https://procclean.kjanat.com"
+Repository = "https://github.com/kjanat/procclean"
+
+[project.scripts]
+procclean = "procclean:main"
+
+[dependency-groups]
+dev = [
+  "pre-commit>=4.5.1",
+]
+lint = [
+  "pylint>=4.0.4",
+  "ruff>=0.14.10",
+  "tombi>=0.7.14",
+  "ty>=0.0.8",
+]
+mypy = [
+  "mypy>=1.19.1",
+  "types-psutil>=7.2.1.20251231",
+  "types-tabulate>=0.9.0.20241207",
+]
+site = [
+  "markdown-it-py[plugins]>=4.0.0",
+  "mkdocs>=1.6.1",
+  "mkdocs-material[imaging]>=9.7.1",
+  "mkdocs-rich-argparse",
+]
+test = [
+  "pytest>=9.0.2",
+  "pytest-asyncio>=1.3.0",
+  "pytest-cov>=7.0.0",
+  "pytest-xdist[psutil]>=3.8.0",
+]
+tui = [
+  "textual-dev>=1.8.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.21,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.pytest]
+addopts = ["-n", "logical"]
+asyncio_mode = "strict"
+
+[tool.uv]
+environments = ["sys_platform == 'linux'"]
+default-groups = "all"
+
+[tool.uv.sources]
+mkdocs-rich-argparse = { git = "https://github.com/kjanat/mkdocs_rich_argparse.git", branch = "prog-style" }
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true

procclean-1.2.0/src/procclean/__init__.py

@@ -0,0 +1,11 @@
+"""Process cleanup TUI application."""
+
+from importlib.metadata import version
+
+__version__ = version("procclean")
+
+# Re-export main entry point and core types
+from procclean.__main__ import main
+from procclean.core import ProcessInfo
+
+__all__ = ["ProcessInfo", "__version__", "main"]

procclean-1.2.0/src/procclean/__main__.py

@@ -0,0 +1,22 @@
+"""Entry point for procclean - runs as python -m procclean or via console script."""
+
+from .cli import run_cli
+from .tui import ProcessCleanerApp
+
+
+def main() -> None:
+    """Dispatch to CLI or run TUI.
+
+    Raises:
+        SystemExit: When CLI command returns non-zero exit code.
+    """
+    result = run_cli()
+    if result == -1:
+        # No subcommand - run TUI
+        ProcessCleanerApp().run()
+    else:
+        raise SystemExit(result)
+
+
+if __name__ == "__main__":
+    main()

procclean-1.2.0/src/procclean/cli/__init__.py

@@ -0,0 +1,27 @@
+"""CLI interface for procclean."""
+
+# Internal helpers - exported for testing
+from .commands import (
+    _confirm_kill,
+    _do_preview,
+    _get_kill_targets,
+    cmd_groups,
+    cmd_kill,
+    cmd_list,
+    cmd_memory,
+    get_filtered_processes,
+)
+from .parser import create_parser, run_cli
+
+__all__ = [
+    "_confirm_kill",
+    "_do_preview",
+    "_get_kill_targets",
+    "cmd_groups",
+    "cmd_kill",
+    "cmd_list",
+    "cmd_memory",
+    "create_parser",
+    "get_filtered_processes",
+    "run_cli",
+]

procclean-1.2.0/src/procclean/cli/commands.py

@@ -0,0 +1,213 @@
+"""CLI command handlers."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from rich import print  # pylint: disable=redefined-builtin
+
+from procclean.core import (
+    PREVIEW_LIMIT,
+    filter_by_cwd,
+    filter_high_memory,
+    filter_killable,
+    filter_orphans,
+    find_similar_processes,
+    get_memory_summary,
+    get_process_list,
+    kill_processes,
+    sort_processes,
+)
+from procclean.formatters import format_output
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    """List processes command.
+
+    Returns:
+        int: Exit code (0 on success).
+    """
+    procs = get_filtered_processes(args)
+
+    # Apply sorting
+    reverse = not args.ascending
+    procs = sort_processes(procs, sort_by=args.sort, reverse=reverse)
+
+    # Limit output
+    if args.limit:
+        procs = procs[: args.limit]
+
+    # Parse columns
+    columns = args.columns.split(",") if args.columns else None
+
+    print(format_output(procs, args.format, columns=columns))
+    return 0
+
+
+def cmd_groups(args: argparse.Namespace) -> int:
+    """Show grouped processes command.
+
+    Returns:
+        int: Exit code (0 on success).
+    """
+    procs = get_process_list(min_memory_mb=args.min_memory)
+    groups = find_similar_processes(procs)
+
+    if not groups:
+        print("No process groups found.")
+        return 0
+
+    if args.format == "json":
+        data = {
+            cmd: [
+                {"pid": p.pid, "name": p.name, "rss_mb": round(p.rss_mb, 2)}
+                for p in group_procs
+            ]
+            for cmd, group_procs in groups.items()
+        }
+        print(json.dumps(data, indent=2))
+    else:
+        for cmd, group_procs in sorted(
+            groups.items(), key=lambda x: sum(p.rss_mb for p in x[1]), reverse=True
+        ):
+            total_mb = sum(p.rss_mb for p in group_procs)
+            print(f"\n{cmd} ({len(group_procs)} processes, {total_mb:.1f} MB total)")
+            for p in sorted(group_procs, key=lambda x: x.rss_mb, reverse=True):
+                print(f"  PID {p.pid}: {p.rss_mb:.1f} MB")
+
+    return 0
+
+
+def get_filtered_processes(args: argparse.Namespace) -> list:
+    """Get processes with all filters from args applied.
+
+    Returns:
+        list: Filtered list of processes.
+    """
+    procs = get_process_list(min_memory_mb=getattr(args, "min_memory", 5.0))
+
+    # Apply cwd filter
+    if getattr(args, "cwd", None) is not None:
+        cwd_path = args.cwd or str(Path.cwd())
+        procs = filter_by_cwd(procs, cwd_path)
+
+    # Apply preset filters
+    filt = getattr(args, "filter", None)
+    threshold = getattr(args, "high_memory_threshold", 500.0)
+    if filt == "killable" or getattr(args, "killable", False):
+        procs = filter_killable(procs)
+    elif filt == "orphans" or getattr(args, "orphans", False):
+        procs = filter_orphans(procs)
+    elif filt == "high-memory" or getattr(args, "high_memory", False):
+        procs = filter_high_memory(procs, threshold_mb=threshold)
+
+    return procs
+
+
+def _get_kill_targets(args: argparse.Namespace) -> list:
+    """Get target processes for kill command from PIDs or filters.
+
+    Returns:
+        list: Target processes to kill.
+    """
+    if args.pids:
+        all_procs = get_process_list(min_memory_mb=0)
+        pid_set = set(args.pids)
+        procs = [p for p in all_procs if p.pid in pid_set]
+        found_pids = {p.pid for p in procs}
+        for pid in args.pids:
+            if pid not in found_pids:
+                print(f"Warning: PID {pid} not found")
+        return procs
+    return get_filtered_processes(args)
+
+
+def _do_preview(args: argparse.Namespace, procs: list) -> int:
+    """Show preview of what would be killed.
+
+    Returns:
+        int: Exit code (0 on success).
+    """
+    if hasattr(args, "sort") and args.sort:
+        procs = sort_processes(procs, sort_by=args.sort, reverse=True)
+    if hasattr(args, "limit") and args.limit:
+        procs = procs[: args.limit]
+    columns = args.columns.split(",") if getattr(args, "columns", None) else None
+    fmt = getattr(args, "out_format", "table")
+    print(format_output(procs, fmt, columns=columns))
+    print(f"\n{len(procs)} process(es) would be killed.")
+    return 0
+
+
+def _confirm_kill(args: argparse.Namespace, procs: list) -> bool:
+    """Prompt for kill confirmation.
+
+    Args:
+        args: Parsed CLI arguments.
+        procs: Processes that would be killed.
+
+    Returns:
+        True if the kill action is confirmed (or confirmation is skipped), otherwise
+        False.
+    """
+    if args.yes or not sys.stdin.isatty():
+        return True
+    action = "FORCE KILL" if args.force else "terminate"
+    print(f"About to {action} {len(procs)} process(es):")
+    for p in procs[:PREVIEW_LIMIT]:
+        print(f"  {p.pid}: {p.name} ({p.rss_mb:.1f} MB)")
+    if len(procs) > PREVIEW_LIMIT:
+        print(f"  ... and {len(procs) - PREVIEW_LIMIT} more")
+    try:
+        response = input("Continue? [y/N] ")
+        return response.lower() in {"y", "yes"}
+    except EOFError:
+        return True  # Non-interactive
+
+
+def cmd_kill(args: argparse.Namespace) -> int:
+    """Kill processes command.
+
+    Returns:
+        int: Exit code (0 on success).
+    """
+    procs = _get_kill_targets(args)
+    if not procs:
+        print("No processes match the filters.")
+        return 0
+
+    if getattr(args, "preview", False):
+        return _do_preview(args, procs)
+
+    if not _confirm_kill(args, procs):
+        print("Aborted.")
+        return 1
+
+    results = kill_processes([p.pid for p in procs], force=args.force)
+    exit_code = 0
+    for _, success, msg in results:
+        status = "OK" if success else "FAILED"
+        print(f"[{status}] {msg}")
+        if not success:
+            exit_code = 1
+    return exit_code
+
+
+def cmd_memory(args: argparse.Namespace) -> int:
+    """Show memory summary command.
+
+    Returns:
+        int: Exit code (0 on success).
+    """
+    mem = get_memory_summary()
+
+    if args.format == "json":
+        print(json.dumps(mem, indent=2))
+    else:
+        print(f"Total:  {mem['total_gb']:.2f} GB")
+        print(f"Used:   {mem['used_gb']:.2f} GB ({mem['percent']:.1f}%)")
+        print(f"Free:   {mem['free_gb']:.2f} GB")
+        print(f"Swap:   {mem['swap_used_gb']:.2f} / {mem['swap_total_gb']:.2f} GB")
+
+    return 0