chore(entities): cleanup (#1254)

Author: bonjourmauko

openfisca_core/entities/__init__.py

@@ -1,42 +1,4 @@
-"""Provide a way of representing the entities of a rule system.
-
-Each rule system is comprised by legislation and regulations to be applied upon
-"someone". In legal and economical terms, "someone" is referred to as people:
-individuals, families, tax households, companies, and so on.
-
-People can be either human or non-human, that is a legal entity, also referred
-to as a legal person. Human or non-human, a person is an atomic element of a
-rule system: for example, in most legislations, a salary is invariably owed
-to an individual, and payroll taxes by a company, as a juridical person. In
-OpenFisca, that atomic element is represented as an ``Entity``.
-
-In other cases, legal and regulatory rules are defined for groups or clusters
-of people: for example, income tax is usually due by a tax household, that is
-a group of individuals. There may also be fiduciary entities where the members,
-legal entities, are collectively liable for a property tax. In OpenFisca, those
-cluster elements are represented as a ``GroupEntity``.
-
-In the latter case, the atomic members of a given group may have a different
-``Role`` in the context of a specific rule: for example, income tax
-is due, in some legislations, by a tax household, where we find different
-roles as the declarant, the spouse, the children, and so on…
-
-What's important is that each rule, or in OpenFisca, a ``Variable``
-is defined either for an ``.Entity`` or for a ``GroupEntity``,
-and in the latter case, the way the rule is going to be applied depends
-on the attributes and roles of the members of the group.
-
-Finally, there is a distinction to be made between the "abstract" entities
-described in a rule system, for example an individual, as in "any"
-individual, and an actual individual, like Mauko, Andrea, Mehdi, Seiko,
-or José.
-
-This module provides tools for modelling the former. For the actual
-"simulation" or "application" of any given ``Variable`` to a
-concrete individual or group of individuals, see ``Population``
-and ``GroupPopulation``.
-
-"""
+"""Provide a way of representing the entities of a rule system."""
 
 from . import types
 from ._core_entity import CoreEntity

openfisca_core/entities/_core_entity.py

@@ -113,7 +113,6 @@ def get_variable(
             <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(
@@ -127,10 +126,6 @@ def check_variable_defined_for_entity(self, variable_name: t.VariableName) -> No
         Args:
             variable_name: The ``Variable`` to be found.
 
-        Returns:
-            Variable: When the ``Variable`` exists.
-            None: When the :attr:`_tax_benefit_system` is not set.
-
         Raises:
             ValueError: When the ``Variable`` exists but is defined
                 for another ``Entity``.
@@ -172,7 +167,6 @@ def check_variable_defined_for_entity(self, variable_name: t.VariableName) -> No
             >>> this.check_variable_defined_for_entity("tax")
 
         """
-
         entity: None | t.CoreEntity = None
         variable: None | t.Variable = self.get_variable(
             variable_name,
@@ -216,7 +210,6 @@ def check_role_validity(role: object) -> None:
             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)

openfisca_core/entities/_description.py

@@ -6,7 +6,7 @@
 
 @dataclasses.dataclass(frozen=True)
 class _Description:
-    """A ``Role``'s description.
+    r"""A ``Role``'s description.
 
     Examples:
         >>> data = {

openfisca_core/entities/entity.py

@@ -7,7 +7,7 @@
 
 
 class Entity(CoreEntity):
-    """An entity (e.g. a person, a household) on which calculations can be run.
+    r"""An entity (e.g. a person, a household) on which calculations can be run.
 
     Args:
         key: A key to identify the ``Entity``.

openfisca_core/entities/group_entity.py

@@ -12,7 +12,7 @@
 
 
 class GroupEntity(CoreEntity):
-    """Represents an entity containing several others with different roles.
+    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.

openfisca_core/entities/helpers.py

@@ -70,7 +70,6 @@ def build_entity(
         TypeError: 'Role' object is not subscriptable
 
     """
-
     if is_person:
         return SingleEntity(key, plural, label, doc)
 
@@ -151,7 +150,6 @@ def find_role(
         Role(first_parent)
 
     """
-
     for role in roles:
         if role.subroles:
             for subrole in role.subroles: