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

openfisca_core/parameters/parameter_scale.py

@@ -0,0 +1,121 @@
+import copy
+import os
+
+from openfisca_core import commons, parameters, tools
+from openfisca_core.errors import ParameterParsingError
+from openfisca_core.parameters import AtInstantLike, config, helpers
+from openfisca_core.taxscales import (
+    LinearAverageRateTaxScale,
+    MarginalAmountTaxScale,
+    MarginalRateTaxScale,
+    SingleAmountTaxScale,
+)
+
+
+class ParameterScale(AtInstantLike):
+    """A parameter scale (for instance a  marginal scale)."""
+
+    # 'unit' and 'reference' are only listed here for backward compatibility
+    _allowed_keys = config.COMMON_KEYS.union({"brackets"})
+
+    def __init__(self, name, data, file_path) -> None:
+        """:param name: name of the scale, eg "taxes.some_scale"
+        :param data: Data loaded from a YAML file. In case of a reform, the data can also be created dynamically.
+        :param file_path: File the parameter was loaded from.
+        """
+        self.name: str = name
+        self.file_path: str = file_path
+        helpers._validate_parameter(
+            self,
+            data,
+            data_type=dict,
+            allowed_keys=self._allowed_keys,
+        )
+        self.description: str = data.get("description")
+        self.metadata: dict = {}
+        helpers._set_backward_compatibility_metadata(self, data)
+        self.metadata.update(data.get("metadata", {}))
+
+        if not isinstance(data.get("brackets", []), list):
+            msg = f"Property 'brackets' of scale '{self.name}' must be of type array."
+            raise ParameterParsingError(
+                msg,
+                self.file_path,
+            )
+
+        brackets = []
+        for i, bracket_data in enumerate(data.get("brackets", [])):
+            bracket_name = helpers._compose_name(name, item_name=i)
+            bracket = parameters.ParameterScaleBracket(
+                name=bracket_name,
+                data=bracket_data,
+                file_path=file_path,
+            )
+            brackets.append(bracket)
+        self.brackets: list[parameters.ParameterScaleBracket] = brackets
+
+    def __getitem__(self, key):
+        if isinstance(key, int) and key < len(self.brackets):
+            return self.brackets[key]
+        raise KeyError(key)
+
+    def __repr__(self) -> str:
+        return os.linesep.join(
+            ["brackets:"]
+            + [
+                tools.indent("-" + tools.indent(repr(bracket))[1:])
+                for bracket in self.brackets
+            ],
+        )
+
+    def get_descendants(self):
+        return iter(())
+
+    def clone(self):
+        clone = commons.empty_clone(self)
+        clone.__dict__ = self.__dict__.copy()
+
+        clone.brackets = [bracket.clone() for bracket in self.brackets]
+        clone.metadata = copy.deepcopy(self.metadata)
+
+        return clone
+
+    def _get_at_instant(self, instant):
+        brackets = [bracket.get_at_instant(instant) for bracket in self.brackets]
+
+        if self.metadata.get("type") == "single_amount":
+            scale = SingleAmountTaxScale()
+            for bracket in brackets:
+                if "amount" in bracket._children and "threshold" in bracket._children:
+                    amount = bracket.amount
+                    threshold = bracket.threshold
+                    scale.add_bracket(threshold, amount)
+            return scale
+        if any("amount" in bracket._children for bracket in brackets):
+            scale = MarginalAmountTaxScale()
+            for bracket in brackets:
+                if "amount" in bracket._children and "threshold" in bracket._children:
+                    amount = bracket.amount
+                    threshold = bracket.threshold
+                    scale.add_bracket(threshold, amount)
+            return scale
+        if any("average_rate" in bracket._children for bracket in brackets):
+            scale = LinearAverageRateTaxScale()
+
+            for bracket in brackets:
+                if (
+                    "average_rate" in bracket._children
+                    and "threshold" in bracket._children
+                ):
+                    average_rate = bracket.average_rate
+                    threshold = bracket.threshold
+                    scale.add_bracket(threshold, average_rate)
+            return scale
+        scale = MarginalRateTaxScale()
+
+        for bracket in brackets:
+            if "rate" in bracket._children and "threshold" in bracket._children:
+                rate = bracket.rate
+                threshold = bracket.threshold
+                scale.add_bracket(threshold, rate)
+        return scale

openfisca_core/parameters/parameter_scale_bracket.py

@@ -0,0 +1,7 @@
+from openfisca_core.parameters import ParameterNode
+
+
+class ParameterScaleBracket(ParameterNode):
+    """A parameter scale bracket."""
+
+    _allowed_keys = {"amount", "threshold", "rate", "average_rate"}

openfisca_core/parameters/values_history.py

@@ -0,0 +1,5 @@
+from .parameter import Parameter
+
+
+class ValuesHistory(Parameter):
+    """Only for backward compatibility."""

openfisca_core/parameters/vectorial_parameter_node_at_instant.py

@@ -0,0 +1,179 @@
+from typing import NoReturn
+
+import numpy
+
+from openfisca_core import parameters
+from openfisca_core.indexed_enums import Enum, EnumArray
+
+
+class VectorialParameterNodeAtInstant:
+    def __init__(self, vector, name, instant_str) -> None:
+        self.vector = vector
+        self._name = name
+        self._instant_str = instant_str
+
+    @staticmethod
+    def _get_appropriate_subnode_function(k):
+        if isinstance(k, str):
+            return VectorialParameterNodeAtInstant._get_appropriate_subnode_key_string
+        if isinstance(k, Enum):
+            return VectorialParameterNodeAtInstant._get_appropriate_subnode_key_enum
+        if isinstance(k, numpy.integer):
+            return VectorialParameterNodeAtInstant._get_appropriate_subnode_key_integer
+        return VectorialParameterNodeAtInstant._get_appropriate_subnode_key_date
+
+    @staticmethod
+    def _get_appropriate_subnode_key_string(node, k):
+        return k
+
+    @staticmethod
+    def _get_appropriate_subnode_key_enum(node, k):
+        return k.name
+
+    @staticmethod
+    def _get_appropriate_subnode_key_integer(node, k):
+        return str(k)
+
+    @staticmethod
+    def _get_appropriate_subnode_key_date(node, k):
+        subnodes_name = list(node._children.keys())
+        names = [name for name in subnodes_name if not name.startswith("before")]
+        points_in_time = [
+            numpy.datetime64("-".join(name[len("after_") :].split("_")))
+            for name in names
+        ]
+        index = sum([name <= k for name in points_in_time])
+        return subnodes_name[index]
+
+    def _get_appropriate_keys(key):
+        if isinstance(key, EnumArray):
+            enum = key.possible_values
+            result = numpy.select(
+                [key == item.index for item in enum],
+                [item.name for item in enum],
+                default="",
+            )
+            if numpy.any(result == ""):
+                invalid_indices = key[result == ""]
+                enum_name = enum.__name__ if enum is not None else "Unknown"
+                msg = f"Invalid enum index in EnumArray for {enum_name}: {invalid_indices}"
+                raise ValueError(msg)
+            return result
+        if key.dtype == object and issubclass(type(key[0]), Enum):
+            return key
+        return key
+
+    @staticmethod
+    def build_from_node_name(node, key):
+        VectorialParameterNodeAtInstant.check_node_vectorisable(node)
+        keys = VectorialParameterNodeAtInstant._get_appropriate_keys(key)
+        get_subnode_key = (
+            VectorialParameterNodeAtInstant._get_appropriate_subnode_function(keys[0])
+        )
+        nodes = [node[get_subnode_key(node, key)] for key in keys]
+        return VectorialParameterNodeAtInstant.build_from_nodes(node, nodes)
+
+    @staticmethod
+    def build_from_nodes(node, nodes):
+        if isinstance(nodes[0], parameters.ParameterNodeAtInstant):
+            return VectorialParameterNodeAtInstant(nodes, node._name, node._instant_str)
+        return numpy.array(nodes)
+
+    def __getattr__(self, attribute):
+        return self[attribute]
+
+    def __getitem__(self, key):
+        if isinstance(key, str):
+            keys = [key for v in self.vector]
+        elif isinstance(key[0], Enum):
+            keys = [k.name for k in key]
+        elif isinstance(key, EnumArray):
+            keys = [key.possible_values.names[v] for v in key]
+        else:
+            keys = key
+
+        nodes = [v[a] for (v, a) in zip(self.vector, keys)]
+        return VectorialParameterNodeAtInstant.build_from_nodes(self, nodes)
+
+    @staticmethod
+    def check_node_vectorisable(node) -> None:
+        """Check that a node can be casted to a vectorial node, in order to be able to use fancy indexing."""
+        MESSAGE_PART_1 = "Cannot use fancy indexing on parameter node '{}', as"
+        MESSAGE_PART_3 = (
+            "To use fancy indexing on parameter node, its children must be homogeneous."
+        )
+        MESSAGE_PART_4 = "See more at <https://openfisca.org/doc/coding-the-legislation/legislation_parameters#computing-a-parameter-that-depends-on-a-variable-fancy-indexing>."
+
+        def raise_key_inhomogeneity_error(
+            node_with_key, node_without_key, missing_key
+        ) -> NoReturn:
+            message = f"{MESSAGE_PART_1} '{{}}' exists, but '{{}}' doesn't. {MESSAGE_PART_3} {MESSAGE_PART_4}".format(
+                node._name,
+                f"{node_with_key}.{missing_key}",
+                f"{node_without_key}.{missing_key}",
+            )
+
+            raise ValueError(message)
+
+        def raise_type_inhomogeneity_error(node_name, non_node_name) -> NoReturn:
+            message = f"{MESSAGE_PART_1} '{{}}' is a node, but '{{}}' is not. {MESSAGE_PART_3} {MESSAGE_PART_4}".format(
+                node._name,
+                node_name,
+                non_node_name,
+            )
+
+            raise ValueError(message)
+
+        def raise_not_implemented(node_name, node_type) -> NoReturn:
+            message = f"{MESSAGE_PART_1} '{{}}' is a '{{}}', and fancy indexing has not been implemented yet on this kind of parameters. {MESSAGE_PART_4}".format(
+                node._name,
+                node_name,
+                node_type,
+            )
+            raise NotImplementedError(message)
+
+        def extract_named_children(node):
+            return {
+                f"{node._name}.{key}": value for key, value in node._children.items()
+            }
+
+        def check_nodes_homogeneous(named_nodes) -> None:
+            """Check than several nodes (or parameters, or baremes) have the same structure."""
+            names = list(named_nodes.keys())
+            nodes = list(named_nodes.values())
+            first_node = nodes[0]
+            first_name = names[0]
+            if isinstance(first_node, parameters.ParameterNodeAtInstant):
+                children = extract_named_children(first_node)
+                for subnode, name in list(zip(nodes, names))[1:]:
+                    if not isinstance(subnode, parameters.ParameterNodeAtInstant):
+                        raise_type_inhomogeneity_error(first_name, name)
+                    first_node_keys = first_node._children.keys()
+                    node_keys = subnode._children.keys()
+                    if first_node_keys != node_keys:
+                        missing_keys = set(first_node_keys).difference(node_keys)
+                        if missing_keys:  # If the first_node has a key that node hasn't
+                            raise_key_inhomogeneity_error(
+                                first_name,
+                                name,
+                                missing_keys.pop(),
+                            )
+                        else:  # If If the node has a key that first_node doesn't have
+                            missing_key = (
+                                set(node_keys).difference(first_node_keys).pop()
+                            )
+                            raise_key_inhomogeneity_error(name, first_name, missing_key)
+                    children.update(extract_named_children(subnode))
+                check_nodes_homogeneous(children)
+            elif isinstance(first_node, (float, int, str)):
+                for subnode, name in list(zip(nodes, names))[1:]:
+                    if isinstance(subnode, (int, float, str)):
+                        pass
+                    elif isinstance(subnode, parameters.ParameterNodeAtInstant):
+                        raise_type_inhomogeneity_error(name, first_name)
+                    else:
+                        raise_not_implemented(name, type(subnode).__name__)
+            else:
+                raise_not_implemented(first_name, type(first_node).__name__)
+
+        check_nodes_homogeneous(extract_named_children(node))

openfisca_core/periods/__init__.py

@@ -0,0 +1,77 @@
+# 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 ._errors import InstantError, ParserError, PeriodError
+from .config import (
+    INSTANT_PATTERN,
+    date_by_instant_cache,
+    str_by_instant_cache,
+    year_or_month_or_day_re,
+)
+from .date_unit import DateUnit
+from .helpers import (
+    instant,
+    instant_date,
+    key_period_size,
+    period,
+    unit_weight,
+    unit_weights,
+)
+from .instant_ import Instant
+from .period_ import Period
+
+WEEKDAY = DateUnit.WEEKDAY
+WEEK = DateUnit.WEEK
+DAY = DateUnit.DAY
+MONTH = DateUnit.MONTH
+YEAR = DateUnit.YEAR
+ETERNITY = DateUnit.ETERNITY
+ISOFORMAT = DateUnit.isoformat
+ISOCALENDAR = DateUnit.isocalendar
+
+__all__ = [
+    "DAY",
+    "ETERNITY",
+    "INSTANT_PATTERN",
+    "ISOCALENDAR",
+    "ISOFORMAT",
+    "MONTH",
+    "WEEK",
+    "WEEKDAY",
+    "YEAR",
+    "DateUnit",
+    "Instant",
+    "InstantError",
+    "ParserError",
+    "Period",
+    "PeriodError",
+    "date_by_instant_cache",
+    "instant",
+    "instant_date",
+    "key_period_size",
+    "period",
+    "str_by_instant_cache",
+    "unit_weight",
+    "unit_weights",
+    "year_or_month_or_day_re",
+]

openfisca_core/periods/_errors.py

@@ -0,0 +1,28 @@
+from pendulum.parsing.exceptions import ParserError
+
+
+class InstantError(ValueError):
+    """Raised when an invalid instant-like is provided."""
+
+    def __init__(self, value: str) -> None:
+        msg = (
+            f"'{value}' is not a valid instant string. Instants are described "
+            "using either the 'YYYY-MM-DD' format, for instance '2015-06-15', "
+            "or the 'YYYY-Www-D' format, for instance '2015-W24-1'."
+        )
+        super().__init__(msg)
+
+
+class PeriodError(ValueError):
+    """Raised when an invalid period-like is provided."""
+
+    def __init__(self, value: str) -> None:
+        msg = (
+            "Expected a period (eg. '2017', 'month:2017-01', 'week:2017-W01-1:3', "
+            f"...); got: '{value}'. Learn more about legal period formats in "
+            "OpenFisca: <https://openfisca.org/doc/coding-the-legislation/35_periods.html#periods-in-simulations>."
+        )
+        super().__init__(msg)
+
+
+__all__ = ["InstantError", "ParserError", "PeriodError"]

openfisca_core/periods/_parsers.py

@@ -0,0 +1,122 @@
+"""To parse periods and instants from strings."""
+
+from __future__ import annotations
+
+import datetime
+
+import pendulum
+
+from openfisca_core import types as t
+
+from ._errors import InstantError, ParserError, PeriodError
+from .date_unit import DateUnit
+from .instant_ import Instant
+from .period_ import Period
+
+
+def parse_instant(value: str) -> t.Instant:
+    """Parse a string into an instant.
+
+    Args:
+        value (str): The string to parse.
+
+    Returns:
+        An InstantStr.
+
+    Raises:
+        InstantError: When the string is not a valid ISO Calendar/Format.
+        ParserError: When the string couldn't be parsed.
+
+    Examples:
+        >>> parse_instant("2022")
+        Instant((2022, 1, 1))
+
+        >>> parse_instant("2022-02")
+        Instant((2022, 2, 1))
+
+        >>> parse_instant("2022-W02-7")
+        Instant((2022, 1, 16))
+
+        >>> parse_instant("2022-W013")
+        Traceback (most recent call last):
+        openfisca_core.periods._errors.InstantError: '2022-W013' is not a va...
+
+        >>> parse_instant("2022-02-29")
+        Traceback (most recent call last):
+        pendulum.parsing.exceptions.ParserError: Unable to parse string [202...
+
+    """
+
+    if not isinstance(value, t.InstantStr):
+        raise InstantError(str(value))
+
+    date = pendulum.parse(value, exact=True)
+
+    if not isinstance(date, datetime.date):
+        msg = f"Unable to parse string [{value}]"
+        raise ParserError(msg)
+
+    return Instant((date.year, date.month, date.day))
+
+
+def parse_period(value: str) -> t.Period:
+    """Parses ISO format/calendar periods.
+
+    Such as "2012" or "2015-03".
+
+    Examples:
+        >>> parse_period("2022")
+        Period((<DateUnit.YEAR: 'year'>, Instant((2022, 1, 1)), 1))
+
+        >>> parse_period("2022-02")
+        Period((<DateUnit.MONTH: 'month'>, Instant((2022, 2, 1)), 1))
+
+        >>> parse_period("2022-W02-7")
+        Period((<DateUnit.WEEKDAY: 'weekday'>, Instant((2022, 1, 16)), 1))
+
+    """
+
+    try:
+        instant = parse_instant(value)
+
+    except InstantError as error:
+        raise PeriodError(value) from error
+
+    unit = parse_unit(value)
+
+    return Period((unit, instant, 1))
+
+
+def parse_unit(value: str) -> t.DateUnit:
+    """Determine the date unit of a date string.
+
+    Args:
+        value (str): The date string to parse.
+
+    Returns:
+        A DateUnit.
+
+    Raises:
+        InstantError: when no DateUnit can be determined.
+
+    Examples:
+        >>> parse_unit("2022")
+        <DateUnit.YEAR: 'year'>
+
+        >>> parse_unit("2022-W03-1")
+        <DateUnit.WEEKDAY: 'weekday'>
+
+    """
+
+    if not isinstance(value, t.InstantStr):
+        raise InstantError(str(value))
+
+    length = len(value.split("-"))
+
+    if isinstance(value, t.ISOCalendarStr):
+        return DateUnit.isocalendar[-length]
+
+    return DateUnit.isoformat[-length]
+
+
+__all__ = ["parse_instant", "parse_period", "parse_unit"]

openfisca_core/periods/config.py

@@ -0,0 +1,20 @@
+import re
+
+import pendulum
+
+from openfisca_core import types as t
+
+# Matches "2015", "2015-01", "2015-01-01"
+# Does not match "2015-13", "2015-12-32"
+INSTANT_PATTERN = re.compile(
+    r"^\d{4}(-(0[1-9]|1[012]))?(-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01]))?$",
+)
+
+date_by_instant_cache: dict[t.Instant, pendulum.Date] = {}
+str_by_instant_cache: dict[t.Instant, t.InstantStr] = {}
+year_or_month_or_day_re = re.compile(
+    r"(18|19|20)\d{2}(-(0?[1-9]|1[0-2])(-([0-2]?\d|3[0-1]))?)?$",
+)
+
+
+__all__ = ["INSTANT_PATTERN", "date_by_instant_cache", "str_by_instant_cache"]

openfisca_core/periods/date_unit.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from enum import EnumMeta
+
+from strenum import StrEnum
+
+from openfisca_core import types as t
+
+
+class DateUnitMeta(EnumMeta):
+    @property
+    def isoformat(self) -> tuple[t.DateUnit, ...]:
+        """Creates a :obj:`tuple` of ``key`` with isoformat items.
+
+        Returns:
+            tuple(str): A :obj:`tuple` containing the ``keys``.
+
+        Examples:
+            >>> DateUnit.isoformat
+            (<DateUnit.DAY: 'day'>, <DateUnit.MONTH: 'month'>, <DateUnit.YE...)
+
+            >>> DateUnit.DAY in DateUnit.isoformat
+            True
+
+            >>> DateUnit.WEEK in DateUnit.isoformat
+            False
+
+        """
+        return DateUnit.DAY, DateUnit.MONTH, DateUnit.YEAR
+
+    @property
+    def isocalendar(self) -> tuple[t.DateUnit, ...]:
+        """Creates a :obj:`tuple` of ``key`` with isocalendar items.
+
+        Returns:
+            tuple(str): A :obj:`tuple` containing the ``keys``.
+
+        Examples:
+            >>> DateUnit.isocalendar
+            (<DateUnit.WEEKDAY: 'weekday'>, <DateUnit.WEEK: 'week'>, <DateU...)
+
+            >>> DateUnit.WEEK in DateUnit.isocalendar
+            True
+
+            >>> "day" in DateUnit.isocalendar
+            False
+
+        """
+        return DateUnit.WEEKDAY, DateUnit.WEEK, DateUnit.YEAR
+
+
+class DateUnit(StrEnum, metaclass=DateUnitMeta):
+    """The date units of a rule system.
+
+    Examples:
+        >>> repr(DateUnit)
+        "<enum 'DateUnit'>"
+
+        >>> repr(DateUnit.DAY)
+        "<DateUnit.DAY: 'day'>"
+
+        >>> str(DateUnit.DAY)
+        'day'
+
+        >>> dict([(DateUnit.DAY, DateUnit.DAY.value)])
+        {<DateUnit.DAY: 'day'>: 'day'}
+
+        >>> list(DateUnit)
+        [<DateUnit.WEEKDAY: 'weekday'>, <DateUnit.WEEK: 'week'>, <DateUnit.D...
+
+        >>> len(DateUnit)
+        6
+
+        >>> DateUnit["DAY"]
+        <DateUnit.DAY: 'day'>
+
+        >>> DateUnit(DateUnit.DAY)
+        <DateUnit.DAY: 'day'>
+
+        >>> DateUnit.DAY in DateUnit
+        True
+
+        >>> "day" in list(DateUnit)
+        True
+
+        >>> DateUnit.DAY == "day"
+        True
+
+        >>> DateUnit.DAY.name
+        'DAY'
+
+        >>> DateUnit.DAY.value
+        'day'
+
+    """
+
+    def __contains__(self, other: object) -> bool:
+        if isinstance(other, str):
+            return super().__contains__(other)
+        return NotImplemented
+
+    WEEKDAY = "weekday"
+    WEEK = "week"
+    DAY = "day"
+    MONTH = "month"
+    YEAR = "year"
+    ETERNITY = "eternity"
+
+
+__all__ = ["DateUnit"]