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

utilities/functions.py

@@ -1,43 +1,20 @@
 from __future__ import annotations
 
-from collections.abc import Callable, Iterable, Iterator
-from dataclasses import asdict, dataclass
-from functools import _lru_cache_wrapper, cached_property, partial, reduce, wraps
+from dataclasses import dataclass
+from functools import wraps
 from inspect import getattr_static
 from pathlib import Path
-from re import findall
-from types import (
-    BuiltinFunctionType,
-    FunctionType,
-    MethodDescriptorType,
-    MethodType,
-    MethodWrapperType,
-    WrapperDescriptorType,
-)
-from typing import TYPE_CHECKING, Any, Literal, TypeGuard, cast, overload, override
+from typing import TYPE_CHECKING, Any, Literal, assert_never, overload, override
 
 from whenever import Date, PlainDateTime, Time, TimeDelta, ZonedDateTime
 
-from utilities.reprlib import get_repr, get_repr_and_class
-from utilities.sentinel import Sentinel, is_sentinel, sentinel
-from utilities.types import Dataclass, Number, SupportsRichComparison, TypeLike
+from utilities.constants import SECOND
+from utilities.core import get_class_name, repr_, repr_str
 
 if TYPE_CHECKING:
-    from collections.abc import Container
+    from collections.abc import Callable, Container, Iterable, Iterator
 
-
-def apply_decorators[F1: Callable, F2: Callable](
-    func: F1, /, *decorators: Callable[[F2], F2]
-) -> F1:
-    """Apply a set of decorators to a function."""
-    return reduce(_apply_decorators_one, decorators, func)
-
-
-def _apply_decorators_one[F: Callable](acc: F, el: Callable[[Any], Any], /) -> F:
-    return el(acc)
-
-
-##
+    from utilities.types import Duration, Number, TypeLike
 
 
 @overload
@@ -274,7 +251,7 @@ class EnsureMemberError(Exception):
     @override
     def __str__(self) -> str:
         return _make_error_msg(
-            self.obj, f"a member of {get_repr(self.container)}", nullable=self.nullable
+            self.obj, f"a member of {repr_(self.container)}", nullable=self.nullable
         )
 
 
@@ -485,207 +462,31 @@ class EnsureZonedDateTimeError(Exception):
 ##
 
 
-def first[T](pair: tuple[T, Any], /) -> T:
-    """Get the first element in a pair."""
-    return pair[0]
-
-
-##
-
-
-@overload
-def get_class[T](obj: type[T], /) -> type[T]: ...
-@overload
-def get_class[T](obj: T, /) -> type[T]: ...
-def get_class[T](obj: T | type[T], /) -> type[T]:
-    """Get the class of an object, unless it is already a class."""
-    return obj if isinstance(obj, type) else type(obj)
-
-
-##
-
-
-def get_class_name(obj: Any, /, *, qual: bool = False) -> str:
-    """Get the name of the class of an object, unless it is already a class."""
-    cls = get_class(obj)
-    return f"{cls.__module__}.{cls.__qualname__}" if qual else cls.__name__
+def in_milli_seconds(duration: Duration, /) -> float:
+    """Convert a duration to milli-seconds."""
+    return 1e3 * in_seconds(duration)
 
 
-##
-
-
-def get_func_name(obj: Callable[..., Any], /) -> str:
-    """Get the name of a callable."""
-    if isinstance(obj, BuiltinFunctionType):
-        return obj.__name__
-    if isinstance(obj, FunctionType):
-        name = obj.__name__
-        pattern = r"^.+\.([A-Z]\w+\." + name + ")$"
-        try:
-            (full_name,) = findall(pattern, obj.__qualname__)
-        except ValueError:
-            return name
-        return full_name
-    if isinstance(obj, MethodType):
-        return f"{get_class_name(obj.__self__)}.{obj.__name__}"
-    if isinstance(
-        obj,
-        MethodType | MethodDescriptorType | MethodWrapperType | WrapperDescriptorType,
-    ):
-        return obj.__qualname__
-    if isinstance(obj, _lru_cache_wrapper):
-        return cast("Any", obj).__name__
-    if isinstance(obj, partial):
-        return get_func_name(obj.func)
-    return get_class_name(obj)
-
-
-##
+def in_seconds(duration: Duration, /) -> float:
+    """Convert a duration to seconds."""
+    match duration:
+        case int() | float():
+            return duration
+        case TimeDelta():
+            return duration.in_seconds()
+        case never:
+            assert_never(never)
 
 
-def get_func_qualname(obj: Callable[..., Any], /) -> str:
-    """Get the qualified name of a callable."""
-    if isinstance(
-        obj, BuiltinFunctionType | FunctionType | MethodType | _lru_cache_wrapper
-    ):
-        return f"{obj.__module__}.{obj.__qualname__}"
-    if isinstance(
-        obj, MethodDescriptorType | MethodWrapperType | WrapperDescriptorType
-    ):
-        return f"{obj.__objclass__.__module__}.{obj.__qualname__}"
-    if isinstance(obj, partial):
-        return get_func_qualname(obj.func)
-    return f"{obj.__module__}.{get_class_name(obj)}"
-
-
-##
-
-
-def identity[T](obj: T, /) -> T:
-    """Return the object itself."""
-    return obj
-
-
-##
-
-
-def is_none(obj: Any, /) -> TypeGuard[None]:
-    """Check if an object is `None`."""
-    return obj is None
-
-
-##
-
-
-def is_not_none(obj: Any, /) -> bool:
-    """Check if an object is not `None`."""
-    return obj is not None
-
-
-##
-
-
-def map_object[T](
-    func: Callable[[Any], Any], obj: T, /, *, before: Callable[[Any], Any] | None = None
-) -> T:
-    """Map a function over an object, across a variety of structures."""
-    if before is not None:
-        obj = before(obj)
-    match obj:
-        case dict():
-            return type(obj)({
-                k: map_object(func, v, before=before) for k, v in obj.items()
-            })
-        case frozenset() | list() | set() | tuple():
-            return type(obj)(map_object(func, i, before=before) for i in obj)
-        case Dataclass():
-            return map_object(func, asdict(obj), before=before)
-        case _:
-            return func(obj)
-
-
-##
-
-
-@overload
-def min_nullable[T: SupportsRichComparison](
-    iterable: Iterable[T | None], /, *, default: Sentinel = ...
-) -> T: ...
-@overload
-def min_nullable[T: SupportsRichComparison, U](
-    iterable: Iterable[T | None], /, *, default: U = ...
-) -> T | U: ...
-def min_nullable[T: SupportsRichComparison, U](
-    iterable: Iterable[T | None], /, *, default: U | Sentinel = sentinel
-) -> T | U:
-    """Compute the minimum of a set of values; ignoring nulls."""
-    values = (i for i in iterable if i is not None)
-    if is_sentinel(default):
-        try:
-            return min(values)
-        except ValueError:
-            raise MinNullableError(values=values) from None
-    return min(values, default=default)
-
-
-@dataclass(kw_only=True, slots=True)
-class MinNullableError[T: SupportsRichComparison](Exception):
-    values: Iterable[T]
-
-    @override
-    def __str__(self) -> str:
-        return "Minimum of an all-None iterable is undefined"
-
-
-@overload
-def max_nullable[T: SupportsRichComparison](
-    iterable: Iterable[T | None], /, *, default: Sentinel = ...
-) -> T: ...
-@overload
-def max_nullable[T: SupportsRichComparison, U](
-    iterable: Iterable[T | None], /, *, default: U = ...
-) -> T | U: ...
-def max_nullable[T: SupportsRichComparison, U](
-    iterable: Iterable[T | None], /, *, default: U | Sentinel = sentinel
-) -> T | U:
-    """Compute the maximum of a set of values; ignoring nulls."""
-    values = (i for i in iterable if i is not None)
-    if is_sentinel(default):
-        try:
-            return max(values)
-        except ValueError:
-            raise MaxNullableError(values=values) from None
-    return max(values, default=default)
-
-
-@dataclass(kw_only=True, slots=True)
-class MaxNullableError[TSupportsRichComparison](Exception):
-    values: Iterable[TSupportsRichComparison]
-
-    @override
-    def __str__(self) -> str:
-        return "Maximum of an all-None iterable is undefined"
-
-
-##
-
-
-def not_func[**P](func: Callable[P, bool], /) -> Callable[P, bool]:
-    """Lift a boolean-valued function to return its conjugation."""
-
-    @wraps(func)
-    def wrapped(*args: P.args, **kwargs: P.kwargs) -> bool:
-        return not func(*args, **kwargs)
-
-    return wrapped
-
-
-##
-
-
-def second[U](pair: tuple[Any, U], /) -> U:
-    """Get the second element in a pair."""
-    return pair[1]
+def in_timedelta(duration: Duration, /) -> TimeDelta:
+    """Convert a duration to a timedelta."""
+    match duration:
+        case int() | float():
+            return duration * SECOND
+        case TimeDelta():
+            return duration
+        case never:
+            assert_never(never)
 
 
 ##
@@ -693,7 +494,7 @@ 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__:
+    if __debug__:  # pragma: no cover
         return func
 
     @wraps(func)
@@ -726,25 +527,8 @@ def yield_object_attributes(
 ##
 
 
-def yield_object_properties(
-    obj: Any, /, *, skip: Iterable[str] | None = None
-) -> Iterator[tuple[str, Any]]:
-    """Yield all the object properties."""
-    yield from yield_object_attributes(obj, skip=skip, static_type=property)
-
-
-def yield_object_cached_properties(
-    obj: Any, /, *, skip: Iterable[str] | None = None
-) -> Iterator[tuple[str, Any]]:
-    """Yield all the object cached properties."""
-    yield from yield_object_attributes(obj, skip=skip, static_type=cached_property)
-
-
-##
-
-
 def _make_error_msg(obj: Any, desc: str, /, *, nullable: bool = False) -> str:
-    msg = f"{get_repr_and_class(obj)} must be {desc}"
+    msg = f"Object {repr_str(obj)} of type {get_class_name(obj)!r} must be {desc}"
     if nullable:
         msg += " or None"
     return msg
@@ -766,9 +550,6 @@ __all__ = [
     "EnsureTimeDeltaError",
     "EnsureTimeError",
     "EnsureZonedDateTimeError",
-    "MaxNullableError",
-    "MinNullableError",
-    "apply_decorators",
     "ensure_bool",
     "ensure_bytes",
     "ensure_class",
@@ -784,21 +565,9 @@ __all__ = [
     "ensure_time",
     "ensure_time_delta",
     "ensure_zoned_date_time",
-    "first",
-    "get_class",
-    "get_class_name",
-    "get_func_name",
-    "get_func_qualname",
-    "identity",
-    "is_none",
-    "is_not_none",
-    "map_object",
-    "max_nullable",
-    "min_nullable",
-    "not_func",
-    "second",
+    "in_milli_seconds",
+    "in_seconds",
+    "in_timedelta",
     "skip_if_optimize",
     "yield_object_attributes",
-    "yield_object_cached_properties",
-    "yield_object_properties",
 ]

utilities/http.py

@@ -1,11 +1,10 @@
 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
 
@@ -22,7 +21,7 @@ def get_public_ip(*, timeout: float | None = None) -> IPv4Address:
 ##
 
 
-@enhanced_context_manager
+@contextmanager
 def yield_connection(
     host: str, /, *, timeout: float | None = None
 ) -> Iterator[HTTPSConnection]:

utilities/hypothesis.py

@@ -51,8 +51,13 @@ from whenever import (
     ZonedDateTime,
 )
 
-from utilities.functions import ensure_int, ensure_str, max_nullable, min_nullable
-from utilities.math import (
+from utilities.constants import (
+    DATE_DELTA_MAX,
+    DATE_DELTA_MIN,
+    DATE_TIME_DELTA_MAX,
+    DATE_TIME_DELTA_MIN,
+    DAY,
+    IS_LINUX,
     MAX_FLOAT32,
     MAX_FLOAT64,
     MAX_INT8,
@@ -73,37 +78,42 @@ from utilities.math import (
     MIN_UINT16,
     MIN_UINT32,
     MIN_UINT64,
-    is_zero,
+    TEMP_DIR,
+    TIME_DELTA_MAX,
+    TIME_DELTA_MIN,
+    UTC,
+    Sentinel,
+    sentinel,
+)
+from utilities.core import (
+    Permissions,
+    TemporaryDirectory,
+    get_env,
+    get_now,
+    is_sentinel,
+    max_nullable,
+    min_nullable,
+    to_zone_info,
+    yield_temp_cwd,
 )
-from utilities.os import get_env_var
-from utilities.pathlib import module_path, temp_cwd
-from utilities.platform import IS_LINUX, IS_WINDOWS
-from utilities.sentinel import Sentinel, is_sentinel, sentinel
-from utilities.tempfile import TEMP_DIR, TemporaryDirectory
-from utilities.version import Version
+from utilities.functions import ensure_int, ensure_str
+from utilities.math import is_zero
+from utilities.pathlib import module_path
+from utilities.version import Version2, Version3
 from utilities.whenever import (
-    DATE_DELTA_MAX,
-    DATE_DELTA_MIN,
     DATE_DELTA_PARSABLE_MAX,
     DATE_DELTA_PARSABLE_MIN,
-    DATE_TIME_DELTA_MAX,
-    DATE_TIME_DELTA_MIN,
     DATE_TIME_DELTA_PARSABLE_MAX,
     DATE_TIME_DELTA_PARSABLE_MIN,
     DATE_TWO_DIGIT_YEAR_MAX,
     DATE_TWO_DIGIT_YEAR_MIN,
-    DAY,
-    TIME_DELTA_MAX,
-    TIME_DELTA_MIN,
     DatePeriod,
     TimePeriod,
     ZonedDateTimePeriod,
-    get_now,
     to_date_time_delta,
     to_days,
     to_nanoseconds,
 )
-from utilities.zoneinfo import UTC, to_zone_info
 
 if TYPE_CHECKING:
     from collections.abc import Collection, Hashable, Iterable, Iterator
@@ -553,7 +563,7 @@ def floats_extra(
 @composite
 def git_repos(draw: DrawFn, /) -> Path:
     path = draw(temp_paths())
-    with temp_cwd(path):
+    with yield_temp_cwd(path):
         _ = check_call(["git", "init", "-b", "master"])
         _ = check_call(["git", "config", "user.name", "User"])
         _ = check_call(["git", "config", "user.email", "a@z.com"])
@@ -864,6 +874,38 @@ def _path_parts(draw: DrawFn, /) -> str:
 ##
 
 
+@composite
+def permissions(
+    draw: DrawFn,
+    /,
+    *,
+    user_read: MaybeSearchStrategy[bool | None] = None,
+    user_write: MaybeSearchStrategy[bool | None] = None,
+    user_execute: MaybeSearchStrategy[bool | None] = None,
+    group_read: MaybeSearchStrategy[bool | None] = None,
+    group_write: MaybeSearchStrategy[bool | None] = None,
+    group_execute: MaybeSearchStrategy[bool | None] = None,
+    others_read: MaybeSearchStrategy[bool | None] = None,
+    others_write: MaybeSearchStrategy[bool | None] = None,
+    others_execute: MaybeSearchStrategy[bool | None] = None,
+) -> Permissions:
+    """Strategy for generating `Permissions`."""
+    return Permissions(
+        user_read=draw2(draw, user_read, booleans()),
+        user_write=draw2(draw, user_write, booleans()),
+        user_execute=draw2(draw, user_execute, booleans()),
+        group_read=draw2(draw, group_read, booleans()),
+        group_write=draw2(draw, group_write, booleans()),
+        group_execute=draw2(draw, group_execute, booleans()),
+        others_read=draw2(draw, others_read, booleans()),
+        others_write=draw2(draw, others_write, booleans()),
+        others_execute=draw2(draw, others_execute, booleans()),
+    )
+
+
+##
+
+
 @composite
 def plain_date_times(
     draw: DrawFn,
@@ -1007,7 +1049,7 @@ def setup_hypothesis_profiles(
                     assert_never(never)
 
     phases = {Phase.explicit, Phase.reuse, Phase.generate, Phase.target}
-    if "HYPOTHESIS_NO_SHRINK" not in environ:
+    if "HYPOTHESIS_NO_SHRINK" not in environ:  # pragma: no cover
         phases.add(Phase.shrink)
     for profile in Profile:
         try:
@@ -1024,7 +1066,7 @@ def setup_hypothesis_profiles(
             suppress_health_check=suppress_health_check,
             verbosity=profile.verbosity,
         )
-    profile = get_env_var("HYPOTHESIS_PROFILE", default=Profile.default.name)
+    profile = get_env("HYPOTHESIS_PROFILE", default=Profile.default.name)
     settings.load_profile(profile)
 
 
@@ -1128,9 +1170,7 @@ def temp_dirs(draw: DrawFn, /) -> TemporaryDirectory:
     """Search strategy for temporary directories."""
     _TEMP_DIR_HYPOTHESIS.mkdir(exist_ok=True)
     uuid = draw(uuids())
-    return TemporaryDirectory(
-        prefix=f"{uuid}__", dir=_TEMP_DIR_HYPOTHESIS, ignore_cleanup_errors=IS_WINDOWS
-    )
+    return TemporaryDirectory(prefix=f"{uuid}__", dir=_TEMP_DIR_HYPOTHESIS)
 
 
 ##
@@ -1453,12 +1493,25 @@ def urls(
 
 
 @composite
-def versions(draw: DrawFn, /, *, suffix: MaybeSearchStrategy[bool] = False) -> Version:
-    """Strategy for generating versions."""
+def version2s(
+    draw: DrawFn, /, *, suffix: MaybeSearchStrategy[bool] = False
+) -> Version2:
+    """Strategy for generating Version2 objects."""
+    major, minor = draw(pairs(integers(min_value=0)))
+    _ = assume((major >= 1) or (minor >= 1))
+    suffix_use = draw(text_ascii(min_size=1)) if draw2(draw, suffix) else None
+    return Version2(major=major, minor=minor, suffix=suffix_use)
+
+
+@composite
+def version3s(
+    draw: DrawFn, /, *, suffix: MaybeSearchStrategy[bool] = False
+) -> Version3:
+    """Strategy for generating Version3 objects."""
     major, minor, patch = draw(triples(integers(min_value=0)))
     _ = assume((major >= 1) or (minor >= 1) or (patch >= 1))
     suffix_use = draw(text_ascii(min_size=1)) if draw2(draw, suffix) else None
-    return Version(major=major, minor=minor, patch=patch, suffix=suffix_use)
+    return Version3(major=major, minor=minor, patch=patch, suffix=suffix_use)
 
 
 ##
@@ -1570,7 +1623,7 @@ def zoned_date_times(
     with (
         assume_does_not_raise(RepeatedTime),
         assume_does_not_raise(SkippedTime),
-        assume_does_not_raise(ValueError, match=r"Resulting datetime is out of range"),
+        assume_does_not_raise(ValueError, match=r"Resulting time is out of range"),
     ):
         zoned = plain.assume_tz(time_zone_.key, disambiguate="raise")
     with assume_does_not_raise(OverflowError, match=r"date value out of range"):
@@ -1613,6 +1666,7 @@ __all__ = [
     "numbers",
     "pairs",
     "paths",
+    "permissions",
     "plain_date_times",
     "py_datetimes",
     "quadruples",
@@ -1639,7 +1693,8 @@ __all__ = [
     "uint32s",
     "uint64s",
     "urls",
-    "versions",
+    "version2s",
+    "version3s",
     "year_months",
     "zone_infos",
     "zoned_date_time_periods",

utilities/importlib.py

@@ -1,7 +1,23 @@
 from __future__ import annotations
 
+import importlib.resources
 from importlib import import_module
 from importlib.util import find_spec
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from utilities.errors import ImpossibleCaseError
+
+if TYPE_CHECKING:
+    from importlib.resources import Anchor
+
+
+def files(*, anchor: Anchor | None = None) -> Path:
+    """Get the path for an anchor."""
+    path = importlib.resources.files(anchor)
+    if isinstance(path, Path):
+        return path
+    raise ImpossibleCaseError(case=[f"{path=}"])  # pragma: no cover
 
 
 def is_valid_import(module: str, /, *, name: str | None = None) -> bool:
@@ -15,4 +31,4 @@ def is_valid_import(module: str, /, *, name: str | None = None) -> bool:
     return hasattr(mod, name)
 
 
-__all__ = ["is_valid_import"]
+__all__ = ["files", "is_valid_import"]