procclean 1.2.0__py3-none-any.whl

procclean/core/process.py

@@ -0,0 +1,160 @@
+"""Process listing and grouping utilities."""
+
+import os
+from pathlib import Path
+
+import psutil
+
+from .models import ProcessInfo
+
+
+def get_tmux_env(pid: int) -> bool:
+    """Check whether the process has a TMUX environment variable.
+
+    Args:
+        pid: Process ID.
+
+    Returns:
+        True if the process environment contains ``TMUX=``, otherwise False.
+    """
+    try:
+        environ_path = Path(f"/proc/{pid}/environ")
+        if environ_path.exists():
+            environ = environ_path.read_bytes().decode("utf-8", errors="ignore")
+            return "TMUX=" in environ
+    except (PermissionError, FileNotFoundError, ProcessLookupError):
+        pass
+    return False
+
+
+def get_cwd(pid: int) -> str:
+    """Get process working directory.
+
+    Args:
+        pid: Process ID.
+
+    Returns:
+        The resolved current working directory for the process, or "?" if it
+        cannot be determined due to permissions or the process no longer
+        existing.
+    """
+    try:
+        return str(Path(f"/proc/{pid}/cwd").readlink())
+    except (PermissionError, FileNotFoundError, ProcessLookupError):
+        return "?"
+
+
+def get_process_list(
+    sort_by: str = "memory",
+    filter_user: str | None = None,
+    min_memory_mb: float = 10.0,
+) -> list[ProcessInfo]:
+    """Get list of processes with detailed info.
+
+    Args:
+        sort_by: Field to sort by ("memory", "cpu", or "name").
+        filter_user: Only include processes owned by this user. Defaults to the
+            current user.
+        min_memory_mb: Minimum RSS (in MB) for a process to be included.
+
+    Returns:
+        A list of ProcessInfo entries matching the filters, sorted by ``sort_by``.
+    """
+    processes = []
+    current_user = os.getlogin()
+    filter_user = filter_user or current_user
+
+    for proc in psutil.process_iter([
+        "pid",
+        "name",
+        "cmdline",
+        "ppid",
+        "memory_info",
+        "cpu_percent",
+        "username",
+        "create_time",
+        "status",
+    ]):
+        try:
+            info = proc.info
+            if info["username"] != filter_user:
+                continue
+
+            rss_mb = (
+                (info["memory_info"].rss / 1024 / 1024) if info["memory_info"] else 0
+            )
+            if rss_mb < min_memory_mb:
+                continue
+
+            ppid = info["ppid"] or 0
+            try:
+                parent = psutil.Process(ppid)
+                parent_name = parent.name()
+            except (psutil.NoSuchProcess, psutil.AccessDenied):
+                parent_name = "?"
+
+            # Check if orphaned (parent is init/systemd)
+            is_orphan = ppid == 1 or parent_name in {"systemd", "init"}
+
+            cmdline = " ".join(info["cmdline"] or [])[:200]
+            if not cmdline:
+                cmdline = info["name"]
+
+            processes.append(
+                ProcessInfo(
+                    pid=info["pid"],
+                    name=info["name"],
+                    cmdline=cmdline,
+                    cwd=get_cwd(info["pid"]),
+                    ppid=ppid,
+                    parent_name=parent_name,
+                    rss_mb=rss_mb,
+                    cpu_percent=info["cpu_percent"] or 0,
+                    username=info["username"],
+                    create_time=info["create_time"] or 0,
+                    is_orphan=is_orphan,
+                    in_tmux=get_tmux_env(info["pid"]) if is_orphan else False,
+                    status=info["status"] or "?",
+                )
+            )
+        except (psutil.NoSuchProcess, psutil.AccessDenied, psutil.ZombieProcess):
+            continue
+
+    if sort_by == "memory":
+        processes.sort(key=lambda p: p.rss_mb, reverse=True)
+    elif sort_by == "cpu":
+        processes.sort(key=lambda p: p.cpu_percent, reverse=True)
+    elif sort_by == "name":
+        processes.sort(key=lambda p: p.name.lower())
+
+    return processes
+
+
+def find_similar_processes(
+    processes: list[ProcessInfo],
+) -> dict[str, list[ProcessInfo]]:
+    """Group processes by similar command patterns.
+
+    Args:
+        processes: Processes to group.
+
+    Returns:
+        A mapping of group keys (normalized executable/command names) to the list
+        of processes in that group. Only groups containing more than one process
+        are returned.
+    """
+    groups: dict[str, list[ProcessInfo]] = {}
+
+    for proc in processes:
+        # Extract key identifier from cmdline
+        cmd = proc.cmdline.split()[0] if proc.cmdline else proc.name
+        # Normalize paths
+        if "/" in cmd:
+            cmd = cmd.split("/")[-1]
+
+        if cmd not in groups:
+            groups[cmd] = []
+        groups[cmd].append(proc)
+
+    # Only return groups with multiple processes
+    return {k: v for k, v in groups.items() if len(v) > 1}

procclean/formatters/__init__.py

@@ -0,0 +1,33 @@
+"""Output formatters for process data."""
+
+from .columns import (
+    COLUMNS,
+    DEFAULT_COLUMNS,
+    ClipSide,
+    ColumnSpec,
+    clip,
+    get_available_columns,
+)
+from .output import (
+    format_csv,
+    format_json,
+    format_markdown,
+    format_output,
+    format_table,
+    get_rows,
+)
+
+__all__ = [
+    "COLUMNS",
+    "DEFAULT_COLUMNS",
+    "ClipSide",
+    "ColumnSpec",
+    "clip",
+    "format_csv",
+    "format_json",
+    "format_markdown",
+    "format_output",
+    "format_table",
+    "get_available_columns",
+    "get_rows",
+]

procclean/formatters/columns.py

@@ -0,0 +1,128 @@
+"""Column specifications for process tables."""
+
+from collections.abc import Callable
+from dataclasses import dataclass, replace
+from enum import StrEnum, auto
+from typing import Self
+
+from procclean.core import ProcessInfo
+
+
+class ClipSide(StrEnum):
+    """Which side to truncate when clipping."""
+
+    LEFT = auto()  # Keep right portion (good for paths)
+    RIGHT = auto()  # Keep left portion (good for names)
+
+
+def clip(s: str, max_len: int, side: ClipSide = ClipSide.RIGHT) -> str:
+    """Truncate string, adding ellipsis on clipped side.
+
+    Args:
+        s: Input string to potentially clip.
+        max_len: Maximum length of returned string, including ellipsis.
+        side: Which side to truncate when clipping.
+
+    Returns:
+        The original string if it fits within ``max_len``; otherwise a clipped
+        version with an ellipsis on the clipped side.
+    """
+    if len(s) <= max_len:
+        return s
+    match side:
+        case ClipSide.LEFT:
+            return f"...{s[-(max_len - 3) :]}"
+        case ClipSide.RIGHT:
+            return f"{s[: max_len - 3]}..."
+
+
+@dataclass(frozen=True, slots=True)
+class ColumnSpec[T]:
+    """Specification for a table column."""
+
+    key: str
+    header: str
+    get: Callable[[ProcessInfo], T]
+    fmt: Callable[[T], str] = str
+    max_width: int | None = None
+    clip_side: ClipSide = ClipSide.RIGHT
+
+    def extract(self, proc: ProcessInfo) -> str:
+        """Extract and format value from a process.
+
+        Args:
+            proc: Process to extract the value from.
+
+        Returns:
+            The formatted value, clipped with an ellipsis if it exceeds
+            ``max_width``.
+        """
+        formatted = self.fmt(self.get(proc))
+        if self.max_width and len(formatted) > self.max_width:
+            return clip(formatted, self.max_width, self.clip_side)
+        return formatted
+
+    def with_width(self, width: int, side: ClipSide = ClipSide.RIGHT) -> Self:
+        """Return a copy with specified max width and clip side.
+
+        Args:
+            width: Maximum width for the column output.
+            side: Which side to truncate when clipping.
+
+        Returns:
+            A new ``ColumnSpec`` with ``max_width`` and ``clip_side`` set.
+        """
+        return replace(self, max_width=width, clip_side=side)
+
+
+def _fmt_float1(v: float) -> str:
+    return f"{v:.1f}"
+
+
+def _fmt_status(p: ProcessInfo) -> str:
+    parts = [p.status]
+    if p.is_orphan:
+        parts.append("[orphan]")
+    if p.in_tmux:
+        parts.append("[tmux]")
+    return " ".join(parts)
+
+
+# Column definitions
+COLUMNS: dict[str, ColumnSpec] = {
+    "pid": ColumnSpec("pid", "PID", lambda p: p.pid),
+    "name": ColumnSpec("name", "Name", lambda p: p.name, max_width=25),
+    "rss_mb": ColumnSpec("rss_mb", "RAM (MB)", lambda p: p.rss_mb, _fmt_float1),
+    "cpu_percent": ColumnSpec(
+        "cpu_percent", "CPU%", lambda p: p.cpu_percent, _fmt_float1
+    ),
+    "cwd": ColumnSpec(
+        "cwd", "CWD", lambda p: p.cwd, max_width=40, clip_side=ClipSide.LEFT
+    ),
+    "ppid": ColumnSpec("ppid", "PPID", lambda p: p.ppid),
+    "parent_name": ColumnSpec(
+        "parent_name", "Parent", lambda p: p.parent_name, max_width=15
+    ),
+    "status": ColumnSpec("status", "Status", lambda p: p, _fmt_status),
+    "cmdline": ColumnSpec("cmdline", "Command", lambda p: p.cmdline, max_width=60),
+    "username": ColumnSpec("username", "User", lambda p: p.username),
+}
+
+DEFAULT_COLUMNS: tuple[str, ...] = (
+    "pid",
+    "name",
+    "rss_mb",
+    "cpu_percent",
+    "cwd",
+    "ppid",
+    "status",
+)
+
+
+def get_available_columns() -> list[str]:
+    """Return list of available column keys.
+
+    Returns:
+        A list of keys for all available columns.
+    """
+    return list(COLUMNS)

procclean/formatters/output.py

@@ -0,0 +1,158 @@
+"""Output format functions for process data."""
+
+import csv
+import io
+import json
+from collections.abc import Sequence
+from dataclasses import asdict, fields
+
+from tabulate import tabulate
+
+from procclean.core import ProcessInfo
+
+from .columns import COLUMNS, DEFAULT_COLUMNS
+
+
+def get_rows(
+    procs: list[ProcessInfo],
+    columns: Sequence[str] | None = None,
+) -> tuple[list[str], list[list[str]]]:
+    """Extract headers and formatted rows from processes.
+
+    Args:
+        procs: Processes to extract rows from.
+        columns: Optional ordered list of column keys to include.
+
+    Returns:
+        A tuple of (headers, rows), where headers is a list of column headers and
+        rows is a list of formatted string rows.
+    """
+    cols = columns or DEFAULT_COLUMNS
+    specs = [COLUMNS[c] for c in cols if c in COLUMNS]
+    headers = [s.header for s in specs]
+    rows = [[s.extract(p) for s in specs] for p in procs]
+    return headers, rows
+
+
+def format_table(
+    procs: list[ProcessInfo],
+    columns: Sequence[str] | None = None,
+) -> str:
+    """Format processes as ASCII table.
+
+    Args:
+        procs: Processes to format.
+        columns: Optional ordered list of column keys to include.
+
+    Returns:
+        A formatted ASCII table string, or a message if no processes are found.
+    """
+    if not procs:
+        return "No processes found."
+    headers, rows = get_rows(procs, columns)
+    return tabulate(rows, headers=headers, tablefmt="simple_outline")
+
+
+def format_markdown(
+    procs: list[ProcessInfo],
+    columns: Sequence[str] | None = None,
+) -> str:
+    """Format processes as a GitHub-flavored Markdown table.
+
+    Args:
+        procs: Processes to format.
+        columns: Optional ordered list of column keys to include.
+
+    Returns:
+        A formatted Markdown table string, or a message if no processes are found.
+    """
+    if not procs:
+        return "No processes found."
+    headers, rows = get_rows(procs, columns)
+    return tabulate(rows, headers=headers, tablefmt="pipe")
+
+
+def _serialize_process(p: ProcessInfo) -> dict:
+    """Convert a process to a JSON-serializable dictionary.
+
+    Float values are rounded to 2 decimal places for stable output.
+
+    Args:
+        p: Process to serialize.
+
+    Returns:
+        A JSON-serializable dict representation of the process.
+    """
+    data = asdict(p)
+    data["rss_mb"] = round(data["rss_mb"], 2)
+    data["cpu_percent"] = round(data["cpu_percent"], 2)
+    return data
+
+
+def format_json(procs: list[ProcessInfo]) -> str:
+    """Format processes as JSON.
+
+    Args:
+        procs: Processes to format.
+
+    Returns:
+        A pretty-printed JSON string representing the processes.
+    """
+    return json.dumps([_serialize_process(p) for p in procs], indent=2)
+
+
+def format_csv(procs: list[ProcessInfo]) -> str:
+    """Format processes as CSV.
+
+    Args:
+        procs: Processes to format.
+
+    Returns:
+        A CSV string representing the processes. If no processes are provided,
+        returns an empty string.
+    """
+    if not procs:
+        return ""
+    output = io.StringIO()
+    writer = csv.writer(output)
+
+    # Get field names from dataclass
+    fieldnames = [f.name for f in fields(ProcessInfo)]
+    writer.writerow(fieldnames)
+
+    for p in procs:
+        row = []
+        for name in fieldnames:
+            val = getattr(p, name)
+            if isinstance(val, float):
+                val = f"{val:.2f}"
+            row.append(val)
+        writer.writerow(row)
+
+    return output.getvalue()
+
+
+def format_output(
+    procs: list[ProcessInfo],
+    fmt: str,
+    columns: Sequence[str] | None = None,
+) -> str:
+    """Format processes in the requested format.
+
+    Args:
+        procs: Processes to format.
+        fmt: Output format key (e.g., "json", "csv", "md"/"markdown").
+        columns: Optional ordered list of column keys to include (table/markdown).
+
+    Returns:
+        The formatted output string.
+    """
+    match fmt:
+        case "json":
+            return format_json(procs)
+        case "csv":
+            return format_csv(procs)
+        case "md" | "markdown":
+            return format_markdown(procs, columns)
+        case _:
+            return format_table(procs, columns)

procclean/tui/__init__.py

@@ -0,0 +1,6 @@
+"""TUI interface for procclean."""
+
+from .app import ProcessCleanerApp
+from .screens import ConfirmKillScreen
+
+__all__ = ["ConfirmKillScreen", "ProcessCleanerApp"]