pyluach package

Pyluach is a Python package for manipulating Hebrew calendar dates and Hebrew-Gregorian conversions.

Submodules

pyluach.dates module

The dates module implements classes for representing and manipulating several date types.

Classes

  • BaseDate
  • CalendarDateMixin
  • JulianDay
  • GregorianDate
  • HebrewDate

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: object

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.

shabbos()[source]

Return the Shabbos on or following the date.

Returns:Self if it’s Shabbos or else the following Shabbos as the same date type as operated on.
Return type:Date
class pyluach.dates.CalendarDateMixin(year, month, day, jd=None)[source]

Bases: object

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
dict()[source]

Return the date as a dictionary.

Returns:A dictionary in the form {'year': int, 'month': int, 'day': int}.
Return type:Dict
tuple()[source]

Return date as tuple.

Returns:A tuple of ints in the form (year, month, day).
Return type:tuple of ints
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
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!

dict()

Return the date as a dictionary.

Returns:A dictionary in the form {'year': int, 'month': int, 'day': int}.
Return type:Dict
static 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
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
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
shabbos()

Return the Shabbos on or following the date.

Returns:Self if it’s Shabbos or else the following Shabbos as the same date type as operated on.
Return type:Date
to_heb()[source]

Convert to Hebrew date.

Returns:The equivalent HebrewDate instance.
Return type:HebrewDate
to_jd()[source]

Convert to a Julian day.

Returns:The equivalent JulianDay instance.
Return type:JulianDay
to_pydate()[source]

Convert to a standard library date.

Returns:The equivalent datetime.date instance.
Return type:datetime.date
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
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
dict()

Return the date as a dictionary.

Returns:A dictionary in the form {'year': int, 'month': int, 'day': int}.
Return type:Dict
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
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
shabbos()

Return the Shabbos on or following the date.

Returns:Self if it’s Shabbos or else the following Shabbos as the same date type as operated on.
Return type:Date
to_greg()[source]

Convert to a Gregorian date.

Returns:The equivalent GregorianDate instance.
Return type:GregorianDate
to_jd()[source]

Convert to a Julian day.

Returns:The equivalent JulianDay instance.
Return type:JulianDay
to_pydate()[source]

Convert to a standard library date.

Returns:The equivalent datetime.date instance.
Return type:datetime.date
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

Note

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.

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.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
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
shabbos()

Return the Shabbos on or following the date.

Returns:Self if it’s Shabbos or else the following Shabbos as the same date type as operated on.
Return type:Date
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
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
weekday()[source]

Return weekday of date.

Returns:The weekday with Sunday as 1 through Saturday as 7.
Return type:int

pyluach.hebrewcal module

class pyluach.hebrewcal.Month(year, month)[source]

Bases: object

A Month object represents a month of the Hebrew calendar.

Parameters:
  • year (int) –
  • month (int) – The month as an integer starting with 7 for Tishrei through 13 if necessary for Adar Sheni and then 1-6 for Nissan - Elul.
year

The Hebrew year.

Type:int
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:int
name

The name of the month.

Type:str
iterdates()[source]

Return iterator that yields an instance of HebrewDate.

Yields:HebrewDate – The next Hebrew Date of the year starting the first day of Tishrei through the last day of Ellul.
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:int
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.
Parameters:year (int) – A Hebrew year.
year

The hebrew year.

Type:int
leap

True if the year is a leap year else false.

Type:bool
iterdates()[source]

Yield HebrewDate instance for each day of the year.

Yields:HebrewDate – The next date of the Hebrew calendar year starting with the first of Tishrei.
iterdays()[source]

Yield integer for each day of the year.

Yields:int – An integer beginning with 1 representing the next day of the year.
itermonths()[source]

Yield Month instance for each month of the year.

Yields:Month – The next month in the Hebrew calendar year as a luachcal.hebrewcal.Month instance beginning with Tishrei and ending with Elul.
pyluach.hebrewcal.holiday(date, israel=False)[source]

Return Jewish holiday of given date.

The holidays include the major and minor religious Jewish holidays including fast days.

Parameters:
  • date (HebrewDate, GregorianDate, or JulianDay) – Any date that implements a to_heb() method which returns a HebrewDate can be used.
  • israel (boolian, optional) – True if you want the holidays according to the israel schedule. Defaults to False.
Returns:

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

Return type:

str or None

pyluach.parshios module

This module has functions to find the weekly parasha for a given Shabbos.

pyluach.parshios.PARSHIOS

A list of all of the parsha names starting with Beraishis through V’zos Habrocha.

Type:list of str

Notes

The algorithm is based on Dr. Irv Bromberg’s, University of Toronto at http://individual.utoronto.ca/kalendis/hebrew/parshah.htm

All parsha names are transliterated into the American Ashkenazik pronunciation.

pyluach.parshios.getparsha(date, israel=False)[source]

Return the parsha for a given date.

Returns the parsha for the Shabbos on or following the given date.

Parameters:
  • date (HebrewDate, GregorianDate, or JulianDay) – This date does not have to be a Shabbos.
  • israel (bool, optional) – True if you want the parsha according to the Israel schedule (with only one day of Yom Tov). Defaults to False.
Returns:

A list of the numbers of the parshios for the Shabbos of the given date, beginning with 0 for Beraishis, or None if the Shabbos doesn’t have a parsha (i.e. it’s on Yom Tov).

Return type:

list of ints or None

pyluach.parshios.getparsha_string(date, israel=False)[source]

Return the parsha as a string for the given date.

This function wraps getparsha returning a the parsha name transliterated into English.

Parameters:
  • date (HebrewDate, GregorianDate, or JulianDay) – This date does not have to be a Shabbos.
  • israel (bool, optional) – True if you want the parsha according to the Israel schedule (with only one day of Yom Tov). Defaults to False.
Returns:

The name of the parsha seperated by a comma and space if it is a double parsha or None if there is no parsha that Shabbos (ie. it’s yom tov).

Return type:

str or None

pyluach.parshios.iterparshios(year, israel=False)[source]

Generate all the parshios in the year.

Parameters:
  • year (int) – The Hebrew year to get the parshios for.
  • israel (bool, optional) – True if you want the parsha according to the Israel schedule (with only one day of Yom Tov). Defaults to False
Yields:

list of ints or None – A list of the numbers of the parshios for the next Shabbos in the given year. Yields None for a Shabbos that doesn’t have its own parsha (i.e. it occurs on a yom tov).

pyluach.parshios.parshatable(year, israel=False)[source]

Return a table of all the Shabbosos in the year

Parameters:
  • year (int) – The Hebrew year to get the parshios for.
  • israel (bool, optional) – True if you want the parshios according to the Israel schedule (with only one day of Yom Tov). Defaults to False.
Returns:

An ordered dictionary with the date of each Shabbos as the key mapped to the parsha as a list of ints, or None for a Shabbos with no parsha.

Return type:

OrderedDict