Adds the Period class

Author: sdispater

docs/index.rst

@@ -726,7 +726,7 @@ Each method returns a new ``Pendulum`` instance.
 Difference
 ==========
 
-The ``diff()`` method returns a `Interval`_ instance that represents the total duration
+The ``diff()`` method returns a `Period`_ instance that represents the total duration
 between two ``Pendulum`` instances. This interval can be then expressed in various units.
 These interval methods always return *the total difference expressed* in the specified time requested.
 All values are truncated and not rounded.
@@ -1052,7 +1052,6 @@ level.
 Interval
 ========
 
-When you subtract a ``Pendulum`` instance to another, it will return a ``Interval`` instance.
 The ``Interval`` class is inherited from the native ``timedelta`` class.
 It has many improvements over the base class.
 
@@ -1189,3 +1188,64 @@ It also has a handy ``in_words()``, which determines the interval representation
 
     it.in_words(locale='de')
     '168 Wochen 1 Tag 2 Stunden 1 Minute 24 Sekunden'
+
+
+Period
+======
+
+When you subtract a ``Pendulum`` instance to another, or use the ``diff()`` method, it will return a ``Period`` instance.
+it inherits from the `Interval`_ class with the added benefit that it is aware of the
+instances that generated it, so that it can give access to more methods and properties:
+
+.. code-block:: python
+
+    from pendulum import Pendulum
+
+    start = Pendulum(2000, 1, 1)
+    end = Pendulum(2000, 1, 31)
+
+    period = end - start
+    period.in_weekdays()
+    21
+
+    period.in_weekend_days()
+    10
+
+
+Instantiation
+-------------
+
+You can create an instance in the following ways:
+
+.. code-block:: python
+
+    import pendulum
+
+    start = pendulum.Pendulum(2000, 1, 1)
+    end = pendulum.Pendulum(2000, 1, 31)
+
+    period = pendulum.Period(start, end)
+    period = pendulum.period(start, end)
+
+You can also make an inverted period:
+
+.. code-block:: python
+
+    period = pendulum.period(end, start)
+    period.in_weekdays()
+    -21
+
+    period.in_weekend_days()
+    -10
+
+If you have inverted dates but want to make sure that the period is positive,
+you set the ``absolute`` keyword argument to ``True``:
+
+.. code-block:: python
+
+    period = pendulum.period(end, start, absolute=True)
+    period.in_weekdays()
+    21
+
+    period.in_weekend_days()
+    10

pendulum/__init__.py

@@ -2,6 +2,7 @@
 
 from .pendulum import Pendulum
 from .interval import Interval
+from .period import Period
 
 # Constants
 MONDAY = Pendulum.MONDAY
@@ -56,3 +57,6 @@
 
 # Interval
 interval = Interval
+
+# Period
+period = Period

pendulum/interval.py

@@ -177,63 +177,3 @@ class AbsoluteInterval(AbsoluteIntervalMixin, Interval):
     """
     Interval that expresses a time difference in absolute values.
     """
-
-
-class DatetimeAwareInterval(WordableIntervalMixin, BaseInterval):
-    """
-    Interval class that is aware of the datetimes that generated the
-    time difference.
-    """
-
-    def __new__(cls, dt1, dt2, days=0, seconds=0, microseconds=0,
-                 milliseconds=0, minutes=0, hours=0, weeks=0):
-        return super(DatetimeAwareInterval, cls).__new__(
-            cls, days, seconds, microseconds, milliseconds, minutes, hours, weeks
-        )
-
-    def __init__(self, dt1, dt2, days=0, seconds=0, microseconds=0,
-                 milliseconds=0, minutes=0, hours=0, weeks=0):
-        super(DatetimeAwareInterval, self).__init__(
-            days, seconds, microseconds, milliseconds, minutes, hours, weeks
-        )
-
-        self._dt1 = dt1
-        self._dt2 = dt2
-
-    @classmethod
-    def instance(cls, delta, dt1, dt2):
-        return cls(dt1, dt2, days=delta.days, seconds=delta.seconds, microseconds=delta.microseconds)
-
-
-class DatetimeAwareAbsoluteInterval(AbsoluteIntervalMixin, DatetimeAwareInterval):
-    """
-    Interval class that is aware of the datetimes that generated the
-    time difference and expresses it in absolute values.
-    """
-
-
-class IntervalFactory(object):
-    """
-    Factory to get the poper interval class.
-    """
-
-    @classmethod
-    def get(cls, dt1, dt2, absolute=False):
-        """
-        Gets the proper interval class for two given datetimes.
-
-        :param dt1: The first datetime
-        :type dt1: Pendulum or datetime
-
-        :param dt2: The second datetime
-        :type dt2: Pendulum or datetime
-
-        :rtype: Interval
-        """
-        delta = dt1 - dt2
-
-        klass = DatetimeAwareInterval
-        if absolute:
-            klass = DatetimeAwareAbsoluteInterval
-
-        return klass.instance(delta, dt1, dt2)

pendulum/pendulum.py

@@ -16,7 +16,7 @@
 from dateutil.relativedelta import relativedelta
 from dateutil import parser as dateparser
 
-from .interval import IntervalFactory
+from .period import Period
 from .exceptions import PendulumException
 from .mixins.default import TranslatableMixin
 from ._compat import PY33, basestring
@@ -1171,7 +1171,7 @@ def maximum(self, dt=None):
         """
         return self.max_(dt)
 
-    def is_week_day(self):
+    def is_weekday(self):
         """
         Determines if the instance is a weekday.
 
@@ -1457,12 +1457,12 @@ def diff(self, dt=None, abs=True):
         :param abs: Whether to return an absolute interval or not
         :type abs: bool
 
-        :rtype: Interval
+        :rtype: Period
         """
         if dt is None:
             dt = self.now(self._tz)
 
-        return IntervalFactory.get(self._get_datetime(dt), self._datetime, absolute=abs)
+        return Period(self, self._get_datetime(dt, pendulum=True), absolute=abs)
 
     def diff_for_humans(self, other=None, absolute=False, locale=None):
         """

pendulum/period.py

@@ -0,0 +1,89 @@
+# -*- coding: utf-8 -*-
+
+from .mixins.interval import WordableIntervalMixin
+from .interval import BaseInterval
+
+
+class Period(WordableIntervalMixin, BaseInterval):
+    """
+    Interval class that is aware of the datetimes that generated the
+    time difference.
+    """
+
+    def __new__(cls, start, end, absolute=False):
+        from .pendulum import Pendulum
+
+        if absolute and start > end:
+            end, start = start, end
+
+        if isinstance(start, Pendulum):
+            start = start._datetime
+
+        if isinstance(end, Pendulum):
+            end = end._datetime
+
+        delta = end - start
+
+        return super(Period, cls).__new__(
+            cls, seconds=delta.total_seconds()
+        )
+
+    def __init__(self, start, end, absolute=False):
+        from .pendulum import Pendulum
+
+        super(Period, self).__init__()
+
+        if not isinstance(start, Pendulum):
+            start = Pendulum.instance(start)
+
+        if not isinstance(end, Pendulum):
+            end = Pendulum.instance(end)
+
+        self._invert = False
+        if start > end:
+            self._invert = True
+
+            if absolute:
+                end, start = start, end
+
+        self._absolute = absolute
+        self._start = start
+        self._end = end
+
+    @property
+    def start(self):
+        return self._start
+
+    @property
+    def end(self):
+        return self._end
+
+    def in_weekdays(self):
+        start, end = self.start.start_of('day'), self.end.start_of('day')
+        if not self._absolute and self.invert:
+            start, end = self.end.start_of('day'), self.start.start_of('day')
+
+        days = 0
+        while start <= end:
+            if start.is_weekday():
+                days += 1
+
+            start = start.add(days=1)
+
+        return days * (-1 if not self._absolute and self.invert else 1)
+
+    def in_weekend_days(self):
+        start, end = self.start.start_of('day'), self.end.start_of('day')
+        if not self._absolute and self.invert:
+            start, end = self.end.start_of('day'), self.start.start_of('day')
+
+        days = 0
+        while start <= end:
+            if start.is_weekend():
+                days += 1
+
+            start = start.add(days=1)
+
+        return days * (-1 if not self._absolute and self.invert else 1)
+
+

tests/pendulum_tests/test_diff.py

@@ -79,6 +79,30 @@ def test_diff_in_days_ensure_is_truncated(self):
         dt = Pendulum.create_from_date(2000, 1, 1)
         self.assertEqual(1, dt.diff(dt.copy().add(days=1).add(hours=13)).in_days())
 
+    def test_diff_in_weekdays_positive(self):
+        dt = Pendulum.create_from_date(2000, 1, 1)
+        self.assertEqual(21, dt.diff(dt.end_of('month')).in_weekdays())
+
+    def test_diff_in_weekdays_negative_no_sign(self):
+        dt = Pendulum.create_from_date(2000, 1, 31)
+        self.assertEqual(21, dt.diff(dt.start_of('month')).in_weekdays())
+
+    def test_diff_in_weekdays_negative_with_sign(self):
+        dt = Pendulum.create_from_date(2000, 1, 31)
+        self.assertEqual(-21, dt.diff(dt.start_of('month'), False).in_weekdays())
+
+    def test_diff_in_weekend_days_positive(self):
+        dt = Pendulum.create_from_date(2000, 1, 1)
+        self.assertEqual(10, dt.diff(dt.end_of('month')).in_weekend_days())
+
+    def test_diff_in_weekend_days_negative_no_sign(self):
+        dt = Pendulum.create_from_date(2000, 1, 31)
+        self.assertEqual(10, dt.diff(dt.start_of('month')).in_weekend_days())
+
+    def test_diff_in_weekend_days_negative_with_sign(self):
+        dt = Pendulum.create_from_date(2000, 1, 31)
+        self.assertEqual(-10, dt.diff(dt.start_of('month'), False).in_weekend_days())
+
     def test_diff_in_weeks_positive(self):
         dt = Pendulum.create_from_date(2000, 1, 1)
         self.assertEqual(52, dt.diff(dt.copy().add(years=1)).in_weeks())

tests/pendulum_tests/test_getters.py

@@ -151,11 +151,11 @@ def test_timezone_name(self):
         d = Pendulum.create_from_date(2000, 1, 1, -5)
         self.assertEqual(None, d.timezone_name)
 
-    def test_is_week_day(self):
+    def test_is_weekday(self):
         d = Pendulum.now().next(Pendulum.MONDAY)
-        self.assertTrue(d.is_week_day())
+        self.assertTrue(d.is_weekday())
         d = d.next(Pendulum.SATURDAY)
-        self.assertFalse(d.is_week_day())
+        self.assertFalse(d.is_weekday())
 
     def test_is_weekend(self):
         d = Pendulum.now().next(Pendulum.MONDAY)

tests/period_tests/__init__.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+

tests/period_tests/test_construct.py

@@ -0,0 +1,49 @@
+# -*- coding: utf-8 -*-
+
+from datetime import datetime
+from pendulum import Period, Pendulum
+
+from .. import AbstractTestCase
+
+
+class ConstructTest(AbstractTestCase):
+
+    def test_with_datetimes(self):
+        dt1 = datetime(2000, 1, 1)
+        dt2 = datetime(2000, 1, 31)
+
+        p = Period(dt1, dt2)
+        self.assertIsInstanceOfPendulum(p.start)
+        self.assertIsInstanceOfPendulum(p.end)
+        self.assertPendulum(p.start, 2000, 1, 1)
+        self.assertPendulum(p.end, 2000, 1, 31)
+
+    def test_with_pendulum(self):
+        dt1 = Pendulum(2000, 1, 1)
+        dt2 = Pendulum(2000, 1, 31)
+
+        p = Period(dt1, dt2)
+        self.assertIsInstanceOfPendulum(p.start)
+        self.assertIsInstanceOfPendulum(p.end)
+        self.assertPendulum(p.start, 2000, 1, 1)
+        self.assertPendulum(p.end, 2000, 1, 31)
+
+    def test_inverted(self):
+        dt1 = Pendulum(2000, 1, 1)
+        dt2 = Pendulum(2000, 1, 31)
+
+        p = Period(dt2, dt1)
+        self.assertIsInstanceOfPendulum(p.start)
+        self.assertIsInstanceOfPendulum(p.end)
+        self.assertPendulum(p.start, 2000, 1, 31)
+        self.assertPendulum(p.end, 2000, 1, 1)
+
+    def test_inverted_and_absolute(self):
+        dt1 = Pendulum(2000, 1, 1)
+        dt2 = Pendulum(2000, 1, 31)
+
+        p = Period(dt2, dt1, True)
+        self.assertIsInstanceOfPendulum(p.start)
+        self.assertIsInstanceOfPendulum(p.end)
+        self.assertPendulum(p.start, 2000, 1, 1)
+        self.assertPendulum(p.end, 2000, 1, 31)