feat: add future_date, future_datetime, past_date, past_datetime methods

Add methods to generate dates and datetimes relative to the current time:
- future_date(days=30): Random date between tomorrow and N days ahead
- future_datetime(days=30, timezone=None): Random datetime from now+1s to N days ahead
- past_date(days=30): Random date between N days ago and yesterday
- past_datetime(days=30, timezone=None): Random datetime from N days ago to now-1s

Closes #775

Author: rodrigo.nogueira

CHANGELOG.rst

@@ -1,8 +1,9 @@
 Version 19.1.0
 --------------
 
-- Added support for E.164 phone number formatting to the ``Person`` provider’s ``phone_number()`` method.
+- Added support for E.164 phone number formatting to the ``Person`` provider's ``phone_number()`` method.
 - Added ``secondary_address()`` method to the ``Address`` provider.
+- Add ``future_date()``, ``future_datetime()``, ``past_date()`` and ``past_datetime()`` methods for the ``Datetime`` provider. See (`#775 <https://github.com/lk-geimfari/mimesis/issues/775>`_).
 
 Version 19.0.0
 --------------
@@ -15,6 +16,8 @@ Version 19.0.0
 - Add ``SchemaBuilder`` for generating relational data.
 - Add ``ip_v4_cidr()``, ``ip_v6_cidr()`` and ``cloud_region()`` methods for the ``Internet`` provider.
 
+
+
 Version 18.0.0
 --------------
 

mimesis/providers/date.py

@@ -289,6 +289,72 @@ def timestamp(
         else:
             return int(stamp.timestamp())
 
+    def future_date(self, days: int = 30) -> Date:
+        """Generates a random date in the future.
+
+        :param days: Maximum number of days in the future.
+        :return: A date object between tomorrow and `days` from now.
+        """
+        today = date.today()
+        start_date = today + timedelta(days=1)
+        end_date = today + timedelta(days=days)
+        delta_days = self.random.randint(0, (end_date - start_date).days)
+        return start_date + timedelta(days=delta_days)
+
+    def future_datetime(self, days: int = 30, timezone: str | None = None) -> DateTime:
+        """Generates a random datetime in the future.
+
+        :param days: Maximum number of days in the future.
+        :param timezone: Set custom timezone (pytz required).
+        :return: A datetime object between now and `days` from now.
+        """
+        now = datetime.now()
+        start_dt = now + timedelta(seconds=1)
+        end_dt = now + timedelta(days=days)
+        delta_seconds = self.random.randint(0, int((end_dt - start_dt).total_seconds()))
+        result = start_dt + timedelta(seconds=delta_seconds)
+
+        if timezone:
+            if not pytz:
+                raise ImportError("Timezones are supported only with pytz")
+            tz = pytz.timezone(timezone)
+            result = tz.localize(result)
+
+        return result
+
+    def past_date(self, days: int = 30) -> Date:
+        """Generates a random date in the past.
+
+        :param days: Maximum number of days in the past.
+        :return: A date object between `days` ago and yesterday.
+        """
+        today = date.today()
+        start_date = today - timedelta(days=days)
+        end_date = today - timedelta(days=1)
+        delta_days = self.random.randint(0, (end_date - start_date).days)
+        return start_date + timedelta(days=delta_days)
+
+    def past_datetime(self, days: int = 30, timezone: str | None = None) -> DateTime:
+        """Generates a random datetime in the past.
+
+        :param days: Maximum number of days in the past.
+        :param timezone: Set custom timezone (pytz required).
+        :return: A datetime object between `days` ago and now.
+        """
+        now = datetime.now()
+        start_dt = now - timedelta(days=days)
+        end_dt = now - timedelta(seconds=1)
+        delta_seconds = self.random.randint(0, int((end_dt - start_dt).total_seconds()))
+        result = start_dt + timedelta(seconds=delta_seconds)
+
+        if timezone:
+            if not pytz:
+                raise ImportError("Timezones are supported only with pytz")
+            tz = pytz.timezone(timezone)
+            result = tz.localize(result)
+
+        return result
+
     def duration(
         self,
         min_duration: int = 1,

tests/test_providers/test_localized/test_date.py

@@ -258,6 +258,56 @@ def test_duration_error(self, _datetime):
                 duration_unit=DurationUnit.WEEKS,
             )
 
+    @pytest.mark.parametrize("days", [7, 30, 90])
+    def test_future_date(self, _datetime, days):
+        today = datetime.date.today()
+        result = _datetime.future_date(days=days)
+        assert isinstance(result, datetime.date)
+        assert result > today
+        assert result <= today + datetime.timedelta(days=days)
+
+    @pytest.mark.parametrize(
+        "days, timezone",
+        [
+            (30, None),
+            (30, "Europe/Paris"),
+        ],
+    )
+    def test_future_datetime(self, _datetime, days, timezone):
+        now = datetime.datetime.now()
+        result = _datetime.future_datetime(days=days, timezone=timezone)
+        assert isinstance(result, datetime.datetime)
+        assert result.replace(tzinfo=None) > now
+        if timezone:
+            assert result.tzinfo is not None
+        else:
+            assert result.tzinfo is None
+
+    @pytest.mark.parametrize("days", [7, 30, 90])
+    def test_past_date(self, _datetime, days):
+        today = datetime.date.today()
+        result = _datetime.past_date(days=days)
+        assert isinstance(result, datetime.date)
+        assert result < today
+        assert result >= today - datetime.timedelta(days=days)
+
+    @pytest.mark.parametrize(
+        "days, timezone",
+        [
+            (30, None),
+            (30, "Europe/Paris"),
+        ],
+    )
+    def test_past_datetime(self, _datetime, days, timezone):
+        now = datetime.datetime.now()
+        result = _datetime.past_datetime(days=days, timezone=timezone)
+        assert isinstance(result, datetime.datetime)
+        assert result.replace(tzinfo=None) < now
+        if timezone:
+            assert result.tzinfo is not None
+        else:
+            assert result.tzinfo is None
+
 
 class TestSeededDatetime:
     @pytest.fixture
@@ -338,3 +388,21 @@ def test_duratioh(self, d1, d2):
         assert d1.duration(10, 20, DurationUnit.WEEKS) == d2.duration(
             10, 20, DurationUnit.WEEKS
         )
+
+    def test_future_date(self, d1, d2):
+        assert d1.future_date() == d2.future_date()
+        assert d1.future_date(days=7) == d2.future_date(days=7)
+
+    def test_future_datetime(self, d1, d2):
+        r1 = d1.future_datetime().replace(microsecond=0)
+        r2 = d2.future_datetime().replace(microsecond=0)
+        assert r1 == r2
+
+    def test_past_date(self, d1, d2):
+        assert d1.past_date() == d2.past_date()
+        assert d1.past_date(days=7) == d2.past_date(days=7)
+
+    def test_past_datetime(self, d1, d2):
+        r1 = d1.past_datetime().replace(microsecond=0)
+        r2 = d2.past_datetime().replace(microsecond=0)
+        assert r1 == r2