Add duration method for Datetime provider

Author: lk-geimfari

CHANGELOG.rst

@@ -1,3 +1,9 @@
+Version 17.0.0
+--------------
+
+- Added ``mimesis.enums.DurationUnit`` enum.
+- Added ``.duration()`` method for ``Datetime`` provider to generate random durations.
+
 Version 16.0.0
 --------------
 

docs/conf.py

@@ -70,9 +70,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = "16.0"
+version = "17.0"
 # The full version, including alpha/beta/rc tags.
-release = "16.0.0"
+release = "17.0.0"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

mimesis/__init__.py

@@ -16,6 +16,7 @@
     CountryCode,
     DocumentFile,
     DSNType,
+    DurationUnit,
     EANFormat,
     EmojyCategory,
     FileType,
@@ -107,6 +108,7 @@
     "Algorithm",
     "AudioFile",
     "CardType",
+    "DurationUnit",
     "CompressedFile",
     "CountryCode",
     "DocumentFile",
@@ -146,7 +148,7 @@
     "__license__",
 ]
 
-__version__ = "16.0.0"
+__version__ = "17.0.0"
 __title__ = "mimesis"
 __description__ = "Mimesis: Fake Data Generator."
 __url__ = "https://github.com/lk-geimfari/mimesis"

mimesis/enums.py

@@ -13,6 +13,21 @@
 from enum import Enum, auto
 
 
+class DurationUnit(Enum):
+    """Provides duration units.
+
+    An argument for :meth:`~mimesis.Datetime.duration()`.
+    """
+
+    WEEKS = "weeks"
+    DAYS = "days"
+    HOURS = "hours"
+    MINUTES = "minutes"
+    SECONDS = "seconds"
+    MILLISECONDS = "milliseconds"
+    MICROSECONDS = "microseconds"
+
+
 class Locale(Enum):
     """This class provides access to the supported locales from one place.
 

mimesis/providers/date.py

@@ -6,7 +6,7 @@
 
 from mimesis.compat import pytz
 from mimesis.datasets import GMT_OFFSETS, ROMAN_NUMS, TIMEZONES
-from mimesis.enums import TimestampFormat, TimezoneRegion
+from mimesis.enums import DurationUnit, TimestampFormat, TimezoneRegion
 from mimesis.providers.base import BaseDataProvider
 from mimesis.types import Date, DateTime, Time
 
@@ -288,3 +288,33 @@ def timestamp(
             return stamp.isoformat()
         else:
             return int(stamp.timestamp())
+
+    def duration(
+        self,
+        min_duration: int = 1,
+        max_duration: int = 10,
+        duration_unit: DurationUnit | None = DurationUnit.MINUTES,
+    ) -> timedelta:
+        """Generate a random duration.
+
+        The default duration unit is Duration.MINUTES.
+
+        When the duration unit is None, then random
+        duration from DurationUnit is chosen.
+
+        A timedelta object represents a duration, the difference
+        between two datetime or date instances.
+
+        :param min_duration: Minimum duration.
+        :param max_duration: Maximum duration.
+        :param duration_unit: Duration unit.
+        :return: Duration as timedelta.
+        """
+        if min_duration > max_duration:
+            raise ValueError("min_duration must be less or equal to max_duration")
+
+        if not isinstance(min_duration, int) or not isinstance(max_duration, int):
+            raise TypeError("min_duration and max_duration must be integers")
+
+        unit = self.validate_enum(duration_unit, DurationUnit)
+        return timedelta(**{unit: self.random.randint(min_duration, max_duration)})

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "mimesis"
-version = "16.0.0"
+version = "17.0.0"
 description = "Mimesis: Fake Data Generator."
 authors = ["Isaak Uchakaev <[email protected]>"]
 license = "MIT"

tests/test_providers/test_datetime.py tests/test_providers/test_date.py

@@ -5,7 +5,7 @@
 
 from mimesis import Datetime
 from mimesis.datasets import GMT_OFFSETS, TIMEZONES
-from mimesis.enums import TimestampFormat, TimezoneRegion
+from mimesis.enums import DurationUnit, TimestampFormat, TimezoneRegion
 from mimesis.exceptions import NonEnumerableError
 
 from . import patterns
@@ -215,6 +215,49 @@ def test_week_date(self, _datetime):
         assert (int(year) >= 2017) and (int(year) <= _datetime._CURRENT_YEAR)
         assert int(week) <= 52
 
+    @pytest.mark.parametrize(
+        "min_duration, max_duration, duration_unit",
+        [
+            (1, 10, DurationUnit.WEEKS),
+            (1, 10, DurationUnit.DAYS),
+            (1, 10, DurationUnit.HOURS),
+            (1, 10, DurationUnit.MINUTES),
+            (1, 10, DurationUnit.SECONDS),
+            (1, 10, DurationUnit.MILLISECONDS),
+            (1, 10, DurationUnit.MICROSECONDS),
+            (1, 10, None),
+        ],
+    )
+    def test_duration(self, _datetime, min_duration, max_duration, duration_unit):
+        result = _datetime.duration(
+            min_duration=min_duration,
+            max_duration=max_duration,
+            duration_unit=duration_unit,
+        )
+        assert isinstance(result, datetime.timedelta)
+
+    def test_duration_error(self, _datetime):
+        with pytest.raises(ValueError):
+            _datetime.duration(
+                min_duration=10,
+                max_duration=1,
+                duration_unit=DurationUnit.WEEKS,
+            )
+
+        with pytest.raises(NonEnumerableError):
+            _datetime.duration(
+                min_duration=10,
+                max_duration=10,
+                duration_unit="Blabla",
+            )
+
+        with pytest.raises(TypeError):
+            _datetime.duration(
+                min_duration=10.5,
+                max_duration=10.9,
+                duration_unit=DurationUnit.WEEKS,
+            )
+
 
 class TestSeededDatetime:
     @pytest.fixture
@@ -289,3 +332,9 @@ def test_bulk_create_datetimes(self, d1, d2):
         assert d1.bulk_create_datetimes(
             date_start, date_end, minutes=10
         ) == d2.bulk_create_datetimes(date_start, date_end, minutes=10)
+
+    def test_duratioh(self, d1, d2):
+        assert d1.duration() == d2.duration()
+        assert d1.duration(10, 20, DurationUnit.WEEKS) == d2.duration(
+            10, 20, DurationUnit.WEEKS
+        )