Summary

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

Key Benefits for PolicyEngine US

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 large-scale microsimulations

Free-Threaded Python (No GIL)

• Free-threaded mode is now officially supported
• Could enable true parallel computation for state-by-state 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 tax calculations
• Better type hint performance

Other Improvements

• Native Zstandard compression for faster data loading
• Improved error messages for debugging complex tax 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 state tax 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