dycw-utilities 0.174.12__py3-none-any.whl → 0.174.14__py3-none-any.whl

{dycw_utilities-0.174.12.dist-info → dycw_utilities-0.174.14.dist-info}/METADATA

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

{dycw_utilities-0.174.12.dist-info → dycw_utilities-0.174.14.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=VFU3kmpNxjyAnXuMdW-ygHCxl3CNmUA0rP-wy1y_uzg,61
+utilities/__init__.py,sha256=wElh7rM2Gp4Qe3xG2KlBo0z_G6fFiYwVzZ10q9vTQac,61
 utilities/aeventkit.py,sha256=OmDBhYGgbsKrB7cdC5FFpJHUatX9O76eTeKVVTksp2Y,12673
 utilities/altair.py,sha256=rUK99g9x6CYDDfiZrf-aTx5fSRbL1Q8ctgKORowzXHg,9060
 utilities/asyncio.py,sha256=aJySVxBY0gqsIYnoNmH7-1r8djKuf4vSsU69VCD08t8,16772
@@ -47,7 +47,7 @@ utilities/orjson.py,sha256=T_0SlK811ysg46d3orvIPY3JpBa4FRMpP2wlPQo7-gU,41854
 utilities/os.py,sha256=kjKKSQfnRqFTTZ315iavaaGd3gGuYNoSWlxVLCJjyQs,4852
 utilities/parse.py,sha256=g7Qm9eBOIeDId2tGA021CIaeF6jp1TI8rx4srdvlyoo,17937
 utilities/pathlib.py,sha256=EKZn-wWxH7MEWFrQGqHIoB-GJzyXeiEj8iDIgvkr8Wk,9325
-utilities/permissions.py,sha256=u-1PMJGC8PDbZltR4SozBuKKX5yIubmXPuiKrBx3IKU,8943
+utilities/permissions.py,sha256=vLXlWztSVYffbrxptne7ksj6dU1HLekm4fEvS4ny_4Q,8944
 utilities/pickle.py,sha256=MBT2xZCsv0pH868IXLGKnlcqNx2IRVKYNpRcqiQQqxw,653
 utilities/platform.py,sha256=0pYO5v7L2sU5UN87zHhEEhTKsZ9NIEM8N6UCr0F7bLY,2778
 utilities/polars.py,sha256=cNFBLWgOMUAp_Sz4xtlto17uZswZRrcfQYC95QKyaY4,87483
@@ -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=dIBguvLB0WepJKqgBxlzF6r8z9HW5JiGKLg-eslpuec,22549
+utilities/subprocess.py,sha256=tYfdY7CdVc91rs9AZ-KSwLvKyNNoPunDOWLgCtwuTvs,28490
 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.12.dist-info/WHEEL,sha256=ZyFSCYkV2BrxH6-HRVRg3R9Fo7MALzer9KiPYqNxSbo,79
-dycw_utilities-0.174.12.dist-info/entry_points.txt,sha256=ykGI1ArwOPHqm2g5Cqh3ENdMxEej_a_FcOUov5EM5Oc,155
-dycw_utilities-0.174.12.dist-info/METADATA,sha256=Cf8kQqLOY8YDH8nG9Y7WcGf6xJFGxfDIMC1Amw13isc,1710
-dycw_utilities-0.174.12.dist-info/RECORD,,
+dycw_utilities-0.174.14.dist-info/WHEEL,sha256=ZyFSCYkV2BrxH6-HRVRg3R9Fo7MALzer9KiPYqNxSbo,79
+dycw_utilities-0.174.14.dist-info/entry_points.txt,sha256=ykGI1ArwOPHqm2g5Cqh3ENdMxEej_a_FcOUov5EM5Oc,155
+dycw_utilities-0.174.14.dist-info/METADATA,sha256=nHCDEWfo7tFV9RLiNWEE9IqfJAvwPWvuv6rn07LnXpw,1710
+dycw_utilities-0.174.14.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.174.12"
+__version__ = "0.174.14"

utilities/permissions.py

@@ -25,6 +25,7 @@ from utilities.sentinel import Sentinel, sentinel
 if TYPE_CHECKING:
     from utilities.types import PathLike
 
+
 type PermissionsLike = Permissions | int | str
 
 

utilities/subprocess.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
+import shutil
 import sys
 from contextlib import contextmanager
 from dataclasses import dataclass
 from io import StringIO
 from pathlib import Path
 from shlex import join
+from shutil import copyfile, copytree, move, rmtree
 from string import Template
 from subprocess import PIPE, CalledProcessError, Popen
 from threading import Thread
@@ -15,12 +17,14 @@ 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.text import strip_and_dedent
 from utilities.whenever import to_seconds
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
 
+    from utilities.permissions import PermissionsLike
     from utilities.types import (
         LoggerLike,
         MaybeIterable,
@@ -44,6 +48,7 @@ UPDATE_CA_CERTIFICATES: str = "update-ca-certificates"
 
 
 def apt_install_cmd(package: str, /) -> list[str]:
+    """Command to use 'apt' to install a package."""
     return ["apt", "install", "-y", package]
 
 
@@ -51,6 +56,7 @@ def apt_install_cmd(package: str, /) -> list[str]:
 
 
 def cat_cmd(path: PathLike, /) -> list[str]:
+    """Command to use 'cat' to concatenate and print files."""
     return ["cat", str(path)]
 
 
@@ -58,30 +64,78 @@ def cat_cmd(path: PathLike, /) -> list[str]:
 
 
 def cd_cmd(path: PathLike, /) -> list[str]:
+    """Command to use 'cd' to change working directory."""
     return ["cd", str(path)]
 
 
 ##
 
 
-def chmod_cmd(path: PathLike, mode: str, /) -> list[str]:
-    return ["chmod", mode, 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)))
+
+
+##
+
+
+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)]
+
+
+##
+
+
+def chown(
+    path: PathLike,
+    /,
+    *,
+    sudo: 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)
 
 
 ##
 
 
 def chown_cmd(
-    path: PathLike, /, *, user: str | None = None, group: str | None = None
+    path: PathLike, /, *, user: str | int | None = None, group: str | int | None = None
 ) -> list[str]:
+    """Command to use 'chown' to change file owner and/or group."""
     match user, group:
         case None, None:
             raise ChownCmdError
-        case str(), None:
+        case str() | int(), None:
             ownership = "user"
-        case None, str():
+        case None, str() | int():
             ownership = f":{group}"
-        case str(), str():
+        case str() | int(), str() | int():
             ownership = f"{user}:{group}"
         case never:
             assert_never(never)
@@ -98,7 +152,46 @@ class ChownCmdError(Exception):
 ##
 
 
+def cp(
+    src: PathLike,
+    dest: PathLike,
+    /,
+    *,
+    sudo: bool = False,
+    perms: PermissionsLike | None = None,
+    owner: str | int | None = None,
+    group: str | int | None = None,
+) -> None:
+    """Copy a file/directory."""
+    mkdir(dest, sudo=sudo, parent=True)
+    if sudo:
+        run(*sudo_cmd(*cp_cmd(src, dest)))
+    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)
+
+
+@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"
+
+
 def cp_cmd(src: PathLike, dest: PathLike, /) -> list[str]:
+    """Command to use 'cp' to copy a file/directory."""
     return ["cp", "-r", str(src), str(dest)]
 
 
@@ -106,6 +199,7 @@ def cp_cmd(src: PathLike, dest: PathLike, /) -> list[str]:
 
 
 def echo_cmd(text: str, /) -> list[str]:
+    """Command to use 'echo' to write arguments to the standard output."""
     return ["echo", text]
 
 
@@ -115,6 +209,7 @@ def echo_cmd(text: str, /) -> list[str]:
 def expand_path(
     path: PathLike, /, *, subs: StrMapping | None = None, sudo: bool = False
 ) -> Path:
+    """Expand a path using `subprocess`."""
     if subs is not None:
         path = Template(str(path)).substitute(**subs)
     if sudo:  # pragma: no cover
@@ -126,6 +221,7 @@ def expand_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)]
 
 
@@ -133,6 +229,7 @@ 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]
 
@@ -141,6 +238,7 @@ def git_hard_reset_cmd(*, branch: str | None = None) -> list[str]:
 
 
 def maybe_parent(path: PathLike, /, *, parent: bool = False) -> Path:
+    """Get the parent of a path, if required."""
     path = Path(path)
     return path.parent if parent else path
 
@@ -148,15 +246,8 @@ def maybe_parent(path: PathLike, /, *, parent: bool = False) -> Path:
 ##
 
 
-def maybe_sudo_cmd(cmd: str, /, *args: str, sudo: bool = False) -> list[str]:
-    parts: list[str] = [cmd, *args]
-    return sudo_cmd(*parts) if sudo else parts
-
-
-##
-
-
 def mkdir(path: PathLike, /, *, sudo: bool = False, parent: bool = False) -> None:
+    """Make a directory."""
     if sudo:  # pragma: no cover
         run(*sudo_cmd(*mkdir_cmd(path, parent=parent)))
     else:
@@ -167,20 +258,71 @@ def mkdir(path: PathLike, /, *, sudo: bool = False, parent: bool = False) -> Non
 
 
 def mkdir_cmd(path: PathLike, /, *, parent: bool = False) -> list[str]:
+    """Command to use 'mv' to make a directory."""
     return ["mkdir", "-p", str(maybe_parent(path, parent=parent))]
 
 
 ##
 
 
+def mv(
+    src: PathLike,
+    dest: PathLike,
+    /,
+    *,
+    sudo: bool = False,
+    perms: PermissionsLike | None = None,
+    owner: str | int | None = None,
+    group: str | int | None = None,
+) -> None:
+    """Move a file/directory."""
+    mkdir(dest, sudo=sudo, parent=True)
+    if sudo:
+        run(*sudo_cmd(*cp_cmd(src, dest)))
+    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)
+
+
+@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"
+
+
 def mv_cmd(src: PathLike, dest: PathLike, /) -> list[str]:
+    """Command to use 'mv' to move a file/directory."""
     return ["mv", str(src), str(dest)]
 
 
 ##
 
 
+def rm(path: PathLike, /, *, sudo: bool = False) -> None:
+    """Remove a file/directory."""
+    if sudo:  # pragma: no cover
+        run(*sudo_cmd(*rm_cmd(path)))
+    else:
+        path = Path(path)
+        if path.is_file():
+            path.unlink(missing_ok=True)
+        elif path.is_dir():
+            rmtree(path, ignore_errors=True)
+
+
 def rm_cmd(path: PathLike, /) -> list[str]:
+    """Command to use 'rm' to remove a file/directory."""
     return ["rm", "-rf", str(path)]
 
 
@@ -206,6 +348,7 @@ def rsync(
     exclude: MaybeIterable[str] | None = None,
     chmod: str | None = None,
 ) -> None:
+    """Remote & local file copying."""
     mkdir_args = maybe_sudo_cmd(*mkdir_cmd(dest, parent=True), sudo=sudo)  # skipif-ci
     ssh(  # skipif-ci
         user,
@@ -250,9 +393,6 @@ def rsync(
         )
 
 
-##
-
-
 def rsync_cmd(
     src_or_srcs: MaybeIterable[PathLike],
     user: str,
@@ -270,6 +410,7 @@ def rsync_cmd(
     sudo: bool = False,
     parent: bool = False,
 ) -> list[str]:
+    """Command to use 'rsync' to do remote & local file copying."""
     args: list[str] = ["rsync"]
     if archive:
         args.append("--archive")
@@ -427,6 +568,7 @@ def run(
     retry: Retry | None = None,
     logger: LoggerLike | None = None,
 ) -> str | None:
+    """Run a command in a subprocess."""
     args: list[str] = []
     if user is not None:  # pragma: no cover
         args.extend(["su", "-", str(user)])
@@ -567,6 +709,7 @@ def _run_write_to_streams(text: str, /, *outputs: IO[str]) -> None:
 
 
 def set_hostname_cmd(hostname: str, /) -> list[str]:
+    """Command to set the system hostname."""
     return ["hostnamectl", "set-hostname", hostname]
 
 
@@ -686,6 +829,7 @@ def ssh(
     retry: Retry | None = None,
     logger: LoggerLike | None = None,
 ) -> str | None:
+    """Execute a command on a remote machine."""
     cmd_and_args = ssh_cmd(  # skipif-ci
         user,
         hostname,
@@ -708,9 +852,6 @@ def ssh(
     )
 
 
-##
-
-
 def ssh_cmd(
     user: str,
     hostname: str,
@@ -720,6 +861,7 @@ def ssh_cmd(
     host_key_algorithms: list[str] = _HOST_KEY_ALGORITHMS,
     strict_host_key_checking: bool = True,
 ) -> 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,
@@ -728,15 +870,13 @@ def ssh_cmd(
     return [*args, f"{user}@{hostname}", *cmd_and_cmds_or_args]
 
 
-##
-
-
 def ssh_opts_cmd(
     *,
     batch_mode: bool = True,
     host_key_algorithms: list[str] = _HOST_KEY_ALGORITHMS,
     strict_host_key_checking: bool = True,
 ) -> list[str]:
+    """Command to use prepare 'ssh' to execute a command on a remote machine."""
     args: list[str] = ["ssh"]
     if batch_mode:
         args.extend(["-o", "BatchMode=yes"])
@@ -750,6 +890,7 @@ def ssh_opts_cmd(
 
 
 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]
 
 
@@ -757,21 +898,52 @@ def ssh_keygen_cmd(hostname: str, /) -> list[str]:
 
 
 def sudo_cmd(cmd: str, /, *args: str) -> list[str]:
+    """Command to use 'sudo' to execute a command as another user."""
     return ["sudo", cmd, *args]
 
 
+def maybe_sudo_cmd(cmd: str, /, *args: str, sudo: bool = False) -> list[str]:
+    """Command to use 'sudo' to execute a command as another user, if required."""
+    parts: list[str] = [cmd, *args]
+    return sudo_cmd(*parts) if sudo else parts
+
+
 ##
 
 
 def sudo_nopasswd_cmd(user: str, /) -> str:
+    """Command to allow a user to use password-free `sudo`."""
     return f"{user} ALL=(ALL) NOPASSWD: ALL"
 
 
 ##
 
 
-def symlink_cmd(src: PathLike, dest: PathLike, /) -> list[str]:
-    return ["ln", "-s", str(src), str(dest)]
+def symlink(targret: PathLike, link: PathLike, /, *, sudo: bool = False) -> None:
+    """Make a symbolic link."""
+    rm(link, sudo=sudo)
+    mkdir(link, sudo=sudo, parent=True)
+    if sudo:  # pragma: no cover
+        run(*sudo_cmd(*symlink_cmd(targret, link)))
+    else:
+        targret, link = map(Path, [targret, link])
+        link.symlink_to(targret)
+
+
+def symlink_cmd(target: PathLike, link: PathLike, /) -> list[str]:
+    """Command to use 'symlink' to make a symbolic link."""
+    return ["ln", "-s", str(target), str(link)]
+
+
+##
+
+
+def tee_cmd(*, append: bool = False) -> list[str]:
+    """Command to use 'tee' to duplicate standard input."""
+    args: list[str] = ["tee"]
+    if append:
+        args.append("-a")
+    return args
 
 
 ##
@@ -833,10 +1005,15 @@ __all__ = [
     "RESTART_SSHD",
     "UPDATE_CA_CERTIFICATES",
     "ChownCmdError",
+    "CpError",
+    "MvFileError",
     "apt_install_cmd",
     "cd_cmd",
+    "chmod",
     "chmod_cmd",
+    "chown",
     "chown_cmd",
+    "cp",
     "cp_cmd",
     "echo_cmd",
     "expand_path",
@@ -846,7 +1023,9 @@ __all__ = [
     "maybe_sudo_cmd",
     "mkdir",
     "mkdir_cmd",
+    "mv",
     "mv_cmd",
+    "rm",
     "rm_cmd",
     "rsync",
     "rsync_cmd",
@@ -857,7 +1036,9 @@ __all__ = [
     "ssh_opts_cmd",
     "sudo_cmd",
     "sudo_nopasswd_cmd",
+    "symlink",
     "symlink_cmd",
+    "tee_cmd",
     "touch_cmd",
     "uv_run_cmd",
     "yield_ssh_temp_dir",