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

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

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

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

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

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

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from collections.abc import Callable, Iterable
+from collections.abc import Callable, Iterable, Mapping
 from dataclasses import dataclass, replace
 from functools import cache
 from logging import LogRecord
@@ -8,9 +8,12 @@ from statistics import fmean
 from typing import (
     TYPE_CHECKING,
     Any,
+    ClassVar,
+    Literal,
     Self,
     SupportsFloat,
     assert_never,
+    cast,
     overload,
     override,
 )
@@ -28,7 +31,7 @@ from utilities.math import sign
 from utilities.platform import get_strftime
 from utilities.re import ExtractGroupsError, extract_groups
 from utilities.sentinel import Sentinel, sentinel
-from utilities.types import MaybeStr
+from utilities.types import DateTimeRoundUnit, MaybeStr
 from utilities.tzlocal import LOCAL_TIME_ZONE, LOCAL_TIME_ZONE_NAME
 from utilities.zoneinfo import UTC, get_time_zone_name
 
@@ -166,6 +169,127 @@ def format_compact(datetime: ZonedDateTime, /) -> str:
 ##
 
 
+class Freq:
+    """A rounding frequency."""
+
+    unit: DateTimeRoundUnit
+    increment: int
+    _mapping: ClassVar[Mapping[DateTimeRoundUnit, _DateTimeRoundUnitAbbrev]] = {
+        "day": "D",
+        "hour": "H",
+        "minute": "M",
+        "second": "S",
+        "millisecond": "ms",
+        "microsecond": "us",
+        "nanosecond": "ns",
+    }
+
+    def __init__(
+        self, *, unit: DateTimeRoundUnit = "second", increment: int = 1
+    ) -> None:
+        super().__init__()
+        if (unit == "day") and (increment != 1):
+            raise _FreqDayIncrementError(increment=increment)
+        if (unit == "hour") and not ((0 < increment < 24) and (24 % increment == 0)):
+            raise _FreqIncrementError(unit=unit, increment=increment, divisor=24)
+        if (unit in {"minute", "second"}) and not (
+            (0 < increment < 60) and (60 % increment == 0)
+        ):
+            raise _FreqIncrementError(unit=unit, increment=increment, divisor=60)
+        if (unit in {"millisecond", "microsecond", "nanosecond"}) and not (
+            (0 < increment < 1000) and (1000 % increment == 0)
+        ):
+            raise _FreqIncrementError(unit=unit, increment=increment, divisor=1000)
+        self.unit = unit
+        self.increment = increment
+
+    @override
+    def __eq__(self, other: object, /) -> bool:
+        if not isinstance(other, Freq):
+            return NotImplemented
+        return (self.unit == other.unit) and (self.increment == other.increment)
+
+    @override
+    def __hash__(self) -> int:
+        return hash((self.unit, self.increment))
+
+    @override
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(unit={self.unit!r}, increment={self.increment})"
+
+    @classmethod
+    def parse(cls, text: str, /) -> Self:
+        try:
+            increment, abbrev = extract_groups(r"^(\d*)(D|H|M|S|ms|us|ns)$", text)
+        except ExtractGroupsError:
+            raise _FreqParseError(text=text) from None
+        return cls(
+            unit=cls._expand(cast("_DateTimeRoundUnitAbbrev", abbrev)),
+            increment=int(increment) if len(increment) >= 1 else 1,
+        )
+
+    def serialize(self) -> str:
+        if self.increment == 1:
+            return self._abbreviation
+        return f"{self.increment}{self._abbreviation}"
+
+    @classmethod
+    def _abbreviate(cls, unit: DateTimeRoundUnit, /) -> _DateTimeRoundUnitAbbrev:
+        return cls._mapping[unit]
+
+    @property
+    def _abbreviation(self) -> _DateTimeRoundUnitAbbrev:
+        return self._mapping[self.unit]
+
+    @classmethod
+    def _expand(cls, unit: _DateTimeRoundUnitAbbrev, /) -> DateTimeRoundUnit:
+        values: set[DateTimeRoundUnit] = {
+            k for k, v in cls._mapping.items() if v == unit
+        }
+        (value,) = values
+        return value
+
+
+type FreqLike = MaybeStr[Freq]
+type _DateTimeRoundUnitAbbrev = Literal["D", "H", "M", "S", "ms", "us", "ns"]
+
+
+@dataclass(kw_only=True, slots=True)
+class FreqError(Exception): ...
+
+
+@dataclass(kw_only=True, slots=True)
+class _FreqDayIncrementError(FreqError):
+    increment: int
+
+    @override
+    def __str__(self) -> str:
+        return f"Increment must be 1 for the 'day' unit; got {self.increment}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _FreqIncrementError(FreqError):
+    unit: DateTimeRoundUnit
+    increment: int
+    divisor: int
+
+    @override
+    def __str__(self) -> str:
+        return f"Increment must be a proper divisor of {self.divisor} for the {self.unit!r} unit; got {self.increment}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _FreqParseError(FreqError):
+    text: str
+
+    @override
+    def __str__(self) -> str:
+        return f"Unable to parse frequency; got {self.text!r}"
+
+
+##
+
+
 def from_timestamp(i: float, /, *, time_zone: TimeZoneLike = UTC) -> ZonedDateTime:
     """Get a zoned datetime from a timestamp."""
     return ZonedDateTime.from_timestamp(i, tz=get_time_zone_name(time_zone))
@@ -736,6 +860,9 @@ __all__ = [
     "ZONED_DATE_TIME_MAX",
     "ZONED_DATE_TIME_MIN",
     "DateOrMonth",
+    "Freq",
+    "FreqError",
+    "FreqLike",
     "MeanDateTimeError",
     "MinMaxDateError",
     "Month",