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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dycw-utilities
-Version: 0.174.10
+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.10.dist-info → dycw_utilities-0.174.11.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=0CWy0Ep-3LcvfPyRs5NDWEzJToyo7mozx2oLa1j9OoA,61
+utilities/__init__.py,sha256=Ed7ve87kqMRppt7gnxtu2swOV8yOK_hwjAE5eRBPgKg,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=HSVpLef4lfG6GsbeDgYbKRe_92Kk6dNPrB0kw7GsXMY,8093
+utilities/permissions.py,sha256=xw3mDS5UT3SO5_AZ0RXYMQi1hU-3LedAWHdHEsOAHu0,8697
 utilities/pickle.py,sha256=MBT2xZCsv0pH868IXLGKnlcqNx2IRVKYNpRcqiQQqxw,653
 utilities/platform.py,sha256=0pYO5v7L2sU5UN87zHhEEhTKsZ9NIEM8N6UCr0F7bLY,2778
 utilities/polars.py,sha256=cNFBLWgOMUAp_Sz4xtlto17uZswZRrcfQYC95QKyaY4,87483
@@ -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.10.dist-info/WHEEL,sha256=ZyFSCYkV2BrxH6-HRVRg3R9Fo7MALzer9KiPYqNxSbo,79
-dycw_utilities-0.174.10.dist-info/entry_points.txt,sha256=ykGI1ArwOPHqm2g5Cqh3ENdMxEej_a_FcOUov5EM5Oc,155
-dycw_utilities-0.174.10.dist-info/METADATA,sha256=xJJPzLScczDipOwF6AP4Tqr8p__BH8NV6WcuwhqZIq0,1710
-dycw_utilities-0.174.10.dist-info/RECORD,,
+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,,

utilities/__init__.py

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

utilities/permissions.py

@@ -14,15 +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.re import ExtractGroupsError, extract_groups
 from utilities.sentinel import Sentinel, sentinel
 
+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
@@ -34,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
-    ) -> int:
-        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:
@@ -87,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
@@ -101,12 +114,12 @@ class Permissions:
         return repr(self)
 
     @classmethod
-    def from_int(cls, n: int, /) -> Self:
+    def from_human_int(cls, n: int, /) -> Self:
         if not (0 <= n <= 777):
-            raise PermissionsFromIntRangeError(n=n)
-        user_read, user_write, user_execute = cls._from_int(n, (n // 100) % 10)
-        group_read, group_write, group_execute = cls._from_int(n, (n // 10) % 10)
-        others_read, others_write, others_execute = cls._from_int(n, n % 10)
+            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,
@@ -120,13 +133,13 @@ class Permissions:
         )
 
     @classmethod
-    def _from_int(cls, n: int, digit: int, /) -> tuple[bool, bool, bool]:
+    def _from_human_int(cls, n: int, digit: int, /) -> tuple[bool, bool, bool]:
         if not (0 <= digit <= 7):
-            raise PermissionsFromIntDigitError(n=n, digit=digit)
+            raise PermissionsFromHumanIntDigitError(n=n, digit=digit)
         return bool(4 & digit), bool(2 & digit), bool(1 & digit)
 
     @classmethod
-    def from_octal(cls, n: int, /) -> Self:
+    def from_int(cls, n: int, /) -> Self:
         if 0o0 <= n <= 0o777:
             return cls(
                 user_read=bool(n & S_IRUSR),
@@ -139,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:
@@ -170,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,
@@ -216,33 +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 PermissionsFromIntRangeError(PermissionsFromIntError):
+class PermissionsFromHumanIntRangeError(PermissionsFromHumanIntError):
     @override
     def __str__(self) -> str:
-        return f"Invalid integer for permissions; got {self.n}"
+        return f"Invalid human integer for permissions; got {self.n}"
 
 
 @dataclass(kw_only=True, slots=True)
-class PermissionsFromIntDigitError(PermissionsFromIntError):
+class PermissionsFromHumanIntDigitError(PermissionsFromHumanIntError):
     digit: int
 
     @override
     def __str__(self) -> str:
-        return f"Invalid integer for permissions; got digit {self.digit} in {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)
@@ -257,8 +280,9 @@ class PermissionsFromTextError(PermissionsError):
 __all__ = [
     "Permissions",
     "PermissionsError",
-    "PermissionsFromIntDigitError",
+    "PermissionsFromHumanIntDigitError",
+    "PermissionsFromHumanIntError",
     "PermissionsFromIntError",
-    "PermissionsFromOctalError",
     "PermissionsFromTextError",
+    "ensure_perms",
 ]