dycw-utilities 0.146.2__py3-none-any.whl → 0.178.1__py3-none-any.whl

utilities/pathlib.py

@@ -12,7 +12,9 @@ from typing import TYPE_CHECKING, Literal, assert_never, overload, override
 
 from utilities.contextlib import enhanced_context_manager
 from utilities.errors import ImpossibleCaseError
-from utilities.sentinel import Sentinel, sentinel
+from utilities.grp import get_gid_name
+from utilities.pwd import get_uid_name
+from utilities.sentinel import Sentinel
 
 if TYPE_CHECKING:
     from collections.abc import Iterator, Sequence
@@ -52,33 +54,22 @@ def expand_path(path: PathLike, /) -> Path:
 ##
 
 
-@overload
-def get_path(*, path: MaybeCallablePathLike | None) -> Path: ...
-@overload
-def get_path(*, path: Sentinel) -> Sentinel: ...
-def get_path(
-    *, path: MaybeCallablePathLike | None | Sentinel = sentinel
-) -> Path | None | Sentinel:
-    """Get the path."""
-    match path:
-        case Path() | Sentinel():
-            return path
-        case str():
-            return Path(path)
-        case None:
-            return Path.cwd()
-        case Callable() as func:
-            return get_path(path=func())
-        case _ as never:
-            assert_never(never)
+def get_file_group(path: PathLike, /) -> str | None:
+    """Get the group of a file."""
+    return get_gid_name(to_path(path).stat().st_gid)
+
+
+def get_file_owner(path: PathLike, /) -> str | None:
+    """Get the owner of a file."""
+    return get_uid_name(to_path(path).stat().st_uid)
 
 
 ##
 
 
-def get_package_root(*, path: MaybeCallablePathLike | None = None) -> Path:
+def get_package_root(path: MaybeCallablePathLike = Path.cwd, /) -> Path:
     """Get the package root."""
-    path = get_path(path=path)
+    path = to_path(path)
     path_dir = path.parent if path.is_file() else path
     all_paths = list(chain([path_dir], path_dir.parents))
     try:
@@ -103,9 +94,9 @@ class GetPackageRootError(Exception):
 ##
 
 
-def get_repo_root(*, path: MaybeCallablePathLike | None = None) -> Path:
+def get_repo_root(path: MaybeCallablePathLike = Path.cwd, /) -> Path:
     """Get the repo root."""
-    path = get_path(path=path)
+    path = to_path(path)
     path_dir = path.parent if path.is_file() else path
     try:
         output = check_output(
@@ -118,15 +109,30 @@ def get_repo_root(*, path: MaybeCallablePathLike | None = None) -> Path:
         # newer versions of git report "Not a git repository", whilst older
         # versions report "not a git repository"
         if search("fatal: not a git repository", error.stderr, flags=IGNORECASE):
-            raise GetRepoRootError(path=path) from None
+            raise _GetRepoRootNotARepoError(path=path) from None
         raise  # pragma: no cover
+    except FileNotFoundError as error:  # pragma: no cover
+        if search("No such file or directory: 'git'", str(error), flags=IGNORECASE):
+            raise _GetRepoRootGitNotFoundError from None
+        raise
     else:
         return Path(output.strip("\n"))
 
 
 @dataclass(kw_only=True, slots=True)
-class GetRepoRootError(Exception):
-    path: PathLike
+class GetRepoRootError(Exception): ...
+
+
+@dataclass(kw_only=True, slots=True)
+class _GetRepoRootGitNotFoundError(GetRepoRootError):
+    @override
+    def __str__(self) -> str:
+        return "'git' not found"  # pragma: no cover
+
+
+@dataclass(kw_only=True, slots=True)
+class _GetRepoRootNotARepoError(GetRepoRootError):
+    path: Path
 
     @override
     def __str__(self) -> str:
@@ -136,15 +142,15 @@ class GetRepoRootError(Exception):
 ##
 
 
-def get_root(*, path: MaybeCallablePathLike | None = None) -> Path:
+def get_root(path: MaybeCallablePathLike = Path.cwd, /) -> Path:
     """Get the root of a path."""
-    path = get_path(path=path)
+    path = to_path(path)
     try:
-        repo = get_repo_root(path=path)
+        repo = get_repo_root(path)
     except GetRepoRootError:
         repo = None
     try:
-        package = get_package_root(path=path)
+        package = get_package_root(path)
     except GetPackageRootError:
         package = None
     match repo, package:
@@ -164,7 +170,7 @@ def get_root(*, path: MaybeCallablePathLike | None = None) -> Path:
             raise ImpossibleCaseError(  # pragma: no cover
                 case=[f"{repo=}", f"{package=}"]
             )
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -213,7 +219,7 @@ def get_tail(
             return _get_tail_core(path, next(iter(matches)))
         case _, "later":
             return _get_tail_core(path, next(iter(reversed(matches))))
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -305,6 +311,30 @@ def temp_cwd(path: PathLike, /) -> Iterator[None]:
         chdir(prev)
 
 
+##
+
+
+@overload
+def to_path(path: Sentinel, /) -> Sentinel: ...
+@overload
+def to_path(path: MaybeCallablePathLike | None = Path.cwd, /) -> Path: ...
+def to_path(
+    path: MaybeCallablePathLike | None | Sentinel = Path.cwd, /
+) -> Path | Sentinel:
+    """Get the path."""
+    match path:
+        case Path() | Sentinel():
+            return path
+        case None:
+            return Path.cwd()
+        case str():
+            return Path(path)
+        case Callable() as func:
+            return to_path(func())
+        case never:
+            assert_never(never)
+
+
 __all__ = [
     "PWD",
     "GetPackageRootError",
@@ -312,12 +342,14 @@ __all__ = [
     "GetTailError",
     "ensure_suffix",
     "expand_path",
+    "get_file_group",
+    "get_file_owner",
     "get_package_root",
-    "get_path",
     "get_repo_root",
     "get_tail",
     "is_sub_path",
     "list_dir",
     "module_path",
     "temp_cwd",
+    "to_path",
 ]

utilities/permissions.py

@@ -0,0 +1,298 @@
+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,
+    S_IWGRP,
+    S_IWOTH,
+    S_IWUSR,
+    S_IXGRP,
+    S_IXOTH,
+    S_IXUSR,
+)
+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
+
+
+##
+
+
+def ensure_perms(perms: PermissionsLike, /) -> Permissions:
+    """Ensure a set of file permissions."""
+    match perms:
+        case Permissions():
+            return perms
+        case int():
+            return Permissions.from_int(perms)
+        case str():
+            return Permissions.from_text(perms)
+        case never:
+            assert_never(never)
+
+
+##
+
+
+@dataclass(order=True, unsafe_hash=True, kw_only=True, slots=True)
+class Permissions:
+    """A set of file permissions."""
+
+    user_read: bool = False
+    user_write: bool = False
+    user_execute: bool = False
+    group_read: bool = False
+    group_write: bool = False
+    group_execute: bool = False
+    others_read: bool = False
+    others_write: bool = False
+    others_execute: bool = False
+
+    def __int__(self) -> int:
+        flags: list[int] = [
+            S_IRUSR if self.user_read else 0,
+            S_IWUSR if self.user_write else 0,
+            S_IXUSR if self.user_execute else 0,
+            S_IRGRP if self.group_read else 0,
+            S_IWGRP if self.group_write else 0,
+            S_IXGRP if self.group_execute else 0,
+            S_IROTH if self.others_read else 0,
+            S_IWOTH if self.others_write else 0,
+            S_IXOTH if self.others_execute else 0,
+        ]
+        return reduce(or_, flags)
+
+    @override
+    def __repr__(self) -> str:
+        return ",".join([
+            self._repr_parts(
+                "u",
+                read=self.user_read,
+                write=self.user_write,
+                execute=self.user_execute,
+            ),
+            self._repr_parts(
+                "g",
+                read=self.group_read,
+                write=self.group_write,
+                execute=self.group_execute,
+            ),
+            self._repr_parts(
+                "o",
+                read=self.others_read,
+                write=self.others_write,
+                execute=self.others_execute,
+            ),
+        ])
+
+    def _repr_parts(
+        self,
+        prefix: Literal["u", "g", "o"],
+        /,
+        *,
+        read: bool = False,
+        write: bool = False,
+        execute: bool = False,
+    ) -> str:
+        parts: list[str] = [
+            "r" if read else "",
+            "w" if write else "",
+            "x" if execute else "",
+        ]
+        return f"{prefix}={''.join(parts)}"
+
+    @override
+    def __str__(self) -> str:
+        return repr(self)
+
+    @classmethod
+    def from_human_int(cls, n: int, /) -> Self:
+        if not (0 <= n <= 777):
+            raise PermissionsFromHumanIntRangeError(n=n)
+        user_read, user_write, user_execute = cls._from_human_int(n, (n // 100) % 10)
+        group_read, group_write, group_execute = cls._from_human_int(n, (n // 10) % 10)
+        others_read, others_write, others_execute = cls._from_human_int(n, n % 10)
+        return cls(
+            user_read=user_read,
+            user_write=user_write,
+            user_execute=user_execute,
+            group_read=group_read,
+            group_write=group_write,
+            group_execute=group_execute,
+            others_read=others_read,
+            others_write=others_write,
+            others_execute=others_execute,
+        )
+
+    @classmethod
+    def _from_human_int(cls, n: int, digit: int, /) -> tuple[bool, bool, bool]:
+        if not (0 <= digit <= 7):
+            raise PermissionsFromHumanIntDigitError(n=n, digit=digit)
+        return bool(4 & digit), bool(2 & digit), bool(1 & digit)
+
+    @classmethod
+    def from_int(cls, n: int, /) -> Self:
+        if 0o0 <= n <= 0o777:
+            return cls(
+                user_read=bool(n & S_IRUSR),
+                user_write=bool(n & S_IWUSR),
+                user_execute=bool(n & S_IXUSR),
+                group_read=bool(n & S_IRGRP),
+                group_write=bool(n & S_IWGRP),
+                group_execute=bool(n & S_IXGRP),
+                others_read=bool(n & S_IROTH),
+                others_write=bool(n & S_IWOTH),
+                others_execute=bool(n & S_IXOTH),
+            )
+        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:
+            user, group, others = extract_groups(
+                r"^u=(r?w?x?),g=(r?w?x?),o=(r?w?x?)$", text
+            )
+        except ExtractGroupsError:
+            raise PermissionsFromTextError(text=text) from None
+        user_read, user_write, user_execute = cls._from_text_part(user)
+        group_read, group_write, group_execute = cls._from_text_part(group)
+        others_read, others_write, others_execute = cls._from_text_part(others)
+        return cls(
+            user_read=user_read,
+            user_write=user_write,
+            user_execute=user_execute,
+            group_read=group_read,
+            group_write=group_write,
+            group_execute=group_execute,
+            others_read=others_read,
+            others_write=others_write,
+            others_execute=others_execute,
+        )
+
+    @classmethod
+    def _from_text_part(cls, text: str, /) -> tuple[bool, bool, bool]:
+        read, write, execute = extract_groups("^(r?)(w?)(x?)$", text)
+        return read != "", write != "", execute != ""
+
+    @property
+    def human_int(self) -> int:
+        return (
+            100
+            * self._human_int(
+                read=self.user_read, write=self.user_write, execute=self.user_execute
+            )
+            + 10
+            * self._human_int(
+                read=self.group_read, write=self.group_write, execute=self.group_execute
+            )
+            + self._human_int(
+                read=self.others_read,
+                write=self.others_write,
+                execute=self.others_execute,
+            )
+        )
+
+    def _human_int(
+        self, *, read: bool = False, write: bool = False, execute: bool = False
+    ) -> int:
+        return (4 if read else 0) + (2 if write else 0) + (1 if execute else 0)
+
+    def replace(
+        self,
+        *,
+        user_read: bool | Sentinel = sentinel,
+        user_write: bool | Sentinel = sentinel,
+        user_execute: bool | Sentinel = sentinel,
+        group_read: bool | Sentinel = sentinel,
+        group_write: bool | Sentinel = sentinel,
+        group_execute: bool | Sentinel = sentinel,
+        others_read: bool | Sentinel = sentinel,
+        others_write: bool | Sentinel = sentinel,
+        others_execute: bool | Sentinel = sentinel,
+    ) -> Self:
+        return replace_non_sentinel(
+            self,
+            user_read=user_read,
+            user_write=user_write,
+            user_execute=user_execute,
+            group_read=group_read,
+            group_write=group_write,
+            group_execute=group_execute,
+            others_read=others_read,
+            others_write=others_write,
+            others_execute=others_execute,
+        )
+
+
+@dataclass(kw_only=True, slots=True)
+class PermissionsError(Exception): ...
+
+
+@dataclass(kw_only=True, slots=True)
+class PermissionsFromHumanIntError(PermissionsError):
+    n: int
+
+
+@dataclass(kw_only=True, slots=True)
+class PermissionsFromHumanIntRangeError(PermissionsFromHumanIntError):
+    @override
+    def __str__(self) -> str:
+        return f"Invalid human integer for permissions; got {self.n}"
+
+
+@dataclass(kw_only=True, slots=True)
+class PermissionsFromHumanIntDigitError(PermissionsFromHumanIntError):
+    digit: int
+
+    @override
+    def __str__(self) -> str:
+        return (
+            f"Invalid human integer for permissions; got digit {self.digit} in {self.n}"
+        )
+
+
+@dataclass(kw_only=True, slots=True)
+class PermissionsFromIntError(PermissionsError):
+    n: int
+
+    @override
+    def __str__(self) -> str:
+        return f"Invalid integer for permissions; got {self.n} = {oct(self.n)}"
+
+
+@dataclass(kw_only=True, slots=True)
+class PermissionsFromTextError(PermissionsError):
+    text: str
+
+    @override
+    def __str__(self) -> str:
+        return f"Invalid string for permissions; got {self.text!r}"
+
+
+__all__ = [
+    "Permissions",
+    "PermissionsError",
+    "PermissionsFromHumanIntDigitError",
+    "PermissionsFromHumanIntError",
+    "PermissionsFromIntError",
+    "PermissionsFromTextError",
+    "ensure_perms",
+]

utilities/platform.py

@@ -9,6 +9,7 @@ from typing import TYPE_CHECKING, Literal, assert_never, override
 if TYPE_CHECKING:
     from collections.abc import Iterable, Iterator
 
+
 System = Literal["windows", "mac", "linux"]
 
 
@@ -50,7 +51,7 @@ IS_NOT_LINUX = not IS_LINUX
 def get_max_pid() -> int | None:
     """Get the maximum process ID."""
     match SYSTEM:
-        case "windows":  # pragma: no cover
+        case "windows":  # skipif-not-windows
             return None
         case "mac":  # skipif-not-macos
             return 99999
@@ -60,7 +61,7 @@ def get_max_pid() -> int | None:
                 return int(path.read_text())
             except FileNotFoundError:  # pragma: no cover
                 return None
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -79,7 +80,7 @@ def get_strftime(text: str, /) -> str:
             return text
         case "linux":  # skipif-not-linux
             return sub("%Y", "%4Y", text)
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -95,7 +96,7 @@ def maybe_yield_lower_case(text: Iterable[str], /) -> Iterator[str]:
             yield from (t.lower() for t in text)
         case "linux":  # skipif-not-linux
             yield from text
-        case _ as never:
+        case never:
             assert_never(never)