ycdemo / fastapi / tests/ test_request_params/ test_file/ test_nullable_and_defaults.py

from typing import Annotated

import pytest
from fastapi import FastAPI, File, Form, UploadFile, params
from fastapi.testclient import TestClient
from inline_snapshot import snapshot
from pydantic import AliasChoices, BaseModel, ConfigDict, Field

app = FastAPI()


@app.post("/required-bytes")
def read_required_bytes(
    file: Annotated[bytes | None, File()],
    files: Annotated[list[bytes] | None, File()],
):
    assert file is not None
    assert files is not None
    return {"file": len(file), "files": [len(value) for value in files]}


@app.post("/required-uploadfile")
def read_required_uploadfile(
    file: Annotated[UploadFile | None, File()],
    files: Annotated[list[UploadFile] | None, File()],
):
    assert file is not None
    assert files is not None
    return {"file": file.size, "files": [value.size for value in files]}


@app.post("/optional-bytes")
def read_optional_bytes(
    file: Annotated[bytes | None, File()] = None,
    files: Annotated[list[bytes] | None, File()] = None,
):
    return {
        "file": len(file) if file is not None else None,
        "files": [len(value) for value in files] if files is not None else None,
    }


@app.post("/optional-uploadfile")
def read_optional_uploadfile(
    file: Annotated[UploadFile | None, File()] = None,
    files: Annotated[list[UploadFile] | None, File()] = None,
):
    return {
        "file": file.size if file is not None else None,
        "files": [value.size for value in files] if files is not None else None,
    }


@app.post("/bytes-defaults")
def read_bytes_defaults(
    *,
    file: Annotated[bytes | None, File()] = b"default",
    files: Annotated[list[bytes] | None, File(default_factory=lambda: [b"default"])],
):
    assert file is not None
    assert files is not None
    return {"file": len(file), "files": [len(value) for value in files]}


client = TestClient(app)

# HTTPX drops empty filenames, so send the browser's multipart representation directly.
EMPTY_FILE_FORM = (
    b"--boundary\r\n"
    b'Content-Disposition: form-data; name="file"; filename=""\r\n'
    b"Content-Type: application/octet-stream\r\n\r\n"
    b"\r\n--boundary\r\n"
    b'Content-Disposition: form-data; name="files"; filename=""\r\n'
    b"Content-Type: application/octet-stream\r\n\r\n"
    b"\r\n--boundary--\r\n"
)


@pytest.mark.parametrize("path", ["/required-bytes", "/required-uploadfile"])
@pytest.mark.parametrize(
    "content",
    [
        pytest.param(b"", id="omitted"),
        pytest.param(EMPTY_FILE_FORM, id="no-selection"),
    ],
)
def test_missing_required_nullable_files(path, content):
    response = client.post(
        path,
        content=content,
        headers={"content-type": "multipart/form-data; boundary=boundary"},
    )
    assert response.status_code == 422
    assert [(error["type"], error["loc"]) for error in response.json()["detail"]] == [
        ("missing", ["body", "file"]),
        ("missing", ["body", "files"]),
    ]


@pytest.mark.parametrize("path", ["/optional-bytes", "/optional-uploadfile"])
@pytest.mark.parametrize(
    "content",
    [
        pytest.param(b"", id="omitted"),
        pytest.param(EMPTY_FILE_FORM, id="no-selection"),
    ],
)
def test_missing_optional_nullable_files(path, content):
    response = client.post(
        path,
        content=content,
        headers={"content-type": "multipart/form-data; boundary=boundary"},
    )
    assert response.status_code == 200
    assert response.json() == {"file": None, "files": None}


@pytest.mark.parametrize(
    "path",
    [
        "/required-bytes",
        "/required-uploadfile",
        "/optional-bytes",
        "/optional-uploadfile",
    ],
)
@pytest.mark.parametrize("content", [b"", b"hello"])
def test_named_file_is_supplied_even_when_empty(path, content):
    response = client.post(
        path,
        files=[
            ("file", ("empty.txt", content)),
            ("files", ("first.txt", content)),
            ("files", ("second.txt", content)),
        ],
    )
    assert response.status_code == 200
    assert response.json() == {
        "file": len(content),
        "files": [len(content), len(content)],
    }


@pytest.mark.parametrize(
    "content",
    [
        pytest.param(b"", id="omitted"),
        pytest.param(EMPTY_FILE_FORM, id="no-selection"),
    ],
)
def test_missing_files_use_bytes_defaults(content):
    response = client.post(
        "/bytes-defaults",
        content=content,
        headers={"content-type": "multipart/form-data; boundary=boundary"},
    )
    assert response.status_code == 200
    assert response.json() == {"file": 7, "files": [7]}


@pytest.mark.parametrize("content,expected", [(b"", 0), (b"hello", 5)])
def test_supplied_files_override_bytes_defaults(content, expected):
    response = client.post(
        "/bytes-defaults",
        files=[
            ("file", ("file.txt", content)),
            ("files", ("file.txt", content)),
        ],
    )
    assert response.status_code == 200
    assert response.json() == {"file": expected, "files": [expected]}


@pytest.mark.parametrize("path", ["/required-bytes", "/required-uploadfile"])
def test_file_without_a_name_is_supplied_when_it_has_content(path):
    response = client.post(
        path,
        content=(
            b"--boundary\r\n"
            b'Content-Disposition: form-data; name="file"; filename=""\r\n'
            b"Content-Type: application/octet-stream\r\n\r\n"
            b"hello\r\n--boundary\r\n"
            b'Content-Disposition: form-data; name="files"; filename=""\r\n'
            b"Content-Type: application/octet-stream\r\n\r\n"
            b"hello\r\n--boundary--\r\n"
        ),
        headers={"content-type": "multipart/form-data; boundary=boundary"},
    )
    assert response.status_code == 200
    assert response.json() == {"file": 5, "files": [5]}


@pytest.mark.parametrize("path", ["/required-bytes", "/required-uploadfile"])
def test_file_list_ignores_unselected_inputs(path):
    response = client.post(
        path,
        content=(
            b"--boundary\r\n"
            b'Content-Disposition: form-data; name="file"; filename="empty.txt"\r\n'
            b"Content-Type: application/octet-stream\r\n\r\n"
            b"\r\n--boundary\r\n"
            b'Content-Disposition: form-data; name="files"; filename="first.txt"\r\n'
            b"Content-Type: application/octet-stream\r\n\r\n"
            b"\r\n--boundary\r\n"
            b'Content-Disposition: form-data; name="files"; filename=""\r\n'
            b"Content-Type: application/octet-stream\r\n\r\n"
            b"\r\n--boundary\r\n"
            b'Content-Disposition: form-data; name="files"; filename="last.txt"\r\n'
            b"Content-Type: application/octet-stream\r\n\r\n"
            b"hello\r\n--boundary--\r\n"
        ),
        headers={"content-type": "multipart/form-data; boundary=boundary"},
    )
    assert response.status_code == 200
    assert response.json() == {"file": 0, "files": [0, 5]}


def test_multipart_text_items_in_bytes_list_are_preserved():
    response = client.post(
        "/required-bytes",
        files=[
            ("file", ("empty.txt", b"")),
            ("files", (None, "")),
            ("files", (None, "text")),
            ("files", ("selected.txt", b"hello")),
        ],
    )
    assert response.status_code == 200
    assert response.json() == {"file": 0, "files": [0, 4, 5]}


def test_unselected_files_in_form_model_use_defaults_and_remain_unset():
    app = FastAPI()

    class FileModel(BaseModel):
        file: UploadFile | None = None
        files: Annotated[list[UploadFile], Field(default_factory=list)]

    @app.post("/")
    def upload(params: Annotated[FileModel, Form()]):
        assert params.file is None
        assert params.files == []
        return params.model_dump(exclude_unset=True)

    client = TestClient(app)
    response = client.post(
        "/",
        content=EMPTY_FILE_FORM,
        headers={"content-type": "multipart/form-data; boundary=boundary"},
    )
    assert response.status_code == 200
    assert response.json() == {}


def test_required_non_nullable_files():
    app = FastAPI()

    @app.post("/")
    def upload(
        file: Annotated[UploadFile, File()], files: Annotated[list[bytes], File()]
    ):
        return {"file": file.size, "files": [len(value) for value in files]}

    client = TestClient(app)
    response = client.post(
        "/",
        content=EMPTY_FILE_FORM,
        headers={"content-type": "multipart/form-data; boundary=boundary"},
    )
    assert response.status_code == 422
    assert [(error["type"], error["loc"]) for error in response.json()["detail"]] == [
        ("missing", ["body", "file"]),
        ("missing", ["body", "files"]),
    ]

    response = client.post(
        "/",
        files=[("file", ("empty.txt", b"")), ("files", ("empty.txt", b""))],
    )
    assert response.status_code == 200
    assert response.json() == {"file": 0, "files": [0]}


@pytest.mark.parametrize("alias", ["primary", "secondary"])
def test_individual_file_alias_choices(alias: str):
    app = FastAPI()

    @app.post("/")
    def read_file(
        file: Annotated[
            bytes,
            File(alias="legacy", validation_alias=AliasChoices("primary", "secondary")),
        ],
    ):
        return file.decode()

    client = TestClient(app)
    response = client.post("/", files={alias: ("hello.txt", b"hello")})
    assert response.status_code == 200
    assert response.json() == "hello"


def test_file_alias_choices_errors_use_selected_aliases():
    app = FastAPI()

    @app.post("/")
    def read_files(
        file: Annotated[
            UploadFile,
            File(alias="legacy", validation_alias=AliasChoices("primary", "secondary")),
        ],
        files: Annotated[
            list[UploadFile],
            File(validation_alias=AliasChoices("primary-files", "secondary-files")),
        ],
    ):
        return {"file": file.filename, "files": [item.filename for item in files]}

    client = TestClient(app)
    response = client.post(
        "/",
        files=[
            ("secondary", ("one.txt", b"one")),
            ("secondary-files", ("two.txt", b"two")),
            ("secondary-files", ("three.txt", b"three")),
        ],
    )
    assert response.status_code == 200
    assert response.json() == {"file": "one.txt", "files": ["two.txt", "three.txt"]}

    response = client.post(
        "/",
        files=[
            ("secondary", (None, "invalid")),
            ("secondary-files", ("valid.txt", b"valid")),
            ("secondary-files", (None, "invalid")),
            ("legacy", ("ignored.txt", b"ignored")),
        ],
    )
    assert response.status_code == 422
    assert [(error["type"], error["loc"]) for error in response.json()["detail"]] == [
        ("value_error", ["body", "secondary"]),
        ("value_error", ["body", "secondary-files", 1]),
    ]

    response = client.post(
        "/",
        files=[
            ("primary", (None, "invalid")),
            ("secondary", ("valid.txt", b"valid")),
            ("primary-files", (None, "invalid")),
            ("secondary-files", ("valid.txt", b"valid")),
        ],
    )
    assert response.status_code == 422
    assert [(error["type"], error["loc"]) for error in response.json()["detail"]] == [
        ("value_error", ["body", "primary"]),
        ("value_error", ["body", "primary-files", 0]),
    ]

    response = client.post("/")
    assert response.status_code == 422
    assert [(error["type"], error["loc"]) for error in response.json()["detail"]] == [
        ("missing", ["body", "primary"]),
        ("missing", ["body", "primary-files"]),
    ]


def test_unselected_file_alias_choices_use_the_next_alias():
    app = FastAPI()

    @app.post("/")
    def read_file(
        file: Annotated[
            bytes,
            File(alias="legacy", validation_alias=AliasChoices("file", "selected")),
        ],
    ):
        return file.decode()

    client = TestClient(app)
    response = client.post(
        "/",
        content=(
            b"--boundary\r\n"
            b'Content-Disposition: form-data; name="file"; filename=""\r\n'
            b"Content-Type: application/octet-stream\r\n\r\n"
            b"\r\n--boundary\r\n"
            b'Content-Disposition: form-data; name="selected"; filename="hello.txt"\r\n'
            b"Content-Type: application/octet-stream\r\n\r\n"
            b"hello\r\n--boundary--\r\n"
        ),
        headers={"content-type": "multipart/form-data; boundary=boundary"},
    )
    assert response.status_code == 200
    assert response.json() == "hello"

    response = client.post(
        "/",
        content=EMPTY_FILE_FORM,
        headers={"content-type": "multipart/form-data; boundary=boundary"},
    )
    assert response.status_code == 422
    assert [(error["type"], error["loc"]) for error in response.json()["detail"]] == [
        ("missing", ["body", "file"]),
    ]


@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_model_files_can_share_an_unused_alias_choice():
    app = FastAPI()

    class FileModel(BaseModel):
        files: Annotated[
            list[UploadFile], Field(validation_alias=AliasChoices("files", "legacy"))
        ]
        file: Annotated[
            UploadFile, Field(validation_alias=AliasChoices("file", "legacy"))
        ]

    @app.post("/")
    def read_form(data: Annotated[FileModel, Form()]):
        return {
            "files": [file.filename for file in data.files],
            "file": data.file.filename,
        }

    client = TestClient(app)
    response = client.post(
        "/",
        files=[
            ("legacy", ("one.txt", b"one")),
            ("legacy", ("two.txt", b"two")),
            ("file", ("hello.txt", b"hello")),
        ],
    )
    assert response.status_code == 200
    assert response.json() == {"files": ["one.txt", "two.txt"], "file": "hello.txt"}


def test_openapi_schema():
    response = client.get("/openapi.json")
    assert response.status_code == 200, response.text
    assert response.json() == snapshot(
        {
            "openapi": "3.1.0",
            "info": {"title": "FastAPI", "version": "0.1.0"},
            "paths": {
                "/required-bytes": {
                    "post": {
                        "summary": "Read Required Bytes",
                        "operationId": "read_required_bytes_required_bytes_post",
                        "requestBody": {
                            "content": {
                                "multipart/form-data": {
                                    "schema": {
                                        "$ref": "#/components/schemas/Body_read_required_bytes_required_bytes_post"
                                    }
                                }
                            },
                            "required": True,
                        },
                        "responses": {
                            "200": {
                                "description": "Successful Response",
                                "content": {"application/json": {"schema": {}}},
                            },
                            "422": {
                                "description": "Validation Error",
                                "content": {
                                    "application/json": {
                                        "schema": {
                                            "$ref": "#/components/schemas/HTTPValidationError"
                                        }
                                    }
                                },
                            },
                        },
                    }
                },
                "/required-uploadfile": {
                    "post": {
                        "summary": "Read Required Uploadfile",
                        "operationId": "read_required_uploadfile_required_uploadfile_post",
                        "requestBody": {
                            "content": {
                                "multipart/form-data": {
                                    "schema": {
                                        "$ref": "#/components/schemas/Body_read_required_uploadfile_required_uploadfile_post"
                                    }
                                }
                            },
                            "required": True,
                        },
                        "responses": {
                            "200": {
                                "description": "Successful Response",
                                "content": {"application/json": {"schema": {}}},
                            },
                            "422": {
                                "description": "Validation Error",
                                "content": {
                                    "application/json": {
                                        "schema": {
                                            "$ref": "#/components/schemas/HTTPValidationError"
                                        }
                                    }
                                },
                            },
                        },
                    }
                },
                "/optional-bytes": {
                    "post": {
                        "summary": "Read Optional Bytes",
                        "operationId": "read_optional_bytes_optional_bytes_post",
                        "requestBody": {
                            "content": {
                                "multipart/form-data": {
                                    "schema": {
                                        "$ref": "#/components/schemas/Body_read_optional_bytes_optional_bytes_post"
                                    }
                                }
                            }
                        },
                        "responses": {
                            "200": {
                                "description": "Successful Response",
                                "content": {"application/json": {"schema": {}}},
                            },
                            "422": {
                                "description": "Validation Error",
                                "content": {
                                    "application/json": {
                                        "schema": {
                                            "$ref": "#/components/schemas/HTTPValidationError"
                                        }
                                    }
                                },
                            },
                        },
                    }
                },
                "/optional-uploadfile": {
                    "post": {
                        "summary": "Read Optional Uploadfile",
                        "operationId": "read_optional_uploadfile_optional_uploadfile_post",
                        "requestBody": {
                            "content": {
                                "multipart/form-data": {
                                    "schema": {
                                        "$ref": "#/components/schemas/Body_read_optional_uploadfile_optional_uploadfile_post"
                                    }
                                }
                            }
                        },
                        "responses": {
                            "200": {
                                "description": "Successful Response",
                                "content": {"application/json": {"schema": {}}},
                            },
                            "422": {
                                "description": "Validation Error",
                                "content": {
                                    "application/json": {
                                        "schema": {
                                            "$ref": "#/components/schemas/HTTPValidationError"
                                        }
                                    }
                                },
                            },
                        },
                    }
                },
                "/bytes-defaults": {
                    "post": {
                        "summary": "Read Bytes Defaults",
                        "operationId": "read_bytes_defaults_bytes_defaults_post",
                        "requestBody": {
                            "content": {
                                "multipart/form-data": {
                                    "schema": {
                                        "$ref": "#/components/schemas/Body_read_bytes_defaults_bytes_defaults_post"
                                    }
                                }
                            }
                        },
                        "responses": {
                            "200": {
                                "description": "Successful Response",
                                "content": {"application/json": {"schema": {}}},
                            },
                            "422": {
                                "description": "Validation Error",
                                "content": {
                                    "application/json": {
                                        "schema": {
                                            "$ref": "#/components/schemas/HTTPValidationError"
                                        }
                                    }
                                },
                            },
                        },
                    }
                },
            },
            "components": {
                "schemas": {
                    "Body_read_bytes_defaults_bytes_defaults_post": {
                        "properties": {
                            "file": {
                                "anyOf": [
                                    {
                                        "type": "string",
                                        "contentMediaType": "application/octet-stream",
                                    },
                                    {"type": "null"},
                                ],
                                "title": "File",
                                "default": "default",
                            },
                            "files": {
                                "anyOf": [
                                    {
                                        "items": {
                                            "type": "string",
                                            "contentMediaType": "application/octet-stream",
                                        },
                                        "type": "array",
                                    },
                                    {"type": "null"},
                                ],
                                "title": "Files",
                            },
                        },
                        "type": "object",
                        "title": "Body_read_bytes_defaults_bytes_defaults_post",
                    },
                    "Body_read_optional_bytes_optional_bytes_post": {
                        "properties": {
                            "file": {
                                "anyOf": [
                                    {
                                        "type": "string",
                                        "contentMediaType": "application/octet-stream",
                                    },
                                    {"type": "null"},
                                ],
                                "title": "File",
                            },
                            "files": {
                                "anyOf": [
                                    {
                                        "items": {
                                            "type": "string",
                                            "contentMediaType": "application/octet-stream",
                                        },
                                        "type": "array",
                                    },
                                    {"type": "null"},
                                ],
                                "title": "Files",
                            },
                        },
                        "type": "object",
                        "title": "Body_read_optional_bytes_optional_bytes_post",
                    },
                    "Body_read_optional_uploadfile_optional_uploadfile_post": {
                        "properties": {
                            "file": {
                                "anyOf": [
                                    {
                                        "type": "string",
                                        "contentMediaType": "application/octet-stream",
                                    },
                                    {"type": "null"},
                                ],
                                "title": "File",
                            },
                            "files": {
                                "anyOf": [
                                    {
                                        "items": {
                                            "type": "string",
                                            "contentMediaType": "application/octet-stream",
                                        },
                                        "type": "array",
                                    },
                                    {"type": "null"},
                                ],
                                "title": "Files",
                            },
                        },
                        "type": "object",
                        "title": "Body_read_optional_uploadfile_optional_uploadfile_post",
                    },
                    "Body_read_required_bytes_required_bytes_post": {
                        "properties": {
                            "file": {
                                "anyOf": [
                                    {
                                        "type": "string",
                                        "contentMediaType": "application/octet-stream",
                                    },
                                    {"type": "null"},
                                ],
                                "title": "File",
                            },
                            "files": {
                                "anyOf": [
                                    {
                                        "items": {
                                            "type": "string",
                                            "contentMediaType": "application/octet-stream",
                                        },
                                        "type": "array",
                                    },
                                    {"type": "null"},
                                ],
                                "title": "Files",
                            },
                        },
                        "type": "object",
                        "required": ["file", "files"],
                        "title": "Body_read_required_bytes_required_bytes_post",
                    },
                    "Body_read_required_uploadfile_required_uploadfile_post": {
                        "properties": {
                            "file": {
                                "anyOf": [
                                    {
                                        "type": "string",
                                        "contentMediaType": "application/octet-stream",
                                    },
                                    {"type": "null"},
                                ],
                                "title": "File",
                            },
                            "files": {
                                "anyOf": [
                                    {
                                        "items": {
                                            "type": "string",
                                            "contentMediaType": "application/octet-stream",
                                        },
                                        "type": "array",
                                    },
                                    {"type": "null"},
                                ],
                                "title": "Files",
                            },
                        },
                        "type": "object",
                        "required": ["file", "files"],
                        "title": "Body_read_required_uploadfile_required_uploadfile_post",
                    },
                    "HTTPValidationError": {
                        "properties": {
                            "detail": {
                                "items": {
                                    "$ref": "#/components/schemas/ValidationError"
                                },
                                "type": "array",
                                "title": "Detail",
                            }
                        },
                        "type": "object",
                        "title": "HTTPValidationError",
                    },
                    "ValidationError": {
                        "properties": {
                            "loc": {
                                "items": {
                                    "anyOf": [{"type": "string"}, {"type": "integer"}]
                                },
                                "type": "array",
                                "title": "Location",
                            },
                            "msg": {"type": "string", "title": "Message"},
                            "type": {"type": "string", "title": "Error Type"},
                            "input": {"title": "Input"},
                            "ctx": {"type": "object", "title": "Context"},
                        },
                        "type": "object",
                        "required": ["loc", "msg", "type"],
                        "title": "ValidationError",
                    },
                }
            },
        }
    )