From 89789c80aeb3743bd76486f3d28a174f1815c771 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Wed, 4 Oct 2023 17:51:10 -0500 Subject: [PATCH 01/38] =?UTF-8?q?=F0=9F=94=A7=20Update=20sponsors,=20Bump.?= =?UTF-8?q?sh=20images=20(#10381)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- docs/en/data/sponsors.yml | 2 +- docs/en/docs/img/sponsors/bump-sh-banner.svg | 48 +++++++++++++++++ docs/en/docs/img/sponsors/bump-sh.svg | 56 ++++++++++++++++++++ docs/en/overrides/main.html | 2 +- 5 files changed, 107 insertions(+), 3 deletions(-) create mode 100644 docs/en/docs/img/sponsors/bump-sh-banner.svg create mode 100644 docs/en/docs/img/sponsors/bump-sh.svg diff --git a/README.md b/README.md index b86143f3d..3f125e60e 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ The key features are: - + diff --git a/docs/en/data/sponsors.yml b/docs/en/data/sponsors.yml index cea547a10..dac47d2f0 100644 --- a/docs/en/data/sponsors.yml +++ b/docs/en/data/sponsors.yml @@ -13,7 +13,7 @@ gold: img: https://fastapi.tiangolo.com/img/sponsors/porter.png - url: https://bump.sh/fastapi?utm_source=fastapi&utm_medium=referral&utm_campaign=sponsor title: Automate FastAPI documentation generation with Bump.sh - img: https://fastapi.tiangolo.com/img/sponsors/bump-sh.png + img: https://fastapi.tiangolo.com/img/sponsors/bump-sh.svg silver: - url: https://www.deta.sh/?ref=fastapi title: The launchpad for all your (team's) ideas diff --git a/docs/en/docs/img/sponsors/bump-sh-banner.svg b/docs/en/docs/img/sponsors/bump-sh-banner.svg new file mode 100644 index 000000000..c8ec7675a --- /dev/null +++ b/docs/en/docs/img/sponsors/bump-sh-banner.svg @@ -0,0 +1,48 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/docs/img/sponsors/bump-sh.svg b/docs/en/docs/img/sponsors/bump-sh.svg new file mode 100644 index 000000000..053e54b1d --- /dev/null +++ b/docs/en/docs/img/sponsors/bump-sh.svg @@ -0,0 +1,56 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/overrides/main.html b/docs/en/overrides/main.html index d867d2ee5..4c7f19fd4 100644 --- a/docs/en/overrides/main.html +++ b/docs/en/overrides/main.html @@ -49,7 +49,7 @@
- +
From c1adce4fe93a0035e69988f7e051cfab97d8acef Mon Sep 17 00:00:00 2001 From: github-actions Date: Wed, 4 Oct 2023 22:52:00 +0000 Subject: [PATCH 02/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 87476fd1e..3c7ecad43 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -2,6 +2,7 @@ ## Latest Changes +* ๐Ÿ”ง Update sponsors, Bump.sh images. PR [#10381](https://github.com/tiangolo/fastapi/pull/10381) by [@tiangolo](https://github.com/tiangolo). * ๐Ÿ‘ฅ Update FastAPI People. PR [#10363](https://github.com/tiangolo/fastapi/pull/10363) by [@tiangolo](https://github.com/tiangolo). ## 0.103.2 From 2ba7586ff3f4dca379043489141c6d07cb2451bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Tue, 17 Oct 2023 09:59:11 +0400 Subject: [PATCH 03/38] =?UTF-8?q?=E2=AC=86=EF=B8=8F=20Drop=20support=20for?= =?UTF-8?q?=20Python=203.7,=20require=20Python=203.8=20or=20above=20(#1044?= =?UTF-8?q?2)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * ๐Ÿ“ Update docs, require Python 3.8+, drop 3.7 * ๐Ÿ”ง Update pyproject.toml, drop support for Python 3.7, require Python 3.8+ * ๐Ÿ‘ท Update CI GitHub Actions, drop support for Python 3.7, require 3.8+ * ๐Ÿ“ Update docs' references to Python 3.6 and 3.7, use Python 3.8 --- .github/workflows/publish.yml | 2 +- .github/workflows/test.yml | 2 +- README.md | 6 +- docs/de/docs/features.md | 2 +- .../docs/advanced/additional-status-codes.md | 4 +- .../en/docs/advanced/advanced-dependencies.md | 16 ++--- docs/en/docs/advanced/generate-clients.md | 6 +- .../docs/advanced/security/http-basic-auth.md | 12 ++-- .../docs/advanced/security/oauth2-scopes.md | 32 ++++----- docs/en/docs/advanced/settings.md | 12 ++-- docs/en/docs/advanced/testing-dependencies.md | 4 +- docs/en/docs/advanced/websockets.md | 6 +- .../docs/how-to/separate-openapi-schemas.md | 8 +-- docs/en/docs/index.md | 6 +- docs/en/docs/python-types.md | 24 +++---- docs/en/docs/tutorial/background-tasks.md | 4 +- docs/en/docs/tutorial/bigger-applications.md | 4 +- docs/en/docs/tutorial/body-fields.md | 8 +-- docs/en/docs/tutorial/body-multiple-params.md | 18 ++--- docs/en/docs/tutorial/body-nested-models.md | 20 +++--- docs/en/docs/tutorial/body-updates.md | 8 +-- docs/en/docs/tutorial/body.md | 12 ++-- docs/en/docs/tutorial/cookie-params.md | 8 +-- .../dependencies/classes-as-dependencies.md | 52 +++++++------- ...pendencies-in-path-operation-decorators.md | 16 ++--- .../dependencies/dependencies-with-yield.md | 8 +-- .../dependencies/global-dependencies.md | 4 +- docs/en/docs/tutorial/dependencies/index.md | 14 ++-- .../tutorial/dependencies/sub-dependencies.md | 16 ++--- docs/en/docs/tutorial/encoder.md | 2 +- docs/en/docs/tutorial/extra-data-types.md | 8 +-- docs/en/docs/tutorial/extra-models.md | 10 +-- docs/en/docs/tutorial/header-params.md | 16 ++--- .../tutorial/path-operation-configuration.md | 10 +-- .../path-params-numeric-validations.md | 26 +++---- .../tutorial/query-params-str-validations.md | 72 +++++++++---------- docs/en/docs/tutorial/query-params.md | 8 +-- docs/en/docs/tutorial/request-files.md | 28 ++++---- .../docs/tutorial/request-forms-and-files.md | 8 +-- docs/en/docs/tutorial/request-forms.md | 8 +-- docs/en/docs/tutorial/response-model.md | 28 ++++---- docs/en/docs/tutorial/schema-extra-example.md | 18 ++--- docs/en/docs/tutorial/security/first-steps.md | 12 ++-- .../tutorial/security/get-current-user.md | 24 +++---- docs/en/docs/tutorial/security/oauth2-jwt.md | 16 ++--- .../docs/tutorial/security/simple-oauth2.md | 20 +++--- docs/en/docs/tutorial/sql-databases.md | 20 +++--- docs/en/docs/tutorial/testing.md | 4 +- docs/es/docs/features.md | 2 +- docs/es/docs/index.md | 6 +- docs/fr/docs/features.md | 2 +- docs/fr/docs/index.md | 6 +- docs/ja/docs/features.md | 2 +- docs/ja/docs/index.md | 2 +- docs/ko/docs/index.md | 2 +- docs/pl/docs/features.md | 2 +- docs/pl/docs/index.md | 4 +- docs/pt/docs/features.md | 2 +- docs/pt/docs/index.md | 6 +- docs/pt/docs/tutorial/body-multiple-params.md | 10 +-- docs/pt/docs/tutorial/encoder.md | 2 +- docs/pt/docs/tutorial/extra-models.md | 10 +-- docs/pt/docs/tutorial/header-params.md | 8 +-- .../tutorial/path-operation-configuration.md | 10 +-- .../path-params-numeric-validations.md | 4 +- docs/pt/docs/tutorial/query-params.md | 8 +-- docs/ru/docs/features.md | 2 +- docs/ru/docs/index.md | 6 +- docs/ru/docs/tutorial/background-tasks.md | 2 +- docs/ru/docs/tutorial/body-fields.md | 4 +- docs/ru/docs/tutorial/body-multiple-params.md | 18 ++--- docs/ru/docs/tutorial/body-nested-models.md | 20 +++--- docs/ru/docs/tutorial/cookie-params.md | 4 +- .../dependencies/global-dependencies.md | 4 +- docs/ru/docs/tutorial/extra-data-types.md | 4 +- docs/ru/docs/tutorial/extra-models.md | 10 +-- docs/ru/docs/tutorial/header-params.md | 16 ++--- .../tutorial/path-operation-configuration.md | 10 +-- .../path-params-numeric-validations.md | 26 +++---- .../tutorial/query-params-str-validations.md | 72 +++++++++---------- docs/ru/docs/tutorial/query-params.md | 8 +-- docs/ru/docs/tutorial/request-forms.md | 8 +-- docs/ru/docs/tutorial/response-model.md | 28 ++++---- docs/ru/docs/tutorial/schema-extra-example.md | 12 ++-- docs/ru/docs/tutorial/testing.md | 4 +- docs/tr/docs/features.md | 2 +- docs/tr/docs/index.md | 6 +- docs/uk/docs/python-types.md | 22 +++--- docs/uk/docs/tutorial/body.md | 12 ++-- docs/uk/docs/tutorial/cookie-params.md | 8 +-- docs/uk/docs/tutorial/encoder.md | 2 +- docs/uk/docs/tutorial/extra-data-types.md | 8 +-- docs/vi/docs/features.md | 2 +- docs/vi/docs/index.md | 6 +- docs/vi/docs/python-types.md | 18 ++--- docs/yo/docs/index.md | 6 +- docs/zh/docs/advanced/generate-clients.md | 6 +- docs/zh/docs/advanced/settings.md | 12 ++-- docs/zh/docs/advanced/websockets.md | 6 +- docs/zh/docs/index.md | 6 +- docs/zh/docs/tutorial/background-tasks.md | 4 +- docs/zh/docs/tutorial/body-fields.md | 8 +-- docs/zh/docs/tutorial/body-multiple-params.md | 18 ++--- docs/zh/docs/tutorial/body-nested-models.md | 20 +++--- docs/zh/docs/tutorial/body.md | 12 ++-- docs/zh/docs/tutorial/cookie-params.md | 8 +-- .../dependencies/classes-as-dependencies.md | 4 +- docs/zh/docs/tutorial/encoder.md | 2 +- docs/zh/docs/tutorial/extra-data-types.md | 8 +-- docs/zh/docs/tutorial/extra-models.md | 10 +-- docs/zh/docs/tutorial/header-params.md | 16 ++--- .../path-params-numeric-validations.md | 10 +-- .../tutorial/query-params-str-validations.md | 2 +- docs/zh/docs/tutorial/request-files.md | 6 +- docs/zh/docs/tutorial/response-model.md | 8 +-- docs/zh/docs/tutorial/schema-extra-example.md | 8 +-- docs/zh/docs/tutorial/security/first-steps.md | 4 +- docs/zh/docs/tutorial/sql-databases.md | 20 +++--- docs/zh/docs/tutorial/testing.md | 4 +- pyproject.toml | 3 +- 120 files changed, 657 insertions(+), 658 deletions(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index b84c5bf17..5ab0603b9 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -17,7 +17,7 @@ jobs: - name: Set up Python uses: actions/setup-python@v4 with: - python-version: "3.7" + python-version: "3.10" # Issue ref: https://github.com/actions/setup-python/issues/436 # cache: "pip" cache-dependency-path: pyproject.toml diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 4ebc64a14..769b52021 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -42,7 +42,7 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"] + python-version: ["3.8", "3.9", "3.10", "3.11"] pydantic-version: ["pydantic-v1", "pydantic-v2"] fail-fast: false steps: diff --git a/README.md b/README.md index 3f125e60e..aeb29b587 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ --- -FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.7+ based on standard Python type hints. +FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.8+ based on standard Python type hints. The key features are: @@ -120,7 +120,7 @@ If you are building a CLI app to be ## Requirements -Python 3.7+ +Python 3.8+ FastAPI stands on the shoulders of giants: @@ -336,7 +336,7 @@ You do that with standard modern Python types. You don't have to learn a new syntax, the methods or classes of a specific library, etc. -Just standard **Python 3.7+**. +Just standard **Python 3.8+**. For example, for an `int`: diff --git a/docs/de/docs/features.md b/docs/de/docs/features.md index f281afd1e..64fa8092d 100644 --- a/docs/de/docs/features.md +++ b/docs/de/docs/features.md @@ -25,7 +25,7 @@ Mit einer interaktiven API-Dokumentation und explorativen webbasierten Benutzers ### Nur modernes Python -Alles basiert auf **Python 3.6 Typ**-Deklarationen (dank Pydantic). Es muss keine neue Syntax gelernt werden, nur standardisiertes modernes Python. +Alles basiert auf **Python 3.8 Typ**-Deklarationen (dank Pydantic). Es muss keine neue Syntax gelernt werden, nur standardisiertes modernes Python. diff --git a/docs/en/docs/advanced/additional-status-codes.md b/docs/en/docs/advanced/additional-status-codes.md index 416444d3b..0ce275343 100644 --- a/docs/en/docs/advanced/additional-status-codes.md +++ b/docs/en/docs/advanced/additional-status-codes.md @@ -26,7 +26,7 @@ To achieve that, import `JSONResponse`, and return your content there directly, {!> ../../../docs_src/additional_status_codes/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="4 26" {!> ../../../docs_src/additional_status_codes/tutorial001_an.py!} @@ -41,7 +41,7 @@ To achieve that, import `JSONResponse`, and return your content there directly, {!> ../../../docs_src/additional_status_codes/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/advanced/advanced-dependencies.md b/docs/en/docs/advanced/advanced-dependencies.md index 402c5d755..0cffab56d 100644 --- a/docs/en/docs/advanced/advanced-dependencies.md +++ b/docs/en/docs/advanced/advanced-dependencies.md @@ -24,13 +24,13 @@ To do that, we declare a method `__call__`: {!> ../../../docs_src/dependencies/tutorial011_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="11" {!> ../../../docs_src/dependencies/tutorial011_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -51,13 +51,13 @@ And now, we can use `__init__` to declare the parameters of the instance that we {!> ../../../docs_src/dependencies/tutorial011_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="8" {!> ../../../docs_src/dependencies/tutorial011_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -78,13 +78,13 @@ We could create an instance of this class with: {!> ../../../docs_src/dependencies/tutorial011_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="17" {!> ../../../docs_src/dependencies/tutorial011_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -113,13 +113,13 @@ checker(q="somequery") {!> ../../../docs_src/dependencies/tutorial011_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="21" {!> ../../../docs_src/dependencies/tutorial011_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/advanced/generate-clients.md b/docs/en/docs/advanced/generate-clients.md index f439ed93a..07a8f039f 100644 --- a/docs/en/docs/advanced/generate-clients.md +++ b/docs/en/docs/advanced/generate-clients.md @@ -35,7 +35,7 @@ Let's start with a simple FastAPI application: {!> ../../../docs_src/generate_clients/tutorial001_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9-11 14-15 18 19 23" {!> ../../../docs_src/generate_clients/tutorial001.py!} @@ -147,7 +147,7 @@ For example, you could have a section for **items** and another section for **us {!> ../../../docs_src/generate_clients/tutorial002_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="23 28 36" {!> ../../../docs_src/generate_clients/tutorial002.py!} @@ -204,7 +204,7 @@ You can then pass that custom function to **FastAPI** as the `generate_unique_id {!> ../../../docs_src/generate_clients/tutorial003_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="8-9 12" {!> ../../../docs_src/generate_clients/tutorial003.py!} diff --git a/docs/en/docs/advanced/security/http-basic-auth.md b/docs/en/docs/advanced/security/http-basic-auth.md index 8177a4b28..6f9002f60 100644 --- a/docs/en/docs/advanced/security/http-basic-auth.md +++ b/docs/en/docs/advanced/security/http-basic-auth.md @@ -26,13 +26,13 @@ Then, when you type that username and password, the browser sends them in the he {!> ../../../docs_src/security/tutorial006_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="2 7 11" {!> ../../../docs_src/security/tutorial006_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -65,13 +65,13 @@ Then we can use `secrets.compare_digest()` to ensure that `credentials.username` {!> ../../../docs_src/security/tutorial007_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 12-24" {!> ../../../docs_src/security/tutorial007_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -148,13 +148,13 @@ After detecting that the credentials are incorrect, return an `HTTPException` wi {!> ../../../docs_src/security/tutorial007_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="26-30" {!> ../../../docs_src/security/tutorial007_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/advanced/security/oauth2-scopes.md b/docs/en/docs/advanced/security/oauth2-scopes.md index 41cd61683..304a46090 100644 --- a/docs/en/docs/advanced/security/oauth2-scopes.md +++ b/docs/en/docs/advanced/security/oauth2-scopes.md @@ -68,7 +68,7 @@ First, let's quickly see the parts that change from the examples in the main **T {!> ../../../docs_src/security/tutorial005_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="2 4 8 12 47 65 106 108-116 122-125 129-135 140 156" {!> ../../../docs_src/security/tutorial005_an.py!} @@ -92,7 +92,7 @@ First, let's quickly see the parts that change from the examples in the main **T {!> ../../../docs_src/security/tutorial005_py39.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -121,7 +121,7 @@ The `scopes` parameter receives a `dict` with each scope as a key and the descri {!> ../../../docs_src/security/tutorial005_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="63-66" {!> ../../../docs_src/security/tutorial005_an.py!} @@ -146,7 +146,7 @@ The `scopes` parameter receives a `dict` with each scope as a key and the descri {!> ../../../docs_src/security/tutorial005_py39.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -188,7 +188,7 @@ And we return the scopes as part of the JWT token. {!> ../../../docs_src/security/tutorial005_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="156" {!> ../../../docs_src/security/tutorial005_an.py!} @@ -212,7 +212,7 @@ And we return the scopes as part of the JWT token. {!> ../../../docs_src/security/tutorial005_py39.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -254,7 +254,7 @@ In this case, it requires the scope `me` (it could require more than one scope). {!> ../../../docs_src/security/tutorial005_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="4 140 171" {!> ../../../docs_src/security/tutorial005_an.py!} @@ -278,7 +278,7 @@ In this case, it requires the scope `me` (it could require more than one scope). {!> ../../../docs_src/security/tutorial005_py39.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -320,7 +320,7 @@ This `SecurityScopes` class is similar to `Request` (`Request` was used to get t {!> ../../../docs_src/security/tutorial005_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="8 106" {!> ../../../docs_src/security/tutorial005_an.py!} @@ -344,7 +344,7 @@ This `SecurityScopes` class is similar to `Request` (`Request` was used to get t {!> ../../../docs_src/security/tutorial005_py39.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -377,7 +377,7 @@ In this exception, we include the scopes required (if any) as a string separated {!> ../../../docs_src/security/tutorial005_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="106 108-116" {!> ../../../docs_src/security/tutorial005_an.py!} @@ -401,7 +401,7 @@ In this exception, we include the scopes required (if any) as a string separated {!> ../../../docs_src/security/tutorial005_py39.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -436,7 +436,7 @@ We also verify that we have a user with that username, and if not, we raise that {!> ../../../docs_src/security/tutorial005_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="47 117-128" {!> ../../../docs_src/security/tutorial005_an.py!} @@ -460,7 +460,7 @@ We also verify that we have a user with that username, and if not, we raise that {!> ../../../docs_src/security/tutorial005_py39.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -487,7 +487,7 @@ For this, we use `security_scopes.scopes`, that contains a `list` with all these {!> ../../../docs_src/security/tutorial005_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="129-135" {!> ../../../docs_src/security/tutorial005_an.py!} @@ -511,7 +511,7 @@ For this, we use `security_scopes.scopes`, that contains a `list` with all these {!> ../../../docs_src/security/tutorial005_py39.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/advanced/settings.md b/docs/en/docs/advanced/settings.md index 8f6c7da93..d39130777 100644 --- a/docs/en/docs/advanced/settings.md +++ b/docs/en/docs/advanced/settings.md @@ -260,13 +260,13 @@ Now we create a dependency that returns a new `config.Settings()`. {!> ../../../docs_src/settings/app02_an_py39/main.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="6 12-13" {!> ../../../docs_src/settings/app02_an/main.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -288,13 +288,13 @@ And then we can require it from the *path operation function* as a dependency an {!> ../../../docs_src/settings/app02_an_py39/main.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="17 19-21" {!> ../../../docs_src/settings/app02_an/main.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -396,13 +396,13 @@ But as we are using the `@lru_cache()` decorator on top, the `Settings` object w {!> ../../../docs_src/settings/app03_an_py39/main.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 11" {!> ../../../docs_src/settings/app03_an/main.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/advanced/testing-dependencies.md b/docs/en/docs/advanced/testing-dependencies.md index ee48a735d..57dd87f56 100644 --- a/docs/en/docs/advanced/testing-dependencies.md +++ b/docs/en/docs/advanced/testing-dependencies.md @@ -40,7 +40,7 @@ And then **FastAPI** will call that override instead of the original dependency. {!> ../../../docs_src/dependency_testing/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="29-30 33" {!> ../../../docs_src/dependency_testing/tutorial001_an.py!} @@ -55,7 +55,7 @@ And then **FastAPI** will call that override instead of the original dependency. {!> ../../../docs_src/dependency_testing/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/advanced/websockets.md b/docs/en/docs/advanced/websockets.md index 94cf191d2..49b8fba89 100644 --- a/docs/en/docs/advanced/websockets.md +++ b/docs/en/docs/advanced/websockets.md @@ -124,7 +124,7 @@ They work the same way as for other FastAPI endpoints/*path operations*: {!> ../../../docs_src/websockets/tutorial002_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="69-70 83" {!> ../../../docs_src/websockets/tutorial002_an.py!} @@ -139,7 +139,7 @@ They work the same way as for other FastAPI endpoints/*path operations*: {!> ../../../docs_src/websockets/tutorial002_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -191,7 +191,7 @@ When a WebSocket connection is closed, the `await websocket.receive_text()` will {!> ../../../docs_src/websockets/tutorial003_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="81-83" {!> ../../../docs_src/websockets/tutorial003.py!} diff --git a/docs/en/docs/how-to/separate-openapi-schemas.md b/docs/en/docs/how-to/separate-openapi-schemas.md index d38be3c59..10be1071a 100644 --- a/docs/en/docs/how-to/separate-openapi-schemas.md +++ b/docs/en/docs/how-to/separate-openapi-schemas.md @@ -44,7 +44,7 @@ Let's say you have a Pydantic model with default values, like this one: -=== "Python 3.7+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/separate_openapi_schemas/tutorial001.py[ln:1-9]!} @@ -99,7 +99,7 @@ If you use this model as an input like here: -=== "Python 3.7+" +=== "Python 3.8+" ```Python hl_lines="16" {!> ../../../docs_src/separate_openapi_schemas/tutorial001.py[ln:1-17]!} @@ -142,7 +142,7 @@ But if you use the same model as an output, like here: {!> ../../../docs_src/separate_openapi_schemas/tutorial001_py39.py!} ``` -=== "Python 3.7+" +=== "Python 3.8+" ```Python hl_lines="21" {!> ../../../docs_src/separate_openapi_schemas/tutorial001.py!} @@ -214,7 +214,7 @@ In that case, you can disable this feature in **FastAPI**, with the parameter `s {!> ../../../docs_src/separate_openapi_schemas/tutorial002_py39.py!} ``` -=== "Python 3.7+" +=== "Python 3.8+" ```Python hl_lines="12" {!> ../../../docs_src/separate_openapi_schemas/tutorial002.py!} diff --git a/docs/en/docs/index.md b/docs/en/docs/index.md index ebd74bc8f..cd3f3e000 100644 --- a/docs/en/docs/index.md +++ b/docs/en/docs/index.md @@ -27,7 +27,7 @@ --- -FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.7+ based on standard Python type hints. +FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.8+ based on standard Python type hints. The key features are: @@ -115,7 +115,7 @@ If you are building a CLI app to be ## Requirements -Python 3.7+ +Python 3.8+ FastAPI stands on the shoulders of giants: @@ -331,7 +331,7 @@ You do that with standard modern Python types. You don't have to learn a new syntax, the methods or classes of a specific library, etc. -Just standard **Python 3.7+**. +Just standard **Python 3.8+**. For example, for an `int`: diff --git a/docs/en/docs/python-types.md b/docs/en/docs/python-types.md index 693613a36..cdd22ea4a 100644 --- a/docs/en/docs/python-types.md +++ b/docs/en/docs/python-types.md @@ -182,7 +182,7 @@ For example, let's define a variable to be a `list` of `str`. {!> ../../../docs_src/python_types/tutorial006_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" From `typing`, import `List` (with a capital `L`): @@ -230,7 +230,7 @@ You would do the same to declare `tuple`s and `set`s: {!> ../../../docs_src/python_types/tutorial007_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 4" {!> ../../../docs_src/python_types/tutorial007.py!} @@ -255,7 +255,7 @@ The second type parameter is for the values of the `dict`: {!> ../../../docs_src/python_types/tutorial008_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 4" {!> ../../../docs_src/python_types/tutorial008.py!} @@ -281,7 +281,7 @@ In Python 3.10 there's also a **new syntax** where you can put the possible type {!> ../../../docs_src/python_types/tutorial008b_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 4" {!> ../../../docs_src/python_types/tutorial008b.py!} @@ -311,13 +311,13 @@ This also means that in Python 3.10, you can use `Something | None`: {!> ../../../docs_src/python_types/tutorial009_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 4" {!> ../../../docs_src/python_types/tutorial009.py!} ``` -=== "Python 3.6+ alternative" +=== "Python 3.8+ alternative" ```Python hl_lines="1 4" {!> ../../../docs_src/python_types/tutorial009b.py!} @@ -375,10 +375,10 @@ These types that take type parameters in square brackets are called **Generic ty * `set` * `dict` - And the same as with Python 3.6, from the `typing` module: + And the same as with Python 3.8, from the `typing` module: * `Union` - * `Optional` (the same as with Python 3.6) + * `Optional` (the same as with Python 3.8) * ...and others. In Python 3.10, as an alternative to using the generics `Union` and `Optional`, you can use the vertical bar (`|`) to declare unions of types, that's a lot better and simpler. @@ -392,13 +392,13 @@ These types that take type parameters in square brackets are called **Generic ty * `set` * `dict` - And the same as with Python 3.6, from the `typing` module: + And the same as with Python 3.8, from the `typing` module: * `Union` * `Optional` * ...and others. -=== "Python 3.6+" +=== "Python 3.8+" * `List` * `Tuple` @@ -458,7 +458,7 @@ An example from the official Pydantic docs: {!> ../../../docs_src/python_types/tutorial011_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python {!> ../../../docs_src/python_types/tutorial011.py!} @@ -486,7 +486,7 @@ Python also has a feature that allows putting **additional metadata** in these t {!> ../../../docs_src/python_types/tutorial013_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" In versions below Python 3.9, you import `Annotated` from `typing_extensions`. diff --git a/docs/en/docs/tutorial/background-tasks.md b/docs/en/docs/tutorial/background-tasks.md index 178297192..bc8e2af6a 100644 --- a/docs/en/docs/tutorial/background-tasks.md +++ b/docs/en/docs/tutorial/background-tasks.md @@ -69,7 +69,7 @@ Using `BackgroundTasks` also works with the dependency injection system, you can {!> ../../../docs_src/background_tasks/tutorial002_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="14 16 23 26" {!> ../../../docs_src/background_tasks/tutorial002_an.py!} @@ -84,7 +84,7 @@ Using `BackgroundTasks` also works with the dependency injection system, you can {!> ../../../docs_src/background_tasks/tutorial002_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/tutorial/bigger-applications.md b/docs/en/docs/tutorial/bigger-applications.md index 26d26475f..1cf7e50e0 100644 --- a/docs/en/docs/tutorial/bigger-applications.md +++ b/docs/en/docs/tutorial/bigger-applications.md @@ -118,13 +118,13 @@ We will now use a simple dependency to read a custom `X-Token` header: {!> ../../../docs_src/bigger_applications/app_an_py39/dependencies.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 5-7" {!> ../../../docs_src/bigger_applications/app_an/dependencies.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/tutorial/body-fields.md b/docs/en/docs/tutorial/body-fields.md index 8966032ff..55e67fdd6 100644 --- a/docs/en/docs/tutorial/body-fields.md +++ b/docs/en/docs/tutorial/body-fields.md @@ -18,7 +18,7 @@ First, you have to import it: {!> ../../../docs_src/body_fields/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="4" {!> ../../../docs_src/body_fields/tutorial001_an.py!} @@ -33,7 +33,7 @@ First, you have to import it: {!> ../../../docs_src/body_fields/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -61,7 +61,7 @@ You can then use `Field` with model attributes: {!> ../../../docs_src/body_fields/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="12-15" {!> ../../../docs_src/body_fields/tutorial001_an.py!} @@ -76,7 +76,7 @@ You can then use `Field` with model attributes: {!> ../../../docs_src/body_fields/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/tutorial/body-multiple-params.md b/docs/en/docs/tutorial/body-multiple-params.md index b214092c9..ebef8eeaa 100644 --- a/docs/en/docs/tutorial/body-multiple-params.md +++ b/docs/en/docs/tutorial/body-multiple-params.md @@ -20,7 +20,7 @@ And you can also declare body parameters as optional, by setting the default to {!> ../../../docs_src/body_multiple_params/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="19-21" {!> ../../../docs_src/body_multiple_params/tutorial001_an.py!} @@ -35,7 +35,7 @@ And you can also declare body parameters as optional, by setting the default to {!> ../../../docs_src/body_multiple_params/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -68,7 +68,7 @@ But you can also declare multiple body parameters, e.g. `item` and `user`: {!> ../../../docs_src/body_multiple_params/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="22" {!> ../../../docs_src/body_multiple_params/tutorial002.py!} @@ -123,7 +123,7 @@ But you can instruct **FastAPI** to treat it as another body key using `Body`: {!> ../../../docs_src/body_multiple_params/tutorial003_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="24" {!> ../../../docs_src/body_multiple_params/tutorial003_an.py!} @@ -138,7 +138,7 @@ But you can instruct **FastAPI** to treat it as another body key using `Body`: {!> ../../../docs_src/body_multiple_params/tutorial003_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -197,7 +197,7 @@ For example: {!> ../../../docs_src/body_multiple_params/tutorial004_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="28" {!> ../../../docs_src/body_multiple_params/tutorial004_an.py!} @@ -212,7 +212,7 @@ For example: {!> ../../../docs_src/body_multiple_params/tutorial004_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -250,7 +250,7 @@ as in: {!> ../../../docs_src/body_multiple_params/tutorial005_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="18" {!> ../../../docs_src/body_multiple_params/tutorial005_an.py!} @@ -265,7 +265,7 @@ as in: {!> ../../../docs_src/body_multiple_params/tutorial005_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/tutorial/body-nested-models.md b/docs/en/docs/tutorial/body-nested-models.md index ffa0c0d0e..3a1052397 100644 --- a/docs/en/docs/tutorial/body-nested-models.md +++ b/docs/en/docs/tutorial/body-nested-models.md @@ -12,7 +12,7 @@ You can define an attribute to be a subtype. For example, a Python `list`: {!> ../../../docs_src/body_nested_models/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="14" {!> ../../../docs_src/body_nested_models/tutorial001.py!} @@ -73,7 +73,7 @@ So, in our example, we can make `tags` be specifically a "list of strings": {!> ../../../docs_src/body_nested_models/tutorial002_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="14" {!> ../../../docs_src/body_nested_models/tutorial002.py!} @@ -99,7 +99,7 @@ Then we can declare `tags` as a set of strings: {!> ../../../docs_src/body_nested_models/tutorial003_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 14" {!> ../../../docs_src/body_nested_models/tutorial003.py!} @@ -137,7 +137,7 @@ For example, we can define an `Image` model: {!> ../../../docs_src/body_nested_models/tutorial004_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9-11" {!> ../../../docs_src/body_nested_models/tutorial004.py!} @@ -159,7 +159,7 @@ And then we can use it as the type of an attribute: {!> ../../../docs_src/body_nested_models/tutorial004_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="20" {!> ../../../docs_src/body_nested_models/tutorial004.py!} @@ -208,7 +208,7 @@ For example, as in the `Image` model we have a `url` field, we can declare it to {!> ../../../docs_src/body_nested_models/tutorial005_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="4 10" {!> ../../../docs_src/body_nested_models/tutorial005.py!} @@ -232,7 +232,7 @@ You can also use Pydantic models as subtypes of `list`, `set`, etc: {!> ../../../docs_src/body_nested_models/tutorial006_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="20" {!> ../../../docs_src/body_nested_models/tutorial006.py!} @@ -283,7 +283,7 @@ You can define arbitrarily deeply nested models: {!> ../../../docs_src/body_nested_models/tutorial007_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9 14 20 23 27" {!> ../../../docs_src/body_nested_models/tutorial007.py!} @@ -314,7 +314,7 @@ as in: {!> ../../../docs_src/body_nested_models/tutorial008_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="15" {!> ../../../docs_src/body_nested_models/tutorial008.py!} @@ -354,7 +354,7 @@ In this case, you would accept any `dict` as long as it has `int` keys with `flo {!> ../../../docs_src/body_nested_models/tutorial009_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/body_nested_models/tutorial009.py!} diff --git a/docs/en/docs/tutorial/body-updates.md b/docs/en/docs/tutorial/body-updates.md index a32948db1..3341f2d5d 100644 --- a/docs/en/docs/tutorial/body-updates.md +++ b/docs/en/docs/tutorial/body-updates.md @@ -18,7 +18,7 @@ You can use the `jsonable_encoder` to convert the input data to data that can be {!> ../../../docs_src/body_updates/tutorial001_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="30-35" {!> ../../../docs_src/body_updates/tutorial001.py!} @@ -79,7 +79,7 @@ Then you can use this to generate a `dict` with only the data that was set (sent {!> ../../../docs_src/body_updates/tutorial002_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="34" {!> ../../../docs_src/body_updates/tutorial002.py!} @@ -103,7 +103,7 @@ Like `stored_item_model.copy(update=update_data)`: {!> ../../../docs_src/body_updates/tutorial002_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="35" {!> ../../../docs_src/body_updates/tutorial002.py!} @@ -136,7 +136,7 @@ In summary, to apply partial updates you would: {!> ../../../docs_src/body_updates/tutorial002_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="30-37" {!> ../../../docs_src/body_updates/tutorial002.py!} diff --git a/docs/en/docs/tutorial/body.md b/docs/en/docs/tutorial/body.md index 172b91fdf..67ba48f1e 100644 --- a/docs/en/docs/tutorial/body.md +++ b/docs/en/docs/tutorial/body.md @@ -25,7 +25,7 @@ First, you need to import `BaseModel` from `pydantic`: {!> ../../../docs_src/body/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="4" {!> ../../../docs_src/body/tutorial001.py!} @@ -43,7 +43,7 @@ Use standard Python types for all the attributes: {!> ../../../docs_src/body/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="7-11" {!> ../../../docs_src/body/tutorial001.py!} @@ -81,7 +81,7 @@ To add it to your *path operation*, declare it the same way you declared path an {!> ../../../docs_src/body/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="18" {!> ../../../docs_src/body/tutorial001.py!} @@ -155,7 +155,7 @@ Inside of the function, you can access all the attributes of the model object di {!> ../../../docs_src/body/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="21" {!> ../../../docs_src/body/tutorial002.py!} @@ -173,7 +173,7 @@ You can declare path parameters and request body at the same time. {!> ../../../docs_src/body/tutorial003_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="17-18" {!> ../../../docs_src/body/tutorial003.py!} @@ -191,7 +191,7 @@ You can also declare **body**, **path** and **query** parameters, all at the sam {!> ../../../docs_src/body/tutorial004_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="18" {!> ../../../docs_src/body/tutorial004.py!} diff --git a/docs/en/docs/tutorial/cookie-params.md b/docs/en/docs/tutorial/cookie-params.md index 111e93458..3436a7df3 100644 --- a/docs/en/docs/tutorial/cookie-params.md +++ b/docs/en/docs/tutorial/cookie-params.md @@ -18,7 +18,7 @@ First import `Cookie`: {!> ../../../docs_src/cookie_params/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="3" {!> ../../../docs_src/cookie_params/tutorial001_an.py!} @@ -33,7 +33,7 @@ First import `Cookie`: {!> ../../../docs_src/cookie_params/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -60,7 +60,7 @@ The first value is the default value, you can pass all the extra validation or a {!> ../../../docs_src/cookie_params/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/cookie_params/tutorial001_an.py!} @@ -75,7 +75,7 @@ The first value is the default value, you can pass all the extra validation or a {!> ../../../docs_src/cookie_params/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/tutorial/dependencies/classes-as-dependencies.md b/docs/en/docs/tutorial/dependencies/classes-as-dependencies.md index 498d935fe..842f2adf6 100644 --- a/docs/en/docs/tutorial/dependencies/classes-as-dependencies.md +++ b/docs/en/docs/tutorial/dependencies/classes-as-dependencies.md @@ -18,7 +18,7 @@ In the previous example, we were returning a `dict` from our dependency ("depend {!> ../../../docs_src/dependencies/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="12" {!> ../../../docs_src/dependencies/tutorial001_an.py!} @@ -33,7 +33,7 @@ In the previous example, we were returning a `dict` from our dependency ("depend {!> ../../../docs_src/dependencies/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -115,7 +115,7 @@ Then, we can change the dependency "dependable" `common_parameters` from above t {!> ../../../docs_src/dependencies/tutorial002_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="12-16" {!> ../../../docs_src/dependencies/tutorial002_an.py!} @@ -130,7 +130,7 @@ Then, we can change the dependency "dependable" `common_parameters` from above t {!> ../../../docs_src/dependencies/tutorial002_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -153,7 +153,7 @@ Pay attention to the `__init__` method used to create the instance of the class: {!> ../../../docs_src/dependencies/tutorial002_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="13" {!> ../../../docs_src/dependencies/tutorial002_an.py!} @@ -168,7 +168,7 @@ Pay attention to the `__init__` method used to create the instance of the class: {!> ../../../docs_src/dependencies/tutorial002_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -191,7 +191,7 @@ Pay attention to the `__init__` method used to create the instance of the class: {!> ../../../docs_src/dependencies/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/dependencies/tutorial001_an.py!} @@ -206,7 +206,7 @@ Pay attention to the `__init__` method used to create the instance of the class: {!> ../../../docs_src/dependencies/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -241,7 +241,7 @@ Now you can declare your dependency using this class. {!> ../../../docs_src/dependencies/tutorial002_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="20" {!> ../../../docs_src/dependencies/tutorial002_an.py!} @@ -256,7 +256,7 @@ Now you can declare your dependency using this class. {!> ../../../docs_src/dependencies/tutorial002_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -271,7 +271,7 @@ Now you can declare your dependency using this class. Notice how we write `CommonQueryParams` twice in the above code: -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -280,7 +280,7 @@ Notice how we write `CommonQueryParams` twice in the above code: commons: CommonQueryParams = Depends(CommonQueryParams) ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] @@ -300,13 +300,13 @@ From it is that FastAPI will extract the declared parameters and that is what Fa In this case, the first `CommonQueryParams`, in: -=== "Python 3.6+" +=== "Python 3.8+" ```Python commons: Annotated[CommonQueryParams, ... ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -319,13 +319,13 @@ In this case, the first `CommonQueryParams`, in: You could actually write just: -=== "Python 3.6+" +=== "Python 3.8+" ```Python commons: Annotated[Any, Depends(CommonQueryParams)] ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -348,7 +348,7 @@ You could actually write just: {!> ../../../docs_src/dependencies/tutorial003_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="20" {!> ../../../docs_src/dependencies/tutorial003_an.py!} @@ -363,7 +363,7 @@ You could actually write just: {!> ../../../docs_src/dependencies/tutorial003_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -380,7 +380,7 @@ But declaring the type is encouraged as that way your editor will know what will But you see that we are having some code repetition here, writing `CommonQueryParams` twice: -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -389,7 +389,7 @@ But you see that we are having some code repetition here, writing `CommonQueryPa commons: CommonQueryParams = Depends(CommonQueryParams) ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] @@ -401,13 +401,13 @@ For those specific cases, you can do the following: Instead of writing: -=== "Python 3.6+" +=== "Python 3.8+" ```Python commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -418,13 +418,13 @@ Instead of writing: ...you write: -=== "Python 3.6+" +=== "Python 3.8+" ```Python commons: Annotated[CommonQueryParams, Depends()] ``` -=== "Python 3.6 non-Annotated" +=== "Python 3.8 non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -449,7 +449,7 @@ The same example would then look like: {!> ../../../docs_src/dependencies/tutorial004_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="20" {!> ../../../docs_src/dependencies/tutorial004_an.py!} @@ -464,7 +464,7 @@ The same example would then look like: {!> ../../../docs_src/dependencies/tutorial004_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md b/docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md index ccef5aef4..eaab51d1b 100644 --- a/docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md +++ b/docs/en/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md @@ -20,13 +20,13 @@ It should be a `list` of `Depends()`: {!> ../../../docs_src/dependencies/tutorial006_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="18" {!> ../../../docs_src/dependencies/tutorial006_an.py!} ``` -=== "Python 3.6 non-Annotated" +=== "Python 3.8 non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -63,13 +63,13 @@ They can declare request requirements (like headers) or other sub-dependencies: {!> ../../../docs_src/dependencies/tutorial006_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="7 12" {!> ../../../docs_src/dependencies/tutorial006_an.py!} ``` -=== "Python 3.6 non-Annotated" +=== "Python 3.8 non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -88,13 +88,13 @@ These dependencies can `raise` exceptions, the same as normal dependencies: {!> ../../../docs_src/dependencies/tutorial006_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9 14" {!> ../../../docs_src/dependencies/tutorial006_an.py!} ``` -=== "Python 3.6 non-Annotated" +=== "Python 3.8 non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -115,13 +115,13 @@ So, you can re-use a normal dependency (that returns a value) you already use so {!> ../../../docs_src/dependencies/tutorial006_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10 15" {!> ../../../docs_src/dependencies/tutorial006_an.py!} ``` -=== "Python 3.6 non-Annotated" +=== "Python 3.8 non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md index 8a5422ac8..fe18f1f1d 100644 --- a/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md +++ b/docs/en/docs/tutorial/dependencies/dependencies-with-yield.md @@ -72,13 +72,13 @@ For example, `dependency_c` can have a dependency on `dependency_b`, and `depend {!> ../../../docs_src/dependencies/tutorial008_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="5 13 21" {!> ../../../docs_src/dependencies/tutorial008_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -99,13 +99,13 @@ And, in turn, `dependency_b` needs the value from `dependency_a` (here named `de {!> ../../../docs_src/dependencies/tutorial008_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="17-18 25-26" {!> ../../../docs_src/dependencies/tutorial008_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/tutorial/dependencies/global-dependencies.md b/docs/en/docs/tutorial/dependencies/global-dependencies.md index 0989b31d4..0dcf73176 100644 --- a/docs/en/docs/tutorial/dependencies/global-dependencies.md +++ b/docs/en/docs/tutorial/dependencies/global-dependencies.md @@ -12,13 +12,13 @@ In that case, they will be applied to all the *path operations* in the applicati {!> ../../../docs_src/dependencies/tutorial012_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="16" {!> ../../../docs_src/dependencies/tutorial012_an.py!} ``` -=== "Python 3.6 non-Annotated" +=== "Python 3.8 non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/tutorial/dependencies/index.md b/docs/en/docs/tutorial/dependencies/index.md index f6f4bced0..bc98cb26e 100644 --- a/docs/en/docs/tutorial/dependencies/index.md +++ b/docs/en/docs/tutorial/dependencies/index.md @@ -43,7 +43,7 @@ It is just a function that can take all the same parameters that a *path operati {!> ../../../docs_src/dependencies/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9-12" {!> ../../../docs_src/dependencies/tutorial001_an.py!} @@ -58,7 +58,7 @@ It is just a function that can take all the same parameters that a *path operati {!> ../../../docs_src/dependencies/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -106,7 +106,7 @@ And then it just returns a `dict` containing those values. {!> ../../../docs_src/dependencies/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="3" {!> ../../../docs_src/dependencies/tutorial001_an.py!} @@ -121,7 +121,7 @@ And then it just returns a `dict` containing those values. {!> ../../../docs_src/dependencies/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -146,7 +146,7 @@ The same way you use `Body`, `Query`, etc. with your *path operation function* p {!> ../../../docs_src/dependencies/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="16 21" {!> ../../../docs_src/dependencies/tutorial001_an.py!} @@ -161,7 +161,7 @@ The same way you use `Body`, `Query`, etc. with your *path operation function* p {!> ../../../docs_src/dependencies/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -231,7 +231,7 @@ But because we are using `Annotated`, we can store that `Annotated` value in a v {!> ../../../docs_src/dependencies/tutorial001_02_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="15 19 24" {!> ../../../docs_src/dependencies/tutorial001_02_an.py!} diff --git a/docs/en/docs/tutorial/dependencies/sub-dependencies.md b/docs/en/docs/tutorial/dependencies/sub-dependencies.md index b50de1a46..1cb469a80 100644 --- a/docs/en/docs/tutorial/dependencies/sub-dependencies.md +++ b/docs/en/docs/tutorial/dependencies/sub-dependencies.md @@ -22,7 +22,7 @@ You could create a first dependency ("dependable") like: {!> ../../../docs_src/dependencies/tutorial005_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9-10" {!> ../../../docs_src/dependencies/tutorial005_an.py!} @@ -37,7 +37,7 @@ You could create a first dependency ("dependable") like: {!> ../../../docs_src/dependencies/tutorial005_py310.py!} ``` -=== "Python 3.6 non-Annotated" +=== "Python 3.8 non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -66,7 +66,7 @@ Then you can create another dependency function (a "dependable") that at the sam {!> ../../../docs_src/dependencies/tutorial005_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="14" {!> ../../../docs_src/dependencies/tutorial005_an.py!} @@ -81,7 +81,7 @@ Then you can create another dependency function (a "dependable") that at the sam {!> ../../../docs_src/dependencies/tutorial005_py310.py!} ``` -=== "Python 3.6 non-Annotated" +=== "Python 3.8 non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -113,7 +113,7 @@ Then we can use the dependency with: {!> ../../../docs_src/dependencies/tutorial005_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="24" {!> ../../../docs_src/dependencies/tutorial005_an.py!} @@ -128,7 +128,7 @@ Then we can use the dependency with: {!> ../../../docs_src/dependencies/tutorial005_py310.py!} ``` -=== "Python 3.6 non-Annotated" +=== "Python 3.8 non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -161,14 +161,14 @@ And it will save the returned value in a ../../../docs_src/encoder/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="5 22" {!> ../../../docs_src/encoder/tutorial001.py!} diff --git a/docs/en/docs/tutorial/extra-data-types.md b/docs/en/docs/tutorial/extra-data-types.md index b34ccd26f..fd7a99af3 100644 --- a/docs/en/docs/tutorial/extra-data-types.md +++ b/docs/en/docs/tutorial/extra-data-types.md @@ -67,7 +67,7 @@ Here's an example *path operation* with parameters using some of the above types {!> ../../../docs_src/extra_data_types/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 3 13-17" {!> ../../../docs_src/extra_data_types/tutorial001_an.py!} @@ -82,7 +82,7 @@ Here's an example *path operation* with parameters using some of the above types {!> ../../../docs_src/extra_data_types/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -105,7 +105,7 @@ Note that the parameters inside the function have their natural data type, and y {!> ../../../docs_src/extra_data_types/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="19-20" {!> ../../../docs_src/extra_data_types/tutorial001_an.py!} @@ -120,7 +120,7 @@ Note that the parameters inside the function have their natural data type, and y {!> ../../../docs_src/extra_data_types/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/tutorial/extra-models.md b/docs/en/docs/tutorial/extra-models.md index e91e879e4..590d095bd 100644 --- a/docs/en/docs/tutorial/extra-models.md +++ b/docs/en/docs/tutorial/extra-models.md @@ -23,7 +23,7 @@ Here's a general idea of how the models could look like with their password fiel {!> ../../../docs_src/extra_models/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9 11 16 22 24 29-30 33-35 40-41" {!> ../../../docs_src/extra_models/tutorial001.py!} @@ -164,7 +164,7 @@ That way, we can declare just the differences between the models (with plaintext {!> ../../../docs_src/extra_models/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9 15-16 19-20 23-24" {!> ../../../docs_src/extra_models/tutorial002.py!} @@ -187,7 +187,7 @@ To do that, use the standard Python type hint ../../../docs_src/extra_models/tutorial003.py!} @@ -219,7 +219,7 @@ For that, use the standard Python `typing.List` (or just `list` in Python 3.9 an {!> ../../../docs_src/extra_models/tutorial004_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 20" {!> ../../../docs_src/extra_models/tutorial004.py!} @@ -239,7 +239,7 @@ In this case, you can use `typing.Dict` (or just `dict` in Python 3.9 and above) {!> ../../../docs_src/extra_models/tutorial005_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 8" {!> ../../../docs_src/extra_models/tutorial005.py!} diff --git a/docs/en/docs/tutorial/header-params.md b/docs/en/docs/tutorial/header-params.md index 9e928cdc6..bbba90998 100644 --- a/docs/en/docs/tutorial/header-params.md +++ b/docs/en/docs/tutorial/header-params.md @@ -18,7 +18,7 @@ First import `Header`: {!> ../../../docs_src/header_params/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="3" {!> ../../../docs_src/header_params/tutorial001_an.py!} @@ -33,7 +33,7 @@ First import `Header`: {!> ../../../docs_src/header_params/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -60,7 +60,7 @@ The first value is the default value, you can pass all the extra validation or a {!> ../../../docs_src/header_params/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/header_params/tutorial001_an.py!} @@ -75,7 +75,7 @@ The first value is the default value, you can pass all the extra validation or a {!> ../../../docs_src/header_params/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -120,7 +120,7 @@ If for some reason you need to disable automatic conversion of underscores to hy {!> ../../../docs_src/header_params/tutorial002_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="12" {!> ../../../docs_src/header_params/tutorial002_an.py!} @@ -135,7 +135,7 @@ If for some reason you need to disable automatic conversion of underscores to hy {!> ../../../docs_src/header_params/tutorial002_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -169,7 +169,7 @@ For example, to declare a header of `X-Token` that can appear more than once, yo {!> ../../../docs_src/header_params/tutorial003_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/header_params/tutorial003_an.py!} @@ -193,7 +193,7 @@ For example, to declare a header of `X-Token` that can appear more than once, yo {!> ../../../docs_src/header_params/tutorial003_py39.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/tutorial/path-operation-configuration.md b/docs/en/docs/tutorial/path-operation-configuration.md index 7d4d4bcca..babf85acb 100644 --- a/docs/en/docs/tutorial/path-operation-configuration.md +++ b/docs/en/docs/tutorial/path-operation-configuration.md @@ -25,7 +25,7 @@ But if you don't remember what each number code is for, you can use the shortcut {!> ../../../docs_src/path_operation_configuration/tutorial001_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="3 17" {!> ../../../docs_src/path_operation_configuration/tutorial001.py!} @@ -54,7 +54,7 @@ You can add tags to your *path operation*, pass the parameter `tags` with a `lis {!> ../../../docs_src/path_operation_configuration/tutorial002_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="17 22 27" {!> ../../../docs_src/path_operation_configuration/tutorial002.py!} @@ -92,7 +92,7 @@ You can add a `summary` and `description`: {!> ../../../docs_src/path_operation_configuration/tutorial003_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="20-21" {!> ../../../docs_src/path_operation_configuration/tutorial003.py!} @@ -116,7 +116,7 @@ You can write ../../../docs_src/path_operation_configuration/tutorial004.py!} @@ -142,7 +142,7 @@ You can specify the response description with the parameter `response_descriptio {!> ../../../docs_src/path_operation_configuration/tutorial005_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="21" {!> ../../../docs_src/path_operation_configuration/tutorial005.py!} diff --git a/docs/en/docs/tutorial/path-params-numeric-validations.md b/docs/en/docs/tutorial/path-params-numeric-validations.md index 9255875d6..57ad20b13 100644 --- a/docs/en/docs/tutorial/path-params-numeric-validations.md +++ b/docs/en/docs/tutorial/path-params-numeric-validations.md @@ -18,7 +18,7 @@ First, import `Path` from `fastapi`, and import `Annotated`: {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="3-4" {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an.py!} @@ -33,7 +33,7 @@ First, import `Path` from `fastapi`, and import `Annotated`: {!> ../../../docs_src/path_params_numeric_validations/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -67,7 +67,7 @@ For example, to declare a `title` metadata value for the path parameter `item_id {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="11" {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an.py!} @@ -82,7 +82,7 @@ For example, to declare a `title` metadata value for the path parameter `item_id {!> ../../../docs_src/path_params_numeric_validations/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -117,7 +117,7 @@ It doesn't matter for **FastAPI**. It will detect the parameters by their names, So, you can declare your function as: -=== "Python 3.6 non-Annotated" +=== "Python 3.8 non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -134,7 +134,7 @@ But have in mind that if you use `Annotated`, you won't have this problem, it wo {!> ../../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/path_params_numeric_validations/tutorial002_an.py!} @@ -174,7 +174,7 @@ Have in mind that if you use `Annotated`, as you are not using function paramete {!> ../../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/path_params_numeric_validations/tutorial003_an.py!} @@ -192,13 +192,13 @@ Here, with `ge=1`, `item_id` will need to be an integer number "`g`reater than o {!> ../../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/path_params_numeric_validations/tutorial004_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -220,13 +220,13 @@ The same applies for: {!> ../../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/path_params_numeric_validations/tutorial005_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -251,13 +251,13 @@ And the same for lt. {!> ../../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="12" {!> ../../../docs_src/path_params_numeric_validations/tutorial006_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/tutorial/query-params-str-validations.md b/docs/en/docs/tutorial/query-params-str-validations.md index 5d1c08add..0b2cf02a8 100644 --- a/docs/en/docs/tutorial/query-params-str-validations.md +++ b/docs/en/docs/tutorial/query-params-str-validations.md @@ -10,7 +10,7 @@ Let's take this application as example: {!> ../../../docs_src/query_params_str_validations/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/query_params_str_validations/tutorial001.py!} @@ -42,7 +42,7 @@ To achieve that, first import: {!> ../../../docs_src/query_params_str_validations/tutorial002_an_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" In versions of Python below Python 3.9 you import `Annotated` from `typing_extensions`. @@ -73,7 +73,7 @@ We had this type annotation: q: str | None = None ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python q: Union[str, None] = None @@ -87,7 +87,7 @@ What we will do is wrap that with `Annotated`, so it becomes: q: Annotated[str | None] = None ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python q: Annotated[Union[str, None]] = None @@ -107,7 +107,7 @@ Now that we have this `Annotated` where we can put more metadata, add `Query` to {!> ../../../docs_src/query_params_str_validations/tutorial002_an_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/query_params_str_validations/tutorial002_an.py!} @@ -138,7 +138,7 @@ This is how you would use `Query()` as the default value of your function parame {!> ../../../docs_src/query_params_str_validations/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/query_params_str_validations/tutorial002.py!} @@ -251,7 +251,7 @@ You can also add a parameter `min_length`: {!> ../../../docs_src/query_params_str_validations/tutorial003_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="11" {!> ../../../docs_src/query_params_str_validations/tutorial003_an.py!} @@ -266,7 +266,7 @@ You can also add a parameter `min_length`: {!> ../../../docs_src/query_params_str_validations/tutorial003_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -291,7 +291,7 @@ You can define a ../../../docs_src/query_params_str_validations/tutorial004_an.py!} @@ -306,7 +306,7 @@ You can define a ../../../docs_src/query_params_str_validations/tutorial005_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="8" {!> ../../../docs_src/query_params_str_validations/tutorial005_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -405,13 +405,13 @@ So, when you need to declare a value as required while using `Query`, you can si {!> ../../../docs_src/query_params_str_validations/tutorial006_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="8" {!> ../../../docs_src/query_params_str_validations/tutorial006_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -435,13 +435,13 @@ There's an alternative way to explicitly declare that a value is required. You c {!> ../../../docs_src/query_params_str_validations/tutorial006b_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="8" {!> ../../../docs_src/query_params_str_validations/tutorial006b_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -475,7 +475,7 @@ To do that, you can declare that `None` is a valid type but still use `...` as t {!> ../../../docs_src/query_params_str_validations/tutorial006c_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/query_params_str_validations/tutorial006c_an.py!} @@ -490,7 +490,7 @@ To do that, you can declare that `None` is a valid type but still use `...` as t {!> ../../../docs_src/query_params_str_validations/tutorial006c_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -512,13 +512,13 @@ If you feel uncomfortable using `...`, you can also import and use `Required` fr {!> ../../../docs_src/query_params_str_validations/tutorial006d_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="2 9" {!> ../../../docs_src/query_params_str_validations/tutorial006d_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -548,7 +548,7 @@ For example, to declare a query parameter `q` that can appear multiple times in {!> ../../../docs_src/query_params_str_validations/tutorial011_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/query_params_str_validations/tutorial011_an.py!} @@ -572,7 +572,7 @@ For example, to declare a query parameter `q` that can appear multiple times in {!> ../../../docs_src/query_params_str_validations/tutorial011_py39.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -617,7 +617,7 @@ And you can also define a default `list` of values if none are provided: {!> ../../../docs_src/query_params_str_validations/tutorial012_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/query_params_str_validations/tutorial012_an.py!} @@ -632,7 +632,7 @@ And you can also define a default `list` of values if none are provided: {!> ../../../docs_src/query_params_str_validations/tutorial012_py39.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -668,13 +668,13 @@ You can also use `list` directly instead of `List[str]` (or `list[str]` in Pytho {!> ../../../docs_src/query_params_str_validations/tutorial013_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="8" {!> ../../../docs_src/query_params_str_validations/tutorial013_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -713,7 +713,7 @@ You can add a `title`: {!> ../../../docs_src/query_params_str_validations/tutorial007_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="11" {!> ../../../docs_src/query_params_str_validations/tutorial007_an.py!} @@ -728,7 +728,7 @@ You can add a `title`: {!> ../../../docs_src/query_params_str_validations/tutorial007_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -751,7 +751,7 @@ And a `description`: {!> ../../../docs_src/query_params_str_validations/tutorial008_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="15" {!> ../../../docs_src/query_params_str_validations/tutorial008_an.py!} @@ -766,7 +766,7 @@ And a `description`: {!> ../../../docs_src/query_params_str_validations/tutorial008_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -805,7 +805,7 @@ Then you can declare an `alias`, and that alias is what will be used to find the {!> ../../../docs_src/query_params_str_validations/tutorial009_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/query_params_str_validations/tutorial009_an.py!} @@ -820,7 +820,7 @@ Then you can declare an `alias`, and that alias is what will be used to find the {!> ../../../docs_src/query_params_str_validations/tutorial009_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -849,7 +849,7 @@ Then pass the parameter `deprecated=True` to `Query`: {!> ../../../docs_src/query_params_str_validations/tutorial010_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="20" {!> ../../../docs_src/query_params_str_validations/tutorial010_an.py!} @@ -864,7 +864,7 @@ Then pass the parameter `deprecated=True` to `Query`: {!> ../../../docs_src/query_params_str_validations/tutorial010_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -893,7 +893,7 @@ To exclude a query parameter from the generated OpenAPI schema (and thus, from t {!> ../../../docs_src/query_params_str_validations/tutorial014_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="11" {!> ../../../docs_src/query_params_str_validations/tutorial014_an.py!} @@ -908,7 +908,7 @@ To exclude a query parameter from the generated OpenAPI schema (and thus, from t {!> ../../../docs_src/query_params_str_validations/tutorial014_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/tutorial/query-params.md b/docs/en/docs/tutorial/query-params.md index 0b74b10f8..988ff4bf1 100644 --- a/docs/en/docs/tutorial/query-params.md +++ b/docs/en/docs/tutorial/query-params.md @@ -69,7 +69,7 @@ The same way, you can declare optional query parameters, by setting their defaul {!> ../../../docs_src/query_params/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/query_params/tutorial002.py!} @@ -90,7 +90,7 @@ You can also declare `bool` types, and they will be converted: {!> ../../../docs_src/query_params/tutorial003_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/query_params/tutorial003.py!} @@ -143,7 +143,7 @@ They will be detected by name: {!> ../../../docs_src/query_params/tutorial004_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="8 10" {!> ../../../docs_src/query_params/tutorial004.py!} @@ -209,7 +209,7 @@ And of course, you can define some parameters as required, some as having a defa {!> ../../../docs_src/query_params/tutorial006_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/query_params/tutorial006.py!} diff --git a/docs/en/docs/tutorial/request-files.md b/docs/en/docs/tutorial/request-files.md index 1fe1e7a33..c85a68ed6 100644 --- a/docs/en/docs/tutorial/request-files.md +++ b/docs/en/docs/tutorial/request-files.md @@ -19,13 +19,13 @@ Import `File` and `UploadFile` from `fastapi`: {!> ../../../docs_src/request_files/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1" {!> ../../../docs_src/request_files/tutorial001_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -44,13 +44,13 @@ Create file parameters the same way you would for `Body` or `Form`: {!> ../../../docs_src/request_files/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="8" {!> ../../../docs_src/request_files/tutorial001_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -85,13 +85,13 @@ Define a file parameter with a type of `UploadFile`: {!> ../../../docs_src/request_files/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="13" {!> ../../../docs_src/request_files/tutorial001_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -181,7 +181,7 @@ You can make a file optional by using standard type annotations and setting a de {!> ../../../docs_src/request_files/tutorial001_02_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10 18" {!> ../../../docs_src/request_files/tutorial001_02_an.py!} @@ -196,7 +196,7 @@ You can make a file optional by using standard type annotations and setting a de {!> ../../../docs_src/request_files/tutorial001_02_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -215,13 +215,13 @@ You can also use `File()` with `UploadFile`, for example, to set additional meta {!> ../../../docs_src/request_files/tutorial001_03_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="8 14" {!> ../../../docs_src/request_files/tutorial001_03_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -244,7 +244,7 @@ To use that, declare a list of `bytes` or `UploadFile`: {!> ../../../docs_src/request_files/tutorial002_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="11 16" {!> ../../../docs_src/request_files/tutorial002_an.py!} @@ -259,7 +259,7 @@ To use that, declare a list of `bytes` or `UploadFile`: {!> ../../../docs_src/request_files/tutorial002_py39.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -285,7 +285,7 @@ And the same way as before, you can use `File()` to set additional parameters, e {!> ../../../docs_src/request_files/tutorial003_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="12 19-21" {!> ../../../docs_src/request_files/tutorial003_an.py!} @@ -300,7 +300,7 @@ And the same way as before, you can use `File()` to set additional parameters, e {!> ../../../docs_src/request_files/tutorial003_py39.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/tutorial/request-forms-and-files.md b/docs/en/docs/tutorial/request-forms-and-files.md index 1818946c4..a58291dc8 100644 --- a/docs/en/docs/tutorial/request-forms-and-files.md +++ b/docs/en/docs/tutorial/request-forms-and-files.md @@ -15,13 +15,13 @@ You can define files and form fields at the same time using `File` and `Form`. {!> ../../../docs_src/request_forms_and_files/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1" {!> ../../../docs_src/request_forms_and_files/tutorial001_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -40,13 +40,13 @@ Create file and form parameters the same way you would for `Body` or `Query`: {!> ../../../docs_src/request_forms_and_files/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9-11" {!> ../../../docs_src/request_forms_and_files/tutorial001_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/tutorial/request-forms.md b/docs/en/docs/tutorial/request-forms.md index 5d441a614..0e8ac5f4f 100644 --- a/docs/en/docs/tutorial/request-forms.md +++ b/docs/en/docs/tutorial/request-forms.md @@ -17,13 +17,13 @@ Import `Form` from `fastapi`: {!> ../../../docs_src/request_forms/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1" {!> ../../../docs_src/request_forms/tutorial001_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -42,13 +42,13 @@ Create form parameters the same way you would for `Body` or `Query`: {!> ../../../docs_src/request_forms/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="8" {!> ../../../docs_src/request_forms/tutorial001_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/tutorial/response-model.md b/docs/en/docs/tutorial/response-model.md index 2181cfb5a..d6d3d61cb 100644 --- a/docs/en/docs/tutorial/response-model.md +++ b/docs/en/docs/tutorial/response-model.md @@ -16,7 +16,7 @@ You can use **type annotations** the same way you would for input data in functi {!> ../../../docs_src/response_model/tutorial001_01_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="18 23" {!> ../../../docs_src/response_model/tutorial001_01.py!} @@ -65,7 +65,7 @@ You can use the `response_model` parameter in any of the *path operations*: {!> ../../../docs_src/response_model/tutorial001_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="17 22 24-27" {!> ../../../docs_src/response_model/tutorial001.py!} @@ -101,7 +101,7 @@ Here we are declaring a `UserIn` model, it will contain a plaintext password: {!> ../../../docs_src/response_model/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9 11" {!> ../../../docs_src/response_model/tutorial002.py!} @@ -121,7 +121,7 @@ And we are using this model to declare our input and the same model to declare o {!> ../../../docs_src/response_model/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="18" {!> ../../../docs_src/response_model/tutorial002.py!} @@ -146,7 +146,7 @@ We can instead create an input model with the plaintext password and an output m {!> ../../../docs_src/response_model/tutorial003_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9 11 16" {!> ../../../docs_src/response_model/tutorial003.py!} @@ -160,7 +160,7 @@ Here, even though our *path operation function* is returning the same input user {!> ../../../docs_src/response_model/tutorial003_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="24" {!> ../../../docs_src/response_model/tutorial003.py!} @@ -174,7 +174,7 @@ Here, even though our *path operation function* is returning the same input user {!> ../../../docs_src/response_model/tutorial003_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="22" {!> ../../../docs_src/response_model/tutorial003.py!} @@ -208,7 +208,7 @@ And in those cases, we can use classes and inheritance to take advantage of func {!> ../../../docs_src/response_model/tutorial003_01_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9-13 15-16 20" {!> ../../../docs_src/response_model/tutorial003_01.py!} @@ -284,7 +284,7 @@ The same would happen if you had something like a ../../../docs_src/security/tutorial003_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="83-86" {!> ../../../docs_src/security/tutorial003_an.py!} @@ -209,7 +209,7 @@ So, the thief won't be able to try to use those same passwords in another system {!> ../../../docs_src/security/tutorial003_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -264,7 +264,7 @@ For this simple example, we are going to just be completely insecure and return {!> ../../../docs_src/security/tutorial003_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="88" {!> ../../../docs_src/security/tutorial003_an.py!} @@ -279,7 +279,7 @@ For this simple example, we are going to just be completely insecure and return {!> ../../../docs_src/security/tutorial003_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. @@ -321,7 +321,7 @@ So, in our endpoint, we will only get a user if the user exists, was correctly a {!> ../../../docs_src/security/tutorial003_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="59-67 70-75 95" {!> ../../../docs_src/security/tutorial003_an.py!} @@ -336,7 +336,7 @@ So, in our endpoint, we will only get a user if the user exists, was correctly a {!> ../../../docs_src/security/tutorial003_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/en/docs/tutorial/sql-databases.md b/docs/en/docs/tutorial/sql-databases.md index 6e0e5dc06..010244bbf 100644 --- a/docs/en/docs/tutorial/sql-databases.md +++ b/docs/en/docs/tutorial/sql-databases.md @@ -281,7 +281,7 @@ But for security, the `password` won't be in other Pydantic *models*, for exampl {!> ../../../docs_src/sql_databases/sql_app_py39/schemas.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="3 6-8 11-12 23-24 27-28" {!> ../../../docs_src/sql_databases/sql_app/schemas.py!} @@ -325,7 +325,7 @@ Not only the IDs of those items, but all the data that we defined in the Pydanti {!> ../../../docs_src/sql_databases/sql_app_py39/schemas.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="15-17 31-34" {!> ../../../docs_src/sql_databases/sql_app/schemas.py!} @@ -354,7 +354,7 @@ In the `Config` class, set the attribute `orm_mode = True`. {!> ../../../docs_src/sql_databases/sql_app_py39/schemas.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="15 19-20 31 36-37" {!> ../../../docs_src/sql_databases/sql_app/schemas.py!} @@ -494,7 +494,7 @@ In a very simplistic way create the database tables: {!> ../../../docs_src/sql_databases/sql_app_py39/main.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/sql_databases/sql_app/main.py!} @@ -528,7 +528,7 @@ Our dependency will create a new SQLAlchemy `SessionLocal` that will be used in {!> ../../../docs_src/sql_databases/sql_app_py39/main.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="15-20" {!> ../../../docs_src/sql_databases/sql_app/main.py!} @@ -553,7 +553,7 @@ This will then give us better editor support inside the *path operation function {!> ../../../docs_src/sql_databases/sql_app_py39/main.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="24 32 38 47 53" {!> ../../../docs_src/sql_databases/sql_app/main.py!} @@ -574,7 +574,7 @@ Now, finally, here's the standard **FastAPI** *path operations* code. {!> ../../../docs_src/sql_databases/sql_app_py39/main.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="23-28 31-34 37-42 45-49 52-55" {!> ../../../docs_src/sql_databases/sql_app/main.py!} @@ -673,7 +673,7 @@ For example, in a background task worker with ../../../docs_src/sql_databases/sql_app_py39/schemas.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python {!> ../../../docs_src/sql_databases/sql_app/schemas.py!} @@ -693,7 +693,7 @@ For example, in a background task worker with ../../../docs_src/sql_databases/sql_app_py39/main.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python {!> ../../../docs_src/sql_databases/sql_app/main.py!} @@ -752,7 +752,7 @@ The middleware we'll add (just a function) will create a new SQLAlchemy `Session {!> ../../../docs_src/sql_databases/sql_app_py39/alt_main.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="14-22" {!> ../../../docs_src/sql_databases/sql_app/alt_main.py!} diff --git a/docs/en/docs/tutorial/testing.md b/docs/en/docs/tutorial/testing.md index ec133a4d0..3f8dd69a1 100644 --- a/docs/en/docs/tutorial/testing.md +++ b/docs/en/docs/tutorial/testing.md @@ -122,7 +122,7 @@ Both *path operations* require an `X-Token` header. {!> ../../../docs_src/app_testing/app_b_an_py39/main.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python {!> ../../../docs_src/app_testing/app_b_an/main.py!} @@ -137,7 +137,7 @@ Both *path operations* require an `X-Token` header. {!> ../../../docs_src/app_testing/app_b_py310/main.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/es/docs/features.md b/docs/es/docs/features.md index 5d6b6509a..d05c4f73e 100644 --- a/docs/es/docs/features.md +++ b/docs/es/docs/features.md @@ -25,7 +25,7 @@ Documentaciรณn interactiva de la API e interfaces web de exploraciรณn. Hay mรบlt ### Simplemente Python moderno -Todo estรก basado en las declaraciones de tipo de **Python 3.6** estรกndar (gracias a Pydantic). No necesitas aprender una sintรกxis nueva, solo Python moderno. +Todo estรก basado en las declaraciones de tipo de **Python 3.8** estรกndar (gracias a Pydantic). No necesitas aprender una sintรกxis nueva, solo Python moderno. Si necesitas un repaso de 2 minutos de cรณmo usar los tipos de Python (asรญ no uses FastAPI) prueba el tutorial corto: [Python Types](python-types.md){.internal-link target=_blank}. diff --git a/docs/es/docs/index.md b/docs/es/docs/index.md index 5b75880c0..30a575577 100644 --- a/docs/es/docs/index.md +++ b/docs/es/docs/index.md @@ -23,7 +23,7 @@ **Cรณdigo Fuente**: https://github.com/tiangolo/fastapi --- -FastAPI es un web framework moderno y rรกpido (de alto rendimiento) para construir APIs con Python 3.6+ basado en las anotaciones de tipos estรกndar de Python. +FastAPI es un web framework moderno y rรกpido (de alto rendimiento) para construir APIs con Python 3.8+ basado en las anotaciones de tipos estรกndar de Python. Sus caracterรญsticas principales son: @@ -106,7 +106,7 @@ Si estรกs construyendo un app de CLI< ## Wymagania -Python 3.7+ +Python 3.8+ FastAPI oparty jest na: @@ -321,7 +321,7 @@ Robisz to tak samo jak ze standardowymi typami w Pythonie. Nie musisz sie uczyฤ‡ ลผadnej nowej skล‚adni, metod lub klas ze specyficznych bibliotek itp. -Po prostu standardowy **Python 3.6+**. +Po prostu standardowy **Python 3.8+**. Na przykล‚ad, dla danych typu `int`: diff --git a/docs/pt/docs/features.md b/docs/pt/docs/features.md index bd0db8e76..822992c5b 100644 --- a/docs/pt/docs/features.md +++ b/docs/pt/docs/features.md @@ -25,7 +25,7 @@ Documentaรงรฃo interativa da API e navegaรงรฃo _web_ da interface de usuรกrio. C ### Apenas Python moderno -Tudo รฉ baseado no padrรฃo das declaraรงรตes de **tipos do Python 3.6** (graรงas ao Pydantic). Nenhuma sintaxe nova para aprender. Apenas o padrรฃo moderno do Python. +Tudo รฉ baseado no padrรฃo das declaraรงรตes de **tipos do Python 3.8** (graรงas ao Pydantic). Nenhuma sintaxe nova para aprender. Apenas o padrรฃo moderno do Python. Se vocรช precisa refrescar a memรณria rapidamente sobre como usar tipos do Python (mesmo que vocรช nรฃo use o FastAPI), confira esse rรกpido tutorial: [Tipos do Python](python-types.md){.internal-link target=_blank}. diff --git a/docs/pt/docs/index.md b/docs/pt/docs/index.md index 591e7f3d4..d1e64b3b9 100644 --- a/docs/pt/docs/index.md +++ b/docs/pt/docs/index.md @@ -24,7 +24,7 @@ --- -FastAPI รฉ um moderno e rรกpido (alta performance) _framework web_ para construรงรฃo de APIs com Python 3.6 ou superior, baseado nos _type hints_ padrรตes do Python. +FastAPI รฉ um moderno e rรกpido (alta performance) _framework web_ para construรงรฃo de APIs com Python 3.8 ou superior, baseado nos _type hints_ padrรตes do Python. Os recursos chave sรฃo: @@ -100,7 +100,7 @@ Se vocรช estiver construindo uma aplicaรงรฃo ../../../docs_src/body_multiple_params/tutorial001.py!} @@ -44,7 +44,7 @@ Mas vocรช pode tambรฉm declarar mรบltiplos parรขmetros de corpo, por exemplo, `i {!> ../../../docs_src/body_multiple_params/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="22" {!> ../../../docs_src/body_multiple_params/tutorial002.py!} @@ -87,7 +87,7 @@ Se vocรช declarรก-lo como รฉ, porque รฉ um valor singular, o **FastAPI** assumir Mas vocรช pode instruir o **FastAPI** para tratรก-lo como outra chave do corpo usando `Body`: -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="22" {!> ../../../docs_src/body_multiple_params/tutorial003.py!} @@ -143,7 +143,7 @@ Por exemplo: {!> ../../../docs_src/body_multiple_params/tutorial004_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="27" {!> ../../../docs_src/body_multiple_params/tutorial004.py!} @@ -172,7 +172,7 @@ como em: {!> ../../../docs_src/body_multiple_params/tutorial005_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="17" {!> ../../../docs_src/body_multiple_params/tutorial005.py!} diff --git a/docs/pt/docs/tutorial/encoder.md b/docs/pt/docs/tutorial/encoder.md index bb4483fdc..b9bfbf63b 100644 --- a/docs/pt/docs/tutorial/encoder.md +++ b/docs/pt/docs/tutorial/encoder.md @@ -26,7 +26,7 @@ A funรงรฃo recebe um objeto, como um modelo Pydantic e retorna uma versรฃo compa {!> ../../../docs_src/encoder/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="5 22" {!> ../../../docs_src/encoder/tutorial001.py!} diff --git a/docs/pt/docs/tutorial/extra-models.md b/docs/pt/docs/tutorial/extra-models.md index dd5407eb2..1343a3ae4 100644 --- a/docs/pt/docs/tutorial/extra-models.md +++ b/docs/pt/docs/tutorial/extra-models.md @@ -17,7 +17,7 @@ Isso รฉ especialmente o caso para modelos de usuรกrios, porque: Aqui estรก uma ideia geral de como os modelos poderiam parecer com seus campos de senha e os lugares onde sรฃo usados: -=== "Python 3.6 and above" +=== "Python 3.8 and above" ```Python hl_lines="9 11 16 22 24 29-30 33-35 40-41" {!> ../../../docs_src/extra_models/tutorial001.py!} @@ -158,7 +158,7 @@ Toda conversรฃo de dados, validaรงรฃo, documentaรงรฃo, etc. ainda funcionarรก no Dessa forma, podemos declarar apenas as diferenรงas entre os modelos (com `password` em texto claro, com `hashed_password` e sem senha): -=== "Python 3.6 and above" +=== "Python 3.8 and above" ```Python hl_lines="9 15-16 19-20 23-24" {!> ../../../docs_src/extra_models/tutorial002.py!} @@ -181,7 +181,7 @@ Para fazer isso, use a dica de tipo padrรฃo do Python `Union`, inclua o tipo mais especรญfico primeiro, seguido pelo tipo menos especรญfico. No exemplo abaixo, o tipo mais especรญfico `PlaneItem` vem antes de `CarItem` em `Union[PlaneItem, CarItem]`. -=== "Python 3.6 and above" +=== "Python 3.8 and above" ```Python hl_lines="1 14-15 18-20 33" {!> ../../../docs_src/extra_models/tutorial003.py!} @@ -213,7 +213,7 @@ Da mesma forma, vocรช pode declarar respostas de listas de objetos. Para isso, use o padrรฃo Python `typing.List` (ou simplesmente `list` no Python 3.9 e superior): -=== "Python 3.6 and above" +=== "Python 3.8 and above" ```Python hl_lines="1 20" {!> ../../../docs_src/extra_models/tutorial004.py!} @@ -233,7 +233,7 @@ Isso รฉ รบtil se vocรช nรฃo souber os nomes de campo / atributo vรกlidos (que se Neste caso, vocรช pode usar `typing.Dict` (ou simplesmente dict no Python 3.9 e superior): -=== "Python 3.6 and above" +=== "Python 3.8 and above" ```Python hl_lines="1 8" {!> ../../../docs_src/extra_models/tutorial005.py!} diff --git a/docs/pt/docs/tutorial/header-params.md b/docs/pt/docs/tutorial/header-params.md index bc8843327..4bdfb7e9c 100644 --- a/docs/pt/docs/tutorial/header-params.md +++ b/docs/pt/docs/tutorial/header-params.md @@ -12,7 +12,7 @@ Primeiro importe `Header`: {!> ../../../docs_src/header_params/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="3" {!> ../../../docs_src/header_params/tutorial001.py!} @@ -30,7 +30,7 @@ O primeiro valor รฉ o valor padrรฃo, vocรช pode passar todas as validaรงรตes adi {!> ../../../docs_src/header_params/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/header_params/tutorial001.py!} @@ -66,7 +66,7 @@ Se por algum motivo vocรช precisar desabilitar a conversรฃo automรกtica de subli {!> ../../../docs_src/header_params/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/header_params/tutorial002.py!} @@ -97,7 +97,7 @@ Por exemplo, para declarar um cabeรงalho de `X-Token` que pode aparecer mais de {!> ../../../docs_src/header_params/tutorial003_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/header_params/tutorial003.py!} diff --git a/docs/pt/docs/tutorial/path-operation-configuration.md b/docs/pt/docs/tutorial/path-operation-configuration.md index e0a23f665..13a87240f 100644 --- a/docs/pt/docs/tutorial/path-operation-configuration.md +++ b/docs/pt/docs/tutorial/path-operation-configuration.md @@ -13,7 +13,7 @@ Vocรช pode passar diretamente o cรณdigo `int`, como `404`. Mas se vocรช nรฃo se lembrar o que cada cรณdigo numรฉrico significa, pode usar as constantes de atalho em `status`: -=== "Python 3.6 and above" +=== "Python 3.8 and above" ```Python hl_lines="3 17" {!> ../../../docs_src/path_operation_configuration/tutorial001.py!} @@ -42,7 +42,7 @@ Esse cรณdigo de status serรก usado na resposta e serรก adicionado ao esquema Ope Vocรช pode adicionar tags para sua *operaรงรฃo de rota*, passe o parรขmetro `tags` com uma `list` de `str` (comumente apenas um `str`): -=== "Python 3.6 and above" +=== "Python 3.8 and above" ```Python hl_lines="17 22 27" {!> ../../../docs_src/path_operation_configuration/tutorial002.py!} @@ -80,7 +80,7 @@ Nestes casos, pode fazer sentido armazenar as tags em um `Enum`. Vocรช pode adicionar um `summary` e uma `description`: -=== "Python 3.6 and above" +=== "Python 3.8 and above" ```Python hl_lines="20-21" {!> ../../../docs_src/path_operation_configuration/tutorial003.py!} @@ -104,7 +104,7 @@ Como as descriรงรตes tendem a ser longas e cobrir vรกrias linhas, vocรช pode dec Vocรช pode escrever Markdown na docstring, ele serรก interpretado e exibido corretamente (levando em conta a indentaรงรฃo da docstring). -=== "Python 3.6 and above" +=== "Python 3.8 and above" ```Python hl_lines="19-27" {!> ../../../docs_src/path_operation_configuration/tutorial004.py!} @@ -131,7 +131,7 @@ Ela serรก usada nas documentaรงรตes interativas: Vocรช pode especificar a descriรงรฃo da resposta com o parรขmetro `response_description`: -=== "Python 3.6 and above" +=== "Python 3.8 and above" ```Python hl_lines="21" {!> ../../../docs_src/path_operation_configuration/tutorial005.py!} diff --git a/docs/pt/docs/tutorial/path-params-numeric-validations.md b/docs/pt/docs/tutorial/path-params-numeric-validations.md index ec9b74b30..eb0d31dc3 100644 --- a/docs/pt/docs/tutorial/path-params-numeric-validations.md +++ b/docs/pt/docs/tutorial/path-params-numeric-validations.md @@ -12,7 +12,7 @@ Primeiro, importe `Path` de `fastapi`: {!> ../../../docs_src/path_params_numeric_validations/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="3" {!> ../../../docs_src/path_params_numeric_validations/tutorial001.py!} @@ -30,7 +30,7 @@ Por exemplo para declarar um valor de metadado `title` para o parรขmetro de rota {!> ../../../docs_src/path_params_numeric_validations/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/path_params_numeric_validations/tutorial001.py!} diff --git a/docs/pt/docs/tutorial/query-params.md b/docs/pt/docs/tutorial/query-params.md index 3ada4fd21..08bb99dbc 100644 --- a/docs/pt/docs/tutorial/query-params.md +++ b/docs/pt/docs/tutorial/query-params.md @@ -69,7 +69,7 @@ Da mesma forma, vocรช pode declarar parรขmetros de consulta opcionais, definindo {!> ../../../docs_src/query_params/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/query_params/tutorial002.py!} @@ -91,7 +91,7 @@ Vocรช tambรฉm pode declarar tipos `bool`, e eles serรฃo convertidos: {!> ../../../docs_src/query_params/tutorial003_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/query_params/tutorial003.py!} @@ -143,7 +143,7 @@ Eles serรฃo detectados pelo nome: {!> ../../../docs_src/query_params/tutorial004_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="8 10" {!> ../../../docs_src/query_params/tutorial004.py!} @@ -209,7 +209,7 @@ E claro, vocรช pode definir alguns parรขmetros como obrigatรณrios, alguns possui {!> ../../../docs_src/query_params/tutorial006_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/query_params/tutorial006.py!} diff --git a/docs/ru/docs/features.md b/docs/ru/docs/features.md index e18f7bc87..97841cc83 100644 --- a/docs/ru/docs/features.md +++ b/docs/ru/docs/features.md @@ -27,7 +27,7 @@ ### ะขะพะปัŒะบะพ ัะพะฒั€ะตะผะตะฝะฝั‹ะน Python -ะ’ัะต ัั‚ะธ ะฒะพะทะผะพะถะฝะพัั‚ะธ ะพัะฝะพะฒะฐะฝั‹ ะฝะฐ ัั‚ะฐะฝะดะฐั€ั‚ะฝั‹ั… **ะฐะฝะฝะพั‚ะฐั†ะธัั… ั‚ะธะฟะพะฒ Python 3.6** (ะฑะปะฐะณะพะดะฐั€ั Pydantic). ะะต ะฝัƒะถะฝะพ ะธะทัƒั‡ะฐั‚ัŒ ะฝะพะฒั‹ะน ัะธะฝั‚ะฐะบัะธั. ะขะพะปัŒะบะพ ะปะธัˆัŒ ัั‚ะฐะฝะดะฐั€ั‚ะฝั‹ะน ัะพะฒั€ะตะผะตะฝะฝั‹ะน Python. +ะ’ัะต ัั‚ะธ ะฒะพะทะผะพะถะฝะพัั‚ะธ ะพัะฝะพะฒะฐะฝั‹ ะฝะฐ ัั‚ะฐะฝะดะฐั€ั‚ะฝั‹ั… **ะฐะฝะฝะพั‚ะฐั†ะธัั… ั‚ะธะฟะพะฒ Python 3.8** (ะฑะปะฐะณะพะดะฐั€ั Pydantic). ะะต ะฝัƒะถะฝะพ ะธะทัƒั‡ะฐั‚ัŒ ะฝะพะฒั‹ะน ัะธะฝั‚ะฐะบัะธั. ะขะพะปัŒะบะพ ะปะธัˆัŒ ัั‚ะฐะฝะดะฐั€ั‚ะฝั‹ะน ัะพะฒั€ะตะผะตะฝะฝั‹ะน Python. ะ•ัะปะธ ะฒะฐะผ ะฝัƒะถะฝะพ ะพัะฒะตะถะธั‚ัŒ ะทะฝะฐะฝะธั, ะบะฐะบ ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฐะฝะฝะพั‚ะฐั†ะธะธ ั‚ะธะฟะพะฒ ะฒ Python (ะดะฐะถะต ะตัะปะธ ะฒั‹ ะฝะต ะธัะฟะพะปัŒะทัƒะตั‚ะต FastAPI), ะฒั‹ะดะตะปะธั‚ะต 2 ะผะธะฝัƒั‚ั‹ ะธ ะฟั€ะพัะผะพั‚ั€ะธั‚ะต ะบั€ะฐั‚ะบะพะต ั€ัƒะบะพะฒะพะดัั‚ะฒะพ: [ะ’ะฒะตะดะตะฝะธะต ะฒ ะฐะฝะฝะพั‚ะฐั†ะธะธ ั‚ะธะฟะพะฒ Pythonยถ ](python-types.md){.internal-link target=_blank}. diff --git a/docs/ru/docs/index.md b/docs/ru/docs/index.md index 30c32e046..97a3947bd 100644 --- a/docs/ru/docs/index.md +++ b/docs/ru/docs/index.md @@ -27,7 +27,7 @@ --- -FastAPI โ€” ัั‚ะพ ัะพะฒั€ะตะผะตะฝะฝั‹ะน, ะฑั‹ัั‚ั€ั‹ะน (ะฒั‹ัะพะบะพะฟั€ะพะธะทะฒะพะดะธั‚ะตะปัŒะฝั‹ะน) ะฒะตะฑ-ั„ั€ะตะนะผะฒะพั€ะบ ะดะปั ัะพะทะดะฐะฝะธั API ะธัะฟะพะปัŒะทัƒั Python 3.6+, ะฒ ะพัะฝะพะฒะต ะบะพั‚ะพั€ะพะณะพ ะปะตะถะธั‚ ัั‚ะฐะฝะดะฐั€ั‚ะฝะฐั ะฐะฝะฝะพั‚ะฐั†ะธั ั‚ะธะฟะพะฒ Python. +FastAPI โ€” ัั‚ะพ ัะพะฒั€ะตะผะตะฝะฝั‹ะน, ะฑั‹ัั‚ั€ั‹ะน (ะฒั‹ัะพะบะพะฟั€ะพะธะทะฒะพะดะธั‚ะตะปัŒะฝั‹ะน) ะฒะตะฑ-ั„ั€ะตะนะผะฒะพั€ะบ ะดะปั ัะพะทะดะฐะฝะธั API ะธัะฟะพะปัŒะทัƒั Python 3.8+, ะฒ ะพัะฝะพะฒะต ะบะพั‚ะพั€ะพะณะพ ะปะตะถะธั‚ ัั‚ะฐะฝะดะฐั€ั‚ะฝะฐั ะฐะฝะฝะพั‚ะฐั†ะธั ั‚ะธะฟะพะฒ Python. ะšะปัŽั‡ะตะฒั‹ะต ะพัะพะฑะตะฝะฝะพัั‚ะธ: @@ -109,7 +109,7 @@ FastAPI โ€” ัั‚ะพ ัะพะฒั€ะตะผะตะฝะฝั‹ะน, ะฑั‹ัั‚ั€ั‹ะน (ะฒั‹ัะพะบะพะฟั€ะพะธ ## ะ—ะฐะฒะธัะธะผะพัั‚ะธ -Python 3.7+ +Python 3.8+ FastAPI ัั‚ะพะธั‚ ะฝะฐ ะฟะปะตั‡ะฐั… ะณะธะณะฐะฝั‚ะพะฒ: @@ -325,7 +325,7 @@ def update_item(item_id: int, item: Item): ะ’ะฐะผ ะฝะต ะฝัƒะถะฝะพ ะธะทัƒั‡ะฐั‚ัŒ ะฝะพะฒั‹ะน ัะธะฝั‚ะฐะบัะธั, ะผะตั‚ะพะดั‹ ะธะปะธ ะบะปะฐััั‹ ะบะพะฝะบั€ะตั‚ะฝะพะน ะฑะธะฑะปะธะพั‚ะตะบะธ ะธ ั‚. ะด. -ะขะพะปัŒะบะพ ัั‚ะฐะฝะดะฐั€ั‚ะฝั‹ะน **Python 3.6+**. +ะขะพะปัŒะบะพ ัั‚ะฐะฝะดะฐั€ั‚ะฝั‹ะน **Python 3.8+**. ะะฐะฟั€ะธะผะตั€, ะดะปั `int`: diff --git a/docs/ru/docs/tutorial/background-tasks.md b/docs/ru/docs/tutorial/background-tasks.md index 81efda786..7a3cf6d83 100644 --- a/docs/ru/docs/tutorial/background-tasks.md +++ b/docs/ru/docs/tutorial/background-tasks.md @@ -63,7 +63,7 @@ {!> ../../../docs_src/background_tasks/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="13 15 22 25" {!> ../../../docs_src/background_tasks/tutorial002.py!} diff --git a/docs/ru/docs/tutorial/body-fields.md b/docs/ru/docs/tutorial/body-fields.md index 2dc6c1e26..02a598004 100644 --- a/docs/ru/docs/tutorial/body-fields.md +++ b/docs/ru/docs/tutorial/body-fields.md @@ -12,7 +12,7 @@ {!> ../../../docs_src/body_fields/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="4" {!> ../../../docs_src/body_fields/tutorial001.py!} @@ -31,7 +31,7 @@ {!> ../../../docs_src/body_fields/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="11-14" {!> ../../../docs_src/body_fields/tutorial001.py!} diff --git a/docs/ru/docs/tutorial/body-multiple-params.md b/docs/ru/docs/tutorial/body-multiple-params.md index a20457092..e52ef6f6f 100644 --- a/docs/ru/docs/tutorial/body-multiple-params.md +++ b/docs/ru/docs/tutorial/body-multiple-params.md @@ -20,7 +20,7 @@ {!> ../../../docs_src/body_multiple_params/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="19-21" {!> ../../../docs_src/body_multiple_params/tutorial001_an.py!} @@ -35,7 +35,7 @@ {!> ../../../docs_src/body_multiple_params/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! ะ—ะฐะผะตั‚ะบะฐ ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated`, ะตัะปะธ ัั‚ะพ ะฒะพะทะผะพะถะฝะพ. @@ -68,7 +68,7 @@ {!> ../../../docs_src/body_multiple_params/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="22" {!> ../../../docs_src/body_multiple_params/tutorial002.py!} @@ -123,7 +123,7 @@ {!> ../../../docs_src/body_multiple_params/tutorial003_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="24" {!> ../../../docs_src/body_multiple_params/tutorial003_an.py!} @@ -138,7 +138,7 @@ {!> ../../../docs_src/body_multiple_params/tutorial003_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! ะ—ะฐะผะตั‚ะบะฐ ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ `Annotated` ะฒะตั€ัะธัŽ, ะตัะปะธ ัั‚ะพ ะฒะพะทะผะพะถะฝะพ. @@ -197,7 +197,7 @@ q: str | None = None {!> ../../../docs_src/body_multiple_params/tutorial004_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="28" {!> ../../../docs_src/body_multiple_params/tutorial004_an.py!} @@ -212,7 +212,7 @@ q: str | None = None {!> ../../../docs_src/body_multiple_params/tutorial004_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! ะ—ะฐะผะตั‚ะบะฐ ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ `Annotated` ะฒะตั€ัะธัŽ, ะตัะปะธ ัั‚ะพ ะฒะพะทะผะพะถะฝะพ. @@ -250,7 +250,7 @@ item: Item = Body(embed=True) {!> ../../../docs_src/body_multiple_params/tutorial005_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="18" {!> ../../../docs_src/body_multiple_params/tutorial005_an.py!} @@ -265,7 +265,7 @@ item: Item = Body(embed=True) {!> ../../../docs_src/body_multiple_params/tutorial005_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! ะ—ะฐะผะตั‚ะบะฐ ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ `Annotated` ะฒะตั€ัะธัŽ, ะตัะปะธ ัั‚ะพ ะฒะพะทะผะพะถะฝะพ. diff --git a/docs/ru/docs/tutorial/body-nested-models.md b/docs/ru/docs/tutorial/body-nested-models.md index 6435e316f..a6d123d30 100644 --- a/docs/ru/docs/tutorial/body-nested-models.md +++ b/docs/ru/docs/tutorial/body-nested-models.md @@ -12,7 +12,7 @@ {!> ../../../docs_src/body_nested_models/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="14" {!> ../../../docs_src/body_nested_models/tutorial001.py!} @@ -73,7 +73,7 @@ my_list: List[str] {!> ../../../docs_src/body_nested_models/tutorial002_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="14" {!> ../../../docs_src/body_nested_models/tutorial002.py!} @@ -99,7 +99,7 @@ my_list: List[str] {!> ../../../docs_src/body_nested_models/tutorial003_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 14" {!> ../../../docs_src/body_nested_models/tutorial003.py!} @@ -137,7 +137,7 @@ my_list: List[str] {!> ../../../docs_src/body_nested_models/tutorial004_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9-11" {!> ../../../docs_src/body_nested_models/tutorial004.py!} @@ -159,7 +159,7 @@ my_list: List[str] {!> ../../../docs_src/body_nested_models/tutorial004_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="20" {!> ../../../docs_src/body_nested_models/tutorial004.py!} @@ -208,7 +208,7 @@ my_list: List[str] {!> ../../../docs_src/body_nested_models/tutorial005_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="4 10" {!> ../../../docs_src/body_nested_models/tutorial005.py!} @@ -232,7 +232,7 @@ my_list: List[str] {!> ../../../docs_src/body_nested_models/tutorial006_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="20" {!> ../../../docs_src/body_nested_models/tutorial006.py!} @@ -283,7 +283,7 @@ my_list: List[str] {!> ../../../docs_src/body_nested_models/tutorial007_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9 14 20 23 27" {!> ../../../docs_src/body_nested_models/tutorial007.py!} @@ -314,7 +314,7 @@ images: list[Image] {!> ../../../docs_src/body_nested_models/tutorial008_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="15" {!> ../../../docs_src/body_nested_models/tutorial008.py!} @@ -354,7 +354,7 @@ images: list[Image] {!> ../../../docs_src/body_nested_models/tutorial009_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/body_nested_models/tutorial009.py!} diff --git a/docs/ru/docs/tutorial/cookie-params.md b/docs/ru/docs/tutorial/cookie-params.md index a6f2caa26..5f99458b6 100644 --- a/docs/ru/docs/tutorial/cookie-params.md +++ b/docs/ru/docs/tutorial/cookie-params.md @@ -12,7 +12,7 @@ {!> ../../../docs_src/cookie_params/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="3" {!> ../../../docs_src/cookie_params/tutorial001.py!} @@ -30,7 +30,7 @@ {!> ../../../docs_src/cookie_params/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/cookie_params/tutorial001.py!} diff --git a/docs/ru/docs/tutorial/dependencies/global-dependencies.md b/docs/ru/docs/tutorial/dependencies/global-dependencies.md index 870d42cf5..eb1b4d7c1 100644 --- a/docs/ru/docs/tutorial/dependencies/global-dependencies.md +++ b/docs/ru/docs/tutorial/dependencies/global-dependencies.md @@ -12,13 +12,13 @@ {!> ../../../docs_src/dependencies/tutorial012_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="16" {!> ../../../docs_src/dependencies/tutorial012_an.py!} ``` -=== "Python 3.6 non-Annotated" +=== "Python 3.8 non-Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ 'Annotated' ะฒะตั€ัะธัŽ, ะตัะปะธ ัั‚ะพ ะฒะพะทะผะพะถะฝะพ. diff --git a/docs/ru/docs/tutorial/extra-data-types.md b/docs/ru/docs/tutorial/extra-data-types.md index efcbcb38a..0f613a6b2 100644 --- a/docs/ru/docs/tutorial/extra-data-types.md +++ b/docs/ru/docs/tutorial/extra-data-types.md @@ -55,7 +55,7 @@ ะ’ะพั‚ ะฟั€ะธะผะตั€ *ะพะฟะตั€ะฐั†ะธะธ ะฟัƒั‚ะธ* ั ะฟะฐั€ะฐะผะตั‚ั€ะฐะผะธ, ะบะพั‚ะพั€ั‹ะน ะดะตะผะพะฝัั‚ั€ะธั€ัƒะตั‚ ะฝะตะบะพั‚ะพั€ั‹ะต ะธะท ะฒั‹ัˆะตะฟะตั€ะตั‡ะธัะปะตะฝะฝั‹ั… ั‚ะธะฟะพะฒ. -=== "Python 3.6 ะธ ะฒั‹ัˆะต" +=== "Python 3.8 ะธ ะฒั‹ัˆะต" ```Python hl_lines="1 3 12-16" {!> ../../../docs_src/extra_data_types/tutorial001.py!} @@ -69,7 +69,7 @@ ะžะฑั€ะฐั‚ะธั‚ะต ะฒะฝะธะผะฐะฝะธะต, ั‡ั‚ะพ ะฟะฐั€ะฐะผะตั‚ั€ั‹ ะฒะฝัƒั‚ั€ะธ ั„ัƒะฝะบั†ะธะธ ะธะผะตัŽั‚ ัะฒะพะน ะตัั‚ะตัั‚ะฒะตะฝะฝั‹ะน ั‚ะธะฟ ะดะฐะฝะฝั‹ั…, ะธ ะฒั‹, ะฝะฐะฟั€ะธะผะตั€, ะผะพะถะตั‚ะต ะฒั‹ะฟะพะปะฝัั‚ัŒ ะพะฑั‹ั‡ะฝั‹ะต ะผะฐะฝะธะฟัƒะปัั†ะธะธ ั ะดะฐั‚ะฐะผะธ, ั‚ะฐะบะธะต ะบะฐะบ: -=== "Python 3.6 ะธ ะฒั‹ัˆะต" +=== "Python 3.8 ะธ ะฒั‹ัˆะต" ```Python hl_lines="18-19" {!> ../../../docs_src/extra_data_types/tutorial001.py!} diff --git a/docs/ru/docs/tutorial/extra-models.md b/docs/ru/docs/tutorial/extra-models.md index a346f7432..30176b4e3 100644 --- a/docs/ru/docs/tutorial/extra-models.md +++ b/docs/ru/docs/tutorial/extra-models.md @@ -23,7 +23,7 @@ {!> ../../../docs_src/extra_models/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9 11 16 22 24 29-30 33-35 40-41" {!> ../../../docs_src/extra_models/tutorial001.py!} @@ -164,7 +164,7 @@ UserInDB( {!> ../../../docs_src/extra_models/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9 15-16 19-20 23-24" {!> ../../../docs_src/extra_models/tutorial002.py!} @@ -187,7 +187,7 @@ UserInDB( {!> ../../../docs_src/extra_models/tutorial003_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 14-15 18-20 33" {!> ../../../docs_src/extra_models/tutorial003.py!} @@ -219,7 +219,7 @@ some_variable: PlaneItem | CarItem {!> ../../../docs_src/extra_models/tutorial004_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 20" {!> ../../../docs_src/extra_models/tutorial004.py!} @@ -239,7 +239,7 @@ some_variable: PlaneItem | CarItem {!> ../../../docs_src/extra_models/tutorial005_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 8" {!> ../../../docs_src/extra_models/tutorial005.py!} diff --git a/docs/ru/docs/tutorial/header-params.md b/docs/ru/docs/tutorial/header-params.md index 0ff8ea489..1be4ac707 100644 --- a/docs/ru/docs/tutorial/header-params.md +++ b/docs/ru/docs/tutorial/header-params.md @@ -18,7 +18,7 @@ {!> ../../../docs_src/header_params/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="3" {!> ../../../docs_src/header_params/tutorial001_an.py!} @@ -33,7 +33,7 @@ {!> ../../../docs_src/header_params/tutorial001_py310.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะŸั€ะตะดะฟะพั‡ั‚ะธั‚ะตะปัŒะฝะตะต ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั ะฐะฝะฝะพั‚ะฐั†ะธะตะน, ะตัะปะธ ัั‚ะพ ะฒะพะทะผะพะถะฝะพ. @@ -60,7 +60,7 @@ {!> ../../../docs_src/header_params/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/header_params/tutorial001_an.py!} @@ -75,7 +75,7 @@ {!> ../../../docs_src/header_params/tutorial001_py310.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะŸั€ะตะดะฟะพั‡ั‚ะธั‚ะตะปัŒะฝะตะต ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั ะฐะฝะฝะพั‚ะฐั†ะธะตะน, ะตัะปะธ ัั‚ะพ ะฒะพะทะผะพะถะฝะพ. @@ -120,7 +120,7 @@ {!> ../../../docs_src/header_params/tutorial002_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="12" {!> ../../../docs_src/header_params/tutorial002_an.py!} @@ -135,7 +135,7 @@ {!> ../../../docs_src/header_params/tutorial002_py310.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะŸั€ะตะดะฟะพั‡ั‚ะธั‚ะตะปัŒะฝะตะต ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั ะฐะฝะฝะพั‚ะฐั†ะธะตะน, ะตัะปะธ ัั‚ะพ ะฒะพะทะผะพะถะฝะพ. @@ -169,7 +169,7 @@ {!> ../../../docs_src/header_params/tutorial003_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/header_params/tutorial003_an.py!} @@ -193,7 +193,7 @@ {!> ../../../docs_src/header_params/tutorial003_py39.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะŸั€ะตะดะฟะพั‡ั‚ะธั‚ะตะปัŒะฝะตะต ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั ะฐะฝะฝะพั‚ะฐั†ะธะตะน, ะตัะปะธ ัั‚ะพ ะฒะพะทะผะพะถะฝะพ. diff --git a/docs/ru/docs/tutorial/path-operation-configuration.md b/docs/ru/docs/tutorial/path-operation-configuration.md index 013903add..db99409f4 100644 --- a/docs/ru/docs/tutorial/path-operation-configuration.md +++ b/docs/ru/docs/tutorial/path-operation-configuration.md @@ -25,7 +25,7 @@ {!> ../../../docs_src/path_operation_configuration/tutorial001_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="3 17" {!> ../../../docs_src/path_operation_configuration/tutorial001.py!} @@ -54,7 +54,7 @@ {!> ../../../docs_src/path_operation_configuration/tutorial002_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="17 22 27" {!> ../../../docs_src/path_operation_configuration/tutorial002.py!} @@ -92,7 +92,7 @@ {!> ../../../docs_src/path_operation_configuration/tutorial003_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="20-21" {!> ../../../docs_src/path_operation_configuration/tutorial003.py!} @@ -116,7 +116,7 @@ {!> ../../../docs_src/path_operation_configuration/tutorial004_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="19-27" {!> ../../../docs_src/path_operation_configuration/tutorial004.py!} @@ -142,7 +142,7 @@ {!> ../../../docs_src/path_operation_configuration/tutorial005_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="21" {!> ../../../docs_src/path_operation_configuration/tutorial005.py!} diff --git a/docs/ru/docs/tutorial/path-params-numeric-validations.md b/docs/ru/docs/tutorial/path-params-numeric-validations.md index 0d034ef34..bd2c29d0a 100644 --- a/docs/ru/docs/tutorial/path-params-numeric-validations.md +++ b/docs/ru/docs/tutorial/path-params-numeric-validations.md @@ -18,7 +18,7 @@ {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="3-4" {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an.py!} @@ -33,7 +33,7 @@ {!> ../../../docs_src/path_params_numeric_validations/tutorial001_py310.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated` ะตัะปะธ ะฒะพะทะผะพะถะฝะพ. @@ -67,7 +67,7 @@ {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="11" {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an.py!} @@ -82,7 +82,7 @@ {!> ../../../docs_src/path_params_numeric_validations/tutorial001_py310.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated` ะตัะปะธ ะฒะพะทะผะพะถะฝะพ. @@ -117,7 +117,7 @@ ะŸะพัั‚ะพะผัƒ ะฒั‹ ะผะพะถะตั‚ะต ะพะฟั€ะตะดะตะปะธั‚ัŒ ั„ัƒะฝะบั†ะธัŽ ั‚ะฐะบ: -=== "Python 3.6 ะฑะตะท Annotated" +=== "Python 3.8 ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated` ะตัะปะธ ะฒะพะทะผะพะถะฝะพ. @@ -134,7 +134,7 @@ {!> ../../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/path_params_numeric_validations/tutorial002_an.py!} @@ -174,7 +174,7 @@ Python ะฝะต ะฑัƒะดะตั‚ ะฝะธั‡ะตะณะพ ะดะตะปะฐั‚ัŒ ั `*`, ะฝะพ ะพะฝ ะฑัƒะดะตั‚ ะท {!> ../../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/path_params_numeric_validations/tutorial003_an.py!} @@ -192,13 +192,13 @@ Python ะฝะต ะฑัƒะดะตั‚ ะฝะธั‡ะตะณะพ ะดะตะปะฐั‚ัŒ ั `*`, ะฝะพ ะพะฝ ะฑัƒะดะตั‚ ะท {!> ../../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/path_params_numeric_validations/tutorial004_an.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated` ะตัะปะธ ะฒะพะทะผะพะถะฝะพ. @@ -220,13 +220,13 @@ Python ะฝะต ะฑัƒะดะตั‚ ะฝะธั‡ะตะณะพ ะดะตะปะฐั‚ัŒ ั `*`, ะฝะพ ะพะฝ ะฑัƒะดะตั‚ ะท {!> ../../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/path_params_numeric_validations/tutorial005_an.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated` ะตัะปะธ ะฒะพะทะผะพะถะฝะพ. @@ -251,13 +251,13 @@ Python ะฝะต ะฑัƒะดะตั‚ ะฝะธั‡ะตะณะพ ะดะตะปะฐั‚ัŒ ั `*`, ะฝะพ ะพะฝ ะฑัƒะดะตั‚ ะท {!> ../../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="12" {!> ../../../docs_src/path_params_numeric_validations/tutorial006_an.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated` ะตัะปะธ ะฒะพะทะผะพะถะฝะพ. diff --git a/docs/ru/docs/tutorial/query-params-str-validations.md b/docs/ru/docs/tutorial/query-params-str-validations.md index 68042db63..15be5dbf6 100644 --- a/docs/ru/docs/tutorial/query-params-str-validations.md +++ b/docs/ru/docs/tutorial/query-params-str-validations.md @@ -10,7 +10,7 @@ {!> ../../../docs_src/query_params_str_validations/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/query_params_str_validations/tutorial001.py!} @@ -42,7 +42,7 @@ Query-ะฟะฐั€ะฐะผะตั‚ั€ `q` ะธะผะตะตั‚ ั‚ะธะฟ `Union[str, None]` (ะธะปะธ `str | N {!> ../../../docs_src/query_params_str_validations/tutorial002_an_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ะ’ ะฒะตั€ัะธัั… Python ะฝะธะถะต Python 3.9 `Annotation` ะธะผะฟะพั€ั‚ะธั€ัƒะตั‚ัั ะธะท `typing_extensions`. @@ -66,7 +66,7 @@ Query-ะฟะฐั€ะฐะผะตั‚ั€ `q` ะธะผะตะตั‚ ั‚ะธะฟ `Union[str, None]` (ะธะปะธ `str | N q: str | None = None ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python q: Union[str, None] = None @@ -80,7 +80,7 @@ Query-ะฟะฐั€ะฐะผะตั‚ั€ `q` ะธะผะตะตั‚ ั‚ะธะฟ `Union[str, None]` (ะธะปะธ `str | N q: Annotated[str | None] = None ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python q: Annotated[Union[str, None]] = None @@ -100,7 +100,7 @@ Query-ะฟะฐั€ะฐะผะตั‚ั€ `q` ะธะผะตะตั‚ ั‚ะธะฟ `Union[str, None]` (ะธะปะธ `str | N {!> ../../../docs_src/query_params_str_validations/tutorial002_an_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/query_params_str_validations/tutorial002_an.py!} @@ -131,7 +131,7 @@ Query-ะฟะฐั€ะฐะผะตั‚ั€ `q` ะธะผะตะตั‚ ั‚ะธะฟ `Union[str, None]` (ะธะปะธ `str | N {!> ../../../docs_src/query_params_str_validations/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/query_params_str_validations/tutorial002.py!} @@ -244,7 +244,7 @@ q: str = Query(default="rick") {!> ../../../docs_src/query_params_str_validations/tutorial003_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="11" {!> ../../../docs_src/query_params_str_validations/tutorial003_an.py!} @@ -259,7 +259,7 @@ q: str = Query(default="rick") {!> ../../../docs_src/query_params_str_validations/tutorial003_py310.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated` ะตัะปะธ ะฒะพะทะผะพะถะฝะพ. @@ -284,7 +284,7 @@ q: str = Query(default="rick") {!> ../../../docs_src/query_params_str_validations/tutorial004_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="12" {!> ../../../docs_src/query_params_str_validations/tutorial004_an.py!} @@ -299,7 +299,7 @@ q: str = Query(default="rick") {!> ../../../docs_src/query_params_str_validations/tutorial004_py310.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated` ะตัะปะธ ะฒะพะทะผะพะถะฝะพ. @@ -330,13 +330,13 @@ q: str = Query(default="rick") {!> ../../../docs_src/query_params_str_validations/tutorial005_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="8" {!> ../../../docs_src/query_params_str_validations/tutorial005_an.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated` ะตัะปะธ ะฒะพะทะผะพะถะฝะพ. @@ -384,13 +384,13 @@ q: Union[str, None] = None {!> ../../../docs_src/query_params_str_validations/tutorial006_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="8" {!> ../../../docs_src/query_params_str_validations/tutorial006_an.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated` ะตัะปะธ ะฒะพะทะผะพะถะฝะพ. @@ -414,13 +414,13 @@ q: Union[str, None] = None {!> ../../../docs_src/query_params_str_validations/tutorial006b_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="8" {!> ../../../docs_src/query_params_str_validations/tutorial006b_an.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated` ะตัะปะธ ะฒะพะทะผะพะถะฝะพ. @@ -454,7 +454,7 @@ q: Union[str, None] = None {!> ../../../docs_src/query_params_str_validations/tutorial006c_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/query_params_str_validations/tutorial006c_an.py!} @@ -469,7 +469,7 @@ q: Union[str, None] = None {!> ../../../docs_src/query_params_str_validations/tutorial006c_py310.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated` ะตัะปะธ ะฒะพะทะผะพะถะฝะพ. @@ -491,13 +491,13 @@ q: Union[str, None] = None {!> ../../../docs_src/query_params_str_validations/tutorial006d_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="2 9" {!> ../../../docs_src/query_params_str_validations/tutorial006d_an.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated` ะตัะปะธ ะฒะพะทะผะพะถะฝะพ. @@ -527,7 +527,7 @@ q: Union[str, None] = None {!> ../../../docs_src/query_params_str_validations/tutorial011_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/query_params_str_validations/tutorial011_an.py!} @@ -551,7 +551,7 @@ q: Union[str, None] = None {!> ../../../docs_src/query_params_str_validations/tutorial011_py39.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated` ะตัะปะธ ะฒะพะทะผะพะถะฝะพ. @@ -596,7 +596,7 @@ http://localhost:8000/items/?q=foo&q=bar {!> ../../../docs_src/query_params_str_validations/tutorial012_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/query_params_str_validations/tutorial012_an.py!} @@ -611,7 +611,7 @@ http://localhost:8000/items/?q=foo&q=bar {!> ../../../docs_src/query_params_str_validations/tutorial012_py39.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated` ะตัะปะธ ะฒะพะทะผะพะถะฝะพ. @@ -647,13 +647,13 @@ http://localhost:8000/items/ {!> ../../../docs_src/query_params_str_validations/tutorial013_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="8" {!> ../../../docs_src/query_params_str_validations/tutorial013_an.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated` ะตัะปะธ ะฒะพะทะผะพะถะฝะพ. @@ -692,7 +692,7 @@ http://localhost:8000/items/ {!> ../../../docs_src/query_params_str_validations/tutorial007_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="11" {!> ../../../docs_src/query_params_str_validations/tutorial007_an.py!} @@ -707,7 +707,7 @@ http://localhost:8000/items/ {!> ../../../docs_src/query_params_str_validations/tutorial007_py310.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated` ะตัะปะธ ะฒะพะทะผะพะถะฝะพ. @@ -730,7 +730,7 @@ http://localhost:8000/items/ {!> ../../../docs_src/query_params_str_validations/tutorial008_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="15" {!> ../../../docs_src/query_params_str_validations/tutorial008_an.py!} @@ -745,7 +745,7 @@ http://localhost:8000/items/ {!> ../../../docs_src/query_params_str_validations/tutorial008_py310.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated` ะตัะปะธ ะฒะพะทะผะพะถะฝะพ. @@ -784,7 +784,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems {!> ../../../docs_src/query_params_str_validations/tutorial009_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/query_params_str_validations/tutorial009_an.py!} @@ -799,7 +799,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems {!> ../../../docs_src/query_params_str_validations/tutorial009_py310.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated` ะตัะปะธ ะฒะพะทะผะพะถะฝะพ. @@ -828,7 +828,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems {!> ../../../docs_src/query_params_str_validations/tutorial010_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="20" {!> ../../../docs_src/query_params_str_validations/tutorial010_an.py!} @@ -843,7 +843,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems {!> ../../../docs_src/query_params_str_validations/tutorial010_py310.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated` ะตัะปะธ ะฒะพะทะผะพะถะฝะพ. @@ -872,7 +872,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems {!> ../../../docs_src/query_params_str_validations/tutorial014_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="11" {!> ../../../docs_src/query_params_str_validations/tutorial014_an.py!} @@ -887,7 +887,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems {!> ../../../docs_src/query_params_str_validations/tutorial014_py310.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated` ะตัะปะธ ะฒะพะทะผะพะถะฝะพ. diff --git a/docs/ru/docs/tutorial/query-params.md b/docs/ru/docs/tutorial/query-params.md index 68333ec56..6e885cb65 100644 --- a/docs/ru/docs/tutorial/query-params.md +++ b/docs/ru/docs/tutorial/query-params.md @@ -69,7 +69,7 @@ http://127.0.0.1:8000/items/?skip=20 {!> ../../../docs_src/query_params/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/query_params/tutorial002.py!} @@ -90,7 +90,7 @@ http://127.0.0.1:8000/items/?skip=20 {!> ../../../docs_src/query_params/tutorial003_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/query_params/tutorial003.py!} @@ -143,7 +143,7 @@ http://127.0.0.1:8000/items/foo?short=yes {!> ../../../docs_src/query_params/tutorial004_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="8 10" {!> ../../../docs_src/query_params/tutorial004.py!} @@ -209,7 +209,7 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy {!> ../../../docs_src/query_params/tutorial006_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/query_params/tutorial006.py!} diff --git a/docs/ru/docs/tutorial/request-forms.md b/docs/ru/docs/tutorial/request-forms.md index a20cf78e0..0fc9e4eda 100644 --- a/docs/ru/docs/tutorial/request-forms.md +++ b/docs/ru/docs/tutorial/request-forms.md @@ -17,13 +17,13 @@ {!> ../../../docs_src/request_forms/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1" {!> ../../../docs_src/request_forms/tutorial001_an.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ 'Annotated' ะฒะตั€ัะธัŽ, ะตัะปะธ ัั‚ะพ ะฒะพะทะผะพะถะฝะพ. @@ -42,13 +42,13 @@ {!> ../../../docs_src/request_forms/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="8" {!> ../../../docs_src/request_forms/tutorial001_an.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ 'Annotated' ะฒะตั€ัะธัŽ, ะตัะปะธ ัั‚ะพ ะฒะพะทะผะพะถะฝะพ. diff --git a/docs/ru/docs/tutorial/response-model.md b/docs/ru/docs/tutorial/response-model.md index c5e111790..38b45e2a5 100644 --- a/docs/ru/docs/tutorial/response-model.md +++ b/docs/ru/docs/tutorial/response-model.md @@ -16,7 +16,7 @@ FastAPI ะฟะพะทะฒะพะปัะตั‚ ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ **ะฐะฝะฝะพั‚ะฐั†ะธะธ ั‚ะธะฟ {!> ../../../docs_src/response_model/tutorial001_01_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="18 23" {!> ../../../docs_src/response_model/tutorial001_01.py!} @@ -65,7 +65,7 @@ FastAPI ะฑัƒะดะตั‚ ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ัั‚ะพั‚ ะฒะพะทะฒั€ะฐั‰ะฐะตะผั‹ะน ั‚ {!> ../../../docs_src/response_model/tutorial001_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="17 22 24-27" {!> ../../../docs_src/response_model/tutorial001.py!} @@ -101,7 +101,7 @@ FastAPI ะฑัƒะดะตั‚ ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะทะฝะฐั‡ะตะฝะธะต `response_model` ะด {!> ../../../docs_src/response_model/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9 11" {!> ../../../docs_src/response_model/tutorial002.py!} @@ -120,7 +120,7 @@ FastAPI ะฑัƒะดะตั‚ ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะทะฝะฐั‡ะตะฝะธะต `response_model` ะด {!> ../../../docs_src/response_model/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="18" {!> ../../../docs_src/response_model/tutorial002.py!} @@ -145,7 +145,7 @@ FastAPI ะฑัƒะดะตั‚ ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะทะฝะฐั‡ะตะฝะธะต `response_model` ะด {!> ../../../docs_src/response_model/tutorial003_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9 11 16" {!> ../../../docs_src/response_model/tutorial003.py!} @@ -159,7 +159,7 @@ FastAPI ะฑัƒะดะตั‚ ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะทะฝะฐั‡ะตะฝะธะต `response_model` ะด {!> ../../../docs_src/response_model/tutorial003_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="24" {!> ../../../docs_src/response_model/tutorial003.py!} @@ -173,7 +173,7 @@ FastAPI ะฑัƒะดะตั‚ ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะทะฝะฐั‡ะตะฝะธะต `response_model` ะด {!> ../../../docs_src/response_model/tutorial003_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="22" {!> ../../../docs_src/response_model/tutorial003.py!} @@ -207,7 +207,7 @@ FastAPI ะฑัƒะดะตั‚ ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะทะฝะฐั‡ะตะฝะธะต `response_model` ะด {!> ../../../docs_src/response_model/tutorial003_01_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9-13 15-16 20" {!> ../../../docs_src/response_model/tutorial003_01.py!} @@ -283,7 +283,7 @@ FastAPI ัะพะฒะผะตัั‚ะฝะพ ั Pydantic ะฒั‹ะฟะพะปะฝะธั‚ ะฝะตะบะพั‚ะพั€ัƒัŽ ะผะฐ {!> ../../../docs_src/response_model/tutorial003_04_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/response_model/tutorial003_04.py!} @@ -305,7 +305,7 @@ FastAPI ัะพะฒะผะตัั‚ะฝะพ ั Pydantic ะฒั‹ะฟะพะปะฝะธั‚ ะฝะตะบะพั‚ะพั€ัƒัŽ ะผะฐ {!> ../../../docs_src/response_model/tutorial003_05_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/response_model/tutorial003_05.py!} @@ -329,7 +329,7 @@ FastAPI ัะพะฒะผะตัั‚ะฝะพ ั Pydantic ะฒั‹ะฟะพะปะฝะธั‚ ะฝะตะบะพั‚ะพั€ัƒัŽ ะผะฐ {!> ../../../docs_src/response_model/tutorial004_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="11 13-14" {!> ../../../docs_src/response_model/tutorial004.py!} @@ -359,7 +359,7 @@ FastAPI ัะพะฒะผะตัั‚ะฝะพ ั Pydantic ะฒั‹ะฟะพะปะฝะธั‚ ะฝะตะบะพั‚ะพั€ัƒัŽ ะผะฐ {!> ../../../docs_src/response_model/tutorial004_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="24" {!> ../../../docs_src/response_model/tutorial004.py!} @@ -446,7 +446,7 @@ FastAPI ะดะพัั‚ะฐั‚ะพั‡ะฝะพ ัƒะผะตะฝ (ะฝะฐ ัะฐะผะพะผ ะดะตะปะต, ัั‚ะพ ะทะฐัะป {!> ../../../docs_src/response_model/tutorial005_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="31 37" {!> ../../../docs_src/response_model/tutorial005.py!} @@ -467,7 +467,7 @@ FastAPI ะดะพัั‚ะฐั‚ะพั‡ะฝะพ ัƒะผะตะฝ (ะฝะฐ ัะฐะผะพะผ ะดะตะปะต, ัั‚ะพ ะทะฐัะป {!> ../../../docs_src/response_model/tutorial006_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="31 37" {!> ../../../docs_src/response_model/tutorial006.py!} diff --git a/docs/ru/docs/tutorial/schema-extra-example.md b/docs/ru/docs/tutorial/schema-extra-example.md index a0363b9ba..a13ab5935 100644 --- a/docs/ru/docs/tutorial/schema-extra-example.md +++ b/docs/ru/docs/tutorial/schema-extra-example.md @@ -14,7 +14,7 @@ {!> ../../../docs_src/schema_extra_example/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="15-23" {!> ../../../docs_src/schema_extra_example/tutorial001.py!} @@ -39,7 +39,7 @@ {!> ../../../docs_src/schema_extra_example/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="4 10-13" {!> ../../../docs_src/schema_extra_example/tutorial002.py!} @@ -78,7 +78,7 @@ {!> ../../../docs_src/schema_extra_example/tutorial003_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="23-28" {!> ../../../docs_src/schema_extra_example/tutorial003_an.py!} @@ -93,7 +93,7 @@ {!> ../../../docs_src/schema_extra_example/tutorial003_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ะ—ะฐะผะตั‚ะบะฐ ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated`, ะตัะปะธ ัั‚ะพ ะฒะพะทะผะพะถะฝะพ. @@ -133,7 +133,7 @@ {!> ../../../docs_src/schema_extra_example/tutorial004_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="24-50" {!> ../../../docs_src/schema_extra_example/tutorial004_an.py!} @@ -148,7 +148,7 @@ {!> ../../../docs_src/schema_extra_example/tutorial004_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ะ—ะฐะผะตั‚ะบะฐ ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ะฒะตั€ัะธัŽ ั `Annotated`, ะตัะปะธ ัั‚ะพ ะฒะพะทะผะพะถะฝะพ. diff --git a/docs/ru/docs/tutorial/testing.md b/docs/ru/docs/tutorial/testing.md index 3f9005112..ca47a6f51 100644 --- a/docs/ru/docs/tutorial/testing.md +++ b/docs/ru/docs/tutorial/testing.md @@ -122,7 +122,7 @@ {!> ../../../docs_src/app_testing/app_b_an_py39/main.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python {!> ../../../docs_src/app_testing/app_b_an/main.py!} @@ -137,7 +137,7 @@ {!> ../../../docs_src/app_testing/app_b_py310/main.py!} ``` -=== "Python 3.6+ ะฑะตะท Annotated" +=== "Python 3.8+ ะฑะตะท Annotated" !!! tip "ะŸะพะดัะบะฐะทะบะฐ" ะŸะพ ะฒะพะทะผะพะถะฝะพัั‚ะธ ะธัะฟะพะปัŒะทัƒะนั‚ะต ะฒะตั€ัะธัŽ ั `Annotated`. diff --git a/docs/tr/docs/features.md b/docs/tr/docs/features.md index f8220fb58..8b143ffe7 100644 --- a/docs/tr/docs/features.md +++ b/docs/tr/docs/features.md @@ -27,7 +27,7 @@ OpenAPI standartlarฤฑna dayalฤฑ olan bir framework olarak, geliลŸtiricilerin bir ### Sadece modern Python -Tamamiyle standartlar **Python 3.6**'nฤฑn type hintlerine dayanฤฑyor (Pydantic'in sayesinde). Yeni bir syntax รถฤŸrenmene gerek yok. Sadece modern Python. +Tamamiyle standartlar **Python 3.8**'nฤฑn type hintlerine dayanฤฑyor (Pydantic'in sayesinde). Yeni bir syntax รถฤŸrenmene gerek yok. Sadece modern Python. EฤŸer Python type hintlerini bilmiyorsan veya bir hatฤฑrlatmaya ihtiyacฤฑn var ise(FastAPI kullanmasan bile) ลŸu iki dakikalฤฑk kรผรงรผk bilgilendirici iรงeriฤŸe bir gรถz at: [Python Types](python-types.md){.internal-link target=_blank}. diff --git a/docs/tr/docs/index.md b/docs/tr/docs/index.md index e74efbc2f..e61f5b82c 100644 --- a/docs/tr/docs/index.md +++ b/docs/tr/docs/index.md @@ -24,7 +24,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.8+'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: @@ -115,7 +115,7 @@ EฤŸer API yerine komut satฤฑrฤฑ uygulamasฤฑ ## Gereksinimler -Python 3.7+ +Python 3.8+ FastAPI iki devin omuzlarฤฑ รผstรผnde duruyor: @@ -331,7 +331,7 @@ Type-hinting iลŸlemini Python dilindeki standart veri tipleri ile yapabilirsin Yeni bir syntax'e alฤฑลŸmana gerek yok, metodlar ve classlar zaten spesifik kรผtรผphanelere ait. -Sadece standart **Python 3.6+**. +Sadece standart **Python 3.8+**. ร–rnek olarak, `int` tanฤฑmlamak iรงin: diff --git a/docs/uk/docs/python-types.md b/docs/uk/docs/python-types.md index f792e83a8..6c8e29016 100644 --- a/docs/uk/docs/python-types.md +++ b/docs/uk/docs/python-types.md @@ -164,7 +164,7 @@ John Doe ะะฐะฟั€ะธะบะปะฐะด, ะดะฐะฒะฐะนั‚ะต ะฒะธะทะฝะฐั‡ะธะผะพ ะทะผั–ะฝะฝัƒ, ัะบะฐ ะฑัƒะดะต `list` ั–ะท `str`. -=== "Python 3.6 ั– ะฒะธั‰ะต" +=== "Python 3.8 ั– ะฒะธั‰ะต" ะ— ะผะพะดัƒะปั `typing`, ั–ะผะฟะพั€ั‚ัƒั”ะผะพ `List` (ะท ะฒะตะปะธะบะพั— ะปั–ั‚ะตั€ะธ `L`): @@ -218,7 +218,7 @@ John Doe ะ’ะธ ะฟะพะฒะธะฝะฝั– ะทั€ะพะฑะธั‚ะธ ั‚ะต ะถ ัะฐะผะต, ั‰ะพะฑ ะพะณะพะปะพัะธั‚ะธ `tuple` ั– `set`: -=== "Python 3.6 ั– ะฒะธั‰ะต" +=== "Python 3.8 ั– ะฒะธั‰ะต" ```Python hl_lines="1 4" {!> ../../../docs_src/python_types/tutorial007.py!} @@ -243,7 +243,7 @@ John Doe ะ”ั€ัƒะณะธะน ะฟะฐั€ะฐะผะตั‚ั€ ั‚ะธะฟัƒ ะดะปั ะทะฝะฐั‡ะตะฝะฝั ัƒ `dict`: -=== "Python 3.6 ั– ะฒะธั‰ะต" +=== "Python 3.8 ั– ะฒะธั‰ะต" ```Python hl_lines="1 4" {!> ../../../docs_src/python_types/tutorial008.py!} @@ -269,7 +269,7 @@ John Doe ะฃ Python 3.10 ั‚ะฐะบะพะถ ั” **ะฐะปัŒั‚ะตั€ะฝะฐั‚ะธะฒะฝะธะน ัะธะฝั‚ะฐะบัะธั**, ัƒ ัะบะพะผัƒ ะฒะธ ะผะพะถะตั‚ะต ั€ะพะทะดั–ะปะธั‚ะธ ะผะพะถะปะธะฒั– ั‚ะธะฟะธ ะทะฐ ะดะพะฟะพะผะพะณะพัŽ ะฒะตั€ั‚ะธะบะฐะปัŒะฝะพั— ัะผัƒะณะธ (`|`). -=== "Python 3.6 ั– ะฒะธั‰ะต" +=== "Python 3.8 ั– ะฒะธั‰ะต" ```Python hl_lines="1 4" {!> ../../../docs_src/python_types/tutorial008b.py!} @@ -299,13 +299,13 @@ John Doe ะฆะต ั‚ะฐะบะพะถ ะพะทะฝะฐั‡ะฐั”, ั‰ะพ ะฒ Python 3.10 ะฒะธ ะผะพะถะตั‚ะต ะฒะธะบะพั€ะธัั‚ะพะฒัƒะฒะฐั‚ะธ `Something | None`: -=== "Python 3.6 ั– ะฒะธั‰ะต" +=== "Python 3.8 ั– ะฒะธั‰ะต" ```Python hl_lines="1 4" {!> ../../../docs_src/python_types/tutorial009.py!} ``` -=== "Python 3.6 ั– ะฒะธั‰ะต - ะฐะปัŒั‚ะตั€ะฝะฐั‚ะธะฒะฐ" +=== "Python 3.8 ั– ะฒะธั‰ะต - ะฐะปัŒั‚ะตั€ะฝะฐั‚ะธะฒะฐ" ```Python hl_lines="1 4" {!> ../../../docs_src/python_types/tutorial009b.py!} @@ -321,7 +321,7 @@ John Doe ะฆั– ั‚ะธะฟะธ, ัะบั– ะฟั€ะธะนะผะฐัŽั‚ัŒ ะฟะฐั€ะฐะผะตั‚ั€ะธ ั‚ะธะฟัƒ ัƒ ะบะฒะฐะดั€ะฐั‚ะฝะธั… ะดัƒะถะบะฐั…, ะฝะฐะทะธะฒะฐัŽั‚ัŒัั **Generic types** or **Generics**, ะฝะฐะฟั€ะธะบะปะฐะด: -=== "Python 3.6 ั– ะฒะธั‰ะต" +=== "Python 3.8 ั– ะฒะธั‰ะต" * `List` * `Tuple` @@ -340,7 +340,7 @@ John Doe * `set` * `dict` - ะ† ั‚ะต ัะฐะผะต, ั‰ะพ ะน ัƒ Python 3.6, ั–ะท ะผะพะดัƒะปั `typing`: + ะ† ั‚ะต ัะฐะผะต, ั‰ะพ ะน ัƒ Python 3.8, ั–ะท ะผะพะดัƒะปั `typing`: * `Union` * `Optional` @@ -355,10 +355,10 @@ John Doe * `set` * `dict` - ะ† ั‚ะต ัะฐะผะต, ั‰ะพ ะน ัƒ Python 3.6, ั–ะท ะผะพะดัƒะปั `typing`: + ะ† ั‚ะต ัะฐะผะต, ั‰ะพ ะน ัƒ Python 3.8, ั–ะท ะผะพะดัƒะปั `typing`: * `Union` - * `Optional` (ั‚ะฐะบ ัะฐะผะพ ัะบ ัƒ Python 3.6) + * `Optional` (ั‚ะฐะบ ัะฐะผะพ ัะบ ัƒ Python 3.8) * ...ั‚ะฐ ั–ะฝัˆั–. ะฃ Python 3.10, ัะบ ะฐะปัŒั‚ะตั€ะฝะฐั‚ะธะฒะฐ ะฒะธะบะพั€ะธัั‚ะฐะฝะฝัŽ `Union` ั‚ะฐ `Optional`, ะฒะธ ะผะพะถะตั‚ะต ะฒะธะบะพั€ะธัั‚ะพะฒัƒะฒะฐั‚ะธ ะฒะตั€ั‚ะธะบะฐะปัŒะฝัƒ ัะผัƒะณัƒ (`|`) ั‰ะพะฑ ะพะณะพะปะพัะธั‚ะธ ะพะฑ'ั”ะดะฝะฐะฝะฝั ั‚ะธะฟั–ะฒ. @@ -397,7 +397,7 @@ John Doe ะŸั€ะธะบะปะฐะด ะท ะดะพะบัƒะผะตะฝั‚ะฐั†ั–ั— Pydantic: -=== "Python 3.6 ั– ะฒะธั‰ะต" +=== "Python 3.8 ั– ะฒะธั‰ะต" ```Python {!> ../../../docs_src/python_types/tutorial011.py!} diff --git a/docs/uk/docs/tutorial/body.md b/docs/uk/docs/tutorial/body.md index e78c5de0e..9759e7f45 100644 --- a/docs/uk/docs/tutorial/body.md +++ b/docs/uk/docs/tutorial/body.md @@ -19,7 +19,7 @@ ะกะฟะพั‡ะฐั‚ะบัƒ ะฒะฐะผ ะฟะพั‚ั€ั–ะฑะฝะพ ั–ะผะฟะพั€ั‚ัƒะฒะฐั‚ะธ `BaseModel` ะท `pydantic`: -=== "Python 3.6 ั– ะฒะธั‰ะต" +=== "Python 3.8 ั– ะฒะธั‰ะต" ```Python hl_lines="4" {!> ../../../docs_src/body/tutorial001.py!} @@ -37,7 +37,7 @@ ะ’ะธะบะพั€ะธัั‚ะพะฒัƒะนั‚ะต ัั‚ะฐะฝะดะฐั€ั‚ะฝั– ั‚ะธะฟะธ Python ะดะปั ะฒัั–ั… ะฐั‚ั€ะธะฑัƒั‚ั–ะฒ: -=== "Python 3.6 ั– ะฒะธั‰ะต" +=== "Python 3.8 ั– ะฒะธั‰ะต" ```Python hl_lines="7-11" {!> ../../../docs_src/body/tutorial001.py!} @@ -75,7 +75,7 @@ ะฉะพะฑ ะดะพะดะฐั‚ะธ ะผะพะดะตะปัŒ ะดะฐะฝะธั… ะดะพ ะฒะฐัˆะพั— *ะพะฟะตั€ะฐั†ั–ั— ัˆะปัั…ัƒ*, ะพะณะพะปะพัั–ั‚ัŒ ั—ั— ั‚ะฐะบ ัะฐะผะพ, ัะบ ะฒะธ ะพะณะพะปะพัะธะปะธ ะฟะฐั€ะฐะผะตั‚ั€ะธ ัˆะปัั…ัƒ ั‚ะฐ ะทะฐะฟะธั‚ัƒ: -=== "Python 3.6 ั– ะฒะธั‰ะต" +=== "Python 3.8 ั– ะฒะธั‰ะต" ```Python hl_lines="18" {!> ../../../docs_src/body/tutorial001.py!} @@ -149,7 +149,7 @@ ะฃัะตั€ะตะดะธะฝั– ั„ัƒะฝะบั†ั–ั— ะฒะธ ะผะพะถะตั‚ะต ะพั‚ั€ะธะผะฐั‚ะธ ะฟั€ัะผะธะน ะดะพัั‚ัƒะฟ ะดะพ ะฒัั–ั… ะฐั‚ั€ะธะฑัƒั‚ั–ะฒ ะพะฑโ€™ั”ะบั‚ะฐ ะผะพะดะตะปั–: -=== "Python 3.6 ั– ะฒะธั‰ะต" +=== "Python 3.8 ั– ะฒะธั‰ะต" ```Python hl_lines="21" {!> ../../../docs_src/body/tutorial002.py!} @@ -167,7 +167,7 @@ **FastAPI** ั€ะพะทะฟั–ะทะฝะฐั”, ั‰ะพ ะฟะฐั€ะฐะผะตั‚ั€ะธ ั„ัƒะฝะบั†ั–ั—, ัะบั– ะฒั–ะดะฟะพะฒั–ะดะฐัŽั‚ัŒ ะฟะฐั€ะฐะผะตั‚ั€ะฐะผ ัˆะปัั…ัƒ, ะผะฐัŽั‚ัŒ ะฑัƒั‚ะธ **ะฒะทัั‚ั– ะท ัˆะปัั…ัƒ**, ะฐ ะฟะฐั€ะฐะผะตั‚ั€ะธ ั„ัƒะฝะบั†ั–ั—, ัะบั– ะพะณะพะปะพัˆัƒัŽั‚ัŒัั ัะบ ะผะพะดะตะปั– Pydantic, **ะฒะทัั‚ั– ะท ั‚ั–ะปะฐ ะทะฐะฟะธั‚ัƒ**. -=== "Python 3.6 ั– ะฒะธั‰ะต" +=== "Python 3.8 ั– ะฒะธั‰ะต" ```Python hl_lines="17-18" {!> ../../../docs_src/body/tutorial003.py!} @@ -185,7 +185,7 @@ **FastAPI** ั€ะพะทะฟั–ะทะฝะฐั” ะบะพะถะตะฝ ะท ะฝะธั… ั– ะฒั–ะทัŒะผะต ะดะฐะฝั– ะท ะฟะพั‚ั€ั–ะฑะฝะพะณะพ ะผั–ัั†ั. -=== "Python 3.6 ั– ะฒะธั‰ะต" +=== "Python 3.8 ั– ะฒะธั‰ะต" ```Python hl_lines="18" {!> ../../../docs_src/body/tutorial004.py!} diff --git a/docs/uk/docs/tutorial/cookie-params.md b/docs/uk/docs/tutorial/cookie-params.md index 2b0e8993c..199b93839 100644 --- a/docs/uk/docs/tutorial/cookie-params.md +++ b/docs/uk/docs/tutorial/cookie-params.md @@ -18,7 +18,7 @@ {!> ../../../docs_src/cookie_params/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="3" {!> ../../../docs_src/cookie_params/tutorial001_an.py!} @@ -33,7 +33,7 @@ {!> ../../../docs_src/cookie_params/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ะ‘ะฐะถะฐะฝะพ ะฒะธะบะพั€ะธัั‚ะพะฒัƒะฒะฐั‚ะธ `Annotated` ะฒะตั€ัั–ัŽ, ัะบั‰ะพ ั†ะต ะผะพะถะปะธะฒะพ. @@ -60,7 +60,7 @@ {!> ../../../docs_src/cookie_params/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/cookie_params/tutorial001_an.py!} @@ -75,7 +75,7 @@ {!> ../../../docs_src/cookie_params/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ะ‘ะฐะถะฐะฝะพ ะฒะธะบะพั€ะธัั‚ะพะฒัƒะฒะฐั‚ะธ `Annotated` ะฒะตั€ัั–ัŽ, ัะบั‰ะพ ั†ะต ะผะพะถะปะธะฒะพ. diff --git a/docs/uk/docs/tutorial/encoder.md b/docs/uk/docs/tutorial/encoder.md index d660447b4..b6583341f 100644 --- a/docs/uk/docs/tutorial/encoder.md +++ b/docs/uk/docs/tutorial/encoder.md @@ -26,7 +26,7 @@ {!> ../../../docs_src/encoder/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="5 22" {!> ../../../docs_src/encoder/tutorial001.py!} diff --git a/docs/uk/docs/tutorial/extra-data-types.md b/docs/uk/docs/tutorial/extra-data-types.md index ba75ee627..ec5ec0d18 100644 --- a/docs/uk/docs/tutorial/extra-data-types.md +++ b/docs/uk/docs/tutorial/extra-data-types.md @@ -67,7 +67,7 @@ {!> ../../../docs_src/extra_data_types/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 3 13-17" {!> ../../../docs_src/extra_data_types/tutorial001_an.py!} @@ -82,7 +82,7 @@ {!> ../../../docs_src/extra_data_types/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ะ‘ะฐะถะฐะฝะพ ะฒะธะบะพั€ะธัั‚ะพะฒัƒะฒะฐั‚ะธ `Annotated` ะฒะตั€ัั–ัŽ, ัะบั‰ะพ ั†ะต ะผะพะถะปะธะฒะพ. @@ -105,7 +105,7 @@ {!> ../../../docs_src/extra_data_types/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="19-20" {!> ../../../docs_src/extra_data_types/tutorial001_an.py!} @@ -120,7 +120,7 @@ {!> ../../../docs_src/extra_data_types/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ะ‘ะฐะถะฐะฝะพ ะฒะธะบะพั€ะธัั‚ะพะฒัƒะฒะฐั‚ะธ `Annotated` ะฒะตั€ัั–ัŽ, ัะบั‰ะพ ั†ะต ะผะพะถะปะธะฒะพ. diff --git a/docs/vi/docs/features.md b/docs/vi/docs/features.md index 0599530e8..306aeb359 100644 --- a/docs/vi/docs/features.md +++ b/docs/vi/docs/features.md @@ -26,7 +26,7 @@ Tร i liแป‡u tฦฐฦกng tรกc API vร  web giao diแป‡n ngฦฐแปi dรนng. Lร  mแป™t frame ### Chแป‰ cแบงn phiรชn bแบฃn Python hiแป‡n ฤ‘แบกi -Tแบฅt cแบฃ ฤ‘ฦฐแปฃc dแปฑa trรชn khai bรกo kiแปƒu dแปฏ liแป‡u chuแบฉn cแปงa **Python 3.6** (cแบฃm ฦกn Pydantic). Bแบกn khรดng cแบงn hแปc cรบ phรกp mแป›i, chแป‰ cแบงn biแบฟt chuแบฉn Python hiแป‡n ฤ‘แบกi. +Tแบฅt cแบฃ ฤ‘ฦฐแปฃc dแปฑa trรชn khai bรกo kiแปƒu dแปฏ liแป‡u chuแบฉn cแปงa **Python 3.8** (cแบฃm ฦกn Pydantic). Bแบกn khรดng cแบงn hแปc cรบ phรกp mแป›i, chแป‰ cแบงn biแบฟt chuแบฉn Python hiแป‡n ฤ‘แบกi. Nแบฟu bแบกn cแบงn 2 phรบt ฤ‘แปƒ lร m mแป›i lแบกi cรกch sแปญ dแปฅng cรกc kiแปƒu dแปฏ liแป‡u mแป›i cแปงa Python (thแบญm chรญ nแบฟu bแบกn khรดng sแปญ dแปฅng FastAPI), xem hฦฐแป›ng dแบซn ngแบฏn: [Kiแปƒu dแปฏ liแป‡u Python](python-types.md){.internal-link target=_blank}. diff --git a/docs/vi/docs/index.md b/docs/vi/docs/index.md index 0e773a011..3f416dbec 100644 --- a/docs/vi/docs/index.md +++ b/docs/vi/docs/index.md @@ -27,7 +27,7 @@ --- -FastAPI lร  mแป™t web framework hiแป‡n ฤ‘แบกi, hiแป‡u nฤƒng cao ฤ‘แปƒ xรขy dแปฑng web APIs vแป›i Python 3.7+ dแปฑa trรชn tiรชu chuแบฉn Python type hints. +FastAPI lร  mแป™t web framework hiแป‡n ฤ‘แบกi, hiแป‡u nฤƒng cao ฤ‘แปƒ xรขy dแปฑng web APIs vแป›i Python 3.8+ dแปฑa trรชn tiรชu chuแบฉn Python type hints. Nhแปฏng tรญnh nฤƒng nhฦฐ: @@ -116,7 +116,7 @@ Nแบฟu bแบกn ฤ‘ang xรขy dแปฑng mแป™t CLI ../../../docs_src/python_types/tutorial006_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" Tแปซ `typing`, import `List` (vแป›i chแปฏ cรกi `L` viแบฟt hoa): @@ -230,7 +230,7 @@ Bแบกn sแบฝ lร m ฤ‘iแปu tฦฐฦกng tแปฑ ฤ‘แปƒ khai bรกo cรกc `tuple` vร  cรกc `set {!> ../../../docs_src/python_types/tutorial007_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 4" {!> ../../../docs_src/python_types/tutorial007.py!} @@ -255,7 +255,7 @@ Tham sแป‘ kiแปƒu dแปฏ liแป‡u thแปฉ hai dร nh cho giรก trแป‹ cแปงa `dict`. {!> ../../../docs_src/python_types/tutorial008_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 4" {!> ../../../docs_src/python_types/tutorial008.py!} @@ -284,7 +284,7 @@ Trong Python 3.10 cลฉng cรณ mแป™t **cรบ phรกp mแป›i** mร  bแบกn cรณ thแปƒ ฤ‘แบทt {!> ../../../docs_src/python_types/tutorial008b_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 4" {!> ../../../docs_src/python_types/tutorial008b.py!} @@ -314,13 +314,13 @@ Sแปญ dแปฅng `Optional[str]` thay cho `str` sแบฝ cho phรฉp trรฌnh soแบกn thแบฃo g {!> ../../../docs_src/python_types/tutorial009_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 4" {!> ../../../docs_src/python_types/tutorial009.py!} ``` -=== "Python 3.6+ alternative" +=== "Python 3.8+ alternative" ```Python hl_lines="1 4" {!> ../../../docs_src/python_types/tutorial009b.py!} @@ -404,7 +404,7 @@ Nhแปฏng kiแปƒu dแปฏ liแป‡u nร y lแบฅy tham sแป‘ kiแปƒu dแปฏ liแป‡u trong dแบฅu n * `Optional` * ...and others. -=== "Python 3.6+" +=== "Python 3.8+" * `List` * `Tuple` @@ -464,7 +464,7 @@ Mแป™t vรญ dแปฅ tแปซ tร i liแป‡u chรญnh thแปฉc cแปงa Pydantic: {!> ../../../docs_src/python_types/tutorial011_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python {!> ../../../docs_src/python_types/tutorial011.py!} @@ -493,7 +493,7 @@ Python cลฉng cรณ mแป™t tรญnh nฤƒng cho phรฉp ฤ‘แบทt **metadata bแป• sung** trong {!> ../../../docs_src/python_types/tutorial013_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" แปž phiรชn bแบฃn dฦฐแป›i Python 3.9, bแบกn import `Annotated` tแปซ `typing_extensions`. diff --git a/docs/yo/docs/index.md b/docs/yo/docs/index.md index ca75a6b13..101e13b6b 100644 --- a/docs/yo/docs/index.md +++ b/docs/yo/docs/index.md @@ -27,7 +27,7 @@ --- -FastAPI jแบนฬ รฌgbร lรณdรฉ, tรญ รณ yรกra (iแนฃแบน-giga), รฌlร nร  wแบนฬแบนฬbรน fรบn kikแป ร wแปn API pแบนฬ€lรบ Python 3.7+ รจyรญ tรญ รณ da lori ร wแปn รฌtแปฬkasรญ ร mรฌ irรบfแบนฬ Python. +FastAPI jแบนฬ รฌgbร lรณdรฉ, tรญ รณ yรกra (iแนฃแบน-giga), รฌlร nร  wแบนฬแบนฬbรน fรบn kikแป ร wแปn API pแบนฬ€lรบ Python 3.8+ รจyรญ tรญ รณ da lori ร wแปn รฌtแปฬkasรญ ร mรฌ irรบfแบนฬ Python. ร€wแปn แบนya pร tร kรฌ ni: @@ -115,7 +115,7 @@ Ti o ba n kแป ohun รจlรฒ CLI lรกti ## รˆrรฒjร  -Python 3.7+ +Python 3.8+ FastAPI dรบrรณ lรณrรญ ร wแปn รจjรฌkรก tรญ ร wแปn รฒmรญrร n: @@ -331,7 +331,7 @@ O แนฃe รฌyแบนn pแบนฬ€lรบ irรบfแบนฬ ร mรฌ รฌtแปฬkasรญ รฌgbร lรณdรฉ Python. O รฒ nรญlรฒ lรกti kแปฬ sรญล„tรกร sรฌ tuntun, รฌlร nร  tร bรญ แปฬ€wแปฬ kรญlรกร sรฌ kan pร tรณ, abbl (i.e. ร ti bแบนbแบน lแป). -รŒtแปฬkasรญ **Python 3.7+** +รŒtแปฬkasรญ **Python 3.8+** Fรบn ร pแบนแบนrแบน, fรบn `int`: diff --git a/docs/zh/docs/advanced/generate-clients.md b/docs/zh/docs/advanced/generate-clients.md index f3a58c062..e222e479c 100644 --- a/docs/zh/docs/advanced/generate-clients.md +++ b/docs/zh/docs/advanced/generate-clients.md @@ -22,7 +22,7 @@ {!> ../../../docs_src/generate_clients/tutorial001_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9-11 14-15 18 19 23" {!> ../../../docs_src/generate_clients/tutorial001.py!} @@ -134,7 +134,7 @@ frontend-app@1.0.0 generate-client /home/user/code/frontend-app {!> ../../../docs_src/generate_clients/tutorial002_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="23 28 36" {!> ../../../docs_src/generate_clients/tutorial002.py!} @@ -191,7 +191,7 @@ FastAPIไธบๆฏไธช*่ทฏๅพ„ๆ“ไฝœ*ไฝฟ็”จไธ€ไธช**ๅ”ฏไธ€ID**๏ผŒๅฎƒ็”จไบŽ**ๆ“ไฝœID** {!> ../../../docs_src/generate_clients/tutorial003_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="8-9 12" {!> ../../../docs_src/generate_clients/tutorial003.py!} diff --git a/docs/zh/docs/advanced/settings.md b/docs/zh/docs/advanced/settings.md index 597e99a77..7f718acef 100644 --- a/docs/zh/docs/advanced/settings.md +++ b/docs/zh/docs/advanced/settings.md @@ -223,13 +223,13 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp"uvicorn main:app {!> ../../../docs_src/settings/app02_an_py39/main.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="6 12-13" {!> ../../../docs_src/settings/app02_an/main.py!} ``` -=== "Python 3.6+ ้žๆณจ่งฃ็‰ˆๆœฌ" +=== "Python 3.8+ ้žๆณจ่งฃ็‰ˆๆœฌ" !!! tip ๅฆ‚ๆžœๅฏ่ƒฝ๏ผŒ่ฏทๅฐฝ้‡ไฝฟ็”จ `Annotated` ็‰ˆๆœฌใ€‚ @@ -251,13 +251,13 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp"uvicorn main:app {!> ../../../docs_src/settings/app02_an_py39/main.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="17 19-21" {!> ../../../docs_src/settings/app02_an/main.py!} ``` -=== "Python 3.6+ ้žๆณจ่งฃ็‰ˆๆœฌ" +=== "Python 3.8+ ้žๆณจ่งฃ็‰ˆๆœฌ" !!! tip ๅฆ‚ๆžœๅฏ่ƒฝ๏ผŒ่ฏทๅฐฝ้‡ไฝฟ็”จ `Annotated` ็‰ˆๆœฌใ€‚ @@ -345,13 +345,13 @@ def get_settings(): {!> ../../../docs_src/settings/app03_an_py39/main.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 11" {!> ../../../docs_src/settings/app03_an/main.py!} ``` -=== "Python 3.6+ ้žๆณจ่งฃ็‰ˆๆœฌ" +=== "Python 3.8+ ้žๆณจ่งฃ็‰ˆๆœฌ" !!! tip ๅฆ‚ๆžœๅฏ่ƒฝ๏ผŒ่ฏทๅฐฝ้‡ไฝฟ็”จ `Annotated` ็‰ˆๆœฌใ€‚ diff --git a/docs/zh/docs/advanced/websockets.md b/docs/zh/docs/advanced/websockets.md index a723487fd..a5cbdd965 100644 --- a/docs/zh/docs/advanced/websockets.md +++ b/docs/zh/docs/advanced/websockets.md @@ -118,7 +118,7 @@ $ uvicorn main:app --reload {!> ../../../docs_src/websockets/tutorial002_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="69-70 83" {!> ../../../docs_src/websockets/tutorial002_an.py!} @@ -133,7 +133,7 @@ $ uvicorn main:app --reload {!> ../../../docs_src/websockets/tutorial002_py310.py!} ``` -=== "Python 3.6+ ้žๅธฆๆณจ่งฃ็‰ˆๆœฌ" +=== "Python 3.8+ ้žๅธฆๆณจ่งฃ็‰ˆๆœฌ" !!! tip ๅฆ‚ๆžœๅฏ่ƒฝ๏ผŒ่ฏทๅฐฝ้‡ไฝฟ็”จ `Annotated` ็‰ˆๆœฌใ€‚ @@ -181,7 +181,7 @@ $ uvicorn main:app --reload {!> ../../../docs_src/websockets/tutorial003_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="81-83" {!> ../../../docs_src/websockets/tutorial003.py!} diff --git a/docs/zh/docs/index.md b/docs/zh/docs/index.md index 1de2a8d36..d776e5813 100644 --- a/docs/zh/docs/index.md +++ b/docs/zh/docs/index.md @@ -24,7 +24,7 @@ --- -FastAPI ๆ˜ฏไธ€ไธช็”จไบŽๆž„ๅปบ API ็š„็Žฐไปฃใ€ๅฟซ้€Ÿ๏ผˆ้ซ˜ๆ€ง่ƒฝ๏ผ‰็š„ web ๆก†ๆžถ๏ผŒไฝฟ็”จ Python 3.6+ ๅนถๅŸบไบŽๆ ‡ๅ‡†็š„ Python ็ฑปๅž‹ๆ็คบใ€‚ +FastAPI ๆ˜ฏไธ€ไธช็”จไบŽๆž„ๅปบ API ็š„็Žฐไปฃใ€ๅฟซ้€Ÿ๏ผˆ้ซ˜ๆ€ง่ƒฝ๏ผ‰็š„ web ๆก†ๆžถ๏ผŒไฝฟ็”จ Python 3.8+ ๅนถๅŸบไบŽๆ ‡ๅ‡†็š„ Python ็ฑปๅž‹ๆ็คบใ€‚ ๅ…ณ้”ฎ็‰นๆ€ง: @@ -107,7 +107,7 @@ FastAPI ๆ˜ฏไธ€ไธช็”จไบŽๆž„ๅปบ API ็š„็Žฐไปฃใ€ๅฟซ้€Ÿ๏ผˆ้ซ˜ๆ€ง่ƒฝ๏ผ‰็š„ web ๆก† ## ไพ่ต– -Python 3.6 ๅŠๆ›ด้ซ˜็‰ˆๆœฌ +Python 3.8 ๅŠๆ›ด้ซ˜็‰ˆๆœฌ FastAPI ็ซ™ๅœจไปฅไธ‹ๅทจไบบ็š„่‚ฉ่†€ไน‹ไธŠ๏ผš @@ -323,7 +323,7 @@ def update_item(item_id: int, item: Item): ไฝ ไธ้œ€่ฆๅŽปๅญฆไน ๆ–ฐ็š„่ฏญๆณ•ใ€ไบ†่งฃ็‰นๅฎšๅบ“็š„ๆ–นๆณ•ๆˆ–็ฑป๏ผŒ็ญ‰็ญ‰ใ€‚ -ๅช้œ€่ฆไฝฟ็”จๆ ‡ๅ‡†็š„ **Python 3.6 ๅŠๆ›ด้ซ˜็‰ˆๆœฌ**ใ€‚ +ๅช้œ€่ฆไฝฟ็”จๆ ‡ๅ‡†็š„ **Python 3.8 ๅŠๆ›ด้ซ˜็‰ˆๆœฌ**ใ€‚ ไธพไธชไพ‹ๅญ๏ผŒๆฏ”ๅฆ‚ๅฃฐๆ˜Ž `int` ็ฑปๅž‹๏ผš diff --git a/docs/zh/docs/tutorial/background-tasks.md b/docs/zh/docs/tutorial/background-tasks.md index c8568298b..94b75d4fd 100644 --- a/docs/zh/docs/tutorial/background-tasks.md +++ b/docs/zh/docs/tutorial/background-tasks.md @@ -69,7 +69,7 @@ {!> ../../../docs_src/background_tasks/tutorial002_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="14 16 23 26" {!> ../../../docs_src/background_tasks/tutorial002_an.py!} @@ -84,7 +84,7 @@ {!> ../../../docs_src/background_tasks/tutorial002_py310.py!} ``` -=== "Python 3.6+ ๆฒกAnnotated" +=== "Python 3.8+ ๆฒกAnnotated" !!! tip ๅฐฝๅฏ่ƒฝ้€‰ๆ‹ฉไฝฟ็”จ `Annotated` ็š„็‰ˆๆœฌใ€‚ diff --git a/docs/zh/docs/tutorial/body-fields.md b/docs/zh/docs/tutorial/body-fields.md index c153784dc..fb6c6d9b6 100644 --- a/docs/zh/docs/tutorial/body-fields.md +++ b/docs/zh/docs/tutorial/body-fields.md @@ -18,7 +18,7 @@ {!> ../../../docs_src/body_fields/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="4" {!> ../../../docs_src/body_fields/tutorial001_an.py!} @@ -33,7 +33,7 @@ {!> ../../../docs_src/body_fields/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ๅฐฝๅฏ่ƒฝ้€‰ๆ‹ฉไฝฟ็”จ `Annotated` ็š„็‰ˆๆœฌใ€‚ @@ -61,7 +61,7 @@ {!> ../../../docs_src/body_fields/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="12-15" {!> ../../../docs_src/body_fields/tutorial001_an.py!} @@ -76,7 +76,7 @@ {!> ../../../docs_src/body_fields/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/docs/zh/docs/tutorial/body-multiple-params.md b/docs/zh/docs/tutorial/body-multiple-params.md index ee2cba6df..c93ef2f5c 100644 --- a/docs/zh/docs/tutorial/body-multiple-params.md +++ b/docs/zh/docs/tutorial/body-multiple-params.md @@ -20,7 +20,7 @@ {!> ../../../docs_src/body_multiple_params/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="19-21" {!> ../../../docs_src/body_multiple_params/tutorial001_an.py!} @@ -35,7 +35,7 @@ {!> ../../../docs_src/body_multiple_params/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ๅฐฝๅฏ่ƒฝ้€‰ๆ‹ฉไฝฟ็”จ `Annotated` ็š„็‰ˆๆœฌใ€‚ @@ -68,7 +68,7 @@ {!> ../../../docs_src/body_multiple_params/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="22" {!> ../../../docs_src/body_multiple_params/tutorial002.py!} @@ -124,7 +124,7 @@ {!> ../../../docs_src/body_multiple_params/tutorial003_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="24" {!> ../../../docs_src/body_multiple_params/tutorial003_an.py!} @@ -139,7 +139,7 @@ {!> ../../../docs_src/body_multiple_params/tutorial003_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ๅฐฝๅฏ่ƒฝ้€‰ๆ‹ฉไฝฟ็”จ `Annotated` ็š„็‰ˆๆœฌใ€‚ @@ -193,7 +193,7 @@ q: str = None {!> ../../../docs_src/body_multiple_params/tutorial004_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="28" {!> ../../../docs_src/body_multiple_params/tutorial004_an.py!} @@ -208,7 +208,7 @@ q: str = None {!> ../../../docs_src/body_multiple_params/tutorial004_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ๅฐฝๅฏ่ƒฝ้€‰ๆ‹ฉไฝฟ็”จ `Annotated` ็š„็‰ˆๆœฌใ€‚ @@ -247,7 +247,7 @@ item: Item = Body(embed=True) {!> ../../../docs_src/body_multiple_params/tutorial005_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="18" {!> ../../../docs_src/body_multiple_params/tutorial005_an.py!} @@ -262,7 +262,7 @@ item: Item = Body(embed=True) {!> ../../../docs_src/body_multiple_params/tutorial005_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ๅฐฝๅฏ่ƒฝ้€‰ๆ‹ฉไฝฟ็”จ `Annotated` ็š„็‰ˆๆœฌใ€‚ diff --git a/docs/zh/docs/tutorial/body-nested-models.md b/docs/zh/docs/tutorial/body-nested-models.md index 7704d2624..c65308bef 100644 --- a/docs/zh/docs/tutorial/body-nested-models.md +++ b/docs/zh/docs/tutorial/body-nested-models.md @@ -12,7 +12,7 @@ {!> ../../../docs_src/body_nested_models/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="14" {!> ../../../docs_src/body_nested_models/tutorial001.py!} @@ -63,7 +63,7 @@ my_list: List[str] {!> ../../../docs_src/body_nested_models/tutorial002_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="14" {!> ../../../docs_src/body_nested_models/tutorial002.py!} @@ -89,7 +89,7 @@ Python ๅ…ทๆœ‰ไธ€็ง็‰นๆฎŠ็š„ๆ•ฐๆฎ็ฑปๅž‹ๆฅไฟๅญ˜ไธ€็ป„ๅ”ฏไธ€็š„ๅ…ƒ็ด ๏ผŒๅณ `se {!> ../../../docs_src/body_nested_models/tutorial003_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 14" {!> ../../../docs_src/body_nested_models/tutorial003.py!} @@ -127,7 +127,7 @@ Pydantic ๆจกๅž‹็š„ๆฏไธชๅฑžๆ€ง้ƒฝๅ…ทๆœ‰็ฑปๅž‹ใ€‚ {!> ../../../docs_src/body_nested_models/tutorial004_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9-11" {!> ../../../docs_src/body_nested_models/tutorial004.py!} @@ -149,7 +149,7 @@ Pydantic ๆจกๅž‹็š„ๆฏไธชๅฑžๆ€ง้ƒฝๅ…ทๆœ‰็ฑปๅž‹ใ€‚ {!> ../../../docs_src/body_nested_models/tutorial004_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="20" {!> ../../../docs_src/body_nested_models/tutorial004.py!} @@ -198,7 +198,7 @@ Pydantic ๆจกๅž‹็š„ๆฏไธชๅฑžๆ€ง้ƒฝๅ…ทๆœ‰็ฑปๅž‹ใ€‚ {!> ../../../docs_src/body_nested_models/tutorial005_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="4 10" {!> ../../../docs_src/body_nested_models/tutorial005.py!} @@ -222,7 +222,7 @@ Pydantic ๆจกๅž‹็š„ๆฏไธชๅฑžๆ€ง้ƒฝๅ…ทๆœ‰็ฑปๅž‹ใ€‚ {!> ../../../docs_src/body_nested_models/tutorial006_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="20" {!> ../../../docs_src/body_nested_models/tutorial006.py!} @@ -273,7 +273,7 @@ Pydantic ๆจกๅž‹็š„ๆฏไธชๅฑžๆ€ง้ƒฝๅ…ทๆœ‰็ฑปๅž‹ใ€‚ {!> ../../../docs_src/body_nested_models/tutorial007_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9 14 20 23 27" {!> ../../../docs_src/body_nested_models/tutorial007.py!} @@ -298,7 +298,7 @@ images: List[Image] {!> ../../../docs_src/body_nested_models/tutorial008_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="15" {!> ../../../docs_src/body_nested_models/tutorial008.py!} @@ -338,7 +338,7 @@ images: List[Image] {!> ../../../docs_src/body_nested_models/tutorial009_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/body_nested_models/tutorial009.py!} diff --git a/docs/zh/docs/tutorial/body.md b/docs/zh/docs/tutorial/body.md index d00c96dc3..5cf53c0c2 100644 --- a/docs/zh/docs/tutorial/body.md +++ b/docs/zh/docs/tutorial/body.md @@ -23,7 +23,7 @@ {!> ../../../docs_src/body/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="4" {!> ../../../docs_src/body/tutorial001.py!} @@ -41,7 +41,7 @@ {!> ../../../docs_src/body/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="7-11" {!> ../../../docs_src/body/tutorial001.py!} @@ -79,7 +79,7 @@ {!> ../../../docs_src/body/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="18" {!> ../../../docs_src/body/tutorial001.py!} @@ -142,7 +142,7 @@ Pydantic ๆœฌ่บซ็”š่‡ณไนŸ่ฟ›่กŒไบ†ไธ€ไบ›ๆ›ดๆ”นไปฅๆ”ฏๆŒๆญคๅŠŸ่ƒฝใ€‚ {!> ../../../docs_src/body/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="21" {!> ../../../docs_src/body/tutorial002.py!} @@ -160,7 +160,7 @@ Pydantic ๆœฌ่บซ็”š่‡ณไนŸ่ฟ›่กŒไบ†ไธ€ไบ›ๆ›ดๆ”นไปฅๆ”ฏๆŒๆญคๅŠŸ่ƒฝใ€‚ {!> ../../../docs_src/body/tutorial003_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="17-18" {!> ../../../docs_src/body/tutorial003.py!} @@ -178,7 +178,7 @@ Pydantic ๆœฌ่บซ็”š่‡ณไนŸ่ฟ›่กŒไบ†ไธ€ไบ›ๆ›ดๆ”นไปฅๆ”ฏๆŒๆญคๅŠŸ่ƒฝใ€‚ {!> ../../../docs_src/body/tutorial004_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="18" {!> ../../../docs_src/body/tutorial004.py!} diff --git a/docs/zh/docs/tutorial/cookie-params.md b/docs/zh/docs/tutorial/cookie-params.md index 470fd8e82..f115f9677 100644 --- a/docs/zh/docs/tutorial/cookie-params.md +++ b/docs/zh/docs/tutorial/cookie-params.md @@ -18,7 +18,7 @@ {!> ../../../docs_src/cookie_params/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="3" {!> ../../../docs_src/cookie_params/tutorial001_an.py!} @@ -33,7 +33,7 @@ {!> ../../../docs_src/cookie_params/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ๅฐฝๅฏ่ƒฝ้€‰ๆ‹ฉไฝฟ็”จ `Annotated` ็š„็‰ˆๆœฌใ€‚ @@ -61,7 +61,7 @@ {!> ../../../docs_src/cookie_params/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/cookie_params/tutorial001_an.py!} @@ -76,7 +76,7 @@ {!> ../../../docs_src/cookie_params/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ๅฐฝๅฏ่ƒฝ้€‰ๆ‹ฉไฝฟ็”จ `Annotated` ็š„็‰ˆๆœฌใ€‚ diff --git a/docs/zh/docs/tutorial/dependencies/classes-as-dependencies.md b/docs/zh/docs/tutorial/dependencies/classes-as-dependencies.md index f404820df..1866da298 100644 --- a/docs/zh/docs/tutorial/dependencies/classes-as-dependencies.md +++ b/docs/zh/docs/tutorial/dependencies/classes-as-dependencies.md @@ -12,7 +12,7 @@ {!> ../../../docs_src/dependencies/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/dependencies/tutorial001.py!} @@ -85,7 +85,7 @@ fluffy = Cat(name="Mr Fluffy") {!> ../../../docs_src/dependencies/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="11-15" {!> ../../../docs_src/dependencies/tutorial002.py!} diff --git a/docs/zh/docs/tutorial/encoder.md b/docs/zh/docs/tutorial/encoder.md index 76ed846ce..859ebc2e8 100644 --- a/docs/zh/docs/tutorial/encoder.md +++ b/docs/zh/docs/tutorial/encoder.md @@ -26,7 +26,7 @@ {!> ../../../docs_src/encoder/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="5 22" {!> ../../../docs_src/encoder/tutorial001.py!} diff --git a/docs/zh/docs/tutorial/extra-data-types.md b/docs/zh/docs/tutorial/extra-data-types.md index 76d606903..a74efa61b 100644 --- a/docs/zh/docs/tutorial/extra-data-types.md +++ b/docs/zh/docs/tutorial/extra-data-types.md @@ -67,7 +67,7 @@ {!> ../../../docs_src/extra_data_types/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 3 13-17" {!> ../../../docs_src/extra_data_types/tutorial001_an.py!} @@ -82,7 +82,7 @@ {!> ../../../docs_src/extra_data_types/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ๅฐฝๅฏ่ƒฝ้€‰ๆ‹ฉไฝฟ็”จ `Annotated` ็š„็‰ˆๆœฌใ€‚ @@ -105,7 +105,7 @@ {!> ../../../docs_src/extra_data_types/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="19-20" {!> ../../../docs_src/extra_data_types/tutorial001_an.py!} @@ -120,7 +120,7 @@ {!> ../../../docs_src/extra_data_types/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ๅฐฝๅฏ่ƒฝ้€‰ๆ‹ฉไฝฟ็”จ `Annotated` ็š„็‰ˆๆœฌใ€‚ diff --git a/docs/zh/docs/tutorial/extra-models.md b/docs/zh/docs/tutorial/extra-models.md index 32f8f9df1..06427a73d 100644 --- a/docs/zh/docs/tutorial/extra-models.md +++ b/docs/zh/docs/tutorial/extra-models.md @@ -23,7 +23,7 @@ {!> ../../../docs_src/extra_models/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9 11 16 22 24 29-30 33-35 40-41" {!> ../../../docs_src/extra_models/tutorial001.py!} @@ -164,7 +164,7 @@ UserInDB( {!> ../../../docs_src/extra_models/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9 15-16 19-20 23-24" {!> ../../../docs_src/extra_models/tutorial002.py!} @@ -188,7 +188,7 @@ UserInDB( {!> ../../../docs_src/extra_models/tutorial003_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 14-15 18-20 33" {!> ../../../docs_src/extra_models/tutorial003.py!} @@ -206,7 +206,7 @@ UserInDB( {!> ../../../docs_src/extra_models/tutorial004_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 20" {!> ../../../docs_src/extra_models/tutorial004.py!} @@ -226,7 +226,7 @@ UserInDB( {!> ../../../docs_src/extra_models/tutorial005_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="1 8" {!> ../../../docs_src/extra_models/tutorial005.py!} diff --git a/docs/zh/docs/tutorial/header-params.md b/docs/zh/docs/tutorial/header-params.md index 22ff6dc27..2701167b3 100644 --- a/docs/zh/docs/tutorial/header-params.md +++ b/docs/zh/docs/tutorial/header-params.md @@ -18,7 +18,7 @@ {!> ../../../docs_src/header_params/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="3" {!> ../../../docs_src/header_params/tutorial001_an.py!} @@ -33,7 +33,7 @@ {!> ../../../docs_src/header_params/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ๅฐฝๅฏ่ƒฝ้€‰ๆ‹ฉไฝฟ็”จ `Annotated` ็š„็‰ˆๆœฌใ€‚ @@ -60,7 +60,7 @@ {!> ../../../docs_src/header_params/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/header_params/tutorial001_an.py!} @@ -75,7 +75,7 @@ {!> ../../../docs_src/header_params/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ๅฐฝๅฏ่ƒฝ้€‰ๆ‹ฉไฝฟ็”จ `Annotated` ็š„็‰ˆๆœฌใ€‚ @@ -120,7 +120,7 @@ {!> ../../../docs_src/header_params/tutorial002_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="12" {!> ../../../docs_src/header_params/tutorial002_an.py!} @@ -135,7 +135,7 @@ {!> ../../../docs_src/header_params/tutorial002_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ๅฐฝๅฏ่ƒฝ้€‰ๆ‹ฉไฝฟ็”จ `Annotated` ็š„็‰ˆๆœฌใ€‚ @@ -170,7 +170,7 @@ {!> ../../../docs_src/header_params/tutorial003_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10" {!> ../../../docs_src/header_params/tutorial003_an.py!} @@ -194,7 +194,7 @@ {!> ../../../docs_src/header_params/tutorial003_py39.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ๅฐฝๅฏ่ƒฝ้€‰ๆ‹ฉไฝฟ็”จ `Annotated` ็š„็‰ˆๆœฌใ€‚ diff --git a/docs/zh/docs/tutorial/path-params-numeric-validations.md b/docs/zh/docs/tutorial/path-params-numeric-validations.md index 78fa922b4..9b41ad7cf 100644 --- a/docs/zh/docs/tutorial/path-params-numeric-validations.md +++ b/docs/zh/docs/tutorial/path-params-numeric-validations.md @@ -18,7 +18,7 @@ {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="3-4" {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an.py!} @@ -33,7 +33,7 @@ {!> ../../../docs_src/path_params_numeric_validations/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ๅฐฝๅฏ่ƒฝ้€‰ๆ‹ฉไฝฟ็”จ `Annotated` ็š„็‰ˆๆœฌใ€‚ @@ -60,7 +60,7 @@ {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="11" {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an.py!} @@ -75,7 +75,7 @@ {!> ../../../docs_src/path_params_numeric_validations/tutorial001_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ๅฐฝๅฏ่ƒฝ้€‰ๆ‹ฉไฝฟ็”จ `Annotated` ็š„็‰ˆๆœฌใ€‚ @@ -107,7 +107,7 @@ ๅ› ๆญค๏ผŒไฝ ๅฏไปฅๅฐ†ๅ‡ฝๆ•ฐๅฃฐๆ˜Žไธบ๏ผš -=== "Python 3.6 non-Annotated" +=== "Python 3.8 non-Annotated" !!! tip ๅฐฝๅฏ่ƒฝ้€‰ๆ‹ฉไฝฟ็”จ `Annotated` ็š„็‰ˆๆœฌใ€‚ diff --git a/docs/zh/docs/tutorial/query-params-str-validations.md b/docs/zh/docs/tutorial/query-params-str-validations.md index 7244aeade..39253eb0d 100644 --- a/docs/zh/docs/tutorial/query-params-str-validations.md +++ b/docs/zh/docs/tutorial/query-params-str-validations.md @@ -10,7 +10,7 @@ {!> ../../../docs_src/query_params_str_validations/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/query_params_str_validations/tutorial001.py!} diff --git a/docs/zh/docs/tutorial/request-files.md b/docs/zh/docs/tutorial/request-files.md index 03474907e..2c48f33ca 100644 --- a/docs/zh/docs/tutorial/request-files.md +++ b/docs/zh/docs/tutorial/request-files.md @@ -130,7 +130,7 @@ contents = myfile.file.read() {!> ../../../docs_src/request_files/tutorial001_02_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9 17" {!> ../../../docs_src/request_files/tutorial001_02.py!} @@ -158,7 +158,7 @@ FastAPI ๆ”ฏๆŒๅŒๆ—ถไธŠไผ ๅคšไธชๆ–‡ไปถใ€‚ {!> ../../../docs_src/request_files/tutorial002_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="10 15" {!> ../../../docs_src/request_files/tutorial002.py!} @@ -183,7 +183,7 @@ FastAPI ๆ”ฏๆŒๅŒๆ—ถไธŠไผ ๅคšไธชๆ–‡ไปถใ€‚ {!> ../../../docs_src/request_files/tutorial003_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="18" {!> ../../../docs_src/request_files/tutorial003.py!} diff --git a/docs/zh/docs/tutorial/response-model.md b/docs/zh/docs/tutorial/response-model.md index f529cb0d8..e731b6989 100644 --- a/docs/zh/docs/tutorial/response-model.md +++ b/docs/zh/docs/tutorial/response-model.md @@ -20,7 +20,7 @@ {!> ../../../docs_src/response_model/tutorial001_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="17 22 24-27" {!> ../../../docs_src/response_model/tutorial001.py!} @@ -78,7 +78,7 @@ FastAPI ๅฐ†ไฝฟ็”จๆญค `response_model` ๆฅ๏ผš {!> ../../../docs_src/response_model/tutorial003_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9 11 16" {!> ../../../docs_src/response_model/tutorial003.py!} @@ -92,7 +92,7 @@ FastAPI ๅฐ†ไฝฟ็”จๆญค `response_model` ๆฅ๏ผš {!> ../../../docs_src/response_model/tutorial003_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="24" {!> ../../../docs_src/response_model/tutorial003.py!} @@ -106,7 +106,7 @@ FastAPI ๅฐ†ไฝฟ็”จๆญค `response_model` ๆฅ๏ผš {!> ../../../docs_src/response_model/tutorial003_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="22" {!> ../../../docs_src/response_model/tutorial003.py!} diff --git a/docs/zh/docs/tutorial/schema-extra-example.md b/docs/zh/docs/tutorial/schema-extra-example.md index 816e8f68e..ebc04da8b 100644 --- a/docs/zh/docs/tutorial/schema-extra-example.md +++ b/docs/zh/docs/tutorial/schema-extra-example.md @@ -16,7 +16,7 @@ {!> ../../../docs_src/schema_extra_example/tutorial001_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="15-23" {!> ../../../docs_src/schema_extra_example/tutorial001.py!} @@ -34,7 +34,7 @@ {!> ../../../docs_src/schema_extra_example/tutorial002_py310.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="4 10-13" {!> ../../../docs_src/schema_extra_example/tutorial002.py!} @@ -61,7 +61,7 @@ {!> ../../../docs_src/schema_extra_example/tutorial003_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="23-28" {!> ../../../docs_src/schema_extra_example/tutorial003_an.py!} @@ -76,7 +76,7 @@ {!> ../../../docs_src/schema_extra_example/tutorial003_py310.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ๅฐฝๅฏ่ƒฝ้€‰ๆ‹ฉไฝฟ็”จ `Annotated` ็š„็‰ˆๆœฌใ€‚ diff --git a/docs/zh/docs/tutorial/security/first-steps.md b/docs/zh/docs/tutorial/security/first-steps.md index 7b1052e12..dda956417 100644 --- a/docs/zh/docs/tutorial/security/first-steps.md +++ b/docs/zh/docs/tutorial/security/first-steps.md @@ -26,13 +26,13 @@ {!> ../../../docs_src/security/tutorial001_an_py39.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python {!> ../../../docs_src/security/tutorial001_an.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip ๅฐฝๅฏ่ƒฝ้€‰ๆ‹ฉไฝฟ็”จ `Annotated` ็š„็‰ˆๆœฌใ€‚ diff --git a/docs/zh/docs/tutorial/sql-databases.md b/docs/zh/docs/tutorial/sql-databases.md index 482588f94..8b09dc677 100644 --- a/docs/zh/docs/tutorial/sql-databases.md +++ b/docs/zh/docs/tutorial/sql-databases.md @@ -258,7 +258,7 @@ connect_args={"check_same_thread": False} {!> ../../../docs_src/sql_databases/sql_app_py39/schemas.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="3 6-8 11-12 23-24 27-28" {!> ../../../docs_src/sql_databases/sql_app/schemas.py!} @@ -302,7 +302,7 @@ name: str {!> ../../../docs_src/sql_databases/sql_app_py39/schemas.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="15-17 31-34" {!> ../../../docs_src/sql_databases/sql_app/schemas.py!} @@ -331,7 +331,7 @@ name: str {!> ../../../docs_src/sql_databases/sql_app_py39/schemas.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="15 19-20 31 36-37" {!> ../../../docs_src/sql_databases/sql_app/schemas.py!} @@ -471,7 +471,7 @@ current_user.items {!> ../../../docs_src/sql_databases/sql_app_py39/main.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="9" {!> ../../../docs_src/sql_databases/sql_app/main.py!} @@ -505,7 +505,7 @@ current_user.items {!> ../../../docs_src/sql_databases/sql_app_py39/main.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="15-20" {!> ../../../docs_src/sql_databases/sql_app/main.py!} @@ -530,7 +530,7 @@ current_user.items {!> ../../../docs_src/sql_databases/sql_app_py39/main.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="24 32 38 47 53" {!> ../../../docs_src/sql_databases/sql_app/main.py!} @@ -551,7 +551,7 @@ current_user.items {!> ../../../docs_src/sql_databases/sql_app_py39/main.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="23-28 31-34 37-42 45-49 52-55" {!> ../../../docs_src/sql_databases/sql_app/main.py!} @@ -650,7 +650,7 @@ def read_user(user_id: int, db: Session = Depends(get_db)): {!> ../../../docs_src/sql_databases/sql_app_py39/schemas.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python {!> ../../../docs_src/sql_databases/sql_app/schemas.py!} @@ -670,7 +670,7 @@ def read_user(user_id: int, db: Session = Depends(get_db)): {!> ../../../docs_src/sql_databases/sql_app_py39/main.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python {!> ../../../docs_src/sql_databases/sql_app/main.py!} @@ -729,7 +729,7 @@ $ uvicorn sql_app.main:app --reload {!> ../../../docs_src/sql_databases/sql_app_py39/alt_main.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python hl_lines="14-22" {!> ../../../docs_src/sql_databases/sql_app/alt_main.py!} diff --git a/docs/zh/docs/tutorial/testing.md b/docs/zh/docs/tutorial/testing.md index 41f01f8d8..77fff7596 100644 --- a/docs/zh/docs/tutorial/testing.md +++ b/docs/zh/docs/tutorial/testing.md @@ -122,7 +122,7 @@ {!> ../../../docs_src/app_testing/app_b_an_py39/main.py!} ``` -=== "Python 3.6+" +=== "Python 3.8+" ```Python {!> ../../../docs_src/app_testing/app_b_an/main.py!} @@ -137,7 +137,7 @@ {!> ../../../docs_src/app_testing/app_b_py310/main.py!} ``` -=== "Python 3.6+ non-Annotated" +=== "Python 3.8+ non-Annotated" !!! tip Prefer to use the `Annotated` version if possible. diff --git a/pyproject.toml b/pyproject.toml index 2870b31a5..b49f472d5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ build-backend = "hatchling.build" name = "fastapi" description = "FastAPI framework, high performance, easy to learn, fast to code, ready for production" readme = "README.md" -requires-python = ">=3.7" +requires-python = ">=3.8" license = "MIT" authors = [ { name = "Sebastiรกn Ramรญrez", email = "tiangolo@gmail.com" }, @@ -32,7 +32,6 @@ classifiers = [ "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Programming Language :: Python :: 3 :: Only", - "Programming Language :: Python :: 3.7", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", From 4ef8c3286dca34ef5821eadd6e692044169beb80 Mon Sep 17 00:00:00 2001 From: github-actions Date: Tue, 17 Oct 2023 05:59:55 +0000 Subject: [PATCH 04/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 3c7ecad43..b7fe5a640 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -2,6 +2,7 @@ ## Latest Changes +* โฌ†๏ธ Drop support for Python 3.7, require Python 3.8 or above. PR [#10442](https://github.com/tiangolo/fastapi/pull/10442) by [@tiangolo](https://github.com/tiangolo). * ๐Ÿ”ง Update sponsors, Bump.sh images. PR [#10381](https://github.com/tiangolo/fastapi/pull/10381) by [@tiangolo](https://github.com/tiangolo). * ๐Ÿ‘ฅ Update FastAPI People. PR [#10363](https://github.com/tiangolo/fastapi/pull/10363) by [@tiangolo](https://github.com/tiangolo). ## 0.103.2 From 6b0c77e554ff6462696159899b9fe710a5d6a8fc Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 17 Oct 2023 11:18:40 +0400 Subject: [PATCH 05/38] =?UTF-8?q?=E2=AC=86=20Bump=20pypa/gh-action-pypi-pu?= =?UTF-8?q?blish=20from=201.8.6=20to=201.8.10=20(#10061)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumps [pypa/gh-action-pypi-publish](https://github.com/pypa/gh-action-pypi-publish) from 1.8.6 to 1.8.10. - [Release notes](https://github.com/pypa/gh-action-pypi-publish/releases) - [Commits](https://github.com/pypa/gh-action-pypi-publish/compare/v1.8.6...v1.8.10) --- updated-dependencies: - dependency-name: pypa/gh-action-pypi-publish dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/publish.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 5ab0603b9..faa46d751 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -32,7 +32,7 @@ jobs: - name: Build distribution run: python -m build - name: Publish - uses: pypa/gh-action-pypi-publish@v1.8.6 + uses: pypa/gh-action-pypi-publish@v1.8.10 with: password: ${{ secrets.PYPI_API_TOKEN }} - name: Dump GitHub context From e5fd92a7aba2ce9e3eebce1d683f10858cbbfb34 Mon Sep 17 00:00:00 2001 From: github-actions Date: Tue, 17 Oct 2023 07:19:26 +0000 Subject: [PATCH 06/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index b7fe5a640..f4d546900 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -2,6 +2,7 @@ ## Latest Changes +* โฌ† Bump pypa/gh-action-pypi-publish from 1.8.6 to 1.8.10. PR [#10061](https://github.com/tiangolo/fastapi/pull/10061) by [@dependabot[bot]](https://github.com/apps/dependabot). * โฌ†๏ธ Drop support for Python 3.7, require Python 3.8 or above. PR [#10442](https://github.com/tiangolo/fastapi/pull/10442) by [@tiangolo](https://github.com/tiangolo). * ๐Ÿ”ง Update sponsors, Bump.sh images. PR [#10381](https://github.com/tiangolo/fastapi/pull/10381) by [@tiangolo](https://github.com/tiangolo). * ๐Ÿ‘ฅ Update FastAPI People. PR [#10363](https://github.com/tiangolo/fastapi/pull/10363) by [@tiangolo](https://github.com/tiangolo). From d03373f3e803e637017fe4807cbefd08d218f8e0 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 17 Oct 2023 11:19:41 +0400 Subject: [PATCH 07/38] =?UTF-8?q?=E2=AC=86=20Bump=20actions/checkout=20fro?= =?UTF-8?q?m=203=20to=204=20(#10208)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumps [actions/checkout](https://github.com/actions/checkout) from 3 to 4. - [Release notes](https://github.com/actions/checkout/releases) - [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md) - [Commits](https://github.com/actions/checkout/compare/v3...v4) --- updated-dependencies: - dependency-name: actions/checkout dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/build-docs.yml | 6 +++--- .github/workflows/deploy-docs.yml | 2 +- .github/workflows/latest-changes.yml | 2 +- .github/workflows/notify-translations.yml | 2 +- .github/workflows/people.yml | 2 +- .github/workflows/publish.yml | 2 +- .github/workflows/test.yml | 6 +++--- 7 files changed, 11 insertions(+), 11 deletions(-) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index dedf23fb9..a1ce0860a 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -17,7 +17,7 @@ jobs: outputs: docs: ${{ steps.filter.outputs.docs }} steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 # For pull requests it's not necessary to checkout the code but for master it is - uses: dorny/paths-filter@v2 id: filter @@ -35,7 +35,7 @@ jobs: outputs: langs: ${{ steps.show-langs.outputs.langs }} steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v4 with: @@ -71,7 +71,7 @@ jobs: env: GITHUB_CONTEXT: ${{ toJson(github) }} run: echo "$GITHUB_CONTEXT" - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v4 with: diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index dcd6d7107..8af8ba827 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -14,7 +14,7 @@ jobs: env: GITHUB_CONTEXT: ${{ toJson(github) }} run: echo "$GITHUB_CONTEXT" - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Clean site run: | rm -rf ./site diff --git a/.github/workflows/latest-changes.yml b/.github/workflows/latest-changes.yml index e38870f46..ffec5ee5e 100644 --- a/.github/workflows/latest-changes.yml +++ b/.github/workflows/latest-changes.yml @@ -24,7 +24,7 @@ jobs: env: GITHUB_CONTEXT: ${{ toJson(github) }} run: echo "$GITHUB_CONTEXT" - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 with: # To allow latest-changes to commit to the main branch token: ${{ secrets.FASTAPI_LATEST_CHANGES }} diff --git a/.github/workflows/notify-translations.yml b/.github/workflows/notify-translations.yml index 44ee83ec0..c0904ce48 100644 --- a/.github/workflows/notify-translations.yml +++ b/.github/workflows/notify-translations.yml @@ -23,7 +23,7 @@ jobs: env: GITHUB_CONTEXT: ${{ toJson(github) }} run: echo "$GITHUB_CONTEXT" - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 # Allow debugging with tmate - name: Setup tmate session uses: mxschmitt/action-tmate@v3 diff --git a/.github/workflows/people.yml b/.github/workflows/people.yml index 4480a1427..b0868771d 100644 --- a/.github/workflows/people.yml +++ b/.github/workflows/people.yml @@ -19,7 +19,7 @@ jobs: env: GITHUB_CONTEXT: ${{ toJson(github) }} run: echo "$GITHUB_CONTEXT" - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 # Ref: https://github.com/actions/runner/issues/2033 - name: Fix git safe.directory in container run: mkdir -p /home/runner/work/_temp/_github_home && printf "[safe]\n\tdirectory = /github/workspace" > /home/runner/work/_temp/_github_home/.gitconfig diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index faa46d751..8cbd01b92 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -13,7 +13,7 @@ jobs: env: GITHUB_CONTEXT: ${{ toJson(github) }} run: echo "$GITHUB_CONTEXT" - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v4 with: diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 769b52021..7eccaa0ac 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -17,7 +17,7 @@ jobs: env: GITHUB_CONTEXT: ${{ toJson(github) }} run: echo "$GITHUB_CONTEXT" - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v4 with: @@ -50,7 +50,7 @@ jobs: env: GITHUB_CONTEXT: ${{ toJson(github) }} run: echo "$GITHUB_CONTEXT" - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v4 with: @@ -92,7 +92,7 @@ jobs: env: GITHUB_CONTEXT: ${{ toJson(github) }} run: echo "$GITHUB_CONTEXT" - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - uses: actions/setup-python@v4 with: python-version: '3.8' From 89e741765250b907b846192069e05f91d50bcaaa Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 17 Oct 2023 11:20:09 +0400 Subject: [PATCH 08/38] =?UTF-8?q?=E2=AC=86=20Bump=20dawidd6/action-downloa?= =?UTF-8?q?d-artifact=20from=202.27.0=20to=202.28.0=20(#10268)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumps [dawidd6/action-download-artifact](https://github.com/dawidd6/action-download-artifact) from 2.27.0 to 2.28.0. - [Release notes](https://github.com/dawidd6/action-download-artifact/releases) - [Commits](https://github.com/dawidd6/action-download-artifact/compare/v2.27.0...v2.28.0) --- updated-dependencies: - dependency-name: dawidd6/action-download-artifact dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/deploy-docs.yml | 2 +- .github/workflows/smokeshow.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 8af8ba827..155ebd0a8 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -21,7 +21,7 @@ jobs: mkdir ./site - name: Download Artifact Docs id: download - uses: dawidd6/action-download-artifact@v2.27.0 + uses: dawidd6/action-download-artifact@v2.28.0 with: if_no_artifact_found: ignore github_token: ${{ secrets.FASTAPI_PREVIEW_DOCS_DOWNLOAD_ARTIFACTS }} diff --git a/.github/workflows/smokeshow.yml b/.github/workflows/smokeshow.yml index 4e689d95c..38b44c413 100644 --- a/.github/workflows/smokeshow.yml +++ b/.github/workflows/smokeshow.yml @@ -24,7 +24,7 @@ jobs: - run: pip install smokeshow - - uses: dawidd6/action-download-artifact@v2.27.0 + - uses: dawidd6/action-download-artifact@v2.28.0 with: github_token: ${{ secrets.FASTAPI_SMOKESHOW_DOWNLOAD_ARTIFACTS }} workflow: test.yml From 912e4bb90603860fd5d7dd759c3db02dbfd1addc Mon Sep 17 00:00:00 2001 From: github-actions Date: Tue, 17 Oct 2023 07:20:20 +0000 Subject: [PATCH 09/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index f4d546900..7be1eda35 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -2,6 +2,7 @@ ## Latest Changes +* โฌ† Bump actions/checkout from 3 to 4. PR [#10208](https://github.com/tiangolo/fastapi/pull/10208) by [@dependabot[bot]](https://github.com/apps/dependabot). * โฌ† Bump pypa/gh-action-pypi-publish from 1.8.6 to 1.8.10. PR [#10061](https://github.com/tiangolo/fastapi/pull/10061) by [@dependabot[bot]](https://github.com/apps/dependabot). * โฌ†๏ธ Drop support for Python 3.7, require Python 3.8 or above. PR [#10442](https://github.com/tiangolo/fastapi/pull/10442) by [@tiangolo](https://github.com/tiangolo). * ๐Ÿ”ง Update sponsors, Bump.sh images. PR [#10381](https://github.com/tiangolo/fastapi/pull/10381) by [@tiangolo](https://github.com/tiangolo). From 3fa44aabe37362d4640403d9571897ea7dd5cf9b Mon Sep 17 00:00:00 2001 From: github-actions Date: Tue, 17 Oct 2023 07:20:59 +0000 Subject: [PATCH 10/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 7be1eda35..4222c4400 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -2,6 +2,7 @@ ## Latest Changes +* โฌ† Bump dawidd6/action-download-artifact from 2.27.0 to 2.28.0. PR [#10268](https://github.com/tiangolo/fastapi/pull/10268) by [@dependabot[bot]](https://github.com/apps/dependabot). * โฌ† Bump actions/checkout from 3 to 4. PR [#10208](https://github.com/tiangolo/fastapi/pull/10208) by [@dependabot[bot]](https://github.com/apps/dependabot). * โฌ† Bump pypa/gh-action-pypi-publish from 1.8.6 to 1.8.10. PR [#10061](https://github.com/tiangolo/fastapi/pull/10061) by [@dependabot[bot]](https://github.com/apps/dependabot). * โฌ†๏ธ Drop support for Python 3.7, require Python 3.8 or above. PR [#10442](https://github.com/tiangolo/fastapi/pull/10442) by [@tiangolo](https://github.com/tiangolo). From 05ca41cfd1c56157cf5bd2b3c1958263bdd71611 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Wed, 18 Oct 2023 16:36:40 +0400 Subject: [PATCH 11/38] =?UTF-8?q?=E2=9C=A8=20Add=20reference=20(code=20API?= =?UTF-8?q?)=20docs=20with=20PEP=20727,=20add=20subclass=20with=20custom?= =?UTF-8?q?=20docstrings=20for=20`BackgroundTasks`,=20refactor=20docs=20st?= =?UTF-8?q?ructure=20(#10392)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * โž• Add mkdocstrings and griffe-typingdoc to dependencies * ๐Ÿ”ง Add mkdocstrings configs to MkDocs * ๐Ÿ“ Add first WIP reference page * โฌ†๏ธ Upgrade typing-extensions to the minimum version including Doc() * ๐Ÿ“ Add docs to FastAPI parameters * ๐Ÿ“ Add docstrings for OpenAPI docs utils * ๐Ÿ“ Add docstrings for security utils * ๐Ÿ“ Add docstrings for UploadFile * ๐Ÿ“ Update docstrings in FastAPI class * ๐Ÿ“ Add docstrings for path operation methods * ๐Ÿ“ Add docstring for jsonable_encoder * ๐Ÿ“ Add docstrings for exceptions * ๐Ÿ“ Add docstsrings for parameter functions * ๐Ÿ“ Add docstrings for responses * ๐Ÿ“ Add docstrings for APIRouter * โ™ป๏ธ Sub-class BackgroundTasks to document it with docstrings * ๐Ÿ“ Update usage of background tasks in dependencies * โœ… Update tests with new deprecation warnings * ๐Ÿ“ Add new reference docs * ๐Ÿ”ง Update MkDocs with new reference docs * โœ… Update pytest fixture, deprecation is raised only once * ๐ŸŽจ Update format for types in exceptions.py * โ™ป๏ธ Update annotations in BackgroundTask, `Annotated` can't take ParamSpec's P.args or P.kwargs * โœ๏ธ Fix typos caught by @pawamoy * ๐Ÿ”ง Update and fix MkDocstrings configs from @pawamoy tips * ๐Ÿ“ Update reference docs * โœ๏ธ Fix typos found by @pawamoy * โž• Add HTTPX as a dependency for docs, for the TestClient * ๐Ÿ”ง Update MkDocs config, rename websockets reference * ๐Ÿ”‡ Add type-ignores for Doc as the stubs haven't been released for mypy * ๐Ÿ”ฅ Remove duplicated deprecated notice * ๐Ÿ”‡ Remove typing error for unreleased stub in openapi/docs.py * โœ… Add tests for UploadFile for coverage * โฌ†๏ธ Upgrade griffe-typingdoc==0.2.2 * ๐Ÿ“ Refactor docs structure * ๐Ÿ”จ Update README generation with new index frontmatter and style * ๐Ÿ”จ Update generation of languages, remove from top menu, keep in lang menu * ๐Ÿ“ Add OpenAPI Pydantic models * ๐Ÿ”จ Update docs script to not translate Reference and Release Notes * ๐Ÿ”ง Add reference for OpenAPI models * ๐Ÿ”ง Update MkDocs config for mkdocstrings insiders * ๐Ÿ‘ท Install mkdocstring insiders in CI for docs * ๐Ÿ› Fix MkDocstrings insiders install URL * โž• Move dependencies shared by docs and tests to its own requirements file * ๐Ÿ‘ท Update cache keys for test and docs dependencies * ๐Ÿ“ Remove no longer needed __init__ placeholder docstrings * ๐Ÿ“ Move docstring for APIRouter to the class level (not __init__ level) * ๐Ÿ”ฅ Remove no longer needed dummy placeholder __init__ docstring --- .github/workflows/build-docs.yml | 14 +- .github/workflows/test.yml | 4 +- docs/en/docs/about/index.md | 3 + docs/en/docs/fastapi-people.md | 5 + docs/en/docs/features.md | 5 + docs/en/docs/help/index.md | 3 + docs/en/docs/index.md | 9 + docs/en/docs/learn/index.md | 5 + docs/en/docs/reference/apirouter.md | 25 + docs/en/docs/reference/background.md | 13 + docs/en/docs/reference/dependencies.md | 32 + docs/en/docs/reference/encoders.md | 3 + docs/en/docs/reference/exceptions.md | 22 + docs/en/docs/reference/fastapi.md | 32 + docs/en/docs/reference/httpconnection.md | 13 + docs/en/docs/reference/index.md | 7 + docs/en/docs/reference/middleware.md | 46 + docs/en/docs/reference/openapi/docs.md | 11 + docs/en/docs/reference/openapi/index.md | 5 + docs/en/docs/reference/openapi/models.md | 5 + docs/en/docs/reference/parameters.md | 36 + docs/en/docs/reference/request.md | 18 + docs/en/docs/reference/response.md | 15 + docs/en/docs/reference/responses.md | 166 + docs/en/docs/reference/security/index.md | 76 + docs/en/docs/reference/staticfiles.md | 14 + docs/en/docs/reference/status.md | 39 + docs/en/docs/reference/templating.md | 14 + docs/en/docs/reference/testclient.md | 14 + docs/en/docs/reference/uploadfile.md | 23 + docs/en/docs/reference/websockets.md | 70 + docs/en/docs/release-notes.md | 5 + docs/en/docs/resources/index.md | 3 + docs/en/mkdocs.yml | 297 +- fastapi/applications.py | 4269 +++++++++++++++-- fastapi/background.py | 60 +- fastapi/datastructures.py | 123 +- fastapi/dependencies/utils.py | 18 +- fastapi/encoders.py | 110 +- fastapi/exceptions.py | 131 +- fastapi/openapi/docs.py | 169 +- fastapi/param_functions.py | 2179 ++++++++- fastapi/responses.py | 14 + fastapi/routing.py | 3483 +++++++++++++- fastapi/security/api_key.py | 227 +- fastapi/security/http.py | 285 +- fastapi/security/oauth2.py | 549 ++- fastapi/security/open_id_connect_url.py | 58 +- pyproject.toml | 2 +- requirements-docs-tests.txt | 3 + requirements-docs.txt | 3 + requirements-tests.txt | 3 +- scripts/docs.py | 7 +- scripts/mkdocs_hooks.py | 8 + tests/test_datastructures.py | 18 + tests/test_router_events.py | 3 + .../test_tutorial001.py | 15 +- .../test_events/test_tutorial001.py | 13 +- .../test_events/test_tutorial002.py | 13 +- .../test_testing/test_tutorial003.py | 4 +- 60 files changed, 11811 insertions(+), 1008 deletions(-) create mode 100644 docs/en/docs/about/index.md create mode 100644 docs/en/docs/help/index.md create mode 100644 docs/en/docs/learn/index.md create mode 100644 docs/en/docs/reference/apirouter.md create mode 100644 docs/en/docs/reference/background.md create mode 100644 docs/en/docs/reference/dependencies.md create mode 100644 docs/en/docs/reference/encoders.md create mode 100644 docs/en/docs/reference/exceptions.md create mode 100644 docs/en/docs/reference/fastapi.md create mode 100644 docs/en/docs/reference/httpconnection.md create mode 100644 docs/en/docs/reference/index.md create mode 100644 docs/en/docs/reference/middleware.md create mode 100644 docs/en/docs/reference/openapi/docs.md create mode 100644 docs/en/docs/reference/openapi/index.md create mode 100644 docs/en/docs/reference/openapi/models.md create mode 100644 docs/en/docs/reference/parameters.md create mode 100644 docs/en/docs/reference/request.md create mode 100644 docs/en/docs/reference/response.md create mode 100644 docs/en/docs/reference/responses.md create mode 100644 docs/en/docs/reference/security/index.md create mode 100644 docs/en/docs/reference/staticfiles.md create mode 100644 docs/en/docs/reference/status.md create mode 100644 docs/en/docs/reference/templating.md create mode 100644 docs/en/docs/reference/testclient.md create mode 100644 docs/en/docs/reference/uploadfile.md create mode 100644 docs/en/docs/reference/websockets.md create mode 100644 docs/en/docs/resources/index.md create mode 100644 requirements-docs-tests.txt diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index a1ce0860a..4100781c5 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -44,14 +44,17 @@ jobs: id: cache with: path: ${{ env.pythonLocation }} - key: ${{ runner.os }}-python-docs-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml', 'requirements-docs.txt') }}-v06 + key: ${{ runner.os }}-python-docs-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml', 'requirements-docs.txt', 'requirements-docs-tests.txt') }}-v06 - name: Install docs extras if: steps.cache.outputs.cache-hit != 'true' run: pip install -r requirements-docs.txt # Install MkDocs Material Insiders here just to put it in the cache for the rest of the steps - name: Install Material for MkDocs Insiders if: ( github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork == false ) && steps.cache.outputs.cache-hit != 'true' - run: pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/squidfunk/mkdocs-material-insiders.git + run: | + pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/squidfunk/mkdocs-material-insiders.git + pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/griffe-typing-deprecated.git + pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/mkdocstrings-python.git - name: Export Language Codes id: show-langs run: | @@ -80,13 +83,16 @@ jobs: id: cache with: path: ${{ env.pythonLocation }} - key: ${{ runner.os }}-python-docs-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml', 'requirements-docs.txt') }}-v06 + key: ${{ runner.os }}-python-docs-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml', 'requirements-docs.txt', 'requirements-docs-tests.txt') }}-v06 - name: Install docs extras if: steps.cache.outputs.cache-hit != 'true' run: pip install -r requirements-docs.txt - name: Install Material for MkDocs Insiders if: ( github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork == false ) && steps.cache.outputs.cache-hit != 'true' - run: pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/squidfunk/mkdocs-material-insiders.git + run: | + pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/squidfunk/mkdocs-material-insiders.git + pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/griffe-typing-deprecated.git + pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/mkdocstrings-python.git - name: Update Languages run: python ./scripts/docs.py update-languages - uses: actions/cache@v3 diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 7eccaa0ac..59754525d 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -29,7 +29,7 @@ jobs: id: cache with: path: ${{ env.pythonLocation }} - key: ${{ runner.os }}-python-${{ env.pythonLocation }}-pydantic-v2-${{ hashFiles('pyproject.toml', 'requirements-tests.txt') }}-test-v06 + key: ${{ runner.os }}-python-${{ env.pythonLocation }}-pydantic-v2-${{ hashFiles('pyproject.toml', 'requirements-tests.txt', 'requirements-docs-tests.txt') }}-test-v06 - name: Install Dependencies if: steps.cache.outputs.cache-hit != 'true' run: pip install -r requirements-tests.txt @@ -62,7 +62,7 @@ jobs: id: cache with: path: ${{ env.pythonLocation }} - key: ${{ runner.os }}-python-${{ env.pythonLocation }}-${{ matrix.pydantic-version }}-${{ hashFiles('pyproject.toml', 'requirements-tests.txt') }}-test-v06 + key: ${{ runner.os }}-python-${{ env.pythonLocation }}-${{ matrix.pydantic-version }}-${{ hashFiles('pyproject.toml', 'requirements-tests.txt', 'requirements-docs-tests.txt') }}-test-v06 - name: Install Dependencies if: steps.cache.outputs.cache-hit != 'true' run: pip install -r requirements-tests.txt diff --git a/docs/en/docs/about/index.md b/docs/en/docs/about/index.md new file mode 100644 index 000000000..27b78696b --- /dev/null +++ b/docs/en/docs/about/index.md @@ -0,0 +1,3 @@ +# About + +About FastAPI, its design, inspiration and more. ๐Ÿค“ diff --git a/docs/en/docs/fastapi-people.md b/docs/en/docs/fastapi-people.md index 20caaa1ee..7e26358d8 100644 --- a/docs/en/docs/fastapi-people.md +++ b/docs/en/docs/fastapi-people.md @@ -1,3 +1,8 @@ +--- +hide: + - navigation +--- + # FastAPI People FastAPI has an amazing community that welcomes people from all backgrounds. diff --git a/docs/en/docs/features.md b/docs/en/docs/features.md index 98f37b534..6f13b03bb 100644 --- a/docs/en/docs/features.md +++ b/docs/en/docs/features.md @@ -1,3 +1,8 @@ +--- +hide: + - navigation +--- + # Features ## FastAPI features diff --git a/docs/en/docs/help/index.md b/docs/en/docs/help/index.md new file mode 100644 index 000000000..5ee7df2fe --- /dev/null +++ b/docs/en/docs/help/index.md @@ -0,0 +1,3 @@ +# Help + +Help and get help, contribute, get involved. ๐Ÿค diff --git a/docs/en/docs/index.md b/docs/en/docs/index.md index cd3f3e000..3660e74e3 100644 --- a/docs/en/docs/index.md +++ b/docs/en/docs/index.md @@ -1,3 +1,12 @@ +--- +hide: + - navigation +--- + + +

FastAPI

diff --git a/docs/en/docs/learn/index.md b/docs/en/docs/learn/index.md new file mode 100644 index 000000000..d056fb320 --- /dev/null +++ b/docs/en/docs/learn/index.md @@ -0,0 +1,5 @@ +# Learn + +Here are the introductory sections and the tutorials to learn **FastAPI**. + +You could consider this a **book**, a **course**, the **official** and recommended way to learn FastAPI. ๐Ÿ˜Ž diff --git a/docs/en/docs/reference/apirouter.md b/docs/en/docs/reference/apirouter.md new file mode 100644 index 000000000..b779ad291 --- /dev/null +++ b/docs/en/docs/reference/apirouter.md @@ -0,0 +1,25 @@ +# `APIRouter` class + +Here's the reference information for the `APIRouter` class, with all its parameters, +attributes and methods. + +You can import the `APIRouter` class directly from `fastapi`: + +```python +from fastapi import APIRouter +``` + +::: fastapi.APIRouter + options: + members: + - websocket + - include_router + - get + - put + - post + - delete + - options + - head + - patch + - trace + - on_event diff --git a/docs/en/docs/reference/background.md b/docs/en/docs/reference/background.md new file mode 100644 index 000000000..e0c0be899 --- /dev/null +++ b/docs/en/docs/reference/background.md @@ -0,0 +1,13 @@ +# Background Tasks - `BackgroundTasks` + +You can declare a parameter in a *path operation function* or dependency function +with the type `BackgroundTasks`, and then you can use it to schedule the execution +of background tasks after the response is sent. + +You can import it directly from `fastapi`: + +```python +from fastapi import BackgroundTasks +``` + +::: fastapi.BackgroundTasks diff --git a/docs/en/docs/reference/dependencies.md b/docs/en/docs/reference/dependencies.md new file mode 100644 index 000000000..95cd101e4 --- /dev/null +++ b/docs/en/docs/reference/dependencies.md @@ -0,0 +1,32 @@ +# Dependencies - `Depends()` and `Security()` + +## `Depends()` + +Dependencies are handled mainly with the special function `Depends()` that takes a +callable. + +Here is the reference for it and its parameters. + +You can import it directly from `fastapi`: + +```python +from fastapi import Depends +``` + +::: fastapi.Depends + +## `Security()` + +For many scenarios, you can handle security (authorization, authentication, etc.) with +dependendencies, using `Depends()`. + +But when you want to also declare OAuth2 scopes, you can use `Security()` instead of +`Depends()`. + +You can import `Security()` directly from `fastapi`: + +```python +from fastapi import Security +``` + +::: fastapi.Security diff --git a/docs/en/docs/reference/encoders.md b/docs/en/docs/reference/encoders.md new file mode 100644 index 000000000..28df2e43a --- /dev/null +++ b/docs/en/docs/reference/encoders.md @@ -0,0 +1,3 @@ +# Encoders - `jsonable_encoder` + +::: fastapi.encoders.jsonable_encoder diff --git a/docs/en/docs/reference/exceptions.md b/docs/en/docs/reference/exceptions.md new file mode 100644 index 000000000..adc9b91ce --- /dev/null +++ b/docs/en/docs/reference/exceptions.md @@ -0,0 +1,22 @@ +# Exceptions - `HTTPException` and `WebSocketException` + +These are the exceptions that you can raise to show errors to the client. + +When you raise an exception, as would happen with normal Python, the rest of the +excecution is aborted. This way you can raise these exceptions from anywhere in the +code to abort a request and show the error to the client. + +You can use: + +* `HTTPException` +* `WebSocketException` + +These exceptions can be imported directly from `fastapi`: + +```python +from fastapi import HTTPException, WebSocketException +``` + +::: fastapi.HTTPException + +::: fastapi.WebSocketException diff --git a/docs/en/docs/reference/fastapi.md b/docs/en/docs/reference/fastapi.md new file mode 100644 index 000000000..8b87664cb --- /dev/null +++ b/docs/en/docs/reference/fastapi.md @@ -0,0 +1,32 @@ +# `FastAPI` class + +Here's the reference information for the `FastAPI` class, with all its parameters, +attributes and methods. + +You can import the `FastAPI` class directly from `fastapi`: + +```python +from fastapi import FastAPI +``` + +::: fastapi.FastAPI + options: + members: + - openapi_version + - webhooks + - state + - dependency_overrides + - openapi + - websocket + - include_router + - get + - put + - post + - delete + - options + - head + - patch + - trace + - on_event + - middleware + - exception_handler diff --git a/docs/en/docs/reference/httpconnection.md b/docs/en/docs/reference/httpconnection.md new file mode 100644 index 000000000..43dfc46f9 --- /dev/null +++ b/docs/en/docs/reference/httpconnection.md @@ -0,0 +1,13 @@ +# `HTTPConnection` class + +When you want to define dependencies that should be compatible with both HTTP and +WebSockets, you can define a parameter that takes an `HTTPConnection` instead of a +`Request` or a `WebSocket`. + +You can import it from `fastapi.requests`: + +```python +from fastapi.requests import HTTPConnection +``` + +::: fastapi.requests.HTTPConnection diff --git a/docs/en/docs/reference/index.md b/docs/en/docs/reference/index.md new file mode 100644 index 000000000..994b3c38c --- /dev/null +++ b/docs/en/docs/reference/index.md @@ -0,0 +1,7 @@ +# Reference - Code API + +Here's the reference or code API, the classes, functions, parameters, attributes, and +all the FastAPI parts you can use in you applications. + +If you want to **learn FastAPI** you are much better off reading the +[FastAPI Tutorial](https://fastapi.tiangolo.com/tutorial/). diff --git a/docs/en/docs/reference/middleware.md b/docs/en/docs/reference/middleware.md new file mode 100644 index 000000000..89704d3c8 --- /dev/null +++ b/docs/en/docs/reference/middleware.md @@ -0,0 +1,46 @@ +# Middleware + +There are several middlewares available provided by Starlette directly. + +Read more about them in the +[FastAPI docs for Middleware](https://fastapi.tiangolo.com/advanced/middleware/). + +::: fastapi.middleware.cors.CORSMiddleware + +It can be imported from `fastapi`: + +```python +from fastapi.middleware.cors import CORSMiddleware +``` + +::: fastapi.middleware.gzip.GZipMiddleware + +It can be imported from `fastapi`: + +```python +from fastapi.middleware.gzip import GZipMiddleware +``` + +::: fastapi.middleware.httpsredirect.HTTPSRedirectMiddleware + +It can be imported from `fastapi`: + +```python +from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware +``` + +::: fastapi.middleware.trustedhost.TrustedHostMiddleware + +It can be imported from `fastapi`: + +```python +from fastapi.middleware.trustedhost import TrustedHostMiddleware +``` + +::: fastapi.middleware.wsgi.WSGIMiddleware + +It can be imported from `fastapi`: + +```python +from fastapi.middleware.wsgi import WSGIMiddleware +``` diff --git a/docs/en/docs/reference/openapi/docs.md b/docs/en/docs/reference/openapi/docs.md new file mode 100644 index 000000000..ab620833e --- /dev/null +++ b/docs/en/docs/reference/openapi/docs.md @@ -0,0 +1,11 @@ +# OpenAPI `docs` + +Utilities to handle OpenAPI automatic UI documentation, including Swagger UI (by default at `/docs`) and ReDoc (by default at `/redoc`). + +::: fastapi.openapi.docs.get_swagger_ui_html + +::: fastapi.openapi.docs.get_redoc_html + +::: fastapi.openapi.docs.get_swagger_ui_oauth2_redirect_html + +::: fastapi.openapi.docs.swagger_ui_default_parameters diff --git a/docs/en/docs/reference/openapi/index.md b/docs/en/docs/reference/openapi/index.md new file mode 100644 index 000000000..e2b313f15 --- /dev/null +++ b/docs/en/docs/reference/openapi/index.md @@ -0,0 +1,5 @@ +# OpenAPI + +There are several utilities to handle OpenAPI. + +You normally don't need to use them unless you have a specific advanced use case that requires it. diff --git a/docs/en/docs/reference/openapi/models.md b/docs/en/docs/reference/openapi/models.md new file mode 100644 index 000000000..4a6b0770e --- /dev/null +++ b/docs/en/docs/reference/openapi/models.md @@ -0,0 +1,5 @@ +# OpenAPI `models` + +OpenAPI Pydantic models used to generate and validate the generated OpenAPI. + +::: fastapi.openapi.models diff --git a/docs/en/docs/reference/parameters.md b/docs/en/docs/reference/parameters.md new file mode 100644 index 000000000..8f77f0161 --- /dev/null +++ b/docs/en/docs/reference/parameters.md @@ -0,0 +1,36 @@ +# Request Parameters + +Here's the reference information for the request parameters. + +These are the special functions that you can put in *path operation function* +parameters or dependency functions with `Annotated` to get data from the request. + +It includes: + +* `Query()` +* `Path()` +* `Body()` +* `Cookie()` +* `Header()` +* `Form()` +* `File()` + +You can import them all directly from `fastapi`: + +```python +from fastapi import Body, Cookie, File, Form, Header, Path, Query +``` + +::: fastapi.Query + +::: fastapi.Path + +::: fastapi.Body + +::: fastapi.Cookie + +::: fastapi.Header + +::: fastapi.Form + +::: fastapi.File diff --git a/docs/en/docs/reference/request.md b/docs/en/docs/reference/request.md new file mode 100644 index 000000000..91ec7d37b --- /dev/null +++ b/docs/en/docs/reference/request.md @@ -0,0 +1,18 @@ +# `Request` class + +You can declare a parameter in a *path operation function* or dependency to be of type +`Request` and then you can access the raw request object directly, without any +validation, etc. + +You can import it directly from `fastapi`: + +```python +from fastapi import Request +``` + +!!! tip + When you want to define dependencies that should be compatible with both HTTP and + WebSockets, you can define a parameter that takes an `HTTPConnection` instead of a + `Request` or a `WebSocket`. + +::: fastapi.Request diff --git a/docs/en/docs/reference/response.md b/docs/en/docs/reference/response.md new file mode 100644 index 000000000..916254583 --- /dev/null +++ b/docs/en/docs/reference/response.md @@ -0,0 +1,15 @@ +# `Response` class + +You can declare a parameter in a *path operation function* or dependency to be of type +`Response` and then you can set data for the response like headers or cookies. + +You can also use it directly to create an instance of it and return it from your *path +operations*. + +You can import it directly from `fastapi`: + +```python +from fastapi import Response +``` + +::: fastapi.Response diff --git a/docs/en/docs/reference/responses.md b/docs/en/docs/reference/responses.md new file mode 100644 index 000000000..2cbbd8963 --- /dev/null +++ b/docs/en/docs/reference/responses.md @@ -0,0 +1,166 @@ +# Custom Response Classes - File, HTML, Redirect, Streaming, etc. + +There are several custom response classes you can use to create an instance and return +them directly from your *path operations*. + +Read more about it in the +[FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/). + +You can import them directly from `fastapi.responses`: + +```python +from fastapi.responses import ( + FileResponse, + HTMLResponse, + JSONResponse, + ORJSONResponse, + PlainTextResponse, + RedirectResponse, + Response, + StreamingResponse, + UJSONResponse, +) +``` + +## FastAPI Responses + +There are a couple of custom FastAPI response classes, you can use them to optimize JSON performance. + +::: fastapi.responses.UJSONResponse + options: + members: + - charset + - status_code + - media_type + - body + - background + - raw_headers + - render + - init_headers + - headers + - set_cookie + - delete_cookie + +::: fastapi.responses.ORJSONResponse + options: + members: + - charset + - status_code + - media_type + - body + - background + - raw_headers + - render + - init_headers + - headers + - set_cookie + - delete_cookie + +## Starlette Responses + +::: fastapi.responses.FileResponse + options: + members: + - chunk_size + - charset + - status_code + - media_type + - body + - background + - raw_headers + - render + - init_headers + - headers + - set_cookie + - delete_cookie + +::: fastapi.responses.HTMLResponse + options: + members: + - charset + - status_code + - media_type + - body + - background + - raw_headers + - render + - init_headers + - headers + - set_cookie + - delete_cookie + +::: fastapi.responses.JSONResponse + options: + members: + - charset + - status_code + - media_type + - body + - background + - raw_headers + - render + - init_headers + - headers + - set_cookie + - delete_cookie + +::: fastapi.responses.PlainTextResponse + options: + members: + - charset + - status_code + - media_type + - body + - background + - raw_headers + - render + - init_headers + - headers + - set_cookie + - delete_cookie + +::: fastapi.responses.RedirectResponse + options: + members: + - charset + - status_code + - media_type + - body + - background + - raw_headers + - render + - init_headers + - headers + - set_cookie + - delete_cookie + +::: fastapi.responses.Response + options: + members: + - charset + - status_code + - media_type + - body + - background + - raw_headers + - render + - init_headers + - headers + - set_cookie + - delete_cookie + +::: fastapi.responses.StreamingResponse + options: + members: + - body_iterator + - charset + - status_code + - media_type + - body + - background + - raw_headers + - render + - init_headers + - headers + - set_cookie + - delete_cookie diff --git a/docs/en/docs/reference/security/index.md b/docs/en/docs/reference/security/index.md new file mode 100644 index 000000000..ff86e9e30 --- /dev/null +++ b/docs/en/docs/reference/security/index.md @@ -0,0 +1,76 @@ +# Security Tools + +When you need to declare dependencies with OAuth2 scopes you use `Security()`. + +But you still need to define what is the dependable, the callable that you pass as +a parameter to `Depends()` or `Security()`. + +There are multiple tools that you can use to create those dependables, and they get +integrated into OpenAPI so they are shown in the automatic docs UI, they can be used +by automatically generated clients and SDKs, etc. + +You can import them from `fastapi.security`: + +```python +from fastapi.security import ( + APIKeyCookie, + APIKeyHeader, + APIKeyQuery, + HTTPAuthorizationCredentials, + HTTPBasic, + HTTPBasicCredentials, + HTTPBearer, + HTTPDigest, + OAuth2, + OAuth2AuthorizationCodeBearer, + OAuth2PasswordBearer, + OAuth2PasswordRequestForm, + OAuth2PasswordRequestFormStrict, + OpenIdConnect, + SecurityScopes, +) +``` + +## API Key Security Schemes + +::: fastapi.security.APIKeyCookie + +::: fastapi.security.APIKeyHeader + +::: fastapi.security.APIKeyQuery + +## HTTP Authentication Schemes + +::: fastapi.security.HTTPBasic + +::: fastapi.security.HTTPBearer + +::: fastapi.security.HTTPDigest + +## HTTP Credentials + +::: fastapi.security.HTTPAuthorizationCredentials + +::: fastapi.security.HTTPBasicCredentials + +## OAuth2 Authentication + +::: fastapi.security.OAuth2 + +::: fastapi.security.OAuth2AuthorizationCodeBearer + +::: fastapi.security.OAuth2PasswordBearer + +## OAuth2 Password Form + +::: fastapi.security.OAuth2PasswordRequestForm + +::: fastapi.security.OAuth2PasswordRequestFormStrict + +## OAuth2 Security Scopes in Dependencies + +::: fastapi.security.SecurityScopes + +## OpenID Connect + +::: fastapi.security.OpenIdConnect diff --git a/docs/en/docs/reference/staticfiles.md b/docs/en/docs/reference/staticfiles.md new file mode 100644 index 000000000..ce66f17b3 --- /dev/null +++ b/docs/en/docs/reference/staticfiles.md @@ -0,0 +1,14 @@ +# Static Files - `StaticFiles` + +You can use the `StaticFiles` class to serve static files, like JavaScript, CSS, images, etc. + +Read more about it in the +[FastAPI docs for Static Files](https://fastapi.tiangolo.com/tutorial/static-files/). + +You can import it directly from `fastapi.staticfiles`: + +```python +from fastapi.staticfiles import StaticFiles +``` + +::: fastapi.staticfiles.StaticFiles diff --git a/docs/en/docs/reference/status.md b/docs/en/docs/reference/status.md new file mode 100644 index 000000000..54fba9387 --- /dev/null +++ b/docs/en/docs/reference/status.md @@ -0,0 +1,39 @@ +# Status Codes + +You can import the `status` module from `fastapi`: + +```python +from fastapi import status +``` + +`status` is provided directly by Starlette. + +It containes a group of named constants (variables) with integer status codes. + +For example: + +* 200: `status.HTTP_200_OK` +* 403: `status.HTTP_403_FORBIDDEN` +* etc. + +It can be convenient to quickly access HTTP (and WebSocket) status codes in your app, +using autocompletion for the name without having to remember the integer status codes +by memory. + +Read more about it in the +[FastAPI docs about Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). + +## Example + +```python +from fastapi import FastAPI, status + +app = FastAPI() + + +@app.get("/items/", status_code=status.HTTP_418_IM_A_TEAPOT) +def read_items(): + return [{"name": "Plumbus"}, {"name": "Portal Gun"}] +``` + +::: fastapi.status diff --git a/docs/en/docs/reference/templating.md b/docs/en/docs/reference/templating.md new file mode 100644 index 000000000..c865badfc --- /dev/null +++ b/docs/en/docs/reference/templating.md @@ -0,0 +1,14 @@ +# Templating - `Jinja2Templates` + +You can use the `Jinja2Templates` class to render Jinja templates. + +Read more about it in the +[FastAPI docs for Templates](https://fastapi.tiangolo.com/advanced/templates/). + +You can import it directly from `fastapi.templating`: + +```python +from fastapi.templating import Jinja2Templates +``` + +::: fastapi.templating.Jinja2Templates diff --git a/docs/en/docs/reference/testclient.md b/docs/en/docs/reference/testclient.md new file mode 100644 index 000000000..e391d964a --- /dev/null +++ b/docs/en/docs/reference/testclient.md @@ -0,0 +1,14 @@ +# Test Client - `TestClient` + +You can use the `TestClient` class to test FastAPI applications without creating an actual HTTP and socket connection, just communicating directly with the FastAPI code. + +Read more about it in the +[FastAPI docs for Testing](https://fastapi.tiangolo.com/tutorial/testing/). + +You can import it directly from `fastapi.testclient`: + +```python +from fastapi.testclient import TestClient +``` + +::: fastapi.testclient.TestClient diff --git a/docs/en/docs/reference/uploadfile.md b/docs/en/docs/reference/uploadfile.md new file mode 100644 index 000000000..45c644b18 --- /dev/null +++ b/docs/en/docs/reference/uploadfile.md @@ -0,0 +1,23 @@ +# `UploadFile` class + +You can define *path operation function* parameters to be of the type `UploadFile` +to receive files from the request. + +You can import it directly from `fastapi`: + +```python +from fastapi import UploadFile +``` + +::: fastapi.UploadFile + options: + members: + - file + - filename + - size + - headers + - content_type + - read + - write + - seek + - close diff --git a/docs/en/docs/reference/websockets.md b/docs/en/docs/reference/websockets.md new file mode 100644 index 000000000..2a0469467 --- /dev/null +++ b/docs/en/docs/reference/websockets.md @@ -0,0 +1,70 @@ +# WebSockets + +When defining WebSockets, you normally declare a parameter of type `WebSocket` and +with it you can read data from the client and send data to it. + +It is provided directly by Starlette, but you can import it from `fastapi`: + +```python +from fastapi import WebSocket +``` + +!!! tip + When you want to define dependencies that should be compatible with both HTTP and + WebSockets, you can define a parameter that takes an `HTTPConnection` instead of a + `Request` or a `WebSocket`. + +::: fastapi.WebSocket + options: + members: + - scope + - app + - url + - base_url + - headers + - query_params + - path_params + - cookies + - client + - state + - url_for + - client_state + - application_state + - receive + - send + - accept + - receive_text + - receive_bytes + - receive_json + - iter_text + - iter_bytes + - iter_json + - send_text + - send_bytes + - send_json + - close + +When a client disconnects, a `WebSocketDisconnect` exception is raised, you can catch +it. + +You can import it directly form `fastapi`: + +```python +from fastapi import WebSocketDisconnect +``` + +::: fastapi.WebSocketDisconnect + +## WebSockets - additional classes + +Additional classes for handling WebSockets. + +Provided directly by Starlette, but you can import it from `fastapi`: + +```python +from fastapi.websockets import WebSocketDisconnect, WebSocketState +``` + +::: fastapi.websockets.WebSocketDisconnect + +::: fastapi.websockets.WebSocketState diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 4222c4400..62ffd4b35 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -1,3 +1,8 @@ +--- +hide: + - navigation +--- + # Release Notes ## Latest Changes diff --git a/docs/en/docs/resources/index.md b/docs/en/docs/resources/index.md new file mode 100644 index 000000000..8c7cac43b --- /dev/null +++ b/docs/en/docs/resources/index.md @@ -0,0 +1,3 @@ +# Resources + +Additional resources, external links, articles and more. โœˆ๏ธ diff --git a/docs/en/mkdocs.yml b/docs/en/mkdocs.yml index ba1ac7924..a64eff269 100644 --- a/docs/en/mkdocs.yml +++ b/docs/en/mkdocs.yml @@ -30,6 +30,7 @@ theme: - content.code.annotate - content.code.copy - content.code.select + - navigation.tabs icon: repo: fontawesome/brands/github-alt logo: img/icon-white.svg @@ -52,142 +53,174 @@ plugins: advanced/custom-request-and-route.md: how-to/custom-request-and-route.md advanced/conditional-openapi.md: how-to/conditional-openapi.md advanced/extending-openapi.md: how-to/extending-openapi.md + mkdocstrings: + handlers: + python: + options: + extensions: + - griffe_typingdoc + show_root_heading: true + show_if_no_docstring: true + preload_modules: [httpx, starlette] + inherited_members: true + members_order: source + separate_signature: true + unwrap_annotated: true + filters: ["!^_"] + merge_init_into_class: true + docstring_section_style: spacy + signature_crossrefs: true + show_symbol_type_heading: true + show_symbol_type_toc: true nav: - FastAPI: index.md -- Languages: - - en: / - - de: /de/ - - em: /em/ - - es: /es/ - - fa: /fa/ - - fr: /fr/ - - he: /he/ - - id: /id/ - - ja: /ja/ - - ko: /ko/ - - pl: /pl/ - - pt: /pt/ - - ru: /ru/ - - tr: /tr/ - - uk: /uk/ - - ur: /ur/ - - vi: /vi/ - - yo: /yo/ - - zh: /zh/ - features.md +- Learn: + - learn/index.md + - python-types.md + - async.md + - Tutorial - User Guide: + - tutorial/index.md + - tutorial/first-steps.md + - tutorial/path-params.md + - tutorial/query-params.md + - tutorial/body.md + - tutorial/query-params-str-validations.md + - tutorial/path-params-numeric-validations.md + - tutorial/body-multiple-params.md + - tutorial/body-fields.md + - tutorial/body-nested-models.md + - tutorial/schema-extra-example.md + - tutorial/extra-data-types.md + - tutorial/cookie-params.md + - tutorial/header-params.md + - tutorial/response-model.md + - tutorial/extra-models.md + - tutorial/response-status-code.md + - tutorial/request-forms.md + - tutorial/request-files.md + - tutorial/request-forms-and-files.md + - tutorial/handling-errors.md + - tutorial/path-operation-configuration.md + - tutorial/encoder.md + - tutorial/body-updates.md + - Dependencies: + - tutorial/dependencies/index.md + - tutorial/dependencies/classes-as-dependencies.md + - tutorial/dependencies/sub-dependencies.md + - tutorial/dependencies/dependencies-in-path-operation-decorators.md + - tutorial/dependencies/global-dependencies.md + - tutorial/dependencies/dependencies-with-yield.md + - Security: + - tutorial/security/index.md + - tutorial/security/first-steps.md + - tutorial/security/get-current-user.md + - tutorial/security/simple-oauth2.md + - tutorial/security/oauth2-jwt.md + - tutorial/middleware.md + - tutorial/cors.md + - tutorial/sql-databases.md + - tutorial/bigger-applications.md + - tutorial/background-tasks.md + - tutorial/metadata.md + - tutorial/static-files.md + - tutorial/testing.md + - tutorial/debugging.md + - Advanced User Guide: + - advanced/index.md + - advanced/path-operation-advanced-configuration.md + - advanced/additional-status-codes.md + - advanced/response-directly.md + - advanced/custom-response.md + - advanced/additional-responses.md + - advanced/response-cookies.md + - advanced/response-headers.md + - advanced/response-change-status-code.md + - advanced/advanced-dependencies.md + - Advanced Security: + - advanced/security/index.md + - advanced/security/oauth2-scopes.md + - advanced/security/http-basic-auth.md + - advanced/using-request-directly.md + - advanced/dataclasses.md + - advanced/middleware.md + - advanced/sub-applications.md + - advanced/behind-a-proxy.md + - advanced/templates.md + - advanced/websockets.md + - advanced/events.md + - advanced/testing-websockets.md + - advanced/testing-events.md + - advanced/testing-dependencies.md + - advanced/testing-database.md + - advanced/async-tests.md + - advanced/settings.md + - advanced/openapi-callbacks.md + - advanced/openapi-webhooks.md + - advanced/wsgi.md + - advanced/generate-clients.md + - Deployment: + - deployment/index.md + - deployment/versions.md + - deployment/https.md + - deployment/manually.md + - deployment/concepts.md + - deployment/cloud.md + - deployment/server-workers.md + - deployment/docker.md + - How To - Recipes: + - how-to/index.md + - how-to/general.md + - how-to/sql-databases-peewee.md + - how-to/async-sql-encode-databases.md + - how-to/nosql-databases-couchbase.md + - how-to/graphql.md + - how-to/custom-request-and-route.md + - how-to/conditional-openapi.md + - how-to/extending-openapi.md + - how-to/separate-openapi-schemas.md + - how-to/custom-docs-ui-assets.md + - how-to/configure-swagger-ui.md +- Reference (Code API): + - reference/index.md + - reference/fastapi.md + - reference/parameters.md + - reference/status.md + - reference/uploadfile.md + - reference/exceptions.md + - reference/dependencies.md + - reference/apirouter.md + - reference/background.md + - reference/request.md + - reference/websockets.md + - reference/httpconnection.md + - reference/response.md + - reference/responses.md + - reference/middleware.md + - OpenAPI: + - reference/openapi/index.md + - reference/openapi/docs.md + - reference/openapi/models.md + - reference/security/index.md + - reference/encoders.md + - reference/staticfiles.md + - reference/templating.md + - reference/testclient.md - fastapi-people.md -- python-types.md -- Tutorial - User Guide: - - tutorial/index.md - - tutorial/first-steps.md - - tutorial/path-params.md - - tutorial/query-params.md - - tutorial/body.md - - tutorial/query-params-str-validations.md - - tutorial/path-params-numeric-validations.md - - tutorial/body-multiple-params.md - - tutorial/body-fields.md - - tutorial/body-nested-models.md - - tutorial/schema-extra-example.md - - tutorial/extra-data-types.md - - tutorial/cookie-params.md - - tutorial/header-params.md - - tutorial/response-model.md - - tutorial/extra-models.md - - tutorial/response-status-code.md - - tutorial/request-forms.md - - tutorial/request-files.md - - tutorial/request-forms-and-files.md - - tutorial/handling-errors.md - - tutorial/path-operation-configuration.md - - tutorial/encoder.md - - tutorial/body-updates.md - - Dependencies: - - tutorial/dependencies/index.md - - tutorial/dependencies/classes-as-dependencies.md - - tutorial/dependencies/sub-dependencies.md - - tutorial/dependencies/dependencies-in-path-operation-decorators.md - - tutorial/dependencies/global-dependencies.md - - tutorial/dependencies/dependencies-with-yield.md - - Security: - - tutorial/security/index.md - - tutorial/security/first-steps.md - - tutorial/security/get-current-user.md - - tutorial/security/simple-oauth2.md - - tutorial/security/oauth2-jwt.md - - tutorial/middleware.md - - tutorial/cors.md - - tutorial/sql-databases.md - - tutorial/bigger-applications.md - - tutorial/background-tasks.md - - tutorial/metadata.md - - tutorial/static-files.md - - tutorial/testing.md - - tutorial/debugging.md -- Advanced User Guide: - - advanced/index.md - - advanced/path-operation-advanced-configuration.md - - advanced/additional-status-codes.md - - advanced/response-directly.md - - advanced/custom-response.md - - advanced/additional-responses.md - - advanced/response-cookies.md - - advanced/response-headers.md - - advanced/response-change-status-code.md - - advanced/advanced-dependencies.md - - Advanced Security: - - advanced/security/index.md - - advanced/security/oauth2-scopes.md - - advanced/security/http-basic-auth.md - - advanced/using-request-directly.md - - advanced/dataclasses.md - - advanced/middleware.md - - advanced/sub-applications.md - - advanced/behind-a-proxy.md - - advanced/templates.md - - advanced/websockets.md - - advanced/events.md - - advanced/testing-websockets.md - - advanced/testing-events.md - - advanced/testing-dependencies.md - - advanced/testing-database.md - - advanced/async-tests.md - - advanced/settings.md - - advanced/openapi-callbacks.md - - advanced/openapi-webhooks.md - - advanced/wsgi.md - - advanced/generate-clients.md -- async.md -- Deployment: - - deployment/index.md - - deployment/versions.md - - deployment/https.md - - deployment/manually.md - - deployment/concepts.md - - deployment/cloud.md - - deployment/server-workers.md - - deployment/docker.md -- How To - Recipes: - - how-to/index.md - - how-to/general.md - - how-to/sql-databases-peewee.md - - how-to/async-sql-encode-databases.md - - how-to/nosql-databases-couchbase.md - - how-to/graphql.md - - how-to/custom-request-and-route.md - - how-to/conditional-openapi.md - - how-to/extending-openapi.md - - how-to/separate-openapi-schemas.md - - how-to/custom-docs-ui-assets.md - - how-to/configure-swagger-ui.md -- project-generation.md -- alternatives.md -- history-design-future.md -- external-links.md -- benchmarks.md -- help-fastapi.md -- newsletter.md -- contributing.md +- Resources: + - resources/index.md + - project-generation.md + - external-links.md + - newsletter.md +- About: + - about/index.md + - alternatives.md + - history-design-future.md + - benchmarks.md +- Help: + - help/index.md + - help-fastapi.md + - contributing.md - release-notes.md markdown_extensions: toc: diff --git a/fastapi/applications.py b/fastapi/applications.py index 5cc568292..46b7ae81b 100644 --- a/fastapi/applications.py +++ b/fastapi/applications.py @@ -43,57 +43,792 @@ from starlette.requests import Request from starlette.responses import HTMLResponse, JSONResponse, Response from starlette.routing import BaseRoute from starlette.types import ASGIApp, Lifespan, Receive, Scope, Send +from typing_extensions import Annotated, Doc, deprecated # type: ignore [attr-defined] AppType = TypeVar("AppType", bound="FastAPI") class FastAPI(Starlette): + """ + `FastAPI` app class, the main entrypoint to use FastAPI. + + Read more in the + [FastAPI docs for First Steps](https://fastapi.tiangolo.com/tutorial/first-steps/). + + ## Example + + ```python + from fastapi import FastAPI + + app = FastAPI() + ``` + """ + def __init__( self: AppType, *, - debug: bool = False, - routes: Optional[List[BaseRoute]] = None, - title: str = "FastAPI", - summary: Optional[str] = None, - description: str = "", - version: str = "0.1.0", - openapi_url: Optional[str] = "/openapi.json", - openapi_tags: Optional[List[Dict[str, Any]]] = None, - servers: Optional[List[Dict[str, Union[str, Any]]]] = None, - dependencies: Optional[Sequence[Depends]] = None, - default_response_class: Type[Response] = Default(JSONResponse), - redirect_slashes: bool = True, - docs_url: Optional[str] = "/docs", - redoc_url: Optional[str] = "/redoc", - swagger_ui_oauth2_redirect_url: Optional[str] = "/docs/oauth2-redirect", - swagger_ui_init_oauth: Optional[Dict[str, Any]] = None, - middleware: Optional[Sequence[Middleware]] = None, - exception_handlers: Optional[ - Dict[ - Union[int, Type[Exception]], - Callable[[Request, Any], Coroutine[Any, Any, Response]], - ] + debug: Annotated[ + bool, + Doc( + """ + Boolean indicating if debug tracebacks should be returned on server + errors. + + Read more in the + [Starlette docs for Applications](https://www.starlette.io/applications/#instantiating-the-application). + """ + ), + ] = False, + routes: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + **Note**: you probably shouldn't use this parameter, it is inherited + from Starlette and supported for compatibility. + + In FastAPI, you normally would use the *path operation* decorators, + like: + + * `app.get()` + * `app.post()` + * etc. + + --- + + A list of routes to serve incoming HTTP and WebSocket requests. + """ + ), + deprecated( + """ + You normally wouldn't use this parameter with FastAPI, it is inherited + from Starlette and supported for compatibility. + + In FastAPI, you normally would use the *path operation methods*, + like `app.get()`, `app.post()`, etc. + """ + ), ] = None, - on_startup: Optional[Sequence[Callable[[], Any]]] = None, - on_shutdown: Optional[Sequence[Callable[[], Any]]] = None, - lifespan: Optional[Lifespan[AppType]] = None, - terms_of_service: Optional[str] = None, - contact: Optional[Dict[str, Union[str, Any]]] = None, - license_info: Optional[Dict[str, Union[str, Any]]] = None, - openapi_prefix: str = "", - root_path: str = "", - root_path_in_servers: bool = True, - responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, - callbacks: Optional[List[BaseRoute]] = None, - webhooks: Optional[routing.APIRouter] = None, - deprecated: Optional[bool] = None, - include_in_schema: bool = True, - swagger_ui_parameters: Optional[Dict[str, Any]] = None, - generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( - generate_unique_id - ), - separate_input_output_schemas: bool = True, - **extra: Any, + title: Annotated[ + str, + Doc( + """ + The title of the API. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more in the + [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-api). + + **Example** + + ```python + from fastapi import FastAPI + + app = FastAPI(title="ChimichangApp") + ``` + """ + ), + ] = "FastAPI", + summary: Annotated[ + Optional[str], + Doc( + """ + A short summary of the API. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more in the + [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-api). + + **Example** + + ```python + from fastapi import FastAPI + + app = FastAPI(summary="Deadpond's favorite app. Nuff said.") + ``` + """ + ), + ] = None, + description: Annotated[ + str, + Doc( + ''' + A description of the API. Supports Markdown (using + [CommonMark syntax](https://commonmark.org/)). + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more in the + [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-api). + + **Example** + + ```python + from fastapi import FastAPI + + app = FastAPI( + description=""" + ChimichangApp API helps you do awesome stuff. ๐Ÿš€ + + ## Items + + You can **read items**. + + ## Users + + You will be able to: + + * **Create users** (_not implemented_). + * **Read users** (_not implemented_). + + """ + ) + ``` + ''' + ), + ] = "", + version: Annotated[ + str, + Doc( + """ + The version of the API. + + **Note** This is the version of your application, not the version of + the OpenAPI specification nor the version of FastAPI being used. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more in the + [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-api). + + **Example** + + ```python + from fastapi import FastAPI + + app = FastAPI(version="0.0.1") + ``` + """ + ), + ] = "0.1.0", + openapi_url: Annotated[ + Optional[str], + Doc( + """ + The URL where the OpenAPI schema will be served from. + + If you set it to `None`, no OpenAPI schema will be served publicly, and + the default automatic endpoints `/docs` and `/redoc` will also be + disabled. + + Read more in the + [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#openapi-url). + + **Example** + + ```python + from fastapi import FastAPI + + app = FastAPI(openapi_url="/api/v1/openapi.json") + ``` + """ + ), + ] = "/openapi.json", + openapi_tags: Annotated[ + Optional[List[Dict[str, Any]]], + Doc( + """ + A list of tags used by OpenAPI, these are the same `tags` you can set + in the *path operations*, like: + + * `@app.get("/users/", tags=["users"])` + * `@app.get("/items/", tags=["items"])` + + The order of the tags can be used to specify the order shown in + tools like Swagger UI, used in the automatic path `/docs`. + + It's not required to specify all the tags used. + + The tags that are not declared MAY be organized randomly or based + on the tools' logic. Each tag name in the list MUST be unique. + + The value of each item is a `dict` containing: + + * `name`: The name of the tag. + * `description`: A short description of the tag. + [CommonMark syntax](https://commonmark.org/) MAY be used for rich + text representation. + * `externalDocs`: Additional external documentation for this tag. If + provided, it would contain a `dict` with: + * `description`: A short description of the target documentation. + [CommonMark syntax](https://commonmark.org/) MAY be used for + rich text representation. + * `url`: The URL for the target documentation. Value MUST be in + the form of a URL. + + Read more in the + [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-tags). + + **Example** + + ```python + from fastapi import FastAPI + + tags_metadata = [ + { + "name": "users", + "description": "Operations with users. The **login** logic is also here.", + }, + { + "name": "items", + "description": "Manage items. So _fancy_ they have their own docs.", + "externalDocs": { + "description": "Items external docs", + "url": "https://fastapi.tiangolo.com/", + }, + }, + ] + + app = FastAPI(openapi_tags=tags_metadata) + ``` + """ + ), + ] = None, + servers: Annotated[ + Optional[List[Dict[str, Union[str, Any]]]], + Doc( + """ + A `list` of `dict`s with connectivity information to a target server. + + You would use it, for example, if your application is served from + different domains and you want to use the same Swagger UI in the + browser to interact with each of them (instead of having multiple + browser tabs open). Or if you want to leave fixed the possible URLs. + + If the servers `list` is not provided, or is an empty `list`, the + default value would be a a `dict` with a `url` value of `/`. + + Each item in the `list` is a `dict` containing: + + * `url`: A URL to the target host. This URL supports Server Variables + and MAY be relative, to indicate that the host location is relative + to the location where the OpenAPI document is being served. Variable + substitutions will be made when a variable is named in `{`brackets`}`. + * `description`: An optional string describing the host designated by + the URL. [CommonMark syntax](https://commonmark.org/) MAY be used for + rich text representation. + * `variables`: A `dict` between a variable name and its value. The value + is used for substitution in the server's URL template. + + Read more in the + [FastAPI docs for Behind a Proxy](https://fastapi.tiangolo.com/advanced/behind-a-proxy/#additional-servers). + + **Example** + + ```python + from fastapi import FastAPI + + app = FastAPI( + servers=[ + {"url": "https://stag.example.com", "description": "Staging environment"}, + {"url": "https://prod.example.com", "description": "Production environment"}, + ] + ) + ``` + """ + ), + ] = None, + dependencies: Annotated[ + Optional[Sequence[Depends]], + Doc( + """ + A list of global dependencies, they will be applied to each + *path operation*, including in sub-routers. + + Read more about it in the + [FastAPI docs for Global Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/global-dependencies/). + + **Example** + + ```python + from fastapi import Depends, FastAPI + + from .dependencies import func_dep_1, func_dep_2 + + app = FastAPI(dependencies=[Depends(func_dep_1), Depends(func_dep_2)]) + ``` + """ + ), + ] = None, + default_response_class: Annotated[ + Type[Response], + Doc( + """ + The default response class to be used. + + Read more in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#default-response-class). + + **Example** + + ```python + from fastapi import FastAPI + from fastapi.responses import ORJSONResponse + + app = FastAPI(default_response_class=ORJSONResponse) + ``` + """ + ), + ] = Default(JSONResponse), + redirect_slashes: Annotated[ + bool, + Doc( + """ + Whether to detect and redirect slashes in URLs when the client doesn't + use the same format. + + **Example** + + ```python + from fastapi import FastAPI + + app = FastAPI(redirect_slashes=True) # the default + + @app.get("/items/") + async def read_items(): + return [{"item_id": "Foo"}] + ``` + + With this app, if a client goes to `/items` (without a trailing slash), + they will be automatically redirected with an HTTP status code of 307 + to `/items/`. + """ + ), + ] = True, + docs_url: Annotated[ + Optional[str], + Doc( + """ + The path to the automatic interactive API documentation. + It is handled in the browser by Swagger UI. + + The default URL is `/docs`. You can disable it by setting it to `None`. + + If `openapi_url` is set to `None`, this will be automatically disabled. + + Read more in the + [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#docs-urls). + + **Example** + + ```python + from fastapi import FastAPI + + app = FastAPI(docs_url="/documentation", redoc_url=None) + ``` + """ + ), + ] = "/docs", + redoc_url: Annotated[ + Optional[str], + Doc( + """ + The path to the alternative automatic interactive API documentation + provided by ReDoc. + + The default URL is `/redoc`. You can disable it by setting it to `None`. + + If `openapi_url` is set to `None`, this will be automatically disabled. + + Read more in the + [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#docs-urls). + + **Example** + + ```python + from fastapi import FastAPI + + app = FastAPI(docs_url="/documentation", redoc_url="redocumentation") + ``` + """ + ), + ] = "/redoc", + swagger_ui_oauth2_redirect_url: Annotated[ + Optional[str], + Doc( + """ + The OAuth2 redirect endpoint for the Swagger UI. + + By default it is `/docs/oauth2-redirect`. + + This is only used if you use OAuth2 (with the "Authorize" button) + with Swagger UI. + """ + ), + ] = "/docs/oauth2-redirect", + swagger_ui_init_oauth: Annotated[ + Optional[Dict[str, Any]], + Doc( + """ + OAuth2 configuration for the Swagger UI, by default shown at `/docs`. + + Read more about the available configuration options in the + [Swagger UI docs](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/). + """ + ), + ] = None, + middleware: Annotated[ + Optional[Sequence[Middleware]], + Doc( + """ + List of middleware to be added when creating the application. + + In FastAPI you would normally do this with `app.add_middleware()` + instead. + + Read more in the + [FastAPI docs for Middleware](https://fastapi.tiangolo.com/tutorial/middleware/). + """ + ), + ] = None, + exception_handlers: Annotated[ + Optional[ + Dict[ + Union[int, Type[Exception]], + Callable[[Request, Any], Coroutine[Any, Any, Response]], + ] + ], + Doc( + """ + A dictionary with handlers for exceptions. + + In FastAPI, you would normally use the decorator + `@app.exception_handler()`. + + Read more in the + [FastAPI docs for Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/). + """ + ), + ] = None, + on_startup: Annotated[ + Optional[Sequence[Callable[[], Any]]], + Doc( + """ + A list of startup event handler functions. + + You should instead use the `lifespan` handlers. + + Read more in the [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/). + """ + ), + ] = None, + on_shutdown: Annotated[ + Optional[Sequence[Callable[[], Any]]], + Doc( + """ + A list of shutdown event handler functions. + + You should instead use the `lifespan` handlers. + + Read more in the + [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/). + """ + ), + ] = None, + lifespan: Annotated[ + Optional[Lifespan[AppType]], + Doc( + """ + A `Lifespan` context manager handler. This replaces `startup` and + `shutdown` functions with a single context manager. + + Read more in the + [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/). + """ + ), + ] = None, + terms_of_service: Annotated[ + Optional[str], + Doc( + """ + A URL to the Terms of Service for your API. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more at the + [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-api). + + **Example** + + ```python + app = FastAPI(terms_of_service="http://example.com/terms/") + ``` + """ + ), + ] = None, + contact: Annotated[ + Optional[Dict[str, Union[str, Any]]], + Doc( + """ + A dictionary with the contact information for the exposed API. + + It can contain several fields. + + * `name`: (`str`) The name of the contact person/organization. + * `url`: (`str`) A URL pointing to the contact information. MUST be in + the format of a URL. + * `email`: (`str`) The email address of the contact person/organization. + MUST be in the format of an email address. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more at the + [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-api). + + **Example** + + ```python + app = FastAPI( + contact={ + "name": "Deadpoolio the Amazing", + "url": "http://x-force.example.com/contact/", + "email": "dp@x-force.example.com", + } + ) + ``` + """ + ), + ] = None, + license_info: Annotated[ + Optional[Dict[str, Union[str, Any]]], + Doc( + """ + A dictionary with the license information for the exposed API. + + It can contain several fields. + + * `name`: (`str`) **REQUIRED** (if a `license_info` is set). The + license name used for the API. + * `identifier`: (`str`) An [SPDX](https://spdx.dev/) license expression + for the API. The `identifier` field is mutually exclusive of the `url` + field. Available since OpenAPI 3.1.0, FastAPI 0.99.0. + * `url`: (`str`) A URL to the license used for the API. This MUST be + the format of a URL. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more at the + [FastAPI docs for Metadata and Docs URLs](https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-api). + + **Example** + + ```python + app = FastAPI( + license_info={ + "name": "Apache 2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0.html", + } + ) + ``` + """ + ), + ] = None, + openapi_prefix: Annotated[ + str, + Doc( + """ + A URL prefix for the OpenAPI URL. + """ + ), + deprecated( + """ + "openapi_prefix" has been deprecated in favor of "root_path", which + follows more closely the ASGI standard, is simpler, and more + automatic. + """ + ), + ] = "", + root_path: Annotated[ + str, + Doc( + """ + A path prefix handled by a proxy that is not seen by the application + but is seen by external clients, which affects things like Swagger UI. + + Read more about it at the + [FastAPI docs for Behind a Proxy](https://fastapi.tiangolo.com/advanced/behind-a-proxy/). + + **Example** + + ```python + from fastapi import FastAPI + + app = FastAPI(root_path="/api/v1") + ``` + """ + ), + ] = "", + root_path_in_servers: Annotated[ + bool, + Doc( + """ + To disable automatically generating the URLs in the `servers` field + in the autogenerated OpenAPI using the `root_path`. + + Read more about it in the + [FastAPI docs for Behind a Proxy](https://fastapi.tiangolo.com/advanced/behind-a-proxy/#disable-automatic-server-from-root_path). + + **Example** + + ```python + from fastapi import FastAPI + + app = FastAPI(root_path_in_servers=False) + ``` + """ + ), + ] = True, + responses: Annotated[ + Optional[Dict[Union[int, str], Dict[str, Any]]], + Doc( + """ + Additional responses to be shown in OpenAPI. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Additional Responses in OpenAPI](https://fastapi.tiangolo.com/advanced/additional-responses/). + + And in the + [FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies). + """ + ), + ] = None, + callbacks: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + OpenAPI callbacks that should apply to all *path operations*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). + """ + ), + ] = None, + webhooks: Annotated[ + Optional[routing.APIRouter], + Doc( + """ + Add OpenAPI webhooks. This is similar to `callbacks` but it doesn't + depend on specific *path operations*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + **Note**: This is available since OpenAPI 3.1.0, FastAPI 0.99.0. + + Read more about it in the + [FastAPI docs for OpenAPI Webhooks](https://fastapi.tiangolo.com/advanced/openapi-webhooks/). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark all *path operations* as deprecated. You probably don't need it, + but it's available. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + include_in_schema: Annotated[ + bool, + Doc( + """ + To include (or not) all the *path operations* in the generated OpenAPI. + You probably don't need it, but it's available. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi). + """ + ), + ] = True, + swagger_ui_parameters: Annotated[ + Optional[Dict[str, Any]], + Doc( + """ + Parameters to configure Swagger UI, the autogenerated interactive API + documentation (by default at `/docs`). + + Read more about it in the + [FastAPI docs about how to Configure Swagger UI](https://fastapi.tiangolo.com/how-to/configure-swagger-ui/). + """ + ), + ] = None, + generate_unique_id_function: Annotated[ + Callable[[routing.APIRoute], str], + Doc( + """ + Customize the function used to generate unique IDs for the *path + operations* shown in the generated OpenAPI. + + This is particularly useful when automatically generating clients or + SDKs for your API. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = Default(generate_unique_id), + separate_input_output_schemas: Annotated[ + bool, + Doc( + """ + Whether to generate separate OpenAPI schemas for request body and + response body when the results would be more precise. + + This is particularly useful when automatically generating clients. + + For example, if you have a model like: + + ```python + from pydantic import BaseModel + + class Item(BaseModel): + name: str + tags: list[str] = [] + ``` + + When `Item` is used for input, a request body, `tags` is not required, + the client doesn't have to provide it. + + But when using `Item` for output, for a response body, `tags` is always + available because it has a default value, even if it's just an empty + list. So, the client should be able to always expect it. + + In this case, there would be two different schemas, one for input and + another one for output. + """ + ), + ] = True, + **extra: Annotated[ + Any, + Doc( + """ + Extra keyword arguments to be stored in the app, not used by FastAPI + anywhere. + """ + ), + ], ) -> None: self.debug = debug self.title = title @@ -114,7 +849,37 @@ class FastAPI(Starlette): self.servers = servers or [] self.separate_input_output_schemas = separate_input_output_schemas self.extra = extra - self.openapi_version = "3.1.0" + self.openapi_version: Annotated[ + str, + Doc( + """ + The version string of OpenAPI. + + FastAPI will generate OpenAPI version 3.1.0, and will output that as + the OpenAPI version. But some tools, even though they might be + compatible with OpenAPI 3.1.0, might not recognize it as a valid. + + So you could override this value to trick those tools into using + the generated OpenAPI. Have in mind that this is a hack. But if you + avoid using features added in OpenAPI 3.1.0, it might work for your + use case. + + This is not passed as a parameter to the `FastAPI` class to avoid + giving the false idea that FastAPI would generate a different OpenAPI + schema. It is only available as an attribute. + + **Example** + + ```python + from fastapi import FastAPI + + app = FastAPI() + + app.openapi_version = "3.0.2" + ``` + """ + ), + ] = "3.1.0" self.openapi_schema: Optional[Dict[str, Any]] = None if self.openapi_url: assert self.title, "A title must be provided for OpenAPI, e.g.: 'My API'" @@ -127,10 +892,55 @@ class FastAPI(Starlette): "automatic. Check the docs at " "https://fastapi.tiangolo.com/advanced/sub-applications/" ) - self.webhooks = webhooks or routing.APIRouter() + self.webhooks: Annotated[ + routing.APIRouter, + Doc( + """ + The `app.webhooks` attribute is an `APIRouter` with the *path + operations* that will be used just for documentation of webhooks. + + Read more about it in the + [FastAPI docs for OpenAPI Webhooks](https://fastapi.tiangolo.com/advanced/openapi-webhooks/). + """ + ), + ] = ( + webhooks or routing.APIRouter() + ) self.root_path = root_path or openapi_prefix - self.state: State = State() - self.dependency_overrides: Dict[Callable[..., Any], Callable[..., Any]] = {} + self.state: Annotated[ + State, + Doc( + """ + A state object for the application. This is the same object for the + entire application, it doesn't change from request to request. + + You normally woudln't use this in FastAPI, for most of the cases you + would instead use FastAPI dependencies. + + This is simply inherited from Starlette. + + Read more about it in the + [Starlette docs for Applications](https://www.starlette.io/applications/#storing-state-on-the-app-instance). + """ + ), + ] = State() + self.dependency_overrides: Annotated[ + Dict[Callable[..., Any], Callable[..., Any]], + Doc( + """ + A dictionary with overrides for the dependencies. + + Each key is the original dependency callable, and the value is the + actual dependency that should be called. + + This is for testing, to replace expensive dependencies with testing + versions. + + Read more about it in the + [FastAPI docs for Testing Dependencies with Overrides](https://fastapi.tiangolo.com/advanced/testing-dependencies/). + """ + ), + ] = {} self.router: routing.APIRouter = routing.APIRouter( routes=routes, redirect_slashes=redirect_slashes, @@ -215,6 +1025,19 @@ class FastAPI(Starlette): return app def openapi(self) -> Dict[str, Any]: + """ + Generate the OpenAPI schema of the application. This is called by FastAPI + internally. + + The first time it is called it stores the result in the attribute + `app.openapi_schema`, and next times it is called, it just returns that same + result. To avoid the cost of generating the schema every time. + + If you need to modify the generated OpenAPI schema, you could modify it. + + Read more in the + [FastAPI docs for OpenAPI](https://fastapi.tiangolo.com/how-to/extending-openapi/). + """ if not self.openapi_schema: self.openapi_schema = get_openapi( title=self.title, @@ -427,11 +1250,58 @@ class FastAPI(Starlette): def websocket( self, - path: str, - name: Optional[str] = None, + path: Annotated[ + str, + Doc( + """ + WebSocket path. + """ + ), + ], + name: Annotated[ + Optional[str], + Doc( + """ + A name for the WebSocket. Only used internally. + """ + ), + ] = None, *, - dependencies: Optional[Sequence[Depends]] = None, + dependencies: Annotated[ + Optional[Sequence[Depends]], + Doc( + """ + A list of dependencies (using `Depends()`) to be used for this + WebSocket. + + Read more about it in the + [FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/). + """ + ), + ] = None, ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Decorate a WebSocket function. + + Read more about it in the + [FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/). + + **Example** + + ```python + from fastapi import FastAPI, WebSocket + + app = FastAPI() + + @app.websocket("/ws") + async def websocket_endpoint(websocket: WebSocket): + await websocket.accept() + while True: + data = await websocket.receive_text() + await websocket.send_text(f"Message text was: {data}") + ``` + """ + def decorator(func: DecoratedCallable) -> DecoratedCallable: self.add_api_websocket_route( path, @@ -445,62 +1315,556 @@ class FastAPI(Starlette): def include_router( self, - router: routing.APIRouter, + router: Annotated[routing.APIRouter, Doc("The `APIRouter` to include.")], *, - prefix: str = "", - tags: Optional[List[Union[str, Enum]]] = None, - dependencies: Optional[Sequence[Depends]] = None, - responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, - deprecated: Optional[bool] = None, - include_in_schema: bool = True, - default_response_class: Type[Response] = Default(JSONResponse), - callbacks: Optional[List[BaseRoute]] = None, - generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( - generate_unique_id - ), - ) -> None: - self.router.include_router( - router, - prefix=prefix, - tags=tags, - dependencies=dependencies, - responses=responses, - deprecated=deprecated, - include_in_schema=include_in_schema, - default_response_class=default_response_class, - callbacks=callbacks, - generate_unique_id_function=generate_unique_id_function, - ) + prefix: Annotated[str, Doc("An optional path prefix for the router.")] = "", + tags: Annotated[ + Optional[List[Union[str, Enum]]], + Doc( + """ + A list of tags to be applied to all the *path operations* in this + router. - def get( - self, - path: str, - *, - response_model: Any = Default(None), - status_code: Optional[int] = None, - tags: Optional[List[Union[str, Enum]]] = None, - dependencies: Optional[Sequence[Depends]] = None, - summary: Optional[str] = None, - description: Optional[str] = None, - response_description: str = "Successful Response", - responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, - deprecated: Optional[bool] = None, - operation_id: Optional[str] = None, - response_model_include: Optional[IncEx] = None, - response_model_exclude: Optional[IncEx] = None, - response_model_by_alias: bool = True, - response_model_exclude_unset: bool = False, - response_model_exclude_defaults: bool = False, - response_model_exclude_none: bool = False, - include_in_schema: bool = True, - response_class: Type[Response] = Default(JSONResponse), - name: Optional[str] = None, - callbacks: Optional[List[BaseRoute]] = None, - openapi_extra: Optional[Dict[str, Any]] = None, - generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( - generate_unique_id - ), - ) -> Callable[[DecoratedCallable], DecoratedCallable]: + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + dependencies: Annotated[ + Optional[Sequence[Depends]], + Doc( + """ + A list of dependencies (using `Depends()`) to be applied to all the + *path operations* in this router. + + Read more about it in the + [FastAPI docs for Bigger Applications - Multiple Files](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies). + + **Example** + + ```python + from fastapi import Depends, FastAPI + + from .dependencies import get_token_header + from .internal import admin + + app = FastAPI() + + app.include_router( + admin.router, + dependencies=[Depends(get_token_header)], + ) + ``` + """ + ), + ] = None, + responses: Annotated[ + Optional[Dict[Union[int, str], Dict[str, Any]]], + Doc( + """ + Additional responses to be shown in OpenAPI. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Additional Responses in OpenAPI](https://fastapi.tiangolo.com/advanced/additional-responses/). + + And in the + [FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark all the *path operations* in this router as deprecated. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + **Example** + + ```python + from fastapi import FastAPI + + from .internal import old_api + + app = FastAPI() + + app.include_router( + old_api.router, + deprecated=True, + ) + ``` + """ + ), + ] = None, + include_in_schema: Annotated[ + bool, + Doc( + """ + Include (or not) all the *path operations* in this router in the + generated OpenAPI schema. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + + **Example** + + ```python + from fastapi import FastAPI + + from .internal import old_api + + app = FastAPI() + + app.include_router( + old_api.router, + include_in_schema=False, + ) + ``` + """ + ), + ] = True, + default_response_class: Annotated[ + Type[Response], + Doc( + """ + Default response class to be used for the *path operations* in this + router. + + Read more in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#default-response-class). + + **Example** + + ```python + from fastapi import FastAPI + from fastapi.responses import ORJSONResponse + + from .internal import old_api + + app = FastAPI() + + app.include_router( + old_api.router, + default_response_class=ORJSONResponse, + ) + ``` + """ + ), + ] = Default(JSONResponse), + callbacks: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + List of *path operations* that will be used as OpenAPI callbacks. + + This is only for OpenAPI documentation, the callbacks won't be used + directly. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). + """ + ), + ] = None, + generate_unique_id_function: Annotated[ + Callable[[routing.APIRoute], str], + Doc( + """ + Customize the function used to generate unique IDs for the *path + operations* shown in the generated OpenAPI. + + This is particularly useful when automatically generating clients or + SDKs for your API. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = Default(generate_unique_id), + ) -> None: + """ + Include an `APIRouter` in the same app. + + Read more about it in the + [FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/). + + ## Example + + ```python + from fastapi import FastAPI + + from .users import users_router + + app = FastAPI() + + app.include_router(users_router) + ``` + """ + self.router.include_router( + router, + prefix=prefix, + tags=tags, + dependencies=dependencies, + responses=responses, + deprecated=deprecated, + include_in_schema=include_in_schema, + default_response_class=default_response_class, + callbacks=callbacks, + generate_unique_id_function=generate_unique_id_function, + ) + + def get( + self, + path: Annotated[ + str, + Doc( + """ + The URL path to be used for this *path operation*. + + For example, in `http://example.com/items`, the path is `/items`. + """ + ), + ], + *, + response_model: Annotated[ + Any, + Doc( + """ + The type to use for the response. + + It could be any valid Pydantic *field* type. So, it doesn't have to + be a Pydantic model, it could be other things, like a `list`, `dict`, + etc. + + It will be used for: + + * Documentation: the generated OpenAPI (and the UI at `/docs`) will + show it as the response (JSON Schema). + * Serialization: you could return an arbitrary object and the + `response_model` would be used to serialize that object into the + corresponding JSON. + * Filtering: the JSON sent to the client will only contain the data + (fields) defined in the `response_model`. If you returned an object + that contains an attribute `password` but the `response_model` does + not include that field, the JSON sent to the client would not have + that `password`. + * Validation: whatever you return will be serialized with the + `response_model`, converting any data as necessary to generate the + corresponding JSON. But if the data in the object returned is not + valid, that would mean a violation of the contract with the client, + so it's an error from the API developer. So, FastAPI will raise an + error and return a 500 error code (Internal Server Error). + + Read more about it in the + [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). + """ + ), + ] = Default(None), + status_code: Annotated[ + Optional[int], + Doc( + """ + The default status code to be used for the response. + + You could override the status code by returning a response directly. + + Read more about it in the + [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). + """ + ), + ] = None, + tags: Annotated[ + Optional[List[Union[str, Enum]]], + Doc( + """ + A list of tags to be applied to the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). + """ + ), + ] = None, + dependencies: Annotated[ + Optional[Sequence[Depends]], + Doc( + """ + A list of dependencies (using `Depends()`) to be applied to the + *path operation*. + + Read more about it in the + [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). + """ + ), + ] = None, + summary: Annotated[ + Optional[str], + Doc( + """ + A summary for the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + A description for the *path operation*. + + If not provided, it will be extracted automatically from the docstring + of the *path operation function*. + + It can contain Markdown. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + response_description: Annotated[ + str, + Doc( + """ + The description for the default response. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = "Successful Response", + responses: Annotated[ + Optional[Dict[Union[int, str], Dict[str, Any]]], + Doc( + """ + Additional responses that could be returned by this *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this *path operation* as deprecated. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + operation_id: Annotated[ + Optional[str], + Doc( + """ + Custom operation ID to be used by this *path operation*. + + By default, it is generated automatically. + + If you provide a custom operation ID, you need to make sure it is + unique for the whole API. + + You can customize the + operation ID generation with the parameter + `generate_unique_id_function` in the `FastAPI` class. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = None, + response_model_include: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to include only certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_exclude: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to exclude certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_by_alias: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response model + should be serialized by alias when an alias is used. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = True, + response_model_exclude_unset: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that were not set and + have their default values. This is different from + `response_model_exclude_defaults` in that if the fields are set, + they will be included in the response, even if the value is the same + as the default. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_defaults: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that have the same value + as the default. This is different from `response_model_exclude_unset` + in that if the fields are set but contain the same default values, + they will be excluded from the response. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_none: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data should + exclude fields set to `None`. + + This is much simpler (less smart) than `response_model_exclude_unset` + and `response_model_exclude_defaults`. You probably want to use one of + those two instead of this one, as those allow returning `None` values + when it makes sense. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). + """ + ), + ] = False, + include_in_schema: Annotated[ + bool, + Doc( + """ + Include this *path operation* in the generated OpenAPI schema. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi). + """ + ), + ] = True, + response_class: Annotated[ + Type[Response], + Doc( + """ + Response class to be used for this *path operation*. + + This will not be used if you return a response directly. + + Read more about it in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). + """ + ), + ] = Default(JSONResponse), + name: Annotated[ + Optional[str], + Doc( + """ + Name for this *path operation*. Only used internally. + """ + ), + ] = None, + callbacks: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + List of *path operations* that will be used as OpenAPI callbacks. + + This is only for OpenAPI documentation, the callbacks won't be used + directly. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). + """ + ), + ] = None, + openapi_extra: Annotated[ + Optional[Dict[str, Any]], + Doc( + """ + Extra metadata to be included in the OpenAPI schema for this *path + operation*. + + Read more about it in the + [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). + """ + ), + ] = None, + generate_unique_id_function: Annotated[ + Callable[[routing.APIRoute], str], + Doc( + """ + Customize the function used to generate unique IDs for the *path + operations* shown in the generated OpenAPI. + + This is particularly useful when automatically generating clients or + SDKs for your API. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = Default(generate_unique_id), + ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Add a *path operation* using an HTTP GET operation. + + ## Example + + ```python + from fastapi import FastAPI + + app = FastAPI() + + @app.get("/items/") + def read_items(): + return [{"name": "Empanada"}, {"name": "Arepa"}] + ``` + """ return self.router.get( path, response_model=response_model, @@ -529,33 +1893,356 @@ class FastAPI(Starlette): def put( self, - path: str, + path: Annotated[ + str, + Doc( + """ + The URL path to be used for this *path operation*. + + For example, in `http://example.com/items`, the path is `/items`. + """ + ), + ], *, - response_model: Any = Default(None), - status_code: Optional[int] = None, - tags: Optional[List[Union[str, Enum]]] = None, - dependencies: Optional[Sequence[Depends]] = None, - summary: Optional[str] = None, - description: Optional[str] = None, - response_description: str = "Successful Response", - responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, - deprecated: Optional[bool] = None, - operation_id: Optional[str] = None, - response_model_include: Optional[IncEx] = None, - response_model_exclude: Optional[IncEx] = None, - response_model_by_alias: bool = True, - response_model_exclude_unset: bool = False, - response_model_exclude_defaults: bool = False, - response_model_exclude_none: bool = False, - include_in_schema: bool = True, - response_class: Type[Response] = Default(JSONResponse), - name: Optional[str] = None, - callbacks: Optional[List[BaseRoute]] = None, - openapi_extra: Optional[Dict[str, Any]] = None, - generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( - generate_unique_id - ), + response_model: Annotated[ + Any, + Doc( + """ + The type to use for the response. + + It could be any valid Pydantic *field* type. So, it doesn't have to + be a Pydantic model, it could be other things, like a `list`, `dict`, + etc. + + It will be used for: + + * Documentation: the generated OpenAPI (and the UI at `/docs`) will + show it as the response (JSON Schema). + * Serialization: you could return an arbitrary object and the + `response_model` would be used to serialize that object into the + corresponding JSON. + * Filtering: the JSON sent to the client will only contain the data + (fields) defined in the `response_model`. If you returned an object + that contains an attribute `password` but the `response_model` does + not include that field, the JSON sent to the client would not have + that `password`. + * Validation: whatever you return will be serialized with the + `response_model`, converting any data as necessary to generate the + corresponding JSON. But if the data in the object returned is not + valid, that would mean a violation of the contract with the client, + so it's an error from the API developer. So, FastAPI will raise an + error and return a 500 error code (Internal Server Error). + + Read more about it in the + [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). + """ + ), + ] = Default(None), + status_code: Annotated[ + Optional[int], + Doc( + """ + The default status code to be used for the response. + + You could override the status code by returning a response directly. + + Read more about it in the + [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). + """ + ), + ] = None, + tags: Annotated[ + Optional[List[Union[str, Enum]]], + Doc( + """ + A list of tags to be applied to the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). + """ + ), + ] = None, + dependencies: Annotated[ + Optional[Sequence[Depends]], + Doc( + """ + A list of dependencies (using `Depends()`) to be applied to the + *path operation*. + + Read more about it in the + [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). + """ + ), + ] = None, + summary: Annotated[ + Optional[str], + Doc( + """ + A summary for the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + A description for the *path operation*. + + If not provided, it will be extracted automatically from the docstring + of the *path operation function*. + + It can contain Markdown. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + response_description: Annotated[ + str, + Doc( + """ + The description for the default response. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = "Successful Response", + responses: Annotated[ + Optional[Dict[Union[int, str], Dict[str, Any]]], + Doc( + """ + Additional responses that could be returned by this *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this *path operation* as deprecated. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + operation_id: Annotated[ + Optional[str], + Doc( + """ + Custom operation ID to be used by this *path operation*. + + By default, it is generated automatically. + + If you provide a custom operation ID, you need to make sure it is + unique for the whole API. + + You can customize the + operation ID generation with the parameter + `generate_unique_id_function` in the `FastAPI` class. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = None, + response_model_include: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to include only certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_exclude: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to exclude certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_by_alias: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response model + should be serialized by alias when an alias is used. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = True, + response_model_exclude_unset: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that were not set and + have their default values. This is different from + `response_model_exclude_defaults` in that if the fields are set, + they will be included in the response, even if the value is the same + as the default. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_defaults: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that have the same value + as the default. This is different from `response_model_exclude_unset` + in that if the fields are set but contain the same default values, + they will be excluded from the response. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_none: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data should + exclude fields set to `None`. + + This is much simpler (less smart) than `response_model_exclude_unset` + and `response_model_exclude_defaults`. You probably want to use one of + those two instead of this one, as those allow returning `None` values + when it makes sense. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). + """ + ), + ] = False, + include_in_schema: Annotated[ + bool, + Doc( + """ + Include this *path operation* in the generated OpenAPI schema. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi). + """ + ), + ] = True, + response_class: Annotated[ + Type[Response], + Doc( + """ + Response class to be used for this *path operation*. + + This will not be used if you return a response directly. + + Read more about it in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). + """ + ), + ] = Default(JSONResponse), + name: Annotated[ + Optional[str], + Doc( + """ + Name for this *path operation*. Only used internally. + """ + ), + ] = None, + callbacks: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + List of *path operations* that will be used as OpenAPI callbacks. + + This is only for OpenAPI documentation, the callbacks won't be used + directly. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). + """ + ), + ] = None, + openapi_extra: Annotated[ + Optional[Dict[str, Any]], + Doc( + """ + Extra metadata to be included in the OpenAPI schema for this *path + operation*. + + Read more about it in the + [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). + """ + ), + ] = None, + generate_unique_id_function: Annotated[ + Callable[[routing.APIRoute], str], + Doc( + """ + Customize the function used to generate unique IDs for the *path + operations* shown in the generated OpenAPI. + + This is particularly useful when automatically generating clients or + SDKs for your API. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Add a *path operation* using an HTTP PUT operation. + + ## Example + + ```python + from fastapi import FastAPI + from pydantic import BaseModel + + class Item(BaseModel): + name: str + description: str | None = None + + app = FastAPI() + + @app.put("/items/{item_id}") + def replace_item(item_id: str, item: Item): + return {"message": "Item replaced", "id": item_id} + ``` + """ return self.router.put( path, response_model=response_model, @@ -584,33 +2271,356 @@ class FastAPI(Starlette): def post( self, - path: str, + path: Annotated[ + str, + Doc( + """ + The URL path to be used for this *path operation*. + + For example, in `http://example.com/items`, the path is `/items`. + """ + ), + ], *, - response_model: Any = Default(None), - status_code: Optional[int] = None, - tags: Optional[List[Union[str, Enum]]] = None, - dependencies: Optional[Sequence[Depends]] = None, - summary: Optional[str] = None, - description: Optional[str] = None, - response_description: str = "Successful Response", - responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, - deprecated: Optional[bool] = None, - operation_id: Optional[str] = None, - response_model_include: Optional[IncEx] = None, - response_model_exclude: Optional[IncEx] = None, - response_model_by_alias: bool = True, - response_model_exclude_unset: bool = False, - response_model_exclude_defaults: bool = False, - response_model_exclude_none: bool = False, - include_in_schema: bool = True, - response_class: Type[Response] = Default(JSONResponse), - name: Optional[str] = None, - callbacks: Optional[List[BaseRoute]] = None, - openapi_extra: Optional[Dict[str, Any]] = None, - generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( - generate_unique_id - ), + response_model: Annotated[ + Any, + Doc( + """ + The type to use for the response. + + It could be any valid Pydantic *field* type. So, it doesn't have to + be a Pydantic model, it could be other things, like a `list`, `dict`, + etc. + + It will be used for: + + * Documentation: the generated OpenAPI (and the UI at `/docs`) will + show it as the response (JSON Schema). + * Serialization: you could return an arbitrary object and the + `response_model` would be used to serialize that object into the + corresponding JSON. + * Filtering: the JSON sent to the client will only contain the data + (fields) defined in the `response_model`. If you returned an object + that contains an attribute `password` but the `response_model` does + not include that field, the JSON sent to the client would not have + that `password`. + * Validation: whatever you return will be serialized with the + `response_model`, converting any data as necessary to generate the + corresponding JSON. But if the data in the object returned is not + valid, that would mean a violation of the contract with the client, + so it's an error from the API developer. So, FastAPI will raise an + error and return a 500 error code (Internal Server Error). + + Read more about it in the + [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). + """ + ), + ] = Default(None), + status_code: Annotated[ + Optional[int], + Doc( + """ + The default status code to be used for the response. + + You could override the status code by returning a response directly. + + Read more about it in the + [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). + """ + ), + ] = None, + tags: Annotated[ + Optional[List[Union[str, Enum]]], + Doc( + """ + A list of tags to be applied to the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). + """ + ), + ] = None, + dependencies: Annotated[ + Optional[Sequence[Depends]], + Doc( + """ + A list of dependencies (using `Depends()`) to be applied to the + *path operation*. + + Read more about it in the + [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). + """ + ), + ] = None, + summary: Annotated[ + Optional[str], + Doc( + """ + A summary for the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + A description for the *path operation*. + + If not provided, it will be extracted automatically from the docstring + of the *path operation function*. + + It can contain Markdown. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + response_description: Annotated[ + str, + Doc( + """ + The description for the default response. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = "Successful Response", + responses: Annotated[ + Optional[Dict[Union[int, str], Dict[str, Any]]], + Doc( + """ + Additional responses that could be returned by this *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this *path operation* as deprecated. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + operation_id: Annotated[ + Optional[str], + Doc( + """ + Custom operation ID to be used by this *path operation*. + + By default, it is generated automatically. + + If you provide a custom operation ID, you need to make sure it is + unique for the whole API. + + You can customize the + operation ID generation with the parameter + `generate_unique_id_function` in the `FastAPI` class. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = None, + response_model_include: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to include only certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_exclude: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to exclude certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_by_alias: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response model + should be serialized by alias when an alias is used. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = True, + response_model_exclude_unset: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that were not set and + have their default values. This is different from + `response_model_exclude_defaults` in that if the fields are set, + they will be included in the response, even if the value is the same + as the default. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_defaults: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that have the same value + as the default. This is different from `response_model_exclude_unset` + in that if the fields are set but contain the same default values, + they will be excluded from the response. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_none: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data should + exclude fields set to `None`. + + This is much simpler (less smart) than `response_model_exclude_unset` + and `response_model_exclude_defaults`. You probably want to use one of + those two instead of this one, as those allow returning `None` values + when it makes sense. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). + """ + ), + ] = False, + include_in_schema: Annotated[ + bool, + Doc( + """ + Include this *path operation* in the generated OpenAPI schema. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi). + """ + ), + ] = True, + response_class: Annotated[ + Type[Response], + Doc( + """ + Response class to be used for this *path operation*. + + This will not be used if you return a response directly. + + Read more about it in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). + """ + ), + ] = Default(JSONResponse), + name: Annotated[ + Optional[str], + Doc( + """ + Name for this *path operation*. Only used internally. + """ + ), + ] = None, + callbacks: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + List of *path operations* that will be used as OpenAPI callbacks. + + This is only for OpenAPI documentation, the callbacks won't be used + directly. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). + """ + ), + ] = None, + openapi_extra: Annotated[ + Optional[Dict[str, Any]], + Doc( + """ + Extra metadata to be included in the OpenAPI schema for this *path + operation*. + + Read more about it in the + [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). + """ + ), + ] = None, + generate_unique_id_function: Annotated[ + Callable[[routing.APIRoute], str], + Doc( + """ + Customize the function used to generate unique IDs for the *path + operations* shown in the generated OpenAPI. + + This is particularly useful when automatically generating clients or + SDKs for your API. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Add a *path operation* using an HTTP POST operation. + + ## Example + + ```python + from fastapi import FastAPI + from pydantic import BaseModel + + class Item(BaseModel): + name: str + description: str | None = None + + app = FastAPI() + + @app.post("/items/") + def create_item(item: Item): + return {"message": "Item created"} + ``` + """ return self.router.post( path, response_model=response_model, @@ -639,33 +2649,351 @@ class FastAPI(Starlette): def delete( self, - path: str, + path: Annotated[ + str, + Doc( + """ + The URL path to be used for this *path operation*. + + For example, in `http://example.com/items`, the path is `/items`. + """ + ), + ], *, - response_model: Any = Default(None), - status_code: Optional[int] = None, - tags: Optional[List[Union[str, Enum]]] = None, - dependencies: Optional[Sequence[Depends]] = None, - summary: Optional[str] = None, - description: Optional[str] = None, - response_description: str = "Successful Response", - responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, - deprecated: Optional[bool] = None, - operation_id: Optional[str] = None, - response_model_include: Optional[IncEx] = None, - response_model_exclude: Optional[IncEx] = None, - response_model_by_alias: bool = True, - response_model_exclude_unset: bool = False, - response_model_exclude_defaults: bool = False, - response_model_exclude_none: bool = False, - include_in_schema: bool = True, - response_class: Type[Response] = Default(JSONResponse), - name: Optional[str] = None, - callbacks: Optional[List[BaseRoute]] = None, - openapi_extra: Optional[Dict[str, Any]] = None, - generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( - generate_unique_id - ), + response_model: Annotated[ + Any, + Doc( + """ + The type to use for the response. + + It could be any valid Pydantic *field* type. So, it doesn't have to + be a Pydantic model, it could be other things, like a `list`, `dict`, + etc. + + It will be used for: + + * Documentation: the generated OpenAPI (and the UI at `/docs`) will + show it as the response (JSON Schema). + * Serialization: you could return an arbitrary object and the + `response_model` would be used to serialize that object into the + corresponding JSON. + * Filtering: the JSON sent to the client will only contain the data + (fields) defined in the `response_model`. If you returned an object + that contains an attribute `password` but the `response_model` does + not include that field, the JSON sent to the client would not have + that `password`. + * Validation: whatever you return will be serialized with the + `response_model`, converting any data as necessary to generate the + corresponding JSON. But if the data in the object returned is not + valid, that would mean a violation of the contract with the client, + so it's an error from the API developer. So, FastAPI will raise an + error and return a 500 error code (Internal Server Error). + + Read more about it in the + [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). + """ + ), + ] = Default(None), + status_code: Annotated[ + Optional[int], + Doc( + """ + The default status code to be used for the response. + + You could override the status code by returning a response directly. + + Read more about it in the + [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). + """ + ), + ] = None, + tags: Annotated[ + Optional[List[Union[str, Enum]]], + Doc( + """ + A list of tags to be applied to the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). + """ + ), + ] = None, + dependencies: Annotated[ + Optional[Sequence[Depends]], + Doc( + """ + A list of dependencies (using `Depends()`) to be applied to the + *path operation*. + + Read more about it in the + [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). + """ + ), + ] = None, + summary: Annotated[ + Optional[str], + Doc( + """ + A summary for the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + A description for the *path operation*. + + If not provided, it will be extracted automatically from the docstring + of the *path operation function*. + + It can contain Markdown. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + response_description: Annotated[ + str, + Doc( + """ + The description for the default response. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = "Successful Response", + responses: Annotated[ + Optional[Dict[Union[int, str], Dict[str, Any]]], + Doc( + """ + Additional responses that could be returned by this *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this *path operation* as deprecated. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + operation_id: Annotated[ + Optional[str], + Doc( + """ + Custom operation ID to be used by this *path operation*. + + By default, it is generated automatically. + + If you provide a custom operation ID, you need to make sure it is + unique for the whole API. + + You can customize the + operation ID generation with the parameter + `generate_unique_id_function` in the `FastAPI` class. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = None, + response_model_include: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to include only certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_exclude: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to exclude certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_by_alias: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response model + should be serialized by alias when an alias is used. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = True, + response_model_exclude_unset: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that were not set and + have their default values. This is different from + `response_model_exclude_defaults` in that if the fields are set, + they will be included in the response, even if the value is the same + as the default. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_defaults: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that have the same value + as the default. This is different from `response_model_exclude_unset` + in that if the fields are set but contain the same default values, + they will be excluded from the response. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_none: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data should + exclude fields set to `None`. + + This is much simpler (less smart) than `response_model_exclude_unset` + and `response_model_exclude_defaults`. You probably want to use one of + those two instead of this one, as those allow returning `None` values + when it makes sense. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). + """ + ), + ] = False, + include_in_schema: Annotated[ + bool, + Doc( + """ + Include this *path operation* in the generated OpenAPI schema. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi). + """ + ), + ] = True, + response_class: Annotated[ + Type[Response], + Doc( + """ + Response class to be used for this *path operation*. + + This will not be used if you return a response directly. + + Read more about it in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). + """ + ), + ] = Default(JSONResponse), + name: Annotated[ + Optional[str], + Doc( + """ + Name for this *path operation*. Only used internally. + """ + ), + ] = None, + callbacks: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + List of *path operations* that will be used as OpenAPI callbacks. + + This is only for OpenAPI documentation, the callbacks won't be used + directly. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). + """ + ), + ] = None, + openapi_extra: Annotated[ + Optional[Dict[str, Any]], + Doc( + """ + Extra metadata to be included in the OpenAPI schema for this *path + operation*. + + Read more about it in the + [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). + """ + ), + ] = None, + generate_unique_id_function: Annotated[ + Callable[[routing.APIRoute], str], + Doc( + """ + Customize the function used to generate unique IDs for the *path + operations* shown in the generated OpenAPI. + + This is particularly useful when automatically generating clients or + SDKs for your API. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Add a *path operation* using an HTTP DELETE operation. + + ## Example + + ```python + from fastapi import FastAPI + + app = FastAPI() + + @app.delete("/items/{item_id}") + def delete_item(item_id: str): + return {"message": "Item deleted"} + ``` + """ return self.router.delete( path, response_model=response_model, @@ -694,33 +3022,351 @@ class FastAPI(Starlette): def options( self, - path: str, + path: Annotated[ + str, + Doc( + """ + The URL path to be used for this *path operation*. + + For example, in `http://example.com/items`, the path is `/items`. + """ + ), + ], *, - response_model: Any = Default(None), - status_code: Optional[int] = None, - tags: Optional[List[Union[str, Enum]]] = None, - dependencies: Optional[Sequence[Depends]] = None, - summary: Optional[str] = None, - description: Optional[str] = None, - response_description: str = "Successful Response", - responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, - deprecated: Optional[bool] = None, - operation_id: Optional[str] = None, - response_model_include: Optional[IncEx] = None, - response_model_exclude: Optional[IncEx] = None, - response_model_by_alias: bool = True, - response_model_exclude_unset: bool = False, - response_model_exclude_defaults: bool = False, - response_model_exclude_none: bool = False, - include_in_schema: bool = True, - response_class: Type[Response] = Default(JSONResponse), - name: Optional[str] = None, - callbacks: Optional[List[BaseRoute]] = None, - openapi_extra: Optional[Dict[str, Any]] = None, - generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( - generate_unique_id - ), + response_model: Annotated[ + Any, + Doc( + """ + The type to use for the response. + + It could be any valid Pydantic *field* type. So, it doesn't have to + be a Pydantic model, it could be other things, like a `list`, `dict`, + etc. + + It will be used for: + + * Documentation: the generated OpenAPI (and the UI at `/docs`) will + show it as the response (JSON Schema). + * Serialization: you could return an arbitrary object and the + `response_model` would be used to serialize that object into the + corresponding JSON. + * Filtering: the JSON sent to the client will only contain the data + (fields) defined in the `response_model`. If you returned an object + that contains an attribute `password` but the `response_model` does + not include that field, the JSON sent to the client would not have + that `password`. + * Validation: whatever you return will be serialized with the + `response_model`, converting any data as necessary to generate the + corresponding JSON. But if the data in the object returned is not + valid, that would mean a violation of the contract with the client, + so it's an error from the API developer. So, FastAPI will raise an + error and return a 500 error code (Internal Server Error). + + Read more about it in the + [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). + """ + ), + ] = Default(None), + status_code: Annotated[ + Optional[int], + Doc( + """ + The default status code to be used for the response. + + You could override the status code by returning a response directly. + + Read more about it in the + [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). + """ + ), + ] = None, + tags: Annotated[ + Optional[List[Union[str, Enum]]], + Doc( + """ + A list of tags to be applied to the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). + """ + ), + ] = None, + dependencies: Annotated[ + Optional[Sequence[Depends]], + Doc( + """ + A list of dependencies (using `Depends()`) to be applied to the + *path operation*. + + Read more about it in the + [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). + """ + ), + ] = None, + summary: Annotated[ + Optional[str], + Doc( + """ + A summary for the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + A description for the *path operation*. + + If not provided, it will be extracted automatically from the docstring + of the *path operation function*. + + It can contain Markdown. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + response_description: Annotated[ + str, + Doc( + """ + The description for the default response. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = "Successful Response", + responses: Annotated[ + Optional[Dict[Union[int, str], Dict[str, Any]]], + Doc( + """ + Additional responses that could be returned by this *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this *path operation* as deprecated. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + operation_id: Annotated[ + Optional[str], + Doc( + """ + Custom operation ID to be used by this *path operation*. + + By default, it is generated automatically. + + If you provide a custom operation ID, you need to make sure it is + unique for the whole API. + + You can customize the + operation ID generation with the parameter + `generate_unique_id_function` in the `FastAPI` class. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = None, + response_model_include: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to include only certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_exclude: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to exclude certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_by_alias: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response model + should be serialized by alias when an alias is used. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = True, + response_model_exclude_unset: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that were not set and + have their default values. This is different from + `response_model_exclude_defaults` in that if the fields are set, + they will be included in the response, even if the value is the same + as the default. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_defaults: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that have the same value + as the default. This is different from `response_model_exclude_unset` + in that if the fields are set but contain the same default values, + they will be excluded from the response. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_none: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data should + exclude fields set to `None`. + + This is much simpler (less smart) than `response_model_exclude_unset` + and `response_model_exclude_defaults`. You probably want to use one of + those two instead of this one, as those allow returning `None` values + when it makes sense. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). + """ + ), + ] = False, + include_in_schema: Annotated[ + bool, + Doc( + """ + Include this *path operation* in the generated OpenAPI schema. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi). + """ + ), + ] = True, + response_class: Annotated[ + Type[Response], + Doc( + """ + Response class to be used for this *path operation*. + + This will not be used if you return a response directly. + + Read more about it in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). + """ + ), + ] = Default(JSONResponse), + name: Annotated[ + Optional[str], + Doc( + """ + Name for this *path operation*. Only used internally. + """ + ), + ] = None, + callbacks: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + List of *path operations* that will be used as OpenAPI callbacks. + + This is only for OpenAPI documentation, the callbacks won't be used + directly. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). + """ + ), + ] = None, + openapi_extra: Annotated[ + Optional[Dict[str, Any]], + Doc( + """ + Extra metadata to be included in the OpenAPI schema for this *path + operation*. + + Read more about it in the + [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). + """ + ), + ] = None, + generate_unique_id_function: Annotated[ + Callable[[routing.APIRoute], str], + Doc( + """ + Customize the function used to generate unique IDs for the *path + operations* shown in the generated OpenAPI. + + This is particularly useful when automatically generating clients or + SDKs for your API. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Add a *path operation* using an HTTP OPTIONS operation. + + ## Example + + ```python + from fastapi import FastAPI + + app = FastAPI() + + @app.options("/items/") + def get_item_options(): + return {"additions": ["Aji", "Guacamole"]} + ``` + """ return self.router.options( path, response_model=response_model, @@ -747,35 +3393,353 @@ class FastAPI(Starlette): generate_unique_id_function=generate_unique_id_function, ) - def head( - self, - path: str, - *, - response_model: Any = Default(None), - status_code: Optional[int] = None, - tags: Optional[List[Union[str, Enum]]] = None, - dependencies: Optional[Sequence[Depends]] = None, - summary: Optional[str] = None, - description: Optional[str] = None, - response_description: str = "Successful Response", - responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, - deprecated: Optional[bool] = None, - operation_id: Optional[str] = None, - response_model_include: Optional[IncEx] = None, - response_model_exclude: Optional[IncEx] = None, - response_model_by_alias: bool = True, - response_model_exclude_unset: bool = False, - response_model_exclude_defaults: bool = False, - response_model_exclude_none: bool = False, - include_in_schema: bool = True, - response_class: Type[Response] = Default(JSONResponse), - name: Optional[str] = None, - callbacks: Optional[List[BaseRoute]] = None, - openapi_extra: Optional[Dict[str, Any]] = None, - generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( - generate_unique_id - ), + def head( + self, + path: Annotated[ + str, + Doc( + """ + The URL path to be used for this *path operation*. + + For example, in `http://example.com/items`, the path is `/items`. + """ + ), + ], + *, + response_model: Annotated[ + Any, + Doc( + """ + The type to use for the response. + + It could be any valid Pydantic *field* type. So, it doesn't have to + be a Pydantic model, it could be other things, like a `list`, `dict`, + etc. + + It will be used for: + + * Documentation: the generated OpenAPI (and the UI at `/docs`) will + show it as the response (JSON Schema). + * Serialization: you could return an arbitrary object and the + `response_model` would be used to serialize that object into the + corresponding JSON. + * Filtering: the JSON sent to the client will only contain the data + (fields) defined in the `response_model`. If you returned an object + that contains an attribute `password` but the `response_model` does + not include that field, the JSON sent to the client would not have + that `password`. + * Validation: whatever you return will be serialized with the + `response_model`, converting any data as necessary to generate the + corresponding JSON. But if the data in the object returned is not + valid, that would mean a violation of the contract with the client, + so it's an error from the API developer. So, FastAPI will raise an + error and return a 500 error code (Internal Server Error). + + Read more about it in the + [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). + """ + ), + ] = Default(None), + status_code: Annotated[ + Optional[int], + Doc( + """ + The default status code to be used for the response. + + You could override the status code by returning a response directly. + + Read more about it in the + [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). + """ + ), + ] = None, + tags: Annotated[ + Optional[List[Union[str, Enum]]], + Doc( + """ + A list of tags to be applied to the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). + """ + ), + ] = None, + dependencies: Annotated[ + Optional[Sequence[Depends]], + Doc( + """ + A list of dependencies (using `Depends()`) to be applied to the + *path operation*. + + Read more about it in the + [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). + """ + ), + ] = None, + summary: Annotated[ + Optional[str], + Doc( + """ + A summary for the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + A description for the *path operation*. + + If not provided, it will be extracted automatically from the docstring + of the *path operation function*. + + It can contain Markdown. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + response_description: Annotated[ + str, + Doc( + """ + The description for the default response. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = "Successful Response", + responses: Annotated[ + Optional[Dict[Union[int, str], Dict[str, Any]]], + Doc( + """ + Additional responses that could be returned by this *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this *path operation* as deprecated. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + operation_id: Annotated[ + Optional[str], + Doc( + """ + Custom operation ID to be used by this *path operation*. + + By default, it is generated automatically. + + If you provide a custom operation ID, you need to make sure it is + unique for the whole API. + + You can customize the + operation ID generation with the parameter + `generate_unique_id_function` in the `FastAPI` class. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = None, + response_model_include: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to include only certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_exclude: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to exclude certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_by_alias: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response model + should be serialized by alias when an alias is used. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = True, + response_model_exclude_unset: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that were not set and + have their default values. This is different from + `response_model_exclude_defaults` in that if the fields are set, + they will be included in the response, even if the value is the same + as the default. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_defaults: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that have the same value + as the default. This is different from `response_model_exclude_unset` + in that if the fields are set but contain the same default values, + they will be excluded from the response. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_none: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data should + exclude fields set to `None`. + + This is much simpler (less smart) than `response_model_exclude_unset` + and `response_model_exclude_defaults`. You probably want to use one of + those two instead of this one, as those allow returning `None` values + when it makes sense. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). + """ + ), + ] = False, + include_in_schema: Annotated[ + bool, + Doc( + """ + Include this *path operation* in the generated OpenAPI schema. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi). + """ + ), + ] = True, + response_class: Annotated[ + Type[Response], + Doc( + """ + Response class to be used for this *path operation*. + + This will not be used if you return a response directly. + + Read more about it in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). + """ + ), + ] = Default(JSONResponse), + name: Annotated[ + Optional[str], + Doc( + """ + Name for this *path operation*. Only used internally. + """ + ), + ] = None, + callbacks: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + List of *path operations* that will be used as OpenAPI callbacks. + + This is only for OpenAPI documentation, the callbacks won't be used + directly. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). + """ + ), + ] = None, + openapi_extra: Annotated[ + Optional[Dict[str, Any]], + Doc( + """ + Extra metadata to be included in the OpenAPI schema for this *path + operation*. + + Read more about it in the + [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). + """ + ), + ] = None, + generate_unique_id_function: Annotated[ + Callable[[routing.APIRoute], str], + Doc( + """ + Customize the function used to generate unique IDs for the *path + operations* shown in the generated OpenAPI. + + This is particularly useful when automatically generating clients or + SDKs for your API. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Add a *path operation* using an HTTP HEAD operation. + + ## Example + + ```python + from fastapi import FastAPI, Response + + app = FastAPI() + + @app.head("/items/", status_code=204) + def get_items_headers(response: Response): + response.headers["X-Cat-Dog"] = "Alone in the world" + ``` + """ return self.router.head( path, response_model=response_model, @@ -804,33 +3768,356 @@ class FastAPI(Starlette): def patch( self, - path: str, + path: Annotated[ + str, + Doc( + """ + The URL path to be used for this *path operation*. + + For example, in `http://example.com/items`, the path is `/items`. + """ + ), + ], *, - response_model: Any = Default(None), - status_code: Optional[int] = None, - tags: Optional[List[Union[str, Enum]]] = None, - dependencies: Optional[Sequence[Depends]] = None, - summary: Optional[str] = None, - description: Optional[str] = None, - response_description: str = "Successful Response", - responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, - deprecated: Optional[bool] = None, - operation_id: Optional[str] = None, - response_model_include: Optional[IncEx] = None, - response_model_exclude: Optional[IncEx] = None, - response_model_by_alias: bool = True, - response_model_exclude_unset: bool = False, - response_model_exclude_defaults: bool = False, - response_model_exclude_none: bool = False, - include_in_schema: bool = True, - response_class: Type[Response] = Default(JSONResponse), - name: Optional[str] = None, - callbacks: Optional[List[BaseRoute]] = None, - openapi_extra: Optional[Dict[str, Any]] = None, - generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( - generate_unique_id - ), + response_model: Annotated[ + Any, + Doc( + """ + The type to use for the response. + + It could be any valid Pydantic *field* type. So, it doesn't have to + be a Pydantic model, it could be other things, like a `list`, `dict`, + etc. + + It will be used for: + + * Documentation: the generated OpenAPI (and the UI at `/docs`) will + show it as the response (JSON Schema). + * Serialization: you could return an arbitrary object and the + `response_model` would be used to serialize that object into the + corresponding JSON. + * Filtering: the JSON sent to the client will only contain the data + (fields) defined in the `response_model`. If you returned an object + that contains an attribute `password` but the `response_model` does + not include that field, the JSON sent to the client would not have + that `password`. + * Validation: whatever you return will be serialized with the + `response_model`, converting any data as necessary to generate the + corresponding JSON. But if the data in the object returned is not + valid, that would mean a violation of the contract with the client, + so it's an error from the API developer. So, FastAPI will raise an + error and return a 500 error code (Internal Server Error). + + Read more about it in the + [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). + """ + ), + ] = Default(None), + status_code: Annotated[ + Optional[int], + Doc( + """ + The default status code to be used for the response. + + You could override the status code by returning a response directly. + + Read more about it in the + [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). + """ + ), + ] = None, + tags: Annotated[ + Optional[List[Union[str, Enum]]], + Doc( + """ + A list of tags to be applied to the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). + """ + ), + ] = None, + dependencies: Annotated[ + Optional[Sequence[Depends]], + Doc( + """ + A list of dependencies (using `Depends()`) to be applied to the + *path operation*. + + Read more about it in the + [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). + """ + ), + ] = None, + summary: Annotated[ + Optional[str], + Doc( + """ + A summary for the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + A description for the *path operation*. + + If not provided, it will be extracted automatically from the docstring + of the *path operation function*. + + It can contain Markdown. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + response_description: Annotated[ + str, + Doc( + """ + The description for the default response. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = "Successful Response", + responses: Annotated[ + Optional[Dict[Union[int, str], Dict[str, Any]]], + Doc( + """ + Additional responses that could be returned by this *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this *path operation* as deprecated. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + operation_id: Annotated[ + Optional[str], + Doc( + """ + Custom operation ID to be used by this *path operation*. + + By default, it is generated automatically. + + If you provide a custom operation ID, you need to make sure it is + unique for the whole API. + + You can customize the + operation ID generation with the parameter + `generate_unique_id_function` in the `FastAPI` class. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = None, + response_model_include: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to include only certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_exclude: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to exclude certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_by_alias: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response model + should be serialized by alias when an alias is used. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = True, + response_model_exclude_unset: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that were not set and + have their default values. This is different from + `response_model_exclude_defaults` in that if the fields are set, + they will be included in the response, even if the value is the same + as the default. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_defaults: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that have the same value + as the default. This is different from `response_model_exclude_unset` + in that if the fields are set but contain the same default values, + they will be excluded from the response. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_none: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data should + exclude fields set to `None`. + + This is much simpler (less smart) than `response_model_exclude_unset` + and `response_model_exclude_defaults`. You probably want to use one of + those two instead of this one, as those allow returning `None` values + when it makes sense. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). + """ + ), + ] = False, + include_in_schema: Annotated[ + bool, + Doc( + """ + Include this *path operation* in the generated OpenAPI schema. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi). + """ + ), + ] = True, + response_class: Annotated[ + Type[Response], + Doc( + """ + Response class to be used for this *path operation*. + + This will not be used if you return a response directly. + + Read more about it in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). + """ + ), + ] = Default(JSONResponse), + name: Annotated[ + Optional[str], + Doc( + """ + Name for this *path operation*. Only used internally. + """ + ), + ] = None, + callbacks: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + List of *path operations* that will be used as OpenAPI callbacks. + + This is only for OpenAPI documentation, the callbacks won't be used + directly. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). + """ + ), + ] = None, + openapi_extra: Annotated[ + Optional[Dict[str, Any]], + Doc( + """ + Extra metadata to be included in the OpenAPI schema for this *path + operation*. + + Read more about it in the + [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). + """ + ), + ] = None, + generate_unique_id_function: Annotated[ + Callable[[routing.APIRoute], str], + Doc( + """ + Customize the function used to generate unique IDs for the *path + operations* shown in the generated OpenAPI. + + This is particularly useful when automatically generating clients or + SDKs for your API. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Add a *path operation* using an HTTP PATCH operation. + + ## Example + + ```python + from fastapi import FastAPI + from pydantic import BaseModel + + class Item(BaseModel): + name: str + description: str | None = None + + app = FastAPI() + + @app.patch("/items/") + def update_item(item: Item): + return {"message": "Item updated in place"} + ``` + """ return self.router.patch( path, response_model=response_model, @@ -859,33 +4146,351 @@ class FastAPI(Starlette): def trace( self, - path: str, + path: Annotated[ + str, + Doc( + """ + The URL path to be used for this *path operation*. + + For example, in `http://example.com/items`, the path is `/items`. + """ + ), + ], *, - response_model: Any = Default(None), - status_code: Optional[int] = None, - tags: Optional[List[Union[str, Enum]]] = None, - dependencies: Optional[Sequence[Depends]] = None, - summary: Optional[str] = None, - description: Optional[str] = None, - response_description: str = "Successful Response", - responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, - deprecated: Optional[bool] = None, - operation_id: Optional[str] = None, - response_model_include: Optional[IncEx] = None, - response_model_exclude: Optional[IncEx] = None, - response_model_by_alias: bool = True, - response_model_exclude_unset: bool = False, - response_model_exclude_defaults: bool = False, - response_model_exclude_none: bool = False, - include_in_schema: bool = True, - response_class: Type[Response] = Default(JSONResponse), - name: Optional[str] = None, - callbacks: Optional[List[BaseRoute]] = None, - openapi_extra: Optional[Dict[str, Any]] = None, - generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( - generate_unique_id - ), + response_model: Annotated[ + Any, + Doc( + """ + The type to use for the response. + + It could be any valid Pydantic *field* type. So, it doesn't have to + be a Pydantic model, it could be other things, like a `list`, `dict`, + etc. + + It will be used for: + + * Documentation: the generated OpenAPI (and the UI at `/docs`) will + show it as the response (JSON Schema). + * Serialization: you could return an arbitrary object and the + `response_model` would be used to serialize that object into the + corresponding JSON. + * Filtering: the JSON sent to the client will only contain the data + (fields) defined in the `response_model`. If you returned an object + that contains an attribute `password` but the `response_model` does + not include that field, the JSON sent to the client would not have + that `password`. + * Validation: whatever you return will be serialized with the + `response_model`, converting any data as necessary to generate the + corresponding JSON. But if the data in the object returned is not + valid, that would mean a violation of the contract with the client, + so it's an error from the API developer. So, FastAPI will raise an + error and return a 500 error code (Internal Server Error). + + Read more about it in the + [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). + """ + ), + ] = Default(None), + status_code: Annotated[ + Optional[int], + Doc( + """ + The default status code to be used for the response. + + You could override the status code by returning a response directly. + + Read more about it in the + [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). + """ + ), + ] = None, + tags: Annotated[ + Optional[List[Union[str, Enum]]], + Doc( + """ + A list of tags to be applied to the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). + """ + ), + ] = None, + dependencies: Annotated[ + Optional[Sequence[Depends]], + Doc( + """ + A list of dependencies (using `Depends()`) to be applied to the + *path operation*. + + Read more about it in the + [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). + """ + ), + ] = None, + summary: Annotated[ + Optional[str], + Doc( + """ + A summary for the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + A description for the *path operation*. + + If not provided, it will be extracted automatically from the docstring + of the *path operation function*. + + It can contain Markdown. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + response_description: Annotated[ + str, + Doc( + """ + The description for the default response. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = "Successful Response", + responses: Annotated[ + Optional[Dict[Union[int, str], Dict[str, Any]]], + Doc( + """ + Additional responses that could be returned by this *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this *path operation* as deprecated. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + operation_id: Annotated[ + Optional[str], + Doc( + """ + Custom operation ID to be used by this *path operation*. + + By default, it is generated automatically. + + If you provide a custom operation ID, you need to make sure it is + unique for the whole API. + + You can customize the + operation ID generation with the parameter + `generate_unique_id_function` in the `FastAPI` class. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = None, + response_model_include: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to include only certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_exclude: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to exclude certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_by_alias: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response model + should be serialized by alias when an alias is used. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = True, + response_model_exclude_unset: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that were not set and + have their default values. This is different from + `response_model_exclude_defaults` in that if the fields are set, + they will be included in the response, even if the value is the same + as the default. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_defaults: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that have the same value + as the default. This is different from `response_model_exclude_unset` + in that if the fields are set but contain the same default values, + they will be excluded from the response. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_none: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data should + exclude fields set to `None`. + + This is much simpler (less smart) than `response_model_exclude_unset` + and `response_model_exclude_defaults`. You probably want to use one of + those two instead of this one, as those allow returning `None` values + when it makes sense. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). + """ + ), + ] = False, + include_in_schema: Annotated[ + bool, + Doc( + """ + Include this *path operation* in the generated OpenAPI schema. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi). + """ + ), + ] = True, + response_class: Annotated[ + Type[Response], + Doc( + """ + Response class to be used for this *path operation*. + + This will not be used if you return a response directly. + + Read more about it in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). + """ + ), + ] = Default(JSONResponse), + name: Annotated[ + Optional[str], + Doc( + """ + Name for this *path operation*. Only used internally. + """ + ), + ] = None, + callbacks: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + List of *path operations* that will be used as OpenAPI callbacks. + + This is only for OpenAPI documentation, the callbacks won't be used + directly. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). + """ + ), + ] = None, + openapi_extra: Annotated[ + Optional[Dict[str, Any]], + Doc( + """ + Extra metadata to be included in the OpenAPI schema for this *path + operation*. + + Read more about it in the + [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). + """ + ), + ] = None, + generate_unique_id_function: Annotated[ + Callable[[routing.APIRoute], str], + Doc( + """ + Customize the function used to generate unique IDs for the *path + operations* shown in the generated OpenAPI. + + This is particularly useful when automatically generating clients or + SDKs for your API. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Add a *path operation* using an HTTP TRACE operation. + + ## Example + + ```python + from fastapi import FastAPI + + app = FastAPI() + + @app.put("/items/{item_id}") + def trace_item(item_id: str): + return None + ``` + """ return self.router.trace( path, response_model=response_model, @@ -921,14 +4526,72 @@ class FastAPI(Starlette): return decorator + @deprecated( + """ + on_event is deprecated, use lifespan event handlers instead. + + Read more about it in the + [FastAPI docs for Lifespan Events](https://fastapi.tiangolo.com/advanced/events/). + """ + ) def on_event( - self, event_type: str + self, + event_type: Annotated[ + str, + Doc( + """ + The type of event. `startup` or `shutdown`. + """ + ), + ], ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Add an event handler for the application. + + `on_event` is deprecated, use `lifespan` event handlers instead. + + Read more about it in the + [FastAPI docs for Lifespan Events](https://fastapi.tiangolo.com/advanced/events/#alternative-events-deprecated). + """ return self.router.on_event(event_type) def middleware( - self, middleware_type: str + self, + middleware_type: Annotated[ + str, + Doc( + """ + The type of middleware. Currently only supports `http`. + """ + ), + ], ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Add a middleware to the application. + + Read more about it in the + [FastAPI docs for Middleware](https://fastapi.tiangolo.com/tutorial/middleware/). + + ## Example + + ```python + import time + + from fastapi import FastAPI, Request + + app = FastAPI() + + + @app.middleware("http") + async def add_process_time_header(request: Request, call_next): + start_time = time.time() + response = await call_next(request) + process_time = time.time() - start_time + response.headers["X-Process-Time"] = str(process_time) + return response + ``` + """ + def decorator(func: DecoratedCallable) -> DecoratedCallable: self.add_middleware(BaseHTTPMiddleware, dispatch=func) return func @@ -936,8 +4599,46 @@ class FastAPI(Starlette): return decorator def exception_handler( - self, exc_class_or_status_code: Union[int, Type[Exception]] + self, + exc_class_or_status_code: Annotated[ + Union[int, Type[Exception]], + Doc( + """ + The Exception class this would handle, or a status code. + """ + ), + ], ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Add an exception handler to the app. + + Read more about it in the + [FastAPI docs for Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/). + + ## Example + + ```python + from fastapi import FastAPI, Request + from fastapi.responses import JSONResponse + + + class UnicornException(Exception): + def __init__(self, name: str): + self.name = name + + + app = FastAPI() + + + @app.exception_handler(UnicornException) + async def unicorn_exception_handler(request: Request, exc: UnicornException): + return JSONResponse( + status_code=418, + content={"message": f"Oops! {exc.name} did something. There goes a rainbow..."}, + ) + ``` + """ + def decorator(func: DecoratedCallable) -> DecoratedCallable: self.add_exception_handler(exc_class_or_status_code, func) return func diff --git a/fastapi/background.py b/fastapi/background.py index dd3bbe249..35ab1b227 100644 --- a/fastapi/background.py +++ b/fastapi/background.py @@ -1 +1,59 @@ -from starlette.background import BackgroundTasks as BackgroundTasks # noqa +from typing import Any, Callable + +from starlette.background import BackgroundTasks as StarletteBackgroundTasks +from typing_extensions import Annotated, Doc, ParamSpec # type: ignore [attr-defined] + +P = ParamSpec("P") + + +class BackgroundTasks(StarletteBackgroundTasks): + """ + A collection of background tasks that will be called after a response has been + sent to the client. + + Read more about it in the + [FastAPI docs for Background Tasks](https://fastapi.tiangolo.com/tutorial/background-tasks/). + + ## Example + + ```python + from fastapi import BackgroundTasks, FastAPI + + app = FastAPI() + + + def write_notification(email: str, message=""): + with open("log.txt", mode="w") as email_file: + content = f"notification for {email}: {message}" + email_file.write(content) + + + @app.post("/send-notification/{email}") + async def send_notification(email: str, background_tasks: BackgroundTasks): + background_tasks.add_task(write_notification, email, message="some notification") + return {"message": "Notification sent in the background"} + ``` + """ + + def add_task( + self, + func: Annotated[ + Callable[P, Any], + Doc( + """ + The function to call after the response is sent. + + It can be a regular `def` function or an `async def` function. + """ + ), + ], + *args: P.args, + **kwargs: P.kwargs, + ) -> None: + """ + Add a function to be called in the background after the response is sent. + + Read more about it in the + [FastAPI docs for Background Tasks](https://fastapi.tiangolo.com/tutorial/background-tasks/). + """ + return super().add_task(func, *args, **kwargs) diff --git a/fastapi/datastructures.py b/fastapi/datastructures.py index b2865cd40..ce03e3ce4 100644 --- a/fastapi/datastructures.py +++ b/fastapi/datastructures.py @@ -1,4 +1,14 @@ -from typing import Any, Callable, Dict, Iterable, Type, TypeVar, cast +from typing import ( + Any, + BinaryIO, + Callable, + Dict, + Iterable, + Optional, + Type, + TypeVar, + cast, +) from fastapi._compat import ( PYDANTIC_V2, @@ -14,9 +24,120 @@ from starlette.datastructures import Headers as Headers # noqa: F401 from starlette.datastructures import QueryParams as QueryParams # noqa: F401 from starlette.datastructures import State as State # noqa: F401 from starlette.datastructures import UploadFile as StarletteUploadFile +from typing_extensions import Annotated, Doc # type: ignore [attr-defined] class UploadFile(StarletteUploadFile): + """ + A file uploaded in a request. + + Define it as a *path operation function* (or dependency) parameter. + + If you are using a regular `def` function, you can use the `upload_file.file` + attribute to access the raw standard Python file (blocking, not async), useful and + needed for non-async code. + + Read more about it in the + [FastAPI docs for Request Files](https://fastapi.tiangolo.com/tutorial/request-files/). + + ## Example + + ```python + from typing import Annotated + + from fastapi import FastAPI, File, UploadFile + + app = FastAPI() + + + @app.post("/files/") + async def create_file(file: Annotated[bytes, File()]): + return {"file_size": len(file)} + + + @app.post("/uploadfile/") + async def create_upload_file(file: UploadFile): + return {"filename": file.filename} + ``` + """ + + file: Annotated[ + BinaryIO, + Doc("The standard Python file object (non-async)."), + ] + filename: Annotated[Optional[str], Doc("The original file name.")] + size: Annotated[Optional[int], Doc("The size of the file in bytes.")] + headers: Annotated[Headers, Doc("The headers of the request.")] + content_type: Annotated[ + Optional[str], Doc("The content type of the request, from the headers.") + ] + + async def write( + self, + data: Annotated[ + bytes, + Doc( + """ + The bytes to write to the file. + """ + ), + ], + ) -> None: + """ + Write some bytes to the file. + + You normally wouldn't use this from a file you read in a request. + + To be awaitable, compatible with async, this is run in threadpool. + """ + return await super().write(data) + + async def read( + self, + size: Annotated[ + int, + Doc( + """ + The number of bytes to read from the file. + """ + ), + ] = -1, + ) -> bytes: + """ + Read some bytes from the file. + + To be awaitable, compatible with async, this is run in threadpool. + """ + return await super().read(size) + + async def seek( + self, + offset: Annotated[ + int, + Doc( + """ + The position in bytes to seek to in the file. + """ + ), + ], + ) -> None: + """ + Move to a position in the file. + + Any next read or write will be done from that position. + + To be awaitable, compatible with async, this is run in threadpool. + """ + return await super().seek(offset) + + async def close(self) -> None: + """ + Close the file. + + To be awaitable, compatible with async, this is run in threadpool. + """ + return await super().close() + @classmethod def __get_validators__(cls: Type["UploadFile"]) -> Iterable[Callable[..., Any]]: yield cls.validate diff --git a/fastapi/dependencies/utils.py b/fastapi/dependencies/utils.py index e2915268c..96e07a45c 100644 --- a/fastapi/dependencies/utils.py +++ b/fastapi/dependencies/utils.py @@ -44,6 +44,7 @@ from fastapi._compat import ( serialize_sequence_value, value_is_sequence, ) +from fastapi.background import BackgroundTasks from fastapi.concurrency import ( AsyncExitStack, asynccontextmanager, @@ -56,7 +57,7 @@ from fastapi.security.oauth2 import OAuth2, SecurityScopes from fastapi.security.open_id_connect_url import OpenIdConnect from fastapi.utils import create_response_field, get_path_param_names from pydantic.fields import FieldInfo -from starlette.background import BackgroundTasks +from starlette.background import BackgroundTasks as StarletteBackgroundTasks from starlette.concurrency import run_in_threadpool from starlette.datastructures import FormData, Headers, QueryParams, UploadFile from starlette.requests import HTTPConnection, Request @@ -305,7 +306,7 @@ def add_non_field_param_to_dependency( elif lenient_issubclass(type_annotation, Response): dependant.response_param_name = param_name return True - elif lenient_issubclass(type_annotation, BackgroundTasks): + elif lenient_issubclass(type_annotation, StarletteBackgroundTasks): dependant.background_tasks_param_name = param_name return True elif lenient_issubclass(type_annotation, SecurityScopes): @@ -382,7 +383,14 @@ def analyze_param( if lenient_issubclass( type_annotation, - (Request, WebSocket, HTTPConnection, Response, BackgroundTasks, SecurityScopes), + ( + Request, + WebSocket, + HTTPConnection, + Response, + StarletteBackgroundTasks, + SecurityScopes, + ), ): assert depends is None, f"Cannot specify `Depends` for type {type_annotation!r}" assert ( @@ -510,14 +518,14 @@ async def solve_dependencies( request: Union[Request, WebSocket], dependant: Dependant, body: Optional[Union[Dict[str, Any], FormData]] = None, - background_tasks: Optional[BackgroundTasks] = None, + background_tasks: Optional[StarletteBackgroundTasks] = None, response: Optional[Response] = None, dependency_overrides_provider: Optional[Any] = None, dependency_cache: Optional[Dict[Tuple[Callable[..., Any], Tuple[str]], Any]] = None, ) -> Tuple[ Dict[str, Any], List[Any], - Optional[BackgroundTasks], + Optional[StarletteBackgroundTasks], Response, Dict[Tuple[Callable[..., Any], Tuple[str]], Any], ]: diff --git a/fastapi/encoders.py b/fastapi/encoders.py index 30493697e..e50171393 100644 --- a/fastapi/encoders.py +++ b/fastapi/encoders.py @@ -22,6 +22,7 @@ from pydantic import BaseModel from pydantic.color import Color from pydantic.networks import AnyUrl, NameEmail from pydantic.types import SecretBytes, SecretStr +from typing_extensions import Annotated, Doc # type: ignore [attr-defined] from ._compat import PYDANTIC_V2, Url, _model_dump @@ -99,16 +100,107 @@ encoders_by_class_tuples = generate_encoders_by_class_tuples(ENCODERS_BY_TYPE) def jsonable_encoder( - obj: Any, - include: Optional[IncEx] = None, - exclude: Optional[IncEx] = None, - by_alias: bool = True, - exclude_unset: bool = False, - exclude_defaults: bool = False, - exclude_none: bool = False, - custom_encoder: Optional[Dict[Any, Callable[[Any], Any]]] = None, - sqlalchemy_safe: bool = True, + obj: Annotated[ + Any, + Doc( + """ + The input object to convert to JSON. + """ + ), + ], + include: Annotated[ + Optional[IncEx], + Doc( + """ + Pydantic's `include` parameter, passed to Pydantic models to set the + fields to include. + """ + ), + ] = None, + exclude: Annotated[ + Optional[IncEx], + Doc( + """ + Pydantic's `exclude` parameter, passed to Pydantic models to set the + fields to exclude. + """ + ), + ] = None, + by_alias: Annotated[ + bool, + Doc( + """ + Pydantic's `by_alias` parameter, passed to Pydantic models to define if + the output should use the alias names (when provided) or the Python + attribute names. In an API, if you set an alias, it's probably because you + want to use it in the result, so you probably want to leave this set to + `True`. + """ + ), + ] = True, + exclude_unset: Annotated[ + bool, + Doc( + """ + Pydantic's `exclude_unset` parameter, passed to Pydantic models to define + if it should exclude from the output the fields that were not explicitly + set (and that only had their default values). + """ + ), + ] = False, + exclude_defaults: Annotated[ + bool, + Doc( + """ + Pydantic's `exclude_defaults` parameter, passed to Pydantic models to define + if it should exclude from the output the fields that had the same default + value, even when they were explicitly set. + """ + ), + ] = False, + exclude_none: Annotated[ + bool, + Doc( + """ + Pydantic's `exclude_none` parameter, passed to Pydantic models to define + if it should exclude from the output any fields that have a `None` value. + """ + ), + ] = False, + custom_encoder: Annotated[ + Optional[Dict[Any, Callable[[Any], Any]]], + Doc( + """ + Pydantic's `custom_encoder` parameter, passed to Pydantic models to define + a custom encoder. + """ + ), + ] = None, + sqlalchemy_safe: Annotated[ + bool, + Doc( + """ + Exclude from the output any fields that start with the name `_sa`. + + This is mainly a hack for compatibility with SQLAlchemy objects, they + store internal SQLAlchemy-specific state in attributes named with `_sa`, + and those objects can't (and shouldn't be) serialized to JSON. + """ + ), + ] = True, ) -> Any: + """ + Convert any object to something that can be encoded in JSON. + + This is used internally by FastAPI to make sure anything you return can be + encoded as JSON before it is sent to the client. + + You can also use it yourself, for example to convert objects before saving them + in a database that supports only JSON. + + Read more about it in the + [FastAPI docs for JSON Compatible Encoder](https://fastapi.tiangolo.com/tutorial/encoder/). + """ custom_encoder = custom_encoder or {} if custom_encoder: if type(obj) in custom_encoder: diff --git a/fastapi/exceptions.py b/fastapi/exceptions.py index 42f4709fb..680d288e4 100644 --- a/fastapi/exceptions.py +++ b/fastapi/exceptions.py @@ -1,20 +1,141 @@ -from typing import Any, Dict, Optional, Sequence, Type +from typing import Any, Dict, Optional, Sequence, Type, Union from pydantic import BaseModel, create_model from starlette.exceptions import HTTPException as StarletteHTTPException -from starlette.exceptions import WebSocketException as WebSocketException # noqa: F401 +from starlette.exceptions import WebSocketException as StarletteWebSocketException +from typing_extensions import Annotated, Doc # type: ignore [attr-defined] class HTTPException(StarletteHTTPException): + """ + An HTTP exception you can raise in your own code to show errors to the client. + + This is for client errors, invalid authentication, invalid data, etc. Not for server + errors in your code. + + Read more about it in the + [FastAPI docs for Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/). + + ## Example + + ```python + from fastapi import FastAPI, HTTPException + + app = FastAPI() + + items = {"foo": "The Foo Wrestlers"} + + + @app.get("/items/{item_id}") + async def read_item(item_id: str): + if item_id not in items: + raise HTTPException(status_code=404, detail="Item not found") + return {"item": items[item_id]} + ``` + """ + def __init__( self, - status_code: int, - detail: Any = None, - headers: Optional[Dict[str, str]] = None, + status_code: Annotated[ + int, + Doc( + """ + HTTP status code to send to the client. + """ + ), + ], + detail: Annotated[ + Any, + Doc( + """ + Any data to be sent to the client in the `detail` key of the JSON + response. + """ + ), + ] = None, + headers: Annotated[ + Optional[Dict[str, str]], + Doc( + """ + Any headers to send to the client in the response. + """ + ), + ] = None, ) -> None: super().__init__(status_code=status_code, detail=detail, headers=headers) +class WebSocketException(StarletteWebSocketException): + """ + A WebSocket exception you can raise in your own code to show errors to the client. + + This is for client errors, invalid authentication, invalid data, etc. Not for server + errors in your code. + + Read more about it in the + [FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/). + + ## Example + + ```python + from typing import Annotated + + from fastapi import ( + Cookie, + FastAPI, + WebSocket, + WebSocketException, + status, + ) + + app = FastAPI() + + @app.websocket("/items/{item_id}/ws") + async def websocket_endpoint( + *, + websocket: WebSocket, + session: Annotated[str | None, Cookie()] = None, + item_id: str, + ): + if session is None: + raise WebSocketException(code=status.WS_1008_POLICY_VIOLATION) + await websocket.accept() + while True: + data = await websocket.receive_text() + await websocket.send_text(f"Session cookie is: {session}") + await websocket.send_text(f"Message text was: {data}, for item ID: {item_id}") + ``` + """ + + def __init__( + self, + code: Annotated[ + int, + Doc( + """ + A closing code from the + [valid codes defined in the specification](https://datatracker.ietf.org/doc/html/rfc6455#section-7.4.1). + """ + ), + ], + reason: Annotated[ + Union[str, None], + Doc( + """ + The reason to close the WebSocket connection. + + It is UTF-8-encoded data. The interpretation of the reason is up to the + application, it is not specified by the WebSocket specification. + + It could contain text that could be human-readable or interpretable + by the client code, etc. + """ + ), + ] = None, + ) -> None: + super().__init__(code=code, reason=reason) + + RequestErrorModel: Type[BaseModel] = create_model("Request") WebSocketErrorModel: Type[BaseModel] = create_model("WebSocket") diff --git a/fastapi/openapi/docs.py b/fastapi/openapi/docs.py index 81f67dcc5..8cf0d17a1 100644 --- a/fastapi/openapi/docs.py +++ b/fastapi/openapi/docs.py @@ -3,8 +3,18 @@ from typing import Any, Dict, Optional from fastapi.encoders import jsonable_encoder from starlette.responses import HTMLResponse +from typing_extensions import Annotated, Doc # type: ignore [attr-defined] -swagger_ui_default_parameters = { +swagger_ui_default_parameters: Annotated[ + Dict[str, Any], + Doc( + """ + Default configurations for Swagger UI. + + You can use it as a template to add any other configurations needed. + """ + ), +] = { "dom_id": "#swagger-ui", "layout": "BaseLayout", "deepLinking": True, @@ -15,15 +25,91 @@ swagger_ui_default_parameters = { def get_swagger_ui_html( *, - openapi_url: str, - title: str, - swagger_js_url: str = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js", - swagger_css_url: str = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css", - swagger_favicon_url: str = "https://fastapi.tiangolo.com/img/favicon.png", - oauth2_redirect_url: Optional[str] = None, - init_oauth: Optional[Dict[str, Any]] = None, - swagger_ui_parameters: Optional[Dict[str, Any]] = None, + openapi_url: Annotated[ + str, + Doc( + """ + The OpenAPI URL that Swagger UI should load and use. + + This is normally done automatically by FastAPI using the default URL + `/openapi.json`. + """ + ), + ], + title: Annotated[ + str, + Doc( + """ + The HTML `` content, normally shown in the browser tab. + """ + ), + ], + swagger_js_url: Annotated[ + str, + Doc( + """ + The URL to use to load the Swagger UI JavaScript. + + It is normally set to a CDN URL. + """ + ), + ] = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js", + swagger_css_url: Annotated[ + str, + Doc( + """ + The URL to use to load the Swagger UI CSS. + + It is normally set to a CDN URL. + """ + ), + ] = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css", + swagger_favicon_url: Annotated[ + str, + Doc( + """ + The URL of the favicon to use. It is normally shown in the browser tab. + """ + ), + ] = "https://fastapi.tiangolo.com/img/favicon.png", + oauth2_redirect_url: Annotated[ + Optional[str], + Doc( + """ + The OAuth2 redirect URL, it is normally automatically handled by FastAPI. + """ + ), + ] = None, + init_oauth: Annotated[ + Optional[Dict[str, Any]], + Doc( + """ + A dictionary with Swagger UI OAuth2 initialization configurations. + """ + ), + ] = None, + swagger_ui_parameters: Annotated[ + Optional[Dict[str, Any]], + Doc( + """ + Configuration parameters for Swagger UI. + + It defaults to [swagger_ui_default_parameters][fastapi.openapi.docs.swagger_ui_default_parameters]. + """ + ), + ] = None, ) -> HTMLResponse: + """ + Generate and return the HTML that loads Swagger UI for the interactive + API docs (normally served at `/docs`). + + You would only call this function yourself if you needed to override some parts, + for example the URLs to use to load Swagger UI's JavaScript and CSS. + + Read more about it in the + [FastAPI docs for Configure Swagger UI](https://fastapi.tiangolo.com/how-to/configure-swagger-ui/) + and the [FastAPI docs for Custom Docs UI Static Assets (Self-Hosting)](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/). + """ current_swagger_ui_parameters = swagger_ui_default_parameters.copy() if swagger_ui_parameters: current_swagger_ui_parameters.update(swagger_ui_parameters) @@ -74,12 +160,62 @@ def get_swagger_ui_html( def get_redoc_html( *, - openapi_url: str, - title: str, - redoc_js_url: str = "https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js", - redoc_favicon_url: str = "https://fastapi.tiangolo.com/img/favicon.png", - with_google_fonts: bool = True, + openapi_url: Annotated[ + str, + Doc( + """ + The OpenAPI URL that ReDoc should load and use. + + This is normally done automatically by FastAPI using the default URL + `/openapi.json`. + """ + ), + ], + title: Annotated[ + str, + Doc( + """ + The HTML `<title>` content, normally shown in the browser tab. + """ + ), + ], + redoc_js_url: Annotated[ + str, + Doc( + """ + The URL to use to load the ReDoc JavaScript. + + It is normally set to a CDN URL. + """ + ), + ] = "https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js", + redoc_favicon_url: Annotated[ + str, + Doc( + """ + The URL of the favicon to use. It is normally shown in the browser tab. + """ + ), + ] = "https://fastapi.tiangolo.com/img/favicon.png", + with_google_fonts: Annotated[ + bool, + Doc( + """ + Load and use Google Fonts. + """ + ), + ] = True, ) -> HTMLResponse: + """ + Generate and return the HTML response that loads ReDoc for the alternative + API docs (normally served at `/redoc`). + + You would only call this function yourself if you needed to override some parts, + for example the URLs to use to load ReDoc's JavaScript and CSS. + + Read more about it in the + [FastAPI docs for Custom Docs UI Static Assets (Self-Hosting)](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/). + """ html = f""" <!DOCTYPE html> <html> @@ -118,6 +254,11 @@ def get_redoc_html( def get_swagger_ui_oauth2_redirect_html() -> HTMLResponse: + """ + Generate the HTML response with the OAuth2 redirection for Swagger UI. + + You normally don't need to use or change this. + """ # copied from https://github.com/swagger-api/swagger-ui/blob/v4.14.0/dist/oauth2-redirect.html html = """ <!doctype html> diff --git a/fastapi/param_functions.py b/fastapi/param_functions.py index 63914d1d6..3f6dbc959 100644 --- a/fastapi/param_functions.py +++ b/fastapi/param_functions.py @@ -3,43 +3,218 @@ from typing import Any, Callable, Dict, List, Optional, Sequence, Union from fastapi import params from fastapi._compat import Undefined from fastapi.openapi.models import Example -from typing_extensions import Annotated, deprecated +from typing_extensions import Annotated, Doc, deprecated # type: ignore [attr-defined] _Unset: Any = Undefined def Path( # noqa: N802 - default: Any = ..., + default: Annotated[ + Any, + Doc( + """ + Default value if the parameter field is not set. + + This doesn't affect `Path` parameters as the value is always required. + The parameter is available only for compatibility. + """ + ), + ] = ..., *, - default_factory: Union[Callable[[], Any], None] = _Unset, - alias: Optional[str] = None, - alias_priority: Union[int, None] = _Unset, + default_factory: Annotated[ + Union[Callable[[], Any], None], + Doc( + """ + A callable to generate the default value. + + This doesn't affect `Path` parameters as the value is always required. + The parameter is available only for compatibility. + """ + ), + ] = _Unset, + alias: Annotated[ + Optional[str], + Doc( + """ + An alternative name for the parameter field. + + This will be used to extract the data and for the generated OpenAPI. + It is particularly useful when you can't use the name you want because it + is a Python reserved keyword or similar. + """ + ), + ] = None, + alias_priority: Annotated[ + Union[int, None], + Doc( + """ + Priority of the alias. This affects whether an alias generator is used. + """ + ), + ] = _Unset, # TODO: update when deprecating Pydantic v1, import these types # validation_alias: str | AliasPath | AliasChoices | None - validation_alias: Union[str, None] = None, - serialization_alias: Union[str, None] = None, - title: Optional[str] = None, - description: Optional[str] = None, - gt: Optional[float] = None, - ge: Optional[float] = None, - lt: Optional[float] = None, - le: Optional[float] = None, - min_length: Optional[int] = None, - max_length: Optional[int] = None, - pattern: Optional[str] = None, + validation_alias: Annotated[ + Union[str, None], + Doc( + """ + 'Whitelist' validation step. The parameter field will be the single one + allowed by the alias or set of aliases defined. + """ + ), + ] = None, + serialization_alias: Annotated[ + Union[str, None], + Doc( + """ + 'Blacklist' validation step. The vanilla parameter field will be the + single one of the alias' or set of aliases' fields and all the other + fields will be ignored at serialization time. + """ + ), + ] = None, + title: Annotated[ + Optional[str], + Doc( + """ + Human-readable title. + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + Human-readable description. + """ + ), + ] = None, + gt: Annotated[ + Optional[float], + Doc( + """ + Greater than. If set, value must be greater than this. Only applicable to + numbers. + """ + ), + ] = None, + ge: Annotated[ + Optional[float], + Doc( + """ + Greater than or equal. If set, value must be greater than or equal to + this. Only applicable to numbers. + """ + ), + ] = None, + lt: Annotated[ + Optional[float], + Doc( + """ + Less than. If set, value must be less than this. Only applicable to numbers. + """ + ), + ] = None, + le: Annotated[ + Optional[float], + Doc( + """ + Less than or equal. If set, value must be less than or equal to this. + Only applicable to numbers. + """ + ), + ] = None, + min_length: Annotated[ + Optional[int], + Doc( + """ + Minimum length for strings. + """ + ), + ] = None, + max_length: Annotated[ + Optional[int], + Doc( + """ + Maximum length for strings. + """ + ), + ] = None, + pattern: Annotated[ + Optional[str], + Doc( + """ + RegEx pattern for strings. + """ + ), + ] = None, regex: Annotated[ Optional[str], + Doc( + """ + RegEx pattern for strings. + """ + ), deprecated( "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead." ), ] = None, - discriminator: Union[str, None] = None, - strict: Union[bool, None] = _Unset, - multiple_of: Union[float, None] = _Unset, - allow_inf_nan: Union[bool, None] = _Unset, - max_digits: Union[int, None] = _Unset, - decimal_places: Union[int, None] = _Unset, - examples: Optional[List[Any]] = None, + discriminator: Annotated[ + Union[str, None], + Doc( + """ + Parameter field name for discriminating the type in a tagged union. + """ + ), + ] = None, + strict: Annotated[ + Union[bool, None], + Doc( + """ + If `True`, strict validation is applied to the field. + """ + ), + ] = _Unset, + multiple_of: Annotated[ + Union[float, None], + Doc( + """ + Value must be a multiple of this. Only applicable to numbers. + """ + ), + ] = _Unset, + allow_inf_nan: Annotated[ + Union[bool, None], + Doc( + """ + Allow `inf`, `-inf`, `nan`. Only applicable to numbers. + """ + ), + ] = _Unset, + max_digits: Annotated[ + Union[int, None], + Doc( + """ + Maximum number of allow digits for strings. + """ + ), + ] = _Unset, + decimal_places: Annotated[ + Union[int, None], + Doc( + """ + Maximum number of decimal places allowed for numbers. + """ + ), + ] = _Unset, + examples: Annotated[ + Optional[List[Any]], + Doc( + """ + Example values for this field. + """ + ), + ] = None, example: Annotated[ Optional[Any], deprecated( @@ -47,12 +222,87 @@ def Path( # noqa: N802 "although still supported. Use examples instead." ), ] = _Unset, - openapi_examples: Optional[Dict[str, Example]] = None, - deprecated: Optional[bool] = None, - include_in_schema: bool = True, - json_schema_extra: Union[Dict[str, Any], None] = None, - **extra: Any, + openapi_examples: Annotated[ + Optional[Dict[str, Example]], + Doc( + """ + OpenAPI-specific examples. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Swagger UI (that provides the `/docs` interface) has better support for the + OpenAPI-specific examples than the JSON Schema `examples`, that's the main + use case for this. + + Read more about it in the + [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this parameter field as deprecated. + + It will affect the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + include_in_schema: Annotated[ + bool, + Doc( + """ + To include (or not) this parameter field in the generated OpenAPI. + You probably don't need it, but it's available. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = True, + json_schema_extra: Annotated[ + Union[Dict[str, Any], None], + Doc( + """ + Any additional JSON schema data. + """ + ), + ] = None, + **extra: Annotated[ + Any, + Doc( + """ + Include extra fields used by the JSON Schema. + """ + ), + deprecated( + """ + The `extra` kwargs is deprecated. Use `json_schema_extra` instead. + """ + ), + ], ) -> Any: + """ + Declare a path parameter for a *path operation*. + + Read more about it in the + [FastAPI docs for Path Parameters and Numeric Validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/). + + ```python + from typing import Annotated + + from fastapi import FastAPI, Path + + app = FastAPI() + + + @app.get("/items/{item_id}") + async def read_items( + item_id: Annotated[int, Path(title="The ID of the item to get")], + ): + return {"item_id": item_id} + ``` + """ return params.Path( default=default, default_factory=default_factory, @@ -87,37 +337,209 @@ def Path( # noqa: N802 def Query( # noqa: N802 - default: Any = Undefined, + default: Annotated[ + Any, + Doc( + """ + Default value if the parameter field is not set. + """ + ), + ] = Undefined, *, - default_factory: Union[Callable[[], Any], None] = _Unset, - alias: Optional[str] = None, - alias_priority: Union[int, None] = _Unset, + default_factory: Annotated[ + Union[Callable[[], Any], None], + Doc( + """ + A callable to generate the default value. + + This doesn't affect `Path` parameters as the value is always required. + The parameter is available only for compatibility. + """ + ), + ] = _Unset, + alias: Annotated[ + Optional[str], + Doc( + """ + An alternative name for the parameter field. + + This will be used to extract the data and for the generated OpenAPI. + It is particularly useful when you can't use the name you want because it + is a Python reserved keyword or similar. + """ + ), + ] = None, + alias_priority: Annotated[ + Union[int, None], + Doc( + """ + Priority of the alias. This affects whether an alias generator is used. + """ + ), + ] = _Unset, # TODO: update when deprecating Pydantic v1, import these types # validation_alias: str | AliasPath | AliasChoices | None - validation_alias: Union[str, None] = None, - serialization_alias: Union[str, None] = None, - title: Optional[str] = None, - description: Optional[str] = None, - gt: Optional[float] = None, - ge: Optional[float] = None, - lt: Optional[float] = None, - le: Optional[float] = None, - min_length: Optional[int] = None, - max_length: Optional[int] = None, - pattern: Optional[str] = None, + validation_alias: Annotated[ + Union[str, None], + Doc( + """ + 'Whitelist' validation step. The parameter field will be the single one + allowed by the alias or set of aliases defined. + """ + ), + ] = None, + serialization_alias: Annotated[ + Union[str, None], + Doc( + """ + 'Blacklist' validation step. The vanilla parameter field will be the + single one of the alias' or set of aliases' fields and all the other + fields will be ignored at serialization time. + """ + ), + ] = None, + title: Annotated[ + Optional[str], + Doc( + """ + Human-readable title. + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + Human-readable description. + """ + ), + ] = None, + gt: Annotated[ + Optional[float], + Doc( + """ + Greater than. If set, value must be greater than this. Only applicable to + numbers. + """ + ), + ] = None, + ge: Annotated[ + Optional[float], + Doc( + """ + Greater than or equal. If set, value must be greater than or equal to + this. Only applicable to numbers. + """ + ), + ] = None, + lt: Annotated[ + Optional[float], + Doc( + """ + Less than. If set, value must be less than this. Only applicable to numbers. + """ + ), + ] = None, + le: Annotated[ + Optional[float], + Doc( + """ + Less than or equal. If set, value must be less than or equal to this. + Only applicable to numbers. + """ + ), + ] = None, + min_length: Annotated[ + Optional[int], + Doc( + """ + Minimum length for strings. + """ + ), + ] = None, + max_length: Annotated[ + Optional[int], + Doc( + """ + Maximum length for strings. + """ + ), + ] = None, + pattern: Annotated[ + Optional[str], + Doc( + """ + RegEx pattern for strings. + """ + ), + ] = None, regex: Annotated[ Optional[str], + Doc( + """ + RegEx pattern for strings. + """ + ), deprecated( "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead." ), ] = None, - discriminator: Union[str, None] = None, - strict: Union[bool, None] = _Unset, - multiple_of: Union[float, None] = _Unset, - allow_inf_nan: Union[bool, None] = _Unset, - max_digits: Union[int, None] = _Unset, - decimal_places: Union[int, None] = _Unset, - examples: Optional[List[Any]] = None, + discriminator: Annotated[ + Union[str, None], + Doc( + """ + Parameter field name for discriminating the type in a tagged union. + """ + ), + ] = None, + strict: Annotated[ + Union[bool, None], + Doc( + """ + If `True`, strict validation is applied to the field. + """ + ), + ] = _Unset, + multiple_of: Annotated[ + Union[float, None], + Doc( + """ + Value must be a multiple of this. Only applicable to numbers. + """ + ), + ] = _Unset, + allow_inf_nan: Annotated[ + Union[bool, None], + Doc( + """ + Allow `inf`, `-inf`, `nan`. Only applicable to numbers. + """ + ), + ] = _Unset, + max_digits: Annotated[ + Union[int, None], + Doc( + """ + Maximum number of allow digits for strings. + """ + ), + ] = _Unset, + decimal_places: Annotated[ + Union[int, None], + Doc( + """ + Maximum number of decimal places allowed for numbers. + """ + ), + ] = _Unset, + examples: Annotated[ + Optional[List[Any]], + Doc( + """ + Example values for this field. + """ + ), + ] = None, example: Annotated[ Optional[Any], deprecated( @@ -125,11 +547,65 @@ def Query( # noqa: N802 "although still supported. Use examples instead." ), ] = _Unset, - openapi_examples: Optional[Dict[str, Example]] = None, - deprecated: Optional[bool] = None, - include_in_schema: bool = True, - json_schema_extra: Union[Dict[str, Any], None] = None, - **extra: Any, + openapi_examples: Annotated[ + Optional[Dict[str, Example]], + Doc( + """ + OpenAPI-specific examples. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Swagger UI (that provides the `/docs` interface) has better support for the + OpenAPI-specific examples than the JSON Schema `examples`, that's the main + use case for this. + + Read more about it in the + [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this parameter field as deprecated. + + It will affect the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + include_in_schema: Annotated[ + bool, + Doc( + """ + To include (or not) this parameter field in the generated OpenAPI. + You probably don't need it, but it's available. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = True, + json_schema_extra: Annotated[ + Union[Dict[str, Any], None], + Doc( + """ + Any additional JSON schema data. + """ + ), + ] = None, + **extra: Annotated[ + Any, + Doc( + """ + Include extra fields used by the JSON Schema. + """ + ), + deprecated( + """ + The `extra` kwargs is deprecated. Use `json_schema_extra` instead. + """ + ), + ], ) -> Any: return params.Query( default=default, @@ -165,38 +641,220 @@ def Query( # noqa: N802 def Header( # noqa: N802 - default: Any = Undefined, + default: Annotated[ + Any, + Doc( + """ + Default value if the parameter field is not set. + """ + ), + ] = Undefined, *, - default_factory: Union[Callable[[], Any], None] = _Unset, - alias: Optional[str] = None, - alias_priority: Union[int, None] = _Unset, + default_factory: Annotated[ + Union[Callable[[], Any], None], + Doc( + """ + A callable to generate the default value. + + This doesn't affect `Path` parameters as the value is always required. + The parameter is available only for compatibility. + """ + ), + ] = _Unset, + alias: Annotated[ + Optional[str], + Doc( + """ + An alternative name for the parameter field. + + This will be used to extract the data and for the generated OpenAPI. + It is particularly useful when you can't use the name you want because it + is a Python reserved keyword or similar. + """ + ), + ] = None, + alias_priority: Annotated[ + Union[int, None], + Doc( + """ + Priority of the alias. This affects whether an alias generator is used. + """ + ), + ] = _Unset, # TODO: update when deprecating Pydantic v1, import these types # validation_alias: str | AliasPath | AliasChoices | None - validation_alias: Union[str, None] = None, - serialization_alias: Union[str, None] = None, - convert_underscores: bool = True, - title: Optional[str] = None, - description: Optional[str] = None, - gt: Optional[float] = None, - ge: Optional[float] = None, - lt: Optional[float] = None, - le: Optional[float] = None, - min_length: Optional[int] = None, - max_length: Optional[int] = None, - pattern: Optional[str] = None, + validation_alias: Annotated[ + Union[str, None], + Doc( + """ + 'Whitelist' validation step. The parameter field will be the single one + allowed by the alias or set of aliases defined. + """ + ), + ] = None, + serialization_alias: Annotated[ + Union[str, None], + Doc( + """ + 'Blacklist' validation step. The vanilla parameter field will be the + single one of the alias' or set of aliases' fields and all the other + fields will be ignored at serialization time. + """ + ), + ] = None, + convert_underscores: Annotated[ + bool, + Doc( + """ + Automatically convert underscores to hyphens in the parameter field name. + + Read more about it in the + [FastAPI docs for Header Parameters](https://fastapi.tiangolo.com/tutorial/header-params/#automatic-conversion) + """ + ), + ] = True, + title: Annotated[ + Optional[str], + Doc( + """ + Human-readable title. + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + Human-readable description. + """ + ), + ] = None, + gt: Annotated[ + Optional[float], + Doc( + """ + Greater than. If set, value must be greater than this. Only applicable to + numbers. + """ + ), + ] = None, + ge: Annotated[ + Optional[float], + Doc( + """ + Greater than or equal. If set, value must be greater than or equal to + this. Only applicable to numbers. + """ + ), + ] = None, + lt: Annotated[ + Optional[float], + Doc( + """ + Less than. If set, value must be less than this. Only applicable to numbers. + """ + ), + ] = None, + le: Annotated[ + Optional[float], + Doc( + """ + Less than or equal. If set, value must be less than or equal to this. + Only applicable to numbers. + """ + ), + ] = None, + min_length: Annotated[ + Optional[int], + Doc( + """ + Minimum length for strings. + """ + ), + ] = None, + max_length: Annotated[ + Optional[int], + Doc( + """ + Maximum length for strings. + """ + ), + ] = None, + pattern: Annotated[ + Optional[str], + Doc( + """ + RegEx pattern for strings. + """ + ), + ] = None, regex: Annotated[ Optional[str], + Doc( + """ + RegEx pattern for strings. + """ + ), deprecated( "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead." ), ] = None, - discriminator: Union[str, None] = None, - strict: Union[bool, None] = _Unset, - multiple_of: Union[float, None] = _Unset, - allow_inf_nan: Union[bool, None] = _Unset, - max_digits: Union[int, None] = _Unset, - decimal_places: Union[int, None] = _Unset, - examples: Optional[List[Any]] = None, + discriminator: Annotated[ + Union[str, None], + Doc( + """ + Parameter field name for discriminating the type in a tagged union. + """ + ), + ] = None, + strict: Annotated[ + Union[bool, None], + Doc( + """ + If `True`, strict validation is applied to the field. + """ + ), + ] = _Unset, + multiple_of: Annotated[ + Union[float, None], + Doc( + """ + Value must be a multiple of this. Only applicable to numbers. + """ + ), + ] = _Unset, + allow_inf_nan: Annotated[ + Union[bool, None], + Doc( + """ + Allow `inf`, `-inf`, `nan`. Only applicable to numbers. + """ + ), + ] = _Unset, + max_digits: Annotated[ + Union[int, None], + Doc( + """ + Maximum number of allow digits for strings. + """ + ), + ] = _Unset, + decimal_places: Annotated[ + Union[int, None], + Doc( + """ + Maximum number of decimal places allowed for numbers. + """ + ), + ] = _Unset, + examples: Annotated[ + Optional[List[Any]], + Doc( + """ + Example values for this field. + """ + ), + ] = None, example: Annotated[ Optional[Any], deprecated( @@ -204,11 +862,65 @@ def Header( # noqa: N802 "although still supported. Use examples instead." ), ] = _Unset, - openapi_examples: Optional[Dict[str, Example]] = None, - deprecated: Optional[bool] = None, - include_in_schema: bool = True, - json_schema_extra: Union[Dict[str, Any], None] = None, - **extra: Any, + openapi_examples: Annotated[ + Optional[Dict[str, Example]], + Doc( + """ + OpenAPI-specific examples. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Swagger UI (that provides the `/docs` interface) has better support for the + OpenAPI-specific examples than the JSON Schema `examples`, that's the main + use case for this. + + Read more about it in the + [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this parameter field as deprecated. + + It will affect the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + include_in_schema: Annotated[ + bool, + Doc( + """ + To include (or not) this parameter field in the generated OpenAPI. + You probably don't need it, but it's available. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = True, + json_schema_extra: Annotated[ + Union[Dict[str, Any], None], + Doc( + """ + Any additional JSON schema data. + """ + ), + ] = None, + **extra: Annotated[ + Any, + Doc( + """ + Include extra fields used by the JSON Schema. + """ + ), + deprecated( + """ + The `extra` kwargs is deprecated. Use `json_schema_extra` instead. + """ + ), + ], ) -> Any: return params.Header( default=default, @@ -245,37 +957,209 @@ def Header( # noqa: N802 def Cookie( # noqa: N802 - default: Any = Undefined, + default: Annotated[ + Any, + Doc( + """ + Default value if the parameter field is not set. + """ + ), + ] = Undefined, *, - default_factory: Union[Callable[[], Any], None] = _Unset, - alias: Optional[str] = None, - alias_priority: Union[int, None] = _Unset, + default_factory: Annotated[ + Union[Callable[[], Any], None], + Doc( + """ + A callable to generate the default value. + + This doesn't affect `Path` parameters as the value is always required. + The parameter is available only for compatibility. + """ + ), + ] = _Unset, + alias: Annotated[ + Optional[str], + Doc( + """ + An alternative name for the parameter field. + + This will be used to extract the data and for the generated OpenAPI. + It is particularly useful when you can't use the name you want because it + is a Python reserved keyword or similar. + """ + ), + ] = None, + alias_priority: Annotated[ + Union[int, None], + Doc( + """ + Priority of the alias. This affects whether an alias generator is used. + """ + ), + ] = _Unset, # TODO: update when deprecating Pydantic v1, import these types # validation_alias: str | AliasPath | AliasChoices | None - validation_alias: Union[str, None] = None, - serialization_alias: Union[str, None] = None, - title: Optional[str] = None, - description: Optional[str] = None, - gt: Optional[float] = None, - ge: Optional[float] = None, - lt: Optional[float] = None, - le: Optional[float] = None, - min_length: Optional[int] = None, - max_length: Optional[int] = None, - pattern: Optional[str] = None, + validation_alias: Annotated[ + Union[str, None], + Doc( + """ + 'Whitelist' validation step. The parameter field will be the single one + allowed by the alias or set of aliases defined. + """ + ), + ] = None, + serialization_alias: Annotated[ + Union[str, None], + Doc( + """ + 'Blacklist' validation step. The vanilla parameter field will be the + single one of the alias' or set of aliases' fields and all the other + fields will be ignored at serialization time. + """ + ), + ] = None, + title: Annotated[ + Optional[str], + Doc( + """ + Human-readable title. + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + Human-readable description. + """ + ), + ] = None, + gt: Annotated[ + Optional[float], + Doc( + """ + Greater than. If set, value must be greater than this. Only applicable to + numbers. + """ + ), + ] = None, + ge: Annotated[ + Optional[float], + Doc( + """ + Greater than or equal. If set, value must be greater than or equal to + this. Only applicable to numbers. + """ + ), + ] = None, + lt: Annotated[ + Optional[float], + Doc( + """ + Less than. If set, value must be less than this. Only applicable to numbers. + """ + ), + ] = None, + le: Annotated[ + Optional[float], + Doc( + """ + Less than or equal. If set, value must be less than or equal to this. + Only applicable to numbers. + """ + ), + ] = None, + min_length: Annotated[ + Optional[int], + Doc( + """ + Minimum length for strings. + """ + ), + ] = None, + max_length: Annotated[ + Optional[int], + Doc( + """ + Maximum length for strings. + """ + ), + ] = None, + pattern: Annotated[ + Optional[str], + Doc( + """ + RegEx pattern for strings. + """ + ), + ] = None, regex: Annotated[ Optional[str], + Doc( + """ + RegEx pattern for strings. + """ + ), deprecated( "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead." ), ] = None, - discriminator: Union[str, None] = None, - strict: Union[bool, None] = _Unset, - multiple_of: Union[float, None] = _Unset, - allow_inf_nan: Union[bool, None] = _Unset, - max_digits: Union[int, None] = _Unset, - decimal_places: Union[int, None] = _Unset, - examples: Optional[List[Any]] = None, + discriminator: Annotated[ + Union[str, None], + Doc( + """ + Parameter field name for discriminating the type in a tagged union. + """ + ), + ] = None, + strict: Annotated[ + Union[bool, None], + Doc( + """ + If `True`, strict validation is applied to the field. + """ + ), + ] = _Unset, + multiple_of: Annotated[ + Union[float, None], + Doc( + """ + Value must be a multiple of this. Only applicable to numbers. + """ + ), + ] = _Unset, + allow_inf_nan: Annotated[ + Union[bool, None], + Doc( + """ + Allow `inf`, `-inf`, `nan`. Only applicable to numbers. + """ + ), + ] = _Unset, + max_digits: Annotated[ + Union[int, None], + Doc( + """ + Maximum number of allow digits for strings. + """ + ), + ] = _Unset, + decimal_places: Annotated[ + Union[int, None], + Doc( + """ + Maximum number of decimal places allowed for numbers. + """ + ), + ] = _Unset, + examples: Annotated[ + Optional[List[Any]], + Doc( + """ + Example values for this field. + """ + ), + ] = None, example: Annotated[ Optional[Any], deprecated( @@ -283,11 +1167,65 @@ def Cookie( # noqa: N802 "although still supported. Use examples instead." ), ] = _Unset, - openapi_examples: Optional[Dict[str, Example]] = None, - deprecated: Optional[bool] = None, - include_in_schema: bool = True, - json_schema_extra: Union[Dict[str, Any], None] = None, - **extra: Any, + openapi_examples: Annotated[ + Optional[Dict[str, Example]], + Doc( + """ + OpenAPI-specific examples. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Swagger UI (that provides the `/docs` interface) has better support for the + OpenAPI-specific examples than the JSON Schema `examples`, that's the main + use case for this. + + Read more about it in the + [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this parameter field as deprecated. + + It will affect the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + include_in_schema: Annotated[ + bool, + Doc( + """ + To include (or not) this parameter field in the generated OpenAPI. + You probably don't need it, but it's available. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = True, + json_schema_extra: Annotated[ + Union[Dict[str, Any], None], + Doc( + """ + Any additional JSON schema data. + """ + ), + ] = None, + **extra: Annotated[ + Any, + Doc( + """ + Include extra fields used by the JSON Schema. + """ + ), + deprecated( + """ + The `extra` kwargs is deprecated. Use `json_schema_extra` instead. + """ + ), + ], ) -> Any: return params.Cookie( default=default, @@ -323,39 +1261,232 @@ def Cookie( # noqa: N802 def Body( # noqa: N802 - default: Any = Undefined, + default: Annotated[ + Any, + Doc( + """ + Default value if the parameter field is not set. + """ + ), + ] = Undefined, *, - default_factory: Union[Callable[[], Any], None] = _Unset, - embed: bool = False, - media_type: str = "application/json", - alias: Optional[str] = None, - alias_priority: Union[int, None] = _Unset, + default_factory: Annotated[ + Union[Callable[[], Any], None], + Doc( + """ + A callable to generate the default value. + + This doesn't affect `Path` parameters as the value is always required. + The parameter is available only for compatibility. + """ + ), + ] = _Unset, + embed: Annotated[ + bool, + Doc( + """ + When `embed` is `True`, the parameter will be expected in a JSON body as a + key instead of being the JSON body itself. + + This happens automatically when more than one `Body` parameter is declared. + + Read more about it in the + [FastAPI docs for Body - Multiple Parameters](https://fastapi.tiangolo.com/tutorial/body-multiple-params/#embed-a-single-body-parameter). + """ + ), + ] = False, + media_type: Annotated[ + str, + Doc( + """ + The media type of this parameter field. Changing it would affect the + generated OpenAPI, but currently it doesn't affect the parsing of the data. + """ + ), + ] = "application/json", + alias: Annotated[ + Optional[str], + Doc( + """ + An alternative name for the parameter field. + + This will be used to extract the data and for the generated OpenAPI. + It is particularly useful when you can't use the name you want because it + is a Python reserved keyword or similar. + """ + ), + ] = None, + alias_priority: Annotated[ + Union[int, None], + Doc( + """ + Priority of the alias. This affects whether an alias generator is used. + """ + ), + ] = _Unset, # TODO: update when deprecating Pydantic v1, import these types # validation_alias: str | AliasPath | AliasChoices | None - validation_alias: Union[str, None] = None, - serialization_alias: Union[str, None] = None, - title: Optional[str] = None, - description: Optional[str] = None, - gt: Optional[float] = None, - ge: Optional[float] = None, - lt: Optional[float] = None, - le: Optional[float] = None, - min_length: Optional[int] = None, - max_length: Optional[int] = None, - pattern: Optional[str] = None, + validation_alias: Annotated[ + Union[str, None], + Doc( + """ + 'Whitelist' validation step. The parameter field will be the single one + allowed by the alias or set of aliases defined. + """ + ), + ] = None, + serialization_alias: Annotated[ + Union[str, None], + Doc( + """ + 'Blacklist' validation step. The vanilla parameter field will be the + single one of the alias' or set of aliases' fields and all the other + fields will be ignored at serialization time. + """ + ), + ] = None, + title: Annotated[ + Optional[str], + Doc( + """ + Human-readable title. + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + Human-readable description. + """ + ), + ] = None, + gt: Annotated[ + Optional[float], + Doc( + """ + Greater than. If set, value must be greater than this. Only applicable to + numbers. + """ + ), + ] = None, + ge: Annotated[ + Optional[float], + Doc( + """ + Greater than or equal. If set, value must be greater than or equal to + this. Only applicable to numbers. + """ + ), + ] = None, + lt: Annotated[ + Optional[float], + Doc( + """ + Less than. If set, value must be less than this. Only applicable to numbers. + """ + ), + ] = None, + le: Annotated[ + Optional[float], + Doc( + """ + Less than or equal. If set, value must be less than or equal to this. + Only applicable to numbers. + """ + ), + ] = None, + min_length: Annotated[ + Optional[int], + Doc( + """ + Minimum length for strings. + """ + ), + ] = None, + max_length: Annotated[ + Optional[int], + Doc( + """ + Maximum length for strings. + """ + ), + ] = None, + pattern: Annotated[ + Optional[str], + Doc( + """ + RegEx pattern for strings. + """ + ), + ] = None, regex: Annotated[ Optional[str], + Doc( + """ + RegEx pattern for strings. + """ + ), deprecated( "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead." ), ] = None, - discriminator: Union[str, None] = None, - strict: Union[bool, None] = _Unset, - multiple_of: Union[float, None] = _Unset, - allow_inf_nan: Union[bool, None] = _Unset, - max_digits: Union[int, None] = _Unset, - decimal_places: Union[int, None] = _Unset, - examples: Optional[List[Any]] = None, + discriminator: Annotated[ + Union[str, None], + Doc( + """ + Parameter field name for discriminating the type in a tagged union. + """ + ), + ] = None, + strict: Annotated[ + Union[bool, None], + Doc( + """ + If `True`, strict validation is applied to the field. + """ + ), + ] = _Unset, + multiple_of: Annotated[ + Union[float, None], + Doc( + """ + Value must be a multiple of this. Only applicable to numbers. + """ + ), + ] = _Unset, + allow_inf_nan: Annotated[ + Union[bool, None], + Doc( + """ + Allow `inf`, `-inf`, `nan`. Only applicable to numbers. + """ + ), + ] = _Unset, + max_digits: Annotated[ + Union[int, None], + Doc( + """ + Maximum number of allow digits for strings. + """ + ), + ] = _Unset, + decimal_places: Annotated[ + Union[int, None], + Doc( + """ + Maximum number of decimal places allowed for numbers. + """ + ), + ] = _Unset, + examples: Annotated[ + Optional[List[Any]], + Doc( + """ + Example values for this field. + """ + ), + ] = None, example: Annotated[ Optional[Any], deprecated( @@ -363,11 +1494,65 @@ def Body( # noqa: N802 "although still supported. Use examples instead." ), ] = _Unset, - openapi_examples: Optional[Dict[str, Example]] = None, - deprecated: Optional[bool] = None, - include_in_schema: bool = True, - json_schema_extra: Union[Dict[str, Any], None] = None, - **extra: Any, + openapi_examples: Annotated[ + Optional[Dict[str, Example]], + Doc( + """ + OpenAPI-specific examples. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Swagger UI (that provides the `/docs` interface) has better support for the + OpenAPI-specific examples than the JSON Schema `examples`, that's the main + use case for this. + + Read more about it in the + [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this parameter field as deprecated. + + It will affect the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + include_in_schema: Annotated[ + bool, + Doc( + """ + To include (or not) this parameter field in the generated OpenAPI. + You probably don't need it, but it's available. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = True, + json_schema_extra: Annotated[ + Union[Dict[str, Any], None], + Doc( + """ + Any additional JSON schema data. + """ + ), + ] = None, + **extra: Annotated[ + Any, + Doc( + """ + Include extra fields used by the JSON Schema. + """ + ), + deprecated( + """ + The `extra` kwargs is deprecated. Use `json_schema_extra` instead. + """ + ), + ], ) -> Any: return params.Body( default=default, @@ -405,38 +1590,218 @@ def Body( # noqa: N802 def Form( # noqa: N802 - default: Any = Undefined, + default: Annotated[ + Any, + Doc( + """ + Default value if the parameter field is not set. + """ + ), + ] = Undefined, *, - default_factory: Union[Callable[[], Any], None] = _Unset, - media_type: str = "application/x-www-form-urlencoded", - alias: Optional[str] = None, - alias_priority: Union[int, None] = _Unset, + default_factory: Annotated[ + Union[Callable[[], Any], None], + Doc( + """ + A callable to generate the default value. + + This doesn't affect `Path` parameters as the value is always required. + The parameter is available only for compatibility. + """ + ), + ] = _Unset, + media_type: Annotated[ + str, + Doc( + """ + The media type of this parameter field. Changing it would affect the + generated OpenAPI, but currently it doesn't affect the parsing of the data. + """ + ), + ] = "application/x-www-form-urlencoded", + alias: Annotated[ + Optional[str], + Doc( + """ + An alternative name for the parameter field. + + This will be used to extract the data and for the generated OpenAPI. + It is particularly useful when you can't use the name you want because it + is a Python reserved keyword or similar. + """ + ), + ] = None, + alias_priority: Annotated[ + Union[int, None], + Doc( + """ + Priority of the alias. This affects whether an alias generator is used. + """ + ), + ] = _Unset, # TODO: update when deprecating Pydantic v1, import these types # validation_alias: str | AliasPath | AliasChoices | None - validation_alias: Union[str, None] = None, - serialization_alias: Union[str, None] = None, - title: Optional[str] = None, - description: Optional[str] = None, - gt: Optional[float] = None, - ge: Optional[float] = None, - lt: Optional[float] = None, - le: Optional[float] = None, - min_length: Optional[int] = None, - max_length: Optional[int] = None, - pattern: Optional[str] = None, + validation_alias: Annotated[ + Union[str, None], + Doc( + """ + 'Whitelist' validation step. The parameter field will be the single one + allowed by the alias or set of aliases defined. + """ + ), + ] = None, + serialization_alias: Annotated[ + Union[str, None], + Doc( + """ + 'Blacklist' validation step. The vanilla parameter field will be the + single one of the alias' or set of aliases' fields and all the other + fields will be ignored at serialization time. + """ + ), + ] = None, + title: Annotated[ + Optional[str], + Doc( + """ + Human-readable title. + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + Human-readable description. + """ + ), + ] = None, + gt: Annotated[ + Optional[float], + Doc( + """ + Greater than. If set, value must be greater than this. Only applicable to + numbers. + """ + ), + ] = None, + ge: Annotated[ + Optional[float], + Doc( + """ + Greater than or equal. If set, value must be greater than or equal to + this. Only applicable to numbers. + """ + ), + ] = None, + lt: Annotated[ + Optional[float], + Doc( + """ + Less than. If set, value must be less than this. Only applicable to numbers. + """ + ), + ] = None, + le: Annotated[ + Optional[float], + Doc( + """ + Less than or equal. If set, value must be less than or equal to this. + Only applicable to numbers. + """ + ), + ] = None, + min_length: Annotated[ + Optional[int], + Doc( + """ + Minimum length for strings. + """ + ), + ] = None, + max_length: Annotated[ + Optional[int], + Doc( + """ + Maximum length for strings. + """ + ), + ] = None, + pattern: Annotated[ + Optional[str], + Doc( + """ + RegEx pattern for strings. + """ + ), + ] = None, regex: Annotated[ Optional[str], + Doc( + """ + RegEx pattern for strings. + """ + ), deprecated( "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead." ), ] = None, - discriminator: Union[str, None] = None, - strict: Union[bool, None] = _Unset, - multiple_of: Union[float, None] = _Unset, - allow_inf_nan: Union[bool, None] = _Unset, - max_digits: Union[int, None] = _Unset, - decimal_places: Union[int, None] = _Unset, - examples: Optional[List[Any]] = None, + discriminator: Annotated[ + Union[str, None], + Doc( + """ + Parameter field name for discriminating the type in a tagged union. + """ + ), + ] = None, + strict: Annotated[ + Union[bool, None], + Doc( + """ + If `True`, strict validation is applied to the field. + """ + ), + ] = _Unset, + multiple_of: Annotated[ + Union[float, None], + Doc( + """ + Value must be a multiple of this. Only applicable to numbers. + """ + ), + ] = _Unset, + allow_inf_nan: Annotated[ + Union[bool, None], + Doc( + """ + Allow `inf`, `-inf`, `nan`. Only applicable to numbers. + """ + ), + ] = _Unset, + max_digits: Annotated[ + Union[int, None], + Doc( + """ + Maximum number of allow digits for strings. + """ + ), + ] = _Unset, + decimal_places: Annotated[ + Union[int, None], + Doc( + """ + Maximum number of decimal places allowed for numbers. + """ + ), + ] = _Unset, + examples: Annotated[ + Optional[List[Any]], + Doc( + """ + Example values for this field. + """ + ), + ] = None, example: Annotated[ Optional[Any], deprecated( @@ -444,11 +1809,65 @@ def Form( # noqa: N802 "although still supported. Use examples instead." ), ] = _Unset, - openapi_examples: Optional[Dict[str, Example]] = None, - deprecated: Optional[bool] = None, - include_in_schema: bool = True, - json_schema_extra: Union[Dict[str, Any], None] = None, - **extra: Any, + openapi_examples: Annotated[ + Optional[Dict[str, Example]], + Doc( + """ + OpenAPI-specific examples. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Swagger UI (that provides the `/docs` interface) has better support for the + OpenAPI-specific examples than the JSON Schema `examples`, that's the main + use case for this. + + Read more about it in the + [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this parameter field as deprecated. + + It will affect the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + include_in_schema: Annotated[ + bool, + Doc( + """ + To include (or not) this parameter field in the generated OpenAPI. + You probably don't need it, but it's available. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = True, + json_schema_extra: Annotated[ + Union[Dict[str, Any], None], + Doc( + """ + Any additional JSON schema data. + """ + ), + ] = None, + **extra: Annotated[ + Any, + Doc( + """ + Include extra fields used by the JSON Schema. + """ + ), + deprecated( + """ + The `extra` kwargs is deprecated. Use `json_schema_extra` instead. + """ + ), + ], ) -> Any: return params.Form( default=default, @@ -485,38 +1904,218 @@ def Form( # noqa: N802 def File( # noqa: N802 - default: Any = Undefined, + default: Annotated[ + Any, + Doc( + """ + Default value if the parameter field is not set. + """ + ), + ] = Undefined, *, - default_factory: Union[Callable[[], Any], None] = _Unset, - media_type: str = "multipart/form-data", - alias: Optional[str] = None, - alias_priority: Union[int, None] = _Unset, + default_factory: Annotated[ + Union[Callable[[], Any], None], + Doc( + """ + A callable to generate the default value. + + This doesn't affect `Path` parameters as the value is always required. + The parameter is available only for compatibility. + """ + ), + ] = _Unset, + media_type: Annotated[ + str, + Doc( + """ + The media type of this parameter field. Changing it would affect the + generated OpenAPI, but currently it doesn't affect the parsing of the data. + """ + ), + ] = "multipart/form-data", + alias: Annotated[ + Optional[str], + Doc( + """ + An alternative name for the parameter field. + + This will be used to extract the data and for the generated OpenAPI. + It is particularly useful when you can't use the name you want because it + is a Python reserved keyword or similar. + """ + ), + ] = None, + alias_priority: Annotated[ + Union[int, None], + Doc( + """ + Priority of the alias. This affects whether an alias generator is used. + """ + ), + ] = _Unset, # TODO: update when deprecating Pydantic v1, import these types # validation_alias: str | AliasPath | AliasChoices | None - validation_alias: Union[str, None] = None, - serialization_alias: Union[str, None] = None, - title: Optional[str] = None, - description: Optional[str] = None, - gt: Optional[float] = None, - ge: Optional[float] = None, - lt: Optional[float] = None, - le: Optional[float] = None, - min_length: Optional[int] = None, - max_length: Optional[int] = None, - pattern: Optional[str] = None, + validation_alias: Annotated[ + Union[str, None], + Doc( + """ + 'Whitelist' validation step. The parameter field will be the single one + allowed by the alias or set of aliases defined. + """ + ), + ] = None, + serialization_alias: Annotated[ + Union[str, None], + Doc( + """ + 'Blacklist' validation step. The vanilla parameter field will be the + single one of the alias' or set of aliases' fields and all the other + fields will be ignored at serialization time. + """ + ), + ] = None, + title: Annotated[ + Optional[str], + Doc( + """ + Human-readable title. + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + Human-readable description. + """ + ), + ] = None, + gt: Annotated[ + Optional[float], + Doc( + """ + Greater than. If set, value must be greater than this. Only applicable to + numbers. + """ + ), + ] = None, + ge: Annotated[ + Optional[float], + Doc( + """ + Greater than or equal. If set, value must be greater than or equal to + this. Only applicable to numbers. + """ + ), + ] = None, + lt: Annotated[ + Optional[float], + Doc( + """ + Less than. If set, value must be less than this. Only applicable to numbers. + """ + ), + ] = None, + le: Annotated[ + Optional[float], + Doc( + """ + Less than or equal. If set, value must be less than or equal to this. + Only applicable to numbers. + """ + ), + ] = None, + min_length: Annotated[ + Optional[int], + Doc( + """ + Minimum length for strings. + """ + ), + ] = None, + max_length: Annotated[ + Optional[int], + Doc( + """ + Maximum length for strings. + """ + ), + ] = None, + pattern: Annotated[ + Optional[str], + Doc( + """ + RegEx pattern for strings. + """ + ), + ] = None, regex: Annotated[ Optional[str], + Doc( + """ + RegEx pattern for strings. + """ + ), deprecated( "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead." ), ] = None, - discriminator: Union[str, None] = None, - strict: Union[bool, None] = _Unset, - multiple_of: Union[float, None] = _Unset, - allow_inf_nan: Union[bool, None] = _Unset, - max_digits: Union[int, None] = _Unset, - decimal_places: Union[int, None] = _Unset, - examples: Optional[List[Any]] = None, + discriminator: Annotated[ + Union[str, None], + Doc( + """ + Parameter field name for discriminating the type in a tagged union. + """ + ), + ] = None, + strict: Annotated[ + Union[bool, None], + Doc( + """ + If `True`, strict validation is applied to the field. + """ + ), + ] = _Unset, + multiple_of: Annotated[ + Union[float, None], + Doc( + """ + Value must be a multiple of this. Only applicable to numbers. + """ + ), + ] = _Unset, + allow_inf_nan: Annotated[ + Union[bool, None], + Doc( + """ + Allow `inf`, `-inf`, `nan`. Only applicable to numbers. + """ + ), + ] = _Unset, + max_digits: Annotated[ + Union[int, None], + Doc( + """ + Maximum number of allow digits for strings. + """ + ), + ] = _Unset, + decimal_places: Annotated[ + Union[int, None], + Doc( + """ + Maximum number of decimal places allowed for numbers. + """ + ), + ] = _Unset, + examples: Annotated[ + Optional[List[Any]], + Doc( + """ + Example values for this field. + """ + ), + ] = None, example: Annotated[ Optional[Any], deprecated( @@ -524,11 +2123,65 @@ def File( # noqa: N802 "although still supported. Use examples instead." ), ] = _Unset, - openapi_examples: Optional[Dict[str, Example]] = None, - deprecated: Optional[bool] = None, - include_in_schema: bool = True, - json_schema_extra: Union[Dict[str, Any], None] = None, - **extra: Any, + openapi_examples: Annotated[ + Optional[Dict[str, Example]], + Doc( + """ + OpenAPI-specific examples. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Swagger UI (that provides the `/docs` interface) has better support for the + OpenAPI-specific examples than the JSON Schema `examples`, that's the main + use case for this. + + Read more about it in the + [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this parameter field as deprecated. + + It will affect the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + include_in_schema: Annotated[ + bool, + Doc( + """ + To include (or not) this parameter field in the generated OpenAPI. + You probably don't need it, but it's available. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = True, + json_schema_extra: Annotated[ + Union[Dict[str, Any], None], + Doc( + """ + Any additional JSON schema data. + """ + ), + ] = None, + **extra: Annotated[ + Any, + Doc( + """ + Include extra fields used by the JSON Schema. + """ + ), + deprecated( + """ + The `extra` kwargs is deprecated. Use `json_schema_extra` instead. + """ + ), + ], ) -> Any: return params.File( default=default, @@ -565,15 +2218,143 @@ def File( # noqa: N802 def Depends( # noqa: N802 - dependency: Optional[Callable[..., Any]] = None, *, use_cache: bool = True + dependency: Annotated[ + Optional[Callable[..., Any]], + Doc( + """ + A "dependable" callable (like a function). + + Don't call it directly, FastAPI will call it for you, just pass the object + directly. + """ + ), + ] = None, + *, + use_cache: Annotated[ + bool, + Doc( + """ + By default, after a dependency is called the first time in a request, if + the dependency is declared again for the rest of the request (for example + if the dependency is needed by several dependencies), the value will be + re-used for the rest of the request. + + Set `use_cache` to `False` to disable this behavior and ensure the + dependency is called again (if declared more than once) in the same request. + """ + ), + ] = True, ) -> Any: + """ + Declare a FastAPI dependency. + + It takes a single "dependable" callable (like a function). + + Don't call it directly, FastAPI will call it for you. + + Read more about it in the + [FastAPI docs for Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/). + + **Example** + + ```python + from typing import Annotated + + from fastapi import Depends, FastAPI + + app = FastAPI() + + + async def common_parameters(q: str | None = None, skip: int = 0, limit: int = 100): + return {"q": q, "skip": skip, "limit": limit} + + + @app.get("/items/") + async def read_items(commons: Annotated[dict, Depends(common_parameters)]): + return commons + ``` + """ return params.Depends(dependency=dependency, use_cache=use_cache) def Security( # noqa: N802 - dependency: Optional[Callable[..., Any]] = None, + dependency: Annotated[ + Optional[Callable[..., Any]], + Doc( + """ + A "dependable" callable (like a function). + + Don't call it directly, FastAPI will call it for you, just pass the object + directly. + """ + ), + ] = None, *, - scopes: Optional[Sequence[str]] = None, - use_cache: bool = True, + scopes: Annotated[ + Optional[Sequence[str]], + Doc( + """ + OAuth2 scopes required for the *path operation* that uses this Security + dependency. + + The term "scope" comes from the OAuth2 specification, it seems to be + intentionaly vague and interpretable. It normally refers to permissions, + in cases to roles. + + These scopes are integrated with OpenAPI (and the API docs at `/docs`). + So they are visible in the OpenAPI specification. + ) + """ + ), + ] = None, + use_cache: Annotated[ + bool, + Doc( + """ + By default, after a dependency is called the first time in a request, if + the dependency is declared again for the rest of the request (for example + if the dependency is needed by several dependencies), the value will be + re-used for the rest of the request. + + Set `use_cache` to `False` to disable this behavior and ensure the + dependency is called again (if declared more than once) in the same request. + """ + ), + ] = True, ) -> Any: + """ + Declare a FastAPI Security dependency. + + The only difference with a regular dependency is that it can declare OAuth2 + scopes that will be integrated with OpenAPI and the automatic UI docs (by default + at `/docs`). + + It takes a single "dependable" callable (like a function). + + Don't call it directly, FastAPI will call it for you. + + Read more about it in the + [FastAPI docs for Security](https://fastapi.tiangolo.com/tutorial/security/) and + in the + [FastAPI docs for OAuth2 scopes](https://fastapi.tiangolo.com/advanced/security/oauth2-scopes/). + + **Example** + + ```python + from typing import Annotated + + from fastapi import Depends, FastAPI + + from .db import User + from .security import get_current_active_user + + app = FastAPI() + + @app.get("/users/me/items/") + async def read_own_items( + current_user: Annotated[User, Security(get_current_active_user, scopes=["items"])] + ): + return [{"item_id": "Foo", "owner": current_user.username}] + ``` + """ return params.Security(dependency=dependency, scopes=scopes, use_cache=use_cache) diff --git a/fastapi/responses.py b/fastapi/responses.py index c0a13b755..6c8db6f33 100644 --- a/fastapi/responses.py +++ b/fastapi/responses.py @@ -21,12 +21,26 @@ except ImportError: # pragma: nocover class UJSONResponse(JSONResponse): + """ + JSON response using the high-performance ujson library to serialize data to JSON. + + Read more about it in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/). + """ + def render(self, content: Any) -> bytes: assert ujson is not None, "ujson must be installed to use UJSONResponse" return ujson.dumps(content, ensure_ascii=False).encode("utf-8") class ORJSONResponse(JSONResponse): + """ + JSON response using the high-performance orjson library to serialize data to JSON. + + Read more about it in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/). + """ + def render(self, content: Any) -> bytes: assert orjson is not None, "orjson must be installed to use ORJSONResponse" return orjson.dumps( diff --git a/fastapi/routing.py b/fastapi/routing.py index 1e3dfb4d5..e33e1d832 100644 --- a/fastapi/routing.py +++ b/fastapi/routing.py @@ -69,6 +69,7 @@ from starlette.routing import ( from starlette.routing import Mount as Mount # noqa from starlette.types import ASGIApp, Lifespan, Scope from starlette.websockets import WebSocket +from typing_extensions import Annotated, Doc, deprecated # type: ignore [attr-defined] def _prepare_response_content( @@ -519,30 +520,253 @@ class APIRoute(routing.Route): class APIRouter(routing.Router): + """ + `APIRouter` class, used to group *path operations*, for example to structure + an app in multiple files. It would then be included in the `FastAPI` app, or + in another `APIRouter` (ultimately included in the app). + + Read more about it in the + [FastAPI docs for Bigger Applications - Multiple Files](https://fastapi.tiangolo.com/tutorial/bigger-applications/). + + ## Example + + ```python + from fastapi import APIRouter, FastAPI + + app = FastAPI() + router = APIRouter() + + + @router.get("/users/", tags=["users"]) + async def read_users(): + return [{"username": "Rick"}, {"username": "Morty"}] + + + app.include_router(router) + ``` + """ + def __init__( self, *, - prefix: str = "", - tags: Optional[List[Union[str, Enum]]] = None, - dependencies: Optional[Sequence[params.Depends]] = None, - default_response_class: Type[Response] = Default(JSONResponse), - responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, - callbacks: Optional[List[BaseRoute]] = None, - routes: Optional[List[routing.BaseRoute]] = None, - redirect_slashes: bool = True, - default: Optional[ASGIApp] = None, - dependency_overrides_provider: Optional[Any] = None, - route_class: Type[APIRoute] = APIRoute, - on_startup: Optional[Sequence[Callable[[], Any]]] = None, - on_shutdown: Optional[Sequence[Callable[[], Any]]] = None, + prefix: Annotated[str, Doc("An optional path prefix for the router.")] = "", + tags: Annotated[ + Optional[List[Union[str, Enum]]], + Doc( + """ + A list of tags to be applied to all the *path operations* in this + router. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + dependencies: Annotated[ + Optional[Sequence[params.Depends]], + Doc( + """ + A list of dependencies (using `Depends()`) to be applied to all the + *path operations* in this router. + + Read more about it in the + [FastAPI docs for Bigger Applications - Multiple Files](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies). + """ + ), + ] = None, + default_response_class: Annotated[ + Type[Response], + Doc( + """ + The default response class to be used. + + Read more in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#default-response-class). + """ + ), + ] = Default(JSONResponse), + responses: Annotated[ + Optional[Dict[Union[int, str], Dict[str, Any]]], + Doc( + """ + Additional responses to be shown in OpenAPI. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Additional Responses in OpenAPI](https://fastapi.tiangolo.com/advanced/additional-responses/). + + And in the + [FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies). + """ + ), + ] = None, + callbacks: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + OpenAPI callbacks that should apply to all *path operations* in this + router. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). + """ + ), + ] = None, + routes: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + **Note**: you probably shouldn't use this parameter, it is inherited + from Starlette and supported for compatibility. + + In FastAPI, you normally would use the *path operation* decorators, + like: + + * `router.get()` + * `router.post()` + * etc. + + --- + + A list of routes to serve incoming HTTP and WebSocket requests. + """ + ), + deprecated( + """ + You normally wouldn't use this parameter with FastAPI, it is inherited + from Starlette and supported for compatibility. + + In FastAPI, you normally would use the *path operation methods*, + like `router.get()`, `router.post()`, etc. + """ + ), + ] = None, + redirect_slashes: Annotated[ + bool, + Doc( + """ + Whether to detect and redirect slashes in URLs when the client doesn't + use the same format. + """ + ), + ] = True, + default: Annotated[ + Optional[ASGIApp], + Doc( + """ + Default function handler for this router. Used to handle + 404 Not Found errors. + """ + ), + ] = None, + dependency_overrides_provider: Annotated[ + Optional[Any], + Doc( + """ + Only used internally by FastAPI to handle dependency overrides. + + You shouldn't need to use it. It normally points to the `FastAPI` app + object. + """ + ), + ] = None, + route_class: Annotated[ + Type[APIRoute], + Doc( + """ + Custom route (*path operation*) class to be used by this router. + + Read more about it in the + [FastAPI docs for Custom Request and APIRoute class](https://fastapi.tiangolo.com/how-to/custom-request-and-route/#custom-apiroute-class-in-a-router). + """ + ), + ] = APIRoute, + on_startup: Annotated[ + Optional[Sequence[Callable[[], Any]]], + Doc( + """ + A list of startup event handler functions. + + You should instead use the `lifespan` handlers. + + Read more in the [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/). + """ + ), + ] = None, + on_shutdown: Annotated[ + Optional[Sequence[Callable[[], Any]]], + Doc( + """ + A list of shutdown event handler functions. + + You should instead use the `lifespan` handlers. + + Read more in the + [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/). + """ + ), + ] = None, # the generic to Lifespan[AppType] is the type of the top level application # which the router cannot know statically, so we use typing.Any - lifespan: Optional[Lifespan[Any]] = None, - deprecated: Optional[bool] = None, - include_in_schema: bool = True, - generate_unique_id_function: Callable[[APIRoute], str] = Default( - generate_unique_id - ), + lifespan: Annotated[ + Optional[Lifespan[Any]], + Doc( + """ + A `Lifespan` context manager handler. This replaces `startup` and + `shutdown` functions with a single context manager. + + Read more in the + [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark all *path operations* in this router as deprecated. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + include_in_schema: Annotated[ + bool, + Doc( + """ + To include (or not) all the *path operations* in this router in the + generated OpenAPI. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi). + """ + ), + ] = True, + generate_unique_id_function: Annotated[ + Callable[[APIRoute], str], + Doc( + """ + Customize the function used to generate unique IDs for the *path + operations* shown in the generated OpenAPI. + + This is particularly useful when automatically generating clients or + SDKs for your API. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = Default(generate_unique_id), ) -> None: super().__init__( routes=routes, @@ -755,11 +979,63 @@ class APIRouter(routing.Router): def websocket( self, - path: str, - name: Optional[str] = None, + path: Annotated[ + str, + Doc( + """ + WebSocket path. + """ + ), + ], + name: Annotated[ + Optional[str], + Doc( + """ + A name for the WebSocket. Only used internally. + """ + ), + ] = None, *, - dependencies: Optional[Sequence[params.Depends]] = None, + dependencies: Annotated[ + Optional[Sequence[params.Depends]], + Doc( + """ + A list of dependencies (using `Depends()`) to be used for this + WebSocket. + + Read more about it in the + [FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/). + """ + ), + ] = None, ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Decorate a WebSocket function. + + Read more about it in the + [FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/). + + **Example** + + ## Example + + ```python + from fastapi import APIRouter, FastAPI, WebSocket + + app = FastAPI() + router = APIRouter() + + @router.websocket("/ws") + async def websocket_endpoint(websocket: WebSocket): + await websocket.accept() + while True: + data = await websocket.receive_text() + await websocket.send_text(f"Message text was: {data}") + + app.include_router(router) + ``` + """ + def decorator(func: DecoratedCallable) -> DecoratedCallable: self.add_api_websocket_route( path, func, name=name, dependencies=dependencies @@ -779,20 +1055,139 @@ class APIRouter(routing.Router): def include_router( self, - router: "APIRouter", + router: Annotated["APIRouter", Doc("The `APIRouter` to include.")], *, - prefix: str = "", - tags: Optional[List[Union[str, Enum]]] = None, - dependencies: Optional[Sequence[params.Depends]] = None, - default_response_class: Type[Response] = Default(JSONResponse), - responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, - callbacks: Optional[List[BaseRoute]] = None, - deprecated: Optional[bool] = None, - include_in_schema: bool = True, - generate_unique_id_function: Callable[[APIRoute], str] = Default( - generate_unique_id - ), + prefix: Annotated[str, Doc("An optional path prefix for the router.")] = "", + tags: Annotated[ + Optional[List[Union[str, Enum]]], + Doc( + """ + A list of tags to be applied to all the *path operations* in this + router. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + dependencies: Annotated[ + Optional[Sequence[params.Depends]], + Doc( + """ + A list of dependencies (using `Depends()`) to be applied to all the + *path operations* in this router. + + Read more about it in the + [FastAPI docs for Bigger Applications - Multiple Files](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies). + """ + ), + ] = None, + default_response_class: Annotated[ + Type[Response], + Doc( + """ + The default response class to be used. + + Read more in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#default-response-class). + """ + ), + ] = Default(JSONResponse), + responses: Annotated[ + Optional[Dict[Union[int, str], Dict[str, Any]]], + Doc( + """ + Additional responses to be shown in OpenAPI. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Additional Responses in OpenAPI](https://fastapi.tiangolo.com/advanced/additional-responses/). + + And in the + [FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies). + """ + ), + ] = None, + callbacks: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + OpenAPI callbacks that should apply to all *path operations* in this + router. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark all *path operations* in this router as deprecated. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + include_in_schema: Annotated[ + bool, + Doc( + """ + Include (or not) all the *path operations* in this router in the + generated OpenAPI schema. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = True, + generate_unique_id_function: Annotated[ + Callable[[APIRoute], str], + Doc( + """ + Customize the function used to generate unique IDs for the *path + operations* shown in the generated OpenAPI. + + This is particularly useful when automatically generating clients or + SDKs for your API. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = Default(generate_unique_id), ) -> None: + """ + Include another `APIRouter` in the same current `APIRouter`. + + Read more about it in the + [FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/). + + ## Example + + ```python + from fastapi import APIRouter, FastAPI + + app = FastAPI() + internal_router = APIRouter() + users_router = APIRouter() + + @users_router.get("/users/") + def read_users(): + return [{"name": "Rick"}, {"name": "Morty"}] + + internal_router.include_router(users_router) + app.include_router(internal_router) + ``` + """ if prefix: assert prefix.startswith("/"), "A path prefix must start with '/'" assert not prefix.endswith( @@ -900,33 +1295,354 @@ class APIRouter(routing.Router): def get( self, - path: str, + path: Annotated[ + str, + Doc( + """ + The URL path to be used for this *path operation*. + + For example, in `http://example.com/items`, the path is `/items`. + """ + ), + ], *, - response_model: Any = Default(None), - status_code: Optional[int] = None, - tags: Optional[List[Union[str, Enum]]] = None, - dependencies: Optional[Sequence[params.Depends]] = None, - summary: Optional[str] = None, - description: Optional[str] = None, - response_description: str = "Successful Response", - responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, - deprecated: Optional[bool] = None, - operation_id: Optional[str] = None, - response_model_include: Optional[IncEx] = None, - response_model_exclude: Optional[IncEx] = None, - response_model_by_alias: bool = True, - response_model_exclude_unset: bool = False, - response_model_exclude_defaults: bool = False, - response_model_exclude_none: bool = False, - include_in_schema: bool = True, - response_class: Type[Response] = Default(JSONResponse), - name: Optional[str] = None, - callbacks: Optional[List[BaseRoute]] = None, - openapi_extra: Optional[Dict[str, Any]] = None, - generate_unique_id_function: Callable[[APIRoute], str] = Default( - generate_unique_id - ), + response_model: Annotated[ + Any, + Doc( + """ + The type to use for the response. + + It could be any valid Pydantic *field* type. So, it doesn't have to + be a Pydantic model, it could be other things, like a `list`, `dict`, + etc. + + It will be used for: + + * Documentation: the generated OpenAPI (and the UI at `/docs`) will + show it as the response (JSON Schema). + * Serialization: you could return an arbitrary object and the + `response_model` would be used to serialize that object into the + corresponding JSON. + * Filtering: the JSON sent to the client will only contain the data + (fields) defined in the `response_model`. If you returned an object + that contains an attribute `password` but the `response_model` does + not include that field, the JSON sent to the client would not have + that `password`. + * Validation: whatever you return will be serialized with the + `response_model`, converting any data as necessary to generate the + corresponding JSON. But if the data in the object returned is not + valid, that would mean a violation of the contract with the client, + so it's an error from the API developer. So, FastAPI will raise an + error and return a 500 error code (Internal Server Error). + + Read more about it in the + [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). + """ + ), + ] = Default(None), + status_code: Annotated[ + Optional[int], + Doc( + """ + The default status code to be used for the response. + + You could override the status code by returning a response directly. + + Read more about it in the + [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). + """ + ), + ] = None, + tags: Annotated[ + Optional[List[Union[str, Enum]]], + Doc( + """ + A list of tags to be applied to the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). + """ + ), + ] = None, + dependencies: Annotated[ + Optional[Sequence[params.Depends]], + Doc( + """ + A list of dependencies (using `Depends()`) to be applied to the + *path operation*. + + Read more about it in the + [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). + """ + ), + ] = None, + summary: Annotated[ + Optional[str], + Doc( + """ + A summary for the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + A description for the *path operation*. + + If not provided, it will be extracted automatically from the docstring + of the *path operation function*. + + It can contain Markdown. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + response_description: Annotated[ + str, + Doc( + """ + The description for the default response. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = "Successful Response", + responses: Annotated[ + Optional[Dict[Union[int, str], Dict[str, Any]]], + Doc( + """ + Additional responses that could be returned by this *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this *path operation* as deprecated. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + operation_id: Annotated[ + Optional[str], + Doc( + """ + Custom operation ID to be used by this *path operation*. + + By default, it is generated automatically. + + If you provide a custom operation ID, you need to make sure it is + unique for the whole API. + + You can customize the + operation ID generation with the parameter + `generate_unique_id_function` in the `FastAPI` class. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = None, + response_model_include: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to include only certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_exclude: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to exclude certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_by_alias: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response model + should be serialized by alias when an alias is used. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = True, + response_model_exclude_unset: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that were not set and + have their default values. This is different from + `response_model_exclude_defaults` in that if the fields are set, + they will be included in the response, even if the value is the same + as the default. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_defaults: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that have the same value + as the default. This is different from `response_model_exclude_unset` + in that if the fields are set but contain the same default values, + they will be excluded from the response. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_none: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data should + exclude fields set to `None`. + + This is much simpler (less smart) than `response_model_exclude_unset` + and `response_model_exclude_defaults`. You probably want to use one of + those two instead of this one, as those allow returning `None` values + when it makes sense. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). + """ + ), + ] = False, + include_in_schema: Annotated[ + bool, + Doc( + """ + Include this *path operation* in the generated OpenAPI schema. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi). + """ + ), + ] = True, + response_class: Annotated[ + Type[Response], + Doc( + """ + Response class to be used for this *path operation*. + + This will not be used if you return a response directly. + + Read more about it in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). + """ + ), + ] = Default(JSONResponse), + name: Annotated[ + Optional[str], + Doc( + """ + Name for this *path operation*. Only used internally. + """ + ), + ] = None, + callbacks: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + List of *path operations* that will be used as OpenAPI callbacks. + + This is only for OpenAPI documentation, the callbacks won't be used + directly. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). + """ + ), + ] = None, + openapi_extra: Annotated[ + Optional[Dict[str, Any]], + Doc( + """ + Extra metadata to be included in the OpenAPI schema for this *path + operation*. + + Read more about it in the + [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). + """ + ), + ] = None, + generate_unique_id_function: Annotated[ + Callable[[APIRoute], str], + Doc( + """ + Customize the function used to generate unique IDs for the *path + operations* shown in the generated OpenAPI. + + This is particularly useful when automatically generating clients or + SDKs for your API. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Add a *path operation* using an HTTP GET operation. + + ## Example + + ```python + from fastapi import APIRouter, FastAPI + + app = FastAPI() + router = APIRouter() + + @router.get("/items/") + def read_items(): + return [{"name": "Empanada"}, {"name": "Arepa"}] + + app.include_router(router) + ``` + """ return self.api_route( path=path, response_model=response_model, @@ -956,33 +1672,359 @@ class APIRouter(routing.Router): def put( self, - path: str, + path: Annotated[ + str, + Doc( + """ + The URL path to be used for this *path operation*. + + For example, in `http://example.com/items`, the path is `/items`. + """ + ), + ], *, - response_model: Any = Default(None), - status_code: Optional[int] = None, - tags: Optional[List[Union[str, Enum]]] = None, - dependencies: Optional[Sequence[params.Depends]] = None, - summary: Optional[str] = None, - description: Optional[str] = None, - response_description: str = "Successful Response", - responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, - deprecated: Optional[bool] = None, - operation_id: Optional[str] = None, - response_model_include: Optional[IncEx] = None, - response_model_exclude: Optional[IncEx] = None, - response_model_by_alias: bool = True, - response_model_exclude_unset: bool = False, - response_model_exclude_defaults: bool = False, - response_model_exclude_none: bool = False, - include_in_schema: bool = True, - response_class: Type[Response] = Default(JSONResponse), - name: Optional[str] = None, - callbacks: Optional[List[BaseRoute]] = None, - openapi_extra: Optional[Dict[str, Any]] = None, - generate_unique_id_function: Callable[[APIRoute], str] = Default( - generate_unique_id - ), + response_model: Annotated[ + Any, + Doc( + """ + The type to use for the response. + + It could be any valid Pydantic *field* type. So, it doesn't have to + be a Pydantic model, it could be other things, like a `list`, `dict`, + etc. + + It will be used for: + + * Documentation: the generated OpenAPI (and the UI at `/docs`) will + show it as the response (JSON Schema). + * Serialization: you could return an arbitrary object and the + `response_model` would be used to serialize that object into the + corresponding JSON. + * Filtering: the JSON sent to the client will only contain the data + (fields) defined in the `response_model`. If you returned an object + that contains an attribute `password` but the `response_model` does + not include that field, the JSON sent to the client would not have + that `password`. + * Validation: whatever you return will be serialized with the + `response_model`, converting any data as necessary to generate the + corresponding JSON. But if the data in the object returned is not + valid, that would mean a violation of the contract with the client, + so it's an error from the API developer. So, FastAPI will raise an + error and return a 500 error code (Internal Server Error). + + Read more about it in the + [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). + """ + ), + ] = Default(None), + status_code: Annotated[ + Optional[int], + Doc( + """ + The default status code to be used for the response. + + You could override the status code by returning a response directly. + + Read more about it in the + [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). + """ + ), + ] = None, + tags: Annotated[ + Optional[List[Union[str, Enum]]], + Doc( + """ + A list of tags to be applied to the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). + """ + ), + ] = None, + dependencies: Annotated[ + Optional[Sequence[params.Depends]], + Doc( + """ + A list of dependencies (using `Depends()`) to be applied to the + *path operation*. + + Read more about it in the + [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). + """ + ), + ] = None, + summary: Annotated[ + Optional[str], + Doc( + """ + A summary for the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + A description for the *path operation*. + + If not provided, it will be extracted automatically from the docstring + of the *path operation function*. + + It can contain Markdown. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + response_description: Annotated[ + str, + Doc( + """ + The description for the default response. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = "Successful Response", + responses: Annotated[ + Optional[Dict[Union[int, str], Dict[str, Any]]], + Doc( + """ + Additional responses that could be returned by this *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this *path operation* as deprecated. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + operation_id: Annotated[ + Optional[str], + Doc( + """ + Custom operation ID to be used by this *path operation*. + + By default, it is generated automatically. + + If you provide a custom operation ID, you need to make sure it is + unique for the whole API. + + You can customize the + operation ID generation with the parameter + `generate_unique_id_function` in the `FastAPI` class. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = None, + response_model_include: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to include only certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_exclude: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to exclude certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_by_alias: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response model + should be serialized by alias when an alias is used. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = True, + response_model_exclude_unset: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that were not set and + have their default values. This is different from + `response_model_exclude_defaults` in that if the fields are set, + they will be included in the response, even if the value is the same + as the default. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_defaults: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that have the same value + as the default. This is different from `response_model_exclude_unset` + in that if the fields are set but contain the same default values, + they will be excluded from the response. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_none: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data should + exclude fields set to `None`. + + This is much simpler (less smart) than `response_model_exclude_unset` + and `response_model_exclude_defaults`. You probably want to use one of + those two instead of this one, as those allow returning `None` values + when it makes sense. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). + """ + ), + ] = False, + include_in_schema: Annotated[ + bool, + Doc( + """ + Include this *path operation* in the generated OpenAPI schema. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi). + """ + ), + ] = True, + response_class: Annotated[ + Type[Response], + Doc( + """ + Response class to be used for this *path operation*. + + This will not be used if you return a response directly. + + Read more about it in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). + """ + ), + ] = Default(JSONResponse), + name: Annotated[ + Optional[str], + Doc( + """ + Name for this *path operation*. Only used internally. + """ + ), + ] = None, + callbacks: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + List of *path operations* that will be used as OpenAPI callbacks. + + This is only for OpenAPI documentation, the callbacks won't be used + directly. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). + """ + ), + ] = None, + openapi_extra: Annotated[ + Optional[Dict[str, Any]], + Doc( + """ + Extra metadata to be included in the OpenAPI schema for this *path + operation*. + + Read more about it in the + [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). + """ + ), + ] = None, + generate_unique_id_function: Annotated[ + Callable[[APIRoute], str], + Doc( + """ + Customize the function used to generate unique IDs for the *path + operations* shown in the generated OpenAPI. + + This is particularly useful when automatically generating clients or + SDKs for your API. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Add a *path operation* using an HTTP PUT operation. + + ## Example + + ```python + from fastapi import APIRouter, FastAPI + from pydantic import BaseModel + + class Item(BaseModel): + name: str + description: str | None = None + + app = FastAPI() + router = APIRouter() + + @router.put("/items/{item_id}") + def replace_item(item_id: str, item: Item): + return {"message": "Item replaced", "id": item_id} + + app.include_router(router) + ``` + """ return self.api_route( path=path, response_model=response_model, @@ -1012,33 +2054,359 @@ class APIRouter(routing.Router): def post( self, - path: str, + path: Annotated[ + str, + Doc( + """ + The URL path to be used for this *path operation*. + + For example, in `http://example.com/items`, the path is `/items`. + """ + ), + ], *, - response_model: Any = Default(None), - status_code: Optional[int] = None, - tags: Optional[List[Union[str, Enum]]] = None, - dependencies: Optional[Sequence[params.Depends]] = None, - summary: Optional[str] = None, - description: Optional[str] = None, - response_description: str = "Successful Response", - responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, - deprecated: Optional[bool] = None, - operation_id: Optional[str] = None, - response_model_include: Optional[IncEx] = None, - response_model_exclude: Optional[IncEx] = None, - response_model_by_alias: bool = True, - response_model_exclude_unset: bool = False, - response_model_exclude_defaults: bool = False, - response_model_exclude_none: bool = False, - include_in_schema: bool = True, - response_class: Type[Response] = Default(JSONResponse), - name: Optional[str] = None, - callbacks: Optional[List[BaseRoute]] = None, - openapi_extra: Optional[Dict[str, Any]] = None, - generate_unique_id_function: Callable[[APIRoute], str] = Default( - generate_unique_id - ), + response_model: Annotated[ + Any, + Doc( + """ + The type to use for the response. + + It could be any valid Pydantic *field* type. So, it doesn't have to + be a Pydantic model, it could be other things, like a `list`, `dict`, + etc. + + It will be used for: + + * Documentation: the generated OpenAPI (and the UI at `/docs`) will + show it as the response (JSON Schema). + * Serialization: you could return an arbitrary object and the + `response_model` would be used to serialize that object into the + corresponding JSON. + * Filtering: the JSON sent to the client will only contain the data + (fields) defined in the `response_model`. If you returned an object + that contains an attribute `password` but the `response_model` does + not include that field, the JSON sent to the client would not have + that `password`. + * Validation: whatever you return will be serialized with the + `response_model`, converting any data as necessary to generate the + corresponding JSON. But if the data in the object returned is not + valid, that would mean a violation of the contract with the client, + so it's an error from the API developer. So, FastAPI will raise an + error and return a 500 error code (Internal Server Error). + + Read more about it in the + [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). + """ + ), + ] = Default(None), + status_code: Annotated[ + Optional[int], + Doc( + """ + The default status code to be used for the response. + + You could override the status code by returning a response directly. + + Read more about it in the + [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). + """ + ), + ] = None, + tags: Annotated[ + Optional[List[Union[str, Enum]]], + Doc( + """ + A list of tags to be applied to the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). + """ + ), + ] = None, + dependencies: Annotated[ + Optional[Sequence[params.Depends]], + Doc( + """ + A list of dependencies (using `Depends()`) to be applied to the + *path operation*. + + Read more about it in the + [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). + """ + ), + ] = None, + summary: Annotated[ + Optional[str], + Doc( + """ + A summary for the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + A description for the *path operation*. + + If not provided, it will be extracted automatically from the docstring + of the *path operation function*. + + It can contain Markdown. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + response_description: Annotated[ + str, + Doc( + """ + The description for the default response. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = "Successful Response", + responses: Annotated[ + Optional[Dict[Union[int, str], Dict[str, Any]]], + Doc( + """ + Additional responses that could be returned by this *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this *path operation* as deprecated. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + operation_id: Annotated[ + Optional[str], + Doc( + """ + Custom operation ID to be used by this *path operation*. + + By default, it is generated automatically. + + If you provide a custom operation ID, you need to make sure it is + unique for the whole API. + + You can customize the + operation ID generation with the parameter + `generate_unique_id_function` in the `FastAPI` class. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = None, + response_model_include: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to include only certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_exclude: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to exclude certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_by_alias: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response model + should be serialized by alias when an alias is used. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = True, + response_model_exclude_unset: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that were not set and + have their default values. This is different from + `response_model_exclude_defaults` in that if the fields are set, + they will be included in the response, even if the value is the same + as the default. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_defaults: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that have the same value + as the default. This is different from `response_model_exclude_unset` + in that if the fields are set but contain the same default values, + they will be excluded from the response. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_none: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data should + exclude fields set to `None`. + + This is much simpler (less smart) than `response_model_exclude_unset` + and `response_model_exclude_defaults`. You probably want to use one of + those two instead of this one, as those allow returning `None` values + when it makes sense. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). + """ + ), + ] = False, + include_in_schema: Annotated[ + bool, + Doc( + """ + Include this *path operation* in the generated OpenAPI schema. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi). + """ + ), + ] = True, + response_class: Annotated[ + Type[Response], + Doc( + """ + Response class to be used for this *path operation*. + + This will not be used if you return a response directly. + + Read more about it in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). + """ + ), + ] = Default(JSONResponse), + name: Annotated[ + Optional[str], + Doc( + """ + Name for this *path operation*. Only used internally. + """ + ), + ] = None, + callbacks: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + List of *path operations* that will be used as OpenAPI callbacks. + + This is only for OpenAPI documentation, the callbacks won't be used + directly. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). + """ + ), + ] = None, + openapi_extra: Annotated[ + Optional[Dict[str, Any]], + Doc( + """ + Extra metadata to be included in the OpenAPI schema for this *path + operation*. + + Read more about it in the + [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). + """ + ), + ] = None, + generate_unique_id_function: Annotated[ + Callable[[APIRoute], str], + Doc( + """ + Customize the function used to generate unique IDs for the *path + operations* shown in the generated OpenAPI. + + This is particularly useful when automatically generating clients or + SDKs for your API. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Add a *path operation* using an HTTP POST operation. + + ## Example + + ```python + from fastapi import APIRouter, FastAPI + from pydantic import BaseModel + + class Item(BaseModel): + name: str + description: str | None = None + + app = FastAPI() + router = APIRouter() + + @router.post("/items/") + def create_item(item: Item): + return {"message": "Item created"} + + app.include_router(router) + ``` + """ return self.api_route( path=path, response_model=response_model, @@ -1068,33 +2436,354 @@ class APIRouter(routing.Router): def delete( self, - path: str, + path: Annotated[ + str, + Doc( + """ + The URL path to be used for this *path operation*. + + For example, in `http://example.com/items`, the path is `/items`. + """ + ), + ], *, - response_model: Any = Default(None), - status_code: Optional[int] = None, - tags: Optional[List[Union[str, Enum]]] = None, - dependencies: Optional[Sequence[params.Depends]] = None, - summary: Optional[str] = None, - description: Optional[str] = None, - response_description: str = "Successful Response", - responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, - deprecated: Optional[bool] = None, - operation_id: Optional[str] = None, - response_model_include: Optional[IncEx] = None, - response_model_exclude: Optional[IncEx] = None, - response_model_by_alias: bool = True, - response_model_exclude_unset: bool = False, - response_model_exclude_defaults: bool = False, - response_model_exclude_none: bool = False, - include_in_schema: bool = True, - response_class: Type[Response] = Default(JSONResponse), - name: Optional[str] = None, - callbacks: Optional[List[BaseRoute]] = None, - openapi_extra: Optional[Dict[str, Any]] = None, - generate_unique_id_function: Callable[[APIRoute], str] = Default( - generate_unique_id - ), + response_model: Annotated[ + Any, + Doc( + """ + The type to use for the response. + + It could be any valid Pydantic *field* type. So, it doesn't have to + be a Pydantic model, it could be other things, like a `list`, `dict`, + etc. + + It will be used for: + + * Documentation: the generated OpenAPI (and the UI at `/docs`) will + show it as the response (JSON Schema). + * Serialization: you could return an arbitrary object and the + `response_model` would be used to serialize that object into the + corresponding JSON. + * Filtering: the JSON sent to the client will only contain the data + (fields) defined in the `response_model`. If you returned an object + that contains an attribute `password` but the `response_model` does + not include that field, the JSON sent to the client would not have + that `password`. + * Validation: whatever you return will be serialized with the + `response_model`, converting any data as necessary to generate the + corresponding JSON. But if the data in the object returned is not + valid, that would mean a violation of the contract with the client, + so it's an error from the API developer. So, FastAPI will raise an + error and return a 500 error code (Internal Server Error). + + Read more about it in the + [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). + """ + ), + ] = Default(None), + status_code: Annotated[ + Optional[int], + Doc( + """ + The default status code to be used for the response. + + You could override the status code by returning a response directly. + + Read more about it in the + [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). + """ + ), + ] = None, + tags: Annotated[ + Optional[List[Union[str, Enum]]], + Doc( + """ + A list of tags to be applied to the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). + """ + ), + ] = None, + dependencies: Annotated[ + Optional[Sequence[params.Depends]], + Doc( + """ + A list of dependencies (using `Depends()`) to be applied to the + *path operation*. + + Read more about it in the + [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). + """ + ), + ] = None, + summary: Annotated[ + Optional[str], + Doc( + """ + A summary for the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + A description for the *path operation*. + + If not provided, it will be extracted automatically from the docstring + of the *path operation function*. + + It can contain Markdown. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + response_description: Annotated[ + str, + Doc( + """ + The description for the default response. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = "Successful Response", + responses: Annotated[ + Optional[Dict[Union[int, str], Dict[str, Any]]], + Doc( + """ + Additional responses that could be returned by this *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this *path operation* as deprecated. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + operation_id: Annotated[ + Optional[str], + Doc( + """ + Custom operation ID to be used by this *path operation*. + + By default, it is generated automatically. + + If you provide a custom operation ID, you need to make sure it is + unique for the whole API. + + You can customize the + operation ID generation with the parameter + `generate_unique_id_function` in the `FastAPI` class. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = None, + response_model_include: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to include only certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_exclude: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to exclude certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_by_alias: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response model + should be serialized by alias when an alias is used. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = True, + response_model_exclude_unset: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that were not set and + have their default values. This is different from + `response_model_exclude_defaults` in that if the fields are set, + they will be included in the response, even if the value is the same + as the default. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_defaults: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that have the same value + as the default. This is different from `response_model_exclude_unset` + in that if the fields are set but contain the same default values, + they will be excluded from the response. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_none: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data should + exclude fields set to `None`. + + This is much simpler (less smart) than `response_model_exclude_unset` + and `response_model_exclude_defaults`. You probably want to use one of + those two instead of this one, as those allow returning `None` values + when it makes sense. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). + """ + ), + ] = False, + include_in_schema: Annotated[ + bool, + Doc( + """ + Include this *path operation* in the generated OpenAPI schema. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi). + """ + ), + ] = True, + response_class: Annotated[ + Type[Response], + Doc( + """ + Response class to be used for this *path operation*. + + This will not be used if you return a response directly. + + Read more about it in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). + """ + ), + ] = Default(JSONResponse), + name: Annotated[ + Optional[str], + Doc( + """ + Name for this *path operation*. Only used internally. + """ + ), + ] = None, + callbacks: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + List of *path operations* that will be used as OpenAPI callbacks. + + This is only for OpenAPI documentation, the callbacks won't be used + directly. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). + """ + ), + ] = None, + openapi_extra: Annotated[ + Optional[Dict[str, Any]], + Doc( + """ + Extra metadata to be included in the OpenAPI schema for this *path + operation*. + + Read more about it in the + [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). + """ + ), + ] = None, + generate_unique_id_function: Annotated[ + Callable[[APIRoute], str], + Doc( + """ + Customize the function used to generate unique IDs for the *path + operations* shown in the generated OpenAPI. + + This is particularly useful when automatically generating clients or + SDKs for your API. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Add a *path operation* using an HTTP DELETE operation. + + ## Example + + ```python + from fastapi import APIRouter, FastAPI + + app = FastAPI() + router = APIRouter() + + @router.delete("/items/{item_id}") + def delete_item(item_id: str): + return {"message": "Item deleted"} + + app.include_router(router) + ``` + """ return self.api_route( path=path, response_model=response_model, @@ -1124,33 +2813,354 @@ class APIRouter(routing.Router): def options( self, - path: str, + path: Annotated[ + str, + Doc( + """ + The URL path to be used for this *path operation*. + + For example, in `http://example.com/items`, the path is `/items`. + """ + ), + ], *, - response_model: Any = Default(None), - status_code: Optional[int] = None, - tags: Optional[List[Union[str, Enum]]] = None, - dependencies: Optional[Sequence[params.Depends]] = None, - summary: Optional[str] = None, - description: Optional[str] = None, - response_description: str = "Successful Response", - responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, - deprecated: Optional[bool] = None, - operation_id: Optional[str] = None, - response_model_include: Optional[IncEx] = None, - response_model_exclude: Optional[IncEx] = None, - response_model_by_alias: bool = True, - response_model_exclude_unset: bool = False, - response_model_exclude_defaults: bool = False, - response_model_exclude_none: bool = False, - include_in_schema: bool = True, - response_class: Type[Response] = Default(JSONResponse), - name: Optional[str] = None, - callbacks: Optional[List[BaseRoute]] = None, - openapi_extra: Optional[Dict[str, Any]] = None, - generate_unique_id_function: Callable[[APIRoute], str] = Default( - generate_unique_id - ), + response_model: Annotated[ + Any, + Doc( + """ + The type to use for the response. + + It could be any valid Pydantic *field* type. So, it doesn't have to + be a Pydantic model, it could be other things, like a `list`, `dict`, + etc. + + It will be used for: + + * Documentation: the generated OpenAPI (and the UI at `/docs`) will + show it as the response (JSON Schema). + * Serialization: you could return an arbitrary object and the + `response_model` would be used to serialize that object into the + corresponding JSON. + * Filtering: the JSON sent to the client will only contain the data + (fields) defined in the `response_model`. If you returned an object + that contains an attribute `password` but the `response_model` does + not include that field, the JSON sent to the client would not have + that `password`. + * Validation: whatever you return will be serialized with the + `response_model`, converting any data as necessary to generate the + corresponding JSON. But if the data in the object returned is not + valid, that would mean a violation of the contract with the client, + so it's an error from the API developer. So, FastAPI will raise an + error and return a 500 error code (Internal Server Error). + + Read more about it in the + [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). + """ + ), + ] = Default(None), + status_code: Annotated[ + Optional[int], + Doc( + """ + The default status code to be used for the response. + + You could override the status code by returning a response directly. + + Read more about it in the + [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). + """ + ), + ] = None, + tags: Annotated[ + Optional[List[Union[str, Enum]]], + Doc( + """ + A list of tags to be applied to the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). + """ + ), + ] = None, + dependencies: Annotated[ + Optional[Sequence[params.Depends]], + Doc( + """ + A list of dependencies (using `Depends()`) to be applied to the + *path operation*. + + Read more about it in the + [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). + """ + ), + ] = None, + summary: Annotated[ + Optional[str], + Doc( + """ + A summary for the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + A description for the *path operation*. + + If not provided, it will be extracted automatically from the docstring + of the *path operation function*. + + It can contain Markdown. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + response_description: Annotated[ + str, + Doc( + """ + The description for the default response. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = "Successful Response", + responses: Annotated[ + Optional[Dict[Union[int, str], Dict[str, Any]]], + Doc( + """ + Additional responses that could be returned by this *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this *path operation* as deprecated. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + operation_id: Annotated[ + Optional[str], + Doc( + """ + Custom operation ID to be used by this *path operation*. + + By default, it is generated automatically. + + If you provide a custom operation ID, you need to make sure it is + unique for the whole API. + + You can customize the + operation ID generation with the parameter + `generate_unique_id_function` in the `FastAPI` class. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = None, + response_model_include: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to include only certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_exclude: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to exclude certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_by_alias: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response model + should be serialized by alias when an alias is used. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = True, + response_model_exclude_unset: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that were not set and + have their default values. This is different from + `response_model_exclude_defaults` in that if the fields are set, + they will be included in the response, even if the value is the same + as the default. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_defaults: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that have the same value + as the default. This is different from `response_model_exclude_unset` + in that if the fields are set but contain the same default values, + they will be excluded from the response. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_none: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data should + exclude fields set to `None`. + + This is much simpler (less smart) than `response_model_exclude_unset` + and `response_model_exclude_defaults`. You probably want to use one of + those two instead of this one, as those allow returning `None` values + when it makes sense. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). + """ + ), + ] = False, + include_in_schema: Annotated[ + bool, + Doc( + """ + Include this *path operation* in the generated OpenAPI schema. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi). + """ + ), + ] = True, + response_class: Annotated[ + Type[Response], + Doc( + """ + Response class to be used for this *path operation*. + + This will not be used if you return a response directly. + + Read more about it in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). + """ + ), + ] = Default(JSONResponse), + name: Annotated[ + Optional[str], + Doc( + """ + Name for this *path operation*. Only used internally. + """ + ), + ] = None, + callbacks: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + List of *path operations* that will be used as OpenAPI callbacks. + + This is only for OpenAPI documentation, the callbacks won't be used + directly. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). + """ + ), + ] = None, + openapi_extra: Annotated[ + Optional[Dict[str, Any]], + Doc( + """ + Extra metadata to be included in the OpenAPI schema for this *path + operation*. + + Read more about it in the + [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). + """ + ), + ] = None, + generate_unique_id_function: Annotated[ + Callable[[APIRoute], str], + Doc( + """ + Customize the function used to generate unique IDs for the *path + operations* shown in the generated OpenAPI. + + This is particularly useful when automatically generating clients or + SDKs for your API. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Add a *path operation* using an HTTP OPTIONS operation. + + ## Example + + ```python + from fastapi import APIRouter, FastAPI + + app = FastAPI() + router = APIRouter() + + @router.options("/items/") + def get_item_options(): + return {"additions": ["Aji", "Guacamole"]} + + app.include_router(router) + ``` + """ return self.api_route( path=path, response_model=response_model, @@ -1180,33 +3190,359 @@ class APIRouter(routing.Router): def head( self, - path: str, + path: Annotated[ + str, + Doc( + """ + The URL path to be used for this *path operation*. + + For example, in `http://example.com/items`, the path is `/items`. + """ + ), + ], *, - response_model: Any = Default(None), - status_code: Optional[int] = None, - tags: Optional[List[Union[str, Enum]]] = None, - dependencies: Optional[Sequence[params.Depends]] = None, - summary: Optional[str] = None, - description: Optional[str] = None, - response_description: str = "Successful Response", - responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, - deprecated: Optional[bool] = None, - operation_id: Optional[str] = None, - response_model_include: Optional[IncEx] = None, - response_model_exclude: Optional[IncEx] = None, - response_model_by_alias: bool = True, - response_model_exclude_unset: bool = False, - response_model_exclude_defaults: bool = False, - response_model_exclude_none: bool = False, - include_in_schema: bool = True, - response_class: Type[Response] = Default(JSONResponse), - name: Optional[str] = None, - callbacks: Optional[List[BaseRoute]] = None, - openapi_extra: Optional[Dict[str, Any]] = None, - generate_unique_id_function: Callable[[APIRoute], str] = Default( - generate_unique_id - ), + response_model: Annotated[ + Any, + Doc( + """ + The type to use for the response. + + It could be any valid Pydantic *field* type. So, it doesn't have to + be a Pydantic model, it could be other things, like a `list`, `dict`, + etc. + + It will be used for: + + * Documentation: the generated OpenAPI (and the UI at `/docs`) will + show it as the response (JSON Schema). + * Serialization: you could return an arbitrary object and the + `response_model` would be used to serialize that object into the + corresponding JSON. + * Filtering: the JSON sent to the client will only contain the data + (fields) defined in the `response_model`. If you returned an object + that contains an attribute `password` but the `response_model` does + not include that field, the JSON sent to the client would not have + that `password`. + * Validation: whatever you return will be serialized with the + `response_model`, converting any data as necessary to generate the + corresponding JSON. But if the data in the object returned is not + valid, that would mean a violation of the contract with the client, + so it's an error from the API developer. So, FastAPI will raise an + error and return a 500 error code (Internal Server Error). + + Read more about it in the + [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). + """ + ), + ] = Default(None), + status_code: Annotated[ + Optional[int], + Doc( + """ + The default status code to be used for the response. + + You could override the status code by returning a response directly. + + Read more about it in the + [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). + """ + ), + ] = None, + tags: Annotated[ + Optional[List[Union[str, Enum]]], + Doc( + """ + A list of tags to be applied to the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). + """ + ), + ] = None, + dependencies: Annotated[ + Optional[Sequence[params.Depends]], + Doc( + """ + A list of dependencies (using `Depends()`) to be applied to the + *path operation*. + + Read more about it in the + [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). + """ + ), + ] = None, + summary: Annotated[ + Optional[str], + Doc( + """ + A summary for the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + A description for the *path operation*. + + If not provided, it will be extracted automatically from the docstring + of the *path operation function*. + + It can contain Markdown. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + response_description: Annotated[ + str, + Doc( + """ + The description for the default response. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = "Successful Response", + responses: Annotated[ + Optional[Dict[Union[int, str], Dict[str, Any]]], + Doc( + """ + Additional responses that could be returned by this *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this *path operation* as deprecated. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + operation_id: Annotated[ + Optional[str], + Doc( + """ + Custom operation ID to be used by this *path operation*. + + By default, it is generated automatically. + + If you provide a custom operation ID, you need to make sure it is + unique for the whole API. + + You can customize the + operation ID generation with the parameter + `generate_unique_id_function` in the `FastAPI` class. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = None, + response_model_include: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to include only certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_exclude: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to exclude certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_by_alias: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response model + should be serialized by alias when an alias is used. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = True, + response_model_exclude_unset: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that were not set and + have their default values. This is different from + `response_model_exclude_defaults` in that if the fields are set, + they will be included in the response, even if the value is the same + as the default. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_defaults: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that have the same value + as the default. This is different from `response_model_exclude_unset` + in that if the fields are set but contain the same default values, + they will be excluded from the response. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_none: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data should + exclude fields set to `None`. + + This is much simpler (less smart) than `response_model_exclude_unset` + and `response_model_exclude_defaults`. You probably want to use one of + those two instead of this one, as those allow returning `None` values + when it makes sense. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). + """ + ), + ] = False, + include_in_schema: Annotated[ + bool, + Doc( + """ + Include this *path operation* in the generated OpenAPI schema. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi). + """ + ), + ] = True, + response_class: Annotated[ + Type[Response], + Doc( + """ + Response class to be used for this *path operation*. + + This will not be used if you return a response directly. + + Read more about it in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). + """ + ), + ] = Default(JSONResponse), + name: Annotated[ + Optional[str], + Doc( + """ + Name for this *path operation*. Only used internally. + """ + ), + ] = None, + callbacks: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + List of *path operations* that will be used as OpenAPI callbacks. + + This is only for OpenAPI documentation, the callbacks won't be used + directly. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). + """ + ), + ] = None, + openapi_extra: Annotated[ + Optional[Dict[str, Any]], + Doc( + """ + Extra metadata to be included in the OpenAPI schema for this *path + operation*. + + Read more about it in the + [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). + """ + ), + ] = None, + generate_unique_id_function: Annotated[ + Callable[[APIRoute], str], + Doc( + """ + Customize the function used to generate unique IDs for the *path + operations* shown in the generated OpenAPI. + + This is particularly useful when automatically generating clients or + SDKs for your API. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Add a *path operation* using an HTTP HEAD operation. + + ## Example + + ```python + from fastapi import APIRouter, FastAPI + from pydantic import BaseModel + + class Item(BaseModel): + name: str + description: str | None = None + + app = FastAPI() + router = APIRouter() + + @router.head("/items/", status_code=204) + def get_items_headers(response: Response): + response.headers["X-Cat-Dog"] = "Alone in the world" + + app.include_router(router) + ``` + """ return self.api_route( path=path, response_model=response_model, @@ -1236,33 +3572,359 @@ class APIRouter(routing.Router): def patch( self, - path: str, + path: Annotated[ + str, + Doc( + """ + The URL path to be used for this *path operation*. + + For example, in `http://example.com/items`, the path is `/items`. + """ + ), + ], *, - response_model: Any = Default(None), - status_code: Optional[int] = None, - tags: Optional[List[Union[str, Enum]]] = None, - dependencies: Optional[Sequence[params.Depends]] = None, - summary: Optional[str] = None, - description: Optional[str] = None, - response_description: str = "Successful Response", - responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, - deprecated: Optional[bool] = None, - operation_id: Optional[str] = None, - response_model_include: Optional[IncEx] = None, - response_model_exclude: Optional[IncEx] = None, - response_model_by_alias: bool = True, - response_model_exclude_unset: bool = False, - response_model_exclude_defaults: bool = False, - response_model_exclude_none: bool = False, - include_in_schema: bool = True, - response_class: Type[Response] = Default(JSONResponse), - name: Optional[str] = None, - callbacks: Optional[List[BaseRoute]] = None, - openapi_extra: Optional[Dict[str, Any]] = None, - generate_unique_id_function: Callable[[APIRoute], str] = Default( - generate_unique_id - ), + response_model: Annotated[ + Any, + Doc( + """ + The type to use for the response. + + It could be any valid Pydantic *field* type. So, it doesn't have to + be a Pydantic model, it could be other things, like a `list`, `dict`, + etc. + + It will be used for: + + * Documentation: the generated OpenAPI (and the UI at `/docs`) will + show it as the response (JSON Schema). + * Serialization: you could return an arbitrary object and the + `response_model` would be used to serialize that object into the + corresponding JSON. + * Filtering: the JSON sent to the client will only contain the data + (fields) defined in the `response_model`. If you returned an object + that contains an attribute `password` but the `response_model` does + not include that field, the JSON sent to the client would not have + that `password`. + * Validation: whatever you return will be serialized with the + `response_model`, converting any data as necessary to generate the + corresponding JSON. But if the data in the object returned is not + valid, that would mean a violation of the contract with the client, + so it's an error from the API developer. So, FastAPI will raise an + error and return a 500 error code (Internal Server Error). + + Read more about it in the + [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). + """ + ), + ] = Default(None), + status_code: Annotated[ + Optional[int], + Doc( + """ + The default status code to be used for the response. + + You could override the status code by returning a response directly. + + Read more about it in the + [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). + """ + ), + ] = None, + tags: Annotated[ + Optional[List[Union[str, Enum]]], + Doc( + """ + A list of tags to be applied to the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). + """ + ), + ] = None, + dependencies: Annotated[ + Optional[Sequence[params.Depends]], + Doc( + """ + A list of dependencies (using `Depends()`) to be applied to the + *path operation*. + + Read more about it in the + [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). + """ + ), + ] = None, + summary: Annotated[ + Optional[str], + Doc( + """ + A summary for the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + A description for the *path operation*. + + If not provided, it will be extracted automatically from the docstring + of the *path operation function*. + + It can contain Markdown. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + response_description: Annotated[ + str, + Doc( + """ + The description for the default response. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = "Successful Response", + responses: Annotated[ + Optional[Dict[Union[int, str], Dict[str, Any]]], + Doc( + """ + Additional responses that could be returned by this *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this *path operation* as deprecated. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + operation_id: Annotated[ + Optional[str], + Doc( + """ + Custom operation ID to be used by this *path operation*. + + By default, it is generated automatically. + + If you provide a custom operation ID, you need to make sure it is + unique for the whole API. + + You can customize the + operation ID generation with the parameter + `generate_unique_id_function` in the `FastAPI` class. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = None, + response_model_include: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to include only certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_exclude: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to exclude certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_by_alias: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response model + should be serialized by alias when an alias is used. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = True, + response_model_exclude_unset: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that were not set and + have their default values. This is different from + `response_model_exclude_defaults` in that if the fields are set, + they will be included in the response, even if the value is the same + as the default. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_defaults: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that have the same value + as the default. This is different from `response_model_exclude_unset` + in that if the fields are set but contain the same default values, + they will be excluded from the response. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_none: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data should + exclude fields set to `None`. + + This is much simpler (less smart) than `response_model_exclude_unset` + and `response_model_exclude_defaults`. You probably want to use one of + those two instead of this one, as those allow returning `None` values + when it makes sense. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). + """ + ), + ] = False, + include_in_schema: Annotated[ + bool, + Doc( + """ + Include this *path operation* in the generated OpenAPI schema. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi). + """ + ), + ] = True, + response_class: Annotated[ + Type[Response], + Doc( + """ + Response class to be used for this *path operation*. + + This will not be used if you return a response directly. + + Read more about it in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). + """ + ), + ] = Default(JSONResponse), + name: Annotated[ + Optional[str], + Doc( + """ + Name for this *path operation*. Only used internally. + """ + ), + ] = None, + callbacks: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + List of *path operations* that will be used as OpenAPI callbacks. + + This is only for OpenAPI documentation, the callbacks won't be used + directly. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). + """ + ), + ] = None, + openapi_extra: Annotated[ + Optional[Dict[str, Any]], + Doc( + """ + Extra metadata to be included in the OpenAPI schema for this *path + operation*. + + Read more about it in the + [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). + """ + ), + ] = None, + generate_unique_id_function: Annotated[ + Callable[[APIRoute], str], + Doc( + """ + Customize the function used to generate unique IDs for the *path + operations* shown in the generated OpenAPI. + + This is particularly useful when automatically generating clients or + SDKs for your API. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Add a *path operation* using an HTTP PATCH operation. + + ## Example + + ```python + from fastapi import APIRouter, FastAPI + from pydantic import BaseModel + + class Item(BaseModel): + name: str + description: str | None = None + + app = FastAPI() + router = APIRouter() + + @router.patch("/items/") + def update_item(item: Item): + return {"message": "Item updated in place"} + + app.include_router(router) + ``` + """ return self.api_route( path=path, response_model=response_model, @@ -1292,33 +3954,359 @@ class APIRouter(routing.Router): def trace( self, - path: str, + path: Annotated[ + str, + Doc( + """ + The URL path to be used for this *path operation*. + + For example, in `http://example.com/items`, the path is `/items`. + """ + ), + ], *, - response_model: Any = Default(None), - status_code: Optional[int] = None, - tags: Optional[List[Union[str, Enum]]] = None, - dependencies: Optional[Sequence[params.Depends]] = None, - summary: Optional[str] = None, - description: Optional[str] = None, - response_description: str = "Successful Response", - responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, - deprecated: Optional[bool] = None, - operation_id: Optional[str] = None, - response_model_include: Optional[IncEx] = None, - response_model_exclude: Optional[IncEx] = None, - response_model_by_alias: bool = True, - response_model_exclude_unset: bool = False, - response_model_exclude_defaults: bool = False, - response_model_exclude_none: bool = False, - include_in_schema: bool = True, - response_class: Type[Response] = Default(JSONResponse), - name: Optional[str] = None, - callbacks: Optional[List[BaseRoute]] = None, - openapi_extra: Optional[Dict[str, Any]] = None, - generate_unique_id_function: Callable[[APIRoute], str] = Default( - generate_unique_id - ), + response_model: Annotated[ + Any, + Doc( + """ + The type to use for the response. + + It could be any valid Pydantic *field* type. So, it doesn't have to + be a Pydantic model, it could be other things, like a `list`, `dict`, + etc. + + It will be used for: + + * Documentation: the generated OpenAPI (and the UI at `/docs`) will + show it as the response (JSON Schema). + * Serialization: you could return an arbitrary object and the + `response_model` would be used to serialize that object into the + corresponding JSON. + * Filtering: the JSON sent to the client will only contain the data + (fields) defined in the `response_model`. If you returned an object + that contains an attribute `password` but the `response_model` does + not include that field, the JSON sent to the client would not have + that `password`. + * Validation: whatever you return will be serialized with the + `response_model`, converting any data as necessary to generate the + corresponding JSON. But if the data in the object returned is not + valid, that would mean a violation of the contract with the client, + so it's an error from the API developer. So, FastAPI will raise an + error and return a 500 error code (Internal Server Error). + + Read more about it in the + [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). + """ + ), + ] = Default(None), + status_code: Annotated[ + Optional[int], + Doc( + """ + The default status code to be used for the response. + + You could override the status code by returning a response directly. + + Read more about it in the + [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/). + """ + ), + ] = None, + tags: Annotated[ + Optional[List[Union[str, Enum]]], + Doc( + """ + A list of tags to be applied to the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags). + """ + ), + ] = None, + dependencies: Annotated[ + Optional[Sequence[params.Depends]], + Doc( + """ + A list of dependencies (using `Depends()`) to be applied to the + *path operation*. + + Read more about it in the + [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/). + """ + ), + ] = None, + summary: Annotated[ + Optional[str], + Doc( + """ + A summary for the *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + A description for the *path operation*. + + If not provided, it will be extracted automatically from the docstring + of the *path operation function*. + + It can contain Markdown. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). + """ + ), + ] = None, + response_description: Annotated[ + str, + Doc( + """ + The description for the default response. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = "Successful Response", + responses: Annotated[ + Optional[Dict[Union[int, str], Dict[str, Any]]], + Doc( + """ + Additional responses that could be returned by this *path operation*. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + deprecated: Annotated[ + Optional[bool], + Doc( + """ + Mark this *path operation* as deprecated. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + operation_id: Annotated[ + Optional[str], + Doc( + """ + Custom operation ID to be used by this *path operation*. + + By default, it is generated automatically. + + If you provide a custom operation ID, you need to make sure it is + unique for the whole API. + + You can customize the + operation ID generation with the parameter + `generate_unique_id_function` in the `FastAPI` class. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = None, + response_model_include: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to include only certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_exclude: Annotated[ + Optional[IncEx], + Doc( + """ + Configuration passed to Pydantic to exclude certain fields in the + response data. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = None, + response_model_by_alias: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response model + should be serialized by alias when an alias is used. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude). + """ + ), + ] = True, + response_model_exclude_unset: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that were not set and + have their default values. This is different from + `response_model_exclude_defaults` in that if the fields are set, + they will be included in the response, even if the value is the same + as the default. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_defaults: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data + should have all the fields, including the ones that have the same value + as the default. This is different from `response_model_exclude_unset` + in that if the fields are set but contain the same default values, + they will be excluded from the response. + + When `True`, default values are omitted from the response. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter). + """ + ), + ] = False, + response_model_exclude_none: Annotated[ + bool, + Doc( + """ + Configuration passed to Pydantic to define if the response data should + exclude fields set to `None`. + + This is much simpler (less smart) than `response_model_exclude_unset` + and `response_model_exclude_defaults`. You probably want to use one of + those two instead of this one, as those allow returning `None` values + when it makes sense. + + Read more about it in the + [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none). + """ + ), + ] = False, + include_in_schema: Annotated[ + bool, + Doc( + """ + Include this *path operation* in the generated OpenAPI schema. + + This affects the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi). + """ + ), + ] = True, + response_class: Annotated[ + Type[Response], + Doc( + """ + Response class to be used for this *path operation*. + + This will not be used if you return a response directly. + + Read more about it in the + [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse). + """ + ), + ] = Default(JSONResponse), + name: Annotated[ + Optional[str], + Doc( + """ + Name for this *path operation*. Only used internally. + """ + ), + ] = None, + callbacks: Annotated[ + Optional[List[BaseRoute]], + Doc( + """ + List of *path operations* that will be used as OpenAPI callbacks. + + This is only for OpenAPI documentation, the callbacks won't be used + directly. + + It will be added to the generated OpenAPI (e.g. visible at `/docs`). + + Read more about it in the + [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). + """ + ), + ] = None, + openapi_extra: Annotated[ + Optional[Dict[str, Any]], + Doc( + """ + Extra metadata to be included in the OpenAPI schema for this *path + operation*. + + Read more about it in the + [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema). + """ + ), + ] = None, + generate_unique_id_function: Annotated[ + Callable[[APIRoute], str], + Doc( + """ + Customize the function used to generate unique IDs for the *path + operations* shown in the generated OpenAPI. + + This is particularly useful when automatically generating clients or + SDKs for your API. + + Read more about it in the + [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). + """ + ), + ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Add a *path operation* using an HTTP TRACE operation. + + ## Example + + ```python + from fastapi import APIRouter, FastAPI + from pydantic import BaseModel + + class Item(BaseModel): + name: str + description: str | None = None + + app = FastAPI() + router = APIRouter() + + @router.put("/items/{item_id}") + def trace_item(item_id: str): + return None + + app.include_router(router) + ``` + """ return self.api_route( path=path, response_model=response_model, @@ -1346,9 +4334,34 @@ class APIRouter(routing.Router): generate_unique_id_function=generate_unique_id_function, ) + @deprecated( + """ + on_event is deprecated, use lifespan event handlers instead. + + Read more about it in the + [FastAPI docs for Lifespan Events](https://fastapi.tiangolo.com/advanced/events/). + """ + ) def on_event( - self, event_type: str + self, + event_type: Annotated[ + str, + Doc( + """ + The type of event. `startup` or `shutdown`. + """ + ), + ], ) -> Callable[[DecoratedCallable], DecoratedCallable]: + """ + Add an event handler for the router. + + `on_event` is deprecated, use `lifespan` event handlers instead. + + Read more about it in the + [FastAPI docs for Lifespan Events](https://fastapi.tiangolo.com/advanced/events/#alternative-events-deprecated). + """ + def decorator(func: DecoratedCallable) -> DecoratedCallable: self.add_event_handler(event_type, func) return func diff --git a/fastapi/security/api_key.py b/fastapi/security/api_key.py index 8b2c5c080..b1a6b4f94 100644 --- a/fastapi/security/api_key.py +++ b/fastapi/security/api_key.py @@ -5,6 +5,7 @@ from fastapi.security.base import SecurityBase from starlette.exceptions import HTTPException from starlette.requests import Request from starlette.status import HTTP_403_FORBIDDEN +from typing_extensions import Annotated, Doc # type: ignore [attr-defined] class APIKeyBase(SecurityBase): @@ -12,13 +13,83 @@ class APIKeyBase(SecurityBase): class APIKeyQuery(APIKeyBase): + """ + API key authentication using a query parameter. + + This defines the name of the query parameter that should be provided in the request + with the API key and integrates that into the OpenAPI documentation. It extracts + the key value sent in the query parameter automatically and provides it as the + dependency result. But it doesn't define how to send that API key to the client. + + ## Usage + + Create an instance object and use that object as the dependency in `Depends()`. + + The dependency result will be a string containing the key value. + + ## Example + + ```python + from fastapi import Depends, FastAPI + from fastapi.security import APIKeyQuery + + app = FastAPI() + + query_scheme = APIKeyQuery(name="api_key") + + + @app.get("/items/") + async def read_items(api_key: str = Depends(query_scheme)): + return {"api_key": api_key} + ``` + """ + def __init__( self, *, - name: str, - scheme_name: Optional[str] = None, - description: Optional[str] = None, - auto_error: bool = True, + name: Annotated[ + str, + Doc("Query parameter name."), + ], + scheme_name: Annotated[ + Optional[str], + Doc( + """ + Security scheme name. + + It will be included in the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + Security scheme description. + + It will be included in the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + auto_error: Annotated[ + bool, + Doc( + """ + By default, if the query parameter is not provided, `APIKeyQuery` will + automatically cancel the request and sebd the client an error. + + If `auto_error` is set to `False`, when the query parameter is not + available, instead of erroring out, the dependency result will be + `None`. + + This is useful when you want to have optional authentication. + + It is also useful when you want to have authentication that can be + provided in one of multiple optional ways (for example, in a query + parameter or in an HTTP Bearer token). + """ + ), + ] = True, ): self.model: APIKey = APIKey( **{"in": APIKeyIn.query}, # type: ignore[arg-type] @@ -41,13 +112,79 @@ class APIKeyQuery(APIKeyBase): class APIKeyHeader(APIKeyBase): + """ + API key authentication using a header. + + This defines the name of the header that should be provided in the request with + the API key and integrates that into the OpenAPI documentation. It extracts + the key value sent in the header automatically and provides it as the dependency + result. But it doesn't define how to send that key to the client. + + ## Usage + + Create an instance object and use that object as the dependency in `Depends()`. + + The dependency result will be a string containing the key value. + + ## Example + + ```python + from fastapi import Depends, FastAPI + from fastapi.security import APIKeyHeader + + app = FastAPI() + + header_scheme = APIKeyHeader(name="x-key") + + + @app.get("/items/") + async def read_items(key: str = Depends(header_scheme)): + return {"key": key} + ``` + """ + def __init__( self, *, - name: str, - scheme_name: Optional[str] = None, - description: Optional[str] = None, - auto_error: bool = True, + name: Annotated[str, Doc("Header name.")], + scheme_name: Annotated[ + Optional[str], + Doc( + """ + Security scheme name. + + It will be included in the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + Security scheme description. + + It will be included in the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + auto_error: Annotated[ + bool, + Doc( + """ + By default, if the header is not provided, `APIKeyHeader` will + automatically cancel the request and send the client an error. + + If `auto_error` is set to `False`, when the header is not available, + instead of erroring out, the dependency result will be `None`. + + This is useful when you want to have optional authentication. + + It is also useful when you want to have authentication that can be + provided in one of multiple optional ways (for example, in a header or + in an HTTP Bearer token). + """ + ), + ] = True, ): self.model: APIKey = APIKey( **{"in": APIKeyIn.header}, # type: ignore[arg-type] @@ -70,13 +207,79 @@ class APIKeyHeader(APIKeyBase): class APIKeyCookie(APIKeyBase): + """ + API key authentication using a cookie. + + This defines the name of the cookie that should be provided in the request with + the API key and integrates that into the OpenAPI documentation. It extracts + the key value sent in the cookie automatically and provides it as the dependency + result. But it doesn't define how to set that cookie. + + ## Usage + + Create an instance object and use that object as the dependency in `Depends()`. + + The dependency result will be a string containing the key value. + + ## Example + + ```python + from fastapi import Depends, FastAPI + from fastapi.security import APIKeyCookie + + app = FastAPI() + + cookie_scheme = APIKeyCookie(name="session") + + + @app.get("/items/") + async def read_items(session: str = Depends(cookie_scheme)): + return {"session": session} + ``` + """ + def __init__( self, *, - name: str, - scheme_name: Optional[str] = None, - description: Optional[str] = None, - auto_error: bool = True, + name: Annotated[str, Doc("Cookie name.")], + scheme_name: Annotated[ + Optional[str], + Doc( + """ + Security scheme name. + + It will be included in the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + Security scheme description. + + It will be included in the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + auto_error: Annotated[ + bool, + Doc( + """ + By default, if the cookie is not provided, `APIKeyCookie` will + automatically cancel the request and send the client an error. + + If `auto_error` is set to `False`, when the cookie is not available, + instead of erroring out, the dependency result will be `None`. + + This is useful when you want to have optional authentication. + + It is also useful when you want to have authentication that can be + provided in one of multiple optional ways (for example, in a cookie or + in an HTTP Bearer token). + """ + ), + ] = True, ): self.model: APIKey = APIKey( **{"in": APIKeyIn.cookie}, # type: ignore[arg-type] diff --git a/fastapi/security/http.py b/fastapi/security/http.py index 8fc0aafd9..3627777d6 100644 --- a/fastapi/security/http.py +++ b/fastapi/security/http.py @@ -10,16 +10,60 @@ from fastapi.security.utils import get_authorization_scheme_param from pydantic import BaseModel from starlette.requests import Request from starlette.status import HTTP_401_UNAUTHORIZED, HTTP_403_FORBIDDEN +from typing_extensions import Annotated, Doc # type: ignore [attr-defined] class HTTPBasicCredentials(BaseModel): - username: str - password: str + """ + The HTTP Basic credendials given as the result of using `HTTPBasic` in a + dependency. + + Read more about it in the + [FastAPI docs for HTTP Basic Auth](https://fastapi.tiangolo.com/advanced/security/http-basic-auth/). + """ + + username: Annotated[str, Doc("The HTTP Basic username.")] + password: Annotated[str, Doc("The HTTP Basic password.")] class HTTPAuthorizationCredentials(BaseModel): - scheme: str - credentials: str + """ + The HTTP authorization credentials in the result of using `HTTPBearer` or + `HTTPDigest` in a dependency. + + The HTTP authorization header value is split by the first space. + + The first part is the `scheme`, the second part is the `credentials`. + + For example, in an HTTP Bearer token scheme, the client will send a header + like: + + ``` + Authorization: Bearer deadbeef12346 + ``` + + In this case: + + * `scheme` will have the value `"Bearer"` + * `credentials` will have the value `"deadbeef12346"` + """ + + scheme: Annotated[ + str, + Doc( + """ + The HTTP authorization scheme extracted from the header value. + """ + ), + ] + credentials: Annotated[ + str, + Doc( + """ + The HTTP authorization credentials extracted from the header value. + """ + ), + ] class HTTPBase(SecurityBase): @@ -51,13 +95,89 @@ class HTTPBase(SecurityBase): class HTTPBasic(HTTPBase): + """ + HTTP Basic authentication. + + ## Usage + + Create an instance object and use that object as the dependency in `Depends()`. + + The dependency result will be an `HTTPBasicCredentials` object containing the + `username` and the `password`. + + Read more about it in the + [FastAPI docs for HTTP Basic Auth](https://fastapi.tiangolo.com/advanced/security/http-basic-auth/). + + ## Example + + ```python + from typing import Annotated + + from fastapi import Depends, FastAPI + from fastapi.security import HTTPBasic, HTTPBasicCredentials + + app = FastAPI() + + security = HTTPBasic() + + + @app.get("/users/me") + def read_current_user(credentials: Annotated[HTTPBasicCredentials, Depends(security)]): + return {"username": credentials.username, "password": credentials.password} + ``` + """ + def __init__( self, *, - scheme_name: Optional[str] = None, - realm: Optional[str] = None, - description: Optional[str] = None, - auto_error: bool = True, + scheme_name: Annotated[ + Optional[str], + Doc( + """ + Security scheme name. + + It will be included in the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + realm: Annotated[ + Optional[str], + Doc( + """ + HTTP Basic authentication realm. + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + Security scheme description. + + It will be included in the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + auto_error: Annotated[ + bool, + Doc( + """ + By default, if the HTTP Basic authentication is not provided (a + header), `HTTPBasic` will automatically cancel the request and send the + client an error. + + If `auto_error` is set to `False`, when the HTTP Basic authentication + is not available, instead of erroring out, the dependency result will + be `None`. + + This is useful when you want to have optional authentication. + + It is also useful when you want to have authentication that can be + provided in one of multiple optional ways (for example, in HTTP Basic + authentication or in an HTTP Bearer token). + """ + ), + ] = True, ): self.model = HTTPBaseModel(scheme="basic", description=description) self.scheme_name = scheme_name or self.__class__.__name__ @@ -98,13 +218,81 @@ class HTTPBasic(HTTPBase): class HTTPBearer(HTTPBase): + """ + HTTP Bearer token authentication. + + ## Usage + + Create an instance object and use that object as the dependency in `Depends()`. + + The dependency result will be an `HTTPAuthorizationCredentials` object containing + the `scheme` and the `credentials`. + + ## Example + + ```python + from typing import Annotated + + from fastapi import Depends, FastAPI + from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer + + app = FastAPI() + + security = HTTPBearer() + + + @app.get("/users/me") + def read_current_user( + credentials: Annotated[HTTPAuthorizationCredentials, Depends(security)] + ): + return {"scheme": credentials.scheme, "credentials": credentials.credentials} + ``` + """ + def __init__( self, *, - bearerFormat: Optional[str] = None, - scheme_name: Optional[str] = None, - description: Optional[str] = None, - auto_error: bool = True, + bearerFormat: Annotated[Optional[str], Doc("Bearer token format.")] = None, + scheme_name: Annotated[ + Optional[str], + Doc( + """ + Security scheme name. + + It will be included in the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + Security scheme description. + + It will be included in the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + auto_error: Annotated[ + bool, + Doc( + """ + By default, if the HTTP Bearer token not provided (in an + `Authorization` header), `HTTPBearer` will automatically cancel the + request and send the client an error. + + If `auto_error` is set to `False`, when the HTTP Bearer token + is not available, instead of erroring out, the dependency result will + be `None`. + + This is useful when you want to have optional authentication. + + It is also useful when you want to have authentication that can be + provided in one of multiple optional ways (for example, in an HTTP + Bearer token or in a cookie). + """ + ), + ] = True, ): self.model = HTTPBearerModel(bearerFormat=bearerFormat, description=description) self.scheme_name = scheme_name or self.__class__.__name__ @@ -134,12 +322,79 @@ class HTTPBearer(HTTPBase): class HTTPDigest(HTTPBase): + """ + HTTP Digest authentication. + + ## Usage + + Create an instance object and use that object as the dependency in `Depends()`. + + The dependency result will be an `HTTPAuthorizationCredentials` object containing + the `scheme` and the `credentials`. + + ## Example + + ```python + from typing import Annotated + + from fastapi import Depends, FastAPI + from fastapi.security import HTTPAuthorizationCredentials, HTTPDigest + + app = FastAPI() + + security = HTTPDigest() + + + @app.get("/users/me") + def read_current_user( + credentials: Annotated[HTTPAuthorizationCredentials, Depends(security)] + ): + return {"scheme": credentials.scheme, "credentials": credentials.credentials} + ``` + """ + def __init__( self, *, - scheme_name: Optional[str] = None, - description: Optional[str] = None, - auto_error: bool = True, + scheme_name: Annotated[ + Optional[str], + Doc( + """ + Security scheme name. + + It will be included in the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + Security scheme description. + + It will be included in the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + auto_error: Annotated[ + bool, + Doc( + """ + By default, if the HTTP Digest not provided, `HTTPDigest` will + automatically cancel the request and send the client an error. + + If `auto_error` is set to `False`, when the HTTP Digest is not + available, instead of erroring out, the dependency result will + be `None`. + + This is useful when you want to have optional authentication. + + It is also useful when you want to have authentication that can be + provided in one of multiple optional ways (for example, in HTTP + Digest or in a cookie). + """ + ), + ] = True, ): self.model = HTTPBaseModel(scheme="digest", description=description) self.scheme_name = scheme_name or self.__class__.__name__ diff --git a/fastapi/security/oauth2.py b/fastapi/security/oauth2.py index e4c4357e7..d427783ad 100644 --- a/fastapi/security/oauth2.py +++ b/fastapi/security/oauth2.py @@ -10,51 +10,136 @@ from starlette.requests import Request from starlette.status import HTTP_401_UNAUTHORIZED, HTTP_403_FORBIDDEN # TODO: import from typing when deprecating Python 3.9 -from typing_extensions import Annotated +from typing_extensions import Annotated, Doc # type: ignore [attr-defined] class OAuth2PasswordRequestForm: """ - This is a dependency class, use it like: + This is a dependency class to collect the `username` and `password` as form data + for an OAuth2 password flow. - @app.post("/login") - def login(form_data: OAuth2PasswordRequestForm = Depends()): - data = form_data.parse() - print(data.username) - print(data.password) - for scope in data.scopes: - print(scope) - if data.client_id: - print(data.client_id) - if data.client_secret: - print(data.client_secret) - return data + The OAuth2 specification dictates that for a password flow the data should be + collected using form data (instead of JSON) and that it should have the specific + fields `username` and `password`. + All the initialization parameters are extracted from the request. - It creates the following Form request parameters in your endpoint: + Read more about it in the + [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/). - grant_type: the OAuth2 spec says it is required and MUST be the fixed string "password". - Nevertheless, this dependency class is permissive and allows not passing it. If you want to enforce it, - use instead the OAuth2PasswordRequestFormStrict dependency. - username: username string. The OAuth2 spec requires the exact field name "username". - password: password string. The OAuth2 spec requires the exact field name "password". - scope: Optional string. Several scopes (each one a string) separated by spaces. E.g. - "items:read items:write users:read profile openid" - client_id: optional string. OAuth2 recommends sending the client_id and client_secret (if any) - using HTTP Basic auth, as: client_id:client_secret - client_secret: optional string. OAuth2 recommends sending the client_id and client_secret (if any) - using HTTP Basic auth, as: client_id:client_secret + ## Example + + ```python + from typing import Annotated + + from fastapi import Depends, FastAPI + from fastapi.security import OAuth2PasswordRequestForm + + app = FastAPI() + + + @app.post("/login") + def login(form_data: Annotated[OAuth2PasswordRequestForm, Depends()]): + data = {} + data["scopes"] = [] + for scope in form_data.scopes: + data["scopes"].append(scope) + if form_data.client_id: + data["client_id"] = form_data.client_id + if form_data.client_secret: + data["client_secret"] = form_data.client_secret + return data + ``` + + Note that for OAuth2 the scope `items:read` is a single scope in an opaque string. + You could have custom internal logic to separate it by colon caracters (`:`) or + similar, and get the two parts `items` and `read`. Many applications do that to + group and organize permisions, you could do it as well in your application, just + know that that it is application specific, it's not part of the specification. """ def __init__( self, *, - grant_type: Annotated[Union[str, None], Form(pattern="password")] = None, - username: Annotated[str, Form()], - password: Annotated[str, Form()], - scope: Annotated[str, Form()] = "", - client_id: Annotated[Union[str, None], Form()] = None, - client_secret: Annotated[Union[str, None], Form()] = None, + grant_type: Annotated[ + Union[str, None], + Form(pattern="password"), + Doc( + """ + The OAuth2 spec says it is required and MUST be the fixed string + "password". Nevertheless, this dependency class is permissive and + allows not passing it. If you want to enforce it, use instead the + `OAuth2PasswordRequestFormStrict` dependency. + """ + ), + ] = None, + username: Annotated[ + str, + Form(), + Doc( + """ + `username` string. The OAuth2 spec requires the exact field name + `username`. + """ + ), + ], + password: Annotated[ + str, + Form(), + Doc( + """ + `password` string. The OAuth2 spec requires the exact field name + `password". + """ + ), + ], + scope: Annotated[ + str, + Form(), + Doc( + """ + A single string with actually several scopes separated by spaces. Each + scope is also a string. + + For example, a single string with: + + ```python + "items:read items:write users:read profile openid" + ```` + + would represent the scopes: + + * `items:read` + * `items:write` + * `users:read` + * `profile` + * `openid` + """ + ), + ] = "", + client_id: Annotated[ + Union[str, None], + Form(), + Doc( + """ + If there's a `client_id`, it can be sent as part of the form fields. + But the OAuth2 specification recommends sending the `client_id` and + `client_secret` (if any) using HTTP Basic auth. + """ + ), + ] = None, + client_secret: Annotated[ + Union[str, None], + Form(), + Doc( + """ + If there's a `client_password` (and a `client_id`), they can be sent + as part of the form fields. But the OAuth2 specification recommends + sending the `client_id` and `client_secret` (if any) using HTTP Basic + auth. + """ + ), + ] = None, ): self.grant_type = grant_type self.username = username @@ -66,23 +151,54 @@ class OAuth2PasswordRequestForm: class OAuth2PasswordRequestFormStrict(OAuth2PasswordRequestForm): """ - This is a dependency class, use it like: + This is a dependency class to collect the `username` and `password` as form data + for an OAuth2 password flow. + + The OAuth2 specification dictates that for a password flow the data should be + collected using form data (instead of JSON) and that it should have the specific + fields `username` and `password`. + + All the initialization parameters are extracted from the request. + + The only difference between `OAuth2PasswordRequestFormStrict` and + `OAuth2PasswordRequestForm` is that `OAuth2PasswordRequestFormStrict` requires the + client to send the form field `grant_type` with the value `"password"`, which + is required in the OAuth2 specification (it seems that for no particular reason), + while for `OAuth2PasswordRequestForm` `grant_type` is optional. + + Read more about it in the + [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/). + + ## Example + + ```python + from typing import Annotated + + from fastapi import Depends, FastAPI + from fastapi.security import OAuth2PasswordRequestForm - @app.post("/login") - def login(form_data: OAuth2PasswordRequestFormStrict = Depends()): - data = form_data.parse() - print(data.username) - print(data.password) - for scope in data.scopes: - print(scope) - if data.client_id: - print(data.client_id) - if data.client_secret: - print(data.client_secret) - return data + app = FastAPI() - It creates the following Form request parameters in your endpoint: + @app.post("/login") + def login(form_data: Annotated[OAuth2PasswordRequestFormStrict, Depends()]): + data = {} + data["scopes"] = [] + for scope in form_data.scopes: + data["scopes"].append(scope) + if form_data.client_id: + data["client_id"] = form_data.client_id + if form_data.client_secret: + data["client_secret"] = form_data.client_secret + return data + ``` + + Note that for OAuth2 the scope `items:read` is a single scope in an opaque string. + You could have custom internal logic to separate it by colon caracters (`:`) or + similar, and get the two parts `items` and `read`. Many applications do that to + group and organize permisions, you could do it as well in your application, just + know that that it is application specific, it's not part of the specification. + grant_type: the OAuth2 spec says it is required and MUST be the fixed string "password". This dependency is strict about it. If you want to be permissive, use instead the @@ -99,12 +215,85 @@ class OAuth2PasswordRequestFormStrict(OAuth2PasswordRequestForm): def __init__( self, - grant_type: Annotated[str, Form(pattern="password")], - username: Annotated[str, Form()], - password: Annotated[str, Form()], - scope: Annotated[str, Form()] = "", - client_id: Annotated[Union[str, None], Form()] = None, - client_secret: Annotated[Union[str, None], Form()] = None, + grant_type: Annotated[ + str, + Form(pattern="password"), + Doc( + """ + The OAuth2 spec says it is required and MUST be the fixed string + "password". This dependency is strict about it. If you want to be + permissive, use instead the `OAuth2PasswordRequestForm` dependency + class. + """ + ), + ], + username: Annotated[ + str, + Form(), + Doc( + """ + `username` string. The OAuth2 spec requires the exact field name + `username`. + """ + ), + ], + password: Annotated[ + str, + Form(), + Doc( + """ + `password` string. The OAuth2 spec requires the exact field name + `password". + """ + ), + ], + scope: Annotated[ + str, + Form(), + Doc( + """ + A single string with actually several scopes separated by spaces. Each + scope is also a string. + + For example, a single string with: + + ```python + "items:read items:write users:read profile openid" + ```` + + would represent the scopes: + + * `items:read` + * `items:write` + * `users:read` + * `profile` + * `openid` + """ + ), + ] = "", + client_id: Annotated[ + Union[str, None], + Form(), + Doc( + """ + If there's a `client_id`, it can be sent as part of the form fields. + But the OAuth2 specification recommends sending the `client_id` and + `client_secret` (if any) using HTTP Basic auth. + """ + ), + ] = None, + client_secret: Annotated[ + Union[str, None], + Form(), + Doc( + """ + If there's a `client_password` (and a `client_id`), they can be sent + as part of the form fields. But the OAuth2 specification recommends + sending the `client_id` and `client_secret` (if any) using HTTP Basic + auth. + """ + ), + ] = None, ): super().__init__( grant_type=grant_type, @@ -117,13 +306,69 @@ class OAuth2PasswordRequestFormStrict(OAuth2PasswordRequestForm): class OAuth2(SecurityBase): + """ + This is the base class for OAuth2 authentication, an instance of it would be used + as a dependency. All other OAuth2 classes inherit from it and customize it for + each OAuth2 flow. + + You normally would not create a new class inheriting from it but use one of the + existing subclasses, and maybe compose them if you want to support multiple flows. + + Read more about it in the + [FastAPI docs for Security](https://fastapi.tiangolo.com/tutorial/security/). + """ + def __init__( self, *, - flows: Union[OAuthFlowsModel, Dict[str, Dict[str, Any]]] = OAuthFlowsModel(), - scheme_name: Optional[str] = None, - description: Optional[str] = None, - auto_error: bool = True, + flows: Annotated[ + Union[OAuthFlowsModel, Dict[str, Dict[str, Any]]], + Doc( + """ + The dictionary of OAuth2 flows. + """ + ), + ] = OAuthFlowsModel(), + scheme_name: Annotated[ + Optional[str], + Doc( + """ + Security scheme name. + + It will be included in the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + Security scheme description. + + It will be included in the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + auto_error: Annotated[ + bool, + Doc( + """ + By default, if no HTTP Auhtorization header is provided, required for + OAuth2 authentication, it will automatically cancel the request and + send the client an error. + + If `auto_error` is set to `False`, when the HTTP Authorization header + is not available, instead of erroring out, the dependency result will + be `None`. + + This is useful when you want to have optional authentication. + + It is also useful when you want to have authentication that can be + provided in one of multiple optional ways (for example, with OAuth2 + or in a cookie). + """ + ), + ] = True, ): self.model = OAuth2Model( flows=cast(OAuthFlowsModel, flows), description=description @@ -144,13 +389,74 @@ class OAuth2(SecurityBase): class OAuth2PasswordBearer(OAuth2): + """ + OAuth2 flow for authentication using a bearer token obtained with a password. + An instance of it would be used as a dependency. + + Read more about it in the + [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/). + """ + def __init__( self, - tokenUrl: str, - scheme_name: Optional[str] = None, - scopes: Optional[Dict[str, str]] = None, - description: Optional[str] = None, - auto_error: bool = True, + tokenUrl: Annotated[ + str, + Doc( + """ + The URL to obtain the OAuth2 token. This would be the *path operation* + that has `OAuth2PasswordRequestForm` as a dependency. + """ + ), + ], + scheme_name: Annotated[ + Optional[str], + Doc( + """ + Security scheme name. + + It will be included in the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + scopes: Annotated[ + Optional[Dict[str, str]], + Doc( + """ + The OAuth2 scopes that would be required by the *path operations* that + use this dependency. + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + Security scheme description. + + It will be included in the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + auto_error: Annotated[ + bool, + Doc( + """ + By default, if no HTTP Auhtorization header is provided, required for + OAuth2 authentication, it will automatically cancel the request and + send the client an error. + + If `auto_error` is set to `False`, when the HTTP Authorization header + is not available, instead of erroring out, the dependency result will + be `None`. + + This is useful when you want to have optional authentication. + + It is also useful when you want to have authentication that can be + provided in one of multiple optional ways (for example, with OAuth2 + or in a cookie). + """ + ), + ] = True, ): if not scopes: scopes = {} @@ -180,15 +486,79 @@ class OAuth2PasswordBearer(OAuth2): class OAuth2AuthorizationCodeBearer(OAuth2): + """ + OAuth2 flow for authentication using a bearer token obtained with an OAuth2 code + flow. An instance of it would be used as a dependency. + """ + def __init__( self, authorizationUrl: str, - tokenUrl: str, - refreshUrl: Optional[str] = None, - scheme_name: Optional[str] = None, - scopes: Optional[Dict[str, str]] = None, - description: Optional[str] = None, - auto_error: bool = True, + tokenUrl: Annotated[ + str, + Doc( + """ + The URL to obtain the OAuth2 token. + """ + ), + ], + refreshUrl: Annotated[ + Optional[str], + Doc( + """ + The URL to refresh the token and obtain a new one. + """ + ), + ] = None, + scheme_name: Annotated[ + Optional[str], + Doc( + """ + Security scheme name. + + It will be included in the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + scopes: Annotated[ + Optional[Dict[str, str]], + Doc( + """ + The OAuth2 scopes that would be required by the *path operations* that + use this dependency. + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + Security scheme description. + + It will be included in the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + auto_error: Annotated[ + bool, + Doc( + """ + By default, if no HTTP Auhtorization header is provided, required for + OAuth2 authentication, it will automatically cancel the request and + send the client an error. + + If `auto_error` is set to `False`, when the HTTP Authorization header + is not available, instead of erroring out, the dependency result will + be `None`. + + This is useful when you want to have optional authentication. + + It is also useful when you want to have authentication that can be + provided in one of multiple optional ways (for example, with OAuth2 + or in a cookie). + """ + ), + ] = True, ): if not scopes: scopes = {} @@ -226,6 +596,45 @@ class OAuth2AuthorizationCodeBearer(OAuth2): class SecurityScopes: - def __init__(self, scopes: Optional[List[str]] = None): - self.scopes = scopes or [] - self.scope_str = " ".join(self.scopes) + """ + This is a special class that you can define in a parameter in a dependency to + obtain the OAuth2 scopes required by all the dependencies in the same chain. + + This way, multiple dependencies can have different scopes, even when used in the + same *path operation*. And with this, you can access all the scopes required in + all those dependencies in a single place. + + Read more about it in the + [FastAPI docs for OAuth2 scopes](https://fastapi.tiangolo.com/advanced/security/oauth2-scopes/). + """ + + def __init__( + self, + scopes: Annotated[ + Optional[List[str]], + Doc( + """ + This will be filled by FastAPI. + """ + ), + ] = None, + ): + self.scopes: Annotated[ + List[str], + Doc( + """ + The list of all the scopes required by dependencies. + """ + ), + ] = ( + scopes or [] + ) + self.scope_str: Annotated[ + str, + Doc( + """ + All the scopes required by all the dependencies in a single string + separated by spaces, as defined in the OAuth2 specification. + """ + ), + ] = " ".join(self.scopes) diff --git a/fastapi/security/open_id_connect_url.py b/fastapi/security/open_id_connect_url.py index 4e65f1f6c..c612b475d 100644 --- a/fastapi/security/open_id_connect_url.py +++ b/fastapi/security/open_id_connect_url.py @@ -5,16 +5,66 @@ from fastapi.security.base import SecurityBase from starlette.exceptions import HTTPException from starlette.requests import Request from starlette.status import HTTP_403_FORBIDDEN +from typing_extensions import Annotated, Doc # type: ignore [attr-defined] class OpenIdConnect(SecurityBase): + """ + OpenID Connect authentication class. An instance of it would be used as a + dependency. + """ + def __init__( self, *, - openIdConnectUrl: str, - scheme_name: Optional[str] = None, - description: Optional[str] = None, - auto_error: bool = True, + openIdConnectUrl: Annotated[ + str, + Doc( + """ + The OpenID Connect URL. + """ + ), + ], + scheme_name: Annotated[ + Optional[str], + Doc( + """ + Security scheme name. + + It will be included in the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + description: Annotated[ + Optional[str], + Doc( + """ + Security scheme description. + + It will be included in the generated OpenAPI (e.g. visible at `/docs`). + """ + ), + ] = None, + auto_error: Annotated[ + bool, + Doc( + """ + By default, if no HTTP Auhtorization header is provided, required for + OpenID Connect authentication, it will automatically cancel the request + and send the client an error. + + If `auto_error` is set to `False`, when the HTTP Authorization header + is not available, instead of erroring out, the dependency result will + be `None`. + + This is useful when you want to have optional authentication. + + It is also useful when you want to have authentication that can be + provided in one of multiple optional ways (for example, with OpenID + Connect or in a cookie). + """ + ), + ] = True, ): self.model = OpenIdConnectModel( openIdConnectUrl=openIdConnectUrl, description=description diff --git a/pyproject.toml b/pyproject.toml index b49f472d5..addde1d33 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -42,7 +42,7 @@ classifiers = [ dependencies = [ "starlette>=0.27.0,<0.28.0", "pydantic>=1.7.4,!=1.8,!=1.8.1,!=2.0.0,!=2.0.1,!=2.1.0,<3.0.0", - "typing-extensions>=4.5.0", + "typing-extensions>=4.8.0", # TODO: remove this pin after upgrading Starlette 0.31.1 "anyio>=3.7.1,<4.0.0", ] diff --git a/requirements-docs-tests.txt b/requirements-docs-tests.txt new file mode 100644 index 000000000..1a4a57267 --- /dev/null +++ b/requirements-docs-tests.txt @@ -0,0 +1,3 @@ +# For mkdocstrings and tests +httpx >=0.23.0,<0.25.0 +black == 23.3.0 diff --git a/requirements-docs.txt b/requirements-docs.txt index 2e667720e..3e0df6483 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -1,4 +1,5 @@ -e . +-r requirements-docs-tests.txt mkdocs-material==9.1.21 mdx-include >=1.4.1,<2.0.0 mkdocs-markdownextradata-plugin >=0.1.7,<0.3.0 @@ -12,3 +13,5 @@ jieba==0.42.1 pillow==9.5.0 # For image processing by Material for MkDocs cairosvg==2.7.0 +mkdocstrings[python]==0.23.0 +griffe-typingdoc==0.2.2 diff --git a/requirements-tests.txt b/requirements-tests.txt index 6f7f4ac23..de8d3f26c 100644 --- a/requirements-tests.txt +++ b/requirements-tests.txt @@ -1,11 +1,10 @@ -e . +-r requirements-docs-tests.txt pydantic-settings >=2.0.0 pytest >=7.1.3,<8.0.0 coverage[toml] >= 6.5.0,< 8.0 mypy ==1.4.1 ruff ==0.0.275 -black == 23.3.0 -httpx >=0.23.0,<0.25.0 email_validator >=1.1.1,<3.0.0 dirty-equals ==0.6.0 # TODO: once removing databases from tutorial, upgrade SQLAlchemy diff --git a/scripts/docs.py b/scripts/docs.py index 968dd9a3d..0023c670c 100644 --- a/scripts/docs.py +++ b/scripts/docs.py @@ -153,17 +153,21 @@ index_sponsors_template = """ def generate_readme_content() -> str: en_index = en_docs_path / "docs" / "index.md" content = en_index.read_text("utf-8") + match_pre = re.search(r"</style>\n\n", content) match_start = re.search(r"<!-- sponsors -->", content) match_end = re.search(r"<!-- /sponsors -->", content) sponsors_data_path = en_docs_path / "data" / "sponsors.yml" sponsors = mkdocs.utils.yaml_load(sponsors_data_path.read_text(encoding="utf-8")) if not (match_start and match_end): raise RuntimeError("Couldn't auto-generate sponsors section") + if not match_pre: + raise RuntimeError("Couldn't find pre section (<style>) in index.md") + frontmatter_end = match_pre.end() pre_end = match_start.end() post_start = match_end.start() template = Template(index_sponsors_template) message = template.render(sponsors=sponsors) - pre_content = content[:pre_end] + pre_content = content[frontmatter_end:pre_end] post_content = content[post_start:] new_content = pre_content + message + post_content return new_content @@ -286,7 +290,6 @@ def update_config() -> None: else: use_name = alternate_dict[url] new_alternate.append({"link": url, "name": use_name}) - config["nav"][1] = {"Languages": languages} config["extra"]["alternate"] = new_alternate en_config_path.write_text( yaml.dump(config, sort_keys=False, width=200, allow_unicode=True), diff --git a/scripts/mkdocs_hooks.py b/scripts/mkdocs_hooks.py index 008751f8a..b12487b50 100644 --- a/scripts/mkdocs_hooks.py +++ b/scripts/mkdocs_hooks.py @@ -8,6 +8,11 @@ from mkdocs.structure.files import File, Files from mkdocs.structure.nav import Link, Navigation, Section from mkdocs.structure.pages import Page +non_traslated_sections = [ + "reference/", + "release-notes.md", +] + @lru_cache() def get_missing_translation_content(docs_dir: str) -> str: @@ -123,6 +128,9 @@ def on_page_markdown( markdown: str, *, page: Page, config: MkDocsConfig, files: Files ) -> str: if isinstance(page.file, EnFile): + for excluded_section in non_traslated_sections: + if page.file.src_path.startswith(excluded_section): + return markdown missing_translation_content = get_missing_translation_content(config.docs_dir) header = "" body = markdown diff --git a/tests/test_datastructures.py b/tests/test_datastructures.py index b91467265..7e57d525c 100644 --- a/tests/test_datastructures.py +++ b/tests/test_datastructures.py @@ -1,3 +1,4 @@ +import io from pathlib import Path from typing import List @@ -52,3 +53,20 @@ def test_upload_file_is_closed(tmp_path: Path): assert testing_file_store assert testing_file_store[0].file.closed + + +# For UploadFile coverage, segments copied from Starlette tests + + +@pytest.mark.anyio +async def test_upload_file(): + stream = io.BytesIO(b"data") + file = UploadFile(filename="file", file=stream, size=4) + assert await file.read() == b"data" + assert file.size == 4 + await file.write(b" and more data!") + assert await file.read() == b"" + assert file.size == 19 + await file.seek(0) + assert await file.read() == b"data and more data!" + await file.close() diff --git a/tests/test_router_events.py b/tests/test_router_events.py index ba6b76382..1b9de18ae 100644 --- a/tests/test_router_events.py +++ b/tests/test_router_events.py @@ -21,6 +21,9 @@ def state() -> State: return State() +@pytest.mark.filterwarnings( + r"ignore:\s*on_event is deprecated, use lifespan event handlers instead.*:DeprecationWarning" +) def test_router_events(state: State) -> None: app = FastAPI() diff --git a/tests/test_tutorial/test_async_sql_databases/test_tutorial001.py b/tests/test_tutorial/test_async_sql_databases/test_tutorial001.py index 25d6df3e9..13568a532 100644 --- a/tests/test_tutorial/test_async_sql_databases/test_tutorial001.py +++ b/tests/test_tutorial/test_async_sql_databases/test_tutorial001.py @@ -1,13 +1,20 @@ +import pytest +from fastapi import FastAPI from fastapi.testclient import TestClient -from docs_src.async_sql_databases.tutorial001 import app - from ...utils import needs_pydanticv1 +@pytest.fixture(name="app", scope="module") +def get_app(): + with pytest.warns(DeprecationWarning): + from docs_src.async_sql_databases.tutorial001 import app + yield app + + # TODO: pv2 add version with Pydantic v2 @needs_pydanticv1 -def test_create_read(): +def test_create_read(app: FastAPI): with TestClient(app) as client: note = {"text": "Foo bar", "completed": False} response = client.post("/notes/", json=note) @@ -21,7 +28,7 @@ def test_create_read(): assert data in response.json() -def test_openapi_schema(): +def test_openapi_schema(app: FastAPI): with TestClient(app) as client: response = client.get("/openapi.json") assert response.status_code == 200, response.text diff --git a/tests/test_tutorial/test_events/test_tutorial001.py b/tests/test_tutorial/test_events/test_tutorial001.py index a5bb299ac..f65b92d12 100644 --- a/tests/test_tutorial/test_events/test_tutorial001.py +++ b/tests/test_tutorial/test_events/test_tutorial001.py @@ -1,16 +1,23 @@ +import pytest +from fastapi import FastAPI from fastapi.testclient import TestClient -from docs_src.events.tutorial001 import app +@pytest.fixture(name="app", scope="module") +def get_app(): + with pytest.warns(DeprecationWarning): + from docs_src.events.tutorial001 import app + yield app -def test_events(): + +def test_events(app: FastAPI): with TestClient(app) as client: response = client.get("/items/foo") assert response.status_code == 200, response.text assert response.json() == {"name": "Fighters"} -def test_openapi_schema(): +def test_openapi_schema(app: FastAPI): with TestClient(app) as client: response = client.get("/openapi.json") assert response.status_code == 200, response.text diff --git a/tests/test_tutorial/test_events/test_tutorial002.py b/tests/test_tutorial/test_events/test_tutorial002.py index 81cbf4ab6..137294d73 100644 --- a/tests/test_tutorial/test_events/test_tutorial002.py +++ b/tests/test_tutorial/test_events/test_tutorial002.py @@ -1,9 +1,16 @@ +import pytest +from fastapi import FastAPI from fastapi.testclient import TestClient -from docs_src.events.tutorial002 import app +@pytest.fixture(name="app", scope="module") +def get_app(): + with pytest.warns(DeprecationWarning): + from docs_src.events.tutorial002 import app + yield app -def test_events(): + +def test_events(app: FastAPI): with TestClient(app) as client: response = client.get("/items/") assert response.status_code == 200, response.text @@ -12,7 +19,7 @@ def test_events(): assert "Application shutdown" in log.read() -def test_openapi_schema(): +def test_openapi_schema(app: FastAPI): with TestClient(app) as client: response = client.get("/openapi.json") assert response.status_code == 200, response.text diff --git a/tests/test_tutorial/test_testing/test_tutorial003.py b/tests/test_tutorial/test_testing/test_tutorial003.py index d9e16390e..2a5d67071 100644 --- a/tests/test_tutorial/test_testing/test_tutorial003.py +++ b/tests/test_tutorial/test_testing/test_tutorial003.py @@ -1,5 +1,7 @@ -from docs_src.app_testing.tutorial003 import test_read_items +import pytest def test_main(): + with pytest.warns(DeprecationWarning): + from docs_src.app_testing.tutorial003 import test_read_items test_read_items() From f056d001e5fe2b29f00cdc8e68f3c01feb40ce89 Mon Sep 17 00:00:00 2001 From: github-actions <github-actions@github.com> Date: Wed, 18 Oct 2023 12:37:29 +0000 Subject: [PATCH 12/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 62ffd4b35..c3485050f 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -7,6 +7,7 @@ hide: ## Latest Changes +* โœจ Add reference (code API) docs with PEP 727, add subclass with custom docstrings for `BackgroundTasks`, refactor docs structure. PR [#10392](https://github.com/tiangolo/fastapi/pull/10392) by [@tiangolo](https://github.com/tiangolo). * โฌ† Bump dawidd6/action-download-artifact from 2.27.0 to 2.28.0. PR [#10268](https://github.com/tiangolo/fastapi/pull/10268) by [@dependabot[bot]](https://github.com/apps/dependabot). * โฌ† Bump actions/checkout from 3 to 4. PR [#10208](https://github.com/tiangolo/fastapi/pull/10208) by [@dependabot[bot]](https://github.com/apps/dependabot). * โฌ† Bump pypa/gh-action-pypi-publish from 1.8.6 to 1.8.10. PR [#10061](https://github.com/tiangolo/fastapi/pull/10061) by [@dependabot[bot]](https://github.com/apps/dependabot). From 76e547f254f92a06d9b5a103dfa32693c3d38451 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= <tiangolo@gmail.com> Date: Wed, 18 Oct 2023 16:50:22 +0400 Subject: [PATCH 13/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/release-notes.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index c3485050f..e49394e72 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -7,13 +7,22 @@ hide: ## Latest Changes -* โœจ Add reference (code API) docs with PEP 727, add subclass with custom docstrings for `BackgroundTasks`, refactor docs structure. PR [#10392](https://github.com/tiangolo/fastapi/pull/10392) by [@tiangolo](https://github.com/tiangolo). +## Features + +* โœจ Add reference (code API) docs with PEP 727, add subclass with custom docstrings for `BackgroundTasks`, refactor docs structure. PR [#10392](https://github.com/tiangolo/fastapi/pull/10392) by [@tiangolo](https://github.com/tiangolo). New docs at [FastAPI Reference - Code API](https://fastapi.tiangolo.com/reference/). + +## Upgrades + +* โฌ†๏ธ Drop support for Python 3.7, require Python 3.8 or above. PR [#10442](https://github.com/tiangolo/fastapi/pull/10442) by [@tiangolo](https://github.com/tiangolo). + +### Internal + * โฌ† Bump dawidd6/action-download-artifact from 2.27.0 to 2.28.0. PR [#10268](https://github.com/tiangolo/fastapi/pull/10268) by [@dependabot[bot]](https://github.com/apps/dependabot). * โฌ† Bump actions/checkout from 3 to 4. PR [#10208](https://github.com/tiangolo/fastapi/pull/10208) by [@dependabot[bot]](https://github.com/apps/dependabot). * โฌ† Bump pypa/gh-action-pypi-publish from 1.8.6 to 1.8.10. PR [#10061](https://github.com/tiangolo/fastapi/pull/10061) by [@dependabot[bot]](https://github.com/apps/dependabot). -* โฌ†๏ธ Drop support for Python 3.7, require Python 3.8 or above. PR [#10442](https://github.com/tiangolo/fastapi/pull/10442) by [@tiangolo](https://github.com/tiangolo). * ๐Ÿ”ง Update sponsors, Bump.sh images. PR [#10381](https://github.com/tiangolo/fastapi/pull/10381) by [@tiangolo](https://github.com/tiangolo). * ๐Ÿ‘ฅ Update FastAPI People. PR [#10363](https://github.com/tiangolo/fastapi/pull/10363) by [@tiangolo](https://github.com/tiangolo). + ## 0.103.2 ### Refactors From 38f191dcd30c7e7b7d422b4406f8eb8c6805b09d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= <tiangolo@gmail.com> Date: Wed, 18 Oct 2023 16:51:07 +0400 Subject: [PATCH 14/38] =?UTF-8?q?=F0=9F=94=96=20Release=20version=200.104.?= =?UTF-8?q?0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/release-notes.md | 2 ++ fastapi/__init__.py | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index e49394e72..b78b2cb5a 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -7,6 +7,8 @@ hide: ## Latest Changes +## 0.104.0 + ## Features * โœจ Add reference (code API) docs with PEP 727, add subclass with custom docstrings for `BackgroundTasks`, refactor docs structure. PR [#10392](https://github.com/tiangolo/fastapi/pull/10392) by [@tiangolo](https://github.com/tiangolo). New docs at [FastAPI Reference - Code API](https://fastapi.tiangolo.com/reference/). diff --git a/fastapi/__init__.py b/fastapi/__init__.py index 981ca4945..4fdb155c2 100644 --- a/fastapi/__init__.py +++ b/fastapi/__init__.py @@ -1,6 +1,6 @@ """FastAPI framework, high performance, easy to learn, fast to code, ready for production""" -__version__ = "0.103.2" +__version__ = "0.104.0" from starlette import status as status From c13aa9ed5f19feccdb41a8af465cbaa1de218630 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= <tiangolo@gmail.com> Date: Fri, 20 Oct 2023 12:27:26 +0400 Subject: [PATCH 15/38] =?UTF-8?q?=F0=9F=94=A5=20Remove=20unnecessary=20dup?= =?UTF-8?q?licated=20docstrings=20(#10484)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- fastapi/applications.py | 7 ------- fastapi/routing.py | 7 ------- 2 files changed, 14 deletions(-) diff --git a/fastapi/applications.py b/fastapi/applications.py index 46b7ae81b..8ca374a54 100644 --- a/fastapi/applications.py +++ b/fastapi/applications.py @@ -86,13 +86,6 @@ class FastAPI(Starlette): **Note**: you probably shouldn't use this parameter, it is inherited from Starlette and supported for compatibility. - In FastAPI, you normally would use the *path operation* decorators, - like: - - * `app.get()` - * `app.post()` - * etc. - --- A list of routes to serve incoming HTTP and WebSocket requests. diff --git a/fastapi/routing.py b/fastapi/routing.py index e33e1d832..54d53bbbf 100644 --- a/fastapi/routing.py +++ b/fastapi/routing.py @@ -624,13 +624,6 @@ class APIRouter(routing.Router): **Note**: you probably shouldn't use this parameter, it is inherited from Starlette and supported for compatibility. - In FastAPI, you normally would use the *path operation* decorators, - like: - - * `router.get()` - * `router.post()` - * etc. - --- A list of routes to serve incoming HTTP and WebSocket requests. From 7670a132b3ce3374ed52c02659989a07da406985 Mon Sep 17 00:00:00 2001 From: github-actions <github-actions@github.com> Date: Fri, 20 Oct 2023 08:28:05 +0000 Subject: [PATCH 16/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index b78b2cb5a..90ad69c28 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -7,6 +7,7 @@ hide: ## Latest Changes +* ๐Ÿ”ฅ Remove unnecessary duplicated docstrings. PR [#10484](https://github.com/tiangolo/fastapi/pull/10484) by [@tiangolo](https://github.com/tiangolo). ## 0.104.0 ## Features From dc7838eec310454d9b1a41712e75d220e18e2bdd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= <tiangolo@gmail.com> Date: Fri, 20 Oct 2023 12:39:03 +0400 Subject: [PATCH 17/38] =?UTF-8?q?=F0=9F=94=A5=20Drop/close=20Gitter=20chat?= =?UTF-8?q?.=20Questions=20should=20go=20to=20GitHub=20Discussions,=20free?= =?UTF-8?q?=20conversations=20to=20Discord.=20(#10485)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/em/docs/help-fastapi.md | 2 - docs/en/docs/help-fastapi.md | 2 - docs/en/docs/js/chat.js | 3 -- docs/fr/docs/help-fastapi.md | 18 --------- docs/ja/docs/help-fastapi.md | 14 ------- docs/pl/docs/help-fastapi.md | 2 - docs/pt/docs/help-fastapi.md | 2 - docs/ru/docs/help-fastapi.md | 2 - docs/zh/docs/help-fastapi.md | 2 - scripts/gitter_releases_bot.py | 67 ---------------------------------- scripts/notify.sh | 5 --- 11 files changed, 119 deletions(-) delete mode 100644 docs/en/docs/js/chat.js delete mode 100644 scripts/gitter_releases_bot.py delete mode 100755 scripts/notify.sh diff --git a/docs/em/docs/help-fastapi.md b/docs/em/docs/help-fastapi.md index d7b66185d..b998ade42 100644 --- a/docs/em/docs/help-fastapi.md +++ b/docs/em/docs/help-fastapi.md @@ -231,8 +231,6 @@ โš™๏ธ ๐Ÿ’ฌ ๐Ÿ•ด ๐ŸŽ ๐Ÿข ๐Ÿ’ฌ. -๐Ÿ“ค โฎ๏ธ <a href="https://gitter.im/tiangolo/fastapi" class="external-link" target="_blank">๐ŸฅŠ ๐Ÿ’ฌ</a>, โœ‹๏ธ โšซ๏ธ ๐Ÿšซ โœ”๏ธ ๐Ÿ“ป & ๐Ÿง โš’, ๐Ÿ’ฌ ๐ŸŒ– โš , ๐Ÿ˜ง ๐Ÿ”œ ๐Ÿ‘ โš™๏ธ. - ### ๐Ÿšซ โš™๏ธ ๐Ÿ’ฌ โ” โœ”๏ธ ๐Ÿคฏ ๐Ÿ‘ˆ ๐Ÿ’ฌ โœ” ๐ŸŒ… "๐Ÿ†“ ๐Ÿ’ฌ", โšซ๏ธ โฉ ๐Ÿ’ญ โ” ๐Ÿ‘ˆ ๐Ÿ’โ€โ™‚๏ธ ๐Ÿข & ๐ŸŒ… โš  โ”,, ๐Ÿ‘† ๐Ÿ’ช ๐Ÿšซ ๐Ÿ“จ โ”. diff --git a/docs/en/docs/help-fastapi.md b/docs/en/docs/help-fastapi.md index e977dba20..8199c9b9a 100644 --- a/docs/en/docs/help-fastapi.md +++ b/docs/en/docs/help-fastapi.md @@ -231,8 +231,6 @@ Join the ๐Ÿ‘ฅ <a href="https://discord.gg/VQjSZaeJmf" class="external-link" targ Use the chat only for other general conversations. -There is also the previous <a href="https://gitter.im/tiangolo/fastapi" class="external-link" target="_blank">Gitter chat</a>, but as it doesn't have channels and advanced features, conversations are more difficult, so Discord is now the recommended system. - ### Don't use the chat for questions Have in mind that as chats allow more "free conversation", it's easy to ask questions that are too general and more difficult to answer, so, you might not receive answers. diff --git a/docs/en/docs/js/chat.js b/docs/en/docs/js/chat.js deleted file mode 100644 index debdef4da..000000000 --- a/docs/en/docs/js/chat.js +++ /dev/null @@ -1,3 +0,0 @@ -((window.gitter = {}).chat = {}).options = { - room: 'tiangolo/fastapi' -}; diff --git a/docs/fr/docs/help-fastapi.md b/docs/fr/docs/help-fastapi.md index 3bc3c3a8a..525c699f5 100644 --- a/docs/fr/docs/help-fastapi.md +++ b/docs/fr/docs/help-fastapi.md @@ -84,24 +84,6 @@ Vous pouvez <a href="https://github.com/tiangolo/fastapi" class="external-link" * Pour corriger une Issue/Bug existant. * Pour ajouter une nouvelle fonctionnalitรฉ. -## Rejoindre le chat - -<a href="https://gitter.im/tiangolo/fastapi?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge" target="_blank"> - <img src="https://badges.gitter.im/tiangolo/fastapi.svg" alt="Rejoindre le chat ร  https://gitter.im/tiangolo/fastapi"> -</a> - -Rejoignez le chat sur Gitter: <a href="https://gitter.im/tiangolo/fastapi" class="external-link" target="_blank">https://gitter.im/tiangolo/fastapi</a>. - -Vous pouvez y avoir des conversations rapides avec d'autres personnes, aider les autres, partager des idรฉes, etc. - -Mais gardez ร  l'esprit que, comme il permet une "conversation plus libre", il est facile de poser des questions trop gรฉnรฉrales et plus difficiles ร  rรฉpondre, de sorte que vous risquez de ne pas recevoir de rรฉponses. - -Dans les Issues de GitHub, le modรจle vous guidera pour รฉcrire la bonne question afin que vous puissiez plus facilement obtenir une bonne rรฉponse, ou mรชme rรฉsoudre le problรจme vous-mรชme avant mรชme de le poser. Et dans GitHub, je peux m'assurer que je rรฉponds toujours ร  tout, mรชme si cela prend du temps. Je ne peux pas faire cela personnellement avec le chat Gitter. ๐Ÿ˜… - -Les conversations dans Gitter ne sont pas non plus aussi facilement consultables que dans GitHub, de sorte que les questions et les rรฉponses peuvent se perdre dans la conversation. - -De l'autre cรดtรฉ, il y a plus de 1000 personnes dans le chat, il y a donc de fortes chances que vous y trouviez quelqu'un ร  qui parler, presque tout le temps. ๐Ÿ˜„ - ## Parrainer l'auteur Vous pouvez รฉgalement soutenir financiรจrement l'auteur (moi) via <a href="https://github.com/sponsors/tiangolo" class="external-link" target="_blank">GitHub sponsors</a>. diff --git a/docs/ja/docs/help-fastapi.md b/docs/ja/docs/help-fastapi.md index 166acb586..e753b7ce3 100644 --- a/docs/ja/docs/help-fastapi.md +++ b/docs/ja/docs/help-fastapi.md @@ -82,20 +82,6 @@ GitHubใƒฌใƒใ‚ธใƒˆใƒชใง<a href="https://github.com/tiangolo/fastapi/issues/new/ * ๆ—ขๅญ˜ใฎissue/ใƒใ‚ฐใ‚’ไฟฎๆญฃใ€‚ * ๆ–ฐๆฉŸ่ƒฝใ‚’่ฟฝๅŠ ใ€‚ -## ใƒใƒฃใƒƒใƒˆใซๅ‚ๅŠ  - -Gitterใงใƒใƒฃใƒƒใƒˆใซๅ‚ๅŠ : <a href="https://gitter.im/tiangolo/fastapi" class="external-link" target="_blank">https://gitter.im/tiangolo/fastapi</a>. - -ใใ“ใงใ€ไป–ใฎไบบใจๆ‰‹ๆ—ฉใไผš่ฉฑใ—ใŸใ‚Šใ€ๆ‰‹ๅŠฉใ‘ใ‚„ใ‚ขใ‚คใƒ‡ใ‚ขใฎๅ…ฑๆœ‰ใชใฉใŒใงใใพใ™ใ€‚ - -ใ—ใ‹ใ—ใ€ใ€Œ่‡ช็”ฑใชไผš่ฉฑใ€ใŒ่จฑๅฎนใ•ใ‚Œใฆใ„ใ‚‹ใฎใงไธ€่ˆฌ็š„ใ™ใŽใฆๅ›ž็ญ”ใŒ้›ฃใ—ใ„่ณชๅ•ใ‚‚ใ—ใ‚„ใ™ใใชใ‚Šใพใ™ใ€‚ใใฎใ›ใ„ใงๅ›ž็ญ”ใ‚’ๅพ—ใ‚‰ใ‚Œใชใ„ใ‹ใ‚‚ใ—ใ‚Œใพใ›ใ‚“ใ€‚ - -GitHub issuesใงใฏ่‰ฏใ„ๅ›ž็ญ”ใ‚’ๅพ—ใ‚„ใ™ใ„่ณชๅ•ใŒใงใใ‚‹ใ‚ˆใ†ใซใ€ใ‚‚ใ—ใใฏใ€่ณชๅ•ใ™ใ‚‹ๅ‰ใซ่‡ช่บซใง่งฃๆฑบใงใใ‚‹ใ‚ˆใ†ใซใƒ†ใƒณใƒ—ใƒฌใƒผใƒˆใŒใ‚ฌใ‚คใƒ‰ใ—ใฆใใ‚Œใพใ™ใ€‚ใใ—ใฆใ€GitHubใงใฏใŸใจใˆๆ™‚้–“ใŒใ‹ใ‹ใฃใฆใ‚‚ๅ…จใฆใซ็ญ”ใˆใฆใ„ใ‚‹ใ‹็ขบ่ชใงใใพใ™ใ€‚ๅ€‹ไบบ็š„ใซใฏGitterใƒใƒฃใƒƒใƒˆใงใฏๅŒใ˜ใ“ใจใฏใงใใชใ„ใงใ™ใ€‚๐Ÿ˜… - -Gitterใงใฎไผš่ฉฑใฏGitHubใปใฉ็ฐกๅ˜ใซๆคœ็ดขใงใใชใ„ใฎใงใ€่ณชๅ•ใจๅ›ž็ญ”ใŒไผš่ฉฑใฎไธญใซๅŸ‹ใ‚‚ใ‚Œใฆใ—ใพใ„ใพใ™ใ€‚ - -ไธ€ๆ–นใ€ใƒใƒฃใƒƒใƒˆใซใฏ1000ไบบไปฅไธŠใ„ใ‚‹ใฎใงใ€ใ„ใคใงใ‚‚่ฉฑใ—็›ธๆ‰‹ใŒ่ฆ‹ใคใ‹ใ‚‹ๅฏ่ƒฝๆ€งใŒ้ซ˜ใ„ใงใ™ใ€‚๐Ÿ˜„ - ## ้–‹็™บ่€…ใฎใ‚นใƒใƒณใ‚ตใƒผใซใชใ‚‹ <a href="https://github.com/sponsors/tiangolo" class="external-link" target="_blank">GitHub sponsors</a>ใ‚’้€šใ—ใฆ้–‹็™บ่€…ใ‚’็ตŒๆธˆ็š„ใซใ‚ตใƒใƒผใƒˆใงใใพใ™ใ€‚ diff --git a/docs/pl/docs/help-fastapi.md b/docs/pl/docs/help-fastapi.md index 723df91d1..3d02a8741 100644 --- a/docs/pl/docs/help-fastapi.md +++ b/docs/pl/docs/help-fastapi.md @@ -231,8 +231,6 @@ Doล‚ฤ…cz do ๐Ÿ‘ฅ <a href="https://discord.gg/VQjSZaeJmf" class="external-link" t Uลผywaj czatu tylko do innych ogรณlnych rozmรณw. -Istnieje rรณwnieลผ poprzedni <a href="https://gitter.im/tiangolo/fastapi" class="external-link" target="_blank">czat na Gitter</a>, ale poniewaลผ nie ma tam kanaล‚รณw i zaawansowanych funkcji, rozmowy sฤ… trudniejsze, dlatego teraz zalecany jest Discord. - ### Nie zadawaj pytaล„ na czacie Miej na uwadze, ลผe poniewaลผ czaty pozwalajฤ… na bardziej "swobodnฤ… rozmowฤ™", ล‚atwo jest zadawaฤ‡ pytania, ktรณre sฤ… zbyt ogรณlne i trudniejsze do odpowiedzi, wiฤ™c moลผesz nie otrzymaฤ‡ odpowiedzi. diff --git a/docs/pt/docs/help-fastapi.md b/docs/pt/docs/help-fastapi.md index d82ce3414..d04905197 100644 --- a/docs/pt/docs/help-fastapi.md +++ b/docs/pt/docs/help-fastapi.md @@ -114,8 +114,6 @@ do FastAPI. Use o chat apenas para outro tipo de assunto. -Tambรฉm existe o <a href="https://gitter.im/tiangolo/fastapi" class="external-link" target="_blank">chat do Gitter</a>, 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. diff --git a/docs/ru/docs/help-fastapi.md b/docs/ru/docs/help-fastapi.md index a69e37bd8..65ff768d1 100644 --- a/docs/ru/docs/help-fastapi.md +++ b/docs/ru/docs/help-fastapi.md @@ -223,8 +223,6 @@ ะ˜ัะฟะพะปัŒะทัƒะนั‚ะต ัั‚ะพั‚ ั‡ะฐั‚ ั‚ะพะปัŒะบะพ ะดะปั ะฑะตัะตะด ะฝะฐ ะพั‚ะฒะปะตั‡ั‘ะฝะฝั‹ะต ั‚ะตะผั‹. -ะกัƒั‰ะตัั‚ะฒัƒะตั‚ ั‚ะฐะบะถะต <a href="https://gitter.im/tiangolo/fastapi" class="external-link" target="_blank">ั‡ะฐั‚ ะฒ Gitter</a>, ะฝะพ ะฟะพัะบะพะปัŒะบัƒ ะฒ ะฝะตะผ ะฝะตั‚ ะบะฐะฝะฐะปะพะฒ ะธ ั€ะฐััˆะธั€ะตะฝะฝั‹ั… ั„ัƒะฝะบั†ะธะน, ะพะฑั‰ะตะฝะธะต ะฒ ะฝั‘ะผ ัะปะพะถะฝะตะต, ะฟะพั‚ะพะผัƒ ั€ะตะบะพะผะตะฝะดัƒะตะผะพะน ัะธัั‚ะตะผะพะน ัะฒะปัะตั‚ัั Discord. - ### ะะต ะธัะฟะพะปัŒะทะพะฒะฐั‚ัŒ ั‡ะฐั‚ั‹ ะดะปั ะฒะพะฟั€ะพัะพะฒ ะ˜ะผะตะนั‚ะต ะฒ ะฒะธะดัƒ, ั‡ั‚ะพ ั‡ะฐั‚ั‹ ะฟะพะทะฒะพะปััŽั‚ ะฑะพะปัŒัˆะต "ัะฒะพะฑะพะดะฝะพะณะพ ะพะฑั‰ะตะฝะธั", ะฟะพั‚ะพะผัƒ ั‚ะฐะผ ะปะตะณะบะพ ะทะฐะดะฐะฒะฐั‚ัŒ ะฒะพะฟั€ะพัั‹, ะบะพั‚ะพั€ั‹ะต ัะปะธัˆะบะพะผ ะพะฑั‰ะธะต ะธ ะฝะฐ ะบะพั‚ะพั€ั‹ะต ั‚ั€ัƒะดะฝะตะต ะพั‚ะฒะตั‚ะธั‚ัŒ, ั‚ะฐะบ ั‡ั‚ะพ ะ’ั‹ ะผะพะถะตั‚ะต ะฝะต ะฟะพะปัƒั‡ะธั‚ัŒ ะฝัƒะถะฝั‹ะต ะ’ะฐะผ ะพั‚ะฒะตั‚ั‹. diff --git a/docs/zh/docs/help-fastapi.md b/docs/zh/docs/help-fastapi.md index 2a99950e3..9b70d115a 100644 --- a/docs/zh/docs/help-fastapi.md +++ b/docs/zh/docs/help-fastapi.md @@ -114,8 +114,6 @@ ่Šๅคฉๅฎคไป…ไพ›้—ฒ่Šใ€‚ -ๆˆ‘ไปฌไน‹ๅ‰่ฟ˜ไฝฟ็”จ่ฟ‡ <a href="https://gitter.im/tiangolo/fastapi" class="external-link" target="_blank">Gitter chat</a>๏ผŒไฝ†ๅฎƒไธๆ”ฏๆŒ้ข‘้“็ญ‰้ซ˜็บงๅŠŸ่ƒฝ๏ผŒ่ŠๅคฉไนŸๆฏ”่พƒ้บป็ƒฆ๏ผŒๆ‰€ไปฅ็ŽฐๅœจๆŽจ่ไฝฟ็”จ Discordใ€‚ - ### ๅˆซๅœจ่Šๅคฉๅฎค้‡Œๆ้—ฎ ๆณจๆ„๏ผŒ่Šๅคฉๅฎคๆ›ดๅ€พๅ‘ไบŽโ€œ้—ฒ่Šโ€๏ผŒ็ปๅธธๆœ‰ไบบไผšๆๅ‡บไธ€ไบ›็ฌผ็ปŸๅพ—่ฎฉไบบ้šพไปฅๅ›ž็ญ”็š„้—ฎ้ข˜๏ผŒๆ‰€ไปฅๅœจ่ฟ™้‡Œๆ้—ฎไธ€่ˆฌๆฒกไบบๅ›ž็ญ”ใ€‚ diff --git a/scripts/gitter_releases_bot.py b/scripts/gitter_releases_bot.py deleted file mode 100644 index a033d0d69..000000000 --- a/scripts/gitter_releases_bot.py +++ /dev/null @@ -1,67 +0,0 @@ -import inspect -import os - -import requests - -room_id = "5c9c9540d73408ce4fbc1403" # FastAPI -# room_id = "5cc46398d73408ce4fbed233" # Gitter development - -gitter_token = os.getenv("GITTER_TOKEN") -assert gitter_token -github_token = os.getenv("GITHUB_TOKEN") -assert github_token -tag_name = os.getenv("TAG") -assert tag_name - - -def get_github_graphql(tag_name: str): - github_graphql = """ - { - repository(owner: "tiangolo", name: "fastapi") { - release (tagName: "{{tag_name}}" ) { - description - } - } - } - """ - github_graphql = github_graphql.replace("{{tag_name}}", tag_name) - return github_graphql - - -def get_github_release_text(tag_name: str): - url = "https://api.github.com/graphql" - headers = {"Authorization": f"Bearer {github_token}"} - github_graphql = get_github_graphql(tag_name=tag_name) - response = requests.post(url, json={"query": github_graphql}, headers=headers) - assert response.status_code == 200 - data = response.json() - return data["data"]["repository"]["release"]["description"] - - -def get_gitter_message(release_text: str): - text = f""" - New release! :tada: :rocket: - (by FastAPI bot) - - ## {tag_name} - """ - text = inspect.cleandoc(text) + "\n\n" + release_text - return text - - -def send_gitter_message(text: str): - headers = {"Authorization": f"Bearer {gitter_token}"} - url = f"https://api.gitter.im/v1/rooms/{room_id}/chatMessages" - data = {"text": text} - response = requests.post(url, headers=headers, json=data) - assert response.status_code == 200 - - -def main(): - release_text = get_github_release_text(tag_name=tag_name) - text = get_gitter_message(release_text=release_text) - send_gitter_message(text=text) - - -if __name__ == "__main__": - main() diff --git a/scripts/notify.sh b/scripts/notify.sh deleted file mode 100755 index 8ce550026..000000000 --- a/scripts/notify.sh +++ /dev/null @@ -1,5 +0,0 @@ -#!/usr/bin/env bash - -set -e - -python scripts/gitter_releases_bot.py From dcbe7f7ac0a6503254c8ac90924950b9cfb8fbf0 Mon Sep 17 00:00:00 2001 From: github-actions <github-actions@github.com> Date: Fri, 20 Oct 2023 08:39:45 +0000 Subject: [PATCH 18/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 90ad69c28..0cfb193e3 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -7,6 +7,7 @@ hide: ## Latest Changes +* ๐Ÿ”ฅ Drop/close Gitter chat. Questions should go to GitHub Discussions, free conversations to Discord.. PR [#10485](https://github.com/tiangolo/fastapi/pull/10485) by [@tiangolo](https://github.com/tiangolo). * ๐Ÿ”ฅ Remove unnecessary duplicated docstrings. PR [#10484](https://github.com/tiangolo/fastapi/pull/10484) by [@tiangolo](https://github.com/tiangolo). ## 0.104.0 From 6eb30959bc5486ec19b31675d92744d10d11c9ba Mon Sep 17 00:00:00 2001 From: Tiago Silva <tiago.arasilva@gmail.com> Date: Fri, 20 Oct 2023 09:52:59 +0100 Subject: [PATCH 19/38] =?UTF-8?q?=E2=9C=8F=EF=B8=8F=20Fix=20typo=20in=20`d?= =?UTF-8?q?ocs/en/docs/reference/index.md`=20(#10467)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fix small typo in reference/index.md --- docs/en/docs/reference/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/docs/reference/index.md b/docs/en/docs/reference/index.md index 994b3c38c..512d5c25c 100644 --- a/docs/en/docs/reference/index.md +++ b/docs/en/docs/reference/index.md @@ -1,7 +1,7 @@ # Reference - Code API Here's the reference or code API, the classes, functions, parameters, attributes, and -all the FastAPI parts you can use in you applications. +all the FastAPI parts you can use in your applications. If you want to **learn FastAPI** you are much better off reading the [FastAPI Tutorial](https://fastapi.tiangolo.com/tutorial/). From 968afca0581f24b9a0e6e58bc21d03bd181b8a59 Mon Sep 17 00:00:00 2001 From: github-actions <github-actions@github.com> Date: Fri, 20 Oct 2023 08:53:37 +0000 Subject: [PATCH 20/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 0cfb193e3..00e369236 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -7,6 +7,7 @@ hide: ## Latest Changes +* โœ๏ธ Fix typo in `docs/en/docs/reference/index.md`. PR [#10467](https://github.com/tiangolo/fastapi/pull/10467) by [@tarsil](https://github.com/tarsil). * ๐Ÿ”ฅ Drop/close Gitter chat. Questions should go to GitHub Discussions, free conversations to Discord.. PR [#10485](https://github.com/tiangolo/fastapi/pull/10485) by [@tiangolo](https://github.com/tiangolo). * ๐Ÿ”ฅ Remove unnecessary duplicated docstrings. PR [#10484](https://github.com/tiangolo/fastapi/pull/10484) by [@tiangolo](https://github.com/tiangolo). ## 0.104.0 From 57a030175e7027ba0200c78521efc44800b6fd52 Mon Sep 17 00:00:00 2001 From: yogabonito <yogabonito@users.noreply.github.com> Date: Fri, 20 Oct 2023 10:55:30 +0200 Subject: [PATCH 21/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20docs,=20remove=20?= =?UTF-8?q?references=20to=20removed=20`pydantic.Required`=20in=20`docs/en?= =?UTF-8?q?/docs/tutorial/query-params-str-validations.md`=20(#10469)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../tutorial/query-params-str-validations.md | 27 +------------------ 1 file changed, 1 insertion(+), 26 deletions(-) diff --git a/docs/en/docs/tutorial/query-params-str-validations.md b/docs/en/docs/tutorial/query-params-str-validations.md index 0b2cf02a8..0e777f6a0 100644 --- a/docs/en/docs/tutorial/query-params-str-validations.md +++ b/docs/en/docs/tutorial/query-params-str-validations.md @@ -502,33 +502,8 @@ To do that, you can declare that `None` is a valid type but still use `...` as t !!! tip Pydantic, which is what powers all the data validation and serialization in FastAPI, has a special behavior when you use `Optional` or `Union[Something, None]` without a default value, you can read more about it in the Pydantic docs about <a href="https://pydantic-docs.helpmanual.io/usage/models/#required-optional-fields" class="external-link" target="_blank">Required Optional fields</a>. -### Use Pydantic's `Required` instead of Ellipsis (`...`) - -If you feel uncomfortable using `...`, you can also import and use `Required` from Pydantic: - -=== "Python 3.9+" - - ```Python hl_lines="4 10" - {!> ../../../docs_src/query_params_str_validations/tutorial006d_an_py39.py!} - ``` - -=== "Python 3.8+" - - ```Python hl_lines="2 9" - {!> ../../../docs_src/query_params_str_validations/tutorial006d_an.py!} - ``` - -=== "Python 3.8+ non-Annotated" - - !!! tip - Prefer to use the `Annotated` version if possible. - - ```Python hl_lines="2 8" - {!> ../../../docs_src/query_params_str_validations/tutorial006d.py!} - ``` - !!! tip - Remember that in most of the cases, when something is required, you can simply omit the default, so you normally don't have to use `...` nor `Required`. + Remember that in most of the cases, when something is required, you can simply omit the default, so you normally don't have to use `...`. ## Query parameter list / multiple values From cda5e770abed7efc92dbc96d4a21007ea485b4a6 Mon Sep 17 00:00:00 2001 From: github-actions <github-actions@github.com> Date: Fri, 20 Oct 2023 08:56:08 +0000 Subject: [PATCH 22/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 00e369236..6832da44e 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -7,6 +7,7 @@ hide: ## Latest Changes +* ๐Ÿ“ Update docs, remove references to removed `pydantic.Required` in `docs/en/docs/tutorial/query-params-str-validations.md`. PR [#10469](https://github.com/tiangolo/fastapi/pull/10469) by [@yogabonito](https://github.com/yogabonito). * โœ๏ธ Fix typo in `docs/en/docs/reference/index.md`. PR [#10467](https://github.com/tiangolo/fastapi/pull/10467) by [@tarsil](https://github.com/tarsil). * ๐Ÿ”ฅ Drop/close Gitter chat. Questions should go to GitHub Discussions, free conversations to Discord.. PR [#10485](https://github.com/tiangolo/fastapi/pull/10485) by [@tiangolo](https://github.com/tiangolo). * ๐Ÿ”ฅ Remove unnecessary duplicated docstrings. PR [#10484](https://github.com/tiangolo/fastapi/pull/10484) by [@tiangolo](https://github.com/tiangolo). From 4bd14306771cab5c1bff022dd2b1827cdd0ad186 Mon Sep 17 00:00:00 2001 From: yogabonito <yogabonito@users.noreply.github.com> Date: Fri, 20 Oct 2023 10:58:03 +0200 Subject: [PATCH 23/38] =?UTF-8?q?=E2=9C=8F=EF=B8=8F=20Fix=20typos=20and=20?= =?UTF-8?q?rewordings=20in=20`docs/en/docs/tutorial/body-nested-models.md`?= =?UTF-8?q?=20(#10468)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/tutorial/body-nested-models.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/en/docs/tutorial/body-nested-models.md b/docs/en/docs/tutorial/body-nested-models.md index 3a1052397..387f0de9a 100644 --- a/docs/en/docs/tutorial/body-nested-models.md +++ b/docs/en/docs/tutorial/body-nested-models.md @@ -183,18 +183,18 @@ This would mean that **FastAPI** would expect a body similar to: Again, doing just that declaration, with **FastAPI** you get: -* Editor support (completion, etc), even for nested models +* Editor support (completion, etc.), even for nested models * Data conversion * Data validation * Automatic documentation ## Special types and validation -Apart from normal singular types like `str`, `int`, `float`, etc. You can use more complex singular types that inherit from `str`. +Apart from normal singular types like `str`, `int`, `float`, etc. you can use more complex singular types that inherit from `str`. To see all the options you have, checkout the docs for <a href="https://pydantic-docs.helpmanual.io/usage/types/" class="external-link" target="_blank">Pydantic's exotic types</a>. You will see some examples in the next chapter. -For example, as in the `Image` model we have a `url` field, we can declare it to be instead of a `str`, a Pydantic's `HttpUrl`: +For example, as in the `Image` model we have a `url` field, we can declare it to be an instance of Pydantic's `HttpUrl` instead of a `str`: === "Python 3.10+" @@ -218,7 +218,7 @@ The string will be checked to be a valid URL, and documented in JSON Schema / Op ## Attributes with lists of submodels -You can also use Pydantic models as subtypes of `list`, `set`, etc: +You can also use Pydantic models as subtypes of `list`, `set`, etc.: === "Python 3.10+" @@ -238,7 +238,7 @@ You can also use Pydantic models as subtypes of `list`, `set`, etc: {!> ../../../docs_src/body_nested_models/tutorial006.py!} ``` -This will expect (convert, validate, document, etc) a JSON body like: +This will expect (convert, validate, document, etc.) a JSON body like: ```JSON hl_lines="11" { @@ -334,15 +334,15 @@ But you don't have to worry about them either, incoming dicts are converted auto ## Bodies of arbitrary `dict`s -You can also declare a body as a `dict` with keys of some type and values of other type. +You can also declare a body as a `dict` with keys of some type and values of some other type. -Without having to know beforehand what are the valid field/attribute names (as would be the case with Pydantic models). +This way, you don't have to know beforehand what the valid field/attribute names are (as would be the case with Pydantic models). This would be useful if you want to receive keys that you don't already know. --- -Other useful case is when you want to have keys of other type, e.g. `int`. +Another useful case is when you want to have keys of another type (e.g., `int`). That's what we are going to see here. From 6dac39dbcabbb8ceade5b2b96cd19b6902affbaa Mon Sep 17 00:00:00 2001 From: Surav Shrestha <98219089+suravshresth@users.noreply.github.com> Date: Fri, 20 Oct 2023 14:43:51 +0545 Subject: [PATCH 24/38] =?UTF-8?q?=E2=9C=8F=EF=B8=8F=20Fix=20typo=20in=20`d?= =?UTF-8?q?ocs/en/docs/reference/dependencies.md`=20(#10465)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/reference/dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/docs/reference/dependencies.md b/docs/en/docs/reference/dependencies.md index 95cd101e4..099968267 100644 --- a/docs/en/docs/reference/dependencies.md +++ b/docs/en/docs/reference/dependencies.md @@ -18,7 +18,7 @@ from fastapi import Depends ## `Security()` For many scenarios, you can handle security (authorization, authentication, etc.) with -dependendencies, using `Depends()`. +dependencies, using `Depends()`. But when you want to also declare OAuth2 scopes, you can use `Security()` instead of `Depends()`. From f785a6ce90bb1938779bb8e7d6124229528f9f06 Mon Sep 17 00:00:00 2001 From: github-actions <github-actions@github.com> Date: Fri, 20 Oct 2023 09:00:11 +0000 Subject: [PATCH 25/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 6832da44e..d75f9a08c 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -7,6 +7,7 @@ hide: ## Latest Changes +* โœ๏ธ Fix typos and rewordings in `docs/en/docs/tutorial/body-nested-models.md`. PR [#10468](https://github.com/tiangolo/fastapi/pull/10468) by [@yogabonito](https://github.com/yogabonito). * ๐Ÿ“ Update docs, remove references to removed `pydantic.Required` in `docs/en/docs/tutorial/query-params-str-validations.md`. PR [#10469](https://github.com/tiangolo/fastapi/pull/10469) by [@yogabonito](https://github.com/yogabonito). * โœ๏ธ Fix typo in `docs/en/docs/reference/index.md`. PR [#10467](https://github.com/tiangolo/fastapi/pull/10467) by [@tarsil](https://github.com/tarsil). * ๐Ÿ”ฅ Drop/close Gitter chat. Questions should go to GitHub Discussions, free conversations to Discord.. PR [#10485](https://github.com/tiangolo/fastapi/pull/10485) by [@tiangolo](https://github.com/tiangolo). From ae84ff6e44d45fe75e96fb12ae225046d99c29e8 Mon Sep 17 00:00:00 2001 From: Heinz-Alexander Fuetterer <35225576+afuetterer@users.noreply.github.com> Date: Fri, 20 Oct 2023 11:00:44 +0200 Subject: [PATCH 26/38] =?UTF-8?q?=E2=9C=8F=EF=B8=8F=20Fix=20typos=20in=20e?= =?UTF-8?q?moji=20docs=20and=20in=20some=20source=20examples=20(#10438)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/em/docs/deployment/concepts.md | 14 +++++----- docs/em/docs/deployment/docker.md | 26 +++++++++---------- docs/em/docs/deployment/server-workers.md | 8 +++--- docs/em/docs/project-generation.md | 2 +- docs/en/docs/how-to/sql-databases-peewee.md | 2 +- docs_src/openapi_webhooks/tutorial001.py | 2 +- fastapi/utils.py | 2 +- .../test_openapi_webhooks/test_tutorial001.py | 4 +-- tests/test_webhooks_security.py | 6 ++--- 9 files changed, 33 insertions(+), 33 deletions(-) diff --git a/docs/em/docs/deployment/concepts.md b/docs/em/docs/deployment/concepts.md index 8ce775411..162b68615 100644 --- a/docs/em/docs/deployment/concepts.md +++ b/docs/em/docs/deployment/concepts.md @@ -43,7 +43,7 @@ * โฎ๏ธ ๐Ÿ”ข ๐Ÿฆฒ ๐Ÿ’– Certbot ๐Ÿ“„ ๐Ÿ”• * โœณ * โฎ๏ธ ๐Ÿ”ข ๐Ÿฆฒ ๐Ÿ’– Certbot ๐Ÿ“„ ๐Ÿ”• -* Kubernete โฎ๏ธ ๐Ÿšง ๐Ÿ•น ๐Ÿ’– ๐Ÿ‘Œ +* Kubernetes โฎ๏ธ ๐Ÿšง ๐Ÿ•น ๐Ÿ’– ๐Ÿ‘Œ * โฎ๏ธ ๐Ÿ”ข ๐Ÿฆฒ ๐Ÿ’– ๐Ÿ›‚-๐Ÿ‘จโ€๐Ÿ’ผ ๐Ÿ“„ ๐Ÿ”• * ๐Ÿต ๐Ÿ”˜ โ˜ ๐Ÿ•โ€๐Ÿฆบ ๐Ÿ• ๐Ÿ‘ซ ๐Ÿ•โ€๐Ÿฆบ (โœ ๐Ÿ”› ๐Ÿ‘ถ) @@ -115,7 +115,7 @@ ๐Ÿ–ผ ๐Ÿงฐ ๐Ÿ‘ˆ ๐Ÿ’ช ๐Ÿ‘‰ ๐Ÿ‘จโ€๐Ÿญ: * โ˜ -* Kubernete +* Kubernetes * โ˜ โœ * โ˜ ๐Ÿ ๐Ÿ“ณ * โœณ @@ -165,7 +165,7 @@ ๐Ÿ–ผ, ๐Ÿ‘‰ ๐Ÿ’ช ๐Ÿต: * โ˜ -* Kubernete +* Kubernetes * โ˜ โœ * โ˜ ๐Ÿ ๐Ÿ“ณ * โœณ @@ -233,15 +233,15 @@ * ๐Ÿ ๐Ÿ”œ **๐Ÿ› ๏ธ ๐Ÿ‘จโ€๐Ÿ’ผ** ๐Ÿ‘‚ ๐Ÿ”› **๐Ÿ“ข** & **โ›ด**, ๐Ÿงฌ ๐Ÿ”œ โœ”๏ธ **๐Ÿ’— Uvicorn ๐Ÿ‘จโ€๐Ÿญ ๐Ÿ› ๏ธ** * **Uvicorn** ๐Ÿ› ๏ธ **Uvicorn ๐Ÿ‘จโ€๐Ÿญ** * 1๏ธโƒฃ Uvicorn **๐Ÿ› ๏ธ ๐Ÿ‘จโ€๐Ÿ’ผ** ๐Ÿ”œ ๐Ÿ‘‚ ๐Ÿ”› **๐Ÿ“ข** & **โ›ด**, & โšซ๏ธ ๐Ÿ”œ โ–ถ๏ธ **๐Ÿ’— Uvicorn ๐Ÿ‘จโ€๐Ÿญ ๐Ÿ› ๏ธ** -* **Kubernete** & ๐ŸŽ ๐Ÿ“Ž **๐Ÿ“ฆ โš™๏ธ** +* **Kubernetes** & ๐ŸŽ ๐Ÿ“Ž **๐Ÿ“ฆ โš™๏ธ** * ๐Ÿ•ณ **โ˜** ๐Ÿงฝ ๐Ÿ”œ ๐Ÿ‘‚ ๐Ÿ”› **๐Ÿ“ข** & **โ›ด**. ๐Ÿงฌ ๐Ÿ”œ โœ”๏ธ **๐Ÿ’— ๐Ÿ“ฆ**, ๐Ÿ”  โฎ๏ธ **1๏ธโƒฃ Uvicorn ๐Ÿ› ๏ธ** ๐Ÿƒโ€โ™‚ * **โ˜ ๐Ÿ•โ€๐Ÿฆบ** ๐Ÿ‘ˆ ๐Ÿต ๐Ÿ‘‰ ๐Ÿ‘† * โ˜ ๐Ÿ•โ€๐Ÿฆบ ๐Ÿ”œ ๐ŸŽฒ **๐Ÿต ๐Ÿงฌ ๐Ÿ‘†**. โšซ๏ธ ๐Ÿ”œ ๐ŸŽฒ โžก๏ธ ๐Ÿ‘† ๐Ÿ”ฌ **๐Ÿ› ๏ธ ๐Ÿƒ**, โš–๏ธ **๐Ÿ“ฆ ๐Ÿ–ผ** โš™๏ธ, ๐Ÿ™† ๐Ÿ’ผ, โšซ๏ธ ๐Ÿ”œ ๐ŸŒ… ๐ŸŽฒ **๐Ÿ‘ Uvicorn ๐Ÿ› ๏ธ**, & โ˜ ๐Ÿ•โ€๐Ÿฆบ ๐Ÿ”œ ๐Ÿˆš ๐Ÿ” โšซ๏ธ. !!! tip - ๐Ÿšซ ๐Ÿ˜Ÿ ๐Ÿšฅ ๐Ÿ‘ซ ๐Ÿฌ ๐Ÿ”ƒ **๐Ÿ“ฆ**, โ˜, โš–๏ธ Kubernete ๐Ÿšซ โš’ ๐Ÿ“š ๐Ÿ”‘. + ๐Ÿšซ ๐Ÿ˜Ÿ ๐Ÿšฅ ๐Ÿ‘ซ ๐Ÿฌ ๐Ÿ”ƒ **๐Ÿ“ฆ**, โ˜, โš–๏ธ Kubernetes ๐Ÿšซ โš’ ๐Ÿ“š ๐Ÿ”‘. - ๐Ÿ‘ค ๐Ÿ”œ ๐Ÿ’ฌ ๐Ÿ‘† ๐ŸŒ… ๐Ÿ”ƒ ๐Ÿ“ฆ ๐Ÿ–ผ, โ˜, Kubernete, โ™’๏ธ. ๐Ÿ”ฎ ๐Ÿ“ƒ: [FastAPI ๐Ÿ“ฆ - โ˜](./docker.md){.internal-link target=_blank}. + ๐Ÿ‘ค ๐Ÿ”œ ๐Ÿ’ฌ ๐Ÿ‘† ๐ŸŒ… ๐Ÿ”ƒ ๐Ÿ“ฆ ๐Ÿ–ผ, โ˜, Kubernetes, โ™’๏ธ. ๐Ÿ”ฎ ๐Ÿ“ƒ: [FastAPI ๐Ÿ“ฆ - โ˜](./docker.md){.internal-link target=_blank}. ## โฎ๏ธ ๐Ÿ” โญ โ–ถ๏ธ @@ -268,7 +268,7 @@ ๐Ÿ“ฅ ๐Ÿ’ช ๐Ÿ’ญ: -* "๐Ÿ•‘ ๐Ÿ“ฆ" Kubernete ๐Ÿ‘ˆ ๐Ÿƒ โญ ๐Ÿ‘† ๐Ÿ“ฑ ๐Ÿ“ฆ +* "๐Ÿ•‘ ๐Ÿ“ฆ" Kubernetes ๐Ÿ‘ˆ ๐Ÿƒ โญ ๐Ÿ‘† ๐Ÿ“ฑ ๐Ÿ“ฆ * ๐ŸŽ‰ โœ ๐Ÿ‘ˆ ๐Ÿƒ โฎ๏ธ ๐Ÿ” & โคด๏ธ โ–ถ๏ธ ๐Ÿ‘† ๐Ÿˆธ * ๐Ÿ‘† ๐Ÿ”œ ๐Ÿ’ช ๐ŸŒŒ โ–ถ๏ธ/โ *๐Ÿ‘ˆ* ๐ŸŽ‰ โœ, ๐Ÿ” โŒ, โ™’๏ธ. diff --git a/docs/em/docs/deployment/docker.md b/docs/em/docs/deployment/docker.md index 51ece5599..f28735ed7 100644 --- a/docs/em/docs/deployment/docker.md +++ b/docs/em/docs/deployment/docker.md @@ -74,7 +74,7 @@ CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"] , ๐Ÿ‘† ๐Ÿ”œ ๐Ÿƒ **๐Ÿ’— ๐Ÿ“ฆ** โฎ๏ธ ๐ŸŽ ๐Ÿ‘œ, ๐Ÿ’– ๐Ÿ’ฝ, ๐Ÿ ๐Ÿˆธ, ๐Ÿ•ธ ๐Ÿ’ฝ โฎ๏ธ ๐Ÿ˜ฅ ๐Ÿ•ธ ๐Ÿˆธ, & ๐Ÿ”— ๐Ÿ‘ซ ๐Ÿ‘ฏโ€โ™‚๏ธ ๐Ÿ“จ ๐Ÿ‘ซ ๐Ÿ”— ๐Ÿ•ธ. -๐ŸŒ ๐Ÿ“ฆ ๐Ÿงพ โš™๏ธ (๐Ÿ’– โ˜ โš–๏ธ Kubernete) โœ”๏ธ ๐Ÿ‘ซ ๐Ÿ•ธ โš’ ๐Ÿ› ๏ธ ๐Ÿ”˜ ๐Ÿ‘ซ. +๐ŸŒ ๐Ÿ“ฆ ๐Ÿงพ โš™๏ธ (๐Ÿ’– โ˜ โš–๏ธ Kubernetes) โœ”๏ธ ๐Ÿ‘ซ ๐Ÿ•ธ โš’ ๐Ÿ› ๏ธ ๐Ÿ”˜ ๐Ÿ‘ซ. ## ๐Ÿ“ฆ & ๐Ÿ› ๏ธ @@ -96,7 +96,7 @@ CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"] ๐Ÿ‘‰ โšซ๏ธโ” ๐Ÿ‘† ๐Ÿ”œ ๐Ÿ’š **๐Ÿ† ๐Ÿ’ผ**, ๐Ÿ–ผ: -* โš™๏ธ **Kubernete** โš–๏ธ ๐ŸŽ ๐Ÿงฐ +* โš™๏ธ **Kubernetes** โš–๏ธ ๐ŸŽ ๐Ÿงฐ * ๐Ÿ•โ” ๐Ÿƒโ€โ™‚ ๐Ÿ”› **๐Ÿ“ ๐Ÿ‘ฒ** * โš™๏ธ โ˜ ๐Ÿ•โ€๐Ÿฆบ ๐Ÿ‘ˆ ๐Ÿ”œ ๐Ÿƒ ๐Ÿ“ฆ ๐Ÿ–ผ ๐Ÿ‘†, โ™’๏ธ. @@ -395,7 +395,7 @@ CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"] โšซ๏ธ ๐Ÿ’ช โž•1๏ธโƒฃ ๐Ÿ“ฆ, ๐Ÿ–ผ โฎ๏ธ <a href="https://traefik.io/" class="external-link" target="_blank">Traefik</a>, ๐Ÿšš **๐Ÿ‡บ๐Ÿ‡ธ๐Ÿ”** & **๐Ÿง** ๐Ÿ› ๏ธ **๐Ÿ“„**. !!! tip - Traefik โœ”๏ธ ๐Ÿ› ๏ธ โฎ๏ธ โ˜, Kubernete, & ๐ŸŽ, โšซ๏ธ ๐Ÿ“ถ โฉ โš’ ๐Ÿ†™ & ๐Ÿ”— ๐Ÿ‡บ๐Ÿ‡ธ๐Ÿ” ๐Ÿ‘† ๐Ÿ“ฆ โฎ๏ธ โšซ๏ธ. + Traefik โœ”๏ธ ๐Ÿ› ๏ธ โฎ๏ธ โ˜, Kubernetes, & ๐ŸŽ, โšซ๏ธ ๐Ÿ“ถ โฉ โš’ ๐Ÿ†™ & ๐Ÿ”— ๐Ÿ‡บ๐Ÿ‡ธ๐Ÿ” ๐Ÿ‘† ๐Ÿ“ฆ โฎ๏ธ โšซ๏ธ. ๐Ÿ‘, ๐Ÿ‡บ๐Ÿ‡ธ๐Ÿ” ๐Ÿ’ช ๐Ÿต โ˜ ๐Ÿ•โ€๐Ÿฆบ 1๏ธโƒฃ ๐Ÿ‘ซ ๐Ÿ•โ€๐Ÿฆบ (โช ๐Ÿƒ ๐Ÿˆธ ๐Ÿ“ฆ). @@ -403,7 +403,7 @@ CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"] ๐Ÿ“ค ๐Ÿ›Ž โž•1๏ธโƒฃ ๐Ÿงฐ ๐Ÿˆš **โ–ถ๏ธ & ๐Ÿƒโ€โ™‚** ๐Ÿ‘† ๐Ÿ“ฆ. -โšซ๏ธ ๐Ÿ’ช **โ˜** ๐Ÿ”—, **โ˜ โœ**, **Kubernete**, **โ˜ ๐Ÿ•โ€๐Ÿฆบ**, โ™’๏ธ. +โšซ๏ธ ๐Ÿ’ช **โ˜** ๐Ÿ”—, **โ˜ โœ**, **Kubernetes**, **โ˜ ๐Ÿ•โ€๐Ÿฆบ**, โ™’๏ธ. ๐ŸŒ… (โš–๏ธ ๐ŸŒ) ๐Ÿ’ผ, ๐Ÿ“ค ๐Ÿ™… ๐ŸŽ› ๐Ÿ› ๏ธ ๐Ÿƒ ๐Ÿ“ฆ ๐Ÿ”› ๐Ÿ•ด & ๐Ÿ› ๏ธ โ ๐Ÿ”› โŒ. ๐Ÿ–ผ, โ˜, โšซ๏ธ ๐Ÿ“‹ โธ ๐ŸŽ› `--restart`. @@ -413,7 +413,7 @@ CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"] ๐Ÿšฅ ๐Ÿ‘† โœ”๏ธ <abbr title="A group of machines that are configured to be connected and work together in some way.">๐ŸŒ‘</abbr> ๐ŸŽฐ โฎ๏ธ **โ˜**, โ˜ ๐Ÿ ๐Ÿ“ณ, ๐Ÿ––, โš–๏ธ โž•1๏ธโƒฃ ๐ŸŽ ๐Ÿ— โš™๏ธ ๐Ÿ› ๏ธ ๐Ÿ“Ž ๐Ÿ“ฆ ๐Ÿ”› ๐Ÿ’— ๐ŸŽฐ, โคด๏ธ ๐Ÿ‘† ๐Ÿ”œ ๐ŸŽฒ ๐Ÿ’š **๐Ÿต ๐Ÿงฌ** **๐ŸŒ‘ ๐ŸŽš** โ†ฉ๏ธ โš™๏ธ **๐Ÿ› ๏ธ ๐Ÿ‘จโ€๐Ÿ’ผ** (๐Ÿ’– ๐Ÿ โฎ๏ธ ๐Ÿ‘จโ€๐Ÿญ) ๐Ÿ”  ๐Ÿ“ฆ. -1๏ธโƒฃ ๐Ÿ“š ๐Ÿ“Ž ๐Ÿ“ฆ ๐Ÿงพ โš™๏ธ ๐Ÿ’– Kubernete ๐Ÿ›Ž โœ”๏ธ ๐Ÿ› ๏ธ ๐ŸŒŒ ๐Ÿšš **๐Ÿงฌ ๐Ÿ“ฆ** โช ๐Ÿ”— **๐Ÿ“ โš–** ๐Ÿ“จ ๐Ÿ“จ. ๐ŸŒ **๐ŸŒ‘ ๐ŸŽš**. +1๏ธโƒฃ ๐Ÿ“š ๐Ÿ“Ž ๐Ÿ“ฆ ๐Ÿงพ โš™๏ธ ๐Ÿ’– Kubernetes ๐Ÿ›Ž โœ”๏ธ ๐Ÿ› ๏ธ ๐ŸŒŒ ๐Ÿšš **๐Ÿงฌ ๐Ÿ“ฆ** โช ๐Ÿ”— **๐Ÿ“ โš–** ๐Ÿ“จ ๐Ÿ“จ. ๐ŸŒ **๐ŸŒ‘ ๐ŸŽš**. ๐Ÿ“š ๐Ÿ’ผ, ๐Ÿ‘† ๐Ÿ”œ ๐ŸŽฒ ๐Ÿ’š ๐Ÿ— **โ˜ ๐Ÿ–ผ โšช๏ธโžก๏ธ ๐Ÿ–Œ** [๐Ÿ”ฌ ๐Ÿ”›](#dockerfile), โŽ ๐Ÿ‘† ๐Ÿ”—, & ๐Ÿƒโ€โ™‚ **๐Ÿ‘ Uvicorn ๐Ÿ› ๏ธ** โ†ฉ๏ธ ๐Ÿƒโ€โ™‚ ๐Ÿ•ณ ๐Ÿ’– ๐Ÿ โฎ๏ธ Uvicorn ๐Ÿ‘จโ€๐Ÿญ. @@ -430,7 +430,7 @@ CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"] ### 1๏ธโƒฃ ๐Ÿ“ โš™ - ๐Ÿ’— ๐Ÿ‘จโ€๐Ÿญ ๐Ÿ“ฆ -๐Ÿ•โ” ๐Ÿ‘ท โฎ๏ธ **Kubernete** โš–๏ธ ๐ŸŽ ๐Ÿ“Ž ๐Ÿ“ฆ ๐Ÿงพ โš™๏ธ, โš™๏ธ ๐Ÿ‘ซ ๐Ÿ”— ๐Ÿ•ธ ๐Ÿ› ๏ธ ๐Ÿ”œ โœ” ๐Ÿ‘ **๐Ÿ“ โš™** ๐Ÿ‘ˆ ๐Ÿ‘‚ ๐Ÿ”› ๐Ÿ‘‘ **โ›ด** ๐Ÿ“ถ ๐Ÿ“ป (๐Ÿ“จ) ๐ŸŽฒ **๐Ÿ’— ๐Ÿ“ฆ** ๐Ÿƒ ๐Ÿ‘† ๐Ÿ“ฑ. +๐Ÿ•โ” ๐Ÿ‘ท โฎ๏ธ **Kubernetes** โš–๏ธ ๐ŸŽ ๐Ÿ“Ž ๐Ÿ“ฆ ๐Ÿงพ โš™๏ธ, โš™๏ธ ๐Ÿ‘ซ ๐Ÿ”— ๐Ÿ•ธ ๐Ÿ› ๏ธ ๐Ÿ”œ โœ” ๐Ÿ‘ **๐Ÿ“ โš™** ๐Ÿ‘ˆ ๐Ÿ‘‚ ๐Ÿ”› ๐Ÿ‘‘ **โ›ด** ๐Ÿ“ถ ๐Ÿ“ป (๐Ÿ“จ) ๐ŸŽฒ **๐Ÿ’— ๐Ÿ“ฆ** ๐Ÿƒ ๐Ÿ‘† ๐Ÿ“ฑ. ๐Ÿ”  ๐Ÿ‘ซ ๐Ÿ“ฆ ๐Ÿƒโ€โ™‚ ๐Ÿ‘† ๐Ÿ“ฑ ๐Ÿ”œ ๐Ÿ›Ž โœ”๏ธ **1๏ธโƒฃ ๐Ÿ› ๏ธ** (โœ… Uvicorn ๐Ÿ› ๏ธ ๐Ÿƒ ๐Ÿ‘† FastAPI ๐Ÿˆธ). ๐Ÿ‘ซ ๐Ÿ”œ ๐ŸŒ **๐ŸŒ“ ๐Ÿ“ฆ**, ๐Ÿƒโ€โ™‚ ๐ŸŽ ๐Ÿ‘œ, โœ‹๏ธ ๐Ÿ”  โฎ๏ธ ๐Ÿšฎ ๐Ÿ‘ ๐Ÿ› ๏ธ, ๐Ÿ’พ, โ™’๏ธ. ๐Ÿ‘ˆ ๐ŸŒŒ ๐Ÿ‘† ๐Ÿ”œ โœŠ ๐Ÿ“ˆ **๐Ÿ› ๏ธ** **๐ŸŽ ๐Ÿš** ๐Ÿ’ฝ, โš–๏ธ **๐ŸŽ ๐ŸŽฐ**. @@ -489,7 +489,7 @@ CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"] ๐Ÿšฅ ๐Ÿ‘† ๐Ÿƒ **๐Ÿ‘ ๐Ÿ› ๏ธ ๐Ÿ“ ๐Ÿ“ฆ** ๐Ÿ‘† ๐Ÿ”œ โœ”๏ธ ๐ŸŒ… โš–๏ธ ๐ŸŒ˜ ๐Ÿ‘-๐Ÿ”ฌ, โš–, & ๐Ÿ“‰ ๐Ÿ’ธ ๐Ÿ’พ ๐Ÿด ๐Ÿ”  ๐Ÿ‘ˆ ๐Ÿ“ฆ (๐ŸŒ… ๐ŸŒ˜ 1๏ธโƒฃ ๐Ÿšฅ ๐Ÿ‘ซ ๐Ÿ”). -& โคด๏ธ ๐Ÿ‘† ๐Ÿ’ช โš’ ๐Ÿ‘ˆ ๐ŸŽ ๐Ÿ’พ ๐Ÿ“‰ & ๐Ÿ“„ ๐Ÿ‘† ๐Ÿ“ณ ๐Ÿ‘† ๐Ÿ“ฆ ๐Ÿงพ โš™๏ธ (๐Ÿ–ผ **Kubernete**). ๐Ÿ‘ˆ ๐ŸŒŒ โšซ๏ธ ๐Ÿ”œ ๐Ÿ’ช **๐Ÿ” ๐Ÿ“ฆ** **๐Ÿ’ช ๐ŸŽฐ** โœŠ ๐Ÿ”˜ ๐Ÿง ๐Ÿ’ธ ๐Ÿ’พ ๐Ÿ’ช ๐Ÿ‘ซ, & ๐Ÿ’ธ ๐Ÿ’ช ๐ŸŽฐ ๐ŸŒ‘. +& โคด๏ธ ๐Ÿ‘† ๐Ÿ’ช โš’ ๐Ÿ‘ˆ ๐ŸŽ ๐Ÿ’พ ๐Ÿ“‰ & ๐Ÿ“„ ๐Ÿ‘† ๐Ÿ“ณ ๐Ÿ‘† ๐Ÿ“ฆ ๐Ÿงพ โš™๏ธ (๐Ÿ–ผ **Kubernetes**). ๐Ÿ‘ˆ ๐ŸŒŒ โšซ๏ธ ๐Ÿ”œ ๐Ÿ’ช **๐Ÿ” ๐Ÿ“ฆ** **๐Ÿ’ช ๐ŸŽฐ** โœŠ ๐Ÿ”˜ ๐Ÿง ๐Ÿ’ธ ๐Ÿ’พ ๐Ÿ’ช ๐Ÿ‘ซ, & ๐Ÿ’ธ ๐Ÿ’ช ๐ŸŽฐ ๐ŸŒ‘. ๐Ÿšฅ ๐Ÿ‘† ๐Ÿˆธ **๐Ÿ™…**, ๐Ÿ‘‰ ๐Ÿ”œ ๐ŸŽฒ **๐Ÿšซ โš **, & ๐Ÿ‘† ๐Ÿ’ช ๐Ÿšซ ๐Ÿ’ช โœ” ๐Ÿ‹๏ธ ๐Ÿ’พ ๐Ÿ“‰. โœ‹๏ธ ๐Ÿšฅ ๐Ÿ‘† **โš™๏ธ ๐Ÿ“š ๐Ÿ’พ** (๐Ÿ–ผ โฎ๏ธ **๐ŸŽฐ ๐Ÿซ** ๐Ÿท), ๐Ÿ‘† ๐Ÿ”œ โœ… โ” ๐ŸŒ… ๐Ÿ’พ ๐Ÿ‘† ๐Ÿ˜ฉ & ๐Ÿ”† **๐Ÿ”ข ๐Ÿ“ฆ** ๐Ÿ‘ˆ ๐Ÿƒ **๐Ÿ”  ๐ŸŽฐ** (& ๐ŸŽฒ ๐Ÿšฎ ๐ŸŒ– ๐ŸŽฐ ๐Ÿ‘† ๐ŸŒ‘). @@ -497,14 +497,14 @@ CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"] ## โฎ๏ธ ๐Ÿ” โญ โ–ถ๏ธ & ๐Ÿ“ฆ -๐Ÿšฅ ๐Ÿ‘† โš™๏ธ ๐Ÿ“ฆ (โœ… โ˜, Kubernete), โคด๏ธ ๐Ÿ“ค 2๏ธโƒฃ ๐Ÿ‘‘ ๐ŸŽฏ ๐Ÿ‘† ๐Ÿ’ช โš™๏ธ. +๐Ÿšฅ ๐Ÿ‘† โš™๏ธ ๐Ÿ“ฆ (โœ… โ˜, Kubernetes), โคด๏ธ ๐Ÿ“ค 2๏ธโƒฃ ๐Ÿ‘‘ ๐ŸŽฏ ๐Ÿ‘† ๐Ÿ’ช โš™๏ธ. ### ๐Ÿ’— ๐Ÿ“ฆ -๐Ÿšฅ ๐Ÿ‘† โœ”๏ธ **๐Ÿ’— ๐Ÿ“ฆ**, ๐ŸŽฒ ๐Ÿ”  1๏ธโƒฃ ๐Ÿƒ **๐Ÿ‘ ๐Ÿ› ๏ธ** (๐Ÿ–ผ, **Kubernete** ๐ŸŒ‘), โคด๏ธ ๐Ÿ‘† ๐Ÿ”œ ๐ŸŽฒ ๐Ÿ’š โœ”๏ธ **๐ŸŽ ๐Ÿ“ฆ** ๐Ÿ”จ ๐Ÿ‘ท **โฎ๏ธ ๐Ÿ“ถ** ๐Ÿ‘ ๐Ÿ“ฆ, ๐Ÿƒ ๐Ÿ‘ ๐Ÿ› ๏ธ, **โญ** ๐Ÿƒ ๐Ÿ” ๐Ÿ‘จโ€๐Ÿญ ๐Ÿ“ฆ. +๐Ÿšฅ ๐Ÿ‘† โœ”๏ธ **๐Ÿ’— ๐Ÿ“ฆ**, ๐ŸŽฒ ๐Ÿ”  1๏ธโƒฃ ๐Ÿƒ **๐Ÿ‘ ๐Ÿ› ๏ธ** (๐Ÿ–ผ, **Kubernetes** ๐ŸŒ‘), โคด๏ธ ๐Ÿ‘† ๐Ÿ”œ ๐ŸŽฒ ๐Ÿ’š โœ”๏ธ **๐ŸŽ ๐Ÿ“ฆ** ๐Ÿ”จ ๐Ÿ‘ท **โฎ๏ธ ๐Ÿ“ถ** ๐Ÿ‘ ๐Ÿ“ฆ, ๐Ÿƒ ๐Ÿ‘ ๐Ÿ› ๏ธ, **โญ** ๐Ÿƒ ๐Ÿ” ๐Ÿ‘จโ€๐Ÿญ ๐Ÿ“ฆ. !!! info - ๐Ÿšฅ ๐Ÿ‘† โš™๏ธ Kubernete, ๐Ÿ‘‰ ๐Ÿ”œ ๐ŸŽฒ <a href="https://kubernetes.io/docs/concepts/workloads/pods/init-containers/" class="external-link" target="_blank">๐Ÿ•‘ ๐Ÿ“ฆ</a>. + ๐Ÿšฅ ๐Ÿ‘† โš™๏ธ Kubernetes, ๐Ÿ‘‰ ๐Ÿ”œ ๐ŸŽฒ <a href="https://kubernetes.io/docs/concepts/workloads/pods/init-containers/" class="external-link" target="_blank">๐Ÿ•‘ ๐Ÿ“ฆ</a>. ๐Ÿšฅ ๐Ÿ‘† โš™๏ธ ๐Ÿ’ผ ๐Ÿ“ค ๐Ÿ™…โ€โ™‚ โš  ๐Ÿƒโ€โ™‚ ๐Ÿ‘ˆ โฎ๏ธ ๐Ÿ“ถ **๐Ÿ’— ๐Ÿ•ฐ ๐Ÿ”—** (๐Ÿ–ผ ๐Ÿšฅ ๐Ÿ‘† ๐Ÿšซ ๐Ÿƒ ๐Ÿ’ฝ ๐Ÿ› ๏ธ, โœ‹๏ธ โœ… ๐Ÿšฅ ๐Ÿ’ฝ ๐Ÿ”œ), โคด๏ธ ๐Ÿ‘† ๐Ÿ’ช ๐Ÿšฎ ๐Ÿ‘ซ ๐Ÿ”  ๐Ÿ“ฆ โ–ถ๏ธ๏ธ โญ โ–ถ๏ธ ๐Ÿ‘‘ ๐Ÿ› ๏ธ. @@ -574,7 +574,7 @@ COPY ./app /app/app ### ๐Ÿ•โ” โš™๏ธ -๐Ÿ‘† ๐Ÿ”œ ๐ŸŽฒ **๐Ÿšซ** โš™๏ธ ๐Ÿ‘‰ ๐Ÿ›‚ ๐Ÿงข ๐Ÿ–ผ (โš–๏ธ ๐Ÿ™† ๐ŸŽ ๐ŸŽ 1๏ธโƒฃ) ๐Ÿšฅ ๐Ÿ‘† โš™๏ธ **Kubernete** (โš–๏ธ ๐ŸŽ) & ๐Ÿ‘† โช โš’ **๐Ÿงฌ** ๐ŸŒ‘ ๐ŸŽš, โฎ๏ธ ๐Ÿ’— **๐Ÿ“ฆ**. ๐Ÿ“š ๐Ÿ’ผ, ๐Ÿ‘† ๐Ÿ‘ ๐Ÿ“† **๐Ÿ— ๐Ÿ–ผ โšช๏ธโžก๏ธ ๐Ÿ–Œ** ๐Ÿ”ฌ ๐Ÿ”›: [๐Ÿ— โ˜ ๐Ÿ–ผ FastAPI](#build-a-docker-image-for-fastapi). +๐Ÿ‘† ๐Ÿ”œ ๐ŸŽฒ **๐Ÿšซ** โš™๏ธ ๐Ÿ‘‰ ๐Ÿ›‚ ๐Ÿงข ๐Ÿ–ผ (โš–๏ธ ๐Ÿ™† ๐ŸŽ ๐ŸŽ 1๏ธโƒฃ) ๐Ÿšฅ ๐Ÿ‘† โš™๏ธ **Kubernetes** (โš–๏ธ ๐ŸŽ) & ๐Ÿ‘† โช โš’ **๐Ÿงฌ** ๐ŸŒ‘ ๐ŸŽš, โฎ๏ธ ๐Ÿ’— **๐Ÿ“ฆ**. ๐Ÿ“š ๐Ÿ’ผ, ๐Ÿ‘† ๐Ÿ‘ ๐Ÿ“† **๐Ÿ— ๐Ÿ–ผ โšช๏ธโžก๏ธ ๐Ÿ–Œ** ๐Ÿ”ฌ ๐Ÿ”›: [๐Ÿ— โ˜ ๐Ÿ–ผ FastAPI](#build-a-docker-image-for-fastapi). ๐Ÿ‘‰ ๐Ÿ–ผ ๐Ÿ”œ โš  โœด๏ธ ๐ŸŽ ๐Ÿ’ผ ๐Ÿ”ฌ ๐Ÿ”› [๐Ÿ“ฆ โฎ๏ธ ๐Ÿ’— ๐Ÿ› ๏ธ & ๐ŸŽ ๐Ÿ’ผ](#containers-with-multiple-processes-and-special-cases). ๐Ÿ–ผ, ๐Ÿšฅ ๐Ÿ‘† ๐Ÿˆธ **๐Ÿ™… ๐Ÿฅƒ** ๐Ÿ‘ˆ โš’ ๐Ÿ”ข ๐Ÿ”ข ๐Ÿ› ๏ธ โš“๏ธ ๐Ÿ”› ๐Ÿ’ฝ ๐Ÿ‘ท ๐Ÿ‘, ๐Ÿ‘† ๐Ÿšซ ๐Ÿ’š ๐Ÿ˜ฅ โฎ๏ธ โŽ ๐Ÿ› ๏ธ ๐Ÿงฌ ๐ŸŒ‘ ๐ŸŽš, & ๐Ÿ‘† ๐Ÿšซ ๐Ÿƒ ๐ŸŒ… ๐ŸŒ˜ 1๏ธโƒฃ ๐Ÿ“ฆ โฎ๏ธ ๐Ÿ‘† ๐Ÿ“ฑ. โš–๏ธ ๐Ÿšฅ ๐Ÿ‘† ๐Ÿ› ๏ธ โฎ๏ธ **โ˜ โœ**, ๐Ÿƒ ๐Ÿ”› ๐Ÿ‘ ๐Ÿ’ฝ, โ™’๏ธ. @@ -585,7 +585,7 @@ COPY ./app /app/app ๐Ÿ–ผ: * โฎ๏ธ **โ˜ โœ** ๐Ÿ‘ ๐Ÿ’ฝ -* โฎ๏ธ **Kubernete** ๐ŸŒ‘ +* โฎ๏ธ **Kubernetes** ๐ŸŒ‘ * โฎ๏ธ โ˜ ๐Ÿ ๐Ÿ“ณ ๐ŸŒ‘ * โฎ๏ธ โž•1๏ธโƒฃ ๐Ÿงฐ ๐Ÿ’– ๐Ÿ–– * โฎ๏ธ โ˜ ๐Ÿ•โ€๐Ÿฆบ ๐Ÿ‘ˆ โœŠ ๐Ÿ‘† ๐Ÿ“ฆ ๐Ÿ–ผ & ๐Ÿ› ๏ธ โšซ๏ธ @@ -682,7 +682,7 @@ CMD ["uvicorn", "app.main:app", "--proxy-headers", "--host", "0.0.0.0", "--port" ## ๐ŸŒƒ -โš™๏ธ ๐Ÿ“ฆ โš™๏ธ (โœ… โฎ๏ธ **โ˜** & **Kubernete**) โšซ๏ธ โ–ถ๏ธ๏ธ ๐Ÿ“ถ ๐ŸŽฏ ๐Ÿต ๐ŸŒ **๐Ÿ› ๏ธ ๐Ÿ”ง**: +โš™๏ธ ๐Ÿ“ฆ โš™๏ธ (โœ… โฎ๏ธ **โ˜** & **Kubernetes**) โšซ๏ธ โ–ถ๏ธ๏ธ ๐Ÿ“ถ ๐ŸŽฏ ๐Ÿต ๐ŸŒ **๐Ÿ› ๏ธ ๐Ÿ”ง**: * ๐Ÿ‡บ๐Ÿ‡ธ๐Ÿ” * ๐Ÿƒโ€โ™‚ ๐Ÿ”› ๐Ÿ•ด diff --git a/docs/em/docs/deployment/server-workers.md b/docs/em/docs/deployment/server-workers.md index ca068d744..b7e58c4f4 100644 --- a/docs/em/docs/deployment/server-workers.md +++ b/docs/em/docs/deployment/server-workers.md @@ -18,9 +18,9 @@ ๐Ÿ“ฅ ๐Ÿ‘ค ๐Ÿ”œ ๐ŸŽฆ ๐Ÿ‘† โ” โš™๏ธ <a href="https://gunicorn.org/" class="external-link" target="_blank">**๐Ÿ**</a> โฎ๏ธ **Uvicorn ๐Ÿ‘จโ€๐Ÿญ ๐Ÿ› ๏ธ**. !!! info - ๐Ÿšฅ ๐Ÿ‘† โš™๏ธ ๐Ÿ“ฆ, ๐Ÿ–ผ โฎ๏ธ โ˜ โš–๏ธ Kubernete, ๐Ÿ‘ค ๐Ÿ”œ ๐Ÿ’ฌ ๐Ÿ‘† ๐ŸŒ… ๐Ÿ”ƒ ๐Ÿ‘ˆ โญ ๐Ÿ“ƒ: [FastAPI ๐Ÿ“ฆ - โ˜](./docker.md){.internal-link target=_blank}. + ๐Ÿšฅ ๐Ÿ‘† โš™๏ธ ๐Ÿ“ฆ, ๐Ÿ–ผ โฎ๏ธ โ˜ โš–๏ธ Kubernetes, ๐Ÿ‘ค ๐Ÿ”œ ๐Ÿ’ฌ ๐Ÿ‘† ๐ŸŒ… ๐Ÿ”ƒ ๐Ÿ‘ˆ โญ ๐Ÿ“ƒ: [FastAPI ๐Ÿ“ฆ - โ˜](./docker.md){.internal-link target=_blank}. - ๐ŸŽฏ, ๐Ÿ•โ” ๐Ÿƒ ๐Ÿ”› **Kubernete** ๐Ÿ‘† ๐Ÿ”œ ๐ŸŽฒ **๐Ÿšซ** ๐Ÿ’š โš™๏ธ ๐Ÿ & โ†ฉ๏ธ ๐Ÿƒ **๐Ÿ‘ Uvicorn ๐Ÿ› ๏ธ ๐Ÿ“ ๐Ÿ“ฆ**, โœ‹๏ธ ๐Ÿ‘ค ๐Ÿ”œ ๐Ÿ’ฌ ๐Ÿ‘† ๐Ÿ”ƒ โšซ๏ธ โช ๐Ÿ‘ˆ ๐Ÿ“ƒ. + ๐ŸŽฏ, ๐Ÿ•โ” ๐Ÿƒ ๐Ÿ”› **Kubernetes** ๐Ÿ‘† ๐Ÿ”œ ๐ŸŽฒ **๐Ÿšซ** ๐Ÿ’š โš™๏ธ ๐Ÿ & โ†ฉ๏ธ ๐Ÿƒ **๐Ÿ‘ Uvicorn ๐Ÿ› ๏ธ ๐Ÿ“ ๐Ÿ“ฆ**, โœ‹๏ธ ๐Ÿ‘ค ๐Ÿ”œ ๐Ÿ’ฌ ๐Ÿ‘† ๐Ÿ”ƒ โšซ๏ธ โช ๐Ÿ‘ˆ ๐Ÿ“ƒ. ## ๐Ÿ โฎ๏ธ Uvicorn ๐Ÿ‘จโ€๐Ÿญ @@ -167,7 +167,7 @@ $ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 ๐Ÿ‘ค ๐Ÿ”œ ๐ŸŽฆ ๐Ÿ‘† **๐Ÿ›‚ โ˜ ๐Ÿ–ผ** ๐Ÿ‘ˆ ๐Ÿ”Œ **๐Ÿ โฎ๏ธ Uvicorn ๐Ÿ‘จโ€๐Ÿญ** & ๐Ÿ”ข ๐Ÿ“ณ ๐Ÿ‘ˆ ๐Ÿ’ช โš  ๐Ÿ™… ๐Ÿ’ผ. -๐Ÿ“ค ๐Ÿ‘ค ๐Ÿ”œ ๐ŸŽฆ ๐Ÿ‘† โ” **๐Ÿ— ๐Ÿ‘† ๐Ÿ‘ ๐Ÿ–ผ โšช๏ธโžก๏ธ ๐Ÿ–Œ** ๐Ÿƒ ๐Ÿ‘ Uvicorn ๐Ÿ› ๏ธ (๐Ÿต ๐Ÿ). โšซ๏ธ ๐Ÿ™… ๐Ÿ› ๏ธ & ๐ŸŽฒ โšซ๏ธโ” ๐Ÿ‘† ๐Ÿ”œ ๐Ÿ’š ๐Ÿ•โ” โš™๏ธ ๐Ÿ“Ž ๐Ÿ“ฆ ๐Ÿงพ โš™๏ธ ๐Ÿ’– **Kubernete**. +๐Ÿ“ค ๐Ÿ‘ค ๐Ÿ”œ ๐ŸŽฆ ๐Ÿ‘† โ” **๐Ÿ— ๐Ÿ‘† ๐Ÿ‘ ๐Ÿ–ผ โšช๏ธโžก๏ธ ๐Ÿ–Œ** ๐Ÿƒ ๐Ÿ‘ Uvicorn ๐Ÿ› ๏ธ (๐Ÿต ๐Ÿ). โšซ๏ธ ๐Ÿ™… ๐Ÿ› ๏ธ & ๐ŸŽฒ โšซ๏ธโ” ๐Ÿ‘† ๐Ÿ”œ ๐Ÿ’š ๐Ÿ•โ” โš™๏ธ ๐Ÿ“Ž ๐Ÿ“ฆ ๐Ÿงพ โš™๏ธ ๐Ÿ’– **Kubernetes**. ## ๐ŸŒƒ @@ -175,4 +175,4 @@ $ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 ๐Ÿ‘† ๐Ÿ’ช โš™๏ธ ๐Ÿ‘‰ ๐Ÿงฐ & ๐Ÿ’ญ ๐Ÿšฅ ๐Ÿ‘† โš’ ๐Ÿ†™ **๐Ÿ‘† ๐Ÿ‘ ๐Ÿ› ๏ธ โš™๏ธ** โช โœŠ ๐Ÿ’… ๐ŸŽ ๐Ÿ› ๏ธ ๐Ÿ”ง ๐Ÿ‘†. -โœ… ๐Ÿ‘… โญ ๐Ÿ“ƒ ๐Ÿ’ก ๐Ÿ”ƒ **FastAPI** โฎ๏ธ ๐Ÿ“ฆ (โœ… โ˜ & Kubernete). ๐Ÿ‘† ๐Ÿ”œ ๐Ÿ‘€ ๐Ÿ‘ˆ ๐Ÿ‘ˆ ๐Ÿงฐ โœ”๏ธ ๐Ÿ™… ๐ŸŒŒ โŽ ๐ŸŽ **๐Ÿ› ๏ธ ๐Ÿ”ง** ๐Ÿ‘. ๐Ÿ‘ถ +โœ… ๐Ÿ‘… โญ ๐Ÿ“ƒ ๐Ÿ’ก ๐Ÿ”ƒ **FastAPI** โฎ๏ธ ๐Ÿ“ฆ (โœ… โ˜ & Kubernetes). ๐Ÿ‘† ๐Ÿ”œ ๐Ÿ‘€ ๐Ÿ‘ˆ ๐Ÿ‘ˆ ๐Ÿงฐ โœ”๏ธ ๐Ÿ™… ๐ŸŒŒ โŽ ๐ŸŽ **๐Ÿ› ๏ธ ๐Ÿ”ง** ๐Ÿ‘. ๐Ÿ‘ถ diff --git a/docs/em/docs/project-generation.md b/docs/em/docs/project-generation.md index 5fd667ad1..ae959e1d5 100644 --- a/docs/em/docs/project-generation.md +++ b/docs/em/docs/project-generation.md @@ -79,6 +79,6 @@ * **๐ŸŒˆ** ๐Ÿ•œ ๐Ÿท ๐Ÿ› ๏ธ. * **โ˜ ๐Ÿง  ๐Ÿ”Ž** ๐Ÿ“จ ๐Ÿ“ ๐Ÿ—. * **๐Ÿญ ๐Ÿ”œ** ๐Ÿ ๐Ÿ•ธ ๐Ÿ’ฝ โš™๏ธ Uvicorn & ๐Ÿ. -* **โ˜ ๐Ÿ‘ฉโ€๐Ÿ’ป** Kubernete (๐Ÿฆฒ) ๐Ÿ†‘/๐Ÿ’ฟ ๐Ÿ› ๏ธ ๐Ÿ—. +* **โ˜ ๐Ÿ‘ฉโ€๐Ÿ’ป** Kubernetes (๐Ÿฆฒ) ๐Ÿ†‘/๐Ÿ’ฟ ๐Ÿ› ๏ธ ๐Ÿ—. * **๐Ÿคธโ€โ™‚** ๐Ÿ’ช โš’ 1๏ธโƒฃ ๐ŸŒˆ ๐Ÿ— ๐Ÿ‡ช๐Ÿ‡ธ โฎ๏ธ ๐Ÿ— ๐Ÿ–ฅ. * **๐Ÿ’ช ๐Ÿง** ๐ŸŽ ๐Ÿท ๐Ÿ› ๏ธ (Pytorch, ๐Ÿ‡ธ๐Ÿ‡ฒ), ๐Ÿšซ ๐ŸŒˆ. diff --git a/docs/en/docs/how-to/sql-databases-peewee.md b/docs/en/docs/how-to/sql-databases-peewee.md index bf2f2e714..b0ab7c633 100644 --- a/docs/en/docs/how-to/sql-databases-peewee.md +++ b/docs/en/docs/how-to/sql-databases-peewee.md @@ -363,7 +363,7 @@ It will have the database connection open at the beginning and will just wait so This will easily let you test that your app with Peewee and FastAPI is behaving correctly with all the stuff about threads. -If you want to check how Peewee would break your app if used without modification, go the the `sql_app/database.py` file and comment the line: +If you want to check how Peewee would break your app if used without modification, go the `sql_app/database.py` file and comment the line: ```Python # db._state = PeeweeConnectionState() diff --git a/docs_src/openapi_webhooks/tutorial001.py b/docs_src/openapi_webhooks/tutorial001.py index 5016f5b00..55822bb48 100644 --- a/docs_src/openapi_webhooks/tutorial001.py +++ b/docs_src/openapi_webhooks/tutorial001.py @@ -8,7 +8,7 @@ app = FastAPI() class Subscription(BaseModel): username: str - montly_fee: float + monthly_fee: float start_date: datetime diff --git a/fastapi/utils.py b/fastapi/utils.py index 267d64ce8..53b47a160 100644 --- a/fastapi/utils.py +++ b/fastapi/utils.py @@ -117,7 +117,7 @@ def create_cloned_field( if PYDANTIC_V2: return field # cloned_types caches already cloned types to support recursive models and improve - # performance by avoiding unecessary cloning + # performance by avoiding unnecessary cloning if cloned_types is None: cloned_types = _CLONED_TYPES_CACHE diff --git a/tests/test_tutorial/test_openapi_webhooks/test_tutorial001.py b/tests/test_tutorial/test_openapi_webhooks/test_tutorial001.py index 9111fdb2f..dc67ec401 100644 --- a/tests/test_tutorial/test_openapi_webhooks/test_tutorial001.py +++ b/tests/test_tutorial/test_openapi_webhooks/test_tutorial001.py @@ -85,7 +85,7 @@ def test_openapi_schema(): "Subscription": { "properties": { "username": {"type": "string", "title": "Username"}, - "montly_fee": {"type": "number", "title": "Montly Fee"}, + "monthly_fee": {"type": "number", "title": "Monthly Fee"}, "start_date": { "type": "string", "format": "date-time", @@ -93,7 +93,7 @@ def test_openapi_schema(): }, }, "type": "object", - "required": ["username", "montly_fee", "start_date"], + "required": ["username", "monthly_fee", "start_date"], "title": "Subscription", }, "ValidationError": { diff --git a/tests/test_webhooks_security.py b/tests/test_webhooks_security.py index a1c7b18fb..21a694cb5 100644 --- a/tests/test_webhooks_security.py +++ b/tests/test_webhooks_security.py @@ -13,7 +13,7 @@ bearer_scheme = HTTPBearer() class Subscription(BaseModel): username: str - montly_fee: float + monthly_fee: float start_date: datetime @@ -93,7 +93,7 @@ def test_openapi_schema(): "Subscription": { "properties": { "username": {"type": "string", "title": "Username"}, - "montly_fee": {"type": "number", "title": "Montly Fee"}, + "monthly_fee": {"type": "number", "title": "Monthly Fee"}, "start_date": { "type": "string", "format": "date-time", @@ -101,7 +101,7 @@ def test_openapi_schema(): }, }, "type": "object", - "required": ["username", "montly_fee", "start_date"], + "required": ["username", "monthly_fee", "start_date"], "title": "Subscription", }, "ValidationError": { From eb017270fca06383e7d44f45a6850d58c315760f Mon Sep 17 00:00:00 2001 From: github-actions <github-actions@github.com> Date: Fri, 20 Oct 2023 09:00:53 +0000 Subject: [PATCH 27/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index d75f9a08c..9c7d78cb8 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -7,6 +7,7 @@ hide: ## Latest Changes +* โœ๏ธ Fix typo in `docs/en/docs/reference/dependencies.md`. PR [#10465](https://github.com/tiangolo/fastapi/pull/10465) by [@suravshresth](https://github.com/suravshresth). * โœ๏ธ Fix typos and rewordings in `docs/en/docs/tutorial/body-nested-models.md`. PR [#10468](https://github.com/tiangolo/fastapi/pull/10468) by [@yogabonito](https://github.com/yogabonito). * ๐Ÿ“ Update docs, remove references to removed `pydantic.Required` in `docs/en/docs/tutorial/query-params-str-validations.md`. PR [#10469](https://github.com/tiangolo/fastapi/pull/10469) by [@yogabonito](https://github.com/yogabonito). * โœ๏ธ Fix typo in `docs/en/docs/reference/index.md`. PR [#10467](https://github.com/tiangolo/fastapi/pull/10467) by [@tarsil](https://github.com/tarsil). From f41eb5e0051c12d3508841a5d7c42b838fb63ad6 Mon Sep 17 00:00:00 2001 From: github-actions <github-actions@github.com> Date: Fri, 20 Oct 2023 09:03:34 +0000 Subject: [PATCH 28/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 9c7d78cb8..fd1aa90cb 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -7,6 +7,7 @@ hide: ## Latest Changes +* โœ๏ธ Fix typos in emoji docs and in some source examples. PR [#10438](https://github.com/tiangolo/fastapi/pull/10438) by [@afuetterer](https://github.com/afuetterer). * โœ๏ธ Fix typo in `docs/en/docs/reference/dependencies.md`. PR [#10465](https://github.com/tiangolo/fastapi/pull/10465) by [@suravshresth](https://github.com/suravshresth). * โœ๏ธ Fix typos and rewordings in `docs/en/docs/tutorial/body-nested-models.md`. PR [#10468](https://github.com/tiangolo/fastapi/pull/10468) by [@yogabonito](https://github.com/yogabonito). * ๐Ÿ“ Update docs, remove references to removed `pydantic.Required` in `docs/en/docs/tutorial/query-params-str-validations.md`. PR [#10469](https://github.com/tiangolo/fastapi/pull/10469) by [@yogabonito](https://github.com/yogabonito). From 89e03bad1644c7a0b63960c4299ca79ebb1ae31c Mon Sep 17 00:00:00 2001 From: Giulio Davide Carparelli <giulio.davide.97@gmail.com> Date: Fri, 20 Oct 2023 11:08:42 +0200 Subject: [PATCH 29/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20example=20validat?= =?UTF-8?q?ion=20error=20from=20Pydantic=20v1=20to=20match=20Pydantic=20v2?= =?UTF-8?q?=20in=20`docs/en/docs/tutorial/path-params.md`=20(#10043)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/tutorial/path-params.md | 22 ++++++++++++---------- docs/en/docs/tutorial/query-params.md | 22 ++++++++++++---------- 2 files changed, 24 insertions(+), 20 deletions(-) diff --git a/docs/en/docs/tutorial/path-params.md b/docs/en/docs/tutorial/path-params.md index 6594a7a8b..847b56334 100644 --- a/docs/en/docs/tutorial/path-params.md +++ b/docs/en/docs/tutorial/path-params.md @@ -46,16 +46,18 @@ But if you go to the browser at <a href="http://127.0.0.1:8000/items/foo" class= ```JSON { - "detail": [ - { - "loc": [ - "path", - "item_id" - ], - "msg": "value is not a valid integer", - "type": "type_error.integer" - } - ] + "detail": [ + { + "type": "int_parsing", + "loc": [ + "path", + "item_id" + ], + "msg": "Input should be a valid integer, unable to parse string as an integer", + "input": "foo", + "url": "https://errors.pydantic.dev/2.1/v/int_parsing" + } + ] } ``` diff --git a/docs/en/docs/tutorial/query-params.md b/docs/en/docs/tutorial/query-params.md index 988ff4bf1..bc3b11948 100644 --- a/docs/en/docs/tutorial/query-params.md +++ b/docs/en/docs/tutorial/query-params.md @@ -173,16 +173,18 @@ http://127.0.0.1:8000/items/foo-item ```JSON { - "detail": [ - { - "loc": [ - "query", - "needy" - ], - "msg": "field required", - "type": "value_error.missing" - } - ] + "detail": [ + { + "type": "missing", + "loc": [ + "query", + "needy" + ], + "msg": "Field required", + "input": null, + "url": "https://errors.pydantic.dev/2.1/v/missing" + } + ] } ``` From 07a9b240e9a8acad3f9ab64fb921daf275aeeb85 Mon Sep 17 00:00:00 2001 From: github-actions <github-actions@github.com> Date: Fri, 20 Oct 2023 09:13:35 +0000 Subject: [PATCH 30/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index fd1aa90cb..df004dd8c 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -7,6 +7,7 @@ hide: ## Latest Changes +* ๐Ÿ“ Update example validation error from Pydantic v1 to match Pydantic v2 in `docs/en/docs/tutorial/path-params.md`. PR [#10043](https://github.com/tiangolo/fastapi/pull/10043) by [@giuliowaitforitdavide](https://github.com/giuliowaitforitdavide). * โœ๏ธ Fix typos in emoji docs and in some source examples. PR [#10438](https://github.com/tiangolo/fastapi/pull/10438) by [@afuetterer](https://github.com/afuetterer). * โœ๏ธ Fix typo in `docs/en/docs/reference/dependencies.md`. PR [#10465](https://github.com/tiangolo/fastapi/pull/10465) by [@suravshresth](https://github.com/suravshresth). * โœ๏ธ Fix typos and rewordings in `docs/en/docs/tutorial/body-nested-models.md`. PR [#10468](https://github.com/tiangolo/fastapi/pull/10468) by [@yogabonito](https://github.com/yogabonito). From 9b3e166b4343941790302dd8fe943cab50ffc4c0 Mon Sep 17 00:00:00 2001 From: worldworm <13227454+worldworm@users.noreply.github.com> Date: Fri, 20 Oct 2023 11:19:31 +0200 Subject: [PATCH 31/38] =?UTF-8?q?=E2=9C=8F=EF=B8=8F=20Fix=20link=20to=20SP?= =?UTF-8?q?DX=20license=20identifier=20in=20`docs/en/docs/tutorial/metadat?= =?UTF-8?q?a.md`=20(#10433)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sebastiรกn Ramรญrez <tiangolo@gmail.com> --- docs/en/docs/tutorial/metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/docs/tutorial/metadata.md b/docs/en/docs/tutorial/metadata.md index e75b4a0b9..504204e98 100644 --- a/docs/en/docs/tutorial/metadata.md +++ b/docs/en/docs/tutorial/metadata.md @@ -14,7 +14,7 @@ You can set the following fields that are used in the OpenAPI specification and | `version` | `string` | The version of the API. This is the version of your own application, not of OpenAPI. For example `2.5.0`. | | `terms_of_service` | `str` | A URL to the Terms of Service for the API. If provided, this has to be a URL. | | `contact` | `dict` | The contact information for the exposed API. It can contain several fields. <details><summary><code>contact</code> fields</summary><table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td><code>str</code></td><td>The identifying name of the contact person/organization.</td></tr><tr><td><code>url</code></td><td><code>str</code></td><td>The URL pointing to the contact information. MUST be in the format of a URL.</td></tr><tr><td><code>email</code></td><td><code>str</code></td><td>The email address of the contact person/organization. MUST be in the format of an email address.</td></tr></tbody></table></details> | -| `license_info` | `dict` | The license information for the exposed API. It can contain several fields. <details><summary><code>license_info</code> fields</summary><table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td><code>str</code></td><td><strong>REQUIRED</strong> (if a <code>license_info</code> is set). The license name used for the API.</td></tr><tr><td><code>identifier</code></td><td><code>str</code></td><td>An <a href="https://spdx.dev/spdx-specification-21-web-version/#h.jxpfx0ykyb60" class="external-link" target="_blank">SPDX</a> license expression for the API. The <code>identifier</code> field is mutually exclusive of the <code>url</code> field. <small>Available since OpenAPI 3.1.0, FastAPI 0.99.0.</small></td></tr><tr><td><code>url</code></td><td><code>str</code></td><td>A URL to the license used for the API. MUST be in the format of a URL.</td></tr></tbody></table></details> | +| `license_info` | `dict` | The license information for the exposed API. It can contain several fields. <details><summary><code>license_info</code> fields</summary><table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td><code>str</code></td><td><strong>REQUIRED</strong> (if a <code>license_info</code> is set). The license name used for the API.</td></tr><tr><td><code>identifier</code></td><td><code>str</code></td><td>An <a href="https://spdx.org/licenses/" class="external-link" target="_blank">SPDX</a> license expression for the API. The <code>identifier</code> field is mutually exclusive of the <code>url</code> field. <small>Available since OpenAPI 3.1.0, FastAPI 0.99.0.</small></td></tr><tr><td><code>url</code></td><td><code>str</code></td><td>A URL to the license used for the API. MUST be in the format of a URL.</td></tr></tbody></table></details> | You can set them as follows: From ab65486e757400b84d0116367ba3db7dcac72fd3 Mon Sep 17 00:00:00 2001 From: github-actions <github-actions@github.com> Date: Fri, 20 Oct 2023 09:21:13 +0000 Subject: [PATCH 32/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index df004dd8c..414afae12 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -7,6 +7,7 @@ hide: ## Latest Changes +* โœ๏ธ Fix link to SPDX license identifier in `docs/en/docs/tutorial/metadata.md`. PR [#10433](https://github.com/tiangolo/fastapi/pull/10433) by [@worldworm](https://github.com/worldworm). * ๐Ÿ“ Update example validation error from Pydantic v1 to match Pydantic v2 in `docs/en/docs/tutorial/path-params.md`. PR [#10043](https://github.com/tiangolo/fastapi/pull/10043) by [@giuliowaitforitdavide](https://github.com/giuliowaitforitdavide). * โœ๏ธ Fix typos in emoji docs and in some source examples. PR [#10438](https://github.com/tiangolo/fastapi/pull/10438) by [@afuetterer](https://github.com/afuetterer). * โœ๏ธ Fix typo in `docs/en/docs/reference/dependencies.md`. PR [#10465](https://github.com/tiangolo/fastapi/pull/10465) by [@suravshresth](https://github.com/suravshresth). From 9bfbacfe98c877ba661e0e40c8dcac7571de819a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= <tiangolo@gmail.com> Date: Sat, 21 Oct 2023 11:10:18 +0400 Subject: [PATCH 33/38] =?UTF-8?q?=F0=9F=90=9B=20Fix=20overriding=20MKDocs?= =?UTF-8?q?=20theme=20lang=20in=20hook=20(#10490)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- scripts/mkdocs_hooks.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/mkdocs_hooks.py b/scripts/mkdocs_hooks.py index b12487b50..2b6a05642 100644 --- a/scripts/mkdocs_hooks.py +++ b/scripts/mkdocs_hooks.py @@ -24,7 +24,7 @@ def get_missing_translation_content(docs_dir: str) -> str: @lru_cache() def get_mkdocs_material_langs() -> List[str]: material_path = Path(material.__file__).parent - material_langs_path = material_path / "partials" / "languages" + material_langs_path = material_path / "templates" / "partials" / "languages" langs = [file.stem for file in material_langs_path.glob("*.html")] return langs From 808e3bb9d56ac85e28e6f5e982f06209ad059436 Mon Sep 17 00:00:00 2001 From: github-actions <github-actions@github.com> Date: Sat, 21 Oct 2023 07:11:00 +0000 Subject: [PATCH 34/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 414afae12..163e708b8 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -7,6 +7,7 @@ hide: ## Latest Changes +* ๐Ÿ› Fix overriding MKDocs theme lang in hook. PR [#10490](https://github.com/tiangolo/fastapi/pull/10490) by [@tiangolo](https://github.com/tiangolo). * โœ๏ธ Fix link to SPDX license identifier in `docs/en/docs/tutorial/metadata.md`. PR [#10433](https://github.com/tiangolo/fastapi/pull/10433) by [@worldworm](https://github.com/worldworm). * ๐Ÿ“ Update example validation error from Pydantic v1 to match Pydantic v2 in `docs/en/docs/tutorial/path-params.md`. PR [#10043](https://github.com/tiangolo/fastapi/pull/10043) by [@giuliowaitforitdavide](https://github.com/giuliowaitforitdavide). * โœ๏ธ Fix typos in emoji docs and in some source examples. PR [#10438](https://github.com/tiangolo/fastapi/pull/10438) by [@afuetterer](https://github.com/afuetterer). From e8bd645fa9ee0a8ed3ba4df9cd8c743332a5d2ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= <tiangolo@gmail.com> Date: Sun, 22 Oct 2023 11:35:13 +0400 Subject: [PATCH 35/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20data=20structure?= =?UTF-8?q?=20and=20render=20for=20external-links=20(#10495)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * ๐Ÿ“ Update data structure and render for external-links * ๐Ÿ“ Update translations for external links --- docs/em/docs/external-links.md | 68 +++----------------------------- docs/en/data/external_links.yml | 22 +++++------ docs/en/docs/external-links.md | 70 +++------------------------------ docs/fr/docs/external-links.md | 61 +++------------------------- docs/ja/docs/external-links.md | 61 +++------------------------- docs/pt/docs/external-links.md | 61 +++------------------------- docs/ru/docs/external-links.md | 61 +++------------------------- 7 files changed, 47 insertions(+), 357 deletions(-) diff --git a/docs/em/docs/external-links.md b/docs/em/docs/external-links.md index 4440b1f12..5ba668bfa 100644 --- a/docs/em/docs/external-links.md +++ b/docs/em/docs/external-links.md @@ -11,77 +11,21 @@ ## ๐Ÿ“„ -### ๐Ÿ‡ช๐Ÿ‡ธ +{% for section_name, section_content in external_links.items() %} -{% if external_links %} -{% for article in external_links.articles.english %} +## {{ section_name }} -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} - -### ๐Ÿ‡ฏ๐Ÿ‡ต - -{% if external_links %} -{% for article in external_links.articles.japanese %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} - -### ๐Ÿ‡ป๐Ÿ‡ณ - -{% if external_links %} -{% for article in external_links.articles.vietnamese %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} - -### ๐Ÿ‡ท๐Ÿ‡บ - -{% if external_links %} -{% for article in external_links.articles.russian %} +{% for lang_name, lang_content in section_content.items() %} -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} +### {{ lang_name }} -### ๐Ÿ‡ฉ๐Ÿ‡ช +{% for item in lang_content %} -{% if external_links %} -{% for article in external_links.articles.german %} +* <a href="{{ item.link }}" class="external-link" target="_blank">{{ item.title }}</a> by <a href="{{ item.author_link }}" class="external-link" target="_blank">{{ item.author }}</a>. -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. {% endfor %} -{% endif %} - -### ๐Ÿ‡น๐Ÿ‡ผ - -{% if external_links %} -{% for article in external_links.articles.taiwanese %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. {% endfor %} -{% endif %} - -## ๐Ÿ“ป - -{% if external_links %} -{% for article in external_links.podcasts.english %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} - -## ๐Ÿ’ฌ - -{% if external_links %} -{% for article in external_links.talks.english %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. {% endfor %} -{% endif %} ## ๐Ÿ— diff --git a/docs/en/data/external_links.yml b/docs/en/data/external_links.yml index a7f766d16..726e7eae7 100644 --- a/docs/en/data/external_links.yml +++ b/docs/en/data/external_links.yml @@ -1,5 +1,5 @@ -articles: - english: +Articles: + English: - author: Adejumo Ridwan Suleiman author_link: https://www.linkedin.com/in/adejumoridwan/ link: https://medium.com/python-in-plain-english/build-an-sms-spam-classifier-serverless-database-with-faunadb-and-fastapi-23dbb275bc5b @@ -236,7 +236,7 @@ articles: author_link: https://medium.com/@krishnardt365 link: https://medium.com/@krishnardt365/fastapi-docker-and-postgres-91943e71be92 title: Fastapi, Docker(Docker compose) and Postgres - german: + German: - author: Marcel Sander (actidoo) author_link: https://www.actidoo.com link: https://www.actidoo.com/de/blog/python-fastapi-domain-driven-design @@ -249,7 +249,7 @@ articles: author_link: https://hellocoding.de/autor/felix-schuermeyer/ link: https://hellocoding.de/blog/coding-language/python/fastapi title: REST-API Programmieren mittels Python und dem FastAPI Modul - japanese: + Japanese: - author: '@bee2' author_link: https://qiita.com/bee2 link: https://qiita.com/bee2/items/75d9c0d7ba20e7a4a0e9 @@ -298,7 +298,7 @@ articles: author_link: https://qiita.com/mtitg link: https://qiita.com/mtitg/items/47770e9a562dd150631d title: FastAPI๏ฝœDBๆŽฅ็ถšใ—ใฆCRUDใ™ใ‚‹Python่ฃฝAPIใ‚ตใƒผใƒใƒผใ‚’ๆง‹็ฏ‰ - russian: + Russian: - author: Troy Kรถhler author_link: https://www.linkedin.com/in/trkohler/ link: https://trkohler.com/fast-api-introduction-to-framework @@ -311,18 +311,18 @@ articles: author_link: https://habr.com/ru/users/57uff3r/ link: https://habr.com/ru/post/454440/ title: 'ะœะตะปะบะฐั ะฟะธั‚ะพะฝัั‡ะฐั ั€ะฐะดะพัั‚ัŒ #2: Starlette - ะกะพะปะธะดะฝะฐั ะฟั€ะธะผะพั‡ะบะฐ โ€“ FastAPI' - vietnamese: + Vietnamese: - author: Nguyแป…n Nhรขn author_link: https://fullstackstation.com/author/figonking/ link: https://fullstackstation.com/fastapi-trien-khai-bang-docker/ title: 'FASTAPI: TRIแป‚N KHAI BแบฐNG DOCKER' - taiwanese: + Taiwanese: - author: Leon author_link: http://editor.leonh.space/ link: https://editor.leonh.space/2022/tortoise/ title: 'Tortoise ORM / FastAPI ๆ•ดๅˆๅฟซ้€Ÿ็ญ†่จ˜' -podcasts: - english: +Podcasts: + English: - author: Podcast.`__init__` author_link: https://www.pythonpodcast.com/ link: https://www.pythonpodcast.com/fastapi-web-application-framework-episode-259/ @@ -331,8 +331,8 @@ podcasts: author_link: https://pythonbytes.fm/ link: https://pythonbytes.fm/episodes/show/123/time-to-right-the-py-wrongs?time_in_sec=855 title: FastAPI on PythonBytes -talks: - english: +Talks: + English: - author: Sebastiรกn Ramรญrez (tiangolo) author_link: https://twitter.com/tiangolo link: https://www.youtube.com/watch?v=PnpTY1f4k2U diff --git a/docs/en/docs/external-links.md b/docs/en/docs/external-links.md index 0c91470bc..b89021ee2 100644 --- a/docs/en/docs/external-links.md +++ b/docs/en/docs/external-links.md @@ -9,79 +9,21 @@ Here's an incomplete list of some of them. !!! tip If you have an article, project, tool, or anything related to **FastAPI** that is not yet listed here, create a <a href="https://github.com/tiangolo/fastapi/edit/master/docs/en/data/external_links.yml" class="external-link" target="_blank">Pull Request adding it</a>. -## Articles +{% for section_name, section_content in external_links.items() %} -### English +## {{ section_name }} -{% if external_links %} -{% for article in external_links.articles.english %} +{% for lang_name, lang_content in section_content.items() %} -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} - -### Japanese - -{% if external_links %} -{% for article in external_links.articles.japanese %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} - -### Vietnamese +### {{ lang_name }} -{% if external_links %} -{% for article in external_links.articles.vietnamese %} +{% for item in lang_content %} -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} - -### Russian - -{% if external_links %} -{% for article in external_links.articles.russian %} +* <a href="{{ item.link }}" class="external-link" target="_blank">{{ item.title }}</a> by <a href="{{ item.author_link }}" class="external-link" target="_blank">{{ item.author }}</a>. -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. {% endfor %} -{% endif %} - -### German - -{% if external_links %} -{% for article in external_links.articles.german %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. {% endfor %} -{% endif %} - -### Taiwanese - -{% if external_links %} -{% for article in external_links.articles.taiwanese %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} - -## Podcasts - -{% if external_links %} -{% for article in external_links.podcasts.english %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} - -## Talks - -{% if external_links %} -{% for article in external_links.talks.english %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. {% endfor %} -{% endif %} ## Projects diff --git a/docs/fr/docs/external-links.md b/docs/fr/docs/external-links.md index 002e6d2b2..37b8c5b13 100644 --- a/docs/fr/docs/external-links.md +++ b/docs/fr/docs/external-links.md @@ -9,70 +9,21 @@ Voici une liste incomplรจte de certains d'entre eux. !!! tip "Astuce" Si vous avez un article, projet, outil, ou quoi que ce soit liรฉ ร  **FastAPI** qui n'est actuellement pas listรฉ ici, crรฉez une <a href="https://github.com/tiangolo/fastapi/edit/master/docs/en/data/external_links.yml" class="external-link" target="_blank">Pull Request l'ajoutant</a>. -## Articles +{% for section_name, section_content in external_links.items() %} -### Anglais +## {{ section_name }} -{% if external_links %} -{% for article in external_links.articles.english %} +{% for lang_name, lang_content in section_content.items() %} -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> par <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} - -### Japonais - -{% if external_links %} -{% for article in external_links.articles.japanese %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> par <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} +### {{ lang_name }} -### Vietnamien +{% for item in lang_content %} -{% if external_links %} -{% for article in external_links.articles.vietnamese %} +* <a href="{{ item.link }}" class="external-link" target="_blank">{{ item.title }}</a> by <a href="{{ item.author_link }}" class="external-link" target="_blank">{{ item.author }}</a>. -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> par <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. {% endfor %} -{% endif %} - -### Russe - -{% if external_links %} -{% for article in external_links.articles.russian %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> par <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. {% endfor %} -{% endif %} - -### Allemand - -{% if external_links %} -{% for article in external_links.articles.german %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> par <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} - -## Podcasts - -{% if external_links %} -{% for article in external_links.podcasts.english %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> par <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} - -## Confรฉrences - -{% if external_links %} -{% for article in external_links.talks.english %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> par <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. {% endfor %} -{% endif %} ## Projets diff --git a/docs/ja/docs/external-links.md b/docs/ja/docs/external-links.md index 6703f5fc2..aca5d5b34 100644 --- a/docs/ja/docs/external-links.md +++ b/docs/ja/docs/external-links.md @@ -9,70 +9,21 @@ !!! tip "่ฑ†็Ÿฅ่ญ˜" ใ“ใ“ใซใพใ ่ผ‰ใฃใฆใ„ใชใ„**FastAPI**ใซ้–ข้€ฃใ™ใ‚‹่จ˜ไบ‹ใ€ใƒ—ใƒญใ‚ธใ‚งใ‚ฏใƒˆใ€ใƒ„ใƒผใƒซใชใฉใŒใ‚ใ‚‹ๅ ดๅˆใฏใ€ <a href="https://github.com/tiangolo/fastapi/edit/master/docs/en/data/external_links.yml" class="external-link" target="_blank">ใƒ—ใƒซใƒชใ‚ฏใ‚จใ‚นใƒˆใ—ใฆไธ‹ใ•ใ„</a>ใ€‚ -## ่จ˜ไบ‹ +{% for section_name, section_content in external_links.items() %} -### ่‹ฑ่ชž +## {{ section_name }} -{% if external_links %} -{% for article in external_links.articles.english %} +{% for lang_name, lang_content in section_content.items() %} -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} - -### ๆ—ฅๆœฌ่ชž - -{% if external_links %} -{% for article in external_links.articles.japanese %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} +### {{ lang_name }} -### ใƒ™ใƒˆใƒŠใƒ ่ชž +{% for item in lang_content %} -{% if external_links %} -{% for article in external_links.articles.vietnamese %} +* <a href="{{ item.link }}" class="external-link" target="_blank">{{ item.title }}</a> by <a href="{{ item.author_link }}" class="external-link" target="_blank">{{ item.author }}</a>. -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. {% endfor %} -{% endif %} - -### ใƒญใ‚ทใ‚ข่ชž - -{% if external_links %} -{% for article in external_links.articles.russian %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. {% endfor %} -{% endif %} - -### ใƒ‰ใ‚คใƒ„่ชž - -{% if external_links %} -{% for article in external_links.articles.german %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} - -## ใƒใƒƒใƒ‰ใ‚ญใƒฃใ‚นใƒˆ - -{% if external_links %} -{% for article in external_links.podcasts.english %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} - -## ใƒˆใƒผใ‚ฏ - -{% if external_links %} -{% for article in external_links.talks.english %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. {% endfor %} -{% endif %} ## ใƒ—ใƒญใ‚ธใ‚งใ‚ฏใƒˆ diff --git a/docs/pt/docs/external-links.md b/docs/pt/docs/external-links.md index 6ec6c3a27..77ec32351 100644 --- a/docs/pt/docs/external-links.md +++ b/docs/pt/docs/external-links.md @@ -9,70 +9,21 @@ Aqui tem uma lista, incompleta, de algumas delas. !!! tip "Dica" Se vocรช tem um artigo, projeto, ferramenta ou qualquer coisa relacionada ao **FastAPI** que ainda nรฃo estรก listada aqui, crie um <a href="https://github.com/tiangolo/fastapi/edit/master/docs/external-links.md" class="external-link" target="_blank">_Pull Request_ adicionando ele</a>. -## Artigos +{% for section_name, section_content in external_links.items() %} -### Inglรชs +## {{ section_name }} -{% if external_links %} -{% for article in external_links.articles.english %} +{% for lang_name, lang_content in section_content.items() %} -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} - -### Japonรชs - -{% if external_links %} -{% for article in external_links.articles.japanese %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} +### {{ lang_name }} -### Vietnamita +{% for item in lang_content %} -{% if external_links %} -{% for article in external_links.articles.vietnamese %} +* <a href="{{ item.link }}" class="external-link" target="_blank">{{ item.title }}</a> by <a href="{{ item.author_link }}" class="external-link" target="_blank">{{ item.author }}</a>. -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. {% endfor %} -{% endif %} - -### Russo - -{% if external_links %} -{% for article in external_links.articles.russian %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. {% endfor %} -{% endif %} - -### Alemรฃo - -{% if external_links %} -{% for article in external_links.articles.german %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} - -## Podcasts - -{% if external_links %} -{% for article in external_links.podcasts.english %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} - -## Palestras - -{% if external_links %} -{% for article in external_links.talks.english %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. {% endfor %} -{% endif %} ## Projetos diff --git a/docs/ru/docs/external-links.md b/docs/ru/docs/external-links.md index 4daf65898..2448ef82e 100644 --- a/docs/ru/docs/external-links.md +++ b/docs/ru/docs/external-links.md @@ -9,70 +9,21 @@ !!! tip ะ•ัะปะธ ัƒ ะฒะฐั ะตัั‚ัŒ ัั‚ะฐั‚ัŒั, ะฟั€ะพะตะบั‚, ะธะฝัั‚ั€ัƒะผะตะฝั‚ ะธะปะธ ั‡ั‚ะพ-ะปะธะฑะพ, ัะฒัะทะฐะฝะฝะพะต ั **FastAPI**, ั‡ั‚ะพ ะตั‰ะต ะฝะต ะฟะตั€ะตั‡ะธัะปะตะฝะพ ะทะดะตััŒ, ัะพะทะดะฐะนั‚ะต <a href="https://github.com/tiangolo/fastapi/edit/master/docs/en/data/external_links.yml" class="external-link" target="_blank">Pull Request</a>. -## ะกั‚ะฐั‚ัŒะธ +{% for section_name, section_content in external_links.items() %} -### ะะฐ ะฐะฝะณะปะธะนัะบะพะผ +## {{ section_name }} -{% if external_links %} -{% for article in external_links.articles.english %} +{% for lang_name, lang_content in section_content.items() %} -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} - -### ะะฐ ัะฟะพะฝัะบะพะผ - -{% if external_links %} -{% for article in external_links.articles.japanese %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} +### {{ lang_name }} -### ะะฐ ะฒัŒะตั‚ะฝะฐะผัะบะพะผ +{% for item in lang_content %} -{% if external_links %} -{% for article in external_links.articles.vietnamese %} +* <a href="{{ item.link }}" class="external-link" target="_blank">{{ item.title }}</a> by <a href="{{ item.author_link }}" class="external-link" target="_blank">{{ item.author }}</a>. -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. {% endfor %} -{% endif %} - -### ะะฐ ั€ัƒััะบะพะผ - -{% if external_links %} -{% for article in external_links.articles.russian %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. {% endfor %} -{% endif %} - -### ะะฐ ะฝะตะผะตั†ะบะพะผ - -{% if external_links %} -{% for article in external_links.articles.german %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} - -## ะŸะพะดะบะฐัั‚ั‹ - -{% if external_links %} -{% for article in external_links.podcasts.english %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. -{% endfor %} -{% endif %} - -## Talks - -{% if external_links %} -{% for article in external_links.talks.english %} - -* <a href="{{ article.link }}" class="external-link" target="_blank">{{ article.title }}</a> by <a href="{{ article.author_link }}" class="external-link" target="_blank">{{ article.author }}</a>. {% endfor %} -{% endif %} ## ะŸั€ะพะตะบั‚ั‹ From f9b53ae77834eb803f8043493bd337b8a448ae5a Mon Sep 17 00:00:00 2001 From: github-actions <github-actions@github.com> Date: Sun, 22 Oct 2023 07:35:50 +0000 Subject: [PATCH 36/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 163e708b8..60675c757 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -7,6 +7,7 @@ hide: ## Latest Changes +* ๐Ÿ“ Update data structure and render for external-links. PR [#10495](https://github.com/tiangolo/fastapi/pull/10495) by [@tiangolo](https://github.com/tiangolo). * ๐Ÿ› Fix overriding MKDocs theme lang in hook. PR [#10490](https://github.com/tiangolo/fastapi/pull/10490) by [@tiangolo](https://github.com/tiangolo). * โœ๏ธ Fix link to SPDX license identifier in `docs/en/docs/tutorial/metadata.md`. PR [#10433](https://github.com/tiangolo/fastapi/pull/10433) by [@worldworm](https://github.com/worldworm). * ๐Ÿ“ Update example validation error from Pydantic v1 to match Pydantic v2 in `docs/en/docs/tutorial/path-params.md`. PR [#10043](https://github.com/tiangolo/fastapi/pull/10043) by [@giuliowaitforitdavide](https://github.com/giuliowaitforitdavide). From e0a5edaaa3796bca703ab7f914a69fed98cffcfc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= <tiangolo@gmail.com> Date: Sun, 22 Oct 2023 14:03:38 +0400 Subject: [PATCH 37/38] =?UTF-8?q?=F0=9F=94=A7=20Add=20`CITATION.cff`=20fil?= =?UTF-8?q?e=20for=20academic=20citations=20(#10496)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CITATION.cff | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 CITATION.cff diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 000000000..9028248b1 --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,24 @@ +# This CITATION.cff file was generated with cffinit. +# Visit https://bit.ly/cffinit to generate yours today! + +cff-version: 1.2.0 +title: FastAPI +message: >- + If you use this software, please cite it using the + metadata from this file. +type: software +authors: + - given-names: Sebastiรกn + family-names: Ramรญrez + email: tiangolo@gmail.com +identifiers: +repository-code: 'https://github.com/tiangolo/fastapi' +url: 'https://fastapi.tiangolo.com' +abstract: >- + FastAPI framework, high performance, easy to learn, fast to code, + ready for production +keywords: + - fastapi + - pydantic + - starlette +license: MIT From 4ef7a40eae98c0d346fbfa2472f9b52b1cbf9b8f Mon Sep 17 00:00:00 2001 From: github-actions <github-actions@github.com> Date: Sun, 22 Oct 2023 10:04:16 +0000 Subject: [PATCH 38/38] =?UTF-8?q?=F0=9F=93=9D=20Update=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/docs/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 60675c757..74b0b1b27 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -7,6 +7,7 @@ hide: ## Latest Changes +* ๐Ÿ”ง Add `CITATION.cff` file for academic citations. PR [#10496](https://github.com/tiangolo/fastapi/pull/10496) by [@tiangolo](https://github.com/tiangolo). * ๐Ÿ“ Update data structure and render for external-links. PR [#10495](https://github.com/tiangolo/fastapi/pull/10495) by [@tiangolo](https://github.com/tiangolo). * ๐Ÿ› Fix overriding MKDocs theme lang in hook. PR [#10490](https://github.com/tiangolo/fastapi/pull/10490) by [@tiangolo](https://github.com/tiangolo). * โœ๏ธ Fix link to SPDX license identifier in `docs/en/docs/tutorial/metadata.md`. PR [#10433](https://github.com/tiangolo/fastapi/pull/10433) by [@worldworm](https://github.com/worldworm).