Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update working day related calculations #2010

Merged
merged 4 commits into from
Sep 25, 2024
Merged

Update working day related calculations #2010

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f7a3ab7
Update working day-related calculations:
KJhellico Sep 6, 2024
8b941fe
PR suggestion
KJhellico Sep 23, 2024
4d7b325
Update HolidayBase::get_workdays_number docstring
arkid15r Sep 23, 2024
e1e3129
Rename methods
KJhellico Sep 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions docs/source/examples.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,6 +178,42 @@ To get a list of other categories holidays (for countries that support them):
2023-12-25 Christmas Day
2023-12-26 Bank Holiday

Working day-related calculations
--------------------------------

To check if the specified date is a working day:

.. code-block:: python

>>> us_holidays = holidays.US(years=2024) # Weekends in the US are Saturday and Sunday.
>>> us_holidays.is_working_day("2024-01-01") # Monday, New Year's Day.
False
>>> us_holidays.is_working_day("2024-01-02") # Tuesday, ordinary day.
True
>>> us_holidays.is_working_day("2024-01-06") # Saturday, ordinary day.
False
>>> us_holidays.is_working_day("2024-01-15") # Monday, Martin Luther King Jr. Day.
False

To find the nth working day after the specified date:

.. code-block:: python

>>> us_holidays.get_nth_working_day("2024-12-20", 5)
datetime.date(2024, 12, 30)

Here we calculate the 5th working day after December 20, 2024. Working days are 23 (Mon),
24 (Tue), 26 (Thu), 27 (Fri), 30 (Mon); 21-22, 28-29 - weekends, 25 - Christmas Day.

To calculate the number or working days between two specified dates:

.. code-block:: python

>>> us_holidays.get_working_days_count("2024-04-01", "2024-06-30")
63

Here we calculate the number of working days in Q2 2024.

Date from holiday name
----------------------

Expand Down
30 changes: 19 additions & 11 deletions holidays/holiday_base.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -961,30 +961,38 @@ def get_named(

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

def get_nth_workday(self, key: DateLike, n: int) -> date:
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).
"""
direction = +1 if n > 0 else -1
dt = self.__keytransform__(key)
for _ in range(abs(n)):
dt = _timedelta(dt, direction)
while not self.is_workday(dt):
while not self.is_working_day(dt):
dt = _timedelta(dt, direction)
return dt

def get_workdays_number(self, key1: DateLike, key2: DateLike) -> int:
"""Return the number of working days between two dates (not including the start date)."""
dt1 = self.__keytransform__(key1)
dt2 = self.__keytransform__(key2)
if dt1 == dt2:
return 0
def get_working_days_count(self, start: DateLike, end: DateLike) -> int:
"""Return the number of working days between two dates.

The date range works in a closed interval fashion [start, end] so both
endpoints are included.

:param start:
The range start date.

:param end:
The range end date.
"""
dt1 = self.__keytransform__(start)
dt2 = self.__keytransform__(end)
if dt1 > dt2:
dt1, dt2 = dt2, dt1
days = (dt2 - dt1).days + 1
return sum(self.is_working_day(_timedelta(dt1, n)) for n in range(days))

return sum(self.is_workday(_timedelta(dt1, n)) for n in range(1, (dt2 - dt1).days + 1))

def is_workday(self, key: DateLike) -> bool:
def is_working_day(self, key: DateLike) -> bool:
"""Return True if date is a working day (not a holiday or a weekend)."""
dt = self.__keytransform__(key)
return dt in self.weekend_workdays if self._is_weekend(dt) else dt not in self
Expand Down
96 changes: 48 additions & 48 deletions tests/test_holiday_base.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1140,51 +1140,51 @@ class TestWorkdays(unittest.TestCase):
def setUp(self):
self.hb = CountryStub6(years=2024)

def test_is_workday(self):
self.assertTrue(self.hb.is_workday("2024-02-12"))
self.assertFalse(self.hb.is_workday("2024-02-17"))
self.assertFalse(self.hb.is_workday("2024-02-19"))
self.assertTrue(self.hb.is_workday("2024-02-24"))

self.assertTrue(self.hb.is_workday("2024-04-30"))
self.assertFalse(self.hb.is_workday("2024-05-01"))
self.assertFalse(self.hb.is_workday("2024-05-02"))
self.assertTrue(self.hb.is_workday("2024-05-03"))

def test_get_nth_workday(self):
self.assertEqual(self.hb.get_nth_workday("2024-01-04", 0), date(2024, 1, 4))
self.assertEqual(self.hb.get_nth_workday("2024-01-04", +1), date(2024, 1, 5))
self.assertEqual(self.hb.get_nth_workday("2024-01-04", +3), date(2024, 1, 9))
self.assertEqual(self.hb.get_nth_workday("2024-01-06", +1), date(2024, 1, 8))
self.assertEqual(self.hb.get_nth_workday("2024-01-26", -10), date(2024, 1, 12))
self.assertEqual(self.hb.get_nth_workday("2024-01-21", -1), date(2024, 1, 19))

self.assertEqual(self.hb.get_nth_workday("2024-02-15", +4), date(2024, 2, 22))
self.assertEqual(self.hb.get_nth_workday("2024-02-15", +5), date(2024, 2, 23))
self.assertEqual(self.hb.get_nth_workday("2024-02-15", +6), date(2024, 2, 24))
self.assertEqual(self.hb.get_nth_workday("2024-02-15", +7), date(2024, 2, 26))
self.assertEqual(self.hb.get_nth_workday("2024-02-26", -7), date(2024, 2, 15))
self.assertEqual(self.hb.get_nth_workday("2024-02-25", -7), date(2024, 2, 15))

self.assertEqual(self.hb.get_nth_workday("2024-04-29", +1), date(2024, 4, 30))
self.assertEqual(self.hb.get_nth_workday("2024-04-29", +2), date(2024, 5, 3))
self.assertEqual(self.hb.get_nth_workday("2024-04-29", +3), date(2024, 5, 6))
self.assertEqual(self.hb.get_nth_workday("2024-04-29", +4), date(2024, 5, 7))
self.assertEqual(self.hb.get_nth_workday("2024-05-10", -10), date(2024, 4, 24))
self.assertEqual(self.hb.get_nth_workday("2024-05-10", -7), date(2024, 4, 29))
self.assertEqual(self.hb.get_nth_workday("2024-05-10", -5), date(2024, 5, 3))

def test_get_workdays_number(self):
self.assertEqual(self.hb.get_workdays_number("2024-01-03", "2024-01-23"), 14)
self.assertEqual(self.hb.get_workdays_number("2024-01-23", "2024-01-03"), 14)
self.assertEqual(self.hb.get_workdays_number("2024-01-06", "2024-01-07"), 0)
self.assertEqual(self.hb.get_workdays_number("2024-01-16", "2024-01-16"), 0)

self.assertEqual(self.hb.get_workdays_number("2024-02-08", "2024-02-15"), 5)
self.assertEqual(self.hb.get_workdays_number("2024-02-15", "2024-02-22"), 4)
self.assertEqual(self.hb.get_workdays_number("2024-02-22", "2024-02-29"), 6)

self.assertEqual(self.hb.get_workdays_number("2024-04-29", "2024-05-03"), 2)
self.assertEqual(self.hb.get_workdays_number("2024-04-29", "2024-05-04"), 2)
self.assertEqual(self.hb.get_workdays_number("2024-04-29", "2024-05-05"), 2)
self.assertEqual(self.hb.get_workdays_number("2024-04-29", "2024-05-06"), 3)
def test_is_working_day(self):
self.assertTrue(self.hb.is_working_day("2024-02-12"))
self.assertFalse(self.hb.is_working_day("2024-02-17"))
self.assertFalse(self.hb.is_working_day("2024-02-19"))
self.assertTrue(self.hb.is_working_day("2024-02-24"))

self.assertTrue(self.hb.is_working_day("2024-04-30"))
self.assertFalse(self.hb.is_working_day("2024-05-01"))
self.assertFalse(self.hb.is_working_day("2024-05-02"))
self.assertTrue(self.hb.is_working_day("2024-05-03"))

def test_get_nth_working_day(self):
self.assertEqual(self.hb.get_nth_working_day("2024-01-04", 0), date(2024, 1, 4))
self.assertEqual(self.hb.get_nth_working_day("2024-01-04", +1), date(2024, 1, 5))
self.assertEqual(self.hb.get_nth_working_day("2024-01-04", +3), date(2024, 1, 9))
self.assertEqual(self.hb.get_nth_working_day("2024-01-06", +1), date(2024, 1, 8))
self.assertEqual(self.hb.get_nth_working_day("2024-01-26", -10), date(2024, 1, 12))
self.assertEqual(self.hb.get_nth_working_day("2024-01-21", -1), date(2024, 1, 19))

self.assertEqual(self.hb.get_nth_working_day("2024-02-15", +4), date(2024, 2, 22))
self.assertEqual(self.hb.get_nth_working_day("2024-02-15", +5), date(2024, 2, 23))
self.assertEqual(self.hb.get_nth_working_day("2024-02-15", +6), date(2024, 2, 24))
self.assertEqual(self.hb.get_nth_working_day("2024-02-15", +7), date(2024, 2, 26))
self.assertEqual(self.hb.get_nth_working_day("2024-02-26", -7), date(2024, 2, 15))
self.assertEqual(self.hb.get_nth_working_day("2024-02-25", -7), date(2024, 2, 15))

self.assertEqual(self.hb.get_nth_working_day("2024-04-29", +1), date(2024, 4, 30))
self.assertEqual(self.hb.get_nth_working_day("2024-04-29", +2), date(2024, 5, 3))
self.assertEqual(self.hb.get_nth_working_day("2024-04-29", +3), date(2024, 5, 6))
self.assertEqual(self.hb.get_nth_working_day("2024-04-29", +4), date(2024, 5, 7))
self.assertEqual(self.hb.get_nth_working_day("2024-05-10", -10), date(2024, 4, 24))
self.assertEqual(self.hb.get_nth_working_day("2024-05-10", -7), date(2024, 4, 29))
self.assertEqual(self.hb.get_nth_working_day("2024-05-10", -5), date(2024, 5, 3))

def test_get_working_days_count(self):
self.assertEqual(self.hb.get_working_days_count("2024-01-03", "2024-01-23"), 15)
self.assertEqual(self.hb.get_working_days_count("2024-01-23", "2024-01-03"), 15)
self.assertEqual(self.hb.get_working_days_count("2024-01-06", "2024-01-07"), 0)
self.assertEqual(self.hb.get_working_days_count("2024-01-16", "2024-01-16"), 1)

self.assertEqual(self.hb.get_working_days_count("2024-02-08", "2024-02-15"), 6)
self.assertEqual(self.hb.get_working_days_count("2024-02-15", "2024-02-22"), 5)
self.assertEqual(self.hb.get_working_days_count("2024-02-22", "2024-02-29"), 7)

self.assertEqual(self.hb.get_working_days_count("2024-04-29", "2024-05-03"), 3)
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)
Loading