1010
1111
1212class _CoreEntity :
13- """Base class to build entities from."""
13+ """Base class to build entities from.
1414
15- #: A key to identify the entity.
15+ Args:
16+ __key: A key to identify the ``_CoreEntity``.
17+ __plural: The ``key`` pluralised.
18+ __label: A summary description.
19+ __doc: A full description.
20+ *__args: Additional arguments.
21+
22+ """
23+
24+ #: A key to identify the ``_CoreEntity``.
1625 key : t .EntityKey
1726
18- #: The ``key``, pluralised.
27+ #: The ``key`` pluralised.
1928 plural : t .EntityPlural
2029
2130 #: A summary description.
@@ -24,10 +33,10 @@ class _CoreEntity:
2433 #: A full description.
2534 doc : str
2635
27- #: Whether the entity is a person or not.
36+ #: Whether the ``_CoreEntity`` is a person or not.
2837 is_person : ClassVar [bool ]
2938
30- #: A TaxBenefitSystem instance.
39+ #: A `` TaxBenefitSystem`` instance.
3140 _tax_benefit_system : None | t .TaxBenefitSystem = None
3241
3342 @abc .abstractmethod
@@ -44,15 +53,30 @@ def __repr__(self) -> str:
4453 return f"{ self .__class__ .__name__ } { self .key }
4554
4655 def set_tax_benefit_system (self , tax_benefit_system : t .TaxBenefitSystem ) -> None :
47- """An Entity belongs to a TaxBenefitSystem."""
56+ """A ``_CoreEntity`` belongs to a `` TaxBenefitSystem`` ."""
4857 self ._tax_benefit_system = tax_benefit_system
4958
5059 def get_variable (
5160 self ,
5261 variable_name : t .VariableName ,
5362 check_existence : bool = False ,
5463 ) -> t .Variable | None :
55- """Get a ``variable_name`` from ``variables``."""
64+ """Get ``variable_name`` from ``variables``.
65+
66+ Args:
67+ variable_name: The ``Variable`` to be found.
68+ check_existence: Was the ``Variable`` found?
69+
70+ Returns:
71+ Variable: When the ``Variable`` exists.
72+ None: When the ``Variable`` doesn't exist.
73+
74+ Raises:
75+ ValueError: When ``check_existence`` is ``True`` and
76+ the ``Variable`` doesn't exist.
77+
78+ """
79+
5680 if self ._tax_benefit_system is None :
5781 msg = "You must set 'tax_benefit_system' before calling this method."
5882 raise ValueError (
@@ -61,7 +85,21 @@ def get_variable(
6185 return self ._tax_benefit_system .get_variable (variable_name , check_existence )
6286
6387 def check_variable_defined_for_entity (self , variable_name : t .VariableName ) -> None :
64- """Check if ``variable_name`` is defined for ``self``."""
88+ """Check if ``variable_name`` is defined for ``self``.
89+
90+ Args:
91+ variable_name: The ``Variable`` to be found.
92+
93+ Returns:
94+ Variable: When the ``Variable`` exists.
95+ None: When the :attr:`_tax_benefit_system` is not set.
96+
97+ Raises:
98+ ValueError: When the ``Variable`` exists but is defined
99+ for another ``Entity``.
100+
101+ """
102+
65103 entity : None | t .CoreEntity = None
66104 variable : None | t .Variable = self .get_variable (
67105 variable_name ,
@@ -86,7 +124,16 @@ def check_variable_defined_for_entity(self, variable_name: t.VariableName) -> No
86124
87125 @staticmethod
88126 def check_role_validity (role : object ) -> None :
89- """Check if a ``role`` is an instance of Role."""
127+ """Check if ``role`` is an instance of ``Role``.
128+
129+ Args:
130+ role: Any object.
131+
132+ Raises:
133+ ValueError: When ``role`` is not a ``Role``.
134+
135+ """
136+
90137 if role is not None and not isinstance (role , Role ):
91138 msg = f"{ role }
92139 raise ValueError (msg )
0 commit comments