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

openfisca_core/entities/role.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from . import types as t
+from ._description import _Description
+
+
+class Role:
+    """The role of an ``Entity`` within a ``GroupEntity``.
+
+    Each ``Entity`` related to a ``GroupEntity`` has a ``Role``. For example,
+    if you have a family, its roles could include a parent, a child, and so on.
+    Or if you have a tax household, its roles could include the taxpayer, a
+    spouse, several dependents, and the like.
+
+    Args:
+        description: A description of the Role.
+        entity: The Entity to which the Role belongs.
+
+    Examples:
+        >>> from openfisca_core import entities
+
+        >>> entity = entities.GroupEntity("key", "plural", "label", "doc", [])
+        >>> role = entities.Role({"key": "parent"}, entity)
+
+        >>> repr(entities.Role)
+        "<class 'openfisca_core.entities.role.Role'>"
+
+        >>> repr(role)
+        'Role(parent)'
+
+        >>> str(role)
+        'Role(parent)'
+
+        >>> {role}
+        {Role(parent)}
+
+        >>> role.key
+        'parent'
+
+    """
+
+    #: The ``GroupEntity`` the Role belongs to.
+    entity: t.GroupEntity
+
+    #: A description of the ``Role``.
+    description: _Description
+
+    #: Max number of members.
+    max: None | int = None
+
+    #: A list of subroles.
+    subroles: None | Iterable[Role] = None
+
+    @property
+    def key(self) -> t.RoleKey:
+        """A key to identify the ``Role``."""
+        return t.RoleKey(self.description.key)
+
+    @property
+    def plural(self) -> None | t.RolePlural:
+        """The ``key`` pluralised."""
+        if (plural := self.description.plural) is None:
+            return None
+        return t.RolePlural(plural)
+
+    @property
+    def label(self) -> None | str:
+        """A summary description."""
+        return self.description.label
+
+    @property
+    def doc(self) -> None | str:
+        """A full description, non-indented."""
+        return self.description.doc
+
+    def __init__(self, description: t.RoleParams, entity: t.GroupEntity) -> None:
+        self.description = _Description(
+            key=description["key"],
+            plural=description.get("plural"),
+            label=description.get("label"),
+            doc=description.get("doc"),
+        )
+        self.entity = entity
+        self.max = description.get("max")
+
+    def __repr__(self) -> str:
+        return f"Role({self.key})"
+
+
+__all__ = ["Role"]

openfisca_core/entities/tests/test_entity.py

@@ -0,0 +1,10 @@
+from openfisca_core import entities
+
+
+def test_init_when_doc_indented() -> None:
+    """De-indent the ``doc`` attribute if it is passed at initialisation."""
+    key = "\tkey"
+    doc = "\tdoc"
+    entity = entities.Entity(key, "label", "plural", doc)
+    assert entity.key == key
+    assert entity.doc == doc.lstrip()

openfisca_core/entities/tests/test_group_entity.py

@@ -0,0 +1,70 @@
+from collections.abc import Mapping
+from typing import Any
+
+import pytest
+
+from openfisca_core import entities
+
+
+@pytest.fixture
+def parent() -> str:
+    return "parent"
+
+
+@pytest.fixture
+def uncle() -> str:
+    return "uncle"
+
+
+@pytest.fixture
+def first_parent() -> str:
+    return "first_parent"
+
+
+@pytest.fixture
+def second_parent() -> str:
+    return "second_parent"
+
+
+@pytest.fixture
+def third_parent() -> str:
+    return "third_parent"
+
+
+@pytest.fixture
+def role(parent: str, first_parent: str, third_parent: str) -> Mapping[str, Any]:
+    return {"key": parent, "subroles": {first_parent, third_parent}}
+
+
+@pytest.fixture
+def group_entity(role: Mapping[str, Any]) -> entities.GroupEntity:
+    return entities.GroupEntity("key", "label", "plural", "doc", (role,))
+
+
+def test_init_when_doc_indented() -> None:
+    """De-indent the ``doc`` attribute if it is passed at initialisation."""
+    key = "\tkey"
+    doc = "\tdoc"
+    group_entity = entities.GroupEntity(key, "label", "plural", doc, ())
+    assert group_entity.key == key
+    assert group_entity.doc == doc.lstrip()
+
+
+def test_group_entity_with_roles(
+    group_entity: entities.GroupEntity,
+    parent: str,
+    uncle: str,
+) -> None:
+    """Assign a Role for each role-like passed as argument."""
+    assert hasattr(group_entity, parent.upper())
+    assert not hasattr(group_entity, uncle.upper())
+
+
+def test_group_entity_with_subroles(
+    group_entity: entities.GroupEntity,
+    first_parent: str,
+    second_parent: str,
+) -> None:
+    """Assign a Role for each subrole-like passed as argument."""
+    assert hasattr(group_entity, first_parent.upper())
+    assert not hasattr(group_entity, second_parent.upper())

openfisca_core/entities/tests/test_role.py

@@ -0,0 +1,11 @@
+from openfisca_core import entities
+
+
+def test_init_when_doc_indented() -> None:
+    """De-indent the ``doc`` attribute if it is passed at initialisation."""
+    key = "\tkey"
+    doc = "\tdoc"
+    entity = entities.GroupEntity("key", "plural", "label", "doc", [])
+    role = entities.Role({"key": key, "doc": doc}, entity)
+    assert role.key == key
+    assert role.doc == doc.lstrip()

openfisca_core/entities/types.py

@@ -0,0 +1,44 @@
+from typing import Required
+
+from typing_extensions import TypedDict
+
+from openfisca_core.types import (
+    CoreEntity,
+    EntityKey,
+    EntityPlural,
+    GroupEntity,
+    Role,
+    RoleKey,
+    RolePlural,
+    SingleEntity,
+    TaxBenefitSystem,
+    Variable,
+    VariableName,
+)
+
+# Entities
+
+
+class RoleParams(TypedDict, total=False):
+    key: Required[str]
+    plural: str
+    label: str
+    doc: str
+    max: int
+    subroles: list[str]
+
+
+__all__ = [
+    "CoreEntity",
+    "EntityKey",
+    "EntityPlural",
+    "GroupEntity",
+    "Role",
+    "RoleKey",
+    "RoleParams",
+    "RolePlural",
+    "SingleEntity",
+    "TaxBenefitSystem",
+    "Variable",
+    "VariableName",
+]

openfisca_core/errors/__init__.py

@@ -0,0 +1,64 @@
+# 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 .cycle_error import CycleError
+from .empty_argument_error import EmptyArgumentError
+from .nan_creation_error import NaNCreationError
+from .parameter_not_found_error import (
+    ParameterNotFoundError,
+)
+from .parameter_not_found_error import (
+    ParameterNotFoundError as ParameterNotFound,
+)
+from .parameter_parsing_error import ParameterParsingError
+from .period_mismatch_error import PeriodMismatchError
+from .situation_parsing_error import SituationParsingError
+from .spiral_error import SpiralError
+from .variable_name_config_error import (
+    VariableNameConflictError,
+)
+from .variable_name_config_error import (
+    VariableNameConflictError as VariableNameConflict,
+)
+from .variable_not_found_error import (
+    VariableNotFoundError,
+)
+from .variable_not_found_error import (
+    VariableNotFoundError as VariableNotFound,
+)
+
+__all__ = [
+    "CycleError",
+    "EmptyArgumentError",
+    "NaNCreationError",
+    "ParameterNotFound",  # Deprecated alias for "ParameterNotFoundError
+    "ParameterNotFoundError",
+    "ParameterParsingError",
+    "PeriodMismatchError",
+    "SituationParsingError",
+    "SpiralError",
+    "VariableNameConflict",  # Deprecated alias for "VariableNameConflictError"
+    "VariableNameConflictError",
+    "VariableNotFound",  # Deprecated alias for "VariableNotFoundError"
+    "VariableNotFoundError",
+]

openfisca_core/errors/cycle_error.py

@@ -0,0 +1,2 @@
+class CycleError(Exception):
+    """Simulation error."""

openfisca_core/errors/empty_argument_error.py

@@ -0,0 +1,39 @@
+import os
+import traceback
+
+import numpy
+
+
+class EmptyArgumentError(IndexError):
+    """Exception raised when a method is called with an empty argument."""
+
+    message: str
+
+    def __init__(
+        self,
+        class_name: str,
+        method_name: str,
+        arg_name: str,
+        arg_value: list | numpy.ndarray,
+    ) -> None:
+        message = [
+            f"'{class_name}.{method_name}' can't be run with an empty '{arg_name}':\n",
+            f">>> {arg_name}",
+            f"{arg_value}\n",
+            "Here are some hints to help you get this working:\n",
+            f"- Check that '{class_name}' isn't empty (see '{class_name}.add_bracket')",
+            (
+                f"- Check that '{arg_name}' is being properly assigned "
+                f"('{arg_name}' should be a non empty '{type(arg_value).__name__}')\n"
+            ),
+            "For further support, please do not hesitate to:\n",
+            "- Take a look at the official documentation https://openfisca.org/doc",
+            "- Open an issue on https://github.com/openfisca/openfisca-core/issues/new",
+            "- Mention us via https://twitter.com/openfisca",
+            "- Drop us a line to contact@openfisca.org\n",
+            "😃",
+        ]
+        stacktrace = os.linesep.join(traceback.format_stack())
+        self.message = os.linesep.join([f"  {line}" for line in message])
+        self.message = os.linesep.join([stacktrace, self.message])
+        super().__init__(self.message)

openfisca_core/errors/nan_creation_error.py

@@ -0,0 +1,2 @@
+class NaNCreationError(Exception):
+    """Simulation error."""

openfisca_core/errors/parameter_not_found_error.py

@@ -0,0 +1,16 @@
+class ParameterNotFoundError(AttributeError):
+    """Exception raised when a parameter is not found in the parameters."""
+
+    def __init__(self, name, instant_str, variable_name=None) -> None:
+        """:param name: Name of the parameter
+        :param instant_str: Instant where the parameter does not exist, in the format `YYYY-MM-DD`.
+        :param variable_name: If the parameter was queried during the computation of a variable, name of that variable.
+        """
+        self.name = name
+        self.instant_str = instant_str
+        self.variable_name = variable_name
+        message = f"The parameter '{name}'"
+        if variable_name is not None:
+            message += f" requested by variable '{variable_name}'"
+        message += f" was not found in the {instant_str} tax and benefit system."
+        super().__init__(message)

openfisca_core/errors/parameter_parsing_error.py

@@ -0,0 +1,18 @@
+import os
+
+
+class ParameterParsingError(Exception):
+    """Exception raised when a parameter cannot be parsed."""
+
+    def __init__(self, message, file=None, traceback=None) -> None:
+        """:param message: Error message
+        :param file: Parameter file which caused the error (optional)
+        :param traceback: Traceback (optional)
+        """
+        if file is not None:
+            message = os.linesep.join(
+                [f"Error parsing parameter file '{file}':", message],
+            )
+        if traceback is not None:
+            message = os.linesep.join([traceback, message])
+        super().__init__(message)

openfisca_core/errors/period_mismatch_error.py

@@ -0,0 +1,9 @@
+class PeriodMismatchError(ValueError):
+    """Exception raised when one tries to set a variable value for a period that doesn't match its definition period."""
+
+    def __init__(self, variable_name: str, period, definition_period, message) -> None:
+        self.variable_name = variable_name
+        self.period = period
+        self.definition_period = definition_period
+        self.message = message
+        ValueError.__init__(self, self.message)

openfisca_core/errors/situation_parsing_error.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable
+
+import dpath
+
+
+class SituationParsingError(Exception):
+    """Exception raised when the situation provided as an input for a simulation cannot be parsed."""
+
+    def __init__(
+        self,
+        path: Iterable[str],
+        message: str,
+        code: int | None = None,
+    ) -> None:
+        self.error = {}
+        dpath_path = "/".join([str(item) for item in path])
+        message = str(message).strip(os.linesep).replace(os.linesep, " ")
+        dpath.new(self.error, dpath_path, message)
+        self.code = code
+        Exception.__init__(self, str(self.error))
+
+    def __str__(self) -> str:
+        return str(self.error)

openfisca_core/errors/spiral_error.py

@@ -0,0 +1,2 @@
+class SpiralError(Exception):
+    """Simulation error."""

openfisca_core/errors/variable_name_config_error.py

@@ -0,0 +1,2 @@
+class VariableNameConflictError(Exception):
+    """Exception raised when two variables with the same name are added to a tax and benefit system."""

openfisca_core/errors/variable_not_found_error.py

@@ -0,0 +1,29 @@
+import os
+
+
+class VariableNotFoundError(Exception):
+    """Exception raised when a variable has been queried but is not defined in the TaxBenefitSystem."""
+
+    def __init__(self, variable_name: str, tax_benefit_system) -> None:
+        """:param variable_name: Name of the variable that was queried.
+        :param tax_benefit_system: Tax benefits system that does not contain `variable_name`
+        """
+        country_package_metadata = tax_benefit_system.get_package_metadata()
+        country_package_name = country_package_metadata["name"]
+        country_package_version = country_package_metadata["version"]
+        if country_package_version:
+            country_package_id = f"{country_package_name}@{country_package_version}"
+        else:
+            country_package_id = country_package_name
+        message = os.linesep.join(
+            [
+                f"You tried to calculate or to set a value for variable '{variable_name}', but it was not found in the loaded tax and benefit system ({country_package_id}).",
+                f"Are you sure you spelled '{variable_name}' correctly?",
+                "If this code used to work and suddenly does not, this is most probably linked to an update of the tax and benefit system.",
+                "Look at its changelog to learn about renames and removals and update your code. If it is an official package,",
+                f"it is probably available on <https://github.com/openfisca/{country_package_name}/blob/main/CHANGELOG.md>.",
+            ],
+        )
+        self.message = message
+        self.variable_name = variable_name
+        Exception.__init__(self, self.message)

openfisca_core/experimental/__init__.py

@@ -0,0 +1,9 @@
+"""Experimental features of OpenFisca-Core."""
+
+from ._errors import MemoryConfigWarning
+from ._memory_config import MemoryConfig
+
+__all__ = [
+    "MemoryConfig",
+    "MemoryConfigWarning",
+]

openfisca_core/experimental/_errors.py

@@ -0,0 +1,5 @@
+class MemoryConfigWarning(UserWarning):
+    """Custom warning for MemoryConfig."""
+
+
+__all__ = ["MemoryConfigWarning"]

openfisca_core/experimental/_memory_config.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import warnings
+from collections.abc import Iterable
+
+from ._errors import MemoryConfigWarning
+
+
+class MemoryConfig:
+    """Experimental memory configuration."""
+
+    #: Maximum memory occupation allowed.
+    max_memory_occupation: float
+
+    #: Priority variables.
+    priority_variables: frozenset[str]
+
+    #: Variables to drop.
+    variables_to_drop: frozenset[str]
+
+    def __init__(
+        self,
+        max_memory_occupation: str | float,
+        priority_variables: Iterable[str] = frozenset(),
+        variables_to_drop: Iterable[str] = frozenset(),
+    ) -> None:
+        message = (
+            "Memory configuration is a feature that is still currently under ",
+            "experimentation. You are very welcome to use it and send us ",
+            "precious feedback, but keep in mind that the way it is used might ",
+            "change without any major version bump.",
+        )
+        warnings.warn(message, MemoryConfigWarning, stacklevel=2)
+
+        self.max_memory_occupation = float(max_memory_occupation)
+        if self.max_memory_occupation > 1:
+            msg = "max_memory_occupation must be <= 1"
+            raise ValueError(msg)
+        self.max_memory_occupation_pc = self.max_memory_occupation * 100
+        self.priority_variables = frozenset(priority_variables)
+        self.variables_to_drop = frozenset(variables_to_drop)

openfisca_core/formula_helpers.py

@@ -0,0 +1,9 @@
+# The formula_helpers module has been deprecated since X.X.X,
+# and will be removed in the future.
+#
+# The helpers have been moved to the commons module.
+#
+# 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

openfisca_core/holders/__init__.py

@@ -0,0 +1,33 @@
+# 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 . import types
+from .helpers import set_input_dispatch_by_period, set_input_divide_by_period
+from .holder import Holder
+
+__all__ = [
+    "Holder",
+    "set_input_dispatch_by_period",
+    "set_input_divide_by_period",
+    "types",
+]

openfisca_core/holders/helpers.py

@@ -0,0 +1,93 @@
+import logging
+
+import numpy
+
+from openfisca_core import periods
+
+log = logging.getLogger(__name__)
+
+
+def set_input_dispatch_by_period(holder, period, array) -> None:
+    """This function can be declared as a ``set_input`` attribute of a variable.
+
+    In this case, the variable will accept inputs on larger periods that its definition period, and the value for the larger period will be applied to all its subperiods.
+
+    To read more about ``set_input`` attributes, check the `documentation <https://openfisca.org/doc/coding-the-legislation/35_periods.html#set-input-automatically-process-variable-inputs-defined-for-periods-not-matching-the-definition-period>`_.
+    """
+    array = holder._to_array(array)
+
+    period_size = period.size
+    period_unit = period.unit
+
+    if holder.variable.definition_period not in (
+        periods.DateUnit.isoformat + periods.DateUnit.isocalendar
+    ):
+        msg = "set_input_dispatch_by_period can't be used for eternal variables."
+        raise ValueError(
+            msg,
+        )
+
+    cached_period_unit = holder.variable.definition_period
+    after_instant = period.start.offset(period_size, period_unit)
+
+    # Cache the input data, skipping the existing cached months
+    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:
+            holder._set(sub_period, array)
+        else:
+            # The array of the current sub-period is reused for the next ones.
+            # TODO: refactor or document this behavior
+            array = existing_array
+        sub_period = sub_period.offset(1)
+
+
+def set_input_divide_by_period(holder, period, array) -> None:
+    """This function can be declared as a ``set_input`` attribute of a variable.
+
+    In this case, the variable will accept inputs on larger periods that its definition period, and the value for the larger period will be divided between its subperiods.
+
+    To read more about ``set_input`` attributes, check the `documentation <https://openfisca.org/doc/coding-the-legislation/35_periods.html#set-input-automatically-process-variable-inputs-defined-for-periods-not-matching-the-definition-period>`_.
+    """
+    if not isinstance(array, numpy.ndarray):
+        array = numpy.array(array)
+    period_size = period.size
+    period_unit = period.unit
+
+    if holder.variable.definition_period not in (
+        periods.DateUnit.isoformat + periods.DateUnit.isocalendar
+    ):
+        msg = "set_input_divide_by_period can't be used for eternal variables."
+        raise ValueError(
+            msg,
+        )
+
+    cached_period_unit = holder.variable.definition_period
+    after_instant = period.start.offset(period_size, period_unit)
+
+    # Count the number of elementary periods to change, and the difference with what is already known.
+    remaining_array = array.copy()
+    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)
+        if existing_array is not None:
+            remaining_array -= existing_array
+        else:
+            sub_periods_count += 1
+        sub_period = sub_period.offset(1)
+
+    # Cache the input data
+    if sub_periods_count > 0:
+        divided_array = remaining_array / sub_periods_count
+        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)
+            sub_period = sub_period.offset(1)
+    elif not (remaining_array == 0).all():
+        msg = f"Inconsistent input: variable {holder.variable.name} has already been set for all months contained in period {period}, and value {array} provided for {period} doesn't match the total ({array - remaining_array}). This error may also be thrown if you try to call set_input twice for the same variable and period."
+        raise ValueError(
+            msg,
+        )