fastapi 0.151.0__tar.gz → 0.153.0__tar.gz

{fastapi-0.151.0 → fastapi-0.153.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi
-Version: 0.151.0
+Version: 0.153.0
 Summary: FastAPI framework, high performance, easy to learn, fast to code, ready for production
 Author-Email: Sebastián Ramírez <tiangolo@gmail.com>
 License-Expression: MIT

{fastapi-0.151.0 → fastapi-0.153.0}/fastapi/__init__.py

@@ -1,6 +1,6 @@
 """FastAPI framework, high performance, easy to learn, fast to code, ready for production"""
 
-__version__ = "0.151.0"
+__version__ = "0.153.0"
 
 from starlette import status as status
 

{fastapi-0.151.0 → fastapi-0.153.0}/fastapi/dependencies/utils.py

@@ -15,6 +15,7 @@ from collections.abc import (
 from contextlib import AsyncExitStack, contextmanager
 from copy import copy, deepcopy
 from dataclasses import dataclass
+from functools import partial
 from typing import (
     Annotated,
     Any,
@@ -69,7 +70,7 @@ from fastapi.logger import logger
 from fastapi.security.oauth2 import SecurityScopes
 from fastapi.types import DependencyCacheKey
 from fastapi.utils import create_model_field, get_path_param_names
-from pydantic import AliasChoices, AliasPath, BaseModel, Json
+from pydantic import AliasChoices, AliasPath, BaseModel, BeforeValidator, Json, Tag
 from pydantic.fields import FieldInfo
 from starlette.background import BackgroundTasks as StarletteBackgroundTasks
 from starlette.concurrency import run_in_threadpool
@@ -521,6 +522,10 @@ def analyze_param(
         use_annotation_from_field_info = use_annotation
         if isinstance(field_info, params.Form):
             ensure_multipart_is_installed()
+            if is_union_of_base_models(field_info.annotation):
+                field_info.annotation = _add_form_union_validators(
+                    field_info.annotation
+                )
         if not field_info.alias and getattr(field_info, "convert_underscores", None):
             alias = param_name.replace("_", "-")
         else:
@@ -810,6 +815,7 @@ def request_params_to_args(
         )
 
     params_to_process: dict[str, Any] = {}
+    header_aliases: dict[str, str] = {}
 
     processed_keys = set()
 
@@ -825,6 +831,7 @@ def request_params_to_args(
                 alias = get_validation_alias(field)
                 if alias == field.name:
                     alias = alias.replace("_", "-")
+                    header_aliases[field.name] = alias
         value = _get_multidict_value(field, received_params, alias=alias)
         if value is not Undefined:
             params_to_process[get_validation_alias(field)] = value
@@ -854,6 +861,18 @@ def request_params_to_args(
         v_, errors_ = _validate_value_with_model_field(
             field=first_field, value=params_to_process, values=values, loc=loc
         )
+        if header_aliases and cast(
+            type[BaseModel], first_field.field_info.annotation
+        ).model_config.get("loc_by_alias", True):
+            # Report the header names without changing model aliases or schema.
+            for error in errors_:
+                error_loc = error["loc"]
+                if len(error_loc) > 1 and error_loc[1] in header_aliases:
+                    error["loc"] = (
+                        error_loc[0],
+                        header_aliases[error_loc[1]],
+                        *error_loc[2:],
+                    )
         return {first_field.name: v_}, errors_
 
     for field in fields:
@@ -886,12 +905,55 @@ def is_union_of_base_models(field_type: Any) -> bool:
     union_args = get_args(field_type)
 
     for arg in union_args:
+        if get_origin(arg) is Annotated:
+            arg = get_args(arg)[0]
         if not lenient_issubclass(arg, BaseModel):
             return False
 
     return True
 
 
+def _add_form_union_validators(annotation: Any) -> Any:
+    choices = []
+    for choice in get_args(annotation):
+        model = choice
+        metadata: Sequence[Any] = ()
+        if get_origin(choice) is Annotated:
+            model, *metadata = get_args(choice)
+        validator = BeforeValidator(partial(_normalize_form_model, model=model))
+        # Keep existing discriminator tags or model names in union errors.
+        tag = next(
+            (item for item in reversed(metadata) if isinstance(item, Tag)),
+            Tag(model.__name__),
+        )
+        choices.append(Annotated[choice, validator, tag])
+    return Union[tuple(choices)]  # noqa: UP007
+
+
+def _normalize_form_model(value: Any, *, model: type[BaseModel]) -> Any:
+    if isinstance(value, dict):
+        # Repeated form values must be interpreted separately by each union branch.
+        form_data = FormData(
+            [
+                (key, item)
+                for key, items in value.items()
+                for item in (items if isinstance(items, list) else [items])
+            ]
+        )
+        normalized = {
+            alias: item
+            for alias, item, _ in _extract_form_items(
+                get_cached_model_fields(model), form_data
+            )
+        }
+        # These cannot come from browser form entries, but a validator can supply them.
+        for key, item in value.items():
+            if item is None or (isinstance(item, list) and not item):
+                normalized[key] = item
+        return normalized
+    return value
+
+
 def _should_embed_body_fields(fields: list[ModelField]) -> bool:
     if not fields:
         return False
@@ -916,11 +978,10 @@ def _should_embed_body_fields(fields: list[ModelField]) -> bool:
     return False
 
 
-async def _extract_form_body(
+def _extract_form_items(
     body_fields: list[ModelField],
     received_body: FormData,
-) -> dict[str, Any]:
-    values: dict[str, Any] = {}
+) -> Iterator[tuple[str, Any, ModelField | None]]:
     field_aliases: set[str] = set()
 
     for field in body_fields:
@@ -963,40 +1024,44 @@ async def _extract_form_body(
                 value: Any = False
             else:
                 value = _get_multidict_value(field, received_body, alias=alias)
-            field_info = field.field_info
-            if (
-                isinstance(field_info, params.File)
-                and is_bytes_or_nonable_bytes_annotation(field.field_info.annotation)
-                and isinstance(value, UploadFile)
-            ):
-                value = await value.read()
-            elif (
-                is_bytes_sequence_annotation(field.field_info.annotation)
-                and isinstance(field_info, params.File)
-                and value_is_sequence(value)
-            ):
-                # For types
-                assert isinstance(value, sequence_types)
-                results: list[bytes | str] = []
-                for sub_value in value:
-                    if isinstance(sub_value, UploadFile):
-                        results.append(await sub_value.read())
-                    else:
-                        results.append(sub_value)
-                value = serialize_sequence_value(field=field, value=results)
             if field.config is None:
                 # Individual parameters are later looked up by their declared alias.
                 alias = get_validation_alias(field)
                 field_aliases.add(alias)
             if value is not Undefined:
-                values[alias] = value
+                yield alias, value, field
     for key in received_body.keys():
         if key not in field_aliases:
             param_values = received_body.getlist(key)
             if len(param_values) == 1:
-                values[key] = param_values[0]
+                yield key, param_values[0], None
             else:
-                values[key] = param_values
+                yield key, param_values, None
+
+
+async def _extract_form_body(
+    body_fields: list[ModelField],
+    received_body: FormData,
+) -> dict[str, Any]:
+    values: dict[str, Any] = {}
+    for alias, value, field in _extract_form_items(body_fields, received_body):
+        if field is not None and isinstance(field.field_info, params.File):
+            if is_bytes_or_nonable_bytes_annotation(
+                field.field_info.annotation
+            ) and isinstance(value, UploadFile):
+                value = await value.read()
+            elif is_bytes_sequence_annotation(
+                field.field_info.annotation
+            ) and value_is_sequence(value):
+                assert isinstance(value, sequence_types)
+                results: list[bytes | str] = []
+                for sub_value in value:
+                    if isinstance(sub_value, UploadFile):
+                        results.append(await sub_value.read())
+                    else:
+                        results.append(sub_value)
+                value = serialize_sequence_value(field=field, value=results)
+        values[alias] = value
     return values
 
 
@@ -1022,6 +1087,12 @@ async def request_body_to_args(
         fields_to_extract = get_cached_model_fields(first_field.field_info.annotation)
 
     if isinstance(received_body, FormData):
+        if single_not_embedded_field and is_union_of_base_models(
+            first_field.field_info.annotation
+        ):
+            # Preserve all form values for validators around the union.
+            # Each branch applies its own model field extraction afterward.
+            fields_to_extract = []
         body_to_process = await _extract_form_body(fields_to_extract, received_body)
 
     if single_not_embedded_field:

{fastapi-0.151.0 → fastapi-0.153.0}/pyproject.toml

@@ -53,7 +53,7 @@ dependencies = [
     "annotated-doc>=0.0.2",
     "opentelemetry-api>=1.44.0",
 ]
-version = "0.151.0"
+version = "0.153.0"
 
 [project.urls]
 Homepage = "https://github.com/fastapi/fastapi"

{fastapi-0.151.0 → fastapi-0.153.0}/tests/test_query_cookie_header_model_extra_params.py

@@ -123,7 +123,7 @@ def test_header_model_rejects_underscore_header_with_convert_underscores():
     )
 
     assert resp.status_code == 422
-    assert resp.json()["detail"][0]["loc"] == ["header", "x_user_id"]
+    assert resp.json()["detail"][0]["loc"] == ["header", "x-user-id"]
 
 
 def test_cookie_pass_extra_list():

{fastapi-0.151.0 → fastapi-0.153.0}/tests/test_request_params/test_file/test_nullable_and_defaults.py

@@ -1,10 +1,10 @@
 from typing import Annotated
 
 import pytest
-from fastapi import FastAPI, File, Form, UploadFile
+from fastapi import FastAPI, File, Form, UploadFile, params
 from fastapi.testclient import TestClient
 from inline_snapshot import snapshot
-from pydantic import BaseModel, Field
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field
 
 app = FastAPI()
 
@@ -281,6 +281,43 @@ def test_required_non_nullable_files():
     assert response.json() == {"file": 0, "files": [0]}
 
 
+@pytest.mark.parametrize(
+    "file_alias,files_alias",
+    [("primary", "primary-files"), ("secondary", "secondary-files"), ("file", "files")],
+)
+def test_model_bytes_files_use_validation_aliases(file_alias, files_alias):
+    app = FastAPI()
+
+    class FileModel(BaseModel):
+        model_config = ConfigDict(populate_by_name=True)
+        file: Annotated[
+            bytes, File(validation_alias=AliasChoices("primary", "secondary"))
+        ]
+        files: Annotated[
+            list[bytes],
+            File(validation_alias=AliasChoices("primary-files", "secondary-files")),
+        ]
+
+    if not isinstance(FileModel.model_fields["file"], params.File):
+        pytest.skip("This Pydantic version does not preserve File metadata in models")
+
+    @app.post("/")
+    def read_form(data: Annotated[FileModel, Form()]):
+        return data
+
+    client = TestClient(app)
+    response = client.post(
+        "/",
+        files=[
+            (file_alias, ("one.txt", b"one")),
+            (files_alias, ("two.txt", b"two")),
+            (files_alias, ("three.txt", b"three")),
+        ],
+    )
+    assert response.status_code == 200
+    assert response.json() == {"file": "one", "files": ["two", "three"]}
+
+
 def test_openapi_schema():
     response = client.get("/openapi.json")
     assert response.status_code == 200, response.text

fastapi-0.153.0/tests/test_request_params/test_header/test_nullable_and_defaults.py

@@ -0,0 +1,227 @@
+from typing import Annotated
+
+import pytest
+from fastapi import FastAPI, Header
+from fastapi.testclient import TestClient
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+app = FastAPI()
+
+
+@app.get("/parameter")
+def read_parameter(int_val: Annotated[int | None, Header()]):
+    return int_val
+
+
+class Model(BaseModel):
+    int_val: int | None
+
+
+@app.get("/model")
+def read_model(params: Annotated[Model, Header()]):
+    return params.int_val
+
+
+client = TestClient(app)
+
+
+@pytest.mark.parametrize(
+    "path,title", [("/parameter", "Int-Val"), ("/model", "Int Val")]
+)
+def test_nullable_header_uses_hyphenated_name(path, title):
+    response = client.get(path, headers={"int-val": "0"})
+    assert response.status_code == 200
+    assert response.json() == 0
+    response = client.get("/openapi.json")
+    assert response.status_code == 200, response.text
+    field = response.json()["paths"][path]["get"]["parameters"][0]
+    assert field["name"] == "int-val"
+    assert field["in"] == "header"
+    assert field["required"] is True
+    assert field["schema"]["title"] == title
+    assert field["schema"]["anyOf"] == [{"type": "integer"}, {"type": "null"}]
+
+
+@pytest.mark.parametrize("path", ["/parameter", "/model"])
+@pytest.mark.parametrize(
+    "headers,error_type",
+    [({}, "missing"), ({"int-val": "invalid"}, "int_parsing")],
+)
+def test_nullable_header_error_uses_hyphenated_name(path, headers, error_type):
+    response = client.get(path, headers=headers)
+    assert response.status_code == 422
+    assert [(error["type"], error["loc"]) for error in response.json()["detail"]] == [
+        (error_type, ["header", "int-val"]),
+    ]
+
+
+@pytest.mark.parametrize(
+    "headers,error_type",
+    [({}, "missing"), ({"int_val": "invalid"}, "int_parsing")],
+)
+def test_header_model_without_underscore_conversion(headers, error_type):
+    app = FastAPI()
+
+    @app.get("/")
+    def read_model(params: Annotated[Model, Header(convert_underscores=False)]):
+        return params.int_val
+
+    client = TestClient(app)
+    response = client.get("/", headers={"int_val": "1"})
+    assert response.status_code == 200
+    assert response.json() == 1
+
+    response = client.get("/", headers=headers)
+    assert response.status_code == 422
+    assert [(error["type"], error["loc"]) for error in response.json()["detail"]] == [
+        (error_type, ["header", "int_val"]),
+    ]
+
+
+@pytest.mark.parametrize(
+    "headers,error_type",
+    [
+        ({}, "missing"),
+        (
+            {"int-val": "invalid", "x_count": "invalid", "x_total": "invalid"},
+            "int_parsing",
+        ),
+    ],
+)
+def test_header_model_preserves_explicit_aliases(headers, error_type):
+    app = FastAPI()
+
+    class AliasHeaders(BaseModel):
+        int_val: int
+        count: Annotated[int, Field(alias="x_count")]
+        total: Annotated[int, Field(alias="unused", validation_alias="x_total")]
+
+    @app.get("/")
+    def read_model(params: Annotated[AliasHeaders, Header()]):
+        return params
+
+    client = TestClient(app)
+    response = client.get("/", headers={"int-val": "1", "x_count": "2", "x_total": "3"})
+    assert response.status_code == 200
+    assert response.json() == {"int_val": 1, "x_count": 2, "unused": 3}
+
+    response = client.get("/", headers=headers)
+    assert response.status_code == 422
+    assert [(error["type"], error["loc"]) for error in response.json()["detail"]] == [
+        (error_type, ["header", "int-val"]),
+        (error_type, ["header", "x_count"]),
+        (error_type, ["header", "x_total"]),
+    ]
+
+
+@pytest.mark.parametrize(
+    "headers,error_type",
+    [({}, "missing"), ({"int-val": "invalid", "x_count": "invalid"}, "int_parsing")],
+)
+def test_header_model_can_report_python_field_names(headers, error_type):
+    app = FastAPI()
+
+    class NameLocationHeaders(BaseModel):
+        model_config = ConfigDict(loc_by_alias=False)
+        int_val: int
+        item_count: Annotated[int, Field(alias="x_count")]
+
+    @app.get("/")
+    def read_model(params: Annotated[NameLocationHeaders, Header()]):
+        return params
+
+    client = TestClient(app)
+    response = client.get("/", headers={"int-val": "1", "x_count": "2"})
+    assert response.status_code == 200
+    assert response.json() == {"int_val": 1, "x_count": 2}
+
+    response = client.get("/", headers=headers)
+    assert response.status_code == 422
+    assert [(error["type"], error["loc"]) for error in response.json()["detail"]] == [
+        (error_type, ["header", "int_val"]),
+        (error_type, ["header", "item_count"]),
+    ]
+
+
+def test_header_model_list_error_preserves_item_index():
+    app = FastAPI()
+
+    class ListHeaders(BaseModel):
+        item_ids: list[int]
+
+    @app.get("/")
+    def read_model(params: Annotated[ListHeaders, Header()]):
+        return params.item_ids
+
+    client = TestClient(app)
+    response = client.get("/", headers=[("item-ids", "1"), ("item-ids", "2")])
+    assert response.status_code == 200
+    assert response.json() == [1, 2]
+
+    response = client.get("/", headers=[("item-ids", "1"), ("item-ids", "invalid")])
+    assert response.status_code == 422
+    assert response.json() == {
+        "detail": [
+            {
+                "type": "int_parsing",
+                "loc": ["header", "item-ids", 1],
+                "msg": "Input should be a valid integer, unable to parse string as an integer",
+                "input": "invalid",
+            }
+        ]
+    }
+
+
+def test_header_model_validation_error_has_no_field_location():
+    app = FastAPI()
+
+    class RangeHeaders(BaseModel):
+        range_start: int
+        range_end: int
+
+        @model_validator(mode="after")
+        def validate_range(self):
+            if self.range_start > self.range_end:
+                raise ValueError("range_start must not exceed range_end")
+            return self
+
+    @app.get("/")
+    def read_model(params: Annotated[RangeHeaders, Header()]):
+        return params
+
+    client = TestClient(app)
+    response = client.get("/", headers={"range-start": "1", "range-end": "2"})
+    assert response.status_code == 200
+    assert response.json() == {"range_start": 1, "range_end": 2}
+
+    response = client.get("/", headers={"range-start": "2", "range-end": "1"})
+    assert response.status_code == 422
+    assert [(error["type"], error["loc"]) for error in response.json()["detail"]] == [
+        ("value_error", ["header"]),
+    ]
+
+
+def test_header_model_extra_error_preserves_header_name():
+    app = FastAPI()
+
+    class StrictHeaders(BaseModel):
+        model_config = ConfigDict(extra="forbid")
+        host: str
+        int_val: int
+
+    @app.get("/")
+    def read_model(params: Annotated[StrictHeaders, Header()]):
+        return params.int_val
+
+    client = TestClient(app)
+    client.headers.clear()
+    response = client.get("/", headers={"int-val": "1"})
+    assert response.status_code == 200
+    assert response.json() == 1
+
+    response = client.get("/", headers={"int-val": "invalid", "extra_header": "value"})
+    assert response.status_code == 422
+    assert [(error["type"], error["loc"]) for error in response.json()["detail"]] == [
+        ("int_parsing", ["header", "int-val"]),
+        ("extra_forbidden", ["header", "extra_header"]),
+    ]

{fastapi-0.151.0 → fastapi-0.153.0}/tests/test_tutorial/test_header_param_models/test_tutorial001.py

@@ -63,7 +63,7 @@ def test_header_param_model_invalid(client: TestClient):
             "detail": [
                 {
                     "type": "missing",
-                    "loc": ["header", "save_data"],
+                    "loc": ["header", "save-data"],
                     "msg": "Field required",
                     "input": {
                         "host": "testserver",

{fastapi-0.151.0 → fastapi-0.153.0}/tests/test_tutorial/test_header_param_models/test_tutorial002.py

@@ -63,7 +63,7 @@ def test_header_param_model_invalid(client: TestClient):
             "detail": [
                 {
                     "type": "missing",
-                    "loc": ["header", "save_data"],
+                    "loc": ["header", "save-data"],
                     "msg": "Field required",
                     "input": {"host": "testserver"},
                 }