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: date | HebrewDate = <factory>, diaspora: bool = False, nusach: Literal['sephardi', 'ashkenazi']='sephardi')[source]

Bases: TranslatorMixin

Hebrew date information class.

Provides access to various properties of a given date.

property daf_yomi: str: 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: Return the Omer object.

property parasha: str: 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)[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: None | int = None, month: None | Months = None, day: None | int = 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(*values)[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(*values)[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

biblical_order: int

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: None | int = 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.

length: int | Callable[[int], int]

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

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

class hdate.Zmanim(date: date = <factory>, location: Location = <factory>, 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) → 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) → bool[source]: At the given time, return whether issur melacha is in effect.

location: Location

motzei_shabbat_chag(time: datetime) → 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.