feat: support Python 3.14 (default in Ubuntu 26.04 LTS)

PU
2d ago
+2151-690

Summary

Python 3.14 is the default system Python of Ubuntu 26.04 LTS, so today pip install unstructured fails out of the box there (requires-python = ">=3.11, <3.14"). The blockers that used to justify the cap are gone: llvmlite/numba, torch, onnxruntime, scipy, spacy, pikepdf, pi-heif, psycopg2-binary… all publish cp314 (or abi3) wheels for Linux x86_64/aarch64, macOS arm64 and Windows.

This PR is intentionally minimal and limited to 3.14 support:

  • pyproject.toml: requires-python = ">=3.11, <3.15" and the Programming Language :: Python :: 3.14 classifier.
  • paddleocr extra: not installed on 3.14 (paddlepaddle publishes no cp314 wheels on any platform). Same pattern as the existing Windows/3.13 markers. The paddle OCR agent imports lazily, so nothing else changes.
  • ci.yml: 3.14 added to the matrices that already cover 3.11–3.13. Light jobs on ubuntu-latest already run on the ubuntu-26.04 image.
  • uv.lock: 3.11–3.13 resolutions are unchanged except onnx 1.21.0 → 1.23.2 (1.21.0 has no cp314 wheels). spacy 3.8.16 is used on 3.14 only. Most of the lock diff is the new cp314 wheel entries.
  • Tests, adapted to two Python 3.14 json changes. No library code change:
    • test_streamed_orig_elements.py: 3.14 attaches when serializing … notes to the "Circular reference detected" ValueError, and pytest.raises(match=…) also matches the notes. The test now compares str(exc), which is just as strict on every version.
    • test_json.py / test_ndjson.py: the "too deep to pretty-print" case is skipped on 3.14+ because the json encoder no longer raises RecursionError at that depth. pretty_json_text() keeps its RecursionError guard.

This supersedes the older #4312 in a smaller form: no dependency forks, no lint-target bump, and existing users' pins are untouched.

Validation

  • uv lock --check (uv 0.13.9, same version as CI) passes for 3.11, 3.12, 3.13 and 3.14, on macOS and in a linux/amd64 container.
  • uv sync --locked --all-extras --all-groups on 3.14 installs from wheels only (just a few pure-Python sdists are built).
  • make check: clean.
  • make test on 3.14 (macOS arm64): 5717 passed. The only failures were the 2 json cases above (now handled), the 12 circular-reference parametrizations (now handled), and test_weaviate_schema_is_valid, which timed out starting embedded Weaviate under -n auto load and passes when run alone. The modified test files also pass on 3.13.
  • Same package versions on 3.13 vs 3.14 (scripts/performance/quick_partition_bench.py, warm, median of 3, macOS arm64). No regression, identical element counts:
document (strategy)3.133.14delta
book-war-and-peace-1225p.txt (fast)57.91 s57.01 s−1.6 %
example-10k-230p.html (fast)2.15 s2.11 s−1.9 %
handbook-872p.docx (fast)16.08 s15.94 s−0.9 %
science-exploration-369p.pptx (fast)2.73 s2.80 s+2.7 %
layout-parser-paper.pdf (fast)1.12 s1.15 s+2.4 %
DA-1p.pdf (hi_res)3.58 s3.24 s−9.6 % (noisy)
layout-parser-paper.pdf (hi_res)51.66 s51.44 s−0.4 %

Notes for maintainers

  • Lockfile: with current uv (0.13.x, also tried 0.12.20), uv lock can no longer re-resolve the current main lockfile incrementally. Even uv lock --upgrade-package emoji on an untouched main fails on a python_full_version == '3.12.*' and platform_machine == 's390x' and sys_platform == 'win32' split, because pypandoc-binary has no wheel for it. uv lock --check still passes, so CI is green. A from-scratch lock resolves but upgrades ~300 packages. So this lock was produced from a fresh resolution constrained to the existing versions, and only the packages that need cp314 wheels moved. The resulting lockfile re-resolves incrementally again.
  • pip users: unstructured-inference (used by the pdf/image extras) and unstructured-ingest still declare requires-python <3.14. uv ignores upper bounds of dependencies, but pip does not, so pip install "unstructured[pdf]" on 3.14 will also need a release of those two packages with the cap lifted. Happy to open the matching PRs.

Checklist

  • The PR title is a user-facing release-note entry with a conventional commit prefix.
  • Apply a category label (enhancement, bug, or an appropriate existing label), or ask a maintainer to apply it. (external contributor: could a maintainer please apply enhancement?)
  • For breaking changes, use ! in the title and explain impact and migration above. (not a breaking change)

🤖 Generated with Claude Code