Implement basic ItemizedDelta

Author: ariebovenberg

docs/api.rst

@@ -102,18 +102,6 @@ Concrete classes
 Deltas
 ------
 
-.. autofunction:: whenever.years
-.. autofunction:: whenever.months
-.. autofunction:: whenever.weeks
-.. autofunction:: whenever.days
-
-.. autofunction:: whenever.hours
-.. autofunction:: whenever.minutes
-.. autofunction:: whenever.seconds
-.. autofunction:: whenever.milliseconds
-.. autofunction:: whenever.microseconds
-.. autofunction:: whenever.nanoseconds
-
 .. autoclass:: whenever.TimeDelta
    :members:
    :special-members: __eq__, __neg__, __add__, __sub__, __mul__, __truediv__, __bool__, __abs__, __gt__
@@ -132,6 +120,11 @@ Deltas
    :special-members: __eq__, __neg__, __abs__, __add__, __sub__, __bool__, __mul__
    :member-order: bysource
 
+.. autoclass:: whenever.ItemizedDelta
+   :members:
+   :special-members: __eq__, __neg__, __abs__, __add__, __sub__, __bool__, __mul__
+   :member-order: bysource
+
 .. _date-and-time-api:
 
 Date and time components

docs/deltas.rst

@@ -13,37 +13,48 @@ For example, you might want to reuse a particular duration,
 or perform arithmetic on it.
 For this, **whenever** provides an API
 designed to help you avoid common pitfalls.
-The type annotations and descriptive errors should guide you
-to the correct usage.
 
-Durations are created using the duration units provided.
-Here is a quick demo:
+There are two main kind of deltas:
+
+- :class:`~whenever.TimeDelta` for precise time durations
+  (hours, minutes, seconds, microseconds). This type supports mathematical
+  operations like addition, subtraction, multiplication, and division.
+  Arithmetic on time units is straightforward.
+  It behaves similarly to the :class:`~datetime.timedelta`
+  of the standard library.
+  The drawback is that `TimeDelta` doesn't support calender units
+  like months or years, as their duration varies depending on context.
+  That's where the second type comes in:
+- :class:`~whenever.ItemizedDelta` for calendar-based durations.
+   They don't have a precise duration, as this depends on the context.
+   For example, the number of days in a month varies, and a day may be
+   longer or shorter than 24 hours due to Daylight Saving Time.
+   This makes arithmetic on calendar units less intuitive.
+   In general, arithmetic on these delta's on their own is not supported,
+   a local date/time is needed to provide context.
 
->>> from whenever import years, months, days, hours, minutes
->>> # Precise units create a TimeDelta, supporting broad arithmetic
->>> movie_runtime = hours(2) + minutes(9)
-TimeDelta(02:09:00)
+.. note::
+
+   There also is a third type, :class:`~whenever.ItemizedDateDelta`.
+   It behaves similarly to `ItemizedDelta`, but contains *only* calendar units.
+
+>>> movie_runtime = TimeDelta(hours=2, minutes=9)
+TimeDelta("PT2h9m")
 >>> movie_runtime.in_minutes()
 129.0
 >>> movie_runtime / 1.2  # what if we watch it at 1.2x speed?
-TimeDelta(01:47:30)
-...
->>> # Calendar units create a DateDelta, with more limited arithmetic
->>> project_estimate = months(1) + days(10)
-DateDelta("P1M10D")
->>> Date(2023, 1, 29) + project_estimate
-Date("2023-03-10")
->>> project_estimate * 2  # make it pessimistic
-DateDelta("P2M20D")
-...
->>> # Mixing date and time units creates a generic DateTimeDelta
->>> project_estimate + movie_runtime
-DateTimeDelta("P1M10DT2H9M")
-...
+TimeDelta("Pt1h47m30s")
+>>> Instant.now() + movie_runtime  # when does it end?
+
+
+>>> # If needed, composite, unnormalized durations can be created:
+>>> room_occupied = ItemizedDelta(months=1, days=10, minutes=90)
+ItemizedDelta("P1m10dT90m")
+
 >>> # API ensures common mistakes are caught early:
->>> project_estimate * 1.3             # Impossible arithmetic on calendar units
->>> project_estimate.in_hours()        # Resolving calendar units without context
->>> Date(2023, 1, 29) + movie_runtime  # Adding time to a date
+>>> room_occupied * 1.3        # Impossible arithmetic on calendar units
+>>> room_occupied.in_hours()   # Resolving calendar units without context
+>>> Date(2023, 1, 29) + room_occupied   # Adding time to a date
 
 Types of deltas
 ---------------
@@ -53,18 +64,10 @@ There are three duration types in **whenever**:
 -  :class:`~whenever.TimeDelta`, created by precise units
    :func:`~whenever.hours`, :func:`~whenever.minutes`, :func:`~whenever.seconds`,
    and :func:`~whenever.microseconds`.
-   Their duration is always the same and independent of the calendar.
-   Arithmetic on time units is straightforward.
-   It behaves similarly to the :class:`~datetime.timedelta`
-   of the standard library.
 
 -  :class:`~whenever.DateDelta`, created by the calendar units
    :func:`~whenever.years`, :func:`~whenever.months`, :func:`~whenever.weeks`,
    and :func:`~whenever.days`.
-   They don't have a precise duration, as this depends on the context.
-   For example, the number of days in a month varies, and a day may be
-   longer or shorter than 24 hours due to Daylight Saving Time.
-   This makes arithmetic on calendar units less intuitive.
 
 -  :class:`~whenever.DateTimeDelta`, created when you mix
    time and calendar units.

pyproject.toml

@@ -7,7 +7,7 @@ maintainers = [
     {name = "Arie Bovenberg", email = "a.c.bovenberg@gmail.com"},
 ]
 readme = "README.md"
-version = "0.9.4"
+version = "0.10.0"
 license = "MIT"
 description = "Modern datetime library for Python"
 requires-python = ">=3.9"

pysrc/whenever/__init__.py

@@ -32,7 +32,7 @@
 
 # Yes, we could get the version with importlib.metadata,
 # but we try to keep our import time as low as possible.
-__version__ = "0.9.4"
+__version__ = "0.10.0"
 
 reset_tzpath()  # populate the tzpath once at startup
 

pysrc/whenever/__init__.pyi

@@ -14,6 +14,7 @@ from typing import (
     Iterable,
     Literal,
     TypeAlias,
+    TypedDict,
     final,
     overload,
     type_check_only,
@@ -253,6 +254,38 @@ class TimeDelta(_DeltaMixin, _OrderMixin):
     def in_microseconds(self) -> float: ...
     def in_nanoseconds(self) -> int: ...
     def in_hrs_mins_secs_nanos(self) -> tuple[int, int, int, int]: ...
+    def in_units(
+        self,
+        *units: Literal[
+            "days",
+            "hours",
+            "minutes",
+            "seconds",
+            "nanoseconds",
+        ],
+        round_mode: Literal[
+            "ceil", "floor", "half_ceil", "half_floor", "half_even"
+        ] = ...,
+        round_increment: int = ...,
+        round_unit: Literal[
+            "day",
+            "hour",
+            "minute",
+            "second",
+            "millisecond",
+            "microsecond",
+            "nanosecond",
+        ] = ...,
+    ) -> float: ...
+    def itemize(
+        self,
+        *,
+        units: tuple[str, ...],
+        round_mode: Literal[
+            "ceil", "floor", "half_ceil", "half_floor", "half_even"
+        ] = ...,
+        round_increment: int = ...,
+    ) -> ItemizedDelta: ...
     def py_timedelta(self) -> _timedelta: ...
     @classmethod
     def from_py_timedelta(cls, td: _timedelta, /) -> Self: ...
@@ -305,6 +338,53 @@ class DateDelta(_DeltaMixin):
     def __sub__(self, other: TimeDelta, /) -> DateTimeDelta: ...
     def __rsub__(self, other: TimeDelta, /) -> DateTimeDelta: ...
 
+class DeltaDict(TypedDict, total=False):
+    years: int
+    months: int
+    weeks: int
+    days: int
+    hours: int
+    minutes: int
+    seconds: int
+    nanoseconds: int
+
+@final
+class ItemizedDelta:
+    def __init__(
+        self,
+        *,
+        years: int = ...,
+        months: int = ...,
+        weeks: int = ...,
+        days: int = ...,
+        hours: int = ...,
+        minutes: int = ...,
+        seconds: int = ...,
+        nanoseconds: int = ...,
+    ) -> None: ...
+    @property
+    def sign(self) -> Literal[1, 0, -1]: ...
+    @property
+    def years(self) -> int: ...
+    @property
+    def months(self) -> int: ...
+    @property
+    def weeks(self) -> int: ...
+    @property
+    def days(self) -> int: ...
+    @property
+    def hours(self) -> int: ...
+    @property
+    def minutes(self) -> int: ...
+    @property
+    def seconds(self) -> int: ...
+    def float_seconds(self) -> float: ...
+    def values(self) -> tuple[int, ...]: ...
+    def as_dict(self) -> DeltaDict: ...
+    def format_iso(self, *, lowercase_units: bool = False) -> str: ...
+    @classmethod
+    def parse_iso(cls, s: str, /) -> Self: ...
+
 @final
 class DateTimeDelta(_DeltaMixin):
     @overload

pysrc/whenever/_core.py

@@ -48,6 +48,7 @@
         _unpkl_tdelta,
         _unpkl_time,
         _unpkl_utc,
+        _unpkl_vdelta,
         _unpkl_ym,
         _unpkl_zoned,
     )