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

openfisca_core/projectors/__init__.py

@@ -0,0 +1,39 @@
+# 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 typing
+from .entity_to_person_projector import EntityToPersonProjector
+from .first_person_to_entity_projector import FirstPersonToEntityProjector
+from .helpers import get_projector_from_shortcut, projectable
+from .projector import Projector
+from .unique_role_to_entity_projector import UniqueRoleToEntityProjector
+
+__all__ = [
+    "EntityToPersonProjector",
+    "FirstPersonToEntityProjector",
+    "Projector",
+    "UniqueRoleToEntityProjector",
+    "get_projector_from_shortcut",
+    "projectable",
+    "typing",
+]

openfisca_core/projectors/entity_to_person_projector.py

@@ -0,0 +1,12 @@
+from .projector import Projector
+
+
+class EntityToPersonProjector(Projector):
+    """For instance person.family."""
+
+    def __init__(self, entity, parent=None) -> None:
+        self.reference_entity = entity
+        self.parent = parent
+
+    def transform(self, result):
+        return self.reference_entity.project(result)

openfisca_core/projectors/first_person_to_entity_projector.py

@@ -0,0 +1,13 @@
+from .projector import Projector
+
+
+class FirstPersonToEntityProjector(Projector):
+    """For instance famille.first_person."""
+
+    def __init__(self, entity, parent=None) -> None:
+        self.target_entity = entity
+        self.reference_entity = entity.members
+        self.parent = parent
+
+    def transform(self, result):
+        return self.target_entity.value_from_first_person(result)

openfisca_core/projectors/helpers.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from openfisca_core import entities, projectors
+from openfisca_core.types import GroupEntity, Role, SingleEntity
+
+from .typing import GroupPopulation, Population
+
+
+def projectable(function):
+    """Decorator to indicate that when called on a projector, the outcome of the function must be projected.
+    For instance person.household.sum(...) must be projected on person, while it would not make sense for person.household.get_holder.
+    """
+    function.projectable = True
+    return function
+
+
+def get_projector_from_shortcut(
+    population: Population | GroupPopulation,
+    shortcut: str,
+    parent: projectors.Projector | None = None,
+) -> projectors.Projector | None:
+    """Get a projector from a shortcut.
+
+    Projectors are used to project an invidividual Population's or a
+    collective GroupPopulation's on to other populations.
+
+    The currently available cases are projecting:
+    - from an individual to a group
+    - from a group to an individual
+    - from a group to an individual with a unique role
+
+    For example, if there are two entities, person (Entity) and household
+    (GroupEntity), on which calculations can be run (Population and
+    GroupPopulation respectively), and there is a Variable "rent" defined for
+    the household entity, then `person.household("rent")` will assign a rent to
+    every person within that household.
+
+    Behind the scenes, this is done thanks to a Projector, and this function is
+    used to find the appropriate one for each case. In the above example, the
+    `shortcut` argument would be "household", and the `population` argument
+    would be the Population linked to the "person" Entity in the context
+    of a specific Simulation and TaxBenefitSystem.
+
+    Args:
+        population (Population | GroupPopulation): Where to project from.
+        shortcut (str): Where to project to.
+        parent: ???
+
+    Examples:
+        >>> from openfisca_core import (
+        ...     entities,
+        ...     populations,
+        ...     simulations,
+        ...     taxbenefitsystems,
+        ... )
+
+        >>> entity = entities.Entity("person", "", "", "")
+
+        >>> group_entity_1 = entities.GroupEntity("family", "", "", "", [])
+
+        >>> roles = [
+        ...     {"key": "person", "max": 1},
+        ...     {"key": "animal", "subroles": ["cat", "dog"]},
+        ... ]
+
+        >>> group_entity_2 = entities.GroupEntity("household", "", "", "", roles)
+
+        >>> population = populations.Population(entity)
+
+        >>> group_population_1 = populations.GroupPopulation(group_entity_1, [])
+
+        >>> group_population_2 = populations.GroupPopulation(group_entity_2, [])
+
+        >>> populations = {
+        ...     entity.key: population,
+        ...     group_entity_1.key: group_population_1,
+        ...     group_entity_2.key: group_population_2,
+        ... }
+
+        >>> tax_benefit_system = taxbenefitsystems.TaxBenefitSystem(
+        ...     [entity, group_entity_1, group_entity_2]
+        ... )
+
+        >>> simulation = simulations.Simulation(tax_benefit_system, populations)
+
+        >>> get_projector_from_shortcut(population, "person")
+        <...EntityToPersonProjector object at ...>
+
+        >>> get_projector_from_shortcut(population, "family")
+        <...EntityToPersonProjector object at ...>
+
+        >>> get_projector_from_shortcut(population, "household")
+        <...EntityToPersonProjector object at ...>
+
+        >>> get_projector_from_shortcut(group_population_2, "first_person")
+        <...FirstPersonToEntityProjector object at ...>
+
+        >>> get_projector_from_shortcut(group_population_2, "person")
+        <...UniqueRoleToEntityProjector object at ...>
+
+        >>> get_projector_from_shortcut(group_population_2, "cat")
+        <...UniqueRoleToEntityProjector object at ...>
+
+        >>> get_projector_from_shortcut(group_population_2, "dog")
+        <...UniqueRoleToEntityProjector object at ...>
+
+    """
+    entity: SingleEntity | GroupEntity = population.entity
+
+    if isinstance(entity, entities.Entity):
+        populations: Mapping[
+            str,
+            Population | GroupPopulation,
+        ] = population.simulation.populations
+
+        if shortcut not in populations:
+            return None
+
+        return projectors.EntityToPersonProjector(populations[shortcut], parent)
+
+    if shortcut == "first_person":
+        return projectors.FirstPersonToEntityProjector(population, parent)
+
+    if isinstance(entity, entities.GroupEntity):
+        role: Role | None = entities.find_role(entity.roles, shortcut, total=1)
+
+        if role is not None:
+            return projectors.UniqueRoleToEntityProjector(population, role, parent)
+
+        if shortcut in entity.containing_entities:
+            projector: projectors.Projector = getattr(
+                projectors.FirstPersonToEntityProjector(population, parent),
+                shortcut,
+            )
+            return projector
+
+    return None

openfisca_core/projectors/projector.py

@@ -0,0 +1,38 @@
+from openfisca_core.projectors import helpers
+
+
+class Projector:
+    reference_entity = None
+    parent = None
+
+    def __getattr__(self, attribute):
+        projector = helpers.get_projector_from_shortcut(
+            self.reference_entity,
+            attribute,
+            parent=self,
+        )
+        if projector:
+            return projector
+
+        reference_attr = getattr(self.reference_entity, attribute)
+        if not hasattr(reference_attr, "projectable"):
+            return reference_attr
+
+        def projector_function(*args, **kwargs):
+            result = reference_attr(*args, **kwargs)
+            return self.transform_and_bubble_up(result)
+
+        return projector_function
+
+    def __call__(self, *args, **kwargs):
+        result = self.reference_entity(*args, **kwargs)
+        return self.transform_and_bubble_up(result)
+
+    def transform_and_bubble_up(self, result):
+        transformed_result = self.transform(result)
+        if self.parent is None:
+            return transformed_result
+        return self.parent.transform_and_bubble_up(transformed_result)
+
+    def transform(self, result):
+        return NotImplementedError()

openfisca_core/projectors/typing.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Protocol
+
+from openfisca_core.types import GroupEntity, SingleEntity
+
+
+class Population(Protocol):
+    @property
+    def entity(self) -> SingleEntity: ...
+
+    @property
+    def simulation(self) -> Simulation: ...
+
+
+class GroupPopulation(Protocol):
+    @property
+    def entity(self) -> GroupEntity: ...
+
+    @property
+    def simulation(self) -> Simulation: ...
+
+
+class Simulation(Protocol):
+    @property
+    def populations(self) -> Mapping[str, Population | GroupPopulation]: ...

openfisca_core/projectors/unique_role_to_entity_projector.py

@@ -0,0 +1,14 @@
+from .projector import Projector
+
+
+class UniqueRoleToEntityProjector(Projector):
+    """For instance famille.declarant_principal."""
+
+    def __init__(self, entity, role, parent=None) -> None:
+        self.target_entity = entity
+        self.reference_entity = entity.members
+        self.parent = parent
+        self.role = role
+
+    def transform(self, result):
+        return self.target_entity.value_from_person(result, self.role)

openfisca_core/rates.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 average_rate, marginal_rate  # noqa: F401

openfisca_core/reforms/__init__.py

@@ -0,0 +1,24 @@
+# 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 .reform import Reform  # noqa: F401

openfisca_core/reforms/in_yaml_test_reform.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from openfisca_core.parameters.parameter_node import ParameterNode
+from openfisca_core.reforms import Reform
+from openfisca_core.types import TaxBenefitSystem
+
+
+class InYamlTestReform(Reform):
+    """A class representing a parametric reform directly defined in YAML test files."""
+
+    def __init__(
+        self,
+        baseline: TaxBenefitSystem,
+        reformed_parameters=dict,
+    ) -> None:
+        """Initialize the instance.
+
+        :param baseline: Baseline TaxBenefitSystem.
+        :param reformed_parameters: Yaml file `parameters` value similar to a parameter tree
+        """
+        self.reformed_parameters = reformed_parameters
+        super().__init__(baseline)
+
+    def apply(self):
+        def modify_parameters(local_parameters: ParameterNode) -> ParameterNode:
+            return ParameterNode(data=self.reformed_parameters)
+
+        self.modify_parameters(modifier_function=modify_parameters)

openfisca_core/reforms/reform.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import copy
+
+from openfisca_core.parameters import ParameterNode
+from openfisca_core.taxbenefitsystems import TaxBenefitSystem
+
+
+class Reform(TaxBenefitSystem):
+    """A modified TaxBenefitSystem.
+
+    All reforms must subclass `Reform` and implement a method `apply()`.
+
+    In this method, the reform can add or replace variables and call `modify_parameters` to modify the parameters of the legislation.
+
+    Example:
+        >>> from openfisca_core import reforms
+        >>> from openfisca_core.parameters import load_parameter_file
+        >>>
+        >>> def modify_my_parameters(parameters):
+        >>> # Add new parameters
+        >>>     new_parameters = load_parameter_file(name='reform_name', file_path='path_to_yaml_file.yaml')
+        >>>     parameters.add_child('reform_name', new_parameters)
+        >>>
+        >>> # Update a value
+        >>>     parameters.taxes.some_tax.some_param.update(period=some_period, value=1000.0)
+        >>>
+        >>>    return parameters
+        >>>
+        >>> class MyReform(reforms.Reform):
+        >>>    def apply(self):
+        >>>        self.add_variable(some_variable)
+        >>>        self.update_variable(some_other_variable)
+        >>>        self.modify_parameters(modifier_function = modify_my_parameters)
+
+    """
+
+    name = None
+
+    def __init__(self, baseline) -> None:
+        """:param baseline: Baseline TaxBenefitSystem."""
+        super().__init__(baseline.entities)
+        self.baseline = baseline
+        self.parameters = baseline.parameters
+        self._parameters_at_instant_cache = baseline._parameters_at_instant_cache
+        self.variables = baseline.variables.copy()
+        self.decomposition_file_path = baseline.decomposition_file_path
+        self.key = self.__class__.__name__
+        if not hasattr(self, "apply"):
+            msg = f"Reform {self.key} must define an `apply` function"
+            raise Exception(msg)
+        self.apply()
+
+    def __getattr__(self, attribute):
+        return getattr(self.baseline, attribute)
+
+    @property
+    def full_key(self):
+        key = self.key
+        assert key is not None, (
+            f"key was not set for reform {self} (name: {self.name!r})"
+        )
+        if self.baseline is not None and hasattr(self.baseline, "key"):
+            baseline_full_key = self.baseline.full_key
+            key = f"{baseline_full_key}.{key}"
+        return key
+
+    def modify_parameters(self, modifier_function):
+        """Make modifications on the parameters of the legislation.
+
+        Call this function in `apply()` if the reform asks for legislation parameter modifications.
+
+        Args:
+            modifier_function: A function that takes a :obj:`~parameters.ParameterNode`
+            and should return an object of the same type.
+
+        """
+        baseline_parameters = self.baseline.parameters
+        baseline_parameters_copy = copy.deepcopy(baseline_parameters)
+        reform_parameters = modifier_function(baseline_parameters_copy)
+        if not isinstance(reform_parameters, ParameterNode):
+            raise ValueError(
+                f"modifier_function {modifier_function.__name__} in module {modifier_function.__module__} must return a ParameterNode",
+            )
+        self.parameters = reform_parameters
+        self._parameters_at_instant_cache = {}

openfisca_core/scripts/__init__.py

@@ -0,0 +1,106 @@
+import importlib
+import logging
+import pkgutil
+import traceback
+from os import linesep
+
+log = logging.getLogger(__name__)
+
+
+def add_tax_benefit_system_arguments(parser):
+    parser.add_argument(
+        "-c",
+        "--country-package",
+        action="store",
+        help='country package to use. If not provided, an automatic detection will be attempted by scanning the python packages installed in your environment which name contains the word "openfisca".',
+    )
+    parser.add_argument(
+        "-e",
+        "--extensions",
+        action="store",
+        help="extensions to load",
+        nargs="*",
+    )
+    parser.add_argument(
+        "-r",
+        "--reforms",
+        action="store",
+        help="reforms to apply to the country package",
+        nargs="*",
+    )
+
+    return parser
+
+
+def build_tax_benefit_system(country_package_name, extensions, reforms):
+    if country_package_name is None:
+        country_package_name = detect_country_package()
+    try:
+        country_package = importlib.import_module(country_package_name)
+    except ImportError:
+        message = linesep.join(
+            [
+                traceback.format_exc(),
+                f"Could not import module `{country_package_name}`.",
+                "Are you sure it is installed in your environment? If so, look at the stack trace above to determine the origin of this error.",
+                "See more at <https://github.com/openfisca/country-template#installing>.",
+            ],
+        )
+
+        raise ImportError(message)
+    if not hasattr(country_package, "CountryTaxBenefitSystem"):
+        msg = f"`{country_package_name}` does not seem to be a valid Openfisca country package."
+        raise ImportError(
+            msg,
+        )
+
+    country_package = importlib.import_module(country_package_name)
+    tax_benefit_system = country_package.CountryTaxBenefitSystem()
+
+    if extensions:
+        for extension in extensions:
+            tax_benefit_system.load_extension(extension)
+
+    if reforms:
+        for reform_path in reforms:
+            tax_benefit_system = tax_benefit_system.apply_reform(reform_path)
+
+    return tax_benefit_system
+
+
+# For retro-compatibility:
+build_tax_benefit_sytem = build_tax_benefit_system
+
+
+def detect_country_package():
+    installed_country_packages = []
+    for module_description in pkgutil.iter_modules():
+        module_name = module_description[1]
+        if "openfisca" in module_name.lower():
+            try:
+                module = importlib.import_module(module_name)
+            except ImportError:
+                message = linesep.join(
+                    [
+                        traceback.format_exc(),
+                        f"Could not import module `{module_name}`.",
+                        "Look at the stack trace above to determine the error that stopped installed modules detection.",
+                    ],
+                )
+                raise ImportError(message)
+            if hasattr(module, "CountryTaxBenefitSystem"):
+                installed_country_packages.append(module_name)
+
+    if len(installed_country_packages) == 0:
+        msg = "No country package has been detected on your environment. If your country package is installed but not detected, please use the --country-package option."
+        raise ImportError(
+            msg,
+        )
+    if len(installed_country_packages) > 1:
+        log.warning(
+            "Several country packages detected : `{}`. Using `{}` by default. To use another package, please use the --country-package option.".format(
+                ", ".join(installed_country_packages),
+                installed_country_packages[0],
+            ),
+        )
+    return installed_country_packages[0]