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

openfisca_core/indexed_enums/enum_array.py

@@ -0,0 +1,316 @@
+from __future__ import annotations
+
+from typing import NoReturn, Self
+
+import numpy
+
+from . import types as t
+
+
+class EnumArray(t.EnumArray):
+    """A subclass of :class:`~numpy.ndarray` of :class:`.Enum`.
+
+    :class:`.Enum` arrays are encoded as :class:`int` to improve performance.
+
+    Note:
+        Subclassing :class:`~numpy.ndarray` is a little tricky™. To read more
+        about the :meth:`.__new__` and :meth:`.__array_finalize__` methods
+        below, see `Subclassing ndarray`_.
+
+    Examples:
+        >>> import numpy
+
+        >>> from openfisca_core import indexed_enums as enum, variables
+
+        >>> class Housing(enum.Enum):
+        ...     OWNER = "Owner"
+        ...     TENANT = "Tenant"
+        ...     FREE_LODGER = "Free lodger"
+        ...     HOMELESS = "Homeless"
+
+        >>> array = numpy.array([1], dtype=numpy.int16)
+        >>> enum_array = enum.EnumArray(array, Housing)
+
+        >>> repr(enum.EnumArray)
+        "<class 'openfisca_core.indexed_enums.enum_array.EnumArray'>"
+
+        >>> repr(enum_array)
+        'EnumArray([Housing.TENANT])'
+
+        >>> str(enum_array)
+        "['TENANT']"
+
+        >>> list(map(int, enum_array))
+        [1]
+
+        >>> int(enum_array[0])
+        1
+
+        >>> enum_array[0] in enum_array
+        True
+
+        >>> len(enum_array)
+        1
+
+        >>> enum_array = enum.EnumArray(list(Housing), Housing)
+        Traceback (most recent call last):
+        AttributeError: 'list' object has no attribute 'view'
+
+        >>> class OccupancyStatus(variables.Variable):
+        ...     value_type = enum.Enum
+        ...     possible_values = Housing
+
+        >>> enum.EnumArray(array, OccupancyStatus.possible_values)
+        EnumArray([Housing.TENANT])
+
+    .. _Subclassing ndarray:
+        https://numpy.org/doc/stable/user/basics.subclassing.html
+
+    """
+
+    #: Enum type of the array items.
+    possible_values: None | type[t.Enum]
+
+    def __new__(
+        cls,
+        input_array: t.IndexArray,
+        possible_values: type[t.Enum],
+    ) -> Self:
+        """See comment above."""
+        obj = input_array.view(cls)
+        obj.possible_values = possible_values
+        return obj
+
+    def __array_finalize__(self, obj: None | t.EnumArray | t.VarArray) -> None:
+        """See comment above."""
+        if obj is None:
+            return
+        self.possible_values = getattr(obj, "possible_values", None)
+
+    def __eq__(self, other: object) -> t.BoolArray:  # type: ignore[override]
+        """Compare equality with the item's :attr:`~.Enum.index`.
+
+        When comparing to an item of :attr:`.possible_values`, use the
+        item's :attr:`~.Enum.index`. to speed up the comparison.
+
+        Whenever possible, use :any:`numpy.ndarray.view` so that the result is
+        a classic :class:`~numpy.ndarray`, not an :obj:`.EnumArray`.
+
+        Args:
+            other: Another :class:`object` to compare to.
+
+        Returns:
+            bool: When ???
+            ndarray[bool_]: When ???
+
+        Examples:
+            >>> import numpy
+
+            >>> from openfisca_core import indexed_enums as enum
+
+            >>> class Housing(enum.Enum):
+            ...     OWNER = "Owner"
+            ...     TENANT = "Tenant"
+
+            >>> array = numpy.array([1])
+            >>> enum_array = enum.EnumArray(array, Housing)
+
+            >>> enum_array == Housing
+            array([False,  True])
+
+            >>> enum_array == Housing.TENANT
+            array([ True])
+
+            >>> enum_array == 1
+            array([ True])
+
+            >>> enum_array == [1]
+            array([ True])
+
+            >>> enum_array == [2]
+            array([False])
+
+            >>> enum_array == "1"
+            array([False])
+
+            >>> enum_array is None
+            False
+
+            >>> enum_array == enum.EnumArray(numpy.array([1]), Housing)
+            array([ True])
+
+        Note:
+            This breaks the `Liskov substitution principle`_.
+
+        .. _Liskov substitution principle:
+            https://en.wikipedia.org/wiki/Liskov_substitution_principle
+
+        """
+        result: t.BoolArray
+
+        if self.possible_values is None:
+            return NotImplemented
+        if other is None:
+            return NotImplemented
+        if isinstance(other, type(t.Enum)) and other == self.possible_values:
+            result = (
+                self.view(numpy.ndarray)
+                == self.possible_values.indices[
+                    self.possible_values.indices <= max(self)
+                ]
+            )
+            return result
+        if isinstance(other, t.Enum) and other.__class__ == self.possible_values:
+            result = self.view(numpy.ndarray) == other.index
+            return result
+        # For NumPy >=1.26.x.
+        if isinstance(is_equal := self.view(numpy.ndarray) == other, numpy.ndarray):
+            return is_equal
+        # For NumPy <1.26.x.
+        return numpy.array([is_equal], dtype=t.BoolDType)
+
+    def __ne__(self, other: object) -> t.BoolArray:  # type: ignore[override]
+        """Inequality.
+
+        Args:
+            other: Another :class:`object` to compare to.
+
+        Returns:
+            bool: When ???
+            ndarray[bool_]: When ???
+
+        Examples:
+            >>> import numpy
+
+            >>> from openfisca_core import indexed_enums as enum
+
+            >>> class Housing(enum.Enum):
+            ...     OWNER = "Owner"
+            ...     TENANT = "Tenant"
+
+            >>> array = numpy.array([1])
+            >>> enum_array = enum.EnumArray(array, Housing)
+
+            >>> enum_array != Housing
+            array([ True, False])
+
+            >>> enum_array != Housing.TENANT
+            array([False])
+
+            >>> enum_array != 1
+            array([False])
+
+            >>> enum_array != [1]
+            array([False])
+
+            >>> enum_array != [2]
+            array([ True])
+
+            >>> enum_array != "1"
+            array([ True])
+
+            >>> enum_array is not None
+            True
+
+        Note:
+            This breaks the `Liskov substitution principle`_.
+
+        .. _Liskov substitution principle:
+            https://en.wikipedia.org/wiki/Liskov_substitution_principle
+
+        """
+        return numpy.logical_not(self == other)
+
+    @staticmethod
+    def _forbidden_operation(*__args: object, **__kwds: object) -> NoReturn:
+        msg = (
+            "Forbidden operation. The only operations allowed on EnumArrays "
+            "are '==' and '!='."
+        )
+        raise TypeError(msg)
+
+    __add__ = _forbidden_operation
+    __mul__ = _forbidden_operation
+    __lt__ = _forbidden_operation
+    __le__ = _forbidden_operation
+    __gt__ = _forbidden_operation
+    __ge__ = _forbidden_operation
+    __and__ = _forbidden_operation
+    __or__ = _forbidden_operation
+
+    def decode(self) -> t.ObjArray:
+        """Decode itself to a normal array.
+
+        Returns:
+            ndarray[Enum]: The items of the :obj:`.EnumArray`.
+
+        Raises:
+            TypeError: When the :attr:`.possible_values` is not defined.
+
+        Examples:
+            >>> import numpy
+
+            >>> from openfisca_core import indexed_enums as enum
+
+            >>> class Housing(enum.Enum):
+            ...     OWNER = "Owner"
+            ...     TENANT = "Tenant"
+
+            >>> array = numpy.array([1])
+            >>> enum_array = enum.EnumArray(array, Housing)
+            >>> enum_array.decode()
+            array([Housing.TENANT], dtype=object)
+
+        """
+        result: t.ObjArray
+        if self.possible_values is None:
+            msg = (
+                f"The possible values of the {self.__class__.__name__} are not defined."
+            )
+            raise TypeError(msg)
+        array = self.reshape(1).astype(t.EnumDType) if self.ndim == 0 else self
+        result = self.possible_values.enums[array]
+        return result
+
+    def decode_to_str(self) -> t.StrArray:
+        """Decode itself to an array of strings.
+
+        Returns:
+            ndarray[str_]: The string values of the :obj:`.EnumArray`.
+
+        Raises:
+            TypeError: When the :attr:`.possible_values` is not defined.
+
+        Examples:
+            >>> import numpy
+
+            >>> from openfisca_core import indexed_enums as enum
+
+            >>> class Housing(enum.Enum):
+            ...     OWNER = "Owner"
+            ...     TENANT = "Tenant"
+
+            >>> array = numpy.array([1])
+            >>> enum_array = enum.EnumArray(array, Housing)
+            >>> enum_array.decode_to_str()
+            array(['TENANT'], dtype='<U6')
+
+        """
+        result: t.StrArray
+        if self.possible_values is None:
+            msg = (
+                f"The possible values of the {self.__class__.__name__} are not defined."
+            )
+            raise TypeError(msg)
+        array = self.reshape(1).astype(t.EnumDType) if self.ndim == 0 else self
+        result = self.possible_values.names[array]
+        return result
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.decode()!s})"
+
+    def __str__(self) -> str:
+        return str(self.decode_to_str())
+
+
+__all__ = ["EnumArray"]

openfisca_core/indexed_enums/tests/test_enum.py

@@ -0,0 +1,135 @@
+import numpy
+import pytest
+from numpy.testing import assert_array_equal
+
+from openfisca_core import indexed_enums as enum
+
+
+class Animal(enum.Enum):
+    CAT = b"Cat"
+    DOG = b"Dog"
+
+
+class Colour(enum.Enum):
+    INCARNADINE = "incarnadine"
+    TURQUOISE = "turquoise"
+    AMARANTH = "amaranth"
+
+
+# Arrays of Enum
+
+
+def test_enum_encode_with_array_of_enum():
+    """Does encode when called with an array of enums."""
+    array = numpy.array([Animal.DOG, Animal.DOG, Animal.CAT])
+    enum_array = Animal.encode(array)
+    assert_array_equal(enum_array, numpy.array([1, 1, 0]))
+
+
+def test_enum_encode_with_enum_sequence():
+    """Does encode when called with an enum sequence."""
+    sequence = list(Animal)
+    enum_array = Animal.encode(sequence)
+    assert Animal.DOG in enum_array
+
+
+def test_enum_encode_with_enum_scalar_array():
+    """Does not encode when called with an enum scalar array."""
+    array = numpy.array(Animal.DOG)
+    with pytest.raises(TypeError):
+        Animal.encode(array)
+
+
+def test_enum_encode_with_enum_with_bad_value():
+    """Does not encode when called with a value not in an Enum."""
+    array = numpy.array([Colour.AMARANTH])
+    with pytest.raises(TypeError):
+        Animal.encode(array)
+
+
+# Arrays of int
+
+
+def test_enum_encode_with_array_of_int():
+    """Does encode when called with an array of int."""
+    array = numpy.array([1, 1, 0])
+    enum_array = Animal.encode(array)
+    assert_array_equal(enum_array, numpy.array([1, 1, 0]))
+
+
+def test_enum_encode_with_int_sequence():
+    """Does encode when called with an int sequence."""
+    sequence = (0, 1)
+    enum_array = Animal.encode(sequence)
+    assert Animal.DOG in enum_array
+
+
+def test_enum_encode_with_int_scalar_array():
+    """Does not encode when called with an int scalar array."""
+    array = numpy.array(1)
+    with pytest.raises(TypeError):
+        Animal.encode(array)
+
+
+def test_enum_encode_with_int_with_bad_value():
+    """Does not encode when called with a value not in an Enum."""
+    array = numpy.array([2])
+    with pytest.raises(IndexError):
+        Animal.encode(array)
+
+
+# Arrays of strings
+
+
+def test_enum_encode_with_array_of_string():
+    """Does encode when called with an array of string."""
+    array = numpy.array(["DOG", "DOG", "CAT"])
+    enum_array = Animal.encode(array)
+    assert_array_equal(enum_array, numpy.array([1, 1, 0]))
+
+
+def test_enum_encode_with_str_sequence():
+    """Does encode when called with a str sequence."""
+    sequence = ("DOG", "CAT")
+    enum_array = Animal.encode(sequence)
+    assert Animal.DOG in enum_array
+
+
+def test_enum_encode_with_str_scalar_array():
+    """Does not encode when called with a str scalar array."""
+    array = numpy.array("DOG")
+    with pytest.raises(TypeError):
+        Animal.encode(array)
+
+
+def test_enum_encode_with_str_with_bad_value():
+    """Encode encode when called with a value not in an Enum."""
+    array = numpy.array(["JAIBA"])
+    with pytest.raises(IndexError):
+        Animal.encode(array)
+
+
+# Unsupported encodings
+
+
+def test_enum_encode_with_any_array():
+    """Does not encode when called with unsupported types."""
+    value = {"animal": "dog"}
+    array = numpy.array([value])
+    with pytest.raises(TypeError):
+        Animal.encode(array)
+
+
+def test_enum_encode_with_any_scalar_array():
+    """Does not encode when called with unsupported types."""
+    value = 1.5
+    array = numpy.array(value)
+    with pytest.raises(TypeError):
+        Animal.encode(array)
+
+
+def test_enum_encode_with_any_sequence():
+    """Does not encode when called with unsupported types."""
+    sequence = memoryview(b"DOG")
+    with pytest.raises(IndexError):
+        Animal.encode(sequence)

openfisca_core/indexed_enums/tests/test_enum_array.py

@@ -0,0 +1,30 @@
+import numpy
+import pytest
+
+from openfisca_core import indexed_enums as enum
+
+
+class Fruit(enum.Enum):
+    APPLE = b"apple"
+    BERRY = b"berry"
+
+
+@pytest.fixture
+def enum_array():
+    return enum.EnumArray(numpy.array([1]), Fruit)
+
+
+def test_enum_array_eq_operation(enum_array):
+    """The equality operation is permitted."""
+    assert enum_array == enum.EnumArray(numpy.array([1]), Fruit)
+
+
+def test_enum_array_ne_operation(enum_array):
+    """The non-equality operation is permitted."""
+    assert enum_array != enum.EnumArray(numpy.array([0]), Fruit)
+
+
+def test_enum_array_any_other_operation(enum_array):
+    """Only equality and non-equality operations are permitted."""
+    with pytest.raises(TypeError, match="Forbidden operation."):
+        enum_array * 1

openfisca_core/indexed_enums/types.py

@@ -0,0 +1,49 @@
+from enum import _EnumDict as EnumDict
+from typing import TypeAlias
+
+from numpy import (
+    bool_ as BoolDType,
+)
+from numpy import (
+    generic as VarDType,
+)
+from numpy import (
+    int32 as IntDType,
+)
+from numpy import (
+    object_ as ObjDType,
+)
+from numpy import (
+    str_ as StrDType,
+)
+
+from openfisca_core.types import Array, ArrayLike, DTypeLike, Enum, EnumArray, EnumType
+
+from .config import ENUM_ARRAY_DTYPE as EnumDType
+
+#: Type for enum indices arrays.
+IndexArray: TypeAlias = Array[EnumDType]
+
+#: Type for boolean arrays.
+BoolArray: TypeAlias = Array[BoolDType]
+
+#: Type for int arrays.
+IntArray: TypeAlias = Array[IntDType]
+
+#: Type for str arrays.
+StrArray: TypeAlias = Array[StrDType]
+
+#: Type for object arrays.
+ObjArray: TypeAlias = Array[ObjDType]
+
+#: Type for generic arrays.
+VarArray: TypeAlias = Array[VarDType]
+
+__all__ = [
+    "ArrayLike",
+    "DTypeLike",
+    "Enum",
+    "EnumArray",
+    "EnumDict",
+    "EnumType",
+]

openfisca_core/memory_config.py

@@ -0,0 +1,9 @@
+# The memory config module has been deprecated since X.X.X,
+# and will be removed in the future.
+#
+# Module's contents have been moved to the experimental module.
+#
+# The following are transitional imports to ensure non-breaking changes.
+# Could be deprecated in the next major release.
+
+from openfisca_core.experimental import MemoryConfig  # noqa: F401

openfisca_core/model_api.py

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

openfisca_core/parameters/__init__.py

@@ -0,0 +1,71 @@
+# 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 openfisca_core.errors import ParameterNotFound, ParameterParsingError
+
+from .at_instant_like import AtInstantLike
+from .config import (
+    ALLOWED_PARAM_TYPES,
+    COMMON_KEYS,
+    FILE_EXTENSIONS,
+    date_constructor,
+    dict_no_duplicate_constructor,
+)
+from .helpers import contains_nan, load_parameter_file
+from .parameter import Parameter
+from .parameter_at_instant import ParameterAtInstant
+from .parameter_node import ParameterNode
+from .parameter_node_at_instant import ParameterNodeAtInstant
+from .parameter_scale import ParameterScale
+from .parameter_scale import ParameterScale as Scale
+from .parameter_scale_bracket import (
+    ParameterScaleBracket,
+)
+from .parameter_scale_bracket import (
+    ParameterScaleBracket as Bracket,
+)
+from .values_history import ValuesHistory
+from .vectorial_parameter_node_at_instant import VectorialParameterNodeAtInstant
+
+__all__ = [
+    "ALLOWED_PARAM_TYPES",
+    "COMMON_KEYS",
+    "FILE_EXTENSIONS",
+    "AtInstantLike",
+    "Bracket",
+    "Parameter",
+    "ParameterAtInstant",
+    "ParameterNode",
+    "ParameterNodeAtInstant",
+    "ParameterNotFound",
+    "ParameterParsingError",
+    "ParameterScale",
+    "ParameterScaleBracket",
+    "Scale",
+    "ValuesHistory",
+    "VectorialParameterNodeAtInstant",
+    "contains_nan",
+    "date_constructor",
+    "dict_no_duplicate_constructor",
+    "load_parameter_file",
+]

openfisca_core/parameters/at_instant_like.py

@@ -0,0 +1,17 @@
+import abc
+
+from openfisca_core import periods
+
+
+class AtInstantLike(abc.ABC):
+    """Base class for various types of parameters implementing the at instant protocol."""
+
+    def __call__(self, instant):
+        return self.get_at_instant(instant)
+
+    def get_at_instant(self, instant):
+        instant = str(periods.instant(instant))
+        return self._get_at_instant(instant)
+
+    @abc.abstractmethod
+    def _get_at_instant(self, instant): ...