Add date units to periods

.github/get-numpy-version.py

@@ -2,13 +2,14 @@
 
 from __future__ import annotations
 
-import os
-import sys
 import typing
-from packaging import version
 from typing import NoReturn, Union
 
+import os
+import sys
+
 import numpy
+from packaging import version
 
 if typing.TYPE_CHECKING:
     from packaging.version import LegacyVersion, Version

CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 39.1.0 [#1139](https://github.com/openfisca/openfisca-core/pull/1139)
+
+#### New features
+
+- Introduce `DateUnit` to `periods`
+  - Allows for transparent encapsulation of the atomic units of `periods` (`year`, `month`, ...).
+  - This helps with testing, refactoring and exrtension of `periods` (`weeks` for example).
+
+
+# 39.0.0 [#1138](https://github.com/openfisca/openfisca-core/pull/1138)
+
+#### Breaking changes
+
+- Deprecate `instant_date`.
+- Deprecate `periods.intersect`.
+- Deprecate `periods.unit_weight`.
+- Deprecate `periods.unit_weights`.
+- Make `periods.parse_period` stricter (for example `2022-1` now fails).
+- Refactor `Period.contains` as `Period.__contains__`.
+- Rename `Period.get_subperiods` to `subperiods`.
+- Rename `instant` to `build_instant`.
+- Rename `period` to `build_period`.
+- Transform `Instant.date` from property to method.
+- Transform `Period.date` from property to method.
+
+#### Technical changes
+
+- Add typing to `openfisca_core.periods`.
+- Document `openfisca_core.periods`.
+- Fix `openfisca_core.periods` doctests.
+
+#### Bug fixes
+
+- Fixes impossible `last-of` and `first-of` offsets.
+- Fixes incoherent dates,
+- Fixes several race conditions,
+
 # 38.0.0 [#989](https://github.com/openfisca/openfisca-core/pull/989)
 
 #### New Features

openfisca_core/commons/formulas.py

@@ -1,9 +1,8 @@
+from openfisca_core.types import Array, ArrayLike
 from typing import Any, Dict, Sequence, TypeVar
 
 import numpy
 
-from openfisca_core.types import ArrayLike, Array
-
 T = TypeVar("T")
 
 

openfisca_core/commons/misc.py

@@ -1,6 +1,5 @@
-from typing import TypeVar
-
 from openfisca_core.types import Array
+from typing import TypeVar
 
 T = TypeVar("T")
 

openfisca_core/commons/rates.py

@@ -1,9 +1,8 @@
+from openfisca_core.types import Array, ArrayLike
 from typing import Optional
 
 import numpy
 
-from openfisca_core.types import ArrayLike, Array
-
 
 def average_rate(
         target: Array[float],

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.DateUnit.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.DateUnit.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.DateUnit.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

@@ -5,6 +5,7 @@
 
 from openfisca_core import periods
 from openfisca_core.indexed_enums import EnumArray
+from openfisca_core.periods import DateUnit
 
 
 class OnDiskStorage:
@@ -28,8 +29,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(DateUnit.ETERNITY)
+        period = periods.build_period(period)
 
         values = self._files.get(period)
         if values is None:
@@ -38,8 +39,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(DateUnit.ETERNITY)
+        period = periods.build_period(period)
 
         filename = str(period)
         path = os.path.join(self.storage_dir, filename) + '.npy'
@@ -55,14 +56,14 @@ def delete(self, period = None):
             return
 
         if self.is_eternal:
-            period = periods.period(periods.ETERNITY)
-        period = periods.period(period)
+            period = periods.build_period(DateUnit.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 +77,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/entities/__init__.py

@@ -21,7 +21,7 @@
 #
 # See: https://www.python.org/dev/peps/pep-0008/#imports
 
-from .helpers import build_entity  # noqa: F401
 from .role import Role  # noqa: F401
 from .entity import Entity  # noqa: F401
 from .group_entity import GroupEntity  # noqa: F401
+from .helpers import build_entity  # noqa: F401

openfisca_core/entities/entity.py

@@ -1,9 +1,9 @@
+from openfisca_core.types import TaxBenefitSystem, Variable
 from typing import Any, Optional
 
 import os
 import textwrap
 
-from openfisca_core.types import TaxBenefitSystem, Variable
 from openfisca_core.entities import Role
 
 

openfisca_core/errors/__init__.py

@@ -24,10 +24,13 @@
 from .cycle_error import CycleError  # noqa: F401
 from .empty_argument_error import EmptyArgumentError  # noqa: F401
 from .nan_creation_error import NaNCreationError  # noqa: F401
-from .parameter_not_found_error import ParameterNotFoundError, ParameterNotFoundError as ParameterNotFound  # noqa: F401
+from .parameter_not_found_error import ParameterNotFoundError  # noqa: F401
+from .parameter_not_found_error import ParameterNotFoundError as ParameterNotFound
 from .parameter_parsing_error import ParameterParsingError  # noqa: F401
 from .period_mismatch_error import PeriodMismatchError  # noqa: F401
 from .situation_parsing_error import SituationParsingError  # noqa: F401
 from .spiral_error import SpiralError  # noqa: F401
-from .variable_name_config_error import VariableNameConflictError, VariableNameConflictError as VariableNameConflict  # noqa: F401
-from .variable_not_found_error import VariableNotFoundError, VariableNotFoundError as VariableNotFound  # noqa: F401
+from .variable_name_config_error import VariableNameConflictError  # noqa: F401
+from .variable_name_config_error import VariableNameConflictError as VariableNameConflict
+from .variable_not_found_error import VariableNotFoundError  # noqa: F401
+from .variable_not_found_error import VariableNotFoundError as VariableNotFound

openfisca_core/errors/empty_argument_error.py

@@ -1,6 +1,7 @@
+import typing
+
 import os
 import traceback
-import typing
 
 import numpy
 

openfisca_core/formula_helpers.py

@@ -6,4 +6,8 @@
 # The following are transitional imports to ensure non-breaking changes.
 # Could be deprecated in the next major release.
 
-from openfisca_core.commons import apply_thresholds, concat, switch  # noqa: F401
+from openfisca_core.commons import (  # noqa: F401
+    apply_thresholds,
+    concat,
+    switch,
+    )

openfisca_core/holders/__init__.py

@@ -21,6 +21,9 @@
 #
 # See: https://www.python.org/dev/peps/pep-0008/#imports
 
-from .helpers import set_input_dispatch_by_period, set_input_divide_by_period  # noqa: F401
+from .helpers import (  # noqa: F401
+    set_input_dispatch_by_period,
+    set_input_divide_by_period,
+    )
 from .holder import Holder  # noqa: F401
 from .memory_usage import MemoryUsage  # noqa: F401

openfisca_core/holders/helpers.py

@@ -21,7 +21,7 @@ def set_input_dispatch_by_period(holder, period, array):
     period_size = period.size
     period_unit = period.unit
 
-    if holder.variable.definition_period == periods.ETERNITY:
+    if holder.variable.definition_period == periods.DateUnit.ETERNITY:
         raise ValueError("set_input_dispatch_by_period can't be used for eternal variables.")
 
     cached_period_unit = holder.variable.definition_period
@@ -53,7 +53,7 @@ def set_input_divide_by_period(holder, period, array):
     period_size = period.size
     period_unit = period.unit
 
-    if holder.variable.definition_period == periods.ETERNITY:
+    if holder.variable.definition_period == periods.DateUnit.ETERNITY:
         raise ValueError("set_input_divide_by_period can't be used for eternal variables.")
 
     cached_period_unit = holder.variable.definition_period

openfisca_core/holders/holder.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from openfisca_core.periods.typing import Period
 from typing import Any, Optional, Sequence, Union
 
 import os
@@ -8,15 +9,11 @@
 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
 
@@ -30,7 +27,7 @@ def __init__(self, variable, population):
         self.population = population
         self.variable = variable
         self.simulation = population.simulation
-        self._memory_storage = storage.InMemoryStorage(is_eternal = (self.variable.definition_period == periods.ETERNITY))
+        self._memory_storage = storage.InMemoryStorage(is_eternal = (self.variable.definition_period == periods.DateUnit.ETERNITY))
 
         # By default, do not activate on-disk storage, or variable dropping
         self._disk_storage = None
@@ -67,7 +64,7 @@ def create_disk_storage(self, directory = None, preserve = False):
             os.mkdir(storage_dir)
         return storage.OnDiskStorage(
             storage_dir,
-            is_eternal = (self.variable.definition_period == periods.ETERNITY),
+            is_eternal = (self.variable.definition_period == periods.DateUnit.ETERNITY),
             preserve_storage_dir = preserve
             )
 
@@ -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,10 +207,14 @@ def set_input(
 
         """
 
-        period = periods.period(period)
-        if period.unit == periods.ETERNITY and self.variable.definition_period != periods.ETERNITY:
+        period = periods.build_period(period)
+
+        if period is None:
+            raise ValueError(f"Invalid period value: {period}")
+
+        if period.unit == periods.DateUnit.ETERNITY and self.variable.definition_period != periods.DateUnit.ETERNITY:
             error_message = os.linesep.join([
-                'Unable to set a value for variable {0} for periods.ETERNITY.',
+                'Unable to set a value for variable {0} for DateUnit.ETERNITY.',
                 '{0} is only defined for {1}s. Please adapt your input.',
                 ]).format(
                     self.variable.name,
@@ -260,9 +261,9 @@ def _to_array(self, value):
 
     def _set(self, period, value):
         value = self._to_array(value)
-        if self.variable.definition_period != periods.ETERNITY:
+        if self.variable.definition_period != periods.DateUnit.ETERNITY:
             if period is None:
-                raise ValueError('A period must be specified to set values, except for variables with periods.ETERNITY as as period_definition.')
+                raise ValueError('A period must be specified to set values, except for variables with DateUnit.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'