Support Python 3.14

[rajeeja]

Summary

Add official support for Python 3.14 to UXarray. Local testing shows UXarray already works on Python 3.14.6 with no source changes required — the only necessary change is a numba>=0.63 version floor (older numba does not support 3.14).

Motivation

• Python 3.14 (released 2025-10-07) is the latest stable CPython.
• The dependency ecosystem is ready: numba (0.63+), numpy, xarray, numba-JIT, cartopy, healpix, matplotlib, sphinx/myst-nb all have working 3.14 builds/wheels.
• Benefits: new tail-call interpreter (~3–5% faster general Python), officially supported free-threading (PEP 703/779), incremental GC, faster stdlib (io/pathlib/zlib), improved error messages, stdlib Zstandard.

Compatibility findings (local testing on Python 3.14.6)

Environment: fresh conda env, Python 3.14.6, numba 0.65.1, numpy 2.4.6, matplotlib 3.10.9.

Test results (all passing):

Suite	Result
uxarray import + HEALPix grid + face_areas	pass (4π)
numba @njit compile	pass
test/test_remap.py	26/26 pass
test/test_plot.py	16/16 pass
test/test_subset.py, test_helpers.py, test_dependencies.py, test_icon_io.py	33/33 pass
test/test_remap_yac.py (with YAC 3.18)	15/15 pass

Required change

• Pin numba>=0.63 in pyproject.toml. Per numba's support matrix, numba 0.63 (2025-12) is the first release supporting 3.10 <= python < 3.15; numba 0.61/0.62 cap at < 3.14. Without a floor, a 3.14 install can resolve an unsupported numba and fail at import.

Watch items (not blocking)

• NumPy ceiling: numba 0.65.1 requires numpy < 2.5. Currently fine (2.4.6), but numpy 2.5 + current numba would conflict.
• matplotlib: existing matplotlib<3.11 pin (see Remapping notebook is broken on RTD #1542) is unrelated to 3.14 and still satisfied.

Proposed tasks

• Add numba>=0.63 to pyproject.toml dependencies
• Add Programming Language :: Python :: 3.14 classifier
• Add 3.14 to the CI test matrix (.github/workflows/ci.yml)
• Update docs/CI conda envs (ci/environment.yml, ci/docs.yml) as needed
• Confirm docs build on 3.14
• (Optional) Decide whether to raise the minimum supported Python

Notes

Some of these changes (classifier, numba>=0.63, YAC 3.18 CI Python bump) are already staged on branch rajeeja/upgrade_yac alongside the YAC 3.18 upgrade.

[Sevans711]

A few thoughts / flagging a few issues as related:

1. Official support for 3.14 sounds like a great idea, thank you for opening this issue!
2. Can you provide an example of the install crashing without the numba >= 0.63 pin? On my machine I was able to install via pip and separately via conda, both in Python 3.14, with no issues; both resolved to a correct version of numba automatically without me needing to worry about it and without a pinned version. Related: Remove numpy <2.3 constraint to enable support for Python 3.14 #1434.
3. My preference would be to keep the minimum Python at 3.10 at least until October when it officially reaches end-of-life (https://devguide.python.org/versions/) unless we have a compelling reason to drop support for it before then?
4. Possibly related: Refactor dependencies to make more optional #1548

[rajeeja]

Thanks @Sevans711!

2. Yeah, in a clean env the solver usually grabs a fine numba - the pin is just a floor so a 3.14 install can't fall back to numba 0.61/0.62 (those cap at <3.14). Cheap safety net.

Bigger thing we hit in the YAC 3.18 work (#1563): what actually broke on 3.14 wasn't numba, it was the old pathlib backport still in our env/dev deps. It shadows stdlib pathlib and its from collections import Sequence blows up on 3.10+ (killed the Cython build for YAC). #1563 drops it - pathlib's been stdlib since 3.4 anyway. Worth removing regardless of 3.14.

3. Agree, keep the floor at 3.10 until it EOLs in Oct. This is just about adding 3.14.

Classifier + numba pin + YAC 3.18 on 3.14 + pathlib removal are all in #1563 and green. Still todo: add 3.14 to the main CI matrix and confirm docs build.

[Sevans711]

I'm still a bit confused about the numba pin. We aren't pinning other dependencies for other packages which don't support newer Python. For example, numpy<1.23 isn't supported on Python < 3.10, and numpy<2.0 isn't supported on Python >= 3.12, yet we do not have any pins for numpy in our pyproject.toml. Is there a compelling reason to make numba special (e.g., any observed crash without the pin)?

Other parts sound good!

[rajeeja]

Good call, but I think we should keep the pin here. numpy self-gates via requires-python, so the resolver can't pick a bad combo. numba's older releases don't gate <3.14 reliably, so without a floor a 3.14 install can silently land on an unsupported numba and fail at JIT time. Keeping numba>=0.63 as a cheap guardrail - especially after the pathlib backport just bit us with the same silent-failure pattern.