Holidays

The holiday engine produces every observance of a Hebrew year — festivals, fasts, modern Israeli days, minority feasts, Rosh Chodesh and the special Shabbatot — with the Israel/Diaspora differences resolved. It is built entirely on the calendar core.

The engine

holidays(year, diaspora=True) returns a chronologically sorted list of Holiday objects for a Hebrew year; holidays_on(date) filters to a single Hebrew date.

>>> from hebrewcal.religious.holidays import holidays, holidays_on
>>> from hebrewcal.calendars.hebrew import HebrewDate
>>> days = holidays(5785)              # Diaspora by default
>>> days[0].name, days[0].category.value
('Rosh Hashanah', 'major_festival')
>>> [h.name for h in holidays_on(HebrewDate(5785, 7, 10))]
['Yom Kippur']

A Holiday records a name, a HebrewDate (date) and a Category:

>>> from hebrewcal.religious.holidays import Category
>>> list(Category)
[<Category.MAJOR_FESTIVAL: 'major_festival'>, ...]

Looking up by a civil date

Convert the Gregorian date to Hebrew first:

>>> from hebrewcal import GregorianDate, to_hebrew
>>> from hebrewcal.religious.holidays import holidays_on
>>> [h.name for h in holidays_on(to_hebrew(GregorianDate(2024, 12, 26)))]
['Hanukkah']

Israel vs. Diaspora

Pass diaspora=False for the Israeli calendar. The differences are handled automatically: the second festival day (yom tov sheni), Simchat Torah on 22 Tishri in Israel versus 23 in the Diaspora, a 7-day Pesach versus 8, and one day of Shavuot versus two.

>>> from hebrewcal.religious.holidays import holidays_on
>>> from hebrewcal.calendars.hebrew import HebrewDate
>>> "Simchat Torah" in {h.name for h in holidays_on(HebrewDate(5785, 7, 22), diaspora=False)}
True
>>> "Simchat Torah" in {h.name for h in holidays_on(HebrewDate(5785, 7, 22), diaspora=True)}
False

Categories

Category values

MAJOR_FESTIVAL, CHOL_HAMOED, MINOR_FESTIVAL, FAST, MODERN, ROSH_CHODESH, SPECIAL_SHABBAT, MINORITY.

  • Major festivals — Rosh Hashanah, Yom Kippur, Sukkot (+ Shemini Atzeret / Simchat Torah), Pesach, Shavuot.

  • Minor festivals — Hanukkah, Tu BiShvat, Purim and Shushan Purim, Lag BaOmer, Tu B’Av, Pesach Sheni, Hoshana Rabbah.

  • Fasts — with postponement (see below).

  • Modern — Yom HaShoah, Yom HaZikaron, Yom HaAtzmaut, Yom Yerushalayim.

  • Rosh Chodesh — one or two days per month (not Tishri).

  • Special Shabbatot — Shekalim, Zachor, Parah, HaChodesh, HaGadol, Shuvah, Chazon, Nachamu.

  • Minority — Sigd (Ethiopian Jewry), Mimouna (North African communities).

Fasts and postponement

A fast that would fall on Shabbat is moved: most fasts are postponed to Sunday, while Ta’anit Esther (and Ta’anit Bechorot) are brought forward to the preceding Thursday. Asara B’Tevet is never postponed.

>>> from hebrewcal.religious.holidays import holidays_on
>>> from hebrewcal.calendars.hebrew import HebrewDate
>>> # 3 Tishri 5785 is Shabbat, so Tzom Gedaliah is observed on 4 Tishri.
>>> "Tzom Gedaliah" in {h.name for h in holidays_on(HebrewDate(5785, 7, 4))}
True

Leap years

In a leap year Purim falls in Adar II; Purim Katan marks 14 Adar I.

>>> from hebrewcal.religious.holidays import holidays_on
>>> from hebrewcal.calendars.hebrew import HebrewDate
>>> "Purim" in {h.name for h in holidays_on(HebrewDate(5784, 13, 14))}       # Adar II
True
>>> "Purim Katan" in {h.name for h in holidays_on(HebrewDate(5784, 12, 14))}  # Adar I
True

The Omer count

omer_count returns the day of the Omer (1–49) or None outside the count; omer_week_day gives the (weeks, days) breakdown.

>>> from hebrewcal.religious.omer import omer_count, omer_week_day
>>> from hebrewcal.calendars.hebrew import HebrewDate
>>> omer_count(HebrewDate(5785, 1, 16))     # 16 Nisan = day 1
1
>>> omer_count(HebrewDate(5785, 2, 18))     # Lag BaOmer = day 33
33
>>> omer_week_day(HebrewDate(5785, 2, 18))  # 4 weeks and 5 days
(4, 5)

Verification

Classical festivals, fasts, Hanukkah, Purim and the Omer are cross-checked against an independent Hebrew-calendar reference; the modern Israeli days reproduce the published official dates for recent years.