Upgrade to Python 3.14

[MaxGhenis]

Summary

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

Key Benefits for PolicyEngine

Performance Improvements

• 3-5% geometric mean performance improvement across the board
• Up to 30% faster for certain workloads with newer compilers (Clang 19+ on x86-64/AArch64)
• Incremental garbage collection with reduced pause times
• New interpreter architecture with better optimization

Free-Threaded Python (No GIL)

• Free-threaded mode is now officially supported (no longer experimental)
• Performance penalty reduced to just 5-10% in single-threaded mode
• Opens the door for true parallel computation in microsimulations
• Could enable concurrent policy calculations without multiprocessing overhead

Type System & Numerical Improvements

• Deferred evaluation of type annotations (PEP 649/749) reduces import overhead
• New float.from_number() and complex.from_number() methods
• Enhanced mixed-mode arithmetic rules
• Better type hint performance and flexibility
• New annotationlib module for annotation introspection

Concurrency Features

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

Other Improvements

• Native Zstandard compression support
• Improved error messages and debugging
• Experimental JIT compiler in binary releases
• Simpler exception handling syntax (PEP 758)

Implementation Plan

1. Update pyproject.toml to include Python 3.14 in supported versions
2. Add Python 3.14 to CI/CD test matrix
3. Test compatibility with all dependencies
4. Update documentation to reflect Python 3.14 support
5. Consider testing free-threaded mode for future parallel computation features

Priority

Medium-High - While Python 3.14 offers significant performance improvements, we should wait for initial release stability and ensure downstream dependencies (country models, API) are ready to upgrade in coordination.

References

• Python 3.14 Release Schedule
• What's New in Python 3.14
• PEP 649: Deferred Evaluation of Annotations
• PEP 703: Free-threaded CPython

---

Blocker

Blocked on tables (PyTables) shipping Python 3.14 wheels: PyTables/PyTables#1261

[MaxGhenis]

Blocked on tables (PyTables) shipping Python 3.14 wheels. See PyTables/PyTables#1261 (closed without resolution) and PyTables/PyTables#1262.

h5py 3.15.1 now has 3.14 wheels, so tables is the remaining blocker.