hebrewcal module
The hebrewcal module contains Hebrew calendar related classes and functions.
It contains classes for representing a Hebrew year and month, functions
for getting the holiday or fast day for a given date, and classes adapting
calendar
classes to render Hebrew calendars.
Contents
- exception pyluach.hebrewcal.IllegalMonthError(month)[source]
Bases:
ValueError
An exception for an illegal month.
Subclasses
ValueError
to show a message for an invalid month number for the Hebrew calendar. Mimicscalendar.IllegalMonthError
.- Parameters:
month (int) – The invalid month number
- add_note()
Exception.add_note(note) – add a note to the exception
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception pyluach.hebrewcal.IllegalWeekdayError(weekday)[source]
Bases:
ValueError
An exception for an illegal weekday.
Subclasses
ValueError
to show a message for an invalid weekday number. Mimicscalendar.IllegalWeekdayError
.- Parameters:
month (int) – The invalid month number
- add_note()
Exception.add_note(note) – add a note to the exception
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- class pyluach.hebrewcal.Year(year)[source]
Bases:
object
A Year object represents a Hebrew calendar year.
It provided the following operators:
Operation
Result
year2 = year1 + int
New
Year
int
days after year1.year2 = year1 - int
New
Year
int
days before year1.int = year1 - year2
int
equal to the absolute value of the difference between year2 and year1.bool = year1 == year2
True if year1 represents the same year as year2.
bool = year1 > year2
True if year1 is later than year2.
bool = year1 >= year2
True if year1 is later or equal to year2.
bool = year1 < year2
True if year 1 earlier than year2.
bool = year1 <= year2
True if year 1 earlier or equal to year 2.
- Parameters:
year (int) – A Hebrew year.
- itermonths()[source]
Yield Month instance for each month of the year.
- Yields:
Month
– The next month in the Hebrew calendar year as aMonth
instance beginning with Tishrei through Elul.
- iterdays()[source]
Yield integer for each day of the year.
- Yields:
int
– An integer beginning with 1 for the the next day of the year.
- iterdates()[source]
Iterate through each Hebrew date of the year.
- Yields:
pyluach.dates.HebrewDate
– The next date of the Hebrew calendar year starting with the first of Tishrei.
- classmethod from_pydate(pydate)[source]
Return Year object from python date object.
- Parameters:
pydate (datetime.date) – A python standard library date object
- Returns:
The Hebrew year the given date occurs in
- Return type:
- class pyluach.hebrewcal.Month(year, month)[source]
Bases:
object
A Month object represents a month of the Hebrew calendar.
It provides the same operators as a Year object.
- Parameters:
- month
The month as an integer starting with 7 for Tishrei through 13 if necessary for Adar Sheni and then 1-6 for Nissan - Elul.
- Type:
- classmethod from_pydate(pydate)[source]
Return Month object from python date object.
- Parameters:
pydate (datetime.date) – A python standard library date object
- Returns:
The Hebrew month the given date occurs in
- Return type:
- starting_weekday()[source]
Return first weekday of the month.
- Returns:
The weekday of the first day of the month starting with Sunday as 1 through Saturday as 7.
- Return type:
- iterdates()[source]
Iterate through the Hebrew dates of the month.
- Yields:
pyluach.dates.HebrewDate
– The next Hebrew date of the month.
- molad()[source]
Return the month’s molad.
- Returns:
A dictionary in the form
{weekday: int, hours: int, parts: int}
- Return type:
Note
This method does not return the molad in the form that is traditionally announced in the shul. This is the molad in the form used to calculate the length of the year.
See also
molad_announcement
The molad as it is traditionally announced.
- molad_announcement()[source]
Return the month’s molad in the announcement form.
Returns a dictionary in the form that the molad is traditionally announced. The weekday is adjusted to change at midnight and the hour of the day and minutes are given as traditionally announced. Note that the hour is given as in a twenty four hour clock ie. 0 for 12:00 AM through 23 for 11:00 PM.
- Returns:
A dictionary in the form:
{ weekday: int, hour: int, minutes: int, parts: int }
- Return type:
- pyluach.hebrewcal.to_hebrew_numeral(num, thousands=False, withgershayim=True)[source]
Convert int to Hebrew numeral.
Function useful in formatting Hebrew calendars.
- Parameters:
num (int) – The number to convert
thousands (bool, optional) – True if the hebrew returned should include a letter for the thousands place ie. ‘ה׳’ for five thousand. Default is
False
.withgershayim (bool, optional) –
True
to include a geresh after a single letter and double geresh before the last letter if there is more than one letter. Default isTrue
.
- Returns:
The Hebrew numeral representation of the number.
- Return type:
- class pyluach.hebrewcal.HebrewCalendar(firstweekday=1, hebrewnumerals=True, hebrewweekdays=False, hebrewmonths=False, hebrewyear=False)[source]
Bases:
Calendar
Calendar base class.
This class extends the python library
Calendar
class for the Hebrew calendar. The weekdays are 1 for Sunday through 7 for Shabbos.- Parameters:
firstweekday (int, optional) – The weekday to start each week with. Default is
1
for Sunday.hebrewnumerals (bool, optional) – Default is
True
, which shows the days of the month with Hebrew numerals.False
shows the days of the month as a decimal number.hebrewweekdays (bool, optional) –
True
to show the weekday in Hebrew. Default isFalse
, which shows the weekday in English.hebrewmonths (bool, optional) –
True
to show the month name in Hebrew. Default isFalse
, which shows the month name transliterated into English.hebrewyear (bool, optional) –
True
to show the year in Hebrew numerals. Default isFalse
, which shows the year as a decimal number.
Note
All of the parameters other than firstweekday are not used in the
HebrewCalendar
base class. They’re there for use in child classes.- iterweekdays()[source]
Return one week of weekday numbers.
The numbers start with the configured first one.
- Yields:
int
– The next weekday with 1-7 for Sunday - Shabbos. The iterator starts with theHebrewCalendar
object’s configured first weekday ie. if configured to start with Monday it will first yield 2 and end with 1.
- itermonthdates(year, month)[source]
Yield dates for one month.
The iterator will always iterate through complete weeks, so it will yield dates outside the specified month.
- Parameters:
- Yields:
pyluach.dates.HebrewDate
– The next Hebrew Date of the month starting with the first date of the week the first of the month falls in, and ending with the last date of the week that the last day of the month falls in.
- itermonthdays(year, month)[source]
Like
itermonthdates()
but will yield day numbers. For days outside the specified month the day number is 0.
- yeardatescalendar(year, width=3)[source]
Return data of specified year ready for formatting.
- Parameters:
- Returns:
Returns a list of month rows. Each month row contains a list of up to width months. Each month contains either 5 or 6 weeks, and each week contains 7 days. Days are
HebrewDate
objects.- Return type:
list
of list of list of list ofpyluach.dates.HebrewDate
- yeardays2calendar(year, width=3)[source]
Return the data of the specified year ready for formatting.
This method is similar to the
yeardatescalendar
except the entries in the week lists are(day number, weekday number)
tuples.- Parameters:
- Returns:
Returns a list of month rows. Each month row contains a list of up to width months. Each month contains between 4 and 6 weeks, and each week contains 1-7 days. Days are tuples with the form
(day number, weekday number)
.- Return type:
- yeardayscalendar(year, width=3)[source]
Return the data of the specified year ready for formatting.
This method is similar to the
yeardatescalendar
except the entries in the week lists are day numbers.- Parameters:
- Returns:
Returns a list of month rows. Each month row contains a list of up to width months. Each month contains either 5 or 6 weeks, and each week contains 1-7 days. Each day is the day of the month as an int.
- Return type:
- monthdatescalendar(year, month)[source]
Return matrix (list of lists) of dates for month’s calendar.
Each row represents a week; week entries are HebrewDate instances.
- Parameters:
- Returns:
List of weeks in the month containing 7
HebrewDate
instances each.- Return type:
list
of list ofpyluach.dates.HebrewDate
- monthdays2calendar(year, month)
Return a matrix representing a month’s calendar. Each row represents a week; week entries are (day number, weekday number) tuples. Day numbers outside this month are zero.
- monthdayscalendar(year, month)
Return a matrix representing a month’s calendar. Each row represents a week; days outside this month are zero.
- class pyluach.hebrewcal.HebrewHTMLCalendar(firstweekday=1, hebrewnumerals=True, hebrewweekdays=False, hebrewmonths=False, hebrewyear=False, rtl=False)[source]
Bases:
HebrewCalendar
,HTMLCalendar
Class to generate html calendars .
Adapts
calendar.HTMLCalendar
for the Hebrew calendar.- Parameters:
firstweekday (int, optional) – The weekday to start each week with. Default is
1
for Sunday.hebrewnumerals (bool, optional) – Default is
True
, which shows the days of the month with Hebrew numerals.False
shows the days of the month as a decimal number.hebrewweekdays (bool, optional) –
True
to show the weekday in Hebrew. Default isFalse
, which shows the weekday in English.hebrewmonths (bool, optional) –
True
to show the month name in Hebrew. Default isFalse
, which shows the month name transliterated into English.hebrewyear (bool, optional) –
True
to show the year in Hebrew numerals. Default isFalse
, which shows the year as a decimal number.rtl (bool, optional) –
True
to arrange the months and the days of the month from right to left. Default isFalse
.
- formatweek(theweek)
Return a complete week as a table row.
- formatweekheader()
Return a header for a week as a table row.
- formatyearpage(theyear, width=3, css='calendar.css', encoding=None)
Return a formatted year as a complete HTML page.
- itermonthdates(year, month)
Yield dates for one month.
The iterator will always iterate through complete weeks, so it will yield dates outside the specified month.
- Parameters:
- Yields:
pyluach.dates.HebrewDate
– The next Hebrew Date of the month starting with the first date of the week the first of the month falls in, and ending with the last date of the week that the last day of the month falls in.
- itermonthdays(year, month)
Like
itermonthdates()
but will yield day numbers. For days outside the specified month the day number is 0.
- itermonthdays2(year, month)
Return iterator for the days and weekdays of the month.
- itermonthdays3(year, month)
Return iterator for the year, month, and day of the month.
- itermonthdays4(year, month)
Return iterator for the year, month, day, and weekday
- iterweekdays()
Return one week of weekday numbers.
The numbers start with the configured first one.
- Yields:
int
– The next weekday with 1-7 for Sunday - Shabbos. The iterator starts with theHebrewCalendar
object’s configured first weekday ie. if configured to start with Monday it will first yield 2 and end with 1.
- monthdatescalendar(year, month)
Return matrix (list of lists) of dates for month’s calendar.
Each row represents a week; week entries are HebrewDate instances.
- Parameters:
- Returns:
List of weeks in the month containing 7
HebrewDate
instances each.- Return type:
list
of list ofpyluach.dates.HebrewDate
- monthdays2calendar(year, month)
Return a matrix representing a month’s calendar. Each row represents a week; week entries are (day number, weekday number) tuples. Day numbers outside this month are zero.
- monthdayscalendar(year, month)
Return a matrix representing a month’s calendar. Each row represents a week; days outside this month are zero.
- yeardatescalendar(year, width=3)
Return data of specified year ready for formatting.
- Parameters:
- Returns:
Returns a list of month rows. Each month row contains a list of up to width months. Each month contains either 5 or 6 weeks, and each week contains 7 days. Days are
HebrewDate
objects.- Return type:
list
of list of list of list ofpyluach.dates.HebrewDate
- yeardays2calendar(year, width=3)
Return the data of the specified year ready for formatting.
This method is similar to the
yeardatescalendar
except the entries in the week lists are(day number, weekday number)
tuples.- Parameters:
- Returns:
Returns a list of month rows. Each month row contains a list of up to width months. Each month contains between 4 and 6 weeks, and each week contains 1-7 days. Days are tuples with the form
(day number, weekday number)
.- Return type:
- yeardayscalendar(year, width=3)
Return the data of the specified year ready for formatting.
This method is similar to the
yeardatescalendar
except the entries in the week lists are day numbers.- Parameters:
- Returns:
Returns a list of month rows. Each month row contains a list of up to width months. Each month contains either 5 or 6 weeks, and each week contains 1-7 days. Each day is the day of the month as an int.
- Return type:
- class pyluach.hebrewcal.HebrewTextCalendar(firstweekday=1, hebrewnumerals=True, hebrewweekdays=False, hebrewmonths=False, hebrewyear=False)[source]
Bases:
HebrewCalendar
,TextCalendar
Subclass of HebrewCalendar that outputs a plaintext calendar.
HebrewTextCalendar
adaptscalendar.TextCalendar
for the Hebrew calendar.- Parameters:
firstweekday (int, optional) – The weekday to start each week with. Default is
1
for Sunday.hebrewnumerals (bool, optional) – Default is
True
, which shows the days of the month with Hebrew numerals.False
shows the days of the month as a decimal number.hebrewweekdays (bool, optional) –
True
to show the weekday in Hebrew. Default isFalse
, which shows the weekday in English.hebrewmonths (bool, optional) –
True
to show the month name in Hebrew. Default isFalse
, which shows the month name transliterated into English.hebrewyear (bool, optional) –
True
to show the year in Hebrew numerals. Default isFalse
, which shows the year as a decimal number.
Note
This class generates plain text calendars. Any program that adds any formatting may misrender the calendars especially when using any Hebrew characters.
- formatday(day, weekday, width)[source]
Return a formatted day.
Extends calendar.TextCalendar formatday method.
- formatweekday(day, width)[source]
Return formatted weekday.
Extends calendar.TextCalendar formatweekday method.
- formatyear(theyear, w=2, l=1, c=6, m=3)[source]
Return a year’s calendar as a multi-line string.
- Parameters:
- Return type:
- formatmonth(theyear, themonth, w=0, l=0)
Return a month’s calendar string (multi-line).
- formatweek(theweek, width)
Returns a single week in a string (no newline).
- formatweekheader(width)
Return a header for a week.
- itermonthdates(year, month)
Yield dates for one month.
The iterator will always iterate through complete weeks, so it will yield dates outside the specified month.
- Parameters:
- Yields:
pyluach.dates.HebrewDate
– The next Hebrew Date of the month starting with the first date of the week the first of the month falls in, and ending with the last date of the week that the last day of the month falls in.
- itermonthdays(year, month)
Like
itermonthdates()
but will yield day numbers. For days outside the specified month the day number is 0.
- itermonthdays2(year, month)
Return iterator for the days and weekdays of the month.
- itermonthdays3(year, month)
Return iterator for the year, month, and day of the month.
- itermonthdays4(year, month)
Return iterator for the year, month, day, and weekday
- iterweekdays()
Return one week of weekday numbers.
The numbers start with the configured first one.
- Yields:
int
– The next weekday with 1-7 for Sunday - Shabbos. The iterator starts with theHebrewCalendar
object’s configured first weekday ie. if configured to start with Monday it will first yield 2 and end with 1.
- monthdatescalendar(year, month)
Return matrix (list of lists) of dates for month’s calendar.
Each row represents a week; week entries are HebrewDate instances.
- Parameters:
- Returns:
List of weeks in the month containing 7
HebrewDate
instances each.- Return type:
list
of list ofpyluach.dates.HebrewDate
- monthdays2calendar(year, month)
Return a matrix representing a month’s calendar. Each row represents a week; week entries are (day number, weekday number) tuples. Day numbers outside this month are zero.
- monthdayscalendar(year, month)
Return a matrix representing a month’s calendar. Each row represents a week; days outside this month are zero.
- prmonth(theyear, themonth, w=0, l=0)
Print a month’s calendar.
- prweek(theweek, width)
Print a single week (no newline).
- pryear(theyear, w=0, l=0, c=6, m=3)
Print a year’s calendar.
- yeardatescalendar(year, width=3)
Return data of specified year ready for formatting.
- Parameters:
- Returns:
Returns a list of month rows. Each month row contains a list of up to width months. Each month contains either 5 or 6 weeks, and each week contains 7 days. Days are
HebrewDate
objects.- Return type:
list
of list of list of list ofpyluach.dates.HebrewDate
- yeardays2calendar(year, width=3)
Return the data of the specified year ready for formatting.
This method is similar to the
yeardatescalendar
except the entries in the week lists are(day number, weekday number)
tuples.- Parameters:
- Returns:
Returns a list of month rows. Each month row contains a list of up to width months. Each month contains between 4 and 6 weeks, and each week contains 1-7 days. Days are tuples with the form
(day number, weekday number)
.- Return type:
- yeardayscalendar(year, width=3)
Return the data of the specified year ready for formatting.
This method is similar to the
yeardatescalendar
except the entries in the week lists are day numbers.- Parameters:
- Returns:
Returns a list of month rows. Each month row contains a list of up to width months. Each month contains either 5 or 6 weeks, and each week contains 1-7 days. Each day is the day of the month as an int.
- Return type:
- pyluach.hebrewcal.fast_day(date, hebrew=False)[source]
Return name of fast day or None.
- Parameters:
- Returns:
The name of the fast day or
None
if the given date is not a fast day.- Return type:
str or None
- pyluach.hebrewcal.festival(date, israel=False, hebrew=False, include_working_days=True, prefix_day=False)[source]
Return Jewish festival of given day.
This method will return all major and minor religous Jewish holidays not including fast days.
- Parameters:
date (BaseDate) – Any subclass of
BaseDate
can be used.israel (bool, optional) –
True
if you want the festivals according to the Israel schedule. Defaults toFalse
.hebrew (bool, optional) –
True
if you want the festival name in Hebrew letters. Default isFalse
, which returns the name transliterated into English.include_working_days (bool, optional) –
True
to include festival days on which melacha (work) is allowed; ie. Pesach Sheni, Chol Hamoed, etc. Default isTrue
.prefix_day (bool, optional) –
True
to prefix multi day festivals with the day of the festival. Default isFalse
.
- Returns:
The name of the festival or
None
if the given date is not a Jewish festival.- Return type:
str or None
Examples
>>> from pyluach.dates import HebrewDate pesach = HebrewDate(2023, 1, 15) >>> festival(pesach, prefix_day=True) '1 Pesach' >>> festival(pesach, hebrew=True, prefix_day=True) 'א׳ פסח' >>> shavuos = HebrewDate(5783, 3, 6) >>> festival(shavuos, israel=True, prefix_day=True) 'Shavuos'
- pyluach.hebrewcal.holiday(date, israel=False, hebrew=False, prefix_day=False)[source]
Return Jewish holiday of given date.
The holidays include the major and minor religious Jewish holidays including fast days.
- Parameters:
date (pyluach.dates.BaseDate) – Any subclass of
BaseDate
can be used.israel (bool, optional) –
True
if you want the holidays according to the israel schedule. Default isFalse
.hebrew (bool, optional) –
True
if you want the holiday name in Hebrew letters. Default isFalse
, which returns the name transliterated into English.prefix_day (bool, optional) –
True
to prefix multi day holidays with the day of the holiday. Default isFalse
.
- Returns:
The name of the holiday or
None
if the given date is not a Jewish holiday.- Return type:
str or None
Examples
>>> from pyluach.dates import HebrewDate >>> pesach = HebrewDate(2023, 1, 15) >>> holiday(pesach, prefix_day=True) '1 Pesach' >>> holiday(pesach, hebrew=True, prefix_day=True) 'א׳ פסח' >>> taanis_esther = HebrewDate(5783, 12, 13) >>> holiday(taanis_esther, prefix_day=True) 'Taanis Esther'