Add experimental support for free threading (pydantic#11516)

Author: Viicos

.github/workflows/ci.yml

@@ -90,7 +90,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-13, macos-latest, windows-latest]
-        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.13t']
         include:
           # no pydantic-core binaries for pypy on windows, so tests take absolute ages
           # macos tests with pypy take ages (>10mins) since pypy is very slow
@@ -136,15 +136,20 @@ jobs:
     - name: Test without email-validator
       # speed up by skipping this step on pypy
       if: ${{ !startsWith(matrix.python-version, 'pypy') }}
-      run: make test
+      run: make test NUM_THREADS=${{ endsWith(matrix.python-version, 't') && '4' || '1' }}
+      # Free threaded is flaky, allow failures for now:
+      continue-on-error: ${{ endsWith(matrix.python-version, 't') }}
       env:
         COVERAGE_FILE: coverage/.coverage.${{ runner.os }}-py${{ matrix.python-version }}-without-deps
         CONTEXT: ${{ runner.os }}-py${{ matrix.python-version }}-without-deps
 
     - name: Install extra dependencies
+      # Skip free threaded, we can't install memray
+      if: ${{ !endsWith(matrix.python-version, 't') }}
       run: uv sync --group testing-extra --all-extras
 
     - name: Test with all extra dependencies
+      if: ${{ !endsWith(matrix.python-version, 't') }}
       run: make test
       env:
         COVERAGE_FILE: coverage/.coverage.${{ runner.os }}-py${{ matrix.python-version }}-with-deps

Makefile

@@ -1,5 +1,6 @@
 # .DEFAULT_GOAL := all
 sources = pydantic tests docs/plugins
+NUM_THREADS?=1
 
 .PHONY: .uv  ## Check that uv is installed
 .uv:
@@ -62,7 +63,7 @@ test-typechecking-mypy: .uv
 
 .PHONY: test  ## Run all tests, skipping the type-checker integration tests
 test: .uv
-	uv run coverage run -m pytest --durations=10
+	uv run coverage run -m pytest --durations=10 --parallel-threads $(NUM_THREADS)
 
 .PHONY: benchmark  ## Run all benchmarks
 benchmark: .uv

pydantic/_internal/_generics.py

@@ -94,7 +94,7 @@ def __delitem__(self, key: KT) -> None:
 # and discover later on that we need to re-add all this infrastructure...
 # _GENERIC_TYPES_CACHE = DeepChainMap(GenericTypesCache(), LimitedDict())
 
-_GENERIC_TYPES_CACHE = GenericTypesCache()
+_GENERIC_TYPES_CACHE: ContextVar[GenericTypesCache | None] = ContextVar('_GENERIC_TYPES_CACHE', default=None)
 
 
 class PydanticGenericMetadata(typing_extensions.TypedDict):
@@ -453,14 +453,24 @@ def get_cached_generic_type_early(parent: type[BaseModel], typevar_values: Any)
     during validation, I think it is worthwhile to ensure that types that are functionally equivalent are actually
     equal.
     """
-    return _GENERIC_TYPES_CACHE.get(_early_cache_key(parent, typevar_values))
+    generic_types_cache = _GENERIC_TYPES_CACHE.get()
+    if generic_types_cache is None:
+        generic_types_cache = GenericTypesCache()
+        _GENERIC_TYPES_CACHE.set(generic_types_cache)
+    return generic_types_cache.get(_early_cache_key(parent, typevar_values))
 
 
 def get_cached_generic_type_late(
     parent: type[BaseModel], typevar_values: Any, origin: type[BaseModel], args: tuple[Any, ...]
 ) -> type[BaseModel] | None:
     """See the docstring of `get_cached_generic_type_early` for more information about the two-stage cache lookup."""
-    cached = _GENERIC_TYPES_CACHE.get(_late_cache_key(origin, args, typevar_values))
+    generic_types_cache = _GENERIC_TYPES_CACHE.get()
+    if (
+        generic_types_cache is None
+    ):  # pragma: no cover (early cache is guaranteed to run first and initialize the cache)
+        generic_types_cache = GenericTypesCache()
+        _GENERIC_TYPES_CACHE.set(generic_types_cache)
+    cached = generic_types_cache.get(_late_cache_key(origin, args, typevar_values))
     if cached is not None:
         set_cached_generic_type(parent, typevar_values, cached, origin, args)
     return cached
@@ -476,11 +486,17 @@ def set_cached_generic_type(
     """See the docstring of `get_cached_generic_type_early` for more information about why items are cached with
     two different keys.
     """
-    _GENERIC_TYPES_CACHE[_early_cache_key(parent, typevar_values)] = type_
+    generic_types_cache = _GENERIC_TYPES_CACHE.get()
+    if (
+        generic_types_cache is None
+    ):  # pragma: no cover (cache lookup is guaranteed to run first and initialize the cache)
+        generic_types_cache = GenericTypesCache()
+        _GENERIC_TYPES_CACHE.set(generic_types_cache)
+    generic_types_cache[_early_cache_key(parent, typevar_values)] = type_
     if len(typevar_values) == 1:
-        _GENERIC_TYPES_CACHE[_early_cache_key(parent, typevar_values[0])] = type_
+        generic_types_cache[_early_cache_key(parent, typevar_values[0])] = type_
     if origin and args:
-        _GENERIC_TYPES_CACHE[_late_cache_key(origin, args, typevar_values)] = type_
+        generic_types_cache[_late_cache_key(origin, args, typevar_values)] = type_
 
 
 def _union_orderings_key(typevar_values: Any) -> Any:

pyproject.toml

@@ -78,7 +78,7 @@ dev = [
     'faker',
     'pytest-benchmark',
     'pytest-codspeed',
-    'pytest-memray; platform_python_implementation == "CPython" and platform_system != "Windows"',
+    'pytest-run-parallel>=0.3.1',
     'packaging',
     'jsonschema',
 ]
@@ -114,6 +114,7 @@ testing-extra = [
     'devtools',
     # used in docs tests
     'sqlalchemy',
+    'pytest-memray; platform_python_implementation == "CPython" and platform_system != "Windows"',
 ]
 typechecking = [
     'mypy',

tests/conftest.py

@@ -15,6 +15,7 @@
 
 import pytest
 from _pytest.assertion.rewrite import AssertionRewritingHook
+from _pytest.nodes import Item
 from jsonschema import Draft202012Validator, SchemaError
 
 from pydantic._internal._generate_schema import GenerateSchema
@@ -178,3 +179,24 @@ def generate(*args: Any, **kwargs: Any) -> Any:
         return json_schema
 
     monkeypatch.setattr(GenerateJsonSchema, 'generate', generate)
+
+
+_thread_unsafe_fixtures = (
+    'generate_schema_calls',  # Monkeypatches Pydantic code
+    'benchmark',  # Fixture can't be reused
+    'tmp_path',  # Duplicate paths
+    'tmpdir',  # Duplicate dirs
+    'copy_method',  # Uses `pytest.warns()`
+    'reset_plugins',  # Monkeypatching
+)
+
+
+# Note: it is important to add the marker in the `pytest_itemcollected` hook.
+# `pytest-run-parallel` also implements this hook (and ours is running before),
+# and this wouldn't work if we were to add the "thread_unsafe" marker in say
+# `pytest_collection_modifyitems` (which is the last collection hook to be run).
+def pytest_itemcollected(item: Item) -> None:
+    """Mark tests as thread unsafe if they make use of fixtures that doesn't play well across threads."""
+    fixtures: tuple[str, ...] = getattr(item, 'fixturenames', ())
+    if any(fixture in fixtures for fixture in _thread_unsafe_fixtures):
+        item.add_marker('thread_unsafe')

tests/test_aliases.py

@@ -388,7 +388,13 @@ class Model(BaseModel):
         [False, True, 'bar', does_not_raise()],
         [False, True, 'bar_', does_not_raise()],
         [False, False, 'bar', does_not_raise()],
-        [False, False, 'bar_', pytest.raises(ValueError)],
+        pytest.param(
+            False,
+            False,
+            'bar_',
+            pytest.raises(ValueError),
+            marks=pytest.mark.thread_unsafe(reason='`pytest.raises()` is thread unsafe'),
+        ),
         [True, True, 'bar', does_not_raise()],
         [True, True, 'bar_', does_not_raise()],
         [True, False, 'bar', does_not_raise()],

tests/test_annotated.py

@@ -26,6 +26,12 @@
 NO_VALUE = object()
 
 
+@pytest.mark.thread_unsafe(
+    reason=(
+        'The `FieldInfo.from_annotated_attribute()` implementation directly mutates the assigned value, '
+        'if it is a `Field()`. https://github.com/pydantic/pydantic/issues/11122 tracks this issue'
+    )
+)
 @pytest.mark.parametrize(
     'hint_fn,value,expected_repr',
     [
@@ -113,6 +119,7 @@ class M(BaseModel):
     assert metadata in M.__annotations__['x'].__metadata__, 'Annotated type is recorded'
 
 
+@pytest.mark.thread_unsafe(reason='`pytest.raises()` is thread unsafe')
 @pytest.mark.parametrize(
     ['hint_fn', 'value', 'empty_init_ctx'],
     [

tests/test_config.py

@@ -305,7 +305,13 @@ class ModelNoArbitraryTypes(BaseModel):
             [False, True, 'bar', does_not_raise()],
             [False, True, 'bar_', does_not_raise()],
             [False, False, 'bar', does_not_raise()],
-            [False, False, 'bar_', pytest.raises(ValueError)],
+            pytest.param(
+                False,
+                False,
+                'bar_',
+                pytest.raises(ValueError),
+                marks=pytest.mark.thread_unsafe(reason='`pytest.raises()` is thread unsafe'),
+            ),
             [True, True, 'bar', does_not_raise()],
             [True, True, 'bar_', does_not_raise()],
             [True, False, 'bar', does_not_raise()],
@@ -512,6 +518,7 @@ class Child(Mixin, Parent):
     assert Child.model_config.get('use_enum_values') is True
 
 
+@pytest.mark.thread_unsafe(reason='Flaky')
 def test_config_wrapper_match():
     localns = {
         '_GenerateSchema': GenerateSchema,

tests/test_construction.py

@@ -175,6 +175,7 @@ def test_deep_copy(ModelTwo, copy_method):
     assert m._foo_ is not m2._foo_
 
 
+@pytest.mark.thread_unsafe(reason='`pytest.warns()` is thread unsafe')
 def test_copy_exclude(ModelTwo):
     m = ModelTwo(a=24, d=Model(a='12'))
     m2 = deprecated_copy(m, exclude={'b'})
@@ -191,6 +192,7 @@ def test_copy_exclude(ModelTwo):
     assert m != m2
 
 
+@pytest.mark.thread_unsafe(reason='`pytest.warns()` is thread unsafe')
 def test_copy_include(ModelTwo):
     m = ModelTwo(a=24, d=Model(a='12'))
     m2 = deprecated_copy(m, include={'a'})
@@ -202,6 +204,7 @@ def test_copy_include(ModelTwo):
     assert m != m2
 
 
+@pytest.mark.thread_unsafe(reason='`pytest.warns()` is thread unsafe')
 def test_copy_include_exclude(ModelTwo):
     m = ModelTwo(a=24, d=Model(a='12'))
     m2 = deprecated_copy(m, include={'a', 'b', 'c'}, exclude={'c'})
@@ -210,6 +213,7 @@ def test_copy_include_exclude(ModelTwo):
     assert set(m2.model_dump().keys()) == {'a', 'b'}
 
 
+@pytest.mark.thread_unsafe(reason='`pytest.warns()` is thread unsafe')
 def test_copy_advanced_exclude():
     class SubSubModel(BaseModel):
         a: str
@@ -233,6 +237,7 @@ class Model(BaseModel):
     assert m2.model_dump() == {'f': {'c': 'foo'}}
 
 
+@pytest.mark.thread_unsafe(reason='`pytest.warns()` is thread unsafe')
 def test_copy_advanced_include():
     class SubSubModel(BaseModel):
         a: str
@@ -256,6 +261,7 @@ class Model(BaseModel):
     assert m2.model_dump() == {'e': 'e', 'f': {'d': [{'a': 'c', 'b': 'e'}]}}
 
 
+@pytest.mark.thread_unsafe(reason='`pytest.warns()` is thread unsafe')
 def test_copy_advanced_include_exclude():
     class SubSubModel(BaseModel):
         a: str
@@ -484,6 +490,7 @@ class Model(BaseModel):
     assert m.bar == 'Baz'
 
 
+@pytest.mark.thread_unsafe(reason='`pytest.warns()` is thread unsafe')
 def test_copy_with_excluded_fields():
     class User(BaseModel):
         name: str

tests/test_deprecated.py

@@ -32,6 +32,10 @@
 from pydantic.json_schema import JsonSchemaValue
 from pydantic.type_adapter import TypeAdapter
 
+# `pytest.warns/raises()` is thread unsafe. As these tests are meant to be
+# removed in V3, we just mark all tests as thread unsafe
+pytestmark = pytest.mark.thread_unsafe
+
 
 def deprecated_from_orm(model_type: type[BaseModel], obj: Any) -> Any:
     with pytest.warns(

tests/test_deprecated_validate_arguments.py

@@ -11,6 +11,10 @@
 from pydantic.deprecated.decorator import validate_arguments as validate_arguments_deprecated
 from pydantic.errors import PydanticUserError
 
+# `pytest.warns/raises()` is thread unsafe. As these tests are meant to be
+# removed in V3, we just mark all tests as thread unsafe
+pytestmark = pytest.mark.thread_unsafe
+
 
 def validate_arguments(*args, **kwargs):
     with pytest.warns(

tests/test_discriminated_union.py

@@ -1655,6 +1655,7 @@ class PetModelAnnotatedWithField(BaseModel):
         ]
 
 
+@pytest.mark.thread_unsafe(reason='`pytest.raises()` is thread unsafe')
 def test_callable_discriminated_union_recursive():
     # Demonstrate that the errors are very verbose without a callable discriminator:
     class Model(BaseModel):
@@ -2149,6 +2150,7 @@ class Yard(BaseModel):
     assert str(yard_dict['pet']['type']) == 'dog'
 
 
+@pytest.mark.thread_unsafe(reason='Passes on multithreaded. This needs to be investigated further.')
 @pytest.mark.xfail(reason='Waiting for union serialization fixes via https://github.com/pydantic/pydantic/issues/9688.')
 def test_discriminated_union_serializer() -> None:
     """Reported via https://github.com/pydantic/pydantic/issues/9590."""

tests/test_docs.py

@@ -142,6 +142,7 @@ def run_example(example: CodeExample, eval_example: EvalExample, mocker: Any) ->
         group_globals.set(group_name, d2)
 
 
+@pytest.mark.thread_unsafe
 @pytest.mark.filterwarnings('ignore:(parse_obj_as|schema_json_of|schema_of) is deprecated.*:DeprecationWarning')
 @pytest.mark.skipif(bool(skip_reason), reason=skip_reason or 'not skipping')
 @pytest.mark.parametrize('example', find_examples(str(SOURCES_ROOT), skip=sys.platform == 'win32'), ids=str)
@@ -165,6 +166,7 @@ def set_cwd():
         os.chdir(cwd)
 
 
+@pytest.mark.thread_unsafe
 @pytest.mark.filterwarnings('ignore:(parse_obj_as|schema_json_of|schema_of) is deprecated.*:DeprecationWarning')
 @pytest.mark.filterwarnings('ignore::pydantic.warnings.PydanticExperimentalWarning')
 @pytest.mark.skipif(bool(skip_reason), reason=skip_reason or 'not skipping')
@@ -184,6 +186,7 @@ def test_docs_examples(example: CodeExample, eval_example: EvalExample, tmp_path
     run_example(example, eval_example, mocker)
 
 
+@pytest.mark.thread_unsafe
 @pytest.mark.skipif(bool(skip_reason), reason=skip_reason or 'not skipping')
 @pytest.mark.skipif(sys.version_info >= (3, 13), reason='python-devtools does not yet support python 3.13')
 @pytest.mark.parametrize(

tests/test_exports.py

@@ -28,6 +28,7 @@ def test_public_api_dynamic_imports(attr_name, value):
         assert isinstance(imported_object, object)
 
 
+@pytest.mark.thread_unsafe
 @pytest.mark.filterwarnings('ignore::DeprecationWarning')
 @pytest.mark.filterwarnings('ignore::pydantic.warnings.PydanticExperimentalWarning')
 def test_public_internal():