# dates module

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

## Contents

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

    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)

    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.

    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

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

  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

  tuple()

    Return date as tuple.

    Returns

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

    Return type

      tuple of ints

  dict()

    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)

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

    Return weekday of date.

    Returns

      The weekday with Sunday as 1 through Saturday as 7.

    Return type

      int

  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

  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

  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

  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)

    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.

    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)

  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)

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

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

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

    Convert to a Julian day.

    Returns

      The equivalent JulianDay instance.

    Return type

      JulianDay

  to_heb()

    Convert to Hebrew date.

    Returns

      The equivalent HebrewDate instance.

    Return type

      HebrewDate

  to_pydate()

    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)

    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.

    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)

  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)

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

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

    Convert to a Julian day.

    Returns

      The equivalent JulianDay instance.

    Return type

      JulianDay

  to_greg()

    Convert to a Gregorian date.

    Returns

      The equivalent GregorianDate instance.

    Return type

      GregorianDate

  to_pydate()

    Convert to a standard library date.

    Returns

      The equivalent datetime.date instance.

    Return type

      datetime.date

  month_name(hebrew=False)

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

    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)

    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)

    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.

    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)

    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