🔖 Release 0.15.0, multi-file uploads

✨ Add support for multi-file uploads (#158 )
📝 Use same link in benchmarks as in index
2025-12-27 16:21:06 -05:00 · 2019-04-14 22:14:20 +04:00 · 2019-04-14 22:12:14 +04:00 · 2019-04-12 22:56:09 +04:00 · 2019-04-12 22:43:21 +04:00
13 changed files with 381 additions and 20 deletions
--- a/docs/benchmarks.md
+++ b/docs/benchmarks.md
@@ -1,4 +1,4 @@
-Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as <a href="https://www.techempower.com/benchmarks/#section=test&runid=a979de55-980d-4721-a46f-77298b3f3923&hw=ph&test=fortune&l=zijzen-7" target="_blank">one of the fastest Python frameworks available</a>, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*)
+Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as <a href="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7" target="_blank">one of the fastest Python frameworks available</a>, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*)

 But when checking benchmarks and comparisons you should have the following in mind.

--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -1,5 +1,11 @@
 ## Next release

+## 0.15.0
+
+* Add support for multiple file uploads (as a single form field). New docs at: <a href="https://fastapi.tiangolo.com/tutorial/request-files/#multiple-file-uploads" target="_blank">Multiple file uploads</a>. PR <a href="https://github.com/tiangolo/fastapi/pull/158" target="_blank">#158</a>.
+
+* Add docs for: <a href="https://fastapi.tiangolo.com/tutorial/additional-status-codes/" target="_blank">Additional Status Codes</a>. PR <a href="https://github.com/tiangolo/fastapi/pull/156" target="_blank">#156</a>.
+
 ## 0.14.0

 * Improve automatically generated names of path operations in OpenAPI (in API docs). A function `read_items` instead of having a generated name "Read Items Get" will have "Read Items". PR <a href="https://github.com/tiangolo/fastapi/pull/155" target="_blank">#155</a>.
--- a/docs/src/additional_status_codes/tutorial001.py
+++ b/docs/src/additional_status_codes/tutorial001.py
@@ -0,0 +1,20 @@
+from fastapi import Body, FastAPI
+from starlette.responses import JSONResponse
+from starlette.status import HTTP_201_CREATED
+
+app = FastAPI()
+
+items = {"foo": {"name": "Fighters", "size": 6}, "bar": {"name": "Tenders", "size": 3}}
+
+
+@app.put("/items/{item_id}")
+async def upsert_item(item_id: str, name: str = Body(None), size: int = Body(None)):
+    if item_id in items:
+        item = items[item_id]
+        item["name"] = name
+        item["size"] = size
+        return item
+    else:
+        item = {"name": name, "size": size}
+        items[item_id] = item
+        return JSONResponse(status_code=HTTP_201_CREATED, content=item)
--- a/docs/src/request_files/tutorial002.py
+++ b/docs/src/request_files/tutorial002.py
@@ -0,0 +1,33 @@
+from typing import List
+
+from fastapi import FastAPI, File, UploadFile
+from starlette.responses import HTMLResponse
+
+app = FastAPI()
+
+
+@app.post("/files/")
+async def create_files(files: List[bytes] = File(...)):
+    return {"file_sizes": [len(file) for file in files]}
+
+
+@app.post("/uploadfiles/")
+async def create_upload_files(files: List[UploadFile] = File(...)):
+    return {"filenames": [file.filename for file in files]}
+
+
+@app.get("/")
+async def main():
+    content = """
+<body>
+<form action="/files/" enctype="multipart/form-data" method="post">
+<input name="files" type="file" multiple>
+<input type="submit">
+</form>
+<form action="/uploadfiles/" enctype="multipart/form-data" method="post">
+<input name="files" type="file" multiple>
+<input type="submit">
+</form>
+</body>
+    """
+    return HTMLResponse(content=content)
--- a/docs/tutorial/additional-status-codes.md
+++ b/docs/tutorial/additional-status-codes.md
@@ -0,0 +1,30 @@
+By default, **FastAPI** will return the responses using Starlette's `JSONResponse`, putting the content you return from your *path operation* inside of that `JSONResponse`.
+
+It will use the default status code or the one you set in your *path operation*.
+
+## Additional status codes
+
+If you want to return additional status codes apart from the main one, you can do that by returning a `Response` directly, like a `JSONResponse`, and set the additional status code directly.
+
+For example, let's say that you want to have a *path operation* that allows to update items, and returns HTTP status codes of 200 "OK" when successful.
+
+But you also want it to accept new items. And when the items didn't exist before, it creates them, and returns an HTTP status code of 201 "Created".
+
+To achieve that, import `JSONResponse`, and return your content there directly, setting the `status_code` that you want:
+
+```Python hl_lines="2 20"
+{!./src/additional_status_codes/tutorial001.py!}
+```
+
+!!! warning
+    When you return a `Response` directly, like in the example above, it will be returned directly.
+
+    It won't be serialized with a model, etc.
+    
+    Make sure it has the data you want it to have, and that the values are valid JSON (if you are using `JSONResponse`).
+
+## OpenAPI and API docs
+
+If you return additional status codes and responses directly, they won't be included in the OpenAPI schema (the API docs), because FastAPI doesn't have a way to know before hand what you are going to return.
+
+But you can document that in your code, using: <a href="https://fastapi.tiangolo.com/tutorial/additional-responses/" target="_blank">Additional Responses</a>.
--- a/docs/tutorial/request-files.md
+++ b/docs/tutorial/request-files.md
@@ -43,7 +43,7 @@ Using `UploadFile` has several advantages over `bytes`:

 * It uses a "spooled" file:
    * A file stored in memory up to a maximum size limit, and after passing this limit it will be stored in disk.
-* This means that it will work well for large files like images, videos, large binaries, etc. All without consuming all the memory.
+* This means that it will work well for large files like images, videos, large binaries, etc. without consuming all the memory.
 * You can get metadata from the uploaded file.
 * It has a <a href="https://docs.python.org/3/glossary.html#term-file-like-object" target="_blank">file-like</a> `async` interface.
 * It exposes an actual Python <a href="https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile" target="_blank">`SpooledTemporaryFile`</a> object that you can pass directly to other libraries that expect a file-like object.
@@ -107,6 +107,20 @@ The way HTML forms (`<form></form>`) sends the data to the server normally uses

    This is not a limitation of **FastAPI**, it's part of the HTTP protocol.

+## Multiple file uploads
+
+It's possible to upload several files at the same time.
+
+They would be associated to the same "form field" sent using "form data".
+
+To use that, declare a `List` of `bytes` or `UploadFile`:
+
+```Python hl_lines="10 15"
+{!./src/request_files/tutorial002.py!}
+```
+
+You will receive, as declared, a `list` of `bytes` or `UploadFile`s.
+
 ## Recap

 Use `File` to declare files to be uploaded as input parameters (as form data).
--- a/fastapi/init.py
+++ b/fastapi/init.py
@@ -1,6 +1,6 @@
 """FastAPI framework, high performance, easy to learn, fast to code, ready for production"""

-__version__ = "0.14.0"
+__version__ = "0.15.0"

 from starlette.background import BackgroundTasks

--- a/fastapi/dependencies/utils.py
+++ b/fastapi/dependencies/utils.py
@@ -31,8 +31,8 @@ from pydantic.schema import get_annotation_from_schema
 from pydantic.utils import lenient_issubclass
 from starlette.background import BackgroundTasks
 from starlette.concurrency import run_in_threadpool
-from starlette.datastructures import UploadFile
-from starlette.requests import Headers, QueryParams, Request
+from starlette.datastructures import FormData, Headers, QueryParams, UploadFile
+from starlette.requests import Request

 param_supported_types = (
    str,
@@ -47,6 +47,10 @@ param_supported_types = (
    Decimal,
 )

+sequence_shapes = {Shape.LIST, Shape.SET, Shape.TUPLE}
+sequence_types = (list, set, tuple)
+sequence_shape_to_type = {Shape.LIST: list, Shape.SET: set, Shape.TUPLE: tuple}
+

 def get_sub_dependant(
    *, param: inspect.Parameter, path: str, security_scopes: List[str] = None
@@ -318,7 +322,7 @@ def request_params_to_args(
    values = {}
    errors = []
    for field in required_params:
-        if field.shape in {Shape.LIST, Shape.SET, Shape.TUPLE} and isinstance(
+        if field.shape in sequence_shapes and isinstance(
            received_params, (QueryParams, Headers)
        ):
            value = received_params.getlist(field.alias)
@@ -358,11 +362,20 @@ async def request_body_to_args(
        embed = getattr(field.schema, "embed", None)
        if len(required_params) == 1 and not embed:
            received_body = {field.alias: received_body}
-        elif received_body is None:
-            received_body = {}
        for field in required_params:
-            value = received_body.get(field.alias)
-            if value is None or (isinstance(field.schema, params.Form) and value == ""):
+            if field.shape in sequence_shapes and isinstance(received_body, FormData):
+                value = received_body.getlist(field.alias)
+            else:
+                value = received_body.get(field.alias)
+            if (
+                value is None
+                or (isinstance(field.schema, params.Form) and value == "")
+                or (
+                    isinstance(field.schema, params.Form)
+                    and field.shape in sequence_shapes
+                    and len(value) == 0
+                )
+            ):
                if field.required:
                    errors.append(
                        ErrorWrapper(
@@ -380,6 +393,15 @@ async def request_body_to_args(
                and isinstance(value, UploadFile)
            ):
                value = await value.read()
+            elif (
+                field.shape in sequence_shapes
+                and isinstance(field.schema, params.File)
+                and lenient_issubclass(field.type_, bytes)
+                and isinstance(value, sequence_types)
+            ):
+                awaitables = [sub_value.read() for sub_value in value]
+                contents = await asyncio.gather(*awaitables)
+                value = sequence_shape_to_type[field.shape](contents)
            v_, errors_ = field.validate(value, values, loc=("body", field.alias))
            if isinstance(errors_, ErrorWrapper):
                errors.append(errors_)
@@ -391,10 +413,14 @@ async def request_body_to_args(


 def get_schema_compatible_field(*, field: Field) -> Field:
+    out_field = field
    if lenient_issubclass(field.type_, UploadFile):
-        return Field(
+        use_type: type = bytes
+        if field.shape in sequence_shapes:
+            use_type = List[bytes]
+        out_field = Field(
            name=field.name,
-            type_=bytes,
+            type_=use_type,
            class_validators=field.class_validators,
            model_config=field.model_config,
            default=field.default,
@@ -402,10 +428,10 @@ def get_schema_compatible_field(*, field: Field) -> Field:
            alias=field.alias,
            schema=field.schema,
        )
-    return field
+    return out_field


-def get_body_field(*, dependant: Dependant, name: str) -> Field:
+def get_body_field(*, dependant: Dependant, name: str) -> Optional[Field]:
    flat_dependant = get_flat_dependant(dependant)
    if not flat_dependant.body_params:
        return None
--- a/fastapi/routing.py
+++ b/fastapi/routing.py
@@ -53,12 +53,7 @@ def get_app(
            body = None
            if body_field:
                if is_body_form:
-                    raw_body = await request.form()
-                    form_fields = {}
-                    for field, value in raw_body.items():
-                        form_fields[field] = value
-                    if form_fields:
-                        body = form_fields
+                    body = await request.form()
                else:
                    body_bytes = await request.body()
                    if body_bytes:
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -43,6 +43,7 @@ nav:
        - Handling Errors: 'tutorial/handling-errors.md'
        - Path Operation Configuration: 'tutorial/path-operation-configuration.md'
        - Path Operation Advanced Configuration: 'tutorial/path-operation-advanced-configuration.md'
+        - Additional Status Codes: 'tutorial/additional-status-codes.md'
        - Custom Response: 'tutorial/custom-response.md'
        - Additional Responses: 'tutorial/additional-responses.md'
        - Dependencies:
--- a/tests/test_tutorial/test_additional_status_codes/init.py
+++ b/tests/test_tutorial/test_additional_status_codes/init.py
--- a/tests/test_tutorial/test_additional_status_codes/test_tutorial001.py
+++ b/tests/test_tutorial/test_additional_status_codes/test_tutorial001.py
@@ -0,0 +1,17 @@
+from starlette.testclient import TestClient
+
+from additional_status_codes.tutorial001 import app
+
+client = TestClient(app)
+
+
+def test_update():
+    response = client.put("/items/foo", json={"name": "Wrestlers"})
+    assert response.status_code == 200
+    assert response.json() == {"name": "Wrestlers", "size": None}
+
+
+def test_create():
+    response = client.put("/items/red", json={"name": "Chillies"})
+    assert response.status_code == 201
+    assert response.json() == {"name": "Chillies", "size": None}
--- a/tests/test_tutorial/test_request_files/test_tutorial002.py
+++ b/tests/test_tutorial/test_request_files/test_tutorial002.py
@@ -0,0 +1,219 @@
+import os
+
+from starlette.testclient import TestClient
+
+from request_files.tutorial002 import app
+
+client = TestClient(app)
+
+openapi_schema = {
+    "openapi": "3.0.2",
+    "info": {"title": "Fast API", "version": "0.1.0"},
+    "paths": {
+        "/files/": {
+            "post": {
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    },
+                    "422": {
+                        "description": "Validation Error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HTTPValidationError"
+                                }
+                            }
+                        },
+                    },
+                },
+                "summary": "Create Files",
+                "operationId": "create_files_files__post",
+                "requestBody": {
+                    "content": {
+                        "multipart/form-data": {
+                            "schema": {"$ref": "#/components/schemas/Body_create_files"}
+                        }
+                    },
+                    "required": True,
+                },
+            }
+        },
+        "/uploadfiles/": {
+            "post": {
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    },
+                    "422": {
+                        "description": "Validation Error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HTTPValidationError"
+                                }
+                            }
+                        },
+                    },
+                },
+                "summary": "Create Upload Files",
+                "operationId": "create_upload_files_uploadfiles__post",
+                "requestBody": {
+                    "content": {
+                        "multipart/form-data": {
+                            "schema": {
+                                "$ref": "#/components/schemas/Body_create_upload_files"
+                            }
+                        }
+                    },
+                    "required": True,
+                },
+            }
+        },
+        "/": {
+            "get": {
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    }
+                },
+                "summary": "Main",
+                "operationId": "main__get",
+            }
+        },
+    },
+    "components": {
+        "schemas": {
+            "Body_create_files": {
+                "title": "Body_create_files",
+                "required": ["files"],
+                "type": "object",
+                "properties": {
+                    "files": {
+                        "title": "Files",
+                        "type": "array",
+                        "items": {"type": "string", "format": "binary"},
+                    }
+                },
+            },
+            "Body_create_upload_files": {
+                "title": "Body_create_upload_files",
+                "required": ["files"],
+                "type": "object",
+                "properties": {
+                    "files": {
+                        "title": "Files",
+                        "type": "array",
+                        "items": {"type": "string", "format": "binary"},
+                    }
+                },
+            },
+            "ValidationError": {
+                "title": "ValidationError",
+                "required": ["loc", "msg", "type"],
+                "type": "object",
+                "properties": {
+                    "loc": {
+                        "title": "Location",
+                        "type": "array",
+                        "items": {"type": "string"},
+                    },
+                    "msg": {"title": "Message", "type": "string"},
+                    "type": {"title": "Error Type", "type": "string"},
+                },
+            },
+            "HTTPValidationError": {
+                "title": "HTTPValidationError",
+                "type": "object",
+                "properties": {
+                    "detail": {
+                        "title": "Detail",
+                        "type": "array",
+                        "items": {"$ref": "#/components/schemas/ValidationError"},
+                    }
+                },
+            },
+        }
+    },
+}
+
+
+def test_openapi_schema():
+    response = client.get("/openapi.json")
+    assert response.status_code == 200
+    assert response.json() == openapi_schema
+
+
+file_required = {
+    "detail": [
+        {
+            "loc": ["body", "files"],
+            "msg": "field required",
+            "type": "value_error.missing",
+        }
+    ]
+}
+
+
+def test_post_form_no_body():
+    response = client.post("/files/")
+    assert response.status_code == 422
+    assert response.json() == file_required
+
+
+def test_post_body_json():
+    response = client.post("/files/", json={"file": "Foo"})
+    print(response)
+    print(response.content)
+    assert response.status_code == 422
+    assert response.json() == file_required
+
+
+def test_post_files(tmpdir):
+    path = os.path.join(tmpdir, "test.txt")
+    with open(path, "wb") as file:
+        file.write(b"<file content>")
+    path2 = os.path.join(tmpdir, "test2.txt")
+    with open(path2, "wb") as file:
+        file.write(b"<file content2>")
+
+    client = TestClient(app)
+    response = client.post(
+        "/files/",
+        files=(
+            ("files", ("test.txt", open(path, "rb"))),
+            ("files", ("test2.txt", open(path2, "rb"))),
+        ),
+    )
+    assert response.status_code == 200
+    assert response.json() == {"file_sizes": [14, 15]}
+
+
+def test_post_upload_file(tmpdir):
+    path = os.path.join(tmpdir, "test.txt")
+    with open(path, "wb") as file:
+        file.write(b"<file content>")
+    path2 = os.path.join(tmpdir, "test2.txt")
+    with open(path2, "wb") as file:
+        file.write(b"<file content2>")
+
+    client = TestClient(app)
+    response = client.post(
+        "/uploadfiles/",
+        files=(
+            ("files", ("test.txt", open(path, "rb"))),
+            ("files", ("test2.txt", open(path2, "rb"))),
+        ),
+    )
+    assert response.status_code == 200
+    assert response.json() == {"filenames": ["test.txt", "test2.txt"]}
+
+
+def test_get_root():
+    client = TestClient(app)
+    response = client.get("/")
+    assert response.status_code == 200
+    assert b"<form" in response.content
Author	SHA1	Message	Date
Sebastián Ramírez	4c3cf31730	🔖 Release 0.15.0, multi-file uploads	2019-04-14 22:14:20 +04:00
Sebastián Ramírez	aad6b123f7	✨ Add support for multi-file uploads (#158 )	2019-04-14 22:12:14 +04:00
Sebastián Ramírez	e40e87c662	📝 Use same link in benchmarks as in index	2019-04-12 22:56:09 +04:00
Sebastián Ramírez	84de980977	✨ Add docs about responses with additional status codes (#156 ) * ✨ Add docs about responses with additional status codes * 📝 Update docs, link to documenting additional responses	2019-04-12 22:43:21 +04:00