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 vacanza#1825

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

docs/source/examples.rst

@@ -214,6 +214,34 @@ To calculate the number or working days between two specified dates:
 
 Here we calculate the number of working days in Q2 2024.
 
+Getting the next/previous holiday
+---------------------------------
+
+You can request the next/previous holiday of your selected calendar.
+The function returns the date and the name of the holiday - exluding today.
+
+.. code-block:: python
+
+   >>> us_holidays = holidays.US(years=2025)
+   >>> us_holidays.get_next_holiday() # get the next holiday after today
+   (datetime.date(2025, 1, 20), 'Martin Luther King Jr. Day')
+   >>> us_holidays.get_next_holiday(previous=True)  # get the previous holiday before today
+   (datetime.date(2025, 1, 1), "New Year's Day")
+   >>> us_holidays.get_next_holiday("2025-02-01")  # get the next holiday after a specific date
+   (datetime.date(2025, 2, 17), "Washington's Birthday")
+   >>> us_holidays.get_next_holiday("2025-02-01", previous=True)  # get the previous holiday before a specific date
+   (datetime.date(2025, 1, 20), 'Martin Luther King Jr. Day')
+
+If no holiday can be found (e.g. because the date would be after the end date /
+before the start date), (None, None) is returned.
+
+.. code-block:: python
+
+   >>> us_holidays.get_next_holiday("2100-12-31")
+   (None, None)
+   >>> us_holidays.get_next_holiday("1777-01-01", previous=True)
+   (None, None)
+
 Date from holiday name
 ----------------------
 

holidays/holiday_base.py

@@ -532,7 +532,7 @@ def __getattr__(self, name):
                     return lambda name: self._add_holiday(
                         name,
                         _get_nth_weekday_from(
-                            -int(number[0]) if date_direction == "before" else +int(number[0]),
+                            (-int(number[0]) if date_direction == "before" else +int(number[0])),
                             WEEKDAYS[weekday],
                             date(self._year, MONTHS[month], int(day)),
                         ),
@@ -960,6 +960,31 @@ def get_named(
 
         raise AttributeError(f"Unknown lookup type: {lookup}")
 
+    def get_next_holiday(
+        self, start: DateLike = None, previous: bool = False
+    ) -> Union[tuple[date, str], tuple[None, None]]:
+        """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()
+
+        dt = self.__keytransform__(start)
+        if not previous:
+            next_date = next((x for x in self if x > dt), None)
+            if not next_date and dt.year < self.end_year:
+                self.is_working_day(f"{dt.year + 1}.01.01")  # add another year
+                next_date = next((x for x in self if x > dt), None)
+        else:
+            next_date = next((x for x in reversed(self) if x < dt), None)
+            if not next_date and dt.year > self.start_year:
+                self.is_working_day(f"{dt.year - 1}.12.31")  # add another year
+                next_date = next((x for x in reversed(self) if x < dt), None)
+        if next_date:
+            return next_date, self.get(next_date)
+        else:
+            return None, None
+
     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,87 @@ 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_get_next_holiday_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.assertEqual(
+            self.hb.get_next_holiday(f"{self.nextYear}-01-01"),
+            (date(self.nextYear, 5, 1), "Custom May 1st Holiday"),
+        )
+
+        self.assertIn(
+            self.hb.get_next_holiday(),
+            [
+                (date(self.nextLaborDayYear, 5, 1), "Custom May 1st Holiday"),
+                (date(self.nextLaborDayYear, 5, 2), "Custom May 2nd Holiday"),
+            ],
+        )
+
+    def test_get_next_holiday_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.assertEqual(
+            self.hb.get_next_holiday(f"{self.previousYear}-12-31", previous=True),
+            (date(self.previousYear, 5, 2), "Custom May 2nd Holiday"),
+        )
+
+        self.assertIn(
+            self.hb.get_next_holiday(previous=True),
+            [
+                (date(self.previousLaborDayYear, 5, 2), "Custom May 2nd Holiday"),
+                (date(self.thisYear, 5, 1), "Custom May 1st Holiday"),
+            ],
+        )
+
+    def test_get_next_holiday_corner_cases(self):
+        from holidays.countries.ukraine import UA
+
+        ua = UA()
+        # check for date before start of calendar
+        self.assertEqual(ua.get_next_holiday("1991-01-01", previous=True), (None, None))
+
+        # check for date after end of calendar
+        self.assertEqual(ua.get_next_holiday("2022-03-08"), (None, None))