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

utilities/atools.py

@@ -1,14 +1,17 @@
 from __future__ import annotations
 
 from collections.abc import Callable
-from typing import TYPE_CHECKING, Any
+from functools import partial
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast, overload
 
-from atools import memoize
+import atools
+from whenever import TimeDelta
 
-from utilities.types import Coro
+from utilities.types import Coro, PathLike
 
 if TYPE_CHECKING:
-    from whenever import TimeDelta
+    from atools._memoize_decorator import Keygen, Pickler
 
 
 type _Key[**P, T] = tuple[Callable[P, Coro[T]], TimeDelta]
@@ -36,4 +39,61 @@ async def call_memoized[**P, T](
     return await memoized_func(*args, **kwargs)
 
 
+##
+
+
+@overload
+def memoize[F: Callable[..., Coro[Any]]](
+    func: F,
+    /,
+    *,
+    db_path: PathLike | None = None,
+    duration: float | TimeDelta | None = None,
+    keygen: Keygen | None = None,
+    pickler: Pickler | None = None,
+    size: int | None = None,
+) -> F: ...
+@overload
+def memoize[F: Callable[..., Coro[Any]]](
+    func: None = None,
+    /,
+    *,
+    db_path: PathLike | None = None,
+    duration: float | TimeDelta | None = None,
+    keygen: Keygen | None = None,
+    pickler: Pickler | None = None,
+    size: int | None = None,
+) -> Callable[[F], F]: ...
+def memoize[F: Callable[..., Coro[Any]]](
+    func: F | None = None,
+    /,
+    *,
+    db_path: PathLike | None = None,
+    duration: float | TimeDelta | None = None,
+    keygen: Keygen | None = None,
+    pickler: Pickler | None = None,
+    size: int | None = None,
+) -> F | Callable[[F], F]:
+    """Memoize a function."""
+    if func is None:
+        result = partial(
+            memoize,
+            db_path=db_path,
+            duration=duration,
+            keygen=keygen,
+            pickler=pickler,
+            size=size,
+        )
+        return cast("Callable[[F], F]", result)
+    return atools.memoize(
+        db_path=None if db_path is None else Path(db_path),
+        duration=duration.py_timedelta()
+        if isinstance(duration, TimeDelta)
+        else duration,
+        keygen=keygen,
+        pickler=pickler,
+        size=size,
+    )(func)
+
+
 __all__ = ["call_memoized"]

utilities/cachetools.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from collections.abc import Callable, Hashable, Iterable, Iterator, MutableSet
 from math import inf
 from time import monotonic
-from typing import TYPE_CHECKING, Any, override
+from typing import TYPE_CHECKING, Any, cast, override
 
 import cachetools
 from cachetools.func import ttl_cache
@@ -100,11 +100,14 @@ def cache[F: Callable](
     typed_: bool = False,
 ) -> Callable[[F], F]:
     """Decorate a function with `max_size` and/or `ttl` settings."""
-    return ttl_cache(
-        maxsize=inf if max_size is None else max_size,
-        ttl=inf if max_duration is None else max_duration.in_seconds(),
-        timer=timer,
-        typed=typed_,
+    return cast(
+        "F",
+        ttl_cache(
+            maxsize=max_size,
+            ttl=inf if max_duration is None else max_duration.in_seconds(),
+            timer=timer,
+            typed=typed_,
+        ),
     )
 
 

utilities/click.py

@@ -3,21 +3,22 @@ from __future__ import annotations
 import enum
 import ipaddress
 import pathlib
+import uuid
+from enum import StrEnum
 from typing import TYPE_CHECKING, TypedDict, assert_never, override
 
-import click
 import whenever
 from click import Choice, Context, Parameter, ParamType
 from click.types import IntParamType, StringParamType
 
 from utilities.enum import EnsureEnumError, ensure_enum
-from utilities.functions import EnsureStrError, ensure_str, get_class_name
-from utilities.iterables import is_iterable_not_str
+from utilities.functions import EnsureStrError, ensure_str, get_class, get_class_name
+from utilities.iterables import is_iterable_not_str, one_unique
 from utilities.parse import ParseObjectError, parse_object
 from utilities.text import split_str
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable, Sequence
+    from collections.abc import Iterable
 
     from utilities.types import (
         DateDeltaLike,
@@ -28,6 +29,7 @@ if TYPE_CHECKING:
         IPv6AddressLike,
         MaybeStr,
         MonthDayLike,
+        PathLike,
         PlainDateTimeLike,
         TimeDeltaLike,
         TimeLike,
@@ -36,27 +38,23 @@ if TYPE_CHECKING:
     )
 
 
-FilePath = click.Path(file_okay=True, dir_okay=False, path_type=pathlib.Path)
-DirPath = click.Path(file_okay=False, dir_okay=True, path_type=pathlib.Path)
-ExistingFilePath = click.Path(
-    exists=True, file_okay=True, dir_okay=False, path_type=pathlib.Path
-)
-ExistingDirPath = click.Path(
-    exists=True, file_okay=False, dir_okay=True, path_type=pathlib.Path
-)
-
+class _ContextSettings(TypedDict):
+    context_settings: _ContextSettingsInner
 
-class _HelpOptionNames(TypedDict):
-    help_option_names: Sequence[str]
 
+class _ContextSettingsInner(TypedDict):
+    max_content_width: int
+    help_option_names: list[str]
+    show_default: bool
 
-class _ContextSettings(TypedDict):
-    context_settings: _HelpOptionNames
 
-
-CONTEXT_SETTINGS_HELP_OPTION_NAMES = _ContextSettings(
-    context_settings=_HelpOptionNames(help_option_names=["-h", "--help"])
+_MAX_CONTENT_WIDTH = 120
+_CONTEXT_SETTINGS_INNER = _ContextSettingsInner(
+    max_content_width=_MAX_CONTENT_WIDTH,
+    help_option_names=["-h", "--help"],
+    show_default=True,
 )
+CONTEXT_SETTINGS = _ContextSettings(context_settings=_CONTEXT_SETTINGS_INNER)
 
 
 # parameters
@@ -81,10 +79,10 @@ class Date(ParamType):
                 return value
             case str():
                 try:
-                    return whenever.Date.parse_common_iso(value)
+                    return whenever.Date.parse_iso(value)
                 except ValueError as error:
                     self.fail(str(error), param, ctx)
-            case _ as never:
+            case never:
                 assert_never(never)
 
 
@@ -107,10 +105,10 @@ class DateDelta(ParamType):
                 return value
             case str():
                 try:
-                    return whenever.DateDelta.parse_common_iso(value)
+                    return whenever.DateDelta.parse_iso(value)
                 except ValueError as error:
                     self.fail(str(error), param, ctx)
-            case _ as never:
+            case never:
                 assert_never(never)
 
 
@@ -133,10 +131,10 @@ class DateTimeDelta(ParamType):
                 return value
             case str():
                 try:
-                    return whenever.DateTimeDelta.parse_common_iso(value)
+                    return whenever.DateTimeDelta.parse_iso(value)
                 except ValueError as error:
                     self.fail(str(error), param, ctx)
-            case _ as never:
+            case never:
                 assert_never(never)
 
 
@@ -144,10 +142,13 @@ class Enum[E: enum.Enum](ParamType):
     """An enum-valued parameter."""
 
     @override
-    def __init__(self, enum: type[E], /, *, case_sensitive: bool = False) -> None:
+    def __init__(
+        self, enum: type[E], /, *, value: bool = False, case_sensitive: bool = False
+    ) -> None:
         cls = get_class_name(enum)
         self.name = f"enum[{cls}]"
         self._enum = enum
+        self._value = issubclass(self._enum, StrEnum) or value
         self._case_sensitive = case_sensitive
         super().__init__()
 
@@ -169,7 +170,53 @@ class Enum[E: enum.Enum](ParamType):
     @override
     def get_metavar(self, param: Parameter, ctx: Context) -> str | None:
         _ = ctx
-        desc = ",".join(e.name for e in self._enum)
+        desc = ",".join(str(e.value) if self._value else e.name for e in self._enum)
+        return _make_metavar(param, desc)
+
+
+class EnumPartial[E: enum.Enum](ParamType):
+    """An enum-valued parameter."""
+
+    @override
+    def __init__(
+        self,
+        members: Iterable[E],
+        /,
+        *,
+        value: bool = False,
+        case_sensitive: bool = False,
+    ) -> None:
+        self._members = list(members)
+        self._enum = one_unique(get_class(e) for e in self._members)
+        cls = get_class_name(self._enum)
+        self.name = f"enum-partial[{cls}]"
+        self._value = issubclass(self._enum, StrEnum) or value
+        self._case_sensitive = case_sensitive
+        super().__init__()
+
+    @override
+    def __repr__(self) -> str:
+        cls = get_class_name(self._enum)
+        return f"ENUMPARTIAL[{cls}]"
+
+    @override
+    def convert(
+        self, value: EnumLike[E], param: Parameter | None, ctx: Context | None
+    ) -> E:
+        """Convert a value into the `Enum` type."""
+        try:
+            enum = ensure_enum(value, self._enum, case_sensitive=self._case_sensitive)
+        except EnsureEnumError as error:
+            self.fail(str(error), param, ctx)
+        if enum in self._members:
+            return enum
+        self.fail(f"{enum.value!r} is not a selected member")
+        return None
+
+    @override
+    def get_metavar(self, param: Parameter, ctx: Context) -> str | None:
+        _ = ctx
+        desc = ",".join(str(e.value) if self._value else e.name for e in self._members)
         return _make_metavar(param, desc)
 
 
@@ -195,7 +242,7 @@ class IPv4Address(ParamType):
                     return parse_object(ipaddress.IPv4Address, value)
                 except ParseObjectError as error:
                     self.fail(str(error), param, ctx)
-            case _ as never:
+            case never:
                 assert_never(never)
 
 
@@ -221,7 +268,7 @@ class IPv6Address(ParamType):
                     return parse_object(ipaddress.IPv6Address, value)
                 except ParseObjectError as error:
                     self.fail(str(error), param, ctx)
-            case _ as never:
+            case never:
                 assert_never(never)
 
 
@@ -244,10 +291,33 @@ class MonthDay(ParamType):
                 return value
             case str():
                 try:
-                    return whenever.MonthDay.parse_common_iso(value)
+                    return whenever.MonthDay.parse_iso(value)
                 except ValueError as error:
                     self.fail(str(error), param, ctx)
-            case _ as never:
+            case never:
+                assert_never(never)
+
+
+class Path(ParamType):
+    """A path-valued parameter."""
+
+    name = "path"
+
+    @override
+    def __repr__(self) -> str:
+        return self.name.upper()
+
+    @override
+    def convert(
+        self, value: PathLike, param: Parameter | None, ctx: Context | None
+    ) -> pathlib.Path:
+        """Convert a value into the `Path` type."""
+        match value:
+            case pathlib.Path():
+                return value.expanduser()
+            case str():
+                return pathlib.Path(value).expanduser()
+            case never:
                 assert_never(never)
 
 
@@ -270,10 +340,10 @@ class PlainDateTime(ParamType):
                 return value
             case str():
                 try:
-                    return whenever.PlainDateTime.parse_common_iso(value)
+                    return whenever.PlainDateTime.parse_iso(value)
                 except ValueError as error:
                     self.fail(str(error), param, ctx)
-            case _ as never:
+            case never:
                 assert_never(never)
 
 
@@ -296,10 +366,10 @@ class Time(ParamType):
                 return value
             case str():
                 try:
-                    return whenever.Time.parse_common_iso(value)
+                    return whenever.Time.parse_iso(value)
                 except ValueError as error:
                     self.fail(str(error), param, ctx)
-            case _ as never:
+            case never:
                 assert_never(never)
 
 
@@ -322,10 +392,36 @@ class TimeDelta(ParamType):
                 return value
             case str():
                 try:
-                    return whenever.TimeDelta.parse_common_iso(value)
+                    return whenever.TimeDelta.parse_iso(value)
+                except ValueError as error:
+                    self.fail(str(error), param, ctx)
+            case never:
+                assert_never(never)
+
+
+class UUID(ParamType):
+    """A UUID-valued parameter."""
+
+    name = "uuid"
+
+    @override
+    def __repr__(self) -> str:
+        return self.name.upper()
+
+    @override
+    def convert(
+        self, value: uuid.UUID | str, param: Parameter | None, ctx: Context | None
+    ) -> uuid.UUID:
+        """Convert a value into the `UUID` type."""
+        match value:
+            case uuid.UUID():
+                return value
+            case str():
+                try:
+                    return uuid.UUID(value)
                 except ValueError as error:
                     self.fail(str(error), param, ctx)
-            case _ as never:
+            case never:
                 assert_never(never)
 
 
@@ -348,10 +444,10 @@ class YearMonth(ParamType):
                 return value
             case str():
                 try:
-                    return whenever.YearMonth.parse_common_iso(value)
+                    return whenever.YearMonth.parse_iso(value)
                 except ValueError as error:
                     self.fail(str(error), param, ctx)
-            case _ as never:
+            case never:
                 assert_never(never)
 
 
@@ -374,10 +470,10 @@ class ZonedDateTime(ParamType):
                 return value
             case str():
                 try:
-                    return whenever.ZonedDateTime.parse_common_iso(value)
+                    return whenever.ZonedDateTime.parse_iso(value)
                 except ValueError as error:
                     self.fail(str(error), param, ctx)
-            case _ as never:
+            case never:
                 assert_never(never)
 
 
@@ -429,7 +525,7 @@ class FrozenSetChoices(FrozenSetParameter[Choice, str]):
     @override
     def __init__(
         self,
-        choices: Sequence[str],
+        choices: list[str],
         /,
         *,
         case_sensitive: bool = False,
@@ -514,7 +610,7 @@ class ListChoices(ListParameter[Choice, str]):
     @override
     def __init__(
         self,
-        choices: Sequence[str],
+        choices: list[str],
         /,
         *,
         case_sensitive: bool = False,
@@ -560,15 +656,13 @@ def _make_metavar(param: Parameter, desc: str, /) -> str:
 
 
 __all__ = [
-    "CONTEXT_SETTINGS_HELP_OPTION_NAMES",
+    "CONTEXT_SETTINGS",
+    "UUID",
     "Date",
     "DateDelta",
     "DateTimeDelta",
-    "DirPath",
     "Enum",
-    "ExistingDirPath",
-    "ExistingFilePath",
-    "FilePath",
+    "EnumPartial",
     "FrozenSetChoices",
     "FrozenSetEnums",
     "FrozenSetParameter",
@@ -581,6 +675,8 @@ __all__ = [
     "ListParameter",
     "ListStrs",
     "MonthDay",
+    "Path",
+    "Path",
     "PlainDateTime",
     "Time",
     "TimeDelta",

utilities/concurrent.py

@@ -84,7 +84,7 @@ def concurrent_starmap[T](
                 initargs=initargs,
             ) as pool:
                 result = pool.map(apply, iterable, timeout=timeout, chunksize=chunksize)
-        case _ as never:
+        case never:
             assert_never(never)
     return list(result)
 

utilities/contextlib.py

@@ -8,7 +8,7 @@ from contextlib import (
     asynccontextmanager,
     contextmanager,
 )
-from functools import partial
+from functools import partial, wraps
 from signal import SIGABRT, SIGFPE, SIGILL, SIGINT, SIGSEGV, SIGTERM, getsignal, signal
 from typing import TYPE_CHECKING, Any, assert_never, cast, overload
 
@@ -77,6 +77,7 @@ def enhanced_context_manager[**P, T_co](
     make_gcm = contextmanager(func)
 
     @contextmanager
+    @wraps(func)
     def wrapped(*args: P.args, **kwargs: P.kwargs) -> Iterator[T_co]:
         gcm = make_gcm(*args, **kwargs)
         sigabrt0 = _swap_handler(SIGABRT, gcm) if sigabrt else None
@@ -159,6 +160,7 @@ def enhanced_async_context_manager[**P, T_co](
     make_agcm = asynccontextmanager(func)
 
     @asynccontextmanager
+    @wraps(func)
     async def wrapped(*args: P.args, **kwargs: P.kwargs) -> AsyncIterator[T_co]:
         agcm = make_agcm(*args, **kwargs)
         sigabrt0 = _swap_handler(SIGABRT, agcm) if sigabrt else None
@@ -210,7 +212,7 @@ def _make_handler(
                 _ = loop.call_soon_threadsafe(
                     create_task, agcm.__aexit__(None, None, None)
                 )
-            case _ as never:
+            case never:
                 assert_never(never)
         if callable(orig_handler):  # pragma: no cover
             orig_handler(signum, frame)

utilities/contextvars.py

@@ -1,6 +1,12 @@
 from __future__ import annotations
 
+from contextlib import contextmanager
 from contextvars import ContextVar
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
 
 ##
 
@@ -19,4 +25,17 @@ def set_global_breakpoint() -> None:
     _ = _GLOBAL_BREAKPOINT.set(True)
 
 
-__all__ = ["global_breakpoint", "set_global_breakpoint"]
+##
+
+
+@contextmanager
+def yield_set_context(var: ContextVar[bool], /) -> Iterator[None]:
+    """Yield a context var as being set."""
+    token = var.set(True)
+    try:
+        yield
+    finally:
+        _ = var.reset(token)
+
+
+__all__ = ["global_breakpoint", "set_global_breakpoint", "yield_set_context"]

utilities/cryptography.py

@@ -11,18 +11,18 @@ _ENV_VAR = "FERNET_KEY"
 
 def encrypt(text: str, /, *, env_var: str = _ENV_VAR) -> bytes:
     """Encrypt a string."""
-    return get_fernet(env_var=env_var).encrypt(text.encode())
+    return get_fernet(env_var).encrypt(text.encode())
 
 
 def decrypt(text: bytes, /, *, env_var: str = _ENV_VAR) -> str:
     """Encrypt a string."""
-    return get_fernet(env_var=env_var).decrypt(text).decode()
+    return get_fernet(env_var).decrypt(text).decode()
 
 
 ##
 
 
-def get_fernet(*, env_var: str = _ENV_VAR) -> Fernet:
+def get_fernet(env_var: str = _ENV_VAR, /) -> Fernet:
     """Get the Fernet key."""
     if (key := getenv(env_var)) is None:
         raise GetFernetError(env_var=env_var)