Add duration logic for uncertain years

Author: rlskoeser

src/undate/converters/base.py

@@ -162,6 +162,10 @@ def max_day(self, year: int, month: int) -> int:
         """maximum numeric day for the specified year and month in this calendar"""
         raise NotImplementedError
 
+    def days_in_year(self, year: int) -> int:
+        """number of days in the specified year in this calendar"""
+        raise NotImplementedError
+
     def to_gregorian(self, year, month, day) -> tuple[int, int, int]:
         """Convert a date for this calendar specified by numeric year, month, and day,
         into the Gregorian equivalent date. Should return a tuple of year, month, day.

src/undate/converters/calendars/hebrew/converter.py

@@ -47,6 +47,10 @@ def max_day(self, year: int, month: int) -> int:
         # NOTE: unreleased v2.4.1 of convertdate standardizes month_days to month_length
         return hebrew.month_days(year, month)
 
+    def days_in_year(self, year: int) -> int:
+        """the number of days in the specified year for this calendar"""
+        return int(hebrew.year_days(year))
+
     def to_gregorian(self, year: int, month: int, day: int) -> tuple[int, int, int]:
         """Convert a Hebrew date, specified by year, month, and day,
         to the Gregorian equivalent date. Returns a tuple of year, month, day.

src/undate/undate.py

@@ -126,6 +126,7 @@ def calculate_earliest_latest(self, year, month, day):
         else:
             # use the configured min/max allowable years if we
             # don't have any other bounds
+            # TODO: make calendar-specific? these are min/max for gregorian
             min_year = self.MIN_ALLOWABLE_YEAR
             max_year = self.MAX_ALLOWABLE_YEAR
 
@@ -166,7 +167,7 @@ def calculate_earliest_latest(self, year, month, day):
         else:
             # if we have no day or partial day, calculate min / max
             min_day = 1  # is min day ever anything other than 1 ?
-            rel_year = year if year and isinstance(year, int) else None
+            rel_year = year if year and isinstance(year, int) else max_year
             # use month if it is an integer; otherwise use previusly determined
             # max month (which may not be 12 depending if partially unknown)
             rel_month = month if month and isinstance(month, int) else latest_month
@@ -473,27 +474,29 @@ def duration(self) -> Timedelta | UnDelta:
         if self.precision == DatePrecision.DAY:
             return ONE_DAY
 
+        # if year is unknown or partially unknown, month and year duration both need to calculate for
+        # variant years (leap year, non-leap year), since length may vary
+        possible_years = [self.earliest.year]
+        if self.is_partially_known("year"):
+            # if year is partially known (e.g. 191X), get all possible years in range
+            # TODO: refactor into a function/property; combine/extract from missing digit min/max method
+            possible_years = [
+                int(str(self.year).replace(self.MISSING_DIGIT, str(digit)))
+                for digit in range(0, 10)
+            ]
+            # TODO: once this is working, make more efficient by only getting representative years from the calendar
+        elif not self.known_year:  # completely unknown year
+            # TODO: should leap-year specific logic shift to the calendars,
+            # since it works differently depending on the calendar?
+            possible_years = [
+                self.calendar_converter.LEAP_YEAR,
+                self.calendar_converter.NON_LEAP_YEAR,
+            ]
+        possible_max_days = None
+
         # if precision is month and year is unknown,
         # calculate month duration within a single year (not min/max)
         if self.precision == DatePrecision.MONTH:
-            latest = self.latest
-            # if year is unknown, calculate month duration in
-            # leap year and non-leap year, in case length varies
-            if not self.known_year:
-                # TODO: should leap-year specific logic shift to the calendars,
-                # since it works differently depending on the calendar?
-                possible_years = [
-                    self.calendar_converter.LEAP_YEAR,
-                    self.calendar_converter.NON_LEAP_YEAR,
-                ]
-            # TODO: handle partially known years like 191X,
-            # switch to representative years (depends on calendar)
-            # (to be implemented as part of ambiguous year duration)
-            else:
-                # otherwise, get possible durations for all possible months
-                # for a known year
-                possible_years = [self.earliest.year]
-
             # for every possible month and year, get max days for that month,
             possible_max_days = set()
             # appease mypy, which says month values could be None here;
@@ -506,23 +509,45 @@ def duration(self) -> Timedelta | UnDelta:
                             self.calendar_converter.max_day(year, possible_month)
                         )
 
-                # if there is more than one possible value for month length,
-                # whether due to leap year / non-leap year or ambiguous month,
-                # return an uncertain delta
-                if len(possible_max_days) > 1:
-                    return UnDelta(*possible_max_days)
-
-                # otherwise, calculate timedelta normally based on maximum day
-                max_day = list(possible_max_days)[0]
-                latest = Date(self.earliest.year, self.earliest.month, max_day)
+        # if precision is year but year is unknown, return an uncertain delta
+        elif self.precision == DatePrecision.YEAR:
+            possible_max_days = set()
+            # this is currently hebrew-specific due to the way the start/end of year wraps for that calendar
+            try:
+                possible_max_days = set(
+                    [self.calendar_converter.days_in_year(y) for y in possible_years]
+                )
+            except NotImplementedError:
+                pass
+
+            if not possible_max_days:
+                for year in possible_years:
+                    # TODO: shift logic to calendars for parity with Hebrew?
+                    year_start = Date(
+                        *self.calendar_converter.to_gregorian(
+                            year, self.calendar_converter.min_month(), 1
+                        )
+                    )
+                    last_month = self.calendar_converter.max_month(year)
+                    year_end = Date(
+                        *self.calendar_converter.to_gregorian(
+                            year,
+                            last_month,
+                            self.calendar_converter.max_day(year, last_month),
+                        )
+                    )
 
-                return latest - self.earliest + ONE_DAY
+                    year_days = (year_end - year_start).days + 1
+                    possible_max_days.add(year_days)
 
-        # TODO: handle year precision + unknown/partially known year
-        # (will be handled in separate branch)
+        # if there is more than one possible value for number of days
+        # due to range including lear year / non-leap year, return an uncertain delta
+        if possible_max_days and len(possible_max_days) > 1:
+            return UnDelta(*possible_max_days)
+        else:
+            return Timedelta(possible_max_days.pop())
 
-        # otherwise, calculate based on earliest/latest range
-        # subtract earliest from latest and add a day to count start day
+        # otherwise, subtract earliest from latest and add a day to include start day in the count
         return self.latest - self.earliest + ONE_DAY
 
     def _missing_digit_minmax(

tests/test_undate.py

@@ -438,6 +438,20 @@ def test_partiallyknown_duration(self):
         assert isinstance(feb_duration, UnDelta)
         assert feb_duration.days == UnInt(28, 29)
 
+    def test_partiallyknownyear_duration(self):
+        assert Undate("190X").duration().days == UnInt(365, 366)
+        assert Undate("XXXX").duration().days == UnInt(365, 366)
+        # if possible years don't include any leap years, duration is not ambiguous
+        assert Undate("19X1").duration().days == 365
+        # year duration logic should work in other calendars
+        # islamic
+        assert Undate("108X", calendar="Islamic").duration().days == UnInt(354, 355)
+        # NOTE: completely unknown years is not yet supported for other calendars, will cause an error
+        # assert Undate("XXXX", calendar="Islamic").duration().days == UnInt(354, 355)
+        #
+        print(Undate("536X", calendar="Hebrew").duration())
+        assert Undate("536X", calendar="Hebrew").duration().days == UnInt(353, 385)
+
     def test_known_year(self):
         assert Undate(2022).known_year is True
         assert Undate(month=2, day=5).known_year is False