Document behavior when time delta addition falls after end of month

Document potentially surprising behaviour and add tests to cover these cases.

AUTHORS.md

@@ -15,6 +15,7 @@ switch, and thus all their contributions are dual-licensed.
 - Adrien Cossa <cossa@MASKED>
 - Alec Nikolas Reiter <alecreiter@MASKED>
 - Alec Reiter <areiter@MASKED>
+- Aleksei Strizhak <alexei.mifrill.strizhak@MASKED> (gh: @Mifrill)
 - Alex Chamberlain (gh: @alexchamberlain) **D**
 - Alex Verdyan <verdyan@MASKED>
 - Alex Willmer <alex@moreati.org.uk> (gh: @moreati) **R**

changelog.d/1167.doc.rst

@@ -0,0 +1,3 @@
+Added note into docs and tests where relativedelta would return last day of the month
+only if the same day on a different month resolves to a date that doesn't exist.
+Reported by @hawkEye-01 (gh issue #1167). Fixed by @Mifrill (gh pr #1168)

docs/relativedelta.rst

@@ -91,6 +91,15 @@ boundary.
 
 The logic for years is the same, even on leap years.
 
+If the result falls on a day after the last one of the month, the last day of the month is used instead.
+
+.. doctest::
+
+    >>> date(2003,1,30)+relativedelta(months=+1)
+    datetime.date(2003, 2, 28)
+    >>> date(2003,5,31)+relativedelta(months=-1)
+    datetime.date(2003, 4, 30)
+
 .. doctest:: relativedelta
 
     >>> date(2000,2,28)+relativedelta(years=+1)

tests/test_relativedelta.py

@@ -650,6 +650,67 @@ def testHashable(self):
         except:
             self.fail("relativedelta() failed to hash!")
 
+    def testDayOfMonthPlus(self):
+        assert [
+            date(2021, 1, 28) + relativedelta(months=1),
+            date(2021, 2, 27) + relativedelta(months=1),
+            date(2021, 4, 29) + relativedelta(months=1),
+            date(2021, 5, 30) + relativedelta(months=1),
+        ] == [
+            date(2021, 2, 28),
+            date(2021, 3, 27),
+            date(2021, 5, 29),
+            date(2021, 6, 30),
+        ]
+
+    def testLastDayOfMonthPlus(self):
+        assert [
+            date(2021, 1, 31) + relativedelta(months=1),
+            date(2021, 1, 30) + relativedelta(months=1),
+            date(2021, 1, 29) + relativedelta(months=1),
+            date(2021, 1, 28) + relativedelta(months=1),
+            date(2021, 2, 28) + relativedelta(months=1),
+            date(2021, 4, 30) + relativedelta(months=1),
+            date(2021, 5, 31) + relativedelta(months=1),
+        ] == [
+            date(2021, 2, 28),
+            date(2021, 2, 28),
+            date(2021, 2, 28),
+            date(2021, 2, 28),
+            date(2021, 3, 28),
+            date(2021, 5, 30),
+            date(2021, 6, 30),
+        ]
+
+    def testDayOfMonthMinus(self):
+        assert [
+           date(2021, 2, 27) - relativedelta(months=1),
+           date(2021, 3, 30) - relativedelta(months=1),
+           date(2021, 3, 29) - relativedelta(months=1),
+           date(2021, 3, 28) - relativedelta(months=1),
+           date(2021, 5, 30) - relativedelta(months=1),
+           date(2021, 6, 29) - relativedelta(months=1),
+        ] == [
+            date(2021, 1, 27),
+            date(2021, 2, 28),
+            date(2021, 2, 28),
+            date(2021, 2, 28),
+            date(2021, 4, 30),
+            date(2021, 5, 29),
+        ]
+
+    def testLastDayOfMonthMinus(self):
+        assert [
+            date(2021, 2, 28) - relativedelta(months=1),
+            date(2021, 3, 31) - relativedelta(months=1),
+            date(2021, 5, 31) - relativedelta(months=1),
+            date(2021, 6, 30) - relativedelta(months=1),
+        ] == [
+            date(2021, 1, 28),
+            date(2021, 2, 28),
+            date(2021, 4, 30),
+            date(2021, 5, 30),
+        ]
 
 class RelativeDeltaWeeksPropertyGetterTest(unittest.TestCase):
     """Test the weeks property getter"""