openfisca-excel-reform 0.0.1__tar.gz

openfisca_excel_reform-0.0.1/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: openfisca-excel-reform
+Version: 0.0.1
+Summary: Add your description here
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: openfisca-core[web-api]>=43
+
+Excel reform provide a way to modify a subtree of parameters with an Excel file.
+
+`TestExcelReformIntegration.test_build_reform_excel_and_generate_template` illustrates how this package can be used.

openfisca_excel_reform-0.0.1/README.md

@@ -0,0 +1,3 @@
+Excel reform provide a way to modify a subtree of parameters with an Excel file.
+
+`TestExcelReformIntegration.test_build_reform_excel_and_generate_template` illustrates how this package can be used.

openfisca_excel_reform-0.0.1/openfisca_excel_reform/__init__.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+from typing import IO, Iterator
+
+from openfisca_core.types import TaxBenefitSystem
+
+from datetime import date
+from pathlib import Path
+
+import openpyxl
+
+from openfisca_core.parameters.parameter_node import ParameterNode
+from openfisca_core.parameters.parameter_scale import ParameterScale
+from openfisca_core.parameters.parameter_scale_bracket import ParameterScaleBracket
+from openfisca_core.reforms import Reform
+
+
+def get_parameter_node(
+    p: ParameterNode, segments: str | list[str]
+) -> tuple[ParameterNode | ParameterScale | ParameterScaleBracket, list[str]]:
+    if isinstance(segments, str):
+        segments = segments.split(".")
+    if segments:
+        if hasattr(p, "children"):
+            return get_parameter_node(p.children[segments[0]], segments[1:])
+        else:
+            return p, segments
+    else:
+        return p, []
+
+
+class ExcelReformBuilder:
+    def __init__(
+        self,
+        baseline: type[TaxBenefitSystem],
+        path_or_file: Path | str | IO[bytes],
+    ) -> None:
+        # data_only = True to get the value stored the last time Excel read the sheet
+        self.wb = openpyxl.load_workbook(path_or_file, data_only=True)
+        self.baseline = baseline
+
+    @property
+    def suffixes(self) -> list[str]:
+        return [
+            sheetname[len("Paramètres") :]
+            for sheetname in self.wb.sheetnames
+            if sheetname.startswith("Paramètres")
+        ]
+
+    @property
+    def reforms(self) -> Iterator[ExcelReform]:
+        for suffix in self.suffixes:
+            yield self.build_reform(suffix)
+
+    @property
+    def root_name(self) -> str:
+        assert self.wb["Config"]["A2"].value == "root"
+        return self.wb["Config"]["B2"].value
+
+    def get_parameters(self, suffix: str) -> list[tuple[str, float, date]]:
+        sheet = self.wb[f"Paramètres{suffix}"]
+        nom_col = [
+            i for i, cell in enumerate(sheet.iter_cols()) if cell[0].value == "Nom"
+        ]
+        valeur_col = [
+            i for i, cell in enumerate(sheet.iter_cols()) if cell[0].value == "Valeur"
+        ]
+        date_col = [
+            i for i, cell in enumerate(sheet.iter_cols()) if cell[0].value == "Date"
+        ]
+
+        assert nom_col, "La colonne 'Nom' est manquante"
+        assert valeur_col is not None, "La colonne 'Valeur' est manquante"
+        assert date_col, "La colonne 'Date' est manquante"
+
+        return [
+            (
+                row[nom_col[0]],
+                row[valeur_col[0]],
+                row[date_col[0]].date(),
+            )
+            for row in sheet.iter_rows(min_row=2, values_only=True)
+            if row[date_col[0]]
+        ]
+
+    def build_reform(self, suffix: str) -> "ExcelReform":
+        return ExcelReform(
+            suffix,
+            self.baseline,
+            self.root_name,
+            self.get_parameters(suffix),
+        )
+
+
+class ExcelReformTemplateGenerator:
+    def __init__(
+        self, baseline: type[TaxBenefitSystem], root_name: str, period: date
+    ) -> None:
+        self.baseline = baseline
+        self.root_name = root_name
+        self.period = period
+
+    def generate_parameter_tree_values(self, parameter) -> list[tuple[str, float]]:
+        values = []
+        if type(parameter) is ParameterNode:
+            for child in parameter.children.values():
+                values.extend(self.generate_parameter_tree_values(child))
+        else:
+            value = parameter.get_at_instant(self.period)
+            name = parameter.name.removeprefix(self.root_name + ".")
+            if type(parameter) is ParameterScale:
+                threshold_values = (
+                    value.amounts
+                    if parameter.metadata.get("type") == "single_amount"
+                    else value.rates
+                )
+                for threshold, val in zip(value.thresholds, threshold_values):
+                    values.append((f"{name}.{threshold}", val))
+            else:
+                if isinstance(value, list):
+                    values.append((name, ", ".join(value)))
+                else:
+                    values.append((name, value))
+        return sorted(values, key=lambda v: v[0])
+
+    def parameter_data(self) -> list[tuple[str, float]]:
+        root_parameter, _ = get_parameter_node(self.baseline.parameters, self.root_name)
+        return self.generate_parameter_tree_values(root_parameter)
+
+    def save_template_xlsx(
+        self,
+        path_or_file: Path | str | IO[bytes],
+    ) -> None:
+        wb = openpyxl.Workbook()
+        ws_config = wb.active
+        ws_config.title = "Config"
+        ws_config.append(["Parameter name", "Parameter value"])
+        ws_config.append(["root", self.root_name])
+
+        wb.create_sheet(title="Paramètres")
+        ws_params = wb["Paramètres"]
+        ws_params.append(["Nom", "Date", "Valeur"])
+
+        for name, value in self.parameter_data():
+            ws_params.append([name, self.period, value])
+
+        # Heuristics to adjust to content
+        ws_params.column_dimensions["A"].width = 70
+        ws_params.column_dimensions["B"].width = 12
+        ws_params.column_dimensions["C"].width = 12
+        wb.active = ws_params
+
+        wb.save(path_or_file)
+
+
+class ExcelReform(Reform):
+    """A class representing a reform defined in an Excel file.
+
+    This class extends the Reform class to provide functionality specific to reforms defined in Excel format.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        baseline: TaxBenefitSystem,
+        root_name: str,
+        reformed_parameters: list[tuple[str, str, date | None]] | None = None,
+    ) -> None:
+        """Initialize the ExcelReform instance.
+
+        :param baseline: Baseline TaxBenefitSystem.
+        :param path: Path to the Excel file defining the reform.
+        :param suffix: Suffix to identify the relevant parameters sheet.
+        """
+        self.name = name
+        self.root_name = root_name
+        self.reformed_parameters = reformed_parameters or []
+        super().__init__(baseline)
+
+    def apply(self):
+        def modify_parameters(local_parameters: ParameterNode) -> ParameterNode:
+            # Go down the parameter tree to the parameter root of this Excel reform
+            root, _ = get_parameter_node(local_parameters, self.root_name)
+            # Dict to track scale-based multiline parameters
+            params_with_thresholds: dict[
+                str, tuple[ParameterScale, list[tuple[float, ParameterScaleBracket]]]
+            ] = dict()
+
+            for name, value, date_ in self.reformed_parameters:
+                leaf, threshold = get_parameter_node(root, name)
+                if type(leaf) is ParameterScale:
+                    threshold_value = float(".".join(threshold))
+                    prop_name = (
+                        "amount"
+                        if leaf.metadata.get("type") == "single_amount"
+                        else "rate"
+                    )
+                    stripped_name = ".".join(name.split(".")[:-1])
+
+                    bracket = ParameterScaleBracket(
+                        data={
+                            "threshold": {
+                                date_.isoformat(): {"value": threshold_value}
+                            },
+                            prop_name: {date_.isoformat(): {"value": value}},
+                        }
+                    )
+
+                    params_with_thresholds.setdefault(stripped_name, (leaf, list()))[
+                        1
+                    ].append(
+                        (
+                            threshold_value,
+                            bracket,
+                        )
+                    )
+                else:
+                    if "unit" in leaf.metadata and leaf.metadata["unit"] == "list":
+                        if value is None:
+                            leaf.update(start=date_, value=[])
+                        else:
+                            values = [
+                                p.replace(",", "").strip() for p in value.split(" ")
+                            ]
+                            leaf.update(start=date_, value=[v for v in values if v])
+                    else:
+                        leaf.update(start=date_, value=value)
+
+            for leaf, threshold in params_with_thresholds.values():
+                sorted_brackets = [v[1] for v in sorted(threshold, key=lambda x: x[0])]
+                leaf.brackets = sorted_brackets
+
+            return local_parameters
+
+        self.modify_parameters(modifier_function=modify_parameters)

openfisca_excel_reform-0.0.1/openfisca_excel_reform.egg-info/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: openfisca-excel-reform
+Version: 0.0.1
+Summary: Add your description here
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: openfisca-core[web-api]>=43
+
+Excel reform provide a way to modify a subtree of parameters with an Excel file.
+
+`TestExcelReformIntegration.test_build_reform_excel_and_generate_template` illustrates how this package can be used.

openfisca_excel_reform-0.0.1/openfisca_excel_reform.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+openfisca_excel_reform/__init__.py
+openfisca_excel_reform.egg-info/PKG-INFO
+openfisca_excel_reform.egg-info/SOURCES.txt
+openfisca_excel_reform.egg-info/dependency_links.txt
+openfisca_excel_reform.egg-info/requires.txt
+openfisca_excel_reform.egg-info/top_level.txt
+tests/test_reform.py

openfisca_excel_reform-0.0.1/openfisca_excel_reform.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openfisca_excel_reform-0.0.1/openfisca_excel_reform.egg-info/requires.txt

@@ -0,0 +1,2 @@
+openpyxl>=3.1.5
+openfisca-core[web-api]>=43

openfisca_excel_reform-0.0.1/openfisca_excel_reform.egg-info/top_level.txt

@@ -0,0 +1 @@
+openfisca_excel_reform

openfisca_excel_reform-0.0.1/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = [ "setuptools>=61" ]
+
+[project]
+name = "openfisca-excel-reform"
+version = "0.0.1"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "openpyxl>=3.1.5",
+    "openfisca-core[web-api]>=43",
+]
+
+[dependency-groups]
+dev = [
+    "openfisca-country-template>=8.0.3",
+    "pytest>=8,<9.0",
+]

openfisca_excel_reform-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

openfisca_excel_reform-0.0.1/tests/test_reform.py

@@ -0,0 +1,308 @@
+from typing import IO
+
+import io
+from datetime import date, datetime, time
+
+import openpyxl
+import pytest
+
+from openfisca_core.parameters.parameter_scale import ParameterScale
+from openfisca_excel_reform import (
+    ExcelReform,
+    ExcelReformBuilder,
+    ExcelReformTemplateGenerator,
+    get_parameter_node,
+)
+
+from openfisca_country_template import CountryTaxBenefitSystem
+
+@pytest.fixture(scope="module")
+def tax_benefit_system():
+    return CountryTaxBenefitSystem()
+
+
+def to_wb_file(wb: openpyxl.Workbook) -> IO[bytes]:
+    bytes = io.BytesIO()
+    wb.save(bytes)
+    bytes.seek(0)
+    return bytes
+
+
+@pytest.fixture
+def wb():
+    wb = openpyxl.Workbook()
+    config_sheet = wb.create_sheet("Config")
+    wb.create_sheet("Paramètres")
+    wb.create_sheet("OtherSheet")
+    config_sheet["A2"] = "root"
+    config_sheet["B2"] = "benefits"
+
+    param_sheet = wb.create_sheet("Paramètres_2025")
+    param_sheet["A1"] = "Nom"
+    param_sheet["B1"] = "Date"
+    param_sheet["C1"] = "Valeur"
+
+    param_sheet.append(["parenting_allowance.amount", date(2025, 1, 1), 100000])
+
+    return wb
+
+
+@pytest.fixture
+def wb_file(wb: openpyxl.Workbook) -> IO[bytes]:
+    return to_wb_file(wb)
+
+
+class TestExcelReformBuilder:
+    def test_get_suffixes(self, wb_file):
+        builder = ExcelReformBuilder(baseline=None, path_or_file=wb_file)
+        suffixes = builder.suffixes
+        assert suffixes == ["", "_2025"]
+
+    def test_get_reform_data(self, wb_file):
+        builder = ExcelReformBuilder(baseline=None, path_or_file=wb_file)
+
+        assert builder.root_name == "benefits"
+        assert builder.get_parameters("_2025") == [
+            ("parenting_allowance.amount", 100000, date(2025, 1, 1))
+        ]
+
+    def test_build_reform(self, tax_benefit_system, wb_file):
+        builder = ExcelReformBuilder(baseline=tax_benefit_system, path_or_file=wb_file)
+        reform = builder.build_reform("_2025")
+
+        assert reform.root_name == "benefits"
+        assert reform.reformed_parameters == [
+            ("parenting_allowance.amount", 100000, date(2025, 1, 1))
+        ]
+
+    def test_pas_de_root(self, tax_benefit_system, wb):
+        ws = wb["Config"]
+        ws.delete_rows(2)
+
+        builder = ExcelReformBuilder(
+            baseline=tax_benefit_system, path_or_file=to_wb_file(wb)
+        )
+        with pytest.raises(AssertionError):
+            builder.build_reform("_2025")
+
+    def test_pas_de_period(self, tax_benefit_system, wb: openpyxl.Workbook):
+        ws = wb["Paramètres_2025"]
+        ws.delete_cols(1)
+
+        builder = ExcelReformBuilder(
+            baseline=tax_benefit_system, path_or_file=to_wb_file(wb)
+        )
+        with pytest.raises(AssertionError):
+            builder.build_reform("_2025")
+
+    def test_get_parameters_shuffled_columns(self, wb):
+        param_sheet = wb["Paramètres_2025"]
+        param_sheet.move_range("B1:B20", cols=2, rows=0)
+        param_sheet.delete_cols(2)
+
+        builder = ExcelReformBuilder(baseline=None, path_or_file=to_wb_file(wb))
+        assert builder.get_parameters("_2025") == [
+            ("parenting_allowance.amount", 100000, date(2025, 1, 1))
+        ]
+
+    def test_get_parameters_with_two_periods(self, wb: openpyxl.Workbook):
+        param_sheet = wb["Paramètres_2025"]
+        param_sheet["A3"] = param_sheet["A2"].value
+        param_sheet["B3"] = date(2026, 1, 1)
+        param_sheet["C3"] = 200000
+
+        builder = ExcelReformBuilder(baseline=None, path_or_file=to_wb_file(wb))
+        assert builder.get_parameters("_2025") == [
+            ("parenting_allowance.amount", 100000, date(2025, 1, 1)),
+            ("parenting_allowance.amount", 200000, date(2026, 1, 1)),
+        ]
+
+
+class TestExcelReform:
+    def test_init(self, tax_benefit_system):
+        reform = ExcelReform(
+            name="name",
+            baseline=tax_benefit_system,
+            root_name="benefits",
+            reformed_parameters=[
+                ("parenting_allowance.amount", 1000.0, date(2025, 1, 1))
+            ],
+        )
+
+        assert reform.root_name == "benefits"
+        assert reform.reformed_parameters == [
+            ("parenting_allowance.amount", 1000.0, date(2025, 1, 1))
+        ]
+
+        parameter, _ = get_parameter_node(
+            reform.parameters, "benefits.parenting_allowance.amount"
+        )
+        assert parameter.get_at_instant("2025-01-01") == 1000.0
+
+    def test_partials_parameters(self, tax_benefit_system):
+        reform = ExcelReform(
+            name="name",
+            baseline=tax_benefit_system,
+            root_name="benefits",
+            reformed_parameters=[
+                ("basic_income", 800.0, date(2026, 1, 1)),
+            ],
+        )
+
+        parameter, _ = get_parameter_node(reform.parameters, "benefits.basic_income")
+        assert parameter.get_at_instant("2024-06-01") == 600.0
+        assert parameter.get_at_instant("2025-06-01") == 600.0
+        assert parameter.get_at_instant("2026-06-01") == 800.0
+
+        parameter2, _ = get_parameter_node(
+            reform.parameters, "benefits.parenting_allowance.amount"
+        )
+        assert parameter2.get_at_instant("2024-06-01") == 600.0
+        assert parameter2.get_at_instant("2025-06-01") == 600.0
+
+    def test_brackets(self, tax_benefit_system):
+        reform = ExcelReform(
+            name="name",
+            baseline=tax_benefit_system,
+            root_name="taxes",
+            reformed_parameters=[
+                ("social_security_contribution.0", 0.01, date(2025, 1, 1)),
+                ("social_security_contribution.3000", 0.03, date(2025, 1, 1)),
+                ("social_security_contribution.6000", 0.13, date(2025, 1, 1)),
+                ("social_security_contribution.12400", 0.001, date(2025, 1, 1)),
+            ],
+        )
+        parameter, _ = get_parameter_node(
+            reform.parameters, "taxes.social_security_contribution"
+        )
+        assert isinstance(parameter, ParameterScale)
+        p_instant = parameter.get_at_instant("2025-01")
+        assert len(p_instant.rates) == 4
+        assert len(p_instant.thresholds) == 4
+        assert p_instant.rates == [0.01, 0.03, 0.13, 0.001]
+        assert p_instant.thresholds == [0.0, 3000.0, 6000.0, 12400.0]
+
+    def test_unsorted_brackets(self, tax_benefit_system):
+        reform = ExcelReform(
+            name="name",
+            baseline=tax_benefit_system,
+            root_name="taxes",
+            reformed_parameters=[
+                ("social_security_contribution.6000", 0.13, date(2025, 1, 1)),
+                ("social_security_contribution.0", 0.01, date(2025, 1, 1)),
+                ("social_security_contribution.12400", 0.001, date(2025, 1, 1)),
+                ("social_security_contribution.3000", 0.03, date(2025, 1, 1)),
+            ],
+        )
+        parameter, _ = get_parameter_node(
+            reform.parameters, "taxes.social_security_contribution"
+        )
+        assert isinstance(parameter, ParameterScale)
+        p_instant = parameter.get_at_instant("2025-01")
+        assert len(p_instant.rates) == 4
+        assert len(p_instant.thresholds) == 4
+        assert p_instant.rates == [0.01, 0.03, 0.13, 0.001]
+        assert p_instant.thresholds == [0.0, 3000.0, 6000.0, 12400.0]
+
+    def test_parameters_with_date(self, tax_benefit_system):
+        reform = ExcelReform(
+            name="name",
+            baseline=tax_benefit_system,
+            root_name="benefits",
+            reformed_parameters=[
+                ("basic_income", 500.0, date(2025, 1, 1)),
+                ("basic_income", 600.0, date(2026, 1, 1)),
+            ],
+        )
+
+        parameter, _ = get_parameter_node(reform.parameters, "benefits.basic_income")
+        assert parameter.get_at_instant("2025-06-01") == 500.0
+        assert parameter.get_at_instant("2026-06-01") == 600.0
+
+    def test_bracket_parameters_with_date(self, tax_benefit_system):
+        reform = ExcelReform(
+            name="name",
+            baseline=tax_benefit_system,
+            root_name="taxes",
+            reformed_parameters=[
+                ("social_security_contribution.0", 0.02, date(2025, 1, 1)),
+                ("social_security_contribution.6000", 0.06, date(2025, 1, 1)),
+                ("social_security_contribution.12400", 0.12, date(2025, 1, 1)),
+                ("social_security_contribution.0", 0.03, date(2026, 1, 1)),
+                ("social_security_contribution.6000", 0.07, date(2026, 1, 1)),
+                ("social_security_contribution.12400", 0.13, date(2026, 1, 1)),
+            ],
+        )
+
+        parameter, _ = get_parameter_node(
+            reform.parameters, "taxes.social_security_contribution"
+        )
+        assert isinstance(parameter, ParameterScale)
+
+        p_instant_2025 = parameter.get_at_instant("2025-06")
+        assert p_instant_2025.rates == [0.02, 0.06, 0.12]
+
+        p_instant_2026 = parameter.get_at_instant("2026-06")
+        assert p_instant_2026.rates == [0.05, 0.13, 0.25]
+
+
+class TestExcelReformTemplateGenerator:
+    def test_generate_parameter_data(self, tax_benefit_system):
+        period = date(2025, 1, 1)
+        generator = ExcelReformTemplateGenerator(tax_benefit_system, "benefits", period)
+        parameters = generator.parameter_data()
+        assert parameters == [
+            ("basic_income", 600.0),
+            ("housing_allowance", None),
+            ("parenting_allowance.amount", 600.0),
+            ("parenting_allowance.income_threshold", 500),
+        ]
+
+    def test_generate_parameter_data_with_scale(self, tax_benefit_system):
+        root_name = "taxes"
+        period = date(2025, 1, 1)
+        generator = ExcelReformTemplateGenerator(tax_benefit_system, root_name, period)
+
+        io_bytes = io.BytesIO()
+        generator.save_template_xlsx(io_bytes)
+
+        io_bytes.seek(0)
+        wb = openpyxl.load_workbook(io_bytes)
+
+        config_sheet = wb["Config"]
+        assert config_sheet["A2"].value == "root"
+        assert config_sheet["B2"].value == root_name
+
+        param_sheet = wb["Paramètres"]
+        rows = list(param_sheet.iter_rows(values_only=True))
+
+        # Deal with Excel date to datetime conversion
+        output_period = datetime.combine(period, time())
+        assert rows == [
+            ("Nom", "Date", "Valeur"),
+            ("housing_tax.minimal_amount", output_period, 200),
+            ("housing_tax.rate", output_period, 10),
+            ("income_tax_rate", output_period, 0.15),
+            ("social_security_contribution.0.0", output_period, 0.02),
+            ("social_security_contribution.12400.0", output_period, 0.12),
+            ("social_security_contribution.6000.0", output_period, 0.06),
+        ]
+
+
+class TestExcelReformIntegration:
+    def test_build_reform_excel_and_generate_template(self, tax_benefit_system):
+        root_name = "taxes"
+        period = date(2025, 1, 1)
+        generator = ExcelReformTemplateGenerator(tax_benefit_system, root_name, period)
+
+        io_bytes = io.BytesIO()
+        generator.save_template_xlsx(io_bytes)
+
+        io_bytes.seek(0)
+        ## Here you could update the Excel file
+
+        builder = ExcelReformBuilder(baseline=tax_benefit_system, path_or_file=io_bytes)
+        assert builder.suffixes == [""]
+
+        reform = builder.build_reform(builder.suffixes[0])
+        assert reform.root_name == root_name