add function to get the next holiday

[Rosi2143]

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]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (987ca01) to head (8921633).

Additional details and impacted files

@@            Coverage Diff            @@
##               dev     #2211   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          199       199           
  Lines        12134     12148   +14     
  Branches      1731      1735    +4     
=========================================
+ Hits         12134     12148   +14     

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

[KJhellico]

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

@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.

[KJhellico]

That's a great speed improvement! 👍

[KJhellico]

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]

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.

[arkid15r]

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

[KJhellico]

This version LGTM. For Ukraine, we can override this method individually when the time comes.

[PPsyrius]

LGTM

[Rosi2143]

Hi @KJhellico and @arkid15r ,

will you merge this? I have no write access to your branch.

Thanks

[arkid15r]

Hi @KJhellico and @arkid15r ,

will you merge this? I have no write access to your branch.

Thanks

I'll review it this week. Sorry for the delay.

[sonarqubecloud]

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