Upgrade to Python 3.14

[MaxGhenis]

Summary

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

Key Benefits for policyengine.py

Performance Improvements

• 3-5% geometric mean performance improvement - faster programmatic calculations
• Up to 30% faster for certain workloads with newer compilers
• Incremental garbage collection with reduced pause times
• Better performance for batch analyses and scripting

Free-Threaded Python (No GIL)

• Free-threaded mode is now officially supported
• Users can enable true parallel computation for batch household calculations
• Better performance for data science workflows (Jupyter notebooks, scripts)
• 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
• Enhanced mixed-mode arithmetic
• Better type hint performance for IDE support

Concurrency Features

• InterpreterPoolExecutor for parallel policy calculations
• Multiple interpreters in standard library
• Improved context variable and threading support

Other Improvements

• Native Zstandard compression for faster data I/O
• Improved error messages for better debugging experience
• Simpler exception handling syntax (PEP 758)
• Better integration with data science ecosystem

Implementation Plan

1. Wait for policyengine-api upgrade - Ensure API 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 functionality with Python 3.14
5. Update documentation with Python 3.14 examples
6. Consider adding examples using free-threaded mode for parallel calculations

Priority

Medium - Should coordinate with API upgrade (depends on policyengine-api upgrade). The performance improvements will benefit users running batch analyses and simulations.

Related Issues

• Upgrade to Python 3.14 policyengine-core#399
• Upgrade to Python 3.14 policyengine-us#6626
• Upgrade to Python 3.14 policyengine-uk#1353
• policyengine-api upgrade issue (to be created)

References

• Python 3.14 Release Schedule
• What's New in Python 3.14
• PEP 703: Free-threaded CPython