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.HDateInfo(date: ~datetime.date | ~hdate.hebrew_date.HebrewDate = <factory>, diaspora: bool = False, nusach: ~typing.Literal['sephardi', 'ashkenazi'] = 'sephardi')

Bases: TranslatorMixin

Hebrew date information class.

Provides access to various properties of a given date.

property daf_yomi: Masechta

Return the daf yomi for the given date.

date: date | HebrewDate

diaspora: bool = False

property first_day: HDateInfo

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 HDateInfo is Shabbat followed by no Yom Tov, returns the Saturday. If this HDateInfo is neither Yom Tov, nor Shabbat, this just returns itself.

property gdate: date

Return the Gregorian date for the given Hebrew date.

property gevurot_geshamim: str

Return the rain prayer (Tal uMatar, veTen Beracha, …).

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.

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: HDateInfo

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: HDateInfo

Return the HDateInfo for the next day.

nusach: Literal['sephardi', 'ashkenazi'] = 'sephardi'

property omer: Omer | None

Return the Omer object.

property parasha: Parasha

Return the upcoming parasha.

property previous_day: HDateInfo

Return the HDateInfo for the previous day.

property upcoming_erev_shabbat: HDateInfo

Return the HDateInfo for the upcoming or current Erev Shabbat (Friday).

property upcoming_erev_shabbat_or_erev_yom_tov: HDateInfo

Return the HDateInfo for upcoming or current Erev Shabbat or Erev Yom Tov.

property upcoming_erev_yom_tov: HDateInfo

Return the HDateInfo for the upcoming or current Erev Yom Tov.

property upcoming_shabbat: HDateInfo

Return the HDateInfo for either the upcoming or current Shabbat.

property upcoming_shabbat_or_yom_tov: HDateInfo

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

property upcoming_yom_tov: HDateInfo

Return the HDateInfo for the upcoming or current Yom Tov.

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

Bases: TranslatorMixin

Define a Hebrew date object.

day: int = 1

days_in_month(month: Months) → int

Return the number of days in a month.

dow() → Weekday

Return: day of the week.

static from_gdate(date: date) → HebrewDate

Return Hebrew date from Gregorian date.

static from_jdn(jdn: int) → HebrewDate

Convert from the Julian day to the Hebrew day.

is_leap_year() → bool

Return: True if the year is a leap year.

long_cheshvan() → bool

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

Return a new HebrewDate with a different year/month/day.

short_kislev() → bool

Return whether this year has a short Kislev or not.

to_gdate() → date

Return Gregorian date from Hebrew date.

to_jdn() → int

Compute Julian day number from HebrewDate.

valid_for_year(year: int) → bool

Check if the date is valid for the given year.

year: int = 0

static year_size(hebrew_year: int) → int

Return: total days in hebrew year.

class hdate.HolidayTypes(*values)

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)

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(*values)

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

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

Return the number of days in this month.

classmethod in_year(year: int) → list[Months]

Return the months for the given year.

next_month(year: int) → Months

Return the next month.

prev_month(year: int) → Months

Return the previous month.

class hdate.Zmanim(date: ~datetime.date = <factory>, location: ~hdate.location.Location = <factory>, candle_lighting_offset: int = 18, havdalah_offset: int = 0)

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) → bool

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) → bool

At the given time, return whether issur melacha is in effect.

location: Location

motzei_shabbat_chag(time: datetime) → bool

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.