OpenFisca-Core-test 46.0.0__py3-none-any.whl

openfisca_core/periods/helpers.py

@@ -0,0 +1,314 @@
+from __future__ import annotations
+
+import datetime
+import functools
+from typing import NoReturn
+
+import pendulum
+
+from openfisca_core import types as t
+
+from . import config
+from ._errors import InstantError, PeriodError
+from ._parsers import parse_instant, parse_period
+from .date_unit import DateUnit
+from .instant_ import Instant
+from .period_ import Period
+
+
+@functools.singledispatch
+def instant(value: object) -> t.Instant:
+    """Build a new instant, aka a triple of integers (year, month, day).
+
+    Args:
+        value(object): An ``instant-like`` object.
+
+    Returns:
+        :obj:`.Instant`: A new instant.
+
+    Raises:
+        :exc:`ValueError`: When the arguments were invalid, like "2021-32-13".
+
+    Examples:
+        >>> instant((2021,))
+        Instant((2021, 1, 1))
+
+        >>> instant((2021, 9))
+        Instant((2021, 9, 1))
+
+        >>> instant(datetime.date(2021, 9, 16))
+        Instant((2021, 9, 16))
+
+        >>> instant(Instant((2021, 9, 16)))
+        Instant((2021, 9, 16))
+
+        >>> instant(Period((DateUnit.YEAR, Instant((2021, 9, 16)), 1)))
+        Instant((2021, 9, 16))
+
+        >>> instant(2021)
+        Instant((2021, 1, 1))
+
+        >>> instant("2021")
+        Instant((2021, 1, 1))
+
+        >>> instant([2021])
+        Instant((2021, 1, 1))
+
+        >>> instant([2021, 9])
+        Instant((2021, 9, 1))
+
+        >>> instant(None)
+        Traceback (most recent call last):
+        openfisca_core.periods._errors.InstantError: 'None' is not a valid i...
+
+    """
+
+    if isinstance(value, t.SeqInt):
+        return Instant((list(value) + [1] * 3)[:3])
+
+    raise InstantError(str(value))
+
+
+@instant.register
+def _(value: None) -> NoReturn:
+    raise InstantError(str(value))
+
+
+@instant.register
+def _(value: int) -> t.Instant:
+    return Instant((value, 1, 1))
+
+
+@instant.register
+def _(value: Period) -> t.Instant:
+    return value.start
+
+
+@instant.register
+def _(value: t.Instant) -> t.Instant:
+    return value
+
+
+@instant.register
+def _(value: datetime.date) -> t.Instant:
+    return Instant((value.year, value.month, value.day))
+
+
+@instant.register
+def _(value: str) -> t.Instant:
+    return parse_instant(value)
+
+
+def instant_date(instant: None | t.Instant) -> None | datetime.date:
+    """Returns the date representation of an ``Instant``.
+
+    Args:
+        instant: An ``Instant``.
+
+    Returns:
+        None: When ``instant`` is None.
+        datetime.date: Otherwise.
+
+    Examples:
+        >>> instant_date(Instant((2021, 1, 1)))
+        Date(2021, 1, 1)
+
+    """
+    if instant is None:
+        return None
+
+    instant_date = config.date_by_instant_cache.get(instant)
+
+    if instant_date is None:
+        config.date_by_instant_cache[instant] = instant_date = pendulum.date(*instant)
+
+    return instant_date
+
+
+@functools.singledispatch
+def period(value: object) -> t.Period:
+    """Build a new period, aka a triple (unit, start_instant, size).
+
+    Args:
+        value: A ``period-like`` object.
+
+    Returns:
+        :obj:`.Period`: A period.
+
+    Raises:
+        :exc:`ValueError`: When the arguments were invalid, like "2021-32-13".
+
+    Examples:
+        >>> period(Period((DateUnit.YEAR, Instant((2021, 1, 1)), 1)))
+        Period((<DateUnit.YEAR: 'year'>, Instant((2021, 1, 1)), 1))
+
+        >>> period(Instant((2021, 1, 1)))
+        Period((<DateUnit.DAY: 'day'>, Instant((2021, 1, 1)), 1))
+
+        >>> period(DateUnit.ETERNITY)
+        Period((<DateUnit.ETERNITY: 'eternity'>, Instant((-1, -1, -1)), -1))
+
+        >>> period(2021)
+        Period((<DateUnit.YEAR: 'year'>, Instant((2021, 1, 1)), 1))
+
+        >>> period("2014")
+        Period((<DateUnit.YEAR: 'year'>, Instant((2014, 1, 1)), 1))
+
+        >>> period("year:2014")
+        Period((<DateUnit.YEAR: 'year'>, Instant((2014, 1, 1)), 1))
+
+        >>> period("month:2014-02")
+        Period((<DateUnit.MONTH: 'month'>, Instant((2014, 2, 1)), 1))
+
+        >>> period("year:2014-02")
+        Period((<DateUnit.YEAR: 'year'>, Instant((2014, 2, 1)), 1))
+
+        >>> period("day:2014-02-02")
+        Period((<DateUnit.DAY: 'day'>, Instant((2014, 2, 2)), 1))
+
+        >>> period("day:2014-02-02:3")
+        Period((<DateUnit.DAY: 'day'>, Instant((2014, 2, 2)), 3))
+
+    """
+
+    one, two, three = 1, 2, 3
+
+    # We return an "eternity-period", for example
+    # ``<Period(('eternity', <Instant(-1, -1, -1)>, -1))>``.
+    if str(value).lower() == DateUnit.ETERNITY:
+        return Period.eternity()
+
+    # We try to parse from an ISO format/calendar period.
+    if isinstance(value, t.InstantStr):
+        return parse_period(value)
+
+    # A complex period has a ':' in its string.
+    if isinstance(value, t.PeriodStr):
+        components = value.split(":")
+
+        # The left-most component must be a valid unit
+        unit = components[0]
+
+        if unit not in list(DateUnit) or unit == DateUnit.ETERNITY:
+            raise PeriodError(str(value))
+
+        # Cast ``unit`` to DateUnit.
+        unit = DateUnit(unit)
+
+        # The middle component must be a valid iso period
+        period = parse_period(components[1])
+
+        # Periods like year:2015-03 have a size of 1
+        if len(components) == two:
+            size = one
+
+        # if provided, make sure the size is an integer
+        elif len(components) == three:
+            try:
+                size = int(components[2])
+
+            except ValueError as error:
+                raise PeriodError(str(value)) from error
+
+        # If there are more than 2 ":" in the string, the period is invalid
+        else:
+            raise PeriodError(str(value))
+
+        # Reject ambiguous periods such as month:2014
+        if unit_weight(period.unit) > unit_weight(unit):
+            raise PeriodError(str(value))
+
+        return Period((unit, period.start, size))
+
+    raise PeriodError(str(value))
+
+
+@period.register
+def _(value: None) -> NoReturn:
+    raise PeriodError(str(value))
+
+
+@period.register
+def _(value: int) -> t.Period:
+    return Period((DateUnit.YEAR, instant(value), 1))
+
+
+@period.register
+def _(value: t.Period) -> t.Period:
+    return value
+
+
+@period.register
+def _(value: t.Instant) -> t.Period:
+    return Period((DateUnit.DAY, value, 1))
+
+
+@period.register
+def _(value: datetime.date) -> t.Period:
+    return Period((DateUnit.DAY, instant(value), 1))
+
+
+def key_period_size(period: t.Period) -> str:
+    """Define a key in order to sort periods by length.
+
+    It uses two aspects: first, ``unit``, then, ``size``.
+
+    Args:
+        period: An :mod:`.openfisca_core` :obj:`.Period`.
+
+    Returns:
+        :obj:`str`: A string.
+
+    Examples:
+        >>> instant = Instant((2021, 9, 14))
+
+        >>> period = Period((DateUnit.DAY, instant, 1))
+        >>> key_period_size(period)
+        '100_1'
+
+        >>> period = Period((DateUnit.YEAR, instant, 3))
+        >>> key_period_size(period)
+        '300_3'
+
+    """
+
+    return f"{unit_weight(period.unit)}_{period.size}"
+
+
+def unit_weights() -> dict[t.DateUnit, int]:
+    """Assign weights to date units.
+
+    Examples:
+        >>> unit_weights()
+        {<DateUnit.WEEKDAY: 'weekday'>: 100, ...ETERNITY: 'eternity'>: 400}
+
+    """
+    return {
+        DateUnit.WEEKDAY: 100,
+        DateUnit.WEEK: 200,
+        DateUnit.DAY: 100,
+        DateUnit.MONTH: 200,
+        DateUnit.YEAR: 300,
+        DateUnit.ETERNITY: 400,
+    }
+
+
+def unit_weight(unit: t.DateUnit) -> int:
+    """Retrieves a specific date unit weight.
+
+    Examples:
+        >>> unit_weight(DateUnit.DAY)
+        100
+
+    """
+    return unit_weights()[unit]
+
+
+__all__ = [
+    "instant",
+    "instant_date",
+    "key_period_size",
+    "period",
+    "unit_weight",
+    "unit_weights",
+]

openfisca_core/periods/instant_.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+import pendulum
+
+from openfisca_core import types as t
+
+from . import config
+from .date_unit import DateUnit
+
+
+class Instant(tuple[int, int, int]):
+    """An instant in time (year, month, day).
+
+    An :class:`.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".
+
+    Examples:
+        >>> instant = Instant((2021, 9, 13))
+
+        >>> repr(Instant)
+        "<class 'openfisca_core.periods.instant_.Instant'>"
+
+        >>> repr(instant)
+        'Instant((2021, 9, 13))'
+
+        >>> str(instant)
+        '2021-09-13'
+
+        >>> dict([(instant, (2021, 9, 13))])
+        {Instant((2021, 9, 13)): (2021, 9, 13)}
+
+        >>> list(instant)
+        [2021, 9, 13]
+
+        >>> instant[0]
+        2021
+
+        >>> instant[0] in instant
+        True
+
+        >>> len(instant)
+        3
+
+        >>> 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
+        Date(2021, 9, 13)
+
+        >>> year, month, day = instant
+
+    """
+
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({super().__repr__()})"
+
+    def __str__(self) -> t.InstantStr:
+        instant_str = config.str_by_instant_cache.get(self)
+
+        if instant_str is None:
+            instant_str = t.InstantStr(self.date.isoformat())
+            config.str_by_instant_cache[self] = instant_str
+
+        return instant_str
+
+    def __lt__(self, other: object) -> bool:
+        if isinstance(other, Instant):
+            return super().__lt__(other)
+        return NotImplemented
+
+    def __le__(self, other: object) -> bool:
+        if isinstance(other, Instant):
+            return super().__le__(other)
+        return NotImplemented
+
+    @property
+    def date(self) -> pendulum.Date:
+        instant_date = config.date_by_instant_cache.get(self)
+
+        if instant_date is None:
+            instant_date = pendulum.date(*self)
+            config.date_by_instant_cache[self] = instant_date
+
+        return instant_date
+
+    @property
+    def day(self) -> int:
+        return self[2]
+
+    @property
+    def month(self) -> int:
+        return self[1]
+
+    @property
+    def year(self) -> int:
+        return self[0]
+
+    @property
+    def is_eternal(self) -> bool:
+        return self == self.eternity()
+
+    def offset(self, offset: str | int, unit: t.DateUnit) -> t.Instant | None:
+        """Increments/decrements the given instant with offset units.
+
+        Args:
+            offset: How much of ``unit`` to offset.
+            unit: What to offset
+
+        Returns:
+            :obj:`.Instant`: A new :obj:`.Instant` in time.
+
+        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`.
+
+        Examples:
+            >>> Instant((2020, 12, 31)).offset("first-of", DateUnit.MONTH)
+            Instant((2020, 12, 1))
+
+            >>> Instant((2020, 1, 1)).offset("last-of", DateUnit.YEAR)
+            Instant((2020, 12, 31))
+
+            >>> Instant((2020, 1, 1)).offset(1, DateUnit.YEAR)
+            Instant((2021, 1, 1))
+
+            >>> Instant((2020, 1, 1)).offset(-3, DateUnit.DAY)
+            Instant((2019, 12, 29))
+
+        """
+        year, month, _ = self
+
+        assert unit in (DateUnit.isoformat + DateUnit.isocalendar), (
+            f"Invalid unit: {unit} of type {type(unit)}"
+        )
+
+        if offset == "first-of":
+            if unit == DateUnit.YEAR:
+                return self.__class__((year, 1, 1))
+
+            if unit == DateUnit.MONTH:
+                return self.__class__((year, month, 1))
+
+            if unit == DateUnit.WEEK:
+                date = self.date
+                date = date.start_of("week")
+                return self.__class__((date.year, date.month, date.day))
+            return None
+
+        if offset == "last-of":
+            if unit == DateUnit.YEAR:
+                return self.__class__((year, 12, 31))
+
+            if unit == DateUnit.MONTH:
+                date = self.date
+                date = date.end_of("month")
+                return self.__class__((date.year, date.month, date.day))
+
+            if unit == DateUnit.WEEK:
+                date = self.date
+                date = date.end_of("week")
+                return self.__class__((date.year, date.month, date.day))
+            return None
+
+        assert isinstance(
+            offset,
+            int,
+        ), f"Invalid offset: {offset} of type {type(offset)}"
+
+        if unit == DateUnit.YEAR:
+            date = self.date
+            date = date.add(years=offset)
+            return self.__class__((date.year, date.month, date.day))
+
+        if unit == DateUnit.MONTH:
+            date = self.date
+            date = date.add(months=offset)
+            return self.__class__((date.year, date.month, date.day))
+
+        if unit == DateUnit.WEEK:
+            date = self.date
+            date = date.add(weeks=offset)
+            return self.__class__((date.year, date.month, date.day))
+
+        if unit in (DateUnit.DAY, DateUnit.WEEKDAY):
+            date = self.date
+            date = date.add(days=offset)
+            return self.__class__((date.year, date.month, date.day))
+        return None
+
+    @classmethod
+    def eternity(cls) -> t.Instant:
+        """Return an eternity instant."""
+        return cls((-1, -1, -1))
+
+
+__all__ = ["Instant"]