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

utilities/atomicwrites.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
+import gzip
 import shutil
 from contextlib import ExitStack, contextmanager
 from dataclasses import dataclass
 from pathlib import Path
-from shutil import rmtree
+from shutil import copyfileobj, rmtree
 from typing import TYPE_CHECKING, assert_never, override
 
 from atomicwrites import replace_atomic
@@ -56,7 +57,7 @@ def move(
             raise ImpossibleCaseError(
                 case=[f"{source.is_file()=}", f"{source.is_dir()=}"]
             )
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -111,21 +112,32 @@ def move_many(*paths: tuple[PathLike, PathLike], overwrite: bool = False) -> Non
 
 
 @contextmanager
-def writer(path: PathLike, /, *, overwrite: bool = False) -> Iterator[Path]:
+def writer(
+    path: PathLike, /, *, compress: bool = False, overwrite: bool = False
+) -> Iterator[Path]:
     """Yield a path for atomically writing files to disk."""
     path = Path(path)
     parent = path.parent
     parent.mkdir(parents=True, exist_ok=True)
     name = path.name
     with TemporaryDirectory(suffix=".tmp", prefix=name, dir=parent) as temp_dir:
-        temp_path = Path(temp_dir, name)
+        temp_path1 = Path(temp_dir, name)
         try:
-            yield temp_path
+            yield temp_path1
         except KeyboardInterrupt:
             rmtree(temp_dir)
         else:
+            if compress:
+                temp_path2 = Path(temp_dir, f"{name}.gz")
+                with (
+                    temp_path1.open("rb") as source,
+                    gzip.open(temp_path2, mode="wb") as dest,
+                ):
+                    copyfileobj(source, dest)
+            else:
+                temp_path2 = temp_path1
             try:
-                move(temp_path, path, overwrite=overwrite)
+                move(temp_path2, path, overwrite=overwrite)
             except _MoveSourceNotFoundError as error:
                 raise _WriterTemporaryPathEmptyError(temp_path=error.source) from None
             except _MoveFileExistsError as error:

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,23 +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 StringParamType
+from click.types import IntParamType, StringParamType
 
-import utilities.whenever
 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
-from utilities.whenever import FreqLike, _FreqParseError, _MonthParseCommonISOError
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable, Sequence
+    from collections.abc import Iterable
 
     from utilities.types import (
         DateDeltaLike,
@@ -29,35 +28,33 @@ if TYPE_CHECKING:
         IPv4AddressLike,
         IPv6AddressLike,
         MaybeStr,
+        MonthDayLike,
+        PathLike,
         PlainDateTimeLike,
         TimeDeltaLike,
         TimeLike,
+        YearMonthLike,
         ZonedDateTimeLike,
     )
-    from utilities.whenever import MonthLike
 
 
-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 _HelpOptionNames(TypedDict):
-    help_option_names: Sequence[str]
+class _ContextSettings(TypedDict):
+    context_settings: _ContextSettingsInner
 
 
-class _ContextSettings(TypedDict):
-    context_settings: _HelpOptionNames
+class _ContextSettingsInner(TypedDict):
+    max_content_width: int
+    help_option_names: list[str]
+    show_default: bool
 
 
-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
@@ -82,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)
 
 
@@ -108,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)
 
 
@@ -134,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)
 
 
@@ -145,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__()
 
@@ -170,34 +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 Freq(ParamType):
-    """An frequency-valued parameter."""
+class EnumPartial[E: enum.Enum](ParamType):
+    """An enum-valued parameter."""
 
-    name = "freq"
+    @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:
-        return self.name.upper()
+        cls = get_class_name(self._enum)
+        return f"ENUMPARTIAL[{cls}]"
 
     @override
     def convert(
-        self, value: FreqLike, param: Parameter | None, ctx: Context | None
-    ) -> utilities.whenever.Freq:
-        """Convert a value into the `Freq` type."""
-        match value:
-            case utilities.whenever.Freq():
-                return value
-            case str():
-                try:
-                    return utilities.whenever.Freq.parse(value)
-                except _FreqParseError as error:
-                    self.fail(str(error), param, ctx)
-            case _ as never:
-                assert_never(never)
+        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)
 
 
 class IPv4Address(ParamType):
@@ -222,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)
 
 
@@ -248,14 +267,14 @@ 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)
 
 
-class Month(ParamType):
-    """A month-valued parameter."""
+class MonthDay(ParamType):
+    """A month-day parameter."""
 
-    name = "month"
+    name = "month-day"
 
     @override
     def __repr__(self) -> str:
@@ -263,13 +282,42 @@ class Month(ParamType):
 
     @override
     def convert(
-        self, value: MonthLike, param: Parameter | None, ctx: Context | None
-    ) -> utilities.whenever.Month:
-        """Convert a value into the `Month` type."""
-        try:
-            return utilities.whenever.Month.ensure(value)
-        except _MonthParseCommonISOError as error:
-            self.fail(str(error), param, ctx)
+        self, value: MonthDayLike, param: Parameter | None, ctx: Context | None
+    ) -> whenever.MonthDay:
+        """Convert a value into the `MonthDay` type."""
+        match value:
+            case whenever.MonthDay():
+                return value
+            case str():
+                try:
+                    return whenever.MonthDay.parse_iso(value)
+                except ValueError as error:
+                    self.fail(str(error), param, ctx)
+            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)
 
 
 class PlainDateTime(ParamType):
@@ -291,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)
 
 
@@ -317,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)
 
 
@@ -343,10 +391,62 @@ 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 never:
+                assert_never(never)
+
+
+class YearMonth(ParamType):
+    """A year-month parameter."""
+
+    name = "year-month"
+
+    @override
+    def __repr__(self) -> str:
+        return self.name.upper()
+
+    @override
+    def convert(
+        self, value: YearMonthLike, param: Parameter | None, ctx: Context | None
+    ) -> whenever.YearMonth:
+        """Convert a value into the `YearMonth` type."""
+        match value:
+            case whenever.YearMonth():
+                return value
+            case str():
+                try:
+                    return whenever.YearMonth.parse_iso(value)
                 except ValueError as error:
                     self.fail(str(error), param, ctx)
-            case _ as never:
+            case never:
                 assert_never(never)
 
 
@@ -369,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)
 
 
@@ -424,7 +524,7 @@ class FrozenSetChoices(FrozenSetParameter[Choice, str]):
     @override
     def __init__(
         self,
-        choices: Sequence[str],
+        choices: list[str],
         /,
         *,
         case_sensitive: bool = False,
@@ -445,6 +545,14 @@ class FrozenSetEnums[E: enum.Enum](FrozenSetParameter[Enum[E], E]):
         super().__init__(Enum(enum, case_sensitive=case_sensitive), separator=separator)
 
 
+class FrozenSetInts(FrozenSetParameter[IntParamType, int]):
+    """A frozenset-of-ints-valued parameter."""
+
+    @override
+    def __init__(self, *, separator: str = ",") -> None:
+        super().__init__(IntParamType(), separator=separator)
+
+
 class FrozenSetStrs(FrozenSetParameter[StringParamType, str]):
     """A frozenset-of-strs-valued parameter."""
 
@@ -501,7 +609,7 @@ class ListChoices(ListParameter[Choice, str]):
     @override
     def __init__(
         self,
-        choices: Sequence[str],
+        choices: list[str],
         /,
         *,
         case_sensitive: bool = False,
@@ -522,6 +630,14 @@ class ListEnums[E: enum.Enum](ListParameter[Enum[E], E]):
         super().__init__(Enum(enum, case_sensitive=case_sensitive), separator=separator)
 
 
+class ListInts(ListParameter[IntParamType, int]):
+    """A list-of-ints-valued parameter."""
+
+    @override
+    def __init__(self, *, separator: str = ",") -> None:
+        super().__init__(IntParamType(), separator=separator)
+
+
 class ListStrs(ListParameter[StringParamType, str]):
     """A list-of-strs-valued parameter."""
 
@@ -539,16 +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",
-    "Freq",
+    "EnumPartial",
     "FrozenSetChoices",
     "FrozenSetEnums",
     "FrozenSetParameter",
@@ -557,10 +670,15 @@ __all__ = [
     "IPv6Address",
     "ListChoices",
     "ListEnums",
+    "ListInts",
     "ListParameter",
     "ListStrs",
+    "MonthDay",
+    "Path",
+    "Path",
     "PlainDateTime",
     "Time",
     "TimeDelta",
+    "YearMonth",
     "ZonedDateTime",
 ]

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)