updater-gitplucker 0.1.0__py3-none-any.whl

gitplucker/__init__.py

@@ -0,0 +1,66 @@
+"""gitplucker — modular, pluggable GitHub updater for Python-glued projects.
+
+Public API (stable):
+
+    from gitplucker import (
+        Updater, UpdaterConfig, RepoSubscription,
+        Channel, ApplyStrategy, ConflictPolicy,
+        ManualTrigger, StartupTrigger, BackgroundTrigger,
+    )
+
+See ``docs/INTEGRATION.md`` for a step-by-step wiring guide (written so an AI
+assistant can drop this into an app unattended).
+"""
+
+from __future__ import annotations
+
+from .config import ApplyStrategy, ConflictPolicy, RepoSubscription, UpdaterConfig
+from .errors import (
+    ApplyError,
+    ConfigError,
+    GitHubAPIError,
+    GitpluckerError,
+    MergeConflictError,
+    RepoNotAllowedError,
+    SourceError,
+)
+from .merge import MergeResult, merge_text
+from .models import (
+    ApplyResult,
+    Channel,
+    ChangeType,
+    DependencyChange,
+    FileChange,
+    UpdatePlan,
+)
+from .triggers import BackgroundTrigger, ManualTrigger, StartupTrigger
+from .updater import Updater
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Updater",
+    "UpdaterConfig",
+    "RepoSubscription",
+    "Channel",
+    "ApplyStrategy",
+    "ConflictPolicy",
+    "ChangeType",
+    "UpdatePlan",
+    "FileChange",
+    "DependencyChange",
+    "ApplyResult",
+    "ManualTrigger",
+    "StartupTrigger",
+    "BackgroundTrigger",
+    "merge_text",
+    "MergeResult",
+    "GitpluckerError",
+    "ConfigError",
+    "RepoNotAllowedError",
+    "SourceError",
+    "GitHubAPIError",
+    "MergeConflictError",
+    "ApplyError",
+    "__version__",
+]

gitplucker/backend/__init__.py

@@ -0,0 +1,3 @@
+from .github_api import GitHubClient, ReleaseInfo
+
+__all__ = ["GitHubClient", "ReleaseInfo"]

gitplucker/backend/github_api.py

@@ -0,0 +1,133 @@
+"""Zero-dependency GitHub REST client.
+
+Uses only the stdlib (``urllib``) so the core library installs with no third
+party packages. Every method enforces the repository allowlist: a repo that
+was not explicitly permitted can never be contacted.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable
+
+from ..errors import GitHubAPIError, RepoNotAllowedError
+
+ProgressCb = Callable[[int, int], None]
+
+
+@dataclass
+class ReleaseInfo:
+    tag: str
+    name: str
+    body: str
+    prerelease: bool
+    assets: list[dict] = field(default_factory=list)  # each: {name, browser_download_url, url, size}
+    zipball_url: str = ""
+
+
+class GitHubClient:
+    def __init__(
+        self,
+        allowed_repos: set[str] | list[str],
+        token: str | None = None,
+        api_base: str = "https://api.github.com",
+    ) -> None:
+        self._allowed = set(allowed_repos)
+        self._token = token
+        self._api = api_base.rstrip("/")
+
+    # -- allowlist gate ---------------------------------------------------
+    def _guard(self, repo: str) -> None:
+        if repo not in self._allowed:
+            raise RepoNotAllowedError(
+                f"repo {repo!r} is not allowlisted; refusing to contact GitHub."
+            )
+
+    def _headers(self, accept: str = "application/vnd.github+json") -> dict[str, str]:
+        h = {
+            "Accept": accept,
+            "User-Agent": "gitplucker/0.1",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }
+        if self._token:
+            h["Authorization"] = f"Bearer {self._token}"
+        return h
+
+    def _get_json(self, url: str) -> dict | list:
+        req = urllib.request.Request(url, headers=self._headers())
+        try:
+            with urllib.request.urlopen(req) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            raise GitHubAPIError(f"GET {url} failed: {e.reason}", status=e.code) from e
+        except urllib.error.URLError as e:
+            raise GitHubAPIError(f"GET {url} failed: {e.reason}") from e
+
+    # -- API surface ------------------------------------------------------
+    def get_latest_release(self, repo: str, include_prerelease: bool = False) -> ReleaseInfo | None:
+        self._guard(repo)
+        if include_prerelease:
+            data = self._get_json(f"{self._api}/repos/{repo}/releases")
+            if not data:
+                return None
+            rel = data[0]  # releases come newest-first
+        else:
+            try:
+                rel = self._get_json(f"{self._api}/repos/{repo}/releases/latest")
+            except GitHubAPIError as e:
+                if e.status == 404:
+                    return None
+                raise
+        return ReleaseInfo(
+            tag=rel.get("tag_name", ""),
+            name=rel.get("name") or rel.get("tag_name", ""),
+            body=rel.get("body", "") or "",
+            prerelease=bool(rel.get("prerelease")),
+            assets=rel.get("assets", []) or [],
+            zipball_url=rel.get("zipball_url", ""),
+        )
+
+    def get_branch_head(self, repo: str, branch: str) -> tuple[str, str]:
+        """Return ``(sha, iso_date)`` of the branch tip."""
+        self._guard(repo)
+        data = self._get_json(f"{self._api}/repos/{repo}/branches/{branch}")
+        commit = data.get("commit", {})
+        sha = commit.get("sha", "")
+        date = (
+            commit.get("commit", {}).get("committer", {}).get("date", "")
+            or commit.get("commit", {}).get("author", {}).get("date", "")
+        )
+        return sha, date
+
+    def download(self, repo: str, url: str, dest: Path, progress: ProgressCb | None = None) -> Path:
+        """Download a URL (asset or zipball) to ``dest``, enforcing the allowlist."""
+        self._guard(repo)
+        # Asset API URLs need the octet-stream Accept header to get the binary.
+        accept = "application/octet-stream" if "/releases/assets/" in url else "*/*"
+        req = urllib.request.Request(url, headers=self._headers(accept))
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            with urllib.request.urlopen(req) as resp, open(dest, "wb") as fh:
+                total = int(resp.headers.get("Content-Length") or 0)
+                received = 0
+                while True:
+                    chunk = resp.read(65536)
+                    if not chunk:
+                        break
+                    fh.write(chunk)
+                    received += len(chunk)
+                    if progress:
+                        progress(received, total)
+        except urllib.error.HTTPError as e:
+            raise GitHubAPIError(f"download {url} failed: {e.reason}", status=e.code) from e
+        except urllib.error.URLError as e:
+            raise GitHubAPIError(f"download {url} failed: {e.reason}") from e
+        return dest
+
+    def zipball_url(self, repo: str, ref: str) -> str:
+        self._guard(repo)
+        return f"{self._api}/repos/{repo}/zipball/{ref}"

gitplucker/config.py

@@ -0,0 +1,105 @@
+"""Configuration objects — the whole behaviour of the updater is data-driven.
+
+A host constructs an :class:`UpdaterConfig`, passes it to
+:class:`~gitplucker.updater.Updater`, and never has to subclass anything.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .errors import ConfigError
+from .models import Channel
+
+
+class ConflictPolicy(str):
+    MARK = "mark"        # write git-style conflict markers, keep going
+    LOCAL = "local"      # keep the local version of a conflicted file
+    REMOTE = "remote"    # take the remote version of a conflicted file
+    ABORT = "abort"      # raise MergeConflictError
+
+
+class ApplyStrategy(str):
+    WHOLE_APP = "whole_app"   # replace the tracked tree, backup + rollback
+    SELECTIVE = "selective"   # only paths matching include_globs
+    PACKAGE = "package"       # pip-install the downloaded wheel/sdist
+
+
+@dataclass
+class RepoSubscription:
+    """One repo the app follows, on one or more branches, via one channel."""
+
+    repo: str                                  # "owner/name"
+    branches: list[str] = field(default_factory=lambda: ["main"])
+    channel: Channel = Channel.PYTHON_SOURCE
+    # RELEASE channel: glob picking which asset to download (falls back to zipball).
+    asset_pattern: str = "*.zip"
+    # Only these paths (relative, glob) are considered part of the app payload.
+    include_globs: list[str] = field(default_factory=lambda: ["**/*"])
+    exclude_globs: list[str] = field(
+        default_factory=lambda: [
+            "**/.git/**", "**/__pycache__/**", "**/*.pyc",
+            "**/.gitplucker/**", "**/.venv/**", "**/node_modules/**",
+        ]
+    )
+    # Subfolder inside the repo that maps to install_root ("" == repo root).
+    source_subdir: str = ""
+
+    def __post_init__(self) -> None:
+        if isinstance(self.channel, str):
+            self.channel = Channel(self.channel)
+        if self.repo.count("/") != 1:
+            raise ConfigError(f"repo must be 'owner/name', got {self.repo!r}")
+
+
+@dataclass
+class UpdaterConfig:
+    """Top-level configuration.
+
+    ``allowed_repos`` is the security allowlist: any subscription (or ad-hoc
+    request) whose repo is not listed here is rejected before any network call.
+    """
+
+    install_root: Path
+    subscriptions: list[RepoSubscription] = field(default_factory=list)
+    allowed_repos: list[str] = field(default_factory=list)
+
+    token: str | None = None                    # GitHub PAT for private repos / rate limits
+    api_base: str = "https://api.github.com"
+
+    apply_strategy: str = ApplyStrategy.WHOLE_APP
+    selective_globs: list[str] = field(default_factory=list)  # used by SELECTIVE
+
+    merge: bool = True                          # 3-way merge on python-source
+    conflict_policy: str = ConflictPolicy.MARK
+    auto_install_deps: bool = True
+    requirements_file: str | None = "requirements.txt"  # relative to install_root
+    backup: bool = True
+
+    # Where gitplucker keeps its state (base snapshots, version manifest, backups).
+    state_dir: Path | None = None
+
+    def __post_init__(self) -> None:
+        self.install_root = Path(self.install_root)
+        if self.state_dir is None:
+            self.state_dir = self.install_root / ".gitplucker"
+        self.state_dir = Path(self.state_dir)
+
+        allowed = set(self.allowed_repos)
+        # A subscription implicitly requires its repo to be allowlisted.
+        for sub in self.subscriptions:
+            if sub.repo not in allowed:
+                raise ConfigError(
+                    f"subscription repo {sub.repo!r} is not in allowed_repos "
+                    f"{sorted(allowed)!r}; add it explicitly to permit updates."
+                )
+
+    def is_allowed(self, repo: str) -> bool:
+        return repo in set(self.allowed_repos)
+
+    def subscription_for(self, repo: str, branch: str | None = None) -> RepoSubscription | None:
+        for sub in self.subscriptions:
+            if sub.repo == repo and (branch is None or branch in sub.branches):
+                return sub
+        return None

gitplucker/deps/__init__.py

@@ -0,0 +1,13 @@
+from .python_deps import (
+    scan_imports,
+    resolve_dependencies,
+    install_requirements,
+    PACKAGE_ALIASES,
+)
+
+__all__ = [
+    "scan_imports",
+    "resolve_dependencies",
+    "install_requirements",
+    "PACKAGE_ALIASES",
+]

gitplucker/deps/python_deps.py

@@ -0,0 +1,211 @@
+"""Python dependency auto-detection and installation.
+
+Flow for the ``python-source`` channel:
+
+1. Parse every ``.py`` file in the incoming payload with :mod:`ast`.
+2. Collect top-level imported module names.
+3. Drop the standard library and the app's own local packages.
+4. Whatever's left that isn't importable / installed is surfaced as a
+   :class:`~gitplucker.models.DependencyChange` — shown in the update plan and,
+   if ``auto_install_deps`` is on, ``pip install``-ed on apply.
+"""
+
+from __future__ import annotations
+
+import ast
+import importlib.util
+import subprocess
+import sys
+from pathlib import Path
+
+from ..models import DependencyChange
+
+try:
+    from importlib import metadata as _im
+except ImportError:  # pragma: no cover
+    import importlib_metadata as _im  # type: ignore
+
+# Import name -> pip package name, for the common mismatches.
+PACKAGE_ALIASES: dict[str, str] = {
+    "cv2": "opencv-python",
+    "PIL": "Pillow",
+    "yaml": "PyYAML",
+    "bs4": "beautifulsoup4",
+    "serial": "pyserial",
+    "dotenv": "python-dotenv",
+    "sklearn": "scikit-learn",
+    "skimage": "scikit-image",
+    "google": "google-api-python-client",
+    "OpenGL": "PyOpenGL",
+    "win32api": "pywin32",
+    "win32con": "pywin32",
+    "win32gui": "pywin32",
+    "wx": "wxPython",
+    "Crypto": "pycryptodome",
+    "usb": "pyusb",
+    "zmq": "pyzmq",
+}
+
+_STDLIB = set(getattr(sys, "stdlib_module_names", set())) | {"__future__"}
+
+# Source-layout / directory-convention names that show up as dangling imports
+# (e.g. code meant to run from a parent dir with ``src/`` on sys.path) but must
+# NEVER be auto-installed — real PyPI packages by these names are never intended.
+_NON_PACKAGE_NAMES = {
+    "src", "test", "tests", "docs", "doc", "examples", "example",
+    "scripts", "build", "dist",
+}
+
+
+def _iter_py_files(root: Path) -> list[Path]:
+    skip = {".git", "__pycache__", ".gitplucker", ".venv", "venv", "node_modules"}
+    files: list[Path] = []
+    for p in root.rglob("*.py"):
+        if any(part in skip for part in p.parts):
+            continue
+        files.append(p)
+    return files
+
+
+def _local_top_levels(root: Path) -> set[str]:
+    """Names that resolve to something *inside* the app, so must never be
+    mistaken for a PyPI dependency.
+
+    Import scanning is inherently noisy (dangling/dev-only imports, code that
+    imports a sibling package by name), and the dangerous failure mode is
+    auto-``pip install``-ing a garbage package that happens to share the name.
+    So this is deliberately permissive: a name is treated as local if anywhere
+    in the payload there is a directory or a ``<name>.py`` with that name — not
+    only at the repo root.
+    """
+    local: set[str] = set()
+    skip = {".git", "__pycache__", ".gitplucker", ".venv", "venv", "node_modules"}
+    for p in root.rglob("*"):
+        if any(part in skip for part in p.relative_to(root).parts):
+            continue
+        if p.is_dir():
+            local.add(p.name)          # any dir name (package or namespace dir)
+        elif p.suffix == ".py":
+            local.add(p.stem)          # any module file, at any depth
+    return local
+
+
+def scan_imports(root: Path) -> dict[str, str]:
+    """Return ``{top_level_module: first_file_relpath}`` for all imports found."""
+    found: dict[str, str] = {}
+    root = Path(root)
+    for py in _iter_py_files(root):
+        try:
+            tree = ast.parse(py.read_text(encoding="utf-8", errors="replace"), filename=str(py))
+        except SyntaxError:
+            continue
+        rel = py.relative_to(root).as_posix()
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    top = alias.name.split(".")[0]
+                    found.setdefault(top, rel)
+            elif isinstance(node, ast.ImportFrom):
+                if node.level and node.level > 0:
+                    continue  # relative import -> local, never a dependency
+                if node.module:
+                    top = node.module.split(".")[0]
+                    found.setdefault(top, rel)
+    return found
+
+
+def _installed_packages() -> set[str]:
+    names: set[str] = set()
+    try:
+        for dist in _im.distributions():
+            name = (dist.metadata["Name"] or "").lower()
+            if name:
+                names.add(name)
+    except Exception:
+        pass
+    return names
+
+
+def _is_satisfied(module: str, package: str, installed: set[str]) -> bool:
+    if package.lower() in installed:
+        return True
+    try:
+        return importlib.util.find_spec(module) is not None
+    except (ImportError, ValueError, ModuleNotFoundError):
+        return False
+
+
+def _parse_requirements(path: Path) -> dict[str, str]:
+    """Map lowercased package name -> full requirement spec from a requirements file."""
+    specs: dict[str, str] = {}
+    if not path.exists():
+        return specs
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or line.startswith("-"):
+            continue
+        name = line
+        for sep in ("==", ">=", "<=", "~=", ">", "<", "!=", "[", ";", " "):
+            idx = line.find(sep)
+            if idx > 0:
+                name = line[:idx]
+                break
+        specs[name.strip().lower()] = line
+    return specs
+
+
+def resolve_dependencies(
+    payload_root: Path,
+    requirements_path: Path | None = None,
+    known_modules: set[str] | None = None,
+) -> list[DependencyChange]:
+    """Compute the dependencies the incoming payload needs but the env lacks.
+
+    ``known_modules`` is the set seen in the *previous* applied version; anything
+    outside it is flagged ``is_new`` (a genuinely newly-added module).
+    """
+    payload_root = Path(payload_root)
+    imports = scan_imports(payload_root)
+    local = _local_top_levels(payload_root)
+    installed = _installed_packages()
+    req_specs = _parse_requirements(requirements_path) if requirements_path else {}
+    known = known_modules or set()
+
+    changes: list[DependencyChange] = []
+    for module, first_file in sorted(imports.items()):
+        if module in _STDLIB or module in local or module in _NON_PACKAGE_NAMES:
+            continue
+        package = PACKAGE_ALIASES.get(module, module)
+        if _is_satisfied(module, package, installed):
+            continue
+        spec = ""
+        req = req_specs.get(package.lower())
+        if req and any(op in req for op in ("==", ">=", "<=", "~=", ">", "<", "!=")):
+            # Preserve pinned version from requirements.txt.
+            spec = req[len(package):].split(";")[0].strip()
+        changes.append(
+            DependencyChange(
+                module=module,
+                package=package,
+                spec=spec,
+                is_new=module not in known,
+                reason=f"imported in {first_file}",
+            )
+        )
+    return changes
+
+
+def install_requirements(
+    requirements: list[str],
+    python: str | None = None,
+    extra_pip_args: list[str] | None = None,
+) -> tuple[bool, str]:
+    """``pip install`` the given requirement strings. Returns ``(ok, output)``."""
+    if not requirements:
+        return True, "nothing to install"
+    cmd = [python or sys.executable, "-m", "pip", "install", *(extra_pip_args or []), *requirements]
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True)
+    except Exception as e:  # pragma: no cover
+        return False, f"failed to launch pip: {e}"
+    return proc.returncode == 0, (proc.stdout + proc.stderr)

gitplucker/errors.py

@@ -0,0 +1,43 @@
+"""Exception hierarchy for gitplucker.
+
+Every error raised by the library derives from :class:`GitpluckerError`, so a
+host application can catch the whole surface with a single ``except``.
+"""
+
+from __future__ import annotations
+
+
+class GitpluckerError(Exception):
+    """Base class for all gitplucker errors."""
+
+
+class ConfigError(GitpluckerError):
+    """The :class:`~gitplucker.config.UpdaterConfig` is invalid or inconsistent."""
+
+
+class RepoNotAllowedError(GitpluckerError):
+    """A repository was requested that is not in ``allowed_repos``.
+
+    This is a hard security boundary: gitplucker will never fetch, download, or
+    apply anything from a repo the host did not explicitly permit.
+    """
+
+
+class SourceError(GitpluckerError):
+    """An update source failed to produce a usable payload."""
+
+
+class GitHubAPIError(SourceError):
+    """The GitHub REST API returned an error or unexpected response."""
+
+    def __init__(self, message: str, status: int | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+class MergeConflictError(GitpluckerError):
+    """A merge produced conflicts and the policy was to abort."""
+
+
+class ApplyError(GitpluckerError):
+    """Applying an update failed; a rollback may have been attempted."""

gitplucker/events.py

@@ -0,0 +1,51 @@
+"""Minimal synchronous event bus so hosts can hook into progress/prompts.
+
+The library never blocks on user input directly; instead it emits events and
+(optionally) asks a decision callback. This keeps it usable from a Qt GUI, a
+CLI, or a headless service alike.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+
+# Well-known event names (documented for integrators). Emitting arbitrary names
+# is fine too; these are just the ones the built-in flow raises.
+CHECK_START = "check.start"
+CHECK_DONE = "check.done"
+DOWNLOAD_PROGRESS = "download.progress"   # payload: {repo, received, total}
+MERGE_FILE = "merge.file"                 # payload: {path, conflict}
+CONFLICT = "conflict"                     # payload: {path, lines}
+DEP_DETECTED = "dep.detected"             # payload: {requirement}
+DEP_INSTALL = "dep.install"               # payload: {requirement, ok}
+APPLY_FILE = "apply.file"                 # payload: {path, change}
+BACKUP = "backup"                         # payload: {path}
+ROLLBACK = "rollback"                     # payload: {path}
+APPLY_DONE = "apply.done"                 # payload: {success}
+
+
+Listener = Callable[[str, dict], None]
+
+
+@dataclass
+class EventEmitter:
+    _listeners: list[Listener] = field(default_factory=list)
+
+    def on(self, listener: Listener) -> Listener:
+        """Register a ``listener(event_name, payload)``. Returns it for easy removal."""
+        self._listeners.append(listener)
+        return listener
+
+    def off(self, listener: Listener) -> None:
+        if listener in self._listeners:
+            self._listeners.remove(listener)
+
+    def emit(self, event: str, **payload: Any) -> None:
+        for listener in list(self._listeners):
+            try:
+                listener(event, payload)
+            except Exception:
+                # A misbehaving listener must never break an update.
+                pass