Implement representative years for islamic calendar converter

Author: rlskoeser

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

@@ -21,6 +21,11 @@ class IslamicDateConverter(BaseCalendarConverter):
     name: str = "Islamic"
     calendar_name: str = "Islamic"
 
+    #: arbitrary known non-leap year
+    NON_LEAP_YEAR: int = 1457
+    #: arbitrary known leap year
+    LEAP_YEAR: int = 1458
+
     def __init__(self):
         self.transformer = IslamicDateTransformer()
 
@@ -36,6 +41,32 @@ def max_month(self, year: int) -> int:
         """maximum numeric month for this calendar"""
         return 12
 
+    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 islamic.leap(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: int, month: int, day: int) -> tuple[int, int, int]:
         """Convert a Hijri date, specified by year, month, and day,
         to the Gregorian equivalent date. Returns a tuple of year, month, day.

tests/test_converters/test_calendars/test_islamic/test_islamic_converter.py

@@ -152,3 +152,23 @@ def test_compare_across_calendars(self):
         )
         expected_gregorian_years = [33, 1049, 1350, 1479, 1495, 1995]
         assert [d.earliest.year for d in sorted_dates] == expected_gregorian_years
+
+    def test_representative_years(self):
+        converter = IslamicDateConverter()
+        # single year is not filtered
+        # 1458 is a leap year; 1457 and 1459 are not
+        assert converter.representative_years([1457]) == [1457]
+        # multiple non-leap years, returns just the first
+        assert converter.representative_years([1457, 1459]) == [1457]
+        # next leap year is 2028; returns first leap year and first non-leap year, in input order
+        assert converter.representative_years([1457, 1458, 1459]) == [1457, 1458]
+
+        # if no years are provided, returns a known leap year and non-leap years
+        assert converter.representative_years() == [
+            converter.LEAP_YEAR,
+            converter.NON_LEAP_YEAR,
+        ]
+        assert converter.representative_years([]) == [
+            converter.LEAP_YEAR,
+            converter.NON_LEAP_YEAR,
+        ]