dycw-utilities 0.138.12__tar.gz → 0.138.14__tar.gz

{dycw_utilities-0.138.12 → dycw_utilities-0.138.14}/PKG-INFO

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

{dycw_utilities-0.138.12 → dycw_utilities-0.138.14}/pyproject.toml

@@ -36,7 +36,7 @@ dev = [
   "pytest-timeout >= 2.4.0, < 2.5",
 ]
 eventkit = ["eventkit >= 1.0.3, < 1.1"]
-fastapi = ["fastapi >= 0.115.11, < 0.116"]
+fastapi = ["fastapi >= 0.115.14, < 0.116"]
 fastapi-test = ["httpx", "uvicorn"]
 fpdf2 = ["fpdf2 >= 2.8.3, < 2.9"]
 hashlib-test = ["orjson"]
@@ -106,7 +106,7 @@ dependencies = [
 name = "dycw-utilities"
 readme = "README.md"
 requires-python = ">= 3.12"
-version = "0.138.12"
+version = "0.138.14"
 
 [project.entry-points.pytest11]
 pytest-regressions = "utilities.pytest_regressions_plugin"
@@ -137,7 +137,7 @@ test = [
 # bump-my-version
 [tool.bumpversion]
 allow_dirty = true
-current_version = "0.138.12"
+current_version = "0.138.14"
 
 [[tool.bumpversion.files]]
 filename = "src/utilities/__init__.py"

{dycw_utilities-0.138.12 → dycw_utilities-0.138.14}/src/tests/test_whenever.py

@@ -64,6 +64,7 @@ from utilities.whenever import (
     MeanDateTimeError,
     MinMaxDateError,
     ToDaysError,
+    ToMonthsError,
     ToNanosError,
     ToPyTimeDeltaError,
     WheneverLogRecord,
@@ -74,6 +75,7 @@ from utilities.whenever import (
     _MinMaxDateMinDateError,
     _MinMaxDatePeriodError,
     datetime_utc,
+    diff_year_month,
     format_compact,
     from_timestamp,
     from_timestamp_millis,
@@ -88,6 +90,7 @@ from utilities.whenever import (
     to_date_time_delta,
     to_days,
     to_local_plain,
+    to_months,
     to_nanos,
     to_py_time_delta,
     to_time_delta,
@@ -97,6 +100,8 @@ from utilities.whenever import (
 from utilities.zoneinfo import UTC
 
 if TYPE_CHECKING:
+    from _pytest.mark import ParameterSet
+
     from utilities.sentinel import Sentinel
     from utilities.types import MaybeCallableDate, MaybeCallableZonedDateTime
 
@@ -116,6 +121,35 @@ class TestDatetimeUTC:
         assert result == datetime
 
 
+class TestDiffYearMonth:
+    x: ClassVar[YearMonth] = YearMonth(2005, 7)
+    cases: ClassVar[list[ParameterSet]] = [
+        param(YearMonth(2004, 7), 1, 0),
+        param(YearMonth(2004, 8), 0, 11),
+        param(YearMonth(2005, 1), 0, 6),
+        param(YearMonth(2005, 5), 0, 2),
+        param(YearMonth(2005, 6), 0, 1),
+        param(YearMonth(2005, 7), 0, 0),
+        param(YearMonth(2005, 8), 0, -1),
+        param(YearMonth(2005, 9), 0, -2),
+        param(YearMonth(2006, 1), 0, -6),
+        param(YearMonth(2006, 6), 0, -11),
+        param(YearMonth(2006, 7), -1, 0),
+    ]
+
+    @mark.parametrize(("y", "year", "month"), cases)
+    def test_main(self, *, y: YearMonth, year: int, month: int) -> None:
+        result = diff_year_month(self.x, y)
+        expected = 12 * year + month
+        assert result == expected
+
+    @mark.parametrize(("y", "year", "month"), cases)
+    def test_year_and_month(self, *, y: YearMonth, year: int, month: int) -> None:
+        result = diff_year_month(self.x, y, years=True)
+        expected = (year, month)
+        assert result == expected
+
+
 class TestFormatCompact:
     @given(date=dates())
     def test_date(self, *, date: Date) -> None:
@@ -523,6 +557,24 @@ class TestToLocalPlain:
         assert isinstance(result, PlainDateTime)
 
 
+class TestToMonths:
+    @given(months=integers())
+    def test_main(self, *, months: int) -> None:
+        with (
+            assume_does_not_raise(ValueError, match="months out of range"),
+            assume_does_not_raise(
+                OverflowError, match="Python int too large to convert to C long"
+            ),
+        ):
+            delta = DateDelta(months=months)
+        assert to_months(delta) == months
+
+    def test_error(self) -> None:
+        delta = DateDelta(days=1)
+        with raises(ToMonthsError, match="Date delta must not contain days; got 1"):
+            _ = to_months(delta)
+
+
 class TestToPyTimeDelta:
     @mark.parametrize(
         ("delta", "expected"),

{dycw_utilities-0.138.12 → dycw_utilities-0.138.14}/src/utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.138.12"
+__version__ = "0.138.14"

{dycw_utilities-0.138.12 → dycw_utilities-0.138.14}/src/utilities/whenever.py

@@ -155,6 +155,34 @@ def datetime_utc(
 ##
 
 
+@overload
+def diff_year_month(
+    x: YearMonth, y: YearMonth, /, *, years: Literal[True]
+) -> tuple[int, int]: ...
+@overload
+def diff_year_month(
+    x: YearMonth, y: YearMonth, /, *, years: Literal[False] = False
+) -> int: ...
+@overload
+def diff_year_month(
+    x: YearMonth, y: YearMonth, /, *, years: bool = False
+) -> int | tuple[int, int]: ...
+def diff_year_month(
+    x: YearMonth, y: YearMonth, /, *, years: bool = False
+) -> int | tuple[int, int]:
+    """Compute the difference between two year-months."""
+    x_date, y_date = x.on_day(1), y.on_day(1)
+    diff = x_date - y_date
+    if years:
+        yrs, mth, _ = diff.in_years_months_days()
+        return yrs, mth
+    mth, _ = diff.in_months_days()
+    return mth
+
+
+##
+
+
 def format_compact(
     obj: Date | Time | PlainDateTime | ZonedDateTime, /, *, fmt: str | None = None
 ) -> str:
@@ -552,6 +580,26 @@ def to_local_plain(date_time: ZonedDateTime, /) -> PlainDateTime:
 ##
 
 
+def to_months(delta: DateDelta, /) -> int:
+    """Compute the number of months in a date delta."""
+    months, days = delta.in_months_days()
+    if days != 0:
+        raise ToMonthsError(days=days)
+    return months
+
+
+@dataclass(kw_only=True, slots=True)
+class ToMonthsError(Exception):
+    days: int
+
+    @override
+    def __str__(self) -> str:
+        return f"Date delta must not contain days; got {self.days}"
+
+
+##
+
+
 def to_nanos(delta: DateTimeDelta, /) -> int:
     """Compute the number of nanoseconds in a date-time delta."""
     try:
@@ -801,10 +849,12 @@ __all__ = [
     "MeanDateTimeError",
     "MinMaxDateError",
     "ToDaysError",
+    "ToMonthsError",
     "ToNanosError",
     "ToPyTimeDeltaError",
     "WheneverLogRecord",
     "datetime_utc",
+    "diff_year_month",
     "format_compact",
     "from_timestamp",
     "from_timestamp_millis",
@@ -819,6 +869,7 @@ __all__ = [
     "to_date_time_delta",
     "to_days",
     "to_local_plain",
+    "to_months",
     "to_nanos",
     "to_py_time_delta",
     "to_zoned_date_time",