Add support for converting from Hijri calendar to undate and undate interval

.github/workflows/unit_tests.yml

@@ -8,6 +8,8 @@ on:
       - 'undate/**'
       - 'tests/**'
   pull_request:
+    branches:
+      - "**"
 
 env:
   # python version used to calculate and submit code coverage

pyproject.toml

@@ -9,7 +9,7 @@ readme = "README.md"
 license = { text = "Apache-2" }
 requires-python = ">= 3.9"
 dynamic = ["version"]
-dependencies = ["lark", "numpy"]
+dependencies = ["lark[interegular]", "numpy", "convertdate", "strenum; python_version < '3.11'"]
 authors = [
     { name = "Rebecca Sutton Koeser" },
     { name = "Cole Crawford" },

src/undate/converters/base.py

@@ -1,10 +1,11 @@
 """
-:class:`undate.converters.BaseDateConverter` provides a base class for
+:class:`~undate.converters.BaseDateConverter` provides a base class for
 implementing date converters, which can provide support for
-parsing and generating dates in different formats and also converting
-dates between different calendars.
+parsing and generating dates in different formats.
+The converter subclass :class:`undate.converters.BaseCalendarConverter`
+provides additional functionaly needed for calendar conversion.
 
-To add support for a new date format or calendar conversion:
+To add support for a new date converter:
 
 - Create a new file under ``undate/converters/``
     - For converters with sufficient complexity, you may want to create a submodule;
@@ -18,6 +19,26 @@
 The new subclass should be loaded automatically and included in the converters
 returned by :meth:`BaseDateConverter.available_converters`
 
+To add support for a new calendar converter:
+
+- Create a new file under ``undate/converters/calendars/``
+    - For converters with sufficient complexity, you may want to create a submodule;
+      see ``undate.converters.calendars.hijri`` for an example.
+- Extend ``BaseCalendarConverter`` and implement ``parse`` and ``to_string``
+  formatter methods as desired/appropriate for your converter as well as the
+  additional methods for ``max_month``, ``max_day``, and convertion ``to_gregorian``
+  calendar.
+- Import your calendar in ``undate/converters/calendars/__init__.py`` and include in `__all__``
+- Add unit tests for the new calendar logic under ``tests/test_converters/calendars/``
+- Add the new calendar to the ``Calendar`` enum of supported calendars in
+  ``undate/undate.py`` and confirm that the `get_converter` method loads your
+  calendar converter correctly (an existing unit test should cover this).
+- Consider creating a notebook to demonstrate the use of the calendar
+  converter.
+
+Calendar converter subclasses are also automatically loaded and included
+in the list of available converters.
+
 -------------------
 """
 
@@ -90,6 +111,54 @@
         """
         Dictionary of available converters keyed on name.
         """
+        return {c.name: c for c in cls.subclasses()}  # type: ignore
+
+    @classmethod
+    def subclasses(cls) -> list[Type["BaseDateConverter"]]:
+        """
+        List of available converters classes. Includes calendar convert
+        subclasses.
+        """
         # ensure undate converters are imported
         cls.import_converters()
-        return {c.name: c for c in cls.__subclasses__()}  # type: ignore
+
+        # find all direct subclasses, excluding base calendar converter
+        subclasses = cls.__subclasses__()
+        subclasses.remove(BaseCalendarConverter)
+        # add all subclasses of calendar converter base class
+        subclasses.extend(BaseCalendarConverter.__subclasses__())
+        return subclasses
+
+
+class BaseCalendarConverter(BaseDateConverter):
+    """Base class for calendar converters, with additional methods required
+    for calendars."""
+
+    #: Converter name. Subclasses must define a unique name.
+    name: str = "Base Calendar Converter"
+
+    def min_month(self) -> int:
+        """Smallest numeric month for this calendar."""
+        raise NotImplementedError
+
+    def max_month(self, year: int) -> int:
+        """Maximum numeric month for this calendar"""
+        raise NotImplementedError
+
+    def first_month(self) -> int:
+        """first month in this calendar; by default, returns :meth:`min_month`."""
+        return self.min_month()
+
+    def last_month(self, year: int) -> int:
+        """last month in this calendar; by default, returns :meth:`max_month`."""
+        return self.max_month(year)
+
+    def max_day(self, year: int, month: int) -> int:
+        """maximum numeric day for the specified year and month in this calendar"""
+        raise NotImplementedError
+
+    def to_gregorian(self, year, month, day) -> tuple[int, int, int]:
+        """Convert a date for this calendar specified by numeric year, month, and day,
+        into the Gregorian equivalent date. Should return a tuple of year, month, day.
+        """
+        raise NotImplementedError

src/undate/converters/calendars/__init__.py

@@ -0,0 +1,5 @@
+from undate.converters.calendars.gregorian import GregorianDateConverter
+from undate.converters.calendars.hijri import HijriDateConverter
+from undate.converters.calendars.hebrew import HebrewDateConverter
+
+__all__ = ["HijriDateConverter", "GregorianDateConverter", "HebrewDateConverter"]

src/undate/converters/calendars/gregorian.py

@@ -0,0 +1,51 @@
+from calendar import monthrange
+
+from undate.converters.base import BaseCalendarConverter
+
+
+class GregorianDateConverter(BaseCalendarConverter):
+    """
+    Calendar converter class for Gregorian calendar.
+    """
+
+    #: converter name: Gregorian
+    name: str = "Gregorian"
+    #: calendar
+    calendar_name: str = "Gregorian"
+
+    #: known non-leap year
+    NON_LEAP_YEAR: int = 2022
+
+    def min_month(self) -> int:
+        """First month for the Gregorian calendar."""
+        return 1
+
+    def max_month(self, year: int) -> int:
+        """maximum numeric month for the specified year in the Gregorian calendar"""
+        return 12
+
+    def max_day(self, year: int, month: int) -> int:
+        """maximum numeric day for the specified year and month in this calendar"""
+        # if month is known, use that to calculate
+        if month:
+            # if year is known, use it; otherwise use a known non-leap year
+            # (only matters for February)
+            year = year or self.NON_LEAP_YEAR
+
+            # Use monthrange from python builtin calendar module.
+            # returns first day of the month and number of days in the month
+            # for the specified year and month.
+            _, max_day = monthrange(year, month)
+        else:
+            # if year and month are unknown, return maximum possible
+            max_day = 31
+
+        return max_day
+
+    def to_gregorian(self, year, month, day) -> tuple[int, int, int]:
+        """Convert to Gregorian date. This returns the specified by year, month,
+        and day unchanged, but is provided for consistency since all calendar
+        converters need to support conversion to Gregorian calendar for
+        a common point of comparison.
+        """
+        return (year, month, day)

src/undate/converters/calendars/hebrew/__init__.py

@@ -0,0 +1,3 @@
+from undate.converters.calendars.hebrew.converter import HebrewDateConverter
+
+__all__ = ["HebrewDateConverter"]

src/undate/converters/calendars/hebrew/converter.py

@@ -0,0 +1,78 @@
+from typing import Union
+
+from convertdate import hebrew  # type: ignore
+from lark.exceptions import UnexpectedCharacters
+
+from undate.converters.base import BaseCalendarConverter
+from undate.converters.calendars.hebrew.parser import hebrew_parser
+from undate.converters.calendars.hebrew.transformer import HebrewDateTransformer
+from undate.undate import Undate, UndateInterval
+
+
+class HebrewDateConverter(BaseCalendarConverter):
+    """
+    Converter for Hebrew Anno Mundicalendar.
+
+    Support for parsing Anno Mundi dates and converting to Undate and UndateInterval
+    objects in the Gregorian calendar.
+    """
+
+    #: converter name: Hebrew
+    name: str = "Hebrew"
+    calendar_name: str = "Anno Mundi"
+
+    def __init__(self):
+        self.transformer = HebrewDateTransformer()
+
+    def min_month(self) -> int:
+        """Smallest numeric month for this calendar."""
+        return 1
+
+    def max_month(self, year: int) -> int:
+        """Maximum numeric month for this calendar. In Hebrew calendar, this is 12 or 13
+        depending on whether it is a leap year."""
+        return hebrew.year_months(year)
+
+    def first_month(self) -> int:
+        """First month in this calendar. The Hebrew civil year starts in Tishri."""
+        return hebrew.TISHRI
+
+    def last_month(self, year: int) -> int:
+        """Last month in this calendar. Hebrew civil year starts in Tishri,
+        Elul is the month before Tishri."""
+        return hebrew.ELUL
+
+    def max_day(self, year: int, month: int) -> int:
+        """maximum numeric day for the specified year and month in this calendar"""
+        # NOTE: unreleased v2.4.1 of convertdate standardizes month_days to month_length
+        return hebrew.month_days(year, month)
+
+    def to_gregorian(self, year: int, month: int, day: int) -> tuple[int, int, int]:
+        """Convert a Hebrew date, specified by year, month, and day,
+        to the Gregorian equivalent date. Returns a tuple of year, month, day.
+        """
+        return hebrew.to_gregorian(year, month, day)
+
+    def parse(self, value: str) -> Union[Undate, UndateInterval]:
+        """
+        Parse a Hebrew date string and return an :class:`~undate.undate.Undate` or
+        :class:`~undate.undate.UndateInterval`.
+        The Hebrew date string is preserved in the undate label.
+        """
+        if not value:
+            raise ValueError("Parsing empty string is not supported")
+
+        # parse the input string, then transform to undate object
+        try:
+            # parse the string with our Hebrew date parser
+            parsetree = hebrew_parser.parse(value)
+            # transform the parse tree into an undate or undate interval
+            undate_obj = self.transformer.transform(parsetree)
+            # set the original date as a label, with the calendar name
+            undate_obj.label = f"{value} {self.calendar_name}"
+            return undate_obj
+        except UnexpectedCharacters as err:
+            raise ValueError(f"Could not parse '{value}' as a Hebrew date") from err
+
+    # do we need to support conversion the other direction?
+    # i.e., generate a Hebrew date from an abitrary undate or undate interval?

src/undate/converters/calendars/hebrew/hebrew.lark

@@ -0,0 +1,56 @@
+%import common.WS
+%ignore WS
+
+// only support day month year format for now
+// parser requires numeric day and year to be distinguished based on order
+hebrew_date: day month year | month year | year
+
+// TODO: handle date ranges?
+
+// TODO: add support for qualifiers?
+// PGP dates use qualifiers like "first decade of" (for beginning of month)
+// "first third of", seasons (can look for more examples)
+
+// Hebrew calendar starts with year 1  in 3761 BCE
+year: /\d+/
+
+// months
+month: month_1
+     | month_2
+ 	 | month_3
+ 	 | month_4
+ 	 | month_5
+ 	 | month_6
+ 	 | month_7
+ 	 | month_8
+ 	 | month_9
+ 	 | month_10
+  	 | month_11
+      | month_12
+      | month_13      
+// months have 29 or 30 days; we do not expect leading zeroes
+day: /[1-9]/ | /[12][0-9]/ | /30/
+
+// months, in order; from convertdate list
+// with variants from Princeton Geniza Project
+// support matching with and without accents
+month_1: "Nisan"
+// Iyar or Iyyar
+month_2: /Iyy?ar/
+month_3: "Sivan"
+month_4: "Tammuz"
+month_5: "Av"
+month_6: "Elul"
+// Tishrei or Tishri
+month_7: /Tishre?i/
+month_8: "Heshvan"
+month_9: "Kislev"
+// Tevet or Teveth
+month_10: /[ṬT]eveth?/
+month_11: "Shevat"
+// Adar I or Adar
+month_12: /Adar( I)?/
+// Adar II or Adar Bet
+month_13: /Adar (II|Bet)/
+
+

src/undate/converters/calendars/hebrew/parser.py

@@ -0,0 +1,9 @@
+import pathlib
+
+from lark import Lark
+
+grammar_path = pathlib.Path(__file__).parent / "hebrew.lark"
+
+with open(grammar_path) as grammar:
+    # NOTE: LALR parser is faster but can't be used to ambiguity between years and dates
+    hebrew_parser = Lark(grammar.read(), start="hebrew_date", strict=True)

src/undate/converters/calendars/hebrew/transformer.py

@@ -0,0 +1,40 @@
+from lark import Transformer, Tree
+
+from undate.undate import Undate, Calendar
+
+
+class HebrewUndate(Undate):
+    """Undate convience subclass; sets default calendar to Hebrew."""
+
+    calendar = Calendar.HEBREW
+
+
+class HebrewDateTransformer(Transformer):
+    """Transform a Hebrew date parse tree and return an Undate or
+    UndateInterval."""
+
+    def hebrew_date(self, items):
+        parts = {}
+        for child in items:
+            if child.data in ["year", "month", "day"]:
+                # in each case we expect one integer value;
+                # anonymous tokens convert to their value and cast as int
+                value = int(child.children[0])
+                parts[str(child.data)] = value
+
+        # initialize and return an undate with islamic year, month, day and
+        # islamic calendar
+        return HebrewUndate(**parts)
+
+    # year translation is not needed since we want a tree with name year
+    # this is equivalent to a no-op
+    # def year(self, items):
+    #     return Tree(data="year", children=[items[0]])
+
+    def month(self, items):
+        # month has a nested tree for the rule and the value
+        # the name of the rule (month_1, month_2, etc) gives us the
+        # number of the month needed for converting the date
+        tree = items[0]
+        month_n = tree.data.split("_")[-1]
+        return Tree(data="month", children=[month_n])

src/undate/converters/calendars/hijri/__init__.py

@@ -0,0 +1,3 @@
+from undate.converters.calendars.hijri.converter import HijriDateConverter
+
+__all__ = ["HijriDateConverter"]