Implement representative years filtering method for Gregorian calendar

Author: rlskoeser

src/undate/converters/base.py

@@ -181,6 +181,14 @@ def days_in_year(self, year: int) -> int:
         # add 1 because the difference doesn't include the end point
         return (year_end - year_start).days + 1
 
+    def representative_years(self, years: None | list[int] = None) -> list[int]:
+        """Returns a list of representative years within the specified list.
+        Result should include one for each type of variant year for this
+        calendar (e.g., leap year and non-leap year). If no years are specified,
+        returns a list of representative years for the current 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/gregorian.py

@@ -1,4 +1,4 @@
-from calendar import monthrange
+from calendar import monthrange, isleap
 
 from undate.converters.base import BaseCalendarConverter
 
@@ -45,6 +45,33 @@ def max_day(self, year: int, month: int) -> int:
 
         return max_day
 
+    def representative_years(self, years: None | list[int] = None) -> list[int]:
+        """Takes a list of years and returns a subset with one leap year and one non-leap year.
+        If no years are specified, returns a known leap year and non-leap year.
+        """
+
+        # if years is unset or list is empty
+        if not years:
+            return [self.LEAP_YEAR, self.NON_LEAP_YEAR]
+
+        found_leap = False
+        found_non_leap = False
+        rep_years = []
+        for year in years:
+            if isleap(year):
+                if not found_leap:
+                    found_leap = True
+                    rep_years.append(year)
+            else:
+                if not found_non_leap:
+                    found_non_leap = True
+                    rep_years.append(year)
+            # stop as soon as we've found one example of each type of year
+            if found_leap and found_non_leap:
+                break
+
+        return rep_years
+
     def to_gregorian(self, year, month, day) -> tuple[int, int, int]:
         """Convert to Gregorian date. This returns the specified by year, month,
         and day unchanged, but is provided for consistency since all calendar

src/undate/undate.py

@@ -500,7 +500,13 @@ def representative_years(self) -> list[int]:
         """A list of representative years for this date."""
         try:
             # todo: filter by calendar to minimum needed
-            return list(self.possible_years)
+            try:
+                return self.calendar_converter.representative_years(
+                    list(self.possible_years)
+                )
+            except NotImplementedError:
+                # if calendar converter does not support representative years, return all years
+                return list(self.possible_years)
         except ValueError:
             return [
                 self.calendar_converter.LEAP_YEAR,

tests/test_undate.py

@@ -408,19 +408,11 @@ def test_possible_years(self):
             Undate("XXXX").possible_years
 
     def test_representative_years(self):
+        # single year is returned as is
         assert Undate("1991").representative_years == [1991]
-        assert Undate("190X").representative_years == [
-            1900,
-            1901,
-            1902,
-            1903,
-            1904,
-            1905,
-            1906,
-            1907,
-            1908,
-            1909,
-        ]
+        # for an uncertain year, returns first leap year and non-leap year in range
+        assert Undate("190X").representative_years == [1900, 1904]
+        assert Undate("19XX").representative_years == [1900, 1904]
 
     def test_duration(self):
         day_duration = Undate(2022, 11, 7).duration()