Added include_days param to holiday and festival methods and funtions.

Also wrote tests.

src/pyluach/dates.py

@@ -189,6 +189,31 @@ def shabbos(self):
         """
         return self + (7 - self.weekday())
 
+    def _day_of_holiday(self, israel, hebrew=False):
+        """Return the day of the holiday.
+
+        Parameters
+        ----------
+        israel : bool, optional
+        hebrew : bool, optional
+
+        Returns
+        -------
+        str
+        """
+        name = (
+            utils._fast_day_string(self)
+            or utils._festival_string(self, israel)
+        )
+        if name is not None:
+            first_day = utils._first_day_of_holiday(utils.Days(name))
+            if first_day:
+                day = HebrewDate(self.year, *first_day) - self + 1
+                if hebrew:
+                    day = gematria._num_to_str(day)
+                return str(day)
+        return ''
+
     def fast_day(self, hebrew=False):
         """Return name of fast day of date.
 
@@ -206,7 +231,13 @@ def fast_day(self, hebrew=False):
         """
         return utils._fast_day_string(self, hebrew)
 
-    def festival(self, israel=False, hebrew=False, include_working_days=True):
+    def festival(
+        self,
+        israel=False,
+        hebrew=False,
+        include_working_days=True,
+        include_day=False
+    ):
         """Return name of Jewish festival of date.
 
         This method will return all major and minor religous
@@ -224,18 +255,37 @@ def festival(self, israel=False, hebrew=False, include_working_days=True):
             ``True`` to include festival days on which melacha (work) is
             allowed; ie. Pesach Sheni, Chol Hamoed, etc.
             Default is ``True``.
+        include_day : bool, optional
+            ``True`` to prefix multi day festivals with the day of the
+            festival. Default is ``False``.
+
+        Examples
+        --------
+        >>> pesach = HebrewDate(2023, 1, 15)
+        >>> pesach.festival(include_day=True)
+        '1 Pesach'
+        >>> pesach.festival(hebrew=True, include_day=True)
+        'א׳ פסח'
+        >>> shavuos = HebrewDate(5783, 3, 6)
+        >>> shavuos.festival(israel=True, include_day=True)
+        'Shavuos'
 
         Returns
         -------
         str or None
             The name of the festival or ``None`` if the given date is not
             a Jewish festival.
         """
-        return utils._festival_string(
+        name = utils._festival_string(
             self, israel, hebrew, include_working_days
         )
+        if include_day and name is not None:
+            day = self._day_of_holiday(israel=israel, hebrew=hebrew)
+            if day:
+                return f'{day} {name}'
+        return name
 
-    def holiday(self, israel=False, hebrew=False):
+    def holiday(self, israel=False, hebrew=False, include_day=False):
         """Return name of Jewish holiday of the date.
 
         The holidays include the major and minor religious Jewish
@@ -249,14 +299,31 @@ def holiday(self, israel=False, hebrew=False):
         hebrew : bool, optional
             ``True`` if you want the holiday name in Hebrew letters. Default is
             ``False``, which returns the name transliterated into English.
+        include_day : bool, optional
+            ``True`` to prefix multi day holidays with the day of the
+            holiday. Default is ``False``.
+
+        Examples
+        --------
+        >>> pesach = HebrewDate(2023, 1, 15)
+        >>> pesach.holiday(include_day=True)
+        '1 Pesach'
+        >>> pesach.holiday(hebrew=True, include_day=True)
+        'א׳ פסח'
+        >>> taanis_esther = HebrewDate(5783, 12, 13)
+        >>> taanis_esther.holiday(include_day=True)
+        'Taanis Esther'
 
         Returns
         -------
         str or None
             The name of the holiday or ``None`` if the given date is not
             a Jewish holiday.
         """
-        return utils._holiday(self, israel, hebrew)
+        return (
+            self.fast_day(hebrew=hebrew)
+            or self.festival(israel, hebrew, include_day=include_day)
+        )
 
 
 class CalendarDateMixin:

src/pyluach/hebrewcal.py

@@ -23,7 +23,6 @@
 from pyluach.dates import HebrewDate
 from pyluach import utils
 from pyluach.gematria import _num_to_str
-from pyluach.utils import _holiday, _fast_day_string, _festival_string
 
 
 class IllegalMonthError(ValueError):
@@ -644,8 +643,8 @@ def itermonthdates(self, year, month):
         ----------
         year : int
         month : int
-          The Hebrew month starting with 1 for Nissan through 13 for
-          Adar Sheni if necessary.
+            The Hebrew month starting with 1 for Nissan through 13 for
+            Adar Sheni if necessary.
 
         Yields
         ------
@@ -1231,22 +1230,27 @@ def fast_day(date, hebrew=False):
     Parameters
     ----------
     date : ~pyluach.dates.BaseDate
-      Any date instance from a subclass of ``BaseDate`` can be used.
-
+        Any date instance from a subclass of ``BaseDate`` can be used.
     hebrew : bool, optional
-      ``True`` if you want the fast_day name in Hebrew letters. Default
-      is ``False``, which returns the name transliterated into English.
+        ``True`` if you want the fast_day name in Hebrew letters. Default
+        is ``False``, which returns the name transliterated into English.
 
     Returns
     -------
     str or None
-      The name of the fast day or ``None`` if the given date is not
-      a fast day.
+        The name of the fast day or ``None`` if the given date is not
+        a fast day.
     """
-    return _fast_day_string(date, hebrew)
+    return date.fast_day(hebrew)
 
 
-def festival(date, israel=False, hebrew=False, include_working_days=True):
+def festival(
+    date,
+    israel=False,
+    hebrew=False,
+    include_working_days=True,
+    include_day=False
+):
     """Return Jewish festival of given day.
 
     This method will return all major and minor religous
@@ -1255,51 +1259,79 @@ def festival(date, israel=False, hebrew=False, include_working_days=True):
     Parameters
     ----------
     date : ~pyluach.dates.BaseDate
-      Any subclass of ``BaseDate`` can be used.
+        Any subclass of ``BaseDate`` can be used.
 
     israel : bool, optional
-      ``True`` if you want the festivals according to the Israel
-      schedule. Defaults to ``False``.
-
+        ``True`` if you want the festivals according to the Israel
+        schedule. Defaults to ``False``.
     hebrew : bool, optional
-      ``True`` if you want the festival name in Hebrew letters. Default
-      is ``False``, which returns the name transliterated into English.
-
+        ``True`` if you want the festival name in Hebrew letters. Default
+        is ``False``, which returns the name transliterated into English.
     include_working_days : bool, optional
-      ``True`` to include festival days on which melacha (work) is
-      allowed; ie. Pesach Sheni, Chol Hamoed, etc.
-      Default is ``True``.
+        ``True`` to include festival days on which melacha (work) is
+        allowed; ie. Pesach Sheni, Chol Hamoed, etc.
+        Default is ``True``.
+    include_day : bool, optional
+        ``True`` to prefix multi day festivals with the day of the
+        festival. Default is ``False``.
+
+    Examples
+    --------
+    >>> from pyluach.dates import HebrewDate
+    pesach = HebrewDate(2023, 1, 15)
+    >>> festival(pesach, include_day=True)
+    '1 Pesach'
+    >>> festival(pesach, hebrew=True, include_day=True)
+    'א׳ פסח'
+    >>> shavuos = HebrewDate(5783, 3, 6)
+    >>> festival(shavuos, israel=True, include_day=True)
+    'Shavuos'
 
     Returns
     -------
     str or None
-      The name of the festival or ``None`` if the given date is not
-      a Jewish festival.
+        The name of the festival or ``None`` if the given date is not
+        a Jewish festival.
     """
-    return _festival_string(date, israel, hebrew, include_working_days)
+    return date.festival(israel, hebrew, include_working_days, include_day)
 
 
-def holiday(date, israel=False, hebrew=False):
+def holiday(date, israel=False, hebrew=False, include_day=False):
     """Return Jewish holiday of given date.
 
     The holidays include the major and minor religious Jewish
     holidays including fast days.
 
     Parameters
     ----------
-    date : ~pyluach.dates.BaseDate
+    date : pyluach.dates.BaseDate
         Any subclass of ``BaseDate`` can be used.
     israel : bool, optional
         ``True`` if you want the holidays according to the israel
         schedule. Default is ``False``.
     hebrew : bool, optional
         ``True`` if you want the holiday name in Hebrew letters. Default
         is ``False``, which returns the name transliterated into English.
+    include_day : bool, optional
+        ``True`` to prefix multi day holidays with the day of the
+        holiday. Default is ``False``.
+
+    Examples
+    --------
+    >>> from pyluach.dates import HebrewDate
+    >>> pesach = HebrewDate(2023, 1, 15)
+    >>> holiday(pesach, include_day=True)
+    '1 Pesach'
+    >>> holiday(pesach, hebrew=True, include_day=True)
+    'א׳ פסח'
+    >>> taanis_esther = HebrewDate(5783, 12, 13)
+    >>> holiday(taanis_esther, include_day=True)
+    'Taanis Esther'
 
     Returns
     -------
     str or None
-      The name of the holiday or ``None`` if the given date is not
-      a Jewish holiday.
+        The name of the holiday or ``None`` if the given date is not
+        a Jewish holiday.
     """
-    return _holiday(date, israel, hebrew)
+    return date.holiday(israel, hebrew, include_day)

tests/test_dates.py

@@ -257,6 +257,9 @@ def test_festival(self):
         assert date.festival(hebrew=True) == 'חנוכה'
         assert date.festival(include_working_days=False) is None
 
+    def test_day_of_holiday(self):
+        assert HebrewDate(5783, 12, 14)._day_of_holiday(israel=False) == ''
+
 
 def test_to_pydate():
     day = HebrewDate(5778, 6, 1)

tests/test_hebrewcal.py

@@ -320,17 +320,24 @@ def test_roshhashana(self):
             for location in [True, False]
             for included_days in [True, False]
         ))
+        assert (
+            holiday(roshhashana, hebrew=True, include_day=True)
+            == 'א׳ ראש השנה'
+        )
+        assert festival(roshhashana + 1, include_day=True) == '2 Rosh Hashana'
 
     def test_yomkippur(self):
         yom_kippur = dates.HebrewDate(5775, 7, 10)
         assert holiday(yom_kippur) == 'Yom Kippur'
         assert holiday(yom_kippur, hebrew=True) == 'יום כיפור'
         assert festival(yom_kippur, include_working_days=False) == 'Yom Kippur'
+        assert holiday(yom_kippur, include_day=True) == 'Yom Kippur'
 
     def test_succos(self):
         second_day = dates.HebrewDate(5782, 7, 16)
         day = dates.HebrewDate(5778, 7, 18)
         assert festival(day) == 'Succos'
+        assert holiday(day, hebrew=True, include_day=True) == 'ד׳ סוכות'
         day2 = dates.HebrewDate(5778, 7, 23)
         assert festival(day2, israel=True, hebrew=True) is None
         assert festival(day, include_working_days=False) is None
@@ -347,12 +354,16 @@ def test_shmini(self):
         shmini = dates.HebrewDate(5780, 7, 22)
         assert holiday(shmini, True) == 'Shmini Atzeres'
         assert holiday(shmini) == 'Shmini Atzeres'
-        assert holiday(shmini + 1) == 'Simchas Torah'
-        assert holiday(shmini + 1, True) is None
+        assert holiday(shmini + 1, include_day=True) == 'Simchas Torah'
+        assert holiday(shmini + 1, israel=True, include_day=True) is None
 
     def test_chanuka(self):
         for year in [5778, 5787]:
             chanuka = dates.HebrewDate(year, 9, 25)
+            assert (
+                festival(chanuka + 7, hebrew=True, include_day=True)
+                == 'ח׳ חנוכה'
+            )
             for i in range(8):
                 assert holiday(chanuka + i) == 'Chanuka'
             assert holiday(chanuka + 8) is None
@@ -394,6 +405,11 @@ def test_pesach(self):
             festival(pesach + 1, israel=True, include_working_days=False)
             is None
         )
+        assert holiday(pesach, include_day=True) == '1 Pesach'
+        assert (
+            festival(pesach + 2, include_working_days=False, include_day=True)
+            is None
+        )
 
     def test_pesach_sheni(self):
         ps = dates.HebrewDate(5781, 2, 14)
@@ -419,6 +435,9 @@ def test_shavuos(self):
         assert festival(shavuos + 1, include_working_days=False) == 'Shavuos'
         not_shavuos = dates.HebrewDate(5782, 4, 7)
         assert festival(not_shavuos) is None
+        assert (
+            festival(shavuos + 1, hebrew=True, include_day=True) == 'ב׳ שבועות'
+        )
 
     def test_tubeav(self):
         tubeav = dates.HebrewDate(5779, 5, 15)