API Reference

Jewish calendrical date and times for a given location.

HDate calculates and generates a representation either in English or Hebrew of the Jewish calendrical date and times for a given location

class hdate.HDate(date: date | HebrewDate = datetime.date(2025, 2, 2), diaspora: bool = False, language: str = 'hebrew')[source]

Bases: TranslatorMixin

Hebrew date class.

Supports converting from Gregorian and Julian to Hebrew date.

property daf_yomi: Masechta: Return a string representation of the daf yomi.

property first_day: HDate

Return the first day of Yom Tov or Shabbat.

This is useful for three-day holidays, for example: it will return the first in a string of Yom Tov + Shabbat. If this HDate is Shabbat followed by no Yom Tov, returns the Saturday. If this HDate is neither Yom Tov, nor Shabbat, this just returns itself.

property gdate: date: Return the Gregorian date for the given Hebrew date object.

property hdate: HebrewDate: Return the hebrew date.

property holidays: list[Holiday]: Return the abstract holiday information from holidays table.

property is_holiday: bool: Return True if this date is a holiday (any kind).

property is_shabbat: bool

Return True if this date is Shabbat, specifically Saturday.

Returns False on Friday because the HDate object has no notion of time. For more detailed nuance, use the Zmanim object.

property is_yom_tov: bool: Return True if this date is a Yom Tov.

property last_day: HDate

Return the last day of Yom Tov or Shabbat.

This is useful for three-day holidays, for example: it will return the last in a string of Yom Tov + Shabbat. If this HDate is Shabbat followed by no Yom Tov, returns the Saturday. If this HDate is neither Yom Tov, nor Shabbat, this just returns itself.

property next_day: HDate: Return the HDate for the next day.

property omer: Omer | None: Return the Omer object.

property parasha: Parasha: Return the upcoming parasha.

property previous_day: HDate: Return the HDate for the previous day.

property upcoming_shabbat: HDate

Return the HDate for either the upcoming or current Shabbat.

If it is currently Shabbat, returns the HDate of the Saturday.

property upcoming_shabbat_or_yom_tov: HDate

Return the HDate for the upcoming or current Shabbat or Yom Tov.

If it is currently Shabbat, returns the HDate of the Saturday. If it is currently Yom Tov, returns the HDate of the first day (rather than “leil” Yom Tov). To access Leil Yom Tov, use upcoming_shabbat_or_yom_tov.previous_day.

property upcoming_yom_tov: HDate

Find the next upcoming yom tov (i.e. no-melacha holiday).

If it is currently the day of yom tov (irrespective of zmanim), returns that yom tov.

class hdate.HebrewDate(year: int = 0, month: Months = Months.TISHREI, day: int = 1)[source]

Bases: TranslatorMixin

Define a Hebrew date object.

day: int = 1

days_in_month(month: Months) → int[source]: Return the number of days in a month.

dow() → Weekday[source]: Return: day of the week.

static from_gdate(date: date) → HebrewDate[source]: Return Hebrew date from Gregorian date.

static from_jdn(jdn: int) → HebrewDate[source]: Convert from the Julian day to the Hebrew day.

is_leap_year() → bool[source]: Return: True if the year is a leap year.

long_cheshvan() → bool[source]: Return whether this year has a long Cheshvan or not.

month: Months = 1

replace(year: int | None = None, month: Months | None = None, day: int | None = None) → HebrewDate[source]: Return a new HebrewDate with a different year/month/day.

short_kislev() → bool[source]: Return whether this year has a short Kislev or not.

to_gdate() → date[source]: Return Gregorian date from Hebrew date.

to_jdn() → int[source]: Compute Julian day number from HebrewDate.

valid_for_year(year: int) → bool[source]: Check if the date is valid for the given year.

year: int = 0

static year_size(hebrew_year: int) → int[source]: Return: total days in hebrew year.

class hdate.HolidayTypes(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Container class for holiday type integer mappings.

EREV_YOM_TOV = 2

FAST_DAY = 5

HOL_HAMOED = 3

ISRAEL_NATIONAL_HOLIDAY = 9

MELACHA_PERMITTED_HOLIDAY = 4

MEMORIAL_DAY = 8

MINOR_HOLIDAY = 7

MODERN_HOLIDAY = 6

ROSH_CHODESH = 10

YOM_TOV = 1

class hdate.Location(name: str = 'Jerusalem', latitude: float = 31.778, longitude: float = 35.235, timezone: str | tzinfo = zoneinfo.ZoneInfo(key='Asia/Jerusalem'), altitude: float = 754, diaspora: bool = False)[source]

Bases: object

Define a geolocation for Zmanim calculations.

altitude: float = 754

diaspora: bool = False

latitude: float = 31.778

longitude: float = 35.235

name: str = 'Jerusalem'

timezone: str | tzinfo = zoneinfo.ZoneInfo(key='Asia/Jerusalem')

class hdate.Months(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: TranslatorMixin, IntEnum

Enum class for the Hebrew months.

ADAR = 6

ADAR_I = 7

ADAR_II = 8

AV = 13

ELUL = 14

IYYAR = 10

KISLEV = 3

MARCHESHVAN = 2

NISAN = 9

SHVAT = 5

SIVAN = 11

TAMMUZ = 12

TEVET = 4

TISHREI = 1

compare(other: Months | int, order_type: str = 'calendar') → int[source]

Compare this month to another month.

The comparison can be either “calendar” or “biblical”. When using the biblical order, we consider NISAN as the first month. By default, we use the calendar order starting at TISHREI.

days(year: int | None = None) → int[source]: Return the number of days in this month.

classmethod in_year(year: int) → list[Months][source]: Return the months for the given year.

next_month(year: int) → Months[source]: Return the next month.

prev_month(year: int) → Months[source]: Return the previous month.

class hdate.Zmanim(date: ~datetime.date = <factory>, location: ~hdate.location.Location = <factory>, language: str = 'hebrew', candle_lighting_offset: int = 18, havdalah_offset: int = 0)[source]

Bases: TranslatorMixin

Return Jewish day times.

The Zmanim class returns times for the specified day ONLY. If you wish to obtain times for the interval of a multi-day holiday for example, you need to use Zmanim in conjunction with some of the iterative properties of HDate. Also, Zmanim are reported regardless of the current time. So the havdalah value is constant if the current time is before or after it. The current time is only used to report the “issur_melacha_in_effect” property.

property candle_lighting: datetime | None: Return the time for candle lighting, or None if not applicable.

candle_lighting_offset: int = 18

date: date

erev_shabbat_chag(time: datetime = datetime.datetime(2025, 2, 2, 14, 30, 13, 456598)) → bool[source]: At the given time, return whether erev shabbat or chag

property havdalah: datetime | None

Return the time for havdalah, or None if not applicable.

If havdalah_offset is 0, uses the time for three_stars. Otherwise, adds the offset to the time of sunset and uses that. If it’s currently a multi-day YomTov, and the end of the stretch is after today, the havdalah value is defined to be None (to avoid misleading the user that melacha is permitted).

havdalah_offset: int = 0

issur_melacha_in_effect(time: datetime = datetime.datetime(2025, 2, 2, 14, 30, 13, 456594)) → bool[source]: At the given time, return whether issur melacha is in effect.

language: str = 'hebrew'

location: Location

motzei_shabbat_chag(time: datetime = datetime.datetime(2025, 2, 2, 14, 30, 13, 456599)) → bool[source]: At the given time, return whether motzei shabbat or chag

property zmanim: dict[str, Zman]: Return a list of Jewish times for the given location.