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

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

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

{dycw_utilities-0.174.9 → dycw_utilities-0.174.11}/pyproject.toml

@@ -101,7 +101,7 @@
   name = "dycw-utilities"
   readme = "README.md"
   requires-python = ">= 3.12"
-  version = "0.174.9"
+  version = "0.174.11"
 
   [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.9"
+    current_version = "0.174.11"
 
     [[tool.bumpversion.files]]
       filename = "src/utilities/__init__.py"

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

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

{dycw_utilities-0.174.9 → dycw_utilities-0.174.11}/src/utilities/permissions.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-from contextlib import suppress
 from dataclasses import dataclass
 from functools import reduce
 from operator import or_
@@ -15,27 +14,38 @@ from stat import (
     S_IXOTH,
     S_IXUSR,
 )
-from typing import Literal, Self, override
+from typing import Literal, Self, assert_never, override
 
 from utilities.dataclasses import replace_non_sentinel
-from utilities.functions import ensure_member
-from utilities.re import (
-    ExtractGroupError,
-    ExtractGroupsError,
-    extract_group,
-    extract_groups,
-)
+from utilities.re import ExtractGroupsError, extract_groups
 from utilities.sentinel import Sentinel, sentinel
-from utilities.typing import get_args
 
-_MIN_INT = 0o0
-_MAX_INT = 0o777
-type _ZeroToSeven = Literal[0, 1, 2, 3, 4, 5, 6, 7]
-_ZERO_TO_SEVEN: list[_ZeroToSeven] = list(get_args(_ZeroToSeven.__value__))
+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
@@ -47,26 +57,18 @@ class Permissions:
     others_execute: bool = False
 
     def __int__(self) -> int:
-        return (
-            100
-            * self._int(
-                read=self.user_read, write=self.user_write, execute=self.user_execute
-            )
-            + 10
-            * self._int(
-                read=self.group_read, write=self.group_write, execute=self.group_execute
-            )
-            + self._int(
-                read=self.others_read,
-                write=self.others_write,
-                execute=self.others_execute,
-            )
-        )
-
-    def _int(
-        self, *, read: bool = False, write: bool = False, execute: bool = False
-    ) -> _ZeroToSeven:
-        return (4 if read else 0) + (2 if write else 0) + (1 if execute else 0)
+        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:
@@ -100,13 +102,11 @@ class Permissions:
         write: bool = False,
         execute: bool = False,
     ) -> str:
-        parts: list[str] = []
-        if read:
-            parts.append("r")
-        if write:
-            parts.append("w")
-        if execute:
-            parts.append("x")
+        parts: list[str] = [
+            "r" if read else "",
+            "w" if write else "",
+            "x" if execute else "",
+        ]
         return f"{prefix}={''.join(parts)}"
 
     @override
@@ -114,66 +114,33 @@ class Permissions:
         return repr(self)
 
     @classmethod
-    def from_int(cls, n: int, /) -> Self:
-        with suppress(ExtractGroupsError):
-            user, group, others = extract_groups(r"^([0-7])([0-7])([0-7])$", str(n))
-            user_read, user_write, user_execute = cls._from_int(
-                ensure_member(int(user), _ZERO_TO_SEVEN)
-            )
-            group_read, group_write, group_execute = cls._from_int(
-                ensure_member(int(group), _ZERO_TO_SEVEN)
-            )
-            others_read, others_write, others_execute = cls._from_int(
-                ensure_member(int(others), _ZERO_TO_SEVEN)
-            )
-            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,
-            )
-        with suppress(ExtractGroupsError):
-            group, others = extract_groups(r"^([0-7])([0-7])$", str(n))
-            group_read, group_write, group_execute = cls._from_int(
-                ensure_member(int(group), _ZERO_TO_SEVEN)
-            )
-            others_read, others_write, others_execute = cls._from_int(
-                ensure_member(int(others), _ZERO_TO_SEVEN)
-            )
-            return cls(
-                group_read=group_read,
-                group_write=group_write,
-                group_execute=group_execute,
-                others_read=others_read,
-                others_write=others_write,
-                others_execute=others_execute,
-            )
-        with suppress(ExtractGroupError):
-            others = extract_group(r"^([0-7])$", str(n))
-            others_read, others_write, others_execute = cls._from_int(
-                ensure_member(int(others), _ZERO_TO_SEVEN)
-            )
-            return cls(
-                others_read=others_read,
-                others_write=others_write,
-                others_execute=others_execute,
-            )
-        if n == 0:
-            return cls()
-        raise PermissionsFromIntError(n=n)
+    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_int(cls, n: _ZeroToSeven, /) -> tuple[bool, bool, bool]:
-        return bool(4 & n), bool(2 & n), bool(1 & n)
+    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_octal(cls, n: int, /) -> Self:
-        if _MIN_INT <= n <= _MAX_INT:
+    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),
@@ -185,7 +152,7 @@ class Permissions:
                 others_write=bool(n & S_IWOTH),
                 others_execute=bool(n & S_IXOTH),
             )
-        raise PermissionsFromOctalError(n=n)
+        raise PermissionsFromIntError(n=n)
 
     @classmethod
     def from_text(cls, text: str, /) -> Self:
@@ -216,19 +183,27 @@ class Permissions:
         return read != "", write != "", execute != ""
 
     @property
-    def octal(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)
+    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,
@@ -262,21 +237,35 @@ class PermissionsError(Exception): ...
 
 
 @dataclass(kw_only=True, slots=True)
-class PermissionsFromIntError(PermissionsError):
+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 integer for permissions; got {self.n}"
+        return (
+            f"Invalid human integer for permissions; got digit {self.digit} in {self.n}"
+        )
 
 
 @dataclass(kw_only=True, slots=True)
-class PermissionsFromOctalError(PermissionsError):
+class PermissionsFromIntError(PermissionsError):
     n: int
 
     @override
     def __str__(self) -> str:
-        return f"Invalid octal for permissions; got {oct(self.n)}"
+        return f"Invalid integer for permissions; got {self.n} = {oct(self.n)}"
 
 
 @dataclass(kw_only=True, slots=True)
@@ -291,7 +280,9 @@ class PermissionsFromTextError(PermissionsError):
 __all__ = [
     "Permissions",
     "PermissionsError",
+    "PermissionsFromHumanIntDigitError",
+    "PermissionsFromHumanIntError",
     "PermissionsFromIntError",
-    "PermissionsFromOctalError",
     "PermissionsFromTextError",
+    "ensure_perms",
 ]