From a5554fb141b72a8ee66d734405f788a880315348 Mon Sep 17 00:00:00 2001 From: Schrotti Date: Sat, 4 Jan 2025 12:48:39 +0100 Subject: [PATCH] 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 --- docs/source/examples.rst | 28 +++++++++++++ holidays/holiday_base.py | 27 +++++++++++- tests/test_holiday_base.py | 84 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 138 insertions(+), 1 deletion(-) diff --git a/docs/source/examples.rst b/docs/source/examples.rst index f43a76909..bf726e029 100644 --- a/docs/source/examples.rst +++ b/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 ---------------------- diff --git a/holidays/holiday_base.py b/holidays/holiday_base.py index 2db65448c..4a3f86b23 100644 --- a/holidays/holiday_base.py +++ b/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). diff --git a/tests/test_holiday_base.py b/tests/test_holiday_base.py index c5563c6b1..e0674e352 100644 --- a/tests/test_holiday_base.py +++ b/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))