test: encapsulate periods module

CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+# 39.0.0 [#1138](https://github.com/openfisca/openfisca-core/pull/1138)
+
+#### Breaking changes
+
+- Deprecate `periods.intersect`.
+- Deprecate `periods.unit_weight`.
+- Deprecate `periods.unit_weights`.
+- Rename `instant` to `build_instant`.
+- Rename `period` to `build_period`.
+- Move `instant_date` to `Instant.to_date`.
+- Refactor `Period.contains` as `Period.__contains__`.
+- Make `periods.parse_period` stricter (for example `2022-1` now fails).
+
+#### Technical changes
+
+- Add typing to `openfisca_core.periods`.
+- Fix `openfisca_core.periods` doctests.
+- Document `openfisca_core.periods`.
+
 # 38.0.0 [#989](https://github.com/openfisca/openfisca-core/pull/989)
 
 #### New Features

openfisca_core/data_storage/in_memory_storage.py

@@ -14,8 +14,8 @@ def __init__(self, is_eternal = False):
 
     def get(self, period):
         if self.is_eternal:
-            period = periods.period(periods.ETERNITY)
-        period = periods.period(period)
+            period = periods.build_period(periods.ETERNITY)
+        period = periods.build_period(period)
 
         values = self._arrays.get(period)
         if values is None:
@@ -24,8 +24,8 @@ def get(self, period):
 
     def put(self, value, period):
         if self.is_eternal:
-            period = periods.period(periods.ETERNITY)
-        period = periods.period(period)
+            period = periods.build_period(periods.ETERNITY)
+        period = periods.build_period(period)
 
         self._arrays[period] = value
 
@@ -35,13 +35,13 @@ def delete(self, period = None):
             return
 
         if self.is_eternal:
-            period = periods.period(periods.ETERNITY)
-        period = periods.period(period)
+            period = periods.build_period(periods.ETERNITY)
+        period = periods.build_period(period)
 
         self._arrays = {
             period_item: value
             for period_item, value in self._arrays.items()
-            if not period.contains(period_item)
+            if period_item not in period
             }
 
     def get_known_periods(self):

openfisca_core/data_storage/on_disk_storage.py

@@ -28,8 +28,8 @@ def _decode_file(self, file):
 
     def get(self, period):
         if self.is_eternal:
-            period = periods.period(periods.ETERNITY)
-        period = periods.period(period)
+            period = periods.build_period(periods.ETERNITY)
+        period = periods.build_period(period)
 
         values = self._files.get(period)
         if values is None:
@@ -38,8 +38,8 @@ def get(self, period):
 
     def put(self, value, period):
         if self.is_eternal:
-            period = periods.period(periods.ETERNITY)
-        period = periods.period(period)
+            period = periods.build_period(periods.ETERNITY)
+        period = periods.build_period(period)
 
         filename = str(period)
         path = os.path.join(self.storage_dir, filename) + '.npy'
@@ -55,14 +55,14 @@ def delete(self, period = None):
             return
 
         if self.is_eternal:
-            period = periods.period(periods.ETERNITY)
-        period = periods.period(period)
+            period = periods.build_period(periods.ETERNITY)
+        period = periods.build_period(period)
 
         if period is not None:
             self._files = {
                 period_item: value
                 for period_item, value in self._files.items()
-                if not period.contains(period_item)
+                if period_item not in period
                 }
 
     def get_known_periods(self):
@@ -76,7 +76,7 @@ def restore(self):
                 continue
             path = os.path.join(self.storage_dir, filename)
             filename_core = filename.rsplit('.', 1)[0]
-            period = periods.period(filename_core)
+            period = periods.build_period(filename_core)
             files[period] = path
 
     def __del__(self):

openfisca_core/holders/holder.py

@@ -8,15 +8,12 @@
 import numpy
 import psutil
 
-from openfisca_core import (
-    errors,
-    commons,
-    data_storage as storage,
-    indexed_enums as enums,
-    periods,
-    tools,
-    types,
-    )
+from openfisca_core import commons
+from openfisca_core import data_storage as storage
+from openfisca_core import errors
+from openfisca_core import indexed_enums as enums
+from openfisca_core import periods, tools
+from openfisca_core.periods.typing import Period
 
 from .memory_usage import MemoryUsage
 
@@ -164,7 +161,7 @@ def get_known_periods(self):
 
     def set_input(
             self,
-            period: types.Period,
+            period: Period,
             array: Union[numpy.ndarray, Sequence[Any]],
             ) -> Optional[numpy.ndarray]:
         """Set a Variable's array of values of a given Period.
@@ -210,7 +207,11 @@ def set_input(
 
         """
 
-        period = periods.period(period)
+        period = periods.build_period(period)
+
+        if period is None:
+            raise ValueError(f"Invalid period value: {period}")
+
         if period.unit == periods.ETERNITY and self.variable.definition_period != periods.ETERNITY:
             error_message = os.linesep.join([
                 'Unable to set a value for variable {0} for periods.ETERNITY.',

openfisca_core/model_api.py

@@ -27,7 +27,7 @@
     ValuesHistory,
     )
 
-from openfisca_core.periods import DAY, MONTH, YEAR, ETERNITY, period  # noqa: F401
+from openfisca_core.periods import DAY, MONTH, YEAR, ETERNITY, build_period  # noqa: F401
 from openfisca_core.populations import ADD, DIVIDE  # noqa: F401
 from openfisca_core.reforms import Reform  # noqa: F401
 

openfisca_core/parameters/at_instant_like.py

@@ -12,7 +12,7 @@ def __call__(self, instant):
         return self.get_at_instant(instant)
 
     def get_at_instant(self, instant):
-        instant = str(periods.instant(instant))
+        instant = str(periods.build_instant(instant))
         return self._get_at_instant(instant)
 
     @abc.abstractmethod

openfisca_core/parameters/parameter.py

@@ -120,7 +120,7 @@ def update(self, period = None, start = None, stop = None, value = None):
             if start is not None or stop is not None:
                 raise TypeError("Wrong input for 'update' method: use either 'update(period, value = value)' or 'update(start = start, stop = stop, value = value)'. You cannot both use 'period' and 'start' or 'stop'.")
             if isinstance(period, str):
-                period = periods.period(period)
+                period = periods.build_period(period)
             start = period.start
             stop = period.stop
         if start is None:

openfisca_core/periods/__init__.py

@@ -1,45 +1,34 @@
-# Transitional imports to ensure non-breaking changes.
-# Could be deprecated in the next major release.
-#
-# How imports are being used today:
-#
-#   >>> from openfisca_core.module import symbol
-#
-# The previous example provokes cyclic dependency problems
-# that prevent us from modularizing the different components
-# of the library so to make them easier to test and to maintain.
-#
-# How could them be used after the next major release:
-#
-#   >>> from openfisca_core import module
-#   >>> module.symbol()
-#
-# And for classes:
-#
-#   >>> from openfisca_core.module import Symbol
-#   >>> Symbol()
-#
-# See: https://www.python.org/dev/peps/pep-0008/#imports
-
-from .config import (  # noqa: F401
-    DAY,
-    MONTH,
-    YEAR,
-    ETERNITY,
-    INSTANT_PATTERN,
-    date_by_instant_cache,
-    str_by_instant_cache,
-    year_or_month_or_day_re,
-    )
-
-from .helpers import (  # noqa: F401
-    instant,
-    instant_date,
-    period,
-    key_period_size,
-    unit_weights,
-    unit_weight,
-    )
-
-from .instant_ import Instant  # noqa: F401
-from .period_ import Period  # noqa: F401
+"""Transitional imports to ensure non-breaking changes.
+
+These imports could be deprecated in the next major release.
+
+Currently, imports are used in the following way::
+    from openfisca_core.module import symbol
+
+This example causes cyclic dependency problems, which prevent us from
+modularising the different components of the library and make them easier to
+test and maintain.
+
+After the next major release, imports could be used in the following way::
+    from openfisca_core import module
+    module.symbol()
+
+And for classes::
+    from openfisca_core.module import Symbol
+    Symbol()
+
+.. seealso:: `PEP8#Imports`_ and `OpenFisca's Styleguide`_.
+
+.. _PEP8#Imports:
+    https://www.python.org/dev/peps/pep-0008/#imports
+
+.. _OpenFisca's Styleguide:
+    https://github.com/openfisca/openfisca-core/blob/master/STYLEGUIDE.md
+
+"""
+
+from ._config import INSTANT_PATTERN
+from ._funcs import build_instant, build_period, key_period_size, parse_period
+from ._units import DAY, ETERNITY, MONTH, UNIT_WEIGHTS, YEAR
+from .instant import Instant
+from .period import Period

openfisca_core/periods/_config.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from typing import Pattern
+
+import re
+
+# Matches "2015", "2015-01", "2015-01-01"
+# Does not match "2015-13", "2015-12-32"
+INSTANT_PATTERN: Pattern[str] = re.compile(r"^\d{4}(-(0[1-9]|1[012]))?(-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01]))?$")

openfisca_core/periods/_errors.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ._units import DAY, MONTH, YEAR
+from .typing import Instant
+
+LEARN_MORE = (
+    "Learn more about legal period formats in OpenFisca: "
+    "<https://openfisca.org/doc/coding-the-legislation/35_html#periods-in-simulations>."
+    )
+
+
+class DateUnitValueError(ValueError):
+    """Raised when a date unit's value is not valid."""
+
+    def __init__(self, value: Any) -> None:
+        super().__init__(
+            f"'{value}' is not a valid ISO format date unit. ISO format date "
+            f"units are any of: '{DAY}', '{MONTH}', or '{YEAR}'. {LEARN_MORE}"
+            )
+
+
+class InstantFormatError(ValueError):
+    """Raised when an instant's format is not valid (ISO format)."""
+
+    def __init__(self, value: Any) -> None:
+        super().__init__(
+            f"'{value}' is not a valid instant. Instants are described using "
+            "the 'YYYY-MM-DD' format, for instance '2015-06-15'. {LEARN_MORE}"
+            )
+
+
+class InstantTypeError(TypeError):
+    """Raised when an instant's type is not valid."""
+
+    def __init__(self, value: Any) -> None:
+        super().__init__(
+            f"Invalid instant: {value} of type {type(value)}, expecting an "
+            f"{type(Instant)}. {LEARN_MORE}"
+            )
+
+
+class PeriodFormatError(ValueError):
+    """Raised when a period's format is not valid ."""
+
+    def __init__(self, value: Any) -> None:
+        super().__init__(
+            f"'{value}' is not a valid period. Periods are described using "
+            "the 'unit:YYYY-MM-DD:size' format, for instance "
+            f"'day:2023-01-15:3'. {LEARN_MORE}"
+            )
+
+
+class OffsetTypeError(TypeError):
+    """Raised when an offset's type is not valid."""
+
+    def __init__(self, value: Any) -> None:
+        super().__init__(
+            f"Invalid offset: {value} of type {type(value)}, expecting an "
+            f"{type(int)}. {LEARN_MORE}"
+            )