# `UploadFile` class

You can define *path operation function* parameters to be of the type `UploadFile` to receive files from the request.

You can import it directly from `fastapi`:

```python
from fastapi import UploadFile
```

::: fastapi.UploadFile
    options:
        members:
            - file
            - filename
            - size
            - headers
            - content_type
            - read

@app.post("/optional-list-uploadfile")
async def read_optional_list_uploadfile(
    p: Annotated[Optional[list[UploadFile]], File()] = None,
):
    return {"file_size": [file.size for file in p] if p else None}


@pytest.mark.parametrize(
    "path",
    [
        "/optional-list-bytes",
        "/optional-list-uploadfile",
    ],
)
def test_optional_list_schema(path: str):

Aber es gibt viele Fälle, in denen Sie davon profitieren, `UploadFile` zu verwenden.

## Datei-Parameter mit `UploadFile` { #file-parameters-with-uploadfile }

Definieren Sie einen Datei-Parameter mit dem Typ `UploadFile`:

{* ../../docs_src/request_files/tutorial001_an_py39.py hl[14] *}

`UploadFile` zu verwenden, hat mehrere Vorzüge gegenüber `bytes`:

Але в деяких випадках Вам може знадобитися `UploadFile`.

## Параметри файлу з `UploadFile`

Визначте параметр файлу з типом `UploadFile`:

{* ../../docs_src/request_files/tutorial001_an_py39.py hl[14] *}

Використання `UploadFile` має кілька переваг перед `bytes`:

* Вам не потрібно використовувати `File()` у значенні за замовчуванням параметра.

@app.post("/required-uploadfile", operation_id="required_uploadfile")
async def read_required_uploadfile(p: Annotated[UploadFile, File()]):
    return {"file_size": p.size}


@pytest.mark.parametrize(
    "path",
    [
        "/required-bytes",
        "/required-uploadfile",
    ],
)
def test_required_schema(path: str):
    openapi = app.openapi()
    body_model_name = get_body_model_name(openapi, path)

Pero hay varios casos en los que podrías beneficiarte de usar `UploadFile`.

## Parámetros de Archivo con `UploadFile` { #file-parameters-with-uploadfile }

Define un parámetro de archivo con un tipo de `UploadFile`:

{* ../../docs_src/request_files/tutorial001_an_py39.py hl[14] *}

Usar `UploadFile` tiene varias ventajas sobre `bytes`:

///

文件作为「表单数据」上传。

如果把*路径操作函数*参数的类型声明为 `bytes`，**FastAPI** 将以 `bytes` 形式读取和接收文件内容。

这种方式把文件的所有内容都存储在内存里，适用于小型文件。

不过，很多情况下，`UploadFile` 更好用。

## 含 `UploadFile` 的文件参数

定义文件参数时使用 `UploadFile`：

{* ../../docs_src/request_files/tutorial001.py hl[12] *}

`UploadFile` 与 `bytes` 相比有更多优势：

* 使用 `spooled` 文件：
    * 存储在内存的文件超出最大上限时，FastAPI 会把文件存入磁盘；
* 这种方式更适于处理图像、视频、二进制文件等大型文件，好处是不会占用所有内存；
* 可获取上传文件的元数据；

    ```python
    from typing import Annotated

    from fastapi import FastAPI, File, UploadFile

    app = FastAPI()


    @app.post("/files/")
    async def create_file(file: Annotated[bytes, File()]):
        return {"file_size": len(file)}


    @app.post("/uploadfile/")
    async def create_upload_file(file: UploadFile):
        return {"filename": file.filename}
    ```
    """

    file: Annotated[

    app = FastAPI()

    testing_file_store: list[UploadFile] = []

    @app.post("/uploadfile/")
    def create_upload_file(file: UploadFile):
        testing_file_store.append(file)
        return {"filename": file.filename}

    client = TestClient(app)
    with path.open("rb") as file:
        response = client.post("/uploadfile/", files={"file": file})
    assert response.status_code == 200, response.text

Однако возможны случаи, когда использование `UploadFile` может оказаться полезным.

## Параметры файла с `UploadFile` { #file-parameters-with-uploadfile }

Определите параметр файла с типом `UploadFile`:

{* ../../docs_src/request_files/tutorial001_an_py39.py hl[14] *}

Использование `UploadFile` имеет ряд преимуществ перед `bytes`: