Fix docstrings

Author: MattiSG

CHANGELOG.md

@@ -1,10 +1,16 @@
 # Changelog
 
+### 35.8.4 [#1131](https://github.com/openfisca/openfisca-core/pull/1131)
+
+#### Technical changes
+
+- Correct some type hints and docstrings.
+
 ### 35.8.3 [#1127](https://github.com/openfisca/openfisca-core/pull/1127)
 
 #### Technical changes
 
-- Fix the build for Anaconda in CI. The conda build failed on master because of a replacement in a comment string. 
+- Fix the build for Anaconda in CI. The conda build failed on master because of a replacement in a comment string.
   - The _ were removed in the comment to avoid a replace.
 
 ### 35.8.2 [#1128](https://github.com/openfisca/openfisca-core/pull/1128)

openfisca_core/parameters/parameter.py

@@ -1,21 +1,28 @@
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
 import copy
 import os
-import typing
 
 from openfisca_core import commons, periods
 from openfisca_core.errors import ParameterParsingError
 from openfisca_core.parameters import config, helpers, AtInstantLike, ParameterAtInstant
 
 
 class Parameter(AtInstantLike):
-    """
-    A parameter of the legislation. Parameters can change over time.
+    """A parameter of the legislation.
 
-    :param string name: Name of the parameter, e.g. "taxes.some_tax.some_param"
-    :param dict data: Data loaded from a YAML file.
-    :param string file_path: File the parameter was loaded from.
-    :param string documentation: Documentation describing parameter usage and context.
+    Parameters can change over time.
 
+    Attributes:
+        values_list: List of the values, in reverse chronological order.
+
+
+    Args:
+        name: Name of the parameter, e.g. "taxes.some_tax.some_param".
+        data: Data loaded from a YAML file.
+        file_path: File the parameter was loaded from.
 
     Instantiate a parameter without metadata:
 
@@ -34,18 +41,15 @@ class Parameter(AtInstantLike):
                 }
             })
 
-    .. attribute:: values_list
-
-       List of the values, in reverse chronological order
     """
 
-    def __init__(self, name, data, file_path = None):
+    def __init__(self, name: str, data: dict, file_path: Optional[str] = None) -> None:
         self.name: str = name
-        self.file_path: str = file_path
+        self.file_path: Optional[str] = file_path
         helpers._validate_parameter(self, data, data_type = dict)
-        self.description: str = None
-        self.metadata: typing.Dict = {}
-        self.documentation: str = None
+        self.description: Optional[str] = None
+        self.metadata: Dict = {}
+        self.documentation: Optional[str] = None
         self.values_history = self  # Only for backward compatibility
 
         # Normal parameter declaration: the values are declared under the 'values' key: parse the description and metadata.
@@ -85,7 +89,7 @@ def __init__(self, name, data, file_path = None):
             value_at_instant = ParameterAtInstant(value_name, instant_str, data = instant_info, file_path = self.file_path, metadata = self.metadata)
             values_list.append(value_at_instant)
 
-        self.values_list: typing.List[ParameterAtInstant] = values_list
+        self.values_list: List[ParameterAtInstant] = values_list
 
     def __repr__(self):
         return os.linesep.join([

openfisca_core/parameters/parameter_at_instant.py

@@ -16,8 +16,8 @@ class ParameterAtInstant:
 
     def __init__(self, name, instant_str, data = None, file_path = None, metadata = None):
         """
-        :param string name: name of the parameter, e.g. "taxes.some_tax.some_param"
-        :param string instant_str: Date of the value in the format `YYYY-MM-DD`.
+        :param str name: name of the parameter, e.g. "taxes.some_tax.some_param"
+        :param str instant_str: Date of the value in the format `YYYY-MM-DD`.
         :param dict data: Data, usually loaded from a YAML file.
         """
         self.name: str = name

openfisca_core/parameters/parameter_node.py

@@ -19,10 +19,10 @@ def __init__(self, name = "", directory_path = None, data = None, file_path = No
         """
         Instantiate a ParameterNode either from a dict, (using `data`), or from a directory containing YAML files (using `directory_path`).
 
-        :param string name: Name of the node, eg "taxes.some_tax".
-        :param string directory_path: Directory containing YAML files describing the node.
+        :param str name: Name of the node, eg "taxes.some_tax".
+        :param str directory_path: Directory containing YAML files describing the node.
         :param dict data: Object representing the parameter node. It usually has been extracted from a YAML file.
-        :param string file_path: YAML file from which the `data` has been extracted from.
+        :param str file_path: YAML file from which the `data` has been extracted from.
 
 
         Instantiate a ParameterNode from a dict:

openfisca_core/reforms/reform.py

@@ -1,17 +1,17 @@
+from __future__ import annotations
+
 import copy
 
 from openfisca_core.parameters import ParameterNode
 from openfisca_core.taxbenefitsystems import TaxBenefitSystem
 
 
 class Reform(TaxBenefitSystem):
-    """
-        A modified TaxBenefitSystem
+    """A modified TaxBenefitSystem
 
+    All reforms must subclass `Reform` and implement a method `apply()`.
 
-        All reforms must subclass `Reform` and implement a method `apply()`.
-
-        In this method, the reform can add or replace variables and call `modify_parameters` to modify the parameters of the legislation.
+    In this method, the reform can add or replace variables and call `modify_parameters` to modify the parameters of the legislation.
 
         Example:
 
@@ -64,12 +64,12 @@ def full_key(self):
         return key
 
     def modify_parameters(self, modifier_function):
-        """
-        Make modifications on the parameters of the legislation
+        """Make modifications on the parameters of the legislation.
 
         Call this function in `apply()` if the reform asks for legislation parameter modifications.
 
-        :param modifier_function: A function that takes an object of type :any:`ParameterNode` and should return an object of the same type.
+        Args:
+            modifier_function: A function that takes a :obj:`.ParameterNode` and should return an object of the same type.
         """
         baseline_parameters = self.baseline.parameters
         baseline_parameters_copy = copy.deepcopy(baseline_parameters)

openfisca_core/taxbenefitsystems/tax_benefit_system.py

@@ -1,3 +1,7 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Sequence
+
 import copy
 import glob
 import importlib
@@ -27,28 +31,27 @@ class TaxBenefitSystem:
 
     It stores parameters (values defined for everyone) and variables (values defined for some given entity e.g. a person).
 
-    :param entities: Entities used by the tax benefit system.
-    :param string parameters: Directory containing the YAML parameter files.
-
+    Attributes:
+        parameters: Directory containing the YAML parameter files.
 
-    .. attribute:: parameters
+    Args:
+        entities: Entities used by the tax benefit system.
 
-       :obj:`.ParameterNode` containing the legislation parameters
     """
     _base_tax_benefit_system = None
-    _parameters_at_instant_cache = None
+    _parameters_at_instant_cache: Optional[Dict[Any, Any]] = None
     person_key_plural = None
     preprocess_parameters = None
     baseline = None  # Baseline tax-benefit system. Used only by reforms. Note: Reforms can be chained.
     cache_blacklist = None
     decomposition_file_path = None
 
-    def __init__(self, entities):
+    def __init__(self, entities: Sequence[Entity]) -> None:
         # TODO: Currently: Don't use a weakref, because they are cleared by Paste (at least) at each call.
-        self.parameters = None
+        self.parameters: Optional[ParameterNode] = None
         self._parameters_at_instant_cache = {}  # weakref.WeakValueDictionary()
-        self.variables = {}
-        self.open_api_config = {}
+        self.variables: Dict[Any, Any] = {}
+        self.open_api_config: Dict[Any, Any] = {}
         # Tax benefit systems are mutable, so entities (which need to know about our variables) can't be shared among them
         if entities is None or len(entities) == 0:
             raise Exception("A tax and benefit sytem must have at least an entity.")
@@ -139,13 +142,15 @@ def load_variable(self, variable_class, update = False):
 
         return variable
 
-    def add_variable(self, variable):
-        """
-        Adds an OpenFisca variable to the tax and benefit system.
+    def add_variable(self, variable: Variable) -> Variable:
+        """Adds an OpenFisca variable to the tax and benefit system.
+
+        Args:
+            variable: The variable to add. Must be a subclass of Variable.
 
-        :param .Variable variable: The variable to add. Must be a subclass of Variable.
+        Raises:
+            openfisca_core.errors.VariableNameConflictError: if a variable with the same name have previously been added to the tax and benefit system.
 
-        :raises: :exc:`.VariableNameConflictError` if a variable with the same name have previously been added to the tax and benefit system.
         """
         return self.load_variable(variable, update = False)
 
@@ -231,7 +236,7 @@ def load_extension(self, extension):
         """
         Loads an extension to the tax and benefit system.
 
-        :param string extension: The extension to load. Can be an absolute path pointing to an extension directory, or the name of an OpenFisca extension installed as a pip package.
+        :param str extension: The extension to load. Can be an absolute path pointing to an extension directory, or the name of an OpenFisca extension installed as a pip package.
 
         """
         # Load extension from installed pip package
@@ -251,19 +256,20 @@ def load_extension(self, extension):
             extension_parameters = ParameterNode(directory_path = param_dir)
             self.parameters.merge(extension_parameters)
 
-    def apply_reform(self, reform_path):
-        """
-        Generates a new tax and benefit system applying a reform to the tax and benefit system.
+    def apply_reform(self, reform_path: str) -> "TaxBenefitSystem":
+        """Generates a new tax and benefit system applying a reform to the tax and benefit system.
 
         The current tax and benefit system is **not** mutated.
 
-        :param string reform_path: The reform to apply. Must respect the format *installed_package.sub_module.reform*
+        Args:
+            reform_path: The reform to apply. Must respect the format *installed_package.sub_module.reform*
 
-        :returns: A reformed tax and benefit system.
+        Returns:
+            TaxBenefitSystem: A reformed tax and benefit system.
 
         Example:
 
-        >>> self.apply_reform('openfisca_france.reforms.inversion_revenus')
+            >>> self.apply_reform('openfisca_france.reforms.inversion_revenus')
 
         """
         from openfisca_core.reforms import Reform
@@ -412,9 +418,9 @@ def get_variables(self, entity = None):
         """
         Gets all variables contained in a tax and benefit system.
 
-        :param .Entity entity: If set, returns only the variable defined for the given entity.
+        :param Entity entity: If set, returns only the variable defined for the given entity.
 
-        :returns: A dictionnary, indexed by variable names.
+        :returns: A dictionary, indexed by variable names.
         :rtype: dict
 
         """

openfisca_core/tools/test_runner.py

@@ -44,7 +44,7 @@ def run_tests(tax_benefit_system, paths, options = None):
 
     If `path` is a directory, subdirectories will be recursively explored.
 
-    :param .TaxBenefitSystem tax_benefit_system: the tax-benefit system to use to run the tests
+    :param TaxBenefitSystem tax_benefit_system: the tax-benefit system to use to run the tests
     :param str or list paths: A path, or a list of paths, towards the files or directories containing the tests to run. If a path is a directory, subdirectories will be recursively explored.
     :param dict options: See more details below.
 

openfisca_core/variables/variable.py

@@ -309,7 +309,7 @@ def get_formula(self, period = None):
         If no period is given and the variable has several formula, return the oldest formula.
 
         :returns: Formula used to compute the variable
-        :rtype: .Formula
+        :rtype: :any:`Formula`
 
         """
 

setup.py

@@ -47,7 +47,7 @@
 
 setup(
     name = 'OpenFisca-Core',
-    version = '35.8.3',
+    version = '35.8.4',
     author = 'OpenFisca Team',
     author_email = 'contact@openfisca.org',
     classifiers = [