refactor: consolidate entities types

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+### 43.3.6 [#1324](https://github.com/openfisca/openfisca-core/pull/1324)
+
+#### Technical changes
+
+- Move types from `openfisca_core.entities` to `openfisca_core`
+
 ### 43.3.5 [#1325](https://github.com/openfisca/openfisca-core/pull/1325)
 
 #### Documentation

openfisca_core/entities/__init__.py

@@ -1,6 +1,5 @@
 """Provide a way of representing the entities of a rule system."""
 
-from . import types
 from ._core_entity import CoreEntity
 from .entity import Entity
 from .group_entity import GroupEntity
@@ -19,5 +18,4 @@
     "build_entity",
     "check_role_validity",
     "find_role",
-    "types",
 ]

openfisca_core/entities/_core_entity.py

@@ -5,7 +5,8 @@
 import abc
 import os
 
-from . import types as t
+from openfisca_core import types as t
+
 from .role import Role
 
 
@@ -17,8 +18,7 @@ class CoreEntity:
         **__kwargs: Any keyword arguments.
 
     Examples:
-        >>> from openfisca_core import entities
-        >>> from openfisca_core.entities import types as t
+        >>> from openfisca_core import entities, types as t
 
         >>> class Entity(entities.CoreEntity):
         ...     def __init__(self, key):
@@ -61,7 +61,7 @@ def get_variable(
         self,
         variable_name: t.VariableName,
         check_existence: bool = False,
-    ) -> t.Variable | None:
+    ) -> None | t.Variable:
         """Get ``variable_name`` from ``variables``.
 
         Args:

openfisca_core/entities/entity.py

@@ -2,7 +2,8 @@
 
 import textwrap
 
-from . import types as t
+from openfisca_core import types as t
+
 from ._core_entity import CoreEntity
 
 

openfisca_core/entities/group_entity.py

@@ -6,7 +6,8 @@
 import textwrap
 from itertools import chain
 
-from . import types as t
+from openfisca_core import types as t
+
 from ._core_entity import CoreEntity
 from .role import Role
 
@@ -84,7 +85,7 @@ class GroupEntity(CoreEntity):
     doc: str
 
     #: The list of roles of the ``GroupEntity``.
-    roles: Iterable[Role]
+    roles: Iterable[t.Role]
 
     #: Whether the entity is a person or not.
     is_person: ClassVar[bool] = False
@@ -103,7 +104,7 @@ def __init__(
         self.label = label
         self.doc = textwrap.dedent(doc)
         self.roles_description = roles
-        self.roles: Iterable[Role] = ()
+        self.roles: Iterable[t.Role] = ()
         for role_description in roles:
             role = Role(role_description, self)
             setattr(self, role.key.upper(), role)

openfisca_core/entities/helpers.py

@@ -2,7 +2,8 @@
 
 from collections.abc import Iterable, Sequence
 
-from . import types as t
+from openfisca_core import types as t
+
 from .entity import Entity as SingleEntity
 from .group_entity import GroupEntity
 
@@ -15,7 +16,6 @@ def build_entity(
     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``.
@@ -27,7 +27,6 @@ def build_entity(
         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:
@@ -104,8 +103,7 @@ def find_role(
         None: Else ``None``.
 
     Examples:
-        >>> from openfisca_core import entities
-        >>> from openfisca_core.entities import types as t
+        >>> from openfisca_core import entities, types as t
 
         >>> principal = t.RoleParams(
         ...     key="principal",

openfisca_core/entities/role.py

@@ -2,7 +2,8 @@
 
 from collections.abc import Iterable
 
-from . import types as t
+from openfisca_core import types as t
+
 from ._description import _Description
 
 
@@ -51,7 +52,7 @@ class Role:
     max: None | int = None
 
     #: A list of subroles.
-    subroles: None | Iterable[Role] = None
+    subroles: None | Iterable[t.Role] = None
 
     @property
     def key(self) -> t.RoleKey:

openfisca_core/types.py

@@ -128,38 +128,61 @@ class SeqInt(list[int], metaclass=_SeqIntMeta): ...  # type: ignore[misc]
 
 
 class CoreEntity(Protocol):
-    key: EntityKey
-    plural: EntityPlural
-
-    def check_role_validity(self, role: object, /) -> None: ...
+    @property
+    def key(self, /) -> EntityKey: ...
+    @property
+    def plural(self, /) -> EntityPlural: ...
+    @property
+    def label(self, /) -> str: ...
+    @property
+    def doc(self, /) -> str: ...
+    def set_tax_benefit_system(self, __tbs: TaxBenefitSystem, /) -> None: ...
+    def get_variable(
+        self, __name: VariableName, __check: bool = ..., /
+    ) -> None | Variable: ...
     def check_variable_defined_for_entity(
         self,
-        variable_name: VariableName,
+        __name: VariableName,
         /,
     ) -> None: ...
-    def get_variable(
-        self,
-        variable_name: VariableName,
-        check_existence: bool = ...,
-        /,
-    ) -> None | Variable: ...
+    @staticmethod
+    def check_role_validity(__role: object, /) -> None: ...
 
 
 class SingleEntity(CoreEntity, Protocol): ...
 
 
-class GroupEntity(CoreEntity, Protocol): ...
+class GroupEntity(CoreEntity, Protocol):
+    @property
+    def roles(self, /) -> Iterable[Role]: ...
+    @property
+    def flattened_roles(self, /) -> Iterable[Role]: ...
 
 
 class Role(Protocol):
-    entity: GroupEntity
-    max: int | None
-    subroles: None | Iterable[Role]
-
+    @property
+    def entity(self, /) -> GroupEntity: ...
+    @property
+    def max(self, /) -> None | int: ...
+    @property
+    def subroles(self, /) -> None | Iterable[Role]: ...
     @property
     def key(self, /) -> RoleKey: ...
     @property
     def plural(self, /) -> None | RolePlural: ...
+    @property
+    def label(self, /) -> None | str: ...
+    @property
+    def doc(self, /) -> None | str: ...
+
+
+class RoleParams(TypedDict, total=False):
+    key: Required[str]
+    plural: str
+    label: str
+    doc: str
+    max: int
+    subroles: list[str]
 
 
 # Indexed enums

setup.py

@@ -70,7 +70,7 @@
 
 setup(
     name="OpenFisca-Core",
-    version="43.3.5",
+    version="43.3.6",
     author="OpenFisca Team",
     author_email="[email protected]",
     classifiers=[