dycw-utilities 0.148.5__py3-none-any.whl → 0.174.12__py3-none-any.whl

utilities/orjson.py

@@ -5,7 +5,7 @@ import re
 from collections.abc import Callable, Iterable, Mapping, Sequence
 from contextlib import suppress
 from dataclasses import dataclass, field, replace
-from enum import Enum, unique
+from enum import Enum, StrEnum, unique
 from functools import cached_property, partial
 from itertools import chain
 from logging import Formatter, LogRecord
@@ -20,6 +20,7 @@ from orjson import (
     OPT_PASSTHROUGH_DATACLASS,
     OPT_PASSTHROUGH_DATETIME,
     OPT_SORT_KEYS,
+    JSONDecodeError,
     dumps,
     loads,
 )
@@ -37,7 +38,7 @@ from whenever import (
 
 from utilities.concurrent import concurrent_map
 from utilities.dataclasses import dataclass_to_dict
-from utilities.functions import ensure_class, is_string_mapping
+from utilities.functions import ensure_class
 from utilities.gzip import read_binary
 from utilities.iterables import (
     OneEmptyError,
@@ -50,9 +51,15 @@ from utilities.json import write_formatted_json
 from utilities.logging import get_logging_level_number
 from utilities.math import MAX_INT64, MIN_INT64
 from utilities.types import Dataclass, LogLevel, MaybeIterable, PathLike, StrMapping
+from utilities.typing import is_string_mapping
 from utilities.tzlocal import LOCAL_TIME_ZONE
 from utilities.version import Version, parse_version
-from utilities.whenever import from_timestamp
+from utilities.whenever import (
+    DatePeriod,
+    TimePeriod,
+    ZonedDateTimePeriod,
+    from_timestamp,
+)
 
 if TYPE_CHECKING:
     from collections.abc import Set as AbstractSet
@@ -65,10 +72,11 @@ if TYPE_CHECKING:
 
 
 @unique
-class _Prefixes(Enum):
+class _Prefixes(StrEnum):
     dataclass = "dc"
     date = "d"
     date_delta = "dd"
+    date_period = "dp"
     date_time_delta = "D"
     enum = "e"
     exception_class = "Ex"
@@ -77,7 +85,7 @@ class _Prefixes(Enum):
     frozenset_ = "fr"
     list_ = "l"
     month_day = "md"
-    none = "none"
+    none = "0"
     path = "p"
     plain_date_time = "pd"
     py_date = "!d"
@@ -87,12 +95,14 @@ class _Prefixes(Enum):
     set_ = "s"
     time = "ti"
     time_delta = "td"
+    time_period = "tp"
     tuple_ = "tu"
     unserializable = "un"
     uuid = "uu"
     version = "v"
     year_month = "ym"
     zoned_date_time = "zd"
+    zoned_date_time_period = "zp"
 
 
 type _DataclassHook = Callable[[type[Dataclass], StrMapping], StrMapping]
@@ -167,8 +177,10 @@ def _pre_process(
             return f"[{_Prefixes.date.value}]{date}"
         case DateDelta() as date:
             return f"[{_Prefixes.date_delta.value}]{date}"
-        case DateTimeDelta() as date:
-            return f"[{_Prefixes.date_time_delta.value}]{date}"
+        case DatePeriod() as period:
+            return f"[{_Prefixes.date_period.value}]{period.start},{period.end}"
+        case DateTimeDelta() as date_time_delta:
+            return f"[{_Prefixes.date_time_delta.value}]{date_time_delta}"
         case Exception() as error_:
             return {
                 f"[{_Prefixes.exception_instance.value}|{type(error_).__qualname__}]": pre(
@@ -187,14 +199,16 @@ def _pre_process(
             return f"[{_Prefixes.month_day.value}]{month_day!s}"
         case Path() as path:
             return f"[{_Prefixes.path.value}]{path!s}"
-        case PlainDateTime() as datetime:
-            return f"[{_Prefixes.plain_date_time.value}]{datetime}"
-        case str() as str_:
-            return str_
+        case PlainDateTime() as date_time:
+            return f"[{_Prefixes.plain_date_time.value}]{date_time}"
+        case str() as text:
+            return text
         case Time() as time:
             return f"[{_Prefixes.time.value}]{time}"
         case TimeDelta() as time_delta:
             return f"[{_Prefixes.time_delta.value}]{time_delta}"
+        case TimePeriod() as period:
+            return f"[{_Prefixes.time_period.value}]{period.start},{period.end}"
         case type() as error_cls if issubclass(error_cls, Exception):
             return f"[{_Prefixes.exception_class.value}|{error_cls.__qualname__}]"
         case UUID() as uuid:
@@ -203,8 +217,10 @@ def _pre_process(
             return f"[{_Prefixes.version.value}]{version}"
         case YearMonth() as year_month:
             return f"[{_Prefixes.year_month.value}]{year_month}"
-        case ZonedDateTime() as datetime:
-            return f"[{_Prefixes.zoned_date_time.value}]{datetime}"
+        case ZonedDateTime() as date_time:
+            return f"[{_Prefixes.zoned_date_time.value}]{date_time}"
+        case ZonedDateTimePeriod() as period:
+            return f"[{_Prefixes.zoned_date_time_period.value}]{period.start.to_plain()},{period.end}"
         case dt.datetime() as py_datetime:
             match py_datetime.tzinfo:
                 case None:
@@ -357,8 +373,12 @@ def deserialize(
     redirects: Mapping[str, type[Any]] | None = None,
 ) -> Any:
     """Deserialize an object."""
+    try:
+        obj = loads(data)
+    except JSONDecodeError:
+        raise _DeserializeInvalidJSONError(data=data) from None
     return _object_hook(
-        loads(data),
+        obj,
         data=data,
         dataclass_hook=dataclass_hook,
         objects=objects,
@@ -366,9 +386,15 @@ def deserialize(
     )
 
 
+@dataclass(kw_only=True, slots=True)
+class DeerializeError(Exception):
+    obj: Any
+
+
 (
     _DATE_PATTERN,
     _DATE_DELTA_PATTERN,
+    _DATE_PERIOD_PATTERN,
     _DATE_TIME_DELTA_PATTERN,
     _FLOAT_PATTERN,
     _MONTH_DAY_PATTERN,
@@ -381,15 +407,18 @@ def deserialize(
     _PY_ZONED_DATE_TIME_PATTERN,
     _TIME_PATTERN,
     _TIME_DELTA_PATTERN,
+    _TIME_PERIOD_PATTERN,
     _UUID_PATTERN,
     _VERSION_PATTERN,
     _YEAR_MONTH_PATTERN,
     _ZONED_DATE_TIME_PATTERN,
+    _ZONED_DATE_TIME_PERIOD_PATTERN,
 ) = [
     re.compile(r"^\[" + p.value + r"\](" + ".*" + ")$")
     for p in [
         _Prefixes.date,
         _Prefixes.date_delta,
+        _Prefixes.date_period,
         _Prefixes.date_time_delta,
         _Prefixes.float_,
         _Prefixes.month_day,
@@ -402,10 +431,12 @@ def deserialize(
         _Prefixes.py_zoned_date_time,
         _Prefixes.time,
         _Prefixes.time_delta,
+        _Prefixes.time_period,
         _Prefixes.uuid,
         _Prefixes.version,
         _Prefixes.year_month,
         _Prefixes.zoned_date_time,
+        _Prefixes.zoned_date_time_period,
     ]
 ]
 
@@ -450,39 +481,50 @@ 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_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_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_iso(end)
+                start = PlainDateTime.parse_iso(start).assume_tz(end.tz)
+                return ZonedDateTimePeriod(start, end)
             if (
                 exc_class := _object_hook_exception_class(
                     text, data=data, objects=objects, redirects=redirects
@@ -564,7 +606,7 @@ def _object_hook(
                 )
                 for k, v in mapping.items()
             }
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -708,11 +750,19 @@ def _object_hook_get_object(
 @dataclass(kw_only=True, slots=True)
 class DeserializeError(Exception):
     data: bytes
-    qualname: str
+
+
+@dataclass(kw_only=True, slots=True)
+class _DeserializeInvalidJSONError(DeserializeError):
+    @override
+    def __str__(self) -> str:
+        return f"Invalid JSON: {self.data!r}"
 
 
 @dataclass(kw_only=True, slots=True)
 class _DeserializeNoObjectsError(DeserializeError):
+    qualname: str
+
     @override
     def __str__(self) -> str:
         return f"Objects required to deserialize {self.qualname!r} from {self.data!r}"
@@ -720,6 +770,8 @@ class _DeserializeNoObjectsError(DeserializeError):
 
 @dataclass(kw_only=True, slots=True)
 class _DeserializeObjectNotFoundError(DeserializeError):
+    qualname: str
+
     @override
     def __str__(self) -> str:
         return (
@@ -1006,7 +1058,7 @@ class GetLogRecordsOutput:
                         for r in records
                         if (r.func_name is not None) and search(func_name, r.func_name)
                     ]
-                case _ as never:
+                case never:
                     assert_never(never)
         if extra is not None:
             match extra:
@@ -1019,7 +1071,7 @@ class GetLogRecordsOutput:
                         if (r.extra is not None)
                         and set(r.extra).issuperset(always_iterable(keys))
                     ]
-                case _ as never:
+                case never:
                     assert_never(never)
         if log_file is not None:
             match log_file:
@@ -1034,7 +1086,7 @@ class GetLogRecordsOutput:
                         if (r.log_file is not None)
                         and search(str(log_file), str(r.log_file))
                     ]
-                case _ as never:
+                case never:
                     assert_never(never)
         if log_file_line_num is not None:
             match log_file_line_num:
@@ -1048,7 +1100,7 @@ class GetLogRecordsOutput:
                     records = [
                         r for r in records if r.log_file_line_num == log_file_line_num
                     ]
-                case _ as never:
+                case never:
                     assert_never(never)
         if min_log_file_line_num is not None:
             records = [
@@ -1126,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
@@ -48,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)
 
 
@@ -105,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]
 
@@ -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
@@ -132,6 +166,14 @@ def is_debug() -> bool:
 ##
 
 
+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
@@ -157,12 +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

@@ -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,7 +12,9 @@ from typing import TYPE_CHECKING, Literal, assert_never, overload, override
 
 from utilities.contextlib import enhanced_context_manager
 from utilities.errors import ImpossibleCaseError
-from utilities.sentinel import Sentinel, sentinel
+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
@@ -52,33 +54,22 @@ def expand_path(path: PathLike, /) -> Path:
 ##
 
 
-@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 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 | None = None) -> Path:
+def get_package_root(path: MaybeCallablePathLike = Path.cwd, /) -> Path:
     """Get the package root."""
-    path = get_path(path=path)
+    path = to_path(path)
     path_dir = path.parent if path.is_file() else path
     all_paths = list(chain([path_dir], path_dir.parents))
     try:
@@ -103,9 +94,9 @@ class GetPackageRootError(Exception):
 ##
 
 
-def get_repo_root(*, path: MaybeCallablePathLike | None = None) -> Path:
+def get_repo_root(path: MaybeCallablePathLike = Path.cwd, /) -> Path:
     """Get the repo root."""
-    path = get_path(path=path)
+    path = to_path(path)
     path_dir = path.parent if path.is_file() else path
     try:
         output = check_output(
@@ -118,15 +109,30 @@ def get_repo_root(*, path: MaybeCallablePathLike | None = None) -> Path:
         # newer versions of git report "Not a git repository", whilst older
         # versions report "not a git repository"
         if search("fatal: not a git repository", error.stderr, flags=IGNORECASE):
-            raise GetRepoRootError(path=path) from None
+            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"))
 
 
 @dataclass(kw_only=True, slots=True)
-class GetRepoRootError(Exception):
-    path: PathLike
+class GetRepoRootError(Exception): ...
+
+
+@dataclass(kw_only=True, slots=True)
+class _GetRepoRootGitNotFoundError(GetRepoRootError):
+    @override
+    def __str__(self) -> str:
+        return "'git' not found"
+
+
+@dataclass(kw_only=True, slots=True)
+class _GetRepoRootNotARepoError(GetRepoRootError):
+    path: Path
 
     @override
     def __str__(self) -> str:
@@ -136,15 +142,15 @@ class GetRepoRootError(Exception):
 ##
 
 
-def get_root(*, path: MaybeCallablePathLike | None = None) -> Path:
+def get_root(path: MaybeCallablePathLike = Path.cwd, /) -> Path:
     """Get the root of a path."""
-    path = get_path(path=path)
+    path = to_path(path)
     try:
-        repo = get_repo_root(path=path)
+        repo = get_repo_root(path)
     except GetRepoRootError:
         repo = None
     try:
-        package = get_package_root(path=path)
+        package = get_package_root(path)
     except GetPackageRootError:
         package = None
     match repo, package:
@@ -164,7 +170,7 @@ def get_root(*, path: MaybeCallablePathLike | None = None) -> Path:
             raise ImpossibleCaseError(  # pragma: no cover
                 case=[f"{repo=}", f"{package=}"]
             )
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -213,7 +219,7 @@ def get_tail(
             return _get_tail_core(path, next(iter(matches)))
         case _, "later":
             return _get_tail_core(path, next(iter(reversed(matches))))
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -305,6 +311,30 @@ def temp_cwd(path: PathLike, /) -> Iterator[None]:
         chdir(prev)
 
 
+##
+
+
+@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",
@@ -312,12 +342,14 @@ __all__ = [
     "GetTailError",
     "ensure_suffix",
     "expand_path",
+    "get_file_group",
+    "get_file_owner",
     "get_package_root",
-    "get_path",
     "get_repo_root",
     "get_tail",
     "is_sub_path",
     "list_dir",
     "module_path",
     "temp_cwd",
+    "to_path",
 ]