Merge branch 'release/0.4' into develop

Author: rlskoeser

CHANGELOG.md

@@ -1,5 +1,26 @@
 # Change Log
 
+## 0.4
+
+- Undate is now Calendar aware / Calendar explicit; default is Gregorian
+  - New `BaseCalendarConverter` class, with additional methods required for calendar converters
+  - `HebrewDateConverter`: Parsing and calendar conversion for Hebrew/Anno Mundi
+  - `IslamicDateConverter`: Parsing and calendar conversion for Islamic/Hijri
+  - `GregorianDateConverter`: basic Gregorian calendar logic
+  - `undate.Calendar` class to track `Undate` object calendar, and match with calendar converters
+- BaseDateConverter class now includes nested/descendant subclasses when looking
+  for available converters
+- `Undate.to_undate` method to convert supported date objects to `Undate` (`datetime.date`, `datetime.datetime`, and internal `undate.date.Date` class)
+- `UndateInterval` improvements
+  - Can be initialized with `Undate` objects or any type supported by `Undate.to_undate`
+  - New method for contains (`in`), to determine if another interval or date is contained by an interval
+  - New method `intersection` to determine the overlap between two `UndateInterval` objects
+- EDTF parser : fixed day parsing for some unsupported cases
+- Dropped support for Python 3.9
+- Reorganized examples folder to avoid unnecessary nesting
+  - ISMI data has been updated from older JSON data to examples in RDF (turtle)
+
+
 ## 0.3.1
 
 Update readthedocs config for current installation
@@ -14,7 +35,7 @@ Update readthedocs config for current installation
   - Support 5+ digit years with leading Y (thanks to numpy.datetime64)
   - Jupyter notebook demonstrating / validating EDTF support
     - Full support for Level 0 Date and Time Interval (no Date and Time support)
-    - Level 1: 
+    - Level 1:
       - Letter-prefixed calendar year
       - Unspecified digit from the right
       - Partial support for extended interval

README.md

@@ -5,13 +5,13 @@
 **undate** is a python library for working with uncertain or partially known dates.
 
 > [!WARNING]
-> This is pre-alpha software and is **NOT** feature complete! Use with caution.
-> Currently it only supports parsing and formatting dates in ISO8601 format and
-> some portions of EDTF (Extended Date Time Format).
+> This is alpha software and is not yet feature complete! Use with caution and give us feedback.
+> Currently `undate` supports parsing and formatting dates in ISO8601, some 
+portions of EDTF (Extended Date Time Format), and parsing and conversion for dates in Hebrew Anno Mundi and Islamic Hijri calendars
 
 *Undate was initially created as part of a [DH-Tech](https://dh-tech.github.io/) hackathon in November 2022.*
 
----
+* * * 
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.11068867.svg)](https://doi.org/10.5281/zenodo.11068867)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
@@ -167,9 +167,9 @@ Dates are stored with the year, month, day and appropriate precision for the ori
 >>> tammuz4816 = Undate.parse("26 Tammuz 4816", "Hebrew")
 >>> tammuz4816
 <Undate '26 Tammuz 4816 Anno Mundi' 4816-04-26 (Hebrew)>
->>> rajab495 = Undate.parse("Rajab 495", "Hijri")
+>>> rajab495 = Undate.parse("Rajab 495", "Islamic")
 >>> rajab495
-<Undate 'Rajab 495 Hijrī' 0495-07 (Hijri)>
+<Undate 'Rajab 495 Hijrī' 0495-07 (Islamic)>
 >>> y2k = Undate.parse("2001", "EDTF")
 >>> y2k
 <Undate 2001 (Gregorian)>
@@ -178,12 +178,12 @@ Dates are stored with the year, month, day and appropriate precision for the ori
 >>> [str(d.precision) for d in [rajab495, tammuz4816, y2k]]
 ['MONTH', 'DAY', 'YEAR']
 >>> sorted([rajab495, tammuz4816, y2k])
-[<Undate '26 Tammuz 4816 Anno Mundi' 4816-04-26 (Hebrew)>, <Undate 'Rajab 495 Hijrī' 0495-07 (Hijri)>, <Undate 2001 (Gregorian)>]
+[<Undate '26 Tammuz 4816 Anno Mundi' 4816-04-26 (Hebrew)>, <Undate 'Rajab 495 Hijrī' 0495-07 (Islamic)>, <Undate 2001 (Gregorian)>]
 ```
 
 * * * 
 
-For more examples, refer to the [example notebooks](https://github.com/dh-tech/undate-python/tree/main/examples/notebooks/) included in this repository.
+For more examples, refer to the code notebooks included in the [examples](https://github.com/dh-tech/undate-python/tree/main/examples/) in this repository.
 
 ## Documentation
 

pyproject.toml

@@ -29,7 +29,7 @@ keywords = [
     "digital-humanities",
 ]
 classifiers = [
-    "Development Status :: 2 - Pre-Alpha",
+    "Development Status :: 3 - Alpha",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",

src/undate/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.4.0.dev0"
+__version__ = "0.4.0"
 
 from undate.date import DatePrecision
 from undate.undate import Undate, Calendar

src/undate/interval.py

@@ -94,7 +94,9 @@ def duration(self) -> Timedelta:
 
         # if range is open-ended, can't calculate
         if self.earliest is None or self.latest is None:
-            return NotImplemented
+            raise NotImplementedError(
+                "Cannot calculate duration for open-ended interval"
+            )
 
         # if both years are known, subtract end of range from beginning of start
         if self.latest.known_year and self.earliest.known_year:

src/undate/undate.py

@@ -198,8 +198,8 @@ def set_calendar(self, calendar: Union[str, Calendar]):
                 # look for calendar by upper-case name
                 try:
                     calendar = Calendar[calendar.upper()]
-                except KeyError:
-                    raise ValueError(f"Calendar `{calendar}` is not supported")
+                except KeyError as err:
+                    raise ValueError(f"Calendar `{calendar}` is not supported") from err
             self.calendar = calendar
 
     def __str__(self) -> str:
@@ -292,15 +292,13 @@ def __eq__(self, other: object) -> bool:
         # in one format (i.e. X for missing digits).
         # If we support other formats, will need to normalize to common
         # internal format for comparison
-        if looks_equal:
+        if looks_equal and (
             # if any part of either date that is known is _partially_ known,
             # then these dates are not equal
-            if any(
-                [self.is_partially_known(p) for p in self.initial_values.keys()]
-            ) or any(
-                [other.is_partially_known(p) for p in other.initial_values.keys()]
-            ):
-                return False
+            any([self.is_partially_known(p) for p in self.initial_values.keys()])
+            or any([other.is_partially_known(p) for p in other.initial_values.keys()])
+        ):
+            return False
 
         return looks_equal
 
@@ -368,8 +366,9 @@ def to_undate(cls, other: object) -> "Undate":
         """Convert arbitrary object to Undate, if possible. Raises TypeError
         if conversion is not possible.
 
-        Currently suppports:
+        Currently supports:
             - :class:`datetime.date` or :class:`datetime.datetime`
+            - :class:`undate.date.Date`
 
         """
         match other:

tests/test_converters/test_calendars/test_islamic/test_islamic_parser.py

@@ -1,4 +1,6 @@
 import pytest
+from lark.exceptions import LarkError
+
 from undate.converters.calendars.islamic.parser import islamic_parser
 
 
@@ -72,5 +74,5 @@ def test_should_parse(date_string):
 
 @pytest.mark.parametrize("date_string", error_cases)
 def test_should_error(date_string):
-    with pytest.raises(Exception):
+    with pytest.raises(LarkError):
         islamic_parser.parse(date_string)

tests/test_interval.py

@@ -144,7 +144,10 @@ def test_duration(self):
         assert jan_march_duration.days == 2
 
         # duration is not supported for open-ended intervals
-        assert UndateInterval(Undate(2000), None).duration() == NotImplemented
+        with pytest.raises(
+            NotImplementedError, match="Cannot calculate.*open-ended interval"
+        ):
+            assert UndateInterval(Undate(2000), None).duration()
 
         # one year set and the other not currently raises not implemented error
         with pytest.raises(NotImplementedError):