dycw-utilities 0.132.4__tar.gz → 0.133.1__tar.gz

{dycw_utilities-0.132.4 → dycw_utilities-0.133.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dycw-utilities
-Version: 0.132.4
+Version: 0.133.1
 Author-email: Derek Wan <d.wan@icloud.com>
 License-File: LICENSE
 Requires-Python: >=3.12

{dycw_utilities-0.132.4 → dycw_utilities-0.133.1}/pyproject.toml

@@ -14,6 +14,7 @@ altair-test = [
   "img2pdf",
   "vl-convert-python",
 ]
+arq = ["arq >= 0.26.3, < 0.27"]
 atools = ["atools >= 0.14.2, < 0.15"]
 cachetools = ["cachetools >= 5.5.2, < 5.6"]
 click = ["click >= 8.2.1, < 8.3"]
@@ -29,6 +30,7 @@ dataclasses-test = ["orjson", "polars-lts-cpu"]
 dev = [
   "coloredlogs >= 15.0.1, < 15.1",
   "coverage-conditional-plugin >= 0.9.0, < 0.10",
+  "dycw-pytest-only >= 2.1.1, < 2.2",
   "pyright[nodejs] >= 1.1.401, < 1.2",
   "pytest-cov >= 6.1.1, < 6.2",
 ]
@@ -74,7 +76,7 @@ pytest-regressions = ["pytest-regressions >= 2.8.0, < 2.9"]
 pytest-regressions-test = ["orjson", "polars-lts-cpu"]
 pytest-test = ["orjson", "pytest-rng", "pytest-rerunfailures"]
 python-dotenv = ["python-dotenv >= 1.1.0, < 1.2"]
-redis = ["redis >= 6.2.0, < 6.3", "orjson"]
+redis = ["redis >= 5.3.0, < 6.0", "orjson"]
 redis-test = ["pytest-rerunfailures"]
 reprlib-test = ["rich"]
 scipy = ["scipy >= 1.15.3, < 1.16"]
@@ -102,7 +104,7 @@ dependencies = [
 name = "dycw-utilities"
 readme = "README.md"
 requires-python = ">= 3.12"
-version = "0.132.4"
+version = "0.133.1"
 
 [project.optional-dependencies]
 logging = [
@@ -128,7 +130,7 @@ test = [
 # bump-my-version
 [tool.bumpversion]
 allow_dirty = true
-current_version = "0.132.4"
+current_version = "0.133.1"
 
 [[tool.bumpversion.files]]
 filename = "src/utilities/__init__.py"
@@ -237,6 +239,7 @@ filterwarnings = [
   "error",
   "ignore:.*utcfromtimestamp.* is deprecated and scheduled for removal in a future version:DeprecationWarning",  # luigi
   "ignore:Exception ignored in.* <coroutine object .* at .*>:pytest.PytestUnraisableExceptionWarning",
+  "ignore:Exception in thread Thread-.*:pytest.PytestUnhandledThreadExceptionWarning",
   "ignore:Implicitly cleaning up <TemporaryDirectory '.*'>:ResourceWarning",
   "ignore:ResourceTracker called reentrantly for resource cleanup, which is unsupported:UserWarning",
   "ignore:Task .* without outputs has no custom complete.* method:UserWarning",  # luigi

dycw_utilities-0.133.1/src/tests/test_arq.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from asyncio import sleep
+from typing import TYPE_CHECKING, Any, cast
+
+from hypothesis import given
+from hypothesis.strategies import integers
+
+from utilities.arq import Worker, cron_raw
+from utilities.iterables import one
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from arq.cron import CronJob
+    from arq.typing import WorkerCoroutine
+
+    from utilities.types import CallableCoroutine1
+
+
+class TestWorker:
+    @given(x=integers(), y=integers())
+    async def test_main(self, *, x: int, y: int) -> None:
+        async def func(x: int, y: int, /) -> int:
+            await sleep(0.01)
+            return x + y
+
+        class Example(Worker):
+            functions_raw: Sequence[CallableCoroutine1[Any]] = [func]
+
+        func_use = cast("WorkerCoroutine", one(Example.functions))
+        result = await func_use({}, x, y)
+        assert result == (x + y)
+
+    @given(x=integers(), y=integers())
+    async def test_cron(self, *, x: int, y: int) -> None:
+        async def func(x: int, y: int, /) -> int:
+            await sleep(0.01)
+            return x + y
+
+        class Example(Worker):
+            cron_jobs: Sequence[CronJob] | None = [cron_raw(func, args=(x, y))]
+
+        assert Example.cron_jobs is not None
+        cron_job = one(Example.cron_jobs)
+        result = await cron_job.coroutine({})
+        assert result == (x + y)

{dycw_utilities-0.132.4 → dycw_utilities-0.133.1}/src/tests/test_click.py

@@ -34,6 +34,7 @@ from utilities.click import (
     ExistingDirPath,
     ExistingFilePath,
     FilePath,
+    Freq,
     FrozenSetChoices,
     FrozenSetEnums,
     FrozenSetStrs,
@@ -51,6 +52,7 @@ from utilities.hypothesis import (
     date_deltas,
     date_time_deltas,
     dates,
+    freqs,
     months,
     pairs,
     plain_datetimes,
@@ -209,6 +211,7 @@ class TestParameters:
                 attrgetter("name"),
                 True,
             ),
+            param(Freq(), "FREQ", freqs(), utilities.whenever.Freq.serialize, True),
             param(
                 FrozenSetChoices(["a", "b", "c"]),
                 "FROZENSET[Choice(['a', 'b', 'c'])]",

{dycw_utilities-0.132.4 → dycw_utilities-0.133.1}/src/tests/test_hypothesis.py

@@ -41,6 +41,7 @@ from utilities.hypothesis import (
     Shape,
     _Draw2DefaultGeneratedSentinelError,
     _Draw2InputResolvedToSentinelError,
+    _freq_units,
     assume_does_not_raise,
     bool_arrays,
     date_deltas,
@@ -51,6 +52,7 @@ from utilities.hypothesis import (
     float64s,
     float_arrays,
     floats_extra,
+    freqs,
     git_repos,
     hashables,
     int32s,
@@ -107,6 +109,7 @@ from utilities.version import Version
 from utilities.whenever import (
     DATE_TWO_DIGIT_YEAR_MAX,
     DATE_TWO_DIGIT_YEAR_MIN,
+    Freq,
     Month,
     to_days,
     to_nanos,
@@ -118,7 +121,7 @@ if TYPE_CHECKING:
     from zoneinfo import ZoneInfo
 
     from utilities.tempfile import TemporaryDirectory
-    from utilities.types import Number
+    from utilities.types import DateTimeRoundUnit, Number
 
 
 class TestAssumeDoesNotRaise:
@@ -486,6 +489,15 @@ class TestFloatsExtra:
         assert x == round(x)
 
 
+class TestFreqs:
+    @given(data=data(), unit=_freq_units() | none())
+    def test_main(self, *, data: DataObject, unit: DateTimeRoundUnit | None) -> None:
+        freq = data.draw(freqs(unit=unit))
+        assert isinstance(freq, Freq)
+        if unit is not None:
+            assert freq.unit == unit
+
+
 class TestGitRepos:
     @given(data=data())
     @settings_with_reduced_examples()

{dycw_utilities-0.132.4 → dycw_utilities-0.133.1}/src/tests/test_typed_settings.py

@@ -23,6 +23,7 @@ from utilities.hypothesis import (
     date_deltas,
     date_time_deltas,
     dates,
+    freqs,
     plain_datetimes,
     temp_paths,
     text_ascii,
@@ -37,6 +38,7 @@ from utilities.typed_settings import (
     LoadSettingsError,
     load_settings,
 )
+from utilities.whenever import Freq
 
 app_names = text_ascii(min_size=1).map(str.lower)
 
@@ -56,6 +58,7 @@ class TestExtendedTSConverter:
                 date_time_deltas(parsable=True),
                 DateTimeDelta.format_common_iso,
             ),
+            param(Freq, freqs(), Freq.serialize),
             param(IPv4Address, ip_addresses(v=4), IPv4Address),
             param(IPv6Address, ip_addresses(v=6), IPv6Address),
             param(PlainDateTime, plain_datetimes(), PlainDateTime.format_common_iso),

{dycw_utilities-0.132.4 → dycw_utilities-0.133.1}/src/tests/test_whenever.py

@@ -30,12 +30,15 @@ from utilities.hypothesis import (
     assume_does_not_raise,
     date_deltas,
     dates,
+    freqs,
     months,
     pairs,
     sentinels,
     zoned_datetimes,
 )
 from utilities.sentinel import Sentinel, sentinel
+from utilities.types import DateTimeRoundUnit
+from utilities.typing import get_literal_elements
 from utilities.tzdata import HongKong, Tokyo
 from utilities.tzlocal import LOCAL_TIME_ZONE_NAME
 from utilities.whenever import (
@@ -64,12 +67,16 @@ from utilities.whenever import (
     ZERO_DAYS,
     ZONED_DATE_TIME_MAX,
     ZONED_DATE_TIME_MIN,
+    Freq,
     MeanDateTimeError,
     MinMaxDateError,
     Month,
     ToDaysError,
     ToNanosError,
     WheneverLogRecord,
+    _FreqDayIncrementError,
+    _FreqIncrementError,
+    _FreqParseError,
     _MinMaxDateMaxDateError,
     _MinMaxDateMinDateError,
     _MinMaxDatePeriodError,
@@ -128,6 +135,73 @@ class TestFormatCompact:
         assert parsed == expected
 
 
+class TestFreq:
+    @given(freq=freqs())
+    def test_main(self, *, freq: Freq) -> None:
+        _ = get_now().round(unit=freq.unit, increment=freq.increment, mode="floor")
+
+    @given(unit=sampled_from(get_literal_elements(DateTimeRoundUnit)))
+    def test_abbreviate_and_expand(self, *, unit: DateTimeRoundUnit) -> None:
+        result = Freq._expand(Freq._abbreviate(unit))
+        assert result == unit
+
+    @given(freqs=pairs(freqs()))
+    def test_eq(self, *, freqs: tuple[Freq, Freq]) -> None:
+        x, y = freqs
+        result = x == y
+        assert isinstance(result, bool)
+
+    @given(freq=freqs())
+    def test_eq_non_freq(self, *, freq: Freq) -> None:
+        result = freq == 0
+        assert not result
+
+    @given(freq=freqs())
+    def test_hashable(self, *, freq: Freq) -> None:
+        _ = hash(freq)
+
+    @given(freq=freqs())
+    def test_repr(self, *, freq: Freq) -> None:
+        _ = repr(freq)
+
+    @given(freq=freqs())
+    def test_serialize_and_parse(self, *, freq: Freq) -> None:
+        result = Freq.parse(freq.serialize())
+        assert result == freq
+
+    def test_error_day(self) -> None:
+        with raises(
+            _FreqDayIncrementError,
+            match="Increment must be 1 for the 'day' unit; got 2",
+        ):
+            _ = Freq(unit="day", increment=2)
+
+    def test_error_hour(self) -> None:
+        with raises(
+            _FreqIncrementError,
+            match="Increment must be a proper divisor of 24 for the 'hour' unit; got 5",
+        ):
+            _ = Freq(unit="hour", increment=5)
+
+    def test_error_minute(self) -> None:
+        with raises(
+            _FreqIncrementError,
+            match="Increment must be a proper divisor of 60 for the 'minute' unit; got 7",
+        ):
+            _ = Freq(unit="minute", increment=7)
+
+    def test_error_milliseond(self) -> None:
+        with raises(
+            _FreqIncrementError,
+            match="Increment must be a proper divisor of 1000 for the 'millisecond' unit; got 3",
+        ):
+            _ = Freq(unit="millisecond", increment=3)
+
+    def test_error_parse(self) -> None:
+        with raises(_FreqParseError, match="Unable to parse frequency; got 's'"):
+            _ = Freq.parse("s")
+
+
 class TestFromTimeStamp:
     @given(
         datetime=zoned_datetimes(time_zone=timezones()).map(lambda d: d.round("second"))

{dycw_utilities-0.132.4 → dycw_utilities-0.133.1}/src/utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.132.4"
+__version__ = "0.133.1"

dycw_utilities-0.133.1/src/utilities/arq.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import wraps
+from itertools import chain
+from typing import TYPE_CHECKING, Any, ParamSpec, TypeVar, cast, override
+
+from arq.constants import default_queue_name, expires_extra_ms
+from arq.cron import cron
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable, Sequence
+    from datetime import timezone
+
+    from arq.connections import ArqRedis, RedisSettings
+    from arq.cron import CronJob
+    from arq.jobs import Deserializer, Serializer
+    from arq.typing import (
+        OptionType,
+        SecondsTimedelta,
+        StartupShutdown,
+        WeekdayOptionType,
+        WorkerCoroutine,
+    )
+    from arq.worker import Function
+
+    from utilities.types import CallableCoroutine1, Coroutine1, StrMapping
+
+_P = ParamSpec("_P")
+_T = TypeVar("_T")
+
+
+##
+
+
+def cron_raw(
+    coroutine: CallableCoroutine1[Any],
+    /,
+    *,
+    name: str | None = None,
+    month: OptionType = None,
+    day: OptionType = None,
+    weekday: WeekdayOptionType = None,
+    hour: OptionType = None,
+    minute: OptionType = None,
+    second: OptionType = 0,
+    microsecond: int = 123_456,
+    run_at_startup: bool = False,
+    unique: bool = True,
+    job_id: str | None = None,
+    timeout: SecondsTimedelta | None = None,
+    keep_result: float | None = 0,
+    keep_result_forever: bool | None = False,
+    max_tries: int | None = 1,
+    args: Iterable[Any] | None = None,
+    kwargs: StrMapping | None = None,
+) -> CronJob:
+    """Create a cron job with a raw coroutine function."""
+    lifted = _lift_cron(
+        coroutine, *(() if args is None else args), **({} if kwargs is None else kwargs)
+    )
+    return cron(
+        lifted,
+        name=name,
+        month=month,
+        day=day,
+        weekday=weekday,
+        hour=hour,
+        minute=minute,
+        second=second,
+        microsecond=microsecond,
+        run_at_startup=run_at_startup,
+        unique=unique,
+        job_id=job_id,
+        timeout=timeout,
+        keep_result=keep_result,
+        keep_result_forever=keep_result_forever,
+        max_tries=max_tries,
+    )
+
+
+def _lift_cron(
+    func: Callable[_P, Coroutine1[_T]], *args: _P.args, **kwargs: _P.kwargs
+) -> WorkerCoroutine:
+    """Lift a coroutine function & call arg/kwargs for `cron`."""
+
+    @wraps(func)
+    async def wrapped(ctx: StrMapping, /) -> _T:
+        _ = ctx
+        return await func(*args, **kwargs)
+
+    return cast("Any", wrapped)
+
+
+##
+
+
+class _WorkerMeta(type):
+    @override
+    def __new__(
+        mcs: type[_WorkerMeta],
+        name: str,
+        bases: tuple[type, ...],
+        namespace: dict[str, Any],
+        /,
+    ) -> type[Worker]:
+        cls = cast("type[Worker]", super().__new__(mcs, name, bases, namespace))
+        cls.functions = tuple(chain(cls.functions, map(cls._lift, cls.functions_raw)))
+        return cls
+
+    @classmethod
+    def _lift(cls, func: Callable[_P, Coroutine1[_T]]) -> WorkerCoroutine:
+        """Lift a coroutine function to accept the required `ctx` argument."""
+
+        @wraps(func)
+        async def wrapped(ctx: StrMapping, *args: _P.args, **kwargs: _P.kwargs) -> _T:
+            _ = ctx
+            return await func(*args, **kwargs)
+
+        return cast("Any", wrapped)
+
+
+@dataclass(kw_only=True)
+class Worker(metaclass=_WorkerMeta):
+    """Base class for all workers."""
+
+    functions: Sequence[Function | WorkerCoroutine] = ()
+    functions_raw: Sequence[CallableCoroutine1[Any]] = ()
+    queue_name: str | None = default_queue_name
+    cron_jobs: Sequence[CronJob] | None = None
+    redis_settings: RedisSettings | None = None
+    redis_pool: ArqRedis | None = None
+    burst: bool = False
+    on_startup: StartupShutdown | None = None
+    on_shutdown: StartupShutdown | None = None
+    on_job_start: StartupShutdown | None = None
+    on_job_end: StartupShutdown | None = None
+    after_job_end: StartupShutdown | None = None
+    handle_signals: bool = True
+    job_completion_wait: int = 0
+    max_jobs: int = 10
+    job_timeout: SecondsTimedelta = 300
+    keep_result: SecondsTimedelta = 3600
+    keep_result_forever: bool = False
+    poll_delay: SecondsTimedelta = 0.5
+    queue_read_limit: int | None = None
+    max_tries: int = 5
+    health_check_interval: SecondsTimedelta = 3600
+    health_check_key: str | None = None
+    ctx: dict[Any, Any] | None = None
+    retry_jobs: bool = True
+    allow_abort_jobs: bool = False
+    max_burst_jobs: int = -1
+    job_serializer: Serializer | None = None
+    job_deserializer: Deserializer | None = None
+    expires_extra_ms: int = expires_extra_ms
+    timezone: timezone | None = None
+    log_results: bool = True
+
+
+__all__ = ["Worker", "cron"]

{dycw_utilities-0.132.4 → dycw_utilities-0.133.1}/src/utilities/click.py

@@ -29,7 +29,7 @@ from utilities.types import (
     TimeLike,
     ZonedDateTimeLike,
 )
-from utilities.whenever import _MonthParseCommonISOError
+from utilities.whenever import FreqLike, _FreqParseError, _MonthParseCommonISOError
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Sequence
@@ -177,6 +177,30 @@ class Enum(ParamType, Generic[TEnum]):
         return _make_metavar(param, desc)
 
 
+class Freq(ParamType):
+    """An frequency-valued parameter."""
+
+    @override
+    def __repr__(self) -> str:
+        return "FREQ"
+
+    @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)
+
+
 class IPv4Address(ParamType):
     """An IPv4 address-valued parameter."""
 
@@ -519,6 +543,7 @@ __all__ = [
     "ExistingDirPath",
     "ExistingFilePath",
     "FilePath",
+    "Freq",
     "FrozenSetChoices",
     "FrozenSetEnums",
     "FrozenSetParameter",

{dycw_utilities-0.132.4 → dycw_utilities-0.133.1}/src/utilities/hypothesis.py

@@ -77,6 +77,8 @@ from utilities.pathlib import temp_cwd
 from utilities.platform import IS_WINDOWS
 from utilities.sentinel import Sentinel, sentinel
 from utilities.tempfile import TEMP_DIR, TemporaryDirectory
+from utilities.types import DateTimeRoundUnit
+from utilities.typing import get_literal_elements
 from utilities.version import Version
 from utilities.whenever import (
     DATE_DELTA_MAX,
@@ -100,6 +102,7 @@ from utilities.whenever import (
     TIME_DELTA_MIN,
     TIME_MAX,
     TIME_MIN,
+    Freq,
     Month,
     to_date_time_delta,
     to_days,
@@ -502,6 +505,38 @@ def floats_extra(
 ##
 
 
+@composite
+def freqs(
+    draw: DrawFn, /, *, unit: MaybeSearchStrategy[DateTimeRoundUnit | None] = None
+) -> Freq:
+    unit_ = draw2(draw, unit, _freq_units())
+    match unit_:
+        case "day":
+            return Freq(unit=unit_)
+        case "hour":
+            return Freq(unit=unit_, increment=draw(_freq_increments(24)))
+        case "minute" | "second":
+            return Freq(unit=unit_, increment=draw(_freq_increments(60)))
+        case "millisecond" | "microsecond" | "nanosecond":
+            return Freq(unit=unit_, increment=draw(_freq_increments(1000)))
+        case _ as never:
+            assert_never(never)
+
+
+@composite
+def _freq_units(draw: DrawFn, /) -> DateTimeRoundUnit:
+    return draw(sampled_from(get_literal_elements(DateTimeRoundUnit)))
+
+
+@composite
+def _freq_increments(draw: DrawFn, n: int, /) -> int:
+    divisors = [i for i in range(1, n) if n % i == 0]
+    return draw(sampled_from(divisors))
+
+
+##
+
+
 @composite
 def git_repos(draw: DrawFn, /) -> Path:
     path = draw(temp_paths())
@@ -1264,6 +1299,7 @@ __all__ = [
     "float64s",
     "float_arrays",
     "floats_extra",
+    "freqs",
     "git_repos",
     "hashables",
     "int32s",

{dycw_utilities-0.132.4 → dycw_utilities-0.133.1}/src/utilities/typed_settings.py

@@ -21,6 +21,7 @@ from whenever import (
 )
 
 from utilities.iterables import always_iterable
+from utilities.whenever import Freq
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -52,6 +53,7 @@ class ExtendedTSConverter(TSConverter):
             (Date, Date.parse_common_iso),
             (DateDelta, DateDelta.parse_common_iso),
             (DateTimeDelta, DateTimeDelta.parse_common_iso),
+            (Freq, Freq.parse),
             (IPv4Address, IPv4Address),
             (IPv6Address, IPv6Address),
             (PlainDateTime, PlainDateTime.parse_common_iso),

{dycw_utilities-0.132.4 → dycw_utilities-0.133.1}/src/utilities/types.py

@@ -72,12 +72,16 @@ type Coroutine1[_T] = Coroutine[Any, Any, _T]
 type MaybeAwaitable[_T] = _T | Awaitable[_T]
 type MaybeCallableEvent = MaybeCallable[Event]
 type MaybeCoroutine1[_T] = _T | Coroutine1[_T]
+type CallableCoroutine1[_T] = Callable[..., Coroutine1[_T]]
 
 
 # callable
 TCallable = TypeVar("TCallable", bound=Callable[..., Any])
 TCallable1 = TypeVar("TCallable1", bound=Callable[..., Any])
 TCallable2 = TypeVar("TCallable2", bound=Callable[..., Any])
+TCallableCoroutine1 = TypeVar(
+    "TCallableCoroutine1", bound=Callable[..., Coroutine1[Any]]
+)
 TCallableMaybeCoroutine1None = TypeVar(
     "TCallableMaybeCoroutine1None", bound=Callable[..., MaybeCoroutine1[None]]
 )
@@ -292,6 +296,7 @@ type TimeZoneLike = (
 
 
 __all__ = [
+    "CallableCoroutine1",
     "Coroutine1",
     "Dataclass",
     "DateDeltaLike",
@@ -346,6 +351,7 @@ __all__ = [
     "TCallable",
     "TCallable1",
     "TCallable2",
+    "TCallableCoroutine1",
     "TCallableMaybeCoroutine1None",
     "TDataclass",
     "TEnum",