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

openfisca_core/entities/_core_entity.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+import abc
+import os
+from typing import ClassVar
+
+from . import types as t
+from .role import Role
+
+
+class CoreEntity:
+    """Base class to build entities from.
+
+    Args:
+        *__args: Any arguments.
+        **__kwargs: Any keyword arguments.
+
+    Examples:
+        >>> from openfisca_core import entities
+        >>> from openfisca_core.entities import types as t
+
+        >>> class Entity(entities.CoreEntity):
+        ...     def __init__(self, key):
+        ...         self.key = t.EntityKey(key)
+
+        >>> Entity("individual")
+        Entity(individual)
+
+    """
+
+    #: A key to identify the ``CoreEntity``.
+    key: t.EntityKey
+
+    #: The ``key`` pluralised.
+    plural: t.EntityPlural
+
+    #: A summary description.
+    label: str
+
+    #: A full description.
+    doc: str
+
+    #: Whether the ``CoreEntity`` is a person or not.
+    is_person: ClassVar[bool]
+
+    #: A ``TaxBenefitSystem`` instance.
+    _tax_benefit_system: None | t.TaxBenefitSystem = None
+
+    @abc.abstractmethod
+    def __init__(self, *__args: object, **__kwargs: object) -> None: ...
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.key})"
+
+    def set_tax_benefit_system(self, tax_benefit_system: t.TaxBenefitSystem) -> None:
+        """A ``CoreEntity`` belongs to a ``TaxBenefitSystem``."""
+        self._tax_benefit_system = tax_benefit_system
+
+    def get_variable(
+        self,
+        variable_name: t.VariableName,
+        check_existence: bool = False,
+    ) -> t.Variable | None:
+        """Get ``variable_name`` from ``variables``.
+
+        Args:
+            variable_name: The ``Variable`` to be found.
+            check_existence: Was the ``Variable`` found?
+
+        Returns:
+            Variable: When the ``Variable`` exists.
+            None: When the ``Variable`` doesn't exist.
+
+        Raises:
+            ValueError: When the :attr:`_tax_benefit_system` is not set yet.
+            ValueError: When ``check_existence`` is ``True`` and
+                the ``Variable`` doesn't exist.
+
+        Examples:
+            >>> from openfisca_core import (
+            ...     entities,
+            ...     periods,
+            ...     taxbenefitsystems,
+            ...     variables,
+            ... )
+
+            >>> this = entities.SingleEntity("this", "", "", "")
+            >>> that = entities.SingleEntity("that", "", "", "")
+
+            >>> this.get_variable("tax")
+            Traceback (most recent call last):
+            ValueError: You must set 'tax_benefit_system' before calling this...
+
+            >>> tax_benefit_system = taxbenefitsystems.TaxBenefitSystem([this])
+            >>> this.set_tax_benefit_system(tax_benefit_system)
+
+            >>> this.get_variable("tax")
+
+            >>> this.get_variable("tax", check_existence=True)
+            Traceback (most recent call last):
+            VariableNotFoundError: You tried to calculate or to set a value...
+
+            >>> class tax(variables.Variable):
+            ...     definition_period = periods.MONTH
+            ...     value_type = float
+            ...     entity = that
+
+            >>> this._tax_benefit_system.add_variable(tax)
+            <openfisca_core.entities._core_entity.tax object at ...>
+
+            >>> this.get_variable("tax")
+            <openfisca_core.entities._core_entity.tax object at ...>
+
+        """
+        if self._tax_benefit_system is None:
+            msg = "You must set 'tax_benefit_system' before calling this method."
+            raise ValueError(
+                msg,
+            )
+        return self._tax_benefit_system.get_variable(variable_name, check_existence)
+
+    def check_variable_defined_for_entity(self, variable_name: t.VariableName) -> None:
+        """Check if ``variable_name`` is defined for ``self``.
+
+        Args:
+            variable_name: The ``Variable`` to be found.
+
+        Raises:
+            ValueError: When the ``Variable`` exists but is defined
+                for another ``Entity``.
+
+        Examples:
+            >>> from openfisca_core import (
+            ...     entities,
+            ...     periods,
+            ...     taxbenefitsystems,
+            ...     variables,
+            ... )
+
+            >>> this = entities.SingleEntity("this", "", "", "")
+            >>> that = entities.SingleEntity("that", "", "", "")
+            >>> tax_benefit_system = taxbenefitsystems.TaxBenefitSystem([that])
+            >>> this.set_tax_benefit_system(tax_benefit_system)
+
+            >>> this.check_variable_defined_for_entity("tax")
+            Traceback (most recent call last):
+            VariableNotFoundError: You tried to calculate or to set a value...
+
+            >>> class tax(variables.Variable):
+            ...     definition_period = periods.WEEK
+            ...     value_type = int
+            ...     entity = that
+
+            >>> this._tax_benefit_system.add_variable(tax)
+            <openfisca_core.entities._core_entity.tax object at ...>
+
+            >>> this.check_variable_defined_for_entity("tax")
+            Traceback (most recent call last):
+            ValueError: You tried to compute the variable 'tax' for the enti...
+
+            >>> tax.entity = this
+
+            >>> this._tax_benefit_system.update_variable(tax)
+            <openfisca_core.entities._core_entity.tax object at ...>
+
+            >>> this.check_variable_defined_for_entity("tax")
+
+        """
+        entity: None | t.CoreEntity = None
+        variable: None | t.Variable = self.get_variable(
+            variable_name,
+            check_existence=True,
+        )
+
+        if variable is not None:
+            entity = variable.entity
+
+        if entity is None:
+            return
+
+        if entity.key != self.key:
+            message = (
+                f"You tried to compute the variable '{variable_name}' for",
+                f"the entity '{self.plural}'; however the variable",
+                f"'{variable_name}' is defined for '{entity.plural}'.",
+                "Learn more about entities in our documentation:",
+                "<https://openfisca.org/doc/coding-the-legislation/50_entities.html>.",
+            )
+            raise ValueError(os.linesep.join(message))
+
+    @staticmethod
+    def check_role_validity(role: object) -> None:
+        """Check if ``role`` is an instance of  ``Role``.
+
+        Args:
+            role: Any object.
+
+        Raises:
+            ValueError: When ``role`` is not a ``Role``.
+
+        Examples:
+            >>> from openfisca_core import entities
+
+            >>> role = entities.Role({"key": "key"}, object())
+            >>> entities.check_role_validity(role)
+
+            >>> entities.check_role_validity("hey!")
+            Traceback (most recent call last):
+            ValueError: hey! is not a valid role
+
+        """
+        if role is not None and not isinstance(role, Role):
+            msg = f"{role} is not a valid role"
+            raise ValueError(msg)
+
+
+__all__ = ["CoreEntity"]

openfisca_core/entities/_description.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import dataclasses
+import textwrap
+
+
+@dataclasses.dataclass(frozen=True)
+class _Description:
+    r"""A ``Role``'s description.
+
+    Examples:
+        >>> data = {
+        ...     "key": "parent",
+        ...     "label": "Parents",
+        ...     "plural": "parents",
+        ...     "doc": "\t\t\tThe one/two adults in charge of the household.",
+        ... }
+
+        >>> description = _Description(**data)
+
+        >>> repr(_Description)
+        "<class 'openfisca_core.entities._description._Description'>"
+
+        >>> repr(description)
+        "_Description(key='parent', plural='parents', label='Parents', ...)"
+
+        >>> str(description)
+        "_Description(key='parent', plural='parents', label='Parents', ...)"
+
+        >>> {description}
+        {_Description(key='parent', plural='parents', label='Parents', doc=...}
+
+        >>> description.key
+        'parent'
+
+    """
+
+    #: A key to identify the ``Role``.
+    key: str
+
+    #: The ``key`` pluralised.
+    plural: None | str = None
+
+    #: A summary description.
+    label: None | str = None
+
+    #: A full description, non-indented.
+    doc: None | str = None
+
+    def __post_init__(self) -> None:
+        if self.doc is not None:
+            object.__setattr__(self, "doc", textwrap.dedent(self.doc))
+
+
+__all__ = ["_Description"]

openfisca_core/entities/entity.py

@@ -0,0 +1,60 @@
+import textwrap
+from typing import ClassVar
+
+from . import types as t
+from ._core_entity import CoreEntity
+
+
+class Entity(CoreEntity):
+    r"""An entity (e.g. a person, a household) on which calculations can be run.
+
+    Args:
+        key: A key to identify the ``Entity``.
+        plural: The ``key`` pluralised.
+        label: A summary description.
+        doc: A full description.
+
+    Examples:
+        >>> from openfisca_core import entities
+
+        >>> entity = entities.SingleEntity(
+        ...     "individual",
+        ...     "individuals",
+        ...     "An individual",
+        ...     "\t\t\tThe minimal legal entity on which a rule might be a...",
+        ... )
+
+        >>> repr(entities.SingleEntity)
+        "<class 'openfisca_core.entities.entity.Entity'>"
+
+        >>> repr(entity)
+        'Entity(individual)'
+
+        >>> str(entity)
+        'Entity(individual)'
+
+    """
+
+    #: A key to identify the ``Entity``.
+    key: t.EntityKey
+
+    #: The ``key`` pluralised.
+    plural: t.EntityPlural
+
+    #: A summary description.
+    label: str
+
+    #: A full description.
+    doc: str
+
+    #: Whether the ``Entity`` is a person or not.
+    is_person: ClassVar[bool] = True
+
+    def __init__(self, key: str, plural: str, label: str, doc: str) -> None:
+        self.key = t.EntityKey(key)
+        self.plural = t.EntityPlural(plural)
+        self.label = label
+        self.doc = textwrap.dedent(doc)
+
+
+__all__ = ["Entity"]

openfisca_core/entities/group_entity.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import textwrap
+from collections.abc import Iterable, Sequence
+from itertools import chain
+from typing import ClassVar
+
+from . import types as t
+from ._core_entity import CoreEntity
+from .role import Role
+
+
+class GroupEntity(CoreEntity):
+    r"""Represents an entity containing several others with different roles.
+
+    A ``GroupEntity`` represents an ``Entity`` containing several other entities,
+    with different roles, and on which calculations can be run.
+
+    Args:
+        key: A key to identify the ``GroupEntity``.
+        plural: The ``key`` pluralised.
+        label: A summary description.
+        doc: A full description.
+        roles: The list of roles of the group entity.
+        containing_entities: The list of keys of group entities whose members
+            are guaranteed to be a superset of this group's entities.
+
+    Examples:
+        >>> from openfisca_core import entities
+
+        >>> family_roles = [
+        ...     {
+        ...         "key": "parent",
+        ...         "subroles": ["first_parent", "second_parent"],
+        ...     }
+        ... ]
+
+        >>> family = entities.GroupEntity(
+        ...     "family",
+        ...     "families",
+        ...     "A family",
+        ...     "\t\t\tAll the people somehow related living together.",
+        ...     family_roles,
+        ... )
+
+        >>> household_roles = [
+        ...     {
+        ...         "key": "partners",
+        ...         "subroles": ["first_partner", "second_partner"],
+        ...     }
+        ... ]
+
+        >>> household = entities.GroupEntity(
+        ...     "household",
+        ...     "households",
+        ...     "A household",
+        ...     "\t\t\tAll the people who live together in the same place.",
+        ...     household_roles,
+        ...     (family.key,),
+        ... )
+
+        >>> repr(entities.GroupEntity)
+        "<class 'openfisca_core.entities.group_entity.GroupEntity'>"
+
+        >>> repr(household)
+        'GroupEntity(household)'
+
+        >>> str(household)
+        'GroupEntity(household)'
+
+    """
+
+    #: A key to identify the ``Entity``.
+    key: t.EntityKey
+
+    #: The ``key`` pluralised.
+    plural: t.EntityPlural
+
+    #: A summary description.
+    label: str
+
+    #: A full description.
+    doc: str
+
+    #: The list of roles of the ``GroupEntity``.
+    roles: Iterable[Role]
+
+    #: Whether the entity is a person or not.
+    is_person: ClassVar[bool] = False
+
+    def __init__(
+        self,
+        key: str,
+        plural: str,
+        label: str,
+        doc: str,
+        roles: Sequence[t.RoleParams],
+        containing_entities: Iterable[str] = (),
+    ) -> None:
+        self.key = t.EntityKey(key)
+        self.plural = t.EntityPlural(plural)
+        self.label = label
+        self.doc = textwrap.dedent(doc)
+        self.roles_description = roles
+        self.roles: Iterable[Role] = ()
+        for role_description in roles:
+            role = Role(role_description, self)
+            setattr(self, role.key.upper(), role)
+            self.roles = (*self.roles, role)
+            if subroles := role_description.get("subroles"):
+                role.subroles = ()
+                for subrole_key in subroles:
+                    subrole = Role({"key": subrole_key, "max": 1}, self)
+                    setattr(self, subrole.key.upper(), subrole)
+                    role.subroles = (*role.subroles, subrole)
+                role.max = len(role.subroles)
+        self.flattened_roles = tuple(
+            chain.from_iterable(role.subroles or [role] for role in self.roles),
+        )
+        self.containing_entities = containing_entities
+
+
+__all__ = ["GroupEntity"]

openfisca_core/entities/helpers.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+
+from . import types as t
+from .entity import Entity as SingleEntity
+from .group_entity import GroupEntity
+
+
+def build_entity(
+    key: str,
+    plural: str,
+    label: str,
+    doc: str = "",
+    roles: None | Sequence[t.RoleParams] = None,
+    is_person: bool = False,
+    *,
+    class_override: object = None,
+    containing_entities: Sequence[str] = (),
+) -> t.SingleEntity | t.GroupEntity:
+    """Build an ``Entity`` or a ``GroupEntity``.
+
+    Args:
+        key: Key to identify the ``Entity`` or ``GroupEntity``.
+        plural: The ``key`` pluralised.
+        label: A summary description.
+        doc: A full description.
+        roles: A list of roles —if it's a ``GroupEntity``.
+        is_person: If is an individual, or not.
+        class_override: ?
+        containing_entities: Keys of contained entities.
+
+    Returns:
+        Entity: When ``is_person`` is ``True``.
+        GroupEntity: When ``is_person`` is ``False``.
+
+    Raises:
+        NotImplementedError: If ``roles`` is ``None``.
+
+    Examples:
+        >>> from openfisca_core import entities
+
+        >>> entity = entities.build_entity(
+        ...     "syndicate",
+        ...     "syndicates",
+        ...     "Banks loaning jointly.",
+        ...     roles=[],
+        ...     containing_entities=(),
+        ... )
+        >>> entity
+        GroupEntity(syndicate)
+
+        >>> entities.build_entity(
+        ...     "company",
+        ...     "companies",
+        ...     "A small or medium company.",
+        ...     is_person=True,
+        ... )
+        Entity(company)
+
+        >>> role = entities.Role({"key": "key"}, entity)
+
+        >>> entities.build_entity(
+        ...     "syndicate",
+        ...     "syndicates",
+        ...     "Banks loaning jointly.",
+        ...     roles=[role],
+        ... )
+        Traceback (most recent call last):
+        TypeError: 'Role' object is not subscriptable
+
+    """
+    if is_person:
+        return SingleEntity(key, plural, label, doc)
+
+    if roles is not None:
+        return GroupEntity(
+            key,
+            plural,
+            label,
+            doc,
+            roles,
+            containing_entities=containing_entities,
+        )
+
+    raise NotImplementedError
+
+
+def find_role(
+    roles: Iterable[t.Role],
+    key: t.RoleKey,
+    *,
+    total: None | int = None,
+) -> None | t.Role:
+    """Find a ``Role`` in a ``GroupEntity``.
+
+    Args:
+        roles: The roles to search.
+        key: The key of the role to find.
+        total: The ``max`` attribute of the role to find.
+
+    Returns:
+        Role: The role if found
+        None: Else ``None``.
+
+    Examples:
+        >>> from openfisca_core import entities
+        >>> from openfisca_core.entities import types as t
+
+        >>> principal = t.RoleParams(
+        ...     key="principal",
+        ...     label="Principal",
+        ...     doc="Person focus of a calculation in a family context.",
+        ...     max=1,
+        ... )
+
+        >>> partner = t.RoleParams(
+        ...     key="partner",
+        ...     plural="partners",
+        ...     label="Partners",
+        ...     doc="Persons partners of the principal.",
+        ... )
+
+        >>> parent = t.RoleParams(
+        ...     key="parent",
+        ...     plural="parents",
+        ...     label="Parents",
+        ...     doc="Persons parents of children of the principal",
+        ...     subroles=["first_parent", "second_parent"],
+        ... )
+
+        >>> group_entity = entities.build_entity(
+        ...     key="family",
+        ...     plural="families",
+        ...     label="Family",
+        ...     doc="A Family represents a collection of related persons.",
+        ...     roles=[principal, partner, parent],
+        ... )
+
+        >>> entities.find_role(group_entity.roles, "principal", total=1)
+        Role(principal)
+
+        >>> entities.find_role(group_entity.roles, "partner")
+        Role(partner)
+
+        >>> entities.find_role(group_entity.roles, "parent", total=2)
+        Role(parent)
+
+        >>> entities.find_role(group_entity.roles, "first_parent", total=1)
+        Role(first_parent)
+
+    """
+    for role in roles:
+        if role.subroles:
+            for subrole in role.subroles:
+                if (subrole.max == total) and (subrole.key == key):
+                    return subrole
+
+        if (role.max == total) and (role.key == key):
+            return role
+
+    return None
+
+
+__all__ = ["build_entity", "find_role"]