してカスタムの独自ヘッダーを追加できます。
- ただし、ブラウザのクライアントに表示させたいカスタムヘッダーがある場合は、StarletteのCORSドキュメントに記載されているパラメータ `expose_headers` を使用して、それらをCORS設定に追加する必要があります ([CORS (オリジン間リソース共有)](cors.md){.internal-link target=_blank})
+ ただし、ブラウザのクライアントに表示させたいカスタムヘッダーがある場合は、StarletteのCORSドキュメントに記載されているパラメータ `expose_headers` を使用して、それらをCORS設定に追加する必要があります ([CORS (オリジン間リソース共有)](cors.md){.internal-link target=_blank})
!!! note "技術詳細"
`from starlette.requests import Request` を使用することもできます。
diff --git a/docs/ja/docs/tutorial/path-params.md b/docs/ja/docs/tutorial/path-params.md
index 452ca0c98..66de05afb 100644
--- a/docs/ja/docs/tutorial/path-params.md
+++ b/docs/ja/docs/tutorial/path-params.md
@@ -139,7 +139,7 @@ Pythonのformat文字列と同様のシンタックスで「パスパラメー
### *パスパラメータ*の宣言
-次に、作成したenumクラスである`ModelName`を使用した型アノテーションをもつ*パスパラメータ*を作成します:
+次に、作成したenumクラスである`ModelName`を使用した型アノテーションをもつ*パスパラメータ*を作成します:
```Python hl_lines="16"
{!../../../docs_src/path_params/tutorial005.py!}
diff --git a/docs/ja/docs/tutorial/query-params-str-validations.md b/docs/ja/docs/tutorial/query-params-str-validations.md
index ff0af725f..8d375d7ce 100644
--- a/docs/ja/docs/tutorial/query-params-str-validations.md
+++ b/docs/ja/docs/tutorial/query-params-str-validations.md
@@ -34,12 +34,12 @@
{!../../../docs_src/query_params_str_validations/tutorial002.py!}
```
-デフォルト値`None`を`Query(None)`に置き換える必要があるので、`Query`の最初の引数はデフォルト値を定義するのと同じです。
+デフォルト値`None`を`Query(default=None)`に置き換える必要があるので、`Query`の最初の引数はデフォルト値を定義するのと同じです。
なので:
```Python
-q: Optional[str] = Query(None)
+q: Optional[str] = Query(default=None)
```
...を以下と同じようにパラメータをオプションにします:
@@ -60,7 +60,7 @@ q: Optional[str] = None
もしくは:
```Python
- = Query(None)
+ = Query(default=None)
```
そして、 `None` を利用することでクエリパラメータが必須ではないと検知します。
@@ -70,7 +70,7 @@ q: Optional[str] = None
そして、さらに多くのパラメータを`Query`に渡すことができます。この場合、文字列に適用される、`max_length`パラメータを指定します。
```Python
-q: str = Query(None, max_length=50)
+q: Union[str, None] = Query(default=None, max_length=50)
```
これにより、データを検証し、データが有効でない場合は明確なエラーを表示し、OpenAPIスキーマの *path operation* にパラメータを記載します。
@@ -79,7 +79,7 @@ q: str = Query(None, max_length=50)
パラメータ`min_length`も追加することができます:
-```Python hl_lines="9"
+```Python hl_lines="10"
{!../../../docs_src/query_params_str_validations/tutorial003.py!}
```
@@ -87,7 +87,7 @@ q: str = Query(None, max_length=50)
パラメータが一致するべき正規表現を定義することができます:
-```Python hl_lines="10"
+```Python hl_lines="11"
{!../../../docs_src/query_params_str_validations/tutorial004.py!}
```
@@ -125,13 +125,13 @@ q: str
以下の代わりに:
```Python
-q: Optional[str] = None
+q: Union[str, None] = None
```
現在は以下の例のように`Query`で宣言しています:
```Python
-q: Optional[str] = Query(None, min_length=3)
+q: Union[str, None] = Query(default=None, min_length=3)
```
そのため、`Query`を使用して必須の値を宣言する必要がある場合は、第一引数に`...`を使用することができます:
diff --git a/docs/ja/docs/tutorial/query-params.md b/docs/ja/docs/tutorial/query-params.md
index 91783a53a..9f8c6ab9f 100644
--- a/docs/ja/docs/tutorial/query-params.md
+++ b/docs/ja/docs/tutorial/query-params.md
@@ -18,7 +18,7 @@ http://127.0.0.1:8000/items/?skip=0&limit=10
...クエリパラメータは:
* `skip`: 値は `0`
-* `limit`: 値は `10`
+* `limit`: 値は `10`
これらはURLの一部なので、「自然に」文字列になります。
@@ -75,7 +75,7 @@ http://127.0.0.1:8000/items/?skip=20
!!! note "備考"
FastAPIは、`= None`があるおかげで、`q`がオプショナルだとわかります。
-
+
`Optional[str]` の`Optional` はFastAPIでは使用されていません（FastAPIは`str`の部分のみ使用します）。しかし、`Optional[str]` はエディタがコードのエラーを見つけるのを助けてくれます。
## クエリパラメータの型変換
@@ -116,7 +116,7 @@ http://127.0.0.1:8000/items/foo?short=on
http://127.0.0.1:8000/items/foo?short=yes
```
-もしくは、他の大文字小文字のバリエーション (アッパーケース、最初の文字だけアッパーケース、など)で、関数は `short` パラメータを `True` な `bool` 値として扱います。それ以外は `False` になります。
+もしくは、他の大文字小文字のバリエーション (アッパーケース、最初の文字だけアッパーケース、など)で、関数は `short` パラメータを `True` な `bool` 値として扱います。それ以外は `False` になります。
## 複数のパスパラメータとクエリパラメータ
diff --git a/docs/ja/docs/tutorial/request-forms.md b/docs/ja/docs/tutorial/request-forms.md
index 06105c9ef..bce6e8d9a 100644
--- a/docs/ja/docs/tutorial/request-forms.md
+++ b/docs/ja/docs/tutorial/request-forms.md
@@ -45,7 +45,7 @@ HTMLフォーム（``）がサーバにデータを送信する方
フォームからのデータは通常、`application/x-www-form-urlencoded`の「media type」を使用してエンコードされます。
しかし、フォームがファイルを含む場合は、`multipart/form-data`としてエンコードされます。ファイルの扱いについては次の章で説明します。
-
+
これらのエンコーディングやフォームフィールドの詳細については、MDNのPOSTのウェブドキュメントを参照してください。
!!! warning "注意"
diff --git a/docs/ja/docs/tutorial/static-files.md b/docs/ja/docs/tutorial/static-files.md
index fcc3ba924..1d9c434c3 100644
--- a/docs/ja/docs/tutorial/static-files.md
+++ b/docs/ja/docs/tutorial/static-files.md
@@ -2,20 +2,6 @@
`StaticFiles` を使用して、ディレクトリから静的ファイルを自動的に提供できます。
-## `aiofiles` をインストール
-
-まず、`aiofiles` をインストールする必要があります:
-
-
-
-```console
-$ pip install aiofiles
-
----> 100%
-```
-
-
-
## `StaticFiles` の使用
* `StaticFiles` をインポート。
diff --git a/docs/ja/docs/tutorial/testing.md b/docs/ja/docs/tutorial/testing.md
index ebd2de37c..03b0e1dee 100644
--- a/docs/ja/docs/tutorial/testing.md
+++ b/docs/ja/docs/tutorial/testing.md
@@ -36,7 +36,7 @@
!!! tip "豆知識"
FastAPIアプリケーションへのリクエストの送信とは別に、テストで `async` 関数 (非同期データベース関数など) を呼び出したい場合は、高度なチュートリアルの[Async Tests](../advanced/async-tests.md){.internal-link target=_blank} を参照してください。
-
+
## テストの分離
実際のアプリケーションでは、おそらくテストを別のファイルに保存します。
@@ -74,16 +74,24 @@
これらの *path operation* には `X-Token` ヘッダーが必要です。
-```Python
-{!../../../docs_src/app_testing/main_b.py!}
-```
+=== "Python 3.6 and above"
+
+ ```Python
+ {!> ../../../docs_src/app_testing/app_b/main.py!}
+ ```
+
+=== "Python 3.10 and above"
+
+ ```Python
+ {!> ../../../docs_src/app_testing/app_b_py310/main.py!}
+ ```
### 拡張版テストファイル
次に、先程のものに拡張版のテストを加えた、`test_main_b.py` を作成します。
```Python
-{!../../../docs_src/app_testing/test_main_b.py!}
+{!> ../../../docs_src/app_testing/app_b/test_main.py!}
```
リクエストに情報を渡せるクライアントが必要で、その方法がわからない場合はいつでも、`requests` での実現方法を検索 (Google) できます。
@@ -104,7 +112,7 @@
`TestClient` は、Pydanticモデルではなく、JSONに変換できるデータを受け取ることに注意してください。
テストにPydanticモデルがあり、テスト中にそのデータをアプリケーションに送信したい場合は、[JSON互換エンコーダ](encoder.md){.internal-link target=_blank} で説明されている `jsonable_encoder` が利用できます。
-
+
## 実行
後は、`pytest` をインストールするだけです:
diff --git a/docs/ja/mkdocs.yml b/docs/ja/mkdocs.yml
index f972eb0ff..055404fea 100644
--- a/docs/ja/mkdocs.yml
+++ b/docs/ja/mkdocs.yml
@@ -5,13 +5,15 @@ theme:
name: material
custom_dir: overrides
palette:
- - scheme: default
+ - media: "(prefers-color-scheme: light)"
+ scheme: default
primary: teal
accent: amber
toggle:
icon: material/lightbulb
name: Switch to light mode
- - scheme: slate
+ - media: "(prefers-color-scheme: dark)"
+ scheme: slate
primary: teal
accent: amber
toggle:
@@ -80,6 +82,7 @@ nav:
- advanced/additional-status-codes.md
- advanced/response-directly.md
- advanced/custom-response.md
+ - advanced/conditional-openapi.md
- async.md
- デプロイ:
- deployment/index.md
diff --git a/docs/ko/docs/deployment/versions.md b/docs/ko/docs/deployment/versions.md
index 4c1bcdc2e..074c15158 100644
--- a/docs/ko/docs/deployment/versions.md
+++ b/docs/ko/docs/deployment/versions.md
@@ -6,7 +6,7 @@
이것이 아직도 최신 버전이 `0.x.x`인 이유입니다. 이것은 각각의 버전들이 잠재적으로 변할 수 있다는 것을 보여줍니다. 이는 유의적 버전 관습을 따릅니다.
-지금 바로 **FastAPI**로 응용 프로그램을 만들 수 있습니다. 이때 (아마 지금까지 그래 왔던 것처럼), 사용하는 버전이 코드와 잘 맞는지 확인해야합니다.
+지금 바로 **FastAPI**로 응용 프로그램을 만들 수 있습니다. 이때 (아마 지금까지 그래 왔던 것처럼), 사용하는 버전이 코드와 잘 맞는지 확인해야합니다.
## `fastapi` 버전을 표시
@@ -46,7 +46,7 @@ FastAPI는 오류를 수정하고, 일반적인 변경사항을 위해 "패치"
!!! tip "팁"
여기서 말하는 "패치"란 버전의 마지막 숫자로, 예를 들어 `0.2.3` 버전에서 "패치"는 `3`을 의미합니다.
-따라서 다음과 같이 버전을 표시할 수 있습니다:
+따라서 다음과 같이 버전을 표시할 수 있습니다:
```txt
fastapi>=0.45.0,<0.46.0
@@ -71,7 +71,7 @@ fastapi>=0.45.0,<0.46.0
`starlette`의 버전은 표시할 수 없습니다.
-서로다른 버전의 **FastAPI**가 구체적이고 새로운 버전의 Starlette을 사용할 것입니다.
+서로다른 버전의 **FastAPI**가 구체적이고 새로운 버전의 Starlette을 사용할 것입니다.
그러므로 **FastAPI**가 알맞은 Starlette 버전을 사용하도록 하십시오.
diff --git a/docs/ko/docs/index.md b/docs/ko/docs/index.md
index d0c236906..ec4422994 100644
--- a/docs/ko/docs/index.md
+++ b/docs/ko/docs/index.md
@@ -145,7 +145,7 @@ $ pip install uvicorn[standard]
* `main.py` 파일을 만드십시오:
```Python
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
@@ -158,7 +158,7 @@ def read_root():
@app.get("/items/{item_id}")
-def read_item(item_id: int, q: Optional[str] = None):
+def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
```
@@ -168,7 +168,7 @@ def read_item(item_id: int, q: Optional[str] = None):
여러분의 코드가 `async` / `await`을 사용한다면, `async def`를 사용하십시오.
```Python hl_lines="9 14"
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
@@ -181,7 +181,7 @@ async def read_root():
@app.get("/items/{item_id}")
-async def read_item(item_id: int, q: Optional[str] = None):
+async def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
```
@@ -260,7 +260,7 @@ INFO: Application startup complete.
Pydantic을 이용해 파이썬 표준 타입으로 본문을 선언합니다.
```Python hl_lines="4 9 10 11 12 25 26 27"
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
from pydantic import BaseModel
@@ -271,7 +271,7 @@ app = FastAPI()
class Item(BaseModel):
name: str
price: float
- is_offer: Optional[bool] = None
+ is_offer: Union[bool, None] = None
@app.get("/")
@@ -280,7 +280,7 @@ def read_root():
@app.get("/items/{item_id}")
-def read_item(item_id: int, q: Optional[str] = None):
+def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
@@ -443,7 +443,6 @@ Pydantic이 사용하는:
Starlette이 사용하는:
* requests - `TestClient`를 사용하려면 필요.
-* aiofiles - `FileResponse` 또는 `StaticFiles`를 사용하려면 필요.
* jinja2 - 기본 템플릿 설정을 사용하려면 필요.
* python-multipart - `request.form()`과 함께 "parsing"의 지원을 원하면 필요.
* itsdangerous - `SessionMiddleware` 지원을 위해 필요.
diff --git a/docs/ko/docs/tutorial/header-params.md b/docs/ko/docs/tutorial/header-params.md
index 1c46b32ba..484554e97 100644
--- a/docs/ko/docs/tutorial/header-params.md
+++ b/docs/ko/docs/tutorial/header-params.md
@@ -57,7 +57,7 @@
타입 정의에서 리스트를 사용하여 이러한 케이스를 정의할 수 있습니다.
-중복 헤더의 모든 값을 파이썬 `list`로 수신합니다.
+중복 헤더의 모든 값을 파이썬 `list`로 수신합니다.
예를 들어, 두 번 이상 나타날 수 있는 `X-Token`헤더를 선언하려면, 다음과 같이 작성합니다:
diff --git a/docs/ko/docs/tutorial/path-params-numeric-validations.md b/docs/ko/docs/tutorial/path-params-numeric-validations.md
index abb9d03db..cadf543fc 100644
--- a/docs/ko/docs/tutorial/path-params-numeric-validations.md
+++ b/docs/ko/docs/tutorial/path-params-numeric-validations.md
@@ -43,7 +43,7 @@
따라서 함수를 다음과 같이 선언 할 수 있습니다:
-```Python hl_lines="8"
+```Python hl_lines="7"
{!../../../docs_src/path_params_numeric_validations/tutorial002.py!}
```
@@ -55,7 +55,7 @@
파이썬은 `*`으로 아무런 행동도 하지 않지만, 따르는 매개변수들은 kwargs로도 알려진 키워드 인자(키-값 쌍)여야 함을 인지합니다. 기본값을 가지고 있지 않더라도 그렇습니다.
-```Python hl_lines="8"
+```Python hl_lines="7"
{!../../../docs_src/path_params_numeric_validations/tutorial003.py!}
```
diff --git a/docs/ko/docs/tutorial/path-params.md b/docs/ko/docs/tutorial/path-params.md
index ede63f69d..5cf397e7a 100644
--- a/docs/ko/docs/tutorial/path-params.md
+++ b/docs/ko/docs/tutorial/path-params.md
@@ -241,4 +241,4 @@ Starlette에서 직접 옵션을 사용하면 다음과 같은 URL을 사용하
위 사항들을 그저 한번에 선언하면 됩니다.
-이는 (원래 성능과는 별개로) 대체 프레임워크와 비교했을 때 **FastAPI**의 주요 가시적 장점일 것입니다.
\ No newline at end of file
+이는 (원래 성능과는 별개로) 대체 프레임워크와 비교했을 때 **FastAPI**의 주요 가시적 장점일 것입니다.
diff --git a/docs/ko/docs/tutorial/query-params.md b/docs/ko/docs/tutorial/query-params.md
index 05f2ff9c9..bb631e6ff 100644
--- a/docs/ko/docs/tutorial/query-params.md
+++ b/docs/ko/docs/tutorial/query-params.md
@@ -75,7 +75,7 @@ http://127.0.0.1:8000/items/?skip=20
!!! note "참고"
FastAPI는 `q`가 `= None`이므로 선택적이라는 것을 인지합니다.
- `Optional[str]`에 있는 `Optional`은 FastAPI(FastAPI는 `str` 부분만 사용합니다)가 사용하는게 아니지만, `Optional[str]`은 편집기에게 코드에서 오류를 찾아낼 수 있게 도와줍니다.
+ `Union[str, None]`에 있는 `Union`은 FastAPI(FastAPI는 `str` 부분만 사용합니다)가 사용하는게 아니지만, `Union[str, None]`은 편집기에게 코드에서 오류를 찾아낼 수 있게 도와줍니다.
## 쿼리 매개변수 형변환
diff --git a/docs/ko/docs/tutorial/request-files.md b/docs/ko/docs/tutorial/request-files.md
index 769a676cd..decefe981 100644
--- a/docs/ko/docs/tutorial/request-files.md
+++ b/docs/ko/docs/tutorial/request-files.md
@@ -13,7 +13,7 @@
`fastapi` 에서 `File` 과 `UploadFile` 을 임포트 합니다:
-```Python hl_lines="1"
+```Python hl_lines="1"
{!../../../docs_src/request_files/tutorial001.py!}
```
@@ -21,7 +21,7 @@
`Body` 및 `Form` 과 동일한 방식으로 파일의 매개변수를 생성합니다:
-```Python hl_lines="7"
+```Python hl_lines="7"
{!../../../docs_src/request_files/tutorial001.py!}
```
@@ -45,7 +45,7 @@
`File` 매개변수를 `UploadFile` 타입으로 정의합니다:
-```Python hl_lines="12"
+```Python hl_lines="12"
{!../../../docs_src/request_files/tutorial001.py!}
```
@@ -97,7 +97,7 @@ contents = myfile.file.read()
## "폼 데이터"란
-HTML의 폼들(``)이 서버에 데이터를 전송하는 방식은 대개 데이터에 JSON과는 다른 "특별한" 인코딩을 사용합니다.
+HTML의 폼들(``)이 서버에 데이터를 전송하는 방식은 대개 데이터에 JSON과는 다른 "특별한" 인코딩을 사용합니다.
**FastAPI**는 JSON 대신 올바른 위치에서 데이터를 읽을 수 있도록 합니다.
@@ -121,7 +121,7 @@ HTML의 폼들(``)이 서버에 데이터를 전송하는 방식은
이 기능을 사용하기 위해 , `bytes` 의 `List` 또는 `UploadFile` 를 선언하기 바랍니다:
-```Python hl_lines="10 15"
+```Python hl_lines="10 15"
{!../../../docs_src/request_files/tutorial002.py!}
```
diff --git a/docs/ko/docs/tutorial/request-forms-and-files.md b/docs/ko/docs/tutorial/request-forms-and-files.md
index 6750c7b23..ddf232e7f 100644
--- a/docs/ko/docs/tutorial/request-forms-and-files.md
+++ b/docs/ko/docs/tutorial/request-forms-and-files.md
@@ -9,7 +9,7 @@
## `File` 및 `Form` 업로드
-```Python hl_lines="1"
+```Python hl_lines="1"
{!../../../docs_src/request_forms_and_files/tutorial001.py!}
```
@@ -17,7 +17,7 @@
`Body` 및 `Query`와 동일한 방식으로 파일과 폼의 매개변수를 생성합니다:
-```Python hl_lines="8"
+```Python hl_lines="8"
{!../../../docs_src/request_forms_and_files/tutorial001.py!}
```
diff --git a/docs/ko/docs/tutorial/response-status-code.md b/docs/ko/docs/tutorial/response-status-code.md
index d201867a1..f92c057be 100644
--- a/docs/ko/docs/tutorial/response-status-code.md
+++ b/docs/ko/docs/tutorial/response-status-code.md
@@ -8,11 +8,11 @@
* `@app.delete()`
* 기타
-```Python hl_lines="6"
+```Python hl_lines="6"
{!../../../docs_src/response_status_code/tutorial001.py!}
```
-!!! note "참고"
+!!! note "참고"
`status_code` 는 "데코레이터" 메소드(`get`, `post` 등)의 매개변수입니다. 모든 매개변수들과 본문처럼 *경로 작동 함수*가 아닙니다.
`status_code` 매개변수는 HTTP 상태 코드를 숫자로 입력받습니다.
@@ -27,7 +27,7 @@
-!!! note "참고"
+!!! note "참고"
어떤 응답 코드들은 해당 응답에 본문이 없다는 것을 의미하기도 합니다 (다음 항목 참고).
이에 따라 FastAPI는 응답 본문이 없음을 명시하는 OpenAPI를 생성합니다.
@@ -61,7 +61,7 @@ HTTP는 세자리의 숫자 상태 코드를 응답의 일부로 전송합니다
상기 예시 참고:
-```Python hl_lines="6"
+```Python hl_lines="6"
{!../../../docs_src/response_status_code/tutorial001.py!}
```
@@ -71,7 +71,7 @@ HTTP는 세자리의 숫자 상태 코드를 응답의 일부로 전송합니다
`fastapi.status` 의 편의 변수를 사용할 수 있습니다.
-```Python hl_lines="1 6"
+```Python hl_lines="1 6"
{!../../../docs_src/response_status_code/tutorial002.py!}
```
diff --git a/docs/ko/mkdocs.yml b/docs/ko/mkdocs.yml
index 1e7d60dbd..60cf7d30a 100644
--- a/docs/ko/mkdocs.yml
+++ b/docs/ko/mkdocs.yml
@@ -5,13 +5,15 @@ theme:
name: material
custom_dir: overrides
palette:
- - scheme: default
+ - media: "(prefers-color-scheme: light)"
+ scheme: default
primary: teal
accent: amber
toggle:
icon: material/lightbulb
name: Switch to light mode
- - scheme: slate
+ - media: "(prefers-color-scheme: dark)"
+ scheme: slate
primary: teal
accent: amber
toggle:
diff --git a/docs/nl/docs/index.md b/docs/nl/docs/index.md
index 0070de179..fd52f994c 100644
--- a/docs/nl/docs/index.md
+++ b/docs/nl/docs/index.md
@@ -152,7 +152,7 @@ $ pip install "uvicorn[standard]"
* Create a file `main.py` with:
```Python
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
@@ -165,7 +165,7 @@ def read_root():
@app.get("/items/{item_id}")
-def read_item(item_id: int, q: Optional[str] = None):
+def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
```
@@ -175,7 +175,7 @@ def read_item(item_id: int, q: Optional[str] = None):
If your code uses `async` / `await`, use `async def`:
```Python hl_lines="9 14"
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
@@ -188,7 +188,7 @@ async def read_root():
@app.get("/items/{item_id}")
-async def read_item(item_id: int, q: Optional[str] = None):
+async def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
```
@@ -267,7 +267,7 @@ Now modify the file `main.py` to receive a body from a `PUT` request.
Declare the body using standard Python types, thanks to Pydantic.
```Python hl_lines="4 9-12 25-27"
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
from pydantic import BaseModel
@@ -278,7 +278,7 @@ app = FastAPI()
class Item(BaseModel):
name: str
price: float
- is_offer: Optional[bool] = None
+ is_offer: Union[bool, None] = None
@app.get("/")
@@ -287,7 +287,7 @@ def read_root():
@app.get("/items/{item_id}")
-def read_item(item_id: int, q: Optional[str] = None):
+def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
diff --git a/docs/nl/mkdocs.yml b/docs/nl/mkdocs.yml
index c853216f5..9cd1e0401 100644
--- a/docs/nl/mkdocs.yml
+++ b/docs/nl/mkdocs.yml
@@ -5,13 +5,15 @@ theme:
name: material
custom_dir: overrides
palette:
- - scheme: default
+ - media: "(prefers-color-scheme: light)"
+ scheme: default
primary: teal
accent: amber
toggle:
icon: material/lightbulb
name: Switch to light mode
- - scheme: slate
+ - media: "(prefers-color-scheme: dark)"
+ scheme: slate
primary: teal
accent: amber
toggle:
diff --git a/docs/pl/docs/index.md b/docs/pl/docs/index.md
index 4a300ae63..bbe1b1ad1 100644
--- a/docs/pl/docs/index.md
+++ b/docs/pl/docs/index.md
@@ -144,7 +144,7 @@ $ pip install uvicorn[standard]
* Utwórz plik o nazwie `main.py` z:
```Python
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
@@ -157,7 +157,7 @@ def read_root():
@app.get("/items/{item_id}")
-def read_item(item_id: int, q: Optional[str] = None):
+def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
```
@@ -167,7 +167,7 @@ def read_item(item_id: int, q: Optional[str] = None):
Jeżeli twój kod korzysta z `async` / `await`, użyj `async def`:
```Python hl_lines="9 14"
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
@@ -180,7 +180,7 @@ async def read_root():
@app.get("/items/{item_id}")
-async def read_item(item_id: int, q: Optional[str] = None):
+async def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
```
@@ -258,7 +258,7 @@ Zmodyfikuj teraz plik `main.py`, aby otrzmywał treść (body) żądania `PUT`.
Zadeklaruj treść żądania, używając standardowych typów w Pythonie dzięki Pydantic.
```Python hl_lines="4 9-12 25-27"
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
from pydantic import BaseModel
@@ -269,7 +269,7 @@ app = FastAPI()
class Item(BaseModel):
name: str
price: float
- is_offer: Optional[bool] = None
+ is_offer: Union[bool, None] = None
@app.get("/")
@@ -278,7 +278,7 @@ def read_root():
@app.get("/items/{item_id}")
-def read_item(item_id: int, q: Optional[str] = None):
+def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
diff --git a/docs/pl/docs/tutorial/index.md b/docs/pl/docs/tutorial/index.md
new file mode 100644
index 000000000..ed8752a95
--- /dev/null
+++ b/docs/pl/docs/tutorial/index.md
@@ -0,0 +1,80 @@
+# Samouczek - Wprowadzenie
+
+Ten samouczek pokaże Ci, krok po kroku, jak używać większości funkcji **FastAPI**.
+
+Każda część korzysta z poprzednich, ale jest jednocześnie osobnym tematem. Możesz przejść bezpośrednio do każdego rozdziału, jeśli szukasz rozwiązania konkretnego problemu.
+
+Samouczek jest tak zbudowany, żeby służył jako punkt odniesienia w przyszłości.
+
+Możesz wracać i sprawdzać dokładnie to czego potrzebujesz.
+
+## Wykonywanie kodu
+
+Wszystkie fragmenty kodu mogą być skopiowane bezpośrednio i użyte (są poprawnymi i przetestowanymi plikami).
+
+Żeby wykonać każdy przykład skopiuj kod to pliku `main.py` i uruchom `uvicorn` za pomocą:
+
+
+
+```console
+$ uvicorn main:app --reload
+
+INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+INFO: Started reloader process [28720]
+INFO: Started server process [28722]
+INFO: Waiting for application startup.
+INFO: Application startup complete.
+```
+
+
+
+**BARDZO zalecamy** pisanie bądź kopiowanie kodu, edycję, a następnie wykonywanie go lokalnie.
+
+Użycie w Twoim edytorze jest tym, co pokazuje prawdziwe korzyści z FastAPI, pozwala zobaczyć jak mało kodu musisz napisać, wszystkie funkcje, takie jak kontrola typów, automatyczne uzupełnianie, itd.
+
+---
+
+## Instalacja FastAPI
+
+Jako pierwszy krok zainstaluj FastAPI.
+
+Na potrzeby samouczka możesz zainstalować również wszystkie opcjonalne biblioteki:
+
+
+
+```console
+$ pip install "fastapi[all]"
+
+---> 100%
+```
+
+
+
+...wliczając w to `uvicorn`, który będzie służył jako serwer wykonujacy Twój kod.
+
+!!! note
+ Możesz również wykonać instalację "krok po kroku".
+
+ Prawdopodobnie zechcesz to zrobić, kiedy będziesz wdrażać swoją aplikację w środowisku produkcyjnym:
+
+ ```
+ pip install fastapi
+ ```
+
+ Zainstaluj też `uvicorn`, który będzie służył jako serwer:
+
+ ```
+ pip install "uvicorn[standard]"
+ ```
+
+ Tak samo możesz zainstalować wszystkie dodatkowe biblioteki, których chcesz użyć.
+
+## Zaawansowany poradnik
+
+Jest też **Zaawansowany poradnik**, który możesz przeczytać po lekturze tego **Samouczka**.
+
+**Zaawansowany poradnik** opiera się na tym samouczku, używa tych samych pojęć, żeby pokazać Ci kilka dodatkowych funkcji.
+
+Najpierw jednak powinieneś przeczytać **Samouczek** (czytasz go teraz).
+
+Ten rozdział jest zaprojektowany tak, że możesz stworzyć kompletną aplikację używając tylko informacji tutaj zawartych, a następnie rozszerzać ją na różne sposoby, w zależności od potrzeb, używając kilku dodatkowych pomysłów z **Zaawansowanego poradnika**.
diff --git a/docs/pl/mkdocs.yml b/docs/pl/mkdocs.yml
index 67b41fe53..0c3d100e7 100644
--- a/docs/pl/mkdocs.yml
+++ b/docs/pl/mkdocs.yml
@@ -5,13 +5,15 @@ theme:
name: material
custom_dir: overrides
palette:
- - scheme: default
+ - media: "(prefers-color-scheme: light)"
+ scheme: default
primary: teal
accent: amber
toggle:
icon: material/lightbulb
name: Switch to light mode
- - scheme: slate
+ - media: "(prefers-color-scheme: dark)"
+ scheme: slate
primary: teal
accent: amber
toggle:
@@ -54,6 +56,8 @@ nav:
- tr: /tr/
- uk: /uk/
- zh: /zh/
+- Samouczek:
+ - tutorial/index.md
markdown_extensions:
- toc:
permalink: true
diff --git a/docs/pt/docs/alternatives.md b/docs/pt/docs/alternatives.md
index 6559b7398..61ee4f900 100644
--- a/docs/pt/docs/alternatives.md
+++ b/docs/pt/docs/alternatives.md
@@ -331,7 +331,7 @@ Agora APIStar é um conjunto de ferramentas para validar especificações OpenAP
Existir.
A idéia de declarar múltiplas coisas (validação de dados, serialização e documentação) com os mesmos tipos Python, que ao mesmo tempo fornecesse grande suporte ao editor, era algo que eu considerava uma brilhante idéia.
-
+
E após procurar por um logo tempo por um framework similar e testar muitas alternativas diferentes, APIStar foi a melhor opção disponível.
Então APIStar parou de existir como um servidor e Starlette foi criado, e foi uma nova melhor fundação para tal sistema. Essa foi a inspiração final para construir **FastAPI**.
@@ -390,7 +390,7 @@ Essa é uma das principais coisas que **FastAPI** adiciona no topo, tudo baseado
Controlar todas as partes web centrais. Adiciona recursos no topo.
A classe `FastAPI` em si herda `Starlette`.
-
+
Então, qualquer coisa que você faz com Starlette, você pode fazer diretamente com **FastAPI**, pois ele é basicamente um Starlette com esteróides.
### Uvicorn
diff --git a/docs/pt/docs/async.md b/docs/pt/docs/async.md
index 44f4b5148..be1278a1b 100644
--- a/docs/pt/docs/async.md
+++ b/docs/pt/docs/async.md
@@ -94,7 +94,7 @@ Para "síncrono" (contrário de "assíncrono") também é utilizado o termo "seq
Essa idéia de código **assíncrono** descrito acima é algo às vezes chamado de **"concorrência"**. E é diferente de **"paralelismo"**.
-**Concorrência** e **paralelismo** ambos são relacionados a "diferentes coisas acontecendo mais ou menos ao mesmo tempo".
+**Concorrência** e **paralelismo** ambos são relacionados a "diferentes coisas acontecendo mais ou menos ao mesmo tempo".
Mas os detalhes entre *concorrência* e *paralelismo* são bem diferentes.
@@ -134,7 +134,7 @@ Mas então, embora você ainda não tenha os hambúrgueres, seu trabalho no caix
Mas enquanto você se afasta do balcão e senta na mesa com o número da sua chamada, você pode trocar sua atenção para seu _crush_ :heart_eyes:, e "trabalhar" nisso. Então você está novamente fazendo algo muito "produtivo", como flertar com seu _crush_ :heart_eyes:.
-Então o caixa diz que "seus hambúrgueres estão prontos" colocando seu número no balcão, mas você não corre que nem um maluco imediatamente quando o número exibido é o seu. Você sabe que ninguém irá roubar seus hambúrgueres porquê você tem o número de chamada, e os outros tem os números deles.
+Então o caixa diz que "seus hambúrgueres estão prontos" colocando seu número no balcão, mas você não corre que nem um maluco imediatamente quando o número exibido é o seu. Você sabe que ninguém irá roubar seus hambúrgueres porquê você tem o número de chamada, e os outros tem os números deles.
Então você espera que seu _crush_ :heart_eyes: termine a história que estava contando (terminar o trabalho atual / tarefa sendo processada), sorri gentilmente e diz que você está indo buscar os hambúrgueres.
@@ -358,9 +358,9 @@ Tudo isso é o que deixa o FastAPI poderoso (através do Starlette) e que o faz
!!! warning
Você pode provavelmente pular isso.
-
+
Esses são detalhes muito técnicos de como **FastAPI** funciona por baixo do capô.
-
+
Se você tem algum conhecimento técnico (corrotinas, threads, blocking etc) e está curioso sobre como o FastAPI controla o `async def` vs normal `def`, vá em frente.
### Funções de operação de rota
diff --git a/docs/pt/docs/benchmarks.md b/docs/pt/docs/benchmarks.md
index 7f7c95ba1..07461ce46 100644
--- a/docs/pt/docs/benchmarks.md
+++ b/docs/pt/docs/benchmarks.md
@@ -2,7 +2,7 @@
As comparações independentes da TechEmpower mostram as aplicações **FastAPI** rodando com Uvicorn como um dos _frameworks_ Python mais rápidos disponíveis, somente atrás dos próprios Starlette e Uvicorn (utilizados internamente pelo FastAPI). (*)
-Mas quando se checa _benchmarks_ e comparações você deveria ter o seguinte em mente.
+Mas quando se checa _benchmarks_ e comparações você deveria ter o seguinte em mente.
## Comparações e velocidade
diff --git a/docs/pt/docs/deployment/deta.md b/docs/pt/docs/deployment/deta.md
new file mode 100644
index 000000000..9271bba42
--- /dev/null
+++ b/docs/pt/docs/deployment/deta.md
@@ -0,0 +1,258 @@
+# Implantação FastAPI na Deta
+
+Nessa seção você aprenderá sobre como realizar a implantação de uma aplicação **FastAPI** na Deta utilizando o plano gratuito. 🎁
+
+Isso tudo levará aproximadamente **10 minutos**.
+
+!!! info "Informação"
+ Deta é uma patrocinadora do **FastAPI**. 🎉
+
+## Uma aplicação **FastAPI** simples
+
+* Crie e entre em um diretório para a sua aplicação, por exemplo, `./fastapideta/`.
+
+### Código FastAPI
+
+* Crie o arquivo `main.py` com:
+
+```Python
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/")
+def read_root():
+ return {"Hello": "World"}
+
+
+@app.get("/items/{item_id}")
+def read_item(item_id: int):
+ return {"item_id": item_id}
+```
+
+### Requisitos
+
+Agora, no mesmo diretório crie o arquivo `requirements.txt` com:
+
+```text
+fastapi
+```
+
+!!! tip "Dica"
+ Você não precisa instalar Uvicorn para realizar a implantação na Deta, embora provavelmente queira instalá-lo para testar seu aplicativo localmente.
+
+### Estrutura de diretório
+
+Agora você terá o diretório `./fastapideta/` com dois arquivos:
+
+```
+.
+└── main.py
+└── requirements.txt
+```
+
+## Crie uma conta gratuita na Deta
+
+Agora crie uma conta gratuita na Deta, você precisará apenas de um email e senha.
+
+Você nem precisa de um cartão de crédito.
+
+## Instale a CLI
+
+Depois de ter sua conta criada, instale Deta CLI:
+
+=== "Linux, macOS"
+
+
+
+ ```console
+ $ curl -fsSL https://get.deta.dev/cli.sh | sh
+ ```
+
+
+
+=== "Windows PowerShell"
+
+
+
+ ```console
+ $ iwr https://get.deta.dev/cli.ps1 -useb | iex
+ ```
+
+
+
+Após a instalação, abra um novo terminal para que a CLI seja detectada.
+
+Em um novo terminal, confirme se foi instalado corretamente com:
+
+
+
+```console
+$ deta --help
+
+Deta command line interface for managing deta micros.
+Complete documentation available at https://docs.deta.sh
+
+Usage:
+ deta [flags]
+ deta [command]
+
+Available Commands:
+ auth Change auth settings for a deta micro
+
+...
+```
+
+
+
+!!! tip "Dica"
+ Se você tiver problemas ao instalar a CLI, verifique a documentação oficial da Deta.
+
+## Login pela CLI
+
+Agora faça login na Deta pela CLI com:
+
+
+
+```console
+$ deta login
+
+Please, log in from the web page. Waiting..
+Logged in successfully.
+```
+
+
+
+Isso abrirá um navegador da Web e autenticará automaticamente.
+
+## Implantação com Deta
+
+Em seguida, implante seu aplicativo com a Deta CLI:
+
+
+
+```console
+$ deta new
+
+Successfully created a new micro
+
+// Notice the "endpoint" 🔍
+
+{
+ "name": "fastapideta",
+ "runtime": "python3.7",
+ "endpoint": "https://qltnci.deta.dev",
+ "visor": "enabled",
+ "http_auth": "enabled"
+}
+
+Adding dependencies...
+
+
+---> 100%
+
+
+Successfully installed fastapi-0.61.1 pydantic-1.7.2 starlette-0.13.6
+```
+
+
+
+Você verá uma mensagem JSON semelhante a:
+
+```JSON hl_lines="4"
+{
+ "name": "fastapideta",
+ "runtime": "python3.7",
+ "endpoint": "https://qltnci.deta.dev",
+ "visor": "enabled",
+ "http_auth": "enabled"
+}
+```
+
+!!! tip "Dica"
+ Sua implantação terá um URL `"endpoint"` diferente.
+
+## Confira
+
+Agora, abra seu navegador na URL do `endpoint`. No exemplo acima foi `https://qltnci.deta.dev`, mas o seu será diferente.
+
+Você verá a resposta JSON do seu aplicativo FastAPI:
+
+```JSON
+{
+ "Hello": "World"
+}
+```
+
+Agora vá para o `/docs` da sua API, no exemplo acima seria `https://qltnci.deta.dev/docs`.
+
+Ele mostrará sua documentação como:
+
+
+
+## Permitir acesso público
+
+Por padrão, a Deta lidará com a autenticação usando cookies para sua conta.
+
+Mas quando estiver pronto, você pode torná-lo público com:
+
+
+
+```console
+$ deta auth disable
+
+Successfully disabled http auth
+```
+
+
+
+Agora você pode compartilhar essa URL com qualquer pessoa e elas conseguirão acessar sua API. 🚀
+
+## HTTPS
+
+Parabéns! Você realizou a implantação do seu app FastAPI na Deta! 🎉 🍰
+
+Além disso, observe que a Deta lida corretamente com HTTPS para você, para que você não precise cuidar disso e tenha a certeza de que seus clientes terão uma conexão criptografada segura. ✅ 🔒
+
+## Verifique o Visor
+
+Na UI da sua documentação (você estará em um URL como `https://qltnci.deta.dev/docs`) envie um request para *operação de rota* `/items/{item_id}`.
+
+Por exemplo com ID `5`.
+
+Agora vá para https://web.deta.sh.
+
+Você verá que há uma seção à esquerda chamada "Micros" com cada um dos seus apps.
+
+Você verá uma aba com "Detalhes", e também a aba "Visor", vá para "Visor".
+
+Lá você pode inspecionar as solicitações recentes enviadas ao seu aplicativo.
+
+Você também pode editá-los e reproduzi-los novamente.
+
+
+
+## Saiba mais
+
+Em algum momento, você provavelmente desejará armazenar alguns dados para seu aplicativo de uma forma que persista ao longo do tempo. Para isso você pode usar Deta Base, que também tem um generoso **nível gratuito**.
+
+Você também pode ler mais na documentação da Deta.
+
+## Conceitos de implantação
+
+Voltando aos conceitos que discutimos em [Deployments Concepts](./concepts.md){.internal-link target=_blank}, veja como cada um deles seria tratado com a Deta:
+
+* **HTTPS**: Realizado pela Deta, eles fornecerão um subdomínio e lidarão com HTTPS automaticamente.
+* **Executando na inicialização**: Realizado pela Deta, como parte de seu serviço.
+* **Reinicialização**: Realizado pela Deta, como parte de seu serviço.
+* **Replicação**: Realizado pela Deta, como parte de seu serviço.
+* **Memória**: Limite predefinido pela Deta, você pode contatá-los para aumentá-lo.
+* **Etapas anteriores a inicialização**: Não suportado diretamente, você pode fazê-lo funcionar com o sistema Cron ou scripts adicionais.
+
+!!! note "Nota"
+ O Deta foi projetado para facilitar (e gratuitamente) a implantação rápida de aplicativos simples.
+
+ Ele pode simplificar vários casos de uso, mas, ao mesmo tempo, não suporta outros, como o uso de bancos de dados externos (além do próprio sistema de banco de dados NoSQL da Deta), máquinas virtuais personalizadas, etc.
+
+ Você pode ler mais detalhes na documentação da Deta para ver se é a escolha certa para você.
diff --git a/docs/pt/docs/features.md b/docs/pt/docs/features.md
index 20014fe2d..2b7836a6f 100644
--- a/docs/pt/docs/features.md
+++ b/docs/pt/docs/features.md
@@ -191,7 +191,7 @@ Com **FastAPI** você terá todos os recursos do **Pydantic** (já que FastAPI u
* Vai bem com o/a seu/sua **IDE/linter/cérebro**:
* Como as estruturas de dados do Pydantic são apenas instâncias de classes que você define, a auto completação, _linting_, _mypy_ e a sua intuição devem funcionar corretamente com seus dados validados.
* **Rápido**:
- * em _benchmarks_, o Pydantic é mais rápido que todas as outras bibliotecas testadas.
+ * em _benchmarks_, o Pydantic é mais rápido que todas as outras bibliotecas testadas.
* Valida **estruturas complexas**:
* Use modelos hierárquicos do Pydantic, `List` e `Dict` do `typing` do Python, etc.
* Validadores permitem que esquemas de dados complexos sejam limpos e facilmente definidos, conferidos e documentados como JSON Schema.
diff --git a/docs/pt/docs/help-fastapi.md b/docs/pt/docs/help-fastapi.md
new file mode 100644
index 000000000..d82ce3414
--- /dev/null
+++ b/docs/pt/docs/help-fastapi.md
@@ -0,0 +1,148 @@
+# Ajuda FastAPI - Obter Ajuda
+
+Você gosta do **FastAPI**?
+
+Você gostaria de ajudar o FastAPI, outros usários, e o autor?
+
+Ou você gostaria de obter ajuda relacionada ao **FastAPI**??
+
+Existem métodos muito simples de ajudar (A maioria das ajudas podem ser feitas com um ou dois cliques).
+
+E também existem vários modos de se conseguir ajuda.
+
+## Inscreva-se na newsletter
+
+Você pode se inscrever (pouco frequente) [**FastAPI e amigos** newsletter](/newsletter/){.internal-link target=_blank} para receber atualizações:
+
+* Notícias sobre FastAPI e amigos 🚀
+* Tutoriais 📝
+* Recursos ✨
+* Mudanças de última hora 🚨
+* Truques e dicas ✅
+
+## Siga o FastAPI no twitter
+
+Siga @fastapi no **Twitter** para receber as últimas notícias sobre o **FastAPI**. 🐦
+
+## Favorite o **FastAPI** no GitHub
+
+Você pode "favoritar" o FastAPI no GitHub (clicando na estrela no canto superior direito): https://github.com/tiangolo/fastapi. ⭐️
+
+Favoritando, outros usuários poderão encontrar mais facilmente e verão que já foi útil para muita gente.
+
+## Acompanhe novos updates no repositorio do GitHub
+
+Você pode "acompanhar" (watch) o FastAPI no GitHub (clicando no botão com um "olho" no canto superior direito): https://github.com/tiangolo/fastapi. 👀
+
+Podendo selecionar apenas "Novos Updates".
+
+Fazendo isto, serão enviadas notificações (em seu email) sempre que tiver novos updates (uma nova versão) com correções de bugs e novos recursos no **FastAPI**
+
+## Conect-se com o autor
+
+Você pode se conectar comigo (Sebastián Ramírez / `tiangolo`), o autor.
+
+Você pode:
+
+* Me siga no **GitHub**.
+ * Ver também outros projetos Open Source criados por mim que podem te ajudar.
+ * Me seguir para saber quando um novo projeto Open Source for criado.
+* Me siga no **Twitter**.
+ * Me dizer o motivo pelo o qual você está usando o FastAPI(Adoro ouvir esse tipo de comentário).
+ * Saber quando eu soltar novos anúncios ou novas ferramentas.
+ * Também é possivel seguir o @fastapi no Twitter (uma conta aparte).
+* Conect-se comigo no **Linkedin**.
+ * Saber quando eu fizer novos anúncios ou novas ferramentas (apesar de que uso o twitter com mais frequência 🤷♂).
+* Ler meus artigos (ou me seguir) no **Dev.to** ou no **Medium**.
+ * Ficar por dentro de novas ideias, artigos, e ferramentas criadas por mim.
+ * Me siga para saber quando eu publicar algo novo.
+
+## Tweete sobre **FastAPI**
+
+Tweete sobre o **FastAPI** e compartilhe comigo e com os outros o porque de gostar do FastAPI. 🎉
+
+Adoro ouvir sobre como o **FastAPI** é usado, o que você gosta nele, em qual projeto/empresa está sendo usado, etc.
+
+## Vote no FastAPI
+
+* Vote no **FastAPI** no Slant.
+* Vote no **FastAPI** no AlternativeTo.
+
+## Responda perguntas no GitHub
+
+Você pode acompanhar as perguntas existentes e tentar ajudar outros, . 🤓
+
+Ajudando a responder as questões de varias pessoas, você pode se tornar um [Expert em FastAPI](fastapi-people.md#experts){.internal-link target=_blank} oficial. 🎉
+
+## Acompanhe o repositório do GitHub
+
+Você pode "acompanhar" (watch) o FastAPI no GitHub (clicando no "olho" no canto superior direito): https://github.com/tiangolo/fastapi. 👀
+
+Se você selecionar "Acompanhando" (Watching) em vez de "Apenas Lançamentos" (Releases only) você receberá notificações quando alguém tiver uma nova pergunta.
+
+Assim podendo tentar ajudar a resolver essas questões.
+
+## Faça perguntas
+
+É possível criar uma nova pergunta no repositório do GitHub, por exemplo:
+
+* Faça uma **pergunta** ou pergunte sobre um **problema**.
+* Sugira novos **recursos**.
+
+**Nota**: Se você fizer uma pergunta, então eu gostaria de pedir que você também ajude os outros com suas respectivas perguntas. 😉
+
+## Crie um Pull Request
+
+É possível [contribuir](contributing.md){.internal-link target=_blank} no código fonte fazendo Pull Requests, por exemplo:
+
+* Para corrigir um erro de digitação que você encontrou na documentação.
+* Para compartilhar um artigo, video, ou podcast criados por você sobre o FastAPI editando este arquivo.
+ * Não se esqueça de adicionar o link no começo da seção correspondente.
+* Para ajudar [traduzir a documentação](contributing.md#translations){.internal-link target=_blank} para sua lingua.
+ * Também é possivel revisar as traduções já existentes.
+* Para propor novas seções na documentação.
+* Para corrigir um bug/questão.
+* Para adicionar um novo recurso.
+
+## Entre no chat
+
+Entre no 👥 server de conversa do Discord 👥 e conheça novas pessoas da comunidade
+do FastAPI.
+
+!!! dica
+ Para perguntas, pergunte nas questões do GitHub, lá tem um chance maior de você ser ajudado sobre o FastAPI [FastAPI Experts](fastapi-people.md#experts){.internal-link target=_blank}.
+
+ Use o chat apenas para outro tipo de assunto.
+
+Também existe o chat do Gitter, porém ele não possuí canais e recursos avançados, conversas são mais engessadas, por isso o Discord é mais recomendado.
+
+### Não faça perguntas no chat
+
+Tenha em mente que os chats permitem uma "conversa mais livre", dessa forma é muito fácil fazer perguntas que são muito genéricas e dificeís de responder, assim você pode acabar não sendo respondido.
+
+Nas questões do GitHub o template irá te guiar para que você faça a sua pergunta de um jeito mais correto, fazendo com que você receba respostas mais completas, e até mesmo que você mesmo resolva o problema antes de perguntar. E no GitHub eu garanto que sempre irei responder todas as perguntas, mesmo que leve um tempo. Eu pessoalmente não consigo fazer isso via chat. 😅
+
+Conversas no chat não são tão fáceis de serem encontrados quanto no GitHub, então questões e respostas podem se perder dentro da conversa. E apenas as que estão nas questões do GitHub contam para você se tornar um [Expert em FastAPI](fastapi-people.md#experts){.internal-link target=_blank}, então você receberá mais atenção nas questões do GitHub.
+
+Por outro lado, existem milhares de usuários no chat, então tem uma grande chance de você encontrar alguém para trocar uma idéia por lá em qualquer horário. 😄
+
+## Patrocine o autor
+
+Você também pode ajudar o autor financeiramente (eu) através do GitHub sponsors.
+
+Lá você pode me pagar um cafézinho ☕️ como agradecimento. 😄
+
+E você também pode se tornar um patrocinador Prata ou Ouro do FastAPI. 🏅🎉
+
+## Patrocine as ferramente que potencializam o FastAPI
+
+Como você viu na documentação, o FastAPI se apoia em nos gigantes, Starlette e Pydantic.
+
+Patrocine também:
+
+* Samuel Colvin (Pydantic)
+* Encode (Starlette, Uvicorn)
+
+---
+
+Muito Obrigado! 🚀
diff --git a/docs/pt/docs/index.md b/docs/pt/docs/index.md
index 848fff08a..b1d0c89f2 100644
--- a/docs/pt/docs/index.md
+++ b/docs/pt/docs/index.md
@@ -138,7 +138,7 @@ $ pip install uvicorn[standard]
* Crie um arquivo `main.py` com:
```Python
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
@@ -151,7 +151,7 @@ def read_root():
@app.get("/items/{item_id}")
-def read_item(item_id: int, q: Optional[str] = None):
+def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
```
@@ -161,7 +161,7 @@ def read_item(item_id: int, q: Optional[str] = None):
Se seu código utiliza `async` / `await`, use `async def`:
```Python hl_lines="9 14"
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
@@ -174,7 +174,7 @@ async def read_root():
@app.get("/items/{item_id}")
-async def read_item(item_id: int, q: Optional[str] = None):
+async def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
```
@@ -253,6 +253,8 @@ Agora modifique o arquivo `main.py` para receber um corpo para uma requisição
Declare o corpo utilizando tipos padrão Python, graças ao Pydantic.
```Python hl_lines="4 9-12 25-27"
+from typing import Union
+
from fastapi import FastAPI
from pydantic import BaseModel
@@ -262,7 +264,7 @@ app = FastAPI()
class Item(BaseModel):
name: str
price: float
- is_offer: Optional[bool] = None
+ is_offer: Union[bool] = None
@app.get("/")
@@ -271,7 +273,7 @@ def read_root():
@app.get("/items/{item_id}")
-def read_item(item_id: int, q: Optional[str] = None):
+def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
@@ -365,7 +367,7 @@ Voltando ao código do exemplo anterior, **FastAPI** irá:
* Como o parâmetro `q` é declarado com `= None`, ele é opcional.
* Sem o `None` ele poderia ser obrigatório (como o corpo no caso de `PUT`).
* Para requisições `PUT` para `/items/{item_id}`, lerá o corpo como JSON e:
- * Verifica que tem um atributo obrigatório `name` que deve ser `str`.
+ * Verifica que tem um atributo obrigatório `name` que deve ser `str`.
* Verifica que tem um atributo obrigatório `price` que deve ser `float`.
* Verifica que tem an atributo opcional `is_offer`, que deve ser `bool`, se presente.
* Tudo isso também funciona para objetos JSON profundamente aninhados.
@@ -434,7 +436,6 @@ Usados por Pydantic:
Usados por Starlette:
* requests - Necessário se você quiser utilizar o `TestClient`.
-* aiofiles - Necessário se você quiser utilizar o `FileResponse` ou `StaticFiles`.
* jinja2 - Necessário se você quiser utilizar a configuração padrão de templates.
* python-multipart - Necessário se você quiser suporte com "parsing" de formulário, com `request.form()`.
* itsdangerous - Necessário para suporte a `SessionMiddleware`.
diff --git a/docs/pt/docs/python-types.md b/docs/pt/docs/python-types.md
index df70afd40..9f12211c7 100644
--- a/docs/pt/docs/python-types.md
+++ b/docs/pt/docs/python-types.md
@@ -313,4 +313,3 @@ O importante é que, usando tipos padrão de Python, em um único local (em vez
!!! info "Informação"
Se você já passou por todo o tutorial e voltou para ver mais sobre os tipos, um bom recurso é a "cheat sheet" do `mypy` .
-
diff --git a/docs/pt/docs/tutorial/background-tasks.md b/docs/pt/docs/tutorial/background-tasks.md
new file mode 100644
index 000000000..625fa2b11
--- /dev/null
+++ b/docs/pt/docs/tutorial/background-tasks.md
@@ -0,0 +1,94 @@
+# Tarefas em segundo plano
+
+Você pode definir tarefas em segundo plano a serem executadas _ após _ retornar uma resposta.
+
+Isso é útil para operações que precisam acontecer após uma solicitação, mas que o cliente realmente não precisa esperar a operação ser concluída para receber a resposta.
+
+Isso inclui, por exemplo:
+
+- Envio de notificações por email após a realização de uma ação:
+ - Como conectar-se a um servidor de e-mail e enviar um e-mail tende a ser "lento" (vários segundos), você pode retornar a resposta imediatamente e enviar a notificação por e-mail em segundo plano.
+- Processando dados:
+ - Por exemplo, digamos que você receba um arquivo que deve passar por um processo lento, você pode retornar uma resposta de "Aceito" (HTTP 202) e processá-lo em segundo plano.
+
+## Usando `BackgroundTasks`
+
+Primeiro, importe `BackgroundTasks` e defina um parâmetro em sua _função de operação de caminho_ com uma declaração de tipo de `BackgroundTasks`:
+
+```Python hl_lines="1 13"
+{!../../../docs_src/background_tasks/tutorial001.py!}
+```
+
+O **FastAPI** criará o objeto do tipo `BackgroundTasks` para você e o passará como esse parâmetro.
+
+## Criar uma função de tarefa
+
+Crie uma função a ser executada como tarefa em segundo plano.
+
+É apenas uma função padrão que pode receber parâmetros.
+
+Pode ser uma função `async def` ou `def` normal, o **FastAPI** saberá como lidar com isso corretamente.
+
+Nesse caso, a função de tarefa gravará em um arquivo (simulando o envio de um e-mail).
+
+E como a operação de gravação não usa `async` e `await`, definimos a função com `def` normal:
+
+```Python hl_lines="6-9"
+{!../../../docs_src/background_tasks/tutorial001.py!}
+```
+
+## Adicionar a tarefa em segundo plano
+
+Dentro de sua _função de operação de caminho_, passe sua função de tarefa para o objeto _tarefas em segundo plano_ com o método `.add_task()`:
+
+```Python hl_lines="14"
+{!../../../docs_src/background_tasks/tutorial001.py!}
+```
+
+`.add_task()` recebe como argumentos:
+
+- Uma função de tarefa a ser executada em segundo plano (`write_notification`).
+- Qualquer sequência de argumentos que deve ser passada para a função de tarefa na ordem (`email`).
+- Quaisquer argumentos nomeados que devem ser passados para a função de tarefa (`mensagem = "alguma notificação"`).
+
+## Injeção de dependência
+
+Usar `BackgroundTasks` também funciona com o sistema de injeção de dependência, você pode declarar um parâmetro do tipo `BackgroundTasks` em vários níveis: em uma _função de operação de caminho_, em uma dependência (confiável), em uma subdependência, etc.
+
+O **FastAPI** sabe o que fazer em cada caso e como reutilizar o mesmo objeto, de forma que todas as tarefas em segundo plano sejam mescladas e executadas em segundo plano posteriormente:
+
+```Python hl_lines="13 15 22 25"
+{!../../../docs_src/background_tasks/tutorial002.py!}
+```
+
+Neste exemplo, as mensagens serão gravadas no arquivo `log.txt` _após_ o envio da resposta.
+
+Se houver uma consulta na solicitação, ela será gravada no log em uma tarefa em segundo plano.
+
+E então outra tarefa em segundo plano gerada na _função de operação de caminho_ escreverá uma mensagem usando o parâmetro de caminho `email`.
+
+## Detalhes técnicos
+
+A classe `BackgroundTasks` vem diretamente de `starlette.background`.
+
+Ela é importada/incluída diretamente no FastAPI para que você possa importá-la do `fastapi` e evitar a importação acidental da alternativa `BackgroundTask` (sem o `s` no final) de `starlette.background`.
+
+Usando apenas `BackgroundTasks` (e não `BackgroundTask`), é então possível usá-la como um parâmetro de _função de operação de caminho_ e deixar o **FastAPI** cuidar do resto para você, assim como ao usar o objeto `Request` diretamente.
+
+Ainda é possível usar `BackgroundTask` sozinho no FastAPI, mas você deve criar o objeto em seu código e retornar uma Starlette `Response` incluindo-o.
+
+Você pode ver mais detalhes na documentação oficiais da Starlette para tarefas em segundo plano .
+
+## Ressalva
+
+Se você precisa realizar cálculos pesados em segundo plano e não necessariamente precisa que seja executado pelo mesmo processo (por exemplo, você não precisa compartilhar memória, variáveis, etc), você pode se beneficiar do uso de outras ferramentas maiores, como Celery .
+
+Eles tendem a exigir configurações mais complexas, um gerenciador de fila de mensagens/tarefas, como RabbitMQ ou Redis, mas permitem que você execute tarefas em segundo plano em vários processos e, especialmente, em vários servidores.
+
+Para ver um exemplo, verifique os [Geradores de projeto](../project-generation.md){.internal-link target=\_blank}, todos incluem celery já configurado.
+
+Mas se você precisa acessar variáveis e objetos do mesmo aplicativo **FastAPI**, ou precisa realizar pequenas tarefas em segundo plano (como enviar uma notificação por e-mail), você pode simplesmente usar `BackgroundTasks`.
+
+## Recapitulando
+
+Importe e use `BackgroundTasks` com parâmetros em _funções de operação de caminho_ e dependências para adicionar tarefas em segundo plano.
diff --git a/docs/pt/docs/tutorial/body.md b/docs/pt/docs/tutorial/body.md
new file mode 100644
index 000000000..99e05ab77
--- /dev/null
+++ b/docs/pt/docs/tutorial/body.md
@@ -0,0 +1,165 @@
+# Corpo da Requisição
+
+Quando você precisa enviar dados de um cliente (como de um navegador web) para sua API, você o envia como um **corpo da requisição**.
+
+O corpo da **requisição** é a informação enviada pelo cliente para sua API. O corpo da **resposta** é a informação que sua API envia para o cliente.
+
+Sua API quase sempre irá enviar um corpo na **resposta**. Mas os clientes não necessariamente precisam enviar um corpo em toda **requisição**.
+
+Para declarar um corpo da **requisição**, você utiliza os modelos do Pydantic com todos os seus poderes e benefícios.
+
+!!! info "Informação"
+ Para enviar dados, você deve usar utilizar um dos métodos: `POST` (Mais comum), `PUT`, `DELETE` ou `PATCH`.
+
+ Enviar um corpo em uma requisição `GET` não tem um comportamento definido nas especificações, porém é suportado pelo FastAPI, apenas para casos de uso bem complexos/extremos.
+
+ Como é desencorajado, a documentação interativa com Swagger UI não irá mostrar a documentação para o corpo da requisição para um `GET`, e proxies que intermediarem podem não suportar o corpo da requisição.
+
+## Importe o `BaseModel` do Pydantic
+
+Primeiro, você precisa importar `BaseModel` do `pydantic`:
+
+```Python hl_lines="4"
+{!../../../docs_src/body/tutorial001.py!}
+```
+
+## Crie seu modelo de dados
+
+Então você declara seu modelo de dados como uma classe que herda `BaseModel`.
+
+Utilize os tipos Python padrão para todos os atributos:
+
+```Python hl_lines="7-11"
+{!../../../docs_src/body/tutorial001.py!}
+```
+
+Assim como quando declaramos parâmetros de consulta, quando um atributo do modelo possui um valor padrão, ele se torna opcional. Caso contrário, se torna obrigatório. Use `None` para torná-lo opcional.
+
+Por exemplo, o modelo acima declara um JSON "`object`" (ou `dict` no Python) como esse:
+
+```JSON
+{
+ "name": "Foo",
+ "description": "Uma descrição opcional",
+ "price": 45.2,
+ "tax": 3.5
+}
+```
+
+...como `description` e `tax` são opcionais (Com um valor padrão de `None`), esse JSON "`object`" também é válido:
+
+```JSON
+{
+ "name": "Foo",
+ "price": 45.2
+}
+```
+
+## Declare como um parâmetro
+
+Para adicionar o corpo na *função de operação de rota*, declare-o da mesma maneira que você declarou parâmetros de rota e consulta:
+
+```Python hl_lines="18"
+{!../../../docs_src/body/tutorial001.py!}
+```
+
+...E declare o tipo como o modelo que você criou, `Item`.
+
+## Resultados
+
+Apenas com esse declaração de tipos do Python, o **FastAPI** irá:
+
+* Ler o corpo da requisição como um JSON.
+* Converter os tipos correspondentes (se necessário).
+* Validar os dados.
+ * Se algum dados for inválido, irá retornar um erro bem claro, indicando exatamente onde e o que está incorreto.
+* Entregar a você a informação recebida no parâmetro `item`.
+ * Como você o declarou na função como do tipo `Item`, você também terá o suporte do editor (completação, etc) para todos os atributos e seus tipos.
+* Gerar um Esquema JSON com as definições do seu modelo, você também pode utilizá-lo em qualquer lugar que quiser, se fizer sentido para seu projeto.
+* Esses esquemas farão parte do esquema OpenAPI, e utilizados nas UIs de documentação automática.
+
+## Documentação automática
+
+Os esquemas JSON dos seus modelos farão parte do esquema OpenAPI gerado para sua aplicação, e aparecerão na documentação interativa da API:
+
+
+
+E também serão utilizados em cada *função de operação de rota* que utilizá-los:
+
+
+
+## Suporte do editor de texto:
+
+No seu editor de texto, dentro da função você receberá dicas de tipos e completação em todo lugar (isso não aconteceria se você recebesse um `dict` em vez de um modelo Pydantic):
+
+
+
+Você também poderá receber verificações de erros para operações de tipos incorretas:
+
+
+
+Isso não é por acaso, todo o framework foi construído em volta deste design.
+
+E foi imensamente testado na fase de design, antes de qualquer implementação, para garantir que funcionaria para todos os editores de texto.
+
+Houveram mudanças no próprio Pydantic para que isso fosse possível.
+
+As capturas de tela anteriores foram capturas no Visual Studio Code.
+
+Mas você terá o mesmo suporte do editor no PyCharm e na maioria dos editores Python:
+
+
+
+!!! tip "Dica"
+ Se você utiliza o PyCharm como editor, você pode utilizar o Plugin do Pydantic para o PyCharm .
+
+ Melhora o suporte do editor para seus modelos Pydantic com::
+
+ * completação automática
+ * verificação de tipos
+ * refatoração
+ * buscas
+ * inspeções
+
+## Use o modelo
+
+Dentro da função, você pode acessar todos os atributos do objeto do modelo diretamente:
+
+```Python hl_lines="21"
+{!../../../docs_src/body/tutorial002.py!}
+```
+
+## Corpo da requisição + parâmetros de rota
+
+Você pode declarar parâmetros de rota e corpo da requisição ao mesmo tempo.
+
+O **FastAPI** irá reconhecer que os parâmetros da função que combinam com parâmetros de rota devem ser **retirados da rota**, e parâmetros da função que são declarados como modelos Pydantic sejam **retirados do corpo da requisição**.
+
+```Python hl_lines="17-18"
+{!../../../docs_src/body/tutorial003.py!}
+```
+
+## Corpo da requisição + parâmetros de rota + parâmetros de consulta
+
+Você também pode declarar parâmetros de **corpo**, **rota** e **consulta**, ao mesmo tempo.
+
+O **FastAPI** irá reconhecer cada um deles e retirar a informação do local correto.
+
+```Python hl_lines="18"
+{!../../../docs_src/body/tutorial004.py!}
+```
+
+Os parâmetros da função serão reconhecidos conforme abaixo:
+
+* Se o parâmetro também é declarado na **rota**, será utilizado como um parâmetro de rota.
+* Se o parâmetro é de um **tipo único** (como `int`, `float`, `str`, `bool`, etc) será interpretado como um parâmetro de **consulta**.
+* Se o parâmetro é declarado como um **modelo Pydantic**, será interpretado como o **corpo** da requisição.
+
+!!! note "Observação"
+ O FastAPI saberá que o valor de `q` não é obrigatório por causa do valor padrão `= None`.
+
+ O `Union` em `Union[str, None]` não é utilizado pelo FastAPI, mas permite ao seu editor de texto lhe dar um suporte melhor e detectar erros.
+
+## Sem o Pydantic
+
+Se você não quer utilizar os modelos Pydantic, você também pode utilizar o parâmetro **Body**. Veja a documentação para [Body - Parâmetros múltiplos: Valores singulares no body](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}.
diff --git a/docs/pt/docs/tutorial/cookie-params.md b/docs/pt/docs/tutorial/cookie-params.md
new file mode 100644
index 000000000..1a60e3571
--- /dev/null
+++ b/docs/pt/docs/tutorial/cookie-params.md
@@ -0,0 +1,33 @@
+# Parâmetros de Cookie
+
+Você pode definir parâmetros de Cookie da mesma maneira que define paramêtros com `Query` e `Path`.
+
+## Importe `Cookie`
+
+Primeiro importe `Cookie`:
+
+```Python hl_lines="3"
+{!../../../docs_src/cookie_params/tutorial001.py!}
+```
+
+## Declare parâmetros de `Cookie`
+
+Então declare os paramêtros de cookie usando a mesma estrutura que em `Path` e `Query`.
+
+O primeiro valor é o valor padrão, você pode passar todas as validações adicionais ou parâmetros de anotação:
+
+```Python hl_lines="9"
+{!../../../docs_src/cookie_params/tutorial001.py!}
+```
+
+!!! note "Detalhes Técnicos"
+ `Cookie` é uma classe "irmã" de `Path` e `Query`. Ela também herda da mesma classe em comum `Param`.
+
+ Mas lembre-se que quando você importa `Query`, `Path`, `Cookie` e outras de `fastapi`, elas são na verdade funções que retornam classes especiais.
+
+!!! info "Informação"
+ Para declarar cookies, você precisa usar `Cookie`, caso contrário, os parâmetros seriam interpretados como parâmetros de consulta.
+
+## Recapitulando
+
+Declare cookies com `Cookie`, usando o mesmo padrão comum que utiliza-se em `Query` e `Path`.
diff --git a/docs/pt/docs/tutorial/extra-data-types.md b/docs/pt/docs/tutorial/extra-data-types.md
new file mode 100644
index 000000000..e4b9913dc
--- /dev/null
+++ b/docs/pt/docs/tutorial/extra-data-types.md
@@ -0,0 +1,66 @@
+# Tipos de dados extras
+
+Até agora, você tem usado tipos de dados comuns, tais como:
+
+* `int`
+* `float`
+* `str`
+* `bool`
+
+Mas você também pode usar tipos de dados mais complexos.
+
+E você ainda terá os mesmos recursos que viu até agora:
+
+* Ótimo suporte do editor.
+* Conversão de dados das requisições recebidas.
+* Conversão de dados para os dados da resposta.
+* Validação de dados.
+* Anotação e documentação automáticas.
+
+## Outros tipos de dados
+
+Aqui estão alguns dos tipos de dados adicionais que você pode usar:
+
+* `UUID`:
+ * Um "Identificador Universalmente Único" padrão, comumente usado como ID em muitos bancos de dados e sistemas.
+ * Em requisições e respostas será representado como uma `str`.
+* `datetime.datetime`:
+ * O `datetime.datetime` do Python.
+ * Em requisições e respostas será representado como uma `str` no formato ISO 8601, exemplo: `2008-09-15T15:53:00+05:00`.
+* `datetime.date`:
+ * O `datetime.date` do Python.
+ * Em requisições e respostas será representado como uma `str` no formato ISO 8601, exemplo: `2008-09-15`.
+* `datetime.time`:
+ * O `datetime.time` do Python.
+ * Em requisições e respostas será representado como uma `str` no formato ISO 8601, exemplo: `14:23:55.003`.
+* `datetime.timedelta`:
+ * O `datetime.timedelta` do Python.
+ * Em requisições e respostas será representado como um `float` de segundos totais.
+ * O Pydantic também permite representá-lo como uma "codificação ISO 8601 diferença de tempo", cheque a documentação para mais informações.
+* `frozenset`:
+ * Em requisições e respostas, será tratado da mesma forma que um `set`:
+ * Nas requisições, uma lista será lida, eliminando duplicadas e convertendo-a em um `set`.
+ * Nas respostas, o `set` será convertido para uma `list`.
+ * O esquema gerado vai especificar que os valores do `set` são unicos (usando o `uniqueItems` do JSON Schema).
+* `bytes`:
+ * O `bytes` padrão do Python.
+ * Em requisições e respostas será representado como uma `str`.
+ * O esquema gerado vai especificar que é uma `str` com o "formato" `binary`.
+* `Decimal`:
+ * O `Decimal` padrão do Python.
+ * Em requisições e respostas será representado como um `float`.
+* Você pode checar todos os tipos de dados válidos do Pydantic aqui: Tipos de dados do Pydantic.
+
+## Exemplo
+
+Aqui está um exemplo de *operação de rota* com parâmetros utilizando-se de alguns dos tipos acima.
+
+```Python hl_lines="1 3 12-16"
+{!../../../docs_src/extra_data_types/tutorial001.py!}
+```
+
+Note que os parâmetros dentro da função tem seu tipo de dados natural, e você pode, por exemplo, realizar manipulações normais de data, como:
+
+```Python hl_lines="18-19"
+{!../../../docs_src/extra_data_types/tutorial001.py!}
+```
diff --git a/docs/pt/docs/tutorial/path-params.md b/docs/pt/docs/tutorial/path-params.md
index 20913a564..5de3756ed 100644
--- a/docs/pt/docs/tutorial/path-params.md
+++ b/docs/pt/docs/tutorial/path-params.md
@@ -72,7 +72,7 @@ O mesmo erro apareceria se você tivesse fornecido um `float` ao invés de um `i
## Documentação
-Quando você abrir o seu navegador em http://127.0.0.1:8000/docs, você verá de forma automática e interativa a documtação da API como:
+Quando você abrir o seu navegador em http://127.0.0.1:8000/docs, você verá de forma automática e interativa a documentação da API como:
diff --git a/docs/pt/docs/tutorial/query-params-str-validations.md b/docs/pt/docs/tutorial/query-params-str-validations.md
index baac5f493..9a9e071db 100644
--- a/docs/pt/docs/tutorial/query-params-str-validations.md
+++ b/docs/pt/docs/tutorial/query-params-str-validations.md
@@ -8,12 +8,12 @@ Vamos utilizar essa aplicação como exemplo:
{!../../../docs_src/query_params_str_validations/tutorial001.py!}
```
-O parâmetro de consulta `q` é do tipo `Optional[str]`, o que significa que é do tipo `str` mas que também pode ser `None`, e de fato, o valor padrão é `None`, então o FastAPI saberá que não é obrigatório.
+O parâmetro de consulta `q` é do tipo `Union[str, None]`, o que significa que é do tipo `str` mas que também pode ser `None`, e de fato, o valor padrão é `None`, então o FastAPI saberá que não é obrigatório.
!!! note "Observação"
O FastAPI saberá que o valor de `q` não é obrigatório por causa do valor padrão `= None`.
- O `Optional` em `Optional[str]` não é usado pelo FastAPI, mas permitirá que seu editor lhe dê um melhor suporte e detecte erros.
+ O `Union` em `Union[str, None]` não é usado pelo FastAPI, mas permitirá que seu editor lhe dê um melhor suporte e detecte erros.
## Validação adicional
@@ -35,18 +35,18 @@ Agora utilize-o como valor padrão do seu parâmetro, definindo o parâmetro `ma
{!../../../docs_src/query_params_str_validations/tutorial002.py!}
```
-Note que substituímos o valor padrão de `None` para `Query(None)`, o primeiro parâmetro de `Query` serve para o mesmo propósito: definir o valor padrão do parâmetro.
+Note que substituímos o valor padrão de `None` para `Query(default=None)`, o primeiro parâmetro de `Query` serve para o mesmo propósito: definir o valor padrão do parâmetro.
Então:
```Python
-q: Optional[str] = Query(None)
+q: Union[str, None] = Query(default=None)
```
...Torna o parâmetro opcional, da mesma maneira que:
```Python
-q: Optional[str] = None
+q: Union[str, None] = None
```
Mas o declara explicitamente como um parâmetro de consulta.
@@ -61,17 +61,17 @@ Mas o declara explicitamente como um parâmetro de consulta.
Ou com:
```Python
- = Query(None)
+ = Query(default=None)
```
E irá utilizar o `None` para detectar que o parâmetro de consulta não é obrigatório.
- O `Optional` é apenas para permitir que seu editor de texto lhe dê um melhor suporte.
+ O `Union` é apenas para permitir que seu editor de texto lhe dê um melhor suporte.
Então, podemos passar mais parâmetros para `Query`. Neste caso, o parâmetro `max_length` que se aplica a textos:
```Python
-q: str = Query(None, max_length=50)
+q: str = Query(default=None, max_length=50)
```
Isso irá validar os dados, mostrar um erro claro quando os dados forem inválidos, e documentar o parâmetro na *operação de rota* do esquema OpenAPI..
@@ -80,7 +80,7 @@ Isso irá validar os dados, mostrar um erro claro quando os dados forem inválid
Você também pode incluir um parâmetro `min_length`:
-```Python hl_lines="9"
+```Python hl_lines="10"
{!../../../docs_src/query_params_str_validations/tutorial003.py!}
```
@@ -88,7 +88,7 @@ Você também pode incluir um parâmetro `min_length`:
Você pode definir uma expressão regular que combine com um padrão esperado pelo parâmetro:
-```Python hl_lines="10"
+```Python hl_lines="11"
{!../../../docs_src/query_params_str_validations/tutorial004.py!}
```
@@ -126,13 +126,13 @@ q: str
em vez desta:
```Python
-q: Optional[str] = None
+q: Union[str, None] = None
```
Mas agora nós o estamos declarando como `Query`, conforme abaixo:
```Python
-q: Optional[str] = Query(None, min_length=3)
+q: Union[str, None] = Query(default=None, min_length=3)
```
Então, quando você precisa declarar um parâmetro obrigatório utilizando o `Query`, você pode utilizar `...` como o primeiro argumento:
diff --git a/docs/pt/mkdocs.yml b/docs/pt/mkdocs.yml
index 4861602e4..2bb0b568d 100644
--- a/docs/pt/mkdocs.yml
+++ b/docs/pt/mkdocs.yml
@@ -5,13 +5,15 @@ theme:
name: material
custom_dir: overrides
palette:
- - scheme: default
+ - media: "(prefers-color-scheme: light)"
+ scheme: default
primary: teal
accent: amber
toggle:
icon: material/lightbulb
name: Switch to light mode
- - scheme: slate
+ - media: "(prefers-color-scheme: dark)"
+ scheme: slate
primary: teal
accent: amber
toggle:
@@ -60,8 +62,11 @@ nav:
- tutorial/index.md
- tutorial/first-steps.md
- tutorial/path-params.md
+ - tutorial/body.md
- tutorial/body-fields.md
+ - tutorial/extra-data-types.md
- tutorial/query-params-str-validations.md
+ - tutorial/cookie-params.md
- Segurança:
- tutorial/security/index.md
- Guia de Usuário Avançado:
@@ -70,10 +75,12 @@ nav:
- deployment/index.md
- deployment/versions.md
- deployment/https.md
+ - deployment/deta.md
- alternatives.md
- history-design-future.md
- external-links.md
- benchmarks.md
+- help-fastapi.md
markdown_extensions:
- toc:
permalink: true
diff --git a/docs/ru/docs/async.md b/docs/ru/docs/async.md
new file mode 100644
index 000000000..4c44fc22d
--- /dev/null
+++ b/docs/ru/docs/async.md
@@ -0,0 +1,505 @@
+# Конкурентность и async / await
+
+Здесь приведена подробная информация об использовании синтаксиса `async def` при написании *функций обработки пути*, а также рассмотрены основы асинхронного программирования, конкурентности и параллелизма.
+
+## Нет времени?
+
+TL;DR:
+
+Допустим, вы используете сторонюю библиотеку, которая требует вызова с ключевым словом `await`:
+
+```Python
+results = await some_library()
+```
+
+В этом случае *функции обработки пути* необходимо объявлять с использованием синтаксиса `async def`:
+
+```Python hl_lines="2"
+@app.get('/')
+async def read_results():
+ results = await some_library()
+ return results
+```
+
+!!! note
+ `await` можно использовать только внутри функций, объявленных с использованием `async def`.
+
+---
+
+Если вы обращаетесь к сторонней библиотеке, которая с чем-то взаимодействует
+(с базой данных, API, файловой системой и т. д.), и не имеет поддержки синтаксиса `await`
+(что относится сейчас к большинству библиотек для работы с базами данных), то
+объявляйте *функции обработки пути* обычным образом с помощью `def`, например:
+
+```Python hl_lines="2"
+@app.get('/')
+def results():
+ results = some_library()
+ return results
+```
+
+---
+
+Если вашему приложению (странным образом) не нужно ни с чем взаимодействовать и, соответственно,
+ожидать ответа, используйте `async def`.
+
+---
+
+Если вы не уверены, используйте обычный синтаксис `def`.
+
+---
+
+**Примечание**: при необходимости можно смешивать `def` и `async def` в *функциях обработки пути*
+и использовать в каждом случае наиболее подходящий синтаксис. А FastAPI сделает с этим всё, что нужно.
+
+В любом из описанных случаев FastAPI работает асинхронно и очень быстро.
+
+Однако придерживаясь указанных советов, можно получить дополнительную оптимизацию производительности.
+
+## Технические подробности
+
+Современные версии Python поддерживают разработку так называемого **"асинхронного кода"** посредством написания **"сопрограмм"** с использованием синтаксиса **`async` и `await`**.
+
+Ниже разберём эту фразу по частям:
+
+* **Асинхронный код**
+* **`async` и `await`**
+* **Сопрограммы**
+
+## Асинхронный код
+
+Асинхронный код означает, что в языке 💬 есть возможность сообщить машине / программе 🤖,
+что в определённой точке кода ей 🤖 нужно будет ожидать завершения выполнения *чего-то ещё* в другом месте. Допустим это *что-то ещё* называется "медленный файл" 📝.
+
+И пока мы ждём завершения работы с "медленным файлом" 📝, компьютер может переключиться для выполнения других задач.
+
+Но при каждой возможности компьютер / программа 🤖 будет возвращаться обратно. Например, если он 🤖 опять окажется в режиме ожидания, или когда закончит всю работу. В этом случае компьютер 🤖 проверяет, не завершена ли какая-нибудь из текущих задач.
+
+Потом он 🤖 берёт первую выполненную задачу (допустим, наш "медленный файл" 📝) и продолжает работу, производя с ней необходимые действия.
+
+Вышеупомянутое "что-то ещё", завершения которого приходится ожидать, обычно относится к достаточно "медленным" операциям I/O (по сравнению со скоростью работы процессора и оперативной памяти), например:
+
+* отправка данных от клиента по сети
+* получение клиентом данных, отправленных вашей программой по сети
+* чтение системой содержимого файла с диска и передача этих данных программе
+* запись на диск данных, которые программа передала системе
+* обращение к удалённому API
+* ожидание завершения операции с базой данных
+* получение результатов запроса к базе данных
+* и т. д.
+
+Поскольку в основном время тратится на ожидание выполнения операций I/O,
+их обычно называют операциями, ограниченными скоростью ввода-вывода.
+
+Код называют "асинхронным", потому что компьютеру / программе не требуется "синхронизироваться" с медленной задачей и,
+будучи в простое, ожидать момента её завершения, с тем чтобы забрать результат и продолжить работу.
+
+Вместо этого в "асинхронной" системе завершённая задача может немного подождать (буквально несколько микросекунд),
+пока компьютер / программа занимается другими важными вещами, с тем чтобы потом вернуться,
+забрать результаты выполнения и начать их обрабатывать.
+
+"Синхронное" исполнение (в противовес "асинхронному") также называют "последовательным",
+потому что компьютер / программа последовательно выполняет все требуемые шаги перед тем, как перейти к следующей задаче,
+даже если в процессе приходится ждать.
+
+### Конкурентность и бургеры
+
+Тот **асинхронный** код, о котором идёт речь выше, иногда называют **"конкурентностью"**. Она отличается от **"параллелизма"**.
+
+Да, **конкурентность** и **параллелизм** подразумевают, что разные вещи происходят примерно в одно время.
+
+Но внутреннее устройство **конкурентности** и **параллелизма** довольно разное.
+
+Чтобы это понять, представьте такую картину:
+
+### Конкурентные бургеры
+
+
+
+Вы идёте со своей возлюбленной 😍 в фастфуд 🍔 и становитесь в очередь, в это время кассир 💁 принимает заказы у посетителей перед вами.
+
+Когда наконец подходит очередь, вы заказываете парочку самых вкусных и навороченных бургеров 🍔, один для своей возлюбленной 😍, а другой себе.
+
+Отдаёте деньги 💸.
+
+Кассир 💁 что-то говорит поварам на кухне 👨🍳, теперь они знают, какие бургеры нужно будет приготовить 🍔
+(но пока они заняты бургерами предыдущих клиентов).
+
+Кассир 💁 отдаёт вам чек с номером заказа.
+
+В ожидании еды вы идёте со своей возлюбленной 😍 выбрать столик, садитесь и довольно продолжительное время общаетесь 😍
+(поскольку ваши бургеры самые навороченные, готовятся они не так быстро ✨🍔✨).
+
+Сидя за столиком с возлюбленной 😍 в ожидании бургеров 🍔, вы отлично проводите время,
+восхищаясь её великолепием, красотой и умом ✨😍✨.
+
+Всё ещё ожидая заказ и болтая со своей возлюбленной 😍, время от времени вы проверяете,
+какой номер горит над прилавком, и не подошла ли уже ваша очередь.
+
+И вот наконец настаёт этот момент, и вы идёте к стойке, чтобы забрать бургеры 🍔 и вернуться за столик.
+
+Вы со своей возлюбленной 😍 едите бургеры 🍔 и отлично проводите время ✨.
+
+---
+
+А теперь представьте, что в этой небольшой истории вы компьютер / программа 🤖.
+
+В очереди вы просто глазеете по сторонам 😴, ждёте и ничего особо "продуктивного" не делаете.
+Но очередь движется довольно быстро, поскольку кассир 💁 только принимает заказы (а не занимается приготовлением еды), так что ничего страшного.
+
+Когда подходит очередь вы наконец предпринимаете "продуктивные" действия 🤓: просматриваете меню, выбираете в нём что-то, узнаёте, что хочет ваша возлюбленная 😍, собираетесь оплатить 💸, смотрите, какую достали карту, проверяете, чтобы с вас списали верную сумму, и что в заказе всё верно и т. д.
+
+И хотя вы всё ещё не получили бургеры 🍔, ваша работа с кассиром 💁 ставится "на паузу" ⏸,
+поскольку теперь нужно ждать 🕙, когда заказ приготовят.
+
+Но отойдя с номерком от прилавка, вы садитесь за столик и можете переключить 🔀 внимание
+на свою возлюбленную 😍 и "работать" ⏯ 🤓 уже над этим. И вот вы снова очень
+"продуктивны" 🤓, мило болтаете вдвоём и всё такое 😍.
+
+В какой-то момент кассир 💁 поместит на табло ваш номер, подразумевая, что бургеры готовы 🍔, но вы не станете подскакивать как умалишённый, лишь только увидев на экране свою очередь. Вы уверены, что ваши бургеры 🍔 никто не утащит, ведь у вас свой номерок, а у других свой.
+
+Поэтому вы подождёте, пока возлюбленная 😍 закончит рассказывать историю (закончите текущую работу ⏯ / задачу в обработке 🤓),
+и мило улыбнувшись, скажете, что идёте забирать заказ ⏸.
+
+И вот вы подходите к стойке 🔀, к первоначальной задаче, которая уже завершена ⏯, берёте бургеры 🍔, говорите спасибо и относите заказ за столик. На этом заканчивается этап / задача взаимодействия с кассой ⏹.
+В свою очередь порождается задача "поедание бургеров" 🔀 ⏯, но предыдущая ("получение бургеров") завершена ⏹.
+
+### Параллельные бургеры
+
+Теперь представим, что вместо бургерной "Конкурентные бургеры" вы решили сходить в "Параллельные бургеры".
+
+И вот вы идёте со своей возлюбленной 😍 отведать параллельного фастфуда 🍔.
+
+Вы становитесь в очередь пока несколько (пусть будет 8) кассиров, которые по совместительству ещё и повары 👩🍳👨🍳👩🍳👨🍳👩🍳👨🍳👩🍳👨🍳, принимают заказы у посетителей перед вами.
+
+При этом клиенты не отходят от стойки и ждут 🕙 получения еды, поскольку каждый
+из 8 кассиров идёт на кухню готовить бургеры 🍔, а только потом принимает следующий заказ.
+
+Наконец настаёт ваша очередь, и вы просите два самых навороченных бургера 🍔, один для дамы сердца 😍, а другой себе.
+
+Ни о чём не жалея, расплачиваетесь 💸.
+
+И кассир уходит на кухню 👨🍳.
+
+Вам приходится ждать перед стойкой 🕙, чтобы никто по случайности не забрал ваши бургеры 🍔, ведь никаких номерков у вас нет.
+
+Поскольку вы с возлюбленной 😍 хотите получить заказ вовремя 🕙, и следите за тем, чтобы никто не вклинился в очередь,
+у вас не получается уделять должного внимание своей даме сердца 😞.
+
+Это "синхронная" работа, вы "синхронизированы" с кассиром/поваром 👨🍳. Приходится ждать 🕙 у стойки,
+когда кассир/повар 👨🍳 закончит делать бургеры 🍔 и вручит вам заказ, иначе его случайно может забрать кто-то другой.
+
+Наконец кассир/повар 👨🍳 возвращается с бургерами 🍔 после невыносимо долгого ожидания 🕙 за стойкой.
+
+Вы скорее забираете заказ 🍔 и идёте с возлюбленной 😍 за столик.
+
+Там вы просто едите эти бургеры, и на этом всё 🍔 ⏹.
+
+Вам не особо удалось пообщаться, потому что большую часть времени 🕙 пришлось провести у кассы 😞.
+
+---
+
+В описанном сценарии вы компьютер / программа 🤖 с двумя исполнителями (вы и ваша возлюбленная 😍),
+на протяжении долгого времени 🕙 вы оба уделяете всё внимание ⏯ задаче "ждать на кассе".
+
+В этом ресторане быстрого питания 8 исполнителей (кассиров/поваров) 👩🍳👨🍳👩🍳👨🍳👩🍳👨🍳👩🍳👨🍳.
+Хотя в бургерной конкурентного типа было всего два (один кассир и один повар) 💁 👨🍳.
+
+Несмотря на обилие работников, опыт в итоге получился не из лучших 😞.
+
+---
+
+Так бы выглядел аналог истории про бургерную 🍔 в "параллельном" мире.
+
+Вот более реалистичный пример. Представьте себе банк.
+
+До недавних пор в большинстве банков было несколько кассиров 👨💼👨💼👨💼👨💼 и длинные очереди 🕙🕙🕙🕙🕙🕙🕙🕙.
+
+Каждый кассир обслуживал одного клиента, потом следующего 👨💼⏯.
+
+Нужно было долгое время 🕙 стоять перед окошком вместе со всеми, иначе пропустишь свою очередь.
+
+Сомневаюсь, что у вас бы возникло желание прийти с возлюбленной 😍 в банк 🏦 оплачивать налоги.
+
+### Выводы о бургерах
+
+В нашей истории про поход в фастфуд за бургерами приходится много ждать 🕙,
+поэтому имеет смысл организовать конкурентную систему ⏸🔀⏯.
+
+И то же самое с большинством веб-приложений.
+
+Пользователей очень много, но ваш сервер всё равно вынужден ждать 🕙 запросы по их слабому интернет-соединению.
+
+Потом снова ждать 🕙, пока вернётся ответ.
+
+
+Это ожидание 🕙 измеряется микросекундами, но если всё сложить, то набегает довольно много времени.
+
+Вот почему есть смысл использовать асинхронное ⏸🔀⏯ программирование при построении веб-API.
+
+Большинство популярных фреймворков (включая Flask и Django) создавались
+до появления в Python новых возможностей асинхронного программирования. Поэтому
+их можно разворачивать с поддержкой параллельного исполнения или асинхронного
+программирования старого типа, которое не настолько эффективно.
+
+При том, что основная спецификация асинхронного взаимодействия Python с веб-сервером
+(ASGI)
+была разработана командой Django для внедрения поддержки веб-сокетов.
+
+Именно асинхронность сделала NodeJS таким популярным (несмотря на то, что он не параллельный),
+и в этом преимущество Go как языка программирования.
+
+И тот же уровень производительности даёт **FastAPI**.
+
+Поскольку можно использовать преимущества параллелизма и асинхронности вместе,
+вы получаете производительность лучше, чем у большинства протестированных NodeJS фреймворков
+и на уровне с Go, который является компилируемым языком близким к C (всё благодаря Starlette).
+
+### Получается, конкурентность лучше параллелизма?
+
+Нет! Мораль истории совсем не в этом.
+
+Конкурентность отличается от параллелизма. Она лучше в **конкретных** случаях, где много времени приходится на ожидание.
+Вот почему она зачастую лучше параллелизма при разработке веб-приложений. Но это не значит, что конкурентность лучше в любых сценариях.
+
+Давайте посмотрим с другой стороны, представьте такую картину:
+
+> Вам нужно убраться в большом грязном доме.
+
+*Да, это вся история*.
+
+---
+
+Тут не нужно нигде ждать 🕙, просто есть куча работы в разных частях дома.
+
+Можно организовать очередь как в примере с бургерами, сначала гостиная, потом кухня,
+но это ни на что не повлияет, поскольку вы нигде не ждёте 🕙, а просто трёте да моете.
+
+И понадобится одинаковое количество времени с очередью (конкурентностью) и без неё,
+и работы будет сделано тоже одинаковое количество.
+
+Однако в случае, если бы вы могли привести 8 бывших кассиров/поваров, а ныне уборщиков 👩🍳👨🍳👩🍳👨🍳👩🍳👨🍳👩🍳👨🍳,
+и каждый из них (вместе с вами) взялся бы за свой участок дома,
+с такой помощью вы бы закончили намного быстрее, делая всю работу **параллельно**.
+
+В описанном сценарии каждый уборщик (включая вас) был бы исполнителем, занятым на своём участке работы.
+
+И поскольку большую часть времени выполнения занимает реальная работа (а не ожидание),
+а работу в компьютере делает ЦП,
+такие задачи называют ограниченными производительностью процессора.
+
+---
+
+Ограничение по процессору проявляется в операциях, где требуется выполнять сложные математические вычисления.
+
+Например:
+
+* Обработка **звука** или **изображений**.
+* **Компьютерное зрение**: изображение состоит из миллионов пикселей, в каждом пикселе 3 составляющих цвета,
+обработка обычно требует проведения расчётов по всем пикселям сразу.
+* **Машинное обучение**: здесь обычно требуется умножение "матриц" и "векторов".
+Представьте гигантскую таблицу с числами в Экселе, и все их надо одновременно перемножить.
+* **Глубокое обучение**: это область *машинного обучения*, поэтому сюда подходит то же описание.
+Просто у вас будет не одна таблица в Экселе, а множество. В ряде случаев используется
+специальный процессор для создания и / или использования построенных таким образом моделей.
+
+### Конкурентность + параллелизм: Веб + машинное обучение
+
+**FastAPI** предоставляет возможности конкуретного программирования,
+которое очень распространено в веб-разработке (именно этим славится NodeJS).
+
+Кроме того вы сможете использовать все преимущества параллелизма и
+многопроцессорности (когда несколько процессов работают параллельно),
+если рабочая нагрузка предполагает **ограничение по процессору**,
+как, например, в системах машинного обучения.
+
+Необходимо также отметить, что Python является главным языком в области
+**дата-сайенс**,
+машинного обучения и, особенно, глубокого обучения. Всё это делает FastAPI
+отличным вариантом (среди многих других) для разработки веб-API и приложений
+в области дата-сайенс / машинного обучения.
+
+Как добиться такого параллелизма в эксплуатации описано в разделе [Развёртывание](deployment/index.md){.internal-link target=_blank}.
+
+## `async` и `await`
+
+В современных версиях Python разработка асинхронного кода реализована очень интуитивно.
+Он выглядит как обычный "последовательный" код и самостоятельно выполняет "ожидание", когда это необходимо.
+
+Если некая операция требует ожидания перед тем, как вернуть результат, и
+поддерживает современные возможности Python, код можно написать следующим образом:
+
+```Python
+burgers = await get_burgers(2)
+```
+
+Главное здесь слово `await`. Оно сообщает интерпретатору, что необходимо дождаться ⏸
+пока `get_burgers(2)` закончит свои дела 🕙, и только после этого сохранить результат в `burgers`.
+Зная это, Python может пока переключиться на выполнение других задач 🔀 ⏯
+(например получение следующего запроса).
+
+Чтобы ключевое слово `await` сработало, оно должно находиться внутри функции,
+которая поддерживает асинхронность. Для этого вам просто нужно объявить её как `async def`:
+
+```Python hl_lines="1"
+async def get_burgers(number: int):
+ # Готовим бургеры по специальному асинхронному рецепту
+ return burgers
+```
+
+...вместо `def`:
+
+```Python hl_lines="2"
+# Это не асинхронный код
+def get_sequential_burgers(number: int):
+ # Готовим бургеры последовательно по шагам
+ return burgers
+```
+
+Объявление `async def` указывает интерпретатору, что внутри этой функции
+следует ожидать выражений `await`, и что можно поставить выполнение такой функции на "паузу" ⏸ и
+переключиться на другие задачи 🔀, с тем чтобы вернуться сюда позже.
+
+Если вы хотите вызвать функцию с `async def`, вам нужно "ожидать" её.
+Поэтому такое не сработает:
+
+```Python
+# Это не заработает, поскольку get_burgers объявлена с использованием async def
+burgers = get_burgers(2)
+```
+
+---
+
+Если сторонняя библиотека требует вызывать её с ключевым словом `await`,
+необходимо писать *функции обработки пути* с использованием `async def`, например:
+
+```Python hl_lines="2-3"
+@app.get('/burgers')
+async def read_burgers():
+ burgers = await get_burgers(2)
+ return burgers
+```
+
+### Технические подробности
+
+Как вы могли заметить, `await` может применяться только в функциях, объявленных с использованием `async def`.
+
+
+Но выполнение такой функции необходимо "ожидать" с помощью `await`.
+Это означает, что её можно вызвать только из другой функции, которая тоже объявлена с `async def`.
+
+Но как же тогда появилась первая курица? В смысле... как нам вызвать первую асинхронную функцию?
+
+При работе с **FastAPI** просто не думайте об этом, потому что "первой" функцией является ваша *функция обработки пути*,
+и дальше с этим разберётся FastAPI.
+
+Кроме того, если хотите, вы можете использовать синтаксис `async` / `await` и без FastAPI.
+
+### Пишите свой асинхронный код
+
+Starlette (и **FastAPI**) основаны на AnyIO, что делает их совместимыми как со стандартной библиотекой asyncio в Python, так и с Trio.
+
+В частности, вы можете напрямую использовать AnyIO в тех проектах, где требуется более сложная логика работы с конкурентностью.
+
+Даже если вы не используете FastAPI, вы можете писать асинхронные приложения с помощью AnyIO, чтобы они были максимально совместимыми и получали его преимущества (например *структурную конкурентность*).
+
+### Другие виды асинхронного программирования
+
+Стиль написания кода с `async` и `await` появился в языке Python относительно недавно.
+
+Но он сильно облегчает работу с асинхронным кодом.
+
+Ровно такой же синтаксис (ну или почти такой же) недавно был включён в современные версии JavaScript (в браузере и NodeJS).
+
+До этого поддержка асинхронного кода была реализована намного сложнее, и его было труднее воспринимать.
+
+В предыдущих версиях Python для этого использовались потоки или Gevent. Но такой код намного сложнее понимать, отлаживать и мысленно представлять.
+
+Что касается JavaScript (в браузере и NodeJS), раньше там использовали для этой цели
+"обратные вызовы". Что выливалось в
+ад обратных вызовов.
+
+## Сопрограммы
+
+**Корути́на** (или же сопрограмма) — это крутое словечко для именования той сущности,
+которую возвращает функция `async def`. Python знает, что её можно запустить, как и обычную функцию,
+но кроме того сопрограмму можно поставить на паузу ⏸ в том месте, где встретится слово `await`.
+
+Всю функциональность асинхронного программирования с использованием `async` и `await`
+часто обобщают словом "корутины". Они аналогичны "горутинам", ключевой особенности
+языка Go.
+
+## Заключение
+
+В самом начале была такая фраза:
+
+> Современные версии Python поддерживают разработку так называемого
+**"асинхронного кода"** посредством написания **"сопрограмм"** с использованием
+синтаксиса **`async` и `await`**.
+
+Теперь всё должно звучать понятнее. ✨
+
+На этом основана работа FastAPI (посредством Starlette), и именно это
+обеспечивает его высокую производительность.
+
+## Очень технические подробности
+
+!!! warning
+ Этот раздел читать не обязательно.
+
+ Здесь приводятся подробности внутреннего устройства **FastAPI**.
+
+ Но если вы обладаете техническими знаниями (корутины, потоки, блокировка и т. д.)
+ и вам интересно, как FastAPI обрабатывает `async def` в отличие от обычных `def`,
+ читайте дальше.
+
+### Функции обработки пути
+
+Когда вы объявляете *функцию обработки пути* обычным образом с ключевым словом `def`
+вместо `async def`, FastAPI ожидает её выполнения, запустив функцию во внешнем
+пуле потоков, а не напрямую (это бы заблокировало сервер).
+
+Если ранее вы использовали другой асинхронный фреймворк, который работает иначе,
+и привыкли объявлять простые вычислительные *функции* через `def` ради
+незначительного прироста скорости (порядка 100 наносекунд), обратите внимание,
+что с **FastAPI** вы получите противоположный эффект. В таком случае больше подходит
+`async def`, если только *функция обработки пути* не использует код, приводящий
+к блокировке I/O.
+
+
+
+Но в любом случае велика вероятность, что **FastAPI** [окажется быстрее](/#performance){.internal-link target=_blank}
+другого фреймворка (или хотя бы на уровне с ним).
+
+### Зависимости
+
+То же относится к зависимостям. Если это обычная функция `def`, а не `async def`,
+она запускается во внешнем пуле потоков.
+
+### Подзависимости
+
+Вы можете объявить множество ссылающихся друг на друга зависимостей и подзависимостей
+(в виде параметров при определении функции). Какие-то будут созданы с помощью `async def`,
+другие обычным образом через `def`, и такая схема вполне работоспособна. Функции,
+объявленные с помощью `def` будут запускаться на внешнем потоке (из пула),
+а не с помощью `await`.
+
+### Другие служебные функции
+
+Любые другие служебные функции, которые вы вызываете напрямую, можно объявлять
+с использованием `def` или `async def`. FastAPI не будет влиять на то, как вы
+их запускаете.
+
+Этим они отличаются от функций, которые FastAPI вызывает самостоятельно:
+*функции обработки пути* и зависимости.
+
+Если служебная функция объявлена с помощью `def`, она будет вызвана напрямую
+(как вы и написали в коде), а не в отдельном потоке. Если же она объявлена с
+помощью `async def`, её вызов должен осуществляться с ожиданием через `await`.
+
+---
+
+
+Ещё раз повторим, что все эти технические подробности полезны, только если вы специально их искали.
+
+В противном случае просто ознакомьтесь с основными принципами в разделе выше: Нет времени?.
diff --git a/docs/ru/docs/index.md b/docs/ru/docs/index.md
index 0c2506b87..9a3957d5f 100644
--- a/docs/ru/docs/index.md
+++ b/docs/ru/docs/index.md
@@ -149,7 +149,7 @@ $ pip install uvicorn[standard]
* Create a file `main.py` with:
```Python
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
@@ -162,7 +162,7 @@ def read_root():
@app.get("/items/{item_id}")
-def read_item(item_id: int, q: Optional[str] = None):
+def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
```
@@ -172,7 +172,7 @@ def read_item(item_id: int, q: Optional[str] = None):
If your code uses `async` / `await`, use `async def`:
```Python hl_lines="9 14"
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
@@ -185,7 +185,7 @@ async def read_root():
@app.get("/items/{item_id}")
-async def read_item(item_id: int, q: Optional[str] = None):
+async def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
```
@@ -264,7 +264,7 @@ Now modify the file `main.py` to receive a body from a `PUT` request.
Declare the body using standard Python types, thanks to Pydantic.
```Python hl_lines="4 9-12 25-27"
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
from pydantic import BaseModel
@@ -275,7 +275,7 @@ app = FastAPI()
class Item(BaseModel):
name: str
price: float
- is_offer: Optional[bool] = None
+ is_offer: Union[bool, None] = None
@app.get("/")
@@ -284,7 +284,7 @@ def read_root():
@app.get("/items/{item_id}")
-def read_item(item_id: int, q: Optional[str] = None):
+def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
@@ -321,7 +321,7 @@ And now, go to requests - Required if you want to use the `TestClient`.
-* aiofiles - Required if you want to use `FileResponse` or `StaticFiles`.
* jinja2 - Required if you want to use the default template configuration.
* python-multipart - Required if you want to support form "parsing", with `request.form()`.
* itsdangerous - Required for `SessionMiddleware` support.
diff --git a/docs/ru/docs/python-types.md b/docs/ru/docs/python-types.md
index 99670363c..7523083c8 100644
--- a/docs/ru/docs/python-types.md
+++ b/docs/ru/docs/python-types.md
@@ -1,6 +1,6 @@
# Введение в аннотации типов Python
-Python имеет поддержку необязательных аннотаций типов.
+Python имеет поддержку необязательных аннотаций типов.
**Аннотации типов** являются специальным синтаксисом, который позволяет определять тип переменной.
diff --git a/docs/ru/mkdocs.yml b/docs/ru/mkdocs.yml
index 213f941d7..bb0702489 100644
--- a/docs/ru/mkdocs.yml
+++ b/docs/ru/mkdocs.yml
@@ -5,13 +5,15 @@ theme:
name: material
custom_dir: overrides
palette:
- - scheme: default
+ - media: "(prefers-color-scheme: light)"
+ scheme: default
primary: teal
accent: amber
toggle:
icon: material/lightbulb
name: Switch to light mode
- - scheme: slate
+ - media: "(prefers-color-scheme: dark)"
+ scheme: slate
primary: teal
accent: amber
toggle:
@@ -54,6 +56,7 @@ nav:
- tr: /tr/
- uk: /uk/
- zh: /zh/
+- async.md
markdown_extensions:
- toc:
permalink: true
diff --git a/docs/sq/docs/index.md b/docs/sq/docs/index.md
index 95fb7ae21..29f92e020 100644
--- a/docs/sq/docs/index.md
+++ b/docs/sq/docs/index.md
@@ -149,7 +149,7 @@ $ pip install uvicorn[standard]
* Create a file `main.py` with:
```Python
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
@@ -162,7 +162,7 @@ def read_root():
@app.get("/items/{item_id}")
-def read_item(item_id: int, q: Optional[str] = None):
+def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
```
@@ -172,7 +172,7 @@ def read_item(item_id: int, q: Optional[str] = None):
If your code uses `async` / `await`, use `async def`:
```Python hl_lines="9 14"
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
@@ -185,7 +185,7 @@ async def read_root():
@app.get("/items/{item_id}")
-async def read_item(item_id: int, q: Optional[str] = None):
+async def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
```
@@ -264,7 +264,7 @@ Now modify the file `main.py` to receive a body from a `PUT` request.
Declare the body using standard Python types, thanks to Pydantic.
```Python hl_lines="4 9-12 25-27"
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
from pydantic import BaseModel
@@ -275,7 +275,7 @@ app = FastAPI()
class Item(BaseModel):
name: str
price: float
- is_offer: Optional[bool] = None
+ is_offer: Union[bool, None] = None
@app.get("/")
@@ -284,7 +284,7 @@ def read_root():
@app.get("/items/{item_id}")
-def read_item(item_id: int, q: Optional[str] = None):
+def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
@@ -321,7 +321,7 @@ And now, go to requests - Required if you want to use the `TestClient`.
-* aiofiles - Required if you want to use `FileResponse` or `StaticFiles`.
* jinja2 - Required if you want to use the default template configuration.
* python-multipart - Required if you want to support form "parsing", with `request.form()`.
* itsdangerous - Required for `SessionMiddleware` support.
diff --git a/docs/sq/mkdocs.yml b/docs/sq/mkdocs.yml
index a61f49bc9..8914395fe 100644
--- a/docs/sq/mkdocs.yml
+++ b/docs/sq/mkdocs.yml
@@ -5,13 +5,15 @@ theme:
name: material
custom_dir: overrides
palette:
- - scheme: default
+ - media: "(prefers-color-scheme: light)"
+ scheme: default
primary: teal
accent: amber
toggle:
icon: material/lightbulb
name: Switch to light mode
- - scheme: slate
+ - media: "(prefers-color-scheme: dark)"
+ scheme: slate
primary: teal
accent: amber
toggle:
diff --git a/docs/tr/docs/features.md b/docs/tr/docs/features.md
index c06c27c16..0bcda4e9c 100644
--- a/docs/tr/docs/features.md
+++ b/docs/tr/docs/features.md
@@ -6,7 +6,7 @@
### Açık standartları temel alır
-* API oluşturma işlemlerinde OpenAPI buna path operasyonları parametreleri, body talebi, güvenlik gibi şeyler dahil olmak üzere deklare bunların deklare edilmesi.
+* API oluşturma işlemlerinde OpenAPI buna path operasyonları parametreleri, body talebi, güvenlik gibi şeyler dahil olmak üzere deklare bunların deklare edilmesi.
* Otomatik olarak data modelinin JSON Schema ile beraber dokümante edilmesi (OpenAPI'n kendisi zaten JSON Schema'ya dayanıyor).
* Titiz bir çalışmanın sonucunda yukarıdaki standartlara uygun bir framework oluşturduk. Standartları pastanın üzerine sonradan eklenmiş bir çilek olarak görmedik.
* Ayrıca bu bir çok dilde kullanılabilecek **client code generator** kullanımına da izin veriyor.
@@ -74,7 +74,7 @@ my_second_user: User = User(**second_user_data)
### Editor desteği
-Bütün framework kullanılması kolay ve sezgileri güçlü olması için tasarlandı, verilen bütün kararlar geliştiricilere en iyi geliştirme deneyimini yaşatmak üzere, bir çok editör üzerinde test edildi.
+Bütün framework kullanılması kolay ve sezgileri güçlü olması için tasarlandı, verilen bütün kararlar geliştiricilere en iyi geliştirme deneyimini yaşatmak üzere, bir çok editör üzerinde test edildi.
Son yapılan Python geliştiricileri anketinde, açık ara en çok kullanılan özellik "oto-tamamlama" idi..
@@ -135,7 +135,7 @@ Bütün güvenlik şemaları OpenAPI'da tanımlanmış durumda, kapsadıkları:
Bütün güvenlik özellikleri Starlette'den geliyor (**session cookies'de** dahil olmak üzere).
-Bütün hepsi tekrardan kullanılabilir aletler ve bileşenler olarak, kolayca sistemlerinize, data depolarınıza, ilişkisel ve NoSQL databaselerinize entegre edebileceğiniz şekilde yapıldı.
+Bütün hepsi tekrardan kullanılabilir aletler ve bileşenler olarak, kolayca sistemlerinize, data depolarınıza, ilişkisel ve NoSQL databaselerinize entegre edebileceğiniz şekilde yapıldı.
### Dependency injection
@@ -198,7 +198,7 @@ Aynı şekilde, databaseden gelen objeyi de **direkt olarak isteğe** de tamamiy
* Kullandığın geliştirme araçları ile iyi çalışır **IDE/linter/brain**:
* Pydantic'in veri yapıları aslında sadece senin tanımladığın classlar; Bu yüzden doğrulanmış dataların ile otomatik tamamlama, linting ve mypy'ı kullanarak sorunsuz bir şekilde çalışabilirsin
* **Hızlı**:
- * Benchmarklarda, Pydantic'in diğer bütün test edilmiş bütün kütüphanelerden daha hızlı.
+ * Benchmarklarda, Pydantic'in diğer bütün test edilmiş bütün kütüphanelerden daha hızlı.
* **En kompleks** yapıları bile doğrula:
* Hiyerarşik Pydantic modellerinin kullanımı ile beraber, Python `typing`’s `List` and `Dict`, vs gibi şeyleri doğrula.
* Doğrulayıcılar en kompleks data şemalarının bile temiz ve kolay bir şekilde tanımlanmasına izin veriyor, ve hepsi JSON şeması olarak dokümante ediliyor
@@ -206,4 +206,3 @@ Aynı şekilde, databaseden gelen objeyi de **direkt olarak isteğe** de tamamiy
* **Genişletilebilir**:
* Pydantic özelleştirilmiş data tiplerinin tanımlanmasının yapılmasına izin veriyor ayrıca validator decoratorü ile senin doğrulamaları genişletip, kendi doğrulayıcılarını yazmana izin veriyor.
* 100% test kapsayıcılığı.
-
diff --git a/docs/tr/docs/index.md b/docs/tr/docs/index.md
index 88660f7eb..5693029b5 100644
--- a/docs/tr/docs/index.md
+++ b/docs/tr/docs/index.md
@@ -28,7 +28,7 @@
---
-FastAPI, Python 3.6+'nın standart type hintlerine dayanan modern ve hızlı (yüksek performanslı) API'lar oluşturmak için kullanılabilecek web framework'ü.
+FastAPI, Python 3.6+'nın standart type hintlerine dayanan modern ve hızlı (yüksek performanslı) API'lar oluşturmak için kullanılabilecek web framework'ü.
Ana özellikleri:
@@ -157,7 +157,7 @@ $ pip install uvicorn[standard]
* `main.py` adında bir dosya oluştur :
```Python
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
@@ -170,7 +170,7 @@ def read_root():
@app.get("/items/{item_id}")
-def read_item(item_id: int, q: Optional[str] = None):
+def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
```
@@ -180,7 +180,7 @@ def read_item(item_id: int, q: Optional[str] = None):
Eğer kodunda `async` / `await` var ise, `async def` kullan:
```Python hl_lines="9 14"
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
@@ -193,7 +193,7 @@ async def read_root():
@app.get("/items/{item_id}")
-async def read_item(item_id: int, q: Optional[str] = None):
+async def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
```
@@ -272,7 +272,7 @@ Senin için alternatif olarak (requests - Eğer `TestClient` kullanmak istiyorsan gerekli.
-* aiofiles - `FileResponse` ya da `StaticFiles` kullanmak istiyorsan gerekli.
* jinja2 - Eğer kendine ait template konfigürasyonu oluşturmak istiyorsan gerekli
* python-multipart - Form kullanmak istiyorsan gerekli ("dönüşümü").
* itsdangerous - `SessionMiddleware` desteği için gerekli.
diff --git a/docs/tr/docs/python-types.md b/docs/tr/docs/python-types.md
index 7e46bd031..3b9ab9050 100644
--- a/docs/tr/docs/python-types.md
+++ b/docs/tr/docs/python-types.md
@@ -29,7 +29,7 @@ Programın çıktısı:
John Doe
```
-Fonksiyon sırayla şunları yapar:
+Fonksiyon sırayla şunları yapar:
* `first_name` ve `last_name` değerlerini alır.
* `title()` ile değişkenlerin ilk karakterlerini büyütür.
diff --git a/docs/tr/mkdocs.yml b/docs/tr/mkdocs.yml
index dd52d7fcc..74186033c 100644
--- a/docs/tr/mkdocs.yml
+++ b/docs/tr/mkdocs.yml
@@ -5,13 +5,15 @@ theme:
name: material
custom_dir: overrides
palette:
- - scheme: default
+ - media: "(prefers-color-scheme: light)"
+ scheme: default
primary: teal
accent: amber
toggle:
icon: material/lightbulb
name: Switch to light mode
- - scheme: slate
+ - media: "(prefers-color-scheme: dark)"
+ scheme: slate
primary: teal
accent: amber
toggle:
diff --git a/docs/uk/docs/index.md b/docs/uk/docs/index.md
index 95fb7ae21..29f92e020 100644
--- a/docs/uk/docs/index.md
+++ b/docs/uk/docs/index.md
@@ -149,7 +149,7 @@ $ pip install uvicorn[standard]
* Create a file `main.py` with:
```Python
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
@@ -162,7 +162,7 @@ def read_root():
@app.get("/items/{item_id}")
-def read_item(item_id: int, q: Optional[str] = None):
+def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
```
@@ -172,7 +172,7 @@ def read_item(item_id: int, q: Optional[str] = None):
If your code uses `async` / `await`, use `async def`:
```Python hl_lines="9 14"
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
@@ -185,7 +185,7 @@ async def read_root():
@app.get("/items/{item_id}")
-async def read_item(item_id: int, q: Optional[str] = None):
+async def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
```
@@ -264,7 +264,7 @@ Now modify the file `main.py` to receive a body from a `PUT` request.
Declare the body using standard Python types, thanks to Pydantic.
```Python hl_lines="4 9-12 25-27"
-from typing import Optional
+from typing import Union
from fastapi import FastAPI
from pydantic import BaseModel
@@ -275,7 +275,7 @@ app = FastAPI()
class Item(BaseModel):
name: str
price: float
- is_offer: Optional[bool] = None
+ is_offer: Union[bool, None] = None
@app.get("/")
@@ -284,7 +284,7 @@ def read_root():
@app.get("/items/{item_id}")
-def read_item(item_id: int, q: Optional[str] = None):
+def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
@@ -321,7 +321,7 @@ And now, go to requests - Required if you want to use the `TestClient`.
-* aiofiles - Required if you want to use `FileResponse` or `StaticFiles`.
* jinja2 - Required if you want to use the default template configuration.
* python-multipart - Required if you want to support form "parsing", with `request.form()`.
* itsdangerous - Required for `SessionMiddleware` support.
diff --git a/docs/uk/mkdocs.yml b/docs/uk/mkdocs.yml
index 971a182db..ddf299d8b 100644
--- a/docs/uk/mkdocs.yml
+++ b/docs/uk/mkdocs.yml
@@ -5,13 +5,15 @@ theme:
name: material
custom_dir: overrides
palette:
- - scheme: default
+ - media: "(prefers-color-scheme: light)"
+ scheme: default
primary: teal
accent: amber
toggle:
icon: material/lightbulb
name: Switch to light mode
- - scheme: slate
+ - media: "(prefers-color-scheme: dark)"
+ scheme: slate
primary: teal
accent: amber
toggle:
diff --git a/docs/zh/docs/advanced/additional-status-codes.md b/docs/zh/docs/advanced/additional-status-codes.md
index 1cb724f1d..54ec9775b 100644
--- a/docs/zh/docs/advanced/additional-status-codes.md
+++ b/docs/zh/docs/advanced/additional-status-codes.md
@@ -14,7 +14,7 @@
要实现它，导入 `JSONResponse`，然后在其中直接返回你的内容，并将 `status_code` 设置为为你要的值。
-```Python hl_lines="2 19"
+```Python hl_lines="4 25"
{!../../../docs_src/additional_status_codes/tutorial001.py!}
```
@@ -22,7 +22,7 @@
当你直接返回一个像上面例子中的 `Response` 对象时，它会直接返回。
FastAPI 不会用模型等对该响应进行序列化。
-
+
确保其中有你想要的数据，且返回的值为合法的 JSON（如果你使用 `JSONResponse` 的话）。
!!! note "技术细节"
diff --git a/docs/zh/docs/advanced/custom-response.md b/docs/zh/docs/advanced/custom-response.md
index 5f1a74e9e..155ce2882 100644
--- a/docs/zh/docs/advanced/custom-response.md
+++ b/docs/zh/docs/advanced/custom-response.md
@@ -60,7 +60,7 @@
正如你在 [直接返回响应](response-directly.md){.internal-link target=_blank} 中了解到的，你也可以通过直接返回响应在 *路径操作* 中直接重载响应。
和上面一样的例子，返回一个 `HTMLResponse` 看起来可能是这样：
-
+
```Python hl_lines="2 7 19"
{!../../../docs_src/custom_response/tutorial003.py!}
```
diff --git a/docs/zh/docs/advanced/response-directly.md b/docs/zh/docs/advanced/response-directly.md
index 05926a9c8..797a878eb 100644
--- a/docs/zh/docs/advanced/response-directly.md
+++ b/docs/zh/docs/advanced/response-directly.md
@@ -10,7 +10,7 @@
直接返回响应可能会有用处，比如返回自定义的响应头和 cookies。
-## 返回 `Response`
+## 返回 `Response`
事实上，你可以返回任意 `Response` 或者任意 `Response` 的子类。
@@ -62,4 +62,3 @@
但是你仍可以参考 [OpenApI 中的额外响应](additional-responses.md){.internal-link target=_blank} 给响应编写文档。
在后续的章节中你可以了解到如何使用/声明这些自定义的 `Response` 的同时还保留自动化的数据转换和文档等。
-
diff --git a/docs/zh/docs/benchmarks.md b/docs/zh/docs/benchmarks.md
index c133d51b7..8991c72cd 100644
--- a/docs/zh/docs/benchmarks.md
+++ b/docs/zh/docs/benchmarks.md
@@ -22,7 +22,7 @@
* 具有最佳性能，因为除了服务器本身外，它没有太多额外的代码。
* 您不会直接在 Uvicorn 中编写应用程序。这意味着您的代码至少必须包含 Starlette（或 **FastAPI**）提供的代码。如果您这样做了（即直接在 Uvicorn 中编写应用程序），最终的应用程序会和使用了框架并且最小化了应用代码和 bug 的情况具有相同的性能损耗。
* 如果要对比与 Uvicorn 对标的服务器，请将其与 Daphne，Hypercorn，uWSGI等应用服务器进行比较。
-* **Starlette**:
+* **Starlette**:
* 在 Uvicorn 后使用 Starlette，性能会略有下降。实际上，Starlette 使用 Uvicorn运行。因此，由于必须执行更多的代码，它只会比 Uvicorn 更慢。
* 但它为您提供了构建简单的网络程序的工具，并具有基于路径的路由等功能。
* 如果想对比与 Starlette 对标的开发框架，请将其与 Sanic，Flask，Django 等网络框架（或微框架）进行比较。
diff --git a/docs/zh/docs/contributing.md b/docs/zh/docs/contributing.md
index 402668c47..95500d12b 100644
--- a/docs/zh/docs/contributing.md
+++ b/docs/zh/docs/contributing.md
@@ -497,4 +497,4 @@ $ bash scripts/test-cov-html.sh
-该命令生成了一个 `./htmlcov/` 目录，如果你在浏览器中打开 `./htmlcov/index.html` 文件，你可以交互式地浏览被测试所覆盖的代码区块，并注意是否缺少了任何区块。
+该命令生成了一个 `./htmlcov/` 目录，如果你在浏览器中打开 `./htmlcov/index.html` 文件，你可以交互式地浏览被测试所覆盖的代码区块，并注意是否缺少了任何区块。
diff --git a/docs/zh/docs/fastapi-people.md b/docs/zh/docs/fastapi-people.md
index 75651592d..5d7b0923f 100644
--- a/docs/zh/docs/fastapi-people.md
+++ b/docs/zh/docs/fastapi-people.md
@@ -114,6 +114,8 @@ FastAPI 有一个非常棒的社区，它欢迎来自各个领域和背景的朋
他们主要通过GitHub Sponsors支持我在 **FastAPI** (和其他项目)的工作。
+{% if sponsors %}
+
{% if sponsors.gold %}
### 金牌赞助商
@@ -141,6 +143,8 @@ FastAPI 有一个非常棒的社区，它欢迎来自各个领域和背景的朋
{% endfor %}
{% endif %}
+{% endif %}
+
### 个人赞助
{% if github_sponsors %}
diff --git a/docs/zh/docs/features.md b/docs/zh/docs/features.md
index 4752947a3..fefe4b197 100644
--- a/docs/zh/docs/features.md
+++ b/docs/zh/docs/features.md
@@ -193,9 +193,9 @@ FastAPI 有一个使用非常简单，但是非常强大的 ModelField:
- default_value = Required
+ default_value: Any = Undefined
had_schema = False
if not param.default == param.empty and ignore_default is False:
default_value = param.default
@@ -369,8 +370,13 @@ def get_param_field(
if force_type:
field_info.in_ = force_type # type: ignore
else:
- field_info = default_field_info(default_value)
- required = default_value == Required
+ field_info = default_field_info(default=default_value)
+ required = True
+ if default_value is Required or ignore_default:
+ required = True
+ default_value = None
+ elif default_value is not Undefined:
+ required = False
annotation: Any = Any
if not param.annotation == param.empty:
annotation = param.annotation
@@ -382,12 +388,11 @@ def get_param_field(
field = create_response_field(
name=param.name,
type_=annotation,
- default=None if required else default_value,
+ default=default_value,
alias=alias,
required=required,
field_info=field_info,
)
- field.required = required
if not had_schema and not is_scalar_field(field=field):
field.field_info = params.Body(field_info.default)
if not had_schema and lenient_issubclass(field.type_, UploadFile):
diff --git a/fastapi/exceptions.py b/fastapi/exceptions.py
index f4a837bb4..0f50acc6c 100644
--- a/fastapi/exceptions.py
+++ b/fastapi/exceptions.py
@@ -12,8 +12,7 @@ class HTTPException(StarletteHTTPException):
detail: Any = None,
headers: Optional[Dict[str, Any]] = None,
) -> None:
- super().__init__(status_code=status_code, detail=detail)
- self.headers = headers
+ super().__init__(status_code=status_code, detail=detail, headers=headers)
RequestErrorModel: Type[BaseModel] = create_model("Request")
diff --git a/fastapi/openapi/models.py b/fastapi/openapi/models.py
index 9c6598d2d..35aa1672b 100644
--- a/fastapi/openapi/models.py
+++ b/fastapi/openapi/models.py
@@ -73,7 +73,7 @@ class Server(BaseModel):
class Reference(BaseModel):
- ref: str = Field(..., alias="$ref")
+ ref: str = Field(alias="$ref")
class Discriminator(BaseModel):
@@ -101,28 +101,28 @@ class ExternalDocumentation(BaseModel):
class Schema(BaseModel):
- ref: Optional[str] = Field(None, alias="$ref")
+ ref: Optional[str] = Field(default=None, alias="$ref")
title: Optional[str] = None
multipleOf: Optional[float] = None
maximum: Optional[float] = None
exclusiveMaximum: Optional[float] = None
minimum: Optional[float] = None
exclusiveMinimum: Optional[float] = None
- maxLength: Optional[int] = Field(None, gte=0)
- minLength: Optional[int] = Field(None, gte=0)
+ maxLength: Optional[int] = Field(default=None, gte=0)
+ minLength: Optional[int] = Field(default=None, gte=0)
pattern: Optional[str] = None
- maxItems: Optional[int] = Field(None, gte=0)
- minItems: Optional[int] = Field(None, gte=0)
+ maxItems: Optional[int] = Field(default=None, gte=0)
+ minItems: Optional[int] = Field(default=None, gte=0)
uniqueItems: Optional[bool] = None
- maxProperties: Optional[int] = Field(None, gte=0)
- minProperties: Optional[int] = Field(None, gte=0)
+ maxProperties: Optional[int] = Field(default=None, gte=0)
+ minProperties: Optional[int] = Field(default=None, gte=0)
required: Optional[List[str]] = None
enum: Optional[List[Any]] = None
type: Optional[str] = None
allOf: Optional[List["Schema"]] = None
oneOf: Optional[List["Schema"]] = None
anyOf: Optional[List["Schema"]] = None
- not_: Optional["Schema"] = Field(None, alias="not")
+ not_: Optional["Schema"] = Field(default=None, alias="not")
items: Optional[Union["Schema", List["Schema"]]] = None
properties: Optional[Dict[str, "Schema"]] = None
additionalProperties: Optional[Union["Schema", Reference, bool]] = None
@@ -171,7 +171,7 @@ class Encoding(BaseModel):
class MediaType(BaseModel):
- schema_: Optional[Union[Schema, Reference]] = Field(None, alias="schema")
+ schema_: Optional[Union[Schema, Reference]] = Field(default=None, alias="schema")
example: Optional[Any] = None
examples: Optional[Dict[str, Union[Example, Reference]]] = None
encoding: Optional[Dict[str, Encoding]] = None
@@ -188,7 +188,7 @@ class ParameterBase(BaseModel):
style: Optional[str] = None
explode: Optional[bool] = None
allowReserved: Optional[bool] = None
- schema_: Optional[Union[Schema, Reference]] = Field(None, alias="schema")
+ schema_: Optional[Union[Schema, Reference]] = Field(default=None, alias="schema")
example: Optional[Any] = None
examples: Optional[Dict[str, Union[Example, Reference]]] = None
# Serialization rules for more complex scenarios
@@ -200,7 +200,7 @@ class ParameterBase(BaseModel):
class Parameter(ParameterBase):
name: str
- in_: ParameterInType = Field(..., alias="in")
+ in_: ParameterInType = Field(alias="in")
class Header(ParameterBase):
@@ -258,7 +258,7 @@ class Operation(BaseModel):
class PathItem(BaseModel):
- ref: Optional[str] = Field(None, alias="$ref")
+ ref: Optional[str] = Field(default=None, alias="$ref")
summary: Optional[str] = None
description: Optional[str] = None
get: Optional[Operation] = None
@@ -284,7 +284,7 @@ class SecuritySchemeType(Enum):
class SecurityBase(BaseModel):
- type_: SecuritySchemeType = Field(..., alias="type")
+ type_: SecuritySchemeType = Field(alias="type")
description: Optional[str] = None
class Config:
@@ -299,7 +299,7 @@ class APIKeyIn(Enum):
class APIKey(SecurityBase):
type_ = Field(SecuritySchemeType.apiKey, alias="type")
- in_: APIKeyIn = Field(..., alias="in")
+ in_: APIKeyIn = Field(alias="in")
name: str
diff --git a/fastapi/param_functions.py b/fastapi/param_functions.py
index a553a1461..1932ef065 100644
--- a/fastapi/param_functions.py
+++ b/fastapi/param_functions.py
@@ -5,7 +5,7 @@ from pydantic.fields import Undefined
def Path( # noqa: N802
- default: Any,
+ default: Any = Undefined,
*,
alias: Optional[str] = None,
title: Optional[str] = None,
@@ -44,7 +44,7 @@ def Path( # noqa: N802
def Query( # noqa: N802
- default: Any,
+ default: Any = Undefined,
*,
alias: Optional[str] = None,
title: Optional[str] = None,
@@ -63,7 +63,7 @@ def Query( # noqa: N802
**extra: Any,
) -> Any:
return params.Query(
- default,
+ default=default,
alias=alias,
title=title,
description=description,
@@ -83,7 +83,7 @@ def Query( # noqa: N802
def Header( # noqa: N802
- default: Any,
+ default: Any = Undefined,
*,
alias: Optional[str] = None,
convert_underscores: bool = True,
@@ -103,7 +103,7 @@ def Header( # noqa: N802
**extra: Any,
) -> Any:
return params.Header(
- default,
+ default=default,
alias=alias,
convert_underscores=convert_underscores,
title=title,
@@ -124,7 +124,7 @@ def Header( # noqa: N802
def Cookie( # noqa: N802
- default: Any,
+ default: Any = Undefined,
*,
alias: Optional[str] = None,
title: Optional[str] = None,
@@ -143,7 +143,7 @@ def Cookie( # noqa: N802
**extra: Any,
) -> Any:
return params.Cookie(
- default,
+ default=default,
alias=alias,
title=title,
description=description,
@@ -163,7 +163,7 @@ def Cookie( # noqa: N802
def Body( # noqa: N802
- default: Any,
+ default: Any = Undefined,
*,
embed: bool = False,
media_type: str = "application/json",
@@ -182,7 +182,7 @@ def Body( # noqa: N802
**extra: Any,
) -> Any:
return params.Body(
- default,
+ default=default,
embed=embed,
media_type=media_type,
alias=alias,
@@ -202,7 +202,7 @@ def Body( # noqa: N802
def Form( # noqa: N802
- default: Any,
+ default: Any = Undefined,
*,
media_type: str = "application/x-www-form-urlencoded",
alias: Optional[str] = None,
@@ -220,7 +220,7 @@ def Form( # noqa: N802
**extra: Any,
) -> Any:
return params.Form(
- default,
+ default=default,
media_type=media_type,
alias=alias,
title=title,
@@ -239,7 +239,7 @@ def Form( # noqa: N802
def File( # noqa: N802
- default: Any,
+ default: Any = Undefined,
*,
media_type: str = "multipart/form-data",
alias: Optional[str] = None,
@@ -257,7 +257,7 @@ def File( # noqa: N802
**extra: Any,
) -> Any:
return params.File(
- default,
+ default=default,
media_type=media_type,
alias=alias,
title=title,
diff --git a/fastapi/params.py b/fastapi/params.py
index 042bbd42f..5395b98a3 100644
--- a/fastapi/params.py
+++ b/fastapi/params.py
@@ -16,7 +16,7 @@ class Param(FieldInfo):
def __init__(
self,
- default: Any,
+ default: Any = Undefined,
*,
alias: Optional[str] = None,
title: Optional[str] = None,
@@ -39,7 +39,7 @@ class Param(FieldInfo):
self.examples = examples
self.include_in_schema = include_in_schema
super().__init__(
- default,
+ default=default,
alias=alias,
title=title,
description=description,
@@ -62,7 +62,7 @@ class Path(Param):
def __init__(
self,
- default: Any,
+ default: Any = Undefined,
*,
alias: Optional[str] = None,
title: Optional[str] = None,
@@ -82,7 +82,7 @@ class Path(Param):
):
self.in_ = self.in_
super().__init__(
- ...,
+ default=...,
alias=alias,
title=title,
description=description,
@@ -106,7 +106,7 @@ class Query(Param):
def __init__(
self,
- default: Any,
+ default: Any = Undefined,
*,
alias: Optional[str] = None,
title: Optional[str] = None,
@@ -125,7 +125,7 @@ class Query(Param):
**extra: Any,
):
super().__init__(
- default,
+ default=default,
alias=alias,
title=title,
description=description,
@@ -149,7 +149,7 @@ class Header(Param):
def __init__(
self,
- default: Any,
+ default: Any = Undefined,
*,
alias: Optional[str] = None,
convert_underscores: bool = True,
@@ -170,7 +170,7 @@ class Header(Param):
):
self.convert_underscores = convert_underscores
super().__init__(
- default,
+ default=default,
alias=alias,
title=title,
description=description,
@@ -194,7 +194,7 @@ class Cookie(Param):
def __init__(
self,
- default: Any,
+ default: Any = Undefined,
*,
alias: Optional[str] = None,
title: Optional[str] = None,
@@ -213,7 +213,7 @@ class Cookie(Param):
**extra: Any,
):
super().__init__(
- default,
+ default=default,
alias=alias,
title=title,
description=description,
@@ -235,7 +235,7 @@ class Cookie(Param):
class Body(FieldInfo):
def __init__(
self,
- default: Any,
+ default: Any = Undefined,
*,
embed: bool = False,
media_type: str = "application/json",
@@ -258,7 +258,7 @@ class Body(FieldInfo):
self.example = example
self.examples = examples
super().__init__(
- default,
+ default=default,
alias=alias,
title=title,
description=description,
@@ -297,7 +297,7 @@ class Form(Body):
**extra: Any,
):
super().__init__(
- default,
+ default=default,
embed=True,
media_type=media_type,
alias=alias,
@@ -337,7 +337,7 @@ class File(Form):
**extra: Any,
):
super().__init__(
- default,
+ default=default,
media_type=media_type,
alias=alias,
title=title,
diff --git a/fastapi/routing.py b/fastapi/routing.py
index 805bf5acb..66a24d38f 100644
--- a/fastapi/routing.py
+++ b/fastapi/routing.py
@@ -369,7 +369,7 @@ class APIRoute(routing.Route):
self.path_regex, self.path_format, self.param_convertors = compile_path(path)
if methods is None:
methods = ["GET"]
- self.methods: Set[str] = set([method.upper() for method in methods])
+ self.methods: Set[str] = {method.upper() for method in methods}
if isinstance(generate_unique_id_function, DefaultPlaceholder):
current_generate_unique_id: Callable[
["APIRoute"], str
@@ -483,11 +483,11 @@ class APIRouter(routing.Router):
),
) -> None:
super().__init__(
- routes=routes, # type: ignore # in Starlette
+ routes=routes,
redirect_slashes=redirect_slashes,
- default=default, # type: ignore # in Starlette
- on_startup=on_startup, # type: ignore # in Starlette
- on_shutdown=on_shutdown, # type: ignore # in Starlette
+ default=default,
+ on_startup=on_startup,
+ on_shutdown=on_shutdown,
)
if prefix:
assert prefix.startswith("/"), "A path prefix must start with '/'"
@@ -762,7 +762,7 @@ class APIRouter(routing.Router):
generate_unique_id_function=current_generate_unique_id,
)
elif isinstance(route, routing.Route):
- methods = list(route.methods or []) # type: ignore # in Starlette
+ methods = list(route.methods or [])
self.add_route(
prefix + route.path,
route.endpoint,
diff --git a/fastapi/security/oauth2.py b/fastapi/security/oauth2.py
index bdc6e2ea9..888208c15 100644
--- a/fastapi/security/oauth2.py
+++ b/fastapi/security/oauth2.py
@@ -45,12 +45,12 @@ class OAuth2PasswordRequestForm:
def __init__(
self,
- grant_type: str = Form(None, regex="password"),
- username: str = Form(...),
- password: str = Form(...),
- scope: str = Form(""),
- client_id: Optional[str] = Form(None),
- client_secret: Optional[str] = Form(None),
+ grant_type: str = Form(default=None, regex="password"),
+ username: str = Form(),
+ password: str = Form(),
+ scope: str = Form(default=""),
+ client_id: Optional[str] = Form(default=None),
+ client_secret: Optional[str] = Form(default=None),
):
self.grant_type = grant_type
self.username = username
@@ -95,12 +95,12 @@ class OAuth2PasswordRequestFormStrict(OAuth2PasswordRequestForm):
def __init__(
self,
- grant_type: str = Form(..., regex="password"),
- username: str = Form(...),
- password: str = Form(...),
- scope: str = Form(""),
- client_id: Optional[str] = Form(None),
- client_secret: Optional[str] = Form(None),
+ grant_type: str = Form(regex="password"),
+ username: str = Form(),
+ password: str = Form(),
+ scope: str = Form(default=""),
+ client_id: Optional[str] = Form(default=None),
+ client_secret: Optional[str] = Form(default=None),
):
super().__init__(
grant_type=grant_type,
diff --git a/fastapi/utils.py b/fastapi/utils.py
index b9301499a..a7e135bca 100644
--- a/fastapi/utils.py
+++ b/fastapi/utils.py
@@ -52,7 +52,7 @@ def create_response_field(
Create a new response field. Raises if type_ is invalid.
"""
class_validators = class_validators or {}
- field_info = field_info or FieldInfo(None)
+ field_info = field_info or FieldInfo()
response_field = functools.partial(
ModelField,
@@ -147,15 +147,15 @@ def generate_unique_id(route: "APIRoute") -> str:
def deep_dict_update(main_dict: Dict[Any, Any], update_dict: Dict[Any, Any]) -> None:
- for key in update_dict:
+ for key, value in update_dict.items():
if (
key in main_dict
and isinstance(main_dict[key], dict)
- and isinstance(update_dict[key], dict)
+ and isinstance(value, dict)
):
- deep_dict_update(main_dict[key], update_dict[key])
+ deep_dict_update(main_dict[key], value)
else:
- main_dict[key] = update_dict[key]
+ main_dict[key] = value
def get_value_or_default(
diff --git a/pending_tests/main.py b/pending_tests/main.py
deleted file mode 100644
index 5e919f1bc..000000000
--- a/pending_tests/main.py
+++ /dev/null
@@ -1,118 +0,0 @@
-from fastapi import (
- Body,
- Cookie,
- Depends,
- FastAPI,
- File,
- Form,
- Header,
- Path,
- Query,
- Security,
-)
-from fastapi.security import (
- HTTPBasic,
- OAuth2,
- OAuth2PasswordBearer,
- OAuth2PasswordRequestForm,
-)
-from pydantic import BaseModel
-from starlette.responses import HTMLResponse, JSONResponse, PlainTextResponse
-from starlette.status import HTTP_202_ACCEPTED
-
-app = FastAPI()
-
-
-@app.get("/security")
-def get_security(sec=Security(HTTPBasic())):
- return sec
-
-
-reusable_oauth2 = OAuth2(
- flows={
- "password": {
- "tokenUrl": "token",
- "scopes": {"read:user": "Read a User", "write:user": "Create a user"},
- }
- }
-)
-
-
-@app.get("/security/oauth2")
-def get_security_oauth2(sec=Security(reusable_oauth2, scopes=["read:user"])):
- return sec
-
-
-@app.post("/token")
-def post_token(request_data: OAuth2PasswordRequestForm = Form(...)):
- data = request_data.parse()
- access_token = data.username + ":" + data.password
- return {"access_token": access_token}
-
-
-class Item(BaseModel):
- name: str
- price: float
- is_offer: bool
-
-
-class FakeDB:
- def __init__(self):
- self.data = {
- "johndoe": {
- "username": "johndoe",
- "password": "shouldbehashed",
- "first_name": "John",
- "last_name": "Doe",
- }
- }
-
-
-class DBConnectionManager:
- def __init__(self):
- self.db = FakeDB()
-
- def __call__(self):
- return self.db
-
-
-connection_manager = DBConnectionManager()
-
-
-class TokenUserData(BaseModel):
- username: str
- password: str
-
-
-class UserInDB(BaseModel):
- username: str
- password: str
- first_name: str
- last_name: str
-
-
-def require_token(
- token: str = Security(reusable_oauth2, scopes=["read:user", "write:user"])
-):
- raw_token = token.replace("Bearer ", "")
- # Never do this plaintext password usage in production
- username, password = raw_token.split(":")
- return TokenUserData(username=username, password=password)
-
-
-def require_user(
- db: FakeDB = Depends(connection_manager),
- user_data: TokenUserData = Depends(require_token),
-):
- return db.data[user_data.username]
-
-
-class UserOut(BaseModel):
- username: str
- first_name: str
- last_name: str
-
-
-@app.get("/dependency", response_model=UserOut)
-def get_dependency(user: UserInDB = Depends(require_user)):
- return user
diff --git a/pyproject.toml b/pyproject.toml
index 1a2610740..5ffdf93ad 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -35,7 +35,7 @@ classifiers = [
"Topic :: Internet :: WWW/HTTP",
]
requires = [
- "starlette ==0.18.0",
+ "starlette==0.19.1",
"pydantic >=1.6.2,!=1.7,!=1.7.1,!=1.7.2,!=1.7.3,!=1.8,!=1.8.1,<2.0.0",
]
description-file = "README.md"
@@ -85,6 +85,7 @@ dev = [
"autoflake >=1.4.0,<2.0.0",
"flake8 >=3.8.3,<4.0.0",
"uvicorn[standard] >=0.12.0,<0.18.0",
+ "pre-commit >=2.17.0,<3.0.0",
]
all = [
"requests >=2.24.0,<3.0.0",
@@ -140,6 +141,7 @@ filterwarnings = [
"error",
# TODO: needed by asyncio in Python 3.9.7 https://bugs.python.org/issue45097, try to remove on 3.9.8
'ignore:The loop argument is deprecated since Python 3\.8, and scheduled for removal in Python 3\.10:DeprecationWarning:asyncio',
+ 'ignore:starlette.middleware.wsgi is deprecated and will be removed in a future release\..*:DeprecationWarning:starlette',
# TODO: remove after dropping support for Python 3.6
'ignore:Python 3.6 is no longer supported by the Python core team. Therefore, support for it is deprecated in cryptography and will be removed in a future release.:UserWarning:jose',
]
diff --git a/tests/main.py b/tests/main.py
index d5603d0e6..f70496db8 100644
--- a/tests/main.py
+++ b/tests/main.py
@@ -49,97 +49,97 @@ def get_bool_id(item_id: bool):
@app.get("/path/param/{item_id}")
-def get_path_param_id(item_id: Optional[str] = Path(None)):
+def get_path_param_id(item_id: str = Path()):
return item_id
@app.get("/path/param-required/{item_id}")
-def get_path_param_required_id(item_id: str = Path(...)):
+def get_path_param_required_id(item_id: str = Path()):
return item_id
@app.get("/path/param-minlength/{item_id}")
-def get_path_param_min_length(item_id: str = Path(..., min_length=3)):
+def get_path_param_min_length(item_id: str = Path(min_length=3)):
return item_id
@app.get("/path/param-maxlength/{item_id}")
-def get_path_param_max_length(item_id: str = Path(..., max_length=3)):
+def get_path_param_max_length(item_id: str = Path(max_length=3)):
return item_id
@app.get("/path/param-min_maxlength/{item_id}")
-def get_path_param_min_max_length(item_id: str = Path(..., max_length=3, min_length=2)):
+def get_path_param_min_max_length(item_id: str = Path(max_length=3, min_length=2)):
return item_id
@app.get("/path/param-gt/{item_id}")
-def get_path_param_gt(item_id: float = Path(..., gt=3)):
+def get_path_param_gt(item_id: float = Path(gt=3)):
return item_id
@app.get("/path/param-gt0/{item_id}")
-def get_path_param_gt0(item_id: float = Path(..., gt=0)):
+def get_path_param_gt0(item_id: float = Path(gt=0)):
return item_id
@app.get("/path/param-ge/{item_id}")
-def get_path_param_ge(item_id: float = Path(..., ge=3)):
+def get_path_param_ge(item_id: float = Path(ge=3)):
return item_id
@app.get("/path/param-lt/{item_id}")
-def get_path_param_lt(item_id: float = Path(..., lt=3)):
+def get_path_param_lt(item_id: float = Path(lt=3)):
return item_id
@app.get("/path/param-lt0/{item_id}")
-def get_path_param_lt0(item_id: float = Path(..., lt=0)):
+def get_path_param_lt0(item_id: float = Path(lt=0)):
return item_id
@app.get("/path/param-le/{item_id}")
-def get_path_param_le(item_id: float = Path(..., le=3)):
+def get_path_param_le(item_id: float = Path(le=3)):
return item_id
@app.get("/path/param-lt-gt/{item_id}")
-def get_path_param_lt_gt(item_id: float = Path(..., lt=3, gt=1)):
+def get_path_param_lt_gt(item_id: float = Path(lt=3, gt=1)):
return item_id
@app.get("/path/param-le-ge/{item_id}")
-def get_path_param_le_ge(item_id: float = Path(..., le=3, ge=1)):
+def get_path_param_le_ge(item_id: float = Path(le=3, ge=1)):
return item_id
@app.get("/path/param-lt-int/{item_id}")
-def get_path_param_lt_int(item_id: int = Path(..., lt=3)):
+def get_path_param_lt_int(item_id: int = Path(lt=3)):
return item_id
@app.get("/path/param-gt-int/{item_id}")
-def get_path_param_gt_int(item_id: int = Path(..., gt=3)):
+def get_path_param_gt_int(item_id: int = Path(gt=3)):
return item_id
@app.get("/path/param-le-int/{item_id}")
-def get_path_param_le_int(item_id: int = Path(..., le=3)):
+def get_path_param_le_int(item_id: int = Path(le=3)):
return item_id
@app.get("/path/param-ge-int/{item_id}")
-def get_path_param_ge_int(item_id: int = Path(..., ge=3)):
+def get_path_param_ge_int(item_id: int = Path(ge=3)):
return item_id
@app.get("/path/param-lt-gt-int/{item_id}")
-def get_path_param_lt_gt_int(item_id: int = Path(..., lt=3, gt=1)):
+def get_path_param_lt_gt_int(item_id: int = Path(lt=3, gt=1)):
return item_id
@app.get("/path/param-le-ge-int/{item_id}")
-def get_path_param_le_ge_int(item_id: int = Path(..., le=3, ge=1)):
+def get_path_param_le_ge_int(item_id: int = Path(le=3, ge=1)):
return item_id
@@ -173,19 +173,19 @@ def get_query_type_int_default(query: int = 10):
@app.get("/query/param")
-def get_query_param(query=Query(None)):
+def get_query_param(query=Query(default=None)):
if query is None:
return "foo bar"
return f"foo bar {query}"
@app.get("/query/param-required")
-def get_query_param_required(query=Query(...)):
+def get_query_param_required(query=Query()):
return f"foo bar {query}"
@app.get("/query/param-required/int")
-def get_query_param_required_type(query: int = Query(...)):
+def get_query_param_required_type(query: int = Query()):
return f"foo bar {query}"
diff --git a/tests/test_dependency_normal_exceptions.py b/tests/test_dependency_normal_exceptions.py
index 49a19f460..23c366d5d 100644
--- a/tests/test_dependency_normal_exceptions.py
+++ b/tests/test_dependency_normal_exceptions.py
@@ -26,14 +26,14 @@ async def get_database():
@app.put("/invalid-user/{user_id}")
def put_invalid_user(
- user_id: str, name: str = Body(...), db: dict = Depends(get_database)
+ user_id: str, name: str = Body(), db: dict = Depends(get_database)
):
db[user_id] = name
raise HTTPException(status_code=400, detail="Invalid user")
@app.put("/user/{user_id}")
-def put_user(user_id: str, name: str = Body(...), db: dict = Depends(get_database)):
+def put_user(user_id: str, name: str = Body(), db: dict = Depends(get_database)):
db[user_id] = name
return {"message": "OK"}
diff --git a/tests/test_extra_routes.py b/tests/test_extra_routes.py
index 8f95b7bc9..491ba61c6 100644
--- a/tests/test_extra_routes.py
+++ b/tests/test_extra_routes.py
@@ -32,12 +32,12 @@ def delete_item(item_id: str, item: Item):
@app.head("/items/{item_id}")
def head_item(item_id: str):
- return JSONResponse(headers={"x-fastapi-item-id": item_id})
+ return JSONResponse(None, headers={"x-fastapi-item-id": item_id})
@app.options("/items/{item_id}")
def options_item(item_id: str):
- return JSONResponse(headers={"x-fastapi-item-id": item_id})
+ return JSONResponse(None, headers={"x-fastapi-item-id": item_id})
@app.patch("/items/{item_id}")
@@ -47,7 +47,7 @@ def patch_item(item_id: str, item: Item):
@app.trace("/items/{item_id}")
def trace_item(item_id: str):
- return JSONResponse(media_type="message/http")
+ return JSONResponse(None, media_type="message/http")
client = TestClient(app)
diff --git a/tests/test_forms_from_non_typing_sequences.py b/tests/test_forms_from_non_typing_sequences.py
index be917eab7..52ce24753 100644
--- a/tests/test_forms_from_non_typing_sequences.py
+++ b/tests/test_forms_from_non_typing_sequences.py
@@ -5,17 +5,17 @@ app = FastAPI()
@app.post("/form/python-list")
-def post_form_param_list(items: list = Form(...)):
+def post_form_param_list(items: list = Form()):
return items
@app.post("/form/python-set")
-def post_form_param_set(items: set = Form(...)):
+def post_form_param_set(items: set = Form()):
return items
@app.post("/form/python-tuple")
-def post_form_param_tuple(items: tuple = Form(...)):
+def post_form_param_tuple(items: tuple = Form()):
return items
diff --git a/tests/test_invalid_sequence_param.py b/tests/test_invalid_sequence_param.py
index f00dd7b93..475786adb 100644
--- a/tests/test_invalid_sequence_param.py
+++ b/tests/test_invalid_sequence_param.py
@@ -13,7 +13,7 @@ def test_invalid_sequence():
title: str
@app.get("/items/")
- def read_items(q: List[Item] = Query(None)):
+ def read_items(q: List[Item] = Query(default=None)):
pass # pragma: no cover
@@ -25,7 +25,7 @@ def test_invalid_tuple():
title: str
@app.get("/items/")
- def read_items(q: Tuple[Item, Item] = Query(None)):
+ def read_items(q: Tuple[Item, Item] = Query(default=None)):
pass # pragma: no cover
@@ -37,7 +37,7 @@ def test_invalid_dict():
title: str
@app.get("/items/")
- def read_items(q: Dict[str, Item] = Query(None)):
+ def read_items(q: Dict[str, Item] = Query(default=None)):
pass # pragma: no cover
@@ -49,5 +49,5 @@ def test_invalid_simple_dict():
title: str
@app.get("/items/")
- def read_items(q: Optional[dict] = Query(None)):
+ def read_items(q: Optional[dict] = Query(default=None)):
pass # pragma: no cover
diff --git a/tests/test_jsonable_encoder.py b/tests/test_jsonable_encoder.py
index fa82b5ea8..ed35fd32e 100644
--- a/tests/test_jsonable_encoder.py
+++ b/tests/test_jsonable_encoder.py
@@ -67,7 +67,7 @@ class ModelWithConfig(BaseModel):
class ModelWithAlias(BaseModel):
- foo: str = Field(..., alias="Foo")
+ foo: str = Field(alias="Foo")
class ModelWithDefault(BaseModel):
diff --git a/tests/test_modules_same_name_body/app/a.py b/tests/test_modules_same_name_body/app/a.py
index 3c86c1865..377236890 100644
--- a/tests/test_modules_same_name_body/app/a.py
+++ b/tests/test_modules_same_name_body/app/a.py
@@ -4,5 +4,5 @@ router = APIRouter()
@router.post("/compute")
-def compute(a: int = Body(...), b: str = Body(...)):
+def compute(a: int = Body(), b: str = Body()):
return {"a": a, "b": b}
diff --git a/tests/test_modules_same_name_body/app/b.py b/tests/test_modules_same_name_body/app/b.py
index f7c7fdfc6..b62118f84 100644
--- a/tests/test_modules_same_name_body/app/b.py
+++ b/tests/test_modules_same_name_body/app/b.py
@@ -4,5 +4,5 @@ router = APIRouter()
@router.post("/compute/")
-def compute(a: int = Body(...), b: str = Body(...)):
+def compute(a: int = Body(), b: str = Body()):
return {"a": a, "b": b}
diff --git a/tests/test_multi_query_errors.py b/tests/test_multi_query_errors.py
index 0a15833fa..3da461af5 100644
--- a/tests/test_multi_query_errors.py
+++ b/tests/test_multi_query_errors.py
@@ -7,7 +7,7 @@ app = FastAPI()
@app.get("/items/")
-def read_items(q: List[int] = Query(None)):
+def read_items(q: List[int] = Query(default=None)):
return {"q": q}
diff --git a/tests/test_multipart_installation.py b/tests/test_multipart_installation.py
index c8a6fd942..788d9ef5a 100644
--- a/tests/test_multipart_installation.py
+++ b/tests/test_multipart_installation.py
@@ -12,7 +12,7 @@ def test_incorrect_multipart_installed_form(monkeypatch):
app = FastAPI()
@app.post("/")
- async def root(username: str = Form(...)):
+ async def root(username: str = Form()):
return username # pragma: nocover
@@ -22,7 +22,7 @@ def test_incorrect_multipart_installed_file_upload(monkeypatch):
app = FastAPI()
@app.post("/")
- async def root(f: UploadFile = File(...)):
+ async def root(f: UploadFile = File()):
return f # pragma: nocover
@@ -32,7 +32,7 @@ def test_incorrect_multipart_installed_file_bytes(monkeypatch):
app = FastAPI()
@app.post("/")
- async def root(f: bytes = File(...)):
+ async def root(f: bytes = File()):
return f # pragma: nocover
@@ -42,7 +42,7 @@ def test_incorrect_multipart_installed_multi_form(monkeypatch):
app = FastAPI()
@app.post("/")
- async def root(username: str = Form(...), password: str = Form(...)):
+ async def root(username: str = Form(), password: str = Form()):
return username # pragma: nocover
@@ -52,7 +52,7 @@ def test_incorrect_multipart_installed_form_file(monkeypatch):
app = FastAPI()
@app.post("/")
- async def root(username: str = Form(...), f: UploadFile = File(...)):
+ async def root(username: str = Form(), f: UploadFile = File()):
return username # pragma: nocover
@@ -62,7 +62,7 @@ def test_no_multipart_installed(monkeypatch):
app = FastAPI()
@app.post("/")
- async def root(username: str = Form(...)):
+ async def root(username: str = Form()):
return username # pragma: nocover
@@ -72,7 +72,7 @@ def test_no_multipart_installed_file(monkeypatch):
app = FastAPI()
@app.post("/")
- async def root(f: UploadFile = File(...)):
+ async def root(f: UploadFile = File()):
return f # pragma: nocover
@@ -82,7 +82,7 @@ def test_no_multipart_installed_file_bytes(monkeypatch):
app = FastAPI()
@app.post("/")
- async def root(f: bytes = File(...)):
+ async def root(f: bytes = File()):
return f # pragma: nocover
@@ -92,7 +92,7 @@ def test_no_multipart_installed_multi_form(monkeypatch):
app = FastAPI()
@app.post("/")
- async def root(username: str = Form(...), password: str = Form(...)):
+ async def root(username: str = Form(), password: str = Form()):
return username # pragma: nocover
@@ -102,5 +102,5 @@ def test_no_multipart_installed_form_file(monkeypatch):
app = FastAPI()
@app.post("/")
- async def root(username: str = Form(...), f: UploadFile = File(...)):
+ async def root(username: str = Form(), f: UploadFile = File()):
return username # pragma: nocover
diff --git a/tests/test_param_class.py b/tests/test_param_class.py
index f5767ec96..1fd40dcd2 100644
--- a/tests/test_param_class.py
+++ b/tests/test_param_class.py
@@ -8,7 +8,7 @@ app = FastAPI()
@app.get("/items/")
-def read_items(q: Optional[str] = Param(None)): # type: ignore
+def read_items(q: Optional[str] = Param(default=None)): # type: ignore
return {"q": q}
diff --git a/tests/test_param_include_in_schema.py b/tests/test_param_include_in_schema.py
index 26aa63897..214f039b6 100644
--- a/tests/test_param_include_in_schema.py
+++ b/tests/test_param_include_in_schema.py
@@ -9,26 +9,26 @@ app = FastAPI()
@app.get("/hidden_cookie")
async def hidden_cookie(
- hidden_cookie: Optional[str] = Cookie(None, include_in_schema=False)
+ hidden_cookie: Optional[str] = Cookie(default=None, include_in_schema=False)
):
return {"hidden_cookie": hidden_cookie}
@app.get("/hidden_header")
async def hidden_header(
- hidden_header: Optional[str] = Header(None, include_in_schema=False)
+ hidden_header: Optional[str] = Header(default=None, include_in_schema=False)
):
return {"hidden_header": hidden_header}
@app.get("/hidden_path/{hidden_path}")
-async def hidden_path(hidden_path: str = Path(..., include_in_schema=False)):
+async def hidden_path(hidden_path: str = Path(include_in_schema=False)):
return {"hidden_path": hidden_path}
@app.get("/hidden_query")
async def hidden_query(
- hidden_query: Optional[str] = Query(None, include_in_schema=False)
+ hidden_query: Optional[str] = Query(default=None, include_in_schema=False)
):
return {"hidden_query": hidden_query}
diff --git a/tests/test_repeated_dependency_schema.py b/tests/test_repeated_dependency_schema.py
index 00441694e..ca0305184 100644
--- a/tests/test_repeated_dependency_schema.py
+++ b/tests/test_repeated_dependency_schema.py
@@ -4,7 +4,7 @@ from fastapi.testclient import TestClient
app = FastAPI()
-def get_header(*, someheader: str = Header(...)):
+def get_header(*, someheader: str = Header()):
return someheader
diff --git a/tests/test_request_body_parameters_media_type.py b/tests/test_request_body_parameters_media_type.py
index ace6bdef7..e9cf4006d 100644
--- a/tests/test_request_body_parameters_media_type.py
+++ b/tests/test_request_body_parameters_media_type.py
@@ -21,14 +21,14 @@ class Shop(BaseModel):
@app.post("/products")
-async def create_product(data: Product = Body(..., media_type=media_type, embed=True)):
+async def create_product(data: Product = Body(media_type=media_type, embed=True)):
pass # pragma: no cover
@app.post("/shops")
async def create_shop(
- data: Shop = Body(..., media_type=media_type),
- included: typing.List[Product] = Body([], media_type=media_type),
+ data: Shop = Body(media_type=media_type),
+ included: typing.List[Product] = Body(default=[], media_type=media_type),
):
pass # pragma: no cover
diff --git a/tests/test_required_noneable.py b/tests/test_required_noneable.py
new file mode 100644
index 000000000..5da8cd4d0
--- /dev/null
+++ b/tests/test_required_noneable.py
@@ -0,0 +1,62 @@
+from typing import Union
+
+from fastapi import Body, FastAPI, Query
+from fastapi.testclient import TestClient
+
+app = FastAPI()
+
+
+@app.get("/query")
+def read_query(q: Union[str, None]):
+ return q
+
+
+@app.get("/explicit-query")
+def read_explicit_query(q: Union[str, None] = Query()):
+ return q
+
+
+@app.post("/body-embed")
+def send_body_embed(b: Union[str, None] = Body(embed=True)):
+ return b
+
+
+client = TestClient(app)
+
+
+def test_required_nonable_query_invalid():
+ response = client.get("/query")
+ assert response.status_code == 422
+
+
+def test_required_noneable_query_value():
+ response = client.get("/query", params={"q": "foo"})
+ assert response.status_code == 200
+ assert response.json() == "foo"
+
+
+def test_required_nonable_explicit_query_invalid():
+ response = client.get("/explicit-query")
+ assert response.status_code == 422
+
+
+def test_required_nonable_explicit_query_value():
+ response = client.get("/explicit-query", params={"q": "foo"})
+ assert response.status_code == 200
+ assert response.json() == "foo"
+
+
+def test_required_nonable_body_embed_no_content():
+ response = client.post("/body-embed")
+ assert response.status_code == 422
+
+
+def test_required_nonable_body_embed_invalid():
+ response = client.post("/body-embed", json={"invalid": "invalid"})
+ assert response.status_code == 422
+
+
+def test_required_noneable_body_embed_value():
+ response = client.post("/body-embed", json={"b": "foo"})
+ assert response.status_code == 200
+ assert response.json() == "foo"
diff --git a/tests/test_schema_extra_examples.py b/tests/test_schema_extra_examples.py
index 444e350a8..5047aeaa4 100644
--- a/tests/test_schema_extra_examples.py
+++ b/tests/test_schema_extra_examples.py
@@ -1,3 +1,5 @@
+from typing import Union
+
from fastapi import Body, Cookie, FastAPI, Header, Path, Query
from fastapi.testclient import TestClient
from pydantic import BaseModel
@@ -18,14 +20,13 @@ def schema_extra(item: Item):
@app.post("/example/")
-def example(item: Item = Body(..., example={"data": "Data in Body example"})):
+def example(item: Item = Body(example={"data": "Data in Body example"})):
return item
@app.post("/examples/")
def examples(
item: Item = Body(
- ...,
examples={
"example1": {
"summary": "example1 summary",
@@ -41,7 +42,6 @@ def examples(
@app.post("/example_examples/")
def example_examples(
item: Item = Body(
- ...,
example={"data": "Overriden example"},
examples={
"example1": {"value": {"data": "examples example_examples 1"}},
@@ -55,7 +55,7 @@ def example_examples(
# TODO: enable these tests once/if Form(embed=False) is supported
# TODO: In that case, define if File() should support example/examples too
# @app.post("/form_example")
-# def form_example(firstname: str = Form(..., example="John")):
+# def form_example(firstname: str = Form(example="John")):
# return firstname
@@ -89,7 +89,6 @@ def example_examples(
@app.get("/path_example/{item_id}")
def path_example(
item_id: str = Path(
- ...,
example="item_1",
),
):
@@ -99,7 +98,6 @@ def path_example(
@app.get("/path_examples/{item_id}")
def path_examples(
item_id: str = Path(
- ...,
examples={
"example1": {"summary": "item ID summary", "value": "item_1"},
"example2": {"value": "item_2"},
@@ -112,7 +110,6 @@ def path_examples(
@app.get("/path_example_examples/{item_id}")
def path_example_examples(
item_id: str = Path(
- ...,
example="item_overriden",
examples={
"example1": {"summary": "item ID summary", "value": "item_1"},
@@ -125,8 +122,8 @@ def path_example_examples(
@app.get("/query_example/")
def query_example(
- data: str = Query(
- None,
+ data: Union[str, None] = Query(
+ default=None,
example="query1",
),
):
@@ -135,8 +132,8 @@ def query_example(
@app.get("/query_examples/")
def query_examples(
- data: str = Query(
- None,
+ data: Union[str, None] = Query(
+ default=None,
examples={
"example1": {"summary": "Query example 1", "value": "query1"},
"example2": {"value": "query2"},
@@ -148,8 +145,8 @@ def query_examples(
@app.get("/query_example_examples/")
def query_example_examples(
- data: str = Query(
- None,
+ data: Union[str, None] = Query(
+ default=None,
example="query_overriden",
examples={
"example1": {"summary": "Qeury example 1", "value": "query1"},
@@ -162,8 +159,8 @@ def query_example_examples(
@app.get("/header_example/")
def header_example(
- data: str = Header(
- None,
+ data: Union[str, None] = Header(
+ default=None,
example="header1",
),
):
@@ -172,8 +169,8 @@ def header_example(
@app.get("/header_examples/")
def header_examples(
- data: str = Header(
- None,
+ data: Union[str, None] = Header(
+ default=None,
examples={
"example1": {"summary": "header example 1", "value": "header1"},
"example2": {"value": "header2"},
@@ -185,8 +182,8 @@ def header_examples(
@app.get("/header_example_examples/")
def header_example_examples(
- data: str = Header(
- None,
+ data: Union[str, None] = Header(
+ default=None,
example="header_overriden",
examples={
"example1": {"summary": "Qeury example 1", "value": "header1"},
@@ -199,8 +196,8 @@ def header_example_examples(
@app.get("/cookie_example/")
def cookie_example(
- data: str = Cookie(
- None,
+ data: Union[str, None] = Cookie(
+ default=None,
example="cookie1",
),
):
@@ -209,8 +206,8 @@ def cookie_example(
@app.get("/cookie_examples/")
def cookie_examples(
- data: str = Cookie(
- None,
+ data: Union[str, None] = Cookie(
+ default=None,
examples={
"example1": {"summary": "cookie example 1", "value": "cookie1"},
"example2": {"value": "cookie2"},
@@ -222,8 +219,8 @@ def cookie_examples(
@app.get("/cookie_example_examples/")
def cookie_example_examples(
- data: str = Cookie(
- None,
+ data: Union[str, None] = Cookie(
+ default=None,
example="cookie_overriden",
examples={
"example1": {"summary": "Qeury example 1", "value": "cookie1"},
diff --git a/tests/test_serialize_response_model.py b/tests/test_serialize_response_model.py
index 295667437..3bb46b2e9 100644
--- a/tests/test_serialize_response_model.py
+++ b/tests/test_serialize_response_model.py
@@ -8,7 +8,7 @@ app = FastAPI()
class Item(BaseModel):
- name: str = Field(..., alias="aliased_name")
+ name: str = Field(alias="aliased_name")
price: Optional[float] = None
owner_ids: Optional[List[int]] = None
diff --git a/tests/test_starlette_urlconvertors.py b/tests/test_starlette_urlconvertors.py
index 2320c7005..5a980cbf6 100644
--- a/tests/test_starlette_urlconvertors.py
+++ b/tests/test_starlette_urlconvertors.py
@@ -5,17 +5,17 @@ app = FastAPI()
@app.get("/int/{param:int}")
-def int_convertor(param: int = Path(...)):
+def int_convertor(param: int = Path()):
return {"int": param}
@app.get("/float/{param:float}")
-def float_convertor(param: float = Path(...)):
+def float_convertor(param: float = Path()):
return {"float": param}
@app.get("/path/{param:path}")
-def path_convertor(param: str = Path(...)):
+def path_convertor(param: str = Path()):
return {"path": param}
diff --git a/tests/test_tuples.py b/tests/test_tuples.py
index 2085dc367..18ec2d048 100644
--- a/tests/test_tuples.py
+++ b/tests/test_tuples.py
@@ -27,7 +27,7 @@ def post_tuple_of_models(square: Tuple[Coordinate, Coordinate]):
@app.post("/tuple-form/")
-def hello(values: Tuple[int, int] = Form(...)):
+def hello(values: Tuple[int, int] = Form()):
return values
De la même façon, il existe bien d'autres outils compatibles, y compris des outils de génération de code
-pour de nombreux langages.
+pour de nombreux langages.
## Pydantic
diff --git a/docs/fr/docs/tutorial/query-params.md b/docs/fr/docs/tutorial/query-params.md
index f1f2a605d..7bf3b9e79 100644
--- a/docs/fr/docs/tutorial/query-params.md
+++ b/docs/fr/docs/tutorial/query-params.md
@@ -6,7 +6,7 @@ Quand vous déclarez des paramètres dans votre fonction de chemin qui ne font p
{!../../../docs_src/query_params/tutorial001.py!}
```
-La partie appelée requête (ou **query**) dans une URL est l'ensemble des paires clés-valeurs placées après le `?` , séparées par des `&`.
+La partie appelée requête (ou **query**) dans une URL est l'ensemble des paires clés-valeurs placées après le `?` , séparées par des `&`.
Par exemple, dans l'URL :
@@ -120,7 +120,7 @@ ou n'importe quelle autre variation de casse (tout en majuscules, uniquement la
## Multiples paramètres de chemin et de requête
-Vous pouvez déclarer plusieurs paramètres de chemin et paramètres de requête dans la même fonction, **FastAPI** saura comment les gérer.
+Vous pouvez déclarer plusieurs paramètres de chemin et paramètres de requête dans la même fonction, **FastAPI** saura comment les gérer.
Et vous n'avez pas besoin de les déclarer dans un ordre spécifique.
diff --git a/docs/fr/mkdocs.yml b/docs/fr/mkdocs.yml
index d2681f8d5..bf0d2b21c 100644
--- a/docs/fr/mkdocs.yml
+++ b/docs/fr/mkdocs.yml
@@ -5,13 +5,15 @@ theme:
name: material
custom_dir: overrides
palette:
- - scheme: default
+ - media: "(prefers-color-scheme: light)"
+ scheme: default
primary: teal
accent: amber
toggle:
icon: material/lightbulb
name: Switch to light mode
- - scheme: slate
+ - media: "(prefers-color-scheme: dark)"
+ scheme: slate
primary: teal
accent: amber
toggle:
diff --git a/docs/id/docs/index.md b/docs/id/docs/index.md
index 95fb7ae21..0bb7b55e3 100644
--- a/docs/id/docs/index.md
+++ b/docs/id/docs/index.md
@@ -321,7 +321,7 @@ And now, go to