dycw-utilities 0.113.1__py3-none-any.whl → 0.113.3__py3-none-any.whl

{dycw_utilities-0.113.1.dist-info → dycw_utilities-0.113.3.dist-info}/METADATA

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: dycw-utilities
-Version: 0.113.1
+Version: 0.113.3
 Author-email: Derek Wan <d.wan@icloud.com>
 License-File: LICENSE
 Requires-Python: >=3.12
 Requires-Dist: typing-extensions<4.14,>=4.13.1
 Provides-Extra: test
-Requires-Dist: hypothesis<6.132,>=6.131.9; extra == 'test'
+Requires-Dist: hypothesis<6.132,>=6.131.14; extra == 'test'
 Requires-Dist: pytest-asyncio<0.27,>=0.26.0; extra == 'test'
 Requires-Dist: pytest-cov<6.2,>=6.1.1; extra == 'test'
 Requires-Dist: pytest-instafail<0.6,>=0.5.0; extra == 'test'
@@ -16,7 +16,7 @@ Requires-Dist: pytest-randomly<3.17,>=3.16.0; extra == 'test'
 Requires-Dist: pytest-regressions<2.8,>=2.7.0; extra == 'test'
 Requires-Dist: pytest-rerunfailures<16,>=15.0; extra == 'test'
 Requires-Dist: pytest-rng<1.1,>=1.0.0; extra == 'test'
-Requires-Dist: pytest-timeout<2.4,>=2.3.1; extra == 'test'
+Requires-Dist: pytest-timeout<2.5,>=2.4.0; extra == 'test'
 Requires-Dist: pytest-xdist<3.7,>=3.6.1; extra == 'test'
 Requires-Dist: pytest<8.4,>=8.3.5; extra == 'test'
 Requires-Dist: setuptools>=78.0.2; extra == 'test'
@@ -80,7 +80,7 @@ Provides-Extra: zzz-test-hypothesis
 Requires-Dist: aiosqlite<0.22,>=0.21.0; extra == 'zzz-test-hypothesis'
 Requires-Dist: asyncpg<0.31,>=0.30.0; extra == 'zzz-test-hypothesis'
 Requires-Dist: greenlet<3.3,>=3.2.0; extra == 'zzz-test-hypothesis'
-Requires-Dist: hypothesis<6.132,>=6.131.9; extra == 'zzz-test-hypothesis'
+Requires-Dist: hypothesis<6.132,>=6.131.14; extra == 'zzz-test-hypothesis'
 Requires-Dist: luigi<3.7,>=3.6.0; extra == 'zzz-test-hypothesis'
 Requires-Dist: numpy<2.3,>=2.2.5; extra == 'zzz-test-hypothesis'
 Requires-Dist: pathvalidate<3.3,>=3.2.3; extra == 'zzz-test-hypothesis'

{dycw_utilities-0.113.1.dist-info → dycw_utilities-0.113.3.dist-info}/RECORD

@@ -1,7 +1,7 @@
-utilities/__init__.py,sha256=jYMM0M9M6TZGpXyYU7Rwr3r3k0NY3IhjcbJz_O8C9oM,60
+utilities/__init__.py,sha256=eOSRaK1eqblBSlkDTnJ-3-xWW49Ql-RkfxbwvIfUGyQ,60
 utilities/altair.py,sha256=Gpja-flOo-Db0PIPJLJsgzAlXWoKUjPU1qY-DQ829ek,9156
 utilities/astor.py,sha256=xuDUkjq0-b6fhtwjhbnebzbqQZAjMSHR1IIS5uOodVg,777
-utilities/asyncio.py,sha256=41oQUurWMvadFK5gFnaG21hMM0Vmfn2WS6OpC0R9mas,14757
+utilities/asyncio.py,sha256=6Pv0xK2jP55iF6EYjY1g6_rFGOeJyihxRNxXnOsWv14,15691
 utilities/atomicwrites.py,sha256=geFjn9Pwn-tTrtoGjDDxWli9NqbYfy3gGL6ZBctiqSo,5393
 utilities/atools.py,sha256=IYMuFSFGSKyuQmqD6v5IUtDlz8PPw0Sr87Cub_gRU3M,1168
 utilities/cachetools.py,sha256=C1zqOg7BYz0IfQFK8e3qaDDgEZxDpo47F15RTfJM37Q,2910
@@ -12,7 +12,7 @@ utilities/contextvars.py,sha256=RsSGGrbQqqZ67rOydnM7WWIsM2lIE31UHJLejnHJPWY,505
 utilities/cryptography.py,sha256=HyOewI20cl3uRXsKivhIaeLVDInQdzgXZGaly7hS5dE,771
 utilities/cvxpy.py,sha256=Rv1-fD-XYerosCavRF8Pohop2DBkU3AlFaGTfD8AEAA,13776
 utilities/dataclasses.py,sha256=iiC1wpGXWhaocIikzwBt8bbLWyImoUlOlcDZJGejaIg,33011
-utilities/datetime.py,sha256=OF7jZE702UecnwAbq9D3N-GINpp9gSGoidki1RhimCE,35752
+utilities/datetime.py,sha256=PcN-4_sSPX1zbpdzBQRdo08pubCuGHyigxkV6SUnvlo,38733
 utilities/enum.py,sha256=HoRwVCWzsnH0vpO9ZEcAAIZLMv0Sn2vJxxA4sYMQgDs,5793
 utilities/errors.py,sha256=BtSNP0JC3ik536ddPyTerLomCRJV9f6kdMe6POz0QHM,361
 utilities/eventkit.py,sha256=6M5Xu1SzN-juk9PqBHwy5dS-ta7T0qA6SMpDsakOJ0E,13039
@@ -77,7 +77,7 @@ utilities/text.py,sha256=Fo12N4aA7k2rnb4W4vH9iiDh88Q5_nvRssTkfNsvVM8,10965
 utilities/threading.py,sha256=GvBOp4CyhHfN90wGXZuA2VKe9fGzMaEa7oCl4f3nnPU,1009
 utilities/timer.py,sha256=Rkc49KSpHuC8s7vUxGO9DU55U9I6yDKnchsQqrUCVBs,4075
 utilities/traceback.py,sha256=secexUnBsecfWV4ZuqP1W4pGF3prOeO1CRyJK-8zQDU,27402
-utilities/types.py,sha256=B5slv6Vdj6uRmE1xnEBEJfWJmK_0odEwIUCVC9KHikw,18168
+utilities/types.py,sha256=FhE1b8v_s_IlmXucwY7jAMWAq9cfpzyKssQwgwb3jnM,18267
 utilities/typing.py,sha256=H6ysJkI830aRwLsMKz0SZIw4cpcsm7d6KhQOwr-SDh0,13817
 utilities/tzdata.py,sha256=yCf70NICwAeazN3_JcXhWvRqCy06XJNQ42j7r6gw3HY,1217
 utilities/tzlocal.py,sha256=3upDNFBvGh1l9njmLR2z2S6K6VxQSb7QizYGUbAH3JU,960
@@ -87,7 +87,7 @@ utilities/warnings.py,sha256=un1LvHv70PU-LLv8RxPVmugTzDJkkGXRMZTE2-fTQHw,1771
 utilities/whenever.py,sha256=iLRP_-8CZtBpHKbGZGu-kjSMg1ZubJ-VSmgSy7Eudxw,17787
 utilities/zipfile.py,sha256=24lQc9ATcJxHXBPc_tBDiJk48pWyRrlxO2fIsFxU0A8,699
 utilities/zoneinfo.py,sha256=-Xm57PMMwDTYpxJdkiJG13wnbwK--I7XItBh5WVhD-o,1874
-dycw_utilities-0.113.1.dist-info/METADATA,sha256=yaeQ1FFLx3bZShYnRwFit1bF6k9iieYw8kInaN6kQ2w,12941
-dycw_utilities-0.113.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.113.1.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.113.1.dist-info/RECORD,,
+dycw_utilities-0.113.3.dist-info/METADATA,sha256=FekxkXInaGKIntNnsuUBc8VxfVEcuyBaoxzXdhhdxII,12943
+dycw_utilities-0.113.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.113.3.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.113.3.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.113.1"
+__version__ = "0.113.3"

utilities/asyncio.py

@@ -17,6 +17,7 @@ from asyncio import (
     sleep,
     timeout,
 )
+from collections.abc import Callable
 from contextlib import (
     AsyncExitStack,
     _AsyncGeneratorContextManager,
@@ -27,12 +28,22 @@ from dataclasses import dataclass, field
 from io import StringIO
 from subprocess import PIPE
 from sys import stderr, stdout
-from typing import TYPE_CHECKING, Generic, Self, TextIO, TypeVar, override
+from typing import (
+    TYPE_CHECKING,
+    Generic,
+    Self,
+    TextIO,
+    TypeVar,
+    assert_never,
+    overload,
+    override,
+)
 
 from utilities.datetime import MILLISECOND, datetime_duration_to_float
 from utilities.errors import ImpossibleCaseError
 from utilities.functions import ensure_int, ensure_not_none
-from utilities.types import THashable, TSupportsRichComparison
+from utilities.sentinel import Sentinel, sentinel
+from utilities.types import MaybeCallableEvent, THashable, TSupportsRichComparison
 
 if TYPE_CHECKING:
     from asyncio import _CoroutineLike
@@ -356,6 +367,34 @@ class UniqueQueue(Queue[THashable]):
 ##
 
 
+@overload
+def get_event(*, event: MaybeCallableEvent) -> Event: ...
+@overload
+def get_event(*, event: None) -> None: ...
+@overload
+def get_event(*, event: Sentinel) -> Sentinel: ...
+@overload
+def get_event(*, event: MaybeCallableEvent | Sentinel) -> Event | Sentinel: ...
+@overload
+def get_event(
+    *, event: MaybeCallableEvent | None | Sentinel = sentinel
+) -> Event | None | Sentinel: ...
+def get_event(
+    *, event: MaybeCallableEvent | None | Sentinel = sentinel
+) -> Event | None | Sentinel:
+    """Get the event."""
+    match event:
+        case Event() | None | Sentinel():
+            return event
+        case Callable() as func:
+            return get_event(event=func())
+        case _ as never:
+            assert_never(never)
+
+
+##
+
+
 async def get_items(
     queue: Queue[_T], /, *, max_size: int | None = None, lock: Lock | None = None
 ) -> list[_T]:
@@ -490,6 +529,7 @@ __all__ = [
     "StreamCommandOutput",
     "UniquePriorityQueue",
     "UniqueQueue",
+    "get_event",
     "get_items",
     "get_items_nowait",
     "sleep_dur",

utilities/datetime.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import datetime as dt
-from collections.abc import Callable, Iterable
+from collections.abc import Callable, Iterable, Sequence
 from dataclasses import dataclass, replace
 from re import search, sub
 from statistics import fmean
@@ -495,6 +495,101 @@ def get_half_years(*, n: int = 1) -> dt.timedelta:
 
 HALF_YEAR = get_half_years(n=1)
 
+##
+
+
+def get_min_max_date(
+    *,
+    min_date: dt.date | None = None,
+    max_date: dt.date | None = None,
+    min_age: Duration | None = None,
+    max_age: Duration | None = None,
+    time_zone: TimeZoneLike = UTC,
+) -> tuple[dt.date | None, dt.date | None]:
+    """Get the min/max date given a combination of dates/ages."""
+    today = get_today(time_zone=time_zone)
+    min_parts: Sequence[dt.date] = []
+    if min_date is not None:
+        if min_date > today:
+            raise _GetMinMaxDateMinDateError(min_date=min_date, today=today)
+        min_parts.append(min_date)
+    if max_age is not None:
+        if date_duration_to_timedelta(max_age) < ZERO_TIME:
+            raise _GetMinMaxDateMaxAgeError(max_age=max_age)
+        min_parts.append(sub_duration(today, duration=max_age))
+    min_date_use = max(min_parts, default=None)
+    max_parts: Sequence[dt.date] = []
+    if max_date is not None:
+        if max_date > today:
+            raise _GetMinMaxDateMaxDateError(max_date=max_date, today=today)
+        max_parts.append(max_date)
+    if min_age is not None:
+        if date_duration_to_timedelta(min_age) < ZERO_TIME:
+            raise _GetMinMaxDateMinAgeError(min_age=min_age)
+        max_parts.append(sub_duration(today, duration=min_age))
+    max_date_use = min(max_parts, default=None)
+    if (
+        (min_date_use is not None)
+        and (max_date_use is not None)
+        and (min_date_use > max_date_use)
+    ):
+        raise _GetMinMaxDatePeriodError(min_date=min_date_use, max_date=max_date_use)
+    return min_date_use, max_date_use
+
+
+@dataclass(kw_only=True, slots=True)
+class GetMinMaxDateError(Exception): ...
+
+
+@dataclass(kw_only=True, slots=True)
+class _GetMinMaxDateMinDateError(GetMinMaxDateError):
+    min_date: dt.date
+    today: dt.date
+
+    @override
+    def __str__(self) -> str:
+        return f"Min date must be at most today; got {self.min_date} > {self.today}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _GetMinMaxDateMinAgeError(GetMinMaxDateError):
+    min_age: Duration
+
+    @override
+    def __str__(self) -> str:
+        return f"Min age must be non-negative; got {self.min_age}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _GetMinMaxDateMaxDateError(GetMinMaxDateError):
+    max_date: dt.date
+    today: dt.date
+
+    @override
+    def __str__(self) -> str:
+        return f"Max date must be at most today; got {self.max_date} > {self.today}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _GetMinMaxDateMaxAgeError(GetMinMaxDateError):
+    max_age: Duration
+
+    @override
+    def __str__(self) -> str:
+        return f"Max age must be non-negative; got {self.max_age}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _GetMinMaxDatePeriodError(GetMinMaxDateError):
+    min_date: dt.date
+    max_date: dt.date
+
+    @override
+    def __str__(self) -> str:
+        return (
+            f"Min date must be at most max date; got {self.min_date} > {self.max_date}"
+        )
+
 
 ##
 
@@ -1244,6 +1339,7 @@ __all__ = [
     "CheckDateNotDateTimeError",
     "DateOrMonth",
     "EnsureMonthError",
+    "GetMinMaxDateError",
     "MeanDateTimeError",
     "MeanTimeDeltaError",
     "MillisecondsSinceEpochError",
@@ -1280,6 +1376,7 @@ __all__ = [
     "get_date",
     "get_datetime",
     "get_half_years",
+    "get_min_max_date",
     "get_months",
     "get_now",
     "get_quarters",

utilities/types.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import datetime as dt
+from asyncio import Event
 from collections.abc import Awaitable, Callable, Coroutine, Hashable, Iterable, Mapping
 from enum import Enum
 from logging import Logger
@@ -57,6 +58,7 @@ type TupleOrStrMapping = tuple[Any, ...] | StrMapping
 # asyncio
 type Coroutine1[_T] = Coroutine[Any, Any, _T]
 type MaybeAwaitable[_T] = _T | Awaitable[_T]
+type MaybeCallableEvent = MaybeCallable[Event]
 type MaybeCoroutine1[_T] = _T | Coroutine1[_T]
 
 
@@ -277,6 +279,7 @@ __all__ = [
     "MaybeCallable",
     "MaybeCallableDate",
     "MaybeCallableDateTime",
+    "MaybeCallableEvent",
     "MaybeCoroutine1",
     "MaybeIterable",
     "MaybeIterableHashable",