Rationalise Instant doc & tests

Author: bonjourmauko

openfisca_core/periods/instant_.py

@@ -1,3 +1,7 @@
+from __future__ import annotations
+
+from typing import Union
+
 import calendar
 import datetime
 
@@ -6,35 +10,39 @@
 
 
 class Instant(tuple):
-    """An instant in time (year, month, day).
+    """An instant in time (``year``, ``month``, ``day``).
 
-    An :class:`.Instant` represents the most atomic and indivisible
-    legislation's time unit.
+    An ``Instant`` represents the most atomic and indivisible
+    legislation's date unit.
 
     Current implementation considers this unit to be a day, so
-    :obj:`instants <.Instant>` can be thought of as "day dates".
+    ``instants`` can be thought of as "day dates".
 
     Args:
-        (tuple(tuple(int, int, int))):
+        (tuple(int, int, int)):
             The ``year``, ``month``, and ``day``, accordingly.
 
     Examples:
         >>> instant = Instant((2021, 9, 13))
 
-        >>> repr(Instant)
-        "<class 'openfisca_core.periods.instant_.Instant'>"
+        ``Instants`` are represented as a ``tuple`` containing the date units:
 
         >>> repr(instant)
         'Instant((2021, 9, 13))'
 
+        However, their user-friendly representation is as a date in the
+        ISO format:
+
         >>> str(instant)
         '2021-09-13'
 
+        Because ``Instants`` are ``tuples``, they are immutable, which allows
+        us to use them as keys in hashmaps:
+
         >>> dict([(instant, (2021, 9, 13))])
         {Instant((2021, 9, 13)): (2021, 9, 13)}
 
-        >>> list(instant)
-        [2021, 9, 13]
+        All the rest of the ``tuple`` protocols are inherited as well:
 
         >>> instant[0]
         2021
@@ -48,74 +56,102 @@ class Instant(tuple):
         >>> instant == (2021, 9, 13)
         True
 
-        >>> instant != (2021, 9, 13)
-        False
-
         >>> instant > (2020, 9, 13)
         True
 
-        >>> instant < (2020, 9, 13)
-        False
-
-        >>> instant >= (2020, 9, 13)
-        True
-
-        >>> instant <= (2020, 9, 13)
-        False
-
-        >>> instant.year
-        2021
-
-        >>> instant.month
-        9
-
-        >>> instant.day
-        13
-
-        >>> instant.date
-        datetime.date(2021, 9, 13)
-
         >>> year, month, day = instant
 
     """
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return '{}({})'.format(self.__class__.__name__, super(Instant, self).__repr__())
 
-    def __str__(self):
+    def __str__(self) -> str:
         instant_str = config.str_by_instant_cache.get(self)
         if instant_str is None:
             config.str_by_instant_cache[self] = instant_str = self.date.isoformat()
         return instant_str
 
     @property
-    def date(self):
+    def date(self) -> "datetime.date":
+        """The date representation of the ``Instant``.
+
+        Example:
+            >>> instant = Instant((2021, 10, 1))
+            >>> instant.date
+            datetime.date(2021, 10, 1)
+
+        Returns:
+            A datetime.time.
+
+        """
+
         instant_date = config.date_by_instant_cache.get(self)
         if instant_date is None:
             config.date_by_instant_cache[self] = instant_date = datetime.date(*self)
         return instant_date
 
     @property
-    def day(self):
-        return self[2]
+    def year(self) -> int:
+        """The ``year`` of the ``Instant``.
+
+        Example:
+            >>> instant = Instant((2021, 10, 1))
+            >>> instant.year
+            2021
+
+        Returns:
+            An int.
+
+        """
+
+        return self[0]
 
     @property
-    def month(self):
+    def month(self) -> int:
+        """The ``month`` of the ``Instant``.
+
+        Example:
+            >>> instant = Instant((2021, 10, 1))
+            >>> instant.month
+            10
+
+        Returns:
+            An int.
+
+        """
+
         return self[1]
 
-    def period(self, unit, size = 1):
-        """Creates a new :obj:`.Period` starting at :obj:`.Instant`.
+    @property
+    def day(self) -> int:
+        """The ``day`` of the ``Instant``.
+
+        Example:
+            >>> instant = Instant((2021, 10, 1))
+            >>> instant.day
+            1
+
+        Returns:
+            An int.
+
+        """
+
+        return self[2]
+
+    def period(self, unit: str, size: int = 1) -> "periods.Period":
+        """Creates a new ``Period`` starting at ``self``.
 
         Args:
-            unit: ``day`` or ``month`` or ``year``.
-            size: How many of ``unit``.
+            unit (str): ``day`` or ``month`` or ``year``.
+            size (int): How many of ``unit``.
 
         Returns:
-            A new object :obj:`.Period`.
+            Period: A new one.
 
         Raises:
-            :exc:`AssertionError`: When ``unit`` is not a date unit.
-            :exc:`AssertionError`: When ``size`` is not an unsigned :obj:`int`.
+            AssertionError: When ``unit`` is not a date unit.
+            AssertionError: When ``size`` is not an unsigned ``int``.
 
         Examples:
             >>> Instant((2021, 9, 13)).period("year")
@@ -130,20 +166,20 @@ def period(self, unit, size = 1):
         assert isinstance(size, int) and size >= 1, 'Invalid size: {} of type {}'.format(size, type(size))
         return periods.Period((unit, self, size))
 
-    def offset(self, offset, unit):
+    def offset(self, offset: Union[str, int], unit: str) -> "Instant":
         """Increments/decrements the given instant with offset units.
 
         Args:
-            offset: How much of ``unit`` to offset.
-            unit: What to offset
+            offset (str | int): How much of ``unit`` to offset.
+            unit (str): What to offset.
 
         Returns:
-            :obj:`.Instant`: A new :obj:`.Instant` in time.
+            Instant: A new one.
 
         Raises:
-            :exc:`AssertionError`: When ``unit`` is not a date unit.
-            :exc:`AssertionError`: When ``offset`` is not either ``first-of``,
-                ``last-of``, or any :obj:`int`.
+            AssertionError: When ``unit`` is not a date unit.
+            AssertionError: When ``offset`` is not either ``first-of``,
+                ``last-of``, or any ``int``.
 
         Examples:
             >>> Instant((2020, 12, 31)).offset("first-of", "month")
@@ -215,7 +251,3 @@ def offset(self, offset, unit):
                     day = month_last_day
 
         return self.__class__((year, month, day))
-
-    @property
-    def year(self):
-        return self[0]

openfisca_core/periods/tests/test_instant.py

@@ -0,0 +1,27 @@
+import pytest
+
+from openfisca_core import periods
+from openfisca_core.periods import Instant
+
+
+@pytest.fixture
+def instant():
+    return Instant((2020, 2, 29))
+
+
+@pytest.mark.parametrize("offset, unit, expected", [
+    ["first-of", periods.YEAR, Instant((2020, 1, 1))],
+    ["first-of", periods.MONTH, Instant((2020, 2, 1))],
+    ["first-of", periods.DAY, Instant((2020, 2, 29))],
+    ["last-of", periods.YEAR, Instant((2020, 12, 31))],
+    ["last-of", periods.MONTH, Instant((2020, 2, 29))],
+    ["last-of", periods.DAY, Instant((2020, 2, 29))],
+    [-3, periods.YEAR, Instant((2017, 2, 28))],
+    [-3, periods.MONTH, Instant((2019, 11, 29))],
+    [-3, periods.DAY, Instant((2020, 2, 26))],
+    [3, periods.YEAR, Instant((2023, 2, 28))],
+    [3, periods.MONTH, Instant((2020, 5, 29))],
+    [3, periods.DAY, Instant((2020, 3, 3))],
+    ])
+def test_offset(instant, offset, unit, expected):
+    assert expected == instant.offset(offset, unit)