add function to get the next holiday #2211

Rosi2143 · 2025-01-04T13:18:36Z

Proposed change

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

Documentation will be added once the basic changes are approved.

New country/market holidays support (thank you!)
Supported country/market holidays update (calendar discrepancy fix, localization)
Existing code/documentation/test/process quality improvement (best practice, cleanup, refactoring, optimization)
Dependency update (version deprecation/pin/upgrade)
Bugfix (non-breaking change which fixes an issue)
Breaking change (a code change causing existing functionality to break)
New feature (new holidays functionality in general)

Checklist

I've followed the [contributing guidelines][contributing-guidelines]
I've successfully run make check, all checks and tests are green

codecov · 2025-01-04T15:08:45Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (b9d3006) to head (ec129fb).

Additional details and impacted files

@@            Coverage Diff            @@
##               dev     #2211   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          196       196           
  Lines        11849     11865   +16     
  Branches      1710      1714    +4     
=========================================
+ Hits         11849     11865   +16

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

KJhellico · 2025-01-04T16:33:00Z

@Rosi2143, it's good start! But some checks are required. Try to run this:

from holidays.countries.ukraine import UA
ua = UA()
ua.get_next_holiday("1991-01-01", True)
ua.get_next_holiday("2022-03-08")

Rosi2143 · 2025-01-04T19:39:58Z

@KJhellico: Thanks - I didn't know that there is a start/end-date for a calender. But I guess for some countries it makes sense.

Added the checks and the documentation with the latest version.

KJhellico

@Rosi2143, , well done! Please take a look at a few suggestions.

docs/source/examples.rst

holidays/holiday_base.py

KJhellico

That's a great speed improvement! 👍

holidays/holiday_base.py

tests/test_holiday_base.py

KJhellico · 2025-01-11T15:47:00Z

Since the holidays in the holidays entity object are not always placed in chronological order, it's necessary to sort them before searching:

>>> from holidays.countries.united_states import US
>>> h = US(years=2024)
>>> h.get_next_holiday("2024-02-01")
(datetime.date(2024, 5, 27), 'Memorial Day')
>>> for d, name in h.items():
>>>     print(d, name)
2024-01-01 New Year's Day
2024-05-27 Memorial Day
2024-06-19 Juneteenth National Independence Day
2024-07-04 Independence Day
2024-09-02 Labor Day
2024-11-11 Veterans Day
2024-11-28 Thanksgiving
2024-12-25 Christmas Day
2024-01-15 Martin Luther King Jr. Day
2024-02-19 Washington's Birthday
2024-10-14 Columbus Day

Rosi2143 · 2025-01-12T11:47:02Z

Thanks for the hint that no sorting is applied to calendars.

That was one of the reasons I choose my initial implementation. I wanted to keep all the corner cases out of this function - at the cost of having a longer runtime.
My guess was that this function will not be called frequently, so a little more execution time would not hurt.

But fixed this now as well.

KJhellico · 2025-01-12T17:37:48Z

holidays/holiday_base.py

+        if not previous:
+            next_date = next((x for x in self.get_entries_sorted() if x > dt), None)
+            if not next_date and dt.year < self.end_year:
+                self._populate(dt.year + 1)
+                next_date = next((x for x in self.get_entries_sorted() if x > dt), None)
+        else:
+            next_date = next((x for x in reversed(self.get_entries_sorted()) if x < dt), None)
+            if not next_date and dt.year > self.start_year:
+                self._populate(dt.year - 1)
+                next_date = next((x for x in reversed(self.get_entries_sorted()) if x < dt), None)


Suggested change

if not previous:

next_date = next((x for x in self.get_entries_sorted() if x > dt), None)

if not next_date and dt.year < self.end_year:

self._populate(dt.year + 1)

next_date = next((x for x in self.get_entries_sorted() if x > dt), None)

else:

next_date = next((x for x in reversed(self.get_entries_sorted()) if x < dt), None)

if not next_date and dt.year > self.start_year:

self._populate(dt.year - 1)

next_date = next((x for x in reversed(self.get_entries_sorted()) if x < dt), None)

if not previous:

next_date = next((x for x in sorted(self.keys()) if x > dt), None)

if not next_date:

self._populate(dt.year + 1)

next_date = next((x for x in sorted(self.keys()) if x > dt), None)

else:

next_date = next((x for x in sorted(self.keys(), reverse=True) if x < dt), None)

if not next_date:

self._populate(dt.year - 1)

next_date = next((x for x in sorted(self.keys(), reverse=True) if x < dt), None)

It looks faster and doesn't involve additional functions. And don't squash changes into single commit every time, please.

tests/test_holiday_base.py

arkid15r

Thanks for working on this @Rosi2143
Please consider these comments:

arkid15r · 2025-01-15T01:04:10Z

holidays/holiday_base.py

+        (if previous is False) or the previous holiday (if previous is True).
+        If no date is given the search starts from current date"""
+
+        dt = self.__keytransform__(start) if start else datetime.now().date()


This may automatically expand years and populate holidays. It seems we want just a conversion here? If not then datetime.now().date() needs to be treated the same way.

You are right - when the calendar is empty datetime.now() needs to be tranformed as well.

Thanks.

arkid15r · 2025-01-15T01:08:33Z

holidays/holiday_base.py

@@ -959,6 +959,29 @@ def get_named(

        raise AttributeError(f"Unknown lookup type: {lookup}")

+    def get_next_holiday(


I'm not sure (as I typically am) about naming here. I read get next but then I see previous param.

Let's consider get_closest_holiday with a param in_future=True or similar?

I think get_closest_holiday is good - but would rather use parameter in_past=False.

I wonder what's the rationale behind this?

arkid15r · 2025-01-15T01:09:10Z

holidays/holiday_base.py

@@ -959,6 +959,29 @@ 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]]:


Can we return just None instead of tuple[None, None)?

Fine with me - but it was you proposal 😄 : #1825 (comment)

Yes, you've implemented it correctly with Union[tuple[date, str].
For the no result cases simple None is enough.

arkid15r · 2025-01-15T01:50:27Z

holidays/holiday_base.py

+                self._populate(dt.year + 1)
+                next_date = next((x for x in sorted(self.keys()) if x > dt), None)
+        else:
+            next_date = next((x for x in sorted(self.keys(), reverse=True) if x < dt), None)
+            if not next_date:
+                self._populate(dt.year - 1)


It looks like the logic covers next/previous years holidays only. There is a corner case with at least UA holidays when a year doesn't have any. This would return nothing even after holidays are restored.

But if we want to implement it that way I'd suggest something similar to this (using bisect module):

dt = self.__keytransform__(start if start else datetime.now().date()) self._populate(dt.year - 1) self._populate(dt.year + 1) sorted_keys = sorted(self.keys()) pos = bisect_left(sorted_keys, dt) - 1 if previous else bisect_right(sorted_keys, dt) if 0 <= pos < len(sorted_keys): holiday_date = sorted_keys[pos] holiday_name = self.get(holiday_date) return holiday_date, holiday_name

Hi,

I do not get your cornercase. UA has no holidays added after 2022-03-08, so nothing is returned. Whenever the calendar is changed again - and holidays will continue - the function returns one as well.
The function can only work with the current data set.

Also, do you really want to add another dependency for the expected rare occasions that this function is called?

Sorry for wording it in a hard to understand way. Imagine a situation when holidays in 🇺🇦 are restored (also keep in mind there is a streak w/o holidays, right). So let's say 2025-01-01 was a holiday. If I run the function for 2022-03-08 date it'll return nothing while I expect (2025-01-01, Custom holiday)

The code:

if self._year >= 2025: self._add_holiday_jan_1(tr("Custom holiday"))

The tests:

self.assertNotEqual(ua.get_next_holiday("2022-03-08"), (None, None)) # this fails self.assertEqual(ua["2025-01-01"], "Custom holiday") # this passes

Please also note that tests in the reversed order will pass because of ua["2025-01-01"] that populates 2025 year holidays.

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]>

Use more stable calender for testing make sure calendar is filled also if no date is passed Signed-off-by: Schrotti <[email protected]>

sonarqubecloud · 2025-01-18T09:52:11Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

Rosi2143 requested review from arkid15r, KJhellico and PPsyrius as code owners January 4, 2025 13:18

github-actions bot added the test label Jan 4, 2025

Rosi2143 force-pushed the add_get_next_holiday branch from 053f942 to 562bfa1 Compare January 4, 2025 20:19

github-actions bot added the doc label Jan 4, 2025

Rosi2143 force-pushed the add_get_next_holiday branch from 562bfa1 to c91e03e Compare January 4, 2025 21:07

KJhellico reviewed Jan 7, 2025

View reviewed changes

docs/source/examples.rst Outdated Show resolved Hide resolved

holidays/holiday_base.py Outdated Show resolved Hide resolved

holidays/holiday_base.py Show resolved Hide resolved

Rosi2143 force-pushed the add_get_next_holiday branch from b353dde to a5554fb Compare January 9, 2025 20:36

KJhellico reviewed Jan 10, 2025

View reviewed changes

holidays/holiday_base.py Outdated Show resolved Hide resolved

holidays/holiday_base.py Outdated Show resolved Hide resolved

holidays/holiday_base.py Outdated Show resolved Hide resolved

holidays/holiday_base.py Outdated Show resolved Hide resolved

Rosi2143 force-pushed the add_get_next_holiday branch from a5554fb to c9cd832 Compare January 10, 2025 20:20

arkid15r reviewed Jan 10, 2025

View reviewed changes

tests/test_holiday_base.py Outdated Show resolved Hide resolved

Rosi2143 force-pushed the add_get_next_holiday branch from c9cd832 to adf4653 Compare January 10, 2025 21:41

Rosi2143 force-pushed the add_get_next_holiday branch from 8934029 to e56effc Compare January 12, 2025 11:44

KJhellico reviewed Jan 12, 2025

View reviewed changes

KJhellico reviewed Jan 13, 2025

View reviewed changes

tests/test_holiday_base.py Outdated Show resolved Hide resolved

arkid15r reviewed Jan 15, 2025

View reviewed changes

Rosi2143 added 2 commits January 15, 2025 17:58

get_next_holiday: fix review findings

6fda9a8

Use more stable calender for testing make sure calendar is filled also if no date is passed Signed-off-by: Schrotti <[email protected]>

Rosi2143 force-pushed the add_get_next_holiday branch from 677ac23 to 6fda9a8 Compare January 16, 2025 16:55

Merge branch 'dev' into add_get_next_holiday

ec129fb

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add function to get the next holiday #2211

add function to get the next holiday #2211

Rosi2143 commented Jan 4, 2025

codecov bot commented Jan 4, 2025 •

edited

Loading

KJhellico commented Jan 4, 2025

Rosi2143 commented Jan 4, 2025

KJhellico left a comment

KJhellico left a comment

KJhellico commented Jan 11, 2025

Rosi2143 commented Jan 12, 2025

KJhellico Jan 12, 2025 •

edited

Loading

arkid15r left a comment

arkid15r Jan 15, 2025

Rosi2143 Jan 15, 2025

arkid15r Jan 15, 2025

Rosi2143 Jan 15, 2025

arkid15r Jan 20, 2025

arkid15r Jan 15, 2025

Rosi2143 Jan 15, 2025

arkid15r Jan 15, 2025

arkid15r Jan 15, 2025

arkid15r Jan 15, 2025

Rosi2143 Jan 18, 2025

arkid15r Jan 20, 2025

sonarqubecloud bot commented Jan 18, 2025

		@@ -959,6 +959,29 @@ def get_named(

		raise AttributeError(f"Unknown lookup type: {lookup}")

		def get_next_holiday(

add function to get the next holiday #2211

Are you sure you want to change the base?

add function to get the next holiday #2211

Conversation

Rosi2143 commented Jan 4, 2025

Proposed change

Checklist

codecov bot commented Jan 4, 2025 • edited Loading

Codecov Report

KJhellico commented Jan 4, 2025

Rosi2143 commented Jan 4, 2025

KJhellico left a comment

Choose a reason for hiding this comment

KJhellico left a comment

Choose a reason for hiding this comment

KJhellico commented Jan 11, 2025

Rosi2143 commented Jan 12, 2025

KJhellico Jan 12, 2025 • edited Loading

Choose a reason for hiding this comment

arkid15r left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sonarqubecloud bot commented Jan 18, 2025

Quality Gate passed

codecov bot commented Jan 4, 2025 •

edited

Loading

KJhellico Jan 12, 2025 •

edited

Loading