Upgrade to Python 3.14

[MaxGhenis]

Summary

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

Key Benefits for PolicyEngine Canada

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 provincial 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 and benefit calculations
• Better type hint performance

Other Improvements

• Native Zstandard compression for faster data loading
• Improved error messages for debugging tax/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 provincial and federal calculations
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