dycw-utilities 0.175.17__py3-none-any.whl → 0.185.8__py3-none-any.whl

utilities/subprocess.py

@@ -1,37 +1,56 @@
 from __future__ import annotations
 
-import shutil
+import json
 import sys
-from contextlib import contextmanager
 from dataclasses import dataclass
 from io import StringIO
+from itertools import chain, repeat
+from json import JSONDecodeError
 from pathlib import Path
-from re import search
+from re import MULTILINE, escape, search
 from shlex import join
-from shutil import copyfile, copytree, move, rmtree
+from shutil import rmtree
 from string import Template
 from subprocess import PIPE, CalledProcessError, Popen
 from threading import Thread
-from time import sleep
 from typing import IO, TYPE_CHECKING, Literal, assert_never, overload, override
 
+import utilities.core
+from utilities.constants import HOME, PWD, SECOND
+from utilities.contextlib import enhanced_context_manager
+from utilities.core import (
+    OneEmptyError,
+    Permissions,
+    TemporaryDirectory,
+    _CopyOrMoveSourceNotFoundError,
+    always_iterable,
+    copy,
+    file_or_dir,
+    move,
+    normalize_multi_line_str,
+    one,
+    repr_str,
+)
 from utilities.errors import ImpossibleCaseError
-from utilities.iterables import always_iterable
+from utilities.functions import in_timedelta
 from utilities.logging import to_logger
-from utilities.pathlib import PWD
-from utilities.permissions import Permissions, ensure_perms
-from utilities.tempfile import TemporaryDirectory
-from utilities.text import strip_and_dedent
-from utilities.whenever import SECOND, to_seconds
+from utilities.time import sleep
+from utilities.version import (
+    ParseVersion2Or3Error,
+    Version2,
+    Version3,
+    parse_version_2_or_3,
+)
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterator
+    from collections.abc import Callable, Iterable, Iterator
 
-    from utilities.permissions import PermissionsLike
+    from utilities.core import PermissionsLike
     from utilities.types import (
-        Delta,
+        Duration,
         LoggerLike,
         MaybeIterable,
+        MaybeSequenceStr,
         PathLike,
         Retry,
         StrMapping,
@@ -45,8 +64,12 @@ BASH_LC = ["bash", "-lc"]
 BASH_LS = ["bash", "-ls"]
 CHPASSWD = "chpasswd"
 GIT_BRANCH_SHOW_CURRENT = ["git", "branch", "--show-current"]
-KNOWN_HOSTS = Path.home() / ".ssh/known_hosts"
+ISOLATED = "--isolated"
+KNOWN_HOSTS = HOME / ".ssh/known_hosts"
+MANAGED_PYTHON = "--managed-python"
 MKTEMP_DIR_CMD = ["mktemp", "-d"]
+PRERELEASE_DISALLOW = ["--prerelease", "disallow"]
+RESOLUTION_HIGHEST = ["--resolution", "highest"]
 RESTART_SSHD = ["systemctl", "restart", "sshd"]
 UPDATE_CA_CERTIFICATES: str = "update-ca-certificates"
 
@@ -54,24 +77,89 @@ UPDATE_CA_CERTIFICATES: str = "update-ca-certificates"
 ##
 
 
-def apt_install(package: str, /, *, update: bool = False, sudo: bool = False) -> None:
-    """Install a package."""
+def append_text(
+    path: PathLike,
+    text: str,
+    /,
+    *,
+    sudo: bool = False,
+    skip_if_present: bool = False,
+    flags: int = 0,
+    blank_lines: int = 1,
+) -> None:
+    """Append text to a file."""
+    try:
+        existing = cat(path, sudo=sudo)
+    except (CalledProcessError, FileNotFoundError):
+        tee(path, text, sudo=sudo)
+        return
+    if existing == "":
+        tee(path, text, sudo=sudo)
+        return
+    if skip_if_present and (search(escape(text), existing, flags=flags) is not None):
+        return
+    full = "".join([*repeat("\n", times=blank_lines), text])
+    tee(path, full, sudo=sudo, append=True)
+
+
+##
+
+
+def apt_install(
+    package: str, /, *packages: str, update: bool = False, sudo: bool = False
+) -> None:
+    """Install packages."""
     if update:  # pragma: no cover
-        run(*maybe_sudo_cmd(*APT_UPDATE, sudo=sudo))
-    run(*maybe_sudo_cmd(*apt_install_cmd(package), sudo=sudo))
+        apt_update(sudo=sudo)
+    args = maybe_sudo_cmd(  # pragma: no cover
+        *apt_install_cmd(package, *packages), sudo=sudo
+    )
+    run(*args)  # pragma: no cover
+
 
+def apt_install_cmd(package: str, /, *packages: str) -> list[str]:
+    """Command to use 'apt' to install packages."""
+    return ["apt", "install", "-y", package, *packages]
 
-def apt_install_cmd(package: str, /) -> list[str]:
-    """Command to use 'apt' to install a package."""
-    return ["apt", "install", "-y", package]
+
+##
+
+
+def apt_remove(package: str, /, *packages: str, sudo: bool = False) -> None:
+    """Remove a package."""
+    args = maybe_sudo_cmd(  # pragma: no cover
+        *apt_remove_cmd(package, *packages), sudo=sudo
+    )
+    run(*args)  # pragma: no cover
+
+
+def apt_remove_cmd(package: str, /, *packages: str) -> list[str]:
+    """Command to use 'apt' to remove packages."""
+    return ["apt", "remove", "-y", package, *packages]
+
+
+##
+
+
+def apt_update(*, sudo: bool = False) -> None:
+    """Update 'apt'."""
+    run(*maybe_sudo_cmd(*APT_UPDATE, sudo=sudo))  # pragma: no cover
 
 
 ##
 
 
-def cat_cmd(path: PathLike, /) -> list[str]:
+def cat(path: PathLike, /, *paths: PathLike, sudo: bool = False) -> str:
+    """Concatenate and print files."""
+    if sudo:  # pragma: no cover
+        return run(*sudo_cmd(*cat_cmd(path, *paths)), return_=True)
+    all_paths = list(map(Path, [path, *paths]))
+    return "\n".join(p.read_text() for p in all_paths)
+
+
+def cat_cmd(path: PathLike, /, *paths: PathLike) -> list[str]:
     """Command to use 'cat' to concatenate and print files."""
-    return ["cat", str(path)]
+    return ["cat", str(path), *map(str, paths)]
 
 
 ##
@@ -85,17 +173,40 @@ def cd_cmd(path: PathLike, /) -> list[str]:
 ##
 
 
+def chattr(
+    path: PathLike, /, *, immutable: bool | None = None, sudo: bool = False
+) -> None:
+    """Change file attributes."""
+    args = maybe_sudo_cmd(  # pragma: no cover
+        *chattr_cmd(path, immutable=immutable), sudo=sudo
+    )
+    run(*args)  # pragma: no cover
+
+
+def chattr_cmd(path: PathLike, /, *, immutable: bool | None = None) -> list[str]:
+    """Command to use 'chattr' to change file attributes."""
+    args: list[str] = ["chattr"]
+    if immutable is True:
+        args.append("+i")
+    elif immutable is False:
+        args.append("-i")
+    return [*args, str(path)]
+
+
+##
+
+
 def chmod(path: PathLike, perms: PermissionsLike, /, *, sudo: bool = False) -> None:
     """Change file mode."""
     if sudo:  # pragma: no cover
         run(*sudo_cmd(*chmod_cmd(path, perms)))
-    else:
-        Path(path).chmod(int(ensure_perms(perms)))
+    else:  # pragma: no cover
+        utilities.core.chmod(path, perms)
 
 
 def chmod_cmd(path: PathLike, perms: PermissionsLike, /) -> list[str]:
     """Command to use 'chmod' to change file mode."""
-    return ["chmod", str(ensure_perms(perms)), str(path)]
+    return ["chmod", str(Permissions.new(perms)), str(path)]
 
 
 ##
@@ -106,36 +217,33 @@ def chown(
     /,
     *,
     sudo: bool = False,
+    recursive: bool = False,
     user: str | int | None = None,
     group: str | int | None = None,
 ) -> None:
     """Change file owner and/or group."""
     if sudo:  # pragma: no cover
-        match user, group:
-            case None, None:
-                ...
-            case str() | int() | None, str() | int() | None:
-                run(*sudo_cmd(*chown_cmd(path, user=user, group=group)))
-            case never:
-                assert_never(never)
-    else:
-        match user, group:
-            case None, None:
-                ...
-            case str() | int(), None:
-                shutil.chown(path, user, group)
-            case None, str() | int():
-                shutil.chown(path, user, group)
-            case str() | int(), str() | int():
-                shutil.chown(path, user, group)
-            case never:
-                assert_never(never)
+        if (user is not None) or (group is not None):
+            args = sudo_cmd(
+                *chown_cmd(path, recursive=recursive, user=user, group=group)
+            )
+            run(*args)
+    else:  # pragma: no cover
+        utilities.core.chown(path, recursive=recursive, user=user, group=group)
 
 
 def chown_cmd(
-    path: PathLike, /, *, user: str | int | None = None, group: str | int | None = None
+    path: PathLike,
+    /,
+    *,
+    recursive: bool = False,
+    user: str | int | None = None,
+    group: str | int | None = None,
 ) -> list[str]:
     """Command to use 'chown' to change file owner and/or group."""
+    args: list[str] = ["chown"]
+    if recursive:
+        args.append("-R")
     match user, group:
         case None, None:
             raise ChownCmdError
@@ -147,7 +255,7 @@ def chown_cmd(
             ownership = f"{user}:{group}"
         case never:
             assert_never(never)
-    return ["chown", ownership, str(path)]
+    return [*args, ownership, str(path)]
 
 
 @dataclass(kw_only=True, slots=True)
@@ -162,9 +270,26 @@ class ChownCmdError(Exception):
 
 def chpasswd(user_name: str, password: str, /, *, sudo: bool = False) -> None:
     """Update passwords."""
-    run(  # pragma: no cover
-        *maybe_sudo_cmd(CHPASSWD, sudo=sudo), input=f"{user_name}:{password}"
-    )
+    args = maybe_sudo_cmd(CHPASSWD, sudo=sudo)  # pragma: no cover
+    run(*args, input=f"{user_name}:{password}")  # pragma: no cover
+
+
+##
+
+
+def copy_text(
+    src: PathLike,
+    dest: PathLike,
+    /,
+    *,
+    sudo: bool = False,
+    substitutions: StrMapping | None = None,
+) -> None:
+    """Copy the text contents of a file."""
+    text = cat(src, sudo=sudo)
+    if substitutions is not None:
+        text = Template(text).substitute(**substitutions)
+    tee(dest, text, sudo=sudo)
 
 
 ##
@@ -184,28 +309,24 @@ def cp(
     mkdir(dest, sudo=sudo, parent=True)
     if sudo:  # pragma: no cover
         run(*sudo_cmd(*cp_cmd(src, dest)))
+        if perms is not None:
+            chmod(dest, perms, sudo=True)
+        if (owner is not None) or (group is not None):
+            chown(dest, sudo=True, user=owner, group=group)
     else:
-        src, dest = map(Path, [src, dest])
-        if src.is_file():
-            _ = copyfile(src, dest)
-        elif src.is_dir():
-            _ = copytree(src, dest, dirs_exist_ok=True)
-        else:
-            raise CpError(src=src, dest=dest)
-    if perms is not None:
-        chmod(dest, perms, sudo=sudo)
-    if (owner is not None) or (group is not None):
-        chown(dest, sudo=sudo, user=owner, group=group)
+        try:
+            copy(src, dest, overwrite=True, perms=perms, owner=owner, group=group)
+        except _CopyOrMoveSourceNotFoundError as error:
+            raise CpError(src=error.src) from None
 
 
 @dataclass(kw_only=True, slots=True)
 class CpError(Exception):
     src: Path
-    dest: Path
 
     @override
     def __str__(self) -> str:
-        return f"Unable to copy {str(self.src)!r} to {str(self.dest)!r}; source does not exist"
+        return f"Source {repr_str(self.src)} does not exist"
 
 
 def cp_cmd(src: PathLike, dest: PathLike, /) -> list[str]:
@@ -216,6 +337,185 @@ def cp_cmd(src: PathLike, dest: PathLike, /) -> list[str]:
 ##
 
 
+@overload
+def curl(
+    url: str,
+    /,
+    *,
+    fail: bool = True,
+    location: bool = True,
+    output: PathLike | None = None,
+    show_error: bool = True,
+    silent: bool = True,
+    sudo: bool = False,
+    print: bool = False,
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: Literal[True],
+    return_stdout: Literal[False] = False,
+    return_stderr: Literal[False] = False,
+    retry: Retry | None = None,
+    retry_skip: Callable[[int, str, str], bool] | None = None,
+    logger: LoggerLike | None = None,
+) -> str: ...
+@overload
+def curl(
+    url: str,
+    /,
+    *,
+    fail: bool = True,
+    location: bool = True,
+    output: PathLike | None = None,
+    show_error: bool = True,
+    silent: bool = True,
+    sudo: bool = False,
+    print: bool = False,
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: Literal[False] = False,
+    return_stdout: Literal[True],
+    return_stderr: Literal[False] = False,
+    retry: Retry | None = None,
+    retry_skip: Callable[[int, str, str], bool] | None = None,
+    logger: LoggerLike | None = None,
+) -> str: ...
+@overload
+def curl(
+    url: str,
+    /,
+    *,
+    fail: bool = True,
+    location: bool = True,
+    output: PathLike | None = None,
+    show_error: bool = True,
+    silent: bool = True,
+    sudo: bool = False,
+    print: bool = False,
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: Literal[False] = False,
+    return_stdout: Literal[False] = False,
+    return_stderr: Literal[True],
+    retry: Retry | None = None,
+    retry_skip: Callable[[int, str, str], bool] | None = None,
+    logger: LoggerLike | None = None,
+) -> str: ...
+@overload
+def curl(
+    url: str,
+    /,
+    *,
+    fail: bool = True,
+    location: bool = True,
+    output: PathLike | None = None,
+    show_error: bool = True,
+    silent: bool = True,
+    sudo: bool = False,
+    print: bool = False,
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: Literal[False] = False,
+    return_stdout: Literal[False] = False,
+    return_stderr: Literal[False] = False,
+    retry: Retry | None = None,
+    retry_skip: Callable[[int, str, str], bool] | None = None,
+    logger: LoggerLike | None = None,
+) -> None: ...
+@overload
+def curl(
+    url: str,
+    /,
+    *,
+    fail: bool = True,
+    location: bool = True,
+    output: PathLike | None = None,
+    show_error: bool = True,
+    silent: bool = True,
+    sudo: bool = False,
+    print: bool = False,
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: bool = False,
+    return_stdout: bool = False,
+    return_stderr: bool = False,
+    retry: Retry | None = None,
+    retry_skip: Callable[[int, str, str], bool] | None = None,
+    logger: LoggerLike | None = None,
+) -> str | None: ...
+def curl(
+    url: str,
+    /,
+    *,
+    fail: bool = True,
+    location: bool = True,
+    output: PathLike | None = None,
+    show_error: bool = True,
+    silent: bool = True,
+    sudo: bool = False,
+    print: bool = False,  # noqa: A002
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: bool = False,
+    return_stdout: bool = False,
+    return_stderr: bool = False,
+    retry: Retry | None = None,
+    retry_skip: Callable[[int, str, str], bool] | None = None,
+    logger: LoggerLike | None = None,
+) -> str | None:
+    """Transfer a URL."""
+    args = maybe_sudo_cmd(  # skipif-ci
+        *curl_cmd(
+            url,
+            fail=fail,
+            location=location,
+            output=output,
+            show_error=show_error,
+            silent=silent,
+        ),
+        sudo=sudo,
+    )
+    return run(  # skipif-ci
+        *args,
+        print=print,
+        print_stdout=print_stdout,
+        print_stderr=print_stderr,
+        return_=return_,
+        return_stdout=return_stdout,
+        return_stderr=return_stderr,
+        retry=retry,
+        retry_skip=retry_skip,
+        logger=logger,
+    )
+
+
+def curl_cmd(
+    url: str,
+    /,
+    *,
+    fail: bool = True,
+    location: bool = True,
+    output: PathLike | None = None,
+    show_error: bool = True,
+    silent: bool = True,
+) -> list[str]:
+    """Command to use 'curl' to transfer a URL."""
+    args: list[str] = ["curl"]
+    if fail:
+        args.append("--fail")
+    if location:
+        args.append("--location")
+    if output is not None:
+        args.extend(["--create-dirs", "--output", str(output)])
+    if show_error:
+        args.append("--show-error")
+    if silent:
+        args.append("--silent")
+    return [*args, url]
+
+
+##
+
+
 def echo_cmd(text: str, /) -> list[str]:
     """Command to use 'echo' to write arguments to the standard output."""
     return ["echo", text]
@@ -284,6 +584,53 @@ def git_clone_cmd(url: str, path: PathLike, /) -> list[str]:
 ##
 
 
+def install(
+    path: PathLike,
+    /,
+    *,
+    directory: bool = False,
+    mode: PermissionsLike | None = None,
+    owner: str | int | None = None,
+    group: str | int | None = None,
+    sudo: bool = False,
+) -> None:
+    """Install a binary."""
+    args = maybe_sudo_cmd(
+        *install_cmd(path, directory=directory, mode=mode, owner=owner, group=group),
+        sudo=sudo,
+    )
+    run(*args)
+
+
+def install_cmd(
+    path: PathLike,
+    /,
+    *,
+    directory: bool = False,
+    mode: PermissionsLike | None = None,
+    owner: str | int | None = None,
+    group: str | int | None = None,
+) -> list[str]:
+    """Command to use 'install' to install a binary."""
+    args: list[str] = ["install"]
+    if directory:
+        args.append("-d")
+    if mode is not None:
+        args.extend(["-m", str(Permissions.new(mode))])
+    if owner is not None:
+        args.extend(["-o", str(owner)])
+    if group is not None:
+        args.extend(["-g", str(group)])
+    if directory:
+        args.append(str(path))
+    else:
+        args.extend(["/dev/null", str(path)])
+    return args
+
+
+##
+
+
 def maybe_parent(path: PathLike, /, *, parent: bool = False) -> Path:
     """Get the parent of a path, if required."""
     path = Path(path)
@@ -326,26 +673,24 @@ def mv(
     mkdir(dest, sudo=sudo, parent=True)
     if sudo:  # pragma: no cover
         run(*sudo_cmd(*cp_cmd(src, dest)))
+        if perms is not None:
+            chmod(dest, perms, sudo=True)
+        if (owner is not None) or (group is not None):
+            chown(dest, sudo=True, user=owner, group=group)
     else:
-        src, dest = map(Path, [src, dest])
-        if src.exists():
-            _ = move(src, dest)
-        else:
-            raise MvFileError(src=src, dest=dest)
-    if perms is not None:
-        chmod(dest, perms, sudo=sudo)
-    if (owner is not None) or (group is not None):
-        chown(dest, sudo=sudo, user=owner, group=group)
+        try:
+            move(src, dest, overwrite=True, perms=perms, owner=owner, group=group)
+        except _CopyOrMoveSourceNotFoundError as error:
+            raise MvFileError(src=error.src) from None
 
 
 @dataclass(kw_only=True, slots=True)
 class MvFileError(Exception):
     src: Path
-    dest: Path
 
     @override
     def __str__(self) -> str:
-        return f"Unable to move {str(self.src)!r} to {str(self.dest)!r}; source does not exist"
+        return f"Source {repr_str(self.src)} does not exist"
 
 
 def mv_cmd(src: PathLike, dest: PathLike, /) -> list[str]:
@@ -356,6 +701,20 @@ def mv_cmd(src: PathLike, dest: PathLike, /) -> list[str]:
 ##
 
 
+def replace_text(
+    path: PathLike, /, *replacements: tuple[str, str], sudo: bool = False
+) -> None:
+    """Replace the text in a file."""
+    path = Path(path)
+    text = cat(path, sudo=sudo)
+    for old, new in replacements:
+        text = text.replace(old, new)
+    tee(path, text, sudo=sudo)
+
+
+##
+
+
 def ripgrep(*args: str, path: PathLike = PWD) -> str | None:
     """Search for lines."""
     try:  # skipif-ci
@@ -379,11 +738,17 @@ def rm(path: PathLike, /, *paths: PathLike, sudo: bool = False) -> None:
     if sudo:  # pragma: no cover
         run(*sudo_cmd(*rm_cmd(path, *paths)))
     else:
-        for p in map(Path, [path, *paths]):
-            if p.is_file():
-                p.unlink(missing_ok=True)
-            elif p.is_dir():
-                rmtree(p, ignore_errors=True)
+        all_paths = list(map(Path, [path, *paths]))
+        for p in all_paths:
+            match file_or_dir(p):
+                case "file":
+                    p.unlink(missing_ok=True)
+                case "dir":
+                    rmtree(p, ignore_errors=True)
+                case None:
+                    ...
+                case never:
+                    assert_never(never)
 
 
 def rm_cmd(path: PathLike, /, *paths: PathLike) -> list[str]:
@@ -503,10 +868,10 @@ def rsync_cmd(
         args.extend(["--rsync-path", join(sudo_cmd("rsync"))])
     srcs = list(always_iterable(src_or_srcs))  # do not Path()
     if len(srcs) == 0:
-        raise RsyncCmdNoSourcesError(user=user, hostname=hostname, dest=dest)
+        raise _RsyncCmdNoSourcesError(user=user, hostname=hostname, dest=dest)
     missing = [s for s in srcs if not Path(s).exists()]
     if len(missing) >= 1:
-        raise RsyncCmdSourcesNotFoundError(
+        raise _RsyncCmdSourcesNotFoundError(
             sources=missing, user=user, hostname=hostname, dest=dest
         )
     return [*args, *map(str, srcs), f"{user}@{hostname}:{dest}"]
@@ -518,20 +883,16 @@ class RsyncCmdError(Exception):
     hostname: str
     dest: PathLike
 
-    @override
-    def __str__(self) -> str:
-        return f"No sources selected to send to {self.user}@{self.hostname}:{self.dest}"
-
 
 @dataclass(kw_only=True, slots=True)
-class RsyncCmdNoSourcesError(RsyncCmdError):
+class _RsyncCmdNoSourcesError(RsyncCmdError):
     @override
     def __str__(self) -> str:
         return f"No sources selected to send to {self.user}@{self.hostname}:{self.dest}"
 
 
 @dataclass(kw_only=True, slots=True)
-class RsyncCmdSourcesNotFoundError(RsyncCmdError):
+class _RsyncCmdSourcesNotFoundError(RsyncCmdError):
     sources: list[PathLike]
 
     @override
@@ -549,7 +910,8 @@ def rsync_many(
     /,
     *items: tuple[PathLike, PathLike]
     | tuple[Literal["sudo"], PathLike, PathLike]
-    | tuple[PathLike, PathLike, PermissionsLike],
+    | tuple[PathLike, PathLike, PermissionsLike]
+    | tuple[Literal["sudo"], PathLike, PathLike, PermissionsLike],
     retry: Retry | None = None,
     logger: LoggerLike | None = None,
     keep: bool = False,
@@ -570,7 +932,11 @@ def rsync_many(
             match item:
                 case Path() | str() as src, Path() | str() as dest:
                     cmds.extend(_rsync_many_prepare(src, dest, temp_src, temp_dest))
-                case "sudo", Path() | str() as src, Path() | str() as dest:
+                case (  # pragma: no cover
+                    "sudo",
+                    Path() | str() as src,
+                    Path() | str() as dest,
+                ):
                     cmds.extend(
                         _rsync_many_prepare(src, dest, temp_src, temp_dest, sudo=True)
                     )
@@ -582,6 +948,17 @@ def rsync_many(
                     cmds.extend(
                         _rsync_many_prepare(src, dest, temp_src, temp_dest, perms=perms)
                     )
+                case (  # pragma: no cover
+                    "sudo",
+                    Path() | str() as src,
+                    Path() | str() as dest,
+                    Permissions() | int() | str() as perms,
+                ):
+                    cmds.extend(
+                        _rsync_many_prepare(
+                            src, dest, temp_src, temp_dest, sudo=True, perms=perms
+                        )
+                    )
                 case never:
                     assert_never(never)
         rsync(
@@ -625,13 +1002,19 @@ def _rsync_many_prepare(
         case Path():
             cp(src, temp_src / name)
         case str():
-            if Path(src).exists():
-                cp(src, temp_src / name)
-            else:
+            try:
+                exists = Path(src).exists()
+            except OSError:
                 tee(temp_src / name, src)
+            else:
+                if exists:
+                    cp(src, temp_src / name)
+                else:
+                    tee(temp_src / name, src)
         case never:
             assert_never(never)
     cmds: list[list[str]] = [
+        maybe_sudo_cmd(*rm_cmd(dest), sudo=sudo),
         maybe_sudo_cmd(*mkdir_cmd(dest, parent=True), sudo=sudo),
         maybe_sudo_cmd(*cp_cmd(temp_dest / name, dest), sudo=sudo),
     ]
@@ -832,11 +1215,11 @@ def run(
                     and (retry_skip is not None)
                     and retry_skip(return_code, stdout_text, stderr_text)
                 ):
-                    attempts = delta = None
+                    attempts = duration = None
                 else:
-                    attempts, delta = retry
+                    attempts, duration = retry
                 if logger is not None:
-                    msg = strip_and_dedent(f"""
+                    msg = normalize_multi_line_str(f"""
 'run' failed with:
  - cmd          = {cmd}
  - cmds_or_args = {cmds_or_args}
@@ -854,18 +1237,18 @@ def run(
 {stderr_text}-------------------------------------------------------------------------------
 """)
                     if (attempts is not None) and (attempts >= 1):
-                        if delta is None:
+                        if duration is None:
                             msg = f"{msg}\n\nRetrying {attempts} more time(s)..."
                         else:
-                            msg = f"{msg}\n\nRetrying {attempts} more time(s) after {delta}..."
+                            msg = f"{msg}\n\nRetrying {attempts} more time(s) after {in_timedelta(duration)}..."
                     to_logger(logger).error(msg)
                 error = CalledProcessError(
                     return_code, args, output=stdout_text, stderr=stderr_text
                 )
                 if (attempts is None) or (attempts <= 0):
                     raise error
-                if delta is not None:
-                    sleep(to_seconds(delta))
+                if duration is not None:
+                    sleep(duration)
                 return run(
                     cmd,
                     *cmds_or_args,
@@ -881,14 +1264,14 @@ def run(
                     return_=return_,
                     return_stdout=return_stdout,
                     return_stderr=return_stderr,
-                    retry=(attempts - 1, delta),
+                    retry=(attempts - 1, duration),
                     logger=logger,
                 )
             case never:
                 assert_never(never)
 
 
-@contextmanager
+@enhanced_context_manager
 def _run_yield_write(input_: IO[str], /, *outputs: IO[str]) -> Iterator[None]:
     thread = Thread(target=_run_daemon_target, args=(input_, *outputs), daemon=True)
     thread.start()
@@ -1070,7 +1453,7 @@ def ssh(
             retry_skip=_ssh_retry_skip,
             logger=logger,
         )
-    except CalledProcessError as error:  # skipif-ci
+    except CalledProcessError as error:  # pragma: no cover
         if not _ssh_is_strict_checking_error(error.stderr):
             raise
         ssh_keyscan(hostname, port=port)
@@ -1101,8 +1484,9 @@ def _ssh_retry_skip(return_code: int, stdout: str, stderr: str, /) -> bool:
 
 def _ssh_is_strict_checking_error(text: str, /) -> bool:
     match = search(
-        "No ED25519 host key is known for .* and you have requested strict checking",
+        "(Host key for .* has changed|No ED25519 host key is known for .*) and you have requested strict checking",
         text,
+        flags=MULTILINE,
     )
     return match is not None
 
@@ -1159,15 +1543,15 @@ def ssh_await(
     /,
     *,
     logger: LoggerLike | None = None,
-    delta: Delta = SECOND,
+    duration: Duration = SECOND,
 ) -> None:
     while True:  # skipif-ci
         if logger is not None:
             to_logger(logger).info("Waiting for '%s'...", hostname)
         try:
             ssh(user, hostname, "true")
-        except CalledProcessError:
-            sleep(to_seconds(delta))
+        except CalledProcessError:  # pragma: no cover
+            sleep(duration)
         else:
             if logger is not None:
                 to_logger(logger).info("'%s' is up", hostname)
@@ -1178,13 +1562,19 @@ def ssh_await(
 
 
 def ssh_keyscan(
-    hostname: str, /, *, path: PathLike = KNOWN_HOSTS, port: int | None = None
+    hostname: str,
+    /,
+    *,
+    path: PathLike = KNOWN_HOSTS,
+    retry: Retry | None = None,
+    port: int | None = None,
 ) -> None:
     """Add a known host."""
-    ssh_keygen_remove(hostname, path=path)  # skipif-ci
-    mkdir(path, parent=True)  # skipif-ci
-    with Path(path).open(mode="a") as fh:  # skipif-ci
-        _ = fh.write(run(*ssh_keyscan_cmd(hostname, port=port), return_=True))
+    ssh_keygen_remove(hostname, path=path, retry=retry)  # skipif-ci
+    result = run(  # skipif-ci
+        *ssh_keyscan_cmd(hostname, port=port), return_=True, retry=retry
+    )
+    tee(path, result, append=True)  # skipif-ci
 
 
 def ssh_keyscan_cmd(hostname: str, /, *, port: int | None = None) -> list[str]:
@@ -1198,11 +1588,13 @@ def ssh_keyscan_cmd(hostname: str, /, *, port: int | None = None) -> list[str]:
 ##
 
 
-def ssh_keygen_remove(hostname: str, /, *, path: PathLike = KNOWN_HOSTS) -> None:
+def ssh_keygen_remove(
+    hostname: str, /, *, path: PathLike = KNOWN_HOSTS, retry: Retry | None = None
+) -> None:
     """Remove a known host."""
     path = Path(path)
     if path.exists():
-        run(*ssh_keygen_remove_cmd(hostname, path=path))
+        run(*ssh_keygen_remove_cmd(hostname, path=path), retry=retry)
 
 
 def ssh_keygen_remove_cmd(
@@ -1259,7 +1651,8 @@ def symlink_cmd(target: PathLike, link: PathLike, /) -> list[str]:
 def tee(
     path: PathLike, text: str, /, *, sudo: bool = False, append: bool = False
 ) -> None:
-    """Use 'tee' to duplicate standard input."""
+    """Duplicate standard input."""
+    mkdir(path, sudo=sudo, parent=True)
     if sudo:  # pragma: no cover
         run(*sudo_cmd(*tee_cmd(path, append=append)), input=text)
     else:
@@ -1341,27 +1734,200 @@ def useradd_cmd(
 ##
 
 
-@overload
-def uv_run(
-    module: str,
-    /,
-    *args: str,
-    cwd: PathLike | None = None,
-    print: bool = False,
-    print_stdout: bool = False,
-    print_stderr: bool = False,
-    return_: Literal[True],
-    return_stdout: bool = False,
-    return_stderr: bool = False,
-    retry: Retry | None = None,
-    logger: LoggerLike | None = None,
-) -> str: ...
-@overload
-def uv_run(
-    module: str,
-    /,
-    *args: str,
-    cwd: PathLike | None = None,
+def uv_index_cmd(*, index: MaybeSequenceStr | None = None) -> list[str]:
+    """Generate the `--index` command if necessary."""
+    return [] if index is None else ["--index", ",".join(always_iterable(index))]
+
+
+##
+
+
+type _UvPipListFormat = Literal["columns", "freeze", "json"]
+
+
+@dataclass(order=True, unsafe_hash=True, kw_only=True, slots=True)
+class _UvPipListOutput:
+    name: str
+    version: Version2 | Version3
+    editable_project_location: Path | None = None
+    latest_version: Version2 | Version3 | None = None
+    latest_filetype: str | None = None
+
+
+def uv_pip_list(
+    *,
+    editable: bool = False,
+    exclude_editable: bool = False,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+) -> list[_UvPipListOutput]:
+    """List packages installed in an environment."""
+    cmds_base, cmds_outdated = [
+        uv_pip_list_cmd(
+            editable=editable,
+            exclude_editable=exclude_editable,
+            format_="json",
+            outdated=outdated,
+            index=index,
+            native_tls=native_tls,
+        )
+        for outdated in [False, True]
+    ]
+    text_base, text_outdated = [
+        run(*cmds, return_stdout=True) for cmds in [cmds_base, cmds_outdated]
+    ]
+    dicts_base, dicts_outdated = list(
+        map(_uv_pip_list_loads, [text_base, text_outdated])
+    )
+    return [_uv_pip_list_assemble_output(d, dicts_outdated) for d in dicts_base]
+
+
+def _uv_pip_list_loads(text: str, /) -> list[StrMapping]:
+    try:
+        return json.loads(text)
+    except JSONDecodeError:
+        raise _UvPipListJsonError(text=text) from None
+
+
+def _uv_pip_list_assemble_output(
+    dict_: StrMapping, outdated: Iterable[StrMapping], /
+) -> _UvPipListOutput:
+    name = dict_["name"]
+    try:
+        version = parse_version_2_or_3(dict_["version"])
+    except ParseVersion2Or3Error:
+        raise _UvPipListBaseVersionError(data=dict_) from None
+    try:
+        location = Path(dict_["editable_project_location"])
+    except KeyError:
+        location = None
+    try:
+        outdated_i = one(d for d in outdated if d["name"] == name)
+    except OneEmptyError:
+        latest_version = latest_filetype = None
+    else:
+        try:
+            latest_version = parse_version_2_or_3(outdated_i["latest_version"])
+        except ParseVersion2Or3Error:
+            raise _UvPipListOutdatedVersionError(data=outdated_i) from None
+        latest_filetype = outdated_i["latest_filetype"]
+    return _UvPipListOutput(
+        name=dict_["name"],
+        version=version,
+        editable_project_location=location,
+        latest_version=latest_version,
+        latest_filetype=latest_filetype,
+    )
+
+
+@dataclass(kw_only=True, slots=True)
+class UvPipListError(Exception): ...
+
+
+@dataclass(kw_only=True, slots=True)
+class _UvPipListJsonError(UvPipListError):
+    text: str
+
+    @override
+    def __str__(self) -> str:
+        return f"Unable to parse JSON; got {self.text!r}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _UvPipListBaseVersionError(UvPipListError):
+    data: StrMapping
+
+    @override
+    def __str__(self) -> str:
+        return f"Unable to parse version; got {self.data}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _UvPipListOutdatedVersionError(UvPipListError):
+    data: StrMapping
+
+    @override
+    def __str__(self) -> str:
+        return f"Unable to parse version; got {self.data}"
+
+
+def uv_pip_list_cmd(
+    *,
+    editable: bool = False,
+    exclude_editable: bool = False,
+    format_: _UvPipListFormat = "columns",
+    outdated: bool = False,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+) -> list[str]:
+    """Command to use 'uv' to list packages installed in an environment."""
+    args: list[str] = ["uv", "pip", "list"]
+    if editable:
+        args.append("--editable")
+    if exclude_editable:
+        args.append("--exclude-editable")
+    args.extend(["--format", format_])
+    if outdated:
+        args.append("--outdated")
+    return [
+        *args,
+        "--strict",
+        *uv_index_cmd(index=index),
+        MANAGED_PYTHON,
+        *uv_native_tls_cmd(native_tls=native_tls),
+    ]
+
+
+##
+
+
+def uv_native_tls_cmd(*, native_tls: bool = False) -> list[str]:
+    """Generate the `--native-tls` command if necessary."""
+    return ["--native-tls"] if native_tls else []
+
+
+##
+
+
+@overload
+def uv_run(
+    module: str,
+    /,
+    *args: str,
+    extra: MaybeSequenceStr | None = None,
+    all_extras: bool = False,
+    group: MaybeSequenceStr | None = None,
+    all_groups: bool = False,
+    only_dev: bool = False,
+    with_: MaybeSequenceStr | None = None,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+    env: StrStrMapping | None = None,
+    cwd: PathLike | None = None,
+    print: bool = False,
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: Literal[True],
+    return_stdout: bool = False,
+    return_stderr: bool = False,
+    retry: Retry | None = None,
+    logger: LoggerLike | None = None,
+) -> str: ...
+@overload
+def uv_run(
+    module: str,
+    /,
+    *args: str,
+    extra: MaybeSequenceStr | None = None,
+    all_extras: bool = False,
+    group: MaybeSequenceStr | None = None,
+    all_groups: bool = False,
+    only_dev: bool = False,
+    with_: MaybeSequenceStr | None = None,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+    env: StrStrMapping | None = None,
+    cwd: PathLike | None = None,
     print: bool = False,
     print_stdout: bool = False,
     print_stderr: bool = False,
@@ -1376,6 +1942,15 @@ def uv_run(
     module: str,
     /,
     *args: str,
+    extra: MaybeSequenceStr | None = None,
+    all_extras: bool = False,
+    group: MaybeSequenceStr | None = None,
+    all_groups: bool = False,
+    only_dev: bool = False,
+    with_: MaybeSequenceStr | None = None,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+    env: StrStrMapping | None = None,
     cwd: PathLike | None = None,
     print: bool = False,
     print_stdout: bool = False,
@@ -1391,6 +1966,15 @@ def uv_run(
     module: str,
     /,
     *args: str,
+    extra: MaybeSequenceStr | None = None,
+    all_extras: bool = False,
+    group: MaybeSequenceStr | None = None,
+    all_groups: bool = False,
+    only_dev: bool = False,
+    with_: MaybeSequenceStr | None = None,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+    env: StrStrMapping | None = None,
     cwd: PathLike | None = None,
     print: bool = False,
     print_stdout: bool = False,
@@ -1406,6 +1990,15 @@ def uv_run(
     module: str,
     /,
     *args: str,
+    extra: MaybeSequenceStr | None = None,
+    all_extras: bool = False,
+    group: MaybeSequenceStr | None = None,
+    all_groups: bool = False,
+    only_dev: bool = False,
+    with_: MaybeSequenceStr | None = None,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+    env: StrStrMapping | None = None,
     cwd: PathLike | None = None,
     print: bool = False,
     print_stdout: bool = False,
@@ -1420,7 +2013,16 @@ def uv_run(
     module: str,
     /,
     *args: str,
+    extra: MaybeSequenceStr | None = None,
+    all_extras: bool = False,
+    group: MaybeSequenceStr | None = None,
+    all_groups: bool = False,
+    only_dev: bool = False,
+    with_: MaybeSequenceStr | None = None,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
     cwd: PathLike | None = None,
+    env: StrStrMapping | None = None,
     print: bool = False,  # noqa: A002
     print_stdout: bool = False,
     print_stderr: bool = False,
@@ -1432,8 +2034,20 @@ def uv_run(
 ) -> str | None:
     """Run a command or script."""
     return run(  # pragma: no cover
-        *uv_run_cmd(module, *args),
+        *uv_run_cmd(
+            module,
+            *args,
+            extra=extra,
+            all_extras=all_extras,
+            group=group,
+            all_groups=all_groups,
+            only_dev=only_dev,
+            with_=with_,
+            index=index,
+            native_tls=native_tls,
+        ),
         cwd=cwd,
+        env=env,
         print=print,
         print_stdout=print_stdout,
         print_stderr=print_stderr,
@@ -1445,15 +2059,46 @@ def uv_run(
     )
 
 
-def uv_run_cmd(module: str, /, *args: str) -> list[str]:
+def uv_run_cmd(
+    module: str,
+    /,
+    *args: str,
+    extra: MaybeSequenceStr | None = None,
+    all_extras: bool = False,
+    group: MaybeSequenceStr | None = None,
+    all_groups: bool = False,
+    only_dev: bool = False,
+    with_: MaybeSequenceStr | None = None,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+) -> list[str]:
     """Command to use 'uv' to run a command or script."""
+    parts: list[str] = ["uv", "run"]
+    if extra is not None:
+        for extra_i in always_iterable(extra):
+            parts.extend(["--extra", extra_i])
+    if all_extras:
+        parts.append("--all-extras")
+    if not only_dev:
+        parts.append("--no-dev")
+    if group is not None:
+        for group_i in always_iterable(group):
+            parts.extend(["--group", group_i])
+    if all_groups:
+        parts.append("--all-groups")
+    if only_dev:
+        parts.append("--only-dev")
     return [
-        "uv",
-        "run",
-        "--no-dev",
-        "--active",
-        "--prerelease=disallow",
-        "--managed-python",
+        *parts,
+        "--exact",
+        *uv_with_cmd(with_=with_),
+        ISOLATED,
+        *uv_index_cmd(index=index),
+        *RESOLUTION_HIGHEST,
+        *PRERELEASE_DISALLOW,
+        "--reinstall",
+        *uv_native_tls_cmd(native_tls=native_tls),
+        MANAGED_PYTHON,
         "python",
         "-m",
         module,
@@ -1464,7 +2109,356 @@ def uv_run_cmd(module: str, /, *args: str) -> list[str]:
 ##
 
 
-@contextmanager
+@overload
+def uv_tool_install(
+    package: str,
+    /,
+    *,
+    with_: MaybeSequenceStr | None = None,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+    cwd: PathLike | None = None,
+    env: StrStrMapping | None = None,
+    print: bool = False,
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: Literal[True],
+    return_stdout: bool = False,
+    return_stderr: bool = False,
+    retry: Retry | None = None,
+    logger: LoggerLike | None = None,
+) -> str: ...
+@overload
+def uv_tool_install(
+    package: str,
+    /,
+    *,
+    with_: MaybeSequenceStr | None = None,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+    cwd: PathLike | None = None,
+    env: StrStrMapping | None = None,
+    print: bool = False,
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: bool = False,
+    return_stdout: Literal[True],
+    return_stderr: bool = False,
+    retry: Retry | None = None,
+    logger: LoggerLike | None = None,
+) -> str: ...
+@overload
+def uv_tool_install(
+    package: str,
+    /,
+    *,
+    with_: MaybeSequenceStr | None = None,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+    cwd: PathLike | None = None,
+    env: StrStrMapping | None = None,
+    print: bool = False,
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: bool = False,
+    return_stdout: bool = False,
+    return_stderr: Literal[True],
+    retry: Retry | None = None,
+    logger: LoggerLike | None = None,
+) -> str: ...
+@overload
+def uv_tool_install(
+    package: str,
+    /,
+    *,
+    with_: MaybeSequenceStr | None = None,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+    cwd: PathLike | None = None,
+    env: StrStrMapping | None = None,
+    print: bool = False,
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: Literal[False] = False,
+    return_stdout: Literal[False] = False,
+    return_stderr: Literal[False] = False,
+    retry: Retry | None = None,
+    logger: LoggerLike | None = None,
+) -> None: ...
+@overload
+def uv_tool_install(
+    package: str,
+    /,
+    *,
+    with_: MaybeSequenceStr | None = None,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+    cwd: PathLike | None = None,
+    env: StrStrMapping | None = None,
+    print: bool = False,
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: bool = False,
+    return_stdout: bool = False,
+    return_stderr: bool = False,
+    retry: Retry | None = None,
+    logger: LoggerLike | None = None,
+) -> str | None: ...
+def uv_tool_install(
+    package: str,
+    /,
+    *,
+    with_: MaybeSequenceStr | None = None,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+    cwd: PathLike | None = None,
+    env: StrStrMapping | None = None,
+    print: bool = False,  # noqa: A002
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: bool = False,
+    return_stdout: bool = False,
+    return_stderr: bool = False,
+    retry: Retry | None = None,
+    logger: LoggerLike | None = None,
+) -> str | None:
+    """Install commands provided by a Python package."""
+    return run(  # pragma: no cover
+        *uv_tool_install_cmd(package, with_=with_, index=index, native_tls=native_tls),
+        cwd=cwd,
+        env=env,
+        print=print,
+        print_stdout=print_stdout,
+        print_stderr=print_stderr,
+        return_=return_,
+        return_stdout=return_stdout,
+        return_stderr=return_stderr,
+        retry=retry,
+        logger=logger,
+    )
+
+
+def uv_tool_install_cmd(
+    package: str,
+    /,
+    *,
+    with_: MaybeSequenceStr | None = None,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+) -> list[str]:
+    """Command to use 'uv' to install commands provided by a Python package."""
+    return [
+        "uv",
+        "tool",
+        "install",
+        *uv_with_cmd(with_=with_),
+        *uv_index_cmd(index=index),
+        *RESOLUTION_HIGHEST,
+        *PRERELEASE_DISALLOW,
+        "--reinstall",
+        MANAGED_PYTHON,
+        *uv_native_tls_cmd(native_tls=native_tls),
+        package,
+    ]
+
+
+##
+
+
+@overload
+def uv_tool_run(
+    command: str,
+    /,
+    *args: str,
+    from_: str | None = None,
+    latest: bool = True,
+    with_: MaybeSequenceStr | None = None,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+    cwd: PathLike | None = None,
+    env: StrStrMapping | None = None,
+    print: bool = False,
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: Literal[True],
+    return_stdout: bool = False,
+    return_stderr: bool = False,
+    retry: Retry | None = None,
+    logger: LoggerLike | None = None,
+) -> str: ...
+@overload
+def uv_tool_run(
+    command: str,
+    /,
+    *args: str,
+    from_: str | None = None,
+    latest: bool = True,
+    with_: MaybeSequenceStr | None = None,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+    cwd: PathLike | None = None,
+    env: StrStrMapping | None = None,
+    print: bool = False,
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: bool = False,
+    return_stdout: Literal[True],
+    return_stderr: bool = False,
+    retry: Retry | None = None,
+    logger: LoggerLike | None = None,
+) -> str: ...
+@overload
+def uv_tool_run(
+    command: str,
+    /,
+    *args: str,
+    from_: str | None = None,
+    latest: bool = True,
+    with_: MaybeSequenceStr | None = None,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+    cwd: PathLike | None = None,
+    env: StrStrMapping | None = None,
+    print: bool = False,
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: bool = False,
+    return_stdout: bool = False,
+    return_stderr: Literal[True],
+    retry: Retry | None = None,
+    logger: LoggerLike | None = None,
+) -> str: ...
+@overload
+def uv_tool_run(
+    command: str,
+    /,
+    *,
+    from_: str | None = None,
+    latest: bool = True,
+    with_: MaybeSequenceStr | None = None,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+    cwd: PathLike | None = None,
+    env: StrStrMapping | None = None,
+    print: bool = False,
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: Literal[False] = False,
+    return_stdout: Literal[False] = False,
+    return_stderr: Literal[False] = False,
+    retry: Retry | None = None,
+    logger: LoggerLike | None = None,
+) -> None: ...
+@overload
+def uv_tool_run(
+    command: str,
+    /,
+    *args: str,
+    from_: str | None = None,
+    latest: bool = True,
+    with_: MaybeSequenceStr | None = None,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+    cwd: PathLike | None = None,
+    env: StrStrMapping | None = None,
+    print: bool = False,
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: bool = False,
+    return_stdout: bool = False,
+    return_stderr: bool = False,
+    retry: Retry | None = None,
+    logger: LoggerLike | None = None,
+) -> str | None: ...
+def uv_tool_run(
+    command: str,
+    /,
+    *args: str,
+    from_: str | None = None,
+    latest: bool = True,
+    with_: MaybeSequenceStr | None = None,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+    cwd: PathLike | None = None,
+    env: StrStrMapping | None = None,
+    print: bool = False,  # noqa: A002
+    print_stdout: bool = False,
+    print_stderr: bool = False,
+    return_: bool = False,
+    return_stdout: bool = False,
+    return_stderr: bool = False,
+    retry: Retry | None = None,
+    logger: LoggerLike | None = None,
+) -> str | None:
+    """Run a command provided by a Python package."""
+    return run(  # pragma: no cover
+        *uv_tool_run_cmd(
+            command,
+            *args,
+            from_=from_,
+            latest=latest,
+            with_=with_,
+            index=index,
+            native_tls=native_tls,
+        ),
+        cwd=cwd,
+        env=env,
+        print=print,
+        print_stdout=print_stdout,
+        print_stderr=print_stderr,
+        return_=return_,
+        return_stdout=return_stdout,
+        return_stderr=return_stderr,
+        retry=retry,
+        logger=logger,
+    )
+
+
+def uv_tool_run_cmd(
+    command: str,
+    /,
+    *args: str,
+    from_: str | None = None,
+    latest: bool = True,
+    with_: MaybeSequenceStr | None = None,
+    index: MaybeSequenceStr | None = None,
+    native_tls: bool = False,
+) -> list[str]:
+    """Command to use 'uv' to run a command provided by a Python package."""
+    parts: list[str] = ["uv", "tool", "run"]
+    if from_ is not None:
+        from_use = f"{from_}@latest" if latest else from_
+        parts.extend(["--from", from_use])
+    return [
+        *parts,
+        *uv_with_cmd(with_=with_),
+        ISOLATED,
+        *uv_index_cmd(index=index),
+        *RESOLUTION_HIGHEST,
+        *PRERELEASE_DISALLOW,
+        MANAGED_PYTHON,
+        *uv_native_tls_cmd(native_tls=native_tls),
+        command,
+        *args,
+    ]
+
+
+##
+
+
+def uv_with_cmd(*, with_: MaybeSequenceStr | None = None) -> list[str]:
+    """Generate the `--with` commands if necessary."""
+    return (
+        []
+        if with_ is None
+        else list(chain.from_iterable(["--with", w] for w in always_iterable(with_)))
+    )
+
+
+##
+
+
+@enhanced_context_manager
 def yield_git_repo(url: str, /, *, branch: str | None = None) -> Iterator[Path]:
     """Yield a temporary git repository."""
     with TemporaryDirectory() as temp_dir:
@@ -1475,7 +2469,7 @@ def yield_git_repo(url: str, /, *, branch: str | None = None) -> Iterator[Path]:
 ##
 
 
-@contextmanager
+@enhanced_context_manager
 def yield_ssh_temp_dir(
     user: str,
     hostname: str,
@@ -1505,25 +2499,38 @@ __all__ = [
     "BASH_LS",
     "CHPASSWD",
     "GIT_BRANCH_SHOW_CURRENT",
+    "ISOLATED",
+    "MANAGED_PYTHON",
     "MKTEMP_DIR_CMD",
+    "PRERELEASE_DISALLOW",
+    "RESOLUTION_HIGHEST",
     "RESTART_SSHD",
     "UPDATE_CA_CERTIFICATES",
     "ChownCmdError",
     "CpError",
     "MvFileError",
     "RsyncCmdError",
-    "RsyncCmdNoSourcesError",
-    "RsyncCmdSourcesNotFoundError",
+    "UvPipListError",
+    "append_text",
     "apt_install",
     "apt_install_cmd",
+    "apt_remove",
+    "apt_remove_cmd",
+    "apt_update",
+    "cat",
     "cd_cmd",
+    "chattr",
+    "chattr_cmd",
     "chmod",
     "chmod_cmd",
     "chown",
     "chown_cmd",
     "chpasswd",
+    "copy_text",
     "cp",
     "cp_cmd",
+    "curl",
+    "curl_cmd",
     "echo_cmd",
     "env_cmds",
     "expand_path",
@@ -1532,12 +2539,15 @@ __all__ = [
     "git_checkout_cmd",
     "git_clone",
     "git_clone_cmd",
+    "install",
+    "install_cmd",
     "maybe_parent",
     "maybe_sudo_cmd",
     "mkdir",
     "mkdir_cmd",
     "mv",
     "mv_cmd",
+    "replace_text",
     "ripgrep",
     "ripgrep_cmd",
     "rm",
@@ -1565,8 +2575,16 @@ __all__ = [
     "update_ca_certificates",
     "useradd",
     "useradd_cmd",
+    "uv_native_tls_cmd",
+    "uv_pip_list",
+    "uv_pip_list_cmd",
     "uv_run",
     "uv_run_cmd",
+    "uv_tool_install",
+    "uv_tool_install_cmd",
+    "uv_tool_run",
+    "uv_tool_run_cmd",
+    "uv_with_cmd",
     "yield_git_repo",
     "yield_ssh_temp_dir",
 ]