pyselfupdate 0.5.4__tar.gz → 0.6.0__tar.gz

{pyselfupdate-0.5.4 → pyselfupdate-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyselfupdate
-Version: 0.5.4
+Version: 0.6.0
 Summary: Self-update and update notification for Python CLIs installed with uv tool
 Project-URL: Repository, https://github.com/datapointchris/pyselfupdate
 Project-URL: Issues, https://github.com/datapointchris/pyselfupdate/issues
@@ -143,8 +143,8 @@ fail in ways that are hard to read.
 
 So make `update` the last thing the process does, then call `exit_now`. Or call
 `update_and_reexec`, which replaces the process with the release it installed,
-running the same command line. Its caller never sees the `Result`, so it writes
-`lock_warning` to stderr itself before the re-exec.
+running the same command line. `update_and_reexec` writes `lock_warning` to
+stderr itself before the re-exec, because its caller never sees the `Result`.
 
 `check` reports what `update` would install, and installs nothing:
 
@@ -203,6 +203,8 @@ caller matches a type rather than message text:
 | `NotInstalledError` | uv's receipt is missing or unreadable, or holds a `--with` requirement an update would drop |
 | `NoReleaseError` | The source publishes no release, or its newest tag is not a semantic version |
 | `SourceError` | The source could not be reached, or answered with something unusable |
+| `SelfUpdateSourceFailure` | A `SourceError` from a transport or protocol failure, as opposed to a missing release |
+| `RateLimitedError` | A `SelfUpdateSourceFailure` for a spent rate limit. `authenticated` says which ceiling, and `resets_at` when it lifts, or None |
 | `LockUnreadableError` | The release's `uv.lock` could not be read, so nothing was installed |
 | `InstallFailedError` | `uv tool install` ran and failed, or uv is not on `PATH` |
 

{pyselfupdate-0.5.4 → pyselfupdate-0.6.0}/README.md

@@ -120,8 +120,8 @@ fail in ways that are hard to read.
 
 So make `update` the last thing the process does, then call `exit_now`. Or call
 `update_and_reexec`, which replaces the process with the release it installed,
-running the same command line. Its caller never sees the `Result`, so it writes
-`lock_warning` to stderr itself before the re-exec.
+running the same command line. `update_and_reexec` writes `lock_warning` to
+stderr itself before the re-exec, because its caller never sees the `Result`.
 
 `check` reports what `update` would install, and installs nothing:
 
@@ -180,6 +180,8 @@ caller matches a type rather than message text:
 | `NotInstalledError` | uv's receipt is missing or unreadable, or holds a `--with` requirement an update would drop |
 | `NoReleaseError` | The source publishes no release, or its newest tag is not a semantic version |
 | `SourceError` | The source could not be reached, or answered with something unusable |
+| `SelfUpdateSourceFailure` | A `SourceError` from a transport or protocol failure, as opposed to a missing release |
+| `RateLimitedError` | A `SelfUpdateSourceFailure` for a spent rate limit. `authenticated` says which ceiling, and `resets_at` when it lifts, or None |
 | `LockUnreadableError` | The release's `uv.lock` could not be read, so nothing was installed |
 | `InstallFailedError` | `uv tool install` ran and failed, or uv is not on `PATH` |
 

{pyselfupdate-0.5.4 → pyselfupdate-0.6.0}/pyproject.toml

@@ -42,7 +42,7 @@ dev = [
     "mypy>=1.10.0",
     "pre-commit>=4.3.0",
     "pytest>=8.0.0",
-    "ruff==0.12.5",
+    "ruff==0.17.1",
     "typer>=0.12.0",
 ]
 
@@ -95,6 +95,7 @@ exclude = [
     "build",
     "dist",
 ]
+extend-exclude = ["*.md"]
 
 [tool.ruff.format]
 quote-style = "single"
@@ -158,12 +159,28 @@ major_on_zero = false
 typeCheckingMode = "standard"
 analyzeUnannotatedFunctions = true  # or pylance stops analyzing in vscode
 
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.uv-dynamic-versioning]
+style = "semver"
+
+# A new commit or tag changes the version, so it has to invalidate uv's cache.
+[tool.uv]
+cache-keys = [{ file = "pyproject.toml" }, { git = { commit = true, tags = true } }]
+
+# The published sdist holds the package and its metadata, and none of the
+# repo's tooling or tests. hatchling's default takes the whole tree.
+[tool.hatch.build.targets.sdist]
+only-include = ["src"]
+
 [tool.forge]
 # Keys the shared toolchain standard owns, written by its generator.
 # Dropping one from the template removes it here on the next sync; a key absent
 # from this list belongs to the project and is never touched. Do not hand-edit.
 managed = [
     ["ruff", "line-length"],
+    ["ruff", "extend-exclude"],
     ["ruff", "format", "quote-style"],
     ["ruff", "format", "indent-style"],
     ["ruff", "format", "skip-magic-trailing-comma"],
@@ -197,24 +214,6 @@ managed = [
 # and extra that names them, so a local run and CI cannot disagree.
 pinned = ["ruff"]
 
-# The release tag is the version. python-semantic-release finds no file to
-# stamp, so it tags the merge commit itself and writes no release commit.
-# uv_build cannot do this: its metadata has no dynamic version field.
-[tool.hatch.version]
-source = "uv-dynamic-versioning"
-
-[tool.uv-dynamic-versioning]
-style = "semver"
-
-# A new commit or tag changes the version, so it has to invalidate uv's cache.
-[tool.uv]
-cache-keys = [{ file = "pyproject.toml" }, { git = { commit = true, tags = true } }]
-
-# The published sdist holds the package and its metadata, and none of the
-# repo's tooling or tests, as uv_build's did.
-[tool.hatch.build.targets.sdist]
-only-include = ["src"]
-
 [build-system]
 requires = ["hatchling", "uv-dynamic-versioning"]
 build-backend = "hatchling.build"

{pyselfupdate-0.5.4 → pyselfupdate-0.6.0}/src/pyselfupdate/__init__.py

@@ -24,7 +24,9 @@ from pyselfupdate.errors import LocalInstallError
 from pyselfupdate.errors import LockUnreadableError
 from pyselfupdate.errors import NoReleaseError
 from pyselfupdate.errors import NotInstalledError
+from pyselfupdate.errors import RateLimitedError
 from pyselfupdate.errors import SelfUpdateError
+from pyselfupdate.errors import SelfUpdateSourceFailure
 from pyselfupdate.errors import SourceError
 from pyselfupdate.github import GitHubSource
 from pyselfupdate.install import Installation
@@ -59,9 +61,11 @@ __all__ = [
     'NoReleaseError',
     'NotInstalledError',
     'Outcome',
+    'RateLimitedError',
     'Release',
     'Result',
     'SelfUpdateError',
+    'SelfUpdateSourceFailure',
     'Skip',
     'Source',
     'SourceError',

{pyselfupdate-0.5.4 → pyselfupdate-0.6.0}/src/pyselfupdate/errors.py

@@ -1,10 +1,15 @@
 """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.
+message text. Every class derives from `SelfUpdateError`, which is what a caller
+catches when it does not care why an update did not happen. A class that narrows
+another derives from it, so catching `SourceError` still catches a rate limit.
 """
 
+from __future__ import annotations
+
+import datetime as dt
+
 
 class SelfUpdateError(Exception):
     """Base class for every error this package raises."""
@@ -41,6 +46,31 @@ class SourceError(SelfUpdateError):
     """The release source could not be reached or returned something unusable."""
 
 
+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.
+    """
+
+
+class RateLimitedError(SelfUpdateSourceFailure):
+    """The source's rate limit for this caller is spent.
+
+    `authenticated` says which ceiling was hit. Without a credential the limit
+    is shared by every host behind one address, and supplying a token lifts it.
+    With one, nothing is left to configure, and the caller can only wait.
+    `resets_at` is when the ceiling lifts, in UTC, or None when the response
+    did not say.
+    """
+
+    def __init__(self, message: str, *, authenticated: bool, resets_at: dt.datetime | None = None) -> None:
+        super().__init__(message)
+        self.authenticated = authenticated
+        self.resets_at = resets_at
+
+
 class InstallFailedError(SelfUpdateError):
     """The install command ran and failed."""
 

{pyselfupdate-0.5.4 → pyselfupdate-0.6.0}/src/pyselfupdate/github.py

@@ -27,8 +27,11 @@ from dataclasses import field
 from typing import IO
 
 from pyselfupdate.errors import NoReleaseError
+from pyselfupdate.errors import RateLimitedError
 from pyselfupdate.errors import SelfUpdateError
+from pyselfupdate.errors import SelfUpdateSourceFailure
 from pyselfupdate.errors import SourceError
+from pyselfupdate.install import run_command
 from pyselfupdate.source import Release
 
 API = 'https://api.github.com'
@@ -131,7 +134,7 @@ def token_from_command() -> str:
     if not binary:
         return ''
     try:
-        result = subprocess.run([binary, *argv[1:]], capture_output=True, text=True, check=False, timeout=COMMAND_TIMEOUT_SECONDS)  # noqa: S603
+        result = run_command([binary, *argv[1:]], timeout=COMMAND_TIMEOUT_SECONDS)
     except (OSError, subprocess.SubprocessError):
         return ''
     return result.stdout.strip() if result.returncode == 0 else ''
@@ -306,15 +309,6 @@ class GitHubSource:
             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, *, authenticated: bool) -> SelfUpdateError:
     if error.code == 404:
         # A private repository reached without a token is indistinguishable
@@ -324,12 +318,14 @@ def _http_error(owner: str, repo: str, error: urllib.error.HTTPError, *, authent
     if error.code in (401, 403):
         remaining = error.headers.get('x-ratelimit-remaining') if error.headers else None
         if remaining == '0':
-            return SelfUpdateSourceFailure(_rate_limit_message(error, authenticated=authenticated))
+            resets_at = _reset_moment(error)
+            message = _rate_limit_message(authenticated=authenticated, resets_at=resets_at)
+            return RateLimitedError(message, authenticated=authenticated, resets_at=resets_at)
         return SelfUpdateSourceFailure(f'GitHub refused the request for {owner}/{repo} ({error.code})')
     return SelfUpdateSourceFailure(f'GitHub returned {error.code} for {owner}/{repo}')
 
 
-def _rate_limit_message(error: urllib.error.HTTPError, *, authenticated: bool) -> str:
+def _rate_limit_message(*, authenticated: bool, resets_at: dt.datetime | None) -> str:
     """Which ceiling was hit, and what to do about that one.
 
     The two are different problems with different fixes, and one sentence for
@@ -341,7 +337,10 @@ def _rate_limit_message(error: urllib.error.HTTPError, *, authenticated: bool) -
     The authenticated case should be rare, so it says when the ceiling lifts
     rather than what to change -- there is nothing to change.
     """
-    resets = _reset_clock(error)
+    # A wall-clock time rather than "in 43 minutes", because the message is read
+    # out of a state file long after the request that produced it and a duration
+    # would be counted from the wrong instant.
+    resets = f'; resets at {resets_at:%H:%M} UTC' if resets_at else ''
     if authenticated:
         return f"GitHub's authenticated rate limit (5,000/hour) is exhausted{resets}"
     return (
@@ -350,19 +349,13 @@ def _rate_limit_message(error: urllib.error.HTTPError, *, authenticated: bool) -
     )
 
 
-def _reset_clock(error: urllib.error.HTTPError) -> str:
-    """`; resets at 14:22 UTC`, or nothing when the header is absent or unusable.
-
-    A wall-clock time rather than "in 43 minutes", because the message is read
-    out of a state file long after the request that produced it and a duration
-    would be counted from the wrong instant.
-    """
+def _reset_moment(error: urllib.error.HTTPError) -> dt.datetime | None:
+    """When the spent limit lifts, in UTC, or None when the header is absent or unusable."""
     header = error.headers.get('x-ratelimit-reset') if error.headers else None
     try:
-        moment = dt.datetime.fromtimestamp(int(header or ''), tz=dt.UTC)
+        return dt.datetime.fromtimestamp(int(header or ''), tz=dt.UTC)
     except (TypeError, ValueError, OSError, OverflowError):
-        return ''
-    return f'; resets at {moment:%H:%M} UTC'
+        return None
 
 
 def _quote(ref: str) -> str:

{pyselfupdate-0.5.4 → pyselfupdate-0.6.0}/src/pyselfupdate/install.py

@@ -47,6 +47,14 @@ on one line: uv writes every hash as a continuation line, and
 `_pins_from_export` reads line by line.
 """
 
+LOCK_READ_TIMEOUT_SECONDS = 120.0
+"""The bound on each of the clone and the export that read a release's lock.
+
+Both run before anything is installed, so a stalled remote or a credential
+prompt nobody answers fails the update with `LockUnreadableError` rather than
+holding the command someone typed.
+"""
+
 
 class InstallKind(Enum):
     """How a uv tool was installed, which decides whether it may be updated."""
@@ -64,10 +72,9 @@ class Installation:
     kind: InstallKind
     url: str = ''
 
-    # Whatever followed the `@` at install time: a tag, a branch or a commit,
-    # which uv records alike as `rev=`. Empty when the install follows the
-    # default branch. `updater.installed_from_release` reads it as a release
-    # tag or refuses it.
+    # Whatever followed the `@` at install time, read from the receipt by
+    # `_split_git`. `updater.installed_from_release` reads it as a release tag
+    # or refuses it.
     revision: str = ''
 
     extras: tuple[str, ...] = ()
@@ -95,6 +102,7 @@ def tool_dir() -> Path:
     `UV_TOOL_DIR` first. Otherwise uv's data directory: `%APPDATA%\\uv` on
     Windows, where uv ignores `XDG_DATA_HOME`, and `$XDG_DATA_HOME/uv` or
     `~/.local/share/uv` everywhere else.
+
     Resolved from the environment rather than by running `uv tool dir`, which
     costs a subprocess on a path that runs before every command.
     """
@@ -120,7 +128,11 @@ def read_installation(tool: str) -> Installation:
     """
     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)')
+        raise NotInstalledError(
+            f'{tool} is not installed as a uv tool ({receipt} does not exist). '
+            f"Install a release with `uv tool install '{tool} @ git+<repository url>@<release tag>'`, "
+            f'or `uv tool install {tool}` from a package index'
+        )
 
     try:
         payload = tomllib.loads(receipt.read_text(encoding='utf-8'))
@@ -317,25 +329,37 @@ def read_lock(url: str, ref: str, *, extras: Sequence[str] = ()) -> Pins | None:
     a dependent requests of a git dependency, which `_override_extras` restores.
 
     Raises `LockUnreadableError` when git or uv is not on PATH, the ref will not
-    clone, or uv will not export its lock. None is not a failure:
+    clone, uv will not export its lock, or either outlasts
+    `LOCK_READ_TIMEOUT_SECONDS`. None is not a failure:
     `install_release` installs that tag unlocked and sets `lock_missing`.
     """
     git = shutil.which('git')
     uv = shutil.which('uv')
     if not git or not uv:
         missing = 'git' if not git else 'uv'
-        raise LockUnreadableError(f'{missing} is not on PATH, so the uv.lock at {ref} cannot be read')
+        raise LockUnreadableError(
+            f'{missing} is not on PATH, so the uv.lock at {ref} cannot be read. '
+            f'Install {missing}, or add the directory holding it to PATH, then run the update again'
+        )
 
     # A clone that cannot be deleted stays in the system temp, and the update goes ahead.
     with tempfile.TemporaryDirectory(prefix='pyselfupdate-lock-', ignore_cleanup_errors=True) as scratch:
         checkout = Path(scratch) / 'checkout'
-        cloned = _run([git, 'clone', '--quiet', '--depth', '1', '--branch', ref, url, str(checkout)])
+        clone = [git, 'clone', '--quiet', '--depth', '1', '--branch', ref, url, str(checkout)]
+        try:
+            cloned = run_command(clone, timeout=LOCK_READ_TIMEOUT_SECONDS)
+        except subprocess.TimeoutExpired as error:
+            raise LockUnreadableError(f'cloning {url} at {ref} to read its uv.lock took longer than {error.timeout:g}s') from error
         if cloned.returncode != 0:
             raise LockUnreadableError(f'could not clone {url} at {ref} to read its uv.lock: {_reason(cloned)}')
         lock = checkout / LOCK_NAME
         if not lock.is_file():
             return None
-        exported = _run([uv, *EXPORT, *chain.from_iterable(('--extra', extra) for extra in extras)], cwd=checkout)
+        export = [uv, *EXPORT, *chain.from_iterable(('--extra', extra) for extra in extras)]
+        try:
+            exported = run_command(export, cwd=checkout, timeout=LOCK_READ_TIMEOUT_SECONDS)
+        except subprocess.TimeoutExpired as error:
+            raise LockUnreadableError(f'uv export of the uv.lock at {ref} took longer than {error.timeout:g}s') from error
         if exported.returncode != 0:
             raise LockUnreadableError(f'uv export would not read the uv.lock at {ref}: {_reason(exported)}')
         try:
@@ -416,10 +440,16 @@ def run_install(
     the way `--with` and `--with-editable` install them. `--force` is what
     allows an entry point that already exists to be replaced; without it uv
     refuses rather than overwriting.
+
+    The install runs unbounded. Killed part way, it leaves the tool's
+    environment half rewritten, which is worse than a slow install.
     """
     executable = shutil.which('uv')
     if not executable:
-        raise InstallFailedError('uv is not on PATH, so the tool cannot reinstall itself')
+        raise InstallFailedError(
+            'uv is not on PATH, so the tool cannot reinstall itself. '
+            'Add the directory holding uv to PATH, or install uv from https://docs.astral.sh/uv/, then run the update again'
+        )
 
     with tempfile.TemporaryDirectory(prefix='pyselfupdate-pins-', ignore_cleanup_errors=True) as scratch:
         held = pins.arguments(Path(scratch)) if pins else []
@@ -431,22 +461,28 @@ def run_install(
         command = [executable, 'tool', 'install', '--force', *source_flags, *held, *beside, requirement]
         if quiet:
             command.insert(1, '--quiet')
-        completed = _run(command)
+        completed = run_command(command)
 
     if completed.returncode != 0:
         raise InstallFailedError(f'uv tool install failed: {_reason(completed)}')
 
 
-def _run(command: list[str], cwd: Path | None = None) -> subprocess.CompletedProcess[str]:
-    return subprocess.run(command, cwd=cwd, capture_output=True, text=True, check=False)
+def run_command(command: list[str], *, cwd: Path | None = None, timeout: float | None = None) -> subprocess.CompletedProcess[str]:
+    """Run a program to completion and capture what it printed.
+
+    Every process this package starts goes through here. `timeout` bounds the call in seconds. Past it the program is killed and
+    `subprocess.TimeoutExpired` is raised, which each caller turns into its own
+    failure. None runs unbounded.
+    """
+    return subprocess.run(command, cwd=cwd, capture_output=True, text=True, check=False, timeout=timeout)
 
 
 def _reason(completed: subprocess.CompletedProcess[str]) -> str:
-    """Everything a failing command printed, rather than one line of it.
+    """Everything a failing command printed.
 
-    uv puts a lock's schema error on its first line, git puts a missing ref on
-    its last, and uv wraps a resolution failure so its last line is half a
-    sentence.
+    No single line carries the reason: uv puts a lock's schema error on its
+    first line, git puts a missing ref on its last, and uv wraps a resolution
+    failure so its last line is half a sentence.
     """
     return (completed.stderr or completed.stdout or '').strip() or f'exit status {completed.returncode}'
 

{pyselfupdate-0.5.4 → pyselfupdate-0.6.0}/src/pyselfupdate/notifier.py

@@ -124,10 +124,6 @@ def _asking_for_help() -> bool:
     screen. Nothing a notice is for happens on a help screen, and the check
     costs a releases-API call and a state write every time.
 
-    It lands hardest on a reader that walks a tool's help. Reading every
-    command's help is one invocation per command plus one for the root, and
-    each of them reaches this.
-
     A `--` ends the scan, because everything after it is the command's own
     argument. Skipping when it should not have costs a missed notice, which is
     the cheap direction to be wrong in.

{pyselfupdate-0.5.4 → pyselfupdate-0.6.0}/src/pyselfupdate/typercmd.py

@@ -32,10 +32,39 @@ from pyselfupdate.updater import install_release
 from pyselfupdate.updater import require_updatable
 
 
+def update_help(tool: str, name: str, markup_mode: str | None) -> str:
+    """The update command's help: one line on what it does, then annotated examples.
+
+    Each example keeps a line of its own under each of typer's markup modes,
+    which lay out a help's later paragraphs differently. Markdown joins a
+    paragraph's lines, so the examples sit in a fenced block there. Rich markup
+    keeps the lines as written and would print a fence's backticks. Without
+    rich, click rewraps every paragraph that does not open with its `\\b`
+    marker.
+    """
+    command = f'{tool} {name}'
+    width = len(command) + len(' --no-changelog') + 2
+    examples = '\n'.join(
+        f'{call:<{width}}{purpose}'
+        for call, purpose in (
+            (command, 'install the newest and list its commits'),
+            (f'{command} --check', 'only report whether a newer one exists'),
+            (f'{command} --no-changelog', 'install it without listing its commits'),
+        )
+    )
+    if markup_mode == 'markdown':
+        block = f'```text\n{examples}\n```'
+    elif markup_mode == 'rich':
+        block = examples
+    else:
+        block = f'\b\n{examples}'
+    return f'Update {tool} to the latest release\n\nExamples:\n\n{block}'
+
+
 def add_update_command(app: typer.Typer, config: Config, *, name: str = 'update') -> None:
     """Register `<tool> update` on an existing typer app."""
 
-    @app.command(name=name, help=f'Update {config.tool} to the latest release')
+    @app.command(name=name, help=update_help(config.tool, name, app.rich_markup_mode))
     def update_command(
         check_only: bool = typer.Option(False, '--check', help='Report whether an update is available without installing it'),
         skip_changelog: bool = typer.Option(False, '--no-changelog', help='Do not list the commits between versions'),
@@ -52,17 +81,15 @@ def run_update(config: Config, *, check_only: bool = False, skip_changelog: bool
     library report an update in the same words.
 
     `check_only` reads the receipt first, as an update does, and refuses the
-    same installs. A branch build's version can rank below the release it is
-    ahead of, so a check that skipped the receipt would offer that older
-    release as an update.
-
-    The step order is the load-bearing part. Everything that reaches the network
-    or imports a module happens before the install; after it, this process only
-    prints what it already holds and exits without unwinding. Both halves of
-    that come from a real failure. A tool that fetched its changelog after
-    replacing its own environment died on its HTTP client's lazy import of a
-    transport module. The release it had just installed did not depend on that
-    module, so the install had deleted it.
+    same installs. `updater.installed_from_release` says why a version alone
+    cannot decide.
+
+    Everything that reaches the network or imports a module happens before the
+    install; after it, this process only prints what it already holds and exits
+    without unwinding. An import after the install can name a module the new
+    release no longer ships, which the install has already deleted. An HTTP
+    client's lazy import of its transport is one, and it raises ImportError
+    after the update has succeeded.
     """
     tool = config.tool
     try:

{pyselfupdate-0.5.4 → pyselfupdate-0.6.0}/src/pyselfupdate/updater.py

@@ -60,9 +60,9 @@ class Result:
 def check(config: Config) -> Result:
     """Report whether a newer release exists, without installing anything.
 
-    Compares versions and reads nothing else. A branch build's version can rank
-    below the release it is ahead of, so a caller reporting the result runs
+    Compares versions and reads nothing else. A caller reporting the result runs
     `require_updatable` first, as `update` and `typercmd.run_update` do.
+    `installed_from_release` says why a version alone cannot decide.
     """
     resolved = config.resolved()
     current = _current_version(resolved)
@@ -97,9 +97,8 @@ def installed_from_release(installation: Installation, tag_prefix: str) -> bool:
 
     An index install is. A git install is when its revision is a release tag:
     `tag_prefix` followed by a semantic version, the form a release's
-    `install_ref` takes. uv writes `?rev=` for whatever followed the `@`.
-    `@main` and `@v1.2.3` land in the same field, so only the value tells a
-    branch from a tag.
+    `install_ref` takes. `Installation.revision` holds a branch or a commit in
+    the same field, so only the value tells them apart.
 
     A build from a branch reports a version that ranks wrongly against a
     release. Versioned from git tags, a branch three commits past v1.2.3 builds