Upgrade to Python 3.14

[MaxGhenis]

Summary

Python 3.14 is scheduled for release on October 7, 2025. We should upgrade policyengine-uk to support Python 3.14 and take advantage of its performance improvements and new features.

Key Benefits for PolicyEngine UK

Performance Improvements

• 3-5% geometric mean performance improvement - faster household calculations
• Up to 30% faster for certain workloads with newer compilers
• Incremental garbage collection with reduced pause times
• Better performance for microsimulation scenarios

Free-Threaded Python (No GIL)

• Free-threaded mode is now officially supported
• Could enable true parallel computation for regional calculations
• Potential for faster batch household calculations
• Performance penalty in single-threaded mode reduced to just 5-10%

Type System & Numerical Improvements

• Deferred evaluation of type annotations reduces import overhead
• New float.from_number() and complex.from_number() methods for safer numeric conversions
• Enhanced mixed-mode arithmetic - important for benefit calculations
• Better type hint performance

Other Improvements

• Native Zstandard compression for faster data loading
• Improved error messages for debugging benefit rules
• Simpler exception handling syntax (PEP 758)

Implementation Plan

1. Wait for policyengine-core upgrade - Ensure core library supports Python 3.14 first
2. Update pyproject.toml to include Python 3.14 in supported versions
3. Add Python 3.14 to CI/CD test matrix
4. Test all benefit calculations and microsimulation scenarios
5. Update documentation

Priority

Medium - Should coordinate with policyengine-core upgrade (PolicyEngine/policyengine-core#399). The performance improvements will benefit microsimulation workloads.

References

• Python 3.14 Release Schedule
• What's New in Python 3.14

[vahid-ahmadi]

Done. Python 3.14 is supported:

• pyproject.toml declares the Python :: 3.14 classifier (with requires-python = ">=3.9").
• CI exercises 3.14 via the matrix in .github/workflows/pr_code_changes.yaml (["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]).
• Implemented in Add Python 3.14 support, drop Python 3.10 #1356 (merged 2026-02-24, commit 57c6e90).
• The 3.14-specific regression dividend_income_tax returns 0 due to Python 3.14 compatibility issue #1401 has also been resolved.

Closing as completed.