pyselfupdate 0.1.0__py3-none-any.whl

pyselfupdate/__init__.py

@@ -0,0 +1,72 @@
+"""Self-update and update notification for tools installed with `uv tool`.
+
+Two layers, used independently:
+
+    from pyselfupdate import Config, notify, update
+
+    config = Config(tool='syncer', owner='datapointchris')
+
+    notify(config)   # once a day, print one line if behind. Never raises.
+    update(config)   # install the latest release. Raises on failure.
+
+`notify` belongs in a CLI's root callback and its result should be ignored.
+`update` belongs behind an explicit `<tool> update` command, which is the only
+place update failures are ever reported.
+
+The package has no third-party dependencies. The optional typer integration
+lives in `pyselfupdate.typercmd` and is installed with the `typer` extra.
+"""
+
+from pyselfupdate.config import Config
+from pyselfupdate.errors import InstallFailedError
+from pyselfupdate.errors import InvalidConfigError
+from pyselfupdate.errors import LocalInstallError
+from pyselfupdate.errors import NoReleaseError
+from pyselfupdate.errors import NotInstalledError
+from pyselfupdate.errors import SelfUpdateError
+from pyselfupdate.errors import SourceError
+from pyselfupdate.github import GitHubSource
+from pyselfupdate.install import Installation
+from pyselfupdate.install import InstallKind
+from pyselfupdate.install import read_installation
+from pyselfupdate.notifier import Outcome
+from pyselfupdate.notifier import Skip
+from pyselfupdate.notifier import enabled
+from pyselfupdate.notifier import notify
+from pyselfupdate.source import Release
+from pyselfupdate.source import Source
+from pyselfupdate.state import State
+from pyselfupdate.state import read as read_state
+from pyselfupdate.updater import Result
+from pyselfupdate.updater import changelog
+from pyselfupdate.updater import check
+from pyselfupdate.updater import update
+from pyselfupdate.updater import update_and_reexec
+
+__all__ = [
+    'Config',
+    'GitHubSource',
+    'InstallFailedError',
+    'InstallKind',
+    'Installation',
+    'InvalidConfigError',
+    'LocalInstallError',
+    'NoReleaseError',
+    'NotInstalledError',
+    'Outcome',
+    'Release',
+    'Result',
+    'SelfUpdateError',
+    'Skip',
+    'Source',
+    'SourceError',
+    'State',
+    'changelog',
+    'check',
+    'enabled',
+    'notify',
+    'read_installation',
+    'read_state',
+    'update',
+    'update_and_reexec',
+]

pyselfupdate/config.py

@@ -0,0 +1,100 @@
+"""What to update, and how to reach it."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from dataclasses import field
+
+from pyselfupdate.errors import InvalidConfigError
+from pyselfupdate.github import GitHubSource
+from pyselfupdate.install import current_version
+from pyselfupdate.source import Source
+
+DEFAULT_TIMEOUT = 10.0
+
+
+@dataclass
+class Config:
+    """Describes one updatable tool.
+
+    `tool` is the only required field. Everything else either has a working
+    default or is derived from it, so the common case is `Config(tool='syncer',
+    owner='datapointchris')`.
+    """
+
+    # The uv tool name. Names the receipt directory, the entry point, and the
+    # state file, and is what appears in messages.
+    tool: str
+
+    owner: str = ''
+    repo: str = ''
+
+    # The distribution name to read the running version from, when it differs
+    # from the tool name. Defaults to `tool`.
+    package: str = ''
+
+    # The running version. Defaults to the installed distribution's metadata,
+    # which is correct for anything installed as a uv tool.
+    version: str = ''
+
+    token: str = ''
+    timeout: float = DEFAULT_TIMEOUT
+    allow_prerelease: bool = False
+
+    # Selects one release stream in a repository publishing several, as in
+    # "cli/" for tags of the form cli/v1.2.3. Configures the default GitHub
+    # source and is unused when `source` is supplied.
+    tag_prefix: str = ''
+
+    # Locates releases. Defaults to a GitHubSource built from the fields above.
+    source: Source | None = None
+
+    metadata: dict[str, str] = field(default_factory=dict)
+
+    def require_source(self) -> Source:
+        """The resolved source.
+
+        `resolved()` always populates `source`, but the field stays optional so
+        that constructing a Config does not require one. This is the accessor
+        that expresses "past this point it is set", rather than each caller
+        asserting it.
+        """
+        if self.source is None:
+            raise InvalidConfigError('config was not resolved before use')
+        return self.source
+
+    def resolved(self) -> Config:
+        """A copy with every default filled in, so callers can assume they are set."""
+        if not self.tool:
+            raise InvalidConfigError('tool is required')
+
+        source = self.source
+        owner = self.owner
+        repo = self.repo or self.tool
+
+        if source is None:
+            if not owner:
+                raise InvalidConfigError('owner is required without a custom source')
+            source = GitHubSource(
+                owner=owner,
+                repo=repo,
+                token=self.token,
+                timeout=self.timeout,
+                allow_prerelease=self.allow_prerelease,
+                tag_prefix=self.tag_prefix,
+            )
+
+        package = self.package or self.tool
+        return Config(
+            tool=self.tool,
+            owner=owner,
+            repo=repo,
+            package=package,
+            version=self.version or current_version(package),
+            token=self.token,
+            timeout=self.timeout,
+            allow_prerelease=self.allow_prerelease,
+            tag_prefix=self.tag_prefix,
+            source=source,
+            metadata=self.metadata.copy(),
+        )

pyselfupdate/errors.py

@@ -0,0 +1,39 @@
+"""Exceptions raised by pyselfupdate.
+
+Every failure mode has its own class so callers match on a type rather than on
+message text. The hierarchy is one level deep under `SelfUpdateError`, which is
+what a caller catches when it does not care why an update did not happen.
+"""
+
+
+class SelfUpdateError(Exception):
+    """Base class for every error this package raises."""
+
+
+class InvalidConfigError(SelfUpdateError):
+    """A Config is missing a required field."""
+
+
+class LocalInstallError(SelfUpdateError):
+    """The tool was installed from a local path or as an editable checkout.
+
+    Reinstalling would discard a working copy for a release that may be older,
+    with no way to tell which is newer. This is the analogue of goselfupdate's
+    ErrDevBuild.
+    """
+
+
+class NotInstalledError(SelfUpdateError):
+    """The tool is not installed as a uv tool, so there is nothing to update."""
+
+
+class NoReleaseError(SelfUpdateError):
+    """The source publishes no usable release."""
+
+
+class SourceError(SelfUpdateError):
+    """The release source could not be reached or returned something unusable."""
+
+
+class InstallFailedError(SelfUpdateError):
+    """The install command ran and failed."""

pyselfupdate/github.py

@@ -0,0 +1,182 @@
+"""GitHub as a release source.
+
+Uses `urllib.request` rather than httpx or requests, because the whole point of
+this package is that adding it to a project adds nothing else.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from dataclasses import field
+
+from pyselfupdate.errors import NoReleaseError
+from pyselfupdate.errors import SelfUpdateError
+from pyselfupdate.errors import SourceError
+from pyselfupdate.source import Release
+
+API = 'https://api.github.com'
+DEFAULT_TIMEOUT = 10.0
+
+
+def token_from_env() -> str:
+    """A token from the environment, or an empty string.
+
+    Deliberately does not shell out to `gh auth token`. A library should not
+    spawn a subprocess a caller did not ask for, and a caller who wants that
+    behaviour can pass the token in. This matches goselfupdate.
+    """
+    return os.environ.get('GITHUB_TOKEN') or os.environ.get('GH_TOKEN') or ''
+
+
+@dataclass
+class GitHubSource:
+    """Releases published on GitHub.
+
+    Without a token GitHub allows 60 API requests per hour per IP address and
+    rejects private repositories outright.
+    """
+
+    owner: str
+    repo: str
+    token: str = ''
+    timeout: float = DEFAULT_TIMEOUT
+    allow_prerelease: bool = False
+
+    # Selects one release stream in a repository publishing several, as in
+    # "cli/" for tags of the form cli/v1.2.3. GitHub's /releases/latest cannot
+    # express this -- it returns whichever release is newest overall -- so a
+    # prefix switches to listing and filtering.
+    tag_prefix: str = ''
+
+    headers: dict[str, str] = field(default_factory=dict)
+
+    def latest_release(self) -> Release:
+        if self.tag_prefix or self.allow_prerelease:
+            return self._latest_from_list()
+        return self._latest_from_endpoint()
+
+    def changelog(self, from_ref: str, to_ref: str) -> list[str]:
+        """Commit subjects between two tags, newest last.
+
+        Returns an empty list rather than raising: a missing changelog is not a
+        reason to fail an update that already succeeded.
+        """
+        if not from_ref or not to_ref or from_ref == to_ref:
+            return []
+        path = f'/repos/{self.owner}/{self.repo}/compare/{_quote(from_ref)}...{_quote(to_ref)}'
+        try:
+            payload = self._get(path)
+        except SelfUpdateError:
+            # Every failure, not just transport ones. A tag that GitHub cannot
+            # compare -- because the older one was deleted, or the release was
+            # cut from a different branch -- returns 404, and reporting that as
+            # a failed update after the install already succeeded would be a lie.
+            return []
+        subjects = []
+        for commit in payload.get('commits') or []:
+            message = (commit.get('commit') or {}).get('message') or ''
+            subject = message.splitlines()[0].strip() if message else ''
+            if subject:
+                subjects.append(subject)
+        return subjects
+
+    def _latest_from_endpoint(self) -> Release:
+        payload = self._get(f'/repos/{self.owner}/{self.repo}/releases/latest')
+        tag = payload.get('tag_name') or ''
+        if not tag:
+            raise NoReleaseError(f'{self.owner}/{self.repo} publishes no release')
+        return self._release(payload, tag)
+
+    def _latest_from_list(self) -> Release:
+        # Releases come back newest-first, so the first match is the latest.
+        payload = self._get(f'/repos/{self.owner}/{self.repo}/releases?per_page=100')
+        if not isinstance(payload, list):
+            raise SourceError(f'unexpected response listing releases for {self.owner}/{self.repo}')
+
+        for entry in payload:
+            if entry.get('draft'):
+                continue
+            if entry.get('prerelease') and not self.allow_prerelease:
+                continue
+            tag = entry.get('tag_name') or ''
+            if not tag or not tag.startswith(self.tag_prefix):
+                continue
+            return self._release(entry, tag)
+
+        wanted = f' with prefix {self.tag_prefix!r}' if self.tag_prefix else ''
+        raise NoReleaseError(f'{self.owner}/{self.repo} publishes no release{wanted}')
+
+    def _release(self, payload: dict, tag: str) -> Release:
+        return Release(
+            tag=tag.removeprefix(self.tag_prefix),
+            ref=tag,
+            url=payload.get('html_url') or '',
+            notes=payload.get('body') or '',
+        )
+
+    def _get(self, path: str):
+        url = f'{API}{path}'
+
+        # urlopen honours file:, ftp: and data: as readily as http:. API is a
+        # constant here, but it is a module attribute a caller can reassign --
+        # tests do exactly that -- so the scheme is checked rather than assumed.
+        # Without this, setting it to a file: URL turns a release check into an
+        # arbitrary file read.
+        scheme = urllib.parse.urlparse(url).scheme
+        if scheme not in ('https', 'http'):
+            raise SourceError(f'refusing to fetch {scheme or "a schemeless URL"}: only http and https are allowed')
+
+        request = urllib.request.Request(url)
+        request.add_header('Accept', 'application/vnd.github+json')
+        request.add_header('X-GitHub-Api-Version', '2022-11-28')
+        request.add_header('User-Agent', 'pyselfupdate')
+        token = self.token or token_from_env()
+        if token:
+            request.add_header('Authorization', f'Bearer {token}')
+        for name, value in self.headers.items():
+            request.add_header(name, value)
+
+        try:
+            # B310 is a call blacklist rather than a dataflow check, so it fires
+            # on urlopen regardless of the scheme guard above. That guard, and
+            # test_a_non_http_scheme_is_refused, are the actual defence.
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:  # noqa: S310  # nosec B310
+                return json.load(response)
+        except urllib.error.HTTPError as error:
+            raise _http_error(self.owner, self.repo, error) from error
+        except urllib.error.URLError as error:
+            raise SelfUpdateSourceFailure(f'cannot reach {API}: {error.reason}') from error
+        except json.JSONDecodeError as error:
+            raise SelfUpdateSourceFailure(f'{API}{path} returned invalid JSON') from error
+
+
+class SelfUpdateSourceFailure(SourceError):
+    """A transport or protocol failure, as opposed to a missing release.
+
+    Distinct from NoReleaseError so a caller can tell "GitHub is unreachable"
+    apart from "this repository has published nothing", which are the same HTTP
+    status for a private repository and want different messages.
+    """
+
+
+def _http_error(owner: str, repo: str, error: urllib.error.HTTPError) -> SelfUpdateError:
+    if error.code == 404:
+        # A private repository reached without a token is indistinguishable
+        # from one that does not exist, and saying so is more useful than
+        # reporting a bare 404.
+        return NoReleaseError(f'{owner}/{repo} has no releases, or is private and no token was supplied')
+    if error.code in (401, 403):
+        remaining = error.headers.get('x-ratelimit-remaining') if error.headers else None
+        if remaining == '0':
+            return SelfUpdateSourceFailure('GitHub API rate limit exceeded; set GITHUB_TOKEN to raise it')
+        return SelfUpdateSourceFailure(f'GitHub refused the request for {owner}/{repo} ({error.code})')
+    return SelfUpdateSourceFailure(f'GitHub returned {error.code} for {owner}/{repo}')
+
+
+def _quote(ref: str) -> str:
+    return urllib.parse.quote(ref, safe='')

pyselfupdate/install.py

@@ -0,0 +1,176 @@
+"""Reading and rewriting a uv tool installation.
+
+This is the part with no analogue in goselfupdate. A Go tool updates by
+replacing one file; a uv tool updates by rebuilding the virtual environment its
+own interpreter is running inside, which is why `update` must be the last thing
+a process does before it exits or re-execs.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import tomllib
+from dataclasses import dataclass
+from enum import Enum
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as installed_version
+from pathlib import Path
+
+from pyselfupdate.errors import InstallFailedError
+from pyselfupdate.errors import NotInstalledError
+
+RECEIPT_NAME = 'uv-receipt.toml'
+
+
+class InstallKind(Enum):
+    """How a uv tool was installed, which decides whether it may be updated."""
+
+    GIT = 'git'
+    INDEX = 'index'
+    LOCAL = 'local'
+
+
+@dataclass(frozen=True)
+class Installation:
+    """What uv's own receipt says about an installed tool."""
+
+    tool: str
+    kind: InstallKind
+    url: str = ''
+
+    # The requested revision, empty when the install tracks the default branch.
+    # An empty value on a GIT install is the interesting case: the tool was
+    # installed from a moving target, so "up to date" has no meaning.
+    revision: str = ''
+
+    def is_updatable(self) -> bool:
+        return self.kind is not InstallKind.LOCAL
+
+
+def tool_dir() -> Path:
+    """uv's tool directory.
+
+    Resolved from the environment rather than by running `uv tool dir`, which
+    costs a subprocess on a path that runs before every command.
+    """
+    override = os.environ.get('UV_TOOL_DIR')
+    if override:
+        return Path(override).expanduser()
+    data_home = os.environ.get('XDG_DATA_HOME')
+    base = Path(data_home).expanduser() if data_home else Path.home() / '.local' / 'share'
+    return base / 'uv' / 'tools'
+
+
+def read_installation(tool: str) -> Installation:
+    """Parse uv's receipt for a tool.
+
+    The receipt is uv's own record of how it installed something, written at
+    install time. Reading it beats inferring the same thing at runtime from the
+    executable's path, which cannot tell "uv put it there" apart from "someone
+    dropped a binary in the same directory".
+    """
+    receipt = tool_dir() / tool / RECEIPT_NAME
+    if not receipt.is_file():
+        raise NotInstalledError(f'{tool} is not installed as a uv tool ({receipt} does not exist)')
+
+    try:
+        payload = tomllib.loads(receipt.read_text(encoding='utf-8'))
+    except (OSError, tomllib.TOMLDecodeError) as error:
+        raise NotInstalledError(f'cannot read {receipt}: {error}') from error
+
+    requirements = (payload.get('tool') or {}).get('requirements') or []
+    for requirement in requirements:
+        if requirement.get('name') != tool:
+            continue
+
+        # A local checkout, however uv spelled it. Reinstalling one would
+        # discard the working copy the user is developing against.
+        for key in ('directory', 'path', 'editable'):
+            if requirement.get(key):
+                return Installation(tool, InstallKind.LOCAL, url=str(requirement[key]))
+
+        git = requirement.get('git')
+        if git:
+            url, _, query = str(git).partition('?')
+            return Installation(tool, InstallKind.GIT, url=url, revision=_revision(query))
+
+        return Installation(tool, InstallKind.INDEX)
+
+    raise NotInstalledError(f'{receipt} lists no requirement named {tool}')
+
+
+def _revision(query: str) -> str:
+    """The `rev=` from a git requirement's query string.
+
+    uv writes `...git?rev=v1.2.3` for a pinned install and omits the query
+    entirely for one that follows the default branch.
+    """
+    for part in query.split('&'):
+        key, _, value = part.partition('=')
+        if key == 'rev' and value:
+            return value
+    return ''
+
+
+def current_version(package: str) -> str:
+    """The running build's version, or an empty string when unknown."""
+    try:
+        return installed_version(package)
+    except PackageNotFoundError:
+        return ''
+
+
+def requirement_for(installation: Installation, ref: str) -> str:
+    """The requirement string that installs `ref` of an already-installed tool."""
+    if installation.kind is InstallKind.GIT:
+        return f'{installation.tool} @ git+{installation.url}@{ref}'
+    return f'{installation.tool}=={ref.removeprefix("v")}'
+
+
+def run_install(requirement: str, *, quiet: bool = True) -> None:
+    """Install a requirement over the existing tool.
+
+    `--force` is what allows an entry point that already exists to be replaced;
+    without it uv refuses rather than overwriting.
+    """
+    executable = shutil.which('uv')
+    if not executable:
+        raise InstallFailedError('uv is not on PATH, so the tool cannot reinstall itself')
+
+    command = [executable, 'tool', 'install', '--force', requirement]
+    if quiet:
+        command.insert(1, '--quiet')
+
+    completed = subprocess.run(  # noqa: S603 - argv is built here, never a shell string
+        command,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if completed.returncode != 0:
+        detail = (completed.stderr or completed.stdout or '').strip().splitlines()
+        message = detail[-1] if detail else f'exit status {completed.returncode}'
+        raise InstallFailedError(f'uv tool install failed: {message}')
+
+
+def reexec() -> None:
+    """Replace this process with the newly installed one.
+
+    `uv tool install --force` rewrites the virtual environment this interpreter
+    is running inside. Unlike a binary rename -- where the process holds an
+    inode and is untouched -- that pulls modules out from under a live process,
+    so anything imported afterwards may fail in ways that are very hard to read.
+    Re-exec immediately, with everything already imported.
+
+    Never returns.
+    """
+    sys.stdout.flush()
+    sys.stderr.flush()
+    # Re-exec is the operation, so B606 cannot be designed away. argv[0] is this
+    # program and argv is passed through unchanged -- no shell, no interpolation.
+    # subprocess plus sys.exit would satisfy the linter and be strictly worse:
+    # an extra process, signal forwarding to hand-roll, and both images resident.
+    os.execv(sys.argv[0], sys.argv)  # noqa: S606  # nosec B606