pkgwise 0.1.0__py3-none-any.whl

pkgwise/__init__.py

@@ -0,0 +1,12 @@
+"""PkgWise — Smart Linux Update Analyzer.
+
+Know what you're updating before you update.
+
+PkgWise is an analysis-first package update assistant. It uses the native
+package manager (currently ``pacman`` and ``apt``) as its backend and provides
+a better interface for understanding and selecting package updates.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

pkgwise/__main__.py

@@ -0,0 +1,6 @@
+"""Module entry point: ``python -m pkgwise``."""
+
+from pkgwise.cli import main
+
+if __name__ == "__main__":
+    main()

pkgwise/backends/__init__.py

@@ -0,0 +1 @@
+"""Package-manager backends: pacman (Arch), apt (Debian) and the shared interface."""

pkgwise/backends/arch.py

@@ -0,0 +1,223 @@
+"""Arch Linux backend — wraps the ``pacman`` package manager.
+
+Parser details
+--------------
+``pacman -Qu`` lists outdated packages as ``name current => new``.
+``pacman -Si <name>...`` reads the local sync databases (no network) and
+reports per-package ``Download Size`` and ``Installed Size`` for the *new*
+version, so sizes are realistic for planning an update.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Dict, List, Optional
+
+from pkgwise.backends.base import InstallError, PackageManager
+from pkgwise.core.models import PackageUpdate
+from pkgwise.utils.commands import CommandError, run_command
+
+_QU_LINE = re.compile(r"^(?P<name>[^\s]+)\s+(?P<current>[^\s]+)\s*=>\s*(?P<new>[^\s]+)$")
+_SI_FIELD = re.compile(r"^(?P<key>[^:]+):(?P<value>.*)$")
+
+_UPDATE_COMMAND = "-Su"
+
+
+class ArchBackend(PackageManager):
+    """pacman-backed implementation for Arch Linux and derivatives."""
+
+    executable = "pacman"
+    name = "pacman"
+
+    @property
+    def supported(self) -> bool:
+        import shutil
+
+        return shutil.which("pacman") is not None
+
+    # -- parsing -----------------------------------------------------------
+
+    def check_updates(self) -> List[PackageUpdate]:
+        """Read available updates from the local sync databases (no refresh)."""
+        lines = self._run_pacman(["-Qu"]).stdout.splitlines()
+        parsed = [_parse_qu_line(line) for line in lines]
+        updates: List[PackageUpdate] = []
+        for row in parsed:
+            if row is None:
+                continue
+            name, current, new = row
+            updates.append(
+                PackageUpdate(
+                    name=name,
+                    current_version=current,
+                    new_version=new,
+                    package_manager=self.name,
+                )
+            )
+        if not updates:
+            return updates
+        self._attach_sizes(updates)
+        return updates
+
+    def list_updates(self) -> List[PackageUpdate]:
+        """Refresh sync databases, then return available updates."""
+        self._sync_databases()
+        return self.check_updates()
+
+    def install_updates(self, names: List[str]) -> None:
+        """Build an update transaction for *names* and run it.
+
+        Authorization (root/sudo) is handled by the caller before this runs;
+        the produced command is deterministic and uses ``--noconfirm`` because
+        PkgWise already collected an explicit confirmation.
+        """
+        if not names:
+            return
+        _run_real_install("pacman", self.install_command(names), names)
+
+    def install_command(self, names: List[str]) -> List[str]:
+        """Return the ``pacman`` invocation used to update *names*.
+
+        An empty selection yields an empty command: with no explicit targets
+        ``pacman -Su`` would upgrade the entire system, which PkgWise must
+        never trigger by accident.
+        """
+        selected = sorted(set(names))
+        if not selected:
+            return []
+        return ["pacman", "--noconfirm", _UPDATE_COMMAND, *selected]
+
+    # -- internal helpers --------------------------------------------------
+
+    def _sync_databases(self) -> None:
+        """Refresh the sync databases (``pacman -Sy``); read-only regarding packages."""
+        run_command(["pacman", "-Sy", "--noconfirm"], timeout=300, check=False)
+
+    def _run_pacman(self, args: List[str]):
+        return run_command(["pacman", *args], timeout=180)
+
+    def _attach_sizes(self, updates: List[PackageUpdate]) -> None:
+        """Populate download/installed sizes using ``pacman -Si`` (offline)."""
+        if not updates:
+            return
+        names = [u.name for u in updates]
+        try:
+            output = self._run_pacman(["-Si", *names]).stdout
+        except CommandError:
+            return
+        sizes = _parse_si_blocks(output)
+        for index, update in enumerate(updates):
+            info = sizes.get(update.name)
+            if info is None:
+                continue
+            updated = replaceable(update, info)
+            if updated is not update:
+                updates[index] = updated
+
+
+def replaceable(update: PackageUpdate, info: Dict[str, Optional[int]]) -> PackageUpdate:
+    """Return an updated copy only when *info* provides reliable values."""
+    from dataclasses import replace
+
+    overrides = {}
+    if info.get("download") is not None:
+        overrides["download_size"] = info["download"]
+    if info.get("installed") is not None:
+        overrides["installed_size"] = info["installed"]
+    if not overrides:
+        return update
+    return replace(update, **overrides)
+
+
+def _parse_qu_line(line: str) -> Optional[tuple]:
+    """Parse one ``pacman -Qu`` output line into (name, current, new)."""
+    stripped = line.strip()
+    if not stripped:
+        return None
+    match = _QU_LINE.match(stripped)
+    if not match:
+        return None
+    return (match.group("name"), match.group("current"), match.group("new"))
+
+
+def _parse_si_blocks(output: str) -> Dict[str, Dict[str, Optional[int]]]:
+    """Parse consolidated ``pacman -Si`` output into ``{name: sizes}``.
+
+    Sizes are converted from strings such as ``8.25 MiB`` to integer bytes.
+    Returns an empty dict when nothing parsable is found.
+    """
+    result: Dict[str, Dict[str, Optional[int]]] = {}
+    current: Dict[str, str] = {}
+    for raw in output.splitlines():
+        line = raw.strip()
+        if not line and current:
+            _commit_si_block(result, current)
+            current = {}
+            continue
+        match = _SI_FIELD.match(line)
+        if not match:
+            continue
+        key = match.group("key").strip().lower()
+        value = match.group("value").strip()
+        if key in {"name", "version", "download size", "installed size"}:
+            current[key] = value
+    if current:
+        _commit_si_block(result, current)
+    return result
+
+
+def _commit_si_block(result: Dict[str, Dict[str, Optional[int]]], block: Dict[str, str]) -> None:
+    name = block.get("name")
+    if not name:
+        return
+    entry = {
+        "download": _parse_size(block.get("download size")),
+        "installed": _parse_size(block.get("installed size")),
+    }
+    result[name] = entry
+
+
+def _parse_size(raw: Optional[str]) -> Optional[int]:
+    """Parse pacman sizes like ``408.88 KiB`` / ``4.02 MiB`` into bytes."""
+    if not raw:
+        return None
+    match = re.match(r"^([0-9.]+)\s*([A-Za-z]+)?$", raw.strip())
+    if not match:
+        return None
+    try:
+        value = float(match.group(1))
+    except ValueError:
+        return None
+    unit = (match.group(2) or "B").lower()
+    multiplier = {
+        "b": 1,
+        "kib": 1024,
+        "mib": 1024**2,
+        "gib": 1024**3,
+        "tib": 1024**4,
+    }.get(unit, 1)
+    return int(value * multiplier)
+
+
+def _run_real_install(manager: str, command: List[str], names: List[str]) -> None:
+    """Execute a real install/update command, converting failures to InstallError.
+
+    Never constructs a shell string — always an argument list.
+    """
+    from pkgwise.utils import commands as cmd_utils
+
+    path = cmd_utils.which(manager)
+    if path is None:
+        raise InstallError(
+            f"The package manager '{manager}' is not installed.",
+            detail="Install it before retrying an update.",
+        )
+    try:
+        cmd_utils.run_command(command, timeout=_INSTALL_TIMEOUT, check=False)
+    except cmd_utils.CommandError as exc:
+        raise InstallError(
+            exc.message, returncode=exc.returncode, detail=exc.detail
+        ) from exc
+
+
+_INSTALL_TIMEOUT = 86_400  # 24h: installs can legitimately take a long time

pkgwise/backends/base.py

@@ -0,0 +1,107 @@
+"""Abstract package-manager interface.
+
+The TUI and analyzer talk only to this interface. Concrete backends
+(:mod:`pkgwise.backends.arch` and :mod:`pkgwise.backends.debian`)
+implement the same contract, so adding Fedora/dnf later means adding one new
+backend class — no changes to the UI or analyzer.
+
+Parsers return raw parsed values (``None`` when unknown); assigning priority
+is exclusively the job of :mod:`pkgwise.core.priority`.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import List, Optional
+
+from pkgwise.core.models import PackageUpdate
+
+
+class UpdateCheckError(Exception):
+    """Base error for any backend query failure. Raised with a human message."""
+
+    def __init__(self, message: str, detail: Optional[str] = None):
+        self.message = message
+        self.detail = detail
+        super().__init__(message)
+
+
+class BackendUnavailableError(UpdateCheckError):
+    """The package-manager binary is not installed on this system."""
+
+
+class UnsupportedDistroError(UpdateCheckError):
+    """No backend maps to the detected distribution/package manager."""
+
+
+class PackageManager(ABC):
+    """Common contract every backend implements."""
+
+    #: Binary invoked to perform update operations.
+    executable: str = ""
+
+    #: Human name for the backend, e.g. "pacman".
+    name: str = ""
+
+    @property
+    @abstractmethod
+    def supported(self) -> bool:
+        """True when this backend's package manager is installed."""
+
+    @abstractmethod
+    def check_updates(self) -> List[PackageUpdate]:
+        """Query and return available updates (read-only, no refresh)."""
+
+    @abstractmethod
+    def list_updates(self) -> List[PackageUpdate]:
+        """Update the package index, then return available updates."""
+
+    @abstractmethod
+    def install_updates(self, names: List[str]) -> None:
+        """Perform a real update for the given package names.
+
+        May raise :class:`InstallError` on failure. Intended to be run from
+        middleware that has already checked permissions and disk space.
+        """
+
+    @abstractmethod
+    def install_command(self, names: List[str]) -> List[str]:
+        """Return the argument list that would update *names* (no side effects).
+
+        Exists so callers can display/confirm the exact command first.
+        """
+
+
+class InstallError(Exception):
+    """Raised when an update operation fails."""
+
+    def __init__(self, message: str, returncode: Optional[int] = None, detail: Optional[str] = None):
+        self.message = message
+        self.returncode = returncode
+        self.detail = detail
+        super().__init__(message)
+
+
+def _as_int(raw: Optional[str]) -> Optional[int]:
+    """Parse a size/count string (often with commas or units) to int."""
+    if not raw:
+        return None
+    cleaned = raw.replace(",", "").replace(" ", "").strip()
+    if not cleaned:
+        return None
+    try:
+        return int(cleaned)
+    except (ValueError, TypeError):
+        return None
+
+
+def _yes_no(raw: Optional[str]) -> Optional[bool]:
+    """Parse a y/n style value into a bool, or ``None`` if unparseable."""
+    if raw is None:
+        return None
+    lowered = raw.strip().lower()
+    if lowered in {"y", "yes", "true", "1"}:
+        return True
+    if lowered in {"n", "no", "false", "0"}:
+        return False
+    return None

pkgwise/backends/debian.py

@@ -0,0 +1,247 @@
+"""Debian/Kali backend — wraps the ``apt`` toolchain (``apt-get``/``apt-cache``).
+
+Parser details
+--------------
+``apt-get -s upgrade`` (simulate) lists upgrade actions as ``Inst`` lines:
+
+    Inst libssl3 [3.0.1-1] (3.0.2-1 ...) []
+
+Parsing these gives package name, installed version and candidate version.
+Download sizes come from ``apt-get --print-uris`` (a dry run that emits the
+``.deb`` URL, filename and byte size per package). Installed sizes for the
+*candidate* versions come from ``apt-cache show``.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Dict, List, Optional, Tuple
+
+from pkgwise.backends.base import InstallError, PackageManager, UpdateCheckError
+from pkgwise.core.models import PackageUpdate
+from pkgwise.utils.commands import run_command
+
+_INST_LINE = re.compile(r"^Inst (?P<name>\S+)( \[(?P<current>[^\]]*)\])? \((?P<new>\S+)")
+_URI_LINE = re.compile(r"^'(?P<url>.*)'\s+(?P<filename>\S+)\s+(?P<size>\d+)")
+_STANZA_FIELD = re.compile(r"^(?P<key>[^:]+):\s*(?P<value>.*)$")
+
+_UPGRADE_TARGET = "upgrade"
+
+
+class DebianBackend(PackageManager):
+    """apt-backed implementation for Debian, Kali, Ubuntu and derivatives."""
+
+    executable = "apt-get"
+    name = "apt"
+
+    @property
+    def supported(self) -> bool:
+        import shutil
+
+        return shutil.which("apt-get") is not None
+
+    # -- public API ---------------------------------------------------------
+
+    def check_updates(self) -> List[PackageUpdate]:
+        """Read available upgrades using the current package lists (no refresh)."""
+        updates = self._simulate_upgrade()
+        if not updates:
+            return updates
+        sizes = self._download_sizes()
+        for index, update in enumerate(updates):
+            if update.name in sizes:
+                updates[index] = _with_download_size(update, sizes[update.name])
+        self._attach_installed_sizes(updates)
+        return updates
+
+    def list_updates(self) -> List[PackageUpdate]:
+        """Refresh package lists (``apt-get update``), then list upgrades."""
+        try:
+            result = run_command(["apt-get", "update"], timeout=300, check=False)
+            if result.returncode != 0:
+                raise UpdateCheckError(
+                    "apt-get update could not refresh the package lists.",
+                    detail=(result.stderr or result.stdout or "").strip()[:500],
+                )
+        except UpdateCheckError:
+            raise
+        except Exception as exc:  # TimeoutExpired etc.
+            raise UpdateCheckError(
+                "apt-get update failed unexpectedly.", detail=str(exc)
+            ) from exc
+        return self.check_updates()
+
+    def install_updates(self, names: List[str]) -> None:
+        """Upgrade the given packages to their candidate versions."""
+        if not names:
+            return
+        _run_real_install("apt-get", self.install_command(names), names)
+
+    def install_command(self, names: List[str]) -> List[str]:
+        """Return the ``apt-get`` invocation used to upgrade *names*.
+
+        An empty selection yields an empty command: with no explicit targets
+        ``apt-get install`` would upgrade the entire system, which PkgWise
+        must never trigger by accident.
+        """
+        selected = sorted(set(names))
+        if not selected:
+            return []
+        return ["apt-get", "--yes", "install", *selected]
+
+    # -- parsing helpers -----------------------------------------------------
+
+    def _simulate_upgrade(self) -> List[PackageUpdate]:
+        """Compute pending upgrades via ``apt-get -s upgrade``."""
+        output = self._run(["apt-get", "-s", _UPGRADE_TARGET]).stdout
+        return [row for row in (_parse_inst_line(line) for line in output.splitlines()) if row]
+
+    def _download_sizes(self) -> Dict[str, int]:
+        """Return ``{name: download_bytes}`` from ``apt-get --print-uris``."""
+        try:
+            output = self._run(
+                ["apt-get", "--print-uris", "--yes", _UPGRADE_TARGET],
+                timeout=300,
+            ).stdout
+        except UpdateCheckError:
+            return {}
+        sizes: Dict[str, int] = {}
+        for line in output.splitlines():
+            match = _URI_LINE.match(line.strip())
+            if not match:
+                continue
+            filename = match.group("filename")
+            size = int(match.group("size"))
+            sizes[_package_from_filename(filename)] = size
+        return sizes
+
+    def _attach_installed_sizes(self, updates: List[PackageUpdate]) -> None:
+        """Fill installed sizes from ``apt-cache show`` (candidate versions)."""
+        sizes = _apt_cache_installed_sizes([u.name for u in updates])
+        for index, update in enumerate(updates):
+            installed = sizes.get(update.name)
+            if installed is not None:
+                updates[index] = _with_installed_size(update, installed)
+
+    def _run(self, args: List[str], timeout: int = 180):
+        return run_command(args, timeout=timeout)
+
+
+# -- module-level parsers (pure functions, easily unit-tested) ----------------
+
+
+def _parse_inst_line(line: str) -> Optional[PackageUpdate]:
+    """Parse one simulated ``Inst`` line into a ``PackageUpdate``.
+
+    Returns ``None`` for lines that do not describe an upgrade.
+    """
+    match = _INST_LINE.match(line.strip())
+    if not match:
+        return None
+    return PackageUpdate(
+        name=match.group("name"),
+        current_version=match.group("current"),
+        new_version=match.group("new"),
+        package_manager="apt",
+    )
+
+
+def _package_from_filename(filename: str) -> str:
+    """Derive a package name from a ``.deb`` filename like ``libssl3_3.0.2_amd64.deb``.
+
+    Names contain no underscores, so splitting on the first underscore is safe.
+    """
+    return filename.split("_", 1)[0]
+
+
+def _apt_cache_installed_sizes(names: List[str]) -> Dict[str, int]:
+    """Query ``apt-cache show`` for installed sizes of candidate versions.
+
+    ``Installed-Size`` in apt metadata is expressed in KiB.
+    """
+    if not names:
+        return {}
+    try:
+        import shutil
+
+        if shutil.which("apt-cache") is None:
+            return {}
+        result = run_command(["apt-cache", "show", *names], timeout=180, check=False)
+    except Exception:
+        return {}
+    stanzas = _parse_apt_cache_stanzas(result.stdout)
+    sizes: Dict[str, int] = {}
+    for name, version, kbytes in stanzas:
+        if name not in sizes and kbytes is not None:
+            sizes[name] = kbytes * 1024
+    return sizes
+
+
+def _parse_apt_cache_stanzas(output: str) -> List[Tuple[str, Optional[str], Optional[int]]]:
+    """Parse ``apt-cache show`` blocks into ``(name, version, installed_kb)``.
+
+    Returns the newest stanza per package (apt lists candidates newest-first).
+    """
+    stanzas: List[Dict[str, str]] = []
+    current: Dict[str, str] = {}
+    for raw in output.splitlines():
+        if raw.strip() == "":
+            if current:
+                stanzas.append(current)
+                current = {}
+            continue
+        match = _STANZA_FIELD.match(raw)
+        if not match:
+            continue
+        key = match.group("key").lower()
+        if key in {"package", "version", "installed-size"}:
+            current[key] = match.group("value")
+    if current:
+        stanzas.append(current)
+
+    parsed = []
+    seen_names: set = set()
+    for stanza in stanzas:
+        name = stanza.get("package")
+        if not name or name in seen_names:
+            continue
+        seen_names.add(name)
+        version = stanza.get("version")
+        size: Optional[int] = None
+        if stanza.get("installed-size"):
+            try:
+                size = int(stanza["installed-size"])
+            except ValueError:
+                size = None
+        parsed.append((name, version, size))
+    return parsed
+
+
+def _with_download_size(update: PackageUpdate, size: int) -> PackageUpdate:
+    from dataclasses import replace
+
+    return replace(update, download_size=size)
+
+
+def _with_installed_size(update: PackageUpdate, size: int) -> PackageUpdate:
+    from dataclasses import replace
+
+    return replace(update, installed_size=size)
+
+
+def _run_real_install(manager: str, command: List[str], names: List[str]) -> None:
+    """Execute a destructive command argument list, mapping failures to InstallError."""
+    from pkgwise.utils import commands as cmd_utils
+
+    path = cmd_utils.which(manager)
+    if path is None:
+        raise InstallError(f"The package manager '{manager}' is not installed.")
+    try:
+        cmd_utils.run_command(command, timeout=_INSTALL_TIMEOUT, check=False)
+    except cmd_utils.CommandError as exc:
+        raise InstallError(
+            exc.message, returncode=exc.returncode, detail=exc.detail
+        ) from exc
+
+
+_INSTALL_TIMEOUT = 86_400  # 24h: installs can legitimately take a long time

pkgwise/backends/factory.py

@@ -0,0 +1,63 @@
+"""Backend selection and registration.
+
+New distributions are added by subclassing :class:`PackageManager` and
+registering it here via :data:`BACKENDS` — no changes required in the UI or
+analyzer. Selection is driven by the distro ID reported by os-release.
+"""
+
+from __future__ import annotations
+
+from typing import Dict
+
+from pkgwise.backends.arch import ArchBackend
+from pkgwise.backends.base import PackageManager, UnsupportedDistroError
+from pkgwise.backends.debian import DebianBackend
+from pkgwise.utils import distro as distro_utils
+
+#: distro ID families -> backend class.
+BACKENDS: Dict[str, type] = {
+    "arch": ArchBackend,
+    "debian": DebianBackend,
+    # Future backends register here, e.g. "fedora": DnfBackend
+}
+
+
+def get_backend(distro_name: str = "", package_manager: str = "") -> PackageManager:
+    """Return the backend matching the current system.
+
+    Args:
+        distro_name: rendered distro name (used for error messages only).
+        package_manager: ``pacman``/``apt``/``unknown``; recomputed when empty.
+
+    Raises:
+        UnsupportedDistroError: no backend matches the detected system.
+    """
+    if not package_manager:
+        package_manager = distro_utils.get_system_info().package_manager
+
+    for key, backend_cls in BACKENDS.items():
+        if package_manager in _managers_for(key):
+            instance = backend_cls()
+            if not instance.supported:
+                raise UnsupportedDistroError(
+                    f"{package_manager} is required but was not found on this system.",
+                    detail=f"Install the '{package_manager}' package manager to use PkgWise here.",
+                )
+            return instance
+
+    raise UnsupportedDistroError(
+        "PkgWise does not recognize your Linux distribution.",
+        detail=(
+            f"Detected package manager: {package_manager or 'unknown'} "
+            f"(distro: {distro_name or 'unknown'}). "
+            "Supported: Arch Linux (pacman) and Debian-based systems (apt)."
+        ),
+    )
+
+
+def _managers_for(distro_key: str) -> tuple:
+    """Map a backend key to the package-manager names it satisfies."""
+    return {
+        "arch": ("pacman",),
+        "debian": ("apt", "apt-get"),
+    }.get(distro_key, ())