dycw-utilities 0.174.19__py3-none-any.whl → 0.175.6__py3-none-any.whl

{dycw_utilities-0.174.19.dist-info → dycw_utilities-0.175.6.dist-info}/METADATA

@@ -1,6 +1,7 @@
 Metadata-Version: 2.3
 Name: dycw-utilities
-Version: 0.174.19
+Version: 0.175.6
+Summary: Miscellaneous Python utilities
 Author: Derek Wan
 Author-email: Derek Wan <d.wan@icloud.com>
 Requires-Dist: atomicwrites>=1.4.1,<1.5
@@ -28,14 +29,6 @@ Provides-Extra: logging
 Provides-Extra: test
 Description-Content-Type: text/markdown
 
-[![PyPI version](https://badge.fury.io/py/dycw-utilities.svg)](https://badge.fury.io/py/dycw-utilities)
+# `python-utilities`
 
-# `dycw-utilities`
-
-[All the Python functions I don't want to write twice.](https://github.com/nvim-lua/plenary.nvim)
-
-## Installation
-
-- `pip install dycw-utilities`
-
-or with [extras](https://github.com/dycw/python-utilities/blob/master/pyproject.toml).
+Miscellaneous Python utilities

{dycw_utilities-0.174.19.dist-info → dycw_utilities-0.175.6.dist-info}/RECORD

@@ -1,6 +1,5 @@
-utilities/__init__.py,sha256=nyJKpGIkfnetD4-kNA4ZJixn2uq8SdQrflZtDYf_k2Q,61
-utilities/aeventkit.py,sha256=OmDBhYGgbsKrB7cdC5FFpJHUatX9O76eTeKVVTksp2Y,12673
-utilities/altair.py,sha256=rUK99g9x6CYDDfiZrf-aTx5fSRbL1Q8ctgKORowzXHg,9060
+utilities/__init__.py,sha256=7y6XPRHYRyZjE6Vfy185IzZfDUJT8hoQcrfKUT3_4RU,60
+utilities/altair.py,sha256=TLfRFbG9HwG7SLXoJ-v0r-t49ZaGgTQZD82cpjVi4vs,9085
 utilities/asyncio.py,sha256=aJySVxBY0gqsIYnoNmH7-1r8djKuf4vSsU69VCD08t8,16772
 utilities/atomicwrites.py,sha256=tPo6r-Rypd9u99u66B9z86YBPpnLrlHtwox_8Z7T34Y,5790
 utilities/atools.py,sha256=6neeCcgXxK2dlsc0xp15Za7nSucbCgFtAJepGI_-WXU,2549
@@ -66,7 +65,7 @@ utilities/pytest.py,sha256=9HHwYgZQe6CRF0ekHQEFH05gmoP4Ne0V54RrtUNDfi4,10524
 utilities/pytest_plugins/__init__.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
 utilities/pytest_plugins/pytest_randomly.py,sha256=B1qYVlExGOxTywq2r1SMi5o7btHLk2PNdY_b1p98dkE,409
 utilities/pytest_plugins/pytest_regressions.py,sha256=mnHYBfdprz50UGVkVzV1bZERZN5CFfoF8YbokGxdFwU,1639
-utilities/pytest_regressions.py,sha256=nKdVZAa88_aMo1a8V-EIHg_smZYdk1iDQBm50R3FlO4,4044
+utilities/pytest_regressions.py,sha256=tJxW38u-zpoyjW1N4zogBx4V_07r-ibDInddcEUyXmc,4763
 utilities/random.py,sha256=hZlH4gnAtoaofWswuJYjcygejrY8db4CzP-z_adO2Mo,4165
 utilities/re.py,sha256=S4h-DLL6ScMPqjboZ_uQ1BVTJajrqV06r_81D--_HCE,4573
 utilities/redis.py,sha256=gybjqKea33Jy50n4dHTS14JdquqHaJqHF2dixQljYWQ,30172
@@ -81,7 +80,7 @@ utilities/sqlalchemy.py,sha256=HQYpd7LFxdTF5WYVWYtCJeEBI71EJm7ytvCGyAH9B-U,37163
 utilities/sqlalchemy_polars.py,sha256=JCGhB37raSR7fqeWV5dTsciRTMVzIdVT9YSqKT0piT0,13370
 utilities/statsmodels.py,sha256=koyiBHvpMcSiBfh99wFUfSggLNx7cuAw3rwyfAhoKpQ,3410
 utilities/string.py,sha256=shmBK87zZwzGyixuNuXCiUbqzfeZ9xlrFwz6JTaRvDk,582
-utilities/subprocess.py,sha256=7GEv6T9F7z9nacPymzOUUAF6r6ChPjGgKlL64Zrh-AU,34909
+utilities/subprocess.py,sha256=C9H8GiV4gsNRRJY5mo8_2DcNqfeonxcfT5o6icQeSkg,40599
 utilities/tempfile.py,sha256=Lx6qa16lL1XVH6WdmD_G9vlN6gLI8nrIurxmsFkPKvg,3022
 utilities/testbook.py,sha256=j1KmaVbrX9VrbeMgtPh5gk55myAsn3dyRUn7jGbPbRk,1294
 utilities/text.py,sha256=7SvwcSR2l_5cOrm1samGnR4C-ZI6qyFLHLzSpO1zeHQ,13958
@@ -98,7 +97,7 @@ utilities/warnings.py,sha256=un1LvHv70PU-LLv8RxPVmugTzDJkkGXRMZTE2-fTQHw,1771
 utilities/whenever.py,sha256=F4ek0-OBWxHYrZdmoZt76N2RnNyKY5KrEHt7rqO4AQE,60183
 utilities/zipfile.py,sha256=24lQc9ATcJxHXBPc_tBDiJk48pWyRrlxO2fIsFxU0A8,699
 utilities/zoneinfo.py,sha256=tdIScrTB2-B-LH0ukb1HUXKooLknOfJNwHk10MuMYvA,3619
-dycw_utilities-0.174.19.dist-info/WHEEL,sha256=RRVLqVugUmFOqBedBFAmA4bsgFcROUBiSUKlERi0Hcg,79
-dycw_utilities-0.174.19.dist-info/entry_points.txt,sha256=ykGI1ArwOPHqm2g5Cqh3ENdMxEej_a_FcOUov5EM5Oc,155
-dycw_utilities-0.174.19.dist-info/METADATA,sha256=g_N5AxOBCGnPuLyOGvWEVdKj0mdu7pSyW2R6FBaPCmE,1710
-dycw_utilities-0.174.19.dist-info/RECORD,,
+dycw_utilities-0.175.6.dist-info/WHEEL,sha256=RRVLqVugUmFOqBedBFAmA4bsgFcROUBiSUKlERi0Hcg,79
+dycw_utilities-0.175.6.dist-info/entry_points.txt,sha256=cOGtKeJI0KXLSV7MJ8Dhc2G8jPgDcBDm53MVNJU4ycI,136
+dycw_utilities-0.175.6.dist-info/METADATA,sha256=761YNYgBWP5Xs0xN_xnVhdet11rc3wj-eIQfF_XoqNk,1442
+dycw_utilities-0.175.6.dist-info/RECORD,,

{dycw_utilities-0.174.19.dist-info → dycw_utilities-0.175.6.dist-info}/entry_points.txt

@@ -1,5 +1,3 @@
-[console_scripts]
-
 [pytest11]
 pytest-randomly = utilities.pytest_plugins.pytest_randomly
 pytest-regressions = utilities.pytest_plugins.pytest_regressions

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.174.19"
+__version__ = "0.175.6"

utilities/altair.py

@@ -145,7 +145,9 @@ def plot_dataframes(
     ]
     zoom = selection_interval(bind="scales", encodings=["x"])
     chart = (
-        vconcat(*layers).add_params(zoom).resolve_scale(color="independent", x="shared")
+        vconcat_charts(*layers)
+        .add_params(zoom)
+        .resolve_scale(color="independent", x="shared")
     )
     if title is not None:
         chart = chart.properties(title=title)

utilities/pytest_regressions.py

@@ -1,15 +1,17 @@
 from __future__ import annotations
 
 from contextlib import suppress
+from dataclasses import dataclass
 from json import loads
 from pathlib import Path
 from shutil import copytree
-from typing import TYPE_CHECKING, Any, assert_never
+from typing import TYPE_CHECKING, Any, assert_never, override
 
 from pytest_regressions.file_regression import FileRegressionFixture
 
 from utilities.functions import ensure_str
 from utilities.operator import is_equal
+from utilities.reprlib import get_repr
 
 if TYPE_CHECKING:
     from polars import DataFrame, Series
@@ -70,10 +72,28 @@ class OrjsonRegressionFixture:
             check_fn=self._check_fn,
         )
 
-    def _check_fn(self, path1: Path, path2: Path, /) -> None:
-        left = loads(path1.read_text())
-        right = loads(path2.read_text())
-        assert is_equal(left, right), f"{left=}, {right=}"
+    def _check_fn(self, path_obtained: Path, path_existing: Path, /) -> None:
+        obtained = loads(path_obtained.read_text())
+        existing = loads(path_existing.read_text())
+        if not is_equal(obtained, existing):
+            raise OrjsonRegressionError(
+                path_obtained=path_obtained,
+                path_existing=path_existing,
+                obtained=obtained,
+                existing=existing,
+            )
+
+
+@dataclass(kw_only=True, slots=True)
+class OrjsonRegressionError(Exception):
+    path_obtained: Path
+    path_existing: Path
+    obtained: Any
+    existing: Any
+
+    @override
+    def __str__(self) -> str:
+        return f"Obtained object (at {str(self.path_obtained)!r}) and existing object (at {str(self.path_existing)!r}) differ; got {get_repr(self.obtained)} and {get_repr(self.existing)}"
 
 
 ##

utilities/subprocess.py

@@ -6,6 +6,7 @@ from contextlib import contextmanager
 from dataclasses import dataclass
 from io import StringIO
 from pathlib import Path
+from re import search
 from shlex import join
 from shutil import copyfile, copytree, move, rmtree
 from string import Template
@@ -23,7 +24,7 @@ from utilities.text import strip_and_dedent
 from utilities.whenever import to_seconds
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Callable, Iterator
 
     from utilities.permissions import PermissionsLike
     from utilities.types import (
@@ -41,6 +42,7 @@ APT_UPDATE = ["apt", "update", "-y"]
 BASH_LC = ["bash", "-lc"]
 BASH_LS = ["bash", "-ls"]
 GIT_BRANCH_SHOW_CURRENT = ["git", "branch", "--show-current"]
+KNOWN_HOSTS = Path.home() / ".ssh/known_hosts"
 MKTEMP_DIR_CMD = ["mktemp", "-d"]
 RESTART_SSHD = ["systemctl", "restart", "sshd"]
 UPDATE_CA_CERTIFICATES: str = "update-ca-certificates"
@@ -49,6 +51,13 @@ UPDATE_CA_CERTIFICATES: str = "update-ca-certificates"
 ##
 
 
+def apt_install(package: str, /, *, update: bool = False, sudo: bool = False) -> None:
+    """Install a package."""
+    if update:  # pragma: no cover
+        run(*maybe_sudo_cmd(*APT_UPDATE, sudo=sudo))
+    run(*maybe_sudo_cmd(*apt_install_cmd(package), sudo=sudo))
+
+
 def apt_install_cmd(package: str, /) -> list[str]:
     """Command to use 'apt' to install a package."""
     return ["apt", "install", "-y", package]
@@ -250,7 +259,7 @@ def git_clone(
     rm(path, sudo=sudo)
     run(*maybe_sudo_cmd(*git_clone_cmd(url, path), sudo=sudo))
     if branch is not None:
-        run(*maybe_sudo_cmd(*git_hard_reset_cmd(branch=branch), sudo=sudo), cwd=path)
+        git_checkout(branch, path)
 
 
 def git_clone_cmd(url: str, path: PathLike, /) -> list[str]:
@@ -261,15 +270,6 @@ def git_clone_cmd(url: str, path: PathLike, /) -> list[str]:
 ##
 
 
-def git_hard_reset_cmd(*, branch: str | None = None) -> list[str]:
-    """Command to use 'git hard-reset' to hard reset a repository."""
-    branch_use = "master" if branch is None else branch
-    return ["git", "hard-reset", branch_use]
-
-
-##
-
-
 def maybe_parent(path: PathLike, /, *, parent: bool = False) -> Path:
     """Get the parent of a path, if required."""
     path = Path(path)
@@ -525,6 +525,7 @@ def rsync_many(
     host_key_algorithms: list[str] = _HOST_KEY_ALGORITHMS,
     strict_host_key_checking: bool = True,
     print: bool = False,  # noqa: A002
+    exclude: MaybeIterable[str] | None = None,
 ) -> None:
     cmds: list[list[str]] = []  # skipif-ci
     with (  # skipif-ci
@@ -562,6 +563,7 @@ def rsync_many(
             print=print,
             retry=retry,
             logger=logger,
+            exclude=exclude,
         )
         ssh(
             user,
@@ -627,6 +629,7 @@ def run(
     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: ...
 @overload
@@ -647,6 +650,7 @@ def run(
     return_stdout: Literal[True],
     return_stderr: bool = False,
     retry: Retry | None = None,
+    retry_skip: Callable[[int, str, str], bool] | None = None,
     logger: LoggerLike | None = None,
 ) -> str: ...
 @overload
@@ -667,6 +671,7 @@ def run(
     return_stdout: bool = False,
     return_stderr: Literal[True],
     retry: Retry | None = None,
+    retry_skip: Callable[[int, str, str], bool] | None = None,
     logger: LoggerLike | None = None,
 ) -> str: ...
 @overload
@@ -687,6 +692,7 @@ def run(
     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
@@ -707,6 +713,7 @@ def run(
     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 run(
@@ -726,6 +733,7 @@ def run(
     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:
     """Run a command in a subprocess."""
@@ -783,14 +791,18 @@ def run(
             case 0, False, False:
                 return None
             case _, _, _:
-                if retry is None:
-                    attempts = delta = None
-                else:
-                    attempts, delta = retry
                 _ = stdout.seek(0)
                 stdout_text = stdout.read()
                 _ = stderr.seek(0)
                 stderr_text = stderr.read()
+                if (retry is None) or (
+                    (retry is not None)
+                    and (retry_skip is not None)
+                    and retry_skip(return_code, stdout_text, stderr_text)
+                ):
+                    attempts = delta = None
+                else:
+                    attempts, delta = retry
                 if logger is not None:
                     msg = strip_and_dedent(f"""
 'run' failed with:
@@ -885,6 +897,7 @@ def ssh(
     batch_mode: bool = True,
     host_key_algorithms: list[str] = _HOST_KEY_ALGORITHMS,
     strict_host_key_checking: bool = True,
+    port: int | None = None,
     input: str | None = None,
     print: bool = False,
     print_stdout: bool = False,
@@ -904,6 +917,7 @@ def ssh(
     batch_mode: bool = True,
     host_key_algorithms: list[str] = _HOST_KEY_ALGORITHMS,
     strict_host_key_checking: bool = True,
+    port: int | None = None,
     input: str | None = None,
     print: bool = False,
     print_stdout: bool = False,
@@ -923,6 +937,7 @@ def ssh(
     batch_mode: bool = True,
     host_key_algorithms: list[str] = _HOST_KEY_ALGORITHMS,
     strict_host_key_checking: bool = True,
+    port: int | None = None,
     input: str | None = None,
     print: bool = False,
     print_stdout: bool = False,
@@ -942,6 +957,7 @@ def ssh(
     batch_mode: bool = True,
     host_key_algorithms: list[str] = _HOST_KEY_ALGORITHMS,
     strict_host_key_checking: bool = True,
+    port: int | None = None,
     input: str | None = None,
     print: bool = False,
     print_stdout: bool = False,
@@ -961,6 +977,7 @@ def ssh(
     batch_mode: bool = True,
     host_key_algorithms: list[str] = _HOST_KEY_ALGORITHMS,
     strict_host_key_checking: bool = True,
+    port: int | None = None,
     input: str | None = None,
     print: bool = False,
     print_stdout: bool = False,
@@ -979,6 +996,7 @@ def ssh(
     batch_mode: bool = True,
     host_key_algorithms: list[str] = _HOST_KEY_ALGORITHMS,
     strict_host_key_checking: bool = True,
+    port: int | None = None,
     input: str | None = None,  # noqa: A002
     print: bool = False,  # noqa: A002
     print_stdout: bool = False,
@@ -997,19 +1015,57 @@ def ssh(
         batch_mode=batch_mode,
         host_key_algorithms=host_key_algorithms,
         strict_host_key_checking=strict_host_key_checking,
+        port=port,
     )
-    return run(  # skipif-ci
-        *cmd_and_args,
-        input=input,
-        print=print,
-        print_stdout=print_stdout,
-        print_stderr=print_stderr,
-        return_=return_,
-        return_stdout=return_stdout,
-        return_stderr=return_stderr,
-        retry=retry,
-        logger=logger,
+    try:  # skipif-ci
+        return run(
+            *cmd_and_args,
+            input=input,
+            print=print,
+            print_stdout=print_stdout,
+            print_stderr=print_stderr,
+            return_=return_,
+            return_stdout=return_stdout,
+            return_stderr=return_stderr,
+            retry=retry,
+            retry_skip=_ssh_retry_skip,
+            logger=logger,
+        )
+    except CalledProcessError as error:  # skipif-ci
+        if not _ssh_is_strict_checking_error(error.stderr):
+            raise
+        ssh_keyscan(hostname, port=port)
+        return ssh(
+            user,
+            hostname,
+            *cmd_and_cmds_or_args,
+            batch_mode=batch_mode,
+            host_key_algorithms=host_key_algorithms,
+            strict_host_key_checking=strict_host_key_checking,
+            port=port,
+            input=input,
+            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 _ssh_retry_skip(return_code: int, stdout: str, stderr: str, /) -> bool:
+    _ = (return_code, stdout)
+    return _ssh_is_strict_checking_error(stderr)
+
+
+def _ssh_is_strict_checking_error(text: str, /) -> bool:
+    match = search(
+        "No ED25519 host key is known for .* and you have requested strict checking",
+        text,
     )
+    return match is not None
 
 
 def ssh_cmd(
@@ -1020,12 +1076,14 @@ def ssh_cmd(
     batch_mode: bool = True,
     host_key_algorithms: list[str] = _HOST_KEY_ALGORITHMS,
     strict_host_key_checking: bool = True,
+    port: int | None = None,
 ) -> list[str]:
     """Command to use 'ssh' to execute a command on a remote machine."""
     args: list[str] = ssh_opts_cmd(
         batch_mode=batch_mode,
         host_key_algorithms=host_key_algorithms,
         strict_host_key_checking=strict_host_key_checking,
+        port=port,
     )
     return [*args, f"{user}@{hostname}", *cmd_and_cmds_or_args]
 
@@ -1035,6 +1093,7 @@ def ssh_opts_cmd(
     batch_mode: bool = True,
     host_key_algorithms: list[str] = _HOST_KEY_ALGORITHMS,
     strict_host_key_checking: bool = True,
+    port: int | None = None,
 ) -> list[str]:
     """Command to use prepare 'ssh' to execute a command on a remote machine."""
     args: list[str] = ["ssh"]
@@ -1043,15 +1102,47 @@ def ssh_opts_cmd(
     args.extend(["-o", f"HostKeyAlgorithms={','.join(host_key_algorithms)}"])
     if strict_host_key_checking:
         args.extend(["-o", "StrictHostKeyChecking=yes"])
+    if port is not None:
+        args.extend(["-p", str(port)])
     return [*args, "-T"]
 
 
 ##
 
 
-def ssh_keygen_cmd(hostname: str, /) -> list[str]:
-    """Command to use 'ssh-keygen' to add a known host."""
-    return ["ssh-keygen", "-f", "~/.ssh/known_hosts", "-R", hostname]
+def ssh_keyscan(
+    hostname: str, /, *, path: PathLike = KNOWN_HOSTS, 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))
+
+
+def ssh_keyscan_cmd(hostname: str, /, *, port: int | None = None) -> list[str]:
+    """Command to use 'ssh-keyscan' to add a known host."""
+    args: list[str] = ["ssh-keyscan"]
+    if port is not None:
+        args.extend(["-p", str(port)])
+    return [*args, "-q", "-t", "ed25519", hostname]
+
+
+##
+
+
+def ssh_keygen_remove(hostname: str, /, *, path: PathLike = KNOWN_HOSTS) -> None:
+    """Remove a known host."""
+    path = Path(path)
+    if path.exists():
+        run(*ssh_keygen_remove_cmd(hostname, path=path))
+
+
+def ssh_keygen_remove_cmd(
+    hostname: str, /, *, path: PathLike = KNOWN_HOSTS
+) -> list[str]:
+    """Command to use 'ssh-keygen' to remove a known host."""
+    return ["ssh-keygen", "-f", str(path), "-R", hostname]
 
 
 ##
@@ -1134,9 +1225,108 @@ def touch_cmd(path: PathLike, /) -> list[str]:
 ##
 
 
-def uv_run(module: str, /, *args: str) -> None:
+@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,
+    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_run(
+    module: str,
+    /,
+    *args: str,
+    cwd: PathLike | 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_run(
+    module: str,
+    /,
+    *args: str,
+    cwd: PathLike | 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_run(
+    module: str,
+    /,
+    *args: str,
+    cwd: PathLike | 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_run(
+    module: str,
+    /,
+    *args: str,
+    cwd: PathLike | 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 or script."""
-    run(*uv_run_cmd(module, *args))  # pragma: no cover
+    return run(  # pragma: no cover
+        *uv_run_cmd(module, *args),
+        cwd=cwd,
+        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_run_cmd(module: str, /, *args: str) -> list[str]:
@@ -1207,6 +1397,7 @@ __all__ = [
     "RsyncCmdError",
     "RsyncCmdNoSourcesError",
     "RsyncCmdSourcesNotFoundError",
+    "apt_install",
     "apt_install_cmd",
     "cd_cmd",
     "chmod",
@@ -1222,7 +1413,6 @@ __all__ = [
     "git_checkout_cmd",
     "git_clone",
     "git_clone_cmd",
-    "git_hard_reset_cmd",
     "maybe_parent",
     "maybe_sudo_cmd",
     "mkdir",
@@ -1238,6 +1428,10 @@ __all__ = [
     "set_hostname_cmd",
     "ssh",
     "ssh_cmd",
+    "ssh_keygen_remove",
+    "ssh_keygen_remove_cmd",
+    "ssh_keyscan",
+    "ssh_keyscan_cmd",
     "ssh_opts_cmd",
     "sudo_cmd",
     "sudo_nopasswd_cmd",

utilities/aeventkit.py

@@ -1,389 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-from functools import wraps
-from inspect import iscoroutinefunction
-from typing import TYPE_CHECKING, Any, Self, assert_never, cast, override
-
-from eventkit import (
-    Constant,
-    Count,
-    DropWhile,
-    Enumerate,
-    Event,
-    Filter,
-    Fork,
-    Iterate,
-    Map,
-    Pack,
-    Partial,
-    PartialRight,
-    Pluck,
-    Skip,
-    Star,
-    Take,
-    TakeUntil,
-    TakeWhile,
-    Timestamp,
-)
-
-from utilities.functions import apply_decorators
-from utilities.iterables import always_iterable
-from utilities.logging import to_logger
-
-if TYPE_CHECKING:
-    from collections.abc import Callable
-
-    from utilities.types import Coro, LoggerLike, MaybeCoro, MaybeIterable, TypeLike
-
-
-##
-
-
-def add_listener[E: Event, F: Callable](
-    event: E,
-    listener: Callable[..., MaybeCoro[None]],
-    /,
-    *,
-    error: Callable[[Event, BaseException], MaybeCoro[None]] | None = None,
-    ignore: TypeLike[BaseException] | None = None,
-    logger: LoggerLike | None = None,
-    decorators: MaybeIterable[Callable[[F], F]] | None = None,
-    done: Callable[..., MaybeCoro[None]] | None = None,
-    keep_ref: bool = False,
-) -> E:
-    """Connect a listener to an event."""
-    lifted = lift_listener(
-        listener,
-        event,
-        error=error,
-        ignore=ignore,
-        logger=logger,
-        decorators=decorators,
-    )
-    return cast("E", event.connect(lifted, done=done, keep_ref=keep_ref))
-
-
-##
-
-
-@dataclass(repr=False, kw_only=True)
-class LiftedEvent[F: Callable[..., MaybeCoro[None]]]:
-    """A lifted version of `Event`."""
-
-    event: Event
-
-    def name(self) -> str:
-        return self.event.name()  # pragma: no cover
-
-    def done(self) -> bool:
-        return self.event.done()  # pragma: no cover
-
-    def set_done(self) -> None:
-        self.event.set_done()  # pragma: no cover
-
-    def value(self) -> Any:
-        return self.event.value()  # pragma: no cover
-
-    def connect[F2: Callable](
-        self,
-        listener: F,
-        /,
-        *,
-        error: Callable[[Event, BaseException], MaybeCoro[None]] | None = None,
-        ignore: TypeLike[BaseException] | None = None,
-        logger: LoggerLike | None = None,
-        decorators: MaybeIterable[Callable[[F2], F2]] | None = None,
-        done: Callable[..., MaybeCoro[None]] | None = None,
-        keep_ref: bool = False,
-    ) -> Event:
-        return add_listener(
-            self.event,
-            listener,
-            error=error,
-            ignore=ignore,
-            logger=logger,
-            decorators=decorators,
-            done=done,
-            keep_ref=keep_ref,
-        )
-
-    def disconnect(
-        self, listener: Any, /, *, error: Any = None, done: Any = None
-    ) -> Any:
-        return self.event.disconnect(  # pragma: no cover
-            listener, error=error, done=done
-        )
-
-    def disconnect_obj(self, obj: Any, /) -> None:
-        self.event.disconnect_obj(obj)  # pragma: no cover
-
-    def emit(self, *args: Any) -> None:
-        self.event.emit(*args)  # pragma: no cover
-
-    def emit_threadsafe(self, *args: Any) -> None:
-        self.event.emit_threadsafe(*args)  # pragma: no cover
-
-    def clear(self) -> None:
-        self.event.clear()  # pragma: no cover
-
-    def run(self) -> list[Any]:
-        return self.event.run()  # pragma: no cover
-
-    def pipe(self, *targets: Event) -> Event:
-        return self.event.pipe(*targets)  # pragma: no cover
-
-    def fork(self, *targets: Event) -> Fork:
-        return self.event.fork(*targets)  # pragma: no cover
-
-    def set_source(self, source: Any, /) -> None:
-        self.event.set_source(source)  # pragma: no cover
-
-    def _onFinalize(self, ref: Any) -> None:  # noqa: N802
-        self.event._onFinalize(ref)  # noqa: SLF001 # pragma: no cover
-
-    async def aiter(self, *, skip_to_last: bool = False, tuples: bool = False) -> Any:
-        async for i in self.event.aiter(  # pragma: no cover
-            skip_to_last=skip_to_last, tuples=tuples
-        ):
-            yield i
-
-    __iadd__ = connect
-    __isub__ = disconnect
-    __call__ = emit
-    __or__ = pipe
-
-    @override
-    def __repr__(self) -> str:
-        return self.event.__repr__()  # pragma: no cover
-
-    def __len__(self) -> int:
-        return self.event.__len__()  # pragma: no cover
-
-    def __bool__(self) -> bool:
-        return self.event.__bool__()  # pragma: no cover
-
-    def __getitem__(self, fork_targets: Any, /) -> Fork:
-        return self.event.__getitem__(fork_targets)  # pragma: no cover
-
-    def __await__(self) -> Any:
-        return self.event.__await__()  # pragma: no cover
-
-    def __aiter__(self) -> Any:
-        return self.event.aiter()  # pragma: no cover
-
-    def __contains__(self, c: Any, /) -> bool:
-        return self.event.__contains__(c)  # pragma: no cover
-
-    @override
-    def __reduce__(self) -> Any:
-        return self.event.__reduce__()  # pragma: no cover
-
-    def filter(self, *, predicate: Any = bool) -> Filter:
-        return self.event.filter(predicate=predicate)  # pragma: no cover
-
-    def skip(self, *, count: int = 1) -> Skip:
-        return self.event.skip(count=count)  # pragma: no cover
-
-    def take(self, *, count: int = 1) -> Take:
-        return self.event.take(count=count)  # pragma: no cover
-
-    def takewhile(self, *, predicate: Any = bool) -> TakeWhile:
-        return self.event.takewhile(predicate=predicate)  # pragma: no cover
-
-    def dropwhile(self, *, predicate: Any = lambda x: not x) -> DropWhile:  # pyright: ignore[reportUnknownLambdaType]
-        return self.event.dropwhile(predicate=predicate)  # pragma: no cover
-
-    def takeuntil(self, notifier: Event, /) -> TakeUntil:
-        return self.event.takeuntil(notifier)  # pragma: no cover
-
-    def constant(self, constant: Any, /) -> Constant:
-        return self.event.constant(constant)  # pragma: no cover
-
-    def iterate(self, it: Any, /) -> Iterate:
-        return self.event.iterate(it)  # pragma: no cover
-
-    def count(self, *, start: int = 0, step: int = 1) -> Count:
-        return self.event.count(start=start, step=step)  # pragma: no cover
-
-    def enumerate(self, *, start: int = 0, step: int = 1) -> Enumerate:
-        return self.event.enumerate(start=start, step=step)  # pragma: no cover
-
-    def timestamp(self) -> Timestamp:
-        return self.event.timestamp()  # pragma: no cover
-
-    def partial(self, *left_args: Any) -> Partial:
-        return self.event.partial(*left_args)  # pragma: no cover
-
-    def partial_right(self, *right_args: Any) -> PartialRight:
-        return self.event.partial_right(*right_args)  # pragma: no cover
-
-    def star(self) -> Star:
-        return self.event.star()  # pragma: no cover
-
-    def pack(self) -> Pack:
-        return self.event.pack()  # pragma: no cover
-
-    def pluck(self, *selections: int | str) -> Pluck:
-        return self.event.pluck(*selections)  # pragma: no cover
-
-    def map(
-        self,
-        func: Any,
-        /,
-        *,
-        timeout: float | None = None,
-        ordered: bool = True,
-        task_limit: int | None = None,
-    ) -> Map:
-        return self.event.map(  # pragma: no cover
-            func, timeout=timeout, ordered=ordered, task_limit=task_limit
-        )
-
-
-##
-
-
-class TypedEvent[F: Callable[..., MaybeCoro[None]]](Event):
-    """A typed version of `Event`."""
-
-    @override
-    def connect[F2: Callable](
-        self,
-        listener: F,
-        error: Callable[[Self, BaseException], MaybeCoro[None]] | None = None,
-        done: Callable[[Self], MaybeCoro[None]] | None = None,
-        keep_ref: bool = False,
-        *,
-        ignore: TypeLike[BaseException] | None = None,
-        logger: LoggerLike | None = None,
-        decorators: MaybeIterable[Callable[[F2], F2]] | None = None,
-    ) -> Self:
-        lifted = lift_listener(
-            listener,
-            self,
-            error=cast(
-                "Callable[[Event, BaseException], MaybeCoro[None]] | None", error
-            ),
-            ignore=ignore,
-            logger=logger,
-            decorators=decorators,
-        )
-        return cast(
-            "Self", super().connect(lifted, error=error, done=done, keep_ref=keep_ref)
-        )
-
-
-##
-
-
-def lift_listener[F1: Callable[..., MaybeCoro[None]], F2: Callable](
-    listener: F1,
-    event: Event,
-    /,
-    *,
-    error: Callable[[Event, BaseException], MaybeCoro[None]] | None = None,
-    ignore: TypeLike[BaseException] | None = None,
-    logger: LoggerLike | None = None,
-    decorators: MaybeIterable[Callable[[F2], F2]] | None = None,
-) -> F1:
-    match error, bool(iscoroutinefunction(listener)):
-        case None, False:
-            listener_typed = cast("Callable[..., None]", listener)
-
-            @wraps(listener)
-            def listener_no_error_sync(*args: Any, **kwargs: Any) -> None:
-                try:
-                    listener_typed(*args, **kwargs)
-                except Exception as exc:  # noqa: BLE001
-                    if (ignore is not None) and isinstance(exc, ignore):
-                        return
-                    to_logger(logger).exception("")
-
-            lifted = listener_no_error_sync
-
-        case None, True:
-            listener_typed = cast("Callable[..., Coro[None]]", listener)
-
-            @wraps(listener)
-            async def listener_no_error_async(*args: Any, **kwargs: Any) -> None:
-                try:
-                    await listener_typed(*args, **kwargs)
-                except Exception as exc:  # noqa: BLE001
-                    if (ignore is not None) and isinstance(exc, ignore):
-                        return
-                    to_logger(logger).exception("")
-
-            lifted = listener_no_error_async
-        case _, _:
-            match bool(iscoroutinefunction(listener)), bool(iscoroutinefunction(error)):
-                case False, False:
-                    listener_typed = cast("Callable[..., None]", listener)
-                    error_typed = cast("Callable[[Event, Exception], None]", error)
-
-                    @wraps(listener)
-                    def listener_have_error_sync(*args: Any, **kwargs: Any) -> None:
-                        try:
-                            listener_typed(*args, **kwargs)
-                        except Exception as exc:  # noqa: BLE001
-                            if (ignore is not None) and isinstance(exc, ignore):
-                                return
-                            error_typed(event, exc)
-
-                    lifted = listener_have_error_sync
-                case False, True:
-                    listener_typed = cast("Callable[..., None]", listener)
-                    error_typed = cast(
-                        "Callable[[Event, Exception], Coro[None]]", error
-                    )
-                    raise LiftListenerError(listener=listener_typed, error=error_typed)
-                case True, _:
-                    listener_typed = cast("Callable[..., Coro[None]]", listener)
-
-                    @wraps(listener)
-                    async def listener_have_error_async(
-                        *args: Any, **kwargs: Any
-                    ) -> None:
-                        try:
-                            await listener_typed(*args, **kwargs)
-                        except Exception as exc:  # noqa: BLE001
-                            if (ignore is not None) and isinstance(exc, ignore):
-                                return None
-                            if iscoroutinefunction(error):
-                                error_typed = cast(
-                                    "Callable[[Event, Exception], Coro[None]]", error
-                                )
-                                return await error_typed(event, exc)
-                            error_typed = cast(
-                                "Callable[[Event, Exception], None]", error
-                            )
-                            error_typed(event, exc)
-
-                    lifted = listener_have_error_async
-                case never:
-                    assert_never(never)
-        case never:
-            assert_never(never)
-
-    if decorators is not None:
-        lifted = apply_decorators(lifted, *always_iterable(decorators))
-    return cast("F1", lifted)
-
-
-@dataclass(kw_only=True, slots=True)
-class LiftListenerError(Exception):
-    listener: Callable[..., None]
-    error: Callable[[Event, Exception], Coro[None]]
-
-    @override
-    def __str__(self) -> str:
-        return f"Synchronous listener {self.listener} cannot be paired with an asynchronous error handler {self.error}"
-
-
-__all__ = [
-    "LiftListenerError",
-    "LiftedEvent",
-    "TypedEvent",
-    "add_listener",
-    "lift_listener",
-]