# 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`

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

    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)

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

    Return the date as a dictionary.

    Returns: | A dictionary in the form `{'year': int, 'month': int, 'day': int}`.
    Return type: | Dict

  `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.``GregorianDate`(year, month, day, jd=None)

  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)

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

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

    Convert to Hebrew date.

    Returns: | The equivalent HebrewDate instance.
    Return type: | HebrewDate

  `to_jd`()

    Convert to a Julian day.

    Returns: | The equivalent JulianDay instance.
    Return type: | JulianDay

  `to_pydate`()

    Convert to a standard library date.

    Returns: | The equivalent datetime.date instance.
    Return type: | datetime.date

  static `today`()

    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)

  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)

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

    Convert to a Gregorian date.

    Returns: | The equivalent GregorianDate instance.
    Return type: | GregorianDate

  `to_jd`()

    Convert to a Julian day.

    Returns: | The equivalent JulianDay instance.
    Return type: | JulianDay

  `to_pydate`()

    Convert to a standard library date.

    Returns: | The equivalent datetime.date instance.
    Return type: | datetime.date

  static `today`()

    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)

  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)

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

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

    Convert to a Hebrew date.

    Returns: | The equivalent Hebrew date instance.
    Return type: | HebrewDate

  `to_pydate`()

    Convert to a datetime.date object.

    Returns: | A standard library `datetime.date` instance.
    Return type: | datetime.date

  static `today`()

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

    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)

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

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

    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)

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

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

    Yield integer for each day of the year.

    Yields: | int – An integer beginning with 1 representing the next day of the year.

  `itermonths`()

    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)

  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)

  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)

  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)

  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)

  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