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

openfisca_core/simulations/_build_from_variables.py

@@ -0,0 +1,230 @@
+"""This module contains the _BuildFromVariables class."""
+
+from __future__ import annotations
+
+from typing import Self
+
+from openfisca_core import errors
+
+from ._build_default_simulation import _BuildDefaultSimulation
+from ._type_guards import is_variable_dated
+from .simulation import Simulation
+from .typing import Entity, Population, TaxBenefitSystem, Variables
+
+
+class _BuildFromVariables:
+    """Build a simulation from variables.
+
+    Args:
+        tax_benefit_system(TaxBenefitSystem): The tax-benefit system.
+        params(Variables): The simulation parameters.
+
+    Examples:
+        >>> from openfisca_core import entities, periods, taxbenefitsystems, variables
+
+        >>> role = {"key": "stray", "plural": "stray", "label": "", "doc": ""}
+        >>> single_entity = entities.Entity("dog", "dogs", "", "")
+        >>> group_entity = entities.GroupEntity("pack", "packs", "", "", [role])
+
+        >>> class salary(variables.Variable):
+        ...     definition_period = periods.DateUnit.MONTH
+        ...     entity = single_entity
+        ...     value_type = int
+
+        >>> class taxes(variables.Variable):
+        ...     definition_period = periods.DateUnit.MONTH
+        ...     entity = group_entity
+        ...     value_type = int
+
+        >>> test_entities = [single_entity, group_entity]
+        >>> tax_benefit_system = taxbenefitsystems.TaxBenefitSystem(test_entities)
+        >>> tax_benefit_system.load_variable(salary)
+        <...salary object at ...>
+        >>> tax_benefit_system.load_variable(taxes)
+        <...taxes object at ...>
+        >>> period = "2023-12"
+        >>> variables = {"salary": {period: 10000}, "taxes": 5000}
+        >>> builder = (
+        ...     _BuildFromVariables(tax_benefit_system, variables, period)
+        ...     .add_dated_values()
+        ...     .add_undated_values()
+        ... )
+
+        >>> dogs = builder.populations["dog"].get_holder("salary")
+        >>> dogs.get_array(period)
+        array([10000], dtype=int32)
+
+        >>> pack = builder.populations["pack"].get_holder("taxes")
+        >>> pack.get_array(period)
+        array([5000], dtype=int32)
+
+    """
+
+    #: The number of Population.
+    count: int
+
+    #: The Simulation's default period.
+    default_period: str | None
+
+    #: The built populations.
+    populations: dict[str, Population[Entity]]
+
+    #: The built simulation.
+    simulation: Simulation
+
+    #: The simulation parameters.
+    variables: Variables
+
+    def __init__(
+        self,
+        tax_benefit_system: TaxBenefitSystem,
+        params: Variables,
+        default_period: str | None = None,
+    ) -> None:
+        self.count = _person_count(params)
+
+        default_builder = (
+            _BuildDefaultSimulation(tax_benefit_system, self.count)
+            .add_count()
+            .add_ids()
+            .add_members_entity_id()
+        )
+
+        self.variables = params
+        self.simulation = default_builder.simulation
+        self.populations = default_builder.populations
+        self.default_period = default_period
+
+    def add_dated_values(self) -> Self:
+        """Add the dated input values to the Simulation.
+
+        Returns:
+            _BuildFromVariables: The builder.
+
+        Examples:
+            >>> from openfisca_core import entities, periods, taxbenefitsystems, variables
+
+            >>> role = {"key": "stray", "plural": "stray", "label": "", "doc": ""}
+            >>> single_entity = entities.Entity("dog", "dogs", "", "")
+            >>> group_entity = entities.GroupEntity("pack", "packs", "", "", [role])
+
+
+            >>> class salary(variables.Variable):
+            ...     definition_period = periods.DateUnit.MONTH
+            ...     entity = single_entity
+            ...     value_type = int
+
+            >>> class taxes(variables.Variable):
+            ...     definition_period = periods.DateUnit.MONTH
+            ...     entity = group_entity
+            ...     value_type = int
+
+            >>> test_entities = [single_entity, group_entity]
+            >>> tax_benefit_system = taxbenefitsystems.TaxBenefitSystem(test_entities)
+            >>> tax_benefit_system.load_variable(salary)
+            <...salary object at ...>
+            >>> tax_benefit_system.load_variable(taxes)
+            <...taxes object at ...>
+            >>> period = "2023-12"
+            >>> variables = {"salary": {period: 10000}, "taxes": 5000}
+            >>> builder = _BuildFromVariables(tax_benefit_system, variables)
+            >>> builder.add_dated_values()
+            <..._BuildFromVariables object at ...>
+
+            >>> dogs = builder.populations["dog"].get_holder("salary")
+            >>> dogs.get_array(period)
+            array([10000], dtype=int32)
+
+            >>> pack = builder.populations["pack"].get_holder("taxes")
+            >>> pack.get_array(period)
+
+        """
+        for variable, value in self.variables.items():
+            if is_variable_dated(dated_variable := value):
+                for period, dated_value in dated_variable.items():
+                    self.simulation.set_input(variable, period, dated_value)
+
+        return self
+
+    def add_undated_values(self) -> Self:
+        """Add the undated input values to the Simulation.
+
+        Returns:
+            _BuildFromVariables: The builder.
+
+        Raises:
+            SituationParsingError: If there is not a default period set.
+
+        Examples:
+            >>> from openfisca_core import entities, periods, taxbenefitsystems, variables
+
+            >>> role = {"key": "stray", "plural": "stray", "label": "", "doc": ""}
+            >>> single_entity = entities.Entity("dog", "dogs", "", "")
+            >>> group_entity = entities.GroupEntity("pack", "packs", "", "", [role])
+
+            >>> class salary(variables.Variable):
+            ...     definition_period = periods.DateUnit.MONTH
+            ...     entity = single_entity
+            ...     value_type = int
+
+            >>> class taxes(variables.Variable):
+            ...     definition_period = periods.DateUnit.MONTH
+            ...     entity = group_entity
+            ...     value_type = int
+
+            >>> test_entities = [single_entity, group_entity]
+            >>> tax_benefit_system = taxbenefitsystems.TaxBenefitSystem(test_entities)
+            >>> tax_benefit_system.load_variable(salary)
+            <...salary object at ...>
+            >>> tax_benefit_system.load_variable(taxes)
+            <...taxes object at ...>
+            >>> period = "2023-12"
+            >>> variables = {"salary": {period: 10000}, "taxes": 5000}
+            >>> builder = _BuildFromVariables(tax_benefit_system, variables)
+            >>> builder.add_undated_values()
+            Traceback (most recent call last):
+            openfisca_core.errors.situation_parsing_error.SituationParsingError
+            >>> builder.default_period = period
+            >>> builder.add_undated_values()
+            <..._BuildFromVariables object at ...>
+
+            >>> dogs = builder.populations["dog"].get_holder("salary")
+            >>> dogs.get_array(period)
+
+            >>> pack = builder.populations["pack"].get_holder("taxes")
+            >>> pack.get_array(period)
+            array([5000], dtype=int32)
+
+        """
+        for variable, value in self.variables.items():
+            if not is_variable_dated(undated_value := value):
+                if (period := self.default_period) is None:
+                    message = (
+                        "Can't deal with type: expected object. Input "
+                        "variables should be set for specific periods. For "
+                        "instance: "
+                        "    {'salary': {'2017-01': 2000, '2017-02': 2500}}"
+                        "    {'birth_date': {'ETERNITY': '1980-01-01'}}"
+                    )
+
+                    raise errors.SituationParsingError([variable], message)
+
+                self.simulation.set_input(variable, period, undated_value)
+
+        return self
+
+
+def _person_count(params: Variables) -> int:
+    try:
+        first_value = next(iter(params.values()))
+
+        if isinstance(first_value, dict):
+            first_value = next(iter(first_value.values()))
+
+        if isinstance(first_value, str):
+            return 1
+
+        return len(first_value)
+
+    except Exception:
+        return 1

openfisca_core/simulations/_type_guards.py

@@ -0,0 +1,298 @@
+"""Type guards to help type narrowing simulation parameters."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TypeGuard
+
+from .typing import (
+    Axes,
+    DatedVariable,
+    FullySpecifiedEntities,
+    ImplicitGroupEntities,
+    Params,
+    UndatedVariable,
+    Variables,
+)
+
+
+def are_entities_fully_specified(
+    params: Params,
+    items: Iterable[str],
+) -> TypeGuard[FullySpecifiedEntities]:
+    """Check if the params contain fully specified entities.
+
+    Args:
+        params(Params): Simulation parameters.
+        items(Iterable[str]): List of entities in plural form.
+
+    Returns:
+        bool: True if the params contain fully specified entities.
+
+    Examples:
+        >>> entities = {"persons", "households"}
+
+        >>> params = {
+        ...     "axes": [
+        ...         [
+        ...             {
+        ...                 "count": 2,
+        ...                 "max": 3000,
+        ...                 "min": 0,
+        ...                 "name": "rent",
+        ...                 "period": "2018-11",
+        ...             }
+        ...         ]
+        ...     ],
+        ...     "households": {
+        ...         "housea": {"parents": ["Alicia", "Javier"]},
+        ...         "houseb": {"parents": ["Tom"]},
+        ...     },
+        ...     "persons": {"Alicia": {"salary": {"2018-11": 0}}, "Javier": {}, "Tom": {}},
+        ... }
+
+        >>> are_entities_fully_specified(params, entities)
+        True
+
+        >>> params = {"persons": {"Javier": {"salary": {"2018-11": [2000, 3000]}}}}
+
+        >>> are_entities_fully_specified(params, entities)
+        True
+
+        >>> params = {"persons": {"Javier": {"salary": {"2018-11": 2000}}}}
+
+        >>> are_entities_fully_specified(params, entities)
+        True
+
+        >>> params = {"household": {"parents": ["Javier"]}}
+
+        >>> are_entities_fully_specified(params, entities)
+        False
+
+        >>> params = {"salary": {"2016-10": 12000}}
+
+        >>> are_entities_fully_specified(params, entities)
+        False
+
+        >>> params = {"salary": 12000}
+
+        >>> are_entities_fully_specified(params, entities)
+        False
+
+        >>> params = {}
+
+        >>> are_entities_fully_specified(params, entities)
+        False
+
+    """
+    if not params:
+        return False
+
+    return all(key in items for key in params if key != "axes")
+
+
+def are_entities_short_form(
+    params: Params,
+    items: Iterable[str],
+) -> TypeGuard[ImplicitGroupEntities]:
+    """Check if the params contain short form entities.
+
+    Args:
+        params(Params): Simulation parameters.
+        items(Iterable[str]): List of entities in singular form.
+
+    Returns:
+        bool: True if the params contain short form entities.
+
+    Examples:
+        >>> entities = {"person", "household"}
+
+        >>> params = {
+        ...     "persons": {"Javier": {"salary": {"2018-11": 2000}}},
+        ...     "households": {"household": {"parents": ["Javier"]}},
+        ...     "axes": [[{"count": 1, "max": 1, "min": 1, "name": "household"}]],
+        ... }
+
+        >>> are_entities_short_form(params, entities)
+        False
+
+        >>> params = {"persons": {"Javier": {"salary": {"2018-11": 2000}}}}
+
+        >>> are_entities_short_form(params, entities)
+        False
+
+        >>> params = {
+        ...     "persons": {"Javier": {"salary": {"2018-11": 2000}}},
+        ...     "household": {"parents": ["Javier"]},
+        ...     "axes": [[{"count": 1, "max": 1, "min": 1, "name": "household"}]],
+        ... }
+
+        >>> are_entities_short_form(params, entities)
+        True
+
+        >>> params = {
+        ...     "household": {"parents": ["Javier"]},
+        ...     "axes": [[{"count": 1, "max": 1, "min": 1, "name": "household"}]],
+        ... }
+
+        >>> are_entities_short_form(params, entities)
+        True
+
+        >>> params = {"household": {"parents": ["Javier"]}}
+
+        >>> are_entities_short_form(params, entities)
+        True
+
+        >>> params = {"household": {"parents": "Javier"}}
+
+        >>> are_entities_short_form(params, entities)
+        True
+
+        >>> params = {"salary": {"2016-10": 12000}}
+
+        >>> are_entities_short_form(params, entities)
+        False
+
+        >>> params = {"salary": 12000}
+
+        >>> are_entities_short_form(params, entities)
+        False
+
+        >>> params = {}
+
+        >>> are_entities_short_form(params, entities)
+        False
+
+    """
+    return bool(set(params).intersection(items))
+
+
+def are_entities_specified(
+    params: Params,
+    items: Iterable[str],
+) -> TypeGuard[Variables]:
+    """Check if the params contains entities at all.
+
+    Args:
+        params(Params): Simulation parameters.
+        items(Iterable[str]): List of variables.
+
+    Returns:
+        bool: True if the params does not contain variables at the root level.
+
+    Examples:
+        >>> variables = {"salary"}
+
+        >>> params = {
+        ...     "persons": {"Javier": {"salary": {"2018-11": 2000}}},
+        ...     "households": {"household": {"parents": ["Javier"]}},
+        ...     "axes": [[{"count": 1, "max": 1, "min": 1, "name": "household"}]],
+        ... }
+
+        >>> are_entities_specified(params, variables)
+        True
+
+        >>> params = {"persons": {"Javier": {"salary": {"2018-11": [2000, 3000]}}}}
+
+        >>> are_entities_specified(params, variables)
+        True
+
+        >>> params = {"persons": {"Javier": {"salary": {"2018-11": 2000}}}}
+
+        >>> are_entities_specified(params, variables)
+        True
+
+        >>> params = {"household": {"parents": ["Javier"]}}
+
+        >>> are_entities_specified(params, variables)
+        True
+
+        >>> params = {"salary": {"2016-10": [12000, 13000]}}
+
+        >>> are_entities_specified(params, variables)
+        False
+
+        >>> params = {"salary": {"2016-10": 12000}}
+
+        >>> are_entities_specified(params, variables)
+        False
+
+        >>> params = {"salary": [12000, 13000]}
+
+        >>> are_entities_specified(params, variables)
+        False
+
+        >>> params = {"salary": 12000}
+
+        >>> are_entities_specified(params, variables)
+        False
+
+        >>> params = {}
+
+        >>> are_entities_specified(params, variables)
+        False
+
+    """
+    if not params:
+        return False
+
+    return not any(key in items for key in params)
+
+
+def has_axes(params: Params) -> TypeGuard[Axes]:
+    """Check if the params contains axes.
+
+    Args:
+        params(Params): Simulation parameters.
+
+    Returns:
+        bool: True if the params contain axes.
+
+    Examples:
+        >>> params = {
+        ...     "persons": {"Javier": {"salary": {"2018-11": 2000}}},
+        ...     "households": {"household": {"parents": ["Javier"]}},
+        ...     "axes": [[{"count": 1, "max": 1, "min": 1, "name": "household"}]],
+        ... }
+
+        >>> has_axes(params)
+        True
+
+        >>> params = {"persons": {"Javier": {"salary": {"2018-11": [2000, 3000]}}}}
+
+        >>> has_axes(params)
+        False
+
+    """
+    return params.get("axes", None) is not None
+
+
+def is_variable_dated(
+    variable: DatedVariable | UndatedVariable,
+) -> TypeGuard[DatedVariable]:
+    """Check if the variable is dated.
+
+    Args:
+        variable(DatedVariable | UndatedVariable): A variable.
+
+    Returns:
+        bool: True if the variable is dated.
+
+    Examples:
+        >>> variable = {"2018-11": [2000, 3000]}
+
+        >>> is_variable_dated(variable)
+        True
+
+        >>> variable = {"2018-11": 2000}
+
+        >>> is_variable_dated(variable)
+        True
+
+        >>> variable = 2000
+
+        >>> is_variable_dated(variable)
+        False
+
+    """
+    return isinstance(variable, dict)

openfisca_core/simulations/helpers.py

@@ -0,0 +1,111 @@
+from collections.abc import Iterable
+
+from openfisca_core import errors
+
+from .typing import ParamsWithoutAxes
+
+
+def calculate_output_add(simulation, variable_name: str, period):
+    return simulation.calculate_add(variable_name, period)
+
+
+def calculate_output_divide(simulation, variable_name: str, period):
+    return simulation.calculate_divide(variable_name, period)
+
+
+def check_type(input, input_type, path=None) -> None:
+    json_type_map = {
+        dict: "Object",
+        list: "Array",
+        str: "String",
+    }
+
+    if path is None:
+        path = []
+
+    if not isinstance(input, input_type):
+        raise errors.SituationParsingError(
+            path,
+            f"Invalid type: must be of type '{json_type_map[input_type]}'.",
+        )
+
+
+def check_unexpected_entities(
+    params: ParamsWithoutAxes,
+    entities: Iterable[str],
+) -> None:
+    """Check if the input contains entities that are not in the system.
+
+    Args:
+        params(ParamsWithoutAxes): Simulation parameters.
+        entities(Iterable[str]): List of entities in plural form.
+
+    Raises:
+        SituationParsingError: If there are entities that are not in the system.
+
+    Examples:
+        >>> entities = {"persons", "households"}
+
+        >>> params = {
+        ...     "persons": {"Javier": {"salary": {"2018-11": 2000}}},
+        ...     "households": {"household": {"parents": ["Javier"]}},
+        ... }
+
+        >>> check_unexpected_entities(params, entities)
+
+        >>> params = {"dogs": {"Bart": {"damages": {"2018-11": 2000}}}}
+
+        >>> check_unexpected_entities(params, entities)
+        Traceback (most recent call last):
+        openfisca_core.errors.situation_parsing_error.SituationParsingError
+
+    """
+    if has_unexpected_entities(params, entities):
+        unexpected_entities = [entity for entity in params if entity not in entities]
+
+        message = (
+            "Some entities in the situation are not defined in the loaded tax "
+            "and benefit system. "
+            f"These entities are not found: {', '.join(unexpected_entities)}. "
+            f"The defined entities are: {', '.join(entities)}."
+        )
+
+        raise errors.SituationParsingError([unexpected_entities[0]], message)
+
+
+def has_unexpected_entities(params: ParamsWithoutAxes, entities: Iterable[str]) -> bool:
+    """Check if the input contains entities that are not in the system.
+
+    Args:
+        params(ParamsWithoutAxes): Simulation parameters.
+        entities(Iterable[str]): List of entities in plural form.
+
+    Returns:
+        bool: True if the input contains entities that are not in the system.
+
+    Examples:
+        >>> entities = {"persons", "households"}
+
+        >>> params = {
+        ...     "persons": {"Javier": {"salary": {"2018-11": 2000}}},
+        ...     "households": {"household": {"parents": ["Javier"]}},
+        ... }
+
+        >>> has_unexpected_entities(params, entities)
+        False
+
+        >>> params = {"dogs": {"Bart": {"damages": {"2018-11": 2000}}}}
+
+        >>> has_unexpected_entities(params, entities)
+        True
+
+    """
+    return any(entity for entity in params if entity not in entities)
+
+
+def transform_to_strict_syntax(data):
+    if isinstance(data, (str, int)):
+        data = [data]
+    if isinstance(data, list):
+        return [str(item) if isinstance(item, int) else item for item in data]
+    return data