dates module
The dates module implements classes for representing and manipulating several date types.
Contents
Note
All instances of the classes in this module should be treated as read only. No attributes should be changed once they’re created.
- class pyluach.dates.Rounding(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
Bases:
Enum
Enumerator to provide options for rounding Hebrew dates.
This provides constants to use as arguments for functions. It should not be instantiated.
- PREVIOUS_DAY
If the day is the 30th and the month only has 29 days, round to the 29th of the month.
- NEXT_DAY
If the day is the 30th and the month only has 29 days, round to the 1st of the next month.
- EXCEPTION
If the day is the 30th and the month only has 29 days, raise a ValueError.
- class pyluach.dates.BaseDate[source]
Bases:
ABC
BaseDate is a base class for all date types.
It provides the following arithmetic and comparison operators common to all child date types.
Operation
Result
d2 = date1 + int
New date
int
days after date1d2 = date1 - int
New date
int
days before date1int = date1 - date2
Positive integer equal to the duration from date1 to date2
date1 > date2
True if date1 occurs later than date2
date1 < date2
True if date1 occurs earlier than date2
date1 == date2
True if date1 occurs on the same day as date2
date1 != date2
True if
date1 == date2
is FalseAny subclass of
BaseDate
can be compared to and diffed with any other subclass date.- abstract property jd
Return julian day number.
- Returns:
The Julian day number at midnight (as
n.5
).- Return type:
- weekday()[source]
Return day of week as an integer.
- Returns:
An integer representing the day of the week with Sunday as 1 through Saturday as 7.
- Return type:
- isoweekday()[source]
Return the day of the week corresponding to the iso standard.
- Returns:
An integer representing the day of the week where Monday is 1 and and Sunday is 7.
- Return type:
- shabbos()[source]
Return the Shabbos on or following the date.
- Returns:
self if the date is Shabbos or else the following Shabbos as the same date type as called from.
- Return type:
Examples
>>> heb_date = HebrewDate(5781, 3, 29) >>> greg_date = heb_date.to_greg() >>> heb_date.shabbos() HebrewDate(5781, 4, 2) >>> greg_date.shabbos() GregorianDate(2021, 6, 12)
- festival(israel=False, hebrew=False, include_working_days=True, prefix_day=False)[source]
Return name of Jewish festival of date.
This method will return all major and minor religous Jewish holidays not including fast days.
- Parameters:
israel (bool, optional) –
True
if you want the holidays 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
>>> pesach = HebrewDate(2023, 1, 15) >>> pesach.festival(prefix_day=True) '1 Pesach' >>> pesach.festival(hebrew=True, prefix_day=True) 'א׳ פסח' >>> shavuos = HebrewDate(5783, 3, 6) >>> shavuos.festival(israel=True, prefix_day=True) 'Shavuos'
- holiday(israel=False, hebrew=False, prefix_day=False)[source]
Return name of Jewish holiday of the date.
The holidays include the major and minor religious Jewish holidays including fast days.
- Parameters:
israel (bool, optional) –
True
if you want the holidays according to the Israel schedule. Defaults toFalse
.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
>>> pesach = HebrewDate(2023, 1, 15) >>> pesach.holiday(prefix_day=True) '1 Pesach' >>> pesach.holiday(hebrew=True, prefix_day=True) 'א׳ פסח' >>> taanis_esther = HebrewDate(5783, 12, 13) >>> taanis_esther.holiday(prefix_day=True) 'Taanis Esther'
- class pyluach.dates.CalendarDateMixin(year, month, day, jd=None)[source]
Bases:
object
CalendarDateMixin is a mixin for Hebrew and Gregorian dates.
- tuple()[source]
Return date as tuple.
- Returns:
A tuple of ints in the form
(year, month, day)
.- Return type:
tuple of ints
- dict()[source]
Return the date as a dictionary.
- Returns:
A dictionary in the form
{'year': int, 'month': int, 'day': int}
.- Return type:
- class pyluach.dates.JulianDay(day)[source]
Bases:
BaseDate
A JulianDay object represents a Julian Day at midnight.
- Parameters:
day (float or int) – The julian day. Note that Julian days start at noon so day number 10 is represented as 9.5 which is day 10 at midnight.
- static from_pydate(pydate)[source]
Return a JulianDay from a python date object.
- Parameters:
pydate (datetime.date) – A python standard library
datetime.date
instance- Return type:
- static today()[source]
Return instance of current Julian day from timestamp.
Extends the built-in
datetime.date.today()
.- Returns:
A JulianDay instance representing the current Julian day from the timestamp.
- Return type:
Warning
Julian Days change at noon, but pyluach treats them as if they change at midnight, so at midnight this method will return
JulianDay(n.5)
until the following midnight when it will returnJulianDay(n.5 + 1)
.
- to_greg()[source]
Convert JulianDay to a Gregorian Date.
- Returns:
The equivalent Gregorian date instance.
- Return type:
Notes
This method uses the Fliegel-Van Flandern algorithm.
- to_heb()[source]
Convert to a Hebrew date.
- Returns:
The equivalent Hebrew date instance.
- Return type:
- to_pydate()[source]
Convert to a datetime.date object.
- Returns:
A standard library
datetime.date
instance.- Return type:
- fast_day(hebrew=False)
Return name of fast day of date.
- festival(israel=False, hebrew=False, include_working_days=True, prefix_day=False)
Return name of Jewish festival of date.
This method will return all major and minor religous Jewish holidays not including fast days.
- Parameters:
israel (bool, optional) –
True
if you want the holidays 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
>>> pesach = HebrewDate(2023, 1, 15) >>> pesach.festival(prefix_day=True) '1 Pesach' >>> pesach.festival(hebrew=True, prefix_day=True) 'א׳ פסח' >>> shavuos = HebrewDate(5783, 3, 6) >>> shavuos.festival(israel=True, prefix_day=True) 'Shavuos'
- holiday(israel=False, hebrew=False, prefix_day=False)
Return name of Jewish holiday of the date.
The holidays include the major and minor religious Jewish holidays including fast days.
- Parameters:
israel (bool, optional) –
True
if you want the holidays according to the Israel schedule. Defaults toFalse
.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
>>> pesach = HebrewDate(2023, 1, 15) >>> pesach.holiday(prefix_day=True) '1 Pesach' >>> pesach.holiday(hebrew=True, prefix_day=True) 'א׳ פסח' >>> taanis_esther = HebrewDate(5783, 12, 13) >>> taanis_esther.holiday(prefix_day=True) 'Taanis Esther'
- isoweekday()
Return the day of the week corresponding to the iso standard.
- Returns:
An integer representing the day of the week where Monday is 1 and and Sunday is 7.
- Return type:
- shabbos()
Return the Shabbos on or following the date.
- Returns:
self if the date is Shabbos or else the following Shabbos as the same date type as called from.
- Return type:
Examples
>>> heb_date = HebrewDate(5781, 3, 29) >>> greg_date = heb_date.to_greg() >>> heb_date.shabbos() HebrewDate(5781, 4, 2) >>> greg_date.shabbos() GregorianDate(2021, 6, 12)
- class pyluach.dates.GregorianDate(year, month, day, jd=None)[source]
Bases:
BaseDate
,CalendarDateMixin
A GregorianDate object represents a Gregorian date (year, month, day).
This is an idealized date with the current Gregorian calendar infinitely extended in both directions.
- Parameters:
Warning
Although B.C.E. dates are allowed, they should be treated as approximations as they may return inconsistent results when converting between date types and using arithmetic and comparison operators!
- strftime(fmt)[source]
Return formatted date.
Wraps
datetime.date.strftime()
method and uses the same format options.
- property jd
Return the corresponding Julian day number.
- Returns:
The Julian day number at midnight.
- Return type:
- classmethod from_pydate(pydate)[source]
Return a GregorianDate instance from a python date object.
- Parameters:
pydate (datetime.date) – A python standard library
datetime.date
instance.- Return type:
- static today()[source]
Return a GregorianDate instance for the current day.
This static method wraps the Python standard library’s date.today() method to get the date from the timestamp.
- Returns:
The current Gregorian date from the computer’s timestamp.
- Return type:
- is_leap()[source]
Return if the date is in a leap year
- Returns:
True if the date is in a leap year, False otherwise.
- Return type:
- to_pydate()[source]
Convert to a standard library date.
- Returns:
The equivalent datetime.date instance.
- Return type:
- dict()
Return the date as a dictionary.
- Returns:
A dictionary in the form
{'year': int, 'month': int, 'day': int}
.- Return type:
- fast_day(hebrew=False)
Return name of fast day of date.
- festival(israel=False, hebrew=False, include_working_days=True, prefix_day=False)
Return name of Jewish festival of date.
This method will return all major and minor religous Jewish holidays not including fast days.
- Parameters:
israel (bool, optional) –
True
if you want the holidays 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
>>> pesach = HebrewDate(2023, 1, 15) >>> pesach.festival(prefix_day=True) '1 Pesach' >>> pesach.festival(hebrew=True, prefix_day=True) 'א׳ פסח' >>> shavuos = HebrewDate(5783, 3, 6) >>> shavuos.festival(israel=True, prefix_day=True) 'Shavuos'
- holiday(israel=False, hebrew=False, prefix_day=False)
Return name of Jewish holiday of the date.
The holidays include the major and minor religious Jewish holidays including fast days.
- Parameters:
israel (bool, optional) –
True
if you want the holidays according to the Israel schedule. Defaults toFalse
.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
>>> pesach = HebrewDate(2023, 1, 15) >>> pesach.holiday(prefix_day=True) '1 Pesach' >>> pesach.holiday(hebrew=True, prefix_day=True) 'א׳ פסח' >>> taanis_esther = HebrewDate(5783, 12, 13) >>> taanis_esther.holiday(prefix_day=True) 'Taanis Esther'
- isoweekday()
Return the day of the week corresponding to the iso standard.
- Returns:
An integer representing the day of the week where Monday is 1 and and Sunday is 7.
- Return type:
- replace(year=None, month=None, day=None)
Return new date with new values for the specified field.
- shabbos()
Return the Shabbos on or following the date.
- Returns:
self if the date is Shabbos or else the following Shabbos as the same date type as called from.
- Return type:
Examples
>>> heb_date = HebrewDate(5781, 3, 29) >>> greg_date = heb_date.to_greg() >>> heb_date.shabbos() HebrewDate(5781, 4, 2) >>> greg_date.shabbos() GregorianDate(2021, 6, 12)
- class pyluach.dates.HebrewDate(year, month, day, jd=None)[source]
Bases:
BaseDate
,CalendarDateMixin
A class for manipulating Hebrew dates.
The following format options are available similar to strftime:
Format
Example
Meaning
%a
Sun
Weekday as locale’s abbreviated name
%A
Sunday
Weekday as locale’s full name
%w
1
Weekday as decimal number 1-7 Sunday-Shabbos
%d
07
Day of the month as a 0-padded 2 digit decimal number
%-d
7
Day of the month as a decimal number
%B
Iyar
Month name transliterated into English
%m
02
Month as a 0-padded 2 digit decimal number
%-m
2
Month as a decimal number
%y
82, 01
Year without century as a zero-padded decimal number
%Y
5782
Year as a decimal number
%*a
א׳
Weekday as a Hebrew numeral
%*A
ראשון
Weekday name in Hebrew
%*d
ז׳, ט״ז
Day of month as Hebrew numeral
%*-d
א, טו
Day of month without gershayim
%*B
אייר
Name of month in Hebrew
%*y
תשפ״ב
Year in Hebrew numerals without the thousands place
%*Y
ה’תשפ״ב
Year in Hebrew numerals with the thousands place
%%
%
A literal ‘%’ character
Example
>>> date = HebrewDate(5783, 1, 15) >>> f'Today is {date:%a - %*-d %*B, %*y}' 'Today is Thu - טו אייר, תשפ"ג'
- Parameters:
- month
The Hebrew month starting with Nissan as 1 (and Tishrei as 7). If there is a second Adar it has a value of 13.
- Type:
- Raises:
ValueError – If the year is less than 1, if the month is less than 1 or greater than the last month, or if the day does not exist in the month a
ValueError
will be raised.
- property jd
Return the corresponding Julian day number.
- Returns:
The Julian day number at midnight.
- Return type:
- static from_pydate(pydate)[source]
Return a HebrewDate from a python date object.
- Parameters:
pydate (datetime.date) – A python standard library
datetime.date
instance- Return type:
- static today()[source]
Return HebrewDate instance for the current day.
This static method wraps the Python standard library’s
date.today()
method to get the date from the timestamp.- Returns:
The current Hebrew date from the computer’s timestamp.
- Return type:
Warning
Pyluach treats Hebrew dates as if they change at midnight. If it’s after nightfall but before midnight, to get the true Hebrew date do
HebrewDate.today() + 1
.
- to_greg()[source]
Convert to a Gregorian date.
- Returns:
The equivalent GregorianDate instance.
- Return type:
- to_pydate()[source]
Convert to a standard library date.
- Returns:
The equivalent datetime.date instance.
- Return type:
- hebrew_day(withgershayim=True)[source]
Return the day of the month in Hebrew letters.
- Parameters:
withgershayim (bool, optional) – Default is
True
which includes a geresh with a single character and gershayim between two characters.- Returns:
The day of the month in Hebrew letters.
- Return type:
Examples
>>> date = HebrewDate(5782, 3, 6) >>> date.hebrew_day() 'ו׳' >>> date.hebrew_day(False) 'ו' >>> HebrewDate(5783, 12, 14).hebrew_day() 'י״ד'
- hebrew_year(thousands=False, withgershayim=True)[source]
Return the year in Hebrew letters.
- Parameters:
- Return type:
- hebrew_date_string(thousands=False)[source]
Return a Hebrew string representation of the date.
The date is in the form
f'{day} {month} {year}'
.- Parameters:
thousands (bool) –
True
to have the thousands include in the year. Default isFalse
.- Return type:
Examples
>>> date = HebrewDate(5781, 9, 25) >>> date.hebrew_date_string() 'כ״ה כסלו תשפ״א' >>> date.hebrew_date_string(True) 'כ״ה כסלו ה׳תשפ״א'
- add(years=0, months=0, days=0, adar1=False, rounding=Rounding.NEXT_DAY)[source]
Add years, months, and days to date.
- Parameters:
years (int, optional) – The number of years to add. Default is 0.
months (int, optional) – The number of months to add. Default is 0.
days (int, optional) – The number of days to add. Default is 0.
adar1 (bool, optional) – True to return a date in Adar Aleph if self is in a regular Adar and after adding the years it’s leap year. Default is
False
which will return the date in Adar Beis.rounding (Rounding, optional) – Choose what to do if self is the 30th day of the month, and there are only 29 days in the destination month.
Rounding.NEXT_DAY
to return the first day of the next month.Rounding.PREVIOUS_DAY
to return the last day of the month.Rounding.EXCEPTION
to raise a ValueError. Default isRounding.NEXT_DAY
.
- Return type:
Note
This method first adds the years. If the starting month is Adar and the destination year has two Adars, it chooses which one based on the adar1 argument, then it adds the months. If the starting day doesn’t exist in that month it adjusts it based on the rounding argument, then it adds the days.
Examples
>>> date = HebrewDate(5783, 11, 30) >>> date.add(months=1) HebrewDate(5783, 1, 1) >>> date.add(months=1, rounding=Rounding.PREVIOUS_DAY) HebrewDate(5783, 12, 29)
- dict()
Return the date as a dictionary.
- Returns:
A dictionary in the form
{'year': int, 'month': int, 'day': int}
.- Return type:
- fast_day(hebrew=False)
Return name of fast day of date.
- festival(israel=False, hebrew=False, include_working_days=True, prefix_day=False)
Return name of Jewish festival of date.
This method will return all major and minor religous Jewish holidays not including fast days.
- Parameters:
israel (bool, optional) –
True
if you want the holidays 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
>>> pesach = HebrewDate(2023, 1, 15) >>> pesach.festival(prefix_day=True) '1 Pesach' >>> pesach.festival(hebrew=True, prefix_day=True) 'א׳ פסח' >>> shavuos = HebrewDate(5783, 3, 6) >>> shavuos.festival(israel=True, prefix_day=True) 'Shavuos'
- holiday(israel=False, hebrew=False, prefix_day=False)
Return name of Jewish holiday of the date.
The holidays include the major and minor religious Jewish holidays including fast days.
- Parameters:
israel (bool, optional) –
True
if you want the holidays according to the Israel schedule. Defaults toFalse
.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
>>> pesach = HebrewDate(2023, 1, 15) >>> pesach.holiday(prefix_day=True) '1 Pesach' >>> pesach.holiday(hebrew=True, prefix_day=True) 'א׳ פסח' >>> taanis_esther = HebrewDate(5783, 12, 13) >>> taanis_esther.holiday(prefix_day=True) 'Taanis Esther'
- isoweekday()
Return the day of the week corresponding to the iso standard.
- Returns:
An integer representing the day of the week where Monday is 1 and and Sunday is 7.
- Return type:
- replace(year=None, month=None, day=None)
Return new date with new values for the specified field.
- shabbos()
Return the Shabbos on or following the date.
- Returns:
self if the date is Shabbos or else the following Shabbos as the same date type as called from.
- Return type:
Examples
>>> heb_date = HebrewDate(5781, 3, 29) >>> greg_date = heb_date.to_greg() >>> heb_date.shabbos() HebrewDate(5781, 4, 2) >>> greg_date.shabbos() GregorianDate(2021, 6, 12)
- subtract(years=0, months=0, days=0, adar1=False, rounding=Rounding.NEXT_DAY)[source]
Subtract years, months, and days from date.
- Parameters:
years (int, optional) – The number of years to subtract. Default is 0.
months (int, optional) – The number of months to subtract. Default is 0.
days (int, optional) – The number of days to subtract. Default is 0.
adar1 (bool, optional) – True to return a date in Adar Aleph if self is in a regular Adar and the destination year is leap year. Default is
False
which will return the date in Adar Beis.rounding (Rounding, optional) – Choose what to do if self is the 30th day of the month, and there are only 29 days in the destination month.
Rounding.NEXT_DAY
to return the first day of the next month.Rounding.PREVIOUS_DAY
to return the last day of the month.Rounding.EXCEPTION
to raise a ValueError. Default isRounding.NEXT_DAY
.
- Return type:
Note
This method first subtracts the years. If the starting month is Adar and the destination year has two Adars, it chooses which one based on the adar1 argument, then it subtracts the months. If the starting day doesn’t exist in that month it adjusts it based on the rounding argument, then it subtracts the days.