Add comparison checks for fully unknown years

Author: rlskoeser

src/undate/undate.py

@@ -335,6 +335,10 @@ def __eq__(self, other: object) -> bool:
     def __lt__(self, other: object) -> bool:
         other = self._comparison_type(other)
 
+        # if either date has a completely unknown year, then we can't compare
+        if self.unknown_year or other.unknown_year:
+            return False
+
         # if this date ends before the other date starts,
         # return true (this date is earlier, so it is less)
         if self.latest < other.earliest:
@@ -370,9 +374,20 @@ def __gt__(self, other: object) -> bool:
         # define gt ourselves so we can support > comparison with datetime.date,
         # but rely on existing less than implementation.
         # strictly greater than must rule out equals
+
+        # if either date has a completely unknown year, then we can't compare
+        # NOTE: this means that gt and lt will both be false when comparing
+        # with a date with an unknown year...
+        if self.unknown_year or isinstance(other, Undate) and other.unknown_year:
+            return False
+
         return not (self < other or self == other)
 
     def __le__(self, other: object) -> bool:
+        # if either date has a completely unknown year, then we can't compare
+        if self.unknown_year or isinstance(other, Undate) and other.unknown_year:
+            return False
+
         return self == other or self < other
 
     def __contains__(self, other: object) -> bool:
@@ -383,6 +398,10 @@ def __contains__(self, other: object) -> bool:
         if self == other:
             return False
 
+        # if either date has a completely unknown year, then we can't determine
+        if self.unknown_year or other.unknown_year:
+            return False
+
         return all(
             [
                 self.earliest <= other.earliest,
@@ -419,19 +438,30 @@ def to_undate(cls, other: object) -> "Undate":
 
     @property
     def known_year(self) -> bool:
+        "year is fully known"
         return self.is_known("year")
 
+    @property
+    def unknown_year(self) -> bool:
+        "year is completely unknown"
+        return self.is_unknown("year")
+
     def is_known(self, part: str) -> bool:
-        """Check if a part of the date (year, month, day) is known.
+        """Check if a part of the date (year, month, day) is fully known.
         Returns False if unknown or only partially known."""
         # TODO: should we use constants or enum for values?
 
         # if we have an integer, then consider the date known
         # if we have a string, then it is only partially known; return false
         return isinstance(self.initial_values[part], int)
 
+    def is_unknown(self, part: str) -> bool:
+        """Check if a part of the date (year, month, day) is completely unknown."""
+        return self.initial_values.get(part) is None
+
     def is_partially_known(self, part: str) -> bool:
-        # TODO: should XX / XXXX really be considered partially known? other code seems to assume this, so we'll preserve the behavior
+        # TODO: should XX / XXXX really be considered partially known?
+        # other code seems to assume this, so we'll preserve the behavior
         return isinstance(self.initial_values[part], str)
         # and self.initial_values[part].replace(self.MISSING_DIGIT, "") != ""
 

tests/test_undate.py

@@ -310,6 +310,19 @@ def test_lte(self, earlier, later):
         assert earlier <= later
         assert later >= earlier
 
+    def test_gt_lt_unknown_years(self):
+        # unknown years cannot be compared on either side...
+        year100 = Undate(100)
+        some_january = Undate(month=1)
+        assert not year100 < some_january
+        assert not year100 <= some_january
+        assert not year100 > some_january
+        assert not year100 >= some_january
+        assert not some_january < year100
+        assert not some_january <= year100
+        assert not some_january > year100
+        assert not some_january >= year100
+
     def test_lt_notimplemented(self):
         # how to compare mixed precision where dates overlap?
         # if the second date falls *within* earliest/latest,
@@ -362,6 +375,9 @@ def test_contains(self, date1, date2):
         (Undate(1980, "XX"), Undate(1980, "XX")),
         # - partially unknown month to unknown month
         (Undate(1801, "1X"), Undate(1801, "XX")),
+        # fully unknown year
+        (Undate(month=6, day=1), Undate(2022)),
+        (Undate(1950), Undate(day=31)),
     ]
 
     @pytest.mark.parametrize("date1,date2", testdata_not_contains)
@@ -500,6 +516,7 @@ def test_partiallyknownyear_duration(self):
         assert Undate("XXX", calendar="Hebrew").duration().days == UnInt(353, 385)
 
     def test_known_year(self):
+        # known OR partially known
         assert Undate(2022).known_year is True
         assert Undate(month=2, day=5).known_year is False
         # partially known year is not known
@@ -521,6 +538,34 @@ def test_is_known_day(self):
         assert Undate(month=1, day="X5").is_known("day") is False
         assert Undate(month=1, day="XX").is_known("day") is False
 
+    def test_unknown_year(self):
+        # fully unknown year
+        assert Undate(month=2, day=5).unknown_year is True
+        # known or partially known years = all false for unknown
+        assert Undate(2022).unknown_year is False
+        # partially known year is not unknown
+        assert Undate("19XX").unknown_year is False
+        # fully known string year should be known
+        assert Undate("1900").unknown_year is False
+
+    def test_is_unknown_month(self):
+        # fully unknown month
+        assert Undate(2022).is_unknown("month") is True
+        assert Undate(day=10).is_unknown("month") is True
+        assert Undate(2022, 2).is_unknown("month") is False
+        assert Undate(2022, "5").is_unknown("month") is False
+        assert Undate(2022, "1X").is_unknown("month") is False
+        assert Undate(2022, "XX").is_unknown("month") is False
+
+    def test_is_unknown_day(self):
+        # fully unknown day
+        assert Undate(1984).is_unknown("day") is True
+        assert Undate(month=5).is_unknown("day") is True
+        assert Undate(month=1, day=3).is_unknown("day") is False
+        assert Undate(month=1, day="5").is_unknown("day") is False
+        assert Undate(month=1, day="X5").is_unknown("day") is False
+        assert Undate(month=1, day="XX").is_unknown("day") is False
+
     def test_parse(self):
         assert Undate.parse("1984", "EDTF") == Undate(1984)
         assert Undate.parse("1984-04", "EDTF") == Undate(1984, 4)