dycw-utilities 0.174.11__py3-none-any.whl → 0.174.13__py3-none-any.whl

{dycw_utilities-0.174.11.dist-info → dycw_utilities-0.174.13.dist-info}/METADATA

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

{dycw_utilities-0.174.11.dist-info → dycw_utilities-0.174.13.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=Ed7ve87kqMRppt7gnxtu2swOV8yOK_hwjAE5eRBPgKg,61
+utilities/__init__.py,sha256=MOUKZkLpGGyjxpjT7E-ok6qU-Ad2cKOMOyAdEHZoEGc,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=xw3mDS5UT3SO5_AZ0RXYMQi1hU-3LedAWHdHEsOAHu0,8697
+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=2FvELtLUkr8H2rMRMRr5Ah5LA-p3pZy9PjMeA_ZTw_U,26362
 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.11.dist-info/WHEEL,sha256=ZyFSCYkV2BrxH6-HRVRg3R9Fo7MALzer9KiPYqNxSbo,79
-dycw_utilities-0.174.11.dist-info/entry_points.txt,sha256=ykGI1ArwOPHqm2g5Cqh3ENdMxEej_a_FcOUov5EM5Oc,155
-dycw_utilities-0.174.11.dist-info/METADATA,sha256=tBWZRVdVIvaeaLE3LYeGlWuwUcbt9ZOm0kunrxZj42Y,1710
-dycw_utilities-0.174.11.dist-info/RECORD,,
+dycw_utilities-0.174.13.dist-info/WHEEL,sha256=ZyFSCYkV2BrxH6-HRVRg3R9Fo7MALzer9KiPYqNxSbo,79
+dycw_utilities-0.174.13.dist-info/entry_points.txt,sha256=ykGI1ArwOPHqm2g5Cqh3ENdMxEej_a_FcOUov5EM5Oc,155
+dycw_utilities-0.174.13.dist-info/METADATA,sha256=BuUPpTMsSoLgdvmXiA-oOD_jsg6LYqlWsW_EFvJSTlM,1710
+dycw_utilities-0.174.13.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.174.11"
+__version__ = "0.174.13"

utilities/permissions.py

@@ -3,7 +3,9 @@ from __future__ import annotations
 from dataclasses import dataclass
 from functools import reduce
 from operator import or_
+from pathlib import Path
 from stat import (
+    S_IMODE,
     S_IRGRP,
     S_IROTH,
     S_IRUSR,
@@ -14,12 +16,16 @@ from stat import (
     S_IXOTH,
     S_IXUSR,
 )
-from typing import Literal, Self, assert_never, override
+from typing import TYPE_CHECKING, Literal, Self, assert_never, override
 
 from utilities.dataclasses import replace_non_sentinel
 from utilities.re import ExtractGroupsError, extract_groups
 from utilities.sentinel import Sentinel, sentinel
 
+if TYPE_CHECKING:
+    from utilities.types import PathLike
+
+
 type PermissionsLike = Permissions | int | str
 
 
@@ -154,6 +160,10 @@ class Permissions:
             )
         raise PermissionsFromIntError(n=n)
 
+    @classmethod
+    def from_path(cls, path: PathLike, /) -> Self:
+        return cls.from_int(S_IMODE(Path(path).stat().st_mode))
+
     @classmethod
     def from_text(cls, text: str, /) -> Self:
         try:

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,
@@ -64,24 +68,67 @@ def cd_cmd(path: PathLike, /) -> list[str]:
 ##
 
 
-def chmod_cmd(path: PathLike, mode: str, /) -> list[str]:
-    return ["chmod", mode, str(path)]
+def chmod(path: PathLike, perms: PermissionsLike, /, *, sudo: bool = False) -> None:
+    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]:
+    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:
+    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]:
     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,6 +145,47 @@ class ChownCmdError(Exception):
 ##
 
 
+def copy_file(
+    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 from one location to another."""
+    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 CopyFileError(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 CopyFileError(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]:
     return ["cp", "-r", str(src), str(dest)]
 
@@ -173,6 +261,45 @@ def mkdir_cmd(path: PathLike, /, *, parent: bool = False) -> list[str]:
 ##
 
 
+def move_file(
+    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 from one location to another."""
+    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 MoveFileError(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 MoveFileError(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]:
     return ["mv", str(src), str(dest)]
 
@@ -180,6 +307,20 @@ def mv_cmd(src: PathLike, dest: PathLike, /) -> list[str]:
 ##
 
 
+def remove(path: PathLike, /, *, sudo: bool = False) -> None:
+    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]:
     return ["rm", "-rf", str(path)]
 
@@ -833,10 +974,15 @@ __all__ = [
     "RESTART_SSHD",
     "UPDATE_CA_CERTIFICATES",
     "ChownCmdError",
+    "CopyFileError",
+    "MoveFileError",
     "apt_install_cmd",
     "cd_cmd",
+    "chmod",
     "chmod_cmd",
+    "chown",
     "chown_cmd",
+    "copy_file",
     "cp_cmd",
     "echo_cmd",
     "expand_path",
@@ -846,7 +992,9 @@ __all__ = [
     "maybe_sudo_cmd",
     "mkdir",
     "mkdir_cmd",
+    "move_file",
     "mv_cmd",
+    "remove",
     "rm_cmd",
     "rsync",
     "rsync_cmd",