fastapi 0.159.0__tar.gz → 0.159.1__tar.gz

{fastapi-0.159.0 → fastapi-0.159.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi
-Version: 0.159.0
+Version: 0.159.1
 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.159.1/docs_src/request_form_models/tutorial006_an_py310.py

@@ -0,0 +1,23 @@
+from typing import Annotated, Literal
+
+from fastapi import FastAPI, Form
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Person(BaseModel):
+    kind: Literal["person"]
+    name: str
+
+
+class Company(BaseModel):
+    kind: Literal["company"]
+    company_name: str
+
+
+@app.post("/contacts/")
+async def create_contact(
+    contact: Annotated[Person | Company | None, Form(discriminator="kind")] = None,
+):
+    return contact

fastapi-0.159.1/docs_src/request_form_models/tutorial006_py310.py

@@ -0,0 +1,23 @@
+from typing import Literal
+
+from fastapi import FastAPI, Form
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Person(BaseModel):
+    kind: Literal["person"]
+    name: str
+
+
+class Company(BaseModel):
+    kind: Literal["company"]
+    company_name: str
+
+
+@app.post("/contacts/")
+async def create_contact(
+    contact: Person | Company | None = Form(default=None, discriminator="kind"),
+):
+    return contact

{fastapi-0.159.0 → fastapi-0.159.1}/fastapi/__init__.py

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

{fastapi-0.159.0 → fastapi-0.159.1}/fastapi/dependencies/utils.py

@@ -619,7 +619,7 @@ 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):
+            if _get_form_union_models(field_info.annotation):
                 field_info.annotation = _add_form_union_validators(
                     field_info.annotation
                 )
@@ -1038,28 +1038,28 @@ def request_params_to_args(
     return values, errors
 
 
-def is_union_of_base_models(field_type: Any) -> bool:
-    """Check if field type is a Union where all members are BaseModel subclasses."""
-    origin = get_origin(field_type)
-
-    # Check if it's a Union type (covers both typing.Union and types.UnionType in Python 3.10+)
-    if origin is not Union and origin is not UnionType:
-        return False
-
-    union_args = get_args(field_type)
-
-    for arg in union_args:
+def _get_form_union_models(annotation: Any) -> list[type[BaseModel]]:
+    if get_origin(annotation) not in (Union, UnionType):
+        return []
+    models = []
+    for arg in get_args(annotation):
+        if arg is type(None):
+            continue
         if get_origin(arg) is Annotated:
             arg = get_args(arg)[0]
         if not lenient_issubclass(arg, BaseModel):
-            return False
-
-    return True
+            return []
+        models.append(arg)
+    # A nullable single model uses the regular form model extraction.
+    return models if len(models) > 1 else []
 
 
 def _add_form_union_validators(annotation: Any) -> Any:
-    choices = []
+    choices: list[Any] = []
     for choice in get_args(annotation):
+        if choice is type(None):
+            choices.append(choice)
+            continue
         model = choice
         metadata: Sequence[Any] = ()
         if get_origin(choice) is Annotated:
@@ -1134,7 +1134,7 @@ def _should_embed_body_fields(fields: list[ModelField]) -> bool:
         isinstance(first_field.field_info, params.Form)
         and not lenient_issubclass(first_field.field_info.annotation, BaseModel)
         and _get_form_model(first_field) is None
-        and not is_union_of_base_models(first_field.field_info.annotation)
+        and not _get_form_union_models(first_field.field_info.annotation)
     ):
         return True
     return False
@@ -1223,28 +1223,40 @@ async def _extract_form_body(
         yield alias, value, field
 
 
+def _is_form_model_supplied(
+    model: type[BaseModel],
+    received_body: FormData,
+    known_param_names: set[str] | None = None,
+) -> bool:
+    # Check raw keys before empty fields are removed or checkboxes inferred.
+    own_names = {
+        alias
+        for item in get_cached_model_fields(model)
+        for alias, _ in _get_param_aliases(item)
+    }
+    return bool(
+        own_names.intersection(received_body)
+        or (
+            model.model_config.get("extra") in ("allow", "forbid")
+            and received_body.keys() - (known_param_names or own_names)
+        )
+    )
+
+
 async def _extract_form_model(
     field: ModelField,
     model: type[BaseModel],
     received_body: FormData,
     known_param_names: set[str] | None,
 ) -> Any:
-    model_fields = get_cached_model_fields(model)
-    if field.field_info.annotation is not model:
-        # Check raw keys before empty fields are removed or checkboxes inferred.
-        own_names = {
-            alias for item in model_fields for alias, _ in _get_param_aliases(item)
-        }
-        supplied = own_names.intersection(received_body)
-        extras = received_body.keys() - (known_param_names or own_names)
-        if not supplied and (
-            model.model_config.get("extra") not in ("allow", "forbid") or not extras
-        ):
-            return Undefined
+    if field.field_info.annotation is not model and not _is_form_model_supplied(
+        model, received_body, known_param_names
+    ):
+        return Undefined
     return {
         alias: item
         async for alias, item, _ in _extract_form_body(
-            model_fields, received_body, known_param_names
+            get_cached_model_fields(model), received_body, known_param_names
         )
     }
 
@@ -1267,14 +1279,18 @@ async def request_body_to_args(
     first_field = body_fields[0]
     body_to_process = received_body
     form_values: dict[str, tuple[str, Any]] = {}
+    form_union_absent = False
 
     if isinstance(received_body, FormData):
         fields_to_extract = [
             field for field in body_fields if _get_form_model(field) is None
         ]
-        if single_not_embedded_field and is_union_of_base_models(
-            first_field.field_info.annotation
-        ):
+        union_models = (
+            _get_form_union_models(first_field.field_info.annotation)
+            if single_not_embedded_field
+            else []
+        )
+        if union_models:
             # Preserve all form values for validators around the union.
             # Each branch applies its own model field extraction afterward.
             fields_to_extract = []
@@ -1288,11 +1304,21 @@ async def request_body_to_args(
             elif field is not None:
                 # Keep each parameter's selected alias and scalar/list shape.
                 form_values[field.name] = (alias, value)
+        form_union_absent = (
+            bool(union_models)
+            and type(None) in get_args(first_field.field_info.annotation)
+            and not any(
+                _is_form_model_supplied(model, received_body) for model in union_models
+            )
+        )
 
     if single_not_embedded_field:
         loc: tuple[str, ...] = ("body",)
         v_, errors_ = _validate_value_with_model_field(
-            field=first_field, value=body_to_process, values=values, loc=loc
+            field=first_field,
+            value=Undefined if form_union_absent else body_to_process,
+            values=values,
+            loc=loc,
         )
         return {first_field.name: v_}, errors_
     for field in body_fields:

{fastapi-0.159.0 → fastapi-0.159.1}/pyproject.toml

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

fastapi-0.159.1/tests/test_forms_optional_unions.py

@@ -0,0 +1,413 @@
+from typing import Annotated, Literal, Optional
+
+import pytest
+from fastapi import Depends, FastAPI, Form
+from fastapi.testclient import TestClient
+from pydantic import (
+    AliasChoices,
+    BaseModel,
+    BeforeValidator,
+    ConfigDict,
+    Field,
+    Tag,
+    model_validator,
+)
+
+app = FastAPI()
+
+
+class TextForm(BaseModel):
+    kind: Literal["text"]
+    value: str
+    enabled: bool = True
+
+
+class ListForm(BaseModel):
+    kind: Literal["list"]
+    value: list[str]
+
+
+@app.post("/union")
+def read_union(data: Annotated[TextForm | ListForm | None, Form()] = None):
+    return data
+
+
+@app.post("/discriminated")
+def read_discriminated(
+    data: Annotated[TextForm | ListForm | None, Form(discriminator="kind")] = None,
+):
+    return data
+
+
+client = TestClient(app)
+
+
+@pytest.mark.parametrize("path", ["/union", "/discriminated"])
+def test_absent_union(path):
+    response = client.post(path)
+    assert response.status_code == 200, response.text
+    assert response.json() is None
+    response = client.post(path, data={"unknown": "ignored"})
+    assert response.status_code == 200, response.text
+    assert response.json() is None
+
+
+@pytest.mark.parametrize("path", ["/union", "/discriminated"])
+def test_supplied_union(path):
+    response = client.post(path, data={"kind": "text", "value": "hello"})
+    assert response.status_code == 200, response.text
+    assert response.json() == {"kind": "text", "value": "hello", "enabled": False}
+    response = client.post(path, data={"kind": "list", "value": ["", "blue"]})
+    assert response.status_code == 200, response.text
+    assert response.json() == {"kind": "list", "value": ["", "blue"]}
+
+
+@pytest.mark.parametrize(
+    "path,branch", [("/union", "TextForm"), ("/discriminated", "text")]
+)
+@pytest.mark.parametrize("data", [{"kind": "text"}, {"kind": "text", "value": ""}])
+def test_partial_and_empty_fields(path, branch, data):
+    response = client.post(path, data=data)
+    assert response.status_code == 422
+    error = response.json()["detail"][0]
+    assert error["type"] == "missing"
+    assert error["loc"] == ["body", branch, "value"]
+
+
+@pytest.mark.parametrize("path", ["/union", "/discriminated"])
+def test_multipart_union(path):
+    response = client.post(path, files={"unknown": (None, "ignored")})
+    assert response.status_code == 200, response.text
+    assert response.json() is None
+    response = client.post(
+        path,
+        files=[
+            ("kind", (None, "list")),
+            ("value", (None, "")),
+            ("value", (None, "blue")),
+        ],
+    )
+    assert response.status_code == 200, response.text
+    assert response.json() == {"kind": "list", "value": ["", "blue"]}
+    response = client.post(path, files={"kind": (None, "text"), "value": (None, "")})
+    assert response.status_code == 422
+    assert response.json()["detail"][0]["type"] == "missing"
+
+
+@pytest.mark.parametrize(
+    "data,error_type",
+    [
+        ({"value": "hello"}, "union_tag_not_found"),
+        ({"value": ""}, "union_tag_not_found"),
+        ({"enabled": "false"}, "union_tag_not_found"),
+        ({"kind": ""}, "union_tag_invalid"),
+        ({"kind": "unknown"}, "union_tag_invalid"),
+    ],
+)
+def test_discriminator_errors(data, error_type):
+    response = client.post("/discriminated", data=data)
+    assert response.status_code == 422
+    assert response.json()["detail"][0]["type"] == error_type
+    assert response.json()["detail"][0]["loc"] == ["body"]
+
+
+def test_nullable_union_without_default_is_required():
+    app = FastAPI()
+
+    class Count(BaseModel):
+        count: int = 1
+
+    class Label(BaseModel):
+        label: str = "default"
+
+    @app.post("/")
+    def read(data: Annotated[Count | Label | None, Form()]):
+        return data
+
+    client = TestClient(app)
+    response = client.post("/")
+    assert response.status_code == 422
+    assert response.json()["detail"] == [
+        {"type": "missing", "loc": ["body"], "msg": "Field required", "input": None}
+    ]
+    response = client.post("/", data={"count": "2"})
+    assert response.status_code == 200, response.text
+    assert response.json() == {"count": 2}
+    assert app.openapi()["paths"]["/"]["post"]["requestBody"]["required"] is True
+
+
+@pytest.mark.parametrize("extra", ["ignore", "allow", "forbid"])
+def test_unknown_fields(extra):
+    app = FastAPI()
+
+    class Count(BaseModel):
+        model_config = ConfigDict(extra=extra)
+        count: int = 1
+
+    class Label(BaseModel):
+        model_config = ConfigDict(extra=extra)
+        label: str = "default"
+
+    @app.post("/")
+    def read(
+        data: Annotated[Count | Label | None, Form(union_mode="left_to_right")] = None,
+    ):
+        return data
+
+    client = TestClient(app)
+    response = client.post("/")
+    assert response.status_code == 200, response.text
+    assert response.json() is None
+    response = client.post("/", data={"unknown": ["a", "b"]})
+    if extra == "forbid":
+        assert response.status_code == 422
+        assert [error["loc"] for error in response.json()["detail"]] == [
+            ["body", "Count", "unknown"],
+            ["body", "Label", "unknown"],
+        ]
+        assert all(
+            error["type"] == "extra_forbidden" for error in response.json()["detail"]
+        )
+    else:
+        assert response.status_code == 200, response.text
+        assert response.json() == (
+            {"count": 1, "unknown": ["a", "b"]} if extra == "allow" else None
+        )
+
+
+def test_mixed_extra_configurations_activate_union():
+    app = FastAPI()
+
+    class Ignored(BaseModel):
+        name: str
+
+    class Allowed(BaseModel):
+        model_config = ConfigDict(extra="allow")
+        count: int = 1
+
+    @app.post("/")
+    def read(data: Annotated[Ignored | Allowed | None, Form()] = None):
+        return data
+
+    response = TestClient(app).post("/", data={"unknown": "value"})
+    assert response.status_code == 200, response.text
+    assert response.json() == {"count": 1, "unknown": "value"}
+
+
+@pytest.mark.parametrize("name", ["full_name", "name"])
+def test_aliases_activate_union(name):
+    app = FastAPI()
+
+    class AliasedForm(BaseModel):
+        name: str = Field(validation_alias=AliasChoices("full_name", "name"))
+
+    @app.post("/")
+    def read(data: Annotated[AliasedForm | ListForm | None, Form()] = None):
+        return data
+
+    client = TestClient(app)
+    response = client.post("/", data={"unknown": "ignored"})
+    assert response.status_code == 200, response.text
+    assert response.json() is None
+    response = client.post("/", data={name: "Rick"})
+    assert response.status_code == 200, response.text
+    assert response.json() == {"name": "Rick"}
+
+
+@pytest.mark.parametrize("name", ["full_name", "name"])
+def test_aliases_and_forbidden_extras(name):
+    app = FastAPI()
+
+    class Person(BaseModel):
+        model_config = ConfigDict(extra="forbid")
+        kind: Literal["person"] = Field(alias="type")
+        name: str = Field(validation_alias=AliasChoices("full_name", "name"))
+
+    class Company(BaseModel):
+        model_config = ConfigDict(extra="forbid")
+        kind: Literal["company"] = Field(alias="type")
+        company_name: str
+
+    @app.post("/")
+    def read(
+        data: Annotated[Person | Company | None, Form(discriminator="kind")] = None,
+    ):
+        return data
+
+    client = TestClient(app)
+    response = client.post("/", data={name: "Rick"})
+    assert response.status_code == 422
+    assert response.json()["detail"][0]["type"] == "union_tag_not_found"
+    response = client.post("/", data={"type": "person", name: "Rick"})
+    assert response.status_code == 200, response.text
+    assert response.json() == {"type": "person", "name": "Rick"}
+    response = client.post(
+        "/", data={"type": "person", name: "Rick", "company_name": "Acme"}
+    )
+    assert response.status_code == 422
+    assert response.json()["detail"][0]["type"] == "extra_forbidden"
+    assert response.json()["detail"][0]["loc"] == ["body", "person", "company_name"]
+
+
+def test_branch_tags_and_before_validator():
+    app = FastAPI()
+    calls = []
+
+    def copy_input(data):
+        calls.append(data.copy())
+        return data.copy()
+
+    @app.post("/")
+    def read(
+        data: Annotated[
+            Annotated[TextForm, Tag("text")] | Annotated[ListForm, Tag("list")] | None,
+            BeforeValidator(copy_input),
+            Form(),
+        ] = None,
+    ):
+        return data
+
+    client = TestClient(app)
+    response = client.post("/")
+    assert response.status_code == 200, response.text
+    assert response.json() is None
+    assert calls == []
+    response = client.post("/", data={"kind": "list", "value": ["", "blue"]})
+    assert response.status_code == 200, response.text
+    assert response.json() == {"kind": "list", "value": ["", "blue"]}
+    assert calls == [{"kind": "list", "value": ["", "blue"]}]
+    response = client.post("/", data={"kind": "text", "value": ""})
+    assert response.status_code == 422
+    assert [error["loc"] for error in response.json()["detail"]] == [
+        ["body", "text", "value"],
+        ["body", "list", "kind"],
+    ]
+
+
+def test_defaults_factories_and_validators():
+    app = FastAPI()
+    calls = []
+
+    class Defaults(BaseModel):
+        kind: Literal["defaults"] = "defaults"
+        tags: list[str] = Field(default_factory=list)
+        enabled: bool = True
+
+        @model_validator(mode="after")
+        def record_validation(self):
+            calls.append("validated")
+            return self
+
+    default = Defaults()
+
+    def factory():
+        calls.append("factory")
+        return Defaults()
+
+    @app.post("/default")
+    def read_default(data: Annotated[Defaults | TextForm | None, Form()] = default):
+        assert isinstance(data, Defaults)
+        data.tags.append("new")
+        return data
+
+    @app.post("/factory")
+    def read_factory(
+        data: Annotated[Defaults | TextForm | None, Form(default_factory=factory)],
+    ):
+        return data
+
+    @app.post("/validated-default")
+    def read_validated_default(
+        data: Annotated[
+            Defaults | TextForm | None, Form(validate_default=True)
+        ] = default,
+    ):
+        return data
+
+    client = TestClient(app)
+    calls.clear()
+    for _ in range(2):
+        response = client.post("/default")
+        assert response.status_code == 200, response.text
+        assert response.json() == {"kind": "defaults", "tags": ["new"], "enabled": True}
+    assert default.tags == []
+    assert calls == []
+    response = client.post("/factory")
+    assert response.status_code == 200, response.text
+    assert response.json() == {"kind": "defaults", "tags": [], "enabled": True}
+    assert calls == ["factory", "validated"]
+    calls.clear()
+    response = client.post("/factory", data={"kind": "defaults"})
+    assert response.status_code == 200, response.text
+    assert response.json() == {"kind": "defaults", "tags": [], "enabled": False}
+    assert calls == ["validated"]
+    calls.clear()
+    response = client.post("/validated-default")
+    assert response.status_code == 200, response.text
+    assert calls == ["validated"]
+
+
+def test_optional_union_in_dependency():
+    app = FastAPI()
+
+    def get_form(
+        data: Optional[TextForm | ListForm] = Form(default=None),  # noqa: UP045
+    ):
+        return data
+
+    @app.post("/")
+    def read(data: Annotated[TextForm | ListForm | None, Depends(get_form)]):
+        return data
+
+    client = TestClient(app)
+    response = client.post("/")
+    assert response.status_code == 200, response.text
+    assert response.json() is None
+    response = client.post("/", data={"kind": "text", "value": "hello"})
+    assert response.status_code == 200, response.text
+    assert response.json() == {"kind": "text", "value": "hello", "enabled": False}
+
+
+def test_openapi():
+    schema = app.openapi()
+    assert schema["paths"]["/union"]["post"]["requestBody"] == {
+        "content": {
+            "application/x-www-form-urlencoded": {
+                "schema": {
+                    "anyOf": [
+                        {"$ref": "#/components/schemas/TextForm"},
+                        {"$ref": "#/components/schemas/ListForm"},
+                        {"type": "null"},
+                    ],
+                    "title": "Data",
+                }
+            }
+        }
+    }
+    assert schema["paths"]["/discriminated"]["post"]["requestBody"] == {
+        "content": {
+            "application/x-www-form-urlencoded": {
+                "schema": {
+                    "anyOf": [
+                        {
+                            "oneOf": [
+                                {"$ref": "#/components/schemas/TextForm"},
+                                {"$ref": "#/components/schemas/ListForm"},
+                            ],
+                            "discriminator": {
+                                "propertyName": "kind",
+                                "mapping": {
+                                    "text": "#/components/schemas/TextForm",
+                                    "list": "#/components/schemas/ListForm",
+                                },
+                            },
+                        },
+                        {"type": "null"},
+                    ],
+                    "title": "Data",
+                }
+            }
+        }
+    }
+    assert schema["components"]["schemas"]["TextForm"]["required"] == ["kind", "value"]
+    assert schema["components"]["schemas"]["ListForm"]["required"] == ["kind", "value"]