pyselfupdate 0.4.1__tar.gz → 0.5.0__tar.gz

pyselfupdate-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Birch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{pyselfupdate-0.4.1 → pyselfupdate-0.5.0}/PKG-INFO

@@ -1,15 +1,15 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: pyselfupdate
-Version: 0.4.1
+Version: 0.5.0
 Summary: Self-update and update notification for Python CLIs installed with uv tool
 Keywords: uv,cli,self-update,update-notifier,release
 Author: Chris Birch
 Author-email: Chris Birch <datapointchris@gmail.com>
-License: MIT
+License-Expression: MIT
+License-File: LICENSE
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: System :: Software Distribution
@@ -56,9 +56,9 @@ version exists, so it silently drifts. The usual fix drags an HTTP client, a
 TOML parser and a version library into a tool that had none of them.
 
 This package has zero runtime dependencies — `urllib` for the network,
-`tomllib` for uv's receipt, and its own semver implementation — and CI enforces
-that by importing every module into a virtual environment containing nothing
-else.
+`tomllib` for uv's receipt and lock, and its own semver implementation — and
+CI enforces that by importing every module into a virtual environment
+containing nothing else.
 
 ## notify
 
@@ -128,7 +128,8 @@ environment the running interpreter lives in**. Unlike replacing a Unix binary
 from under a live process, so anything imported afterwards may fail in ways
 that are hard to read. Make it the last thing your process does, then call
 `exit_now` — or use `update_and_reexec` to replace the process with the new
-version immediately.
+version immediately. Its caller never sees the `Result`, so it writes
+`lock_warning` to stderr itself before the re-exec.
 
 That cuts both ways: anything you want to *print* after the install has to be
 fetched before it. `run_update` resolves its changelog first for exactly this
@@ -139,11 +140,34 @@ pieces `update` is made of rather than working around it:
 installation = require_updatable(config)  # refuses a checkout, costs nothing
 result = check(config)  # network, environment still intact
 notes = changelog(config, result.current, result.latest)
-install_release(config, result, installation)
+installed = install_release(config, result, installation)
 print(notes)
+if installed.lock_warning:
+    print(installed.lock_warning, file=sys.stderr)
 exit_now()
 ```
 
+### A git install is held to the release's `uv.lock`
+
+`uv tool install` never reads a lock. Handed a git requirement, it resolves
+every dependency to the newest version, so a tool would run on a set its CI
+never tested. `update` therefore clones the release's tag, exports its
+`uv.lock`, and passes registry pins as `--constraints` and git pins as
+`--overrides`. uv records both in the tool's receipt, so a later
+`uv tool upgrade` stays held to them.
+
+| The tag | What `update` does |
+| --- | --- |
+| Carries a `uv.lock` | Installs the locked versions |
+| Carries none | Installs unlocked and sets `lock_missing`. `lock_warning` names the tag, and `run_update` and `update_and_reexec` print it |
+| Will not clone, or uv will not export its lock | Raises `LockUnreadableError` and installs nothing |
+
+An install from an index reads no lock, because a wheel carries none.
+
+An update reinstalls the tool's own extras, as in `mytool[fast]`, with their
+dependencies held to the lock. Every `--with` and `--with-editable`
+requirement is passed back to uv as well.
+
 ## What will not be updated
 
 Read from uv's own receipt, written at install time, rather than guessed at
@@ -155,6 +179,7 @@ runtime:
 | `name = "mytool"` (from an index) | Updatable |
 | `git = "...git"` with no `rev` | Refused — tracks a branch, so its version says nothing about how far behind it is |
 | `directory` / `path` / `editable` | Refused — reinstalling would discard a working copy |
+| A `--with` requirement no requirements-file line reproduces, such as a relative path | Refused with `NotInstalledError` — the update would drop it |
 
 A tool that cannot be identified at all is treated as local and left alone.
 
@@ -206,8 +231,8 @@ It never raises. A command that is not installed, exits non-zero, or takes
 longer than ten seconds degrades to an unauthenticated request, which still
 works against a public repository.
 
-`token_func` is now only for a credential neither the environment nor a command
-can produce. It is called lazily, for the same reason the command is: the notify
+`token_func` is for a credential neither the environment nor a command can
+produce. It is called lazily, for the same reason the command is: the notify
 gate resolves a `Config` on every invocation and declines most of them without
 reaching the network, and a subprocess in front of that gate is the entire cost
 worth avoiding.

{pyselfupdate-0.4.1 → pyselfupdate-0.5.0}/README.md

@@ -32,9 +32,9 @@ version exists, so it silently drifts. The usual fix drags an HTTP client, a
 TOML parser and a version library into a tool that had none of them.
 
 This package has zero runtime dependencies — `urllib` for the network,
-`tomllib` for uv's receipt, and its own semver implementation — and CI enforces
-that by importing every module into a virtual environment containing nothing
-else.
+`tomllib` for uv's receipt and lock, and its own semver implementation — and
+CI enforces that by importing every module into a virtual environment
+containing nothing else.
 
 ## notify
 
@@ -104,7 +104,8 @@ environment the running interpreter lives in**. Unlike replacing a Unix binary
 from under a live process, so anything imported afterwards may fail in ways
 that are hard to read. Make it the last thing your process does, then call
 `exit_now` — or use `update_and_reexec` to replace the process with the new
-version immediately.
+version immediately. Its caller never sees the `Result`, so it writes
+`lock_warning` to stderr itself before the re-exec.
 
 That cuts both ways: anything you want to *print* after the install has to be
 fetched before it. `run_update` resolves its changelog first for exactly this
@@ -115,11 +116,34 @@ pieces `update` is made of rather than working around it:
 installation = require_updatable(config)  # refuses a checkout, costs nothing
 result = check(config)  # network, environment still intact
 notes = changelog(config, result.current, result.latest)
-install_release(config, result, installation)
+installed = install_release(config, result, installation)
 print(notes)
+if installed.lock_warning:
+    print(installed.lock_warning, file=sys.stderr)
 exit_now()
 ```
 
+### A git install is held to the release's `uv.lock`
+
+`uv tool install` never reads a lock. Handed a git requirement, it resolves
+every dependency to the newest version, so a tool would run on a set its CI
+never tested. `update` therefore clones the release's tag, exports its
+`uv.lock`, and passes registry pins as `--constraints` and git pins as
+`--overrides`. uv records both in the tool's receipt, so a later
+`uv tool upgrade` stays held to them.
+
+| The tag | What `update` does |
+| --- | --- |
+| Carries a `uv.lock` | Installs the locked versions |
+| Carries none | Installs unlocked and sets `lock_missing`. `lock_warning` names the tag, and `run_update` and `update_and_reexec` print it |
+| Will not clone, or uv will not export its lock | Raises `LockUnreadableError` and installs nothing |
+
+An install from an index reads no lock, because a wheel carries none.
+
+An update reinstalls the tool's own extras, as in `mytool[fast]`, with their
+dependencies held to the lock. Every `--with` and `--with-editable`
+requirement is passed back to uv as well.
+
 ## What will not be updated
 
 Read from uv's own receipt, written at install time, rather than guessed at
@@ -131,6 +155,7 @@ runtime:
 | `name = "mytool"` (from an index) | Updatable |
 | `git = "...git"` with no `rev` | Refused — tracks a branch, so its version says nothing about how far behind it is |
 | `directory` / `path` / `editable` | Refused — reinstalling would discard a working copy |
+| A `--with` requirement no requirements-file line reproduces, such as a relative path | Refused with `NotInstalledError` — the update would drop it |
 
 A tool that cannot be identified at all is treated as local and left alone.
 
@@ -182,8 +207,8 @@ It never raises. A command that is not installed, exits non-zero, or takes
 longer than ten seconds degrades to an unauthenticated request, which still
 works against a public repository.
 
-`token_func` is now only for a credential neither the environment nor a command
-can produce. It is called lazily, for the same reason the command is: the notify
+`token_func` is for a credential neither the environment nor a command can
+produce. It is called lazily, for the same reason the command is: the notify
 gate resolves a `Config` on every invocation and declines most of them without
 reaching the network, and a subprocess in front of that gate is the entire cost
 worth avoiding.

{pyselfupdate-0.4.1 → pyselfupdate-0.5.0}/pyproject.toml

@@ -1,7 +1,9 @@
 [project]
 name = "pyselfupdate"
-version = "0.4.1"
+version = "0.5.0"
 description = "Self-update and update notification for Python CLIs installed with uv tool"
+license = "MIT"
+license-files = ["LICENSE"]
 readme = "README.md"
 keywords = [
     "uv",
@@ -14,7 +16,6 @@ classifiers = [
     "Development Status :: 4 - Beta",
     "Environment :: Console",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3 :: Only",
     "Topic :: Software Development :: Libraries",
     "Topic :: System :: Software Distribution",
@@ -27,9 +28,6 @@ dependencies = []
 name = "Chris Birch"
 email = "datapointchris@gmail.com"
 
-[project.license]
-text = "MIT"
-
 [project.optional-dependencies]
 typer = ["typer>=0.12.0"]
 
@@ -44,7 +42,7 @@ dev = [
     "mypy>=1.10.0",
     "pre-commit>=4.3.0",
     "pytest>=8.0.0",
-    "ruff>=0.7.0",
+    "ruff==0.12.5",
     "typer>=0.12.0",
 ]
 
@@ -112,6 +110,7 @@ select = [
     "B",
     "SIM",
     "I",
+    "ICN",
 ]
 ignore = ["SIM108"]
 
@@ -121,9 +120,21 @@ force-single-line = true
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401"]
 
+[tool.ruff.lint.flake8-import-conventions]
+banned-from = [
+    "datetime",
+    "pyspark.sql.functions",
+    "pyspark.sql.types",
+]
+
+[tool.ruff.lint.flake8-import-conventions.extend-aliases]
+datetime = "dt"
+sqlalchemy = "sa"
+"pyspark.sql.functions" = "sf"
+"pyspark.sql.types" = "st"
+
 [tool.semantic_release]
 version_toml = ["pyproject.toml:project.version"]
-branch = "main"
 commit_message = "build(release): {version}"
 build_command = """
     pip install uv
@@ -181,6 +192,40 @@ managed = [
     "lint",
     "isort",
     "force-single-line",
+],
+    [
+    "ruff",
+    "lint",
+    "flake8-import-conventions",
+    "banned-from",
+],
+    [
+    "ruff",
+    "lint",
+    "flake8-import-conventions",
+    "extend-aliases",
+    "datetime",
+],
+    [
+    "ruff",
+    "lint",
+    "flake8-import-conventions",
+    "extend-aliases",
+    "sqlalchemy",
+],
+    [
+    "ruff",
+    "lint",
+    "flake8-import-conventions",
+    "extend-aliases",
+    "pyspark.sql.functions",
+],
+    [
+    "ruff",
+    "lint",
+    "flake8-import-conventions",
+    "extend-aliases",
+    "pyspark.sql.types",
 ],
     [
     "ruff",
@@ -244,11 +289,12 @@ managed = [
     "testpaths",
 ],
 ]
+pinned = ["ruff"]
 
 [tool.uv.build-backend]
 module-name = "pyselfupdate"
 module-root = "src"
 
 [build-system]
-requires = ["uv_build>=0.11.32,<0.12.0"]
+requires = ["uv_build>=0.12.2,<0.13.0"]
 build-backend = "uv_build"

{pyselfupdate-0.4.1 → pyselfupdate-0.5.0}/pyproject.toml.orig

@@ -1,16 +1,16 @@
 [project]
 name = "pyselfupdate"
-version = "0.4.1"
+version = "0.5.0"
 description = "Self-update and update notification for Python CLIs installed with uv tool"
 authors = [{ name = "Chris Birch", email = "datapointchris@gmail.com" }]
-license = { text = "MIT" }
+license = "MIT"
+license-files = ["LICENSE"]
 readme = "README.md"
 keywords = ["uv", "cli", "self-update", "update-notifier", "release"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Environment :: Console",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3 :: Only",
     "Topic :: Software Development :: Libraries",
     "Topic :: System :: Software Distribution",
@@ -42,7 +42,7 @@ dev = [
     "mypy>=1.10.0",
     "pre-commit>=4.3.0",
     "pytest>=8.0.0",
-    "ruff>=0.7.0",
+    "ruff==0.12.5",
     "typer>=0.12.0",
 ]
 
@@ -111,6 +111,7 @@ select = [
     "B",    # flake8-bugbear
     "SIM",  # flake8-simplify
     "I",    # isort
+    "ICN",  # flake8-import-conventions
 ]
 ignore = [
     "SIM108",  # ternary operator — often less readable
@@ -122,9 +123,17 @@ force-single-line = true
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401"]
 
+[tool.ruff.lint.flake8-import-conventions]
+banned-from = ["datetime", "pyspark.sql.functions", "pyspark.sql.types"]
+
+[tool.ruff.lint.flake8-import-conventions.extend-aliases]
+datetime = "dt"
+sqlalchemy = "sa"
+"pyspark.sql.functions" = "sf"
+"pyspark.sql.types" = "st"
+
 [tool.semantic_release]
 version_toml = ["pyproject.toml:project.version"]
-branch = "main"
 commit_message = "build(release): {version}"
 build_command = """
     pip install uv
@@ -154,6 +163,11 @@ managed = [
     ["ruff", "lint", "select"],
     ["ruff", "lint", "ignore"],
     ["ruff", "lint", "isort", "force-single-line"],
+    ["ruff", "lint", "flake8-import-conventions", "banned-from"],
+    ["ruff", "lint", "flake8-import-conventions", "extend-aliases", "datetime"],
+    ["ruff", "lint", "flake8-import-conventions", "extend-aliases", "sqlalchemy"],
+    ["ruff", "lint", "flake8-import-conventions", "extend-aliases", "pyspark.sql.functions"],
+    ["ruff", "lint", "flake8-import-conventions", "extend-aliases", "pyspark.sql.types"],
     ["ruff", "lint", "per-file-ignores", "__init__.py"],
     ["mypy", "pretty"],
     ["mypy", "ignore_missing_imports"],
@@ -169,9 +183,12 @@ managed = [
     ["pytest", "ini_options", "minversion"],
     ["pytest", "ini_options", "testpaths"],
 ]
+# Dependencies held at the version the pre-commit hook runs, in every group
+# and extra that names them, so a local run and CI cannot disagree.
+pinned = ["ruff"]
 
 [build-system]
-requires = ["uv_build>=0.11.32,<0.12.0"]
+requires = ["uv_build>=0.12.2,<0.13.0"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]

{pyselfupdate-0.4.1 → pyselfupdate-0.5.0}/src/pyselfupdate/__init__.py

@@ -21,6 +21,7 @@ from pyselfupdate.config import Config
 from pyselfupdate.errors import InstallFailedError
 from pyselfupdate.errors import InvalidConfigError
 from pyselfupdate.errors import LocalInstallError
+from pyselfupdate.errors import LockUnreadableError
 from pyselfupdate.errors import NoReleaseError
 from pyselfupdate.errors import NotInstalledError
 from pyselfupdate.errors import SelfUpdateError
@@ -54,6 +55,7 @@ __all__ = [
     'Installation',
     'InvalidConfigError',
     'LocalInstallError',
+    'LockUnreadableError',
     'NoReleaseError',
     'NotInstalledError',
     'Outcome',

{pyselfupdate-0.4.1 → pyselfupdate-0.5.0}/src/pyselfupdate/errors.py

@@ -24,7 +24,11 @@ class LocalInstallError(SelfUpdateError):
 
 
 class NotInstalledError(SelfUpdateError):
-    """The tool is not installed as a uv tool, so there is nothing to update."""
+    """uv's receipt is missing, unreadable, or names no requirement for the tool.
+
+    `update` raises it too when the receipt lists a `--with` requirement that no
+    requirements-file line reproduces, because reinstalling would drop it.
+    """
 
 
 class NoReleaseError(SelfUpdateError):
@@ -37,3 +41,12 @@ class SourceError(SelfUpdateError):
 
 class InstallFailedError(SelfUpdateError):
     """The install command ran and failed."""
+
+
+class LockUnreadableError(SelfUpdateError):
+    """The release's `uv.lock` could not be read, so nothing was installed.
+
+    Raised when git or uv is not on PATH, the tag will not clone, or `uv export`
+    refuses the lock. A tag with no `uv.lock` at all is not this error: it
+    installs unlocked and sets `Result.lock_missing`.
+    """

{pyselfupdate-0.4.1 → pyselfupdate-0.5.0}/src/pyselfupdate/github.py

@@ -1,11 +1,18 @@
 """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.
+Uses `urllib.request` rather than httpx2. The package makes one JSON request and
+downloads nothing, and tools with no HTTP client of their own take it for
+self-update, so a client library would land in their dependency tree for this
+one call. `_CredentialScopedRedirects` covers the redirect hazard a client would.
+
+It moves to httpx2 when this package needs a second request shape — a client
+object, streaming, an asset download — or when every consumer already declares
+httpx2.
 """
 
 from __future__ import annotations
 
+import datetime as dt
 import http.client
 import json
 import os
@@ -18,8 +25,6 @@ import urllib.request
 from collections.abc import Callable
 from dataclasses import dataclass
 from dataclasses import field
-from datetime import UTC
-from datetime import datetime
 from typing import IO
 
 from pyselfupdate.errors import NoReleaseError
@@ -168,8 +173,8 @@ class GitHubSource:
     # notify gate declines to check at all. That gate is otherwise free, and a
     # spawn in front of it is the entire cost.
     #
-    # Reaching for `gh` no longer needs one: that is the default below. This is
-    # for a credential neither the environment nor a command can produce.
+    # `gh` needs no `token_func`, because it is the default below. This is for a
+    # credential neither the environment nor a command can produce.
     token_func: Callable[[], str] | None = None
 
     timeout: float = DEFAULT_TIMEOUT
@@ -343,7 +348,7 @@ def _reset_clock(error: urllib.error.HTTPError) -> str:
     """
     header = error.headers.get('x-ratelimit-reset') if error.headers else None
     try:
-        moment = datetime.fromtimestamp(int(header or ''), tz=UTC)
+        moment = dt.datetime.fromtimestamp(int(header or ''), tz=dt.UTC)
     except (TypeError, ValueError, OSError, OverflowError):
         return ''
     return f'; resets at {moment:%H:%M} UTC'

pyselfupdate-0.5.0/src/pyselfupdate/install.py

@@ -0,0 +1,426 @@
+"""Reading and rewriting a uv tool installation.
+
+This is the part with no analog 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.
+
+`uv tool install` never reads a lock. Handed `<tool> @ git+<url>@<tag>`, it
+resolves every dependency to its newest version, while the tool's CI tested the
+versions in its `uv.lock`. So a git install is held to the lock at the tag being
+installed: `read_lock` turns it into constraints and overrides, and
+`run_install` passes them to uv. uv records both in the receipt, so a later
+`uv tool upgrade` stays held to them.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import tomllib
+from collections.abc import Sequence
+from dataclasses import dataclass
+from dataclasses import field
+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 LockUnreadableError
+from pyselfupdate.errors import NotInstalledError
+
+RECEIPT_NAME = 'uv-receipt.toml'
+
+LOCK_NAME = 'uv.lock'
+
+EXPORT = ('export', '--frozen', '--no-default-groups', '--no-emit-workspace', '--no-hashes', '--no-header', '--no-annotate')
+"""The lock's runtime dependencies, one requirement per line.
+
+`--no-emit-workspace` leaves out the tool itself and any workspace member, which
+the commit being installed already pins. `--no-hashes` keeps each requirement
+on one line: uv writes every hash as a continuation line, and
+`_pins_from_export` reads line by line.
+"""
+
+
+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 = ''
+
+    extras: tuple[str, ...] = ()
+
+    # The receipt's other requirements, from `--with` and `--with-editable`, as
+    # requirements-file lines, because a `-e` line is the only way to pass an
+    # editable back.
+    with_requirements: tuple[str, ...] = ()
+
+    # Names of the receipt requirements `_requirement_line` returns None for.
+    # `read_installation` records them rather than raising: the notify gate
+    # treats a failed read as a local install and prints no notice. `update`
+    # raises NotInstalledError on them instead of dropping them.
+    _unrebuildable: tuple[str, ...] = field(default=(), repr=False)
+
+    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 []
+    own = next((requirement for requirement in requirements if requirement.get('name') == tool), None)
+    if own is None:
+        raise NotInstalledError(f'{receipt} lists no requirement named {tool}')
+
+    rebuilt: list[str] = []
+    unrebuildable: list[str] = []
+    for requirement in requirements:
+        if requirement is own:
+            continue
+        line = _requirement_line(requirement)
+        if line is None:
+            unrebuildable.append(str(requirement.get('name') or requirement))
+        else:
+            rebuilt.append(line)
+
+    def installed_as(kind: InstallKind, url: str = '', revision: str = '') -> Installation:
+        extras = tuple(own.get('extras') or ())
+        return Installation(tool, kind, url, revision, extras, tuple(rebuilt), tuple(unrebuildable))
+
+    # 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 own.get(key):
+            return installed_as(InstallKind.LOCAL, url=str(own[key]))
+
+    git = own.get('git')
+    if git:
+        url, query, _ = _split_git(str(git))
+        return installed_as(InstallKind.GIT, url=url, revision=query.get('rev', ''))
+
+    return installed_as(InstallKind.INDEX)
+
+
+def _split_git(git: str) -> tuple[str, dict[str, str], str]:
+    """A receipt's git source as its URL, its query and the commit after `#`.
+
+    uv writes `...git?rev=v1.2.3` for a pinned install and omits the query
+    entirely for one that follows the default branch.
+    """
+    rest, _, commit = git.partition('#')
+    url, _, query = rest.partition('?')
+    pairs = (part.partition('=') for part in query.split('&') if part)
+    return url, {key: value for key, _, value in pairs if value}, commit
+
+
+_LINE_KEYS = frozenset({'name', 'extras', 'marker', 'specifier', 'git', 'subdirectory', 'url', 'path', 'directory', 'editable'})
+
+
+def _requirement_line(requirement: dict) -> str | None:
+    """A receipt requirement as a requirements-file line, or None when no line reproduces it.
+
+    None covers a key outside `_LINE_KEYS`, an editable carrying extras or a
+    marker, and a relative path.
+    """
+    name = requirement.get('name')
+    if not name or set(requirement) - _LINE_KEYS:
+        return None
+    extras = requirement.get('extras') or ()
+    named = f'{name}[{",".join(extras)}]' if extras else name
+    marker = f' ; {requirement["marker"]}' if requirement.get('marker') else ''
+
+    if requirement.get('editable'):
+        uri = _file_uri(requirement['editable'])
+        return f'-e {uri}' if uri and not extras and not marker else None
+    if requirement.get('git'):
+        url, query, commit = _split_git(str(requirement['git']))
+        ref = query.get('rev') or query.get('tag') or query.get('branch') or commit
+        subdirectory = query.get('subdirectory') or requirement.get('subdirectory')
+        return f'{named} @ git+{url}{f"@{ref}" if ref else ""}{f"#subdirectory={subdirectory}" if subdirectory else ""}{marker}'
+    if requirement.get('url'):
+        subdirectory = requirement.get('subdirectory')
+        return f'{named} @ {requirement["url"]}{f"#subdirectory={subdirectory}" if subdirectory else ""}{marker}'
+    for key in ('directory', 'path'):
+        if requirement.get(key):
+            uri = _file_uri(requirement[key])
+            return f'{named} @ {uri}{marker}' if uri else None
+    return f'{named}{requirement.get("specifier") or ""}{marker}'
+
+
+def _file_uri(path: str) -> str:
+    """A `file://` URI for an absolute path, or an empty string for a relative one.
+
+    The receipt does not record what a relative path is relative to.
+    """
+    candidate = Path(path)
+    return candidate.as_uri() if candidate.is_absolute() else ''
+
+
+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, with the extras it has."""
+    named = f'{installation.tool}[{",".join(installation.extras)}]' if installation.extras else installation.tool
+    if installation.kind is InstallKind.GIT:
+        return f'{named} @ git+{installation.url}@{ref}'
+    return f'{named}=={ref.removeprefix("v")}'
+
+
+@dataclass(frozen=True)
+class Pins:
+    """What a `uv.lock` pins, as `--constraints` lines and `--overrides` lines.
+
+    A registry pin is a constraint, which holds a package to the locked version
+    without adding it. A URL pin has to be an override. A lock records
+    `git+<repo>@<commit>` where the package declared `git+<repo>`, and uv
+    refuses a constraint whose URL differs from the declared one with
+    `Requirements contain conflicting URLs`.
+    """
+
+    constraints: tuple[str, ...] = ()
+    overrides: tuple[str, ...] = ()
+
+    def arguments(self, directory: Path) -> list[str]:
+        """Writes each non-empty list into `directory` and returns the flags naming them.
+
+        An empty file is left out rather than passed, because uv warns on one.
+        """
+        flags: list[str] = []
+        for flag, lines in (('--constraints', self.constraints), ('--overrides', self.overrides)):
+            if not lines:
+                continue
+            path = directory / f'{flag.removeprefix("--")}.txt'
+            path.write_text(''.join(f'{line}\n' for line in lines), encoding='utf-8')
+            flags += [flag, str(path)]
+        return flags
+
+
+def read_lock(url: str, ref: str, *, extras: Sequence[str] = ()) -> Pins | None:
+    """What the `uv.lock` at `ref` of a git repository pins, or None when it has none.
+
+    `extras` are the extras the tool is installed with. Each is passed to
+    `uv export` as `--extra`, since a default export leaves an extra's
+    dependencies out. `--all-extras` fails on a project that declares two
+    extras as conflicting.
+
+    Reads a shallow clone of the one ref and lets `uv export` interpret the lock.
+    The lock is also read directly for one thing the export drops: the extras
+    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:
+    `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')
+
+    # 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)])
+        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, *(flag for extra in extras for flag in ('--extra', extra))], cwd=checkout)
+        if exported.returncode != 0:
+            raise LockUnreadableError(f'uv export would not read the uv.lock at {ref}: {_reason(exported)}')
+        try:
+            requested = _override_extras(tomllib.loads(lock.read_text(encoding='utf-8')), extras)
+        except (OSError, tomllib.TOMLDecodeError) as error:
+            raise LockUnreadableError(f'cannot read the uv.lock at {ref}: {error}') from error
+    return _pins_from_export(exported.stdout, requested)
+
+
+def _override_extras(lock: dict, extras: Sequence[str]) -> dict[str, tuple[str, ...]]:
+    """The extras requested of each package, walking dependency edges from the project at the lock's root.
+
+    An override replaces a requirement whole, extras included, and `uv export`
+    writes `gitdep @ git+...` where the tool declared `gitdep[x] @ git+...`.
+    Without this, an update leaves out the packages `x` pulls in. The tool then
+    raises ModuleNotFoundError on its first import of one, after its old
+    environment is gone. The lock keeps the extras on the edge that requests
+    them: `{ name = "gitdep", extra = ["x"] }`.
+
+    Only requested extras are followed, so an override never names an extra
+    the installed tool did not ask for.
+    """
+    packages: dict[str, list[dict]] = {}
+    for package in lock.get('package') or []:
+        packages.setdefault(package.get('name', ''), []).append(package)
+    project = ({'editable': '.'}, {'virtual': '.'})
+    roots = [name for name, entries in packages.items() for package in entries if package.get('source') in project]
+
+    active: dict[str, set[str]] = {root: set(extras) for root in roots}
+    pending = list(roots)
+    while pending:
+        name = pending.pop()
+        for package in packages.get(name, ()):
+            groups = package.get('optional-dependencies') or {}
+            edges = [*(package.get('dependencies') or ()), *(edge for extra in sorted(active[name]) for edge in groups.get(extra, ()))]
+            for edge in edges:
+                target, wanted = edge.get('name', ''), set(edge.get('extra') or ())
+                if target not in active or not wanted <= active[target]:
+                    active.setdefault(target, set()).update(wanted)
+                    pending.append(target)
+    return {name: tuple(sorted(wanted)) for name, wanted in active.items() if wanted}
+
+
+def _pins_from_export(exported: str, extras: dict[str, tuple[str, ...]]) -> Pins:
+    """Sorts `uv export` lines: ` @ ` before any marker makes an override, `==` a constraint.
+
+    Anything else is a path requirement and is dropped. Its code is inside the
+    commit being installed.
+    """
+    constraints: list[str] = []
+    overrides: list[str] = []
+    for line in exported.splitlines():
+        line = line.strip()
+        requirement = line.split(';', 1)[0]
+        if ' @ ' in requirement:
+            name, _, rest = line.partition(' @ ')
+            wanted = extras.get(name.strip())
+            overrides.append(f'{name.strip()}[{",".join(wanted)}] @ {rest}' if wanted else line)
+        elif '==' in requirement:
+            constraints.append(line)
+    return Pins(tuple(constraints), tuple(overrides))
+
+
+def run_install(requirement: str, *, quiet: bool = True, pins: Pins | None = None, with_requirements: Sequence[str] = ()) -> None:
+    """Install a requirement over any existing tool of that name, held to `pins` when given.
+
+    `with_requirements` are requirements-file lines installed beside the tool,
+    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.
+    """
+    executable = shutil.which('uv')
+    if not executable:
+        raise InstallFailedError('uv is not on PATH, so the tool cannot reinstall itself')
+
+    with tempfile.TemporaryDirectory(prefix='pyselfupdate-pins-', ignore_cleanup_errors=True) as scratch:
+        held = pins.arguments(Path(scratch)) if pins else []
+        beside: list[str] = []
+        if with_requirements:
+            listed = Path(scratch) / 'with.txt'
+            listed.write_text(''.join(f'{line}\n' for line in with_requirements), encoding='utf-8')
+            beside = ['--with-requirements', str(listed)]
+        command = [executable, 'tool', 'install', '--force', *held, *beside, requirement]
+        if quiet:
+            command.insert(1, '--quiet')
+        completed = _run(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 _reason(completed: subprocess.CompletedProcess[str]) -> str:
+    """Everything a failing command printed, rather than one line of it.
+
+    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}'
+
+
+def exit_now(code: int = 0) -> None:
+    """End this process immediately, after flushing what it has written.
+
+    The sibling of `reexec` for when there is nothing left to run. Both exist
+    for the same reason: the environment has been rewritten, so no further
+    import can be trusted. `sys.exit` raises SystemExit, which unwinds through
+    whatever CLI framework called us and then through interpreter shutdown --
+    and both are free to import a module they had not needed yet, from a
+    directory that is no longer the one this process started in. `os._exit`
+    skips both, which is why the flushes are done here rather than left to the
+    shutdown that no longer happens.
+
+    Never returns.
+    """
+    sys.stdout.flush()
+    sys.stderr.flush()
+    os._exit(code)
+
+
+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

{pyselfupdate-0.4.1 → pyselfupdate-0.5.0}/src/pyselfupdate/notifier.py

@@ -9,12 +9,12 @@ update failure on every invocation.
 from __future__ import annotations
 
 import atexit
+import datetime as dt
 import os
 import sys
 import time
 from collections.abc import Iterable
 from dataclasses import dataclass
-from datetime import timedelta
 from enum import Enum
 from typing import Any
 from typing import TextIO
@@ -26,7 +26,7 @@ from pyselfupdate.install import InstallKind
 from pyselfupdate.install import read_installation
 from pyselfupdate.updater import check
 
-DEFAULT_INTERVAL = timedelta(hours=24)
+DEFAULT_INTERVAL = dt.timedelta(hours=24)
 
 # Environment variables. Presence-only, any value including empty -- the
 # NO_COLOR convention -- so that NO_AUTO_UPDATE=0 cannot mean "on". The interval
@@ -66,7 +66,7 @@ class Outcome:
 def notify(
     config: Config,
     *,
-    interval: timedelta | None = None,
+    interval: dt.timedelta | None = None,
     out: TextIO | None = None,
     defer: bool = True,
     interactive: bool | None = None,
@@ -141,7 +141,7 @@ def _asking_for_help() -> bool:
 def _notify(
     config: Config,
     *,
-    interval: timedelta | None,
+    interval: dt.timedelta | None,
     out: TextIO | None,
     defer: bool,
     interactive: bool | None,
@@ -248,7 +248,7 @@ def _is_local_install(tool: str) -> bool:
     return installation.kind is InstallKind.GIT and not installation.revision
 
 
-def _interval(tool: str, override: timedelta | None) -> timedelta:
+def _interval(tool: str, override: dt.timedelta | None) -> dt.timedelta:
     if override is not None:
         return override
     for name in (_tool_variable(tool, 'AUTO_UPDATE_INTERVAL'), FLEET_INTERVAL):
@@ -260,7 +260,7 @@ def _interval(tool: str, override: timedelta | None) -> timedelta:
     return DEFAULT_INTERVAL
 
 
-def _parse_interval(raw: str) -> timedelta | None:
+def _parse_interval(raw: str) -> dt.timedelta | None:
     """Parse `30m`, `24h`, `7d`, or a bare number of seconds."""
     raw = raw.strip().lower()
     if not raw:
@@ -274,10 +274,10 @@ def _parse_interval(raw: str) -> timedelta | None:
         return None
     if value < 0:
         return None
-    return timedelta(seconds=value * (multiplier or 1))
+    return dt.timedelta(seconds=value * (multiplier or 1))
 
 
-def _is_due(stored: state_module.State, window: timedelta) -> bool:
+def _is_due(stored: state_module.State, window: dt.timedelta) -> bool:
     if not stored.checked_at_epoch:
         return True
     return time.time() - stored.checked_at_epoch >= window.total_seconds()

{pyselfupdate-0.4.1 → pyselfupdate-0.5.0}/src/pyselfupdate/state.py

@@ -12,13 +12,12 @@ is where `gh` puts the same thing.
 
 from __future__ import annotations
 
+import datetime as dt
 import json
 import os
 import socket
 from dataclasses import asdict
 from dataclasses import dataclass
-from datetime import UTC
-from datetime import datetime
 from pathlib import Path
 
 SCHEMA = 1
@@ -134,9 +133,9 @@ def write(state: State) -> None:
         return
 
 
-def stamp(state: State, moment: datetime | None = None) -> State:
+def stamp(state: State, moment: dt.datetime | None = None) -> State:
     """Set both timestamp fields to the same instant."""
-    now = moment or datetime.now(UTC)
+    now = moment or dt.datetime.now(dt.UTC)
     state.checked_at = now.strftime('%Y-%m-%dT%H:%M:%SZ')
     state.checked_at_epoch = int(now.timestamp())
     return state

{pyselfupdate-0.4.1 → pyselfupdate-0.5.0}/src/pyselfupdate/typercmd.py

@@ -82,12 +82,14 @@ def run_update(config: Config, *, check_only: bool = False, skip_changelog: bool
         return
 
     try:
-        install_release(config, result, installation)
+        installed = install_release(config, result, installation)
     except SelfUpdateError as error:
         typer.echo(f'✗ {tool} update failed: {error}', err=True)
         raise typer.Exit(1) from error
 
     typer.echo(f'✓ {tool} updated: {result.current} → {result.latest}')
+    if installed.lock_warning:
+        typer.echo(f'! {tool}: {installed.lock_warning}', err=True)
     _echo_changes(subjects)
     exit_now()
 

{pyselfupdate-0.4.1 → pyselfupdate-0.5.0}/src/pyselfupdate/updater.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import sys
 from dataclasses import dataclass
 from dataclasses import field
 
@@ -9,9 +10,11 @@ from pyselfupdate import version as semver
 from pyselfupdate.config import Config
 from pyselfupdate.errors import LocalInstallError
 from pyselfupdate.errors import NoReleaseError
+from pyselfupdate.errors import NotInstalledError
 from pyselfupdate.install import Installation
 from pyselfupdate.install import InstallKind
 from pyselfupdate.install import read_installation
+from pyselfupdate.install import read_lock
 from pyselfupdate.install import reexec
 from pyselfupdate.install import requirement_for
 from pyselfupdate.install import run_install
@@ -34,10 +37,25 @@ class Result:
     release: Release | None = None
     metadata: dict[str, str] = field(default_factory=dict)
 
+    # True when a git install ran unlocked because its tag carries no uv.lock.
+    # An index install reads no lock, so it leaves this False.
+    lock_missing: bool = False
+
     @property
     def update_available(self) -> bool:
         return self.current != self.latest
 
+    @property
+    def lock_warning(self) -> str:
+        """A line naming the tag when `lock_missing` is set, else an empty string.
+
+        `run_update` and `update_and_reexec` print it to stderr.
+        """
+        if not self.lock_missing:
+            return ''
+        tag = self.release.install_ref() if self.release else self.latest
+        return f'{tag} has no uv.lock, so its dependencies were installed at their newest versions'
+
 
 def check(config: Config) -> Result:
     """Report whether a newer release exists, without installing anything."""
@@ -75,18 +93,24 @@ def install_release(config: Config, result: Result, installation: Installation,
     success this interpreter's environment has been rewritten underneath it, so
     the caller may not import anything afterwards -- see
     `pyselfupdate.install.reexec` and `pyselfupdate.install.exit_now`.
+
+    A git install is held to the `uv.lock` at the release's tag. A tag without
+    one installs unlocked and comes back with `lock_missing` set. A lock that
+    cannot be read raises `LockUnreadableError` before anything is installed.
     """
     if not result.update_available or result.release is None:
         return result
 
-    requirement = requirement_for(installation, result.release.install_ref())
-    run_install(requirement, quiet=quiet)
+    ref = result.release.install_ref()
+    pins = read_lock(installation.url, ref, extras=installation.extras) if installation.kind is InstallKind.GIT else None
+    run_install(requirement_for(installation, ref), quiet=quiet, pins=pins, with_requirements=installation.with_requirements)
 
     return Result(
         current=result.current,
         latest=result.latest,
         applied=True,
         release=result.release,
+        lock_missing=installation.kind is InstallKind.GIT and pins is None,
     )
 
 
@@ -108,10 +132,13 @@ def update_and_reexec(config: Config, *, quiet: bool = True) -> Result:
     """`update`, then replace this process when anything was installed.
 
     Returns normally only when nothing was installed; otherwise it does not
-    return at all.
+    return at all. The caller never sees the `Result` of an install, so this
+    writes its `lock_warning` to stderr before the re-exec.
     """
     result = update(config, quiet=quiet)
     if result.applied:
+        if result.lock_warning:
+            print(f'! {config.tool}: {result.lock_warning}', file=sys.stderr)
         reexec()
     return result
 
@@ -153,3 +180,9 @@ def _require_updatable(installation: Installation) -> None:
             f'so a release version cannot be compared against it; '
             f'reinstall from a tagged release to enable updates'
         )
+    if installation._unrebuildable:
+        raise NotInstalledError(
+            f'{installation.tool} was installed with {", ".join(installation._unrebuildable)}, '
+            f'which an update cannot pass back to uv and would drop. '
+            f'Reinstall {installation.tool} by hand with `uv tool install --force`'
+        )

pyselfupdate-0.4.1/src/pyselfupdate/install.py

@@ -1,195 +0,0 @@
-"""Reading and rewriting a uv tool installation.
-
-This is the part with no analog 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 exit_now(code: int = 0) -> None:
-    """End this process immediately, after flushing what it has written.
-
-    The sibling of `reexec` for when there is nothing left to run. Both exist
-    for the same reason: the environment has been rewritten, so no further
-    import can be trusted. `sys.exit` raises SystemExit, which unwinds through
-    whatever CLI framework called us and then through interpreter shutdown --
-    and both are free to import a module they had not needed yet, from a
-    directory that is no longer the one this process started in. `os._exit`
-    skips both, which is why the flushes are done here rather than left to the
-    shutdown that no longer happens.
-
-    Never returns.
-    """
-    sys.stdout.flush()
-    sys.stderr.flush()
-    os._exit(code)
-
-
-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