test: encapsulate periods module

CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+# 39.0.0 [#1138](https://github.com/openfisca/openfisca-core/pull/1138)
+
+#### Breaking changes
+
+##### Renames
+
+- Rename `periods.period.get_subperiods` to `periods.period.subperiods`.
+
+##### Deprecations
+
+- Deprecate `INSTANT_PATTERN`
+  - The feature is now provided by `periods.parse`
+- Deprecate `instant_date`.
+  - The feature is now provided by `periods.instant.date`.
+- Deprecate `periods.{unit_weight, unit_weights, key_period_size}`.
+  - These features are now provided by `periods.dateunit`.
+- Deprecate `periods.intersect`.
+  - The feature has no replacement.
+- Make `periods.parse_period` stricter.
+  - For example `2022-1` now fails.
+- Refactor `periods.period.contains` as `__contains__`.
+  - For example `subperiod in period` is now possible.
+
+##### Structural changes
+
+- Transform `Period.date` from property to method.
+  - Now it has to be used as `period.date()` (note the parenthesis).
+- Transform `Instant.date` from property to method.
+  - Now it has to be used as `instant.date()` (note the parenthesis).
+- Rationalise the reference periods.
+  - Before, there was a definite list of reference periods. For example, 
+    `period.first_month` or `period.n_2`.
+  - This has been simplified to allow users to build their own:
+    - `period.ago(unit: DateUnit, size: int = 1) -> Period`.
+    - `period.last(unit: DateUnit, size: int = 1) -> Period`.
+    - `period.first(unit: DateUnit) -> Period`.
+- Rationalise date units.
+  - Before, usage of "month", YEAR, and so on was fairly inconsistent, and 
+    providing a perfect hotbed for bugs to breed.
+  - This has been fixed by introducing a new `dateunit` module, which 
+    provides a single source of truth for all date units.
+  - Note that if you used `periods.YEAR` and the like, there is nothing to 
+    change in your code.
+  - However, strings like `"year"` or `"ETERNITY"` are no longer allowed (in 
+    fact, date unit are int enums an no longer strings). 
+
+#### Technical changes
+
+- Add typing to `openfisca_core.periods`.
+- Fix `openfisca_core.periods` doctests.
+- Document `openfisca_core.periods`.
+
+#### Bug fixes
+
+- Fixes incoherent dates.
+- Fixes several race conditions.
+
 # 38.0.0 [#989](https://github.com/openfisca/openfisca-core/pull/989)
 
 #### New Features
@@ -35,7 +92,7 @@
 
 #### Migration details
 
-- Replace `some_period.start.period` and similar methods with `Period((unit, some_period.start, 1))`.
+- Replace `some_period.start.period` and similar methods with `Period(unit, some_period.start, 1)`.
 
 # 36.0.0 [#1149](https://github.com/openfisca/openfisca-core/pull/1162)
 

openfisca_core/data_storage/in_memory_storage.py

@@ -41,7 +41,7 @@ def delete(self, period = None):
         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

@@ -62,7 +62,7 @@ def delete(self, period = 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):

openfisca_core/holders/helpers.py

@@ -3,7 +3,6 @@
 import numpy
 
 from openfisca_core import periods
-from openfisca_core.periods import Period
 
 log = logging.getLogger(__name__)
 
@@ -28,7 +27,7 @@ def set_input_dispatch_by_period(holder, period, array):
     after_instant = period.start.offset(period_size, period_unit)
 
     # Cache the input data, skipping the existing cached months
-    sub_period = Period((cached_period_unit, period.start, 1))
+    sub_period = periods.Period(cached_period_unit, period.start, 1)
     while sub_period.start < after_instant:
         existing_array = holder.get_array(sub_period)
         if existing_array is None:
@@ -61,7 +60,7 @@ def set_input_divide_by_period(holder, period, array):
 
     # Count the number of elementary periods to change, and the difference with what is already known.
     remaining_array = array.copy()
-    sub_period = Period((cached_period_unit, period.start, 1))
+    sub_period = periods.Period(cached_period_unit, period.start, 1)
     sub_periods_count = 0
     while sub_period.start < after_instant:
         existing_array = holder.get_array(sub_period)
@@ -74,7 +73,7 @@ def set_input_divide_by_period(holder, period, array):
     # Cache the input data
     if sub_periods_count > 0:
         divided_array = remaining_array / sub_periods_count
-        sub_period = Period((cached_period_unit, period.start, 1))
+        sub_period = periods.Period(cached_period_unit, period.start, 1)
         while sub_period.start < after_instant:
             if holder.get_array(sub_period) is None:
                 holder._set(sub_period, divided_array)

openfisca_core/holders/holder.py

@@ -1,22 +1,18 @@
 from __future__ import annotations
 
-from typing import Any, Optional, Sequence, Union
+from typing import Any, Sequence
 
 import os
 import warnings
 
 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 .memory_usage import MemoryUsage
 
@@ -116,7 +112,7 @@ def get_memory_usage(self) -> MemoryUsage:
             >>> entity = entities.Entity("", "", "", "")
 
             >>> class MyVariable(variables.Variable):
-            ...     definition_period = "year"
+            ...     definition_period = periods.YEAR
             ...     entity = entity
             ...     value_type = int
 
@@ -164,9 +160,9 @@ def get_known_periods(self):
 
     def set_input(
             self,
-            period: types.Period,
-            array: Union[numpy.ndarray, Sequence[Any]],
-            ) -> Optional[numpy.ndarray]:
+            period: periods.Period,
+            array: numpy.ndarray | Sequence[Any],
+            ) -> numpy.ndarray | None:
         """Set a Variable's array of values of a given Period.
 
         Args:
@@ -187,7 +183,7 @@ def set_input(
             >>> entity = entities.Entity("", "", "", "")
 
             >>> class MyVariable(variables.Variable):
-            ...     definition_period = "year"
+            ...     definition_period = periods.YEAR
             ...     entity = entity
             ...     value_type = int
 
@@ -211,13 +207,17 @@ def set_input(
         """
 
         period = periods.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.',
                 '{0} is only defined for {1}s. Please adapt your input.',
                 ]).format(
                     self.variable.name,
-                    self.variable.definition_period
+                    str(self.variable.definition_period)
                 )
             raise errors.PeriodMismatchError(
                 self.variable.name,
@@ -265,10 +265,10 @@ def _set(self, period, value):
                 raise ValueError('A period must be specified to set values, except for variables with periods.ETERNITY as as period_definition.')
             if (self.variable.definition_period != period.unit or period.size > 1):
                 name = self.variable.name
-                period_size_adj = f'{period.unit}' if (period.size == 1) else f'{period.size}-{period.unit}s'
+                period_size_adj = f'{str(period.unit)}' if (period.size == 1) else f'{period.size}-{str(period.unit)}s'
                 error_message = os.linesep.join([
                     f'Unable to set a value for variable "{name}" for {period_size_adj}-long period "{period}".',
-                    f'"{name}" can only be set for one {self.variable.definition_period} at a time. Please adapt your input.',
+                    f'"{name}" can only be set for one {str(self.variable.definition_period)} at a time. Please adapt your input.',
                     f'If you are the maintainer of "{name}", you can consider adding it a set_input attribute to enable automatic period casting.'
                     ])
 

openfisca_core/holders/tests/test_helpers.py

@@ -3,7 +3,6 @@
 from openfisca_core import holders, periods, tools
 from openfisca_core.entities import Entity
 from openfisca_core.holders import Holder
-from openfisca_core.periods import Instant, Period
 from openfisca_core.populations import Population
 from openfisca_core.variables import Variable
 
@@ -58,8 +57,8 @@ def test_set_input_dispatch_by_period(
     Income.definition_period = definition_unit
     income = Income()
     holder = Holder(income, population)
-    instant = Instant((2022, 1, 1))
-    dispatch_period = Period((dispatch_unit, instant, 3))
+    instant = periods.Instant(2022, 1, 1)
+    dispatch_period = periods.Period(dispatch_unit, instant, 3)
 
     holders.set_input_dispatch_by_period(holder, dispatch_period, values)
     total = sum(map(holder.get_array, holder.get_known_periods()))
@@ -89,8 +88,8 @@ def test_set_input_divide_by_period(
     Income.definition_period = definition_unit
     income = Income()
     holder = Holder(income, population)
-    instant = Instant((2022, 1, 1))
-    divide_period = Period((divide_unit, instant, 3))
+    instant = periods.Instant(2022, 1, 1)
+    divide_period = periods.Period(divide_unit, instant, 3)
 
     holders.set_input_divide_by_period(holder, divide_period, values)
     last = holder.get_array(holder.get_known_periods()[-1])

openfisca_core/model_api.py

@@ -1,39 +1,34 @@
 from datetime import date  # noqa: F401
 
-from numpy import (   # noqa: F401
-    logical_not as not_,
-    maximum as max_,
-    minimum as min_,
-    round as round_,
-    select,
-    where,
+from numpy import logical_not as not_  # noqa: F401
+from numpy import maximum as max_  # noqa: F401
+from numpy import minimum as min_  # noqa: F401
+from numpy import round as round_  # noqa: F401
+from numpy import select, where  # noqa: F401
+
+from openfisca_core import periods  # noqa: F401
+from openfisca_core.commons import (  # noqa: F401
+    apply_thresholds,
+    concat,
+    switch,
     )
-
-from openfisca_core.commons import apply_thresholds, concat, switch  # noqa: F401
-
 from openfisca_core.holders import (  # noqa: F401
     set_input_dispatch_by_period,
     set_input_divide_by_period,
     )
-
 from openfisca_core.indexed_enums import Enum  # noqa: F401
-
 from openfisca_core.parameters import (  # noqa: F401
+    Bracket,
     load_parameter_file,
+    Parameter,
     ParameterNode,
     Scale,
-    Bracket,
-    Parameter,
     ValuesHistory,
     )
-
-from openfisca_core.periods import DAY, MONTH, YEAR, ETERNITY, period  # noqa: F401
 from openfisca_core.populations import ADD, DIVIDE  # noqa: F401
 from openfisca_core.reforms import Reform  # noqa: F401
-
 from openfisca_core.simulations import (  # noqa: F401
     calculate_output_add,
     calculate_output_divide,
     )
-
 from openfisca_core.variables import Variable  # noqa: F401

openfisca_core/parameters/helpers.py

@@ -63,7 +63,7 @@ def _parse_child(child_name, child, child_path):
         return parameters.Parameter(child_name, child, child_path)
     elif 'brackets' in child:
         return parameters.ParameterScale(child_name, child, child_path)
-    elif isinstance(child, dict) and all([periods.INSTANT_PATTERN.match(str(key)) for key in child.keys()]):
+    elif isinstance(child, dict) and all([periods.parse(str(key)) for key in child.keys()]):
         return parameters.Parameter(child_name, child, child_path)
     else:
         return parameters.ParameterNode(child_name, data = child, file_path = child_path)

openfisca_core/parameters/parameter.py

@@ -73,7 +73,7 @@ def __init__(self, name: str, data: dict, file_path: Optional[str] = None) -> No
 
         values_list = []
         for instant_str in instants:
-            if not periods.INSTANT_PATTERN.match(instant_str):
+            if periods.parse(instant_str) is None:
                 raise ParameterParsingError(
                     "Invalid property '{}' in '{}'. Properties must be valid YYYY-MM-DD instants, such as 2017-01-15."
                     .format(instant_str, self.name),
@@ -126,7 +126,7 @@ def update(self, period = None, start = None, stop = None, value = None):
         if start is None:
             raise ValueError("You must provide either a start or a period")
         start_str = str(start)
-        stop_str = str(stop.offset(1, 'day')) if stop else None
+        stop_str = str(stop.offset(1, periods.DAY)) if stop else None
 
         old_values = self.values_list
         new_values = []