dycw-utilities 0.166.30__py3-none-any.whl → 0.175.17__py3-none-any.whl

utilities/orjson.py

@@ -481,49 +481,49 @@ def _object_hook(
             if match := _NONE_PATTERN.search(text):
                 return None
             if match := _DATE_PATTERN.search(text):
-                return Date.parse_common_iso(match.group(1))
+                return Date.parse_iso(match.group(1))
             if match := _DATE_DELTA_PATTERN.search(text):
-                return DateDelta.parse_common_iso(match.group(1))
+                return DateDelta.parse_iso(match.group(1))
             if match := _DATE_PERIOD_PATTERN.search(text):
-                start, end = map(Date.parse_common_iso, match.group(1).split(","))
+                start, end = map(Date.parse_iso, match.group(1).split(","))
                 return DatePeriod(start, end)
             if match := _DATE_TIME_DELTA_PATTERN.search(text):
-                return DateTimeDelta.parse_common_iso(match.group(1))
+                return DateTimeDelta.parse_iso(match.group(1))
             if match := _FLOAT_PATTERN.search(text):
                 return float(match.group(1))
             if match := _MONTH_DAY_PATTERN.search(text):
-                return MonthDay.parse_common_iso(match.group(1))
+                return MonthDay.parse_iso(match.group(1))
             if match := _PATH_PATTERN.search(text):
                 return Path(match.group(1))
             if match := _PLAIN_DATE_TIME_PATTERN.search(text):
-                return PlainDateTime.parse_common_iso(match.group(1))
+                return PlainDateTime.parse_iso(match.group(1))
             if match := _PY_DATE_PATTERN.search(text):
-                return Date.parse_common_iso(match.group(1)).py_date()
+                return Date.parse_iso(match.group(1)).py_date()
             if match := _PY_PLAIN_DATE_TIME_PATTERN.search(text):
-                return PlainDateTime.parse_common_iso(match.group(1)).py_datetime()
+                return PlainDateTime.parse_iso(match.group(1)).py_datetime()
             if match := _PY_TIME_PATTERN.search(text):
-                return Time.parse_common_iso(match.group(1)).py_time()
+                return Time.parse_iso(match.group(1)).py_time()
             if match := _PY_ZONED_DATE_TIME_PATTERN.search(text):
-                return ZonedDateTime.parse_common_iso(match.group(1)).py_datetime()
+                return ZonedDateTime.parse_iso(match.group(1)).py_datetime()
             if match := _TIME_PATTERN.search(text):
-                return Time.parse_common_iso(match.group(1))
+                return Time.parse_iso(match.group(1))
             if match := _TIME_DELTA_PATTERN.search(text):
-                return TimeDelta.parse_common_iso(match.group(1))
+                return TimeDelta.parse_iso(match.group(1))
             if match := _TIME_PERIOD_PATTERN.search(text):
-                start, end = map(Time.parse_common_iso, match.group(1).split(","))
+                start, end = map(Time.parse_iso, match.group(1).split(","))
                 return TimePeriod(start, end)
             if match := _UUID_PATTERN.search(text):
                 return UUID(match.group(1))
             if match := _VERSION_PATTERN.search(text):
                 return parse_version(match.group(1))
             if match := _YEAR_MONTH_PATTERN.search(text):
-                return YearMonth.parse_common_iso(match.group(1))
+                return YearMonth.parse_iso(match.group(1))
             if match := _ZONED_DATE_TIME_PATTERN.search(text):
-                return ZonedDateTime.parse_common_iso(match.group(1))
+                return ZonedDateTime.parse_iso(match.group(1))
             if match := _ZONED_DATE_TIME_PERIOD_PATTERN.search(text):
                 start, end = match.group(1).split(",")
-                end = ZonedDateTime.parse_common_iso(end)
-                start = PlainDateTime.parse_common_iso(start).assume_tz(end.tz)
+                end = ZonedDateTime.parse_iso(end)
+                start = PlainDateTime.parse_iso(start).assume_tz(end.tz)
                 return ZonedDateTimePeriod(start, end)
             if (
                 exc_class := _object_hook_exception_class(
@@ -1178,7 +1178,7 @@ def _get_log_records_one(
     path = Path(path)
     try:
         lines = path.read_text().splitlines()
-    except UnicodeDecodeError as error:  # skipif-ci-and-windows
+    except UnicodeDecodeError as error:
         return _GetLogRecordsOneOutput(path=path, file_ok=False, other_errors=[error])
     num_lines_blank, num_lines_error = 0, 0
     missing: set[str] = set()

utilities/os.py

@@ -7,6 +7,7 @@ from typing import TYPE_CHECKING, Literal, assert_never, overload, override
 
 from utilities.contextlib import enhanced_context_manager
 from utilities.iterables import OneStrEmptyError, one_str
+from utilities.platform import SYSTEM
 
 if TYPE_CHECKING:
     from collections.abc import Iterator, Mapping
@@ -124,6 +125,39 @@ class GetEnvVarError(Exception):
 ##
 
 
+def get_effective_group_id() -> int | None:
+    """Get the effective group ID."""
+    match SYSTEM:
+        case "windows":  # skipif-not-windows
+            return None
+        case "mac" | "linux":  # skipif-windows
+            from os import getegid
+
+            return getegid()
+        case never:
+            assert_never(never)
+
+
+def get_effective_user_id() -> int | None:
+    """Get the effective user ID."""
+    match SYSTEM:
+        case "windows":  # skipif-not-windows
+            return None
+        case "mac" | "linux":  # skipif-windows
+            from os import geteuid
+
+            return geteuid()
+        case never:
+            assert_never(never)
+
+
+EFFECTIVE_USER_ID = get_effective_user_id()
+EFFECTIVE_GROUP_ID = get_effective_group_id()
+
+
+##
+
+
 def is_debug() -> bool:
     """Check if we are in `DEBUG` mode."""
     return get_env_var("DEBUG", nullable=True) is not None
@@ -165,11 +199,15 @@ def temp_environ(
 
 __all__ = [
     "CPU_COUNT",
+    "EFFECTIVE_GROUP_ID",
+    "EFFECTIVE_USER_ID",
     "GetCPUCountError",
     "GetCPUUseError",
     "IntOrAll",
     "get_cpu_count",
     "get_cpu_use",
+    "get_effective_group_id",
+    "get_effective_user_id",
     "get_env_var",
     "is_debug",
     "is_pytest",

utilities/parse.py

@@ -204,7 +204,7 @@ def _parse_object_type(
         ),
     ):
         try:
-            return cls.parse_common_iso(text)
+            return cls.parse_iso(text)
         except ValueError:
             raise _ParseObjectParseError(type_=cls, text=text) from None
     if issubclass(cls, Path):
@@ -477,7 +477,7 @@ def serialize_object(
             ZonedDateTime,
         ),
     ):
-        return obj.format_common_iso()
+        return obj.format_iso()
     if isinstance(obj, Enum):
         return obj.name
     if isinstance(obj, dict):

utilities/pathlib.py

@@ -12,6 +12,8 @@ from typing import TYPE_CHECKING, Literal, assert_never, overload, override
 
 from utilities.contextlib import enhanced_context_manager
 from utilities.errors import ImpossibleCaseError
+from utilities.grp import get_gid_name
+from utilities.pwd import get_uid_name
 from utilities.sentinel import Sentinel
 
 if TYPE_CHECKING:
@@ -52,6 +54,19 @@ def expand_path(path: PathLike, /) -> Path:
 ##
 
 
+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 = Path.cwd, /) -> Path:
     """Get the package root."""
     path = to_path(path)
@@ -112,7 +127,7 @@ class GetRepoRootError(Exception): ...
 class _GetRepoRootGitNotFoundError(GetRepoRootError):
     @override
     def __str__(self) -> str:
-        return "'git' not found"
+        return "'git' not found"  # pragma: no cover
 
 
 @dataclass(kw_only=True, slots=True)
@@ -327,6 +342,8 @@ __all__ = [
     "GetTailError",
     "ensure_suffix",
     "expand_path",
+    "get_file_group",
+    "get_file_owner",
     "get_package_root",
     "get_repo_root",
     "get_tail",

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

@@ -51,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

utilities/polars.py

@@ -2571,7 +2571,8 @@ def round_to_float(
             return z.round(decimals=utilities.math.number_of_decimals(y) + 1)
         case Series(), Expr() | Series():
             df = (
-                x.to_frame()
+                x
+                .to_frame()
                 .with_columns(y)
                 .with_columns(number_of_decimals(y).alias("_decimals"))
                 .with_row_index(name="_index")
@@ -2638,6 +2639,8 @@ def search_period(
                 return None
             item: dt.datetime = series[index]["start"]
             return index if py_date_time > item else None
+        case never:
+            assert_never(never)
 
 
 ##