dycw-utilities 0.174.16__py3-none-any.whl → 0.174.18__py3-none-any.whl

{dycw_utilities-0.174.16.dist-info → dycw_utilities-0.174.18.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dycw-utilities
-Version: 0.174.16
+Version: 0.174.18
 Author: Derek Wan
 Author-email: Derek Wan <d.wan@icloud.com>
 Requires-Dist: atomicwrites>=1.4.1,<1.5

{dycw_utilities-0.174.16.dist-info → dycw_utilities-0.174.18.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=vtFT93z2VkUoI-200aWbVdTniPgIRP-XjQ6slYwfpHo,61
+utilities/__init__.py,sha256=2xupJL_-0RN3mhQDSD7NIAJegYc_Pr3NKdbT8LPHrvI,61
 utilities/aeventkit.py,sha256=OmDBhYGgbsKrB7cdC5FFpJHUatX9O76eTeKVVTksp2Y,12673
 utilities/altair.py,sha256=rUK99g9x6CYDDfiZrf-aTx5fSRbL1Q8ctgKORowzXHg,9060
 utilities/asyncio.py,sha256=aJySVxBY0gqsIYnoNmH7-1r8djKuf4vSsU69VCD08t8,16772
@@ -12,7 +12,7 @@ utilities/contextvars.py,sha256=J8OhC7jqozAGYOCe2KUWysbPXNGe5JYz3HfaY_mIs08,883
 utilities/cryptography.py,sha256=5PFrzsNUGHay91dFgYnDKwYprXxahrBqztmUqViRzBk,956
 utilities/cvxpy.py,sha256=Rv1-fD-XYerosCavRF8Pohop2DBkU3AlFaGTfD8AEAA,13776
 utilities/dataclasses.py,sha256=xbU3QN1GFy7RC6hIJRZIeUZm7YRlodrgEWmahWG6k2g,32465
-utilities/docker.py,sha256=l_R9Eyhc-_JbkkaYXYKGZ0PZ_oukrSj8aKtD1NyAhMM,7879
+utilities/docker.py,sha256=N__PKd3cnSRsXNEMHMLdLneLdyzfbr2ESkElcwrovvQ,7940
 utilities/enum.py,sha256=5l6pwZD1cjSlVW4ss-zBPspWvrbrYrdtJWcg6f5_J5w,5781
 utilities/errors.py,sha256=mFlDGSM0LI1jZ1pbqwLAH3ttLZ2JVIxyZLojw8tGVZU,1479
 utilities/fastapi.py,sha256=TqyKvBjiMS594sXPjrz-KRTLMb3l3D3rZ1zAYV7GfOk,1454
@@ -81,7 +81,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=c9f3-HCXVOAMBkfcs4ytmtGUKRH24UlV1D_NdvPqfVA,28937
+utilities/subprocess.py,sha256=q0k-Fl8iRKX9UvqtNgshUcrv-tAEzJbeyoQWiWEdql8,34298
 utilities/tempfile.py,sha256=Lx6qa16lL1XVH6WdmD_G9vlN6gLI8nrIurxmsFkPKvg,3022
 utilities/testbook.py,sha256=j1KmaVbrX9VrbeMgtPh5gk55myAsn3dyRUn7jGbPbRk,1294
 utilities/text.py,sha256=7SvwcSR2l_5cOrm1samGnR4C-ZI6qyFLHLzSpO1zeHQ,13958
@@ -98,7 +98,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.16.dist-info/WHEEL,sha256=ZyFSCYkV2BrxH6-HRVRg3R9Fo7MALzer9KiPYqNxSbo,79
-dycw_utilities-0.174.16.dist-info/entry_points.txt,sha256=ykGI1ArwOPHqm2g5Cqh3ENdMxEej_a_FcOUov5EM5Oc,155
-dycw_utilities-0.174.16.dist-info/METADATA,sha256=aNMnbDY3Lh5LGRBgi6ySNdZ3PR2zd3cxGHv28VNPX44,1710
-dycw_utilities-0.174.16.dist-info/RECORD,,
+dycw_utilities-0.174.18.dist-info/WHEEL,sha256=RRVLqVugUmFOqBedBFAmA4bsgFcROUBiSUKlERi0Hcg,79
+dycw_utilities-0.174.18.dist-info/entry_points.txt,sha256=ykGI1ArwOPHqm2g5Cqh3ENdMxEej_a_FcOUov5EM5Oc,155
+dycw_utilities-0.174.18.dist-info/METADATA,sha256=lsjOEHDTftfTew-cUGjw81uggqGrWLEXHVN3snWSV80,1710
+dycw_utilities-0.174.18.dist-info/RECORD,,

{dycw_utilities-0.174.16.dist-info → dycw_utilities-0.174.18.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.9.18
+Generator: uv 0.9.21
 Root-Is-Purelib: true
 Tag: py3-none-any

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.174.16"
+__version__ = "0.174.18"

utilities/docker.py

@@ -269,6 +269,7 @@ def yield_docker_temp_dir(
     logger: LoggerLike | None = None,
     keep: bool = False,
 ) -> Iterator[Path]:
+    """Yield a temporary directory in a Docker container."""
     path = Path(  # skipif-ci
         docker_exec(
             container,

utilities/subprocess.py

@@ -17,7 +17,8 @@ from typing import IO, TYPE_CHECKING, Literal, assert_never, overload, override
 from utilities.errors import ImpossibleCaseError
 from utilities.iterables import always_iterable
 from utilities.logging import to_logger
-from utilities.permissions import ensure_perms
+from utilities.permissions import Permissions, ensure_perms
+from utilities.tempfile import TemporaryDirectory
 from utilities.text import strip_and_dedent
 from utilities.whenever import to_seconds
 
@@ -220,6 +221,16 @@ def expand_path(
 ##
 
 
+def git_clone(
+    url: str, path: PathLike, /, *, sudo: bool = False, branch: str | None = None
+) -> None:
+    """Clone a repository."""
+    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)
+
+
 def git_clone_cmd(url: str, path: PathLike, /) -> list[str]:
     """Command to use 'git clone' to clone a repository."""
     return ["git", "clone", "--recurse-submodules", url, str(path)]
@@ -346,7 +357,7 @@ def rsync(
     chown_user: str | None = None,
     chown_group: str | None = None,
     exclude: MaybeIterable[str] | None = None,
-    chmod: str | None = None,
+    chmod: PermissionsLike | None = None,
 ) -> None:
     """Remote & local file copying."""
     mkdir_args = maybe_sudo_cmd(*mkdir_cmd(dest, parent=True), sudo=sudo)  # skipif-ci
@@ -361,13 +372,13 @@ def rsync(
         retry=retry,
         logger=logger,
     )
-    is_dir = any(Path(s).is_dir() for s in always_iterable(src_or_srcs))  # skipif-ci
+    srcs = list(always_iterable(src_or_srcs))  # skipif-ci
     rsync_args = rsync_cmd(  # skipif-ci
-        src_or_srcs,
+        srcs,
         user,
         hostname,
         dest,
-        archive=is_dir,
+        archive=any(Path(s).is_dir() for s in srcs),
         chown_user=chown_user,
         chown_group=chown_group,
         exclude=exclude,
@@ -375,7 +386,6 @@ def rsync(
         host_key_algorithms=host_key_algorithms,
         strict_host_key_checking=strict_host_key_checking,
         sudo=sudo,
-        parent=is_dir,
     )
     run(*rsync_args, print=print, retry=retry, logger=logger)  # skipif-ci
     if chmod is not None:  # skipif-ci
@@ -408,7 +418,6 @@ def rsync_cmd(
     host_key_algorithms: list[str] = _HOST_KEY_ALGORITHMS,
     strict_host_key_checking: bool = True,
     sudo: bool = False,
-    parent: bool = False,
 ) -> list[str]:
     """Command to use 'rsync' to do remote & local file copying."""
     args: list[str] = ["rsync"]
@@ -438,12 +447,141 @@ def rsync_cmd(
     args.extend(["--rsh", join(rsh_args)])
     if sudo:
         args.extend(["--rsync-path", join(sudo_cmd("rsync"))])
-    dest_use = maybe_parent(dest, parent=parent)
-    return [
-        *args,
-        *map(str, always_iterable(src_or_srcs)),
-        f"{user}@{hostname}:{dest_use}",
+    srcs = list(always_iterable(src_or_srcs))  # do not Path()
+    if len(srcs) == 0:
+        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(
+            sources=missing, user=user, hostname=hostname, dest=dest
+        )
+    return [*args, *map(str, srcs), f"{user}@{hostname}:{dest}"]
+
+
+@dataclass(kw_only=True, slots=True)
+class RsyncCmdError(Exception):
+    user: str
+    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):
+    @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):
+    sources: list[PathLike]
+
+    @override
+    def __str__(self) -> str:
+        desc = ", ".join(map(repr, map(str, self.sources)))
+        return f"Sources selected to send to {self.user}@{self.hostname}:{self.dest} but not found: {desc}"
+
+
+##
+
+
+def rsync_many(
+    user: str,
+    hostname: str,
+    /,
+    *items: tuple[PathLike, PathLike]
+    | tuple[Literal["sudo"], PathLike, PathLike]
+    | tuple[PathLike, PathLike, PermissionsLike],
+    retry: Retry | None = None,
+    logger: LoggerLike | None = None,
+    keep: bool = False,
+    batch_mode: bool = True,
+    host_key_algorithms: list[str] = _HOST_KEY_ALGORITHMS,
+    strict_host_key_checking: bool = True,
+    print: bool = False,  # noqa: A002
+) -> None:
+    cmds: list[list[str]] = []  # skipif-ci
+    with (  # skipif-ci
+        TemporaryDirectory() as temp_src,
+        yield_ssh_temp_dir(
+            user, hostname, retry=retry, logger=logger, keep=keep
+        ) as temp_dest,
+    ):
+        for item in items:
+            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:
+                    cmds.extend(
+                        _rsync_many_prepare(src, dest, temp_src, temp_dest, sudo=True)
+                    )
+                case (
+                    Path() | str() as src,
+                    Path() | str() as dest,
+                    Permissions() | int() | str() as perms,
+                ):
+                    cmds.extend(
+                        _rsync_many_prepare(src, dest, temp_src, temp_dest, perms=perms)
+                    )
+                case never:
+                    assert_never(never)
+        rsync(
+            f"{temp_src}/",
+            user,
+            hostname,
+            temp_dest,
+            batch_mode=batch_mode,
+            host_key_algorithms=host_key_algorithms,
+            strict_host_key_checking=strict_host_key_checking,
+            print=print,
+            retry=retry,
+            logger=logger,
+        )
+        ssh(
+            user,
+            hostname,
+            *BASH_LS,
+            input="\n".join(map(join, cmds)),
+            print=print,
+            retry=retry,
+            logger=logger,
+        )
+
+
+def _rsync_many_prepare(
+    src: PathLike,
+    dest: PathLike,
+    temp_src: PathLike,
+    temp_dest: PathLike,
+    /,
+    *,
+    sudo: bool = False,
+    perms: PermissionsLike | None = None,
+) -> list[list[str]]:
+    dest, temp_src, temp_dest = map(Path, [dest, temp_src, temp_dest])
+    n = len(list(temp_src.iterdir()))
+    name = str(n)
+    match src:
+        case Path():
+            cp(src, temp_src / name)
+        case str():
+            if Path(src).exists():
+                cp(src, temp_src / name)
+            else:
+                tee(temp_src / name, src)
+        case never:
+            assert_never(never)
+    cmds: list[list[str]] = [
+        maybe_sudo_cmd(*mkdir_cmd(dest, parent=True), sudo=sudo),
+        maybe_sudo_cmd(*cp_cmd(temp_dest / name, dest), sudo=sudo),
     ]
+    if perms is not None:
+        cmds.append(maybe_sudo_cmd(*chmod_cmd(dest, perms), sudo=sudo))
+    return cmds
 
 
 ##
@@ -961,14 +1099,26 @@ def tee_cmd(path: PathLike, /, *, append: bool = False) -> list[str]:
 ##
 
 
+def touch(path: PathLike, /, *, sudo: bool = False) -> None:
+    """Change file access and modification times."""
+    run(*maybe_sudo_cmd(*touch_cmd(path), sudo=sudo))
+
+
 def touch_cmd(path: PathLike, /) -> list[str]:
+    """Command to use 'touch' to change file access and modification times."""
     return ["touch", str(path)]
 
 
 ##
 
 
+def uv_run(module: str, /, *args: str) -> None:
+    """Run a command or script."""
+    run(*uv_run_cmd(module, *args))  # pragma: no cover
+
+
 def uv_run_cmd(module: str, /, *args: str) -> list[str]:
+    """Command to use 'uv' to run a command or script."""
     return [
         "uv",
         "run",
@@ -986,6 +1136,17 @@ def uv_run_cmd(module: str, /, *args: str) -> list[str]:
 ##
 
 
+@contextmanager
+def yield_git_repo(url: str, /, *, branch: str | None = None) -> Iterator[Path]:
+    """Yield a temporary git repository."""
+    with TemporaryDirectory() as temp_dir:
+        git_clone(url, temp_dir, branch=branch)
+        yield temp_dir
+
+
+##
+
+
 @contextmanager
 def yield_ssh_temp_dir(
     user: str,
@@ -996,6 +1157,7 @@ def yield_ssh_temp_dir(
     logger: LoggerLike | None = None,
     keep: bool = False,
 ) -> Iterator[Path]:
+    """Yield a temporary directory on a remote machine."""
     path = Path(  # skipif-ci
         ssh(user, hostname, *MKTEMP_DIR_CMD, return_=True, retry=retry, logger=logger)
     )
@@ -1019,6 +1181,9 @@ __all__ = [
     "ChownCmdError",
     "CpError",
     "MvFileError",
+    "RsyncCmdError",
+    "RsyncCmdNoSourcesError",
+    "RsyncCmdSourcesNotFoundError",
     "apt_install_cmd",
     "cd_cmd",
     "chmod",
@@ -1029,6 +1194,7 @@ __all__ = [
     "cp_cmd",
     "echo_cmd",
     "expand_path",
+    "git_clone",
     "git_clone_cmd",
     "git_hard_reset_cmd",
     "maybe_parent",
@@ -1041,6 +1207,7 @@ __all__ = [
     "rm_cmd",
     "rsync",
     "rsync_cmd",
+    "rsync_many",
     "run",
     "set_hostname_cmd",
     "ssh",
@@ -1051,7 +1218,10 @@ __all__ = [
     "symlink",
     "symlink_cmd",
     "tee_cmd",
+    "touch",
     "touch_cmd",
+    "uv_run",
     "uv_run_cmd",
+    "yield_git_repo",
     "yield_ssh_temp_dir",
 ]