OpenFisca-Core-test 46.0.0__py3-none-any.whl

openfisca_core/parameters/config.py

@@ -0,0 +1,55 @@
+import os
+import warnings
+
+import yaml
+
+from openfisca_core.warnings import LibYAMLWarning
+
+try:
+    from yaml import CLoader as Loader
+except ImportError:
+    message = [
+        "libyaml is not installed in your environment.",
+        "This can make OpenFisca slower to start.",
+        "Once you have installed libyaml, run 'pip uninstall pyyaml && pip install pyyaml --no-cache-dir'",
+        "so that it is used in your Python environment." + os.linesep,
+    ]
+    warnings.warn(" ".join(message), LibYAMLWarning, stacklevel=2)
+    from yaml import (  # (see https://github.com/python/mypy/issues/1153#issuecomment-455802270)
+        Loader,
+    )
+
+# 'unit' and 'reference' are only listed here for backward compatibility.
+#  It is now recommended to include them in metadata, until a common consensus emerges.
+ALLOWED_PARAM_TYPES = (float, int, bool, type(None), list, str)
+COMMON_KEYS = {"description", "metadata", "unit", "reference", "documentation"}
+FILE_EXTENSIONS = {".yaml", ".yml"}
+
+
+def date_constructor(_loader, node):
+    return node.value
+
+
+yaml.add_constructor("tag:yaml.org,2002:timestamp", date_constructor, Loader=Loader)
+
+
+def dict_no_duplicate_constructor(loader, node, deep=False):
+    keys = [key.value for key, value in node.value]
+
+    if len(keys) != len(set(keys)):
+        duplicate = next(key for key in keys if keys.count(key) > 1)
+        msg = ""
+        raise yaml.parser.ParserError(
+            msg,
+            node.start_mark,
+            f"Found duplicate key '{duplicate}'",
+        )
+
+    return loader.construct_mapping(node, deep)
+
+
+yaml.add_constructor(
+    yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG,
+    dict_no_duplicate_constructor,
+    Loader=Loader,
+)

openfisca_core/parameters/helpers.py

@@ -0,0 +1,106 @@
+import os
+import traceback
+
+import numpy
+
+from openfisca_core import parameters, periods
+from openfisca_core.errors import ParameterParsingError
+from openfisca_core.parameters import config
+
+
+def contains_nan(vector):
+    if numpy.issubdtype(vector.dtype, numpy.record) or numpy.issubdtype(
+        vector.dtype,
+        numpy.void,
+    ):
+        return any(contains_nan(vector[name]) for name in vector.dtype.names)
+    return numpy.isnan(vector).any()
+
+
+def load_parameter_file(file_path, name=""):
+    """Load parameters from a YAML file (or a directory containing YAML files).
+
+    :returns: An instance of :class:`.ParameterNode` or :class:`.ParameterScale` or :class:`.Parameter`.
+    """
+    if not os.path.exists(file_path):
+        msg = f"{file_path} does not exist"
+        raise ValueError(msg)
+    if os.path.isdir(file_path):
+        return parameters.ParameterNode(name, directory_path=file_path)
+    data = _load_yaml_file(file_path)
+    return _parse_child(name, data, file_path)
+
+
+def _compose_name(path, child_name=None, item_name=None):
+    if not path:
+        return child_name
+    if child_name is not None:
+        return f"{path}.{child_name}"
+    if item_name is not None:
+        return f"{path}[{item_name}]"
+    return None
+
+
+def _load_yaml_file(file_path):
+    with open(file_path) as f:
+        try:
+            return config.yaml.load(f, Loader=config.Loader)
+        except (config.yaml.scanner.ScannerError, config.yaml.parser.ParserError):
+            stack_trace = traceback.format_exc()
+            msg = "Invalid YAML. Check the traceback above for more details."
+            raise ParameterParsingError(
+                msg,
+                file_path,
+                stack_trace,
+            )
+        except Exception:
+            stack_trace = traceback.format_exc()
+            msg = "Invalid parameter file content. Check the traceback above for more details."
+            raise ParameterParsingError(
+                msg,
+                file_path,
+                stack_trace,
+            )
+
+
+def _parse_child(child_name, child, child_path):
+    if "values" in child:
+        return parameters.Parameter(child_name, child, child_path)
+    if "brackets" in child:
+        return parameters.ParameterScale(child_name, child, child_path)
+    if isinstance(child, dict) and all(
+        periods.INSTANT_PATTERN.match(str(key)) for key in child
+    ):
+        return parameters.Parameter(child_name, child, child_path)
+    return parameters.ParameterNode(child_name, data=child, file_path=child_path)
+
+
+def _set_backward_compatibility_metadata(parameter, data) -> None:
+    if data.get("unit") is not None:
+        parameter.metadata["unit"] = data["unit"]
+    if data.get("reference") is not None:
+        parameter.metadata["reference"] = data["reference"]
+
+
+def _validate_parameter(parameter, data, data_type=None, allowed_keys=None) -> None:
+    type_map = {
+        dict: "object",
+        list: "array",
+    }
+
+    if data_type is not None and not isinstance(data, data_type):
+        msg = f"'{parameter.name}' must be of type {type_map[data_type]}."
+        raise ParameterParsingError(
+            msg,
+            parameter.file_path,
+        )
+
+    if allowed_keys is not None:
+        keys = data.keys()
+        for key in keys:
+            if key not in allowed_keys:
+                msg = f"Unexpected property '{key}' in '{parameter.name}'. Allowed properties are {list(allowed_keys)}."
+                raise ParameterParsingError(
+                    msg,
+                    parameter.file_path,
+                )

openfisca_core/parameters/parameter.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+import copy
+import os
+
+from openfisca_core import commons, periods
+from openfisca_core.errors import ParameterParsingError
+
+from . import config, helpers
+from .at_instant_like import AtInstantLike
+from .parameter_at_instant import ParameterAtInstant
+
+
+class Parameter(AtInstantLike):
+    """A parameter of the legislation.
+
+    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:
+
+    >>>  Parameter('rate', data = {
+            "2015-01-01": 550,
+            "2016-01-01": 600
+            })
+
+    Instantiate a parameter with metadata:
+
+    >>>  Parameter('rate', data = {
+            'description': 'Income tax rate applied on salaries',
+            'values': {
+                "2015-01-01": {'value': 550, 'metadata': {'reference': 'http://taxes.gov/income_tax/2015'}},
+                "2016-01-01": {'value': 600, 'metadata': {'reference': 'http://taxes.gov/income_tax/2016'}}
+                }
+            })
+
+    """
+
+    def __init__(self, name: str, data: dict, file_path: str | None = None) -> None:
+        self.name: str = name
+        self.file_path: str | None = file_path
+        helpers._validate_parameter(self, data, data_type=dict)
+        self.description: str | None = None
+        self.metadata: dict = {}
+        self.documentation: str | None = 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.
+        if data.get("values"):
+            # 'unit' and 'reference' are only listed here for backward compatibility
+            helpers._validate_parameter(
+                self,
+                data,
+                allowed_keys=config.COMMON_KEYS.union({"values"}),
+            )
+            self.description = data.get("description")
+
+            helpers._set_backward_compatibility_metadata(self, data)
+            self.metadata.update(data.get("metadata", {}))
+
+            helpers._validate_parameter(self, data["values"], data_type=dict)
+            values = data["values"]
+
+            self.documentation = data.get("documentation")
+
+        else:  # Simplified parameter declaration: only values are provided
+            values = data
+
+        instants = sorted(
+            values.keys(),
+            reverse=True,
+        )  # sort in reverse chronological order
+
+        values_list = []
+        for instant_str in instants:
+            if not periods.INSTANT_PATTERN.match(instant_str):
+                msg = f"Invalid property '{instant_str}' in '{self.name}'. Properties must be valid YYYY-MM-DD instants, such as 2017-01-15."
+                raise ParameterParsingError(
+                    msg,
+                    file_path,
+                )
+
+            instant_info = values[instant_str]
+
+            #  Ignore expected values, as they are just metadata
+            if (
+                instant_info == "expected"
+                or isinstance(instant_info, dict)
+                and instant_info.get("expected")
+            ):
+                continue
+
+            value_name = helpers._compose_name(name, item_name=instant_str)
+            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: list[ParameterAtInstant] = values_list
+
+    def __repr__(self) -> str:
+        return os.linesep.join(
+            [
+                "{}: {}".format(
+                    value.instant_str,
+                    value.value if value.value is not None else "null",
+                )
+                for value in self.values_list
+            ],
+        )
+
+    def __eq__(self, other):
+        return (self.name == other.name) and (self.values_list == other.values_list)
+
+    def clone(self):
+        clone = commons.empty_clone(self)
+        clone.__dict__ = self.__dict__.copy()
+
+        clone.metadata = copy.deepcopy(self.metadata)
+        clone.values_list = [
+            parameter_at_instant.clone() for parameter_at_instant in self.values_list
+        ]
+        return clone
+
+    def update(self, period=None, start=None, stop=None, value=None) -> None:
+        """Change the value for a given period.
+
+        :param period: Period where the value is modified. If set, `start` and `stop` should be `None`.
+        :param start: Start of the period. Instance of `openfisca_core.periods.Instant`. If set, `period` should be `None`.
+        :param stop: Stop of the period. Instance of `openfisca_core.periods.Instant`. If set, `period` should be `None`.
+        :param value: New value. If `None`, the parameter is removed from the legislation parameters for the given period.
+        """
+        if period is not None:
+            if start is not None or stop is not None:
+                msg = "Wrong input for 'update' method: use either 'update(period, value = value)' or 'update(start = start, stop = stop, value = value)'. You cannot both use 'period' and 'start' or 'stop'."
+                raise TypeError(
+                    msg,
+                )
+            if isinstance(period, str):
+                period = periods.period(period)
+            start = period.start
+            stop = period.stop
+        if start is None:
+            msg = "You must provide either a start or a period"
+            raise ValueError(msg)
+        start_str = str(start)
+        stop_str = str(stop.offset(1, "day")) if stop else None
+
+        old_values = self.values_list
+        new_values = []
+        n = len(old_values)
+        i = 0
+
+        # Future intervals : not affected
+        if stop_str:
+            while (i < n) and (old_values[i].instant_str >= stop_str):
+                new_values.append(old_values[i])
+                i += 1
+
+        # Right-overlapped interval
+        if stop_str:
+            if new_values and (stop_str == new_values[-1].instant_str):
+                pass  # such interval is empty
+            elif i < n:
+                overlapped_value = old_values[i].value
+                value_name = helpers._compose_name(self.name, item_name=stop_str)
+                new_interval = ParameterAtInstant(
+                    value_name,
+                    stop_str,
+                    data={"value": overlapped_value},
+                )
+                new_values.append(new_interval)
+            else:
+                value_name = helpers._compose_name(self.name, item_name=stop_str)
+                new_interval = ParameterAtInstant(
+                    value_name,
+                    stop_str,
+                    data={"value": None},
+                )
+                new_values.append(new_interval)
+
+        # Insert new interval
+        value_name = helpers._compose_name(self.name, item_name=start_str)
+        new_interval = ParameterAtInstant(value_name, start_str, data={"value": value})
+        new_values.append(new_interval)
+
+        # Remove covered intervals
+        while (i < n) and (old_values[i].instant_str >= start_str):
+            i += 1
+
+        # Past intervals : not affected
+        while i < n:
+            new_values.append(old_values[i])
+            i += 1
+
+        self.values_list = new_values
+
+    def get_descendants(self):
+        return iter(())
+
+    def _get_at_instant(self, instant):
+        for value_at_instant in self.values_list:
+            if value_at_instant.instant_str <= instant:
+                return value_at_instant.value
+        return None

openfisca_core/parameters/parameter_at_instant.py

@@ -0,0 +1,75 @@
+import copy
+
+from openfisca_core import commons
+from openfisca_core.errors import ParameterParsingError
+from openfisca_core.parameters import config, helpers
+
+
+class ParameterAtInstant:
+    """A value of a parameter at a given instant."""
+
+    # 'unit' and 'reference' are only listed here for backward compatibility
+    _allowed_keys = {"value", "metadata", "unit", "reference"}
+
+    def __init__(
+        self, name, instant_str, data=None, file_path=None, metadata=None
+    ) -> None:
+        """: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
+        self.instant_str: str = instant_str
+        self.file_path: str = file_path
+        self.metadata: dict = {}
+
+        # Accept { 2015-01-01: 4000 }
+        if not isinstance(data, dict) and isinstance(data, config.ALLOWED_PARAM_TYPES):
+            self.value = data
+            return
+
+        self.validate(data)
+        self.value: float = data["value"]
+
+        if metadata is not None:
+            self.metadata.update(metadata)  # Inherit metadata from Parameter
+        helpers._set_backward_compatibility_metadata(self, data)
+        self.metadata.update(data.get("metadata", {}))
+
+    def validate(self, data) -> None:
+        helpers._validate_parameter(
+            self,
+            data,
+            data_type=dict,
+            allowed_keys=self._allowed_keys,
+        )
+        try:
+            value = data["value"]
+        except KeyError:
+            msg = f"Missing 'value' property for {self.name}"
+            raise ParameterParsingError(
+                msg,
+                self.file_path,
+            )
+        if not isinstance(value, config.ALLOWED_PARAM_TYPES):
+            msg = f"Value in {self.name} has type {type(value)}, which is not one of the allowed types ({config.ALLOWED_PARAM_TYPES}): {value}"
+            raise ParameterParsingError(
+                msg,
+                self.file_path,
+            )
+
+    def __eq__(self, other):
+        return (
+            (self.name == other.name)
+            and (self.instant_str == other.instant_str)
+            and (self.value == other.value)
+        )
+
+    def __repr__(self) -> str:
+        return "ParameterAtInstant({self.instant_str: self.value})"
+
+    def clone(self):
+        clone = commons.empty_clone(self)
+        clone.__dict__ = self.__dict__.copy()
+        clone.metadata = copy.deepcopy(self.metadata)
+        return clone

openfisca_core/parameters/parameter_node.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import copy
+import os
+from collections.abc import Iterable
+
+from openfisca_core import commons, parameters, tools
+
+from . import config, helpers
+from .at_instant_like import AtInstantLike
+from .parameter import Parameter
+from .parameter_node_at_instant import ParameterNodeAtInstant
+
+
+class ParameterNode(AtInstantLike):
+    """A node in the legislation `parameter tree <https://openfisca.org/doc/coding-the-legislation/legislation_parameters.html>`_."""
+
+    _allowed_keys: None | Iterable[str] = None  # By default, no restriction on the keys
+
+    def __init__(self, name="", directory_path=None, data=None, file_path=None) -> None:
+        """Instantiate a ParameterNode either from a dict, (using `data`), or from a directory containing YAML files (using `directory_path`).
+
+        :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 str file_path: YAML file from which the `data` has been extracted from.
+
+
+        Instantiate a ParameterNode from a dict:
+
+        >>> node = ParameterNode('basic_income', data = {
+            'amount': {
+              'values': {
+                "2015-01-01": {'value': 550},
+                "2016-01-01": {'value': 600}
+                }
+              },
+            'min_age': {
+              'values': {
+                "2015-01-01": {'value': 25},
+                "2016-01-01": {'value': 18}
+                }
+              },
+            })
+
+        Instantiate a ParameterNode from a directory containing YAML parameter files:
+
+        >>> node = ParameterNode(
+        ...     "benefits",
+        ...     directory_path="/path/to/country_package/parameters/benefits",
+        ... )
+        """
+        self.name: str = name
+        self.children: dict[
+            str,
+            ParameterNode | Parameter | parameters.ParameterScale,
+        ] = {}
+        self.description: str = None
+        self.documentation: str = None
+        self.file_path: str = None
+        self.metadata: dict = {}
+
+        if directory_path:
+            self.file_path = directory_path
+            for child_name in os.listdir(directory_path):
+                child_path = os.path.join(directory_path, child_name)
+                if os.path.isfile(child_path):
+                    child_name, ext = os.path.splitext(child_name)
+
+                    # We ignore non-YAML files
+                    if ext not in config.FILE_EXTENSIONS:
+                        continue
+
+                    if child_name == "index":
+                        data = helpers._load_yaml_file(child_path) or {}
+                        helpers._validate_parameter(
+                            self,
+                            data,
+                            allowed_keys=config.COMMON_KEYS,
+                        )
+                        self.description = data.get("description")
+                        self.documentation = data.get("documentation")
+                        helpers._set_backward_compatibility_metadata(self, data)
+                        self.metadata.update(data.get("metadata", {}))
+                    else:
+                        child_name_expanded = helpers._compose_name(name, child_name)
+                        child = helpers.load_parameter_file(
+                            child_path,
+                            child_name_expanded,
+                        )
+                        self.add_child(child_name, child)
+
+                elif os.path.isdir(child_path):
+                    child_name = os.path.basename(child_path)
+                    child_name_expanded = helpers._compose_name(name, child_name)
+                    child = ParameterNode(
+                        child_name_expanded,
+                        directory_path=child_path,
+                    )
+                    self.add_child(child_name, child)
+
+        else:
+            self.file_path = file_path
+            helpers._validate_parameter(
+                self,
+                data,
+                data_type=dict,
+                allowed_keys=self._allowed_keys,
+            )
+            self.description = data.get("description")
+            self.documentation = data.get("documentation")
+            helpers._set_backward_compatibility_metadata(self, data)
+            self.metadata.update(data.get("metadata", {}))
+            for child_name, child in data.items():
+                if child_name in config.COMMON_KEYS:
+                    continue  # do not treat reserved keys as subparameters.
+
+                child_name = str(child_name)
+                child_name_expanded = helpers._compose_name(name, child_name)
+                child = helpers._parse_child(child_name_expanded, child, file_path)
+                self.add_child(child_name, child)
+
+    def merge(self, other) -> None:
+        """Merges another ParameterNode into the current node.
+
+        In case of child name conflict, the other node child will replace the current node child.
+        """
+        for child_name, child in other.children.items():
+            self.add_child(child_name, child)
+
+    def add_child(self, name, child) -> None:
+        """Add a new child to the node.
+
+        :param name: Name of the child that must be used to access that child. Should not contain anything that could interfere with the operator `.` (dot).
+        :param child: The new child, an instance of :class:`.ParameterScale` or :class:`.Parameter` or :class:`.ParameterNode`.
+        """
+        if name in self.children:
+            msg = f"{self.name} has already a child named {name}"
+            raise ValueError(msg)
+        if not (
+            isinstance(child, (ParameterNode, Parameter, parameters.ParameterScale))
+        ):
+            msg = f"child must be of type ParameterNode, Parameter, or Scale. Instead got {type(child)}"
+            raise TypeError(
+                msg,
+            )
+        self.children[name] = child
+        setattr(self, name, child)
+
+    def __repr__(self) -> str:
+        return os.linesep.join(
+            [
+                os.linesep.join(["{}:", "{}"]).format(name, tools.indent(repr(value)))
+                for name, value in sorted(self.children.items())
+            ],
+        )
+
+    def get_descendants(self):
+        """Return a generator containing all the parameters and nodes recursively contained in this `ParameterNode`."""
+        for child in self.children.values():
+            yield child
+            yield from child.get_descendants()
+
+    def clone(self):
+        clone = commons.empty_clone(self)
+        clone.__dict__ = self.__dict__.copy()
+
+        clone.metadata = copy.deepcopy(self.metadata)
+        clone.children = {key: child.clone() for key, child in self.children.items()}
+        for child_key, child in clone.children.items():
+            setattr(clone, child_key, child)
+
+        return clone
+
+    def _get_at_instant(self, instant):
+        return ParameterNodeAtInstant(self.name, self, instant)

openfisca_core/parameters/parameter_node_at_instant.py

@@ -0,0 +1,57 @@
+import os
+
+import numpy
+
+from openfisca_core import parameters, tools
+from openfisca_core.errors import ParameterNotFoundError
+from openfisca_core.parameters import helpers
+
+
+class ParameterNodeAtInstant:
+    """Parameter node of the legislation, at a given instant."""
+
+    def __init__(self, name, node, instant_str) -> None:
+        """:param name: Name of the node.
+        :param node: Original :any:`ParameterNode` instance.
+        :param instant_str: A date in the format `YYYY-MM-DD`.
+        """
+        # The "technical" attributes are hidden, so that the node children can be easily browsed with auto-completion without pollution
+        self._name = name
+        self._instant_str = instant_str
+        self._children = {}
+
+        for child_name, child in node.children.items():
+            child_at_instant = child._get_at_instant(instant_str)
+            if child_at_instant is not None:
+                self.add_child(child_name, child_at_instant)
+
+    def add_child(self, child_name, child_at_instant) -> None:
+        self._children[child_name] = child_at_instant
+        setattr(self, child_name, child_at_instant)
+
+    def __getattr__(self, key):
+        param_name = helpers._compose_name(self._name, item_name=key)
+        raise ParameterNotFoundError(param_name, self._instant_str)
+
+    def __getitem__(self, key):
+        # If fancy indexing is used, cast to a vectorial node
+        if isinstance(key, numpy.ndarray):
+            return parameters.VectorialParameterNodeAtInstant.build_from_node_name(
+                self, key
+            )
+        try:
+            return self._children[key]
+        except KeyError:
+            param_name = helpers._compose_name(self._name, item_name=key)
+            raise ParameterNotFoundError(param_name, self._instant_str)
+
+    def __iter__(self):
+        return iter(self._children)
+
+    def __repr__(self) -> str:
+        return os.linesep.join(
+            [
+                os.linesep.join(["{}:", "{}"]).format(name, tools.indent(repr(value)))
+                for name, value in self._children.items()
+            ],
+        )