Rename the Period class to Interval (#676)

Author: sdispater

pendulum/__init__.py

@@ -33,8 +33,8 @@
 from pendulum.helpers import set_locale
 from pendulum.helpers import week_ends_at
 from pendulum.helpers import week_starts_at
+from pendulum.interval import Interval
 from pendulum.parser import parse
-from pendulum.period import Period
 from pendulum.testing.traveller import Traveller
 from pendulum.time import Time
 from pendulum.tz import UTC
@@ -286,11 +286,11 @@ def duration(
     )
 
 
-def period(start: DateTime, end: DateTime, absolute: bool = False) -> Period:
+def interval(start: DateTime, end: DateTime, absolute: bool = False) -> Interval:
     """
-    Create a Period instance.
+    Create an Interval instance.
     """
-    return Period(start, end, absolute=absolute)
+    return Interval(start, end, absolute=absolute)
 
 
 # Testing
@@ -334,16 +334,16 @@ def period(start: DateTime, end: DateTime, absolute: bool = False) -> Period:
     "from_timestamp",
     "get_locale",
     "instance",
+    "interval",
     "local",
     "locale",
     "naive",
     "now",
-    "period",
     "set_locale",
     "week_ends_at",
     "week_starts_at",
     "parse",
-    "Period",
+    "Interval",
     "Time",
     "UTC",
     "local_timezone",

pendulum/date.py

@@ -24,8 +24,8 @@
 from pendulum.constants import YEARS_PER_DECADE
 from pendulum.exceptions import PendulumException
 from pendulum.helpers import add_duration
+from pendulum.interval import Interval
 from pendulum.mixins.default import FormattableMixin
-from pendulum.period import Period
 
 
 class Date(FormattableMixin, date):
@@ -267,10 +267,10 @@ def __sub__(self, dt: datetime) -> NoReturn:
         ...
 
     @overload
-    def __sub__(self, dt: Date) -> Period:
+    def __sub__(self, dt: Date) -> Interval:
         ...
 
-    def __sub__(self, other: timedelta | date) -> Date | Period:
+    def __sub__(self, other: timedelta | date) -> Date | Interval:
         if isinstance(other, timedelta):
             return self._subtract_timedelta(other)
 
@@ -283,17 +283,17 @@ def __sub__(self, other: timedelta | date) -> Date | Period:
 
     # DIFFERENCES
 
-    def diff(self, dt: date | None = None, abs: bool = True) -> Period:
+    def diff(self, dt: date | None = None, abs: bool = True) -> Interval:
         """
-        Returns the difference between two Date objects as a Period.
+        Returns the difference between two Date objects as an Interval.
 
         :param dt: The date to compare to (defaults to today)
         :param abs: Whether to return an absolute interval or not
         """
         if dt is None:
             dt = self.today()
 
-        return Period(self, Date(dt.year, dt.month, dt.day), absolute=abs)
+        return Interval(self, Date(dt.year, dt.month, dt.day), absolute=abs)
 
     def diff_for_humans(
         self,

pendulum/datetime.py

@@ -32,7 +32,7 @@
 from pendulum.date import Date
 from pendulum.exceptions import PendulumException
 from pendulum.helpers import add_duration
-from pendulum.period import Period
+from pendulum.interval import Interval
 from pendulum.time import Time
 from pendulum.tz import UTC
 from pendulum.tz import local_timezone
@@ -645,7 +645,7 @@ def _add_timedelta_(self, delta: datetime.timedelta) -> DateTime:
         """
         Add timedelta duration to the instance.
         """
-        if isinstance(delta, pendulum.Period):
+        if isinstance(delta, pendulum.Interval):
             return self.add(
                 years=delta.years,
                 months=delta.months,
@@ -678,14 +678,14 @@ def _subtract_timedelta(self, delta: datetime.timedelta) -> DateTime:
 
     def diff(  # type: ignore[override]
         self, dt: datetime.datetime | None = None, abs: bool = True
-    ) -> Period:
+    ) -> Interval:
         """
-        Returns the difference between two DateTime objects represented as a Period.
+        Returns the difference between two DateTime objects represented as an Interval.
         """
         if dt is None:
             dt = self.now(self.tz)
 
-        return Period(self, dt, absolute=abs)
+        return Interval(self, dt, absolute=abs)
 
     def diff_for_humans(  # type: ignore[override]
         self,
@@ -1170,12 +1170,12 @@ def __sub__(self, other: datetime.timedelta) -> DateTime:
         ...
 
     @overload
-    def __sub__(self, other: DateTime) -> Period:
+    def __sub__(self, other: DateTime) -> Interval:
         ...
 
     def __sub__(
         self, other: datetime.datetime | datetime.timedelta
-    ) -> DateTime | Period:
+    ) -> DateTime | Interval:
         if isinstance(other, datetime.timedelta):
             return self._subtract_timedelta(other)
 
@@ -1198,7 +1198,7 @@ def __sub__(
 
         return other.diff(self, False)
 
-    def __rsub__(self, other: datetime.datetime) -> Period:
+    def __rsub__(self, other: datetime.datetime) -> Interval:
         if not isinstance(other, datetime.datetime):
             return NotImplemented
 

pendulum/period.py renamed to pendulum/interval.py

@@ -24,10 +24,9 @@
     from pendulum.locales.locale import Locale  # noqa
 
 
-class Period(Duration):
+class Interval(Duration):
     """
-    Duration class that is aware of the datetimes that generated the
-    time difference.
+    A period of time between two datetimes.
     """
 
     @overload
@@ -36,7 +35,7 @@ def __new__(
         start: pendulum.DateTime | datetime,
         end: pendulum.DateTime | datetime,
         absolute: bool = False,
-    ) -> Period:
+    ) -> Interval:
         ...
 
     @overload
@@ -45,15 +44,15 @@ def __new__(
         start: pendulum.Date | date,
         end: pendulum.Date | date,
         absolute: bool = False,
-    ) -> Period:
+    ) -> Interval:
         ...
 
     def __new__(
         cls,
         start: pendulum.DateTime | pendulum.Date | datetime | date,
         end: pendulum.DateTime | pendulum.Date | datetime | date,
         absolute: bool = False,
-    ) -> Period:
+    ) -> Interval:
         if (
             isinstance(start, datetime)
             and not isinstance(end, datetime)
@@ -126,7 +125,7 @@ def __new__(
 
         delta: timedelta = _end - _start  # type: ignore[operator]
 
-        return cast(Period, super().__new__(cls, seconds=delta.total_seconds()))
+        return cast(Interval, super().__new__(cls, seconds=delta.total_seconds()))
 
     def __init__(
         self,
@@ -339,7 +338,7 @@ def __add__(self, other: timedelta) -> Duration:
     def __sub__(self, other: timedelta) -> Duration:
         return self.as_interval().__sub__(other)
 
-    def __neg__(self) -> Period:
+    def __neg__(self) -> Interval:
         return self.__class__(self.end, self.start, self._absolute)
 
     def __mul__(self, other: int | float) -> Duration:
@@ -377,7 +376,7 @@ def __mod__(self, other: timedelta) -> Duration:
     def __divmod__(self, other: timedelta) -> tuple[int, Duration]:
         return self.as_interval().__divmod__(other)
 
-    def __abs__(self) -> Period:
+    def __abs__(self) -> Interval:
         return self.__class__(self.start, self.end, absolute=True)
 
     def __repr__(self) -> str:
@@ -390,7 +389,7 @@ def _cmp(self, other: timedelta) -> int:
         # Only needed for PyPy
         assert isinstance(other, timedelta)
 
-        if isinstance(other, Period):
+        if isinstance(other, Interval):
             other = other.as_timedelta()
 
         td = self.as_timedelta()
@@ -414,7 +413,7 @@ def _getstate(
     def __reduce__(
         self,
     ) -> tuple[
-        type[Period],
+        type[Interval],
         tuple[
             pendulum.DateTime | pendulum.Date | datetime | date,
             pendulum.DateTime | pendulum.Date | datetime | date,
@@ -426,7 +425,7 @@ def __reduce__(
     def __reduce_ex__(
         self, protocol: SupportsIndex
     ) -> tuple[
-        type[Period],
+        type[Interval],
         tuple[
             pendulum.DateTime | pendulum.Date | datetime | date,
             pendulum.DateTime | pendulum.Date | datetime | date,
@@ -439,7 +438,7 @@ def __hash__(self) -> int:
         return hash((self.start, self.end, self._absolute))
 
     def __eq__(self, other: object) -> bool:
-        if isinstance(other, Period):
+        if isinstance(other, Interval):
             return (self.start, self.end, self._absolute) == (
                 other.start,
                 other.end,

pendulum/parser.py

@@ -13,7 +13,7 @@
     from pendulum.date import Date
     from pendulum.datetime import DateTime
     from pendulum.duration import Duration
-    from pendulum.period import Period
+    from pendulum.interval import Interval
     from pendulum.time import Time
 
 try:
@@ -29,7 +29,7 @@ def parse(text: str, **options: t.Any) -> Date | Time | DateTime | Duration:
     return _parse(text, **options)
 
 
-def _parse(text: str, **options: t.Any) -> Date | DateTime | Time | Duration | Period:
+def _parse(text: str, **options: t.Any) -> Date | DateTime | Time | Duration | Interval:
     """
     Parses a string with the given options.
 
@@ -68,7 +68,7 @@ def _parse(text: str, **options: t.Any) -> Date | DateTime | Time | Duration | P
             if parsed.start is not None:
                 dt = pendulum.instance(parsed.start, tz=options.get("tz", UTC))
 
-                return pendulum.period(
+                return pendulum.interval(
                     dt,
                     dt.add(
                         years=duration.years,
@@ -86,7 +86,7 @@ def _parse(text: str, **options: t.Any) -> Date | DateTime | Time | Duration | P
                 t.cast(datetime.datetime, parsed.end), tz=options.get("tz", UTC)
             )
 
-            return pendulum.period(
+            return pendulum.interval(
                 dt.subtract(
                     years=duration.years,
                     months=duration.months,
@@ -100,7 +100,7 @@ def _parse(text: str, **options: t.Any) -> Date | DateTime | Time | Duration | P
                 dt,
             )
 
-        return pendulum.period(
+        return pendulum.interval(
             pendulum.instance(
                 t.cast(datetime.datetime, parsed.start), tz=options.get("tz", UTC)
             ),

pyproject.toml

@@ -147,13 +147,13 @@ module = [
     "tests.parsing.test_parsing",
     "tests.parsing.test_parsing_duration",
     "tests.parsing.test_parse_iso8601",
-    "tests.period.test_add_subtract",
-    "tests.period.test_arithmetic",
-    "tests.period.test_behavior",
-    "tests.period.test_construct",
-    "tests.period.test_hashing",
-    "tests.period.test_in_words",
-    "tests.period.test_range",
+    "tests.interval.test_add_subtract",
+    "tests.interval.test_arithmetic",
+    "tests.interval.test_behavior",
+    "tests.interval.test_construct",
+    "tests.interval.test_hashing",
+    "tests.interval.test_in_words",
+    "tests.interval.test_range",
     "tests.time.test_add",
     "tests.time.test_behavior",
     "tests.time.test_comparison",

tests/conftest.py

@@ -62,7 +62,7 @@ def assert_duration(
     minutes=None,
     seconds=None,
     microseconds=None,
-):
+) -> None:
     expected = {}
     actual = {}
 

tests/period/__init__.py renamed to tests/interval/__init__.py

@@ -8,14 +8,14 @@
 def test_multiply():
     dt1 = pendulum.DateTime(2016, 8, 7, 12, 34, 56)
     dt2 = dt1.add(days=6, seconds=34)
-    it = pendulum.period(dt1, dt2)
+    it = pendulum.interval(dt1, dt2)
     mul = it * 2
     assert isinstance(mul, pendulum.Duration)
     assert_duration(mul, 0, 0, 1, 5, 0, 1, 8)
 
     dt1 = pendulum.DateTime(2016, 8, 7, 12, 34, 56)
     dt2 = dt1.add(days=6, seconds=34)
-    it = pendulum.period(dt1, dt2)
+    it = pendulum.interval(dt1, dt2)
     mul = it * 2
     assert isinstance(mul, pendulum.Duration)
     assert_duration(mul, 0, 0, 1, 5, 0, 1, 8)
@@ -24,14 +24,14 @@ def test_multiply():
 def test_divide():
     dt1 = pendulum.DateTime(2016, 8, 7, 12, 34, 56)
     dt2 = dt1.add(days=2, seconds=34)
-    it = pendulum.period(dt1, dt2)
+    it = pendulum.interval(dt1, dt2)
     mul = it / 2
     assert isinstance(mul, pendulum.Duration)
     assert_duration(mul, 0, 0, 0, 1, 0, 0, 17)
 
     dt1 = pendulum.DateTime(2016, 8, 7, 12, 34, 56)
     dt2 = dt1.add(days=2, seconds=35)
-    it = pendulum.period(dt1, dt2)
+    it = pendulum.interval(dt1, dt2)
     mul = it / 2
     assert isinstance(mul, pendulum.Duration)
     assert_duration(mul, 0, 0, 0, 1, 0, 0, 17)
@@ -40,14 +40,14 @@ def test_divide():
 def test_floor_divide():
     dt1 = pendulum.DateTime(2016, 8, 7, 12, 34, 56)
     dt2 = dt1.add(days=2, seconds=34)
-    it = pendulum.period(dt1, dt2)
+    it = pendulum.interval(dt1, dt2)
     mul = it // 2
     assert isinstance(mul, pendulum.Duration)
     assert_duration(mul, 0, 0, 0, 1, 0, 0, 17)
 
     dt1 = pendulum.DateTime(2016, 8, 7, 12, 34, 56)
     dt2 = dt1.add(days=2, seconds=35)
-    it = pendulum.period(dt1, dt2)
+    it = pendulum.interval(dt1, dt2)
     mul = it // 3
     assert isinstance(mul, pendulum.Duration)
     assert_duration(mul, 0, 0, 0, 0, 16, 0, 11)