dycw-utilities 0.174.11__tar.gz → 0.174.13__tar.gz

{dycw_utilities-0.174.11 → dycw_utilities-0.174.13}/PKG-INFO

@@ -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 → dycw_utilities-0.174.13}/pyproject.toml

@@ -101,7 +101,7 @@
   name = "dycw-utilities"
   readme = "README.md"
   requires-python = ">= 3.12"
-  version = "0.174.11"
+  version = "0.174.13"
 
   [project.entry-points.pytest11]
     pytest-randomly = "utilities.pytest_plugins.pytest_randomly"
@@ -135,7 +135,7 @@
   # bump-my-version
   [tool.bumpversion]
     allow_dirty = true
-    current_version = "0.174.11"
+    current_version = "0.174.13"
 
     [[tool.bumpversion.files]]
       filename = "src/utilities/__init__.py"

{dycw_utilities-0.174.11 → dycw_utilities-0.174.13}/src/utilities/__init__.py

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

{dycw_utilities-0.174.11 → dycw_utilities-0.174.13}/src/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:

{dycw_utilities-0.174.11 → dycw_utilities-0.174.13}/src/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",