fix: support Python 3.14 (#5646)

* ci: support Python 3.14

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* fix: Python 3.14 name change

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* tests: fix expected output to handle Python 3.14

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* fix: tighten CLI and add color on 3.14+

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* tests: ignore failure on 3.14.0b1

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* fix: support Python 3.14.0b1 with interperters

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* Update test_multiple_interpreters.py

* Update test_multiple_interpreters.py

* fix: new breakage for 3.14 fixed

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* fix: handle empty annotations 3.14

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* fix: Python 3.14 may not create the annotations dict

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* fix: use PyUnstable_IsImmortal

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* fix: use sys._is_immortal

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* tests: ignore large values for refcount too

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* style: pre-commit fixes

* ci: enable all free-threaded builds

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* fix: patch for embed

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* Revert "fix: patch for embed"

This reverts commit c4226a0671.

* ci: drop new 3.xt additions

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* fix: logic issue, also add some comments

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* Update include/pybind11/pytypes.h

---------

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

tests/pybind11_tests.cpp

@@ -90,7 +90,6 @@ PYBIND11_MODULE(pybind11_tests, m, py::mod_gil_not_used()) {
     m.attr("cpp_std") = cpp_std();
     m.attr("PYBIND11_INTERNALS_ID") = PYBIND11_INTERNALS_ID;
     // Free threaded Python uses UINT32_MAX for immortal objects.
-    m.attr("PYBIND11_REFCNT_IMMORTAL") = UINT32_MAX;
     m.attr("PYBIND11_SIMPLE_GIL_MANAGEMENT") =
 #if defined(PYBIND11_SIMPLE_GIL_MANAGEMENT)
         true;

tests/test_class.py

@@ -6,9 +6,17 @@ from unittest import mock
 import pytest
 
 import env
-from pybind11_tests import PYBIND11_REFCNT_IMMORTAL, ConstructorStats, UserType
+from pybind11_tests import ConstructorStats, UserType
 from pybind11_tests import class_ as m
 
+UINT32MAX = 2**32 - 1
+
+
+def refcount_immortal(ob: object) -> int:
+    if _is_immortal := getattr(sys, "_is_immortal", None):
+        return UINT32MAX if _is_immortal(ob) else sys.getrefcount(ob)
+    return sys.getrefcount(ob)
+
 
 def test_obj_class_name():
     expected_name = "UserType" if env.PYPY else "pybind11_tests.UserType"
@@ -382,23 +390,23 @@ def test_brace_initialization():
 @pytest.mark.xfail("env.PYPY or env.GRAALPY")
 def test_class_refcount():
     """Instances must correctly increase/decrease the reference count of their types (#1029)"""
-    from sys import getrefcount
 
     class PyDog(m.Dog):
         pass
 
     for cls in m.Dog, PyDog:
-        refcount_1 = getrefcount(cls)
+        refcount_1 = refcount_immortal(cls)
         molly = [cls("Molly") for _ in range(10)]
-        refcount_2 = getrefcount(cls)
+        refcount_2 = refcount_immortal(cls)
 
         del molly
         pytest.gc_collect()
-        refcount_3 = getrefcount(cls)
+        refcount_3 = refcount_immortal(cls)
 
+        # Python may report a large value here (above 30 bits), that's also fine
         assert refcount_1 == refcount_3
         assert (refcount_2 > refcount_1) or (
-            refcount_2 == refcount_1 == PYBIND11_REFCNT_IMMORTAL
+            refcount_2 == refcount_1 and refcount_1 >= 2**29
         )
 
 

tests/test_methods_and_attributes.py

@@ -305,6 +305,11 @@ def test_property_rvalue_policy():
 
 # https://foss.heptapod.net/pypy/pypy/-/issues/2447
 @pytest.mark.xfail("env.PYPY")
+@pytest.mark.xfail(
+    sys.version_info == (3, 14, 0, "beta", 1),
+    reason="3.14.0b1 bug: https://github.com/python/cpython/issues/133912",
+    strict=True,
+)
 def test_dynamic_attributes():
     instance = m.DynamicClass()
     assert not hasattr(instance, "foo")

tests/test_multiple_interpreters.py

@@ -15,7 +15,8 @@ def test_independent_subinterpreters():
 
     sys.path.append(".")
 
-    if sys.version_info >= (3, 14):
+    # This is supposed to be added to PyPI sometime in 3.14's lifespan
+    if sys.version_info >= (3, 15):
         import interpreters
     elif sys.version_info >= (3, 13):
         import _interpreters as interpreters
@@ -86,7 +87,7 @@ def test_dependent_subinterpreters():
 
     sys.path.append(".")
 
-    if sys.version_info >= (3, 14):
+    if sys.version_info >= (3, 15):
         import interpreters
     elif sys.version_info >= (3, 13):
         import _interpreters as interpreters

tests/test_operator_overloading.py

@@ -158,4 +158,4 @@ def test_overriding_eq_reset_hash():
 def test_return_set_of_unhashable():
     with pytest.raises(TypeError) as excinfo:
         m.get_unhashable_HashMe_set()
-    assert str(excinfo.value.__cause__).startswith("unhashable type:")
+    assert "unhashable type" in str(excinfo.value.__cause__)

tests/test_pickling.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import pickle
 import re
+import sys
 
 import pytest
 
@@ -62,7 +63,20 @@ def test_roundtrip(cls_name):
 
 
 @pytest.mark.xfail("env.PYPY")
-@pytest.mark.parametrize("cls_name", ["PickleableWithDict", "PickleableWithDictNew"])
+@pytest.mark.parametrize(
+    "cls_name",
+    [
+        pytest.param(
+            "PickleableWithDict",
+            marks=pytest.mark.xfail(
+                sys.version_info == (3, 14, 0, "beta", 1),
+                reason="3.14.0b1 bug: https://github.com/python/cpython/issues/133912",
+                strict=True,
+            ),
+        ),
+        "PickleableWithDictNew",
+    ],
+)
 def test_roundtrip_with_dict(cls_name):
     cls = getattr(m, cls_name)
     p = cls("test_value")

tests/test_pytypes.py

@@ -1143,6 +1143,10 @@ def test_dict_ranges(tested_dict, expected):
 
 # https://docs.python.org/3/howto/annotations.html#accessing-the-annotations-dict-of-an-object-in-python-3-9-and-older
 def get_annotations_helper(o):
+    if sys.version_info >= (3, 14):
+        import annotationlib
+
+        return annotationlib.get_annotations(o) or None
     if isinstance(o, type):
         return o.__dict__.get("__annotations__", None)
     return getattr(o, "__annotations__", None)