dycw-utilities 0.133.0__tar.gz → 0.133.2__tar.gz

{dycw_utilities-0.133.0 → dycw_utilities-0.133.2}/PKG-INFO

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

{dycw_utilities-0.133.0 → dycw_utilities-0.133.2}/pyproject.toml

@@ -30,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",
 ]
@@ -103,7 +104,7 @@ dependencies = [
 name = "dycw-utilities"
 readme = "README.md"
 requires-python = ">= 3.12"
-version = "0.133.0"
+version = "0.133.2"
 
 [project.optional-dependencies]
 logging = [
@@ -129,7 +130,7 @@ test = [
 # bump-my-version
 [tool.bumpversion]
 allow_dirty = true
-current_version = "0.133.0"
+current_version = "0.133.2"
 
 [[tool.bumpversion.files]]
 filename = "src/utilities/__init__.py"
@@ -238,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.0 → dycw_utilities-0.133.2}/src/tests/test_arq.py

@@ -3,45 +3,56 @@ from __future__ import annotations
 from asyncio import sleep
 from typing import TYPE_CHECKING, Any, cast
 
+from arq.connections import ArqRedis
 from hypothesis import given
 from hypothesis.strategies import integers
 
-from utilities.arq import Worker, cron_raw
+from tests.conftest import SKIPIF_CI_AND_NOT_LINUX
+from utilities.arq import Worker, cron_raw, job_enqueuer
 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:
+class TestCronRaw:
     @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)
+        job = cron_raw(func, args=(x, y))
+        result = await job.coroutine({})
         assert result == (x + y)
 
+
+class TestJobEnqueuer:
+    @given(x=integers(), y=integers())
+    @SKIPIF_CI_AND_NOT_LINUX
+    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
+
+        redis = ArqRedis(db=15)
+        _ = await job_enqueuer.settings(queue_name="test")(redis, func, x, y)
+
+
+class TestWorker:
     @given(x=integers(), y=integers())
-    async def test_cron(self, *, x: int, y: int) -> None:
+    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):
-            cron_jobs: Sequence[CronJob] | None = [cron_raw(func, args=(x, y))]
+            functions_raw: Sequence[CallableCoroutine1[Any]] = [func]
 
-        assert Example.cron_jobs is not None
-        cron_job = one(Example.cron_jobs)
-        result = await cron_job.coroutine({})
+        func_use = cast("WorkerCoroutine", one(Example.functions))
+        result = await func_use({}, x, y)
         assert result == (x + y)

{dycw_utilities-0.133.0 → dycw_utilities-0.133.2}/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.133.0 → dycw_utilities-0.133.2}/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.133.0 → dycw_utilities-0.133.2}/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.133.0 → dycw_utilities-0.133.2}/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.133.0 → dycw_utilities-0.133.2}/src/utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.133.0"
+__version__ = "0.133.2"

{dycw_utilities-0.133.0 → dycw_utilities-0.133.2}/src/utilities/arq.py

@@ -3,18 +3,21 @@ 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 typing import TYPE_CHECKING, Any, ParamSpec, Self, TypeVar, cast, override
 
 from arq.constants import default_queue_name, expires_extra_ms
 from arq.cron import cron
 
+from utilities.dataclasses import replace_non_sentinel
+from utilities.sentinel import Sentinel, sentinel
+
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Sequence
-    from datetime import timezone
+    from datetime import datetime, timedelta, timezone
 
     from arq.connections import ArqRedis, RedisSettings
     from arq.cron import CronJob
-    from arq.jobs import Deserializer, Serializer
+    from arq.jobs import Deserializer, Job, Serializer
     from arq.typing import (
         OptionType,
         SecondsTimedelta,
@@ -26,6 +29,7 @@ if TYPE_CHECKING:
 
     from utilities.types import CallableCoroutine1, Coroutine1, StrMapping
 
+
 _P = ParamSpec("_P")
 _T = TypeVar("_T")
 
@@ -95,6 +99,64 @@ def _lift_cron(
 ##
 
 
+@dataclass(kw_only=True, slots=True)
+class _JobEnqueuer:
+    """Enqueuer of jobs."""
+
+    job_id: str | None = None
+    queue_name: str | None = None
+    defer_until: datetime | None = None
+    defer_by: int | float | timedelta | None = None
+    expires: int | float | timedelta | None = None
+    job_try: int | None = None
+
+    async def __call__(
+        self,
+        redis: ArqRedis,
+        function: Callable[_P, Coroutine1[_T]],
+        *args: _P.args,
+        **kwargs: _P.kwargs,
+    ) -> Job | None:
+        return await redis.enqueue_job(  # skipif-ci-and-not-linux
+            function.__name__,
+            *args,
+            _job_id=self.job_id,
+            _queue_name=self.queue_name,
+            _defer_until=self.defer_until,
+            _defer_by=self.defer_by,
+            _expires=self.expires,
+            _job_try=self.job_try,
+            **kwargs,
+        )
+
+    def settings(
+        self,
+        *,
+        job_id: str | None | Sentinel = sentinel,
+        queue_name: str | None | Sentinel = sentinel,
+        defer_until: datetime | None | Sentinel = sentinel,
+        defer_by: float | timedelta | None | Sentinel = sentinel,
+        expires: float | timedelta | None | Sentinel = sentinel,
+        job_try: int | None | Sentinel = sentinel,
+    ) -> Self:
+        """Replace elements of the enqueuer."""
+        return replace_non_sentinel(  # skipif-ci-and-not-linux
+            self,
+            job_id=job_id,
+            queue_name=queue_name,
+            defer_until=defer_until,
+            defer_by=defer_by,
+            expires=expires,
+            job_try=job_try,
+        )
+
+
+job_enqueuer = _JobEnqueuer()
+
+
+##
+
+
 class _WorkerMeta(type):
     @override
     def __new__(
@@ -158,4 +220,4 @@ class Worker(metaclass=_WorkerMeta):
     log_results: bool = True
 
 
-__all__ = ["Worker", "cron"]
+__all__ = ["Worker", "cron", "job_enqueuer"]

{dycw_utilities-0.133.0 → dycw_utilities-0.133.2}/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.133.0 → dycw_utilities-0.133.2}/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.133.0 → dycw_utilities-0.133.2}/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),