add function to get the next holiday

a new function get_next_holiday is added to retrieve the date
of the next known holiday.
Also the name of the holiday is returned.

It is possible to search forward and backward in time.

This should solve #1825

Signed-off-by: Schrotti <[email protected]>

holidays/holiday_base.py

@@ -960,6 +960,19 @@ def get_named(
 
         raise AttributeError(f"Unknown lookup type: {lookup}")
 
+    def get_next_holiday(self, start: DateLike = None, previous: bool = False) -> tuple[date, str]:
+        """Return the date and name of the next holiday from provided date
+        (if previous is False) or the previous holiday (if previous is True).
+        If no date is given the search starts from current date"""
+        if not start:
+            start = datetime.now()
+
+        direction = +1 if not previous else -1
+        dt = _timedelta(self.__keytransform__(start), direction)
+        while not self.get(dt, default=None):
+            dt = _timedelta(dt, direction)
+        return dt, self.get(dt)
+
     def get_nth_working_day(self, key: DateLike, n: int) -> date:
         """Return n-th working day from provided date (if n is positive)
         or n-th working day before provided date (if n is negative).

tests/test_holiday_base.py

@@ -1189,3 +1189,69 @@ def test_get_working_days_count(self):
         self.assertEqual(self.hb.get_working_days_count("2024-04-29", "2024-05-04"), 3)
         self.assertEqual(self.hb.get_working_days_count("2024-04-29", "2024-05-05"), 3)
         self.assertEqual(self.hb.get_working_days_count("2024-04-29", "2024-05-06"), 4)
+
+
+class TestNextHoliday(unittest.TestCase):
+    def setUp(self):
+        self.thisYear = datetime.now().year
+        self.nextYear = self.thisYear + 1
+        self.previousYear = self.thisYear - 1
+        self.hb = CountryStub3(years=self.thisYear)
+        self.nextLaborDayYear = (
+            self.thisYear
+            if datetime.now().date() < self.hb.get_named("Custom May 1st Holiday")[0]
+            else self.nextYear
+        )
+        self.previousLaborDayYear = (
+            self.thisYear
+            if datetime.now().date() > self.hb.get_named("Custom May 1st Holiday")[0]
+            else self.previousYear
+        )
+
+    def test_is_working_day_forward(self):
+        self.assertEqual(
+            self.hb.get_next_holiday(f"{self.thisYear}-01-01"),
+            (date(self.thisYear, 5, 1), "Custom May 1st Holiday"),
+        )
+        self.assertEqual(
+            self.hb.get_next_holiday(f"{self.thisYear}-04-30"),
+            (date(self.thisYear, 5, 1), "Custom May 1st Holiday"),
+        )
+        self.assertEqual(
+            self.hb.get_next_holiday(f"{self.thisYear}-05-01"),
+            (date(self.thisYear, 5, 2), "Custom May 2nd Holiday"),
+        )
+        self.assertEqual(
+            self.hb.get_next_holiday(f"{self.thisYear}-05-02"),
+            (date(self.nextYear, 5, 1), "Custom May 1st Holiday"),
+        )
+
+        self.assertTrue(
+            self.hb.get_next_holiday()
+            in [
+                (date(self.nextLaborDayYear, 5, 1), "Custom May 1st Holiday"),
+                (date(self.nextLaborDayYear, 5, 2), "Custom May 2nd Holiday"),
+            ]
+        )
+
+    def test_is_working_day_reverse(self):
+        self.assertEqual(
+            self.hb.get_next_holiday(f"{self.thisYear}-12-31", previous=True),
+            (date(self.thisYear, 5, 2), "Custom May 2nd Holiday"),
+        )
+        self.assertEqual(
+            self.hb.get_next_holiday(f"{self.thisYear}-05-02", previous=True),
+            (date(self.thisYear, 5, 1), "Custom May 1st Holiday"),
+        )
+        self.assertEqual(
+            self.hb.get_next_holiday(f"{self.thisYear}-04-30", previous=True),
+            (date(self.previousYear, 5, 2), "Custom May 2nd Holiday"),
+        )
+
+        self.assertTrue(
+            self.hb.get_next_holiday(previous=True)
+            in [
+                (date(self.previousLaborDayYear, 5, 2), "Custom May 2nd Holiday"),
+                (date(self.thisYear, 5, 1), "Custom May 1st Holiday"),
+            ]
+        )