dycw-utilities 0.135.0__py3-none-any.whl → 0.178.1__py3-none-any.whl

utilities/functions.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
-from collections.abc import Callable, Iterable, Iterator, Sequence
-from dataclasses import asdict, dataclass, is_dataclass
+from collections.abc import Callable, Iterable, Iterator
+from dataclasses import asdict, dataclass
 from functools import _lru_cache_wrapper, cached_property, partial, reduce, wraps
 from inspect import getattr_static
 from pathlib import Path
@@ -19,18 +19,11 @@ from typing import TYPE_CHECKING, Any, Literal, TypeGuard, cast, overload, overr
 from whenever import Date, PlainDateTime, Time, TimeDelta, ZonedDateTime
 
 from utilities.reprlib import get_repr, get_repr_and_class
-from utilities.sentinel import Sentinel, sentinel
-from utilities.types import (
-    Dataclass,
-    Number,
-    StrMapping,
-    SupportsRichComparison,
-    TupleOrStrMapping,
-    TypeLike,
-)
+from utilities.sentinel import Sentinel, is_sentinel, sentinel
+from utilities.types import Dataclass, Number, SupportsRichComparison, TypeLike
 
 if TYPE_CHECKING:
-    from collections.abc import Container, Hashable, Sized
+    from collections.abc import Container
 
 
 def apply_decorators[F1: Callable, F2: Callable](
@@ -230,25 +223,6 @@ class EnsureFloatError(Exception):
 ##
 
 
-def ensure_hashable(obj: Any, /) -> Hashable:
-    """Ensure an object is hashable."""
-    if is_hashable(obj):
-        return obj
-    raise EnsureHashableError(obj=obj)
-
-
-@dataclass(kw_only=True, slots=True)
-class EnsureHashableError(Exception):
-    obj: Any
-
-    @override
-    def __str__(self) -> str:
-        return _make_error_msg(self.obj, "hashable")
-
-
-##
-
-
 @overload
 def ensure_int(obj: Any, /, *, nullable: bool) -> int | None: ...
 @overload
@@ -405,44 +379,6 @@ class EnsurePlainDateTimeError(Exception):
 ##
 
 
-def ensure_sized(obj: Any, /) -> Sized:
-    """Ensure an object is sized."""
-    if is_sized(obj):
-        return obj
-    raise EnsureSizedError(obj=obj)
-
-
-@dataclass(kw_only=True, slots=True)
-class EnsureSizedError(Exception):
-    obj: Any
-
-    @override
-    def __str__(self) -> str:
-        return _make_error_msg(self.obj, "sized")
-
-
-##
-
-
-def ensure_sized_not_str(obj: Any, /) -> Sized:
-    """Ensure an object is sized, but not a string."""
-    if is_sized_not_str(obj):
-        return obj
-    raise EnsureSizedNotStrError(obj=obj)
-
-
-@dataclass(kw_only=True, slots=True)
-class EnsureSizedNotStrError(Exception):
-    obj: Any
-
-    @override
-    def __str__(self) -> str:
-        return _make_error_msg(self.obj, "sized and not a string")
-
-
-##
-
-
 @overload
 def ensure_str(obj: Any, /, *, nullable: bool) -> str | None: ...
 @overload
@@ -633,67 +569,7 @@ def identity[T](obj: T, /) -> T:
 ##
 
 
-def is_dataclass_class(obj: Any, /) -> TypeGuard[type[Dataclass]]:
-    """Check if an object is a dataclass."""
-    return isinstance(obj, type) and is_dataclass(obj)
-
-
-##
-
-
-def is_dataclass_instance(obj: Any, /) -> TypeGuard[Dataclass]:
-    """Check if an object is an instance of a dataclass."""
-    return (not isinstance(obj, type)) and is_dataclass(obj)
-
-
-##
-
-
-def is_hashable(obj: Any, /) -> TypeGuard[Hashable]:
-    """Check if an object is hashable."""
-    try:
-        _ = hash(obj)
-    except TypeError:
-        return False
-    return True
-
-
-##
-
-
-@overload
-def is_iterable_of[T](obj: Any, cls: type[T], /) -> TypeGuard[Iterable[T]]: ...
-@overload
-def is_iterable_of[T1](
-    obj: Any, cls: tuple[type[T1]], /
-) -> TypeGuard[Iterable[T1]]: ...
-@overload
-def is_iterable_of[T1, T2](
-    obj: Any, cls: tuple[type[T1], type[T2]], /
-) -> TypeGuard[Iterable[T1 | T2]]: ...
-@overload
-def is_iterable_of[T1, T2, T3](
-    obj: Any, cls: tuple[type[T1], type[T2], type[T3]], /
-) -> TypeGuard[Iterable[T1 | T2 | T3]]: ...
-@overload
-def is_iterable_of[T1, T2, T3, T4](
-    obj: Any, cls: tuple[type[T1], type[T2], type[T3], type[T4]], /
-) -> TypeGuard[Iterable[T1 | T2 | T3 | T4]]: ...
-@overload
-def is_iterable_of[T1, T2, T3, T4, T5](
-    obj: Any, cls: tuple[type[T1], type[T2], type[T3], type[T4], type[T5]], /
-) -> TypeGuard[Iterable[T1 | T2 | T3 | T4 | T5]]: ...
-@overload
-def is_iterable_of[T](obj: Any, cls: TypeLike[T], /) -> TypeGuard[Iterable[T]]: ...
-def is_iterable_of[T](obj: Any, cls: TypeLike[T], /) -> TypeGuard[Iterable[T]]:
-    """Check if an object is a iterable of tuple or string mappings."""
-    return isinstance(obj, Iterable) and all(map(make_isinstance(cls), obj))
-
-
-##
-
-
-def is_none(obj: Any, /) -> bool:
+def is_none(obj: Any, /) -> TypeGuard[None]:
     """Check if an object is `None`."""
     return obj is None
 
@@ -709,126 +585,6 @@ def is_not_none(obj: Any, /) -> bool:
 ##
 
 
-@overload
-def is_sequence_of[T](obj: Any, cls: type[T], /) -> TypeGuard[Sequence[T]]: ...
-@overload
-def is_sequence_of[T1](
-    obj: Any, cls: tuple[type[T1]], /
-) -> TypeGuard[Sequence[T1]]: ...
-@overload
-def is_sequence_of[T1, T2](
-    obj: Any, cls: tuple[type[T1], type[T2]], /
-) -> TypeGuard[Sequence[T1 | T2]]: ...
-@overload
-def is_sequence_of[T1, T2, T3](
-    obj: Any, cls: tuple[type[T1], type[T2], type[T3]], /
-) -> TypeGuard[Sequence[T1 | T2 | T3]]: ...
-@overload
-def is_sequence_of[T1, T2, T3, T4](
-    obj: Any, cls: tuple[type[T1], type[T2], type[T3], type[T4]], /
-) -> TypeGuard[Sequence[T1 | T2 | T3 | T4]]: ...
-@overload
-def is_sequence_of[T1, T2, T3, T4, T5](
-    obj: Any, cls: tuple[type[T1], type[T2], type[T3], type[T4], type[T5]], /
-) -> TypeGuard[Sequence[T1 | T2 | T3 | T4 | T5]]: ...
-@overload
-def is_sequence_of[T](obj: Any, cls: TypeLike[T], /) -> TypeGuard[Sequence[T]]: ...
-def is_sequence_of[T](obj: Any, cls: TypeLike[T], /) -> TypeGuard[Sequence[T]]:
-    """Check if an object is a sequence of tuple or string mappings."""
-    return isinstance(obj, Sequence) and is_iterable_of(obj, cls)
-
-
-##
-
-
-def is_sequence_of_tuple_or_str_mapping(
-    obj: Any, /
-) -> TypeGuard[Sequence[TupleOrStrMapping]]:
-    """Check if an object is a sequence of tuple or string mappings."""
-    return isinstance(obj, Sequence) and all(map(is_tuple_or_str_mapping, obj))
-
-
-##
-
-
-def is_sized(obj: Any, /) -> TypeGuard[Sized]:
-    """Check if an object is sized."""
-    try:
-        _ = len(obj)
-    except TypeError:
-        return False
-    return True
-
-
-##
-
-
-def is_sized_not_str(obj: Any, /) -> TypeGuard[Sized]:
-    """Check if an object is sized, but not a string."""
-    return is_sized(obj) and not isinstance(obj, str)
-
-
-##
-
-
-def is_string_mapping(obj: Any, /) -> TypeGuard[StrMapping]:
-    """Check if an object is a string mapping."""
-    return isinstance(obj, dict) and is_iterable_of(obj, str)
-
-
-##
-
-
-def is_tuple(obj: Any, /) -> TypeGuard[tuple[Any, ...]]:
-    """Check if an object is a tuple or string mapping."""
-    return make_isinstance(tuple)(obj)
-
-
-##
-
-
-def is_tuple_or_str_mapping(obj: Any, /) -> TypeGuard[TupleOrStrMapping]:
-    """Check if an object is a tuple or string mapping."""
-    return is_tuple(obj) or is_string_mapping(obj)
-
-
-##
-
-
-@overload
-def make_isinstance[T](cls: type[T], /) -> Callable[[Any], TypeGuard[T]]: ...
-@overload
-def make_isinstance[T1](cls: tuple[type[T1]], /) -> Callable[[Any], TypeGuard[T1]]: ...
-@overload
-def make_isinstance[T1, T2](
-    cls: tuple[type[T1], type[T2]], /
-) -> Callable[[Any], TypeGuard[T1 | T2]]: ...
-@overload
-def make_isinstance[T1, T2, T3](
-    cls: tuple[type[T1], type[T2], type[T3]], /
-) -> Callable[[Any], TypeGuard[T1 | T2 | T3]]: ...
-@overload
-def make_isinstance[T1, T2, T3, T4](
-    cls: tuple[type[T1], type[T2], type[T3], type[T4]], /
-) -> Callable[[Any], TypeGuard[T1 | T2 | T3 | T4]]: ...
-@overload
-def make_isinstance[T1, T2, T3, T4, T5](
-    cls: tuple[type[T1], type[T2], type[T3], type[T4], type[T5]], /
-) -> Callable[[Any], TypeGuard[T1 | T2 | T3 | T4 | T5]]: ...
-@overload
-def make_isinstance[T](cls: TypeLike[T], /) -> Callable[[Any], TypeGuard[T]]: ...
-def make_isinstance[T](cls: TypeLike[T], /) -> Callable[[Any], TypeGuard[T]]:
-    """Make a curried `isinstance` function."""
-    return partial(_make_instance_core, cls=cls)
-
-
-def _make_instance_core[T](obj: Any, /, *, cls: TypeLike[T]) -> TypeGuard[T]:
-    return isinstance(obj, cls)
-
-
-##
-
-
 def map_object[T](
     func: Callable[[Any], Any], obj: T, /, *, before: Callable[[Any], Any] | None = None
 ) -> T:
@@ -864,7 +620,7 @@ def min_nullable[T: SupportsRichComparison, U](
 ) -> T | U:
     """Compute the minimum of a set of values; ignoring nulls."""
     values = (i for i in iterable if i is not None)
-    if isinstance(default, Sentinel):
+    if is_sentinel(default):
         try:
             return min(values)
         except ValueError:
@@ -894,7 +650,7 @@ def max_nullable[T: SupportsRichComparison, U](
 ) -> T | U:
     """Compute the maximum of a set of values; ignoring nulls."""
     values = (i for i in iterable if i is not None)
-    if isinstance(default, Sentinel):
+    if is_sentinel(default):
         try:
             return max(values)
         except ValueError:
@@ -935,6 +691,21 @@ def second[U](pair: tuple[Any, U], /) -> U:
 ##
 
 
+def skip_if_optimize[**P](func: Callable[P, None], /) -> Callable[P, None]:
+    """Skip a function if we are in the optimized mode."""
+    if __debug__:  # pragma: no cover
+        return func
+
+    @wraps(func)
+    def wrapped(*args: P.args, **kwargs: P.kwargs) -> None:
+        _ = (args, kwargs)
+
+    return wrapped
+
+
+##
+
+
 def yield_object_attributes(
     obj: Any,
     /,
@@ -985,15 +756,12 @@ __all__ = [
     "EnsureClassError",
     "EnsureDateError",
     "EnsureFloatError",
-    "EnsureHashableError",
     "EnsureIntError",
     "EnsureMemberError",
     "EnsureNotNoneError",
     "EnsureNumberError",
     "EnsurePathError",
     "EnsurePlainDateTimeError",
-    "EnsureSizedError",
-    "EnsureSizedNotStrError",
     "EnsureStrError",
     "EnsureTimeDeltaError",
     "EnsureTimeError",
@@ -1006,15 +774,12 @@ __all__ = [
     "ensure_class",
     "ensure_date",
     "ensure_float",
-    "ensure_hashable",
     "ensure_int",
     "ensure_member",
     "ensure_not_none",
     "ensure_number",
     "ensure_path",
     "ensure_plain_date_time",
-    "ensure_sized",
-    "ensure_sized_not_str",
     "ensure_str",
     "ensure_time",
     "ensure_time_delta",
@@ -1025,24 +790,14 @@ __all__ = [
     "get_func_name",
     "get_func_qualname",
     "identity",
-    "is_dataclass_class",
-    "is_dataclass_instance",
-    "is_hashable",
-    "is_iterable_of",
     "is_none",
     "is_not_none",
-    "is_sequence_of_tuple_or_str_mapping",
-    "is_sized",
-    "is_sized_not_str",
-    "is_string_mapping",
-    "is_tuple",
-    "is_tuple_or_str_mapping",
-    "make_isinstance",
     "map_object",
     "max_nullable",
     "min_nullable",
     "not_func",
     "second",
+    "skip_if_optimize",
     "yield_object_attributes",
     "yield_object_cached_properties",
     "yield_object_properties",

utilities/git.py

@@ -1,40 +1,19 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
 from pathlib import Path
-from re import IGNORECASE, search
-from subprocess import PIPE, CalledProcessError, check_output
-from typing import TYPE_CHECKING, override
+from typing import TYPE_CHECKING
 
-from utilities.pathlib import PWD
-
-if TYPE_CHECKING:
-    from utilities.types import PathLike
+from git import Repo
 
+from utilities.pathlib import to_path
 
-def get_repo_root(*, path: PathLike = PWD) -> Path:
-    """Get the repo root."""
-    try:
-        output = check_output(
-            ["git", "rev-parse", "--show-toplevel"], stderr=PIPE, cwd=path, text=True
-        )
-    except CalledProcessError as error:
-        # 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(cwd=path) from error
-        raise  # pragma: no cover
-    else:
-        return Path(output.strip("\n"))
-
+if TYPE_CHECKING:
+    from utilities.types import MaybeCallablePathLike
 
-@dataclass(kw_only=True, slots=True)
-class GetRepoRootError(Exception):
-    cwd: PathLike
 
-    @override
-    def __str__(self) -> str:
-        return f"Path is not part of a `git` repository: {self.cwd}"
+def get_repo(path: MaybeCallablePathLike = Path.cwd, /) -> Repo:
+    """Get the repo object."""
+    return Repo(to_path(path), search_parent_directories=True)
 
 
-__all__ = ["GetRepoRootError", "get_repo_root"]
+__all__ = ["get_repo"]

utilities/grp.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import assert_never
+
+from utilities.os import EFFECTIVE_GROUP_ID
+from utilities.platform import SYSTEM
+
+
+def get_gid_name(gid: int, /) -> str | None:
+    """Get the name of a group."""
+    match SYSTEM:
+        case "windows":  # skipif-not-windows
+            return None
+        case "mac" | "linux":
+            from grp import getgrgid
+
+            return getgrgid(gid).gr_name
+        case never:
+            assert_never(never)
+
+
+ROOT_GROUP_NAME = get_gid_name(0)
+EFFECTIVE_GROUP_NAME = (
+    None if EFFECTIVE_GROUP_ID is None else get_gid_name(EFFECTIVE_GROUP_ID)
+)
+
+
+__all__ = ["EFFECTIVE_GROUP_NAME", "ROOT_GROUP_NAME", "get_gid_name"]

utilities/gzip.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import gzip
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from utilities.atomicwrites import writer
+
+if TYPE_CHECKING:
+    from utilities.types import PathLike
+
+
+def read_binary(path: PathLike, /, *, decompress: bool = False) -> bytes:
+    """Read a byte string from disk."""
+    path = Path(path)
+    if decompress:
+        with gzip.open(path) as gz:
+            return gz.read()
+    else:
+        return path.read_bytes()
+
+
+def write_binary(
+    data: bytes, path: PathLike, /, *, compress: bool = False, overwrite: bool = False
+) -> None:
+    """Write a byte string to disk."""
+    with writer(path, compress=compress, overwrite=overwrite) as temp:
+        _ = temp.write_bytes(data)
+
+
+__all__ = ["read_binary", "write_binary"]

utilities/http.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
-from contextlib import contextmanager
 from http.client import HTTPSConnection
 from ipaddress import IPv4Address
 from typing import TYPE_CHECKING
 
+from utilities.contextlib import enhanced_context_manager
+
 if TYPE_CHECKING:
     from collections.abc import Iterator
 
@@ -21,7 +22,7 @@ def get_public_ip(*, timeout: float | None = None) -> IPv4Address:
 ##
 
 
-@contextmanager
+@enhanced_context_manager
 def yield_connection(
     host: str, /, *, timeout: float | None = None
 ) -> Iterator[HTTPSConnection]: