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

utilities/os.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
-from contextlib import contextmanager, suppress
+from contextlib import suppress
 from dataclasses import dataclass
 from os import cpu_count, environ, getenv
 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
@@ -47,7 +49,7 @@ def get_cpu_use(*, n: IntOrAll = "all") -> int:
             raise GetCPUUseError(n=n)
         case "all":
             return CPU_COUNT
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -104,7 +106,7 @@ def get_env_var(
                 return None
             case str(), _:
                 return default
-            case _ as never:
+            case never:
                 assert_never(never)
     return environ[key_use]
 
@@ -123,7 +125,56 @@ class GetEnvVarError(Exception):
 ##
 
 
-@contextmanager
+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
+
+
+##
+
+
+def is_pytest() -> bool:
+    """Check if `pytest` is running."""
+    return get_env_var("PYTEST_VERSION", nullable=True) is not None
+
+
+##
+
+
+@enhanced_context_manager
 def temp_environ(
     env: Mapping[str, str | None] | None = None, **env_kwargs: str | None
 ) -> Iterator[None]:
@@ -148,11 +199,17 @@ 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",
     "temp_environ",
 ]

utilities/parse.py

@@ -1,14 +1,26 @@
 from __future__ import annotations
 
-import datetime as dt
 from contextlib import suppress
 from dataclasses import dataclass
 from enum import Enum
+from ipaddress import IPv4Address, IPv6Address
 from pathlib import Path
 from re import DOTALL
 from types import NoneType
 from typing import TYPE_CHECKING, Any, override
 
+from whenever import (
+    Date,
+    DateDelta,
+    DateTimeDelta,
+    MonthDay,
+    PlainDateTime,
+    Time,
+    TimeDelta,
+    YearMonth,
+    ZonedDateTime,
+)
+
 from utilities.enum import ParseEnumError, parse_enum
 from utilities.iterables import OneEmptyError, OneNonUniqueError, one, one_str
 from utilities.math import ParseNumberError, parse_number
@@ -26,7 +38,7 @@ from utilities.text import (
     split_key_value_pairs,
     split_str,
 )
-from utilities.types import Duration, Number, ParseObjectExtra, SerializeObjectExtra
+from utilities.types import Number, ParseObjectExtra, SerializeObjectExtra
 from utilities.typing import (
     get_args,
     is_dict_type,
@@ -167,14 +179,9 @@ def _parse_object_type(
             return parse_bool(text)
         except ParseBoolError:
             raise _ParseObjectParseError(type_=cls, text=text) from None
-    if is_subclass_gen(cls, int):
-        try:
-            return int(text)
-        except ValueError:
-            raise _ParseObjectParseError(type_=cls, text=text) from None
-    if issubclass(cls, float):
+    if is_subclass_gen(cls, int | float | IPv4Address | IPv6Address):
         try:
-            return float(text)
+            return cls(text)
         except ValueError:
             raise _ParseObjectParseError(type_=cls, text=text) from None
     if issubclass(cls, Enum):
@@ -182,6 +189,24 @@ def _parse_object_type(
             return parse_enum(text, cls, case_sensitive=case_sensitive)
         except ParseEnumError:
             raise _ParseObjectParseError(type_=cls, text=text) from None
+    if issubclass(
+        cls,
+        (
+            Date,
+            DateDelta,
+            DateTimeDelta,
+            MonthDay,
+            PlainDateTime,
+            Time,
+            TimeDelta,
+            YearMonth,
+            ZonedDateTime,
+        ),
+    ):
+        try:
+            return cls.parse_iso(text)
+        except ValueError:
+            raise _ParseObjectParseError(type_=cls, text=text) from None
     if issubclass(cls, Path):
         return Path(text).expanduser()
     if issubclass(cls, Sentinel):
@@ -194,34 +219,6 @@ def _parse_object_type(
             return parse_version(text)
         except ParseVersionError:
             raise _ParseObjectParseError(type_=cls, text=text) from None
-    if is_subclass_gen(cls, dt.date):
-        from utilities.whenever import ParseDateError, parse_date
-
-        try:
-            return parse_date(text)
-        except ParseDateError:
-            raise _ParseObjectParseError(type_=cls, text=text) from None
-    if is_subclass_gen(cls, dt.datetime):
-        from utilities.whenever import ParseDateTimeError, parse_datetime
-
-        try:
-            return parse_datetime(text)
-        except ParseDateTimeError:
-            raise _ParseObjectParseError(type_=cls, text=text) from None
-    if issubclass(cls, dt.time):
-        from utilities.whenever import ParseTimeError, parse_time
-
-        try:
-            return parse_time(text)
-        except ParseTimeError:
-            raise _ParseObjectParseError(type_=cls, text=text) from None
-    if issubclass(cls, dt.timedelta):
-        from utilities.whenever import ParseTimedeltaError, parse_timedelta
-
-        try:
-            return parse_timedelta(text)
-        except ParseTimedeltaError:
-            raise _ParseObjectParseError(type_=cls, text=text) from None
     raise _ParseObjectParseError(type_=cls, text=text)
 
 
@@ -374,13 +371,6 @@ def _parse_object_union_type(type_: Any, text: str, /) -> Any:
             return parse_number(text)
         except ParseNumberError:
             raise _ParseObjectParseError(type_=type_, text=text) from None
-    if type_ is Duration:
-        from utilities.whenever import ParseDurationError, parse_duration
-
-        try:
-            return parse_duration(text)
-        except ParseDurationError:
-            raise _ParseObjectParseError(type_=type_, text=text) from None
     raise _ParseObjectParseError(type_=type_, text=text) from None
 
 
@@ -461,25 +451,33 @@ def serialize_object(
         with suppress(_SerializeObjectSerializeError):
             return _serialize_object_extra(obj, extra)
     if (obj is None) or isinstance(
-        obj, bool | int | float | str | Path | Sentinel | Version
+        obj,
+        bool
+        | int
+        | float
+        | str
+        | IPv4Address
+        | IPv6Address
+        | Path
+        | Sentinel
+        | Version,
     ):
         return str(obj)
-    if is_instance_gen(obj, dt.date):
-        from utilities.whenever import serialize_date
-
-        return serialize_date(obj)
-    if is_instance_gen(obj, dt.datetime):
-        from utilities.whenever import serialize_datetime
-
-        return serialize_datetime(obj)
-    if isinstance(obj, dt.time):
-        from utilities.whenever import serialize_time
-
-        return serialize_time(obj)
-    if isinstance(obj, dt.timedelta):
-        from utilities.whenever import serialize_timedelta
-
-        return serialize_timedelta(obj)
+    if isinstance(
+        obj,
+        (
+            Date,
+            DateDelta,
+            DateTimeDelta,
+            MonthDay,
+            PlainDateTime,
+            Time,
+            TimeDelta,
+            YearMonth,
+            ZonedDateTime,
+        ),
+    ):
+        return obj.format_iso()
     if isinstance(obj, Enum):
         return obj.name
     if isinstance(obj, dict):

utilities/pathlib.py

@@ -1,22 +1,27 @@
 from __future__ import annotations
 
 from collections.abc import Callable
-from contextlib import contextmanager, suppress
 from dataclasses import dataclass
 from itertools import chain
 from os import chdir
+from os.path import expandvars
 from pathlib import Path
 from re import IGNORECASE, search
 from subprocess import PIPE, CalledProcessError, check_output
-from typing import TYPE_CHECKING, assert_never, overload, override
+from typing import TYPE_CHECKING, Literal, assert_never, overload, override
 
-from utilities.sentinel import Sentinel, sentinel
+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:
     from collections.abc import Iterator, Sequence
 
     from utilities.types import MaybeCallablePathLike, PathLike
 
+
 PWD = Path.cwd()
 
 
@@ -24,60 +29,149 @@ def ensure_suffix(path: PathLike, suffix: str, /) -> Path:
     """Ensure a path has a given suffix."""
     path = Path(path)
     parts = path.name.split(".")
-    parts = list(chain([parts[0]], (f".{p}" for p in parts[1:])))
-    if (len(parts) == 0) or (parts[-1] != suffix):
-        parts.append(suffix)
-    name = "".join(parts)
+    suffixes = suffix.strip(".").split(".")
+    max_len = max(len(parts), len(suffixes))
+    try:
+        i = next(i for i in range(max_len, 0, -1) if parts[-i:] == suffixes[:i])
+    except StopIteration:
+        add = suffixes
+    else:
+        add = suffixes[i:]
+    name = ".".join(chain(parts, add))
     return path.with_name(name)
 
 
 ##
 
 
-@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 expand_path(path: PathLike, /) -> Path:
+    """Expand a path."""
+    path = str(path)
+    path = expandvars(path)
+    return Path(path).expanduser()
 
 
 ##
 
 
-def get_root(*, path: MaybeCallablePathLike | None = None) -> Path:
-    """Get the root of a path."""
-    path = get_path(path=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)
+    path_dir = path.parent if path.is_file() else path
+    all_paths = list(chain([path_dir], path_dir.parents))
+    try:
+        return next(
+            p.resolve()
+            for p in all_paths
+            if any(p_i.name == "pyproject.toml" for p_i in p.iterdir())
+        )
+    except StopIteration:
+        raise GetPackageRootError(path=path) from None
+
+
+@dataclass(kw_only=True, slots=True)
+class GetPackageRootError(Exception):
+    path: PathLike
+
+    @override
+    def __str__(self) -> str:
+        return f"Path is not part of a package: {self.path}"
+
+
+##
+
+
+def get_repo_root(path: MaybeCallablePathLike = Path.cwd, /) -> Path:
+    """Get the repo root."""
+    path = to_path(path)
+    path_dir = path.parent if path.is_file() else path
     try:
         output = check_output(
-            ["git", "rev-parse", "--show-toplevel"], stderr=PIPE, cwd=path, text=True
+            ["git", "rev-parse", "--show-toplevel"],
+            stderr=PIPE,
+            cwd=path_dir,
+            text=True,
         )
     except CalledProcessError as error:
         # newer versions of git report "Not a git repository", whilst older
         # versions report "not a git repository"
-        if not search("fatal: not a git repository", error.stderr, flags=IGNORECASE):
-            raise  # pragma: no cover
+        if search("fatal: not a git repository", error.stderr, flags=IGNORECASE):
+            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"))
-    all_paths = list(chain([path], path.parents))
-    with suppress(StopIteration):
-        return next(
-            p for p in all_paths if any(p_i.name == ".envrc" for p_i in p.iterdir())
-        )
-    raise GetRootError(path=path)
+
+
+@dataclass(kw_only=True, slots=True)
+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:
+        return f"Path is not part of a `git` repository: {self.path}"
+
+
+##
+
+
+def get_root(path: MaybeCallablePathLike = Path.cwd, /) -> Path:
+    """Get the root of a path."""
+    path = to_path(path)
+    try:
+        repo = get_repo_root(path)
+    except GetRepoRootError:
+        repo = None
+    try:
+        package = get_package_root(path)
+    except GetPackageRootError:
+        package = None
+    match repo, package:
+        case None, None:
+            raise GetRootError(path=path)
+        case Path(), None:
+            return repo
+        case None, Path():
+            return package
+        case Path(), Path():
+            if repo == package:
+                return repo
+            if is_sub_path(repo, package, strict=True):
+                return repo
+            if is_sub_path(package, repo, strict=True):
+                return package
+            raise ImpossibleCaseError(  # pragma: no cover
+                case=[f"{repo=}", f"{package=}"]
+            )
+        case never:
+            assert_never(never)
 
 
 @dataclass(kw_only=True, slots=True)
@@ -92,6 +186,112 @@ class GetRootError(Exception):
 ##
 
 
+type _GetTailDisambiguate = Literal["raise", "earlier", "later"]
+
+
+def get_tail(
+    path: PathLike, root: PathLike, /, *, disambiguate: _GetTailDisambiguate = "raise"
+) -> Path:
+    """Get the tail of a path following a root match."""
+    path_parts, root_parts = [Path(p).parts for p in [path, root]]
+    len_path, len_root = map(len, [path_parts, root_parts])
+    if len_root > len_path:
+        raise _GetTailLengthError(path=path, root=root, len_root=len_root)
+    candidates = {
+        i + len_root: path_parts[i : i + len_root]
+        for i in range(len_path + 1 - len_root)
+    }
+    matches = {k: v for k, v in candidates.items() if v == root_parts}
+    match len(matches), disambiguate:
+        case 0, _:
+            raise _GetTailEmptyError(path=path, root=root)
+        case 1, _:
+            return _get_tail_core(path, next(iter(matches)))
+        case _, "raise":
+            first, second, *_ = matches
+            raise _GetTailNonUniqueError(
+                path=path,
+                root=root,
+                first=_get_tail_core(path, first),
+                second=_get_tail_core(path, second),
+            )
+        case _, "earlier":
+            return _get_tail_core(path, next(iter(matches)))
+        case _, "later":
+            return _get_tail_core(path, next(iter(reversed(matches))))
+        case never:
+            assert_never(never)
+
+
+def _get_tail_core(path: PathLike, i: int, /) -> Path:
+    parts = Path(path).parts
+    return Path(*parts[i:])
+
+
+@dataclass(kw_only=True, slots=True)
+class GetTailError(Exception):
+    path: PathLike
+    root: PathLike
+
+
+@dataclass(kw_only=True, slots=True)
+class _GetTailLengthError(GetTailError):
+    len_root: int
+
+    @override
+    def __str__(self) -> str:
+        return f"Unable to get the tail of {str(self.path)!r} with root of length {self.len_root}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _GetTailEmptyError(GetTailError):
+    @override
+    def __str__(self) -> str:
+        return (
+            f"Unable to get the tail of {str(self.path)!r} with root {str(self.root)!r}"
+        )
+
+
+@dataclass(kw_only=True, slots=True)
+class _GetTailNonUniqueError(GetTailError):
+    first: Path
+    second: Path
+
+    @override
+    def __str__(self) -> str:
+        return f"Path {str(self.path)!r} must contain exactly one tail with root {str(self.root)!r}; got {str(self.first)!r}, {str(self.second)!r} and perhaps more"
+
+
+##
+
+
+def module_path(
+    path: PathLike,
+    /,
+    *,
+    root: PathLike | None = None,
+    disambiguate: _GetTailDisambiguate = "raise",
+) -> str:
+    """Return a module path."""
+    path = Path(path)
+    if root is not None:
+        path = get_tail(path, root, disambiguate=disambiguate)
+    parts = path.with_suffix("").parts
+    return ".".join(parts)
+
+
+##
+
+
+def is_sub_path(x: PathLike, y: PathLike, /, *, strict: bool = False) -> bool:
+    """Check if a path is a sub path of another."""
+    x, y = [Path(i).resolve() for i in [x, y]]
+    return x.is_relative_to(y) and not (strict and y.is_relative_to(x))
+
+
+##
+
+
 def list_dir(path: PathLike, /) -> Sequence[Path]:
     """List the contents of a directory."""
     return sorted(Path(path).iterdir())
@@ -100,7 +300,7 @@ def list_dir(path: PathLike, /) -> Sequence[Path]:
 ##
 
 
-@contextmanager
+@enhanced_context_manager
 def temp_cwd(path: PathLike, /) -> Iterator[None]:
     """Context manager with temporary current working directory set."""
     prev = Path.cwd()
@@ -111,4 +311,45 @@ def temp_cwd(path: PathLike, /) -> Iterator[None]:
         chdir(prev)
 
 
-__all__ = ["PWD", "ensure_suffix", "get_path", "list_dir", "temp_cwd"]
+##
+
+
+@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",
+    "GetRepoRootError",
+    "GetTailError",
+    "ensure_suffix",
+    "expand_path",
+    "get_file_group",
+    "get_file_owner",
+    "get_package_root",
+    "get_repo_root",
+    "get_tail",
+    "is_sub_path",
+    "list_dir",
+    "module_path",
+    "temp_cwd",
+    "to_path",
+]