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.BaseDate[source]

Bases: abc.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 date1

d2 = date1 - int

New date int days before date1

int = date1 - date2

Integer equal to the absolute value of the difference between date1 and 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 False

date1 >=, <= date2

True if both are True

Any child of BaseDate that implements a jd attribute representing the Julian Day of that date can be compared to and diffed with any other valid date type.

abstract property jd

Return julian day number.

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

int

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

int

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 operated on.

Return type

HebrewDate, GregorianDate, or JulianDay

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)
fast_day(hebrew=False)[source]

Return name of fast day of date.

Parameters

hebrew (bool, optional) – True if you want the fast day name in Hebrew letters. Default is False, which returns the name transliterated into English.

Returns

The name of the fast day or None if the date is not a fast day.

Return type

str or None

festival(israel=False, hebrew=False, include_working_days=True)[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 to False.

  • hebrew (bool, optional) – True if you want the festival name in Hebrew letters. Default is False, 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 is True.

Returns

The name of the festival or None if the given date is not a Jewish festival.

Return type

str or None

holiday(israel=False, hebrew=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 to False.

  • hebrew (bool, optional) – True if you want the holiday name in Hebrew letters. Default is False, which returns the name transliterated into English.

Returns

The name of the holiday or None if the given date is not a Jewish holiday.

Return type

str or None

class pyluach.dates.CalendarDateMixin(year, month, day, jd=None)[source]

Bases: abc.ABC

CalendarDateMixin is a mixin for Hebrew and Gregorian dates.

Parameters
  • year (int) –

  • month (int) –

  • day (int) –

year
Type

int

month
Type

int

day
Type

int

jd

The equivelant Julian day at midnight.

Type

float

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

Dict

class pyluach.dates.JulianDay(day)[source]

Bases: pyluach.dates.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.

day

The Julian Day Number at midnight (as n.5)

Type

float

jd

Alias for day.

Type

float

weekday()[source]

Return weekday of date.

Returns

The weekday with Sunday as 1 through Saturday as 7.

Return type

int

property jd

Return julian day number.

static from_pydate(pydate)[source]

Return a JulianDay from a python date object.

Parameters

pydate (datetime.date) – A python standard library datetime.date instance

Returns

Return type

JulianDay

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

JulianDay

to_greg()[source]

Convert JulianDay to a Gregorian Date.

Returns

The equivalent Gregorian date instance.

Return type

GregorianDate

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

HebrewDate

to_pydate()[source]

Convert to a datetime.date object.

Returns

A standard library datetime.date instance.

Return type

datetime.date

fast_day(hebrew=False)

Return name of fast day of date.

Parameters

hebrew (bool, optional) – True if you want the fast day name in Hebrew letters. Default is False, which returns the name transliterated into English.

Returns

The name of the fast day or None if the date is not a fast day.

Return type

str or None

festival(israel=False, hebrew=False, include_working_days=True)

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 to False.

  • hebrew (bool, optional) – True if you want the festival name in Hebrew letters. Default is False, 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 is True.

Returns

The name of the festival or None if the given date is not a Jewish festival.

Return type

str or None

holiday(israel=False, hebrew=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 to False.

  • hebrew (bool, optional) – True if you want the holiday name in Hebrew letters. Default is False, which returns the name transliterated into English.

Returns

The name of the holiday or None if the given date is not a Jewish holiday.

Return type

str or None

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

int

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 operated on.

Return type

HebrewDate, GregorianDate, or JulianDay

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: pyluach.dates.BaseDate, pyluach.dates.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
  • year (int) –

  • month (int) –

  • day (int) –

  • jd (float, optional) – This parameter should not be assigned manually.

year
Type

int

month
Type

int

day
Type

int

jd

The corresponding Julian Day Number at midnight (as n.5).

Type

float(property)

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!

property jd

Return the corresponding Julian day number.

This property retrieves the corresponding Julian Day as a float if it was passed into the init method or already calculated, and if it wasn’t, it calculates it and saves it for later retrievals and returns it.

Returns

The Julian day number at midnight.

Return type

float

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.

Returns

Return type

GregorianDate

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

GregorianDate

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

bool

to_jd()[source]

Convert to a Julian day.

Returns

The equivalent JulianDay instance.

Return type

JulianDay

to_heb()[source]

Convert to Hebrew date.

Returns

The equivalent HebrewDate instance.

Return type

HebrewDate

to_pydate()[source]

Convert to a standard library date.

Returns

The equivalent datetime.date instance.

Return type

datetime.date

dict()

Return the date as a dictionary.

Returns

A dictionary in the form {'year': int, 'month': int, 'day': int}.

Return type

Dict

fast_day(hebrew=False)

Return name of fast day of date.

Parameters

hebrew (bool, optional) – True if you want the fast day name in Hebrew letters. Default is False, which returns the name transliterated into English.

Returns

The name of the fast day or None if the date is not a fast day.

Return type

str or None

festival(israel=False, hebrew=False, include_working_days=True)

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 to False.

  • hebrew (bool, optional) – True if you want the festival name in Hebrew letters. Default is False, 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 is True.

Returns

The name of the festival or None if the given date is not a Jewish festival.

Return type

str or None

holiday(israel=False, hebrew=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 to False.

  • hebrew (bool, optional) – True if you want the holiday name in Hebrew letters. Default is False, which returns the name transliterated into English.

Returns

The name of the holiday or None if the given date is not a Jewish holiday.

Return type

str or None

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

int

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 operated on.

Return type

HebrewDate, GregorianDate, or JulianDay

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)
tuple()

Return date as tuple.

Returns

A tuple of ints in the form (year, month, day).

Return type

tuple of ints

weekday()

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

int

class pyluach.dates.HebrewDate(year, month, day, jd=None)[source]

Bases: pyluach.dates.BaseDate, pyluach.dates.CalendarDateMixin

A class for manipulating Hebrew dates.

Parameters
  • year (int) – The Hebrew year. If the year is less than 1 it will raise a ValueError.

  • month (int) – The Hebrew month starting with Nissan as 1 (and Tishrei as 7). If there is a second Adar in the year it is represented as 13. A month below 1 or above the last month will raise a ValueError.

  • day (int) – The Hebrew day of the month. An invalid day will raise a ValueError.

  • jd (float, optional) – This parameter should not be assigned manually.

year
Type

int

month

The Hebrew month starting with Nissan as 1 (and Tishrei as 7). If there is a second Adar it is represented as 13.

Type

int

day

The day of the month.

Type

int

property jd

Return the corresponding Julian day number.

This property retrieves the corresponding Julian Day as a float if it was passed into the init method or already calculated, and if it wasn’t, it calculates it, saves it for later retrievals, and returns it.

Returns

The Julian day number at midnight.

Return type

float

static from_pydate(pydate)[source]

Return a HebrewDate from a python date object.

Parameters

pydate (datetime.date) – A python standard library datetime.date instance

Returns

Return type

HebrewDate

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

HebrewDate

Notes

This method coverts the Gregorian date from the time stamp to a Hebrew date, so if it is after nightfall but before midnight you will have to add one day, ie. today = HebrewDate.today() + 1.

to_jd()[source]

Convert to a Julian day.

Returns

The equivalent JulianDay instance.

Return type

JulianDay

to_greg()[source]

Convert to a Gregorian date.

Returns

The equivalent GregorianDate instance.

Return type

GregorianDate

to_pydate()[source]

Convert to a standard library date.

Returns

The equivalent datetime.date instance.

Return type

datetime.date

month_name(hebrew=False)[source]

Return the name of the month.

Parameters

hebrew (bool, optional) – True if the month name should be in Hebrew characters. Default is False which returns the month name transliterated into English.

Returns

Return type

str

hebrew_day()[source]

Return the day of the month in Hebrew letters.

Returns

The day of the month in Hebrew letters. For example ‘א׳’ for 1, ‘ט״ו’ for 15.

Return type

str

hebrew_year(thousands=False)[source]

Return the year in Hebrew letters.

Parameters

thousands (bool) – True to prefix the year with a letter for the thousands place, ie. ‘ה׳תשפ״א’. Default is False.

Returns

Return type

str

dict()

Return the date as a dictionary.

Returns

A dictionary in the form {'year': int, 'month': int, 'day': int}.

Return type

Dict

fast_day(hebrew=False)

Return name of fast day of date.

Parameters

hebrew (bool, optional) – True if you want the fast day name in Hebrew letters. Default is False, which returns the name transliterated into English.

Returns

The name of the fast day or None if the date is not a fast day.

Return type

str or None

festival(israel=False, hebrew=False, include_working_days=True)

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 to False.

  • hebrew (bool, optional) – True if you want the festival name in Hebrew letters. Default is False, 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 is True.

Returns

The name of the festival or None if the given date is not a Jewish festival.

Return type

str or None

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 is False.

Returns

Return type

str

Examples

>>> date = HebrewDate(5781, 9, 25)
>>> date.hebrew_date_string()
'כ״ה כסלו תשפ״א'
>>> date.hebrew_date_string(True)
'כ״ה כסלו ה׳תשפ״א'
holiday(israel=False, hebrew=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 to False.

  • hebrew (bool, optional) – True if you want the holiday name in Hebrew letters. Default is False, which returns the name transliterated into English.

Returns

The name of the holiday or None if the given date is not a Jewish holiday.

Return type

str or None

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

int

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 operated on.

Return type

HebrewDate, GregorianDate, or JulianDay

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)
tuple()

Return date as tuple.

Returns

A tuple of ints in the form (year, month, day).

Return type

tuple of ints

weekday()

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

int