docs(enums): add docs to enums

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+### 42.0.8 [#1272](https://github.com/openfisca/openfisca-core/pull/1272)
+
+#### Documentation
+
+- Add documentation to the `indexed_enums` module
+
 ### 42.0.7 [#1264](https://github.com/openfisca/openfisca-core/pull/1264)
 
 #### Technical changes

openfisca_core/commons/__init__.py

@@ -1,55 +1,4 @@
-"""Common tools for contributors and users.
-
-The tools in this sub-package are intended, to help both contributors
-to OpenFisca Core and to country packages.
-
-Official Public API:
-    * :func:`.apply_thresholds`
-    * :func:`.average_rate`
-    * :func:`.concat`
-    * :func:`.empty_clone`
-    * :func:`.eval_expression`
-    * :func:`.marginal_rate`
-    * :func:`.stringify_array`
-    * :func:`.switch`
-
-Deprecated:
-    * :class:`.Dummy`
-
-Note:
-    The ``deprecated`` imports are transitional, in order to ensure non-breaking
-    changes, and could be removed from the codebase in the next
-    major release.
-
-Note:
-    How imports are being used today::
-
-        from openfisca_core.commons import *  # Bad
-        from openfisca_core.commons.formulas import switch  # Bad
-        from openfisca_core.commons.decorators import deprecated  # Bad
-
-
-    The previous examples provoke cyclic dependency problems, that prevent us
-    from modularizing the different components of the library, which would make
-    them easier to test and to maintain.
-
-    How they could be used in a future release::
-
-        from openfisca_core import commons
-        from openfisca_core.commons import deprecated
-
-        deprecated()  # Good: import classes as publicly exposed
-        commons.switch()  # Good: use functions as publicly exposed
-
-    .. seealso:: `PEP8#Imports`_ and `OpenFisca's Styleguide`_.
-
-    .. _PEP8#Imports:
-        https://www.python.org/dev/peps/pep-0008/#imports
-
-    .. _OpenFisca's Styleguide:
-        https://github.com/openfisca/openfisca-core/blob/master/STYLEGUIDE.md
-
-"""
+"""Common tools for contributors and users."""
 
 from . import types
 from .dummy import Dummy

openfisca_core/commons/formulas.py

@@ -24,10 +24,7 @@ def apply_thresholds(
         choices: A list of the possible values to choose from.
 
     Returns:
-        Array[numpy.float32]: A list of the values chosen.
-
-    Raises:
-        AssertionError: When thresholds and choices are incompatible.
+        ndarray[float32]: A list of the values chosen.
 
     Examples:
         >>> input = numpy.array([4, 5, 6, 7, 8])
@@ -37,7 +34,6 @@ def apply_thresholds(
         array([10, 10, 15, 15, 20])
 
     """
-
     condlist: list[t.Array[numpy.bool_] | bool]
     condlist = [input <= threshold for threshold in thresholds]
 
@@ -66,7 +62,7 @@ def concat(
         that: Another array to concatenate.
 
     Returns:
-        Array[numpy.str_]: An array with the concatenated values.
+        ndarray[str_]: An array with the concatenated values.
 
     Examples:
         >>> this = ["this", "that"]
@@ -75,7 +71,6 @@ def concat(
         array(['this1.0', 'that2.5']...)
 
     """
-
     if not isinstance(this, numpy.ndarray):
         this = numpy.array(this)
 
@@ -105,10 +100,7 @@ def switch(
         value_by_condition: Values to replace for each condition.
 
     Returns:
-        Array: An array with the replaced values.
-
-    Raises:
-        AssertionError: When ``value_by_condition`` is empty.
+        ndarray[float32]: An array with the replaced values.
 
     Examples:
         >>> conditions = numpy.array([1, 1, 1, 2])

openfisca_core/commons/misc.py

@@ -13,7 +13,7 @@ def empty_clone(original: object) -> object:
         original: An object to clone.
 
     Returns:
-        The cloned, empty, object.
+        object: The cloned, empty, object.
 
     Examples:
         >>> Foo = type("Foo", (list,), {})
@@ -50,7 +50,7 @@ def stringify_array(array: None | t.Array[numpy.generic]) -> str:
         array: An array.
 
     Returns:
-        str: "None" if the ``array`` is None.
+        str: ``"None"`` if the ``array`` is ``None``.
         str: The stringified ``array`` otherwise.
 
     Examples:
@@ -71,7 +71,6 @@ def stringify_array(array: None | t.Array[numpy.generic]) -> str:
         "[<class 'list'>, {}, <function stringify_array...]"
 
     """
-
     if array is None:
         return "None"
 
@@ -87,7 +86,7 @@ def eval_expression(
         expression: An expression to evaluate.
 
     Returns:
-        Array: The result of the evaluation.
+        ndarray: The result of the evaluation.
         str: The expression if it couldn't be evaluated.
 
     Examples:
@@ -98,7 +97,6 @@ def eval_expression(
         'salary'
 
     """
-
     try:
         return numexpr.evaluate(expression)
 

openfisca_core/commons/rates.py

@@ -25,9 +25,9 @@ def average_rate(
         trim: The lower and upper bounds of the average rate.
 
     Returns:
-        Array[numpy.float32]: The average rate for each target. When ``trim``
+        ndarray[float32]: The average rate for each target. When ``trim``
             is provided, values that are out of the provided bounds are
-            replaced by :any:`numpy.nan`.
+            replaced by :obj:`numpy.nan`.
 
     Examples:
         >>> target = numpy.array([1, 2, 3])
@@ -37,7 +37,6 @@ def average_rate(
         array([ nan,  0. , -0.5])
 
     """
-
     if not isinstance(varying, numpy.ndarray):
         varying = numpy.array(varying, dtype=numpy.float32)
 
@@ -79,9 +78,9 @@ def marginal_rate(
         trim: The lower and upper bounds of the marginal rate.
 
     Returns:
-        Array[numpy.float32]: The marginal rate for each target. When ``trim``
-        is provided, values that are out of the provided bounds are replaced by
-        :any:`numpy.nan`.
+        ndarray[float32]: The marginal rate for each target. When ``trim``
+            is provided, values that are out of the provided bounds are
+            replaced by :class:`numpy.nan`.
 
     Examples:
         >>> target = numpy.array([1, 2, 3])
@@ -91,7 +90,6 @@ def marginal_rate(
         array([nan, 0.5])
 
     """
-
     if not isinstance(varying, numpy.ndarray):
         varying = numpy.array(varying, dtype=numpy.float32)
 

openfisca_core/commons/tests/test_dummy.py

@@ -5,6 +5,5 @@
 
 def test_dummy_deprecation() -> None:
     """Dummy throws a deprecation warning when instantiated."""
-
     with pytest.warns(DeprecationWarning):
         assert Dummy()

openfisca_core/commons/tests/test_formulas.py

@@ -7,7 +7,6 @@
 
 def test_apply_thresholds_when_several_inputs() -> None:
     """Make a choice for any given input."""
-
     input_ = numpy.array([4, 5, 6, 7, 8, 9, 10])
     thresholds = [5, 7, 9]
     choices = [10, 15, 20, 25]
@@ -19,7 +18,6 @@ def test_apply_thresholds_when_several_inputs() -> None:
 
 def test_apply_thresholds_when_too_many_thresholds() -> None:
     """Raise an AssertionError when thresholds > choices."""
-
     input_ = numpy.array([6])
     thresholds = [5, 7, 9, 11]
     choices = [10, 15, 20]
@@ -30,7 +28,6 @@ def test_apply_thresholds_when_too_many_thresholds() -> None:
 
 def test_apply_thresholds_when_too_many_choices() -> None:
     """Raise an AssertionError when thresholds < choices - 1."""
-
     input_ = numpy.array([6])
     thresholds = [5, 7]
     choices = [10, 15, 20, 25]
@@ -41,7 +38,6 @@ def test_apply_thresholds_when_too_many_choices() -> None:
 
 def test_concat_when_this_is_array_not_str() -> None:
     """Cast ``this`` to ``str`` when it is a NumPy array other than string."""
-
     this = numpy.array([1, 2])
     that = numpy.array(["la", "o"])
 
@@ -52,7 +48,6 @@ def test_concat_when_this_is_array_not_str() -> None:
 
 def test_concat_when_that_is_array_not_str() -> None:
     """Cast ``that`` to ``str`` when it is a NumPy array other than string."""
-
     this = numpy.array(["ho", "cha"])
     that = numpy.array([1, 2])
 
@@ -63,7 +58,6 @@ def test_concat_when_that_is_array_not_str() -> None:
 
 def test_concat_when_args_not_str_array_like() -> None:
     """Cast ``this`` and ``that`` to a NumPy array or strings."""
-
     this = (1, 2)
     that = (3, 4)
 
@@ -74,7 +68,6 @@ def test_concat_when_args_not_str_array_like() -> None:
 
 def test_switch_when_values_are_empty() -> None:
     """Raise an AssertionError when the values are empty."""
-
     conditions = [1, 1, 1, 2]
     value_by_condition = {}
 

openfisca_core/commons/tests/test_rates.py

@@ -8,7 +8,6 @@
 
 def test_average_rate_when_varying_is_zero() -> None:
     """Yield infinity when the varying gross income crosses zero."""
-
     target = numpy.array([1, 2, 3])
     varying = [0, 0, 0]
 
@@ -19,7 +18,6 @@ def test_average_rate_when_varying_is_zero() -> None:
 
 def test_marginal_rate_when_varying_is_zero() -> None:
     """Yield infinity when the varying gross income crosses zero."""
-
     target = numpy.array([1, 2, 3])
     varying = numpy.array([0, 0, 0])
 

openfisca_core/data_storage/__init__.py

@@ -1,25 +1,4 @@
-# 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
+"""Different storage backends for the data of a simulation."""
 
 from . import types
 from .in_memory_storage import InMemoryStorage