⬆️ Support free-threaded Python 3.14t (#15149)

Author: svlandeg

.github/workflows/test.yml

@@ -49,7 +49,8 @@ jobs:
     strategy:
       matrix:
         os: [ windows-latest, macos-latest ]
-        python-version: [ "3.14" ]
+        python-version: [ "3.14", "3.14t" ]
+        deprecated-tests: [ "no-deprecation" ]
         uv-resolution:
           - highest
         starlette-src:
@@ -60,23 +61,33 @@ jobs:
             python-version: "3.10"
             coverage: coverage
             uv-resolution: lowest-direct
+            deprecated-tests: "no-deprecation"
           - os: windows-latest
             python-version: "3.12"
             coverage: coverage
             uv-resolution: lowest-direct
+            deprecated-tests: "no-deprecation"
           - os: ubuntu-latest
             python-version: "3.13"
             coverage: coverage
             uv-resolution: highest
+            deprecated-tests: "no-deprecation"
           - os: ubuntu-latest
             python-version: "3.13"
             uv-resolution: highest
             codspeed: codspeed
+            deprecated-tests: "no-deprecation"
           - os: ubuntu-latest
             python-version: "3.14"
             coverage: coverage
             uv-resolution: highest
             starlette-src: starlette-git
+            deprecated-tests: "test-deprecation"
+          - os: ubuntu-latest
+            python-version: "3.14t"
+            coverage: coverage
+            uv-resolution: highest
+            deprecated-tests: "no-deprecation"
       fail-fast: false
     runs-on: ${{ matrix.os }}
     env:
@@ -108,18 +119,24 @@ jobs:
       - name: Install Starlette from source
         if: matrix.starlette-src == 'starlette-git'
         run: uv pip install "git+https://github.com/Kludex/starlette@main"
+      - name: Install deprecated libraries just for testing
+        if: matrix.deprecated-tests == 'test-deprecation'
+        run: uv pip install orjson ujson
+      - name: Reinstall SQLAlchemy without Cython extensions
+        if: matrix.python-version == '3.14t' && matrix.os == 'ubuntu-latest'
+        run: "DISABLE_SQLALCHEMY_CEXT=1 uv pip install --force-reinstall --no-binary :all: sqlalchemy"
       - run: mkdir coverage
       - name: Test
         run: uv run --no-sync bash scripts/test-cov.sh
         env:
-          COVERAGE_FILE: coverage/.coverage.${{ runner.os }}-py${{ matrix.python-version }}
-          CONTEXT: ${{ runner.os }}-py${{ matrix.python-version }}
+          COVERAGE_FILE: coverage/.coverage.${{ runner.os }}-py${{ matrix.python-version }}-${{ matrix.deprecated-tests}}
+          CONTEXT: ${{ runner.os }}-py${{ matrix.python-version }}-${{ matrix.deprecated-tests}}
       # Do not store coverage for all possible combinations to avoid file size max errors in Smokeshow
       - name: Store coverage files
         if: matrix.coverage == 'coverage'
         uses: actions/upload-artifact@v7
         with:
-          name: coverage-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('**/coverage/.coverage.*') }}
+          name: coverage-${{ runner.os }}-${{ matrix.python-version }}-${{ matrix.deprecated-tests}}-${{ hashFiles('**/coverage/.coverage.*') }}
           path: coverage
           include-hidden-files: true
 

fastapi/responses.py

@@ -1,4 +1,5 @@
-from typing import Any
+import importlib
+from typing import Any, Protocol, cast
 
 from fastapi.exceptions import FastAPIDeprecationWarning
 from fastapi.sse import EventSourceResponse as EventSourceResponse  # noqa
@@ -11,16 +12,28 @@
 from starlette.responses import StreamingResponse as StreamingResponse  # noqa
 from typing_extensions import deprecated
 
+
+class _UjsonModule(Protocol):
+    def dumps(self, __obj: Any, *, ensure_ascii: bool = ...) -> str: ...
+
+
+class _OrjsonModule(Protocol):
+    OPT_NON_STR_KEYS: int
+    OPT_SERIALIZE_NUMPY: int
+
+    def dumps(self, __obj: Any, *, option: int = ...) -> bytes: ...
+
+
 try:
-    import ujson
-except ImportError:  # pragma: nocover
-    ujson = None  # type: ignore
+    ujson = cast(_UjsonModule, importlib.import_module("ujson"))
+except ModuleNotFoundError:  # pragma: nocover
+    ujson = None  # type: ignore  # ty: ignore[unused-ignore-comment]
 
 
 try:
-    import orjson
-except ImportError:  # pragma: nocover
-    orjson = None  # type: ignore
+    orjson = cast(_OrjsonModule, importlib.import_module("orjson"))
+except ModuleNotFoundError:  # pragma: nocover
+    orjson = None  # type: ignore  # ty: ignore[unused-ignore-comment]
 
 
 @deprecated(

pyproject.toml

@@ -59,6 +59,7 @@ Changelog = "https://fastapi.tiangolo.com/release-notes/"
 [project.optional-dependencies]
 standard = [
     "fastapi-cli[standard] >=0.0.8",
+    "fastar >= 0.9.0",
     # For the test client
     "httpx >=0.23.0,<1.0.0",
     # For templates
@@ -149,10 +150,6 @@ docs = [
 docs-tests = [
     "httpx >=0.23.0,<1.0.0",
     "ruff >=0.14.14",
-    # For UJSONResponse
-    "ujson >=5.8.0",
-    # For ORJSONResponse
-    "orjson >=3.9.3",
 ]
 github-actions = [
     "httpx >=0.27.0,<1.0.0",
@@ -178,8 +175,6 @@ tests = [
     "sqlmodel >=0.0.31",
     "strawberry-graphql >=0.200.0,<1.0.0",
     "ty>=0.0.9",
-    "types-orjson >=3.6.2",
-    "types-ujson >=5.10.0.20240515",
     "a2wsgi >=1.9.0,<=2.0.0",
     "pytest-xdist[psutil]>=2.5.0",
     "pytest-cov>=4.0.0",

tests/test_default_response_class.py

@@ -1,15 +1,18 @@
 from typing import Any
 
-import orjson
 from fastapi import APIRouter, FastAPI
 from fastapi.responses import HTMLResponse, JSONResponse, PlainTextResponse
 from fastapi.testclient import TestClient
 
+from tests.utils import needs_orjson
+
 
 class ORJSONResponse(JSONResponse):
     media_type = "application/x-orjson"
 
     def render(self, content: Any) -> bytes:
+        import orjson
+
         return orjson.dumps(content)
 
 
@@ -118,6 +121,7 @@ def get_b_a_c_path_override():
 override_type = "application/x-override"
 
 
+@needs_orjson
 def test_app():
     with client:
         response = client.get("/")
@@ -132,6 +136,7 @@ def test_app_override():
     assert response.headers["content-type"] == text_type
 
 
+@needs_orjson
 def test_router_a():
     with client:
         response = client.get("/a")
@@ -146,6 +151,7 @@ def test_router_a_override():
     assert response.headers["content-type"] == text_type
 
 
+@needs_orjson
 def test_router_a_a():
     with client:
         response = client.get("/a/a")

tests/test_deprecated_responses.py

@@ -7,6 +7,8 @@
 from fastapi.testclient import TestClient
 from pydantic import BaseModel
 
+from tests.utils import needs_orjson, needs_ujson
+
 
 class Item(BaseModel):
     name: str
@@ -28,6 +30,7 @@ def get_items() -> Item:
     return app
 
 
+@needs_orjson
 def test_orjson_response_returns_correct_data():
     app = _make_orjson_app()
     client = TestClient(app)
@@ -38,6 +41,7 @@ def test_orjson_response_returns_correct_data():
     assert response.json() == {"name": "widget", "price": 9.99}
 
 
+@needs_orjson
 def test_orjson_response_emits_deprecation_warning():
     with pytest.warns(FastAPIDeprecationWarning, match="ORJSONResponse is deprecated"):
         ORJSONResponse(content={"hello": "world"})
@@ -58,6 +62,7 @@ def get_items() -> Item:
     return app
 
 
+@needs_ujson
 def test_ujson_response_returns_correct_data():
     app = _make_ujson_app()
     client = TestClient(app)
@@ -68,6 +73,7 @@ def test_ujson_response_returns_correct_data():
     assert response.json() == {"name": "widget", "price": 9.99}
 
 
+@needs_ujson
 def test_ujson_response_emits_deprecation_warning():
     with pytest.warns(FastAPIDeprecationWarning, match="UJSONResponse is deprecated"):
         UJSONResponse(content={"hello": "world"})

tests/test_orjson_response_class.py

@@ -1,5 +1,9 @@
 import warnings
 
+import pytest
+
+pytest.importorskip("orjson")
+
 from fastapi import FastAPI
 from fastapi.exceptions import FastAPIDeprecationWarning
 from fastapi.responses import ORJSONResponse

tests/test_tutorial/test_custom_response/test_tutorial001.py

@@ -4,6 +4,8 @@
 from fastapi.testclient import TestClient
 from inline_snapshot import snapshot
 
+pytest.importorskip("orjson")
+
 
 @pytest.fixture(
     name="client",

tests/test_tutorial/test_custom_response/test_tutorial001b.py

@@ -11,6 +11,8 @@
 
 client = TestClient(app)
 
+pytest.importorskip("orjson")
+
 
 @pytest.mark.filterwarnings("ignore::fastapi.exceptions.FastAPIDeprecationWarning")
 def test_get_custom_response():

tests/test_tutorial/test_custom_response/test_tutorial009c.py

@@ -1,5 +1,8 @@
+import pytest
 from fastapi.testclient import TestClient
 
+pytest.importorskip("orjson")
+
 from docs_src.custom_response.tutorial009c_py310 import app
 
 client = TestClient(app)

tests/utils.py

@@ -1,3 +1,4 @@
+import importlib
 import sys
 
 import pytest
@@ -9,6 +10,16 @@
     sys.version_info < (3, 14), reason="requires python3.14+"
 )
 
+needs_orjson = pytest.mark.skipif(
+    importlib.util.find_spec("orjson") is None,
+    reason="requires orjson",
+)
+
+needs_ujson = pytest.mark.skipif(
+    importlib.util.find_spec("ujson") is None,
+    reason="requires ujson",
+)
+
 workdir_lock = pytest.mark.xdist_group("workdir_lock")