policyengine 3.2.0__tar.gz → 3.2.1__tar.gz

policyengine-3.2.1/.github/bump_version.py

@@ -0,0 +1,77 @@
+"""Infer semver bump from towncrier fragment types and update version."""
+
+import re
+import sys
+from pathlib import Path
+
+
+def get_current_version(pyproject_path: Path) -> str:
+    text = pyproject_path.read_text()
+    match = re.search(r'^version\s*=\s*"(\d+\.\d+\.\d+)"', text, re.MULTILINE)
+    if not match:
+        print(
+            "Could not find version in pyproject.toml",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    return match.group(1)
+
+
+def infer_bump(changelog_dir: Path) -> str:
+    fragments = [
+        f for f in changelog_dir.iterdir() if f.is_file() and f.name != ".gitkeep"
+    ]
+    if not fragments:
+        print("No changelog fragments found", file=sys.stderr)
+        sys.exit(1)
+
+    categories = {f.suffix.lstrip(".") for f in fragments}
+    for f in fragments:
+        parts = f.stem.split(".")
+        if len(parts) >= 2:
+            categories.add(parts[-1])
+
+    if "breaking" in categories:
+        return "major"
+    if "added" in categories or "removed" in categories:
+        return "minor"
+    return "patch"
+
+
+def bump_version(version: str, bump: str) -> str:
+    major, minor, patch = (int(x) for x in version.split("."))
+    if bump == "major":
+        return f"{major + 1}.0.0"
+    elif bump == "minor":
+        return f"{major}.{minor + 1}.0"
+    else:
+        return f"{major}.{minor}.{patch + 1}"
+
+
+def update_file(path: Path, old_version: str, new_version: str):
+    text = path.read_text()
+    updated = text.replace(
+        f'version = "{old_version}"',
+        f'version = "{new_version}"',
+    )
+    if updated != text:
+        path.write_text(updated)
+        print(f"  Updated {path}")
+
+
+def main():
+    root = Path(__file__).resolve().parent.parent
+    pyproject = root / "pyproject.toml"
+    changelog_dir = root / "changelog.d"
+
+    current = get_current_version(pyproject)
+    bump = infer_bump(changelog_dir)
+    new = bump_version(current, bump)
+
+    print(f"Version: {current} -> {new} ({bump})")
+
+    update_file(pyproject, current, new)
+
+
+if __name__ == "__main__":
+    main()

{policyengine-3.2.0 → policyengine-3.2.1}/.github/fetch_version.py

@@ -1,8 +1,8 @@
 def fetch_version():
     try:
-        import importlib
+        from importlib.metadata import version
 
-        return importlib.import_module("policyengine").__version__
+        return version("policyengine")
     except Exception as e:
         print(f"Error fetching version: {e}")
         return None

{policyengine-3.2.0 → policyengine-3.2.1}/.github/workflows/code_changes.yaml

@@ -21,8 +21,14 @@ jobs:
         - name: Install ruff
           run: pip install ruff
 
+        - name: Run ruff format check
+          run: ruff format --check .
+
         - name: Run ruff check
           run: ruff check .
+
+        - name: Run ruff format check
+          run: ruff format --check .
   Test:
       runs-on: macos-latest
       permissions:

{policyengine-3.2.0 → policyengine-3.2.1}/.github/workflows/pr_code_changes.yaml

@@ -3,9 +3,6 @@
 name: Code changes
 on:
   pull_request:
-    branches:
-      - main
-
     paths:
       - src/**
       - tests/**
@@ -21,8 +18,25 @@ jobs:
         - name: Install ruff
           run: pip install ruff
 
+        - name: Run ruff format check
+          run: ruff format --check .
+
         - name: Run ruff check
           run: ruff check .
+  Mypy:
+    runs-on: ubuntu-latest
+    steps:
+        - uses: actions/checkout@v4
+        - name: Install uv
+          uses: astral-sh/setup-uv@v5
+        - name: Set up Python
+          uses: actions/setup-python@v5
+          with:
+              python-version: '3.13'
+        - name: Install package
+          run: uv pip install -e .[dev] --system
+        - name: Run mypy (informational)
+          run: mypy src/policyengine || echo "::warning::mypy found errors (non-blocking until codebase is clean)"
   Test:
     runs-on: macos-latest
     strategy:

{policyengine-3.2.0 → policyengine-3.2.1}/.github/workflows/versioning.yaml

@@ -7,7 +7,7 @@ on:
       - main
 
     paths:
-      - changelog_entry.yaml
+      - changelog.d/**
       - .github/**
   workflow_dispatch:
 
@@ -27,7 +27,7 @@ jobs:
         with:
           python-version: 3.13
       - name: Build changelog
-        run: pip install yaml-changelog && make changelog
+        run: pip install yaml-changelog towncrier && make changelog
       - name: Preview changelog update
         run: ".github/get-changelog-diff.sh"
       - name: Update changelog
@@ -66,3 +66,10 @@ jobs:
           user: __token__
           password: ${{ secrets.PYPI }}
           skip_existing: true
+      - name: Create GitHub Release
+        run: |
+          VERSION=$(python .github/fetch_version.py)
+          gh release create "$VERSION" \
+            --title "v$VERSION" \
+            --notes "See [CHANGELOG.md](https://github.com/PolicyEngine/policyengine.py/blob/main/CHANGELOG.md) for details." \
+            --latest

{policyengine-3.2.0 → policyengine-3.2.1}/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [3.2.1] - 2026-03-10
+
+### Changed
+
+- Migrated from changelog_entry.yaml to towncrier fragments to eliminate merge conflicts.
+- Switched code formatter from black to ruff format.
+
+
 # Changelog
 
 All notable changes to this project will be documented in this file.

{policyengine-3.2.0 → policyengine-3.2.1}/Makefile

@@ -21,14 +21,10 @@ clean:
 	find . -not -path "./.venv/*" -type f -name "*.h5" -delete
 
 changelog:
-	build-changelog changelog.yaml --output changelog.yaml --update-last-date --start-from 1.0.0 --append-file changelog_entry.yaml
-	build-changelog changelog.yaml --org PolicyEngine --repo policyengine.py --output CHANGELOG.md --template .github/changelog_template.md
-	bump-version changelog.yaml pyproject.toml
-	rm changelog_entry.yaml || true
-	touch changelog_entry.yaml
-
+	python .github/bump_version.py
+	towncrier build --yes --version $$(python -c "import re; print(re.search(r'version = \"(.+?)\"', open('pyproject.toml').read()).group(1))")
 build-package:
 	python -m build
 
 test:
-	pytest tests
+	pytest tests --cov=policyengine --cov-report=term-missing

{policyengine-3.2.0 → policyengine-3.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: policyengine
-Version: 3.2.0
+Version: 3.2.1
 Summary: A package to conduct policy analysis using PolicyEngine tax-benefit models.
 Author-email: PolicyEngine <hello@policyengine.org>
 License:                     GNU AFFERO GENERAL PUBLIC LICENSE
@@ -683,7 +683,6 @@ Provides-Extra: us
 Requires-Dist: policyengine_core>=3.23.6; extra == "us"
 Requires-Dist: policyengine-us>=1.213.1; extra == "us"
 Provides-Extra: dev
-Requires-Dist: black; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: furo; extra == "dev"
 Requires-Dist: autodoc_pydantic; extra == "dev"
@@ -692,10 +691,13 @@ Requires-Dist: yaml-changelog>=0.1.7; extra == "dev"
 Requires-Dist: itables; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.26.0; extra == "dev"
-Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: ruff>=0.9.0; extra == "dev"
 Requires-Dist: policyengine_core>=3.23.6; extra == "dev"
 Requires-Dist: policyengine-uk>=2.51.0; extra == "dev"
 Requires-Dist: policyengine-us>=1.213.1; extra == "dev"
+Requires-Dist: towncrier>=24.8.0; extra == "dev"
+Requires-Dist: mypy>=1.11.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
 Dynamic: license-file
 
 # PolicyEngine.py
@@ -748,10 +750,94 @@ print(f"Total UC spending: £{agg.result / 1e9:.1f}bn")
 
 ## Installation
 
+### As a library
+
 ```bash
 pip install policyengine
 ```
 
+This installs both UK and US country models. To install only one:
+
+```bash
+pip install policyengine[uk]    # UK model only
+pip install policyengine[us]    # US model only
+```
+
+### For development
+
+```bash
+git clone https://github.com/PolicyEngine/policyengine.py.git
+cd policyengine.py
+uv pip install -e .[dev]        # install with dev dependencies (pytest, ruff, mypy, etc.)
+```
+
+## Development
+
+### Running configurations
+
+| Configuration | Install | Use case |
+|---------------|---------|----------|
+| **Library user** | `pip install policyengine` | Using the package in your own code |
+| **UK only** | `pip install policyengine[uk]` | Only need UK simulations |
+| **US only** | `pip install policyengine[us]` | Only need US simulations |
+| **Developer** | `uv pip install -e .[dev]` | Contributing to the package |
+
+### Common commands
+
+```bash
+make format           # ruff format
+make test             # pytest with coverage
+make docs             # build Jupyter Book documentation
+make clean            # remove caches, build artifacts, .h5 files
+```
+
+### Testing
+
+Tests require a `HUGGING_FACE_TOKEN` environment variable for downloading datasets:
+
+```bash
+export HUGGING_FACE_TOKEN=hf_...
+make test
+```
+
+To run a specific test:
+
+```bash
+pytest tests/test_models.py -v
+pytest tests/test_parametric_reforms.py -k "test_uk" -v
+```
+
+### Linting and type checking
+
+```bash
+ruff format .                    # format code
+ruff check .                     # lint
+mypy src/policyengine            # type check (informational — not yet enforced in CI)
+```
+
+### CI pipeline
+
+PRs trigger the following checks:
+
+| Check | Status | Command |
+|-------|--------|---------|
+| Lint + format | Required | `ruff check .` + `ruff format --check .` |
+| Tests (Python 3.13) | Required | `make test` |
+| Tests (Python 3.14) | Required | `make test` |
+| Mypy | Informational | `mypy src/policyengine` |
+| Docs build | Required | Jupyter Book build |
+
+### Versioning and releases
+
+This project uses [towncrier](https://towncrier.readthedocs.io/) for changelog management. When making a PR, add a changelog fragment:
+
+```bash
+# Fragment types: breaking, added, changed, fixed, removed
+echo "Description of change" > changelog.d/my-change.added
+```
+
+On merge, the versioning workflow bumps the version, builds the changelog, and creates a GitHub Release.
+
 ## Features
 
 - **Multi-country support**: UK and US tax-benefit systems

{policyengine-3.2.0 → policyengine-3.2.1}/README.md

@@ -48,10 +48,94 @@ print(f"Total UC spending: £{agg.result / 1e9:.1f}bn")
 
 ## Installation
 
+### As a library
+
 ```bash
 pip install policyengine
 ```
 
+This installs both UK and US country models. To install only one:
+
+```bash
+pip install policyengine[uk]    # UK model only
+pip install policyengine[us]    # US model only
+```
+
+### For development
+
+```bash
+git clone https://github.com/PolicyEngine/policyengine.py.git
+cd policyengine.py
+uv pip install -e .[dev]        # install with dev dependencies (pytest, ruff, mypy, etc.)
+```
+
+## Development
+
+### Running configurations
+
+| Configuration | Install | Use case |
+|---------------|---------|----------|
+| **Library user** | `pip install policyengine` | Using the package in your own code |
+| **UK only** | `pip install policyengine[uk]` | Only need UK simulations |
+| **US only** | `pip install policyengine[us]` | Only need US simulations |
+| **Developer** | `uv pip install -e .[dev]` | Contributing to the package |
+
+### Common commands
+
+```bash
+make format           # ruff format
+make test             # pytest with coverage
+make docs             # build Jupyter Book documentation
+make clean            # remove caches, build artifacts, .h5 files
+```
+
+### Testing
+
+Tests require a `HUGGING_FACE_TOKEN` environment variable for downloading datasets:
+
+```bash
+export HUGGING_FACE_TOKEN=hf_...
+make test
+```
+
+To run a specific test:
+
+```bash
+pytest tests/test_models.py -v
+pytest tests/test_parametric_reforms.py -k "test_uk" -v
+```
+
+### Linting and type checking
+
+```bash
+ruff format .                    # format code
+ruff check .                     # lint
+mypy src/policyengine            # type check (informational — not yet enforced in CI)
+```
+
+### CI pipeline
+
+PRs trigger the following checks:
+
+| Check | Status | Command |
+|-------|--------|---------|
+| Lint + format | Required | `ruff check .` + `ruff format --check .` |
+| Tests (Python 3.13) | Required | `make test` |
+| Tests (Python 3.14) | Required | `make test` |
+| Mypy | Informational | `mypy src/policyengine` |
+| Docs build | Required | Jupyter Book build |
+
+### Versioning and releases
+
+This project uses [towncrier](https://towncrier.readthedocs.io/) for changelog management. When making a PR, add a changelog fragment:
+
+```bash
+# Fragment types: breaking, added, changed, fixed, removed
+echo "Description of change" > changelog.d/my-change.added
+```
+
+On merge, the versioning workflow bumps the version, builds the changelog, and creates a GitHub Release.
+
 ## Features
 
 - **Multi-country support**: UK and US tax-benefit systems

{policyengine-3.2.0 → policyengine-3.2.1}/examples/employment_income_variation_uk.py

@@ -125,17 +125,12 @@ def create_dataset_with_varied_employment_income(
         "region": ["LONDON"] * n_households,  # Required by policyengine-uk
         "council_tax": [0.0] * n_households,  # Simplified - no council tax
         "rent": [median_annual_rent] * n_households,  # Median UK rent
-        "tenure_type": ["RENT_PRIVATELY"]
-        * n_households,  # Required for uprating
+        "tenure_type": ["RENT_PRIVATELY"] * n_households,  # Required for uprating
     }
 
     # Create MicroDataFrames
-    person_df = MicroDataFrame(
-        pd.DataFrame(person_data), weights="person_weight"
-    )
-    benunit_df = MicroDataFrame(
-        pd.DataFrame(benunit_data), weights="benunit_weight"
-    )
+    person_df = MicroDataFrame(pd.DataFrame(person_data), weights="person_weight")
+    benunit_df = MicroDataFrame(pd.DataFrame(benunit_data), weights="benunit_weight")
     household_df = MicroDataFrame(
         pd.DataFrame(household_data), weights="household_weight"
     )
@@ -273,9 +268,7 @@ def visualise_results(results: dict) -> None:
     # Calculate net employment income (employment income minus tax)
     net_employment = [
         emp - tax
-        for emp, tax in zip(
-            results["employment_income_hh"], results["household_tax"]
-        )
+        for emp, tax in zip(results["employment_income_hh"], results["household_tax"])
     ]
 
     # Stack benefits and income components using PolicyEngine colors
@@ -339,17 +332,11 @@ def main():
     simulation = run_simulation(dataset)
 
     print("Extracting results using aggregate filters...")
-    results = extract_results_by_employment_income(
-        simulation, employment_incomes
-    )
+    results = extract_results_by_employment_income(simulation, employment_incomes)
 
     print("\nSample results:")
     for emp_inc in [0, 25000, 50000, 100000]:
-        idx = (
-            employment_incomes.index(emp_inc)
-            if emp_inc in employment_incomes
-            else -1
-        )
+        idx = employment_incomes.index(emp_inc) if emp_inc in employment_incomes else -1
         if idx >= 0:
             print(
                 f"  Employment income £{emp_inc:,}: HBAI net income £{results['hbai_household_net_income'][idx]:,.0f}"

{policyengine-3.2.0 → policyengine-3.2.1}/examples/employment_income_variation_us.py

@@ -127,24 +127,16 @@ def create_dataset_with_varied_employment_income(
     }
 
     # Create MicroDataFrames
-    person_df = MicroDataFrame(
-        pd.DataFrame(person_data), weights="person_weight"
-    )
+    person_df = MicroDataFrame(pd.DataFrame(person_data), weights="person_weight")
     household_df = MicroDataFrame(
         pd.DataFrame(household_data), weights="household_weight"
     )
     marital_unit_df = MicroDataFrame(
         pd.DataFrame(marital_unit_data), weights="marital_unit_weight"
     )
-    family_df = MicroDataFrame(
-        pd.DataFrame(family_data), weights="family_weight"
-    )
-    spm_unit_df = MicroDataFrame(
-        pd.DataFrame(spm_unit_data), weights="spm_unit_weight"
-    )
-    tax_unit_df = MicroDataFrame(
-        pd.DataFrame(tax_unit_data), weights="tax_unit_weight"
-    )
+    family_df = MicroDataFrame(pd.DataFrame(family_data), weights="family_weight")
+    spm_unit_df = MicroDataFrame(pd.DataFrame(spm_unit_data), weights="spm_unit_weight")
+    tax_unit_df = MicroDataFrame(pd.DataFrame(tax_unit_data), weights="tax_unit_weight")
 
     # Create temporary file
     tmpdir = tempfile.mkdtemp()
@@ -227,9 +219,7 @@ def visualise_results(results: dict) -> None:
     # Calculate net employment income (employment income minus tax)
     net_employment = [
         emp - tax
-        for emp, tax in zip(
-            results["employment_income_hh"], results["household_tax"]
-        )
+        for emp, tax in zip(results["employment_income_hh"], results["household_tax"])
     ]
 
     # Stack benefits and income components using PolicyEngine colors
@@ -287,17 +277,11 @@ def main():
     simulation = run_simulation(dataset)
 
     print("Extracting results using aggregate filters...")
-    results = extract_results_by_employment_income(
-        simulation, employment_incomes
-    )
+    results = extract_results_by_employment_income(simulation, employment_incomes)
 
     print("\nSample results:")
     for emp_inc in [0, 50000, 100000, 200000]:
-        idx = (
-            employment_incomes.index(emp_inc)
-            if emp_inc in employment_incomes
-            else -1
-        )
+        idx = employment_incomes.index(emp_inc) if emp_inc in employment_incomes else -1
         if idx >= 0:
             print(
                 f"  Employment income ${emp_inc:,}: household net income ${results['household_net_income'][idx]:,.0f}"

{policyengine-3.2.0 → policyengine-3.2.1}/examples/household_impact_example.py

@@ -34,13 +34,9 @@ def uk_example():
     result = calculate_uk_impact(household)
 
     print("\nSingle adult, £50k income:")
-    print(
-        f"  Net income: £{result.household['hbai_household_net_income']:,.0f}"
-    )
+    print(f"  Net income: £{result.household['hbai_household_net_income']:,.0f}")
     print(f"  Income tax: £{result.person[0]['income_tax']:,.0f}")
-    print(
-        f"  National Insurance: £{result.person[0]['national_insurance']:,.0f}"
-    )
+    print(f"  National Insurance: £{result.person[0]['national_insurance']:,.0f}")
     print(f"  Total tax: £{result.household['household_tax']:,.0f}")
 
     # Family with two children, £30k income, renting
@@ -64,9 +60,7 @@ def uk_example():
     result = calculate_uk_impact(household)
 
     print("\nFamily (2 adults, 2 children), £30k income, renting:")
-    print(
-        f"  Net income: £{result.household['hbai_household_net_income']:,.0f}"
-    )
+    print(f"  Net income: £{result.household['hbai_household_net_income']:,.0f}")
     print(f"  Income tax: £{result.person[0]['income_tax']:,.0f}")
     print(f"  Child benefit: £{result.benunit[0]['child_benefit']:,.0f}")
     print(f"  Universal credit: £{result.benunit[0]['universal_credit']:,.0f}")
@@ -81,9 +75,7 @@ def us_example():
 
     # Single adult earning $50,000
     household = USHouseholdInput(
-        people=[
-            {"age": 35, "employment_income": 50_000, "is_tax_unit_head": True}
-        ],
+        people=[{"age": 35, "employment_income": 50_000, "is_tax_unit_head": True}],
         tax_unit={"filing_status": "SINGLE"},
         household={"state_code_str": "CA"},
         year=2024,

{policyengine-3.2.0 → policyengine-3.2.1}/examples/income_distribution_us.py

@@ -26,9 +26,7 @@ from policyengine.utils.plotting import COLORS, format_fig
 
 def load_representative_data(year: int = 2024) -> PolicyEngineUSDataset:
     """Load representative household microdata for a given year."""
-    dataset_path = (
-        Path(__file__).parent / "data" / f"enhanced_cps_2024_year_{year}.h5"
-    )
+    dataset_path = Path(__file__).parent / "data" / f"enhanced_cps_2024_year_{year}.h5"
 
     if not dataset_path.exists():
         raise FileNotFoundError(
@@ -83,15 +81,11 @@ def calculate_income_decile_statistics(simulation: Simulation) -> dict:
             quantile_eq=decile_num,
         )
         if decile_num == 1:
-            print(
-                f"    First Aggregate created ({time.time() - pre_create:.2f}s)"
-            )
+            print(f"    First Aggregate created ({time.time() - pre_create:.2f}s)")
         pre_run = time.time()
         agg.run()
         if decile_num == 1:
-            print(
-                f"    First Aggregate.run() complete ({time.time() - pre_run:.2f}s)"
-            )
+            print(f"    First Aggregate.run() complete ({time.time() - pre_run:.2f}s)")
         market_incomes.append(agg.result / 1e9)
 
         agg = Aggregate(
@@ -234,9 +228,7 @@ def calculate_income_decile_statistics(simulation: Simulation) -> dict:
         print(f"  {prog} complete ({time.time() - prog_start:.2f}s)")
 
     print(f"Tax benefits complete ({time.time() - tax_benefits_start:.2f}s)")
-    print(
-        f"\nTotal statistics calculation time: {time.time() - start_time:.2f}s"
-    )
+    print(f"\nTotal statistics calculation time: {time.time() - start_time:.2f}s")
 
     return {
         "deciles": deciles,
@@ -392,9 +384,7 @@ def main():
     print(f"Total benefits: ${total_benefits:.1f}bn")
     print(f"Total net income: ${total_net_income:.1f}bn")
     print(f"Total households: {total_households:.1f}m")
-    print(
-        f"Average effective tax rate: {total_tax / total_market_income * 100:.1f}%"
-    )
+    print(f"Average effective tax rate: {total_tax / total_market_income * 100:.1f}%")
 
     print("\nBenefit programs by decile:")
     benefit_programs = [

{policyengine-3.2.0 → policyengine-3.2.1}/examples/policy_change_uk.py

@@ -82,9 +82,7 @@ def run_baseline_simulation(dataset: PolicyEngineUKDataset) -> Simulation:
     return simulation
 
 
-def run_reform_simulation(
-    dataset: PolicyEngineUKDataset, policy: Policy
-) -> Simulation:
+def run_reform_simulation(dataset: PolicyEngineUKDataset, policy: Policy) -> Simulation:
     """Run reform microsimulation with policy changes."""
     simulation = Simulation(
         dataset=dataset,
@@ -95,9 +93,7 @@ def run_reform_simulation(
     return simulation
 
 
-def analyse_overall_impact(
-    baseline_sim: Simulation, reform_sim: Simulation
-) -> dict:
+def analyse_overall_impact(baseline_sim: Simulation, reform_sim: Simulation) -> dict:
     """Analyse overall winners, losers, and financial impact."""
     winners = ChangeAggregate(
         baseline_simulation=baseline_sim,
@@ -198,9 +194,7 @@ def analyse_impact_by_income_decile(
     }
 
 
-def visualise_results(
-    overall: dict, by_decile: dict, reform_name: str
-) -> None:
+def visualise_results(overall: dict, by_decile: dict, reform_name: str) -> None:
     """Create visualisations of policy change impacts."""
     fig = make_subplots(
         rows=1,
@@ -270,9 +264,7 @@ def print_summary(overall: dict, decile: dict, reform_name: str) -> None:
     print(f"  Losers: {overall['losers']:.2f}m households")
     print(f"  No change: {overall['no_change']:.2f}m households")
     print("\nFinancial impact:")
-    print(
-        f"  Net income change: £{overall['total_change']:.2f}bn (negative = loss)"
-    )
+    print(f"  Net income change: £{overall['total_change']:.2f}bn (negative = loss)")
     print(f"  Tax revenue change: £{overall['tax_revenue_change']:.2f}bn")
     print("\nImpact by income decile:")
     for i, label in enumerate(decile["labels"]):