:memo: Docs for Form and File parameters

diff --git a/docs/tutorial/form-data.md b/docs/tutorial/form-data.md
deleted file mode 100644 (file)
index dc26cf9..0000000
--- a/docs/tutorial/form-data.md
+++ /dev/null
@@ -1,40 +0,0 @@
-When you need to receive form data instead of JSON, you can use `Form`.
-
-## Import Form
-
-Import `Form` from `fastapi`:
-
-```Python hl_lines="1"
-{!./tutorial/src/form-data/tutorial001.py!}
-```
-
-## Define Form parameters
-
-Create form parameters the same way you would for `Body`:
-
-```Python hl_lines="7"
-{!./tutorial/src/form-data/tutorial001.py!}
-```
-
-For example, for one of the ways the OAuth2 specification can be used (called "password flow") it is required to send a `username` and `password` fields as form data.
-
-The <abbr title="specification">spec</abbr> requires the fields to be specifically named `username` and `password`, and to be sent as form data, not JSON.
-
-With `Form` you can declare the same metadata and validation as with `Body` (and `Query`, `Path`, `Cookie`).
-
-!!! info
-    `Form` is a class that inherits directly from `Body`.
-
-!!! info
-    To declare form bodies, you need to use `Form`, because otherwise the parameters would be interpreted as query parameteres or body (JSON) parameters.
-
-## "Form Data"? 
-
-"Form data" is the way HTML forms (`<form></form>`) send the data to the server.
-
-!!! note "Technical Details"
-    Data from forms is normally encoded using the "media type" `application/x-www-form-urlencoded`. To read more about it head to the <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST" target="_blank"><abbr title="Mozilla Developer Network">MDN</abbr> web docs for <code>POST</code></a>.
-
-## Recap
-
-Use `Form` to declare form data input parameters.

diff --git a/docs/tutorial/request-files.md b/docs/tutorial/request-files.md
new file mode 100644 (file)
index 0000000..f1f8da6
--- /dev/null
+++ b/docs/tutorial/request-files.md
@@ -0,0 +1,48 @@
+You can define files to be uploaded by the client using `File`.
+
+## Import `File`
+
+Import `File` from `fastapi`:
+
+```Python hl_lines="1"
+{!./tutorial/src/request-files/tutorial001.py!}
+```
+
+## Define `File` parameters
+
+Create file parameters the same way you would for `Body` or `Form`:
+
+```Python hl_lines="7"
+{!./tutorial/src/request-files/tutorial001.py!}
+```
+
+The files will be uploaded as form data and you will receive the contents as `bytes`.
+
+!!! info
+    `File` is a class that inherits directly from `Form`.
+
+!!! info
+    To declare File bodies, you need to use `File`, because otherwise the parameters would be interpreted as query parameteres or body (JSON) parameters.
+
+## "Form Data"? 
+
+The way HTML forms (`<form></form>`) sends the data to the server normally uses a "special" encoding for that data, it's different from JSON.
+
+**FastAPI** will make sure to read that data from the right place instead of JSON.
+
+!!! note "Technical Details"
+    Data from forms is normally encoded using the "media type" `application/x-www-form-urlencoded` when it doesn't include files.
+
+    But when the form includes files, it is encoded as `multipart/form-data`. If you use `File`, **FastAPI** will know it has to get the files from the correct part of the body.
+    
+    If you want to read more about these encondings and form fields, head to the <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST" target="_blank"><abbr title="Mozilla Developer Network">MDN</abbr> web docs for <code>POST</code></a>.
+
+
+!!! warning
+    You can declare multiple `File` and `Form` parameters in an endpoint, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `multipart/form-data` instead of `application/json`.
+
+    This is not a limitation of **FastAPI**, it's part of the HTTP protocol.
+
+## Recap
+
+Use `File` to declare files to be uploaded as input parameters (as form data).

diff --git a/docs/tutorial/request-forms-and-files.md b/docs/tutorial/request-forms-and-files.md
new file mode 100644 (file)
index 0000000..87d58dc
--- /dev/null
+++ b/docs/tutorial/request-forms-and-files.md
@@ -0,0 +1,26 @@
+You can define files and form fields at the same time using `File` and `Form`.
+
+## Import `File` and `Form`
+
+```Python hl_lines="1"
+{!./tutorial/src/request-forms-and-files/tutorial001.py!}
+```
+
+## Define `File` and `Form` parameters
+
+Create file and form parameters the same way you would for `Body` or `Query`:
+
+```Python hl_lines="7"
+{!./tutorial/src/request-forms-and-files/tutorial001.py!}
+```
+
+The files and form fields will be uploaded as form data and you will receive the files and form fields.
+
+!!! warning
+    You can declare multiple `File` and `Form` parameters in an endpoint, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `multipart/form-data` instead of `application/json`.
+
+    This is not a limitation of **FastAPI**, it's part of the HTTP protocol.
+
+## Recap
+
+Use `File` and `Form` together when you need to receive data and files in the same request.

diff --git a/docs/tutorial/request-forms.md b/docs/tutorial/request-forms.md
new file mode 100644 (file)
index 0000000..5296164
--- /dev/null
+++ b/docs/tutorial/request-forms.md
@@ -0,0 +1,52 @@
+When you need to receive form fields instead of JSON, you can use `Form`.
+
+## Import `Form`
+
+Import `Form` from `fastapi`:
+
+```Python hl_lines="1"
+{!./tutorial/src/request-forms/tutorial001.py!}
+```
+
+## Define `Form` parameters
+
+Create form parameters the same way you would for `Body` or `Query`:
+
+```Python hl_lines="7"
+{!./tutorial/src/request-forms/tutorial001.py!}
+```
+
+For example, in one of the ways the OAuth2 specification can be used (called "password flow") it is required to send a `username` and `password` as form fields.
+
+The <abbr title="specification">spec</abbr> requires the fields to be exactly named `username` and `password`, and to be sent as form fields, not JSON.
+
+With `Form` you can declare the same metadata and validation as with `Body` (and `Query`, `Path`, `Cookie`).
+
+!!! info
+    `Form` is a class that inherits directly from `Body`.
+
+!!! info
+    To declare form bodies, you need to use `Form` explicitly, because without it the parameters would be interpreted as query parameteres or body (JSON) parameters.
+
+## "Form Fields"? 
+
+The way HTML forms (`<form></form>`) sends the data to the server normally uses a "special" encoding for that data, it's different from JSON.
+
+**FastAPI** will make sure to read that data from the right place instead of JSON.
+
+!!! note "Technical Details"
+    Data from forms is normally encoded using the "media type" `application/x-www-form-urlencoded`.
+
+    But when the form includes files, it is encoded as `multipart/form-data`. You'll read about handling files in the next chapter.
+    
+    If you want to read more about these encondings and form fields, head to the <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST" target="_blank"><abbr title="Mozilla Developer Network">MDN</abbr> web docs for <code>POST</code></a>.
+
+
+!!! warning
+    You can declare multiple `Form` parameters in an endpoint, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `application/x-www-form-urlencoded` instead of `application/json`.
+
+    This is not a limitation of **FastAPI**, it's part of the HTTP protocol.
+
+## Recap
+
+Use `Form` to declare form data input parameters.

diff --git a/docs/tutorial/src/request-files/tutorial001.py b/docs/tutorial/src/request-files/tutorial001.py
new file mode 100644 (file)
index 0000000..3e99fcd
--- /dev/null
+++ b/docs/tutorial/src/request-files/tutorial001.py
@@ -0,0 +1,8 @@
+from fastapi import FastAPI, File
+
+app = FastAPI()
+
+
+@app.post("/files/")
+async def create_file(*, file: bytes = File(...)):
+    return {"file_size": len(file)}

diff --git a/docs/tutorial/src/request-forms-and-files/tutorial001.py b/docs/tutorial/src/request-forms-and-files/tutorial001.py
new file mode 100644 (file)
index 0000000..1882a63
--- /dev/null
+++ b/docs/tutorial/src/request-forms-and-files/tutorial001.py
@@ -0,0 +1,8 @@
+from fastapi import FastAPI, File, Form
+
+app = FastAPI()
+
+
+@app.post("/files/")
+async def create_file(*, file: bytes = File(...), token: str = Form(...)):
+    return {"file_size": len(file), "token": token}

diff --git a/docs/tutorial/src/form-data/tutorial001.py b/docs/tutorial/src/request-forms/tutorial001.py
similarity index 100%
rename from docs/tutorial/src/form-data/tutorial001.py
rename to docs/tutorial/src/request-forms/tutorial001.py

diff --git a/mkdocs.yml b/mkdocs.yml
index 0d1cabcb0bda29e411faf70308b8b48879bf7a90..961a2161c584e11accbdc92083493e9276747728 100644 (file)
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -31,7 +31,9 @@ nav:
         - Header Parameters: 'tutorial/header-params.md'
         - Response Model: 'tutorial/response-model.md'
         - Extra Models: 'tutorial/extra-models.md'
-        - Form Data: 'tutorial/form-data.md'
+        - Form Data: 'tutorial/request-forms.md'
+        - Request Files: 'tutorial/request-files.md'
+        - Request Forms and Files: 'tutorial/request-forms-and-files.md'
     - Concurrency and async / await: 'async.md'
     - Deployment: 'deployment.md'