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

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,52 @@ 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
+        return self.fail(f"{enum.value!r} is not a selected member")
+
+    @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 +241,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 +267,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 +290,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 +339,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 +365,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 +391,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 +443,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 +469,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 +524,7 @@ class FrozenSetChoices(FrozenSetParameter[Choice, str]):
     @override
     def __init__(
         self,
-        choices: Sequence[str],
+        choices: list[str],
         /,
         *,
         case_sensitive: bool = False,
@@ -514,7 +609,7 @@ class ListChoices(ListParameter[Choice, str]):
     @override
     def __init__(
         self,
-        choices: Sequence[str],
+        choices: list[str],
         /,
         *,
         case_sensitive: bool = False,
@@ -560,15 +655,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 +674,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)

utilities/dataclasses.py

@@ -6,11 +6,7 @@ from dataclasses import MISSING, dataclass, field, fields, replace
 from typing import TYPE_CHECKING, Any, Literal, assert_never, overload, override
 
 from utilities.errors import ImpossibleCaseError
-from utilities.functions import (
-    get_class_name,
-    is_dataclass_class,
-    is_dataclass_instance,
-)
+from utilities.functions import get_class_name
 from utilities.iterables import (
     OneStrEmptyError,
     OneStrNonUniqueError,
@@ -25,7 +21,7 @@ from utilities.parse import (
     serialize_object,
 )
 from utilities.re import ExtractGroupError, extract_group
-from utilities.sentinel import Sentinel, sentinel
+from utilities.sentinel import Sentinel, is_sentinel, sentinel
 from utilities.text import (
     BRACKETS,
     LIST_SEPARATOR,
@@ -34,8 +30,8 @@ from utilities.text import (
     _SplitKeyValuePairsSplitError,
     split_key_value_pairs,
 )
-from utilities.types import SupportsLT
-from utilities.typing import get_type_hints
+from utilities.types import MaybeType, SupportsLT
+from utilities.typing import get_type_hints, is_dataclass_class, is_dataclass_instance
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator
@@ -214,7 +210,7 @@ def is_nullable_lt[T: SupportsLT](x: T | None, y: T | None, /) -> bool | None:
             return True
         case 0:
             return None
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -275,8 +271,7 @@ def mapping_to_dataclass[T: Dataclass](
     default = {
         f.name
         for f in fields_use
-        if (not isinstance(f.default, Sentinel))
-        or (not isinstance(f.default_factory, Sentinel))
+        if (not is_sentinel(f.default)) or (not is_sentinel(f.default_factory))
     }
     have = set(field_names_to_values) | default
     missing = {f.name for f in fields_use} - have
@@ -434,12 +429,10 @@ def replace_non_sentinel[T: Dataclass](
     """Replace attributes on a dataclass, filtering out sentinel values."""
     if in_place:
         for k, v in kwargs.items():
-            if not isinstance(v, Sentinel):
+            if not is_sentinel(v):
                 setattr(obj, k, v)
         return None
-    return replace(
-        obj, **{k: v for k, v in kwargs.items() if not isinstance(v, Sentinel)}
-    )
+    return replace(obj, **{k: v for k, v in kwargs.items() if not is_sentinel(v)})
 
 
 ##
@@ -520,7 +513,7 @@ def parse_dataclass[T: Dataclass](
             )
         case Mapping() as keys_to_serializes:
             ...
-        case _ as never:
+        case never:
             assert_never(never)
     fields = list(
         yield_fields(
@@ -833,7 +826,7 @@ def yield_fields(
     warn_name_errors: bool = False,
 ) -> Iterator[_YieldFieldsClass[Any]]: ...
 def yield_fields(
-    obj: Dataclass | type[Dataclass],
+    obj: MaybeType[Dataclass],
     /,
     *,
     globalns: StrMapping | None = None,
@@ -912,17 +905,11 @@ class _YieldFieldsInstance[T]:
         extra: Mapping[type[U], Callable[[U, U], bool]] | None = None,
     ) -> bool:
         """Check if the field value equals its default."""
-        if isinstance(self.default, Sentinel) and isinstance(
-            self.default_factory, Sentinel
-        ):
+        if is_sentinel(self.default) and is_sentinel(self.default_factory):
             return False
-        if (not isinstance(self.default, Sentinel)) and isinstance(
-            self.default_factory, Sentinel
-        ):
+        if (not is_sentinel(self.default)) and is_sentinel(self.default_factory):
             expected = self.default
-        elif isinstance(self.default, Sentinel) and (
-            not isinstance(self.default_factory, Sentinel)
-        ):
+        elif is_sentinel(self.default) and (not is_sentinel(self.default_factory)):
             expected = self.default_factory()
         else:  # pragma: no cover
             raise ImpossibleCaseError(
@@ -1002,7 +989,7 @@ def _empty_error_str_core(
             return f"any field starting with {key!r}"
         case True, False:
             return f"any field starting with {key!r} (modulo case)"
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -1043,7 +1030,7 @@ def _non_unique_error_str_core(
             head_msg = f"exactly one field starting with {key!r}"
         case True, False:
             head_msg = f"exactly one field starting with {key!r} (modulo case)"
-        case _ as never:
+        case never:
             assert_never(never)
     return f"{head_msg}; got {first!r}, {second!r} and perhaps more"