API Reference

The JewCal Class

class JewCal

Convert Gregorian to Jewish dates with holidays and zmanim (Diaspora/Israel).

__init__(gregorian_date: date | None = None, location: Location | None = None, *, diaspora: bool = True) → None

Create a new Jewish date with holidays and zmanim for Diaspora or Israel.

Zmanim are available only if Location is set.
If the Gregorian date is today, check if datetime.now is after nightfall.
If it is after nightfall, the next day for jewish_date is set.

Parameters:

gregorian_date – The Gregorian date to convert from, default is today.
diaspora – True if outside of Israel, False if in Israel.
location – The location to calculate the Zmanim for.

__repr__() → str

Get a printable representation.

Returns:: The JewCal object as a printable representation.

__str__() → str

The Jewish date and events as a string.

Returns:: The Jewish date and events.

property diaspora: bool

Is the schedule for Diaspora or Israel.

Returns:: True if outside of Israel, False if in Israel.

property events: Events

Get the events (Shabbos and Yom Tov) with an action (Candles or Havdalah).

Returns:: The events.

has_events() → bool

Are there any events [(Erev) Shabbos or (Erev) Yom Tov].

Returns:: True if there are any events, False otherwise.

is_erev() → bool

Is it Erev Shabbos and/or Erev Yom Tov.

The return value is False when it is Erev Shabbos or Erev Yom Tov and already Issur Melacha:

it is Erev Shabbos and Yom Tov.
it is Shabbos and Erev Yom Tov.

Returns:: True if it is Erev Shabbos and/or Erev Yom Tov, False otherwise.

is_erev_shabbos() → bool

Is it Erev Shabbos.

Returns:: True if it is Erev Shabbos, False otherwise.

is_erev_yomtov() → bool

Is it Erev Yom Tov.

Returns:: True if it is Erev Yom Tov, False otherwise.

is_issur_melacha() → bool

Is it Issur Melacha.

Returns:: True if it is Issur Melacha, False otherwise.

is_shabbos() → bool

Is it Shabbos.

Returns:: True if it is Shabbos, False otherwise.

is_yomtov() → bool

Is it Yom Tov.

Chol HaMoed is not considered Yom Tov.

Returns:: True if it is Yom Tov, False otherwise.

property jewish_date: JewishDate

Get the date in the Jewish calendar.

Returns:: The Jewish date.

property zmanim: Zmanim | None

Get the Zmanim.

Zmanim are set only if Location is set.

Returns:: The Zmanim.

The Jewish Date

class JewishDate

The Jewish date.

__init__(year: int, month: int, day: int, gregorian_date: date, _is_leap_year: bool) → None

__repr__(): Return repr(self).

__str__() → str

The Jewish date as a string.

Returns:: The Jewish date.

day: int: The day in the Jewish month.

gregorian_date: date: The date in the Gregorian calendar.

month: int: The month in the Jewish year.

year: int: The year in the Jewish calendar.

class Month

The Jewish months.

TISHREI = 7

CHESHVAN = 8

KISLEV = 9

TEVET = 10

SHEVAT = 11

ADAR = 12

ADAR_1 = 14

ADAR_2 = 13

NISAN = 1

IYAR = 2

SIVAN = 3

TAMUZ = 4

AV = 5

ELUL = 6

__str__() → str

Get the month as a readable string.

Returns:: The month.

classmethod get(number: int, *, is_leap: bool) → Month

Get the enum member.

Regarding the months Adar, Adar 1 and 2:

If the Jewish year is non-leap, it returns Adar.
If the Jewish year is leap, it returns Adar 1 or Adar 2.

Parameters:

number – The month number.
is_leap – Is the Jewish year a leap year.

Returns:

The enum member.

__new__(value)

The Events

class Events

The events with an action.

__init__(weekday: dataclasses.InitVar[int], month: dataclasses.InitVar[int], day: dataclasses.InitVar[int], diaspora: dataclasses.InitVar[bool]) → None

__repr__(): Return repr(self).

__str__() → str

Get all the events as a string.

Returns:: All the events as a string.

action: str | None = None

The action (Candles or Havdalah).

If Shabbos and Yom Tov has Candles and Havdalah, Candles has priority.

day: dataclasses.InitVar[int]: The day in the Jewish month.

diaspora: dataclasses.InitVar[bool]: True if outside of Israel, False if in Israel.

month: dataclasses.InitVar[int]: The month of the Jewish year.

shabbos: str | None = None: (Erev) Shabbos definition.

weekday: dataclasses.InitVar[int]: The weekday number in the range of 0-6, where 0=Sunday.

yomtov: str | None = None: (Erev) Yom Tov definition.

The Zmanim

class Location

Location and Zmanim configuration.

__init__(latitude: float, longitude: float, use_tzeis_hakochavim: bool = True, hadlokas_haneiros_minutes: int = 18, tzeis_minutes: int = 72) → None

__repr__(): Return repr(self).

hadlokas_haneiros_minutes: int = 18: Hadlokas Haneiros at minutes before sunset.

latitude: float: The latitude of the location.

longitude: float: The longitude of the location.

tzeis_minutes: int = 72: Tzeis at minutes after sunset.

use_tzeis_hakochavim: bool = True

Use Tzeis Hakochavim or Tzeis at minutes after sunset for nightfall.

True to use Zmanim.tzeis_hakochavim, False to use Zmanim.tzeis_minutes.

class Zmanim

The zmanim of the day.

__init__(gregorian_date: dataclasses.InitVar[date], location: dataclasses.InitVar[Location], set_hadlokas_haneiros: dataclasses.InitVar[bool] = False) → None

__repr__(): Return repr(self).

gregorian_date: dataclasses.InitVar[date]: The date to calculate the Zmanim for.

hadlokas_haneiros: datetime | None = None: Hadlokas Haneiros at minutes before sunset.

is_now_after_nightfall(*, use_tzeis_hakochavim: bool) → bool

Is now after nightfall.

If the date is today, check if datetime.now is after nightfall.

Parameters:: use_tzeis_hakochavim – True to use tzeis_hakochavim, False to use tzeis_minutes for nightfall.
Returns:: True is it after nightfall, False otherwise.

location: dataclasses.InitVar[Location]: The location to calculate the Zmanim for.

plag_hamincha: datetime: Sunrise plus 10.75 halachic hours.

set_hadlokas_haneiros: dataclasses.InitVar[bool] = False: True to set hadlokas_haneiros, False otherwise.

set_zmanim(gregorian_date: date, location: Location, *, set_hadlokas_haneiros: bool = False) → None

Set the zmanim.

Parameters:

gregorian_date – The date of the zmanim.
location – The location to calculate the Zmanim for.
set_hadlokas_haneiros – True to set hadlokas_haneiros, False otherwise.

sunrise: datetime: 0.833 degrees above horizon.

sunset: datetime: 0.833 degrees below horizon

to_dict() → dict[str, str | None]

Get the zmanim as a dictionary.

Returns:: A dictionary representation of the zmanim in UTC.

tzeis_hakochavim: datetime: Nightfall at 8.5 degrees below the horizon.

tzeis_minutes: datetime: Nightfall at minutes after sunset.

Deprecated

property JewCal.year: int

Get the year in the Jewish calendar.

Deprecated since version 0.6.0: Use jewish_date .year

Returns:: The year in the Jewish calendar.

property JewCal.month: int

Get the month in the Jewish year.

Deprecated since version 0.6.0: Use jewish_date .month

Returns:: The month in the Jewish year.

property JewCal.day: int

Get the day in the Jewish month.

Deprecated since version 0.6.0: Use jewish_date .day

Returns:: The day in the Jewish month.

property JewCal.gregorian_date: date

Get the Gregorian date.

Deprecated since version 0.6.0: Use jewish_date .gregorian_date

Returns:: The date in the Gregorian calendar.

property JewCal.shabbos: str | None

Get the (Erev) Shabbos definition.

Deprecated since version 0.6.0: Use events .shabbos

Returns:: The (Erev) Shabbos definition.

property JewCal.yomtov: str | None

Get the (Erev) Yom Tov definition.

Deprecated since version 0.6.0: Use events .yomtov

Returns:: The (Erev) Yom Tov definition.

property JewCal.category: str | None

Get the category (Candles or Havdalah).

Deprecated since version 0.6.0: Use events .action

Returns:: The category (Candles or Havdalah).