Add next_anniversary functions to Date and DateTime

Author: StephenBrown2

docs/docs/comparison.md

@@ -67,11 +67,16 @@ the `now()` is created in the same timezone as the instance.
 >>> birthday = pendulum.datetime(2014, 2, 23)
 >>> past_birthday = pendulum.now().subtract(years=50)
 
->>> born.is_birthday(not_birthday)
+>>> born.is_anniversary(not_birthday)
 False
->>> born.is_birthday(birthday)
+>>> born.is_anniversary(birthday)
 True
->>> past_birthday.is_birthday()
+>>> past_birthday.is_anniversary()
 # Compares to now by default
 True
+>>> born.next_anniversary()
+# Compares to now by default
+DateTime(2021, 4, 23, 0, 0, 0, tzinfo=Timezone('UTC'))
+>>> born.next_anniversary(not_birthday)
+DateTime(2015, 4, 23, 0, 0, 0, tzinfo=Timezone('UTC'))
 ```

pendulum/date.py

@@ -217,6 +217,20 @@ def is_anniversary(self, dt=None):
     # the old name can be completely replaced with the new in one of the future versions
     is_birthday = is_anniversary
 
+    def next_anniversary(self, dt=None):
+        """
+        Return the next anniversary date, either from today, or the given date
+
+        :rtype: Date
+        """
+        if dt is None:
+            dt = Date.today()
+
+        years = dt.year - self.year
+        this_year = self.add(years=years)
+
+        return this_year if this_year.is_future() else self.add(years=years + 1)
+
     # ADDITIONS AND SUBSTRACTIONS
 
     def add(self, years=0, months=0, weeks=0, days=0):

pendulum/datetime.py

@@ -592,6 +592,20 @@ def is_anniversary(self, dt=None):
     # the old name can be completely replaced with the new in one of the future versions
     is_birthday = is_anniversary
 
+    def next_anniversary(self, dt=None):
+        """
+        Return the next anniversary datetime, either from today, or the given datetime
+
+        :rtype: DateTime
+        """
+        if dt is None:
+            dt = self.now(self.tz)
+
+        years = dt.year - self.year
+        this_year = self.add(years=years)
+
+        return this_year if this_year.is_future() else self.add(years=years + 1)
+
     # ADDITIONS AND SUBSTRACTIONS
 
     def add(

tests/date/test_comparison.py

@@ -169,6 +169,17 @@ def test_is_birthday():  # backward compatibility
     assert d3.is_birthday(d1)
 
 
+def test_next_anniversary():
+    start = pendulum.Date(1987, 6, 23)
+    leap_start = pendulum.Date(1988, 2, 29)
+
+    assert start.next_anniversary() == pendulum.Date(2020, 6, 23)
+    assert leap_start.next_anniversary() == pendulum.Date(2021, 2, 28)
+    next_year = pendulum.Date(2021, 1, 1)
+    assert start.next_anniversary(dt=next_year) == pendulum.Date(2021, 6, 23)
+    assert leap_start.next_anniversary(dt=next_year) == pendulum.Date(2021, 2, 28)
+
+
 def test_closest():
     instance = pendulum.Date(2015, 5, 28)
     dt1 = pendulum.Date(2015, 5, 27)

tests/datetime/test_comparison.py

@@ -271,6 +271,17 @@ def test_is_birthday():  # backward compatibility
     assert d3.is_birthday(d1)
 
 
+def test_next_anniversary():
+    start = pendulum.datetime(1987, 6, 23)
+    leap_start = pendulum.datetime(1988, 2, 29)
+
+    assert start.next_anniversary() == pendulum.datetime(2020, 6, 23)
+    assert leap_start.next_anniversary() == pendulum.datetime(2021, 2, 28)
+    next_year = pendulum.datetime(2021, 1, 1)
+    assert start.next_anniversary(dt=next_year) == pendulum.datetime(2021, 6, 23)
+    assert leap_start.next_anniversary(dt=next_year) == pendulum.datetime(2021, 2, 28)
+
+
 def test_closest():
     instance = pendulum.datetime(2015, 5, 28, 12, 0, 0)
     dt1 = pendulum.datetime(2015, 5, 28, 11, 0, 0)