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

utilities/permissions.py

@@ -1,298 +0,0 @@
-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/pickle.py

@@ -1,25 +0,0 @@
-from __future__ import annotations
-
-import gzip
-from pickle import dump, load
-from typing import TYPE_CHECKING, Any
-
-from utilities.atomicwrites import writer
-
-if TYPE_CHECKING:
-    from utilities.types import PathLike
-
-
-def read_pickle(path: PathLike, /) -> Any:
-    """Read an object from disk."""
-    with gzip.open(path, mode="rb") as gz:
-        return load(gz)  # noqa: S301
-
-
-def write_pickle(obj: Any, path: PathLike, /, *, overwrite: bool = False) -> None:
-    """Write an object to disk."""
-    with writer(path, overwrite=overwrite) as temp, gzip.open(temp, mode="wb") as gz:
-        dump(obj, gz)
-
-
-__all__ = ["read_pickle", "write_pickle"]

utilities/pwd.py

@@ -1,28 +0,0 @@
-from __future__ import annotations
-
-from typing import assert_never
-
-from utilities.os import EFFECTIVE_USER_ID
-from utilities.platform import SYSTEM
-
-
-def get_uid_name(uid: int, /) -> str | None:
-    """Get the name of a user ID."""
-    match SYSTEM:
-        case "windows":  # skipif-not-windows
-            return None
-        case "mac" | "linux":  # skipif-windows
-            from pwd import getpwuid
-
-            return getpwuid(uid).pw_name
-        case never:
-            assert_never(never)
-
-
-ROOT_USER_NAME = get_uid_name(0)
-EFFECTIVE_USER_NAME = (
-    None if EFFECTIVE_USER_ID is None else get_uid_name(EFFECTIVE_USER_ID)
-)
-
-
-__all__ = ["EFFECTIVE_USER_NAME", "ROOT_USER_NAME", "get_uid_name"]

utilities/re.py

@@ -1,156 +0,0 @@
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass
-from re import Pattern
-from typing import TYPE_CHECKING, assert_never, override
-
-if TYPE_CHECKING:
-    from utilities.types import PatternLike
-
-
-def ensure_pattern(pattern: PatternLike, /, *, flags: int = 0) -> Pattern[str]:
-    """Ensure a pattern is returned."""
-    match pattern:
-        case Pattern():
-            return pattern
-        case str():
-            return re.compile(pattern, flags=flags)
-        case never:
-            assert_never(never)
-
-
-##
-
-
-def extract_group(pattern: PatternLike, text: str, /, *, flags: int = 0) -> str:
-    """Extract a group.
-
-    The regex must have 1 capture group, and this must match exactly once.
-    """
-    pattern_use = ensure_pattern(pattern, flags=flags)
-    match pattern_use.groups:
-        case 0:
-            raise _ExtractGroupNoCaptureGroupsError(pattern=pattern_use, text=text)
-        case 1:
-            matches: list[str] = pattern_use.findall(text)
-            match len(matches):
-                case 0:
-                    raise _ExtractGroupNoMatchesError(
-                        pattern=pattern_use, text=text
-                    ) from None
-                case 1:
-                    return matches[0]
-                case _:
-                    raise _ExtractGroupMultipleMatchesError(
-                        pattern=pattern_use, text=text, matches=matches
-                    ) from None
-        case _:
-            raise _ExtractGroupMultipleCaptureGroupsError(
-                pattern=pattern_use, text=text
-            )
-
-
-@dataclass(kw_only=True, slots=True)
-class ExtractGroupError(Exception):
-    pattern: Pattern[str]
-    text: str
-
-
-@dataclass(kw_only=True, slots=True)
-class _ExtractGroupMultipleCaptureGroupsError(ExtractGroupError):
-    @override
-    def __str__(self) -> str:
-        return f"Pattern {self.pattern} must contain exactly one capture group; it had multiple"
-
-
-@dataclass(kw_only=True, slots=True)
-class _ExtractGroupMultipleMatchesError(ExtractGroupError):
-    matches: list[str]
-
-    @override
-    def __str__(self) -> str:
-        return f"Pattern {self.pattern} must match against {self.text} exactly once; matches were {self.matches}"
-
-
-@dataclass(kw_only=True, slots=True)
-class _ExtractGroupNoCaptureGroupsError(ExtractGroupError):
-    @override
-    def __str__(self) -> str:
-        return f"Pattern {self.pattern} must contain exactly one capture group; it had none".format(
-            self.pattern
-        )
-
-
-@dataclass(kw_only=True, slots=True)
-class _ExtractGroupNoMatchesError(ExtractGroupError):
-    @override
-    def __str__(self) -> str:
-        return f"Pattern {self.pattern} must match against {self.text}"
-
-
-##
-
-
-def extract_groups(pattern: PatternLike, text: str, /, *, flags: int = 0) -> list[str]:
-    """Extract multiple groups.
-
-    The regex may have any number of capture groups, and they must collectively
-    match exactly once.
-    """
-    pattern_use = ensure_pattern(pattern, flags=flags)
-    if (n_groups := pattern_use.groups) == 0:
-        raise _ExtractGroupsNoCaptureGroupsError(pattern=pattern_use, text=text)
-    matches: list[str] = pattern_use.findall(text)
-    match len(matches), n_groups:
-        case 0, _:
-            raise _ExtractGroupsNoMatchesError(pattern=pattern_use, text=text)
-        case 1, 1:
-            return matches
-        case 1, _:
-            return list(matches[0])
-        case _:
-            raise _ExtractGroupsMultipleMatchesError(
-                pattern=pattern_use, text=text, matches=matches
-            )
-
-
-@dataclass(kw_only=True, slots=True)
-class ExtractGroupsError(Exception):
-    pattern: Pattern[str]
-    text: str
-
-
-@dataclass(kw_only=True, slots=True)
-class _ExtractGroupsMultipleMatchesError(ExtractGroupsError):
-    matches: list[str]
-
-    @override
-    def __str__(self) -> str:
-        return f"Pattern {self.pattern} must match against {self.text} exactly once; matches were {self.matches}"
-
-
-@dataclass(kw_only=True, slots=True)
-class _ExtractGroupsNoCaptureGroupsError(ExtractGroupsError):
-    pattern: Pattern[str]
-    text: str
-
-    @override
-    def __str__(self) -> str:
-        return f"Pattern {self.pattern} must contain at least one capture group"
-
-
-@dataclass(kw_only=True, slots=True)
-class _ExtractGroupsNoMatchesError(ExtractGroupsError):
-    @override
-    def __str__(self) -> str:
-        return f"Pattern {self.pattern} must match against {self.text}"
-
-
-__all__ = [
-    "ExtractGroupError",
-    "ExtractGroupsError",
-    "ensure_pattern",
-    "extract_group",
-    "extract_groups",
-]

utilities/sentinel.py

@@ -1,73 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-from re import IGNORECASE, search
-from typing import Any, override
-
-from typing_extensions import TypeIs
-
-
-class _Meta(type):
-    """Metaclass for the sentinel."""
-
-    instance: Any = None
-
-    @override
-    def __call__(cls, *args: Any, **kwargs: Any) -> Any:
-        if cls.instance is None:
-            cls.instance = super().__call__(*args, **kwargs)
-        return cls.instance
-
-
-SENTINEL_REPR = "<sentinel>"
-
-
-class Sentinel(metaclass=_Meta):
-    """Base class for the sentinel object."""
-
-    @override
-    def __repr__(self) -> str:
-        return SENTINEL_REPR
-
-    @override
-    def __str__(self) -> str:
-        return repr(self)
-
-
-sentinel = Sentinel()
-
-##
-
-
-def is_sentinel(obj: Any, /) -> TypeIs[Sentinel]:
-    """Check if an object is the sentinel."""
-    return obj is sentinel
-
-
-##
-
-
-def parse_sentinel(text: str, /) -> Sentinel:
-    """Parse text into the Sentinel value."""
-    if search("^(|sentinel|<sentinel>)$", text, flags=IGNORECASE):
-        return sentinel
-    raise ParseSentinelError(text=text)
-
-
-@dataclass(kw_only=True, slots=True)
-class ParseSentinelError(Exception):
-    text: str
-
-    @override
-    def __str__(self) -> str:
-        return f"Unable to parse sentinel value; got {self.text!r}"
-
-
-__all__ = [
-    "SENTINEL_REPR",
-    "ParseSentinelError",
-    "Sentinel",
-    "is_sentinel",
-    "parse_sentinel",
-    "sentinel",
-]

utilities/socket.py

@@ -1,8 +0,0 @@
-from __future__ import annotations
-
-from socket import gethostname
-
-HOSTNAME = gethostname()
-
-
-__all__ = ["HOSTNAME"]

utilities/string.py

@@ -1,20 +0,0 @@
-from __future__ import annotations
-
-from os import environ
-from pathlib import Path
-from string import Template
-from typing import Any, assert_never
-
-
-def substitute_environ(path_or_text: Path | str, /, **kwargs: Any) -> str:
-    """Substitute the environment variables in a file."""
-    match path_or_text:
-        case Path() as path:
-            return substitute_environ(path.read_text(), **kwargs)
-        case str() as text:
-            return Template(text).substitute(environ, **kwargs)
-        case never:
-            assert_never(never)
-
-
-__all__ = ["substitute_environ"]