diff --git a/.github/actions/comment-docs-preview-in-pr/Dockerfile b/.github/actions/comment-docs-preview-in-pr/Dockerfile
deleted file mode 100644
index 42627fe19..000000000
--- a/.github/actions/comment-docs-preview-in-pr/Dockerfile
+++ /dev/null
@@ -1,9 +0,0 @@
-FROM python:3.10
-
-COPY ./requirements.txt /app/requirements.txt
-
-RUN pip install -r /app/requirements.txt
-
-COPY ./app /app
-
-CMD ["python", "/app/main.py"]
diff --git a/.github/actions/comment-docs-preview-in-pr/action.yml b/.github/actions/comment-docs-preview-in-pr/action.yml
deleted file mode 100644
index 0eb64402d..000000000
--- a/.github/actions/comment-docs-preview-in-pr/action.yml
+++ /dev/null
@@ -1,13 +0,0 @@
-name: Comment Docs Preview in PR
-description: Comment with the docs URL preview in the PR
-author: Sebastián Ramírez
-
+
@@ -46,23 +46,22 @@ The key features are:
-
+
-
-
-
-
-
-
-
-
+
+
+
+
+
-
+
-
+
+
+
@@ -96,7 +95,7 @@ The key features are:
"_Honestly, what you've built looks super solid and polished. In many ways, it's what I wanted **Hug** to be - it's really inspiring to see someone build that._"
-
email_validator - for email validation.
-* pydantic-settings - for settings management.
-* pydantic-extra-types - for extra types to be used with Pydantic.
+* email-validator - for email validation.
Used by Starlette:
@@ -465,34 +472,27 @@ Used by Starlette:
Used by FastAPI / Starlette:
-* uvicorn - for the server that loads and serves your application.
+* uvicorn - for the server that loads and serves your application. This includes `uvicorn[standard]`, which includes some dependencies (e.g. `uvloop`) needed for high performance serving.
* `fastapi-cli` - to provide the `fastapi` command.
-When you install `fastapi` it comes these standard dependencies.
+### Without `standard` Dependencies
-Additional optional dependencies:
+If you don't want to include the `standard` optional dependencies, you can install with `pip install fastapi` instead of `pip install "fastapi[standard]"`.
+
+### Additional Optional Dependencies
+
+There are some additional dependencies you might want to install.
+
+Additional optional Pydantic dependencies:
+
+* pydantic-settings - for settings management.
+* pydantic-extra-types - for extra types to be used with Pydantic.
+
+Additional optional FastAPI dependencies:
* orjson - Required if you want to use `ORJSONResponse`.
* ujson - Required if you want to use `UJSONResponse`.
-## `fastapi-slim`
-
-If you don't want the extra standard optional dependencies, install `fastapi-slim` instead.
-
-When you install with:
-
-```bash
-pip install fastapi
-```
-
-...it includes the same code and dependencies as:
-
-```bash
-pip install "fastapi-slim[standard]"
-```
-
-The standard extra dependencies are the ones mentioned above.
-
## License
This project is licensed under the terms of the MIT license.
diff --git a/docs/az/docs/fastapi-people.md b/docs/az/docs/fastapi-people.md
deleted file mode 100644
index 9bb7ad6ea..000000000
--- a/docs/az/docs/fastapi-people.md
+++ /dev/null
@@ -1,185 +0,0 @@
----
-hide:
- - navigation
----
-
-# FastAPI İnsanlar
-
-FastAPI-ın bütün mənşəli insanları qəbul edən heyrətamiz icması var.
-
-
-
-## Yaradıcı - İcraçı
-
-Salam! 👋
-
-Bu mənəm:
-
-{% if people %}
-
-
+
@@ -87,7 +87,7 @@ FastAPI Python ilə API yaratmaq üçün standart Python Timothy Crosley - Hug creator (ref)
+
---
@@ -442,7 +442,7 @@ Müstəqil TechEmpower meyarları göstərir ki, Uvicorn üzərində işləyən
Pydantic tərəfindən istifadə olunanlar:
-*
email_validator - e-poçtun yoxlanılması üçün.
+* email-validator - e-poçtun yoxlanılması üçün.
* pydantic-settings - parametrlərin idarə edilməsi üçün.
* pydantic-extra-types - Pydantic ilə istifadə edilə bilən əlavə tiplər üçün.
diff --git a/docs/bn/docs/environment-variables.md b/docs/bn/docs/environment-variables.md
new file mode 100644
index 000000000..9122ca5bf
--- /dev/null
+++ b/docs/bn/docs/environment-variables.md
@@ -0,0 +1,298 @@
+# এনভায়রনমেন্ট ভেরিয়েবলস
+
+/// tip
+
+আপনি যদি "এনভায়রনমেন্ট ভেরিয়েবলস" কী এবং সেগুলো কীভাবে ব্যবহার করতে হয় সেটা জানেন, তাহলে এই অংশটি স্কিপ করে যেতে পারেন।
+
+///
+
+এনভায়রনমেন্ট ভেরিয়েবল (সংক্ষেপে "**env var**" নামেও পরিচিত) হলো এমন একটি ভেরিয়েবল যা পাইথন কোডের **বাইরে**, **অপারেটিং সিস্টেমে** থাকে এবং আপনার পাইথন কোড (বা অন্যান্য প্রোগ্রাম) দ্বারা যাকে রিড করা যায়।
+
+এনভায়রনমেন্ট ভেরিয়েবলস অ্যাপ্লিকেশনের **সেটিংস** পরিচালনা করতে, পাইথনের **ইনস্টলেশন** প্রক্রিয়ার অংশ হিসেবে, ইত্যাদি কাজে উপযোগী হতে পারে।
+
+## Env Vars তৈরী এবং ব্যবহার
+
+আপনি **শেল (টার্মিনাল)**-এ, পাইথনের প্রয়োজন ছাড়াই, এনভায়রনমেন্ট ভেরিয়েবলস **তৈরি** এবং ব্যবহার করতে পারবেনঃ
+
+//// tab | লিনাক্স, ম্যাকওএস, উইন্ডোজ Bash
+
+
email_validator - ইমেল যাচাইকরণের জন্য।
+- email-validator - ইমেল যাচাইকরণের জন্য।
স্টারলেট দ্বারা ব্যবহৃত:
diff --git a/docs/bn/docs/python-types.md b/docs/bn/docs/python-types.md
index 6923363dd..d98c2ec87 100644
--- a/docs/bn/docs/python-types.md
+++ b/docs/bn/docs/python-types.md
@@ -12,16 +12,18 @@ Python-এ ঐচ্ছিক "টাইপ হিন্ট" (যা "টাই
তবে, আপনি যদি কখনো **FastAPI** ব্যবহার নাও করেন, তবুও এগুলি সম্পর্কে একটু শেখা আপনার উপকারে আসবে।
-!!! Note
- যদি আপনি একজন Python বিশেষজ্ঞ হন, এবং টাইপ হিন্ট সম্পর্কে সবকিছু জানেন, তাহলে পরবর্তী অধ্যায়ে চলে যান।
+/// note
+
+যদি আপনি একজন Python বিশেষজ্ঞ হন, এবং টাইপ হিন্ট সম্পর্কে সবকিছু জানেন, তাহলে পরবর্তী অধ্যায়ে চলে যান।
+
+///
## প্রেরণা
চলুন একটি সাধারণ উদাহরণ দিয়ে শুরু করি:
-```Python
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py *}
+
এই প্রোগ্রামটি কল করলে আউটপুট হয়:
@@ -35,9 +37,8 @@ John Doe
* প্রতিটির প্রথম অক্ষরকে `title()` ব্যবহার করে বড় হাতের অক্ষরে রূপান্তর করে।
* তাদেরকে মাঝখানে একটি স্পেস দিয়ে concatenate করে।
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py hl[2] *}
+
### এটি সম্পাদনা করুন
@@ -79,9 +80,8 @@ John Doe
এগুলিই "টাইপ হিন্ট":
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial002.py!}
-```
+{* ../../docs_src/python_types/tutorial002.py hl[1] *}
+
এটি ডিফল্ট ভ্যালু ঘোষণা করার মত নয় যেমন:
@@ -109,9 +109,8 @@ John Doe
এই ফাংশনটি দেখুন, এটিতে ইতিমধ্যে টাইপ হিন্ট রয়েছে:
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial003.py!}
-```
+{* ../../docs_src/python_types/tutorial003.py hl[1] *}
+
এডিটর ভেরিয়েবলগুলির টাইপ জানার কারণে, আপনি শুধুমাত্র অটোকমপ্লিশনই পান না, আপনি এরর চেকও পান:
@@ -119,9 +118,8 @@ John Doe
এখন আপনি জানেন যে আপনাকে এটি ঠিক করতে হবে, `age`-কে একটি স্ট্রিং হিসেবে রূপান্তর করতে `str(age)` ব্যবহার করতে হবে:
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial004.py!}
-```
+{* ../../docs_src/python_types/tutorial004.py hl[2] *}
+
## টাইপ ঘোষণা
@@ -140,9 +138,8 @@ John Doe
* `bool`
* `bytes`
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial005.py!}
-```
+{* ../../docs_src/python_types/tutorial005.py hl[1] *}
+
### টাইপ প্যারামিটার সহ জেনেরিক টাইপ
@@ -170,45 +167,55 @@ Python যত এগিয়ে যাচ্ছে, **নতুন সংস্
উদাহরণস্বরূপ, একটি ভেরিয়েবলকে `str`-এর একটি `list` হিসেবে সংজ্ঞায়িত করা যাক।
-=== "Python 3.9+"
+//// tab | Python 3.9+
- ভেরিয়েবলটি ঘোষণা করুন, একই কোলন (`:`) সিনট্যাক্স ব্যবহার করে।
+ভেরিয়েবলটি ঘোষণা করুন, একই কোলন (`:`) সিনট্যাক্স ব্যবহার করে।
- টাইপ হিসেবে, `list` ব্যবহার করুন।
+টাইপ হিসেবে, `list` ব্যবহার করুন।
- যেহেতু লিস্ট এমন একটি টাইপ যা অভ্যন্তরীণ টাইপগুলি ধারণ করে, আপনি তাদের স্কোয়ার ব্রাকেটের ভিতরে ব্যবহার করুন:
+যেহেতু লিস্ট এমন একটি টাইপ যা অভ্যন্তরীণ টাইপগুলি ধারণ করে, আপনি তাদের স্কোয়ার ব্রাকেটের ভিতরে ব্যবহার করুন:
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial006_py39.py!}
- ```
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial006_py39.py!}
+```
-=== "Python 3.8+"
+////
- `typing` থেকে `List` (বড় হাতের `L` দিয়ে) ইমপোর্ট করুন:
+//// tab | Python 3.8+
- ``` Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial006.py!}
- ```
+`typing` থেকে `List` (বড় হাতের `L` দিয়ে) ইমপোর্ট করুন:
- ভেরিয়েবলটি ঘোষণা করুন, একই কোলন (`:`) সিনট্যাক্স ব্যবহার করে।
+``` Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial006.py!}
+```
- টাইপ হিসেবে, `typing` থেকে আপনার ইম্পোর্ট করা `List` ব্যবহার করুন।
+ভেরিয়েবলটি ঘোষণা করুন, একই কোলন (`:`) সিনট্যাক্স ব্যবহার করে।
- যেহেতু লিস্ট এমন একটি টাইপ যা অভ্যন্তরীণ টাইপগুলি ধারণ করে, আপনি তাদের স্কোয়ার ব্রাকেটের ভিতরে করুন:
+টাইপ হিসেবে, `typing` থেকে আপনার ইম্পোর্ট করা `List` ব্যবহার করুন।
- ```Python hl_lines="4"
- {!> ../../../docs_src/python_types/tutorial006.py!}
- ```
+যেহেতু লিস্ট এমন একটি টাইপ যা অভ্যন্তরীণ টাইপগুলি ধারণ করে, আপনি তাদের স্কোয়ার ব্রাকেটের ভিতরে করুন:
-!!! Info
- স্কোয়ার ব্রাকেট এর ভিতরে ব্যবহৃত এইসব অভন্তরীন টাইপগুলোকে "ইন্টারনাল টাইপ" বলে।
+```Python hl_lines="4"
+{!> ../../docs_src/python_types/tutorial006.py!}
+```
- এই উদাহরণে, এটি হচ্ছে `List`(অথবা পাইথন ৩.৯ বা তার উপরের সংস্করণের ক্ষেত্রে `list`) এ পাস করা টাইপ প্যারামিটার।
+////
+
+/// info
+
+স্কোয়ার ব্রাকেট এর ভিতরে ব্যবহৃত এইসব অভন্তরীন টাইপগুলোকে "ইন্টারনাল টাইপ" বলে।
+
+এই উদাহরণে, এটি হচ্ছে `List`(অথবা পাইথন ৩.৯ বা তার উপরের সংস্করণের ক্ষেত্রে `list`) এ পাস করা টাইপ প্যারামিটার।
+
+///
এর অর্থ হচ্ছে: "ভেরিয়েবল `items` একটি `list`, এবং এই লিস্টের প্রতিটি আইটেম একটি `str`।"
-!!! Tip
- যদি আপনি Python 3.9 বা তার উপরে ব্যবহার করেন, আপনার `typing` থেকে `List` আমদানি করতে হবে না, আপনি সাধারণ `list` ওই টাইপের পরিবর্তে ব্যবহার করতে পারেন।
+/// tip
+
+যদি আপনি Python 3.9 বা তার উপরে ব্যবহার করেন, আপনার `typing` থেকে `List` আমদানি করতে হবে না, আপনি সাধারণ `list` ওই টাইপের পরিবর্তে ব্যবহার করতে পারেন।
+
+///
এর মাধ্যমে, আপনার এডিটর লিস্ট থেকে আইটেম প্রসেস করার সময় সাপোর্ট প্রদান করতে পারবে:
@@ -224,17 +231,21 @@ Python যত এগিয়ে যাচ্ছে, **নতুন সংস্
আপনি `tuple` এবং `set` ঘোষণা করার জন্য একই প্রক্রিয়া অনুসরণ করবেন:
-=== "Python 3.9+"
+//// tab | Python 3.9+
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial007_py39.py!}
- ```
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial007_py39.py!}
+```
-=== "Python 3.8+"
+////
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial007.py!}
- ```
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial007.py!}
+```
+
+////
এর মানে হল:
@@ -249,18 +260,21 @@ Python যত এগিয়ে যাচ্ছে, **নতুন সংস্
দ্বিতীয় টাইপ প্যারামিটারটি হল `dict`-এর মানগুলির জন্য:
-=== "Python 3.9+"
+//// tab | Python 3.9+
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial008_py39.py!}
- ```
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008_py39.py!}
+```
-=== "Python 3.8+"
+////
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial008.py!}
- ```
+//// tab | Python 3.8+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial008.py!}
+```
+
+////
এর মানে হল:
@@ -276,17 +290,21 @@ Python 3.6 এবং তার উপরের সংস্করণগুলি
Python 3.10-এ একটি **নতুন সিনট্যাক্স** আছে যেখানে আপনি সম্ভাব্য টাইপগুলিকে একটি ভার্টিকাল বার (`|`) দ্বারা পৃথক করতে পারেন।
-=== "Python 3.10+"
+//// tab | Python 3.10+
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial008b_py310.py!}
- ```
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008b_py310.py!}
+```
-=== "Python 3.8+"
+////
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial008b.py!}
- ```
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial008b.py!}
+```
+
+////
উভয় ক্ষেত্রেই এর মানে হল যে `item` হতে পারে একটি `int` অথবা `str`।
@@ -297,7 +315,7 @@ Python 3.10-এ একটি **নতুন সিনট্যাক্স** আ
Python 3.6 এবং তার উপরের সংস্করণগুলিতে (Python 3.10 অনতর্ভুক্ত) আপনি `typing` মডিউল থেকে `Optional` ইমপোর্ট করে এটি ঘোষণা এবং ব্যবহার করতে পারেন।
```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial009.py!}
+{!../../docs_src/python_types/tutorial009.py!}
```
`Optional[str]` ব্যবহার করা মানে হল শুধু `str` নয়, এটি হতে পারে `None`-ও, যা আপনার এডিটরকে সেই ত্রুটিগুলি শনাক্ত করতে সাহায্য করবে যেখানে আপনি ধরে নিচ্ছেন যে একটি মান সবসময় `str` হবে, অথচ এটি `None`-ও হতে পারেও।
@@ -306,23 +324,29 @@ Python 3.6 এবং তার উপরের সংস্করণগুলি
এর মানে হল, Python 3.10-এ, আপনি টাইপগুলির ইউনিয়ন ঘোষণা করতে `Something | None` ব্যবহার করতে পারেন:
-=== "Python 3.10+"
+//// tab | Python 3.10+
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial009_py310.py!}
- ```
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial009_py310.py!}
+```
-=== "Python 3.8+"
+////
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial009.py!}
- ```
+//// tab | Python 3.8+
-=== "Python 3.8+ বিকল্প"
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial009.py!}
+```
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial009b.py!}
- ```
+////
+
+//// tab | Python 3.8+ বিকল্প
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial009b.py!}
+```
+
+////
#### `Union` বা `Optional` ব্যবহার
@@ -339,9 +363,8 @@ Python 3.6 এবং তার উপরের সংস্করণগুলি
একটি উদাহরণ হিসেবে, এই ফাংশনটি নিন:
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial009c.py!}
-```
+{* ../../docs_src/python_types/tutorial009c.py hl[1,4] *}
+
`name` প্যারামিটারটি `Optional[str]` হিসেবে সংজ্ঞায়িত হয়েছে, কিন্তু এটি **অপশনাল নয়**, আপনি প্যারামিটার ছাড়া ফাংশনটি কল করতে পারবেন না:
@@ -357,9 +380,8 @@ say_hi(name=None) # এটি কাজ করে, None বৈধ 🎉
সুখবর হল, একবার আপনি Python 3.10 ব্যবহার করা শুরু করলে, আপনাকে এগুলোর ব্যাপারে আর চিন্তা করতে হবে না, যেহুতু আপনি | ব্যবহার করেই ইউনিয়ন ঘোষণা করতে পারবেন:
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial009c_py310.py!}
-```
+{* ../../docs_src/python_types/tutorial009c_py310.py hl[1,4] *}
+
এবং তারপর আপনাকে নামগুলি যেমন `Optional` এবং `Union` নিয়ে আর চিন্তা করতে হবে না। 😎
@@ -367,46 +389,53 @@ say_hi(name=None) # এটি কাজ করে, None বৈধ 🎉
স্কোয়ার ব্র্যাকেটে টাইপ প্যারামিটার নেওয়া এই টাইপগুলিকে **জেনেরিক টাইপ** বা **জেনেরিকস** বলা হয়, যেমন:
-=== "Python 3.10+"
- আপনি সেই একই বিল্টইন টাইপ জেনেরিক্স হিসেবে ব্যবহার করতে পারবেন(ভিতরে টাইপ সহ স্কয়ারে ব্রাকেট দিয়ে):
+//// tab | Python 3.10+
- * `list`
- * `tuple`
- * `set`
- * `dict`
+আপনি সেই একই বিল্টইন টাইপ জেনেরিক্স হিসেবে ব্যবহার করতে পারবেন(ভিতরে টাইপ সহ স্কয়ারে ব্রাকেট দিয়ে):
- এবং Python 3.8 এর মতোই, `typing` মডিউল থেকে:
+* `list`
+* `tuple`
+* `set`
+* `dict`
- * `Union`
- * `Optional` (Python 3.8 এর মতোই)
- * ...এবং অন্যান্য।
+এবং Python 3.8 এর মতোই, `typing` মডিউল থেকে:
- Python 3.10-এ, `Union` এবং `Optional` জেনেরিকস ব্যবহার করার বিকল্প হিসেবে, আপনি টাইপগুলির ইউনিয়ন ঘোষণা করতে ভার্টিকাল বার (`|`) ব্যবহার করতে পারেন, যা ওদের থেকে অনেক ভালো এবং সহজ।
+* `Union`
+* `Optional` (Python 3.8 এর মতোই)
+* ...এবং অন্যান্য।
-=== "Python 3.9+"
+Python 3.10-এ, `Union` এবং `Optional` জেনেরিকস ব্যবহার করার বিকল্প হিসেবে, আপনি টাইপগুলির ইউনিয়ন ঘোষণা করতে ভার্টিকাল বার (`|`) ব্যবহার করতে পারেন, যা ওদের থেকে অনেক ভালো এবং সহজ।
- আপনি সেই একই বিল্টইন টাইপ জেনেরিক্স হিসেবে ব্যবহার করতে পারবেন(ভিতরে টাইপ সহ স্কয়ারে ব্রাকেট দিয়ে):
+////
- * `list`
- * `tuple`
- * `set`
- * `dict`
+//// tab | Python 3.9+
- এবং Python 3.8 এর মতোই, `typing` মডিউল থেকে:
+আপনি সেই একই বিল্টইন টাইপ জেনেরিক্স হিসেবে ব্যবহার করতে পারবেন(ভিতরে টাইপ সহ স্কয়ারে ব্রাকেট দিয়ে):
- * `Union`
- * `Optional`
- * ...এবং অন্যান্য।
+* `list`
+* `tuple`
+* `set`
+* `dict`
-=== "Python 3.8+"
+এবং Python 3.8 এর মতোই, `typing` মডিউল থেকে:
- * `List`
- * `Tuple`
- * `Set`
- * `Dict`
- * `Union`
- * `Optional`
- * ...এবং অন্যান্য।
+* `Union`
+* `Optional`
+* ...এবং অন্যান্য।
+
+////
+
+//// tab | Python 3.8+
+
+* `List`
+* `Tuple`
+* `Set`
+* `Dict`
+* `Union`
+* `Optional`
+* ...এবং অন্যান্য।
+
+////
### ক্লাস হিসেবে টাইপস
@@ -414,15 +443,13 @@ say_hi(name=None) # এটি কাজ করে, None বৈধ 🎉
ধরুন আপনার কাছে `Person` নামে একটি ক্লাস আছে, যার একটি নাম আছে:
-```Python hl_lines="1-3"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
+
তারপর আপনি একটি ভেরিয়েবলকে `Person` টাইপের হিসেবে ঘোষণা করতে পারেন:
-```Python hl_lines="6"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[6] *}
+
এবং তারপর, আবার, আপনি এডিটর সাপোর্ট পেয়ে যাবেন:
@@ -446,55 +473,71 @@ say_hi(name=None) # এটি কাজ করে, None বৈধ 🎉
অফিসিয়াল Pydantic ডক্স থেকে একটি উদাহরণ:
-=== "Python 3.10+"
+//// tab | Python 3.10+
- ```Python
- {!> ../../../docs_src/python_types/tutorial011_py310.py!}
- ```
+```Python
+{!> ../../docs_src/python_types/tutorial011_py310.py!}
+```
-=== "Python 3.9+"
+////
- ```Python
- {!> ../../../docs_src/python_types/tutorial011_py39.py!}
- ```
+//// tab | Python 3.9+
-=== "Python 3.8+"
+```Python
+{!> ../../docs_src/python_types/tutorial011_py39.py!}
+```
- ```Python
- {!> ../../../docs_src/python_types/tutorial011.py!}
- ```
+////
-!!! Info
- [Pydantic সম্পর্কে আরও জানতে, এর ডকুমেন্টেশন দেখুন](https://docs.pydantic.dev/)।
+//// tab | Python 3.8+
+
+```Python
+{!> ../../docs_src/python_types/tutorial011.py!}
+```
+
+////
+
+/// info
+
+[Pydantic সম্পর্কে আরও জানতে, এর ডকুমেন্টেশন দেখুন](https://docs.pydantic.dev/)।
+
+///
**FastAPI** মূলত Pydantic-এর উপর নির্মিত।
আপনি এই সমস্ত কিছুর অনেক বাস্তবসম্মত উদাহরণ পাবেন [টিউটোরিয়াল - ইউজার গাইডে](https://fastapi.tiangolo.com/tutorial/)।
-!!! Tip
- যখন আপনি `Optional` বা `Union[Something, None]` ব্যবহার করেন এবং কোনো ডিফল্ট মান না থাকে, Pydantic-এর একটি বিশেষ আচরণ রয়েছে, আপনি Pydantic ডকুমেন্টেশনে [Required Optional fields](https://docs.pydantic.dev/latest/concepts/models/#required-optional-fields) সম্পর্কে আরও পড়তে পারেন।
+/// tip
+
+যখন আপনি `Optional` বা `Union[Something, None]` ব্যবহার করেন এবং কোনো ডিফল্ট মান না থাকে, Pydantic-এর একটি বিশেষ আচরণ রয়েছে, আপনি Pydantic ডকুমেন্টেশনে [Required Optional fields](https://docs.pydantic.dev/latest/concepts/models/#required-optional-fields) সম্পর্কে আরও পড়তে পারেন।
+
+///
## মেটাডাটা অ্যানোটেশন সহ টাইপ হিন্টস
Python-এ এমন একটি ফিচার আছে যা `Annotated` ব্যবহার করে এই টাইপ হিন্টগুলিতে **অতিরিক্ত মেটাডাটা** রাখতে দেয়।
-=== "Python 3.9+"
+//// tab | Python 3.9+
- Python 3.9-এ, `Annotated` স্ট্যান্ডার্ড লাইব্রেরিতে অন্তর্ভুক্ত, তাই আপনি এটি `typing` থেকে ইমপোর্ট করতে পারেন।
+Python 3.9-এ, `Annotated` স্ট্যান্ডার্ড লাইব্রেরিতে অন্তর্ভুক্ত, তাই আপনি এটি `typing` থেকে ইমপোর্ট করতে পারেন।
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial013_py39.py!}
- ```
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial013_py39.py!}
+```
-=== "Python 3.8+"
+////
- Python 3.9-এর নীচের সংস্করণগুলিতে, আপনি `Annotated`-কে `typing_extensions` থেকে ইমপোর্ট করেন।
+//// tab | Python 3.8+
- এটি **FastAPI** এর সাথে ইতিমদ্ধে ইনস্টল হয়ে থাকবে।
+Python 3.9-এর নীচের সংস্করণগুলিতে, আপনি `Annotated`-কে `typing_extensions` থেকে ইমপোর্ট করেন।
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial013.py!}
- ```
+এটি **FastAPI** এর সাথে ইতিমদ্ধে ইনস্টল হয়ে থাকবে।
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial013.py!}
+```
+
+////
Python নিজে এই `Annotated` দিয়ে কিছুই করে না। এবং এডিটর এবং অন্যান্য টুলগুলির জন্য, টাইপটি এখনও `str`।
@@ -506,10 +549,13 @@ Python নিজে এই `Annotated` দিয়ে কিছুই করে
পরবর্তীতে আপনি দেখবেন এটি কতটা **শক্তিশালী** হতে পারে।
-!!! Tip
- এটি **স্ট্যান্ডার্ড Python** হওয়ার মানে হল আপনি আপনার এডিটরে, আপনি যে টুলগুলি কোড বিশ্লেষণ এবং রিফ্যাক্টর করার জন্য ব্যবহার করেন তাতে **সেরা সম্ভাব্য ডেভেলপার এক্সপেরিয়েন্স** পাবেন। ✨
+/// tip
- এবং এছাড়াও আপনার কোড অন্যান্য অনেক Python টুল এবং লাইব্রেরিগুলির সাথে খুব সামঞ্জস্যপূর্ণ হবে। 🚀
+এটি **স্ট্যান্ডার্ড Python** হওয়ার মানে হল আপনি আপনার এডিটরে, আপনি যে টুলগুলি কোড বিশ্লেষণ এবং রিফ্যাক্টর করার জন্য ব্যবহার করেন তাতে **সেরা সম্ভাব্য ডেভেলপার এক্সপেরিয়েন্স** পাবেন। ✨
+
+এবং এছাড়াও আপনার কোড অন্যান্য অনেক Python টুল এবং লাইব্রেরিগুলির সাথে খুব সামঞ্জস্যপূর্ণ হবে। 🚀
+
+///
## **FastAPI**-এ টাইপ হিন্টস
@@ -533,5 +579,8 @@ Python নিজে এই `Annotated` দিয়ে কিছুই করে
গুরুত্বপূর্ণ বিষয় হল, আপনি যদি স্ট্যান্ডার্ড Python টাইপগুলি ব্যবহার করেন, তবে আরও বেশি ক্লাস, ডেকোরেটর ইত্যাদি যোগ না করেই একই স্থানে **FastAPI** আপনার অনেক কাজ করে দিবে।
-!!! Info
- যদি আপনি টিউটোরিয়ালের সমস্ত বিষয় পড়ে ফেলে থাকেন এবং টাইপ সম্পর্কে আরও জানতে চান, তবে একটি ভালো রিসোর্স হল [mypy এর "cheat sheet"](https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html)। এই "cheat sheet" এ আপনি Python টাইপ হিন্ট সম্পর্কে বেসিক থেকে উন্নত লেভেলের ধারণা পেতে পারেন, যা আপনার কোডে টাইপ সেফটি এবং স্পষ্টতা বাড়াতে সাহায্য করবে।
+/// info
+
+যদি আপনি টিউটোরিয়ালের সমস্ত বিষয় পড়ে ফেলে থাকেন এবং টাইপ সম্পর্কে আরও জানতে চান, তবে একটি ভালো রিসোর্স হল [mypy এর "cheat sheet"](https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html)। এই "cheat sheet" এ আপনি Python টাইপ হিন্ট সম্পর্কে বেসিক থেকে উন্নত লেভেলের ধারণা পেতে পারেন, যা আপনার কোডে টাইপ সেফটি এবং স্পষ্টতা বাড়াতে সাহায্য করবে।
+
+///
diff --git a/docs/de/docs/advanced/additional-responses.md b/docs/de/docs/advanced/additional-responses.md
index 2bfcfab33..bf38d9795 100644
--- a/docs/de/docs/advanced/additional-responses.md
+++ b/docs/de/docs/advanced/additional-responses.md
@@ -1,9 +1,12 @@
# Zusätzliche Responses in OpenAPI
-!!! warning "Achtung"
- Dies ist ein eher fortgeschrittenes Thema.
+/// warning | Achtung
- Wenn Sie mit **FastAPI** beginnen, benötigen Sie dies möglicherweise nicht.
+Dies ist ein eher fortgeschrittenes Thema.
+
+Wenn Sie mit **FastAPI** beginnen, benötigen Sie dies möglicherweise nicht.
+
+///
Sie können zusätzliche Responses mit zusätzlichen Statuscodes, Medientypen, Beschreibungen, usw. deklarieren.
@@ -23,24 +26,28 @@ Jedes dieser Response-`dict`s kann einen Schlüssel `model` haben, welcher ein P
Um beispielsweise eine weitere Response mit dem Statuscode `404` und einem Pydantic-Modell `Message` zu deklarieren, können Sie schreiben:
-```Python hl_lines="18 22"
-{!../../../docs_src/additional_responses/tutorial001.py!}
-```
+{* ../../docs_src/additional_responses/tutorial001.py hl[18,22] *}
-!!! note "Hinweis"
- Beachten Sie, dass Sie die `JSONResponse` direkt zurückgeben müssen.
+/// note | Hinweis
-!!! info
- Der `model`-Schlüssel ist nicht Teil von OpenAPI.
+Beachten Sie, dass Sie die `JSONResponse` direkt zurückgeben müssen.
- **FastAPI** nimmt das Pydantic-Modell von dort, generiert das JSON-Schema und fügt es an der richtigen Stelle ein.
+///
- Die richtige Stelle ist:
+/// info
- * Im Schlüssel `content`, der als Wert ein weiteres JSON-Objekt (`dict`) hat, welches Folgendes enthält:
- * Ein Schlüssel mit dem Medientyp, z. B. `application/json`, der als Wert ein weiteres JSON-Objekt hat, welches Folgendes enthält:
- * Ein Schlüssel `schema`, der als Wert das JSON-Schema aus dem Modell hat, hier ist die richtige Stelle.
- * **FastAPI** fügt hier eine Referenz auf die globalen JSON-Schemas an einer anderen Stelle in Ihrer OpenAPI hinzu, anstatt es direkt einzubinden. Auf diese Weise können andere Anwendungen und Clients diese JSON-Schemas direkt verwenden, bessere Tools zur Codegenerierung bereitstellen, usw.
+Der `model`-Schlüssel ist nicht Teil von OpenAPI.
+
+**FastAPI** nimmt das Pydantic-Modell von dort, generiert das JSON-Schema und fügt es an der richtigen Stelle ein.
+
+Die richtige Stelle ist:
+
+* Im Schlüssel `content`, der als Wert ein weiteres JSON-Objekt (`dict`) hat, welches Folgendes enthält:
+ * Ein Schlüssel mit dem Medientyp, z. B. `application/json`, der als Wert ein weiteres JSON-Objekt hat, welches Folgendes enthält:
+ * Ein Schlüssel `schema`, der als Wert das JSON-Schema aus dem Modell hat, hier ist die richtige Stelle.
+ * **FastAPI** fügt hier eine Referenz auf die globalen JSON-Schemas an einer anderen Stelle in Ihrer OpenAPI hinzu, anstatt es direkt einzubinden. Auf diese Weise können andere Anwendungen und Clients diese JSON-Schemas direkt verwenden, bessere Tools zur Codegenerierung bereitstellen, usw.
+
+///
Die generierten Responses in der OpenAPI für diese *Pfadoperation* lauten:
@@ -168,17 +175,21 @@ Sie können denselben `responses`-Parameter verwenden, um verschiedene Medientyp
Sie können beispielsweise einen zusätzlichen Medientyp `image/png` hinzufügen und damit deklarieren, dass Ihre *Pfadoperation* ein JSON-Objekt (mit dem Medientyp `application/json`) oder ein PNG-Bild zurückgeben kann:
-```Python hl_lines="19-24 28"
-{!../../../docs_src/additional_responses/tutorial002.py!}
-```
+{* ../../docs_src/additional_responses/tutorial002.py hl[19:24,28] *}
-!!! note "Hinweis"
- Beachten Sie, dass Sie das Bild direkt mit einer `FileResponse` zurückgeben müssen.
+/// note | Hinweis
-!!! info
- Sofern Sie in Ihrem Parameter `responses` nicht explizit einen anderen Medientyp angeben, geht FastAPI davon aus, dass die Response denselben Medientyp wie die Haupt-Response-Klasse hat (Standardmäßig `application/json`).
+Beachten Sie, dass Sie das Bild direkt mit einer `FileResponse` zurückgeben müssen.
- Wenn Sie jedoch eine benutzerdefinierte Response-Klasse mit `None` als Medientyp angegeben haben, verwendet FastAPI `application/json` für jede zusätzliche Response, die über ein zugehöriges Modell verfügt.
+///
+
+/// info
+
+Sofern Sie in Ihrem Parameter `responses` nicht explizit einen anderen Medientyp angeben, geht FastAPI davon aus, dass die Response denselben Medientyp wie die Haupt-Response-Klasse hat (Standardmäßig `application/json`).
+
+Wenn Sie jedoch eine benutzerdefinierte Response-Klasse mit `None` als Medientyp angegeben haben, verwendet FastAPI `application/json` für jede zusätzliche Response, die über ein zugehöriges Modell verfügt.
+
+///
## Informationen kombinieren
@@ -192,9 +203,7 @@ Sie können beispielsweise eine Response mit dem Statuscode `404` deklarieren, d
Und eine Response mit dem Statuscode `200`, die Ihr `response_model` verwendet, aber ein benutzerdefiniertes Beispiel (`example`) enthält:
-```Python hl_lines="20-31"
-{!../../../docs_src/additional_responses/tutorial003.py!}
-```
+{* ../../docs_src/additional_responses/tutorial003.py hl[20:31] *}
Es wird alles kombiniert und in Ihre OpenAPI eingebunden und in der API-Dokumentation angezeigt:
@@ -228,9 +237,7 @@ Mit dieser Technik können Sie einige vordefinierte Responses in Ihren *Pfadoper
Zum Beispiel:
-```Python hl_lines="13-17 26"
-{!../../../docs_src/additional_responses/tutorial004.py!}
-```
+{* ../../docs_src/additional_responses/tutorial004.py hl[13:17,26] *}
## Weitere Informationen zu OpenAPI-Responses
diff --git a/docs/de/docs/advanced/additional-status-codes.md b/docs/de/docs/advanced/additional-status-codes.md
index e9de267cf..b07bb90ab 100644
--- a/docs/de/docs/advanced/additional-status-codes.md
+++ b/docs/de/docs/advanced/additional-status-codes.md
@@ -14,53 +14,25 @@ Sie möchten aber auch, dass sie neue Artikel akzeptiert. Und wenn die Elemente
Um dies zu erreichen, importieren Sie `JSONResponse`, und geben Sie Ihren Inhalt direkt zurück, indem Sie den gewünschten `status_code` setzen:
-=== "Python 3.10+"
+{* ../../docs_src/additional_status_codes/tutorial001_an_py310.py hl[4,25] *}
- ```Python hl_lines="4 25"
- {!> ../../../docs_src/additional_status_codes/tutorial001_an_py310.py!}
- ```
+/// warning | Achtung
-=== "Python 3.9+"
+Wenn Sie eine `Response` direkt zurückgeben, wie im obigen Beispiel, wird sie direkt zurückgegeben.
- ```Python hl_lines="4 25"
- {!> ../../../docs_src/additional_status_codes/tutorial001_an_py39.py!}
- ```
+Sie wird nicht mit einem Modell usw. serialisiert.
-=== "Python 3.8+"
+Stellen Sie sicher, dass sie die gewünschten Daten enthält und dass die Werte gültiges JSON sind (wenn Sie `JSONResponse` verwenden).
- ```Python hl_lines="4 26"
- {!> ../../../docs_src/additional_status_codes/tutorial001_an.py!}
- ```
+///
-=== "Python 3.10+ nicht annotiert"
+/// note | Technische Details
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
+Sie können auch `from starlette.responses import JSONResponse` verwenden.
- ```Python hl_lines="2 23"
- {!> ../../../docs_src/additional_status_codes/tutorial001_py310.py!}
- ```
+**FastAPI** bietet dieselben `starlette.responses` auch via `fastapi.responses` an, als Annehmlichkeit für Sie, den Entwickler. Die meisten verfügbaren Responses kommen aber direkt von Starlette. Das Gleiche gilt für `status`.
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="4 25"
- {!> ../../../docs_src/additional_status_codes/tutorial001.py!}
- ```
-
-!!! warning "Achtung"
- Wenn Sie eine `Response` direkt zurückgeben, wie im obigen Beispiel, wird sie direkt zurückgegeben.
-
- Sie wird nicht mit einem Modell usw. serialisiert.
-
- Stellen Sie sicher, dass sie die gewünschten Daten enthält und dass die Werte gültiges JSON sind (wenn Sie `JSONResponse` verwenden).
-
-!!! note "Technische Details"
- Sie können auch `from starlette.responses import JSONResponse` verwenden.
-
- **FastAPI** bietet dieselben `starlette.responses` auch via `fastapi.responses` an, als Annehmlichkeit für Sie, den Entwickler. Die meisten verfügbaren Responses kommen aber direkt von Starlette. Das Gleiche gilt für `status`.
+///
## OpenAPI- und API-Dokumentation
diff --git a/docs/de/docs/advanced/advanced-dependencies.md b/docs/de/docs/advanced/advanced-dependencies.md
index 33b93b332..56eb7d454 100644
--- a/docs/de/docs/advanced/advanced-dependencies.md
+++ b/docs/de/docs/advanced/advanced-dependencies.md
@@ -18,26 +18,7 @@ Nicht die Klasse selbst (die bereits aufrufbar ist), sondern eine Instanz dieser
Dazu deklarieren wir eine Methode `__call__`:
-=== "Python 3.9+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/dependencies/tutorial011_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/dependencies/tutorial011_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/dependencies/tutorial011.py!}
- ```
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[12] *}
In diesem Fall ist dieses `__call__` das, was **FastAPI** verwendet, um nach zusätzlichen Parametern und Unterabhängigkeiten zu suchen, und das ist es auch, was später aufgerufen wird, um einen Wert an den Parameter in Ihrer *Pfadoperation-Funktion* zu übergeben.
@@ -45,26 +26,7 @@ In diesem Fall ist dieses `__call__` das, was **FastAPI** verwendet, um nach zus
Und jetzt können wir `__init__` verwenden, um die Parameter der Instanz zu deklarieren, die wir zum `Parametrisieren` der Abhängigkeit verwenden können:
-=== "Python 3.9+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/dependencies/tutorial011_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/dependencies/tutorial011_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/dependencies/tutorial011.py!}
- ```
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[9] *}
In diesem Fall wird **FastAPI** `__init__` nie berühren oder sich darum kümmern, wir werden es direkt in unserem Code verwenden.
@@ -72,26 +34,7 @@ In diesem Fall wird **FastAPI** `__init__` nie berühren oder sich darum kümmer
Wir könnten eine Instanz dieser Klasse erstellen mit:
-=== "Python 3.9+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/dependencies/tutorial011_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="17"
- {!> ../../../docs_src/dependencies/tutorial011_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="16"
- {!> ../../../docs_src/dependencies/tutorial011.py!}
- ```
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[18] *}
Und auf diese Weise können wir unsere Abhängigkeit „parametrisieren“, die jetzt `"bar"` enthält, als das Attribut `checker.fixed_content`.
@@ -107,32 +50,16 @@ checker(q="somequery")
... und übergibt, was immer das als Wert dieser Abhängigkeit in unserer *Pfadoperation-Funktion* zurückgibt, als den Parameter `fixed_content_included`:
-=== "Python 3.9+"
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[22] *}
- ```Python hl_lines="22"
- {!> ../../../docs_src/dependencies/tutorial011_an_py39.py!}
- ```
+/// tip | Tipp
-=== "Python 3.8+"
+Das alles mag gekünstelt wirken. Und es ist möglicherweise noch nicht ganz klar, welchen Nutzen das hat.
- ```Python hl_lines="21"
- {!> ../../../docs_src/dependencies/tutorial011_an.py!}
- ```
+Diese Beispiele sind bewusst einfach gehalten, zeigen aber, wie alles funktioniert.
-=== "Python 3.8+ nicht annotiert"
+In den Kapiteln zum Thema Sicherheit gibt es Hilfsfunktionen, die auf die gleiche Weise implementiert werden.
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
+Wenn Sie das hier alles verstanden haben, wissen Sie bereits, wie diese Sicherheits-Hilfswerkzeuge unter der Haube funktionieren.
- ```Python hl_lines="20"
- {!> ../../../docs_src/dependencies/tutorial011.py!}
- ```
-
-!!! tip "Tipp"
- Das alles mag gekünstelt wirken. Und es ist möglicherweise noch nicht ganz klar, welchen Nutzen das hat.
-
- Diese Beispiele sind bewusst einfach gehalten, zeigen aber, wie alles funktioniert.
-
- In den Kapiteln zum Thema Sicherheit gibt es Hilfsfunktionen, die auf die gleiche Weise implementiert werden.
-
- Wenn Sie das hier alles verstanden haben, wissen Sie bereits, wie diese Sicherheits-Hilfswerkzeuge unter der Haube funktionieren.
+///
diff --git a/docs/de/docs/advanced/async-tests.md b/docs/de/docs/advanced/async-tests.md
index 2e2c22210..b82aadf00 100644
--- a/docs/de/docs/advanced/async-tests.md
+++ b/docs/de/docs/advanced/async-tests.md
@@ -32,15 +32,11 @@ Betrachten wir als einfaches Beispiel eine Dateistruktur ähnlich der in [Größ
Die Datei `main.py` hätte als Inhalt:
-```Python
-{!../../../docs_src/async_tests/main.py!}
-```
+{* ../../docs_src/async_tests/main.py *}
Die Datei `test_main.py` hätte die Tests für `main.py`, das könnte jetzt so aussehen:
-```Python
-{!../../../docs_src/async_tests/test_main.py!}
-```
+{* ../../docs_src/async_tests/test_main.py *}
## Es ausführen
@@ -60,18 +56,17 @@ $ pytest
Der Marker `@pytest.mark.anyio` teilt pytest mit, dass diese Testfunktion asynchron aufgerufen werden soll:
-```Python hl_lines="7"
-{!../../../docs_src/async_tests/test_main.py!}
-```
+{* ../../docs_src/async_tests/test_main.py hl[7] *}
-!!! tip "Tipp"
- Beachten Sie, dass die Testfunktion jetzt `async def` ist und nicht nur `def` wie zuvor, wenn Sie den `TestClient` verwenden.
+/// tip | Tipp
+
+Beachten Sie, dass die Testfunktion jetzt `async def` ist und nicht nur `def` wie zuvor, wenn Sie den `TestClient` verwenden.
+
+///
Dann können wir einen `AsyncClient` mit der App erstellen und mit `await` asynchrone Requests an ihn senden.
-```Python hl_lines="9-10"
-{!../../../docs_src/async_tests/test_main.py!}
-```
+{* ../../docs_src/async_tests/test_main.py hl[9:12] *}
Das ist das Äquivalent zu:
@@ -81,15 +76,24 @@ response = client.get('/')
... welches wir verwendet haben, um unsere Requests mit dem `TestClient` zu machen.
-!!! tip "Tipp"
- Beachten Sie, dass wir async/await mit dem neuen `AsyncClient` verwenden – der Request ist asynchron.
+/// tip | Tipp
-!!! warning "Achtung"
- Falls Ihre Anwendung auf Lifespan-Events angewiesen ist, der `AsyncClient` löst diese Events nicht aus. Um sicherzustellen, dass sie ausgelöst werden, verwenden Sie `LifespanManager` von florimondmanca/asgi-lifespan.
+Beachten Sie, dass wir async/await mit dem neuen `AsyncClient` verwenden – der Request ist asynchron.
+
+///
+
+/// warning | Achtung
+
+Falls Ihre Anwendung auf Lifespan-Events angewiesen ist, der `AsyncClient` löst diese Events nicht aus. Um sicherzustellen, dass sie ausgelöst werden, verwenden Sie `LifespanManager` von florimondmanca/asgi-lifespan.
+
+///
## Andere asynchrone Funktionsaufrufe
Da die Testfunktion jetzt asynchron ist, können Sie in Ihren Tests neben dem Senden von Requests an Ihre FastAPI-Anwendung jetzt auch andere `async`hrone Funktionen aufrufen (und `await`en), genau so, wie Sie diese an anderer Stelle in Ihrem Code aufrufen würden.
-!!! tip "Tipp"
- Wenn Sie einen `RuntimeError: Task attached to a different loop` erhalten, wenn Sie asynchrone Funktionsaufrufe in Ihre Tests integrieren (z. B. bei Verwendung von MongoDBs MotorClient), dann denken Sie daran, Objekte zu instanziieren, die einen Event Loop nur innerhalb asynchroner Funktionen benötigen, z. B. einen `@app.on_event("startup")`-Callback.
+/// tip | Tipp
+
+Wenn Sie einen `RuntimeError: Task attached to a different loop` erhalten, wenn Sie asynchrone Funktionsaufrufe in Ihre Tests integrieren (z. B. bei Verwendung von MongoDBs MotorClient), dann denken Sie daran, Objekte zu instanziieren, die einen Event Loop nur innerhalb asynchroner Funktionen benötigen, z. B. einen `@app.on_event("startup")`-Callback.
+
+///
diff --git a/docs/de/docs/advanced/behind-a-proxy.md b/docs/de/docs/advanced/behind-a-proxy.md
index ad0a92e28..9e2282280 100644
--- a/docs/de/docs/advanced/behind-a-proxy.md
+++ b/docs/de/docs/advanced/behind-a-proxy.md
@@ -18,9 +18,7 @@ In diesem Fall würde der ursprüngliche Pfad `/app` tatsächlich unter `/api/v1
Auch wenn Ihr gesamter Code unter der Annahme geschrieben ist, dass es nur `/app` gibt.
-```Python hl_lines="6"
-{!../../../docs_src/behind_a_proxy/tutorial001.py!}
-```
+{* ../../docs_src/behind_a_proxy/tutorial001.py hl[6] *}
Und der Proxy würde das **Pfadpräfix** on-the-fly **"entfernen**", bevor er die Anfrage an Uvicorn übermittelt, dafür sorgend, dass Ihre Anwendung davon überzeugt ist, dass sie unter `/app` bereitgestellt wird, sodass Sie nicht Ihren gesamten Code dahingehend aktualisieren müssen, das Präfix `/api/v1` zu verwenden.
@@ -43,8 +41,11 @@ browser --> proxy
proxy --> server
```
-!!! tip "Tipp"
- Die IP `0.0.0.0` wird üblicherweise verwendet, um anzudeuten, dass das Programm alle auf diesem Computer/Server verfügbaren IPs abhört.
+/// tip | Tipp
+
+Die IP `0.0.0.0` wird üblicherweise verwendet, um anzudeuten, dass das Programm alle auf diesem Computer/Server verfügbaren IPs abhört.
+
+///
Die Benutzeroberfläche der Dokumentation würde benötigen, dass das OpenAPI-Schema deklariert, dass sich dieser API-`server` unter `/api/v1` (hinter dem Proxy) befindet. Zum Beispiel:
@@ -81,10 +82,13 @@ $ uvicorn main:app --root-path /api/v1
Falls Sie Hypercorn verwenden, das hat auch die Option `--root-path`.
-!!! note "Technische Details"
- Die ASGI-Spezifikation definiert einen `root_path` für diesen Anwendungsfall.
+/// note | Technische Details
- Und die Kommandozeilenoption `--root-path` stellt diesen `root_path` bereit.
+Die ASGI-Spezifikation definiert einen `root_path` für diesen Anwendungsfall.
+
+Und die Kommandozeilenoption `--root-path` stellt diesen `root_path` bereit.
+
+///
### Überprüfen des aktuellen `root_path`
@@ -92,9 +96,7 @@ Sie können den aktuellen `root_path` abrufen, der von Ihrer Anwendung für jede
Hier fügen wir ihn, nur zu Demonstrationszwecken, in die Nachricht ein.
-```Python hl_lines="8"
-{!../../../docs_src/behind_a_proxy/tutorial001.py!}
-```
+{* ../../docs_src/behind_a_proxy/tutorial001.py hl[8] *}
Wenn Sie Uvicorn dann starten mit:
@@ -121,9 +123,7 @@ wäre die Response etwa:
Falls Sie keine Möglichkeit haben, eine Kommandozeilenoption wie `--root-path` oder ähnlich zu übergeben, können Sie als Alternative beim Erstellen Ihrer FastAPI-Anwendung den Parameter `root_path` setzen:
-```Python hl_lines="3"
-{!../../../docs_src/behind_a_proxy/tutorial002.py!}
-```
+{* ../../docs_src/behind_a_proxy/tutorial002.py hl[3] *}
Die Übergabe des `root_path` an `FastAPI` wäre das Äquivalent zur Übergabe der `--root-path`-Kommandozeilenoption an Uvicorn oder Hypercorn.
@@ -172,8 +172,11 @@ Dann erstellen Sie eine Datei `traefik.toml` mit:
Dadurch wird Traefik angewiesen, Port 9999 abzuhören und eine andere Datei `routes.toml` zu verwenden.
-!!! tip "Tipp"
- Wir verwenden Port 9999 anstelle des Standard-HTTP-Ports 80, damit Sie ihn nicht mit Administratorrechten (`sudo`) ausführen müssen.
+/// tip | Tipp
+
+Wir verwenden Port 9999 anstelle des Standard-HTTP-Ports 80, damit Sie ihn nicht mit Administratorrechten (`sudo`) ausführen müssen.
+
+///
Erstellen Sie nun die andere Datei `routes.toml`:
@@ -239,8 +242,11 @@ Wenn Sie nun zur URL mit dem Port für Uvicorn gehen: http://127.0.0.1:9999/api/v1/app.
@@ -283,8 +289,11 @@ Dies liegt daran, dass FastAPI diesen `root_path` verwendet, um den Default-`ser
## Zusätzliche Server
-!!! warning "Achtung"
- Dies ist ein fortgeschrittener Anwendungsfall. Überspringen Sie das gerne.
+/// warning | Achtung
+
+Dies ist ein fortgeschrittener Anwendungsfall. Überspringen Sie das gerne.
+
+///
Standardmäßig erstellt **FastAPI** einen `server` im OpenAPI-Schema mit der URL für den `root_path`.
@@ -294,9 +303,7 @@ Wenn Sie eine benutzerdefinierte Liste von Servern (`servers`) übergeben und es
Zum Beispiel:
-```Python hl_lines="4-7"
-{!../../../docs_src/behind_a_proxy/tutorial003.py!}
-```
+{* ../../docs_src/behind_a_proxy/tutorial003.py hl[4:7] *}
Erzeugt ein OpenAPI-Schema, wie:
@@ -323,23 +330,27 @@ Erzeugt ein OpenAPI-Schema, wie:
}
```
-!!! tip "Tipp"
- Beachten Sie den automatisch generierten Server mit dem `URL`-Wert `/api/v1`, welcher vom `root_path` stammt.
+/// tip | Tipp
+
+Beachten Sie den automatisch generierten Server mit dem `URL`-Wert `/api/v1`, welcher vom `root_path` stammt.
+
+///
In der Dokumentationsoberfläche unter http://127.0.0.1:9999/api/v1/docs würde es so aussehen:
-!!! tip "Tipp"
- Die Dokumentationsoberfläche interagiert mit dem von Ihnen ausgewählten Server.
+/// tip | Tipp
+
+Die Dokumentationsoberfläche interagiert mit dem von Ihnen ausgewählten Server.
+
+///
### Den automatischen Server von `root_path` deaktivieren
Wenn Sie nicht möchten, dass **FastAPI** einen automatischen Server inkludiert, welcher `root_path` verwendet, können Sie den Parameter `root_path_in_servers=False` verwenden:
-```Python hl_lines="9"
-{!../../../docs_src/behind_a_proxy/tutorial004.py!}
-```
+{* ../../docs_src/behind_a_proxy/tutorial004.py hl[9] *}
Dann wird er nicht in das OpenAPI-Schema aufgenommen.
diff --git a/docs/de/docs/advanced/custom-response.md b/docs/de/docs/advanced/custom-response.md
index 68c037ad7..43cb55e04 100644
--- a/docs/de/docs/advanced/custom-response.md
+++ b/docs/de/docs/advanced/custom-response.md
@@ -12,8 +12,11 @@ Der Inhalt, den Sie von Ihrer *Pfadoperation-Funktion* zurückgeben, wird in die
Und wenn diese `Response` einen JSON-Medientyp (`application/json`) hat, wie es bei `JSONResponse` und `UJSONResponse` der Fall ist, werden die von Ihnen zurückgegebenen Daten automatisch mit jedem Pydantic `response_model` konvertiert (und gefiltert), das Sie im *Pfadoperation-Dekorator* deklariert haben.
-!!! note "Hinweis"
- Wenn Sie eine Response-Klasse ohne Medientyp verwenden, erwartet FastAPI, dass Ihre Response keinen Inhalt hat, und dokumentiert daher das Format der Response nicht in deren generierter OpenAPI-Dokumentation.
+/// note | Hinweis
+
+Wenn Sie eine Response-Klasse ohne Medientyp verwenden, erwartet FastAPI, dass Ihre Response keinen Inhalt hat, und dokumentiert daher das Format der Response nicht in deren generierter OpenAPI-Dokumentation.
+
+///
## `ORJSONResponse` verwenden
@@ -27,19 +30,23 @@ Das liegt daran, dass FastAPI standardmäßig jedes enthaltene Element überprü
Wenn Sie jedoch sicher sind, dass der von Ihnen zurückgegebene Inhalt **mit JSON serialisierbar** ist, können Sie ihn direkt an die Response-Klasse übergeben und die zusätzliche Arbeit vermeiden, die FastAPI hätte, indem es Ihren zurückgegebenen Inhalt durch den `jsonable_encoder` leitet, bevor es ihn an die Response-Klasse übergibt.
-```Python hl_lines="2 7"
-{!../../../docs_src/custom_response/tutorial001b.py!}
-```
+{* ../../docs_src/custom_response/tutorial001b.py hl[2,7] *}
-!!! info
- Der Parameter `response_class` wird auch verwendet, um den „Medientyp“ der Response zu definieren.
+/// info
- In diesem Fall wird der HTTP-Header `Content-Type` auf `application/json` gesetzt.
+Der Parameter `response_class` wird auch verwendet, um den „Medientyp“ der Response zu definieren.
- Und er wird als solcher in OpenAPI dokumentiert.
+In diesem Fall wird der HTTP-Header `Content-Type` auf `application/json` gesetzt.
-!!! tip "Tipp"
- Die `ORJSONResponse` ist derzeit nur in FastAPI verfügbar, nicht in Starlette.
+Und er wird als solcher in OpenAPI dokumentiert.
+
+///
+
+/// tip | Tipp
+
+Die `ORJSONResponse` ist derzeit nur in FastAPI verfügbar, nicht in Starlette.
+
+///
## HTML-Response
@@ -48,16 +55,17 @@ Um eine Response mit HTML direkt von **FastAPI** zurückzugeben, verwenden Sie `
* Importieren Sie `HTMLResponse`.
* Übergeben Sie `HTMLResponse` als den Parameter `response_class` Ihres *Pfadoperation-Dekorators*.
-```Python hl_lines="2 7"
-{!../../../docs_src/custom_response/tutorial002.py!}
-```
+{* ../../docs_src/custom_response/tutorial002.py hl[2,7] *}
-!!! info
- Der Parameter `response_class` wird auch verwendet, um den „Medientyp“ der Response zu definieren.
+/// info
- In diesem Fall wird der HTTP-Header `Content-Type` auf `text/html` gesetzt.
+Der Parameter `response_class` wird auch verwendet, um den „Medientyp“ der Response zu definieren.
- Und er wird als solcher in OpenAPI dokumentiert.
+In diesem Fall wird der HTTP-Header `Content-Type` auf `text/html` gesetzt.
+
+Und er wird als solcher in OpenAPI dokumentiert.
+
+///
### Eine `Response` zurückgeben
@@ -65,15 +73,19 @@ Wie in [Eine Response direkt zurückgeben](response-directly.md){.internal-link
Das gleiche Beispiel von oben, das eine `HTMLResponse` zurückgibt, könnte so aussehen:
-```Python hl_lines="2 7 19"
-{!../../../docs_src/custom_response/tutorial003.py!}
-```
+{* ../../docs_src/custom_response/tutorial003.py hl[2,7,19] *}
-!!! warning "Achtung"
- Eine `Response`, die direkt von Ihrer *Pfadoperation-Funktion* zurückgegeben wird, wird in OpenAPI nicht dokumentiert (zum Beispiel wird der `Content-Type` nicht dokumentiert) und ist in der automatischen interaktiven Dokumentation nicht sichtbar.
+/// warning | Achtung
-!!! info
- Natürlich stammen der eigentliche `Content-Type`-Header, der Statuscode, usw., aus dem `Response`-Objekt, das Sie zurückgegeben haben.
+Eine `Response`, die direkt von Ihrer *Pfadoperation-Funktion* zurückgegeben wird, wird in OpenAPI nicht dokumentiert (zum Beispiel wird der `Content-Type` nicht dokumentiert) und ist in der automatischen interaktiven Dokumentation nicht sichtbar.
+
+///
+
+/// info
+
+Natürlich stammen der eigentliche `Content-Type`-Header, der Statuscode, usw., aus dem `Response`-Objekt, das Sie zurückgegeben haben.
+
+///
### In OpenAPI dokumentieren und `Response` überschreiben
@@ -85,9 +97,7 @@ Die `response_class` wird dann nur zur Dokumentation der OpenAPI-Pfadoperation*
Es könnte zum Beispiel so etwas sein:
-```Python hl_lines="7 21 23"
-{!../../../docs_src/custom_response/tutorial004.py!}
-```
+{* ../../docs_src/custom_response/tutorial004.py hl[7,21,23] *}
In diesem Beispiel generiert die Funktion `generate_html_response()` bereits eine `Response` und gibt sie zurück, anstatt das HTML in einem `str` zurückzugeben.
@@ -103,10 +113,13 @@ Hier sind einige der verfügbaren Responses.
Bedenken Sie, dass Sie `Response` verwenden können, um alles andere zurückzugeben, oder sogar eine benutzerdefinierte Unterklasse zu erstellen.
-!!! note "Technische Details"
- Sie können auch `from starlette.responses import HTMLResponse` verwenden.
+/// note | Technische Details
- **FastAPI** bietet dieselben `starlette.responses` auch via `fastapi.responses` an, als Annehmlichkeit für Sie, den Entwickler. Die meisten verfügbaren Responses kommen aber direkt von Starlette.
+Sie können auch `from starlette.responses import HTMLResponse` verwenden.
+
+**FastAPI** bietet dieselben `starlette.responses` auch via `fastapi.responses` an, als Annehmlichkeit für Sie, den Entwickler. Die meisten verfügbaren Responses kommen aber direkt von Starlette.
+
+///
### `Response`
@@ -123,9 +136,7 @@ Sie akzeptiert die folgenden Parameter:
FastAPI (eigentlich Starlette) fügt automatisch einen Content-Length-Header ein. Außerdem wird es einen Content-Type-Header einfügen, der auf dem media_type basiert, und für Texttypen einen Zeichensatz (charset) anfügen.
-```Python hl_lines="1 18"
-{!../../../docs_src/response_directly/tutorial002.py!}
-```
+{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
### `HTMLResponse`
@@ -135,9 +146,7 @@ Nimmt Text oder Bytes entgegen und gibt eine HTML-Response zurück, wie Sie oben
Nimmt Text oder Bytes entgegen und gibt eine Plain-Text-Response zurück.
-```Python hl_lines="2 7 9"
-{!../../../docs_src/custom_response/tutorial005.py!}
-```
+{* ../../docs_src/custom_response/tutorial005.py hl[2,7,9] *}
### `JSONResponse`
@@ -153,15 +162,19 @@ Eine schnelle alternative JSON-Response mit `ujson`.
-!!! warning "Achtung"
- `ujson` ist bei der Behandlung einiger Sonderfälle weniger sorgfältig als Pythons eingebaute Implementierung.
+/// warning | Achtung
-```Python hl_lines="2 7"
-{!../../../docs_src/custom_response/tutorial001.py!}
-```
+`ujson` ist bei der Behandlung einiger Sonderfälle weniger sorgfältig als Pythons eingebaute Implementierung.
-!!! tip "Tipp"
- Möglicherweise ist `ORJSONResponse` eine schnellere Alternative.
+///
+
+{* ../../docs_src/custom_response/tutorial001.py hl[2,7] *}
+
+/// tip | Tipp
+
+Möglicherweise ist `ORJSONResponse` eine schnellere Alternative.
+
+///
### `RedirectResponse`
@@ -169,18 +182,14 @@ Gibt eine HTTP-Weiterleitung (HTTP-Redirect) zurück. Verwendet standardmäßig
Sie können eine `RedirectResponse` direkt zurückgeben:
-```Python hl_lines="2 9"
-{!../../../docs_src/custom_response/tutorial006.py!}
-```
+{* ../../docs_src/custom_response/tutorial006.py hl[2,9] *}
---
Oder Sie können sie im Parameter `response_class` verwenden:
-```Python hl_lines="2 7 9"
-{!../../../docs_src/custom_response/tutorial006b.py!}
-```
+{* ../../docs_src/custom_response/tutorial006b.py hl[2,7,9] *}
Wenn Sie das tun, können Sie die URL direkt von Ihrer *Pfadoperation*-Funktion zurückgeben.
@@ -190,17 +199,13 @@ In diesem Fall ist der verwendete `status_code` der Standardcode für die `Redir
Sie können den Parameter `status_code` auch in Kombination mit dem Parameter `response_class` verwenden:
-```Python hl_lines="2 7 9"
-{!../../../docs_src/custom_response/tutorial006c.py!}
-```
+{* ../../docs_src/custom_response/tutorial006c.py hl[2,7,9] *}
### `StreamingResponse`
Nimmt einen asynchronen Generator oder einen normalen Generator/Iterator und streamt den Responsebody.
-```Python hl_lines="2 14"
-{!../../../docs_src/custom_response/tutorial007.py!}
-```
+{* ../../docs_src/custom_response/tutorial007.py hl[2,14] *}
#### Verwendung von `StreamingResponse` mit dateiähnlichen Objekten
@@ -211,7 +216,7 @@ Auf diese Weise müssen Sie nicht alles zuerst in den Arbeitsspeicher lesen und
Das umfasst viele Bibliotheken zur Interaktion mit Cloud-Speicher, Videoverarbeitung und anderen.
```{ .python .annotate hl_lines="2 10-12 14" }
-{!../../../docs_src/custom_response/tutorial008.py!}
+{!../../docs_src/custom_response/tutorial008.py!}
```
1. Das ist die Generatorfunktion. Es handelt sich um eine „Generatorfunktion“, da sie `yield`-Anweisungen enthält.
@@ -222,8 +227,11 @@ Das umfasst viele Bibliotheken zur Interaktion mit Cloud-Speicher, Videoverarbei
Auf diese Weise können wir das Ganze in einen `with`-Block einfügen und so sicherstellen, dass das dateiartige Objekt nach Abschluss geschlossen wird.
-!!! tip "Tipp"
- Beachten Sie, dass wir, da wir Standard-`open()` verwenden, welches `async` und `await` nicht unterstützt, hier die Pfadoperation mit normalen `def` deklarieren.
+/// tip | Tipp
+
+Beachten Sie, dass wir, da wir Standard-`open()` verwenden, welches `async` und `await` nicht unterstützt, hier die Pfadoperation mit normalen `def` deklarieren.
+
+///
### `FileResponse`
@@ -238,15 +246,11 @@ Nimmt zur Instanziierung einen anderen Satz von Argumenten entgegen als die ande
Datei-Responses enthalten die entsprechenden `Content-Length`-, `Last-Modified`- und `ETag`-Header.
-```Python hl_lines="2 10"
-{!../../../docs_src/custom_response/tutorial009.py!}
-```
+{* ../../docs_src/custom_response/tutorial009.py hl[2,10] *}
Sie können auch den Parameter `response_class` verwenden:
-```Python hl_lines="2 8 10"
-{!../../../docs_src/custom_response/tutorial009b.py!}
-```
+{* ../../docs_src/custom_response/tutorial009b.py hl[2,8,10] *}
In diesem Fall können Sie den Dateipfad direkt von Ihrer *Pfadoperation*-Funktion zurückgeben.
@@ -260,9 +264,7 @@ Sie möchten etwa, dass Ihre Response eingerücktes und formatiertes JSON zurüc
Sie könnten eine `CustomORJSONResponse` erstellen. Das Wichtigste, was Sie tun müssen, ist, eine `Response.render(content)`-Methode zu erstellen, die den Inhalt als `bytes` zurückgibt:
-```Python hl_lines="9-14 17"
-{!../../../docs_src/custom_response/tutorial009c.py!}
-```
+{* ../../docs_src/custom_response/tutorial009c.py hl[9:14,17] *}
Statt:
@@ -288,12 +290,13 @@ Der Parameter, der das definiert, ist `default_response_class`.
Im folgenden Beispiel verwendet **FastAPI** standardmäßig `ORJSONResponse` in allen *Pfadoperationen*, anstelle von `JSONResponse`.
-```Python hl_lines="2 4"
-{!../../../docs_src/custom_response/tutorial010.py!}
-```
+{* ../../docs_src/custom_response/tutorial010.py hl[2,4] *}
-!!! tip "Tipp"
- Sie können dennoch weiterhin `response_class` in *Pfadoperationen* überschreiben, wie bisher.
+/// tip | Tipp
+
+Sie können dennoch weiterhin `response_class` in *Pfadoperationen* überschreiben, wie bisher.
+
+///
## Zusätzliche Dokumentation
diff --git a/docs/de/docs/advanced/dataclasses.md b/docs/de/docs/advanced/dataclasses.md
index c78a6d3dd..8e537c639 100644
--- a/docs/de/docs/advanced/dataclasses.md
+++ b/docs/de/docs/advanced/dataclasses.md
@@ -4,9 +4,7 @@ FastAPI basiert auf **Pydantic** und ich habe Ihnen gezeigt, wie Sie Pydantic-Mo
Aber FastAPI unterstützt auf die gleiche Weise auch die Verwendung von `dataclasses`:
-```Python hl_lines="1 7-12 19-20"
-{!../../../docs_src/dataclasses/tutorial001.py!}
-```
+{* ../../docs_src/dataclasses/tutorial001.py hl[1,7:12,19:20] *}
Das ist dank **Pydantic** ebenfalls möglich, da es `dataclasses` intern unterstützt.
@@ -20,20 +18,21 @@ Und natürlich wird das gleiche unterstützt:
Das funktioniert genauso wie mit Pydantic-Modellen. Und tatsächlich wird es unter der Haube mittels Pydantic auf die gleiche Weise bewerkstelligt.
-!!! info
- Bedenken Sie, dass Datenklassen nicht alles können, was Pydantic-Modelle können.
+/// info
- Daher müssen Sie möglicherweise weiterhin Pydantic-Modelle verwenden.
+Bedenken Sie, dass Datenklassen nicht alles können, was Pydantic-Modelle können.
- Wenn Sie jedoch eine Menge Datenklassen herumliegen haben, ist dies ein guter Trick, um sie für eine Web-API mithilfe von FastAPI zu verwenden. 🤓
+Daher müssen Sie möglicherweise weiterhin Pydantic-Modelle verwenden.
+
+Wenn Sie jedoch eine Menge Datenklassen herumliegen haben, ist dies ein guter Trick, um sie für eine Web-API mithilfe von FastAPI zu verwenden. 🤓
+
+///
## Datenklassen als `response_model`
Sie können `dataclasses` auch im Parameter `response_model` verwenden:
-```Python hl_lines="1 7-13 19"
-{!../../../docs_src/dataclasses/tutorial002.py!}
-```
+{* ../../docs_src/dataclasses/tutorial002.py hl[1,7:13,19] *}
Die Datenklasse wird automatisch in eine Pydantic-Datenklasse konvertiert.
@@ -49,9 +48,7 @@ In einigen Fällen müssen Sie möglicherweise immer noch Pydantics Version von
In diesem Fall können Sie einfach die Standard-`dataclasses` durch `pydantic.dataclasses` ersetzen, was einen direkten Ersatz darstellt:
-```{ .python .annotate hl_lines="1 5 8-11 14-17 23-25 28" }
-{!../../../docs_src/dataclasses/tutorial003.py!}
-```
+{* ../../docs_src/dataclasses/tutorial003.py hl[1,5,8:11,14:17,23:25,28] *}
1. Wir importieren `field` weiterhin von Standard-`dataclasses`.
diff --git a/docs/de/docs/advanced/events.md b/docs/de/docs/advanced/events.md
index e29f61ab9..65fc9e484 100644
--- a/docs/de/docs/advanced/events.md
+++ b/docs/de/docs/advanced/events.md
@@ -30,26 +30,25 @@ Beginnen wir mit einem Beispiel und sehen es uns dann im Detail an.
Wir erstellen eine asynchrone Funktion `lifespan()` mit `yield` wie folgt:
-```Python hl_lines="16 19"
-{!../../../docs_src/events/tutorial003.py!}
-```
+{* ../../docs_src/events/tutorial003.py hl[16,19] *}
Hier simulieren wir das langsame *Hochfahren*, das Laden des Modells, indem wir die (Fake-)Modellfunktion vor dem `yield` in das Dictionary mit Modellen für maschinelles Lernen einfügen. Dieser Code wird ausgeführt, **bevor** die Anwendung **beginnt, Requests entgegenzunehmen**, während des *Hochfahrens*.
Und dann, direkt nach dem `yield`, entladen wir das Modell. Dieser Code wird unmittelbar vor dem *Herunterfahren* ausgeführt, **nachdem** die Anwendung **die Bearbeitung von Requests abgeschlossen hat**. Dadurch könnten beispielsweise Ressourcen wie Arbeitsspeicher oder eine GPU freigegeben werden.
-!!! tip "Tipp"
- Das *Herunterfahren* würde erfolgen, wenn Sie die Anwendung **stoppen**.
+/// tip | Tipp
- Möglicherweise müssen Sie eine neue Version starten, oder Sie haben es einfach satt, sie auszuführen. 🤷
+Das *Herunterfahren* würde erfolgen, wenn Sie die Anwendung **stoppen**.
+
+Möglicherweise müssen Sie eine neue Version starten, oder Sie haben es einfach satt, sie auszuführen. 🤷
+
+///
### Lifespan-Funktion
Das Erste, was auffällt, ist, dass wir eine asynchrone Funktion mit `yield` definieren. Das ist sehr ähnlich zu Abhängigkeiten mit `yield`.
-```Python hl_lines="14-19"
-{!../../../docs_src/events/tutorial003.py!}
-```
+{* ../../docs_src/events/tutorial003.py hl[14:19] *}
Der erste Teil der Funktion, vor dem `yield`, wird ausgeführt **bevor** die Anwendung startet.
@@ -61,9 +60,7 @@ Wie Sie sehen, ist die Funktion mit einem `@asynccontextmanager` versehen.
Dadurch wird die Funktion in einen sogenannten „**asynchronen Kontextmanager**“ umgewandelt.
-```Python hl_lines="1 13"
-{!../../../docs_src/events/tutorial003.py!}
-```
+{* ../../docs_src/events/tutorial003.py hl[1,13] *}
Ein **Kontextmanager** in Python ist etwas, das Sie in einer `with`-Anweisung verwenden können, zum Beispiel kann `open()` als Kontextmanager verwendet werden:
@@ -85,16 +82,17 @@ In unserem obigen Codebeispiel verwenden wir ihn nicht direkt, sondern übergebe
Der Parameter `lifespan` der `FastAPI`-App benötigt einen **asynchronen Kontextmanager**, wir können ihm also unseren neuen asynchronen Kontextmanager `lifespan` übergeben.
-```Python hl_lines="22"
-{!../../../docs_src/events/tutorial003.py!}
-```
+{* ../../docs_src/events/tutorial003.py hl[22] *}
## Alternative Events (deprecated)
-!!! warning "Achtung"
- Der empfohlene Weg, das *Hochfahren* und *Herunterfahren* zu handhaben, ist die Verwendung des `lifespan`-Parameters der `FastAPI`-App, wie oben beschrieben. Wenn Sie einen `lifespan`-Parameter übergeben, werden die `startup`- und `shutdown`-Eventhandler nicht mehr aufgerufen. Es ist entweder alles `lifespan` oder alles Events, nicht beides.
+/// warning | Achtung
- Sie können diesen Teil wahrscheinlich überspringen.
+Der empfohlene Weg, das *Hochfahren* und *Herunterfahren* zu handhaben, ist die Verwendung des `lifespan`-Parameters der `FastAPI`-App, wie oben beschrieben. Wenn Sie einen `lifespan`-Parameter übergeben, werden die `startup`- und `shutdown`-Eventhandler nicht mehr aufgerufen. Es ist entweder alles `lifespan` oder alles Events, nicht beides.
+
+Sie können diesen Teil wahrscheinlich überspringen.
+
+///
Es gibt eine alternative Möglichkeit, diese Logik zu definieren, sodass sie beim *Hochfahren* und beim *Herunterfahren* ausgeführt wird.
@@ -106,9 +104,7 @@ Diese Funktionen können mit `async def` oder normalem `def` deklariert werden.
Um eine Funktion hinzuzufügen, die vor dem Start der Anwendung ausgeführt werden soll, deklarieren Sie diese mit dem Event `startup`:
-```Python hl_lines="8"
-{!../../../docs_src/events/tutorial001.py!}
-```
+{* ../../docs_src/events/tutorial001.py hl[8] *}
In diesem Fall initialisiert die Eventhandler-Funktion `startup` die „Datenbank“ der Items (nur ein `dict`) mit einigen Werten.
@@ -120,23 +116,27 @@ Und Ihre Anwendung empfängt erst dann Anfragen, wenn alle `startup`-Eventhandle
Um eine Funktion hinzuzufügen, die beim Herunterfahren der Anwendung ausgeführt werden soll, deklarieren Sie sie mit dem Event `shutdown`:
-```Python hl_lines="6"
-{!../../../docs_src/events/tutorial002.py!}
-```
+{* ../../docs_src/events/tutorial002.py hl[6] *}
Hier schreibt die `shutdown`-Eventhandler-Funktion eine Textzeile `"Application shutdown"` in eine Datei `log.txt`.
-!!! info
- In der Funktion `open()` bedeutet `mode="a"` „append“ („anhängen“), sodass die Zeile nach dem, was sich in dieser Datei befindet, hinzugefügt wird, ohne den vorherigen Inhalt zu überschreiben.
+/// info
-!!! tip "Tipp"
- Beachten Sie, dass wir in diesem Fall eine Standard-Python-Funktion `open()` verwenden, die mit einer Datei interagiert.
+In der Funktion `open()` bedeutet `mode="a"` „append“ („anhängen“), sodass die Zeile nach dem, was sich in dieser Datei befindet, hinzugefügt wird, ohne den vorherigen Inhalt zu überschreiben.
- Es handelt sich also um I/O (Input/Output), welches „Warten“ erfordert, bis Dinge auf die Festplatte geschrieben werden.
+///
- Aber `open()` verwendet nicht `async` und `await`.
+/// tip | Tipp
- Daher deklarieren wir die Eventhandler-Funktion mit Standard-`def` statt mit `async def`.
+Beachten Sie, dass wir in diesem Fall eine Standard-Python-Funktion `open()` verwenden, die mit einer Datei interagiert.
+
+Es handelt sich also um I/O (Input/Output), welches „Warten“ erfordert, bis Dinge auf die Festplatte geschrieben werden.
+
+Aber `open()` verwendet nicht `async` und `await`.
+
+Daher deklarieren wir die Eventhandler-Funktion mit Standard-`def` statt mit `async def`.
+
+///
### `startup` und `shutdown` zusammen
@@ -152,10 +152,13 @@ Nur ein technisches Detail für die neugierigen Nerds. 🤓
In der technischen ASGI-Spezifikation ist dies Teil des Lifespan Protokolls und definiert Events namens `startup` und `shutdown`.
-!!! info
- Weitere Informationen zu Starlettes `lifespan`-Handlern finden Sie in Starlettes Lifespan-Dokumentation.
+/// info
- Einschließlich, wie man Lifespan-Zustand handhabt, der in anderen Bereichen Ihres Codes verwendet werden kann.
+Weitere Informationen zu Starlettes `lifespan`-Handlern finden Sie in Starlettes Lifespan-Dokumentation.
+
+Einschließlich, wie man Lifespan-Zustand handhabt, der in anderen Bereichen Ihres Codes verwendet werden kann.
+
+///
## Unteranwendungen
diff --git a/docs/de/docs/advanced/generate-clients.md b/docs/de/docs/advanced/generate-clients.md
index d69437954..f491d29af 100644
--- a/docs/de/docs/advanced/generate-clients.md
+++ b/docs/de/docs/advanced/generate-clients.md
@@ -20,7 +20,7 @@ Einige von diesen ✨ [**sponsern FastAPI**](../help-fastapi.md#den-autor-sponse
Und es zeigt deren wahres Engagement für FastAPI und seine **Community** (Sie), da diese Ihnen nicht nur einen **guten Service** bieten möchten, sondern auch sicherstellen möchten, dass Sie über ein **gutes und gesundes Framework** verfügen, FastAPI. 🙇
-Beispielsweise könnten Sie Speakeasy ausprobieren.
+Beispielsweise könnten Sie Speakeasy ausprobieren.
Es gibt auch mehrere andere Unternehmen, welche ähnliche Dienste anbieten und die Sie online suchen und finden können. 🤓
@@ -28,17 +28,7 @@ Es gibt auch mehrere andere Unternehmen, welche ähnliche Dienste anbieten und d
Beginnen wir mit einer einfachen FastAPI-Anwendung:
-=== "Python 3.9+"
-
- ```Python hl_lines="7-9 12-13 16-17 21"
- {!> ../../../docs_src/generate_clients/tutorial001_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9-11 14-15 18 19 23"
- {!> ../../../docs_src/generate_clients/tutorial001.py!}
- ```
+{* ../../docs_src/generate_clients/tutorial001_py39.py hl[7:9,12:13,16:17,21] *}
Beachten Sie, dass die *Pfadoperationen* die Modelle definieren, welche diese für die Request- und Response-Payload verwenden, indem sie die Modelle `Item` und `ResponseMessage` verwenden.
@@ -123,8 +113,11 @@ Sie erhalten außerdem automatische Vervollständigung für die zu sendende Payl
-!!! tip "Tipp"
- Beachten Sie die automatische Vervollständigung für `name` und `price`, welche in der FastAPI-Anwendung im `Item`-Modell definiert wurden.
+/// tip | Tipp
+
+Beachten Sie die automatische Vervollständigung für `name` und `price`, welche in der FastAPI-Anwendung im `Item`-Modell definiert wurden.
+
+///
Sie erhalten Inline-Fehlerberichte für die von Ihnen gesendeten Daten:
@@ -140,17 +133,7 @@ In vielen Fällen wird Ihre FastAPI-Anwendung größer sein und Sie werden wahrs
Beispielsweise könnten Sie einen Abschnitt für **Items (Artikel)** und einen weiteren Abschnitt für **Users (Benutzer)** haben, und diese könnten durch Tags getrennt sein:
-=== "Python 3.9+"
-
- ```Python hl_lines="21 26 34"
- {!> ../../../docs_src/generate_clients/tutorial002_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="23 28 36"
- {!> ../../../docs_src/generate_clients/tutorial002.py!}
- ```
+{* ../../docs_src/generate_clients/tutorial002_py39.py hl[21,26,34] *}
### Einen TypeScript-Client mit Tags generieren
@@ -197,17 +180,7 @@ Hier verwendet sie beispielsweise den ersten Tag (Sie werden wahrscheinlich nur
Anschließend können Sie diese benutzerdefinierte Funktion als Parameter `generate_unique_id_function` an **FastAPI** übergeben:
-=== "Python 3.9+"
-
- ```Python hl_lines="6-7 10"
- {!> ../../../docs_src/generate_clients/tutorial003_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="8-9 12"
- {!> ../../../docs_src/generate_clients/tutorial003.py!}
- ```
+{* ../../docs_src/generate_clients/tutorial003_py39.py hl[6:7,10] *}
### Einen TypeScript-Client mit benutzerdefinierten Operation-IDs generieren
@@ -229,17 +202,15 @@ Aber für den generierten Client könnten wir die OpenAPI-Operation-IDs direkt v
Wir könnten das OpenAPI-JSON in eine Datei `openapi.json` herunterladen und dann mit einem Skript wie dem folgenden **den vorangestellten Tag entfernen**:
-=== "Python"
+{* ../../docs_src/generate_clients/tutorial004.py *}
- ```Python
- {!> ../../../docs_src/generate_clients/tutorial004.py!}
- ```
+//// tab | Node.js
-=== "Node.js"
+```Javascript
+{!> ../../docs_src/generate_clients/tutorial004.js!}
+```
- ```Javascript
- {!> ../../../docs_src/generate_clients/tutorial004.js!}
- ```
+////
Damit würden die Operation-IDs von Dingen wie `items-get_items` in `get_items` umbenannt, sodass der Client-Generator einfachere Methodennamen generieren kann.
diff --git a/docs/de/docs/advanced/index.md b/docs/de/docs/advanced/index.md
index 048e31e06..d93cd5fe8 100644
--- a/docs/de/docs/advanced/index.md
+++ b/docs/de/docs/advanced/index.md
@@ -6,10 +6,13 @@ Das Haupt-[Tutorial – Benutzerhandbuch](../tutorial/index.md){.internal-link t
In den nächsten Abschnitten sehen Sie weitere Optionen, Konfigurationen und zusätzliche Funktionen.
-!!! tip "Tipp"
- Die nächsten Abschnitte sind **nicht unbedingt „fortgeschritten“**.
+/// tip | Tipp
- Und es ist möglich, dass für Ihren Anwendungsfall die Lösung in einem davon liegt.
+Die nächsten Abschnitte sind **nicht unbedingt „fortgeschritten“**.
+
+Und es ist möglich, dass für Ihren Anwendungsfall die Lösung in einem davon liegt.
+
+///
## Lesen Sie zuerst das Tutorial
diff --git a/docs/de/docs/advanced/middleware.md b/docs/de/docs/advanced/middleware.md
index 2c4e8542a..17b339788 100644
--- a/docs/de/docs/advanced/middleware.md
+++ b/docs/de/docs/advanced/middleware.md
@@ -43,10 +43,13 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow")
**FastAPI** enthält mehrere Middlewares für gängige Anwendungsfälle. Wir werden als Nächstes sehen, wie man sie verwendet.
-!!! note "Technische Details"
- Für die nächsten Beispiele könnten Sie auch `from starlette.middleware.something import SomethingMiddleware` verwenden.
+/// note | Technische Details
- **FastAPI** bietet mehrere Middlewares via `fastapi.middleware` an, als Annehmlichkeit für Sie, den Entwickler. Die meisten verfügbaren Middlewares kommen aber direkt von Starlette.
+Für die nächsten Beispiele könnten Sie auch `from starlette.middleware.something import SomethingMiddleware` verwenden.
+
+**FastAPI** bietet mehrere Middlewares via `fastapi.middleware` an, als Annehmlichkeit für Sie, den Entwickler. Die meisten verfügbaren Middlewares kommen aber direkt von Starlette.
+
+///
## `HTTPSRedirectMiddleware`
@@ -54,17 +57,13 @@ Erzwingt, dass alle eingehenden Requests entweder `https` oder `wss` sein müsse
Alle eingehenden Requests an `http` oder `ws` werden stattdessen an das sichere Schema umgeleitet.
-```Python hl_lines="2 6"
-{!../../../docs_src/advanced_middleware/tutorial001.py!}
-```
+{* ../../docs_src/advanced_middleware/tutorial001.py hl[2,6] *}
## `TrustedHostMiddleware`
Erzwingt, dass alle eingehenden Requests einen korrekt gesetzten `Host`-Header haben, um sich vor HTTP-Host-Header-Angriffen zu schützen.
-```Python hl_lines="2 6-8"
-{!../../../docs_src/advanced_middleware/tutorial002.py!}
-```
+{* ../../docs_src/advanced_middleware/tutorial002.py hl[2,6:8] *}
Die folgenden Argumente werden unterstützt:
@@ -78,9 +77,7 @@ Verarbeitet GZip-Responses für alle Requests, die `"gzip"` im `Accept-Encoding`
Diese Middleware verarbeitet sowohl Standard- als auch Streaming-Responses.
-```Python hl_lines="2 6"
-{!../../../docs_src/advanced_middleware/tutorial003.py!}
-```
+{* ../../docs_src/advanced_middleware/tutorial003.py hl[2,6] *}
Die folgenden Argumente werden unterstützt:
@@ -92,7 +89,6 @@ Es gibt viele andere ASGI-Middlewares.
Zum Beispiel:
-* Sentry
* Uvicorns `ProxyHeadersMiddleware`
* MessagePack
diff --git a/docs/de/docs/advanced/openapi-callbacks.md b/docs/de/docs/advanced/openapi-callbacks.md
index 026fdb4fe..53f06e24e 100644
--- a/docs/de/docs/advanced/openapi-callbacks.md
+++ b/docs/de/docs/advanced/openapi-callbacks.md
@@ -31,12 +31,13 @@ Sie verfügt über eine *Pfadoperation*, die einen `Invoice`-Body empfängt, und
Dieser Teil ist ziemlich normal, der größte Teil des Codes ist Ihnen wahrscheinlich bereits bekannt:
-```Python hl_lines="9-13 36-53"
-{!../../../docs_src/openapi_callbacks/tutorial001.py!}
-```
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[9:13,36:53] *}
-!!! tip "Tipp"
- Der Query-Parameter `callback_url` verwendet einen Pydantic-Url-Typ.
+/// tip | Tipp
+
+Der Query-Parameter `callback_url` verwendet einen Pydantic-Url-Typ.
+
+///
Das einzig Neue ist `callbacks=invoices_callback_router.routes` als Argument für den *Pfadoperation-Dekorator*. Wir werden als Nächstes sehen, was das ist.
@@ -61,10 +62,13 @@ Diese Dokumentation wird in der Swagger-Oberfläche unter `/docs` in Ihrer API a
In diesem Beispiel wird nicht der Callback selbst implementiert (das könnte nur eine Codezeile sein), sondern nur der Dokumentationsteil.
-!!! tip "Tipp"
- Der eigentliche Callback ist nur ein HTTP-Request.
+/// tip | Tipp
- Wenn Sie den Callback selbst implementieren, können Sie beispielsweise HTTPX oder Requests verwenden.
+Der eigentliche Callback ist nur ein HTTP-Request.
+
+Wenn Sie den Callback selbst implementieren, können Sie beispielsweise HTTPX oder Requests verwenden.
+
+///
## Schreiben des Codes, der den Callback dokumentiert
@@ -74,18 +78,19 @@ Sie wissen jedoch bereits, wie Sie mit **FastAPI** ganz einfach eine automatisch
Daher werden wir dasselbe Wissen nutzen, um zu dokumentieren, wie die *externe API* aussehen sollte ... indem wir die *Pfadoperation(en)* erstellen, welche die externe API implementieren soll (die, welche Ihre API aufruft).
-!!! tip "Tipp"
- Wenn Sie den Code zum Dokumentieren eines Callbacks schreiben, kann es hilfreich sein, sich vorzustellen, dass Sie dieser *externe Entwickler* sind. Und dass Sie derzeit die *externe API* implementieren, nicht *Ihre API*.
+/// tip | Tipp
- Wenn Sie diese Sichtweise (des *externen Entwicklers*) vorübergehend übernehmen, wird es offensichtlicher, wo die Parameter, das Pydantic-Modell für den Body, die Response, usw. für diese *externe API* hingehören.
+Wenn Sie den Code zum Dokumentieren eines Callbacks schreiben, kann es hilfreich sein, sich vorzustellen, dass Sie dieser *externe Entwickler* sind. Und dass Sie derzeit die *externe API* implementieren, nicht *Ihre API*.
+
+Wenn Sie diese Sichtweise (des *externen Entwicklers*) vorübergehend übernehmen, wird es offensichtlicher, wo die Parameter, das Pydantic-Modell für den Body, die Response, usw. für diese *externe API* hingehören.
+
+///
### Einen Callback-`APIRouter` erstellen
Erstellen Sie zunächst einen neuen `APIRouter`, der einen oder mehrere Callbacks enthält.
-```Python hl_lines="3 25"
-{!../../../docs_src/openapi_callbacks/tutorial001.py!}
-```
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[3,25] *}
### Die Callback-*Pfadoperation* erstellen
@@ -96,9 +101,7 @@ Sie sollte wie eine normale FastAPI-*Pfadoperation* aussehen:
* Sie sollte wahrscheinlich eine Deklaration des Bodys enthalten, die sie erhalten soll, z. B. `body: InvoiceEvent`.
* Und sie könnte auch eine Deklaration der Response enthalten, die zurückgegeben werden soll, z. B. `response_model=InvoiceEventReceived`.
-```Python hl_lines="16-18 21-22 28-32"
-{!../../../docs_src/openapi_callbacks/tutorial001.py!}
-```
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[16:18,21:22,28:32] *}
Es gibt zwei Hauptunterschiede zu einer normalen *Pfadoperation*:
@@ -154,8 +157,11 @@ und sie würde eine Response von dieser *externen API* mit einem JSON-Body wie d
}
```
-!!! tip "Tipp"
- Beachten Sie, dass die verwendete Callback-URL die URL enthält, die als Query-Parameter in `callback_url` (`https://www.external.org/events`) empfangen wurde, und auch die Rechnungs-`id` aus dem JSON-Body (`2expen51ve`).
+/// tip | Tipp
+
+Beachten Sie, dass die verwendete Callback-URL die URL enthält, die als Query-Parameter in `callback_url` (`https://www.external.org/events`) empfangen wurde, und auch die Rechnungs-`id` aus dem JSON-Body (`2expen51ve`).
+
+///
### Den Callback-Router hinzufügen
@@ -163,12 +169,13 @@ An diesem Punkt haben Sie die benötigte(n) *Callback-Pfadoperation(en)* (diejen
Verwenden Sie nun den Parameter `callbacks` im *Pfadoperation-Dekorator Ihrer API*, um das Attribut `.routes` (das ist eigentlich nur eine `list`e von Routen/*Pfadoperationen*) dieses Callback-Routers zu übergeben:
-```Python hl_lines="35"
-{!../../../docs_src/openapi_callbacks/tutorial001.py!}
-```
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[35] *}
-!!! tip "Tipp"
- Beachten Sie, dass Sie nicht den Router selbst (`invoices_callback_router`) an `callback=` übergeben, sondern das Attribut `.routes`, wie in `invoices_callback_router.routes`.
+/// tip | Tipp
+
+Beachten Sie, dass Sie nicht den Router selbst (`invoices_callback_router`) an `callback=` übergeben, sondern das Attribut `.routes`, wie in `invoices_callback_router.routes`.
+
+///
### Es in der Dokumentation ansehen
diff --git a/docs/de/docs/advanced/openapi-webhooks.md b/docs/de/docs/advanced/openapi-webhooks.md
index 339218080..50b95eaf8 100644
--- a/docs/de/docs/advanced/openapi-webhooks.md
+++ b/docs/de/docs/advanced/openapi-webhooks.md
@@ -22,21 +22,25 @@ Mit **FastAPI** können Sie mithilfe von OpenAPI die Namen dieser Webhooks, die
Dies kann es Ihren Benutzern viel einfacher machen, **deren APIs zu implementieren**, um Ihre **Webhook**-Requests zu empfangen. Möglicherweise können diese sogar einen Teil des eigenem API-Codes automatisch generieren.
-!!! info
- Webhooks sind in OpenAPI 3.1.0 und höher verfügbar und werden von FastAPI `0.99.0` und höher unterstützt.
+/// info
+
+Webhooks sind in OpenAPI 3.1.0 und höher verfügbar und werden von FastAPI `0.99.0` und höher unterstützt.
+
+///
## Eine Anwendung mit Webhooks
Wenn Sie eine **FastAPI**-Anwendung erstellen, gibt es ein `webhooks`-Attribut, mit dem Sie *Webhooks* definieren können, genauso wie Sie *Pfadoperationen* definieren würden, zum Beispiel mit `@app.webhooks.post()`.
-```Python hl_lines="9-13 36-53"
-{!../../../docs_src/openapi_webhooks/tutorial001.py!}
-```
+{* ../../docs_src/openapi_webhooks/tutorial001.py hl[9:13,36:53] *}
Die von Ihnen definierten Webhooks landen im **OpenAPI**-Schema und der automatischen **Dokumentations-Oberfläche**.
-!!! info
- Das `app.webhooks`-Objekt ist eigentlich nur ein `APIRouter`, derselbe Typ, den Sie verwenden würden, wenn Sie Ihre Anwendung mit mehreren Dateien strukturieren.
+/// info
+
+Das `app.webhooks`-Objekt ist eigentlich nur ein `APIRouter`, derselbe Typ, den Sie verwenden würden, wenn Sie Ihre Anwendung mit mehreren Dateien strukturieren.
+
+///
Beachten Sie, dass Sie bei Webhooks tatsächlich keinen *Pfad* (wie `/items/`) deklarieren, sondern dass der Text, den Sie dort übergeben, lediglich eine **Kennzeichnung** des Webhooks (der Name des Events) ist. Zum Beispiel ist in `@app.webhooks.post("new-subscription")` der Webhook-Name `new-subscription`.
diff --git a/docs/de/docs/advanced/path-operation-advanced-configuration.md b/docs/de/docs/advanced/path-operation-advanced-configuration.md
index 406a08e9e..b6e88d2c9 100644
--- a/docs/de/docs/advanced/path-operation-advanced-configuration.md
+++ b/docs/de/docs/advanced/path-operation-advanced-configuration.md
@@ -2,16 +2,17 @@
## OpenAPI operationId
-!!! warning "Achtung"
- Wenn Sie kein „Experte“ für OpenAPI sind, brauchen Sie dies wahrscheinlich nicht.
+/// warning | Achtung
+
+Wenn Sie kein „Experte“ für OpenAPI sind, brauchen Sie dies wahrscheinlich nicht.
+
+///
Mit dem Parameter `operation_id` können Sie die OpenAPI `operationId` festlegen, die in Ihrer *Pfadoperation* verwendet werden soll.
Sie müssten sicherstellen, dass sie für jede Operation eindeutig ist.
-```Python hl_lines="6"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial001.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial001.py hl[6] *}
### Verwendung des Namens der *Pfadoperation-Funktion* als operationId
@@ -19,25 +20,27 @@ Wenn Sie die Funktionsnamen Ihrer API als `operationId`s verwenden möchten, kö
Sie sollten dies tun, nachdem Sie alle Ihre *Pfadoperationen* hinzugefügt haben.
-```Python hl_lines="2 12-21 24"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial002.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial002.py hl[2,12:21,24] *}
-!!! tip "Tipp"
- Wenn Sie `app.openapi()` manuell aufrufen, sollten Sie vorher die `operationId`s aktualisiert haben.
+/// tip | Tipp
-!!! warning "Achtung"
- Wenn Sie dies tun, müssen Sie sicherstellen, dass jede Ihrer *Pfadoperation-Funktionen* einen eindeutigen Namen hat.
+Wenn Sie `app.openapi()` manuell aufrufen, sollten Sie vorher die `operationId`s aktualisiert haben.
- Auch wenn diese sich in unterschiedlichen Modulen (Python-Dateien) befinden.
+///
+
+/// warning | Achtung
+
+Wenn Sie dies tun, müssen Sie sicherstellen, dass jede Ihrer *Pfadoperation-Funktionen* einen eindeutigen Namen hat.
+
+Auch wenn diese sich in unterschiedlichen Modulen (Python-Dateien) befinden.
+
+///
## Von OpenAPI ausschließen
Um eine *Pfadoperation* aus dem generierten OpenAPI-Schema (und damit aus den automatischen Dokumentationssystemen) auszuschließen, verwenden Sie den Parameter `include_in_schema` und setzen Sie ihn auf `False`:
-```Python hl_lines="6"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial003.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial003.py hl[6] *}
## Fortgeschrittene Beschreibung mittels Docstring
@@ -47,9 +50,7 @@ Das Hinzufügen eines `\f` (ein maskiertes „Form Feed“-Zeichen) führt dazu,
Sie wird nicht in der Dokumentation angezeigt, aber andere Tools (z. B. Sphinx) können den Rest verwenden.
-```Python hl_lines="19-29"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial004.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial004.py hl[19:29] *}
## Zusätzliche Responses
@@ -65,8 +66,11 @@ Es gibt hier in der Dokumentation ein ganzes Kapitel darüber, Sie können es un
Wenn Sie in Ihrer Anwendung eine *Pfadoperation* deklarieren, generiert **FastAPI** automatisch die relevanten Metadaten dieser *Pfadoperation*, die in das OpenAPI-Schema aufgenommen werden sollen.
-!!! note "Technische Details"
- In der OpenAPI-Spezifikation wird das Operationsobjekt genannt.
+/// note | Technische Details
+
+In der OpenAPI-Spezifikation wird das Operationsobjekt genannt.
+
+///
Es hat alle Informationen zur *Pfadoperation* und wird zur Erstellung der automatischen Dokumentation verwendet.
@@ -74,10 +78,13 @@ Es enthält `tags`, `parameters`, `requestBody`, `responses`, usw.
Dieses *Pfadoperation*-spezifische OpenAPI-Schema wird normalerweise automatisch von **FastAPI** generiert, Sie können es aber auch erweitern.
-!!! tip "Tipp"
- Dies ist ein Low-Level Erweiterungspunkt.
+/// tip | Tipp
- Wenn Sie nur zusätzliche Responses deklarieren müssen, können Sie dies bequemer mit [Zusätzliche Responses in OpenAPI](additional-responses.md){.internal-link target=_blank} tun.
+Dies ist ein Low-Level Erweiterungspunkt.
+
+Wenn Sie nur zusätzliche Responses deklarieren müssen, können Sie dies bequemer mit [Zusätzliche Responses in OpenAPI](additional-responses.md){.internal-link target=_blank} tun.
+
+///
Sie können das OpenAPI-Schema für eine *Pfadoperation* erweitern, indem Sie den Parameter `openapi_extra` verwenden.
@@ -85,9 +92,7 @@ Sie können das OpenAPI-Schema für eine *Pfadoperation* erweitern, indem Sie de
Dieses `openapi_extra` kann beispielsweise hilfreich sein, um OpenAPI-Erweiterungen zu deklarieren:
-```Python hl_lines="6"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial005.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial005.py hl[6] *}
Wenn Sie die automatische API-Dokumentation öffnen, wird Ihre Erweiterung am Ende der spezifischen *Pfadoperation* angezeigt.
@@ -134,9 +139,7 @@ Sie könnten sich beispielsweise dafür entscheiden, den Request mit Ihrem eigen
Das könnte man mit `openapi_extra` machen:
-```Python hl_lines="20-37 39-40"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial006.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial006.py hl[20:37,39:40] *}
In diesem Beispiel haben wir kein Pydantic-Modell deklariert. Tatsächlich wird der Requestbody nicht einmal als JSON geparst, sondern direkt als `bytes` gelesen und die Funktion `magic_data_reader ()` wäre dafür verantwortlich, ihn in irgendeiner Weise zu parsen.
@@ -150,20 +153,23 @@ Und Sie könnten dies auch tun, wenn der Datentyp in der Anfrage nicht JSON ist.
In der folgenden Anwendung verwenden wir beispielsweise weder die integrierte Funktionalität von FastAPI zum Extrahieren des JSON-Schemas aus Pydantic-Modellen noch die automatische Validierung für JSON. Tatsächlich deklarieren wir den Request-Content-Type als YAML und nicht als JSON:
-=== "Pydantic v2"
+//// tab | Pydantic v2
- ```Python hl_lines="17-22 24"
- {!> ../../../docs_src/path_operation_advanced_configuration/tutorial007.py!}
- ```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[17:22,24] *}
-=== "Pydantic v1"
+////
- ```Python hl_lines="17-22 24"
- {!> ../../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py!}
- ```
+//// tab | Pydantic v1
-!!! info
- In Pydantic Version 1 hieß die Methode zum Abrufen des JSON-Schemas für ein Modell `Item.schema()`, in Pydantic Version 2 heißt die Methode `Item.model_json_schema()`.
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py hl[17:22,24] *}
+
+////
+
+/// info
+
+In Pydantic Version 1 hieß die Methode zum Abrufen des JSON-Schemas für ein Modell `Item.schema()`, in Pydantic Version 2 heißt die Methode `Item.model_json_schema()`.
+
+///
Obwohl wir nicht die standardmäßig integrierte Funktionalität verwenden, verwenden wir dennoch ein Pydantic-Modell, um das JSON-Schema für die Daten, die wir in YAML empfangen möchten, manuell zu generieren.
@@ -171,22 +177,28 @@ Dann verwenden wir den Request direkt und extrahieren den Body als `bytes`. Das
Und dann parsen wir in unserem Code diesen YAML-Inhalt direkt und verwenden dann wieder dasselbe Pydantic-Modell, um den YAML-Inhalt zu validieren:
-=== "Pydantic v2"
+//// tab | Pydantic v2
- ```Python hl_lines="26-33"
- {!> ../../../docs_src/path_operation_advanced_configuration/tutorial007.py!}
- ```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[26:33] *}
-=== "Pydantic v1"
+////
- ```Python hl_lines="26-33"
- {!> ../../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py!}
- ```
+//// tab | Pydantic v1
-!!! info
- In Pydantic Version 1 war die Methode zum Parsen und Validieren eines Objekts `Item.parse_obj()`, in Pydantic Version 2 heißt die Methode `Item.model_validate()`.
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py hl[26:33] *}
-!!! tip "Tipp"
- Hier verwenden wir dasselbe Pydantic-Modell wieder.
+////
- Aber genauso hätten wir es auch auf andere Weise validieren können.
+/// info
+
+In Pydantic Version 1 war die Methode zum Parsen und Validieren eines Objekts `Item.parse_obj()`, in Pydantic Version 2 heißt die Methode `Item.model_validate()`.
+
+///
+
+/// tip | Tipp
+
+Hier verwenden wir dasselbe Pydantic-Modell wieder.
+
+Aber genauso hätten wir es auch auf andere Weise validieren können.
+
+///
diff --git a/docs/de/docs/advanced/response-change-status-code.md b/docs/de/docs/advanced/response-change-status-code.md
index bba908a3e..0aac32f4e 100644
--- a/docs/de/docs/advanced/response-change-status-code.md
+++ b/docs/de/docs/advanced/response-change-status-code.md
@@ -20,9 +20,7 @@ Sie können einen Parameter vom Typ `Response` in Ihrer *Pfadoperation-Funktion*
Anschließend können Sie den `status_code` in diesem *vorübergehenden* Response-Objekt festlegen.
-```Python hl_lines="1 9 12"
-{!../../../docs_src/response_change_status_code/tutorial001.py!}
-```
+{* ../../docs_src/response_change_status_code/tutorial001.py hl[1,9,12] *}
Und dann können Sie wie gewohnt jedes benötigte Objekt zurückgeben (ein `dict`, ein Datenbankmodell usw.).
diff --git a/docs/de/docs/advanced/response-cookies.md b/docs/de/docs/advanced/response-cookies.md
index 0f09bd444..5fe2cf7e3 100644
--- a/docs/de/docs/advanced/response-cookies.md
+++ b/docs/de/docs/advanced/response-cookies.md
@@ -6,9 +6,7 @@ Sie können einen Parameter vom Typ `Response` in Ihrer *Pfadoperation-Funktion*
Und dann können Sie Cookies in diesem *vorübergehenden* Response-Objekt setzen.
-```Python hl_lines="1 8-9"
-{!../../../docs_src/response_cookies/tutorial002.py!}
-```
+{* ../../docs_src/response_cookies/tutorial002.py hl[1,8:9] *}
Anschließend können Sie wie gewohnt jedes gewünschte Objekt zurückgeben (ein `dict`, ein Datenbankmodell, usw.).
@@ -26,24 +24,28 @@ Dazu können Sie eine Response erstellen, wie unter [Eine Response direkt zurüc
Setzen Sie dann Cookies darin und geben Sie sie dann zurück:
-```Python hl_lines="10-12"
-{!../../../docs_src/response_cookies/tutorial001.py!}
-```
+{* ../../docs_src/response_cookies/tutorial001.py hl[10:12] *}
-!!! tip "Tipp"
- Beachten Sie, dass, wenn Sie eine Response direkt zurückgeben, anstatt den `Response`-Parameter zu verwenden, FastAPI diese direkt zurückgibt.
+/// tip | Tipp
- Sie müssen also sicherstellen, dass Ihre Daten vom richtigen Typ sind. Z. B. sollten diese mit JSON kompatibel sein, wenn Sie eine `JSONResponse` zurückgeben.
+Beachten Sie, dass, wenn Sie eine Response direkt zurückgeben, anstatt den `Response`-Parameter zu verwenden, FastAPI diese direkt zurückgibt.
- Und auch, dass Sie keine Daten senden, die durch ein `response_model` hätten gefiltert werden sollen.
+Sie müssen also sicherstellen, dass Ihre Daten vom richtigen Typ sind. Z. B. sollten diese mit JSON kompatibel sein, wenn Sie eine `JSONResponse` zurückgeben.
+
+Und auch, dass Sie keine Daten senden, die durch ein `response_model` hätten gefiltert werden sollen.
+
+///
### Mehr Informationen
-!!! note "Technische Details"
- Sie können auch `from starlette.responses import Response` oder `from starlette.responses import JSONResponse` verwenden.
+/// note | Technische Details
- **FastAPI** bietet dieselben `starlette.responses` auch via `fastapi.responses` an, als Annehmlichkeit für Sie, den Entwickler. Die meisten verfügbaren Responses kommen aber direkt von Starlette.
+Sie können auch `from starlette.responses import Response` oder `from starlette.responses import JSONResponse` verwenden.
- Und da die `Response` häufig zum Setzen von Headern und Cookies verwendet wird, stellt **FastAPI** diese auch unter `fastapi.Response` bereit.
+**FastAPI** bietet dieselben `starlette.responses` auch via `fastapi.responses` an, als Annehmlichkeit für Sie, den Entwickler. Die meisten verfügbaren Responses kommen aber direkt von Starlette.
+
+Und da die `Response` häufig zum Setzen von Headern und Cookies verwendet wird, stellt **FastAPI** diese auch unter `fastapi.Response` bereit.
+
+///
Um alle verfügbaren Parameter und Optionen anzuzeigen, sehen Sie sich deren Dokumentation in Starlette an.
diff --git a/docs/de/docs/advanced/response-directly.md b/docs/de/docs/advanced/response-directly.md
index 13bca7825..b84aa8ab9 100644
--- a/docs/de/docs/advanced/response-directly.md
+++ b/docs/de/docs/advanced/response-directly.md
@@ -14,8 +14,11 @@ Das kann beispielsweise nützlich sein, um benutzerdefinierte Header oder Cookie
Tatsächlich können Sie jede `Response` oder jede Unterklasse davon zurückgeben.
-!!! tip "Tipp"
- `JSONResponse` selbst ist eine Unterklasse von `Response`.
+/// tip | Tipp
+
+`JSONResponse` selbst ist eine Unterklasse von `Response`.
+
+///
Und wenn Sie eine `Response` zurückgeben, wird **FastAPI** diese direkt weiterleiten.
@@ -31,14 +34,15 @@ Sie können beispielsweise kein Pydantic-Modell in eine `JSONResponse` einfügen
In diesen Fällen können Sie den `jsonable_encoder` verwenden, um Ihre Daten zu konvertieren, bevor Sie sie an eine Response übergeben:
-```Python hl_lines="6-7 21-22"
-{!../../../docs_src/response_directly/tutorial001.py!}
-```
+{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *}
-!!! note "Technische Details"
- Sie können auch `from starlette.responses import JSONResponse` verwenden.
+/// note | Technische Details
- **FastAPI** bietet dieselben `starlette.responses` auch via `fastapi.responses` an, als Annehmlichkeit für Sie, den Entwickler. Die meisten verfügbaren Responses kommen aber direkt von Starlette.
+Sie können auch `from starlette.responses import JSONResponse` verwenden.
+
+**FastAPI** bietet dieselben `starlette.responses` auch via `fastapi.responses` an, als Annehmlichkeit für Sie, den Entwickler. Die meisten verfügbaren Responses kommen aber direkt von Starlette.
+
+///
## Eine benutzerdefinierte `Response` zurückgeben
@@ -50,9 +54,7 @@ Nehmen wir an, Sie möchten eine ../../../docs_src/security/tutorial006_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="2 7 11"
- {!> ../../../docs_src/security/tutorial006_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="2 6 10"
- {!> ../../../docs_src/security/tutorial006.py!}
- ```
-
+{* ../../docs_src/security/tutorial006_an_py39.py hl[4,8,12] *}
Wenn Sie versuchen, die URL zum ersten Mal zu öffnen (oder in der Dokumentation auf den Button „Execute“ zu klicken), wird der Browser Sie nach Ihrem Benutzernamen und Passwort fragen:
@@ -59,26 +39,7 @@ Um dies zu lösen, konvertieren wir zunächst den `username` und das `password`
Dann können wir `secrets.compare_digest()` verwenden, um sicherzustellen, dass `credentials.username` `"stanleyjobson"` und `credentials.password` `"swordfish"` ist.
-=== "Python 3.9+"
-
- ```Python hl_lines="1 12-24"
- {!> ../../../docs_src/security/tutorial007_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="1 12-24"
- {!> ../../../docs_src/security/tutorial007_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="1 11-21"
- {!> ../../../docs_src/security/tutorial007.py!}
- ```
+{* ../../docs_src/security/tutorial007_an_py39.py hl[1,12:24] *}
Dies wäre das gleiche wie:
@@ -142,23 +103,4 @@ So ist Ihr Anwendungscode, dank der Verwendung von `secrets.compare_digest()`, v
Nachdem Sie festgestellt haben, dass die Anmeldeinformationen falsch sind, geben Sie eine `HTTPException` mit dem Statuscode 401 zurück (derselbe, der auch zurückgegeben wird, wenn keine Anmeldeinformationen angegeben werden) und fügen den Header `WWW-Authenticate` hinzu, damit der Browser die Anmeldeaufforderung erneut anzeigt:
-=== "Python 3.9+"
-
- ```Python hl_lines="26-30"
- {!> ../../../docs_src/security/tutorial007_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="26-30"
- {!> ../../../docs_src/security/tutorial007_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="23-27"
- {!> ../../../docs_src/security/tutorial007.py!}
- ```
+{* ../../docs_src/security/tutorial007_an_py39.py hl[26:30] *}
diff --git a/docs/de/docs/advanced/security/index.md b/docs/de/docs/advanced/security/index.md
index a3c975bed..25eeb25b5 100644
--- a/docs/de/docs/advanced/security/index.md
+++ b/docs/de/docs/advanced/security/index.md
@@ -4,10 +4,13 @@
Neben den in [Tutorial – Benutzerhandbuch: Sicherheit](../../tutorial/security/index.md){.internal-link target=_blank} behandelten Funktionen gibt es noch einige zusätzliche Funktionen zur Handhabung der Sicherheit.
-!!! tip "Tipp"
- Die nächsten Abschnitte sind **nicht unbedingt „fortgeschritten“**.
+/// tip | Tipp
- Und es ist möglich, dass für Ihren Anwendungsfall die Lösung in einem davon liegt.
+Die nächsten Abschnitte sind **nicht unbedingt „fortgeschritten“**.
+
+Und es ist möglich, dass für Ihren Anwendungsfall die Lösung in einem davon liegt.
+
+///
## Lesen Sie zuerst das Tutorial
diff --git a/docs/de/docs/advanced/security/oauth2-scopes.md b/docs/de/docs/advanced/security/oauth2-scopes.md
index ffd34d65f..ed8f69d18 100644
--- a/docs/de/docs/advanced/security/oauth2-scopes.md
+++ b/docs/de/docs/advanced/security/oauth2-scopes.md
@@ -10,18 +10,21 @@ Jedes Mal, wenn Sie sich mit Facebook, Google, GitHub, Microsoft oder Twitter an
In diesem Abschnitt erfahren Sie, wie Sie Authentifizierung und Autorisierung mit demselben OAuth2, mit Scopes in Ihrer **FastAPI**-Anwendung verwalten.
-!!! warning "Achtung"
- Dies ist ein mehr oder weniger fortgeschrittener Abschnitt. Wenn Sie gerade erst anfangen, können Sie ihn überspringen.
+/// warning | Achtung
- Sie benötigen nicht unbedingt OAuth2-Scopes, und Sie können die Authentifizierung und Autorisierung handhaben wie Sie möchten.
+Dies ist ein mehr oder weniger fortgeschrittener Abschnitt. Wenn Sie gerade erst anfangen, können Sie ihn überspringen.
- Aber OAuth2 mit Scopes kann bequem in Ihre API (mit OpenAPI) und deren API-Dokumentation integriert werden.
+Sie benötigen nicht unbedingt OAuth2-Scopes, und Sie können die Authentifizierung und Autorisierung handhaben wie Sie möchten.
- Dennoch, verwenden Sie solche Scopes oder andere Sicherheits-/Autorisierungsanforderungen in Ihrem Code so wie Sie es möchten.
+Aber OAuth2 mit Scopes kann bequem in Ihre API (mit OpenAPI) und deren API-Dokumentation integriert werden.
- In vielen Fällen kann OAuth2 mit Scopes ein Overkill sein.
+Dennoch, verwenden Sie solche Scopes oder andere Sicherheits-/Autorisierungsanforderungen in Ihrem Code so wie Sie es möchten.
- Aber wenn Sie wissen, dass Sie es brauchen oder neugierig sind, lesen Sie weiter.
+In vielen Fällen kann OAuth2 mit Scopes ein Overkill sein.
+
+Aber wenn Sie wissen, dass Sie es brauchen oder neugierig sind, lesen Sie weiter.
+
+///
## OAuth2-Scopes und OpenAPI
@@ -43,63 +46,23 @@ Er wird normalerweise verwendet, um bestimmte Sicherheitsberechtigungen zu dekla
* `instagram_basic` wird von Facebook / Instagram verwendet.
* `https://www.googleapis.com/auth/drive` wird von Google verwendet.
-!!! info
- In OAuth2 ist ein „Scope“ nur ein String, der eine bestimmte erforderliche Berechtigung deklariert.
+/// info
- Es spielt keine Rolle, ob er andere Zeichen wie `:` enthält oder ob es eine URL ist.
+In OAuth2 ist ein „Scope“ nur ein String, der eine bestimmte erforderliche Berechtigung deklariert.
- Diese Details sind implementierungsspezifisch.
+Es spielt keine Rolle, ob er andere Zeichen wie `:` enthält oder ob es eine URL ist.
- Für OAuth2 sind es einfach nur Strings.
+Diese Details sind implementierungsspezifisch.
+
+Für OAuth2 sind es einfach nur Strings.
+
+///
## Gesamtübersicht
Sehen wir uns zunächst kurz die Teile an, die sich gegenüber den Beispielen im Haupt-**Tutorial – Benutzerhandbuch** für [OAuth2 mit Password (und Hashing), Bearer mit JWT-Tokens](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank} ändern. Diesmal verwenden wir OAuth2-Scopes:
-=== "Python 3.10+"
-
- ```Python hl_lines="4 8 12 46 64 105 107-115 121-124 128-134 139 155"
- {!> ../../../docs_src/security/tutorial005_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="2 4 8 12 46 64 105 107-115 121-124 128-134 139 155"
- {!> ../../../docs_src/security/tutorial005_an_py39.py!}
- ```
-
-=== "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!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="3 7 11 45 63 104 106-114 120-123 127-133 138 154"
- {!> ../../../docs_src/security/tutorial005_py310.py!}
- ```
-
-=== "Python 3.9+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="2 4 8 12 46 64 105 107-115 121-124 128-134 139 155"
- {!> ../../../docs_src/security/tutorial005_py39.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="2 4 8 12 46 64 105 107-115 121-124 128-134 139 155"
- {!> ../../../docs_src/security/tutorial005.py!}
- ```
+{* ../../docs_src/security/tutorial005_an_py310.py hl[4,8,12,46,64,105,107:115,121:124,128:134,139,155] *}
Sehen wir uns diese Änderungen nun Schritt für Schritt an.
@@ -109,51 +72,7 @@ Die erste Änderung ist, dass wir jetzt das OAuth2-Sicherheitsschema mit zwei ve
Der `scopes`-Parameter erhält ein `dict` mit jedem Scope als Schlüssel und dessen Beschreibung als Wert:
-=== "Python 3.10+"
-
- ```Python hl_lines="62-65"
- {!> ../../../docs_src/security/tutorial005_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="62-65"
- {!> ../../../docs_src/security/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="63-66"
- {!> ../../../docs_src/security/tutorial005_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="61-64"
- {!> ../../../docs_src/security/tutorial005_py310.py!}
- ```
-
-
-=== "Python 3.9+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="62-65"
- {!> ../../../docs_src/security/tutorial005_py39.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="62-65"
- {!> ../../../docs_src/security/tutorial005.py!}
- ```
+{* ../../docs_src/security/tutorial005_an_py310.py hl[62:65] *}
Da wir diese Scopes jetzt deklarieren, werden sie in der API-Dokumentation angezeigt, wenn Sie sich einloggen/autorisieren.
@@ -171,55 +90,15 @@ Wir verwenden immer noch dasselbe `OAuth2PasswordRequestForm`. Es enthält eine
Und wir geben die Scopes als Teil des JWT-Tokens zurück.
-!!! danger "Gefahr"
- Der Einfachheit halber fügen wir hier die empfangenen Scopes direkt zum Token hinzu.
+/// danger | Gefahr
- Aus Sicherheitsgründen sollten Sie jedoch sicherstellen, dass Sie in Ihrer Anwendung nur die Scopes hinzufügen, die der Benutzer tatsächlich haben kann, oder die Sie vordefiniert haben.
+Der Einfachheit halber fügen wir hier die empfangenen Scopes direkt zum Token hinzu.
-=== "Python 3.10+"
+Aus Sicherheitsgründen sollten Sie jedoch sicherstellen, dass Sie in Ihrer Anwendung nur die Scopes hinzufügen, die der Benutzer tatsächlich haben kann, oder die Sie vordefiniert haben.
- ```Python hl_lines="155"
- {!> ../../../docs_src/security/tutorial005_an_py310.py!}
- ```
+///
-=== "Python 3.9+"
-
- ```Python hl_lines="155"
- {!> ../../../docs_src/security/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="156"
- {!> ../../../docs_src/security/tutorial005_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="154"
- {!> ../../../docs_src/security/tutorial005_py310.py!}
- ```
-
-=== "Python 3.9+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="155"
- {!> ../../../docs_src/security/tutorial005_py39.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="155"
- {!> ../../../docs_src/security/tutorial005.py!}
- ```
+{* ../../docs_src/security/tutorial005_an_py310.py hl[155] *}
## Scopes in *Pfadoperationen* und Abhängigkeiten deklarieren
@@ -237,62 +116,25 @@ Und die Abhängigkeitsfunktion `get_current_active_user` kann auch Unterabhängi
In diesem Fall erfordert sie den Scope `me` (sie könnte mehr als einen Scope erfordern).
-!!! note "Hinweis"
- Sie müssen nicht unbedingt an verschiedenen Stellen verschiedene Scopes hinzufügen.
+/// note | Hinweis
- Wir tun dies hier, um zu demonstrieren, wie **FastAPI** auf verschiedenen Ebenen deklarierte Scopes verarbeitet.
+Sie müssen nicht unbedingt an verschiedenen Stellen verschiedene Scopes hinzufügen.
-=== "Python 3.10+"
+Wir tun dies hier, um zu demonstrieren, wie **FastAPI** auf verschiedenen Ebenen deklarierte Scopes verarbeitet.
- ```Python hl_lines="4 139 170"
- {!> ../../../docs_src/security/tutorial005_an_py310.py!}
- ```
+///
-=== "Python 3.9+"
+{* ../../docs_src/security/tutorial005_an_py310.py hl[4,139,170] *}
- ```Python hl_lines="4 139 170"
- {!> ../../../docs_src/security/tutorial005_an_py39.py!}
- ```
+/// info | Technische Details
-=== "Python 3.8+"
+`Security` ist tatsächlich eine Unterklasse von `Depends` und hat nur noch einen zusätzlichen Parameter, den wir später kennenlernen werden.
- ```Python hl_lines="4 140 171"
- {!> ../../../docs_src/security/tutorial005_an.py!}
- ```
+Durch die Verwendung von `Security` anstelle von `Depends` weiß **FastAPI** jedoch, dass es Sicherheits-Scopes deklarieren, intern verwenden und die API mit OpenAPI dokumentieren kann.
-=== "Python 3.10+ nicht annotiert"
+Wenn Sie jedoch `Query`, `Path`, `Depends`, `Security` und andere von `fastapi` importieren, handelt es sich tatsächlich um Funktionen, die spezielle Klassen zurückgeben.
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="3 138 167"
- {!> ../../../docs_src/security/tutorial005_py310.py!}
- ```
-
-=== "Python 3.9+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="4 139 168"
- {!> ../../../docs_src/security/tutorial005_py39.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="4 139 168"
- {!> ../../../docs_src/security/tutorial005.py!}
- ```
-
-!!! info "Technische Details"
- `Security` ist tatsächlich eine Unterklasse von `Depends` und hat nur noch einen zusätzlichen Parameter, den wir später kennenlernen werden.
-
- Durch die Verwendung von `Security` anstelle von `Depends` weiß **FastAPI** jedoch, dass es Sicherheits-Scopes deklarieren, intern verwenden und die API mit OpenAPI dokumentieren kann.
-
- Wenn Sie jedoch `Query`, `Path`, `Depends`, `Security` und andere von `fastapi` importieren, handelt es sich tatsächlich um Funktionen, die spezielle Klassen zurückgeben.
+///
## `SecurityScopes` verwenden
@@ -308,50 +150,7 @@ Wir deklarieren auch einen speziellen Parameter vom Typ `SecurityScopes`, der au
Diese `SecurityScopes`-Klasse ähnelt `Request` (`Request` wurde verwendet, um das Request-Objekt direkt zu erhalten).
-=== "Python 3.10+"
-
- ```Python hl_lines="8 105"
- {!> ../../../docs_src/security/tutorial005_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="8 105"
- {!> ../../../docs_src/security/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="8 106"
- {!> ../../../docs_src/security/tutorial005_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="7 104"
- {!> ../../../docs_src/security/tutorial005_py310.py!}
- ```
-
-=== "Python 3.9+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="8 105"
- {!> ../../../docs_src/security/tutorial005_py39.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="8 105"
- {!> ../../../docs_src/security/tutorial005.py!}
- ```
+{* ../../docs_src/security/tutorial005_an_py310.py hl[8,105] *}
## Die `scopes` verwenden
@@ -365,50 +164,7 @@ Wir erstellen eine `HTTPException`, die wir später an mehreren Stellen wiederve
In diese Exception fügen wir (falls vorhanden) die erforderlichen Scopes als durch Leerzeichen getrennten String ein (unter Verwendung von `scope_str`). Wir fügen diesen String mit den Scopes in den Header `WWW-Authenticate` ein (das ist Teil der Spezifikation).
-=== "Python 3.10+"
-
- ```Python hl_lines="105 107-115"
- {!> ../../../docs_src/security/tutorial005_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="105 107-115"
- {!> ../../../docs_src/security/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="106 108-116"
- {!> ../../../docs_src/security/tutorial005_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="104 106-114"
- {!> ../../../docs_src/security/tutorial005_py310.py!}
- ```
-
-=== "Python 3.9+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="105 107-115"
- {!> ../../../docs_src/security/tutorial005_py39.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="105 107-115"
- {!> ../../../docs_src/security/tutorial005.py!}
- ```
+{* ../../docs_src/security/tutorial005_an_py310.py hl[105,107:115] *}
## Den `username` und das Format der Daten überprüfen
@@ -424,50 +180,7 @@ Anstelle beispielsweise eines `dict`s oder etwas anderem, was später in der Anw
Wir verifizieren auch, dass wir einen Benutzer mit diesem Benutzernamen haben, und wenn nicht, lösen wir dieselbe Exception aus, die wir zuvor erstellt haben.
-=== "Python 3.10+"
-
- ```Python hl_lines="46 116-127"
- {!> ../../../docs_src/security/tutorial005_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="46 116-127"
- {!> ../../../docs_src/security/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="47 117-128"
- {!> ../../../docs_src/security/tutorial005_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="45 115-126"
- {!> ../../../docs_src/security/tutorial005_py310.py!}
- ```
-
-=== "Python 3.9+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="46 116-127"
- {!> ../../../docs_src/security/tutorial005_py39.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="46 116-127"
- {!> ../../../docs_src/security/tutorial005.py!}
- ```
+{* ../../docs_src/security/tutorial005_an_py310.py hl[46,116:127] *}
## Die `scopes` verifizieren
@@ -475,50 +188,7 @@ Wir überprüfen nun, ob das empfangenen Token alle Scopes enthält, die von die
Hierzu verwenden wir `security_scopes.scopes`, das eine `list`e mit allen diesen Scopes als `str` enthält.
-=== "Python 3.10+"
-
- ```Python hl_lines="128-134"
- {!> ../../../docs_src/security/tutorial005_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="128-134"
- {!> ../../../docs_src/security/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="129-135"
- {!> ../../../docs_src/security/tutorial005_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="127-133"
- {!> ../../../docs_src/security/tutorial005_py310.py!}
- ```
-
-=== "Python 3.9+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="128-134"
- {!> ../../../docs_src/security/tutorial005_py39.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="128-134"
- {!> ../../../docs_src/security/tutorial005.py!}
- ```
+{* ../../docs_src/security/tutorial005_an_py310.py hl[128:134] *}
## Abhängigkeitsbaum und Scopes
@@ -545,10 +215,13 @@ So sieht die Hierarchie der Abhängigkeiten und Scopes aus:
* `security_scopes.scopes` enthält `["me"]` für die *Pfadoperation* `read_users_me`, da das in der Abhängigkeit `get_current_active_user` deklariert ist.
* `security_scopes.scopes` wird `[]` (nichts) für die *Pfadoperation* `read_system_status` enthalten, da diese keine `Security` mit `scopes` deklariert hat, und deren Abhängigkeit `get_current_user` ebenfalls keinerlei `scopes` deklariert.
-!!! tip "Tipp"
- Das Wichtige und „Magische“ hier ist, dass `get_current_user` für jede *Pfadoperation* eine andere Liste von `scopes` hat, die überprüft werden.
+/// tip | Tipp
- Alles hängt von den „Scopes“ ab, die in jeder *Pfadoperation* und jeder Abhängigkeit im Abhängigkeitsbaum für diese bestimmte *Pfadoperation* deklariert wurden.
+Das Wichtige und „Magische“ hier ist, dass `get_current_user` für jede *Pfadoperation* eine andere Liste von `scopes` hat, die überprüft werden.
+
+Alles hängt von den „Scopes“ ab, die in jeder *Pfadoperation* und jeder Abhängigkeit im Abhängigkeitsbaum für diese bestimmte *Pfadoperation* deklariert wurden.
+
+///
## Weitere Details zu `SecurityScopes`.
@@ -586,10 +259,13 @@ Am häufigsten ist der „Implicit“-Flow.
Am sichersten ist der „Code“-Flow, die Implementierung ist jedoch komplexer, da mehr Schritte erforderlich sind. Da er komplexer ist, schlagen viele Anbieter letztendlich den „Implicit“-Flow vor.
-!!! note "Hinweis"
- Es ist üblich, dass jeder Authentifizierungsanbieter seine Flows anders benennt, um sie zu einem Teil seiner Marke zu machen.
+/// note | Hinweis
- Aber am Ende implementieren sie denselben OAuth2-Standard.
+Es ist üblich, dass jeder Authentifizierungsanbieter seine Flows anders benennt, um sie zu einem Teil seiner Marke zu machen.
+
+Aber am Ende implementieren sie denselben OAuth2-Standard.
+
+///
**FastAPI** enthält Werkzeuge für alle diese OAuth2-Authentifizierungs-Flows in `fastapi.security.oauth2`.
diff --git a/docs/de/docs/advanced/settings.md b/docs/de/docs/advanced/settings.md
index fe01d8e1f..00cc2ac37 100644
--- a/docs/de/docs/advanced/settings.md
+++ b/docs/de/docs/advanced/settings.md
@@ -8,44 +8,51 @@ Aus diesem Grund werden diese üblicherweise in Umgebungsvariablen bereitgestell
## Umgebungsvariablen
-!!! tip "Tipp"
- Wenn Sie bereits wissen, was „Umgebungsvariablen“ sind und wie man sie verwendet, können Sie gerne mit dem nächsten Abschnitt weiter unten fortfahren.
+/// tip | Tipp
+
+Wenn Sie bereits wissen, was „Umgebungsvariablen“ sind und wie man sie verwendet, können Sie gerne mit dem nächsten Abschnitt weiter unten fortfahren.
+
+///
Eine Umgebungsvariable (auch bekannt als „env var“) ist eine Variable, die sich außerhalb des Python-Codes im Betriebssystem befindet und von Ihrem Python-Code (oder auch von anderen Programmen) gelesen werden kann.
Sie können Umgebungsvariablen in der Shell erstellen und verwenden, ohne Python zu benötigen:
-=== "Linux, macOS, Windows Bash"
+//// tab | Linux, macOS, Windows Bash
-
-!!! info
- Die wunderschönen Illustrationen stammen von Ketrina Thompson. 🎨
+/// info
+
+Die wunderschönen Illustrationen stammen von Ketrina Thompson. 🎨
+
+///
---
@@ -199,8 +205,11 @@ Sie essen sie und sind fertig. ⏹
Es wurde nicht viel geredet oder geflirtet, da die meiste Zeit mit Warten 🕙 vor der Theke verbracht wurde. 😞
-!!! info
- Die wunderschönen Illustrationen stammen von Ketrina Thompson. 🎨
+/// info
+
+Die wunderschönen Illustrationen stammen von Ketrina Thompson. 🎨
+
+///
---
@@ -392,12 +401,15 @@ All das ist es, was FastAPI (via Starlette) befeuert und es eine so beeindrucken
## Sehr technische Details
-!!! warning "Achtung"
- Das folgende können Sie wahrscheinlich überspringen.
+/// warning | Achtung
- Dies sind sehr technische Details darüber, wie **FastAPI** unter der Haube funktioniert.
+Das folgende können Sie wahrscheinlich überspringen.
- Wenn Sie über gute technische Kenntnisse verfügen (Coroutinen, Threads, Blocking, usw.) und neugierig sind, wie FastAPI mit `async def`s im Vergleich zu normalen `def`s umgeht, fahren Sie fort.
+Dies sind sehr technische Details darüber, wie **FastAPI** unter der Haube funktioniert.
+
+Wenn Sie über gute technische Kenntnisse verfügen (Coroutinen, Threads, Blocking, usw.) und neugierig sind, wie FastAPI mit `async def`s im Vergleich zu normalen `def`s umgeht, fahren Sie fort.
+
+///
### Pfadoperation-Funktionen
diff --git a/docs/de/docs/contributing.md b/docs/de/docs/contributing.md
deleted file mode 100644
index b1bd62496..000000000
--- a/docs/de/docs/contributing.md
+++ /dev/null
@@ -1,447 +0,0 @@
-# Entwicklung – Mitwirken
-
-Vielleicht möchten Sie sich zuerst die grundlegenden Möglichkeiten anschauen, [FastAPI zu helfen und Hilfe zu erhalten](help-fastapi.md){.internal-link target=_blank}.
-
-## Entwicklung
-
-Wenn Sie das fastapi Repository bereits geklont haben und tief in den Code eintauchen möchten, hier einen Leitfaden zum Einrichten Ihrer Umgebung.
-
-### Virtuelle Umgebung mit `venv`
-
-Sie können mit dem Python-Modul `venv` in einem Verzeichnis eine isolierte virtuelle lokale Umgebung erstellen. Machen wir das im geklonten Repository (da wo sich die `requirements.txt` befindet):
-
-
-
+
@@ -94,7 +94,7 @@ Seine Schlüssel-Merkmale sind:
„_Ehrlich, was Du gebaut hast, sieht super solide und poliert aus. In vielerlei Hinsicht ist es so, wie ich **Hug** haben wollte – es ist wirklich inspirierend, jemanden so etwas bauen zu sehen._“
-
+
---
@@ -449,7 +449,7 @@ Um mehr darüber zu erfahren, siehe den Abschnitt
email_validator - für E-Mail-Validierung.
+* email-validator - für E-Mail-Validierung.
* pydantic-settings - für die Verwaltung von Einstellungen.
* pydantic-extra-types - für zusätzliche Typen, mit Pydantic zu verwenden.
diff --git a/docs/de/docs/newsletter.md b/docs/de/docs/newsletter.md
deleted file mode 100644
index 31995b164..000000000
--- a/docs/de/docs/newsletter.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# FastAPI und Freunde Newsletter
-
-
-
-
diff --git a/docs/de/docs/python-types.md b/docs/de/docs/python-types.md
index d11a193dd..81d43bc5b 100644
--- a/docs/de/docs/python-types.md
+++ b/docs/de/docs/python-types.md
@@ -12,16 +12,17 @@ Dies ist lediglich eine **schnelle Anleitung / Auffrischung** über Pythons Typh
Aber selbst wenn Sie **FastAPI** nie verwenden, wird es für Sie nützlich sein, ein wenig darüber zu lernen.
-!!! note "Hinweis"
- Wenn Sie ein Python-Experte sind und bereits alles über Typhinweise wissen, überspringen Sie dieses Kapitel und fahren Sie mit dem nächsten fort.
+/// note | Hinweis
+
+Wenn Sie ein Python-Experte sind und bereits alles über Typhinweise wissen, überspringen Sie dieses Kapitel und fahren Sie mit dem nächsten fort.
+
+///
## Motivation
Fangen wir mit einem einfachen Beispiel an:
-```Python
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py *}
Dieses Programm gibt aus:
@@ -35,9 +36,7 @@ Die Funktion macht Folgendes:
* Schreibt den ersten Buchstaben eines jeden Wortes groß, mithilfe von `title()`.
* Verkettet sie mit einem Leerzeichen in der Mitte.
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py hl[2] *}
### Bearbeiten Sie es
@@ -79,9 +78,7 @@ Das war's.
Das sind die „Typhinweise“:
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial002.py!}
-```
+{* ../../docs_src/python_types/tutorial002.py hl[1] *}
Das ist nicht das gleiche wie das Deklarieren von Defaultwerten, wie es hier der Fall ist:
@@ -109,9 +106,7 @@ Hier können Sie durch die Optionen blättern, bis Sie diejenige finden, bei der
Sehen Sie sich diese Funktion an, sie hat bereits Typhinweise:
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial003.py!}
-```
+{* ../../docs_src/python_types/tutorial003.py hl[1] *}
Da der Editor die Typen der Variablen kennt, erhalten Sie nicht nur Code-Vervollständigung, sondern auch eine Fehlerprüfung:
@@ -119,9 +114,7 @@ Da der Editor die Typen der Variablen kennt, erhalten Sie nicht nur Code-Vervoll
Jetzt, da Sie wissen, dass Sie das reparieren müssen, konvertieren Sie `age` mittels `str(age)` in einen String:
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial004.py!}
-```
+{* ../../docs_src/python_types/tutorial004.py hl[2] *}
## Deklarieren von Typen
@@ -140,9 +133,7 @@ Zum Beispiel diese:
* `bool`
* `bytes`
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial005.py!}
-```
+{* ../../docs_src/python_types/tutorial005.py hl[1] *}
### Generische Typen mit Typ-Parametern
@@ -170,45 +161,55 @@ Wenn Sie über die **neueste Version von Python** verfügen, verwenden Sie die B
Definieren wir zum Beispiel eine Variable, die eine `list` von `str` – eine Liste von Strings – sein soll.
-=== "Python 3.9+"
+//// tab | Python 3.9+
- Deklarieren Sie die Variable mit der gleichen Doppelpunkt-Syntax (`:`).
+Deklarieren Sie die Variable mit der gleichen Doppelpunkt-Syntax (`:`).
- Als Typ nehmen Sie `list`.
+Als Typ nehmen Sie `list`.
- Da die Liste ein Typ ist, welcher innere Typen enthält, werden diese von eckigen Klammern umfasst:
+Da die Liste ein Typ ist, welcher innere Typen enthält, werden diese von eckigen Klammern umfasst:
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial006_py39.py!}
- ```
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial006_py39.py!}
+```
-=== "Python 3.8+"
+////
- Von `typing` importieren Sie `List` (mit Großbuchstaben `L`):
+//// tab | Python 3.8+
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial006.py!}
- ```
+Von `typing` importieren Sie `List` (mit Großbuchstaben `L`):
- Deklarieren Sie die Variable mit der gleichen Doppelpunkt-Syntax (`:`).
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial006.py!}
+```
- Als Typ nehmen Sie das `List`, das Sie von `typing` importiert haben.
+Deklarieren Sie die Variable mit der gleichen Doppelpunkt-Syntax (`:`).
- Da die Liste ein Typ ist, welcher innere Typen enthält, werden diese von eckigen Klammern umfasst:
+Als Typ nehmen Sie das `List`, das Sie von `typing` importiert haben.
- ```Python hl_lines="4"
- {!> ../../../docs_src/python_types/tutorial006.py!}
- ```
+Da die Liste ein Typ ist, welcher innere Typen enthält, werden diese von eckigen Klammern umfasst:
-!!! tip "Tipp"
- Die inneren Typen in den eckigen Klammern werden als „Typ-Parameter“ bezeichnet.
+```Python hl_lines="4"
+{!> ../../docs_src/python_types/tutorial006.py!}
+```
- In diesem Fall ist `str` der Typ-Parameter, der an `List` übergeben wird (oder `list` in Python 3.9 und darüber).
+////
+
+/// tip | Tipp
+
+Die inneren Typen in den eckigen Klammern werden als „Typ-Parameter“ bezeichnet.
+
+In diesem Fall ist `str` der Typ-Parameter, der an `List` übergeben wird (oder `list` in Python 3.9 und darüber).
+
+///
Das bedeutet: Die Variable `items` ist eine Liste – `list` – und jedes der Elemente in dieser Liste ist ein String – `str`.
-!!! tip "Tipp"
- Wenn Sie Python 3.9 oder höher verwenden, müssen Sie `List` nicht von `typing` importieren, Sie können stattdessen den regulären `list`-Typ verwenden.
+/// tip | Tipp
+
+Wenn Sie Python 3.9 oder höher verwenden, müssen Sie `List` nicht von `typing` importieren, Sie können stattdessen den regulären `list`-Typ verwenden.
+
+///
Auf diese Weise kann Ihr Editor Sie auch bei der Bearbeitung von Einträgen aus der Liste unterstützen:
@@ -224,17 +225,21 @@ Und trotzdem weiß der Editor, dass es sich um ein `str` handelt, und bietet ent
Das Gleiche gilt für die Deklaration eines Tupels – `tuple` – und einer Menge – `set`:
-=== "Python 3.9+"
+//// tab | Python 3.9+
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial007_py39.py!}
- ```
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial007_py39.py!}
+```
-=== "Python 3.8+"
+////
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial007.py!}
- ```
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial007.py!}
+```
+
+////
Das bedeutet:
@@ -249,17 +254,21 @@ Der erste Typ-Parameter ist für die Schlüssel des `dict`.
Der zweite Typ-Parameter ist für die Werte des `dict`:
-=== "Python 3.9+"
+//// tab | Python 3.9+
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial008_py39.py!}
- ```
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008_py39.py!}
+```
-=== "Python 3.8+"
+////
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial008.py!}
- ```
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial008.py!}
+```
+
+////
Das bedeutet:
@@ -275,17 +284,21 @@ In Python 3.6 und höher (inklusive Python 3.10) können Sie den `Union`-Typ von
In Python 3.10 gibt es zusätzlich eine **neue Syntax**, die es erlaubt, die möglichen Typen getrennt von einem vertikalen Balken (`|`) aufzulisten.
-=== "Python 3.10+"
+//// tab | Python 3.10+
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial008b_py310.py!}
- ```
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008b_py310.py!}
+```
-=== "Python 3.8+"
+////
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial008b.py!}
- ```
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial008b.py!}
+```
+
+////
In beiden Fällen bedeutet das, dass `item` ein `int` oder ein `str` sein kann.
@@ -295,9 +308,7 @@ Sie können deklarieren, dass ein Wert ein `str`, aber vielleicht auch `None` se
In Python 3.6 und darüber (inklusive Python 3.10) können Sie das deklarieren, indem Sie `Optional` vom `typing` Modul importieren und verwenden.
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial009.py!}
-```
+{* ../../docs_src/python_types/tutorial009.py hl[1,4] *}
Wenn Sie `Optional[str]` anstelle von nur `str` verwenden, wird Ihr Editor Ihnen dabei helfen, Fehler zu erkennen, bei denen Sie annehmen könnten, dass ein Wert immer eine String (`str`) ist, obwohl er auch `None` sein könnte.
@@ -305,23 +316,29 @@ Wenn Sie `Optional[str]` anstelle von nur `str` verwenden, wird Ihr Editor Ihnen
Das bedeutet auch, dass Sie in Python 3.10 `Something | None` verwenden können:
-=== "Python 3.10+"
+//// tab | Python 3.10+
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial009_py310.py!}
- ```
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial009_py310.py!}
+```
-=== "Python 3.8+"
+////
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial009.py!}
- ```
+//// tab | Python 3.8+
-=== "Python 3.8+ Alternative"
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial009.py!}
+```
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial009b.py!}
- ```
+////
+
+//// tab | Python 3.8+ Alternative
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial009b.py!}
+```
+
+////
#### `Union` oder `Optional` verwenden?
@@ -338,9 +355,7 @@ Es geht nur um Wörter und Namen. Aber diese Worte können beeinflussen, wie Sie
Nehmen wir zum Beispiel diese Funktion:
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial009c.py!}
-```
+{* ../../docs_src/python_types/tutorial009c.py hl[1,4] *}
Der Parameter `name` ist definiert als `Optional[str]`, aber er ist **nicht optional**, Sie können die Funktion nicht ohne diesen Parameter aufrufen:
@@ -356,9 +371,7 @@ say_hi(name=None) # Das funktioniert, None is gültig 🎉
Die gute Nachricht ist, dass Sie sich darüber keine Sorgen mehr machen müssen, wenn Sie Python 3.10 verwenden, da Sie einfach `|` verwenden können, um Vereinigungen von Typen zu definieren:
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial009c_py310.py!}
-```
+{* ../../docs_src/python_types/tutorial009c_py310.py hl[1,4] *}
Und dann müssen Sie sich nicht mehr um Namen wie `Optional` und `Union` kümmern. 😎
@@ -366,47 +379,53 @@ Und dann müssen Sie sich nicht mehr um Namen wie `Optional` und `Union` kümmer
Diese Typen, die Typ-Parameter in eckigen Klammern akzeptieren, werden **generische Typen** oder **Generics** genannt.
-=== "Python 3.10+"
+//// tab | Python 3.10+
- Sie können die eingebauten Typen als Generics verwenden (mit eckigen Klammern und Typen darin):
+Sie können die eingebauten Typen als Generics verwenden (mit eckigen Klammern und Typen darin):
- * `list`
- * `tuple`
- * `set`
- * `dict`
+* `list`
+* `tuple`
+* `set`
+* `dict`
- Verwenden Sie für den Rest, wie unter Python 3.8, das `typing`-Modul:
+Verwenden Sie für den Rest, wie unter Python 3.8, das `typing`-Modul:
- * `Union`
- * `Optional` (so wie unter Python 3.8)
- * ... und andere.
+* `Union`
+* `Optional` (so wie unter Python 3.8)
+* ... und andere.
- In Python 3.10 können Sie als Alternative zu den Generics `Union` und `Optional` den vertikalen Balken (`|`) verwenden, um Vereinigungen von Typen zu deklarieren, das ist besser und einfacher.
+In Python 3.10 können Sie als Alternative zu den Generics `Union` und `Optional` den vertikalen Balken (`|`) verwenden, um Vereinigungen von Typen zu deklarieren, das ist besser und einfacher.
-=== "Python 3.9+"
+////
- Sie können die eingebauten Typen als Generics verwenden (mit eckigen Klammern und Typen darin):
+//// tab | Python 3.9+
- * `list`
- * `tuple`
- * `set`
- * `dict`
+Sie können die eingebauten Typen als Generics verwenden (mit eckigen Klammern und Typen darin):
- Verwenden Sie für den Rest, wie unter Python 3.8, das `typing`-Modul:
+* `list`
+* `tuple`
+* `set`
+* `dict`
- * `Union`
- * `Optional`
- * ... und andere.
+Verwenden Sie für den Rest, wie unter Python 3.8, das `typing`-Modul:
-=== "Python 3.8+"
+* `Union`
+* `Optional`
+* ... und andere.
- * `List`
- * `Tuple`
- * `Set`
- * `Dict`
- * `Union`
- * `Optional`
- * ... und andere.
+////
+
+//// tab | Python 3.8+
+
+* `List`
+* `Tuple`
+* `Set`
+* `Dict`
+* `Union`
+* `Optional`
+* ... und andere.
+
+////
### Klassen als Typen
@@ -414,15 +433,11 @@ Sie können auch eine Klasse als Typ einer Variablen deklarieren.
Nehmen wir an, Sie haben eine Klasse `Person`, mit einem Namen:
-```Python hl_lines="1-3"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
Dann können Sie eine Variable vom Typ `Person` deklarieren:
-```Python hl_lines="6"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[6] *}
Und wiederum bekommen Sie die volle Editor-Unterstützung:
@@ -446,55 +461,71 @@ Und Sie erhalten volle Editor-Unterstützung für dieses Objekt.
Ein Beispiel aus der offiziellen Pydantic Dokumentation:
-=== "Python 3.10+"
+//// tab | Python 3.10+
- ```Python
- {!> ../../../docs_src/python_types/tutorial011_py310.py!}
- ```
+```Python
+{!> ../../docs_src/python_types/tutorial011_py310.py!}
+```
-=== "Python 3.9+"
+////
- ```Python
- {!> ../../../docs_src/python_types/tutorial011_py39.py!}
- ```
+//// tab | Python 3.9+
-=== "Python 3.8+"
+```Python
+{!> ../../docs_src/python_types/tutorial011_py39.py!}
+```
- ```Python
- {!> ../../../docs_src/python_types/tutorial011.py!}
- ```
+////
-!!! info
- Um mehr über Pydantic zu erfahren, schauen Sie sich dessen Dokumentation an.
+//// tab | Python 3.8+
+
+```Python
+{!> ../../docs_src/python_types/tutorial011.py!}
+```
+
+////
+
+/// info
+
+Um mehr über Pydantic zu erfahren, schauen Sie sich dessen Dokumentation an.
+
+///
**FastAPI** basiert vollständig auf Pydantic.
Viel mehr von all dem werden Sie in praktischer Anwendung im [Tutorial - Benutzerhandbuch](tutorial/index.md){.internal-link target=_blank} sehen.
-!!! tip "Tipp"
- Pydantic verhält sich speziell, wenn Sie `Optional` oder `Union[Etwas, None]` ohne einen Default-Wert verwenden. Sie können darüber in der Pydantic Dokumentation unter Required fields mehr erfahren.
+/// tip | Tipp
+
+Pydantic verhält sich speziell, wenn Sie `Optional` oder `Union[Etwas, None]` ohne einen Default-Wert verwenden. Sie können darüber in der Pydantic Dokumentation unter Required fields mehr erfahren.
+
+///
## Typhinweise mit Metadaten-Annotationen
Python bietet auch die Möglichkeit, **zusätzliche Metadaten** in Typhinweisen unterzubringen, mittels `Annotated`.
-=== "Python 3.9+"
+//// tab | Python 3.9+
- In Python 3.9 ist `Annotated` ein Teil der Standardbibliothek, Sie können es von `typing` importieren.
+In Python 3.9 ist `Annotated` ein Teil der Standardbibliothek, Sie können es von `typing` importieren.
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial013_py39.py!}
- ```
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial013_py39.py!}
+```
-=== "Python 3.8+"
+////
- In Versionen niedriger als Python 3.9 importieren Sie `Annotated` von `typing_extensions`.
+//// tab | Python 3.8+
- Es wird bereits mit **FastAPI** installiert sein.
+In Versionen niedriger als Python 3.9 importieren Sie `Annotated` von `typing_extensions`.
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial013.py!}
- ```
+Es wird bereits mit **FastAPI** installiert sein.
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial013.py!}
+```
+
+////
Python selbst macht nichts mit `Annotated`. Für Editoren und andere Tools ist der Typ immer noch `str`.
@@ -506,10 +537,13 @@ Im Moment müssen Sie nur wissen, dass `Annotated` existiert, und dass es Standa
Später werden Sie sehen, wie **mächtig** es sein kann.
-!!! tip "Tipp"
- Der Umstand, dass es **Standard-Python** ist, bedeutet, dass Sie immer noch die **bestmögliche Entwickler-Erfahrung** in ihrem Editor haben, sowie mit den Tools, die Sie nutzen, um ihren Code zu analysieren, zu refaktorisieren, usw. ✨
+/// tip | Tipp
- Und ebenfalls, dass Ihr Code sehr kompatibel mit vielen anderen Python-Tools und -Bibliotheken sein wird. 🚀
+Der Umstand, dass es **Standard-Python** ist, bedeutet, dass Sie immer noch die **bestmögliche Entwickler-Erfahrung** in ihrem Editor haben, sowie mit den Tools, die Sie nutzen, um ihren Code zu analysieren, zu refaktorisieren, usw. ✨
+
+Und ebenfalls, dass Ihr Code sehr kompatibel mit vielen anderen Python-Tools und -Bibliotheken sein wird. 🚀
+
+///
## Typhinweise in **FastAPI**
@@ -533,5 +567,8 @@ Das mag alles abstrakt klingen. Machen Sie sich keine Sorgen. Sie werden all das
Das Wichtigste ist, dass **FastAPI** durch die Verwendung von Standard-Python-Typen an einer einzigen Stelle (anstatt weitere Klassen, Dekoratoren usw. hinzuzufügen) einen Großteil der Arbeit für Sie erledigt.
-!!! info
- Wenn Sie bereits das ganze Tutorial durchgearbeitet haben und mehr über Typen erfahren wollen, dann ist eine gute Ressource der „Cheat Sheet“ von `mypy`.
+/// info
+
+Wenn Sie bereits das ganze Tutorial durchgearbeitet haben und mehr über Typen erfahren wollen, dann ist eine gute Ressource der „Cheat Sheet“ von `mypy`.
+
+///
diff --git a/docs/de/docs/reference/apirouter.md b/docs/de/docs/reference/apirouter.md
deleted file mode 100644
index b0728b7df..000000000
--- a/docs/de/docs/reference/apirouter.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# `APIRouter`-Klasse
-
-Hier sind die Referenzinformationen für die Klasse `APIRouter` mit all ihren Parametern, Attributen und Methoden.
-
-Sie können die `APIRouter`-Klasse direkt von `fastapi` importieren:
-
-```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/de/docs/reference/background.md b/docs/de/docs/reference/background.md
deleted file mode 100644
index 0fd389325..000000000
--- a/docs/de/docs/reference/background.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# Hintergrundtasks – `BackgroundTasks`
-
-Sie können einen Parameter in einer *Pfadoperation-Funktion* oder einer Abhängigkeitsfunktion mit dem Typ `BackgroundTasks` deklarieren und diesen danach verwenden, um die Ausführung von Hintergrundtasks nach dem Senden der Response zu definieren.
-
-Sie können `BackgroundTasks` direkt von `fastapi` importieren:
-
-```python
-from fastapi import BackgroundTasks
-```
-
-::: fastapi.BackgroundTasks
diff --git a/docs/de/docs/reference/dependencies.md b/docs/de/docs/reference/dependencies.md
deleted file mode 100644
index 2ed5b5050..000000000
--- a/docs/de/docs/reference/dependencies.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# Abhängigkeiten – `Depends()` und `Security()`
-
-## `Depends()`
-
-Abhängigkeiten werden hauptsächlich mit der speziellen Funktion `Depends()` behandelt, die ein Callable entgegennimmt.
-
-Hier finden Sie deren Referenz und Parameter.
-
-Sie können sie direkt von `fastapi` importieren:
-
-```python
-from fastapi import Depends
-```
-
-::: fastapi.Depends
-
-## `Security()`
-
-In vielen Szenarien können Sie die Sicherheit (Autorisierung, Authentifizierung usw.) mit Abhängigkeiten handhaben, indem Sie `Depends()` verwenden.
-
-Wenn Sie jedoch auch OAuth2-Scopes deklarieren möchten, können Sie `Security()` anstelle von `Depends()` verwenden.
-
-Sie können `Security()` direkt von `fastapi` importieren:
-
-```python
-from fastapi import Security
-```
-
-::: fastapi.Security
diff --git a/docs/de/docs/reference/encoders.md b/docs/de/docs/reference/encoders.md
deleted file mode 100644
index 2489b8c60..000000000
--- a/docs/de/docs/reference/encoders.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Encoder – `jsonable_encoder`
-
-::: fastapi.encoders.jsonable_encoder
diff --git a/docs/de/docs/reference/exceptions.md b/docs/de/docs/reference/exceptions.md
deleted file mode 100644
index 230f902a9..000000000
--- a/docs/de/docs/reference/exceptions.md
+++ /dev/null
@@ -1,20 +0,0 @@
-# Exceptions – `HTTPException` und `WebSocketException`
-
-Dies sind die Exceptions, die Sie auslösen können, um dem Client Fehler zu berichten.
-
-Wenn Sie eine Exception auslösen, wird, wie es bei normalem Python der Fall wäre, der Rest der Ausführung abgebrochen. Auf diese Weise können Sie diese Exceptions von überall im Code werfen, um einen Request abzubrechen und den Fehler dem Client anzuzeigen.
-
-Sie können Folgendes verwenden:
-
-* `HTTPException`
-* `WebSocketException`
-
-Diese Exceptions können direkt von `fastapi` importiert werden:
-
-```python
-from fastapi import HTTPException, WebSocketException
-```
-
-::: fastapi.HTTPException
-
-::: fastapi.WebSocketException
diff --git a/docs/de/docs/reference/fastapi.md b/docs/de/docs/reference/fastapi.md
deleted file mode 100644
index 4e6a56971..000000000
--- a/docs/de/docs/reference/fastapi.md
+++ /dev/null
@@ -1,31 +0,0 @@
-# `FastAPI`-Klasse
-
-Hier sind die Referenzinformationen für die Klasse `FastAPI` mit all ihren Parametern, Attributen und Methoden.
-
-Sie können die `FastAPI`-Klasse direkt von `fastapi` importieren:
-
-```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/de/docs/reference/httpconnection.md b/docs/de/docs/reference/httpconnection.md
deleted file mode 100644
index 32a9696fa..000000000
--- a/docs/de/docs/reference/httpconnection.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# `HTTPConnection`-Klasse
-
-Wenn Sie Abhängigkeiten definieren möchten, die sowohl mit HTTP als auch mit WebSockets kompatibel sein sollen, können Sie einen Parameter definieren, der eine `HTTPConnection` anstelle eines `Request` oder eines `WebSocket` akzeptiert.
-
-Sie können diese von `fastapi.requests` importieren:
-
-```python
-from fastapi.requests import HTTPConnection
-```
-
-::: fastapi.requests.HTTPConnection
diff --git a/docs/de/docs/reference/index.md b/docs/de/docs/reference/index.md
deleted file mode 100644
index e9362b962..000000000
--- a/docs/de/docs/reference/index.md
+++ /dev/null
@@ -1,8 +0,0 @@
-# Referenz – Code-API
-
-Hier ist die Referenz oder Code-API, die Klassen, Funktionen, Parameter, Attribute und alle FastAPI-Teile, die Sie in Ihren Anwendungen verwenden können.
-
-Wenn Sie **FastAPI** lernen möchten, ist es viel besser, das [FastAPI-Tutorial](https://fastapi.tiangolo.com/tutorial/) zu lesen.
-
-!!! note "Hinweis Deutsche Übersetzung"
- Die nachfolgende API wird aus der Quelltext-Dokumentation erstellt, daher sind nur die Einleitungen auf Deutsch.
diff --git a/docs/de/docs/reference/middleware.md b/docs/de/docs/reference/middleware.md
deleted file mode 100644
index d8d2d50fc..000000000
--- a/docs/de/docs/reference/middleware.md
+++ /dev/null
@@ -1,45 +0,0 @@
-# Middleware
-
-Es gibt mehrere Middlewares, die direkt von Starlette bereitgestellt werden.
-
-Lesen Sie mehr darüber in der [FastAPI-Dokumentation über Middleware](../advanced/middleware.md).
-
-::: fastapi.middleware.cors.CORSMiddleware
-
-Kann von `fastapi` importiert werden:
-
-```python
-from fastapi.middleware.cors import CORSMiddleware
-```
-
-::: fastapi.middleware.gzip.GZipMiddleware
-
-Kann von `fastapi` importiert werden:
-
-```python
-from fastapi.middleware.gzip import GZipMiddleware
-```
-
-::: fastapi.middleware.httpsredirect.HTTPSRedirectMiddleware
-
-Kann von `fastapi` importiert werden:
-
-```python
-from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware
-```
-
-::: fastapi.middleware.trustedhost.TrustedHostMiddleware
-
-Kann von `fastapi` importiert werden:
-
-```python
-from fastapi.middleware.trustedhost import TrustedHostMiddleware
-```
-
-::: fastapi.middleware.wsgi.WSGIMiddleware
-
-Kann von `fastapi` importiert werden:
-
-```python
-from fastapi.middleware.wsgi import WSGIMiddleware
-```
diff --git a/docs/de/docs/reference/openapi/docs.md b/docs/de/docs/reference/openapi/docs.md
deleted file mode 100644
index 3c19ba917..000000000
--- a/docs/de/docs/reference/openapi/docs.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# OpenAPI `docs`
-
-Werkzeuge zur Verwaltung der automatischen OpenAPI-UI-Dokumentation, einschließlich Swagger UI (standardmäßig unter `/docs`) und ReDoc (standardmäßig unter `/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/de/docs/reference/openapi/index.md b/docs/de/docs/reference/openapi/index.md
deleted file mode 100644
index 0ae3d67c6..000000000
--- a/docs/de/docs/reference/openapi/index.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# OpenAPI
-
-Es gibt mehrere Werkzeuge zur Handhabung von OpenAPI.
-
-Normalerweise müssen Sie diese nicht verwenden, es sei denn, Sie haben einen bestimmten fortgeschrittenen Anwendungsfall, welcher das erfordert.
diff --git a/docs/de/docs/reference/openapi/models.md b/docs/de/docs/reference/openapi/models.md
deleted file mode 100644
index 64306b15f..000000000
--- a/docs/de/docs/reference/openapi/models.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# OpenAPI-`models`
-
-OpenAPI Pydantic-Modelle, werden zum Generieren und Validieren der generierten OpenAPI verwendet.
-
-::: fastapi.openapi.models
diff --git a/docs/de/docs/reference/parameters.md b/docs/de/docs/reference/parameters.md
deleted file mode 100644
index 2638eaf48..000000000
--- a/docs/de/docs/reference/parameters.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# Request-Parameter
-
-Hier die Referenzinformationen für die Request-Parameter.
-
-Dies sind die Sonderfunktionen, die Sie mittels `Annotated` in *Pfadoperation-Funktion*-Parameter oder Abhängigkeitsfunktionen einfügen können, um Daten aus dem Request abzurufen.
-
-Dies beinhaltet:
-
-* `Query()`
-* `Path()`
-* `Body()`
-* `Cookie()`
-* `Header()`
-* `Form()`
-* `File()`
-
-Sie können diese alle direkt von `fastapi` importieren:
-
-```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/de/docs/reference/request.md b/docs/de/docs/reference/request.md
deleted file mode 100644
index b170c1e40..000000000
--- a/docs/de/docs/reference/request.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# `Request`-Klasse
-
-Sie können einen Parameter in einer *Pfadoperation-Funktion* oder einer Abhängigkeit als vom Typ `Request` deklarieren und dann direkt auf das Requestobjekt zugreifen, ohne jegliche Validierung, usw.
-
-Sie können es direkt von `fastapi` importieren:
-
-```python
-from fastapi import Request
-```
-
-!!! tip "Tipp"
- Wenn Sie Abhängigkeiten definieren möchten, die sowohl mit HTTP als auch mit WebSockets kompatibel sein sollen, können Sie einen Parameter definieren, der eine `HTTPConnection` anstelle eines `Request` oder eines `WebSocket` akzeptiert.
-
-::: fastapi.Request
diff --git a/docs/de/docs/reference/response.md b/docs/de/docs/reference/response.md
deleted file mode 100644
index 215918931..000000000
--- a/docs/de/docs/reference/response.md
+++ /dev/null
@@ -1,13 +0,0 @@
-# `Response`-Klasse
-
-Sie können einen Parameter in einer *Pfadoperation-Funktion* oder einer Abhängigkeit als `Response` deklarieren und dann Daten für die Response wie Header oder Cookies festlegen.
-
-Diese können Sie auch direkt verwenden, um eine Instanz davon zu erstellen und diese von Ihren *Pfadoperationen* zurückzugeben.
-
-Sie können sie direkt von `fastapi` importieren:
-
-```python
-from fastapi import Response
-```
-
-::: fastapi.Response
diff --git a/docs/de/docs/reference/responses.md b/docs/de/docs/reference/responses.md
deleted file mode 100644
index c0e9f07e7..000000000
--- a/docs/de/docs/reference/responses.md
+++ /dev/null
@@ -1,164 +0,0 @@
-# Benutzerdefinierte Responseklassen – File, HTML, Redirect, Streaming, usw.
-
-Es gibt mehrere benutzerdefinierte Responseklassen, von denen Sie eine Instanz erstellen und diese direkt von Ihren *Pfadoperationen* zurückgeben können.
-
-Lesen Sie mehr darüber in der [FastAPI-Dokumentation zu benutzerdefinierten Responses – HTML, Stream, Datei, andere](../advanced/custom-response.md).
-
-Sie können diese direkt von `fastapi.responses` importieren:
-
-```python
-from fastapi.responses import (
- FileResponse,
- HTMLResponse,
- JSONResponse,
- ORJSONResponse,
- PlainTextResponse,
- RedirectResponse,
- Response,
- StreamingResponse,
- UJSONResponse,
-)
-```
-
-## FastAPI-Responses
-
-Es gibt einige benutzerdefinierte FastAPI-Responseklassen, welche Sie verwenden können, um die JSON-Performanz zu optimieren.
-
-::: 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/de/docs/reference/security/index.md b/docs/de/docs/reference/security/index.md
deleted file mode 100644
index 4c2375f2f..000000000
--- a/docs/de/docs/reference/security/index.md
+++ /dev/null
@@ -1,73 +0,0 @@
-# Sicherheitstools
-
-Wenn Sie Abhängigkeiten mit OAuth2-Scopes deklarieren müssen, verwenden Sie `Security()`.
-
-Aber Sie müssen immer noch definieren, was das Dependable, das Callable ist, welches Sie als Parameter an `Depends()` oder `Security()` übergeben.
-
-Es gibt mehrere Tools, mit denen Sie diese Dependables erstellen können, und sie werden in OpenAPI integriert, sodass sie in der Oberfläche der automatischen Dokumentation angezeigt werden und von automatisch generierten Clients und SDKs, usw., verwendet werden können.
-
-Sie können sie von `fastapi.security` importieren:
-
-```python
-from fastapi.security import (
- APIKeyCookie,
- APIKeyHeader,
- APIKeyQuery,
- HTTPAuthorizationCredentials,
- HTTPBasic,
- HTTPBasicCredentials,
- HTTPBearer,
- HTTPDigest,
- OAuth2,
- OAuth2AuthorizationCodeBearer,
- OAuth2PasswordBearer,
- OAuth2PasswordRequestForm,
- OAuth2PasswordRequestFormStrict,
- OpenIdConnect,
- SecurityScopes,
-)
-```
-
-## API-Schlüssel-Sicherheitsschemas
-
-::: fastapi.security.APIKeyCookie
-
-::: fastapi.security.APIKeyHeader
-
-::: fastapi.security.APIKeyQuery
-
-## HTTP-Authentifizierungsschemas
-
-::: fastapi.security.HTTPBasic
-
-::: fastapi.security.HTTPBearer
-
-::: fastapi.security.HTTPDigest
-
-## HTTP-Anmeldeinformationen
-
-::: fastapi.security.HTTPAuthorizationCredentials
-
-::: fastapi.security.HTTPBasicCredentials
-
-## OAuth2-Authentifizierung
-
-::: fastapi.security.OAuth2
-
-::: fastapi.security.OAuth2AuthorizationCodeBearer
-
-::: fastapi.security.OAuth2PasswordBearer
-
-## OAuth2-Passwortformulare
-
-::: fastapi.security.OAuth2PasswordRequestForm
-
-::: fastapi.security.OAuth2PasswordRequestFormStrict
-
-## OAuth2-Sicherheitsscopes in Abhängigkeiten
-
-::: fastapi.security.SecurityScopes
-
-## OpenID Connect
-
-::: fastapi.security.OpenIdConnect
diff --git a/docs/de/docs/reference/staticfiles.md b/docs/de/docs/reference/staticfiles.md
deleted file mode 100644
index 5629854c6..000000000
--- a/docs/de/docs/reference/staticfiles.md
+++ /dev/null
@@ -1,13 +0,0 @@
-# Statische Dateien – `StaticFiles`
-
-Sie können die `StaticFiles`-Klasse verwenden, um statische Dateien wie JavaScript, CSS, Bilder, usw. bereitzustellen.
-
-Lesen Sie mehr darüber in der [FastAPI-Dokumentation zu statischen Dateien](../tutorial/static-files.md).
-
-Sie können sie direkt von `fastapi.staticfiles` importieren:
-
-```python
-from fastapi.staticfiles import StaticFiles
-```
-
-::: fastapi.staticfiles.StaticFiles
diff --git a/docs/de/docs/reference/status.md b/docs/de/docs/reference/status.md
deleted file mode 100644
index 1d9458ee9..000000000
--- a/docs/de/docs/reference/status.md
+++ /dev/null
@@ -1,36 +0,0 @@
-# Statuscodes
-
-Sie können das Modul `status` von `fastapi` importieren:
-
-```python
-from fastapi import status
-```
-
-`status` wird direkt von Starlette bereitgestellt.
-
-Es enthält eine Gruppe benannter Konstanten (Variablen) mit ganzzahligen Statuscodes.
-
-Zum Beispiel:
-
-* 200: `status.HTTP_200_OK`
-* 403: `status.HTTP_403_FORBIDDEN`
-* usw.
-
-Es kann praktisch sein, schnell auf HTTP- (und WebSocket-)Statuscodes in Ihrer Anwendung zuzugreifen, indem Sie die automatische Vervollständigung für den Namen verwenden, ohne sich die Zahlen für die Statuscodes merken zu müssen.
-
-Lesen Sie mehr darüber in der [FastAPI-Dokumentation zu Response-Statuscodes](../tutorial/response-status-code.md).
-
-## Beispiel
-
-```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/de/docs/reference/templating.md b/docs/de/docs/reference/templating.md
deleted file mode 100644
index c367a0179..000000000
--- a/docs/de/docs/reference/templating.md
+++ /dev/null
@@ -1,13 +0,0 @@
-# Templating – `Jinja2Templates`
-
-Sie können die `Jinja2Templates`-Klasse verwenden, um Jinja-Templates zu rendern.
-
-Lesen Sie mehr darüber in der [FastAPI-Dokumentation zu Templates](../advanced/templates.md).
-
-Sie können die Klasse direkt von `fastapi.templating` importieren:
-
-```python
-from fastapi.templating import Jinja2Templates
-```
-
-::: fastapi.templating.Jinja2Templates
diff --git a/docs/de/docs/reference/testclient.md b/docs/de/docs/reference/testclient.md
deleted file mode 100644
index 5bc089c05..000000000
--- a/docs/de/docs/reference/testclient.md
+++ /dev/null
@@ -1,13 +0,0 @@
-# Testclient – `TestClient`
-
-Sie können die `TestClient`-Klasse verwenden, um FastAPI-Anwendungen zu testen, ohne eine tatsächliche HTTP- und Socket-Verbindung zu erstellen, Sie kommunizieren einfach direkt mit dem FastAPI-Code.
-
-Lesen Sie mehr darüber in der [FastAPI-Dokumentation über Testen](../tutorial/testing.md).
-
-Sie können sie direkt von `fastapi.testclient` importieren:
-
-```python
-from fastapi.testclient import TestClient
-```
-
-::: fastapi.testclient.TestClient
diff --git a/docs/de/docs/reference/uploadfile.md b/docs/de/docs/reference/uploadfile.md
deleted file mode 100644
index 8556edf82..000000000
--- a/docs/de/docs/reference/uploadfile.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# `UploadFile`-Klasse
-
-Sie können *Pfadoperation-Funktionsparameter* als Parameter vom Typ `UploadFile` definieren, um Dateien aus dem Request zu erhalten.
-
-Sie können es direkt von `fastapi` importieren:
-
-```python
-from fastapi import UploadFile
-```
-
-::: fastapi.UploadFile
- options:
- members:
- - file
- - filename
- - size
- - headers
- - content_type
- - read
- - write
- - seek
- - close
diff --git a/docs/de/docs/reference/websockets.md b/docs/de/docs/reference/websockets.md
deleted file mode 100644
index 35657172c..000000000
--- a/docs/de/docs/reference/websockets.md
+++ /dev/null
@@ -1,64 +0,0 @@
-# WebSockets
-
-Bei der Definition von WebSockets deklarieren Sie normalerweise einen Parameter vom Typ `WebSocket` und können damit Daten vom Client lesen und an ihn senden. Er wird direkt von Starlette bereitgestellt, Sie können ihn aber von `fastapi` importieren:
-
-```python
-from fastapi import WebSocket
-```
-
-!!! tip "Tipp"
- Wenn Sie Abhängigkeiten definieren möchten, die sowohl mit HTTP als auch mit WebSockets kompatibel sein sollen, können Sie einen Parameter definieren, der eine `HTTPConnection` anstelle eines `Request` oder eines `WebSocket` akzeptiert.
-
-::: 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
-
-Wenn ein Client die Verbindung trennt, wird eine `WebSocketDisconnect`-Exception ausgelöst, die Sie abfangen können.
-
-Sie können diese direkt von `fastapi` importieren:
-
-```python
-from fastapi import WebSocketDisconnect
-```
-
-::: fastapi.WebSocketDisconnect
-
-## WebSockets – zusätzliche Klassen
-
-Zusätzliche Klassen für die Handhabung von WebSockets.
-
-Werden direkt von Starlette bereitgestellt, Sie können sie jedoch von `fastapi` importieren:
-
-```python
-from fastapi.websockets import WebSocketDisconnect, WebSocketState
-```
-
-::: fastapi.websockets.WebSocketDisconnect
-
-::: fastapi.websockets.WebSocketState
diff --git a/docs/de/docs/tutorial/background-tasks.md b/docs/de/docs/tutorial/background-tasks.md
index a7bfd55a7..05779e12c 100644
--- a/docs/de/docs/tutorial/background-tasks.md
+++ b/docs/de/docs/tutorial/background-tasks.md
@@ -15,9 +15,7 @@ Hierzu zählen beispielsweise:
Importieren Sie zunächst `BackgroundTasks` und definieren Sie einen Parameter in Ihrer *Pfadoperation-Funktion* mit der Typdeklaration `BackgroundTasks`:
-```Python hl_lines="1 13"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *}
**FastAPI** erstellt für Sie das Objekt vom Typ `BackgroundTasks` und übergibt es als diesen Parameter.
@@ -33,17 +31,13 @@ In diesem Fall schreibt die Taskfunktion in eine Datei (den Versand einer E-Mail
Und da der Schreibvorgang nicht `async` und `await` verwendet, definieren wir die Funktion mit normalem `def`:
-```Python hl_lines="6-9"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *}
## Den Hintergrundtask hinzufügen
Übergeben Sie innerhalb Ihrer *Pfadoperation-Funktion* Ihre Taskfunktion mit der Methode `.add_task()` an das *Hintergrundtasks*-Objekt:
-```Python hl_lines="14"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[14] *}
`.add_task()` erhält als Argumente:
@@ -57,41 +51,7 @@ Die Verwendung von `BackgroundTasks` funktioniert auch mit dem ../../../docs_src/background_tasks/tutorial002_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="13 15 22 25"
- {!> ../../../docs_src/background_tasks/tutorial002_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="14 16 23 26"
- {!> ../../../docs_src/background_tasks/tutorial002_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="11 13 20 23"
- {!> ../../../docs_src/background_tasks/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="13 15 22 25"
- {!> ../../../docs_src/background_tasks/tutorial002.py!}
- ```
+{* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *}
In obigem Beispiel werden die Nachrichten, *nachdem* die Response gesendet wurde, in die Datei `log.txt` geschrieben.
@@ -117,8 +77,6 @@ Wenn Sie umfangreiche Hintergrundberechnungen durchführen müssen und diese nic
Sie erfordern in der Regel komplexere Konfigurationen und einen Nachrichten-/Job-Queue-Manager wie RabbitMQ oder Redis, ermöglichen Ihnen jedoch die Ausführung von Hintergrundtasks in mehreren Prozessen und insbesondere auf mehreren Servern.
-Um ein Beispiel zu sehen, sehen Sie sich die [Projektgeneratoren](../project-generation.md){.internal-link target=_blank} an. Sie alle enthalten Celery, bereits konfiguriert.
-
Wenn Sie jedoch über dieselbe **FastAPI**-Anwendung auf Variablen und Objekte zugreifen oder kleine Hintergrundtasks ausführen müssen (z. B. das Senden einer E-Mail-Benachrichtigung), können Sie einfach `BackgroundTasks` verwenden.
## Zusammenfassung
diff --git a/docs/de/docs/tutorial/bigger-applications.md b/docs/de/docs/tutorial/bigger-applications.md
index 66dee0a9a..514e3fd3a 100644
--- a/docs/de/docs/tutorial/bigger-applications.md
+++ b/docs/de/docs/tutorial/bigger-applications.md
@@ -4,8 +4,11 @@ Wenn Sie eine Anwendung oder eine Web-API erstellen, ist es selten der Fall, das
**FastAPI** bietet ein praktisches Werkzeug zur Strukturierung Ihrer Anwendung bei gleichzeitiger Wahrung der Flexibilität.
-!!! info
- Wenn Sie von Flask kommen, wäre dies das Äquivalent zu Flasks Blueprints.
+/// info
+
+Wenn Sie von Flask kommen, wäre dies das Äquivalent zu Flasks Blueprints.
+
+///
## Eine Beispiel-Dateistruktur
@@ -26,16 +29,19 @@ Nehmen wir an, Sie haben eine Dateistruktur wie diese:
│ └── admin.py
```
-!!! tip "Tipp"
- Es gibt mehrere `__init__.py`-Dateien: eine in jedem Verzeichnis oder Unterverzeichnis.
+/// tip | Tipp
- Das ermöglicht den Import von Code aus einer Datei in eine andere.
+Es gibt mehrere `__init__.py`-Dateien: eine in jedem Verzeichnis oder Unterverzeichnis.
- In `app/main.py` könnten Sie beispielsweise eine Zeile wie diese haben:
+Das ermöglicht den Import von Code aus einer Datei in eine andere.
- ```
- from app.routers import items
- ```
+In `app/main.py` könnten Sie beispielsweise eine Zeile wie diese haben:
+
+```
+from app.routers import items
+```
+
+///
* Das Verzeichnis `app` enthält alles. Und es hat eine leere Datei `app/__init__.py`, es handelt sich also um ein „Python-Package“ (eine Sammlung von „Python-Modulen“): `app`.
* Es enthält eine Datei `app/main.py`. Da sie sich in einem Python-Package (einem Verzeichnis mit einer Datei `__init__.py`) befindet, ist sie ein „Modul“ dieses Packages: `app.main`.
@@ -46,7 +52,7 @@ Nehmen wir an, Sie haben eine Dateistruktur wie diese:
* Es gibt auch ein Unterverzeichnis `app/internal/` mit einer weiteren Datei `__init__.py`, es handelt sich also um ein weiteres „Python-Subpackage“: `app.internal`.
* Und die Datei `app/internal/admin.py` ist ein weiteres Submodul: `app.internal.admin`.
-
+
Die gleiche Dateistruktur mit Kommentaren:
@@ -80,7 +86,7 @@ Sie können die *Pfadoperationen* für dieses Modul mit `APIRouter` erstellen.
Sie importieren ihn und erstellen eine „Instanz“ auf die gleiche Weise wie mit der Klasse `FastAPI`:
```Python hl_lines="1 3" title="app/routers/users.py"
-{!../../../docs_src/bigger_applications/app/routers/users.py!}
+{!../../docs_src/bigger_applications/app/routers/users.py!}
```
### *Pfadoperationen* mit `APIRouter`
@@ -90,7 +96,7 @@ Und dann verwenden Sie ihn, um Ihre *Pfadoperationen* zu deklarieren.
Verwenden Sie ihn auf die gleiche Weise wie die Klasse `FastAPI`:
```Python hl_lines="6 11 16" title="app/routers/users.py"
-{!../../../docs_src/bigger_applications/app/routers/users.py!}
+{!../../docs_src/bigger_applications/app/routers/users.py!}
```
Sie können sich `APIRouter` als eine „Mini-`FastAPI`“-Klasse vorstellen.
@@ -99,8 +105,11 @@ Alle die gleichen Optionen werden unterstützt.
Alle die gleichen `parameters`, `responses`, `dependencies`, `tags`, usw.
-!!! tip "Tipp"
- In diesem Beispiel heißt die Variable `router`, aber Sie können ihr einen beliebigen Namen geben.
+/// tip | Tipp
+
+In diesem Beispiel heißt die Variable `router`, aber Sie können ihr einen beliebigen Namen geben.
+
+///
Wir werden diesen `APIRouter` in die Hauptanwendung `FastAPI` einbinden, aber zuerst kümmern wir uns um die Abhängigkeiten und einen anderen `APIRouter`.
@@ -112,31 +121,43 @@ Also fügen wir sie in ihr eigenes `dependencies`-Modul (`app/dependencies.py`)
Wir werden nun eine einfache Abhängigkeit verwenden, um einen benutzerdefinierten `X-Token`-Header zu lesen:
-=== "Python 3.9+"
+//// tab | Python 3.9+
- ```Python hl_lines="3 6-8" title="app/dependencies.py"
- {!> ../../../docs_src/bigger_applications/app_an_py39/dependencies.py!}
- ```
+```Python hl_lines="3 6-8" title="app/dependencies.py"
+{!> ../../docs_src/bigger_applications/app_an_py39/dependencies.py!}
+```
-=== "Python 3.8+"
+////
- ```Python hl_lines="1 5-7" title="app/dependencies.py"
- {!> ../../../docs_src/bigger_applications/app_an/dependencies.py!}
- ```
+//// tab | Python 3.8+
-=== "Python 3.8+ nicht annotiert"
+```Python hl_lines="1 5-7" title="app/dependencies.py"
+{!> ../../docs_src/bigger_applications/app_an/dependencies.py!}
+```
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
+////
- ```Python hl_lines="1 4-6" title="app/dependencies.py"
- {!> ../../../docs_src/bigger_applications/app/dependencies.py!}
- ```
+//// tab | Python 3.8+ nicht annotiert
-!!! tip "Tipp"
- Um dieses Beispiel zu vereinfachen, verwenden wir einen erfundenen Header.
+/// tip | Tipp
- Aber in der Praxis werden Sie mit den integrierten [Sicherheits-Werkzeugen](security/index.md){.internal-link target=_blank} bessere Ergebnisse erzielen.
+Bevorzugen Sie die `Annotated`-Version, falls möglich.
+
+///
+
+```Python hl_lines="1 4-6" title="app/dependencies.py"
+{!> ../../docs_src/bigger_applications/app/dependencies.py!}
+```
+
+////
+
+/// tip | Tipp
+
+Um dieses Beispiel zu vereinfachen, verwenden wir einen erfundenen Header.
+
+Aber in der Praxis werden Sie mit den integrierten [Sicherheits-Werkzeugen](security/index.md){.internal-link target=_blank} bessere Ergebnisse erzielen.
+
+///
## Ein weiteres Modul mit `APIRouter`.
@@ -161,7 +182,7 @@ Wir wissen, dass alle *Pfadoperationen* in diesem Modul folgendes haben:
Anstatt also alles zu jeder *Pfadoperation* hinzuzufügen, können wir es dem `APIRouter` hinzufügen.
```Python hl_lines="5-10 16 21" title="app/routers/items.py"
-{!../../../docs_src/bigger_applications/app/routers/items.py!}
+{!../../docs_src/bigger_applications/app/routers/items.py!}
```
Da der Pfad jeder *Pfadoperation* mit `/` beginnen muss, wie in:
@@ -180,8 +201,11 @@ Wir können auch eine Liste von `tags` und zusätzliche `responses` hinzufügen,
Und wir können eine Liste von `dependencies` hinzufügen, die allen *Pfadoperationen* im Router hinzugefügt und für jeden an sie gerichteten Request ausgeführt/aufgelöst werden.
-!!! tip "Tipp"
- Beachten Sie, dass ähnlich wie bei [Abhängigkeiten in *Pfadoperation-Dekoratoren*](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank} kein Wert an Ihre *Pfadoperation-Funktion* übergeben wird.
+/// tip | Tipp
+
+Beachten Sie, dass ähnlich wie bei [Abhängigkeiten in *Pfadoperation-Dekoratoren*](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank} kein Wert an Ihre *Pfadoperation-Funktion* übergeben wird.
+
+///
Das Endergebnis ist, dass die Pfade für diese Artikel jetzt wie folgt lauten:
@@ -198,11 +222,17 @@ Das Endergebnis ist, dass die Pfade für diese Artikel jetzt wie folgt lauten:
* Zuerst werden die Router-Abhängigkeiten ausgeführt, dann die [`dependencies` im Dekorator](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank} und dann die normalen Parameterabhängigkeiten.
* Sie können auch [`Security`-Abhängigkeiten mit `scopes`](../advanced/security/oauth2-scopes.md){.internal-link target=_blank} hinzufügen.
-!!! tip "Tipp"
- `dependencies` im `APIRouter` können beispielsweise verwendet werden, um eine Authentifizierung für eine ganze Gruppe von *Pfadoperationen* zu erfordern. Selbst wenn die Abhängigkeiten nicht jeder einzeln hinzugefügt werden.
+/// tip | Tipp
-!!! check
- Die Parameter `prefix`, `tags`, `responses` und `dependencies` sind (wie in vielen anderen Fällen) nur ein Feature von **FastAPI**, um Ihnen dabei zu helfen, Codeverdoppelung zu vermeiden.
+`dependencies` im `APIRouter` können beispielsweise verwendet werden, um eine Authentifizierung für eine ganze Gruppe von *Pfadoperationen* zu erfordern. Selbst wenn die Abhängigkeiten nicht jeder einzeln hinzugefügt werden.
+
+///
+
+/// check
+
+Die Parameter `prefix`, `tags`, `responses` und `dependencies` sind (wie in vielen anderen Fällen) nur ein Feature von **FastAPI**, um Ihnen dabei zu helfen, Codeverdoppelung zu vermeiden.
+
+///
### Die Abhängigkeiten importieren
@@ -213,13 +243,16 @@ Und wir müssen die Abhängigkeitsfunktion aus dem Modul `app.dependencies` impo
Daher verwenden wir einen relativen Import mit `..` für die Abhängigkeiten:
```Python hl_lines="3" title="app/routers/items.py"
-{!../../../docs_src/bigger_applications/app/routers/items.py!}
+{!../../docs_src/bigger_applications/app/routers/items.py!}
```
#### Wie relative Importe funktionieren
-!!! tip "Tipp"
- Wenn Sie genau wissen, wie Importe funktionieren, fahren Sie mit dem nächsten Abschnitt unten fort.
+/// tip | Tipp
+
+Wenn Sie genau wissen, wie Importe funktionieren, fahren Sie mit dem nächsten Abschnitt unten fort.
+
+///
Ein einzelner Punkt `.`, wie in:
@@ -237,7 +270,7 @@ Aber diese Datei existiert nicht, unsere Abhängigkeiten befinden sich in einer
Erinnern Sie sich, wie unsere Anwendungs-/Dateistruktur aussieht:
-
+
---
@@ -283,13 +316,16 @@ Wir fügen weder das Präfix `/items` noch `tags=["items"]` zu jeder *Pfadoperat
Aber wir können immer noch _mehr_ `tags` hinzufügen, die auf eine bestimmte *Pfadoperation* angewendet werden, sowie einige zusätzliche `responses`, die speziell für diese *Pfadoperation* gelten:
```Python hl_lines="30-31" title="app/routers/items.py"
-{!../../../docs_src/bigger_applications/app/routers/items.py!}
+{!../../docs_src/bigger_applications/app/routers/items.py!}
```
-!!! tip "Tipp"
- Diese letzte Pfadoperation wird eine Kombination von Tags haben: `["items", "custom"]`.
+/// tip | Tipp
- Und sie wird auch beide Responses in der Dokumentation haben, eine für `404` und eine für `403`.
+Diese letzte Pfadoperation wird eine Kombination von Tags haben: `["items", "custom"]`.
+
+Und sie wird auch beide Responses in der Dokumentation haben, eine für `404` und eine für `403`.
+
+///
## Das Haupt-`FastAPI`.
@@ -308,7 +344,7 @@ Sie importieren und erstellen wie gewohnt eine `FastAPI`-Klasse.
Und wir können sogar [globale Abhängigkeiten](dependencies/global-dependencies.md){.internal-link target=_blank} deklarieren, die mit den Abhängigkeiten für jeden `APIRouter` kombiniert werden:
```Python hl_lines="1 3 7" title="app/main.py"
-{!../../../docs_src/bigger_applications/app/main.py!}
+{!../../docs_src/bigger_applications/app/main.py!}
```
### Den `APIRouter` importieren
@@ -316,7 +352,7 @@ Und wir können sogar [globale Abhängigkeiten](dependencies/global-dependencies
Jetzt importieren wir die anderen Submodule, die `APIRouter` haben:
```Python hl_lines="4-5" title="app/main.py"
-{!../../../docs_src/bigger_applications/app/main.py!}
+{!../../docs_src/bigger_applications/app/main.py!}
```
Da es sich bei den Dateien `app/routers/users.py` und `app/routers/items.py` um Submodule handelt, die Teil desselben Python-Packages `app` sind, können wir einen einzelnen Punkt `.` verwenden, um sie mit „relativen Imports“ zu importieren.
@@ -345,20 +381,23 @@ Wir könnten sie auch wie folgt importieren:
from app.routers import items, users
```
-!!! info
- Die erste Version ist ein „relativer Import“:
+/// info
- ```Python
- from .routers import items, users
- ```
+Die erste Version ist ein „relativer Import“:
- Die zweite Version ist ein „absoluter Import“:
+```Python
+from .routers import items, users
+```
- ```Python
- from app.routers import items, users
- ```
+Die zweite Version ist ein „absoluter Import“:
- Um mehr über Python-Packages und -Module zu erfahren, lesen Sie die offizielle Python-Dokumentation über Module.
+```Python
+from app.routers import items, users
+```
+
+Um mehr über Python-Packages und -Module zu erfahren, lesen Sie die offizielle Python-Dokumentation über Module.
+
+///
### Namenskollisionen vermeiden
@@ -378,7 +417,7 @@ würde der `router` von `users` den von `items` überschreiben und wir könnten
Um also beide in derselben Datei verwenden zu können, importieren wir die Submodule direkt:
```Python hl_lines="5" title="app/main.py"
-{!../../../docs_src/bigger_applications/app/main.py!}
+{!../../docs_src/bigger_applications/app/main.py!}
```
@@ -387,29 +426,38 @@ Um also beide in derselben Datei verwenden zu können, importieren wir die Submo
Inkludieren wir nun die `router` aus diesen Submodulen `users` und `items`:
```Python hl_lines="10-11" title="app/main.py"
-{!../../../docs_src/bigger_applications/app/main.py!}
+{!../../docs_src/bigger_applications/app/main.py!}
```
-!!! info
- `users.router` enthält den `APIRouter` in der Datei `app/routers/users.py`.
+/// info
- Und `items.router` enthält den `APIRouter` in der Datei `app/routers/items.py`.
+`users.router` enthält den `APIRouter` in der Datei `app/routers/users.py`.
+
+Und `items.router` enthält den `APIRouter` in der Datei `app/routers/items.py`.
+
+///
Mit `app.include_router()` können wir jeden `APIRouter` zur Hauptanwendung `FastAPI` hinzufügen.
Es wird alle Routen von diesem Router als Teil von dieser inkludieren.
-!!! note "Technische Details"
- Tatsächlich wird intern eine *Pfadoperation* für jede *Pfadoperation* erstellt, die im `APIRouter` deklariert wurde.
+/// note | Technische Details
- Hinter den Kulissen wird es also tatsächlich so funktionieren, als ob alles dieselbe einzige Anwendung wäre.
+Tatsächlich wird intern eine *Pfadoperation* für jede *Pfadoperation* erstellt, die im `APIRouter` deklariert wurde.
-!!! check
- Bei der Einbindung von Routern müssen Sie sich keine Gedanken über die Performanz machen.
+Hinter den Kulissen wird es also tatsächlich so funktionieren, als ob alles dieselbe einzige Anwendung wäre.
- Dies dauert Mikrosekunden und geschieht nur beim Start.
+///
- Es hat also keinen Einfluss auf die Leistung. ⚡
+/// check
+
+Bei der Einbindung von Routern müssen Sie sich keine Gedanken über die Performanz machen.
+
+Dies dauert Mikrosekunden und geschieht nur beim Start.
+
+Es hat also keinen Einfluss auf die Leistung. ⚡
+
+///
### Einen `APIRouter` mit benutzerdefinierten `prefix`, `tags`, `responses` und `dependencies` einfügen
@@ -420,7 +468,7 @@ Sie enthält einen `APIRouter` mit einigen administrativen *Pfadoperationen*, di
In diesem Beispiel wird es ganz einfach sein. Nehmen wir jedoch an, dass wir, da sie mit anderen Projekten in der Organisation geteilt wird, sie nicht ändern und kein `prefix`, `dependencies`, `tags`, usw. direkt zum `APIRouter` hinzufügen können:
```Python hl_lines="3" title="app/internal/admin.py"
-{!../../../docs_src/bigger_applications/app/internal/admin.py!}
+{!../../docs_src/bigger_applications/app/internal/admin.py!}
```
Aber wir möchten immer noch ein benutzerdefiniertes `prefix` festlegen, wenn wir den `APIRouter` einbinden, sodass alle seine *Pfadoperationen* mit `/admin` beginnen, wir möchten es mit den `dependencies` sichern, die wir bereits für dieses Projekt haben, und wir möchten `tags` und `responses` hinzufügen.
@@ -428,7 +476,7 @@ Aber wir möchten immer noch ein benutzerdefiniertes `prefix` festlegen, wenn wi
Wir können das alles deklarieren, ohne den ursprünglichen `APIRouter` ändern zu müssen, indem wir diese Parameter an `app.include_router()` übergeben:
```Python hl_lines="14-17" title="app/main.py"
-{!../../../docs_src/bigger_applications/app/main.py!}
+{!../../docs_src/bigger_applications/app/main.py!}
```
Auf diese Weise bleibt der ursprüngliche `APIRouter` unverändert, sodass wir dieselbe `app/internal/admin.py`-Datei weiterhin mit anderen Projekten in der Organisation teilen können.
@@ -451,21 +499,24 @@ Wir können *Pfadoperationen* auch direkt zur `FastAPI`-App hinzufügen.
Hier machen wir es ... nur um zu zeigen, dass wir es können 🤷:
```Python hl_lines="21-23" title="app/main.py"
-{!../../../docs_src/bigger_applications/app/main.py!}
+{!../../docs_src/bigger_applications/app/main.py!}
```
und es wird korrekt funktionieren, zusammen mit allen anderen *Pfadoperationen*, die mit `app.include_router()` hinzugefügt wurden.
-!!! info "Sehr technische Details"
- **Hinweis**: Dies ist ein sehr technisches Detail, das Sie wahrscheinlich **einfach überspringen** können.
+/// info | Sehr technische Details
- ---
+**Hinweis**: Dies ist ein sehr technisches Detail, das Sie wahrscheinlich **einfach überspringen** können.
- Die `APIRouter` sind nicht „gemountet“, sie sind nicht vom Rest der Anwendung isoliert.
+---
- Das liegt daran, dass wir deren *Pfadoperationen* in das OpenAPI-Schema und die Benutzeroberflächen einbinden möchten.
+Die `APIRouter` sind nicht „gemountet“, sie sind nicht vom Rest der Anwendung isoliert.
- Da wir sie nicht einfach isolieren und unabhängig vom Rest „mounten“ können, werden die *Pfadoperationen* „geklont“ (neu erstellt) und nicht direkt einbezogen.
+Das liegt daran, dass wir deren *Pfadoperationen* in das OpenAPI-Schema und die Benutzeroberflächen einbinden möchten.
+
+Da wir sie nicht einfach isolieren und unabhängig vom Rest „mounten“ können, werden die *Pfadoperationen* „geklont“ (neu erstellt) und nicht direkt einbezogen.
+
+///
## Es in der automatischen API-Dokumentation ansehen
diff --git a/docs/de/docs/tutorial/body-fields.md b/docs/de/docs/tutorial/body-fields.md
index 643be7489..9fddfb1f0 100644
--- a/docs/de/docs/tutorial/body-fields.md
+++ b/docs/de/docs/tutorial/body-fields.md
@@ -6,98 +6,39 @@ So wie Sie zusätzliche Validation und Metadaten in Parametern der **Pfadoperati
Importieren Sie es zuerst:
-=== "Python 3.10+"
+{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[4] *}
- ```Python hl_lines="4"
- {!> ../../../docs_src/body_fields/tutorial001_an_py310.py!}
- ```
+/// warning | Achtung
-=== "Python 3.9+"
+Beachten Sie, dass `Field` direkt von `pydantic` importiert wird, nicht von `fastapi`, wie die anderen (`Query`, `Path`, `Body`, usw.)
- ```Python hl_lines="4"
- {!> ../../../docs_src/body_fields/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="4"
- {!> ../../../docs_src/body_fields/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="2"
- {!> ../../../docs_src/body_fields/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="4"
- {!> ../../../docs_src/body_fields/tutorial001.py!}
- ```
-
-!!! warning "Achtung"
- Beachten Sie, dass `Field` direkt von `pydantic` importiert wird, nicht von `fastapi`, wie die anderen (`Query`, `Path`, `Body`, usw.)
+///
## Modellattribute deklarieren
Dann können Sie `Field` mit Modellattributen deklarieren:
-=== "Python 3.10+"
-
- ```Python hl_lines="11-14"
- {!> ../../../docs_src/body_fields/tutorial001_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="11-14"
- {!> ../../../docs_src/body_fields/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="12-15"
- {!> ../../../docs_src/body_fields/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="9-12"
- {!> ../../../docs_src/body_fields/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="11-14"
- {!> ../../../docs_src/body_fields/tutorial001.py!}
- ```
+{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[11:14] *}
`Field` funktioniert genauso wie `Query`, `Path` und `Body`, es hat die gleichen Parameter, usw.
-!!! note "Technische Details"
- Tatsächlich erstellen `Query`, `Path` und andere, die sie kennenlernen werden, Instanzen von Unterklassen einer allgemeinen Klasse `Param`, die ihrerseits eine Unterklasse von Pydantics `FieldInfo`-Klasse ist.
+/// note | Technische Details
- Und Pydantics `Field` gibt ebenfalls eine Instanz von `FieldInfo` zurück.
+Tatsächlich erstellen `Query`, `Path` und andere, die sie kennenlernen werden, Instanzen von Unterklassen einer allgemeinen Klasse `Param`, die ihrerseits eine Unterklasse von Pydantics `FieldInfo`-Klasse ist.
- `Body` gibt auch Instanzen einer Unterklasse von `FieldInfo` zurück. Und später werden Sie andere sehen, die Unterklassen der `Body`-Klasse sind.
+Und Pydantics `Field` gibt ebenfalls eine Instanz von `FieldInfo` zurück.
- Denken Sie daran, dass `Query`, `Path` und andere von `fastapi` tatsächlich Funktionen sind, die spezielle Klassen zurückgeben.
+`Body` gibt auch Instanzen einer Unterklasse von `FieldInfo` zurück. Und später werden Sie andere sehen, die Unterklassen der `Body`-Klasse sind.
-!!! tip "Tipp"
- Beachten Sie, dass jedes Modellattribut mit einem Typ, Defaultwert und `Field` die gleiche Struktur hat wie ein Parameter einer Pfadoperation-Funktion, nur mit `Field` statt `Path`, `Query`, `Body`.
+Denken Sie daran, dass `Query`, `Path` und andere von `fastapi` tatsächlich Funktionen sind, die spezielle Klassen zurückgeben.
+
+///
+
+/// tip | Tipp
+
+Beachten Sie, dass jedes Modellattribut mit einem Typ, Defaultwert und `Field` die gleiche Struktur hat wie ein Parameter einer Pfadoperation-Funktion, nur mit `Field` statt `Path`, `Query`, `Body`.
+
+///
## Zusätzliche Information hinzufügen
@@ -105,8 +46,11 @@ Sie können zusätzliche Information in `Field`, `Query`, `Body`, usw. deklarier
Sie werden später mehr darüber lernen, wie man zusätzliche Information unterbringt, wenn Sie lernen, Beispiele zu deklarieren.
-!!! warning "Achtung"
- Extra-Schlüssel, die `Field` überreicht werden, werden auch im resultierenden OpenAPI-Schema Ihrer Anwendung gelistet. Da diese Schlüssel nicht notwendigerweise Teil der OpenAPI-Spezifikation sind, könnten einige OpenAPI-Tools, wie etwa [der OpenAPI-Validator](https://validator.swagger.io/), nicht mit Ihrem generierten Schema funktionieren.
+/// warning | Achtung
+
+Extra-Schlüssel, die `Field` überreicht werden, werden auch im resultierenden OpenAPI-Schema Ihrer Anwendung gelistet. Da diese Schlüssel nicht notwendigerweise Teil der OpenAPI-Spezifikation sind, könnten einige OpenAPI-Tools, wie etwa [der OpenAPI-Validator](https://validator.swagger.io/), nicht mit Ihrem generierten Schema funktionieren.
+
+///
## Zusammenfassung
diff --git a/docs/de/docs/tutorial/body-multiple-params.md b/docs/de/docs/tutorial/body-multiple-params.md
index 6a237243e..8a9978d34 100644
--- a/docs/de/docs/tutorial/body-multiple-params.md
+++ b/docs/de/docs/tutorial/body-multiple-params.md
@@ -8,44 +8,13 @@ Zuerst einmal, Sie können `Path`-, `Query`- und Requestbody-Parameter-Deklarati
Und Sie können auch Body-Parameter als optional kennzeichnen, indem Sie den Defaultwert auf `None` setzen:
-=== "Python 3.10+"
+{* ../../docs_src/body_multiple_params/tutorial001_an_py310.py hl[18:20] *}
- ```Python hl_lines="18-20"
- {!> ../../../docs_src/body_multiple_params/tutorial001_an_py310.py!}
- ```
+/// note | Hinweis
-=== "Python 3.9+"
+Beachten Sie, dass in diesem Fall das `item`, welches vom Body genommen wird, optional ist. Da es `None` als Defaultwert hat.
- ```Python hl_lines="18-20"
- {!> ../../../docs_src/body_multiple_params/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="19-21"
- {!> ../../../docs_src/body_multiple_params/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="17-19"
- {!> ../../../docs_src/body_multiple_params/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="19-21"
- {!> ../../../docs_src/body_multiple_params/tutorial001.py!}
- ```
-
-!!! note "Hinweis"
- Beachten Sie, dass in diesem Fall das `item`, welches vom Body genommen wird, optional ist. Da es `None` als Defaultwert hat.
+///
## Mehrere Body-Parameter
@@ -62,17 +31,7 @@ Im vorherigen Beispiel erwartete die *Pfadoperation* einen JSON-Body mit den Att
Aber Sie können auch mehrere Body-Parameter deklarieren, z. B. `item` und `user`:
-=== "Python 3.10+"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_multiple_params/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/body_multiple_params/tutorial002.py!}
- ```
+{* ../../docs_src/body_multiple_params/tutorial002_py310.py hl[20] *}
In diesem Fall wird **FastAPI** bemerken, dass es mehr als einen Body-Parameter in der Funktion gibt (zwei Parameter, die Pydantic-Modelle sind).
@@ -93,8 +52,11 @@ Es wird deshalb die Parameternamen als Schlüssel (Feldnamen) im Body verwenden,
}
```
-!!! note "Hinweis"
- Beachten Sie, dass, obwohl `item` wie zuvor deklariert wurde, es nun unter einem Schlüssel `item` im Body erwartet wird.
+/// note | Hinweis
+
+Beachten Sie, dass, obwohl `item` wie zuvor deklariert wurde, es nun unter einem Schlüssel `item` im Body erwartet wird.
+
+///
**FastAPI** wird die automatische Konvertierung des Requests übernehmen, sodass der Parameter `item` seinen spezifischen Inhalt bekommt, genau so wie der Parameter `user`.
@@ -110,41 +72,7 @@ Wenn Sie diesen Parameter einfach so hinzufügen, wird **FastAPI** annehmen, das
Aber Sie können **FastAPI** instruieren, ihn als weiteren Body-Schlüssel zu erkennen, indem Sie `Body` verwenden:
-=== "Python 3.10+"
-
- ```Python hl_lines="23"
- {!> ../../../docs_src/body_multiple_params/tutorial003_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="23"
- {!> ../../../docs_src/body_multiple_params/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="24"
- {!> ../../../docs_src/body_multiple_params/tutorial003_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_multiple_params/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/body_multiple_params/tutorial003.py!}
- ```
+{* ../../docs_src/body_multiple_params/tutorial003_an_py310.py hl[23] *}
In diesem Fall erwartet **FastAPI** einen Body wie:
@@ -184,44 +112,13 @@ q: str | None = None
Zum Beispiel:
-=== "Python 3.10+"
+{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[27] *}
- ```Python hl_lines="27"
- {!> ../../../docs_src/body_multiple_params/tutorial004_an_py310.py!}
- ```
+/// info
-=== "Python 3.9+"
+`Body` hat die gleichen zusätzlichen Validierungs- und Metadaten-Parameter wie `Query` und `Path` und andere, die Sie später kennenlernen.
- ```Python hl_lines="27"
- {!> ../../../docs_src/body_multiple_params/tutorial004_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="28"
- {!> ../../../docs_src/body_multiple_params/tutorial004_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="25"
- {!> ../../../docs_src/body_multiple_params/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="27"
- {!> ../../../docs_src/body_multiple_params/tutorial004.py!}
- ```
-
-!!! info
- `Body` hat die gleichen zusätzlichen Validierungs- und Metadaten-Parameter wie `Query` und `Path` und andere, die Sie später kennenlernen.
+///
## Einen einzelnen Body-Parameter einbetten
@@ -237,41 +134,7 @@ item: Item = Body(embed=True)
so wie in:
-=== "Python 3.10+"
-
- ```Python hl_lines="17"
- {!> ../../../docs_src/body_multiple_params/tutorial005_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="17"
- {!> ../../../docs_src/body_multiple_params/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body_multiple_params/tutorial005_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="15"
- {!> ../../../docs_src/body_multiple_params/tutorial005_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="17"
- {!> ../../../docs_src/body_multiple_params/tutorial005.py!}
- ```
+{* ../../docs_src/body_multiple_params/tutorial005_an_py310.py hl[17] *}
In diesem Fall erwartet **FastAPI** einen Body wie:
diff --git a/docs/de/docs/tutorial/body-nested-models.md b/docs/de/docs/tutorial/body-nested-models.md
index a7a15a6c2..6287490c6 100644
--- a/docs/de/docs/tutorial/body-nested-models.md
+++ b/docs/de/docs/tutorial/body-nested-models.md
@@ -6,17 +6,7 @@ Mit **FastAPI** können Sie (dank Pydantic) beliebig tief verschachtelte Modelle
Sie können ein Attribut als Kindtyp definieren, zum Beispiel eine Python-`list`e.
-=== "Python 3.10+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/body_nested_models/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="14"
- {!> ../../../docs_src/body_nested_models/tutorial001.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial001_py310.py hl[12] *}
Das bewirkt, dass `tags` eine Liste ist, wenngleich es nichts über den Typ der Elemente der Liste aussagt.
@@ -30,9 +20,7 @@ In Python 3.9 oder darüber können Sie einfach `list` verwenden, um diese Typan
In Python-Versionen vor 3.9 (3.6 und darüber), müssen Sie zuerst `List` von Pythons Standardmodul `typing` importieren.
-```Python hl_lines="1"
-{!> ../../../docs_src/body_nested_models/tutorial002.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *}
### Eine `list`e mit einem Typ-Parameter deklarieren
@@ -61,23 +49,7 @@ Verwenden Sie dieselbe Standardsyntax für Modellattribute mit inneren Typen.
In unserem Beispiel können wir also bewirken, dass `tags` spezifisch eine „Liste von Strings“ ist:
-=== "Python 3.10+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/body_nested_models/tutorial002_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="14"
- {!> ../../../docs_src/body_nested_models/tutorial002_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="14"
- {!> ../../../docs_src/body_nested_models/tutorial002.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial002_py310.py hl[12] *}
## Set-Typen
@@ -87,23 +59,7 @@ Python hat einen Datentyp speziell für Mengen eindeutiger Dinge: das ../../../docs_src/body_nested_models/tutorial003_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="14"
- {!> ../../../docs_src/body_nested_models/tutorial003_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="1 14"
- {!> ../../../docs_src/body_nested_models/tutorial003.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial003_py310.py hl[12] *}
Jetzt, selbst wenn Sie einen Request mit duplizierten Daten erhalten, werden diese zu einem Set eindeutiger Dinge konvertiert.
@@ -125,45 +81,13 @@ Alles das beliebig tief verschachtelt.
Wir können zum Beispiel ein `Image`-Modell definieren.
-=== "Python 3.10+"
-
- ```Python hl_lines="7-9"
- {!> ../../../docs_src/body_nested_models/tutorial004_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="9-11"
- {!> ../../../docs_src/body_nested_models/tutorial004_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9-11"
- {!> ../../../docs_src/body_nested_models/tutorial004.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[7:9] *}
### Das Kindmodell als Typ verwenden
Und dann können wir es als Typ eines Attributes verwenden.
-=== "Python 3.10+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body_nested_models/tutorial004_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_nested_models/tutorial004_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_nested_models/tutorial004.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[18] *}
Das würde bedeuten, dass **FastAPI** einen Body erwartet wie:
@@ -196,23 +120,7 @@ Um alle Optionen kennenzulernen, die Sie haben, schauen Sie sich ../../../docs_src/body_nested_models/tutorial005_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="4 10"
- {!> ../../../docs_src/body_nested_models/tutorial005_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="4 10"
- {!> ../../../docs_src/body_nested_models/tutorial005.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial005_py310.py hl[2,8] *}
Es wird getestet, ob der String eine gültige URL ist, und als solche wird er in JSON Schema / OpenAPI dokumentiert.
@@ -220,23 +128,7 @@ Es wird getestet, ob der String eine gültige URL ist, und als solche wird er in
Sie können Pydantic-Modelle auch als Typen innerhalb von `list`, `set`, usw. verwenden:
-=== "Python 3.10+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body_nested_models/tutorial006_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_nested_models/tutorial006_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_nested_models/tutorial006.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial006_py310.py hl[18] *}
Das wird einen JSON-Body erwarten (konvertieren, validieren, dokumentieren), wie:
@@ -264,33 +156,23 @@ Das wird einen JSON-Body erwarten (konvertieren, validieren, dokumentieren), wie
}
```
-!!! info
- Beachten Sie, dass der `images`-Schlüssel jetzt eine Liste von Bild-Objekten hat.
+/// info
+
+Beachten Sie, dass der `images`-Schlüssel jetzt eine Liste von Bild-Objekten hat.
+
+///
## Tief verschachtelte Modelle
Sie können beliebig tief verschachtelte Modelle definieren:
-=== "Python 3.10+"
+{* ../../docs_src/body_nested_models/tutorial007_py310.py hl[7,12,18,21,25] *}
- ```Python hl_lines="7 12 18 21 25"
- {!> ../../../docs_src/body_nested_models/tutorial007_py310.py!}
- ```
+/// info
-=== "Python 3.9+"
+Beachten Sie, wie `Offer` eine Liste von `Item`s hat, von denen jedes seinerseits eine optionale Liste von `Image`s hat.
- ```Python hl_lines="9 14 20 23 27"
- {!> ../../../docs_src/body_nested_models/tutorial007_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9 14 20 23 27"
- {!> ../../../docs_src/body_nested_models/tutorial007.py!}
- ```
-
-!!! info
- Beachten Sie, wie `Offer` eine Liste von `Item`s hat, von denen jedes seinerseits eine optionale Liste von `Image`s hat.
+///
## Bodys aus reinen Listen
@@ -308,17 +190,7 @@ images: list[Image]
so wie in:
-=== "Python 3.9+"
-
- ```Python hl_lines="13"
- {!> ../../../docs_src/body_nested_models/tutorial008_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="15"
- {!> ../../../docs_src/body_nested_models/tutorial008.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial008_py39.py hl[13] *}
## Editor-Unterstützung überall
@@ -348,26 +220,19 @@ Das schauen wir uns mal an.
Im folgenden Beispiel akzeptieren Sie irgendein `dict`, solange es `int`-Schlüssel und `float`-Werte hat.
-=== "Python 3.9+"
+{* ../../docs_src/body_nested_models/tutorial009_py39.py hl[7] *}
- ```Python hl_lines="7"
- {!> ../../../docs_src/body_nested_models/tutorial009_py39.py!}
- ```
+/// tip | Tipp
-=== "Python 3.8+"
+Bedenken Sie, dass JSON nur `str` als Schlüssel unterstützt.
- ```Python hl_lines="9"
- {!> ../../../docs_src/body_nested_models/tutorial009.py!}
- ```
+Aber Pydantic hat automatische Datenkonvertierung.
-!!! tip "Tipp"
- Bedenken Sie, dass JSON nur `str` als Schlüssel unterstützt.
+Das bedeutet, dass Ihre API-Clients nur Strings senden können, aber solange diese Strings nur Zahlen enthalten, wird Pydantic sie konvertieren und validieren.
- Aber Pydantic hat automatische Datenkonvertierung.
+Und das `dict` welches Sie als `weights` erhalten, wird `int`-Schlüssel und `float`-Werte haben.
- Das bedeutet, dass Ihre API-Clients nur Strings senden können, aber solange diese Strings nur Zahlen enthalten, wird Pydantic sie konvertieren und validieren.
-
- Und das `dict` welches Sie als `weights` erhalten, wird `int`-Schlüssel und `float`-Werte haben.
+///
## Zusammenfassung
diff --git a/docs/de/docs/tutorial/body-updates.md b/docs/de/docs/tutorial/body-updates.md
index 2b3716d6f..574016c58 100644
--- a/docs/de/docs/tutorial/body-updates.md
+++ b/docs/de/docs/tutorial/body-updates.md
@@ -6,23 +6,7 @@ Um einen Artikel zu aktualisieren, können Sie die ../../../docs_src/body_updates/tutorial001_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="30-35"
- {!> ../../../docs_src/body_updates/tutorial001_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="30-35"
- {!> ../../../docs_src/body_updates/tutorial001.py!}
- ```
+{* ../../docs_src/body_updates/tutorial001_py310.py hl[28:33] *}
`PUT` wird verwendet, um Daten zu empfangen, die die existierenden Daten ersetzen sollen.
@@ -48,14 +32,17 @@ Sie können auch die ../../../docs_src/body_updates/tutorial002_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="34"
- {!> ../../../docs_src/body_updates/tutorial002_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="34"
- {!> ../../../docs_src/body_updates/tutorial002.py!}
- ```
+{* ../../docs_src/body_updates/tutorial002_py310.py hl[32] *}
### Pydantics `update`-Parameter verwenden
Jetzt können Sie eine Kopie des existierenden Modells mittels `.model_copy()` erstellen, wobei Sie dem `update`-Parameter ein `dict` mit den zu ändernden Daten übergeben.
-!!! info
- In Pydantic v1 hieß diese Methode `.copy()`, in Pydantic v2 wurde sie deprecated (aber immer noch unterstützt) und in `.model_copy()` umbenannt.
+/// info
- Die Beispiele hier verwenden `.copy()` für die Kompatibilität mit Pydantic v1, Sie sollten jedoch stattdessen `.model_copy()` verwenden, wenn Sie Pydantic v2 verwenden können.
+In Pydantic v1 hieß diese Methode `.copy()`, in Pydantic v2 wurde sie deprecated (aber immer noch unterstützt) und in `.model_copy()` umbenannt.
+
+Die Beispiele hier verwenden `.copy()` für die Kompatibilität mit Pydantic v1, Sie sollten jedoch stattdessen `.model_copy()` verwenden, wenn Sie Pydantic v2 verwenden können.
+
+///
Wie in `stored_item_model.model_copy(update=update_data)`:
-=== "Python 3.10+"
-
- ```Python hl_lines="33"
- {!> ../../../docs_src/body_updates/tutorial002_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="35"
- {!> ../../../docs_src/body_updates/tutorial002_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="35"
- {!> ../../../docs_src/body_updates/tutorial002.py!}
- ```
+{* ../../docs_src/body_updates/tutorial002_py310.py hl[33] *}
### Rekapitulation zum teilweisen Ersetzen
@@ -134,32 +95,22 @@ Zusammengefasst, um Teil-Ersetzungen vorzunehmen:
* Speichern Sie die Daten in Ihrer Datenbank.
* Geben Sie das aktualisierte Modell zurück.
-=== "Python 3.10+"
+{* ../../docs_src/body_updates/tutorial002_py310.py hl[28:35] *}
- ```Python hl_lines="28-35"
- {!> ../../../docs_src/body_updates/tutorial002_py310.py!}
- ```
+/// tip | Tipp
-=== "Python 3.9+"
+Sie können tatsächlich die gleiche Technik mit einer HTTP `PUT` Operation verwenden.
- ```Python hl_lines="30-37"
- {!> ../../../docs_src/body_updates/tutorial002_py39.py!}
- ```
+Aber dieses Beispiel verwendet `PATCH`, da dieses für solche Anwendungsfälle geschaffen wurde.
-=== "Python 3.8+"
+///
- ```Python hl_lines="30-37"
- {!> ../../../docs_src/body_updates/tutorial002.py!}
- ```
+/// note | Hinweis
-!!! tip "Tipp"
- Sie können tatsächlich die gleiche Technik mit einer HTTP `PUT` Operation verwenden.
+Beachten Sie, dass das hereinkommende Modell immer noch validiert wird.
- Aber dieses Beispiel verwendet `PATCH`, da dieses für solche Anwendungsfälle geschaffen wurde.
+Wenn Sie also Teil-Aktualisierungen empfangen wollen, die alle Attribute auslassen können, müssen Sie ein Modell haben, dessen Attribute alle als optional gekennzeichnet sind (mit Defaultwerten oder `None`).
-!!! note "Hinweis"
- Beachten Sie, dass das hereinkommende Modell immer noch validiert wird.
+Um zu unterscheiden zwischen Modellen für **Aktualisierungen**, mit lauter optionalen Werten, und solchen für die **Erzeugung**, mit benötigten Werten, können Sie die Techniken verwenden, die in [Extramodelle](extra-models.md){.internal-link target=_blank} beschrieben wurden.
- Wenn Sie also Teil-Aktualisierungen empfangen wollen, die alle Attribute auslassen können, müssen Sie ein Modell haben, dessen Attribute alle als optional gekennzeichnet sind (mit Defaultwerten oder `None`).
-
- Um zu unterscheiden zwischen Modellen für **Aktualisierungen**, mit lauter optionalen Werten, und solchen für die **Erzeugung**, mit benötigten Werten, können Sie die Techniken verwenden, die in [Extramodelle](extra-models.md){.internal-link target=_blank} beschrieben wurden.
+///
diff --git a/docs/de/docs/tutorial/body.md b/docs/de/docs/tutorial/body.md
index 6611cb51a..e25323786 100644
--- a/docs/de/docs/tutorial/body.md
+++ b/docs/de/docs/tutorial/body.md
@@ -8,28 +8,21 @@ Ihre API sendet fast immer einen **Response**body. Aber Clients senden nicht unb
Um einen **Request**body zu deklarieren, verwenden Sie Pydantic-Modelle mit allen deren Fähigkeiten und Vorzügen.
-!!! info
- Um Daten zu versenden, sollten Sie eines von: `POST` (meistverwendet), `PUT`, `DELETE` oder `PATCH` verwenden.
+/// info
- Senden Sie einen Body mit einem `GET`-Request, dann führt das laut Spezifikation zu undefiniertem Verhalten. Trotzdem wird es von FastAPI unterstützt, für sehr komplexe/extreme Anwendungsfälle.
+Um Daten zu versenden, sollten Sie eines von: `POST` (meistverwendet), `PUT`, `DELETE` oder `PATCH` verwenden.
- Da aber davon abgeraten wird, zeigt die interaktive Dokumentation mit Swagger-Benutzeroberfläche die Dokumentation für den Body auch nicht an, wenn `GET` verwendet wird. Dazwischengeschaltete Proxys unterstützen es möglicherweise auch nicht.
+Senden Sie einen Body mit einem `GET`-Request, dann führt das laut Spezifikation zu undefiniertem Verhalten. Trotzdem wird es von FastAPI unterstützt, für sehr komplexe/extreme Anwendungsfälle.
+
+Da aber davon abgeraten wird, zeigt die interaktive Dokumentation mit Swagger-Benutzeroberfläche die Dokumentation für den Body auch nicht an, wenn `GET` verwendet wird. Dazwischengeschaltete Proxys unterstützen es möglicherweise auch nicht.
+
+///
## Importieren Sie Pydantics `BaseModel`
Zuerst müssen Sie `BaseModel` von `pydantic` importieren:
-=== "Python 3.10+"
-
- ```Python hl_lines="2"
- {!> ../../../docs_src/body/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="4"
- {!> ../../../docs_src/body/tutorial001.py!}
- ```
+{* ../../docs_src/body/tutorial001_py310.py hl[2] *}
## Erstellen Sie Ihr Datenmodell
@@ -37,17 +30,7 @@ Dann deklarieren Sie Ihr Datenmodell als eine Klasse, die von `BaseModel` erbt.
Verwenden Sie Standard-Python-Typen für die Klassenattribute:
-=== "Python 3.10+"
-
- ```Python hl_lines="5-9"
- {!> ../../../docs_src/body/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="7-11"
- {!> ../../../docs_src/body/tutorial001.py!}
- ```
+{* ../../docs_src/body/tutorial001_py310.py hl[5:9] *}
Wie auch bei Query-Parametern gilt, wenn ein Modellattribut einen Defaultwert hat, ist das Attribut nicht erforderlich. Ansonsten ist es erforderlich. Verwenden Sie `None`, um es als optional zu kennzeichnen.
@@ -75,17 +58,7 @@ Da `description` und `tax` optional sind (mit `None` als Defaultwert), wäre fol
Um es zu Ihrer *Pfadoperation* hinzuzufügen, deklarieren Sie es auf die gleiche Weise, wie Sie Pfad- und Query-Parameter deklariert haben:
-=== "Python 3.10+"
-
- ```Python hl_lines="16"
- {!> ../../../docs_src/body/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body/tutorial001.py!}
- ```
+{* ../../docs_src/body/tutorial001_py310.py hl[16] *}
... und deklarieren Sie seinen Typ als das Modell, welches Sie erstellt haben, `Item`.
@@ -134,32 +107,25 @@ Aber Sie bekommen die gleiche Editor-Unterstützung in
-!!! tip "Tipp"
- Wenn Sie PyCharm als Ihren Editor verwenden, probieren Sie das Pydantic PyCharm Plugin aus.
+/// tip | Tipp
- Es verbessert die Editor-Unterstützung für Pydantic-Modelle, mit:
+Wenn Sie PyCharm als Ihren Editor verwenden, probieren Sie das Pydantic PyCharm Plugin aus.
- * Code-Vervollständigung
- * Typüberprüfungen
- * Refaktorisierung
- * Suchen
- * Inspektionen
+Es verbessert die Editor-Unterstützung für Pydantic-Modelle, mit:
+
+* Code-Vervollständigung
+* Typüberprüfungen
+* Refaktorisierung
+* Suchen
+* Inspektionen
+
+///
## Das Modell verwenden
Innerhalb der Funktion können Sie alle Attribute des Modells direkt verwenden:
-=== "Python 3.10+"
-
- ```Python hl_lines="19"
- {!> ../../../docs_src/body/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="21"
- {!> ../../../docs_src/body/tutorial002.py!}
- ```
+{* ../../docs_src/body/tutorial002_py310.py hl[19] *}
## Requestbody- + Pfad-Parameter
@@ -167,17 +133,7 @@ Sie können Pfad- und Requestbody-Parameter gleichzeitig deklarieren.
**FastAPI** erkennt, dass Funktionsparameter, die mit Pfad-Parametern übereinstimmen, **vom Pfad genommen** werden sollen, und dass Funktionsparameter, welche Pydantic-Modelle sind, **vom Requestbody genommen** werden sollen.
-=== "Python 3.10+"
-
- ```Python hl_lines="15-16"
- {!> ../../../docs_src/body/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="17-18"
- {!> ../../../docs_src/body/tutorial003.py!}
- ```
+{* ../../docs_src/body/tutorial003_py310.py hl[15:16] *}
## Requestbody- + Pfad- + Query-Parameter
@@ -185,17 +141,7 @@ Sie können auch zur gleichen Zeit **Body-**, **Pfad-** und **Query-Parameter**
**FastAPI** wird jeden Parameter korrekt erkennen und die Daten vom richtigen Ort holen.
-=== "Python 3.10+"
-
- ```Python hl_lines="16"
- {!> ../../../docs_src/body/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body/tutorial004.py!}
- ```
+{* ../../docs_src/body/tutorial004_py310.py hl[16] *}
Die Funktionsparameter werden wie folgt erkannt:
@@ -203,10 +149,13 @@ Die Funktionsparameter werden wie folgt erkannt:
* Wenn der Parameter ein **einfacher Typ** ist (wie `int`, `float`, `str`, `bool`, usw.), wird er als **Query**-Parameter interpretiert.
* Wenn der Parameter vom Typ eines **Pydantic-Modells** ist, wird er als Request**body** interpretiert.
-!!! note "Hinweis"
- FastAPI weiß, dass der Wert von `q` nicht erforderlich ist, wegen des definierten Defaultwertes `= None`
+/// note | Hinweis
- Das `Union` in `Union[str, None]` wird von FastAPI nicht verwendet, aber es erlaubt Ihrem Editor, Sie besser zu unterstützen und Fehler zu erkennen.
+FastAPI weiß, dass der Wert von `q` nicht erforderlich ist, wegen des definierten Defaultwertes `= None`
+
+Das `Union` in `Union[str, None]` wird von FastAPI nicht verwendet, aber es erlaubt Ihrem Editor, Sie besser zu unterstützen und Fehler zu erkennen.
+
+///
## Ohne Pydantic
diff --git a/docs/de/docs/tutorial/cookie-params.md b/docs/de/docs/tutorial/cookie-params.md
index c95e28c7d..711c8c8e9 100644
--- a/docs/de/docs/tutorial/cookie-params.md
+++ b/docs/de/docs/tutorial/cookie-params.md
@@ -6,41 +6,7 @@ So wie `Query`- und `Path`-Parameter können Sie auch ../../../docs_src/dependencies/tutorial001_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="3"
- {!> ../../../docs_src/dependencies/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="3"
- {!> ../../../docs_src/dependencies/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="1"
- {!> ../../../docs_src/dependencies/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="3"
- {!> ../../../docs_src/dependencies/tutorial001.py!}
- ```
+{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[3] *}
### Deklarieren der Abhängigkeit im „Dependant“
So wie auch `Body`, `Query`, usw., verwenden Sie `Depends` mit den Parametern Ihrer *Pfadoperation-Funktion*:
-=== "Python 3.10+"
-
- ```Python hl_lines="13 18"
- {!> ../../../docs_src/dependencies/tutorial001_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="15 20"
- {!> ../../../docs_src/dependencies/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="16 21"
- {!> ../../../docs_src/dependencies/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="11 16"
- {!> ../../../docs_src/dependencies/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="15 20"
- {!> ../../../docs_src/dependencies/tutorial001.py!}
- ```
+{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[13,18] *}
Obwohl Sie `Depends` in den Parametern Ihrer Funktion genauso verwenden wie `Body`, `Query`, usw., funktioniert `Depends` etwas anders.
@@ -179,8 +80,11 @@ Sie **rufen diese nicht direkt auf** (fügen Sie am Ende keine Klammern hinzu),
Und diese Funktion akzeptiert Parameter auf die gleiche Weise wie *Pfadoperation-Funktionen*.
-!!! tip "Tipp"
- Im nächsten Kapitel erfahren Sie, welche anderen „Dinge“, außer Funktionen, Sie als Abhängigkeiten verwenden können.
+/// tip | Tipp
+
+Im nächsten Kapitel erfahren Sie, welche anderen „Dinge“, außer Funktionen, Sie als Abhängigkeiten verwenden können.
+
+///
Immer wenn ein neuer Request eintrifft, kümmert sich **FastAPI** darum:
@@ -201,10 +105,13 @@ common_parameters --> read_users
Auf diese Weise schreiben Sie gemeinsam genutzten Code nur einmal, und **FastAPI** kümmert sich darum, ihn für Ihre *Pfadoperationen* aufzurufen.
-!!! check
- Beachten Sie, dass Sie keine spezielle Klasse erstellen und diese irgendwo an **FastAPI** übergeben müssen, um sie zu „registrieren“ oder so ähnlich.
+/// check
- Sie übergeben es einfach an `Depends` und **FastAPI** weiß, wie der Rest erledigt wird.
+Beachten Sie, dass Sie keine spezielle Klasse erstellen und diese irgendwo an **FastAPI** übergeben müssen, um sie zu „registrieren“ oder so ähnlich.
+
+Sie übergeben es einfach an `Depends` und **FastAPI** weiß, wie der Rest erledigt wird.
+
+///
## `Annotated`-Abhängigkeiten wiederverwenden
@@ -218,28 +125,15 @@ commons: Annotated[dict, Depends(common_parameters)]
Da wir jedoch `Annotated` verwenden, können wir diesen `Annotated`-Wert in einer Variablen speichern und an mehreren Stellen verwenden:
-=== "Python 3.10+"
+{* ../../docs_src/dependencies/tutorial001_02_an_py310.py hl[12,16,21] *}
- ```Python hl_lines="12 16 21"
- {!> ../../../docs_src/dependencies/tutorial001_02_an_py310.py!}
- ```
+/// tip | Tipp
-=== "Python 3.9+"
+Das ist schlicht Standard-Python, es wird als „Typalias“ bezeichnet und ist eigentlich nicht **FastAPI**-spezifisch.
- ```Python hl_lines="14 18 23"
- {!> ../../../docs_src/dependencies/tutorial001_02_an_py39.py!}
- ```
+Da **FastAPI** jedoch auf Standard-Python, einschließlich `Annotated`, basiert, können Sie diesen Trick in Ihrem Code verwenden. 😎
-=== "Python 3.8+"
-
- ```Python hl_lines="15 19 24"
- {!> ../../../docs_src/dependencies/tutorial001_02_an.py!}
- ```
-
-!!! tip "Tipp"
- Das ist schlicht Standard-Python, es wird als „Typalias“ bezeichnet und ist eigentlich nicht **FastAPI**-spezifisch.
-
- Da **FastAPI** jedoch auf Standard-Python, einschließlich `Annotated`, basiert, können Sie diesen Trick in Ihrem Code verwenden. 😎
+///
Die Abhängigkeiten funktionieren weiterhin wie erwartet, und das **Beste daran** ist, dass die **Typinformationen erhalten bleiben**, was bedeutet, dass Ihr Editor Ihnen weiterhin **automatische Vervollständigung**, **Inline-Fehler**, usw. bieten kann. Das Gleiche gilt für andere Tools wie `mypy`.
@@ -255,8 +149,11 @@ Und Sie können Abhängigkeiten mit `async def` innerhalb normaler `def`-*Pfadop
Es spielt keine Rolle. **FastAPI** weiß, was zu tun ist.
-!!! note "Hinweis"
- Wenn Ihnen das nichts sagt, lesen Sie den [Async: *„In Eile?“*](../../async.md#in-eile){.internal-link target=_blank}-Abschnitt über `async` und `await` in der Dokumentation.
+/// note | Hinweis
+
+Wenn Ihnen das nichts sagt, lesen Sie den [Async: *„In Eile?“*](../../async.md#in-eile){.internal-link target=_blank}-Abschnitt über `async` und `await` in der Dokumentation.
+
+///
## Integriert in OpenAPI
diff --git a/docs/de/docs/tutorial/dependencies/sub-dependencies.md b/docs/de/docs/tutorial/dependencies/sub-dependencies.md
index 0fa2af839..66bdc7043 100644
--- a/docs/de/docs/tutorial/dependencies/sub-dependencies.md
+++ b/docs/de/docs/tutorial/dependencies/sub-dependencies.md
@@ -10,41 +10,7 @@ Diese können so **tief** verschachtelt sein, wie nötig.
Sie könnten eine erste Abhängigkeit („Dependable“) wie folgt erstellen:
-=== "Python 3.10+"
-
- ```Python hl_lines="8-9"
- {!> ../../../docs_src/dependencies/tutorial005_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="8-9"
- {!> ../../../docs_src/dependencies/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9-10"
- {!> ../../../docs_src/dependencies/tutorial005_an.py!}
- ```
-
-=== "Python 3.10 nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="6-7"
- {!> ../../../docs_src/dependencies/tutorial005_py310.py!}
- ```
-
-=== "Python 3.8 nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="8-9"
- {!> ../../../docs_src/dependencies/tutorial005.py!}
- ```
+{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[8:9] *}
Diese deklariert einen optionalen Abfrageparameter `q` vom Typ `str` und gibt ihn dann einfach zurück.
@@ -54,41 +20,7 @@ Das ist recht einfach (nicht sehr nützlich), hilft uns aber dabei, uns auf die
Dann können Sie eine weitere Abhängigkeitsfunktion (ein „Dependable“) erstellen, die gleichzeitig eine eigene Abhängigkeit deklariert (also auch ein „Dependant“ ist):
-=== "Python 3.10+"
-
- ```Python hl_lines="13"
- {!> ../../../docs_src/dependencies/tutorial005_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="13"
- {!> ../../../docs_src/dependencies/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="14"
- {!> ../../../docs_src/dependencies/tutorial005_an.py!}
- ```
-
-=== "Python 3.10 nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/dependencies/tutorial005_py310.py!}
- ```
-
-=== "Python 3.8 nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="13"
- {!> ../../../docs_src/dependencies/tutorial005.py!}
- ```
+{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[13] *}
Betrachten wir die deklarierten Parameter:
@@ -101,46 +33,15 @@ Betrachten wir die deklarierten Parameter:
Diese Abhängigkeit verwenden wir nun wie folgt:
-=== "Python 3.10+"
+{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[23] *}
- ```Python hl_lines="23"
- {!> ../../../docs_src/dependencies/tutorial005_an_py310.py!}
- ```
+/// info
-=== "Python 3.9+"
+Beachten Sie, dass wir in der *Pfadoperation-Funktion* nur eine einzige Abhängigkeit deklarieren, den `query_or_cookie_extractor`.
- ```Python hl_lines="23"
- {!> ../../../docs_src/dependencies/tutorial005_an_py39.py!}
- ```
+Aber **FastAPI** wird wissen, dass es zuerst `query_extractor` auflösen muss, um dessen Resultat `query_or_cookie_extractor` zu übergeben, wenn dieses aufgerufen wird.
-=== "Python 3.8+"
-
- ```Python hl_lines="24"
- {!> ../../../docs_src/dependencies/tutorial005_an.py!}
- ```
-
-=== "Python 3.10 nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="19"
- {!> ../../../docs_src/dependencies/tutorial005_py310.py!}
- ```
-
-=== "Python 3.8 nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/dependencies/tutorial005.py!}
- ```
-
-!!! info
- Beachten Sie, dass wir in der *Pfadoperation-Funktion* nur eine einzige Abhängigkeit deklarieren, den `query_or_cookie_extractor`.
-
- Aber **FastAPI** wird wissen, dass es zuerst `query_extractor` auflösen muss, um dessen Resultat `query_or_cookie_extractor` zu übergeben, wenn dieses aufgerufen wird.
+///
```mermaid
graph TB
@@ -161,22 +62,29 @@ Und es speichert den zurückgegebenen Wert in einem ../../../docs_src/encoder/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="5 22"
- {!> ../../../docs_src/encoder/tutorial001.py!}
- ```
+{* ../../docs_src/encoder/tutorial001_py310.py hl[4,21] *}
In diesem Beispiel wird das Pydantic-Modell in ein `dict`, und das `datetime`-Objekt in ein `str` konvertiert.
@@ -38,5 +28,8 @@ Das Resultat dieses Aufrufs ist etwas, das mit Pythons Standard- ../../../docs_src/extra_data_types/tutorial001_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="1 3 12-16"
- {!> ../../../docs_src/extra_data_types/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="1 3 13-17"
- {!> ../../../docs_src/extra_data_types/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="1 2 11-15"
- {!> ../../../docs_src/extra_data_types/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="1 2 12-16"
- {!> ../../../docs_src/extra_data_types/tutorial001.py!}
- ```
+{* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[1,3,12:16] *}
Beachten Sie, dass die Parameter innerhalb der Funktion ihren natürlichen Datentyp haben und Sie beispielsweise normale Datumsmanipulationen durchführen können, wie zum Beispiel:
-=== "Python 3.10+"
-
- ```Python hl_lines="18-19"
- {!> ../../../docs_src/extra_data_types/tutorial001_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="18-19"
- {!> ../../../docs_src/extra_data_types/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="19-20"
- {!> ../../../docs_src/extra_data_types/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="17-18"
- {!> ../../../docs_src/extra_data_types/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="18-19"
- {!> ../../../docs_src/extra_data_types/tutorial001.py!}
- ```
+{* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[18:19] *}
diff --git a/docs/de/docs/tutorial/extra-models.md b/docs/de/docs/tutorial/extra-models.md
index cdf16c4ba..6aad1c0f4 100644
--- a/docs/de/docs/tutorial/extra-models.md
+++ b/docs/de/docs/tutorial/extra-models.md
@@ -8,31 +8,27 @@ Insbesondere Benutzermodelle, denn:
* Das **herausgehende Modell** sollte kein Passwort haben.
* Das **Datenbankmodell** sollte wahrscheinlich ein gehashtes Passwort haben.
-!!! danger "Gefahr"
- Speichern Sie niemals das Klartext-Passwort eines Benutzers. Speichern Sie immer den „sicheren Hash“, den Sie verifizieren können.
+/// danger | Gefahr
- Falls Ihnen das nichts sagt, in den [Sicherheits-Kapiteln](security/simple-oauth2.md#passwort-hashing){.internal-link target=_blank} werden Sie lernen, was ein „Passwort-Hash“ ist.
+Speichern Sie niemals das Klartext-Passwort eines Benutzers. Speichern Sie immer den „sicheren Hash“, den Sie verifizieren können.
+
+Falls Ihnen das nichts sagt, in den [Sicherheits-Kapiteln](security/simple-oauth2.md#passwort-hashing){.internal-link target=_blank} werden Sie lernen, was ein „Passwort-Hash“ ist.
+
+///
## Mehrere Modelle
Hier der generelle Weg, wie die Modelle mit ihren Passwort-Feldern aussehen könnten, und an welchen Orten sie verwendet werden würden.
-=== "Python 3.10+"
+{* ../../docs_src/extra_models/tutorial001_py310.py hl[7,9,14,20,22,27:28,31:33,38:39] *}
- ```Python hl_lines="7 9 14 20 22 27-28 31-33 38-39"
- {!> ../../../docs_src/extra_models/tutorial001_py310.py!}
- ```
+/// info
-=== "Python 3.8+"
+In Pydantic v1 hieß diese Methode `.dict()`, in Pydantic v2 wurde sie deprecated (aber immer noch unterstützt) und in `.model_dump()` umbenannt.
- ```Python hl_lines="9 11 16 22 24 29-30 33-35 40-41"
- {!> ../../../docs_src/extra_models/tutorial001.py!}
- ```
+Die Beispiele hier verwenden `.dict()` für die Kompatibilität mit Pydantic v1, Sie sollten jedoch stattdessen `.model_dump()` verwenden, wenn Sie Pydantic v2 verwenden können.
-!!! info
- In Pydantic v1 hieß diese Methode `.dict()`, in Pydantic v2 wurde sie deprecated (aber immer noch unterstützt) und in `.model_dump()` umbenannt.
-
- Die Beispiele hier verwenden `.dict()` für die Kompatibilität mit Pydantic v1, Sie sollten jedoch stattdessen `.model_dump()` verwenden, wenn Sie Pydantic v2 verwenden können.
+///
### Über `**user_in.dict()`
@@ -144,8 +140,11 @@ UserInDB(
)
```
-!!! warning "Achtung"
- Die Hilfsfunktionen `fake_password_hasher` und `fake_save_user` demonstrieren nur den möglichen Fluss der Daten und bieten natürlich keine echte Sicherheit.
+/// warning | Achtung
+
+Die Hilfsfunktionen `fake_password_hasher` und `fake_save_user` demonstrieren nur den möglichen Fluss der Daten und bieten natürlich keine echte Sicherheit.
+
+///
## Verdopplung vermeiden
@@ -163,17 +162,7 @@ Die ganze Datenkonvertierung, -validierung, -dokumentation, usw. wird immer noch
Auf diese Weise beschreiben wir nur noch die Unterschiede zwischen den Modellen (mit Klartext-`password`, mit `hashed_password`, und ohne Passwort):
-=== "Python 3.10+"
-
- ```Python hl_lines="7 13-14 17-18 21-22"
- {!> ../../../docs_src/extra_models/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9 15-16 19-20 23-24"
- {!> ../../../docs_src/extra_models/tutorial002.py!}
- ```
+{* ../../docs_src/extra_models/tutorial002_py310.py hl[7,13:14,17:18,21:22] *}
## `Union`, oder `anyOf`
@@ -183,20 +172,13 @@ Das wird in OpenAPI mit `anyOf` angezeigt.
Um das zu tun, verwenden Sie Pythons Standard-Typhinweis `typing.Union`:
-!!! note "Hinweis"
- Listen Sie, wenn Sie eine `Union` definieren, denjenigen Typ zuerst, der am spezifischsten ist, gefolgt von den weniger spezifischen Typen. Im Beispiel oben, in `Union[PlaneItem, CarItem]` also den spezifischeren `PlaneItem` vor dem weniger spezifischen `CarItem`.
+/// note | Hinweis
-=== "Python 3.10+"
+Listen Sie, wenn Sie eine `Union` definieren, denjenigen Typ zuerst, der am spezifischsten ist, gefolgt von den weniger spezifischen Typen. Im Beispiel oben, in `Union[PlaneItem, CarItem]` also den spezifischeren `PlaneItem` vor dem weniger spezifischen `CarItem`.
- ```Python hl_lines="1 14-15 18-20 33"
- {!> ../../../docs_src/extra_models/tutorial003_py310.py!}
- ```
+///
-=== "Python 3.8+"
-
- ```Python hl_lines="1 14-15 18-20 33"
- {!> ../../../docs_src/extra_models/tutorial003.py!}
- ```
+{* ../../docs_src/extra_models/tutorial003_py310.py hl[1,14:15,18:20,33] *}
### `Union` in Python 3.10
@@ -218,17 +200,7 @@ Genauso können Sie eine Response deklarieren, die eine Liste von Objekten ist.
Verwenden Sie dafür Pythons Standard `typing.List` (oder nur `list` in Python 3.9 und darüber):
-=== "Python 3.9+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/extra_models/tutorial004_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="1 20"
- {!> ../../../docs_src/extra_models/tutorial004.py!}
- ```
+{* ../../docs_src/extra_models/tutorial004_py39.py hl[18] *}
## Response mit beliebigem `dict`
@@ -238,17 +210,7 @@ Das ist nützlich, wenn Sie die gültigen Feld-/Attribut-Namen von vorneherein n
In diesem Fall können Sie `typing.Dict` verwenden (oder nur `dict` in Python 3.9 und darüber):
-=== "Python 3.9+"
-
- ```Python hl_lines="6"
- {!> ../../../docs_src/extra_models/tutorial005_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="1 8"
- {!> ../../../docs_src/extra_models/tutorial005.py!}
- ```
+{* ../../docs_src/extra_models/tutorial005_py39.py hl[6] *}
## Zusammenfassung
diff --git a/docs/de/docs/tutorial/first-steps.md b/docs/de/docs/tutorial/first-steps.md
index 27ba3ec16..3104c8d61 100644
--- a/docs/de/docs/tutorial/first-steps.md
+++ b/docs/de/docs/tutorial/first-steps.md
@@ -2,9 +2,7 @@
Die einfachste FastAPI-Datei könnte wie folgt aussehen:
-```Python
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py *}
Kopieren Sie dies in eine Datei `main.py`.
@@ -24,12 +22,15 @@ $ uvicorn main:app --reload
-!!! note "Hinweis"
- Der Befehl `uvicorn main:app` bezieht sich auf:
+/// note | Hinweis
- * `main`: die Datei `main.py` (das sogenannte Python-„Modul“).
- * `app`: das Objekt, welches in der Datei `main.py` mit der Zeile `app = FastAPI()` erzeugt wurde.
- * `--reload`: lässt den Server nach Codeänderungen neu starten. Verwenden Sie das nur während der Entwicklung.
+Der Befehl `uvicorn main:app` bezieht sich auf:
+
+* `main`: die Datei `main.py` (das sogenannte Python-„Modul“).
+* `app`: das Objekt, welches in der Datei `main.py` mit der Zeile `app = FastAPI()` erzeugt wurde.
+* `--reload`: lässt den Server nach Codeänderungen neu starten. Verwenden Sie das nur während der Entwicklung.
+
+///
In der Konsolenausgabe sollte es eine Zeile geben, die ungefähr so aussieht:
@@ -130,22 +131,21 @@ Ebenfalls können Sie es verwenden, um automatisch Code für Clients zu generier
### Schritt 1: Importieren von `FastAPI`
-```Python hl_lines="1"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[1] *}
`FastAPI` ist eine Python-Klasse, die die gesamte Funktionalität für Ihre API bereitstellt.
-!!! note "Technische Details"
- `FastAPI` ist eine Klasse, die direkt von `Starlette` erbt.
+/// note | Technische Details
- Sie können alle Starlette-Funktionalitäten auch mit `FastAPI` nutzen.
+`FastAPI` ist eine Klasse, die direkt von `Starlette` erbt.
+
+Sie können alle Starlette-Funktionalitäten auch mit `FastAPI` nutzen.
+
+///
### Schritt 2: Erzeugen einer `FastAPI`-„Instanz“
-```Python hl_lines="3"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[3] *}
In diesem Beispiel ist die Variable `app` eine „Instanz“ der Klasse `FastAPI`.
@@ -165,9 +165,7 @@ $ uvicorn main:app --reload
Wenn Sie Ihre Anwendung wie folgt erstellen:
-```Python hl_lines="3"
-{!../../../docs_src/first_steps/tutorial002.py!}
-```
+{* ../../docs_src/first_steps/tutorial002.py hl[3] *}
Und in eine Datei `main.py` einfügen, dann würden Sie `uvicorn` wie folgt aufrufen:
@@ -199,8 +197,11 @@ https://example.com/items/foo
/items/foo
```
-!!! info
- Ein „Pfad“ wird häufig auch als „Endpunkt“ oder „Route“ bezeichnet.
+/// info
+
+Ein „Pfad“ wird häufig auch als „Endpunkt“ oder „Route“ bezeichnet.
+
+///
Bei der Erstellung einer API ist der „Pfad“ die wichtigste Möglichkeit zur Trennung von „Anliegen“ und „Ressourcen“.
@@ -241,25 +242,26 @@ Wir werden sie auch „**Operationen**“ nennen.
#### Definieren eines *Pfadoperation-Dekorators*
-```Python hl_lines="6"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[6] *}
Das `@app.get("/")` sagt **FastAPI**, dass die Funktion direkt darunter für die Bearbeitung von Anfragen zuständig ist, die an:
* den Pfad `/`
* unter der Verwendung der
get-Operation gehen
-!!! info "`@decorator` Information"
- Diese `@something`-Syntax wird in Python „Dekorator“ genannt.
+/// info | `@decorator` Information
- Sie platzieren ihn über einer Funktion. Wie ein hübscher, dekorativer Hut (daher kommt wohl der Begriff).
+Diese `@something`-Syntax wird in Python „Dekorator“ genannt.
- Ein „Dekorator“ nimmt die darunter stehende Funktion und macht etwas damit.
+Sie platzieren ihn über einer Funktion. Wie ein hübscher, dekorativer Hut (daher kommt wohl der Begriff).
- In unserem Fall teilt dieser Dekorator **FastAPI** mit, dass die folgende Funktion mit dem **Pfad** `/` und der **Operation** `get` zusammenhängt.
+Ein „Dekorator“ nimmt die darunter stehende Funktion und macht etwas damit.
- Dies ist der „**Pfadoperation-Dekorator**“.
+In unserem Fall teilt dieser Dekorator **FastAPI** mit, dass die folgende Funktion mit dem **Pfad** `/` und der **Operation** `get` zusammenhängt.
+
+Dies ist der „**Pfadoperation-Dekorator**“.
+
+///
Sie können auch die anderen Operationen verwenden:
@@ -274,14 +276,17 @@ Oder die exotischeren:
* `@app.patch()`
* `@app.trace()`
-!!! tip "Tipp"
- Es steht Ihnen frei, jede Operation (HTTP-Methode) so zu verwenden, wie Sie es möchten.
+/// tip | Tipp
- **FastAPI** erzwingt keine bestimmte Bedeutung.
+Es steht Ihnen frei, jede Operation (HTTP-Methode) so zu verwenden, wie Sie es möchten.
- Die hier aufgeführten Informationen dienen als Leitfaden und sind nicht verbindlich.
+**FastAPI** erzwingt keine bestimmte Bedeutung.
- Wenn Sie beispielsweise GraphQL verwenden, führen Sie normalerweise alle Aktionen nur mit „POST“-Operationen durch.
+Die hier aufgeführten Informationen dienen als Leitfaden und sind nicht verbindlich.
+
+Wenn Sie beispielsweise GraphQL verwenden, führen Sie normalerweise alle Aktionen nur mit „POST“-Operationen durch.
+
+///
### Schritt 4: Definieren der **Pfadoperation-Funktion**
@@ -291,9 +296,7 @@ Das ist unsere „**Pfadoperation-Funktion**“:
* **Operation**: ist `get`.
* **Funktion**: ist die Funktion direkt unter dem „Dekorator“ (unter `@app.get("/")`).
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[7] *}
Dies ist eine Python-Funktion.
@@ -305,18 +308,17 @@ In diesem Fall handelt es sich um eine `async`-Funktion.
Sie könnten sie auch als normale Funktion anstelle von `async def` definieren:
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial003.py!}
-```
+{* ../../docs_src/first_steps/tutorial003.py hl[7] *}
-!!! note "Hinweis"
- Wenn Sie den Unterschied nicht kennen, lesen Sie [Async: *„In Eile?“*](../async.md#in-eile){.internal-link target=_blank}.
+/// note | Hinweis
+
+Wenn Sie den Unterschied nicht kennen, lesen Sie [Async: *„In Eile?“*](../async.md#in-eile){.internal-link target=_blank}.
+
+///
### Schritt 5: den Inhalt zurückgeben
-```Python hl_lines="8"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[8] *}
Sie können ein `dict`, eine `list`, einzelne Werte wie `str`, `int`, usw. zurückgeben.
diff --git a/docs/de/docs/tutorial/handling-errors.md b/docs/de/docs/tutorial/handling-errors.md
index af658b971..31bc6d328 100644
--- a/docs/de/docs/tutorial/handling-errors.md
+++ b/docs/de/docs/tutorial/handling-errors.md
@@ -25,9 +25,7 @@ Um HTTP-Responses mit Fehlern zum Client zurückzugeben, verwenden Sie `HTTPExce
### `HTTPException` importieren
-```Python hl_lines="1"
-{!../../../docs_src/handling_errors/tutorial001.py!}
-```
+{* ../../docs_src/handling_errors/tutorial001.py hl[1] *}
### Eine `HTTPException` in Ihrem Code auslösen
@@ -41,9 +39,7 @@ Der Vorteil, eine Exception auszulösen (`raise`), statt sie zurückzugeben (`re
Im folgenden Beispiel lösen wir, wenn der Client eine ID anfragt, die nicht existiert, eine Exception mit dem Statuscode `404` aus.
-```Python hl_lines="11"
-{!../../../docs_src/handling_errors/tutorial001.py!}
-```
+{* ../../docs_src/handling_errors/tutorial001.py hl[11] *}
### Die resultierende Response
@@ -63,12 +59,15 @@ Aber wenn der Client `http://example.com/items/bar` anfragt (ein nicht-existiere
}
```
-!!! tip "Tipp"
- Wenn Sie eine `HTTPException` auslösen, können Sie dem Parameter `detail` jeden Wert übergeben, der nach JSON konvertiert werden kann, nicht nur `str`.
+/// tip | Tipp
- Zum Beispiel ein `dict`, eine `list`, usw.
+Wenn Sie eine `HTTPException` auslösen, können Sie dem Parameter `detail` jeden Wert übergeben, der nach JSON konvertiert werden kann, nicht nur `str`.
- Das wird automatisch von **FastAPI** gehandhabt und der Wert nach JSON konvertiert.
+Zum Beispiel ein `dict`, eine `list`, usw.
+
+Das wird automatisch von **FastAPI** gehandhabt und der Wert nach JSON konvertiert.
+
+///
## Benutzerdefinierte Header hinzufügen
@@ -78,9 +77,7 @@ Sie müssen das wahrscheinlich nicht direkt in ihrem Code verwenden.
Aber falls es in einem fortgeschrittenen Szenario notwendig ist, können Sie benutzerdefinierte Header wie folgt hinzufügen:
-```Python hl_lines="14"
-{!../../../docs_src/handling_errors/tutorial002.py!}
-```
+{* ../../docs_src/handling_errors/tutorial002.py hl[14] *}
## Benutzerdefinierte Exceptionhandler definieren
@@ -92,9 +89,7 @@ Und Sie möchten diese Exception global mit FastAPI handhaben.
Sie könnten einen benutzerdefinierten Exceptionhandler mittels `@app.exception_handler()` hinzufügen:
-```Python hl_lines="5-7 13-18 24"
-{!../../../docs_src/handling_errors/tutorial003.py!}
-```
+{* ../../docs_src/handling_errors/tutorial003.py hl[5:7,13:18,24] *}
Wenn Sie nun `/unicorns/yolo` anfragen, `raise`d die *Pfadoperation* eine `UnicornException`.
@@ -106,10 +101,13 @@ Sie erhalten also einen sauberen Error mit einem Statuscode `418` und dem JSON-I
{"message": "Oops! yolo did something. There goes a rainbow..."}
```
-!!! note "Technische Details"
- Sie können auch `from starlette.requests import Request` und `from starlette.responses import JSONResponse` verwenden.
+/// note | Technische Details
- **FastAPI** bietet dieselben `starlette.responses` auch via `fastapi.responses` an, als Annehmlichkeit für Sie, den Entwickler. Die meisten verfügbaren Responses kommen aber direkt von Starlette. Das Gleiche gilt für `Request`.
+Sie können auch `from starlette.requests import Request` und `from starlette.responses import JSONResponse` verwenden.
+
+**FastAPI** bietet dieselben `starlette.responses` auch via `fastapi.responses` an, als Annehmlichkeit für Sie, den Entwickler. Die meisten verfügbaren Responses kommen aber direkt von Starlette. Das Gleiche gilt für `Request`.
+
+///
## Die Default-Exceptionhandler überschreiben
@@ -129,9 +127,7 @@ Um diesen zu überschreiben, importieren Sie den `RequestValidationError` und ve
Der Exceptionhandler wird einen `Request` und die Exception entgegennehmen.
-```Python hl_lines="2 14-16"
-{!../../../docs_src/handling_errors/tutorial004.py!}
-```
+{* ../../docs_src/handling_errors/tutorial004.py hl[2,14:16] *}
Wenn Sie nun `/items/foo` besuchen, erhalten Sie statt des Default-JSON-Errors:
@@ -160,8 +156,11 @@ path -> item_id
#### `RequestValidationError` vs. `ValidationError`
-!!! warning "Achtung"
- Das folgende sind technische Details, die Sie überspringen können, wenn sie für Sie nicht wichtig sind.
+/// warning | Achtung
+
+Das folgende sind technische Details, die Sie überspringen können, wenn sie für Sie nicht wichtig sind.
+
+///
`RequestValidationError` ist eine Unterklasse von Pydantics `ValidationError`.
@@ -179,14 +178,15 @@ Genauso können Sie den `HTTPException`-Handler überschreiben.
Zum Beispiel könnten Sie eine Klartext-Response statt JSON für diese Fehler zurückgeben wollen:
-```Python hl_lines="3-4 9-11 22"
-{!../../../docs_src/handling_errors/tutorial004.py!}
-```
+{* ../../docs_src/handling_errors/tutorial004.py hl[3:4,9:11,22] *}
-!!! note "Technische Details"
- Sie können auch `from starlette.responses import PlainTextResponse` verwenden.
+/// note | Technische Details
- **FastAPI** bietet dieselben `starlette.responses` auch via `fastapi.responses` an, als Annehmlichkeit für Sie, den Entwickler. Die meisten verfügbaren Responses kommen aber direkt von Starlette.
+Sie können auch `from starlette.responses import PlainTextResponse` verwenden.
+
+**FastAPI** bietet dieselben `starlette.responses` auch via `fastapi.responses` an, als Annehmlichkeit für Sie, den Entwickler. Die meisten verfügbaren Responses kommen aber direkt von Starlette.
+
+///
### Den `RequestValidationError`-Body verwenden
@@ -194,9 +194,7 @@ Der `RequestValidationError` enthält den empfangenen `body` mit den ungültigen
Sie könnten diesen verwenden, während Sie Ihre Anwendung entwickeln, um den Body zu loggen und zu debuggen, ihn zum Benutzer zurückzugeben, usw.
-```Python hl_lines="14"
-{!../../../docs_src/handling_errors/tutorial005.py!}
-```
+{* ../../docs_src/handling_errors/tutorial005.py hl[14] *}
Jetzt versuchen Sie, einen ungültigen Artikel zu senden:
@@ -252,8 +250,6 @@ from starlette.exceptions import HTTPException as StarletteHTTPException
Wenn Sie die Exception zusammen mit denselben Default-Exceptionhandlern von **FastAPI** verwenden möchten, können Sie die Default-Exceptionhandler von `fastapi.Exception_handlers` importieren und wiederverwenden:
-```Python hl_lines="2-5 15 21"
-{!../../../docs_src/handling_errors/tutorial006.py!}
-```
+{* ../../docs_src/handling_errors/tutorial006.py hl[2:5,15,21] *}
In diesem Beispiel `print`en Sie nur den Fehler mit einer sehr ausdrucksstarken Nachricht, aber Sie sehen, worauf wir hinauswollen. Sie können mit der Exception etwas machen und dann einfach die Default-Exceptionhandler wiederverwenden.
diff --git a/docs/de/docs/tutorial/header-params.md b/docs/de/docs/tutorial/header-params.md
index 3c9807f47..8283cc929 100644
--- a/docs/de/docs/tutorial/header-params.md
+++ b/docs/de/docs/tutorial/header-params.md
@@ -6,41 +6,7 @@ So wie `Query`-, `Path`-, und `Cookie`-Parameter können Sie auch .
+/// tip | Tipp
- Wenn Sie jedoch benutzerdefinierte Header haben, die ein Client in einem Browser sehen soll, müssen Sie sie zu Ihrer CORS-Konfigurationen ([CORS (Cross-Origin Resource Sharing)](cors.md){.internal-link target=_blank}) hinzufügen, indem Sie den Parameter `expose_headers` verwenden, der in der Starlette-CORS-Dokumentation dokumentiert ist.
+Beachten Sie, dass benutzerdefinierte proprietäre Header hinzugefügt werden können. Verwenden Sie dafür das Präfix 'X-'.
-!!! note "Technische Details"
- Sie könnten auch `from starlette.requests import Request` verwenden.
+Wenn Sie jedoch benutzerdefinierte Header haben, die ein Client in einem Browser sehen soll, müssen Sie sie zu Ihrer CORS-Konfigurationen ([CORS (Cross-Origin Resource Sharing)](cors.md){.internal-link target=_blank}) hinzufügen, indem Sie den Parameter `expose_headers` verwenden, der in der Starlette-CORS-Dokumentation dokumentiert ist.
- **FastAPI** bietet es als Komfort für Sie, den Entwickler, an. Aber es stammt direkt von Starlette.
+///
+
+/// note | Technische Details
+
+Sie könnten auch `from starlette.requests import Request` verwenden.
+
+**FastAPI** bietet es als Komfort für Sie, den Entwickler, an. Aber es stammt direkt von Starlette.
+
+///
### Vor und nach der `response`
@@ -50,9 +57,7 @@ Und auch nachdem die `response` generiert wurde, bevor sie zurückgegeben wird.
Sie könnten beispielsweise einen benutzerdefinierten Header `X-Process-Time` hinzufügen, der die Zeit in Sekunden enthält, die benötigt wurde, um den Request zu verarbeiten und eine Response zu generieren:
-```Python hl_lines="10 12-13"
-{!../../../docs_src/middleware/tutorial001.py!}
-```
+{* ../../docs_src/middleware/tutorial001.py hl[10,12:13] *}
## Andere Middlewares
diff --git a/docs/de/docs/tutorial/path-operation-configuration.md b/docs/de/docs/tutorial/path-operation-configuration.md
index 80a4fadc9..7473e515b 100644
--- a/docs/de/docs/tutorial/path-operation-configuration.md
+++ b/docs/de/docs/tutorial/path-operation-configuration.md
@@ -2,8 +2,11 @@
Es gibt mehrere Konfigurations-Parameter, die Sie Ihrem *Pfadoperation-Dekorator* übergeben können.
-!!! warning "Achtung"
- Beachten Sie, dass diese Parameter direkt dem *Pfadoperation-Dekorator* übergeben werden, nicht der *Pfadoperation-Funktion*.
+/// warning | Achtung
+
+Beachten Sie, dass diese Parameter direkt dem *Pfadoperation-Dekorator* übergeben werden, nicht der *Pfadoperation-Funktion*.
+
+///
## Response-Statuscode
@@ -13,52 +16,23 @@ Sie können direkt den `int`-Code übergeben, etwa `404`.
Aber falls Sie sich nicht mehr erinnern, wofür jede Nummer steht, können Sie die Abkürzungs-Konstanten in `status` verwenden:
-=== "Python 3.10+"
-
- ```Python hl_lines="1 15"
- {!> ../../../docs_src/path_operation_configuration/tutorial001_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="3 17"
- {!> ../../../docs_src/path_operation_configuration/tutorial001_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="3 17"
- {!> ../../../docs_src/path_operation_configuration/tutorial001.py!}
- ```
+{* ../../docs_src/path_operation_configuration/tutorial001_py310.py hl[1,15] *}
Dieser Statuscode wird in der Response verwendet und zum OpenAPI-Schema hinzugefügt.
-!!! note "Technische Details"
- Sie können auch `from starlette import status` verwenden.
+/// note | Technische Details
- **FastAPI** bietet dieselben `starlette.status`-Codes auch via `fastapi.status` an, als Annehmlichkeit für Sie, den Entwickler. Sie kommen aber direkt von Starlette.
+Sie können auch `from starlette import status` verwenden.
+
+**FastAPI** bietet dieselben `starlette.status`-Codes auch via `fastapi.status` an, als Annehmlichkeit für Sie, den Entwickler. Sie kommen aber direkt von Starlette.
+
+///
## Tags
Sie können Ihrer *Pfadoperation* Tags hinzufügen, mittels des Parameters `tags`, dem eine `list`e von `str`s übergeben wird (in der Regel nur ein `str`):
-=== "Python 3.10+"
-
- ```Python hl_lines="15 20 25"
- {!> ../../../docs_src/path_operation_configuration/tutorial002_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="17 22 27"
- {!> ../../../docs_src/path_operation_configuration/tutorial002_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="17 22 27"
- {!> ../../../docs_src/path_operation_configuration/tutorial002.py!}
- ```
+{* ../../docs_src/path_operation_configuration/tutorial002_py310.py hl[15,20,25] *}
Diese werden zum OpenAPI-Schema hinzugefügt und von den automatischen Dokumentations-Benutzeroberflächen verwendet:
@@ -72,31 +46,13 @@ In diesem Fall macht es Sinn, die Tags in einem `Enum` zu speichern.
**FastAPI** unterstützt diese genauso wie einfache Strings:
-```Python hl_lines="1 8-10 13 18"
-{!../../../docs_src/path_operation_configuration/tutorial002b.py!}
-```
+{* ../../docs_src/path_operation_configuration/tutorial002b.py hl[1,8:10,13,18] *}
## Zusammenfassung und Beschreibung
Sie können eine Zusammenfassung (`summary`) und eine Beschreibung (`description`) hinzufügen:
-=== "Python 3.10+"
-
- ```Python hl_lines="18-19"
- {!> ../../../docs_src/path_operation_configuration/tutorial003_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="20-21"
- {!> ../../../docs_src/path_operation_configuration/tutorial003_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="20-21"
- {!> ../../../docs_src/path_operation_configuration/tutorial003.py!}
- ```
+{* ../../docs_src/path_operation_configuration/tutorial003_py310.py hl[18:19] *}
## Beschreibung mittels Docstring
@@ -104,23 +60,7 @@ Da Beschreibungen oft mehrere Zeilen lang sind, können Sie die Beschreibung der
Sie können im Docstring Markdown schreiben, es wird korrekt interpretiert und angezeigt (die Einrückung des Docstring beachtend).
-=== "Python 3.10+"
-
- ```Python hl_lines="17-25"
- {!> ../../../docs_src/path_operation_configuration/tutorial004_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="19-27"
- {!> ../../../docs_src/path_operation_configuration/tutorial004_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="19-27"
- {!> ../../../docs_src/path_operation_configuration/tutorial004.py!}
- ```
+{* ../../docs_src/path_operation_configuration/tutorial004_py310.py hl[17:25] *}
In der interaktiven Dokumentation sieht das dann so aus:
@@ -130,31 +70,21 @@ In der interaktiven Dokumentation sieht das dann so aus:
Die Response können Sie mit dem Parameter `response_description` beschreiben:
-=== "Python 3.10+"
+{* ../../docs_src/path_operation_configuration/tutorial005_py310.py hl[19] *}
- ```Python hl_lines="19"
- {!> ../../../docs_src/path_operation_configuration/tutorial005_py310.py!}
- ```
+/// info
-=== "Python 3.9+"
+beachten Sie, dass sich `response_description` speziell auf die Response bezieht, während `description` sich generell auf die *Pfadoperation* bezieht.
- ```Python hl_lines="21"
- {!> ../../../docs_src/path_operation_configuration/tutorial005_py39.py!}
- ```
+///
-=== "Python 3.8+"
+/// check
- ```Python hl_lines="21"
- {!> ../../../docs_src/path_operation_configuration/tutorial005.py!}
- ```
+OpenAPI verlangt, dass jede *Pfadoperation* über eine Beschreibung der Response verfügt.
-!!! info
- beachten Sie, dass sich `response_description` speziell auf die Response bezieht, während `description` sich generell auf die *Pfadoperation* bezieht.
+Daher, wenn Sie keine vergeben, wird **FastAPI** automatisch eine für „Erfolgreiche Response“ erstellen.
-!!! check
- OpenAPI verlangt, dass jede *Pfadoperation* über eine Beschreibung der Response verfügt.
-
- Daher, wenn Sie keine vergeben, wird **FastAPI** automatisch eine für „Erfolgreiche Response“ erstellen.
+///
@@ -162,9 +92,7 @@ Die Response können Sie mit dem Parameter `response_description` beschreiben:
Wenn Sie eine *Pfadoperation* als deprecated kennzeichnen möchten, ohne sie zu entfernen, fügen Sie den Parameter `deprecated` hinzu:
-```Python hl_lines="16"
-{!../../../docs_src/path_operation_configuration/tutorial006.py!}
-```
+{* ../../docs_src/path_operation_configuration/tutorial006.py hl[16] *}
Sie wird in der interaktiven Dokumentation gut sichtbar als deprecated markiert werden:
diff --git a/docs/de/docs/tutorial/path-params-numeric-validations.md b/docs/de/docs/tutorial/path-params-numeric-validations.md
index aa3b59b8b..1acdd5b4e 100644
--- a/docs/de/docs/tutorial/path-params-numeric-validations.md
+++ b/docs/de/docs/tutorial/path-params-numeric-validations.md
@@ -6,48 +6,17 @@ So wie Sie mit `Query` für Query-Parameter zusätzliche Validierungen und Metad
Importieren Sie zuerst `Path` von `fastapi`, und importieren Sie `Annotated`.
-=== "Python 3.10+"
+{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[1,3] *}
- ```Python hl_lines="1 3"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py!}
- ```
+/// info
-=== "Python 3.9+"
+FastAPI unterstützt (und empfiehlt die Verwendung von) `Annotated` seit Version 0.95.0.
- ```Python hl_lines="1 3"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py39.py!}
- ```
+Wenn Sie eine ältere Version haben, werden Sie Fehler angezeigt bekommen, wenn Sie versuchen, `Annotated` zu verwenden.
-=== "Python 3.8+"
+Bitte [aktualisieren Sie FastAPI](../deployment/versions.md#upgrade-der-fastapi-versionen){.internal-link target=_blank} daher mindestens zu Version 0.95.1, bevor Sie `Annotated` verwenden.
- ```Python hl_lines="3-4"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="1"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="3"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001.py!}
- ```
-
-!!! info
- FastAPI unterstützt (und empfiehlt die Verwendung von) `Annotated` seit Version 0.95.0.
-
- Wenn Sie eine ältere Version haben, werden Sie Fehler angezeigt bekommen, wenn Sie versuchen, `Annotated` zu verwenden.
-
- Bitte [aktualisieren Sie FastAPI](../deployment/versions.md#upgrade-der-fastapi-versionen){.internal-link target=_blank} daher mindestens zu Version 0.95.1, bevor Sie `Annotated` verwenden.
+///
## Metadaten deklarieren
@@ -55,53 +24,25 @@ Sie können die gleichen Parameter deklarieren wie für `Query`.
Um zum Beispiel einen `title`-Metadaten-Wert für den Pfad-Parameter `item_id` zu deklarieren, schreiben Sie:
-=== "Python 3.10+"
+{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[10] *}
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py!}
- ```
+/// note | Hinweis
-=== "Python 3.9+"
+Ein Pfad-Parameter ist immer erforderlich, weil er Teil des Pfads sein muss.
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py39.py!}
- ```
+Sie sollten ihn daher mit `...` deklarieren, um ihn als erforderlich auszuzeichnen.
-=== "Python 3.8+"
+Doch selbst wenn Sie ihn mit `None` deklarieren, oder einen Defaultwert setzen, bewirkt das nichts, er bleibt immer erforderlich.
- ```Python hl_lines="11"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001.py!}
- ```
-
-!!! note "Hinweis"
- Ein Pfad-Parameter ist immer erforderlich, weil er Teil des Pfads sein muss.
-
- Sie sollten ihn daher mit `...` deklarieren, um ihn als erforderlich auszuzeichnen.
-
- Doch selbst wenn Sie ihn mit `None` deklarieren, oder einen Defaultwert setzen, bewirkt das nichts, er bleibt immer erforderlich.
+///
## Sortieren Sie die Parameter, wie Sie möchten
-!!! tip "Tipp"
- Wenn Sie `Annotated` verwenden, ist das folgende nicht so wichtig / nicht notwendig.
+/// tip | Tipp
+
+Wenn Sie `Annotated` verwenden, ist das folgende nicht so wichtig / nicht notwendig.
+
+///
Nehmen wir an, Sie möchten den Query-Parameter `q` als erforderlichen `str` deklarieren.
@@ -117,33 +58,31 @@ Für **FastAPI** ist es nicht wichtig. Es erkennt die Parameter anhand ihres Nam
Sie können Ihre Funktion also so deklarieren:
-=== "Python 3.8 nicht annotiert"
+//// tab | Python 3.8 nicht annotiert
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
+/// tip | Tipp
- ```Python hl_lines="7"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial002.py!}
- ```
+Bevorzugen Sie die `Annotated`-Version, falls möglich.
+
+///
+
+```Python hl_lines="7"
+{!> ../../docs_src/path_params_numeric_validations/tutorial002.py!}
+```
+
+////
Aber bedenken Sie, dass Sie dieses Problem nicht haben, wenn Sie `Annotated` verwenden, da Sie nicht die Funktions-Parameter-Defaultwerte für `Query()` oder `Path()` verwenden.
-=== "Python 3.9+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial002_an.py!}
- ```
+{* ../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py hl[10] *}
## Sortieren Sie die Parameter wie Sie möchten: Tricks
-!!! tip "Tipp"
- Wenn Sie `Annotated` verwenden, ist das folgende nicht so wichtig / nicht notwendig.
+/// tip | Tipp
+
+Wenn Sie `Annotated` verwenden, ist das folgende nicht so wichtig / nicht notwendig.
+
+///
Hier ein **kleiner Trick**, der nützlich sein kann, aber Sie werden ihn nicht oft brauchen.
@@ -160,51 +99,20 @@ Wenn Sie eines der folgenden Dinge tun möchten:
Python macht nichts mit diesem `*`, aber es wird wissen, dass alle folgenden Parameter als Keyword-Argumente (Schlüssel-Wert-Paare), auch bekannt als kwargs, verwendet werden. Selbst wenn diese keinen Defaultwert haben.
-```Python hl_lines="7"
-{!../../../docs_src/path_params_numeric_validations/tutorial003.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *}
### Besser mit `Annotated`
Bedenken Sie, dass Sie, wenn Sie `Annotated` verwenden, dieses Problem nicht haben, weil Sie keine Defaultwerte für Ihre Funktionsparameter haben. Sie müssen daher wahrscheinlich auch nicht `*` verwenden.
-=== "Python 3.9+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial003_an.py!}
- ```
+{* ../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py hl[10] *}
## Validierung von Zahlen: Größer oder gleich
Mit `Query` und `Path` (und anderen, die Sie später kennenlernen), können Sie Zahlenbeschränkungen deklarieren.
Hier, mit `ge=1`, wird festgelegt, dass `item_id` eine Ganzzahl benötigt, die größer oder gleich `1` ist (`g`reater than or `e`qual).
-=== "Python 3.9+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial004_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial004.py!}
- ```
+{* ../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py hl[10] *}
## Validierung von Zahlen: Größer und kleiner oder gleich
@@ -213,26 +121,7 @@ Das Gleiche trifft zu auf:
* `gt`: `g`reater `t`han – größer als
* `le`: `l`ess than or `e`qual – kleiner oder gleich
-=== "Python 3.9+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial005_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial005.py!}
- ```
+{* ../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py hl[10] *}
## Validierung von Zahlen: Floats, größer und kleiner
@@ -244,26 +133,7 @@ Hier wird es wichtig, in der Lage zu sein, lt.
-=== "Python 3.9+"
-
- ```Python hl_lines="13"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial006_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial006.py!}
- ```
+{* ../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py hl[13] *}
## Zusammenfassung
@@ -276,18 +146,24 @@ Und Sie können auch Validierungen für Zahlen deklarieren:
* `lt`: `l`ess `t`han – kleiner als
* `le`: `l`ess than or `e`qual – kleiner oder gleich
-!!! info
- `Query`, `Path`, und andere Klassen, die Sie später kennenlernen, sind Unterklassen einer allgemeinen `Param`-Klasse.
+/// info
- Sie alle teilen die gleichen Parameter für zusätzliche Validierung und Metadaten, die Sie gesehen haben.
+`Query`, `Path`, und andere Klassen, die Sie später kennenlernen, sind Unterklassen einer allgemeinen `Param`-Klasse.
-!!! note "Technische Details"
- `Query`, `Path` und andere, die Sie von `fastapi` importieren, sind tatsächlich Funktionen.
+Sie alle teilen die gleichen Parameter für zusätzliche Validierung und Metadaten, die Sie gesehen haben.
- Die, wenn sie aufgerufen werden, Instanzen der Klassen mit demselben Namen zurückgeben.
+///
- Sie importieren also `Query`, welches eine Funktion ist. Aber wenn Sie es aufrufen, gibt es eine Instanz der Klasse zurück, die auch `Query` genannt wird.
+/// note | Technische Details
- Diese Funktionen existieren (statt die Klassen direkt zu verwenden), damit Ihr Editor keine Fehlermeldungen über ihre Typen ausgibt.
+`Query`, `Path` und andere, die Sie von `fastapi` importieren, sind tatsächlich Funktionen.
- Auf diese Weise können Sie Ihren Editor und Ihre Programmier-Tools verwenden, ohne besondere Einstellungen vornehmen zu müssen, um diese Fehlermeldungen stummzuschalten.
+Die, wenn sie aufgerufen werden, Instanzen der Klassen mit demselben Namen zurückgeben.
+
+Sie importieren also `Query`, welches eine Funktion ist. Aber wenn Sie es aufrufen, gibt es eine Instanz der Klasse zurück, die auch `Query` genannt wird.
+
+Diese Funktionen existieren (statt die Klassen direkt zu verwenden), damit Ihr Editor keine Fehlermeldungen über ihre Typen ausgibt.
+
+Auf diese Weise können Sie Ihren Editor und Ihre Programmier-Tools verwenden, ohne besondere Einstellungen vornehmen zu müssen, um diese Fehlermeldungen stummzuschalten.
+
+///
diff --git a/docs/de/docs/tutorial/path-params.md b/docs/de/docs/tutorial/path-params.md
index 8c8f2e008..123990940 100644
--- a/docs/de/docs/tutorial/path-params.md
+++ b/docs/de/docs/tutorial/path-params.md
@@ -2,9 +2,7 @@
Sie können Pfad-„Parameter“ oder -„Variablen“ mit der gleichen Syntax deklarieren, welche in Python-Format-Strings verwendet wird:
-```Python hl_lines="6-7"
-{!../../../docs_src/path_params/tutorial001.py!}
-```
+{* ../../docs_src/path_params/tutorial001.py hl[6:7] *}
Der Wert des Pfad-Parameters `item_id` wird Ihrer Funktion als das Argument `item_id` übergeben.
@@ -18,14 +16,15 @@ Wenn Sie dieses Beispiel ausführen und auf Konversion
@@ -35,10 +34,13 @@ Wenn Sie dieses Beispiel ausführen und Ihren Browser unter „parsen“.
+Beachten Sie, dass der Wert, den Ihre Funktion erhält und zurückgibt, die Zahl `3` ist, also ein `int`. Nicht der String `"3"`, also ein `str`.
+
+Sprich, mit dieser Typdeklaration wird **FastAPI** die Anfrage automatisch „parsen“.
+
+///
## Datenvalidierung
@@ -65,12 +67,15 @@ Der Pfad-Parameter `item_id` hatte den Wert `"foo"`, was kein `int` ist.
Die gleiche Fehlermeldung würde angezeigt werden, wenn Sie ein `float` (also eine Kommazahl) statt eines `int`s übergeben würden, wie etwa in: http://127.0.0.1:8000/items/4.2
-!!! check
- Sprich, mit der gleichen Python-Typdeklaration gibt Ihnen **FastAPI** Datenvalidierung.
+/// check
- Beachten Sie, dass die Fehlermeldung auch direkt die Stelle anzeigt, wo die Validierung nicht erfolgreich war.
+Sprich, mit der gleichen Python-Typdeklaration gibt Ihnen **FastAPI** Datenvalidierung.
- Das ist unglaublich hilfreich, wenn Sie Code entwickeln und debuggen, welcher mit ihrer API interagiert.
+Beachten Sie, dass die Fehlermeldung auch direkt die Stelle anzeigt, wo die Validierung nicht erfolgreich war.
+
+Das ist unglaublich hilfreich, wenn Sie Code entwickeln und debuggen, welcher mit ihrer API interagiert.
+
+///
## Dokumentation
@@ -78,10 +83,13 @@ Wenn Sie die Seite
-!!! check
- Wiederum, mit dieser gleichen Python-Typdeklaration gibt Ihnen **FastAPI** eine automatische, interaktive Dokumentation (verwendet die Swagger-Benutzeroberfläche).
+/// check
- Beachten Sie, dass der Pfad-Parameter dort als Ganzzahl deklariert ist.
+Wiederum, mit dieser gleichen Python-Typdeklaration gibt Ihnen **FastAPI** eine automatische, interaktive Dokumentation (verwendet die Swagger-Benutzeroberfläche).
+
+Beachten Sie, dass der Pfad-Parameter dort als Ganzzahl deklariert ist.
+
+///
## Nützliche Standards. Alternative Dokumentation
@@ -111,17 +119,13 @@ Und Sie haben auch einen Pfad `/users/{user_id}`, um Daten über einen spezifisc
Weil *Pfadoperationen* in ihrer Reihenfolge ausgewertet werden, müssen Sie sicherstellen, dass der Pfad `/users/me` vor `/users/{user_id}` deklariert wurde:
-```Python hl_lines="6 11"
-{!../../../docs_src/path_params/tutorial003.py!}
-```
+{* ../../docs_src/path_params/tutorial003.py hl[6,11] *}
Ansonsten würde der Pfad für `/users/{user_id}` auch `/users/me` auswerten, und annehmen, dass ein Parameter `user_id` mit dem Wert `"me"` übergeben wurde.
Sie können eine Pfadoperation auch nicht erneut definieren:
-```Python hl_lines="6 11"
-{!../../../docs_src/path_params/tutorial003b.py!}
-```
+{* ../../docs_src/path_params/tutorial003b.py hl[6,11] *}
Die erste Definition wird immer verwendet werden, da ihr Pfad zuerst übereinstimmt.
@@ -137,23 +141,25 @@ Indem Sie von `str` erben, weiß die API Dokumentation, dass die Werte des Enums
Erstellen Sie dann Klassen-Attribute mit festgelegten Werten, welches die erlaubten Werte sein werden:
-```Python hl_lines="1 6-9"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[1,6:9] *}
-!!! info
- Enumerationen (oder kurz Enums) gibt es in Python seit Version 3.4.
+/// info
-!!! tip "Tipp"
- Falls Sie sich fragen, was „AlexNet“, „ResNet“ und „LeNet“ ist, das sind Namen von Modellen für maschinelles Lernen.
+Enumerationen (oder kurz Enums) gibt es in Python seit Version 3.4.
+
+///
+
+/// tip | Tipp
+
+Falls Sie sich fragen, was „AlexNet“, „ResNet“ und „LeNet“ ist, das sind Namen von Modellen für maschinelles Lernen.
+
+///
### Deklarieren Sie einen *Pfad-Parameter*
Dann erstellen Sie einen *Pfad-Parameter*, der als Typ die gerade erstellte Enum-Klasse hat (`ModelName`):
-```Python hl_lines="16"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[16] *}
### Testen Sie es in der API-Dokumentation
@@ -169,20 +175,19 @@ Der *Pfad-Parameter* wird ein * ../../../docs_src/query_params_str_validations/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial001.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial001_py310.py hl[7] *}
Der Query-Parameter `q` hat den Typ `Union[str, None]` (oder `str | None` in Python 3.10), was bedeutet, er ist entweder ein `str` oder `None`. Der Defaultwert ist `None`, also weiß FastAPI, der Parameter ist nicht erforderlich.
-!!! note "Hinweis"
- FastAPI weiß nur dank des definierten Defaultwertes `=None`, dass der Wert von `q` nicht erforderlich ist
+/// note | Hinweis
- `Union[str, None]` hingegen erlaubt ihren Editor, Sie besser zu unterstützen und Fehler zu erkennen.
+FastAPI weiß nur dank des definierten Defaultwertes `=None`, dass der Wert von `q` nicht erforderlich ist
+
+`Union[str, None]` hingegen erlaubt ihren Editor, Sie besser zu unterstützen und Fehler zu erkennen.
+
+///
## Zusätzliche Validierung
@@ -34,30 +27,37 @@ Importieren Sie zuerst:
* `Query` von `fastapi`
* `Annotated` von `typing` (oder von `typing_extensions` in Python unter 3.9)
-=== "Python 3.10+"
+//// tab | Python 3.10+
- In Python 3.9 oder darüber, ist `Annotated` Teil der Standardbibliothek, also können Sie es von `typing` importieren.
+In Python 3.9 oder darüber, ist `Annotated` Teil der Standardbibliothek, also können Sie es von `typing` importieren.
- ```Python hl_lines="1 3"
- {!> ../../../docs_src/query_params_str_validations/tutorial002_an_py310.py!}
- ```
+```Python hl_lines="1 3"
+{!> ../../docs_src/query_params_str_validations/tutorial002_an_py310.py!}
+```
-=== "Python 3.8+"
+////
- In Versionen unter Python 3.9 importieren Sie `Annotated` von `typing_extensions`.
+//// tab | Python 3.8+
- Es wird bereits mit FastAPI installiert sein.
+In Versionen unter Python 3.9 importieren Sie `Annotated` von `typing_extensions`.
- ```Python hl_lines="3-4"
- {!> ../../../docs_src/query_params_str_validations/tutorial002_an.py!}
- ```
+Es wird bereits mit FastAPI installiert sein.
-!!! info
- FastAPI unterstützt (und empfiehlt die Verwendung von) `Annotated` seit Version 0.95.0.
+```Python hl_lines="3-4"
+{!> ../../docs_src/query_params_str_validations/tutorial002_an.py!}
+```
- Wenn Sie eine ältere Version haben, werden Sie Fehler angezeigt bekommen, wenn Sie versuchen, `Annotated` zu verwenden.
+////
- Bitte [aktualisieren Sie FastAPI](../deployment/versions.md#upgrade-der-fastapi-versionen){.internal-link target=_blank} daher mindestens zu Version 0.95.1, bevor Sie `Annotated` verwenden.
+/// info
+
+FastAPI unterstützt (und empfiehlt die Verwendung von) `Annotated` seit Version 0.95.0.
+
+Wenn Sie eine ältere Version haben, werden Sie Fehler angezeigt bekommen, wenn Sie versuchen, `Annotated` zu verwenden.
+
+Bitte [aktualisieren Sie FastAPI](../deployment/versions.md#upgrade-der-fastapi-versionen){.internal-link target=_blank} daher mindestens zu Version 0.95.1, bevor Sie `Annotated` verwenden.
+
+///
## `Annotated` im Typ des `q`-Parameters verwenden
@@ -67,31 +67,39 @@ Jetzt ist es an der Zeit, das mit FastAPI auszuprobieren. 🚀
Wir hatten diese Typannotation:
-=== "Python 3.10+"
+//// tab | Python 3.10+
- ```Python
- q: str | None = None
- ```
+```Python
+q: str | None = None
+```
-=== "Python 3.8+"
+////
- ```Python
- q: Union[str, None] = None
- ```
+//// tab | Python 3.8+
+
+```Python
+q: Union[str, None] = None
+```
+
+////
Wir wrappen das nun in `Annotated`, sodass daraus wird:
-=== "Python 3.10+"
+//// tab | Python 3.10+
- ```Python
- q: Annotated[str | None] = None
- ```
+```Python
+q: Annotated[str | None] = None
+```
-=== "Python 3.8+"
+////
- ```Python
- q: Annotated[Union[str, None]] = None
- ```
+//// tab | Python 3.8+
+
+```Python
+q: Annotated[Union[str, None]] = None
+```
+
+////
Beide Versionen bedeuten dasselbe: `q` ist ein Parameter, der `str` oder `None` sein kann. Standardmäßig ist er `None`.
@@ -101,17 +109,7 @@ Wenden wir uns jetzt den spannenden Dingen zu. 🎉
Jetzt, da wir `Annotated` für unsere Metadaten deklariert haben, fügen Sie `Query` hinzu, und setzen Sie den Parameter `max_length` auf `50`:
-=== "Python 3.10+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial002_an_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params_str_validations/tutorial002_an.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial002_an_py310.py hl[9] *}
Beachten Sie, dass der Defaultwert immer noch `None` ist, sodass der Parameter immer noch optional ist.
@@ -127,22 +125,15 @@ FastAPI wird nun:
Frühere Versionen von FastAPI (vor 0.95.0) benötigten `Query` als Defaultwert des Parameters, statt es innerhalb von `Annotated` unterzubringen. Die Chance ist groß, dass Sie Quellcode sehen, der das immer noch so macht, darum erkläre ich es Ihnen.
-!!! tip "Tipp"
- Verwenden Sie für neuen Code, und wann immer möglich, `Annotated`, wie oben erklärt. Es gibt mehrere Vorteile (unten erläutert) und keine Nachteile. 🍰
+/// tip | Tipp
+
+Verwenden Sie für neuen Code, und wann immer möglich, `Annotated`, wie oben erklärt. Es gibt mehrere Vorteile (unten erläutert) und keine Nachteile. 🍰
+
+///
So würden Sie `Query()` als Defaultwert Ihres Funktionsparameters verwenden, den Parameter `max_length` auf 50 gesetzt:
-=== "Python 3.10+"
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params_str_validations/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial002.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial002_py310.py hl[7] *}
Da wir in diesem Fall (ohne die Verwendung von `Annotated`) den Parameter-Defaultwert `None` mit `Query()` ersetzen, müssen wir nun dessen Defaultwert mit dem Parameter `Query(default=None)` deklarieren. Das dient demselben Zweck, `None` als Defaultwert für den Funktionsparameter zu setzen (zumindest für FastAPI).
@@ -172,22 +163,25 @@ q: str | None = None
Nur, dass die `Query`-Versionen den Parameter explizit als Query-Parameter deklarieren.
-!!! info
- Bedenken Sie, dass:
+/// info
- ```Python
- = None
- ```
+Bedenken Sie, dass:
- oder:
+```Python
+= None
+```
- ```Python
- = Query(default=None)
- ```
+oder:
- der wichtigste Teil ist, um einen Parameter optional zu machen, da dieses `None` der Defaultwert ist, und das ist es, was diesen Parameter **nicht erforderlich** macht.
+```Python
+= Query(default=None)
+```
- Der Teil mit `Union[str, None]` erlaubt es Ihrem Editor, Sie besser zu unterstützen, aber er sagt FastAPI nicht, dass dieser Parameter optional ist.
+der wichtigste Teil ist, um einen Parameter optional zu machen, da dieses `None` der Defaultwert ist, und das ist es, was diesen Parameter **nicht erforderlich** macht.
+
+Der Teil mit `Union[str, None]` erlaubt es Ihrem Editor, Sie besser zu unterstützen, aber er sagt FastAPI nicht, dass dieser Parameter optional ist.
+
+///
Jetzt können wir `Query` weitere Parameter übergeben. Fangen wir mit dem `max_length` Parameter an, der auf Strings angewendet wird:
@@ -239,81 +233,13 @@ Da `Annotated` mehrere Metadaten haben kann, können Sie dieselbe Funktion auch
Sie können auch einen Parameter `min_length` hinzufügen:
-=== "Python 3.10+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params_str_validations/tutorial003_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params_str_validations/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/query_params_str_validations/tutorial003_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params_str_validations/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params_str_validations/tutorial003.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial003_an_py310.py hl[10] *}
## Reguläre Ausdrücke hinzufügen
Sie können einen Regulären Ausdruck `pattern` definieren, mit dem der Parameter übereinstimmen muss:
-=== "Python 3.10+"
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/query_params_str_validations/tutorial004_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/query_params_str_validations/tutorial004_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/query_params_str_validations/tutorial004_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/query_params_str_validations/tutorial004.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial004_an_py310.py hl[11] *}
Dieses bestimmte reguläre Suchmuster prüft, ob der erhaltene Parameter-Wert:
@@ -331,11 +257,11 @@ Vor Pydantic Version 2 und vor FastAPI Version 0.100.0, war der Name des Paramet
Sie könnten immer noch Code sehen, der den alten Namen verwendet:
-=== "Python 3.10+ Pydantic v1"
+//// tab | Pydantic v1
- ```Python hl_lines="11"
- {!> ../../../docs_src/query_params_str_validations/tutorial004_an_py310_regex.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial004_regex_an_py310.py hl[11] *}
+
+////
Beachten Sie aber, dass das deprecated ist, und zum neuen Namen `pattern` geändert werden sollte. 🤓
@@ -345,29 +271,13 @@ Sie können natürlich andere Defaultwerte als `None` verwenden.
Beispielsweise könnten Sie den `q` Query-Parameter so deklarieren, dass er eine `min_length` von `3` hat, und den Defaultwert `"fixedquery"`:
-=== "Python 3.9+"
+{* ../../docs_src/query_params_str_validations/tutorial005_an_py39.py hl[9] *}
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial005_an_py39.py!}
- ```
+/// note | Hinweis
-=== "Python 3.8+"
+Ein Parameter ist optional (nicht erforderlich), wenn er irgendeinen Defaultwert, auch `None`, hat.
- ```Python hl_lines="8"
- {!> ../../../docs_src/query_params_str_validations/tutorial005_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params_str_validations/tutorial005.py!}
- ```
-
-!!! note "Hinweis"
- Ein Parameter ist optional (nicht erforderlich), wenn er irgendeinen Defaultwert, auch `None`, hat.
+///
## Erforderliche Parameter
@@ -385,77 +295,25 @@ q: Union[str, None] = None
Aber jetzt deklarieren wir den Parameter mit `Query`, wie in:
-=== "Annotiert"
+//// tab | Annotiert
- ```Python
- q: Annotated[Union[str, None], Query(min_length=3)] = None
- ```
+```Python
+q: Annotated[Union[str, None], Query(min_length=3)] = None
+```
-=== "Nicht annotiert"
+////
- ```Python
- q: Union[str, None] = Query(default=None, min_length=3)
- ```
+//// tab | Nicht annotiert
+
+```Python
+q: Union[str, None] = Query(default=None, min_length=3)
+```
+
+////
Wenn Sie einen Parameter erforderlich machen wollen, während Sie `Query` verwenden, deklarieren Sie ebenfalls einfach keinen Defaultwert:
-=== "Python 3.9+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial006_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/query_params_str_validations/tutorial006_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params_str_validations/tutorial006.py!}
- ```
-
- !!! tip "Tipp"
- Beachten Sie, dass, obwohl in diesem Fall `Query()` der Funktionsparameter-Defaultwert ist, wir nicht `default=None` zu `Query()` hinzufügen.
-
- Verwenden Sie bitte trotzdem die `Annotated`-Version. 😉
-
-### Erforderlich mit Ellipse (`...`)
-
-Es gibt eine Alternative, die explizit deklariert, dass ein Wert erforderlich ist. Sie können als Default das Literal `...` setzen:
-
-=== "Python 3.9+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial006b_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/query_params_str_validations/tutorial006b_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params_str_validations/tutorial006b.py!}
- ```
-
-!!! info
- Falls Sie das `...` bisher noch nicht gesehen haben: Es ist ein spezieller einzelner Wert, Teil von Python und wird „Ellipsis“ genannt (Deutsch: Ellipse).
-
- Es wird von Pydantic und FastAPI verwendet, um explizit zu deklarieren, dass ein Wert erforderlich ist.
-
-Dies wird **FastAPI** wissen lassen, dass dieser Parameter erforderlich ist.
+{* ../../docs_src/query_params_str_validations/tutorial006_an_py39.py hl[9] *}
### Erforderlich, kann `None` sein
@@ -463,47 +321,19 @@ Sie können deklarieren, dass ein Parameter `None` akzeptiert, aber dennoch erfo
Um das zu machen, deklarieren Sie, dass `None` ein gültiger Typ ist, aber verwenden Sie dennoch `...` als Default:
-=== "Python 3.10+"
+{* ../../docs_src/query_params_str_validations/tutorial006c_an_py310.py hl[9] *}
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial006c_an_py310.py!}
- ```
+/// tip | Tipp
-=== "Python 3.9+"
+Pydantic, welches die gesamte Datenvalidierung und Serialisierung in FastAPI antreibt, hat ein spezielles Verhalten, wenn Sie `Optional` oder `Union[Something, None]` ohne Defaultwert verwenden, Sie können mehr darüber in der Pydantic-Dokumentation unter Required fields erfahren.
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial006c_an_py39.py!}
- ```
+///
-=== "Python 3.8+"
+/// tip | Tipp
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params_str_validations/tutorial006c_an.py!}
- ```
+Denken Sie daran, dass Sie in den meisten Fällen, wenn etwas erforderlich ist, einfach den Defaultwert weglassen können. Sie müssen also normalerweise `...` nicht verwenden.
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params_str_validations/tutorial006c_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial006c.py!}
- ```
-
-!!! tip "Tipp"
- Pydantic, welches die gesamte Datenvalidierung und Serialisierung in FastAPI antreibt, hat ein spezielles Verhalten, wenn Sie `Optional` oder `Union[Something, None]` ohne Defaultwert verwenden, Sie können mehr darüber in der Pydantic-Dokumentation unter Required fields erfahren.
-
-!!! tip "Tipp"
- Denken Sie daran, dass Sie in den meisten Fällen, wenn etwas erforderlich ist, einfach den Defaultwert weglassen können. Sie müssen also normalerweise `...` nicht verwenden.
+///
## Query-Parameter-Liste / Mehrere Werte
@@ -511,50 +341,7 @@ Wenn Sie einen Query-Parameter explizit mit `Query` auszeichnen, können Sie ihn
Um zum Beispiel einen Query-Parameter `q` zu deklarieren, der mehrere Male in der URL vorkommen kann, schreiben Sie:
-=== "Python 3.10+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial011_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial011_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params_str_validations/tutorial011_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params_str_validations/tutorial011_py310.py!}
- ```
-
-=== "Python 3.9+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial011_py39.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial011.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial011_an_py310.py hl[9] *}
Dann, mit einer URL wie:
@@ -575,8 +362,11 @@ Die Response für diese URL wäre also:
}
```
-!!! tip "Tipp"
- Um einen Query-Parameter vom Typ `list` zu deklarieren, wie im Beispiel oben, müssen Sie explizit `Query` verwenden, sonst würde der Parameter als Requestbody interpretiert werden.
+/// tip | Tipp
+
+Um einen Query-Parameter vom Typ `list` zu deklarieren, wie im Beispiel oben, müssen Sie explizit `Query` verwenden, sonst würde der Parameter als Requestbody interpretiert werden.
+
+///
Die interaktive API-Dokumentation wird entsprechend aktualisiert und erlaubt jetzt mehrere Werte.
@@ -586,35 +376,7 @@ Die interaktive API-Dokumentation wird entsprechend aktualisiert und erlaubt jet
Und Sie können auch eine Default-`list`e von Werten definieren, wenn keine übergeben werden:
-=== "Python 3.9+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial012_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params_str_validations/tutorial012_an.py!}
- ```
-
-=== "Python 3.9+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params_str_validations/tutorial012_py39.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial012.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial012_an_py39.py hl[9] *}
Wenn Sie auf:
@@ -637,31 +399,15 @@ gehen, wird der Default für `q` verwendet: `["foo", "bar"]`, und als Response e
Sie können auch `list` direkt verwenden, anstelle von `List[str]` (oder `list[str]` in Python 3.9+):
-=== "Python 3.9+"
+{* ../../docs_src/query_params_str_validations/tutorial013_an_py39.py hl[9] *}
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial013_an_py39.py!}
- ```
+/// note | Hinweis
-=== "Python 3.8+"
+Beachten Sie, dass FastAPI in diesem Fall den Inhalt der Liste nicht überprüft.
- ```Python hl_lines="8"
- {!> ../../../docs_src/query_params_str_validations/tutorial013_an.py!}
- ```
+Zum Beispiel würde `List[int]` überprüfen (und dokumentieren) dass die Liste Ganzzahlen enthält. `list` alleine macht das nicht.
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params_str_validations/tutorial013.py!}
- ```
-
-!!! note "Hinweis"
- Beachten Sie, dass FastAPI in diesem Fall den Inhalt der Liste nicht überprüft.
-
- Zum Beispiel würde `List[int]` überprüfen (und dokumentieren) dass die Liste Ganzzahlen enthält. `list` alleine macht das nicht.
+///
## Deklarieren von mehr Metadaten
@@ -669,86 +415,21 @@ Sie können mehr Informationen zum Parameter hinzufügen.
Diese Informationen werden zur generierten OpenAPI hinzugefügt, und von den Dokumentations-Oberflächen und von externen Tools verwendet.
-!!! note "Hinweis"
- Beachten Sie, dass verschiedene Tools OpenAPI möglicherweise unterschiedlich gut unterstützen.
+/// note | Hinweis
- Einige könnten noch nicht alle zusätzlichen Informationen anzeigen, die Sie deklariert haben, obwohl in den meisten Fällen geplant ist, das fehlende Feature zu implementieren.
+Beachten Sie, dass verschiedene Tools OpenAPI möglicherweise unterschiedlich gut unterstützen.
+
+Einige könnten noch nicht alle zusätzlichen Informationen anzeigen, die Sie deklariert haben, obwohl in den meisten Fällen geplant ist, das fehlende Feature zu implementieren.
+
+///
Sie können einen Titel hinzufügen – `title`:
-=== "Python 3.10+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params_str_validations/tutorial007_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params_str_validations/tutorial007_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/query_params_str_validations/tutorial007_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/query_params_str_validations/tutorial007_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params_str_validations/tutorial007.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial007_an_py310.py hl[10] *}
Und eine Beschreibung – `description`:
-=== "Python 3.10+"
-
- ```Python hl_lines="14"
- {!> ../../../docs_src/query_params_str_validations/tutorial008_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="14"
- {!> ../../../docs_src/query_params_str_validations/tutorial008_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="15"
- {!> ../../../docs_src/query_params_str_validations/tutorial008_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/query_params_str_validations/tutorial008_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="13"
- {!> ../../../docs_src/query_params_str_validations/tutorial008.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial008_an_py310.py hl[14] *}
## Alias-Parameter
@@ -768,41 +449,7 @@ Aber Sie möchten dennoch exakt `item-query` verwenden.
Dann können Sie einen `alias` deklarieren, und dieser Alias wird verwendet, um den Parameter-Wert zu finden:
-=== "Python 3.10+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial009_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial009_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params_str_validations/tutorial009_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params_str_validations/tutorial009_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial009.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial009_an_py310.py hl[9] *}
## Parameter als deprecated ausweisen
@@ -812,41 +459,7 @@ Sie müssen ihn eine Weile dort belassen, weil Clients ihn benutzen, aber Sie m
In diesem Fall fügen Sie den Parameter `deprecated=True` zu `Query` hinzu.
-=== "Python 3.10+"
-
- ```Python hl_lines="19"
- {!> ../../../docs_src/query_params_str_validations/tutorial010_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="19"
- {!> ../../../docs_src/query_params_str_validations/tutorial010_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/query_params_str_validations/tutorial010_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="16"
- {!> ../../../docs_src/query_params_str_validations/tutorial010_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/query_params_str_validations/tutorial010.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial010_an_py310.py hl[19] *}
Die Dokumentation wird das so anzeigen:
@@ -856,41 +469,7 @@ Die Dokumentation wird das so anzeigen:
Um einen Query-Parameter vom generierten OpenAPI-Schema auszuschließen (und daher von automatischen Dokumentations-Systemen), setzen Sie den Parameter `include_in_schema` in `Query` auf `False`.
-=== "Python 3.10+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params_str_validations/tutorial014_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params_str_validations/tutorial014_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/query_params_str_validations/tutorial014_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/query_params_str_validations/tutorial014_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params_str_validations/tutorial014.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial014_an_py310.py hl[10] *}
## Zusammenfassung
diff --git a/docs/de/docs/tutorial/query-params.md b/docs/de/docs/tutorial/query-params.md
index 1b9b56bea..0b0f473e2 100644
--- a/docs/de/docs/tutorial/query-params.md
+++ b/docs/de/docs/tutorial/query-params.md
@@ -2,9 +2,7 @@
Wenn Sie in ihrer Funktion Parameter deklarieren, die nicht Teil der Pfad-Parameter sind, dann werden diese automatisch als „Query“-Parameter interpretiert.
-```Python hl_lines="9"
-{!../../../docs_src/query_params/tutorial001.py!}
-```
+{* ../../docs_src/query_params/tutorial001.py hl[9] *}
Query-Parameter (Deutsch: Abfrage-Parameter) sind die Schlüssel-Wert-Paare, die nach dem `?` in einer URL aufgelistet sind, getrennt durch `&`-Zeichen.
@@ -63,38 +61,21 @@ gehen, werden die Parameter-Werte Ihrer Funktion sein:
Auf die gleiche Weise können Sie optionale Query-Parameter deklarieren, indem Sie deren Defaultwert auf `None` setzen:
-=== "Python 3.10+"
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params/tutorial002.py!}
- ```
+{* ../../docs_src/query_params/tutorial002_py310.py hl[7] *}
In diesem Fall wird der Funktionsparameter `q` optional, und standardmäßig `None` sein.
-!!! check
- Beachten Sie auch, dass **FastAPI** intelligent genug ist, um zu erkennen, dass `item_id` ein Pfad-Parameter ist und `q` keiner, daher muss letzteres ein Query-Parameter sein.
+/// check
+
+Beachten Sie auch, dass **FastAPI** intelligent genug ist, um zu erkennen, dass `item_id` ein Pfad-Parameter ist und `q` keiner, daher muss letzteres ein Query-Parameter sein.
+
+///
## Query-Parameter Typkonvertierung
Sie können auch `bool`-Typen deklarieren und sie werden konvertiert:
-=== "Python 3.10+"
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params/tutorial003.py!}
- ```
+{* ../../docs_src/query_params/tutorial003_py310.py hl[7] *}
Wenn Sie nun zu:
@@ -136,17 +117,7 @@ Und Sie müssen sie auch nicht in einer spezifischen Reihenfolge deklarieren.
Parameter werden anhand ihres Namens erkannt:
-=== "Python 3.10+"
-
- ```Python hl_lines="6 8"
- {!> ../../../docs_src/query_params/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="8 10"
- {!> ../../../docs_src/query_params/tutorial004.py!}
- ```
+{* ../../docs_src/query_params/tutorial004_py310.py hl[6,8] *}
## Erforderliche Query-Parameter
@@ -156,9 +127,7 @@ Wenn Sie keinen spezifischen Wert haben wollen, sondern der Parameter einfach op
Aber wenn Sie wollen, dass ein Query-Parameter erforderlich ist, vergeben Sie einfach keinen Defaultwert:
-```Python hl_lines="6-7"
-{!../../../docs_src/query_params/tutorial005.py!}
-```
+{* ../../docs_src/query_params/tutorial005.py hl[6:7] *}
Hier ist `needy` ein erforderlicher Query-Parameter vom Typ `str`.
@@ -204,17 +173,7 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
Und natürlich können Sie einige Parameter als erforderlich, einige mit Defaultwert, und einige als vollständig optional definieren:
-=== "Python 3.10+"
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/query_params/tutorial006_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params/tutorial006.py!}
- ```
+{* ../../docs_src/query_params/tutorial006_py310.py hl[8] *}
In diesem Fall gibt es drei Query-Parameter:
@@ -222,5 +181,8 @@ In diesem Fall gibt es drei Query-Parameter:
* `skip`, ein `int` mit einem Defaultwert `0`.
* `limit`, ein optionales `int`.
-!!! tip "Tipp"
- Sie können auch `Enum`s verwenden, auf die gleiche Weise wie mit [Pfad-Parametern](path-params.md#vordefinierte-parameterwerte){.internal-link target=_blank}.
+/// tip | Tipp
+
+Sie können auch `Enum`s verwenden, auf die gleiche Weise wie mit [Pfad-Parametern](path-params.md#vordefinierte-parameterwerte){.internal-link target=_blank}.
+
+///
diff --git a/docs/de/docs/tutorial/request-files.md b/docs/de/docs/tutorial/request-files.md
index 67b5e3a87..1f01b0d1e 100644
--- a/docs/de/docs/tutorial/request-files.md
+++ b/docs/de/docs/tutorial/request-files.md
@@ -2,70 +2,41 @@
Mit `File` können sie vom Client hochzuladende Dateien definieren.
-!!! info
- Um hochgeladene Dateien zu empfangen, installieren Sie zuerst `python-multipart`.
+/// info
- Z. B. `pip install python-multipart`.
+Um hochgeladene Dateien zu empfangen, installieren Sie zuerst `python-multipart`.
- Das, weil hochgeladene Dateien als „Formulardaten“ gesendet werden.
+Z. B. `pip install python-multipart`.
+
+Das, weil hochgeladene Dateien als „Formulardaten“ gesendet werden.
+
+///
## `File` importieren
Importieren Sie `File` und `UploadFile` von `fastapi`:
-=== "Python 3.9+"
-
- ```Python hl_lines="3"
- {!> ../../../docs_src/request_files/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="1"
- {!> ../../../docs_src/request_files/tutorial001_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="1"
- {!> ../../../docs_src/request_files/tutorial001.py!}
- ```
+{* ../../docs_src/request_files/tutorial001_an_py39.py hl[3] *}
## `File`-Parameter definieren
Erstellen Sie Datei-Parameter, so wie Sie es auch mit `Body` und `Form` machen würden:
-=== "Python 3.9+"
+{* ../../docs_src/request_files/tutorial001_an_py39.py hl[9] *}
- ```Python hl_lines="9"
- {!> ../../../docs_src/request_files/tutorial001_an_py39.py!}
- ```
+/// info
-=== "Python 3.8+"
+`File` ist eine Klasse, die direkt von `Form` erbt.
- ```Python hl_lines="8"
- {!> ../../../docs_src/request_files/tutorial001_an.py!}
- ```
+Aber erinnern Sie sich, dass, wenn Sie `Query`, `Path`, `File` und andere von `fastapi` importieren, diese tatsächlich Funktionen sind, welche spezielle Klassen zurückgeben
-=== "Python 3.8+ nicht annotiert"
+///
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
+/// tip | Tipp
- ```Python hl_lines="7"
- {!> ../../../docs_src/request_files/tutorial001.py!}
- ```
+Um Dateibodys zu deklarieren, müssen Sie `File` verwenden, da diese Parameter sonst als Query-Parameter oder Body(-JSON)-Parameter interpretiert werden würden.
-!!! info
- `File` ist eine Klasse, die direkt von `Form` erbt.
-
- Aber erinnern Sie sich, dass, wenn Sie `Query`, `Path`, `File` und andere von `fastapi` importieren, diese tatsächlich Funktionen sind, welche spezielle Klassen zurückgeben
-
-!!! tip "Tipp"
- Um Dateibodys zu deklarieren, müssen Sie `File` verwenden, da diese Parameter sonst als Query-Parameter oder Body(-JSON)-Parameter interpretiert werden würden.
+///
Die Dateien werden als „Formulardaten“ hochgeladen.
@@ -79,26 +50,7 @@ Aber es gibt viele Fälle, in denen Sie davon profitieren, `UploadFile` zu verwe
Definieren Sie einen Datei-Parameter mit dem Typ `UploadFile`:
-=== "Python 3.9+"
-
- ```Python hl_lines="14"
- {!> ../../../docs_src/request_files/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="13"
- {!> ../../../docs_src/request_files/tutorial001_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/request_files/tutorial001.py!}
- ```
+{* ../../docs_src/request_files/tutorial001_an_py39.py hl[14] *}
`UploadFile` zu verwenden, hat mehrere Vorzüge gegenüber `bytes`:
@@ -141,11 +93,17 @@ Wenn Sie sich innerhalb einer normalen `def`-*Pfadoperation-Funktion* befinden,
contents = myfile.file.read()
```
-!!! note "Technische Details zu `async`"
- Wenn Sie die `async`-Methoden verwenden, führt **FastAPI** die Datei-Methoden in einem Threadpool aus und erwartet sie.
+/// note | Technische Details zu `async`
-!!! note "Technische Details zu Starlette"
- **FastAPI**s `UploadFile` erbt direkt von **Starlette**s `UploadFile`, fügt aber ein paar notwendige Teile hinzu, um es kompatibel mit **Pydantic** und anderen Teilen von FastAPI zu machen.
+Wenn Sie die `async`-Methoden verwenden, führt **FastAPI** die Datei-Methoden in einem Threadpool aus und erwartet sie.
+
+///
+
+/// note | Technische Details zu Starlette
+
+**FastAPI**s `UploadFile` erbt direkt von **Starlette**s `UploadFile`, fügt aber ein paar notwendige Teile hinzu, um es kompatibel mit **Pydantic** und anderen Teilen von FastAPI zu machen.
+
+///
## Was sind „Formulardaten“
@@ -153,82 +111,35 @@ HTML-Formulare (``) senden die Daten in einer „speziellen“ Kodi
**FastAPI** stellt sicher, dass diese Daten korrekt ausgelesen werden, statt JSON zu erwarten.
-!!! note "Technische Details"
- Daten aus Formularen werden, wenn es keine Dateien sind, normalerweise mit dem „media type“ `application/x-www-form-urlencoded` kodiert.
+/// note | Technische Details
- Sollte das Formular aber Dateien enthalten, dann werden diese mit `multipart/form-data` kodiert. Wenn Sie `File` verwenden, wird **FastAPI** wissen, dass es die Dateien vom korrekten Teil des Bodys holen muss.
+Daten aus Formularen werden, wenn es keine Dateien sind, normalerweise mit dem „media type“ `application/x-www-form-urlencoded` kodiert.
- Wenn Sie mehr über Formularfelder und ihre Kodierungen lesen möchten, besuchen Sie die MDN-Webdokumentation für POST.
+Sollte das Formular aber Dateien enthalten, dann werden diese mit `multipart/form-data` kodiert. Wenn Sie `File` verwenden, wird **FastAPI** wissen, dass es die Dateien vom korrekten Teil des Bodys holen muss.
-!!! warning "Achtung"
- Sie können mehrere `File`- und `Form`-Parameter in einer *Pfadoperation* deklarieren, aber Sie können nicht gleichzeitig auch `Body`-Felder deklarieren, welche Sie als JSON erwarten, da der Request den Body mittels `multipart/form-data` statt `application/json` kodiert.
+Wenn Sie mehr über Formularfelder und ihre Kodierungen lesen möchten, besuchen Sie die MDN-Webdokumentation für POST.
- Das ist keine Limitation von **FastAPI**, sondern Teil des HTTP-Protokolls.
+///
+
+/// warning | Achtung
+
+Sie können mehrere `File`- und `Form`-Parameter in einer *Pfadoperation* deklarieren, aber Sie können nicht gleichzeitig auch `Body`-Felder deklarieren, welche Sie als JSON erwarten, da der Request den Body mittels `multipart/form-data` statt `application/json` kodiert.
+
+Das ist keine Limitation von **FastAPI**, sondern Teil des HTTP-Protokolls.
+
+///
## Optionaler Datei-Upload
Sie können eine Datei optional machen, indem Sie Standard-Typannotationen verwenden und den Defaultwert auf `None` setzen:
-=== "Python 3.10+"
-
- ```Python hl_lines="9 17"
- {!> ../../../docs_src/request_files/tutorial001_02_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="9 17"
- {!> ../../../docs_src/request_files/tutorial001_02_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="10 18"
- {!> ../../../docs_src/request_files/tutorial001_02_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="7 15"
- {!> ../../../docs_src/request_files/tutorial001_02_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="9 17"
- {!> ../../../docs_src/request_files/tutorial001_02.py!}
- ```
+{* ../../docs_src/request_files/tutorial001_02_an_py310.py hl[9,17] *}
## `UploadFile` mit zusätzlichen Metadaten
Sie können auch `File()` zusammen mit `UploadFile` verwenden, um zum Beispiel zusätzliche Metadaten zu setzen:
-=== "Python 3.9+"
-
- ```Python hl_lines="9 15"
- {!> ../../../docs_src/request_files/tutorial001_03_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="8 14"
- {!> ../../../docs_src/request_files/tutorial001_03_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="7 13"
- {!> ../../../docs_src/request_files/tutorial001_03.py!}
- ```
+{* ../../docs_src/request_files/tutorial001_03_an_py39.py hl[9,15] *}
## Mehrere Datei-Uploads
@@ -238,76 +149,23 @@ Diese werden demselben Formularfeld zugeordnet, welches mit den Formulardaten ge
Um das zu machen, deklarieren Sie eine Liste von `bytes` oder `UploadFile`s:
-=== "Python 3.9+"
-
- ```Python hl_lines="10 15"
- {!> ../../../docs_src/request_files/tutorial002_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="11 16"
- {!> ../../../docs_src/request_files/tutorial002_an.py!}
- ```
-
-=== "Python 3.9+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="8 13"
- {!> ../../../docs_src/request_files/tutorial002_py39.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="10 15"
- {!> ../../../docs_src/request_files/tutorial002.py!}
- ```
+{* ../../docs_src/request_files/tutorial002_an_py39.py hl[10,15] *}
Sie erhalten, wie deklariert, eine `list`e von `bytes` oder `UploadFile`s.
-!!! note "Technische Details"
- Sie können auch `from starlette.responses import HTMLResponse` verwenden.
+/// note | Technische Details
- **FastAPI** bietet dieselben `starlette.responses` auch via `fastapi.responses` an, als Annehmlichkeit für Sie, den Entwickler. Die meisten verfügbaren Responses kommen aber direkt von Starlette.
+Sie können auch `from starlette.responses import HTMLResponse` verwenden.
+
+**FastAPI** bietet dieselben `starlette.responses` auch via `fastapi.responses` an, als Annehmlichkeit für Sie, den Entwickler. Die meisten verfügbaren Responses kommen aber direkt von Starlette.
+
+///
### Mehrere Datei-Uploads mit zusätzlichen Metadaten
Und so wie zuvor können Sie `File()` verwenden, um zusätzliche Parameter zu setzen, sogar für `UploadFile`:
-=== "Python 3.9+"
-
- ```Python hl_lines="11 18-20"
- {!> ../../../docs_src/request_files/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="12 19-21"
- {!> ../../../docs_src/request_files/tutorial003_an.py!}
- ```
-
-=== "Python 3.9+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="9 16"
- {!> ../../../docs_src/request_files/tutorial003_py39.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="11 18"
- {!> ../../../docs_src/request_files/tutorial003.py!}
- ```
+{* ../../docs_src/request_files/tutorial003_an_py39.py hl[11,18:20] *}
## Zusammenfassung
diff --git a/docs/de/docs/tutorial/request-forms-and-files.md b/docs/de/docs/tutorial/request-forms-and-files.md
index 86b1406e6..3c5e11adf 100644
--- a/docs/de/docs/tutorial/request-forms-and-files.md
+++ b/docs/de/docs/tutorial/request-forms-and-files.md
@@ -2,67 +2,35 @@
Sie können gleichzeitig Dateien und Formulardaten mit `File` und `Form` definieren.
-!!! info
- Um hochgeladene Dateien und/oder Formulardaten zu empfangen, installieren Sie zuerst `python-multipart`.
+/// info
- Z. B. `pip install python-multipart`.
+Um hochgeladene Dateien und/oder Formulardaten zu empfangen, installieren Sie zuerst `python-multipart`.
+
+Z. B. `pip install python-multipart`.
+
+///
## `File` und `Form` importieren
-=== "Python 3.9+"
-
- ```Python hl_lines="3"
- {!> ../../../docs_src/request_forms_and_files/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="1"
- {!> ../../../docs_src/request_forms_and_files/tutorial001_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="1"
- {!> ../../../docs_src/request_forms_and_files/tutorial001.py!}
- ```
+{* ../../docs_src/request_forms_and_files/tutorial001_an_py39.py hl[3] *}
## `File` und `Form`-Parameter definieren
Erstellen Sie Datei- und Formularparameter, so wie Sie es auch mit `Body` und `Query` machen würden:
-=== "Python 3.9+"
-
- ```Python hl_lines="10-12"
- {!> ../../../docs_src/request_forms_and_files/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9-11"
- {!> ../../../docs_src/request_forms_and_files/tutorial001_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/request_forms_and_files/tutorial001.py!}
- ```
+{* ../../docs_src/request_forms_and_files/tutorial001_an_py39.py hl[10:12] *}
Die Datei- und Formularfelder werden als Formulardaten hochgeladen, und Sie erhalten diese Dateien und Formularfelder.
Und Sie können einige der Dateien als `bytes` und einige als `UploadFile` deklarieren.
-!!! warning "Achtung"
- Sie können mehrere `File`- und `Form`-Parameter in einer *Pfadoperation* deklarieren, aber Sie können nicht gleichzeitig auch `Body`-Felder deklarieren, welche Sie als JSON erwarten, da der Request den Body mittels `multipart/form-data` statt `application/json` kodiert.
+/// warning | Achtung
- Das ist keine Limitation von **FastAPI**, sondern Teil des HTTP-Protokolls.
+Sie können mehrere `File`- und `Form`-Parameter in einer *Pfadoperation* deklarieren, aber Sie können nicht gleichzeitig auch `Body`-Felder deklarieren, welche Sie als JSON erwarten, da der Request den Body mittels `multipart/form-data` statt `application/json` kodiert.
+
+Das ist keine Limitation von **FastAPI**, sondern Teil des HTTP-Protokolls.
+
+///
## Zusammenfassung
diff --git a/docs/de/docs/tutorial/request-forms.md b/docs/de/docs/tutorial/request-forms.md
index 6c029b5fe..2f88caaba 100644
--- a/docs/de/docs/tutorial/request-forms.md
+++ b/docs/de/docs/tutorial/request-forms.md
@@ -2,60 +2,25 @@
Wenn Sie Felder aus Formularen statt JSON empfangen müssen, können Sie `Form` verwenden.
-!!! info
- Um Formulare zu verwenden, installieren Sie zuerst `python-multipart`.
+/// info
- Z. B. `pip install python-multipart`.
+Um Formulare zu verwenden, installieren Sie zuerst `python-multipart`.
+
+Z. B. `pip install python-multipart`.
+
+///
## `Form` importieren
Importieren Sie `Form` von `fastapi`:
-=== "Python 3.9+"
-
- ```Python hl_lines="3"
- {!> ../../../docs_src/request_forms/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="1"
- {!> ../../../docs_src/request_forms/tutorial001_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="1"
- {!> ../../../docs_src/request_forms/tutorial001.py!}
- ```
+{* ../../docs_src/request_forms/tutorial001_an_py39.py hl[3] *}
## `Form`-Parameter definieren
Erstellen Sie Formular-Parameter, so wie Sie es auch mit `Body` und `Query` machen würden:
-=== "Python 3.9+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/request_forms/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/request_forms/tutorial001_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/request_forms/tutorial001.py!}
- ```
+{* ../../docs_src/request_forms/tutorial001_an_py39.py hl[9] *}
Zum Beispiel stellt eine der Möglichkeiten, die OAuth2 Spezifikation zu verwenden (genannt „password flow“), die Bedingung, einen `username` und ein `password` als Formularfelder zu senden.
@@ -63,11 +28,17 @@ Die Spec erfordert, dass di
Mit `Form` haben Sie die gleichen Konfigurationsmöglichkeiten wie mit `Body` (und `Query`, `Path`, `Cookie`), inklusive Validierung, Beispielen, einem Alias (z. B. `user-name` statt `username`), usw.
-!!! info
- `Form` ist eine Klasse, die direkt von `Body` erbt.
+/// info
-!!! tip "Tipp"
- Um Formularbodys zu deklarieren, verwenden Sie explizit `Form`, da diese Parameter sonst als Query-Parameter oder Body(-JSON)-Parameter interpretiert werden würden.
+`Form` ist eine Klasse, die direkt von `Body` erbt.
+
+///
+
+/// tip | Tipp
+
+Um Formularbodys zu deklarieren, verwenden Sie explizit `Form`, da diese Parameter sonst als Query-Parameter oder Body(-JSON)-Parameter interpretiert werden würden.
+
+///
## Über „Formularfelder“
@@ -75,17 +46,23 @@ HTML-Formulare (``) senden die Daten in einer „speziellen“ Kodi
**FastAPI** stellt sicher, dass diese Daten korrekt ausgelesen werden, statt JSON zu erwarten.
-!!! note "Technische Details"
- Daten aus Formularen werden normalerweise mit dem „media type“ `application/x-www-form-urlencoded` kodiert.
+/// note | Technische Details
- Wenn das Formular stattdessen Dateien enthält, werden diese mit `multipart/form-data` kodiert. Im nächsten Kapitel erfahren Sie mehr über die Handhabung von Dateien.
+Daten aus Formularen werden normalerweise mit dem „media type“ `application/x-www-form-urlencoded` kodiert.
- Wenn Sie mehr über Formularfelder und ihre Kodierungen lesen möchten, besuchen Sie die MDN-Webdokumentation für POST.
+Wenn das Formular stattdessen Dateien enthält, werden diese mit `multipart/form-data` kodiert. Im nächsten Kapitel erfahren Sie mehr über die Handhabung von Dateien.
-!!! warning "Achtung"
- Sie können mehrere `Form`-Parameter in einer *Pfadoperation* deklarieren, aber Sie können nicht gleichzeitig auch `Body`-Felder deklarieren, welche Sie als JSON erwarten, da der Request den Body mittels `application/x-www-form-urlencoded` statt `application/json` kodiert.
+Wenn Sie mehr über Formularfelder und ihre Kodierungen lesen möchten, besuchen Sie die MDN-Webdokumentation für POST.
- Das ist keine Limitation von **FastAPI**, sondern Teil des HTTP-Protokolls.
+///
+
+/// warning | Achtung
+
+Sie können mehrere `Form`-Parameter in einer *Pfadoperation* deklarieren, aber Sie können nicht gleichzeitig auch `Body`-Felder deklarieren, welche Sie als JSON erwarten, da der Request den Body mittels `application/x-www-form-urlencoded` statt `application/json` kodiert.
+
+Das ist keine Limitation von **FastAPI**, sondern Teil des HTTP-Protokolls.
+
+///
## Zusammenfassung
diff --git a/docs/de/docs/tutorial/response-model.md b/docs/de/docs/tutorial/response-model.md
index d5b92e0f9..faf9be516 100644
--- a/docs/de/docs/tutorial/response-model.md
+++ b/docs/de/docs/tutorial/response-model.md
@@ -4,23 +4,7 @@ Sie können den Typ der ../../../docs_src/response_model/tutorial001_01_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="18 23"
- {!> ../../../docs_src/response_model/tutorial001_01_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="18 23"
- {!> ../../../docs_src/response_model/tutorial001_01.py!}
- ```
+{* ../../docs_src/response_model/tutorial001_01_py310.py hl[16,21] *}
FastAPI wird diesen Rückgabetyp verwenden, um:
@@ -53,35 +37,25 @@ Sie können `response_model` in jeder möglichen *Pfadoperation* verwenden:
* `@app.delete()`
* usw.
-=== "Python 3.10+"
+{* ../../docs_src/response_model/tutorial001_py310.py hl[17,22,24:27] *}
- ```Python hl_lines="17 22 24-27"
- {!> ../../../docs_src/response_model/tutorial001_py310.py!}
- ```
+/// note | Hinweis
-=== "Python 3.9+"
+Beachten Sie, dass `response_model` ein Parameter der „Dekorator“-Methode ist (`get`, `post`, usw.). Nicht der *Pfadoperation-Funktion*, so wie die anderen Parameter.
- ```Python hl_lines="17 22 24-27"
- {!> ../../../docs_src/response_model/tutorial001_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="17 22 24-27"
- {!> ../../../docs_src/response_model/tutorial001.py!}
- ```
-
-!!! note "Hinweis"
- Beachten Sie, dass `response_model` ein Parameter der „Dekorator“-Methode ist (`get`, `post`, usw.). Nicht der *Pfadoperation-Funktion*, so wie die anderen Parameter.
+///
`response_model` nimmt denselben Typ entgegen, den Sie auch für ein Pydantic-Modellfeld deklarieren würden, also etwa ein Pydantic-Modell, aber es kann auch z. B. eine `list`e von Pydantic-Modellen sein, wie etwa `List[Item]`.
FastAPI wird dieses `response_model` nehmen, um die Daten zu dokumentieren, validieren, usw. und auch, um **die Ausgabedaten** entsprechend der Typdeklaration **zu konvertieren und filtern**.
-!!! tip "Tipp"
- Wenn Sie in Ihrem Editor strikte Typchecks haben, mypy, usw., können Sie den Funktions-Rückgabetyp als `Any` deklarieren.
+/// tip | Tipp
- So sagen Sie dem Editor, dass Sie absichtlich *irgendetwas* zurückgeben. Aber FastAPI wird trotzdem die Dokumentation, Validierung, Filterung, usw. der Daten übernehmen, via `response_model`.
+Wenn Sie in Ihrem Editor strikte Typchecks haben, mypy, usw., können Sie den Funktions-Rückgabetyp als `Any` deklarieren.
+
+So sagen Sie dem Editor, dass Sie absichtlich *irgendetwas* zurückgeben. Aber FastAPI wird trotzdem die Dokumentation, Validierung, Filterung, usw. der Daten übernehmen, via `response_model`.
+
+///
### `response_model`-Priorität
@@ -95,37 +69,20 @@ Sie können auch `response_model=None` verwenden, um das Erstellen eines Respons
Im Folgenden deklarieren wir ein `UserIn`-Modell; es enthält ein Klartext-Passwort:
-=== "Python 3.10+"
+{* ../../docs_src/response_model/tutorial002_py310.py hl[7,9] *}
- ```Python hl_lines="7 9"
- {!> ../../../docs_src/response_model/tutorial002_py310.py!}
- ```
+/// info
-=== "Python 3.8+"
+Um `EmailStr` zu verwenden, installieren Sie zuerst `email-validator`.
- ```Python hl_lines="9 11"
- {!> ../../../docs_src/response_model/tutorial002.py!}
- ```
+Z. B. `pip install email-validator`
+oder `pip install pydantic[email]`.
-!!! info
- Um `EmailStr` zu verwenden, installieren Sie zuerst `email_validator`.
-
- Z. B. `pip install email-validator`
- oder `pip install pydantic[email]`.
+///
Wir verwenden dieses Modell, um sowohl unsere Eingabe- als auch Ausgabedaten zu deklarieren:
-=== "Python 3.10+"
-
- ```Python hl_lines="16"
- {!> ../../../docs_src/response_model/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/response_model/tutorial002.py!}
- ```
+{* ../../docs_src/response_model/tutorial002_py310.py hl[16] *}
Immer wenn jetzt ein Browser einen Benutzer mit Passwort erzeugt, gibt die API dasselbe Passwort in der Response zurück.
@@ -133,52 +90,25 @@ Hier ist das möglicherweise kein Problem, da es derselbe Benutzer ist, der das
Aber wenn wir dasselbe Modell für eine andere *Pfadoperation* verwenden, könnten wir das Passwort dieses Benutzers zu jedem Client schicken.
-!!! danger "Gefahr"
- Speichern Sie niemals das Klartext-Passwort eines Benutzers, oder versenden Sie es in einer Response wie dieser, wenn Sie sich nicht der resultierenden Gefahren bewusst sind und nicht wissen, was Sie tun.
+/// danger | Gefahr
+
+Speichern Sie niemals das Klartext-Passwort eines Benutzers, oder versenden Sie es in einer Response wie dieser, wenn Sie sich nicht der resultierenden Gefahren bewusst sind und nicht wissen, was Sie tun.
+
+///
## Ausgabemodell hinzufügen
Wir können stattdessen ein Eingabemodell mit dem Klartext-Passwort, und ein Ausgabemodell ohne das Passwort erstellen:
-=== "Python 3.10+"
-
- ```Python hl_lines="9 11 16"
- {!> ../../../docs_src/response_model/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9 11 16"
- {!> ../../../docs_src/response_model/tutorial003.py!}
- ```
+{* ../../docs_src/response_model/tutorial003_py310.py hl[9,11,16] *}
Obwohl unsere *Pfadoperation-Funktion* hier denselben `user` von der Eingabe zurückgibt, der das Passwort enthält:
-=== "Python 3.10+"
-
- ```Python hl_lines="24"
- {!> ../../../docs_src/response_model/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="24"
- {!> ../../../docs_src/response_model/tutorial003.py!}
- ```
+{* ../../docs_src/response_model/tutorial003_py310.py hl[24] *}
... haben wir deklariert, dass `response_model` das Modell `UserOut` ist, welches das Passwort nicht enthält:
-=== "Python 3.10+"
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/response_model/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/response_model/tutorial003.py!}
- ```
+{* ../../docs_src/response_model/tutorial003_py310.py hl[22] *}
Darum wird **FastAPI** sich darum kümmern, dass alle Daten, die nicht im Ausgabemodell deklariert sind, herausgefiltert werden (mittels Pydantic).
@@ -202,17 +132,7 @@ Aber in den meisten Fällen, wenn wir so etwas machen, wollen wir nur, dass das
Und in solchen Fällen können wir Klassen und Vererbung verwenden, um Vorteil aus den Typannotationen in der Funktion zu ziehen, was vom Editor und von Tools besser unterstützt wird, während wir gleichzeitig FastAPIs **Datenfilterung** behalten.
-=== "Python 3.10+"
-
- ```Python hl_lines="7-10 13-14 18"
- {!> ../../../docs_src/response_model/tutorial003_01_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9-13 15-16 20"
- {!> ../../../docs_src/response_model/tutorial003_01.py!}
- ```
+{* ../../docs_src/response_model/tutorial003_01_py310.py hl[7:10,13:14,18] *}
Damit erhalten wir Tool-Unterstützung, vom Editor und mypy, da dieser Code hinsichtlich der Typen korrekt ist, aber wir erhalten auch die Datenfilterung von FastAPI.
@@ -254,9 +174,7 @@ Es kann Fälle geben, bei denen Sie etwas zurückgeben, das kein gültiges Pydan
Der häufigste Anwendungsfall ist, wenn Sie [eine Response direkt zurückgeben, wie es später im Handbuch für fortgeschrittene Benutzer erläutert wird](../advanced/response-directly.md){.internal-link target=_blank}.
-```Python hl_lines="8 10-11"
-{!> ../../../docs_src/response_model/tutorial003_02.py!}
-```
+{* ../../docs_src/response_model/tutorial003_02.py hl[8,10:11] *}
Dieser einfache Anwendungsfall wird automatisch von FastAPI gehandhabt, weil die Annotation des Rückgabetyps die Klasse (oder eine Unterklasse von) `Response` ist.
@@ -266,9 +184,7 @@ Und Tools werden auch glücklich sein, weil sowohl `RedirectResponse` als auch `
Sie können auch eine Unterklasse von `Response` in der Typannotation verwenden.
-```Python hl_lines="8-9"
-{!> ../../../docs_src/response_model/tutorial003_03.py!}
-```
+{* ../../docs_src/response_model/tutorial003_03.py hl[8:9] *}
Das wird ebenfalls funktionieren, weil `RedirectResponse` eine Unterklasse von `Response` ist, und FastAPI sich um diesen einfachen Anwendungsfall automatisch kümmert.
@@ -278,17 +194,7 @@ Aber wenn Sie ein beliebiges anderes Objekt zurückgeben, das kein gültiger Pyd
Das gleiche wird passieren, wenn Sie eine Union mehrerer Typen haben, und einer oder mehrere sind nicht gültige Pydantic-Typen. Zum Beispiel funktioniert folgendes nicht 💥:
-=== "Python 3.10+"
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/response_model/tutorial003_04_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/response_model/tutorial003_04.py!}
- ```
+{* ../../docs_src/response_model/tutorial003_04_py310.py hl[8] *}
... das scheitert, da die Typannotation kein Pydantic-Typ ist, und auch keine einzelne `Response`-Klasse, oder -Unterklasse, es ist eine Union (eines von beiden) von `Response` und `dict`.
@@ -300,17 +206,7 @@ Aber Sie möchten dennoch den Rückgabetyp in der Funktion annotieren, um Unters
In diesem Fall können Sie die Generierung des Responsemodells abschalten, indem Sie `response_model=None` setzen:
-=== "Python 3.10+"
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/response_model/tutorial003_05_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/response_model/tutorial003_05.py!}
- ```
+{* ../../docs_src/response_model/tutorial003_05_py310.py hl[7] *}
Das bewirkt, dass FastAPI die Generierung des Responsemodells unterlässt, und damit können Sie jede gewünschte Rückgabetyp-Annotation haben, ohne dass es Ihre FastAPI-Anwendung beeinflusst. 🤓
@@ -318,23 +214,7 @@ Das bewirkt, dass FastAPI die Generierung des Responsemodells unterlässt, und d
Ihr Responsemodell könnte Defaultwerte haben, wie:
-=== "Python 3.10+"
-
- ```Python hl_lines="9 11-12"
- {!> ../../../docs_src/response_model/tutorial004_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="11 13-14"
- {!> ../../../docs_src/response_model/tutorial004_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="11 13-14"
- {!> ../../../docs_src/response_model/tutorial004.py!}
- ```
+{* ../../docs_src/response_model/tutorial004_py310.py hl[9,11:12] *}
* `description: Union[str, None] = None` (oder `str | None = None` in Python 3.10) hat einen Defaultwert `None`.
* `tax: float = 10.5` hat einen Defaultwert `10.5`.
@@ -348,23 +228,7 @@ Wenn Sie zum Beispiel Modelle mit vielen optionalen Attributen in einer NoSQL-Da
Sie können den *Pfadoperation-Dekorator*-Parameter `response_model_exclude_unset=True` setzen:
-=== "Python 3.10+"
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/response_model/tutorial004_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="24"
- {!> ../../../docs_src/response_model/tutorial004_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="24"
- {!> ../../../docs_src/response_model/tutorial004.py!}
- ```
+{* ../../docs_src/response_model/tutorial004_py310.py hl[22] *}
Die Defaultwerte werden dann nicht in der Response enthalten sein, sondern nur die tatsächlich gesetzten Werte.
@@ -377,21 +241,30 @@ Wenn Sie also den Artikel mit der ID `foo` bei der *Pfadoperation* anfragen, wir
}
```
-!!! info
- In Pydantic v1 hieß diese Methode `.dict()`, in Pydantic v2 wurde sie deprecated (aber immer noch unterstützt) und in `.model_dump()` umbenannt.
+/// info
- Die Beispiele hier verwenden `.dict()` für die Kompatibilität mit Pydantic v1, Sie sollten jedoch stattdessen `.model_dump()` verwenden, wenn Sie Pydantic v2 verwenden können.
+In Pydantic v1 hieß diese Methode `.dict()`, in Pydantic v2 wurde sie deprecated (aber immer noch unterstützt) und in `.model_dump()` umbenannt.
-!!! info
- FastAPI verwendet `.dict()` von Pydantic Modellen, mit dessen `exclude_unset`-Parameter, um das zu erreichen.
+Die Beispiele hier verwenden `.dict()` für die Kompatibilität mit Pydantic v1, Sie sollten jedoch stattdessen `.model_dump()` verwenden, wenn Sie Pydantic v2 verwenden können.
-!!! info
- Sie können auch:
+///
- * `response_model_exclude_defaults=True`
- * `response_model_exclude_none=True`
+/// info
- verwenden, wie in der Pydantic Dokumentation für `exclude_defaults` und `exclude_none` beschrieben.
+FastAPI verwendet `.dict()` von Pydantic Modellen, mit dessen `exclude_unset`-Parameter, um das zu erreichen.
+
+///
+
+/// info
+
+Sie können auch:
+
+* `response_model_exclude_defaults=True`
+* `response_model_exclude_none=True`
+
+verwenden, wie in der Pydantic Dokumentation für `exclude_defaults` und `exclude_none` beschrieben.
+
+///
#### Daten mit Werten für Felder mit Defaultwerten
@@ -426,10 +299,13 @@ dann ist FastAPI klug genug (tatsächlich ist Pydantic klug genug) zu erkennen,
Diese Felder werden also in der JSON-Response enthalten sein.
-!!! tip "Tipp"
- Beachten Sie, dass Defaultwerte alles Mögliche sein können, nicht nur `None`.
+/// tip | Tipp
- Sie können eine Liste (`[]`), ein `float` `10.5`, usw. sein.
+Beachten Sie, dass Defaultwerte alles Mögliche sein können, nicht nur `None`.
+
+Sie können eine Liste (`[]`), ein `float` `10.5`, usw. sein.
+
+///
### `response_model_include` und `response_model_exclude`
@@ -439,45 +315,31 @@ Diese nehmen ein `set` von `str`s entgegen, welches Namen von Attributen sind, d
Das kann als schnelle Abkürzung verwendet werden, wenn Sie nur ein Pydantic-Modell haben und ein paar Daten von der Ausgabe ausschließen wollen.
-!!! tip "Tipp"
- Es wird dennoch empfohlen, dass Sie die Ideen von oben verwenden, also mehrere Klassen statt dieser Parameter.
+/// tip | Tipp
- Der Grund ist, dass das das generierte JSON-Schema in der OpenAPI ihrer Anwendung (und deren Dokumentation) dennoch das komplette Modell abbildet, selbst wenn Sie `response_model_include` oder `response_model_exclude` verwenden, um einige Attribute auszuschließen.
+Es wird dennoch empfohlen, dass Sie die Ideen von oben verwenden, also mehrere Klassen statt dieser Parameter.
- Das trifft auch auf `response_model_by_alias` zu, welches ähnlich funktioniert.
+Der Grund ist, dass das das generierte JSON-Schema in der OpenAPI ihrer Anwendung (und deren Dokumentation) dennoch das komplette Modell abbildet, selbst wenn Sie `response_model_include` oder `response_model_exclude` verwenden, um einige Attribute auszuschließen.
-=== "Python 3.10+"
+Das trifft auch auf `response_model_by_alias` zu, welches ähnlich funktioniert.
- ```Python hl_lines="29 35"
- {!> ../../../docs_src/response_model/tutorial005_py310.py!}
- ```
+///
-=== "Python 3.8+"
+{* ../../docs_src/response_model/tutorial005_py310.py hl[29,35] *}
- ```Python hl_lines="31 37"
- {!> ../../../docs_src/response_model/tutorial005.py!}
- ```
+/// tip | Tipp
-!!! tip "Tipp"
- Die Syntax `{"name", "description"}` erzeugt ein `set` mit diesen zwei Werten.
+Die Syntax `{"name", "description"}` erzeugt ein `set` mit diesen zwei Werten.
- Äquivalent zu `set(["name", "description"])`.
+Äquivalent zu `set(["name", "description"])`.
+
+///
#### `list`en statt `set`s verwenden
Wenn Sie vergessen, ein `set` zu verwenden, und stattdessen eine `list`e oder ein `tuple` übergeben, wird FastAPI die dennoch in ein `set` konvertieren, und es wird korrekt funktionieren:
-=== "Python 3.10+"
-
- ```Python hl_lines="29 35"
- {!> ../../../docs_src/response_model/tutorial006_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="31 37"
- {!> ../../../docs_src/response_model/tutorial006.py!}
- ```
+{* ../../docs_src/response_model/tutorial006_py310.py hl[29,35] *}
## Zusammenfassung
diff --git a/docs/de/docs/tutorial/response-status-code.md b/docs/de/docs/tutorial/response-status-code.md
index a9cc238f8..a1b388a0a 100644
--- a/docs/de/docs/tutorial/response-status-code.md
+++ b/docs/de/docs/tutorial/response-status-code.md
@@ -8,17 +8,21 @@ So wie ein Responsemodell, können Sie auch einen HTTP-Statuscode für die Respo
* `@app.delete()`
* usw.
-```Python hl_lines="6"
-{!../../../docs_src/response_status_code/tutorial001.py!}
-```
+{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
-!!! note "Hinweis"
- Beachten Sie, dass `status_code` ein Parameter der „Dekorator“-Methode ist (`get`, `post`, usw.). Nicht der *Pfadoperation-Funktion*, so wie die anderen Parameter und der Body.
+/// note | Hinweis
+
+Beachten Sie, dass `status_code` ein Parameter der „Dekorator“-Methode ist (`get`, `post`, usw.). Nicht der *Pfadoperation-Funktion*, so wie die anderen Parameter und der Body.
+
+///
Dem `status_code`-Parameter wird eine Zahl mit dem HTTP-Statuscode übergeben.
-!!! info
- Alternativ kann `status_code` auch ein `IntEnum` erhalten, so wie Pythons `http.HTTPStatus`.
+/// info
+
+Alternativ kann `status_code` auch ein `IntEnum` erhalten, so wie Pythons `http.HTTPStatus`.
+
+///
Das wird:
@@ -27,15 +31,21 @@ Das wird:
-!!! note "Hinweis"
- Einige Responsecodes (siehe nächster Abschnitt) kennzeichnen, dass die Response keinen Body hat.
+/// note | Hinweis
- FastAPI versteht das und wird in der OpenAPI-Dokumentation anzeigen, dass es keinen Responsebody gibt.
+Einige Responsecodes (siehe nächster Abschnitt) kennzeichnen, dass die Response keinen Body hat.
+
+FastAPI versteht das und wird in der OpenAPI-Dokumentation anzeigen, dass es keinen Responsebody gibt.
+
+///
## Über HTTP-Statuscodes
-!!! note "Hinweis"
- Wenn Sie bereits wissen, was HTTP-Statuscodes sind, überspringen Sie dieses Kapitel und fahren Sie mit dem nächsten fort.
+/// note | Hinweis
+
+Wenn Sie bereits wissen, was HTTP-Statuscodes sind, überspringen Sie dieses Kapitel und fahren Sie mit dem nächsten fort.
+
+///
In HTTP senden Sie als Teil der Response einen aus drei Ziffern bestehenden numerischen Statuscode.
@@ -54,16 +64,17 @@ Kurz:
* Für allgemeine Fehler beim Client können Sie einfach `400` verwenden.
* `500` und darüber stehen für Server-Fehler. Diese verwenden Sie fast nie direkt. Wenn etwas an irgendeiner Stelle in Ihrem Anwendungscode oder im Server schiefläuft, wird automatisch einer dieser Fehler-Statuscodes zurückgegeben.
-!!! tip "Tipp"
- Um mehr über Statuscodes zu lernen, und welcher wofür verwendet wird, lesen Sie die MDN Dokumentation über HTTP-Statuscodes.
+/// tip | Tipp
+
+Um mehr über Statuscodes zu lernen, und welcher wofür verwendet wird, lesen Sie die MDN Dokumentation über HTTP-Statuscodes.
+
+///
## Abkürzung, um die Namen zu erinnern
Schauen wir uns das vorherige Beispiel noch einmal an:
-```Python hl_lines="6"
-{!../../../docs_src/response_status_code/tutorial001.py!}
-```
+{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
`201` ist der Statuscode für „Created“ („Erzeugt“).
@@ -71,18 +82,19 @@ Aber Sie müssen sich nicht daran erinnern, welcher dieser Codes was bedeutet.
Sie können die Hilfsvariablen von `fastapi.status` verwenden.
-```Python hl_lines="1 6"
-{!../../../docs_src/response_status_code/tutorial002.py!}
-```
+{* ../../docs_src/response_status_code/tutorial002.py hl[1,6] *}
Diese sind nur eine Annehmlichkeit und enthalten dieselbe Nummer, aber auf diese Weise können Sie die Autovervollständigung Ihres Editors verwenden, um sie zu finden:
-!!! note "Technische Details"
- Sie können auch `from starlette import status` verwenden.
+/// note | Technische Details
- **FastAPI** bietet dieselben `starlette.status`-Codes auch via `fastapi.status` an, als Annehmlichkeit für Sie, den Entwickler. Sie kommen aber direkt von Starlette.
+Sie können auch `from starlette import status` verwenden.
+
+**FastAPI** bietet dieselben `starlette.status`-Codes auch via `fastapi.status` an, als Annehmlichkeit für Sie, den Entwickler. Sie kommen aber direkt von Starlette.
+
+///
## Den Defaultwert ändern
diff --git a/docs/de/docs/tutorial/schema-extra-example.md b/docs/de/docs/tutorial/schema-extra-example.md
index e8bfc9876..f065ad4ca 100644
--- a/docs/de/docs/tutorial/schema-extra-example.md
+++ b/docs/de/docs/tutorial/schema-extra-example.md
@@ -8,71 +8,59 @@ Hier sind mehrere Möglichkeiten, das zu tun.
Sie können `examples` („Beispiele“) für ein Pydantic-Modell deklarieren, welche dem generierten JSON-Schema hinzugefügt werden.
-=== "Python 3.10+ Pydantic v2"
+//// tab | Pydantic v2
- ```Python hl_lines="13-24"
- {!> ../../../docs_src/schema_extra_example/tutorial001_py310.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial001_py310.py hl[13:24] *}
-=== "Python 3.10+ Pydantic v1"
+////
- ```Python hl_lines="13-23"
- {!> ../../../docs_src/schema_extra_example/tutorial001_py310_pv1.py!}
- ```
+//// tab | Pydantic v1
-=== "Python 3.8+ Pydantic v2"
+{* ../../docs_src/schema_extra_example/tutorial001_pv1_py310.py hl[13:23] *}
- ```Python hl_lines="15-26"
- {!> ../../../docs_src/schema_extra_example/tutorial001.py!}
- ```
-
-=== "Python 3.8+ Pydantic v1"
-
- ```Python hl_lines="15-25"
- {!> ../../../docs_src/schema_extra_example/tutorial001_pv1.py!}
- ```
+////
Diese zusätzlichen Informationen werden unverändert zum für dieses Modell ausgegebenen **JSON-Schema** hinzugefügt und in der API-Dokumentation verwendet.
-=== "Pydantic v2"
+//// tab | Pydantic v2
- In Pydantic Version 2 würden Sie das Attribut `model_config` verwenden, das ein `dict` akzeptiert, wie beschrieben in Pydantic-Dokumentation: Configuration.
+In Pydantic Version 2 würden Sie das Attribut `model_config` verwenden, das ein `dict` akzeptiert, wie beschrieben in Pydantic-Dokumentation: Configuration.
- Sie können `json_schema_extra` setzen, mit einem `dict`, das alle zusätzlichen Daten enthält, die im generierten JSON-Schema angezeigt werden sollen, einschließlich `examples`.
+Sie können `json_schema_extra` setzen, mit einem `dict`, das alle zusätzlichen Daten enthält, die im generierten JSON-Schema angezeigt werden sollen, einschließlich `examples`.
-=== "Pydantic v1"
+////
- In Pydantic Version 1 würden Sie eine interne Klasse `Config` und `schema_extra` verwenden, wie beschrieben in Pydantic-Dokumentation: Schema customization.
+//// tab | Pydantic v1
- Sie können `schema_extra` setzen, mit einem `dict`, das alle zusätzlichen Daten enthält, die im generierten JSON-Schema angezeigt werden sollen, einschließlich `examples`.
+In Pydantic Version 1 würden Sie eine interne Klasse `Config` und `schema_extra` verwenden, wie beschrieben in Pydantic-Dokumentation: Schema customization.
-!!! tip "Tipp"
- Mit derselben Technik können Sie das JSON-Schema erweitern und Ihre eigenen benutzerdefinierten Zusatzinformationen hinzufügen.
+Sie können `schema_extra` setzen, mit einem `dict`, das alle zusätzlichen Daten enthält, die im generierten JSON-Schema angezeigt werden sollen, einschließlich `examples`.
- Sie könnten das beispielsweise verwenden, um Metadaten für eine Frontend-Benutzeroberfläche usw. hinzuzufügen.
+////
-!!! info
- OpenAPI 3.1.0 (verwendet seit FastAPI 0.99.0) hat Unterstützung für `examples` hinzugefügt, was Teil des **JSON Schema** Standards ist.
+/// tip | Tipp
- Zuvor unterstützte es nur das Schlüsselwort `example` mit einem einzigen Beispiel. Dieses wird weiterhin von OpenAPI 3.1.0 unterstützt, ist jedoch deprecated und nicht Teil des JSON Schema Standards. Wir empfehlen Ihnen daher, von `example` nach `examples` zu migrieren. 🤓
+Mit derselben Technik können Sie das JSON-Schema erweitern und Ihre eigenen benutzerdefinierten Zusatzinformationen hinzufügen.
- Mehr erfahren Sie am Ende dieser Seite.
+Sie könnten das beispielsweise verwenden, um Metadaten für eine Frontend-Benutzeroberfläche usw. hinzuzufügen.
+
+///
+
+/// info
+
+OpenAPI 3.1.0 (verwendet seit FastAPI 0.99.0) hat Unterstützung für `examples` hinzugefügt, was Teil des **JSON Schema** Standards ist.
+
+Zuvor unterstützte es nur das Schlüsselwort `example` mit einem einzigen Beispiel. Dieses wird weiterhin von OpenAPI 3.1.0 unterstützt, ist jedoch deprecated und nicht Teil des JSON Schema Standards. Wir empfehlen Ihnen daher, von `example` nach `examples` zu migrieren. 🤓
+
+Mehr erfahren Sie am Ende dieser Seite.
+
+///
## Zusätzliche Argumente für `Field`
Wenn Sie `Field()` mit Pydantic-Modellen verwenden, können Sie ebenfalls zusätzliche `examples` deklarieren:
-=== "Python 3.10+"
-
- ```Python hl_lines="2 8-11"
- {!> ../../../docs_src/schema_extra_example/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="4 10-13"
- {!> ../../../docs_src/schema_extra_example/tutorial002.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial002_py310.py hl[2,8:11] *}
## `examples` im JSON-Schema – OpenAPI
@@ -92,41 +80,7 @@ können Sie auch eine Gruppe von `examples` mit zusätzlichen Informationen dekl
Hier übergeben wir `examples`, welches ein einzelnes Beispiel für die in `Body()` erwarteten Daten enthält:
-=== "Python 3.10+"
-
- ```Python hl_lines="22-29"
- {!> ../../../docs_src/schema_extra_example/tutorial003_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="22-29"
- {!> ../../../docs_src/schema_extra_example/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="23-30"
- {!> ../../../docs_src/schema_extra_example/tutorial003_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="18-25"
- {!> ../../../docs_src/schema_extra_example/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="20-27"
- {!> ../../../docs_src/schema_extra_example/tutorial003.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial003_an_py310.py hl[22:29] *}
### Beispiel in der Dokumentations-Benutzeroberfläche
@@ -138,41 +92,7 @@ Mit jeder der oben genannten Methoden würde es in `/docs` so aussehen:
Sie können natürlich auch mehrere `examples` übergeben:
-=== "Python 3.10+"
-
- ```Python hl_lines="23-38"
- {!> ../../../docs_src/schema_extra_example/tutorial004_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="23-38"
- {!> ../../../docs_src/schema_extra_example/tutorial004_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="24-39"
- {!> ../../../docs_src/schema_extra_example/tutorial004_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="19-34"
- {!> ../../../docs_src/schema_extra_example/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="21-36"
- {!> ../../../docs_src/schema_extra_example/tutorial004.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial004_an_py310.py hl[23:38] *}
Wenn Sie das tun, werden die Beispiele Teil des internen **JSON-Schemas** für diese Body-Daten.
@@ -213,41 +133,7 @@ Jedes spezifische Beispiel-`dict` in den `examples` kann Folgendes enthalten:
Sie können es so verwenden:
-=== "Python 3.10+"
-
- ```Python hl_lines="23-49"
- {!> ../../../docs_src/schema_extra_example/tutorial005_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="23-49"
- {!> ../../../docs_src/schema_extra_example/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="24-50"
- {!> ../../../docs_src/schema_extra_example/tutorial005_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="19-45"
- {!> ../../../docs_src/schema_extra_example/tutorial005_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="21-47"
- {!> ../../../docs_src/schema_extra_example/tutorial005.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial005_an_py310.py hl[23:49] *}
### OpenAPI-Beispiele in der Dokumentations-Benutzeroberfläche
@@ -257,17 +143,23 @@ Wenn `openapi_examples` zu `Body()` hinzugefügt wird, würde `/docs` so aussehe
## Technische Details
-!!! tip "Tipp"
- Wenn Sie bereits **FastAPI** Version **0.99.0 oder höher** verwenden, können Sie diese Details wahrscheinlich **überspringen**.
+/// tip | Tipp
- Sie sind für ältere Versionen relevanter, bevor OpenAPI 3.1.0 verfügbar war.
+Wenn Sie bereits **FastAPI** Version **0.99.0 oder höher** verwenden, können Sie diese Details wahrscheinlich **überspringen**.
- Sie können dies als eine kurze **Geschichtsstunde** zu OpenAPI und JSON Schema betrachten. 🤓
+Sie sind für ältere Versionen relevanter, bevor OpenAPI 3.1.0 verfügbar war.
-!!! warning "Achtung"
- Dies sind sehr technische Details zu den Standards **JSON Schema** und **OpenAPI**.
+Sie können dies als eine kurze **Geschichtsstunde** zu OpenAPI und JSON Schema betrachten. 🤓
- Wenn die oben genannten Ideen bereits für Sie funktionieren, reicht das möglicherweise aus und Sie benötigen diese Details wahrscheinlich nicht, überspringen Sie sie gerne.
+///
+
+/// warning | Achtung
+
+Dies sind sehr technische Details zu den Standards **JSON Schema** und **OpenAPI**.
+
+Wenn die oben genannten Ideen bereits für Sie funktionieren, reicht das möglicherweise aus und Sie benötigen diese Details wahrscheinlich nicht, überspringen Sie sie gerne.
+
+///
Vor OpenAPI 3.1.0 verwendete OpenAPI eine ältere und modifizierte Version von **JSON Schema**.
@@ -285,8 +177,11 @@ OpenAPI fügte auch die Felder `example` und `examples` zu anderen Teilen der Sp
* `File()`
* `Form()`
-!!! info
- Dieser alte, OpenAPI-spezifische `examples`-Parameter heißt seit FastAPI `0.103.0` jetzt `openapi_examples`.
+/// info
+
+Dieser alte, OpenAPI-spezifische `examples`-Parameter heißt seit FastAPI `0.103.0` jetzt `openapi_examples`.
+
+///
### JSON Schemas Feld `examples`
@@ -298,10 +193,13 @@ Und jetzt hat dieses neue `examples`-Feld Vorrang vor dem alten (und benutzerdef
Dieses neue `examples`-Feld in JSON Schema ist **nur eine `list`e** von Beispielen, kein Dict mit zusätzlichen Metadaten wie an den anderen Stellen in OpenAPI (oben beschrieben).
-!!! info
- Selbst, nachdem OpenAPI 3.1.0 veröffentlicht wurde, mit dieser neuen, einfacheren Integration mit JSON Schema, unterstützte Swagger UI, das Tool, das die automatische Dokumentation bereitstellt, eine Zeit lang OpenAPI 3.1.0 nicht (das tut es seit Version 5.0.0 🎉).
+/// info
- Aus diesem Grund verwendeten Versionen von FastAPI vor 0.99.0 immer noch Versionen von OpenAPI vor 3.1.0.
+Selbst, nachdem OpenAPI 3.1.0 veröffentlicht wurde, mit dieser neuen, einfacheren Integration mit JSON Schema, unterstützte Swagger UI, das Tool, das die automatische Dokumentation bereitstellt, eine Zeit lang OpenAPI 3.1.0 nicht (das tut es seit Version 5.0.0 🎉).
+
+Aus diesem Grund verwendeten Versionen von FastAPI vor 0.99.0 immer noch Versionen von OpenAPI vor 3.1.0.
+
+///
### Pydantic- und FastAPI-`examples`
diff --git a/docs/de/docs/tutorial/security/first-steps.md b/docs/de/docs/tutorial/security/first-steps.md
index 1e75fa8d9..8fa33db7e 100644
--- a/docs/de/docs/tutorial/security/first-steps.md
+++ b/docs/de/docs/tutorial/security/first-steps.md
@@ -20,35 +20,19 @@ Lassen Sie uns zunächst einfach den Code verwenden und sehen, wie er funktionie
Kopieren Sie das Beispiel in eine Datei `main.py`:
-=== "Python 3.9+"
-
- ```Python
- {!> ../../../docs_src/security/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python
- {!> ../../../docs_src/security/tutorial001_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python
- {!> ../../../docs_src/security/tutorial001.py!}
- ```
+{* ../../docs_src/security/tutorial001_an_py39.py *}
## Ausführen
-!!! info
- Um hochgeladene Dateien zu empfangen, installieren Sie zuerst `python-multipart`.
+/// info
- Z. B. `pip install python-multipart`.
+Um hochgeladene Dateien zu empfangen, installieren Sie zuerst `python-multipart`.
- Das, weil **OAuth2** „Formulardaten“ zum Senden von `username` und `password` verwendet.
+Z. B. `pip install python-multipart`.
+
+Das, weil **OAuth2** „Formulardaten“ zum Senden von `username` und `password` verwendet.
+
+///
Führen Sie das Beispiel aus mit:
@@ -70,17 +54,23 @@ Sie werden etwa Folgendes sehen:
-!!! check "Authorize-Button!"
- Sie haben bereits einen glänzenden, neuen „Authorize“-Button.
+/// check | Authorize-Button!
- Und Ihre *Pfadoperation* hat in der oberen rechten Ecke ein kleines Schloss, auf das Sie klicken können.
+Sie haben bereits einen glänzenden, neuen „Authorize“-Button.
+
+Und Ihre *Pfadoperation* hat in der oberen rechten Ecke ein kleines Schloss, auf das Sie klicken können.
+
+///
Und wenn Sie darauf klicken, erhalten Sie ein kleines Anmeldeformular zur Eingabe eines `username` und `password` (und anderer optionaler Felder):
-!!! note "Hinweis"
- Es spielt keine Rolle, was Sie in das Formular eingeben, es wird noch nicht funktionieren. Wir kommen dahin.
+/// note | Hinweis
+
+Es spielt keine Rolle, was Sie in das Formular eingeben, es wird noch nicht funktionieren. Wir kommen dahin.
+
+///
Dies ist natürlich nicht das Frontend für die Endbenutzer, aber es ist ein großartiges automatisches Tool, um Ihre gesamte API interaktiv zu dokumentieren.
@@ -122,53 +112,43 @@ Betrachten wir es also aus dieser vereinfachten Sicht:
In diesem Beispiel verwenden wir **OAuth2** mit dem **Password**-Flow und einem **Bearer**-Token. Wir machen das mit der Klasse `OAuth2PasswordBearer`.
-!!! info
- Ein „Bearer“-Token ist nicht die einzige Option.
+/// info
- Aber es ist die beste für unseren Anwendungsfall.
+Ein „Bearer“-Token ist nicht die einzige Option.
- Und es ist wahrscheinlich auch für die meisten anderen Anwendungsfälle die beste, es sei denn, Sie sind ein OAuth2-Experte und wissen genau, warum es eine andere Option gibt, die Ihren Anforderungen besser entspricht.
+Aber es ist die beste für unseren Anwendungsfall.
- In dem Fall gibt Ihnen **FastAPI** ebenfalls die Tools, die Sie zum Erstellen brauchen.
+Und es ist wahrscheinlich auch für die meisten anderen Anwendungsfälle die beste, es sei denn, Sie sind ein OAuth2-Experte und wissen genau, warum es eine andere Option gibt, die Ihren Anforderungen besser entspricht.
+
+In dem Fall gibt Ihnen **FastAPI** ebenfalls die Tools, die Sie zum Erstellen brauchen.
+
+///
Wenn wir eine Instanz der Klasse `OAuth2PasswordBearer` erstellen, übergeben wir den Parameter `tokenUrl`. Dieser Parameter enthält die URL, die der Client (das Frontend, das im Browser des Benutzers ausgeführt wird) verwendet, wenn er den `username` und das `password` sendet, um einen Token zu erhalten.
-=== "Python 3.9+"
+{* ../../docs_src/security/tutorial001_an_py39.py hl[8] *}
- ```Python hl_lines="8"
- {!> ../../../docs_src/security/tutorial001_an_py39.py!}
- ```
+/// tip | Tipp
-=== "Python 3.8+"
+Hier bezieht sich `tokenUrl="token"` auf eine relative URL `token`, die wir noch nicht erstellt haben. Da es sich um eine relative URL handelt, entspricht sie `./token`.
- ```Python hl_lines="7"
- {!> ../../../docs_src/security/tutorial001_an.py!}
- ```
+Da wir eine relative URL verwenden, würde sich das, wenn sich Ihre API unter `https://example.com/` befindet, auf `https://example.com/token` beziehen. Wenn sich Ihre API jedoch unter `https://example.com/api/v1/` befände, würde es sich auf `https://example.com/api/v1/token` beziehen.
-=== "Python 3.8+ nicht annotiert"
+Die Verwendung einer relativen URL ist wichtig, um sicherzustellen, dass Ihre Anwendung auch in einem fortgeschrittenen Anwendungsfall, wie [hinter einem Proxy](../../advanced/behind-a-proxy.md){.internal-link target=_blank}, weiterhin funktioniert.
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="6"
- {!> ../../../docs_src/security/tutorial001.py!}
- ```
-
-!!! tip "Tipp"
- Hier bezieht sich `tokenUrl="token"` auf eine relative URL `token`, die wir noch nicht erstellt haben. Da es sich um eine relative URL handelt, entspricht sie `./token`.
-
- Da wir eine relative URL verwenden, würde sich das, wenn sich Ihre API unter `https://example.com/` befindet, auf `https://example.com/token` beziehen. Wenn sich Ihre API jedoch unter `https://example.com/api/v1/` befände, würde es sich auf `https://example.com/api/v1/token` beziehen.
-
- Die Verwendung einer relativen URL ist wichtig, um sicherzustellen, dass Ihre Anwendung auch in einem fortgeschrittenen Anwendungsfall, wie [hinter einem Proxy](../../advanced/behind-a-proxy.md){.internal-link target=_blank}, weiterhin funktioniert.
+///
Dieser Parameter erstellt nicht diesen Endpunkt / diese *Pfadoperation*, sondern deklariert, dass die URL `/token` diejenige sein wird, die der Client verwenden soll, um den Token abzurufen. Diese Information wird in OpenAPI und dann in den interaktiven API-Dokumentationssystemen verwendet.
Wir werden demnächst auch die eigentliche Pfadoperation erstellen.
-!!! info
- Wenn Sie ein sehr strenger „Pythonista“ sind, missfällt Ihnen möglicherweise die Schreibweise des Parameternamens `tokenUrl` anstelle von `token_url`.
+/// info
- Das liegt daran, dass FastAPI denselben Namen wie in der OpenAPI-Spezifikation verwendet. Sodass Sie, wenn Sie mehr über eines dieser Sicherheitsschemas herausfinden möchten, den Namen einfach kopieren und einfügen können, um weitere Informationen darüber zu erhalten.
+Wenn Sie ein sehr strenger „Pythonista“ sind, missfällt Ihnen möglicherweise die Schreibweise des Parameternamens `tokenUrl` anstelle von `token_url`.
+
+Das liegt daran, dass FastAPI denselben Namen wie in der OpenAPI-Spezifikation verwendet. Sodass Sie, wenn Sie mehr über eines dieser Sicherheitsschemas herausfinden möchten, den Namen einfach kopieren und einfügen können, um weitere Informationen darüber zu erhalten.
+
+///
Die Variable `oauth2_scheme` ist eine Instanz von `OAuth2PasswordBearer`, aber auch ein „Callable“.
@@ -184,35 +164,19 @@ Es kann also mit `Depends` verwendet werden.
Jetzt können Sie dieses `oauth2_scheme` als Abhängigkeit `Depends` übergeben.
-=== "Python 3.9+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/security/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/security/tutorial001_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/security/tutorial001.py!}
- ```
+{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *}
Diese Abhängigkeit stellt einen `str` bereit, der dem Parameter `token` der *Pfadoperation-Funktion* zugewiesen wird.
**FastAPI** weiß, dass es diese Abhängigkeit verwenden kann, um ein „Sicherheitsschema“ im OpenAPI-Schema (und der automatischen API-Dokumentation) zu definieren.
-!!! info "Technische Details"
- **FastAPI** weiß, dass es die Klasse `OAuth2PasswordBearer` (deklariert in einer Abhängigkeit) verwenden kann, um das Sicherheitsschema in OpenAPI zu definieren, da es von `fastapi.security.oauth2.OAuth2` erbt, das wiederum von `fastapi.security.base.SecurityBase` erbt.
+/// info | Technische Details
- Alle Sicherheits-Werkzeuge, die in OpenAPI integriert sind (und die automatische API-Dokumentation), erben von `SecurityBase`, so weiß **FastAPI**, wie es sie in OpenAPI integrieren muss.
+**FastAPI** weiß, dass es die Klasse `OAuth2PasswordBearer` (deklariert in einer Abhängigkeit) verwenden kann, um das Sicherheitsschema in OpenAPI zu definieren, da es von `fastapi.security.oauth2.OAuth2` erbt, das wiederum von `fastapi.security.base.SecurityBase` erbt.
+
+Alle Sicherheits-Werkzeuge, die in OpenAPI integriert sind (und die automatische API-Dokumentation), erben von `SecurityBase`, so weiß **FastAPI**, wie es sie in OpenAPI integrieren muss.
+
+///
## Was es macht
diff --git a/docs/de/docs/tutorial/security/get-current-user.md b/docs/de/docs/tutorial/security/get-current-user.md
index 09b55a20e..38f7ffcbf 100644
--- a/docs/de/docs/tutorial/security/get-current-user.md
+++ b/docs/de/docs/tutorial/security/get-current-user.md
@@ -2,26 +2,7 @@
Im vorherigen Kapitel hat das Sicherheitssystem (das auf dem Dependency Injection System basiert) der *Pfadoperation-Funktion* einen `token` vom Typ `str` überreicht:
-=== "Python 3.9+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/security/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/security/tutorial001_an.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/security/tutorial001.py!}
- ```
+{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *}
Aber das ist immer noch nicht so nützlich.
@@ -33,41 +14,7 @@ Erstellen wir zunächst ein Pydantic-Benutzermodell.
So wie wir Pydantic zum Deklarieren von Bodys verwenden, können wir es auch überall sonst verwenden:
-=== "Python 3.10+"
-
- ```Python hl_lines="5 12-16"
- {!> ../../../docs_src/security/tutorial002_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="5 12-16"
- {!> ../../../docs_src/security/tutorial002_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="5 13-17"
- {!> ../../../docs_src/security/tutorial002_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="3 10-14"
- {!> ../../../docs_src/security/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="5 12-16"
- {!> ../../../docs_src/security/tutorial002.py!}
- ```
+{* ../../docs_src/security/tutorial002_an_py310.py hl[5,12:16] *}
## Eine `get_current_user`-Abhängigkeit erstellen
@@ -79,135 +26,39 @@ Erinnern Sie sich, dass Abhängigkeiten Unterabhängigkeiten haben können?
So wie wir es zuvor in der *Pfadoperation* direkt gemacht haben, erhält unsere neue Abhängigkeit `get_current_user` von der Unterabhängigkeit `oauth2_scheme` einen `token` vom Typ `str`:
-=== "Python 3.10+"
-
- ```Python hl_lines="25"
- {!> ../../../docs_src/security/tutorial002_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="25"
- {!> ../../../docs_src/security/tutorial002_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="26"
- {!> ../../../docs_src/security/tutorial002_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="23"
- {!> ../../../docs_src/security/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="25"
- {!> ../../../docs_src/security/tutorial002.py!}
- ```
+{* ../../docs_src/security/tutorial002_an_py310.py hl[25] *}
## Den Benutzer holen
`get_current_user` wird eine von uns erstellte (gefakte) Hilfsfunktion verwenden, welche einen Token vom Typ `str` entgegennimmt und unser Pydantic-`User`-Modell zurückgibt:
-=== "Python 3.10+"
-
- ```Python hl_lines="19-22 26-27"
- {!> ../../../docs_src/security/tutorial002_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="19-22 26-27"
- {!> ../../../docs_src/security/tutorial002_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="20-23 27-28"
- {!> ../../../docs_src/security/tutorial002_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="17-20 24-25"
- {!> ../../../docs_src/security/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="19-22 26-27"
- {!> ../../../docs_src/security/tutorial002.py!}
- ```
+{* ../../docs_src/security/tutorial002_an_py310.py hl[19:22,26:27] *}
## Den aktuellen Benutzer einfügen
Und jetzt können wir wiederum `Depends` mit unserem `get_current_user` in der *Pfadoperation* verwenden:
-=== "Python 3.10+"
-
- ```Python hl_lines="31"
- {!> ../../../docs_src/security/tutorial002_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="31"
- {!> ../../../docs_src/security/tutorial002_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="32"
- {!> ../../../docs_src/security/tutorial002_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="29"
- {!> ../../../docs_src/security/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="31"
- {!> ../../../docs_src/security/tutorial002.py!}
- ```
+{* ../../docs_src/security/tutorial002_an_py310.py hl[31] *}
Beachten Sie, dass wir als Typ von `current_user` das Pydantic-Modell `User` deklarieren.
Das wird uns innerhalb der Funktion bei Codevervollständigung und Typprüfungen helfen.
-!!! tip "Tipp"
- Sie erinnern sich vielleicht, dass Requestbodys ebenfalls mit Pydantic-Modellen deklariert werden.
+/// tip | Tipp
- Weil Sie `Depends` verwenden, wird **FastAPI** hier aber nicht verwirrt.
+Sie erinnern sich vielleicht, dass Requestbodys ebenfalls mit Pydantic-Modellen deklariert werden.
-!!! check
- Die Art und Weise, wie dieses System von Abhängigkeiten konzipiert ist, ermöglicht es uns, verschiedene Abhängigkeiten (verschiedene „Dependables“) zu haben, die alle ein `User`-Modell zurückgeben.
+Weil Sie `Depends` verwenden, wird **FastAPI** hier aber nicht verwirrt.
- Wir sind nicht darauf beschränkt, nur eine Abhängigkeit zu haben, die diesen Typ von Daten zurückgeben kann.
+///
+
+/// check
+
+Die Art und Weise, wie dieses System von Abhängigkeiten konzipiert ist, ermöglicht es uns, verschiedene Abhängigkeiten (verschiedene „Dependables“) zu haben, die alle ein `User`-Modell zurückgeben.
+
+Wir sind nicht darauf beschränkt, nur eine Abhängigkeit zu haben, die diesen Typ von Daten zurückgeben kann.
+
+///
## Andere Modelle
@@ -241,41 +92,7 @@ Und alle (oder beliebige Teile davon) können Vorteil ziehen aus der Wiederverwe
Und alle diese Tausenden von *Pfadoperationen* können nur drei Zeilen lang sein:
-=== "Python 3.10+"
-
- ```Python hl_lines="30-32"
- {!> ../../../docs_src/security/tutorial002_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="30-32"
- {!> ../../../docs_src/security/tutorial002_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="31-33"
- {!> ../../../docs_src/security/tutorial002_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="28-30"
- {!> ../../../docs_src/security/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="30-32"
- {!> ../../../docs_src/security/tutorial002.py!}
- ```
+{* ../../docs_src/security/tutorial002_an_py310.py hl[30:32] *}
## Zusammenfassung
diff --git a/docs/de/docs/tutorial/security/index.md b/docs/de/docs/tutorial/security/index.md
index 7a11e704d..b01243901 100644
--- a/docs/de/docs/tutorial/security/index.md
+++ b/docs/de/docs/tutorial/security/index.md
@@ -32,9 +32,11 @@ Heutzutage ist es nicht sehr populär und wird kaum verwendet.
OAuth2 spezifiziert nicht, wie die Kommunikation verschlüsselt werden soll, sondern erwartet, dass Ihre Anwendung mit HTTPS bereitgestellt wird.
-!!! tip "Tipp"
- Im Abschnitt über **Deployment** erfahren Sie, wie Sie HTTPS mithilfe von Traefik und Let's Encrypt kostenlos einrichten.
+/// tip | Tipp
+Im Abschnitt über **Deployment** erfahren Sie, wie Sie HTTPS mithilfe von Traefik und Let's Encrypt kostenlos einrichten.
+
+///
## OpenID Connect
@@ -87,10 +89,13 @@ OpenAPI definiert die folgenden Sicherheitsschemas:
* Diese automatische Erkennung ist es, die in der OpenID Connect Spezifikation definiert ist.
-!!! tip "Tipp"
- Auch die Integration anderer Authentifizierungs-/Autorisierungsanbieter wie Google, Facebook, Twitter, GitHub, usw. ist möglich und relativ einfach.
+/// tip | Tipp
- Das komplexeste Problem besteht darin, einen Authentifizierungs-/Autorisierungsanbieter wie solche aufzubauen, aber **FastAPI** reicht Ihnen die Tools, das einfach zu erledigen, während Ihnen die schwere Arbeit abgenommen wird.
+Auch die Integration anderer Authentifizierungs-/Autorisierungsanbieter wie Google, Facebook, Twitter, GitHub, usw. ist möglich und relativ einfach.
+
+Das komplexeste Problem besteht darin, einen Authentifizierungs-/Autorisierungsanbieter wie solche aufzubauen, aber **FastAPI** reicht Ihnen die Tools, das einfach zu erledigen, während Ihnen die schwere Arbeit abgenommen wird.
+
+///
## **FastAPI** Tools
diff --git a/docs/de/docs/tutorial/security/oauth2-jwt.md b/docs/de/docs/tutorial/security/oauth2-jwt.md
index 9f43cccc9..178a95d81 100644
--- a/docs/de/docs/tutorial/security/oauth2-jwt.md
+++ b/docs/de/docs/tutorial/security/oauth2-jwt.md
@@ -44,10 +44,13 @@ $ pip install "python-jose[cryptography]"
Hier verwenden wir das empfohlene: pyca/cryptography.
-!!! tip "Tipp"
- Dieses Tutorial verwendete zuvor PyJWT.
+/// tip | Tipp
- Es wurde jedoch aktualisiert, stattdessen python-jose zu verwenden, da dieses alle Funktionen von PyJWT sowie einige Extras bietet, die Sie später möglicherweise benötigen, wenn Sie Integrationen mit anderen Tools erstellen.
+Dieses Tutorial verwendete zuvor PyJWT.
+
+Es wurde jedoch aktualisiert, stattdessen python-jose zu verwenden, da dieses alle Funktionen von PyJWT sowie einige Extras bietet, die Sie später möglicherweise benötigen, wenn Sie Integrationen mit anderen Tools erstellen.
+
+///
## Passwort-Hashing
@@ -83,12 +86,15 @@ $ pip install "passlib[bcrypt]"
-!!! tip "Tipp"
- Mit `passlib` können Sie sogar konfigurieren, Passwörter zu lesen, die von **Django**, einem **Flask**-Sicherheit-Plugin, oder vielen anderen erstellt wurden.
+/// tip | Tipp
- So könnten Sie beispielsweise die gleichen Daten aus einer Django-Anwendung in einer Datenbank mit einer FastAPI-Anwendung teilen. Oder schrittweise eine Django-Anwendung migrieren, während Sie dieselbe Datenbank verwenden.
+Mit `passlib` können Sie sogar konfigurieren, Passwörter zu lesen, die von **Django**, einem **Flask**-Sicherheit-Plugin, oder vielen anderen erstellt wurden.
- Und Ihre Benutzer könnten sich gleichzeitig über Ihre Django-Anwendung oder Ihre **FastAPI**-Anwendung anmelden.
+So könnten Sie beispielsweise die gleichen Daten aus einer Django-Anwendung in einer Datenbank mit einer FastAPI-Anwendung teilen. Oder schrittweise eine Django-Anwendung migrieren, während Sie dieselbe Datenbank verwenden.
+
+Und Ihre Benutzer könnten sich gleichzeitig über Ihre Django-Anwendung oder Ihre **FastAPI**-Anwendung anmelden.
+
+///
## Die Passwörter hashen und überprüfen
@@ -96,12 +102,15 @@ Importieren Sie die benötigten Tools aus `passlib`.
Erstellen Sie einen PassLib-„Kontext“. Der wird für das Hashen und Verifizieren von Passwörtern verwendet.
-!!! tip "Tipp"
- Der PassLib-Kontext kann auch andere Hashing-Algorithmen verwenden, einschließlich deprecateter Alter, um etwa nur eine Verifizierung usw. zu ermöglichen.
+/// tip | Tipp
- Sie könnten ihn beispielsweise verwenden, um von einem anderen System (wie Django) generierte Passwörter zu lesen und zu verifizieren, aber alle neuen Passwörter mit einem anderen Algorithmus wie Bcrypt zu hashen.
+Der PassLib-Kontext kann auch andere Hashing-Algorithmen verwenden, einschließlich deprecateter Alter, um etwa nur eine Verifizierung usw. zu ermöglichen.
- Und mit allen gleichzeitig kompatibel sein.
+Sie könnten ihn beispielsweise verwenden, um von einem anderen System (wie Django) generierte Passwörter zu lesen und zu verifizieren, aber alle neuen Passwörter mit einem anderen Algorithmus wie Bcrypt zu hashen.
+
+Und mit allen gleichzeitig kompatibel sein.
+
+///
Erstellen Sie eine Hilfsfunktion, um ein vom Benutzer stammendes Passwort zu hashen.
@@ -109,44 +118,13 @@ Und eine weitere, um zu überprüfen, ob ein empfangenes Passwort mit dem gespei
Und noch eine, um einen Benutzer zu authentifizieren und zurückzugeben.
-=== "Python 3.10+"
+{* ../../docs_src/security/tutorial004_an_py310.py hl[7,48,55:56,59:60,69:75] *}
- ```Python hl_lines="7 48 55-56 59-60 69-75"
- {!> ../../../docs_src/security/tutorial004_an_py310.py!}
- ```
+/// note | Hinweis
-=== "Python 3.9+"
+Wenn Sie sich die neue (gefakte) Datenbank `fake_users_db` anschauen, sehen Sie, wie das gehashte Passwort jetzt aussieht: `"$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW"`.
- ```Python hl_lines="7 48 55-56 59-60 69-75"
- {!> ../../../docs_src/security/tutorial004_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="7 49 56-57 60-61 70-76"
- {!> ../../../docs_src/security/tutorial004_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="6 47 54-55 58-59 68-74"
- {!> ../../../docs_src/security/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="7 48 55-56 59-60 69-75"
- {!> ../../../docs_src/security/tutorial004.py!}
- ```
-
-!!! note "Hinweis"
- Wenn Sie sich die neue (gefakte) Datenbank `fake_users_db` anschauen, sehen Sie, wie das gehashte Passwort jetzt aussieht: `"$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW"`.
+///
## JWT-Token verarbeiten
@@ -176,41 +154,7 @@ Definieren Sie ein Pydantic-Modell, das im Token-Endpunkt für die Response verw
Erstellen Sie eine Hilfsfunktion, um einen neuen Zugriffstoken zu generieren.
-=== "Python 3.10+"
-
- ```Python hl_lines="6 12-14 28-30 78-86"
- {!> ../../../docs_src/security/tutorial004_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="6 12-14 28-30 78-86"
- {!> ../../../docs_src/security/tutorial004_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="6 13-15 29-31 79-87"
- {!> ../../../docs_src/security/tutorial004_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="5 11-13 27-29 77-85"
- {!> ../../../docs_src/security/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="6 12-14 28-30 78-86"
- {!> ../../../docs_src/security/tutorial004.py!}
- ```
+{* ../../docs_src/security/tutorial004_an_py310.py hl[6,12:14,28:30,78:86] *}
## Die Abhängigkeiten aktualisieren
@@ -220,41 +164,7 @@ Dekodieren Sie den empfangenen Token, validieren Sie ihn und geben Sie den aktue
Wenn der Token ungültig ist, geben Sie sofort einen HTTP-Fehler zurück.
-=== "Python 3.10+"
-
- ```Python hl_lines="89-106"
- {!> ../../../docs_src/security/tutorial004_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="89-106"
- {!> ../../../docs_src/security/tutorial004_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="90-107"
- {!> ../../../docs_src/security/tutorial004_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="88-105"
- {!> ../../../docs_src/security/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="89-106"
- {!> ../../../docs_src/security/tutorial004.py!}
- ```
+{* ../../docs_src/security/tutorial004_an_py310.py hl[89:106] *}
## Die *Pfadoperation* `/token` aktualisieren
@@ -262,41 +172,7 @@ Erstellen Sie ein `timedelta` mit der Ablaufz
Erstellen Sie einen echten JWT-Zugriffstoken und geben Sie ihn zurück.
-=== "Python 3.10+"
-
- ```Python hl_lines="117-132"
- {!> ../../../docs_src/security/tutorial004_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="117-132"
- {!> ../../../docs_src/security/tutorial004_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="118-133"
- {!> ../../../docs_src/security/tutorial004_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="114-129"
- {!> ../../../docs_src/security/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="115-130"
- {!> ../../../docs_src/security/tutorial004.py!}
- ```
+{* ../../docs_src/security/tutorial004_an_py310.py hl[117:132] *}
### Technische Details zum JWT-„Subjekt“ `sub`
@@ -335,8 +211,11 @@ Verwenden Sie die Anmeldeinformationen:
Benutzername: `johndoe`
Passwort: `secret`.
-!!! check
- Beachten Sie, dass im Code nirgendwo das Klartext-Passwort "`secret`" steht, wir haben nur die gehashte Version.
+/// check
+
+Beachten Sie, dass im Code nirgendwo das Klartext-Passwort "`secret`" steht, wir haben nur die gehashte Version.
+
+///
@@ -357,8 +236,11 @@ Wenn Sie die Developer Tools öffnen, können Sie sehen, dass die gesendeten Dat
-!!! note "Hinweis"
- Beachten Sie den Header `Authorization` mit einem Wert, der mit `Bearer` beginnt.
+/// note | Hinweis
+
+Beachten Sie den Header `Authorization` mit einem Wert, der mit `Bearer` beginnt.
+
+///
## Fortgeschrittene Verwendung mit `scopes`
diff --git a/docs/de/docs/tutorial/security/simple-oauth2.md b/docs/de/docs/tutorial/security/simple-oauth2.md
index ed280d486..c0c93cd26 100644
--- a/docs/de/docs/tutorial/security/simple-oauth2.md
+++ b/docs/de/docs/tutorial/security/simple-oauth2.md
@@ -32,14 +32,17 @@ Diese werden normalerweise verwendet, um bestimmte Sicherheitsberechtigungen zu
* `instagram_basic` wird von Facebook / Instagram verwendet.
* `https://www.googleapis.com/auth/drive` wird von Google verwendet.
-!!! info
- In OAuth2 ist ein „Scope“ nur ein String, der eine bestimmte erforderliche Berechtigung deklariert.
+/// info
- Es spielt keine Rolle, ob er andere Zeichen wie `:` enthält oder ob es eine URL ist.
+In OAuth2 ist ein „Scope“ nur ein String, der eine bestimmte erforderliche Berechtigung deklariert.
- Diese Details sind implementierungsspezifisch.
+Es spielt keine Rolle, ob er andere Zeichen wie `:` enthält oder ob es eine URL ist.
- Für OAuth2 sind es einfach nur Strings.
+Diese Details sind implementierungsspezifisch.
+
+Für OAuth2 sind es einfach nur Strings.
+
+///
## Code, um `username` und `password` entgegenzunehmen.
@@ -49,41 +52,7 @@ Lassen Sie uns nun die von **FastAPI** bereitgestellten Werkzeuge verwenden, um
Importieren Sie zunächst `OAuth2PasswordRequestForm` und verwenden Sie es als Abhängigkeit mit `Depends` in der *Pfadoperation* für `/token`:
-=== "Python 3.10+"
-
- ```Python hl_lines="4 78"
- {!> ../../../docs_src/security/tutorial003_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="4 78"
- {!> ../../../docs_src/security/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="4 79"
- {!> ../../../docs_src/security/tutorial003_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="2 74"
- {!> ../../../docs_src/security/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="4 76"
- {!> ../../../docs_src/security/tutorial003.py!}
- ```
+{* ../../docs_src/security/tutorial003_an_py310.py hl[4,78] *}
`OAuth2PasswordRequestForm` ist eine Klassenabhängigkeit, die einen Formularbody deklariert mit:
@@ -92,29 +61,38 @@ Importieren Sie zunächst `OAuth2PasswordRequestForm` und verwenden Sie es als A
* Einem optionalen `scope`-Feld als langem String, bestehend aus durch Leerzeichen getrennten Strings.
* Einem optionalen `grant_type` („Art der Anmeldung“).
-!!! tip "Tipp"
- Die OAuth2-Spezifikation *erfordert* tatsächlich ein Feld `grant_type` mit dem festen Wert `password`, aber `OAuth2PasswordRequestForm` erzwingt dies nicht.
+/// tip | Tipp
- Wenn Sie es erzwingen müssen, verwenden Sie `OAuth2PasswordRequestFormStrict` anstelle von `OAuth2PasswordRequestForm`.
+Die OAuth2-Spezifikation *erfordert* tatsächlich ein Feld `grant_type` mit dem festen Wert `password`, aber `OAuth2PasswordRequestForm` erzwingt dies nicht.
+
+Wenn Sie es erzwingen müssen, verwenden Sie `OAuth2PasswordRequestFormStrict` anstelle von `OAuth2PasswordRequestForm`.
+
+///
* Eine optionale `client_id` (benötigen wir für unser Beispiel nicht).
* Ein optionales `client_secret` (benötigen wir für unser Beispiel nicht).
-!!! info
- `OAuth2PasswordRequestForm` ist keine spezielle Klasse für **FastAPI**, so wie `OAuth2PasswordBearer`.
+/// info
- `OAuth2PasswordBearer` lässt **FastAPI** wissen, dass es sich um ein Sicherheitsschema handelt. Daher wird es auf diese Weise zu OpenAPI hinzugefügt.
+`OAuth2PasswordRequestForm` ist keine spezielle Klasse für **FastAPI**, so wie `OAuth2PasswordBearer`.
- Aber `OAuth2PasswordRequestForm` ist nur eine Klassenabhängigkeit, die Sie selbst hätten schreiben können, oder Sie hätten `Form`ular-Parameter direkt deklarieren können.
+`OAuth2PasswordBearer` lässt **FastAPI** wissen, dass es sich um ein Sicherheitsschema handelt. Daher wird es auf diese Weise zu OpenAPI hinzugefügt.
- Da es sich jedoch um einen häufigen Anwendungsfall handelt, wird er zur Vereinfachung direkt von **FastAPI** bereitgestellt.
+Aber `OAuth2PasswordRequestForm` ist nur eine Klassenabhängigkeit, die Sie selbst hätten schreiben können, oder Sie hätten `Form`ular-Parameter direkt deklarieren können.
+
+Da es sich jedoch um einen häufigen Anwendungsfall handelt, wird er zur Vereinfachung direkt von **FastAPI** bereitgestellt.
+
+///
### Die Formulardaten verwenden
-!!! tip "Tipp"
- Die Instanz der Klassenabhängigkeit `OAuth2PasswordRequestForm` verfügt, statt eines Attributs `scope` mit dem durch Leerzeichen getrennten langen String, über das Attribut `scopes` mit einer tatsächlichen Liste von Strings, einem für jeden gesendeten Scope.
+/// tip | Tipp
- In diesem Beispiel verwenden wir keine `scopes`, aber die Funktionalität ist vorhanden, wenn Sie sie benötigen.
+Die Instanz der Klassenabhängigkeit `OAuth2PasswordRequestForm` verfügt, statt eines Attributs `scope` mit dem durch Leerzeichen getrennten langen String, über das Attribut `scopes` mit einer tatsächlichen Liste von Strings, einem für jeden gesendeten Scope.
+
+In diesem Beispiel verwenden wir keine `scopes`, aber die Funktionalität ist vorhanden, wenn Sie sie benötigen.
+
+///
Rufen Sie nun die Benutzerdaten aus der (gefakten) Datenbank ab, für diesen `username` aus dem Formularfeld.
@@ -122,41 +100,7 @@ Wenn es keinen solchen Benutzer gibt, geben wir die Fehlermeldung „Incorrect u
Für den Fehler verwenden wir die Exception `HTTPException`:
-=== "Python 3.10+"
-
- ```Python hl_lines="3 79-81"
- {!> ../../../docs_src/security/tutorial003_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="3 79-81"
- {!> ../../../docs_src/security/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="3 80-82"
- {!> ../../../docs_src/security/tutorial003_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="1 75-77"
- {!> ../../../docs_src/security/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="3 77-79"
- {!> ../../../docs_src/security/tutorial003.py!}
- ```
+{* ../../docs_src/security/tutorial003_an_py310.py hl[3,79:81] *}
### Das Passwort überprüfen
@@ -182,41 +126,7 @@ Wenn Ihre Datenbank gestohlen wird, hat der Dieb nicht die Klartext-Passwörter
Der Dieb kann also nicht versuchen, die gleichen Passwörter in einem anderen System zu verwenden (da viele Benutzer überall das gleiche Passwort verwenden, wäre dies gefährlich).
-=== "Python 3.10+"
-
- ```Python hl_lines="82-85"
- {!> ../../../docs_src/security/tutorial003_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="82-85"
- {!> ../../../docs_src/security/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="83-86"
- {!> ../../../docs_src/security/tutorial003_an.py!}
- ```
-
-=== "Python 3.10+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="78-81"
- {!> ../../../docs_src/security/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="80-83"
- {!> ../../../docs_src/security/tutorial003.py!}
- ```
+{* ../../docs_src/security/tutorial003_an_py310.py hl[82:85] *}
#### Über `**user_dict`
@@ -234,8 +144,11 @@ UserInDB(
)
```
-!!! info
- Eine ausführlichere Erklärung von `**user_dict` finden Sie in [der Dokumentation für **Extra Modelle**](../extra-models.md#uber-user_indict){.internal-link target=_blank}.
+/// info
+
+Eine ausführlichere Erklärung von `**user_dict` finden Sie in [der Dokumentation für **Extra Modelle**](../extra-models.md#uber-user_indict){.internal-link target=_blank}.
+
+///
## Den Token zurückgeben
@@ -247,55 +160,27 @@ Und es sollte einen `access_token` haben, mit einem String, der unseren Zugriffs
In diesem einfachen Beispiel gehen wir einfach völlig unsicher vor und geben denselben `username` wie der Token zurück.
-!!! tip "Tipp"
- Im nächsten Kapitel sehen Sie eine wirklich sichere Implementierung mit Passwort-Hashing und JWT-Tokens.
+/// tip | Tipp
- Aber konzentrieren wir uns zunächst auf die spezifischen Details, die wir benötigen.
+Im nächsten Kapitel sehen Sie eine wirklich sichere Implementierung mit Passwort-Hashing und JWT-Tokens.
-=== "Python 3.10+"
+Aber konzentrieren wir uns zunächst auf die spezifischen Details, die wir benötigen.
- ```Python hl_lines="87"
- {!> ../../../docs_src/security/tutorial003_an_py310.py!}
- ```
+///
-=== "Python 3.9+"
+{* ../../docs_src/security/tutorial003_an_py310.py hl[87] *}
- ```Python hl_lines="87"
- {!> ../../../docs_src/security/tutorial003_an_py39.py!}
- ```
+/// tip | Tipp
-=== "Python 3.8+"
+Gemäß der Spezifikation sollten Sie ein JSON mit einem `access_token` und einem `token_type` zurückgeben, genau wie in diesem Beispiel.
- ```Python hl_lines="88"
- {!> ../../../docs_src/security/tutorial003_an.py!}
- ```
+Das müssen Sie selbst in Ihrem Code tun und sicherstellen, dass Sie diese JSON-Schlüssel verwenden.
-=== "Python 3.10+ nicht annotiert"
+Es ist fast das Einzige, woran Sie denken müssen, es selbst richtigzumachen und die Spezifikationen einzuhalten.
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
+Den Rest erledigt **FastAPI** für Sie.
- ```Python hl_lines="83"
- {!> ../../../docs_src/security/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="85"
- {!> ../../../docs_src/security/tutorial003.py!}
- ```
-
-!!! tip "Tipp"
- Gemäß der Spezifikation sollten Sie ein JSON mit einem `access_token` und einem `token_type` zurückgeben, genau wie in diesem Beispiel.
-
- Das müssen Sie selbst in Ihrem Code tun und sicherstellen, dass Sie diese JSON-Schlüssel verwenden.
-
- Es ist fast das Einzige, woran Sie denken müssen, es selbst richtigzumachen und die Spezifikationen einzuhalten.
-
- Den Rest erledigt **FastAPI** für Sie.
+///
## Die Abhängigkeiten aktualisieren
@@ -309,56 +194,25 @@ Beide Abhängigkeiten geben nur dann einen HTTP-Error zurück, wenn der Benutzer
In unserem Endpunkt erhalten wir also nur dann einen Benutzer, wenn der Benutzer existiert, korrekt authentifiziert wurde und aktiv ist:
-=== "Python 3.10+"
+{* ../../docs_src/security/tutorial003_an_py310.py hl[58:66,69:74,94] *}
- ```Python hl_lines="58-66 69-74 94"
- {!> ../../../docs_src/security/tutorial003_an_py310.py!}
- ```
+/// info
-=== "Python 3.9+"
+Der zusätzliche Header `WWW-Authenticate` mit dem Wert `Bearer`, den wir hier zurückgeben, ist ebenfalls Teil der Spezifikation.
- ```Python hl_lines="58-66 69-74 94"
- {!> ../../../docs_src/security/tutorial003_an_py39.py!}
- ```
+Jeder HTTP-(Fehler-)Statuscode 401 „UNAUTHORIZED“ soll auch einen `WWW-Authenticate`-Header zurückgeben.
-=== "Python 3.8+"
+Im Fall von Bearer-Tokens (in unserem Fall) sollte der Wert dieses Headers `Bearer` lauten.
- ```Python hl_lines="59-67 70-75 95"
- {!> ../../../docs_src/security/tutorial003_an.py!}
- ```
+Sie können diesen zusätzlichen Header tatsächlich weglassen und es würde trotzdem funktionieren.
-=== "Python 3.10+ nicht annotiert"
+Aber er wird hier bereitgestellt, um den Spezifikationen zu entsprechen.
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
+Außerdem gibt es möglicherweise Tools, die ihn erwarten und verwenden (jetzt oder in der Zukunft) und das könnte für Sie oder Ihre Benutzer jetzt oder in der Zukunft nützlich sein.
- ```Python hl_lines="56-64 67-70 88"
- {!> ../../../docs_src/security/tutorial003_py310.py!}
- ```
+Das ist der Vorteil von Standards ...
-=== "Python 3.8+ nicht annotiert"
-
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
-
- ```Python hl_lines="58-66 69-72 90"
- {!> ../../../docs_src/security/tutorial003.py!}
- ```
-
-!!! info
- Der zusätzliche Header `WWW-Authenticate` mit dem Wert `Bearer`, den wir hier zurückgeben, ist ebenfalls Teil der Spezifikation.
-
- Jeder HTTP-(Fehler-)Statuscode 401 „UNAUTHORIZED“ soll auch einen `WWW-Authenticate`-Header zurückgeben.
-
- Im Fall von Bearer-Tokens (in unserem Fall) sollte der Wert dieses Headers `Bearer` lauten.
-
- Sie können diesen zusätzlichen Header tatsächlich weglassen und es würde trotzdem funktionieren.
-
- Aber er wird hier bereitgestellt, um den Spezifikationen zu entsprechen.
-
- Außerdem gibt es möglicherweise Tools, die ihn erwarten und verwenden (jetzt oder in der Zukunft) und das könnte für Sie oder Ihre Benutzer jetzt oder in der Zukunft nützlich sein.
-
- Das ist der Vorteil von Standards ...
+///
## Es in Aktion sehen
diff --git a/docs/de/docs/tutorial/static-files.md b/docs/de/docs/tutorial/static-files.md
index 1e289e120..50e86d68e 100644
--- a/docs/de/docs/tutorial/static-files.md
+++ b/docs/de/docs/tutorial/static-files.md
@@ -7,14 +7,15 @@ Mit `StaticFiles` können Sie statische Dateien aus einem Verzeichnis automatisc
* Importieren Sie `StaticFiles`.
* „Mounten“ Sie eine `StaticFiles()`-Instanz in einem bestimmten Pfad.
-```Python hl_lines="2 6"
-{!../../../docs_src/static_files/tutorial001.py!}
-```
+{* ../../docs_src/static_files/tutorial001.py hl[2,6] *}
-!!! note "Technische Details"
- Sie könnten auch `from starlette.staticfiles import StaticFiles` verwenden.
+/// note | Technische Details
- **FastAPI** stellt dasselbe `starlette.staticfiles` auch via `fastapi.staticfiles` bereit, als Annehmlichkeit für Sie, den Entwickler. Es kommt aber tatsächlich direkt von Starlette.
+Sie könnten auch `from starlette.staticfiles import StaticFiles` verwenden.
+
+**FastAPI** stellt dasselbe `starlette.staticfiles` auch via `fastapi.staticfiles` bereit, als Annehmlichkeit für Sie, den Entwickler. Es kommt aber tatsächlich direkt von Starlette.
+
+///
### Was ist „Mounten“?
diff --git a/docs/de/docs/tutorial/testing.md b/docs/de/docs/tutorial/testing.md
index 541cc1bf0..e7c1dda95 100644
--- a/docs/de/docs/tutorial/testing.md
+++ b/docs/de/docs/tutorial/testing.md
@@ -8,10 +8,13 @@ Damit können Sie `httpx`.
+/// info
- Z. B. `pip install httpx`.
+Um `TestClient` zu verwenden, installieren Sie zunächst `httpx`.
+
+Z. B. `pip install httpx`.
+
+///
Importieren Sie `TestClient`.
@@ -23,24 +26,31 @@ Verwenden Sie das `TestClient`-Objekt auf die gleiche Weise wie `httpx`.
Schreiben Sie einfache `assert`-Anweisungen mit den Standard-Python-Ausdrücken, die Sie überprüfen müssen (wiederum, Standard-`pytest`).
-```Python hl_lines="2 12 15-18"
-{!../../../docs_src/app_testing/tutorial001.py!}
-```
+{* ../../docs_src/app_testing/tutorial001.py hl[2,12,15:18] *}
-!!! tip "Tipp"
- Beachten Sie, dass die Testfunktionen normal `def` und nicht `async def` sind.
+/// tip | Tipp
- Und die Anrufe an den Client sind ebenfalls normale Anrufe, die nicht `await` verwenden.
+Beachten Sie, dass die Testfunktionen normal `def` und nicht `async def` sind.
- Dadurch können Sie `pytest` ohne Komplikationen direkt nutzen.
+Und die Anrufe an den Client sind ebenfalls normale Anrufe, die nicht `await` verwenden.
-!!! note "Technische Details"
- Sie könnten auch `from starlette.testclient import TestClient` verwenden.
+Dadurch können Sie `pytest` ohne Komplikationen direkt nutzen.
- **FastAPI** stellt denselben `starlette.testclient` auch via `fastapi.testclient` bereit, als Annehmlichkeit für Sie, den Entwickler. Es kommt aber tatsächlich direkt von Starlette.
+///
-!!! tip "Tipp"
- Wenn Sie in Ihren Tests neben dem Senden von Anfragen an Ihre FastAPI-Anwendung auch `async`-Funktionen aufrufen möchten (z. B. asynchrone Datenbankfunktionen), werfen Sie einen Blick auf die [Async-Tests](../advanced/async-tests.md){.internal-link target=_blank} im Handbuch für fortgeschrittene Benutzer.
+/// note | Technische Details
+
+Sie könnten auch `from starlette.testclient import TestClient` verwenden.
+
+**FastAPI** stellt denselben `starlette.testclient` auch via `fastapi.testclient` bereit, als Annehmlichkeit für Sie, den Entwickler. Es kommt aber tatsächlich direkt von Starlette.
+
+///
+
+/// tip | Tipp
+
+Wenn Sie in Ihren Tests neben dem Senden von Anfragen an Ihre FastAPI-Anwendung auch `async`-Funktionen aufrufen möchten (z. B. asynchrone Datenbankfunktionen), werfen Sie einen Blick auf die [Async-Tests](../advanced/async-tests.md){.internal-link target=_blank} im Handbuch für fortgeschrittene Benutzer.
+
+///
## Tests separieren
@@ -62,9 +72,8 @@ Nehmen wir an, Sie haben eine Dateistruktur wie in [Größere Anwendungen](bigge
In der Datei `main.py` haben Sie Ihre **FastAPI**-Anwendung:
-```Python
-{!../../../docs_src/app_testing/main.py!}
-```
+{* ../../docs_src/app_testing/main.py *}
+
### Testdatei
@@ -80,9 +89,8 @@ Dann könnten Sie eine Datei `test_main.py` mit Ihren Tests haben. Sie könnte s
Da sich diese Datei im selben Package befindet, können Sie relative Importe verwenden, um das Objekt `app` aus dem `main`-Modul (`main.py`) zu importieren:
-```Python hl_lines="3"
-{!../../../docs_src/app_testing/test_main.py!}
-```
+{* ../../docs_src/app_testing/test_main.py hl[3] *}
+
... und haben den Code für die Tests wie zuvor.
@@ -110,49 +118,64 @@ Sie verfügt über eine `POST`-Operation, die mehrere Fehler zurückgeben könnt
Beide *Pfadoperationen* erfordern einen `X-Token`-Header.
-=== "Python 3.10+"
+//// tab | Python 3.10+
- ```Python
- {!> ../../../docs_src/app_testing/app_b_an_py310/main.py!}
- ```
+```Python
+{!> ../../docs_src/app_testing/app_b_an_py310/main.py!}
+```
-=== "Python 3.9+"
+////
- ```Python
- {!> ../../../docs_src/app_testing/app_b_an_py39/main.py!}
- ```
+//// tab | Python 3.9+
-=== "Python 3.8+"
+```Python
+{!> ../../docs_src/app_testing/app_b_an_py39/main.py!}
+```
- ```Python
- {!> ../../../docs_src/app_testing/app_b_an/main.py!}
- ```
+////
-=== "Python 3.10+ nicht annotiert"
+//// tab | Python 3.8+
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
+```Python
+{!> ../../docs_src/app_testing/app_b_an/main.py!}
+```
- ```Python
- {!> ../../../docs_src/app_testing/app_b_py310/main.py!}
- ```
+////
-=== "Python 3.8+ nicht annotiert"
+//// tab | Python 3.10+ nicht annotiert
- !!! tip "Tipp"
- Bevorzugen Sie die `Annotated`-Version, falls möglich.
+/// tip | Tipp
- ```Python
- {!> ../../../docs_src/app_testing/app_b/main.py!}
- ```
+Bevorzugen Sie die `Annotated`-Version, falls möglich.
+
+///
+
+```Python
+{!> ../../docs_src/app_testing/app_b_py310/main.py!}
+```
+
+////
+
+//// tab | Python 3.8+ nicht annotiert
+
+/// tip | Tipp
+
+Bevorzugen Sie die `Annotated`-Version, falls möglich.
+
+///
+
+```Python
+{!> ../../docs_src/app_testing/app_b/main.py!}
+```
+
+////
### Erweiterte Testdatei
Anschließend könnten Sie `test_main.py` mit den erweiterten Tests aktualisieren:
-```Python
-{!> ../../../docs_src/app_testing/app_b/test_main.py!}
-```
+{* ../../docs_src/app_testing/app_b/test_main.py *}
+
Wenn Sie möchten, dass der Client Informationen im Request übergibt und Sie nicht wissen, wie das geht, können Sie suchen (googeln), wie es mit `httpx` gemacht wird, oder sogar, wie es mit `requests` gemacht wird, da das Design von HTTPX auf dem Design von Requests basiert.
@@ -168,10 +191,13 @@ Z. B.:
Weitere Informationen zum Übergeben von Daten an das Backend (mithilfe von `httpx` oder dem `TestClient`) finden Sie in der HTTPX-Dokumentation.
-!!! info
- Beachten Sie, dass der `TestClient` Daten empfängt, die nach JSON konvertiert werden können, keine Pydantic-Modelle.
+/// info
- Wenn Sie ein Pydantic-Modell in Ihrem Test haben und dessen Daten während des Testens an die Anwendung senden möchten, können Sie den `jsonable_encoder` verwenden, der in [JSON-kompatibler Encoder](encoder.md){.internal-link target=_blank} beschrieben wird.
+Beachten Sie, dass der `TestClient` Daten empfängt, die nach JSON konvertiert werden können, keine Pydantic-Modelle.
+
+Wenn Sie ein Pydantic-Modell in Ihrem Test haben und dessen Daten während des Testens an die Anwendung senden möchten, können Sie den `jsonable_encoder` verwenden, der in [JSON-kompatibler Encoder](encoder.md){.internal-link target=_blank} beschrieben wird.
+
+///
## Tests ausführen
diff --git a/docs/em/docs/advanced/additional-responses.md b/docs/em/docs/advanced/additional-responses.md
index 26963c2e3..655fc7ab6 100644
--- a/docs/em/docs/advanced/additional-responses.md
+++ b/docs/em/docs/advanced/additional-responses.md
@@ -1,9 +1,12 @@
# 🌖 📨 🗄
-!!! warning
- 👉 👍 🏧 ❔.
+/// warning
- 🚥 👆 ▶️ ⏮️ **FastAPI**, 👆 💪 🚫 💪 👉.
+👉 👍 🏧 ❔.
+
+🚥 👆 ▶️ ⏮️ **FastAPI**, 👆 💪 🚫 💪 👉.
+
+///
👆 💪 📣 🌖 📨, ⏮️ 🌖 👔 📟, 🔉 🆎, 📛, ♒️.
@@ -23,24 +26,28 @@
🖼, 📣 ➕1️⃣ 📨 ⏮️ 👔 📟 `404` & Pydantic 🏷 `Message`, 👆 💪 ✍:
-```Python hl_lines="18 22"
-{!../../../docs_src/additional_responses/tutorial001.py!}
-```
+{* ../../docs_src/additional_responses/tutorial001.py hl[18,22] *}
-!!! note
- ✔️ 🤯 👈 👆 ✔️ 📨 `JSONResponse` 🔗.
+/// note
-!!! info
- `model` 🔑 🚫 🍕 🗄.
+✔️ 🤯 👈 👆 ✔️ 📨 `JSONResponse` 🔗.
- **FastAPI** 🔜 ✊ Pydantic 🏷 ⚪️➡️ 📤, 🏗 `JSON Schema`, & 🚮 ⚫️ ☑ 🥉.
+///
- ☑ 🥉:
+/// info
- * 🔑 `content`, 👈 ✔️ 💲 ➕1️⃣ 🎻 🎚 (`dict`) 👈 🔌:
- * 🔑 ⏮️ 📻 🆎, ✅ `application/json`, 👈 🔌 💲 ➕1️⃣ 🎻 🎚, 👈 🔌:
- * 🔑 `schema`, 👈 ✔️ 💲 🎻 🔗 ⚪️➡️ 🏷, 📥 ☑ 🥉.
- * **FastAPI** 🚮 🔗 📥 🌐 🎻 🔗 ➕1️⃣ 🥉 👆 🗄 ↩️ ✅ ⚫️ 🔗. 👉 🌌, 🎏 🈸 & 👩💻 💪 ⚙️ 👈 🎻 🔗 🔗, 🚚 👻 📟 ⚡ 🧰, ♒️.
+`model` 🔑 🚫 🍕 🗄.
+
+**FastAPI** 🔜 ✊ Pydantic 🏷 ⚪️➡️ 📤, 🏗 `JSON Schema`, & 🚮 ⚫️ ☑ 🥉.
+
+☑ 🥉:
+
+* 🔑 `content`, 👈 ✔️ 💲 ➕1️⃣ 🎻 🎚 (`dict`) 👈 🔌:
+ * 🔑 ⏮️ 📻 🆎, ✅ `application/json`, 👈 🔌 💲 ➕1️⃣ 🎻 🎚, 👈 🔌:
+ * 🔑 `schema`, 👈 ✔️ 💲 🎻 🔗 ⚪️➡️ 🏷, 📥 ☑ 🥉.
+ * **FastAPI** 🚮 🔗 📥 🌐 🎻 🔗 ➕1️⃣ 🥉 👆 🗄 ↩️ ✅ ⚫️ 🔗. 👉 🌌, 🎏 🈸 & 👩💻 💪 ⚙️ 👈 🎻 🔗 🔗, 🚚 👻 📟 ⚡ 🧰, ♒️.
+
+///
🏗 📨 🗄 👉 *➡ 🛠️* 🔜:
@@ -168,17 +175,21 @@
🖼, 👆 💪 🚮 🌖 📻 🆎 `image/png`, 📣 👈 👆 *➡ 🛠️* 💪 📨 🎻 🎚 (⏮️ 📻 🆎 `application/json`) ⚖️ 🇩🇴 🖼:
-```Python hl_lines="19-24 28"
-{!../../../docs_src/additional_responses/tutorial002.py!}
-```
+{* ../../docs_src/additional_responses/tutorial002.py hl[19:24,28] *}
-!!! note
- 👀 👈 👆 ✔️ 📨 🖼 ⚙️ `FileResponse` 🔗.
+/// note
-!!! info
- 🚥 👆 ✔ 🎏 📻 🆎 🎯 👆 `responses` 🔢, FastAPI 🔜 🤔 📨 ✔️ 🎏 📻 🆎 👑 📨 🎓 (🔢 `application/json`).
+👀 👈 👆 ✔️ 📨 🖼 ⚙️ `FileResponse` 🔗.
- ✋️ 🚥 👆 ✔️ ✔ 🛃 📨 🎓 ⏮️ `None` 🚮 📻 🆎, FastAPI 🔜 ⚙️ `application/json` 🙆 🌖 📨 👈 ✔️ 👨💼 🏷.
+///
+
+/// info
+
+🚥 👆 ✔ 🎏 📻 🆎 🎯 👆 `responses` 🔢, FastAPI 🔜 🤔 📨 ✔️ 🎏 📻 🆎 👑 📨 🎓 (🔢 `application/json`).
+
+✋️ 🚥 👆 ✔️ ✔ 🛃 📨 🎓 ⏮️ `None` 🚮 📻 🆎, FastAPI 🔜 ⚙️ `application/json` 🙆 🌖 📨 👈 ✔️ 👨💼 🏷.
+
+///
## 🌀 ℹ
@@ -192,9 +203,7 @@
& 📨 ⏮️ 👔 📟 `200` 👈 ⚙️ 👆 `response_model`, ✋️ 🔌 🛃 `example`:
-```Python hl_lines="20-31"
-{!../../../docs_src/additional_responses/tutorial003.py!}
-```
+{* ../../docs_src/additional_responses/tutorial003.py hl[20:31] *}
⚫️ 🔜 🌐 🌀 & 🔌 👆 🗄, & 🎦 🛠️ 🩺:
@@ -228,9 +237,7 @@ new_dict = {**old_dict, "new key": "new value"}
🖼:
-```Python hl_lines="13-17 26"
-{!../../../docs_src/additional_responses/tutorial004.py!}
-```
+{* ../../docs_src/additional_responses/tutorial004.py hl[13:17,26] *}
## 🌖 ℹ 🔃 🗄 📨
diff --git a/docs/em/docs/advanced/additional-status-codes.md b/docs/em/docs/advanced/additional-status-codes.md
index 392579df6..907c7e68e 100644
--- a/docs/em/docs/advanced/additional-status-codes.md
+++ b/docs/em/docs/advanced/additional-status-codes.md
@@ -14,21 +14,25 @@
🏆 👈, 🗄 `JSONResponse`, & 📨 👆 🎚 📤 🔗, ⚒ `status_code` 👈 👆 💚:
-```Python hl_lines="4 25"
-{!../../../docs_src/additional_status_codes/tutorial001.py!}
-```
+{* ../../docs_src/additional_status_codes/tutorial001.py hl[4,25] *}
-!!! warning
- 🕐❔ 👆 📨 `Response` 🔗, 💖 🖼 🔛, ⚫️ 🔜 📨 🔗.
+/// warning
- ⚫️ 🏆 🚫 🎻 ⏮️ 🏷, ♒️.
+🕐❔ 👆 📨 `Response` 🔗, 💖 🖼 🔛, ⚫️ 🔜 📨 🔗.
- ⚒ 💭 ⚫️ ✔️ 📊 👆 💚 ⚫️ ✔️, & 👈 💲 ☑ 🎻 (🚥 👆 ⚙️ `JSONResponse`).
+⚫️ 🏆 🚫 🎻 ⏮️ 🏷, ♒️.
-!!! note "📡 ℹ"
- 👆 💪 ⚙️ `from starlette.responses import JSONResponse`.
+⚒ 💭 ⚫️ ✔️ 📊 👆 💚 ⚫️ ✔️, & 👈 💲 ☑ 🎻 (🚥 👆 ⚙️ `JSONResponse`).
- **FastAPI** 🚚 🎏 `starlette.responses` `fastapi.responses` 🏪 👆, 👩💻. ✋️ 🌅 💪 📨 👟 🔗 ⚪️➡️ 💃. 🎏 ⏮️ `status`.
+///
+
+/// note | 📡 ℹ
+
+👆 💪 ⚙️ `from starlette.responses import JSONResponse`.
+
+**FastAPI** 🚚 🎏 `starlette.responses` `fastapi.responses` 🏪 👆, 👩💻. ✋️ 🌅 💪 📨 👟 🔗 ⚪️➡️ 💃. 🎏 ⏮️ `status`.
+
+///
## 🗄 & 🛠️ 🩺
diff --git a/docs/em/docs/advanced/advanced-dependencies.md b/docs/em/docs/advanced/advanced-dependencies.md
index fa1554734..3404c2687 100644
--- a/docs/em/docs/advanced/advanced-dependencies.md
+++ b/docs/em/docs/advanced/advanced-dependencies.md
@@ -18,9 +18,7 @@
👈, 👥 📣 👩🔬 `__call__`:
-```Python hl_lines="10"
-{!../../../docs_src/dependencies/tutorial011.py!}
-```
+{* ../../docs_src/dependencies/tutorial011.py hl[10] *}
👉 💼, 👉 `__call__` ⚫️❔ **FastAPI** 🔜 ⚙️ ✅ 🌖 🔢 & 🎧-🔗, & 👉 ⚫️❔ 🔜 🤙 🚶♀️ 💲 🔢 👆 *➡ 🛠️ 🔢* ⏪.
@@ -28,9 +26,7 @@
& 🔜, 👥 💪 ⚙️ `__init__` 📣 🔢 👐 👈 👥 💪 ⚙️ "🔗" 🔗:
-```Python hl_lines="7"
-{!../../../docs_src/dependencies/tutorial011.py!}
-```
+{* ../../docs_src/dependencies/tutorial011.py hl[7] *}
👉 💼, **FastAPI** 🏆 🚫 ⏱ 👆 ⚖️ 💅 🔃 `__init__`, 👥 🔜 ⚙️ ⚫️ 🔗 👆 📟.
@@ -38,9 +34,7 @@
👥 💪 ✍ 👐 👉 🎓 ⏮️:
-```Python hl_lines="16"
-{!../../../docs_src/dependencies/tutorial011.py!}
-```
+{* ../../docs_src/dependencies/tutorial011.py hl[16] *}
& 👈 🌌 👥 💪 "🔗" 👆 🔗, 👈 🔜 ✔️ `"bar"` 🔘 ⚫️, 🔢 `checker.fixed_content`.
@@ -56,15 +50,16 @@ checker(q="somequery")
...& 🚶♀️ ⚫️❔ 👈 📨 💲 🔗 👆 *➡ 🛠️ 🔢* 🔢 `fixed_content_included`:
-```Python hl_lines="20"
-{!../../../docs_src/dependencies/tutorial011.py!}
-```
+{* ../../docs_src/dependencies/tutorial011.py hl[20] *}
-!!! tip
- 🌐 👉 💪 😑 🎭. & ⚫️ 💪 🚫 📶 🆑 ❔ ⚫️ ⚠.
+/// tip
- 👫 🖼 😫 🙅, ✋️ 🎦 ❔ ⚫️ 🌐 👷.
+🌐 👉 💪 😑 🎭. & ⚫️ 💪 🚫 📶 🆑 ❔ ⚫️ ⚠.
- 📃 🔃 💂♂, 📤 🚙 🔢 👈 🛠️ 👉 🎏 🌌.
+👫 🖼 😫 🙅, ✋️ 🎦 ❔ ⚫️ 🌐 👷.
- 🚥 👆 🤔 🌐 👉, 👆 ⏪ 💭 ❔ 👈 🚙 🧰 💂♂ 👷 🔘.
+📃 🔃 💂♂, 📤 🚙 🔢 👈 🛠️ 👉 🎏 🌌.
+
+🚥 👆 🤔 🌐 👉, 👆 ⏪ 💭 ❔ 👈 🚙 🧰 💂♂ 👷 🔘.
+
+///
diff --git a/docs/em/docs/advanced/async-tests.md b/docs/em/docs/advanced/async-tests.md
index df94c6ce7..283d4aa09 100644
--- a/docs/em/docs/advanced/async-tests.md
+++ b/docs/em/docs/advanced/async-tests.md
@@ -32,15 +32,11 @@
📁 `main.py` 🔜 ✔️:
-```Python
-{!../../../docs_src/async_tests/main.py!}
-```
+{* ../../docs_src/async_tests/main.py *}
📁 `test_main.py` 🔜 ✔️ 💯 `main.py`, ⚫️ 💪 👀 💖 👉 🔜:
-```Python
-{!../../../docs_src/async_tests/test_main.py!}
-```
+{* ../../docs_src/async_tests/test_main.py *}
## 🏃 ⚫️
@@ -60,18 +56,17 @@ $ pytest
📑 `@pytest.mark.anyio` 💬 ✳ 👈 👉 💯 🔢 🔜 🤙 🔁:
-```Python hl_lines="7"
-{!../../../docs_src/async_tests/test_main.py!}
-```
+{* ../../docs_src/async_tests/test_main.py hl[7] *}
-!!! tip
- 🗒 👈 💯 🔢 🔜 `async def` ↩️ `def` ⏭ 🕐❔ ⚙️ `TestClient`.
+/// tip
+
+🗒 👈 💯 🔢 🔜 `async def` ↩️ `def` ⏭ 🕐❔ ⚙️ `TestClient`.
+
+///
⤴️ 👥 💪 ✍ `AsyncClient` ⏮️ 📱, & 📨 🔁 📨 ⚫️, ⚙️ `await`.
-```Python hl_lines="9-10"
-{!../../../docs_src/async_tests/test_main.py!}
-```
+{* ../../docs_src/async_tests/test_main.py hl[9:12] *}
👉 🌓:
@@ -81,12 +76,18 @@ response = client.get('/')
...👈 👥 ⚙️ ⚒ 👆 📨 ⏮️ `TestClient`.
-!!! tip
- 🗒 👈 👥 ⚙️ 🔁/⌛ ⏮️ 🆕 `AsyncClient` - 📨 🔁.
+/// tip
+
+🗒 👈 👥 ⚙️ 🔁/⌛ ⏮️ 🆕 `AsyncClient` - 📨 🔁.
+
+///
## 🎏 🔁 🔢 🤙
🔬 🔢 🔜 🔁, 👆 💪 🔜 🤙 (& `await`) 🎏 `async` 🔢 ↖️ ⚪️➡️ 📨 📨 👆 FastAPI 🈸 👆 💯, ⚫️❔ 👆 🔜 🤙 👫 🙆 🙆 👆 📟.
-!!! tip
- 🚥 👆 ⚔ `RuntimeError: Task attached to a different loop` 🕐❔ 🛠️ 🔁 🔢 🤙 👆 💯 (✅ 🕐❔ ⚙️ ✳ MotorClient) 💭 🔗 🎚 👈 💪 🎉 ➰ 🕴 🏞 🔁 🔢, ✅ `'@app.on_event("startup")` ⏲.
+/// tip
+
+🚥 👆 ⚔ `RuntimeError: Task attached to a different loop` 🕐❔ 🛠️ 🔁 🔢 🤙 👆 💯 (✅ 🕐❔ ⚙️ ✳ MotorClient) 💭 🔗 🎚 👈 💪 🎉 ➰ 🕴 🏞 🔁 🔢, ✅ `'@app.on_event("startup")` ⏲.
+
+///
diff --git a/docs/em/docs/advanced/behind-a-proxy.md b/docs/em/docs/advanced/behind-a-proxy.md
index e3fd26735..8b14152c9 100644
--- a/docs/em/docs/advanced/behind-a-proxy.md
+++ b/docs/em/docs/advanced/behind-a-proxy.md
@@ -39,8 +39,11 @@ browser --> proxy
proxy --> server
```
-!!! tip
- 📢 `0.0.0.0` 🛎 ⚙️ ⛓ 👈 📋 👂 🔛 🌐 📢 💪 👈 🎰/💽.
+/// tip
+
+📢 `0.0.0.0` 🛎 ⚙️ ⛓ 👈 📋 👂 🔛 🌐 📢 💪 👈 🎰/💽.
+
+///
🩺 🎚 🔜 💪 🗄 🔗 📣 👈 👉 🛠️ `server` 🔎 `/api/v1` (⛅ 🗳). 🖼:
@@ -77,10 +80,13 @@ $ uvicorn main:app --root-path /api/v1
🚥 👆 ⚙️ Hypercorn, ⚫️ ✔️ 🎛 `--root-path`.
-!!! note "📡 ℹ"
- 🔫 🔧 🔬 `root_path` 👉 ⚙️ 💼.
+/// note | 📡 ℹ
- & `--root-path` 📋 ⏸ 🎛 🚚 👈 `root_path`.
+🔫 🔧 🔬 `root_path` 👉 ⚙️ 💼.
+
+ & `--root-path` 📋 ⏸ 🎛 🚚 👈 `root_path`.
+
+///
### ✅ ⏮️ `root_path`
@@ -88,9 +94,7 @@ $ uvicorn main:app --root-path /api/v1
📥 👥 ✅ ⚫️ 📧 🎦 🎯.
-```Python hl_lines="8"
-{!../../../docs_src/behind_a_proxy/tutorial001.py!}
-```
+{* ../../docs_src/behind_a_proxy/tutorial001.py hl[8] *}
⤴️, 🚥 👆 ▶️ Uvicorn ⏮️:
@@ -117,9 +121,7 @@ $ uvicorn main:app --root-path /api/v1
👐, 🚥 👆 🚫 ✔️ 🌌 🚚 📋 ⏸ 🎛 💖 `--root-path` ⚖️ 🌓, 👆 💪 ⚒ `root_path` 🔢 🕐❔ 🏗 👆 FastAPI 📱:
-```Python hl_lines="3"
-{!../../../docs_src/behind_a_proxy/tutorial002.py!}
-```
+{* ../../docs_src/behind_a_proxy/tutorial002.py hl[3] *}
🚶♀️ `root_path` `FastAPI` 🔜 🌓 🚶♀️ `--root-path` 📋 ⏸ 🎛 Uvicorn ⚖️ Hypercorn.
@@ -168,8 +170,11 @@ Uvicorn 🔜 ⌛ 🗳 🔐 Uvicorn `http://127.0.0.1:8000/app`, & ⤴️ ⚫
👉 💬 Traefik 👂 🔛 ⛴ 9️⃣9️⃣9️⃣9️⃣ & ⚙️ ➕1️⃣ 📁 `routes.toml`.
-!!! tip
- 👥 ⚙️ ⛴ 9️⃣9️⃣9️⃣9️⃣ ↩️ 🐩 🇺🇸🔍 ⛴ 8️⃣0️⃣ 👈 👆 🚫 ✔️ 🏃 ⚫️ ⏮️ 📡 (`sudo`) 😌.
+/// tip
+
+👥 ⚙️ ⛴ 9️⃣9️⃣9️⃣9️⃣ ↩️ 🐩 🇺🇸🔍 ⛴ 8️⃣0️⃣ 👈 👆 🚫 ✔️ 🏃 ⚫️ ⏮️ 📡 (`sudo`) 😌.
+
+///
🔜 ✍ 👈 🎏 📁 `routes.toml`:
@@ -235,8 +240,11 @@ $ uvicorn main:app --root-path /api/v1
}
```
-!!! tip
- 👀 👈 ✋️ 👆 🔐 ⚫️ `http://127.0.0.1:8000/app` ⚫️ 🎦 `root_path` `/api/v1`, ✊ ⚪️➡️ 🎛 `--root-path`.
+/// tip
+
+👀 👈 ✋️ 👆 🔐 ⚫️ `http://127.0.0.1:8000/app` ⚫️ 🎦 `root_path` `/api/v1`, ✊ ⚪️➡️ 🎛 `--root-path`.
+
+///
& 🔜 📂 📛 ⏮️ ⛴ Traefik, ✅ ➡ 🔡: http://127.0.0.1:9999/api/v1/app.
@@ -279,8 +287,11 @@ $ uvicorn main:app --root-path /api/v1
## 🌖 💽
-!!! warning
- 👉 🌅 🏧 ⚙️ 💼. 💭 🆓 🚶 ⚫️.
+/// warning
+
+👉 🌅 🏧 ⚙️ 💼. 💭 🆓 🚶 ⚫️.
+
+///
🔢, **FastAPI** 🔜 ✍ `server` 🗄 🔗 ⏮️ 📛 `root_path`.
@@ -290,9 +301,7 @@ $ uvicorn main:app --root-path /api/v1
🖼:
-```Python hl_lines="4-7"
-{!../../../docs_src/behind_a_proxy/tutorial003.py!}
-```
+{* ../../docs_src/behind_a_proxy/tutorial003.py hl[4:7] *}
🔜 🏗 🗄 🔗 💖:
@@ -319,23 +328,27 @@ $ uvicorn main:app --root-path /api/v1
}
```
-!!! tip
- 👀 🚘-🏗 💽 ⏮️ `url` 💲 `/api/v1`, ✊ ⚪️➡️ `root_path`.
+/// tip
+
+👀 🚘-🏗 💽 ⏮️ `url` 💲 `/api/v1`, ✊ ⚪️➡️ `root_path`.
+
+///
🩺 🎚 http://127.0.0.1:9999/api/v1/docs ⚫️ 🔜 👀 💖:
-!!! tip
- 🩺 🎚 🔜 🔗 ⏮️ 💽 👈 👆 🖊.
+/// tip
+
+🩺 🎚 🔜 🔗 ⏮️ 💽 👈 👆 🖊.
+
+///
### ❎ 🏧 💽 ⚪️➡️ `root_path`
🚥 👆 🚫 💚 **FastAPI** 🔌 🏧 💽 ⚙️ `root_path`, 👆 💪 ⚙️ 🔢 `root_path_in_servers=False`:
-```Python hl_lines="9"
-{!../../../docs_src/behind_a_proxy/tutorial004.py!}
-```
+{* ../../docs_src/behind_a_proxy/tutorial004.py hl[9] *}
& ⤴️ ⚫️ 🏆 🚫 🔌 ⚫️ 🗄 🔗.
diff --git a/docs/em/docs/advanced/custom-response.md b/docs/em/docs/advanced/custom-response.md
index cf76c01d0..ab95b3e7b 100644
--- a/docs/em/docs/advanced/custom-response.md
+++ b/docs/em/docs/advanced/custom-response.md
@@ -12,8 +12,11 @@
& 🚥 👈 `Response` ✔️ 🎻 📻 🆎 (`application/json`), 💖 💼 ⏮️ `JSONResponse` & `UJSONResponse`, 💽 👆 📨 🔜 🔁 🗜 (& ⛽) ⏮️ 🙆 Pydantic `response_model` 👈 👆 📣 *➡ 🛠️ 👨🎨*.
-!!! note
- 🚥 👆 ⚙️ 📨 🎓 ⏮️ 🙅♂ 📻 🆎, FastAPI 🔜 ⌛ 👆 📨 ✔️ 🙅♂ 🎚, ⚫️ 🔜 🚫 📄 📨 📁 🚮 🏗 🗄 🩺.
+/// note
+
+🚥 👆 ⚙️ 📨 🎓 ⏮️ 🙅♂ 📻 🆎, FastAPI 🔜 ⌛ 👆 📨 ✔️ 🙅♂ 🎚, ⚫️ 🔜 🚫 📄 📨 📁 🚮 🏗 🗄 🩺.
+
+///
## ⚙️ `ORJSONResponse`
@@ -27,19 +30,23 @@
✋️ 🚥 👆 🎯 👈 🎚 👈 👆 🛬 **🎻 ⏮️ 🎻**, 👆 💪 🚶♀️ ⚫️ 🔗 📨 🎓 & ❎ ➕ 🌥 👈 FastAPI 🔜 ✔️ 🚶♀️ 👆 📨 🎚 🔘 `jsonable_encoder` ⏭ 🚶♀️ ⚫️ 📨 🎓.
-```Python hl_lines="2 7"
-{!../../../docs_src/custom_response/tutorial001b.py!}
-```
+{* ../../docs_src/custom_response/tutorial001b.py hl[2,7] *}
-!!! info
- 🔢 `response_class` 🔜 ⚙️ 🔬 "📻 🆎" 📨.
+/// info
- 👉 💼, 🇺🇸🔍 🎚 `Content-Type` 🔜 ⚒ `application/json`.
+🔢 `response_class` 🔜 ⚙️ 🔬 "📻 🆎" 📨.
- & ⚫️ 🔜 📄 ✅ 🗄.
+👉 💼, 🇺🇸🔍 🎚 `Content-Type` 🔜 ⚒ `application/json`.
-!!! tip
- `ORJSONResponse` ⏳ 🕴 💪 FastAPI, 🚫 💃.
+ & ⚫️ 🔜 📄 ✅ 🗄.
+
+///
+
+/// tip
+
+`ORJSONResponse` ⏳ 🕴 💪 FastAPI, 🚫 💃.
+
+///
## 🕸 📨
@@ -48,16 +55,17 @@
* 🗄 `HTMLResponse`.
* 🚶♀️ `HTMLResponse` 🔢 `response_class` 👆 *➡ 🛠️ 👨🎨*.
-```Python hl_lines="2 7"
-{!../../../docs_src/custom_response/tutorial002.py!}
-```
+{* ../../docs_src/custom_response/tutorial002.py hl[2,7] *}
-!!! info
- 🔢 `response_class` 🔜 ⚙️ 🔬 "📻 🆎" 📨.
+/// info
- 👉 💼, 🇺🇸🔍 🎚 `Content-Type` 🔜 ⚒ `text/html`.
+🔢 `response_class` 🔜 ⚙️ 🔬 "📻 🆎" 📨.
- & ⚫️ 🔜 📄 ✅ 🗄.
+👉 💼, 🇺🇸🔍 🎚 `Content-Type` 🔜 ⚒ `text/html`.
+
+ & ⚫️ 🔜 📄 ✅ 🗄.
+
+///
### 📨 `Response`
@@ -65,15 +73,19 @@
🎏 🖼 ⚪️➡️ 🔛, 🛬 `HTMLResponse`, 💪 👀 💖:
-```Python hl_lines="2 7 19"
-{!../../../docs_src/custom_response/tutorial003.py!}
-```
+{* ../../docs_src/custom_response/tutorial003.py hl[2,7,19] *}
-!!! warning
- `Response` 📨 🔗 👆 *➡ 🛠️ 🔢* 🏆 🚫 📄 🗄 (🖼, `Content-Type` 🏆 🚫 📄) & 🏆 🚫 ⭐ 🏧 🎓 🩺.
+/// warning
-!!! info
- ↗️, ☑ `Content-Type` 🎚, 👔 📟, ♒️, 🔜 👟 ⚪️➡️ `Response` 🎚 👆 📨.
+`Response` 📨 🔗 👆 *➡ 🛠️ 🔢* 🏆 🚫 📄 🗄 (🖼, `Content-Type` 🏆 🚫 📄) & 🏆 🚫 ⭐ 🏧 🎓 🩺.
+
+///
+
+/// info
+
+↗️, ☑ `Content-Type` 🎚, 👔 📟, ♒️, 🔜 👟 ⚪️➡️ `Response` 🎚 👆 📨.
+
+///
### 📄 🗄 & 🔐 `Response`
@@ -85,9 +97,7 @@
🖼, ⚫️ 💪 🕳 💖:
-```Python hl_lines="7 21 23"
-{!../../../docs_src/custom_response/tutorial004.py!}
-```
+{* ../../docs_src/custom_response/tutorial004.py hl[7,21,23] *}
👉 🖼, 🔢 `generate_html_response()` ⏪ 🏗 & 📨 `Response` ↩️ 🛬 🕸 `str`.
@@ -103,10 +113,13 @@
✔️ 🤯 👈 👆 💪 ⚙️ `Response` 📨 🕳 🙆, ⚖️ ✍ 🛃 🎧-🎓.
-!!! note "📡 ℹ"
- 👆 💪 ⚙️ `from starlette.responses import HTMLResponse`.
+/// note | 📡 ℹ
- **FastAPI** 🚚 🎏 `starlette.responses` `fastapi.responses` 🏪 👆, 👩💻. ✋️ 🌅 💪 📨 👟 🔗 ⚪️➡️ 💃.
+👆 💪 ⚙️ `from starlette.responses import HTMLResponse`.
+
+**FastAPI** 🚚 🎏 `starlette.responses` `fastapi.responses` 🏪 👆, 👩💻. ✋️ 🌅 💪 📨 👟 🔗 ⚪️➡️ 💃.
+
+///
### `Response`
@@ -123,9 +136,7 @@
FastAPI (🤙 💃) 🔜 🔁 🔌 🎚-📐 🎚. ⚫️ 🔜 🔌 🎚-🆎 🎚, ⚓️ 🔛 = & 🔁 = ✍ 🆎.
-```Python hl_lines="1 18"
-{!../../../docs_src/response_directly/tutorial002.py!}
-```
+{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
### `HTMLResponse`
@@ -135,9 +146,7 @@ FastAPI (🤙 💃) 🔜 🔁 🔌 🎚-📐 🎚. ⚫️ 🔜 🔌 🎚-🆎
✊ ✍ ⚖️ 🔢 & 📨 ✅ ✍ 📨.
-```Python hl_lines="2 7 9"
-{!../../../docs_src/custom_response/tutorial005.py!}
-```
+{* ../../docs_src/custom_response/tutorial005.py hl[2,7,9] *}
### `JSONResponse`
@@ -153,15 +162,19 @@ FastAPI (🤙 💃) 🔜 🔁 🔌 🎚-📐 🎚. ⚫️ 🔜 🔌 🎚-🆎
🎛 🎻 📨 ⚙️ `ujson`.
-!!! warning
- `ujson` 🌘 💛 🌘 🐍 🏗-🛠️ ❔ ⚫️ 🍵 📐-💼.
+/// warning
-```Python hl_lines="2 7"
-{!../../../docs_src/custom_response/tutorial001.py!}
-```
+`ujson` 🌘 💛 🌘 🐍 🏗-🛠️ ❔ ⚫️ 🍵 📐-💼.
-!!! tip
- ⚫️ 💪 👈 `ORJSONResponse` 💪 ⏩ 🎛.
+///
+
+{* ../../docs_src/custom_response/tutorial001.py hl[2,7] *}
+
+/// tip
+
+⚫️ 💪 👈 `ORJSONResponse` 💪 ⏩ 🎛.
+
+///
### `RedirectResponse`
@@ -169,18 +182,14 @@ FastAPI (🤙 💃) 🔜 🔁 🔌 🎚-📐 🎚. ⚫️ 🔜 🔌 🎚-🆎
👆 💪 📨 `RedirectResponse` 🔗:
-```Python hl_lines="2 9"
-{!../../../docs_src/custom_response/tutorial006.py!}
-```
+{* ../../docs_src/custom_response/tutorial006.py hl[2,9] *}
---
⚖️ 👆 💪 ⚙️ ⚫️ `response_class` 🔢:
-```Python hl_lines="2 7 9"
-{!../../../docs_src/custom_response/tutorial006b.py!}
-```
+{* ../../docs_src/custom_response/tutorial006b.py hl[2,7,9] *}
🚥 👆 👈, ⤴️ 👆 💪 📨 📛 🔗 ⚪️➡️ 👆 *➡ 🛠️* 🔢.
@@ -190,17 +199,13 @@ FastAPI (🤙 💃) 🔜 🔁 🔌 🎚-📐 🎚. ⚫️ 🔜 🔌 🎚-🆎
👆 💪 ⚙️ `status_code` 🔢 🌀 ⏮️ `response_class` 🔢:
-```Python hl_lines="2 7 9"
-{!../../../docs_src/custom_response/tutorial006c.py!}
-```
+{* ../../docs_src/custom_response/tutorial006c.py hl[2,7,9] *}
### `StreamingResponse`
✊ 🔁 🚂 ⚖️ 😐 🚂/🎻 & 🎏 📨 💪.
-```Python hl_lines="2 14"
-{!../../../docs_src/custom_response/tutorial007.py!}
-```
+{* ../../docs_src/custom_response/tutorial007.py hl[2,14] *}
#### ⚙️ `StreamingResponse` ⏮️ 📁-💖 🎚
@@ -211,7 +216,7 @@ FastAPI (🤙 💃) 🔜 🔁 🔌 🎚-📐 🎚. ⚫️ 🔜 🔌 🎚-🆎
👉 🔌 📚 🗃 🔗 ⏮️ ☁ 💾, 📹 🏭, & 🎏.
```{ .python .annotate hl_lines="2 10-12 14" }
-{!../../../docs_src/custom_response/tutorial008.py!}
+{!../../docs_src/custom_response/tutorial008.py!}
```
1️⃣. 👉 🚂 🔢. ⚫️ "🚂 🔢" ↩️ ⚫️ 🔌 `yield` 📄 🔘.
@@ -222,8 +227,11 @@ FastAPI (🤙 💃) 🔜 🔁 🔌 🎚-📐 🎚. ⚫️ 🔜 🔌 🎚-🆎
🔨 ⚫️ 👉 🌌, 👥 💪 🚮 ⚫️ `with` 🍫, & 👈 🌌, 🚚 👈 ⚫️ 📪 ⏮️ 🏁.
-!!! tip
- 👀 👈 📥 👥 ⚙️ 🐩 `open()` 👈 🚫 🐕🦺 `async` & `await`, 👥 📣 ➡ 🛠️ ⏮️ 😐 `def`.
+/// tip
+
+👀 👈 📥 👥 ⚙️ 🐩 `open()` 👈 🚫 🐕🦺 `async` & `await`, 👥 📣 ➡ 🛠️ ⏮️ 😐 `def`.
+
+///
### `FileResponse`
@@ -238,15 +246,11 @@ FastAPI (🤙 💃) 🔜 🔁 🔌 🎚-📐 🎚. ⚫️ 🔜 🔌 🎚-🆎
📁 📨 🔜 🔌 ☑ `Content-Length`, `Last-Modified` & `ETag` 🎚.
-```Python hl_lines="2 10"
-{!../../../docs_src/custom_response/tutorial009.py!}
-```
+{* ../../docs_src/custom_response/tutorial009.py hl[2,10] *}
👆 💪 ⚙️ `response_class` 🔢:
-```Python hl_lines="2 8 10"
-{!../../../docs_src/custom_response/tutorial009b.py!}
-```
+{* ../../docs_src/custom_response/tutorial009b.py hl[2,8,10] *}
👉 💼, 👆 💪 📨 📁 ➡ 🔗 ⚪️➡️ 👆 *➡ 🛠️* 🔢.
@@ -260,9 +264,7 @@ FastAPI (🤙 💃) 🔜 🔁 🔌 🎚-📐 🎚. ⚫️ 🔜 🔌 🎚-🆎
👆 💪 ✍ `CustomORJSONResponse`. 👑 👜 👆 ✔️ ✍ `Response.render(content)` 👩🔬 👈 📨 🎚 `bytes`:
-```Python hl_lines="9-14 17"
-{!../../../docs_src/custom_response/tutorial009c.py!}
-```
+{* ../../docs_src/custom_response/tutorial009c.py hl[9:14,17] *}
🔜 ↩️ 🛬:
@@ -288,12 +290,13 @@ FastAPI (🤙 💃) 🔜 🔁 🔌 🎚-📐 🎚. ⚫️ 🔜 🔌 🎚-🆎
🖼 🔛, **FastAPI** 🔜 ⚙️ `ORJSONResponse` 🔢, 🌐 *➡ 🛠️*, ↩️ `JSONResponse`.
-```Python hl_lines="2 4"
-{!../../../docs_src/custom_response/tutorial010.py!}
-```
+{* ../../docs_src/custom_response/tutorial010.py hl[2,4] *}
-!!! tip
- 👆 💪 🔐 `response_class` *➡ 🛠️* ⏭.
+/// tip
+
+👆 💪 🔐 `response_class` *➡ 🛠️* ⏭.
+
+///
## 🌖 🧾
diff --git a/docs/em/docs/advanced/dataclasses.md b/docs/em/docs/advanced/dataclasses.md
index e8c4b99a2..4dd597262 100644
--- a/docs/em/docs/advanced/dataclasses.md
+++ b/docs/em/docs/advanced/dataclasses.md
@@ -4,9 +4,7 @@ FastAPI 🏗 🔛 🔝 **Pydantic**, & 👤 ✔️ 🌏 👆 ❔ ⚙️ Pyda
✋️ FastAPI 🐕🦺 ⚙️ `dataclasses` 🎏 🌌:
-```Python hl_lines="1 7-12 19-20"
-{!../../../docs_src/dataclasses/tutorial001.py!}
-```
+{* ../../docs_src/dataclasses/tutorial001.py hl[1,7:12,19:20] *}
👉 🐕🦺 👏 **Pydantic**, ⚫️ ✔️ 🔗 🐕🦺 `dataclasses`.
@@ -20,20 +18,21 @@ FastAPI 🏗 🔛 🔝 **Pydantic**, & 👤 ✔️ 🌏 👆 ❔ ⚙️ Pyda
👉 👷 🎏 🌌 ⏮️ Pydantic 🏷. & ⚫️ 🤙 🏆 🎏 🌌 🔘, ⚙️ Pydantic.
-!!! info
- ✔️ 🤯 👈 🎻 💪 🚫 🌐 Pydantic 🏷 💪.
+/// info
- , 👆 5️⃣📆 💪 ⚙️ Pydantic 🏷.
+✔️ 🤯 👈 🎻 💪 🚫 🌐 Pydantic 🏷 💪.
- ✋️ 🚥 👆 ✔️ 📚 🎻 🤥 🤭, 👉 👌 🎱 ⚙️ 👫 🏋️ 🕸 🛠️ ⚙️ FastAPI. 👶
+, 👆 5️⃣📆 💪 ⚙️ Pydantic 🏷.
+
+✋️ 🚥 👆 ✔️ 📚 🎻 🤥 🤭, 👉 👌 🎱 ⚙️ 👫 🏋️ 🕸 🛠️ ⚙️ FastAPI. 👶
+
+///
## 🎻 `response_model`
👆 💪 ⚙️ `dataclasses` `response_model` 🔢:
-```Python hl_lines="1 7-13 19"
-{!../../../docs_src/dataclasses/tutorial002.py!}
-```
+{* ../../docs_src/dataclasses/tutorial002.py hl[1,7:13,19] *}
🎻 🔜 🔁 🗜 Pydantic 🎻.
@@ -50,7 +49,7 @@ FastAPI 🏗 🔛 🔝 **Pydantic**, & 👤 ✔️ 🌏 👆 ❔ ⚙️ Pyda
👈 💼, 👆 💪 🎯 💱 🐩 `dataclasses` ⏮️ `pydantic.dataclasses`, ❔ 💧-♻:
```{ .python .annotate hl_lines="1 5 8-11 14-17 23-25 28" }
-{!../../../docs_src/dataclasses/tutorial003.py!}
+{!../../docs_src/dataclasses/tutorial003.py!}
```
1️⃣. 👥 🗄 `field` ⚪️➡️ 🐩 `dataclasses`.
diff --git a/docs/em/docs/advanced/events.md b/docs/em/docs/advanced/events.md
index 19421ff58..68adb6d65 100644
--- a/docs/em/docs/advanced/events.md
+++ b/docs/em/docs/advanced/events.md
@@ -30,26 +30,25 @@
👥 ✍ 🔁 🔢 `lifespan()` ⏮️ `yield` 💖 👉:
-```Python hl_lines="16 19"
-{!../../../docs_src/events/tutorial003.py!}
-```
+{* ../../docs_src/events/tutorial003.py hl[16,19] *}
📥 👥 ⚖ 😥 *🕴* 🛠️ 🚚 🏷 🚮 (❌) 🏷 🔢 📖 ⏮️ 🎰 🏫 🏷 ⏭ `yield`. 👉 📟 🔜 🛠️ **⏭** 🈸 **▶️ ✊ 📨**, ⏮️ *🕴*.
& ⤴️, ▶️️ ⏮️ `yield`, 👥 🚚 🏷. 👉 📟 🔜 🛠️ **⏮️** 🈸 **🏁 🚚 📨**, ▶️️ ⏭ *🤫*. 👉 💪, 🖼, 🚀 ℹ 💖 💾 ⚖️ 💻.
-!!! tip
- `shutdown` 🔜 🔨 🕐❔ 👆 **⛔️** 🈸.
+/// tip
- 🎲 👆 💪 ▶️ 🆕 ⏬, ⚖️ 👆 🤚 🎡 🏃 ⚫️. 🤷
+`shutdown` 🔜 🔨 🕐❔ 👆 **⛔️** 🈸.
+
+🎲 👆 💪 ▶️ 🆕 ⏬, ⚖️ 👆 🤚 🎡 🏃 ⚫️. 🤷
+
+///
### 🔆 🔢
🥇 👜 👀, 👈 👥 ⚖ 🔁 🔢 ⏮️ `yield`. 👉 📶 🎏 🔗 ⏮️ `yield`.
-```Python hl_lines="14-19"
-{!../../../docs_src/events/tutorial003.py!}
-```
+{* ../../docs_src/events/tutorial003.py hl[14:19] *}
🥇 🍕 🔢, ⏭ `yield`, 🔜 🛠️ **⏭** 🈸 ▶️.
@@ -61,9 +60,7 @@
👈 🗜 🔢 🔘 🕳 🤙 "**🔁 🔑 👨💼**".
-```Python hl_lines="1 13"
-{!../../../docs_src/events/tutorial003.py!}
-```
+{* ../../docs_src/events/tutorial003.py hl[1,13] *}
**🔑 👨💼** 🐍 🕳 👈 👆 💪 ⚙️ `with` 📄, 🖼, `open()` 💪 ⚙️ 🔑 👨💼:
@@ -85,16 +82,17 @@ async with lifespan(app):
`lifespan` 🔢 `FastAPI` 📱 ✊ **🔁 🔑 👨💼**, 👥 💪 🚶♀️ 👆 🆕 `lifespan` 🔁 🔑 👨💼 ⚫️.
-```Python hl_lines="22"
-{!../../../docs_src/events/tutorial003.py!}
-```
+{* ../../docs_src/events/tutorial003.py hl[22] *}
## 🎛 🎉 (😢)
-!!! warning
- 👍 🌌 🍵 *🕴* & *🤫* ⚙️ `lifespan` 🔢 `FastAPI` 📱 🔬 🔛.
+/// warning
- 👆 💪 🎲 🚶 👉 🍕.
+👍 🌌 🍵 *🕴* & *🤫* ⚙️ `lifespan` 🔢 `FastAPI` 📱 🔬 🔛.
+
+👆 💪 🎲 🚶 👉 🍕.
+
+///
📤 🎛 🌌 🔬 👉 ⚛ 🛠️ ⏮️ *🕴* & ⏮️ *🤫*.
@@ -106,9 +104,7 @@ async with lifespan(app):
🚮 🔢 👈 🔜 🏃 ⏭ 🈸 ▶️, 📣 ⚫️ ⏮️ 🎉 `"startup"`:
-```Python hl_lines="8"
-{!../../../docs_src/events/tutorial001.py!}
-```
+{* ../../docs_src/events/tutorial001.py hl[8] *}
👉 💼, `startup` 🎉 🐕🦺 🔢 🔜 🔢 🏬 "💽" ( `dict`) ⏮️ 💲.
@@ -120,26 +116,33 @@ async with lifespan(app):
🚮 🔢 👈 🔜 🏃 🕐❔ 🈸 🤫 🔽, 📣 ⚫️ ⏮️ 🎉 `"shutdown"`:
-```Python hl_lines="6"
-{!../../../docs_src/events/tutorial002.py!}
-```
+{* ../../docs_src/events/tutorial002.py hl[6] *}
📥, `shutdown` 🎉 🐕🦺 🔢 🔜 ✍ ✍ ⏸ `"Application shutdown"` 📁 `log.txt`.
-!!! info
- `open()` 🔢, `mode="a"` ⛓ "🎻",, ⏸ 🔜 🚮 ⏮️ ⚫️❔ 🔛 👈 📁, 🍵 📁 ⏮️ 🎚.
+/// info
-!!! tip
- 👀 👈 👉 💼 👥 ⚙️ 🐩 🐍 `open()` 🔢 👈 🔗 ⏮️ 📁.
+`open()` 🔢, `mode="a"` ⛓ "🎻",, ⏸ 🔜 🚮 ⏮️ ⚫️❔ 🔛 👈 📁, 🍵 📁 ⏮️ 🎚.
- , ⚫️ 🔌 👤/🅾 (🔢/🔢), 👈 🚚 "⌛" 👜 ✍ 💾.
+///
- ✋️ `open()` 🚫 ⚙️ `async` & `await`.
+/// tip
- , 👥 📣 🎉 🐕🦺 🔢 ⏮️ 🐩 `def` ↩️ `async def`.
+👀 👈 👉 💼 👥 ⚙️ 🐩 🐍 `open()` 🔢 👈 🔗 ⏮️ 📁.
-!!! info
- 👆 💪 ✍ 🌅 🔃 👫 🎉 🐕🦺 💃 🎉' 🩺.
+, ⚫️ 🔌 👤/🅾 (🔢/🔢), 👈 🚚 "⌛" 👜 ✍ 💾.
+
+✋️ `open()` 🚫 ⚙️ `async` & `await`.
+
+, 👥 📣 🎉 🐕🦺 🔢 ⏮️ 🐩 `def` ↩️ `async def`.
+
+///
+
+/// info
+
+👆 💪 ✍ 🌅 🔃 👫 🎉 🐕🦺 💃 🎉' 🩺.
+
+///
### `startup` & `shutdown` 👯♂️
diff --git a/docs/em/docs/advanced/generate-clients.md b/docs/em/docs/advanced/generate-clients.md
index 261f9fb61..a680c9051 100644
--- a/docs/em/docs/advanced/generate-clients.md
+++ b/docs/em/docs/advanced/generate-clients.md
@@ -16,17 +16,7 @@
➡️ ▶️ ⏮️ 🙅 FastAPI 🈸:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="9-11 14-15 18 19 23"
- {!> ../../../docs_src/generate_clients/tutorial001.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="7-9 12-13 16-17 21"
- {!> ../../../docs_src/generate_clients/tutorial001_py39.py!}
- ```
+{* ../../docs_src/generate_clients/tutorial001.py hl[9:11,14:15,18,19,23] *}
👀 👈 *➡ 🛠️* 🔬 🏷 👫 ⚙️ 📨 🚀 & 📨 🚀, ⚙️ 🏷 `Item` & `ResponseMessage`.
@@ -111,8 +101,11 @@ frontend-app@1.0.0 generate-client /home/user/code/frontend-app
-!!! tip
- 👀 ✍ `name` & `price`, 👈 🔬 FastAPI 🈸, `Item` 🏷.
+/// tip
+
+👀 ✍ `name` & `price`, 👈 🔬 FastAPI 🈸, `Item` 🏷.
+
+///
👆 🔜 ✔️ ⏸ ❌ 📊 👈 👆 📨:
@@ -129,17 +122,7 @@ frontend-app@1.0.0 generate-client /home/user/code/frontend-app
🖼, 👆 💪 ✔️ 📄 **🏬** & ➕1️⃣ 📄 **👩💻**, & 👫 💪 👽 🔖:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="23 28 36"
- {!> ../../../docs_src/generate_clients/tutorial002.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="21 26 34"
- {!> ../../../docs_src/generate_clients/tutorial002_py39.py!}
- ```
+{* ../../docs_src/generate_clients/tutorial002.py hl[23,28,36] *}
### 🏗 📕 👩💻 ⏮️ 🔖
@@ -186,17 +169,7 @@ FastAPI ⚙️ **😍 🆔** 🔠 *➡ 🛠️*, ⚫️ ⚙️ **🛠️ 🆔**
👆 💪 ⤴️ 🚶♀️ 👈 🛃 🔢 **FastAPI** `generate_unique_id_function` 🔢:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="8-9 12"
- {!> ../../../docs_src/generate_clients/tutorial003.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="6-7 10"
- {!> ../../../docs_src/generate_clients/tutorial003_py39.py!}
- ```
+{* ../../docs_src/generate_clients/tutorial003.py hl[8:9,12] *}
### 🏗 📕 👩💻 ⏮️ 🛃 🛠️ 🆔
@@ -218,9 +191,7 @@ FastAPI ⚙️ **😍 🆔** 🔠 *➡ 🛠️*, ⚫️ ⚙️ **🛠️ 🆔**
👥 💪 ⏬ 🗄 🎻 📁 `openapi.json` & ⤴️ 👥 💪 **❎ 👈 🔡 🔖** ⏮️ ✍ 💖 👉:
-```Python
-{!../../../docs_src/generate_clients/tutorial004.py!}
-```
+{* ../../docs_src/generate_clients/tutorial004.py *}
⏮️ 👈, 🛠️ 🆔 🔜 📁 ⚪️➡️ 👜 💖 `items-get_items` `get_items`, 👈 🌌 👩💻 🚂 💪 🏗 🙅 👩🔬 📛.
diff --git a/docs/em/docs/advanced/index.md b/docs/em/docs/advanced/index.md
index 43bada6b4..48ef8e46d 100644
--- a/docs/em/docs/advanced/index.md
+++ b/docs/em/docs/advanced/index.md
@@ -6,10 +6,13 @@
⏭ 📄 👆 🔜 👀 🎏 🎛, 📳, & 🌖 ⚒.
-!!! tip
- ⏭ 📄 **🚫 🎯 "🏧"**.
+/// tip
- & ⚫️ 💪 👈 👆 ⚙️ 💼, ⚗ 1️⃣ 👫.
+⏭ 📄 **🚫 🎯 "🏧"**.
+
+ & ⚫️ 💪 👈 👆 ⚙️ 💼, ⚗ 1️⃣ 👫.
+
+///
## ✍ 🔰 🥇
diff --git a/docs/em/docs/advanced/middleware.md b/docs/em/docs/advanced/middleware.md
index b3e722ed0..cb04fa3fb 100644
--- a/docs/em/docs/advanced/middleware.md
+++ b/docs/em/docs/advanced/middleware.md
@@ -43,10 +43,13 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow")
**FastAPI** 🔌 📚 🛠️ ⚠ ⚙️ 💼, 👥 🔜 👀 ⏭ ❔ ⚙️ 👫.
-!!! note "📡 ℹ"
- ⏭ 🖼, 👆 💪 ⚙️ `from starlette.middleware.something import SomethingMiddleware`.
+/// note | 📡 ℹ
- **FastAPI** 🚚 📚 🛠️ `fastapi.middleware` 🏪 👆, 👩💻. ✋️ 🌅 💪 🛠️ 👟 🔗 ⚪️➡️ 💃.
+⏭ 🖼, 👆 💪 ⚙️ `from starlette.middleware.something import SomethingMiddleware`.
+
+**FastAPI** 🚚 📚 🛠️ `fastapi.middleware` 🏪 👆, 👩💻. ✋️ 🌅 💪 🛠️ 👟 🔗 ⚪️➡️ 💃.
+
+///
## `HTTPSRedirectMiddleware`
@@ -54,17 +57,13 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow")
🙆 📨 📨 `http` ⚖️ `ws` 🔜 ❎ 🔐 ⚖ ↩️.
-```Python hl_lines="2 6"
-{!../../../docs_src/advanced_middleware/tutorial001.py!}
-```
+{* ../../docs_src/advanced_middleware/tutorial001.py hl[2,6] *}
## `TrustedHostMiddleware`
🛠️ 👈 🌐 📨 📨 ✔️ ☑ ⚒ `Host` 🎚, ✔ 💂♂ 🛡 🇺🇸🔍 🦠 🎚 👊.
-```Python hl_lines="2 6-8"
-{!../../../docs_src/advanced_middleware/tutorial002.py!}
-```
+{* ../../docs_src/advanced_middleware/tutorial002.py hl[2,6:8] *}
📄 ❌ 🐕🦺:
@@ -78,9 +77,7 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow")
🛠️ 🔜 🍵 👯♂️ 🐩 & 🎥 📨.
-```Python hl_lines="2 6"
-{!../../../docs_src/advanced_middleware/tutorial003.py!}
-```
+{* ../../docs_src/advanced_middleware/tutorial003.py hl[2,6] *}
📄 ❌ 🐕🦺:
@@ -92,7 +89,6 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow")
🖼:
-* 🔫
* Uvicorn `ProxyHeadersMiddleware`
* 🇸🇲
diff --git a/docs/em/docs/advanced/openapi-callbacks.md b/docs/em/docs/advanced/openapi-callbacks.md
index 3355d6071..b0a821668 100644
--- a/docs/em/docs/advanced/openapi-callbacks.md
+++ b/docs/em/docs/advanced/openapi-callbacks.md
@@ -31,12 +31,13 @@
👉 🍕 📶 😐, 🌅 📟 🎲 ⏪ 😰 👆:
-```Python hl_lines="9-13 36-53"
-{!../../../docs_src/openapi_callbacks/tutorial001.py!}
-```
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[9:13,36:53] *}
-!!! tip
- `callback_url` 🔢 🔢 ⚙️ Pydantic 📛 🆎.
+/// tip
+
+`callback_url` 🔢 🔢 ⚙️ Pydantic 📛 🆎.
+
+///
🕴 🆕 👜 `callbacks=messages_callback_router.routes` ❌ *➡ 🛠️ 👨🎨*. 👥 🔜 👀 ⚫️❔ 👈 ⏭.
@@ -61,10 +62,13 @@ httpx.post(callback_url, json={"description": "Invoice paid", "paid": True})
👉 🖼 🚫 🛠️ ⏲ ⚫️ (👈 💪 ⏸ 📟), 🕴 🧾 🍕.
-!!! tip
- ☑ ⏲ 🇺🇸🔍 📨.
+/// tip
- 🕐❔ 🛠️ ⏲ 👆, 👆 💪 ⚙️ 🕳 💖 🇸🇲 ⚖️ 📨.
+☑ ⏲ 🇺🇸🔍 📨.
+
+🕐❔ 🛠️ ⏲ 👆, 👆 💪 ⚙️ 🕳 💖 🇸🇲 ⚖️ 📨.
+
+///
## ✍ ⏲ 🧾 📟
@@ -74,18 +78,19 @@ httpx.post(callback_url, json={"description": "Invoice paid", "paid": True})
👥 🔜 ⚙️ 👈 🎏 💡 📄 ❔ *🔢 🛠️* 🔜 👀 💖... 🏗 *➡ 🛠️(Ⓜ)* 👈 🔢 🛠️ 🔜 🛠️ (🕐 👆 🛠️ 🔜 🤙).
-!!! tip
- 🕐❔ ✍ 📟 📄 ⏲, ⚫️ 💪 ⚠ 🌈 👈 👆 👈 *🔢 👩💻*. & 👈 👆 ⏳ 🛠️ *🔢 🛠️*, 🚫 *👆 🛠️*.
+/// tip
- 🍕 🛠️ 👉 ☝ 🎑 ( *🔢 👩💻*) 💪 ℹ 👆 💭 💖 ⚫️ 🌅 ⭐ 🌐❔ 🚮 🔢, Pydantic 🏷 💪, 📨, ♒️. 👈 *🔢 🛠️*.
+🕐❔ ✍ 📟 📄 ⏲, ⚫️ 💪 ⚠ 🌈 👈 👆 👈 *🔢 👩💻*. & 👈 👆 ⏳ 🛠️ *🔢 🛠️*, 🚫 *👆 🛠️*.
+
+🍕 🛠️ 👉 ☝ 🎑 ( *🔢 👩💻*) 💪 ℹ 👆 💭 💖 ⚫️ 🌅 ⭐ 🌐❔ 🚮 🔢, Pydantic 🏷 💪, 📨, ♒️. 👈 *🔢 🛠️*.
+
+///
### ✍ ⏲ `APIRouter`
🥇 ✍ 🆕 `APIRouter` 👈 🔜 🔌 1️⃣ ⚖️ 🌅 ⏲.
-```Python hl_lines="3 25"
-{!../../../docs_src/openapi_callbacks/tutorial001.py!}
-```
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[3,25] *}
### ✍ ⏲ *➡ 🛠️*
@@ -96,9 +101,7 @@ httpx.post(callback_url, json={"description": "Invoice paid", "paid": True})
* ⚫️ 🔜 🎲 ✔️ 📄 💪 ⚫️ 🔜 📨, ✅ `body: InvoiceEvent`.
* & ⚫️ 💪 ✔️ 📄 📨 ⚫️ 🔜 📨, ✅ `response_model=InvoiceEventReceived`.
-```Python hl_lines="16-18 21-22 28-32"
-{!../../../docs_src/openapi_callbacks/tutorial001.py!}
-```
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[16:18,21:22,28:32] *}
📤 2️⃣ 👑 🔺 ⚪️➡️ 😐 *➡ 🛠️*:
@@ -154,8 +157,11 @@ https://www.external.org/events/invoices/2expen51ve
}
```
-!!! tip
- 👀 ❔ ⏲ 📛 ⚙️ 🔌 📛 📨 🔢 🔢 `callback_url` (`https://www.external.org/events`) & 🧾 `id` ⚪️➡️ 🔘 🎻 💪 (`2expen51ve`).
+/// tip
+
+👀 ❔ ⏲ 📛 ⚙️ 🔌 📛 📨 🔢 🔢 `callback_url` (`https://www.external.org/events`) & 🧾 `id` ⚪️➡️ 🔘 🎻 💪 (`2expen51ve`).
+
+///
### 🚮 ⏲ 📻
@@ -163,12 +169,13 @@ https://www.external.org/events/invoices/2expen51ve
🔜 ⚙️ 🔢 `callbacks` *👆 🛠️ ➡ 🛠️ 👨🎨* 🚶♀️ 🔢 `.routes` (👈 🤙 `list` 🛣/*➡ 🛠️*) ⚪️➡️ 👈 ⏲ 📻:
-```Python hl_lines="35"
-{!../../../docs_src/openapi_callbacks/tutorial001.py!}
-```
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[35] *}
-!!! tip
- 👀 👈 👆 🚫 🚶♀️ 📻 ⚫️ (`invoices_callback_router`) `callback=`, ✋️ 🔢 `.routes`, `invoices_callback_router.routes`.
+/// tip
+
+👀 👈 👆 🚫 🚶♀️ 📻 ⚫️ (`invoices_callback_router`) `callback=`, ✋️ 🔢 `.routes`, `invoices_callback_router.routes`.
+
+///
### ✅ 🩺
diff --git a/docs/em/docs/advanced/path-operation-advanced-configuration.md b/docs/em/docs/advanced/path-operation-advanced-configuration.md
index 3dc5ac536..9d9d5fa8d 100644
--- a/docs/em/docs/advanced/path-operation-advanced-configuration.md
+++ b/docs/em/docs/advanced/path-operation-advanced-configuration.md
@@ -2,16 +2,17 @@
## 🗄 {
-!!! warning
- 🚥 👆 🚫 "🕴" 🗄, 👆 🎲 🚫 💪 👉.
+/// warning
+
+🚥 👆 🚫 "🕴" 🗄, 👆 🎲 🚫 💪 👉.
+
+///
👆 💪 ⚒ 🗄 `operationId` ⚙️ 👆 *➡ 🛠️* ⏮️ 🔢 `operation_id`.
👆 🔜 ✔️ ⚒ 💭 👈 ⚫️ 😍 🔠 🛠️.
-```Python hl_lines="6"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial001.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial001.py hl[6] *}
### ⚙️ *➡ 🛠️ 🔢* 📛 {
@@ -19,25 +20,27 @@
👆 🔜 ⚫️ ⏮️ ❎ 🌐 👆 *➡ 🛠️*.
-```Python hl_lines="2 12-21 24"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial002.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial002.py hl[2,12:21,24] *}
-!!! tip
- 🚥 👆 ❎ 🤙 `app.openapi()`, 👆 🔜 ℹ `operationId`Ⓜ ⏭ 👈.
+/// tip
-!!! warning
- 🚥 👆 👉, 👆 ✔️ ⚒ 💭 🔠 1️⃣ 👆 *➡ 🛠️ 🔢* ✔️ 😍 📛.
+🚥 👆 ❎ 🤙 `app.openapi()`, 👆 🔜 ℹ `operationId`Ⓜ ⏭ 👈.
- 🚥 👫 🎏 🕹 (🐍 📁).
+///
+
+/// warning
+
+🚥 👆 👉, 👆 ✔️ ⚒ 💭 🔠 1️⃣ 👆 *➡ 🛠️ 🔢* ✔️ 😍 📛.
+
+🚥 👫 🎏 🕹 (🐍 📁).
+
+///
## 🚫 ⚪️➡️ 🗄
🚫 *➡ 🛠️* ⚪️➡️ 🏗 🗄 🔗 (& ➡️, ⚪️➡️ 🏧 🧾 ⚙️), ⚙️ 🔢 `include_in_schema` & ⚒ ⚫️ `False`:
-```Python hl_lines="6"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial003.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial003.py hl[6] *}
## 🏧 📛 ⚪️➡️ #️⃣
@@ -47,9 +50,7 @@
⚫️ 🏆 🚫 🎦 🆙 🧾, ✋️ 🎏 🧰 (✅ 🐉) 🔜 💪 ⚙️ 🎂.
-```Python hl_lines="19-29"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial004.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial004.py hl[19:29] *}
## 🌖 📨
@@ -65,8 +66,11 @@
🕐❔ 👆 📣 *➡ 🛠️* 👆 🈸, **FastAPI** 🔁 🏗 🔗 🗃 🔃 👈 *➡ 🛠️* 🔌 🗄 🔗.
-!!! note "📡 ℹ"
- 🗄 🔧 ⚫️ 🤙 🛠️ 🎚.
+/// note | 📡 ℹ
+
+🗄 🔧 ⚫️ 🤙 🛠️ 🎚.
+
+///
⚫️ ✔️ 🌐 ℹ 🔃 *➡ 🛠️* & ⚙️ 🏗 🏧 🧾.
@@ -74,10 +78,13 @@
👉 *➡ 🛠️*-🎯 🗄 🔗 🛎 🏗 🔁 **FastAPI**, ✋️ 👆 💪 ↔ ⚫️.
-!!! tip
- 👉 🔅 🎚 ↔ ☝.
+/// tip
- 🚥 👆 🕴 💪 📣 🌖 📨, 🌅 🏪 🌌 ⚫️ ⏮️ [🌖 📨 🗄](additional-responses.md){.internal-link target=_blank}.
+👉 🔅 🎚 ↔ ☝.
+
+🚥 👆 🕴 💪 📣 🌖 📨, 🌅 🏪 🌌 ⚫️ ⏮️ [🌖 📨 🗄](additional-responses.md){.internal-link target=_blank}.
+
+///
👆 💪 ↔ 🗄 🔗 *➡ 🛠️* ⚙️ 🔢 `openapi_extra`.
@@ -85,9 +92,7 @@
👉 `openapi_extra` 💪 👍, 🖼, 📣 [🗄 ↔](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions):
-```Python hl_lines="6"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial005.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial005.py hl[6] *}
🚥 👆 📂 🏧 🛠️ 🩺, 👆 ↔ 🔜 🎦 🆙 🔝 🎯 *➡ 🛠️*.
@@ -134,9 +139,7 @@
👆 💪 👈 ⏮️ `openapi_extra`:
-```Python hl_lines="20-37 39-40"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial006.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial006.py hl[20:37,39:40] *}
👉 🖼, 👥 🚫 📣 🙆 Pydantic 🏷. 👐, 📨 💪 🚫 🎻 🎻, ⚫️ ✍ 🔗 `bytes`, & 🔢 `magic_data_reader()` 🔜 🈚 🎻 ⚫️ 🌌.
@@ -150,9 +153,7 @@
🖼, 👉 🈸 👥 🚫 ⚙️ FastAPI 🛠️ 🛠️ ⚗ 🎻 🔗 ⚪️➡️ Pydantic 🏷 🚫 🏧 🔬 🎻. 👐, 👥 📣 📨 🎚 🆎 📁, 🚫 🎻:
-```Python hl_lines="17-22 24"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial007.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[17:22,24] *}
👐, 👐 👥 🚫 ⚙️ 🔢 🛠️ 🛠️, 👥 ⚙️ Pydantic 🏷 ❎ 🏗 🎻 🔗 💽 👈 👥 💚 📨 📁.
@@ -160,11 +161,12 @@
& ⤴️ 👆 📟, 👥 🎻 👈 📁 🎚 🔗, & ⤴️ 👥 🔄 ⚙️ 🎏 Pydantic 🏷 ✔ 📁 🎚:
-```Python hl_lines="26-33"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial007.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[26:33] *}
-!!! tip
- 📥 👥 🏤-⚙️ 🎏 Pydantic 🏷.
+/// tip
- ✋️ 🎏 🌌, 👥 💪 ✔️ ✔ ⚫️ 🎏 🌌.
+📥 👥 🏤-⚙️ 🎏 Pydantic 🏷.
+
+✋️ 🎏 🌌, 👥 💪 ✔️ ✔ ⚫️ 🎏 🌌.
+
+///
diff --git a/docs/em/docs/advanced/response-change-status-code.md b/docs/em/docs/advanced/response-change-status-code.md
index 156efcc16..4933484dd 100644
--- a/docs/em/docs/advanced/response-change-status-code.md
+++ b/docs/em/docs/advanced/response-change-status-code.md
@@ -20,9 +20,7 @@
& ⤴️ 👆 💪 ⚒ `status_code` 👈 *🔀* 📨 🎚.
-```Python hl_lines="1 9 12"
-{!../../../docs_src/response_change_status_code/tutorial001.py!}
-```
+{* ../../docs_src/response_change_status_code/tutorial001.py hl[1,9,12] *}
& ⤴️ 👆 💪 📨 🙆 🎚 👆 💪, 👆 🛎 🔜 ( `dict`, 💽 🏷, ♒️).
diff --git a/docs/em/docs/advanced/response-cookies.md b/docs/em/docs/advanced/response-cookies.md
index 23fffe1dd..d9fdbaa87 100644
--- a/docs/em/docs/advanced/response-cookies.md
+++ b/docs/em/docs/advanced/response-cookies.md
@@ -6,9 +6,7 @@
& ⤴️ 👆 💪 ⚒ 🍪 👈 *🔀* 📨 🎚.
-```Python hl_lines="1 8-9"
-{!../../../docs_src/response_cookies/tutorial002.py!}
-```
+{* ../../docs_src/response_cookies/tutorial002.py hl[1,8:9] *}
& ⤴️ 👆 💪 📨 🙆 🎚 👆 💪, 👆 🛎 🔜 ( `dict`, 💽 🏷, ♒️).
@@ -26,24 +24,28 @@
⤴️ ⚒ 🍪 ⚫️, & ⤴️ 📨 ⚫️:
-```Python hl_lines="10-12"
-{!../../../docs_src/response_cookies/tutorial001.py!}
-```
+{* ../../docs_src/response_cookies/tutorial001.py hl[10:12] *}
-!!! tip
- ✔️ 🤯 👈 🚥 👆 📨 📨 🔗 ↩️ ⚙️ `Response` 🔢, FastAPI 🔜 📨 ⚫️ 🔗.
+/// tip
- , 👆 🔜 ✔️ ⚒ 💭 👆 💽 ☑ 🆎. 🤶 Ⓜ. ⚫️ 🔗 ⏮️ 🎻, 🚥 👆 🛬 `JSONResponse`.
+✔️ 🤯 👈 🚥 👆 📨 📨 🔗 ↩️ ⚙️ `Response` 🔢, FastAPI 🔜 📨 ⚫️ 🔗.
- & 👈 👆 🚫 📨 🙆 📊 👈 🔜 ✔️ ⛽ `response_model`.
+, 👆 🔜 ✔️ ⚒ 💭 👆 💽 ☑ 🆎. 🤶 Ⓜ. ⚫️ 🔗 ⏮️ 🎻, 🚥 👆 🛬 `JSONResponse`.
+
+ & 👈 👆 🚫 📨 🙆 📊 👈 🔜 ✔️ ⛽ `response_model`.
+
+///
### 🌅 ℹ
-!!! note "📡 ℹ"
- 👆 💪 ⚙️ `from starlette.responses import Response` ⚖️ `from starlette.responses import JSONResponse`.
+/// note | 📡 ℹ
- **FastAPI** 🚚 🎏 `starlette.responses` `fastapi.responses` 🏪 👆, 👩💻. ✋️ 🌅 💪 📨 👟 🔗 ⚪️➡️ 💃.
+👆 💪 ⚙️ `from starlette.responses import Response` ⚖️ `from starlette.responses import JSONResponse`.
- & `Response` 💪 ⚙️ 🛎 ⚒ 🎚 & 🍪, **FastAPI** 🚚 ⚫️ `fastapi.Response`.
+**FastAPI** 🚚 🎏 `starlette.responses` `fastapi.responses` 🏪 👆, 👩💻. ✋️ 🌅 💪 📨 👟 🔗 ⚪️➡️ 💃.
+
+ & `Response` 💪 ⚙️ 🛎 ⚒ 🎚 & 🍪, **FastAPI** 🚚 ⚫️ `fastapi.Response`.
+
+///
👀 🌐 💪 🔢 & 🎛, ✅ 🧾 💃.
diff --git a/docs/em/docs/advanced/response-directly.md b/docs/em/docs/advanced/response-directly.md
index ba09734fb..29819a205 100644
--- a/docs/em/docs/advanced/response-directly.md
+++ b/docs/em/docs/advanced/response-directly.md
@@ -14,8 +14,11 @@
👐, 👆 💪 📨 🙆 `Response` ⚖️ 🙆 🎧-🎓 ⚫️.
-!!! tip
- `JSONResponse` ⚫️ 🎧-🎓 `Response`.
+/// tip
+
+`JSONResponse` ⚫️ 🎧-🎓 `Response`.
+
+///
& 🕐❔ 👆 📨 `Response`, **FastAPI** 🔜 🚶♀️ ⚫️ 🔗.
@@ -31,14 +34,15 @@
📚 💼, 👆 💪 ⚙️ `jsonable_encoder` 🗜 👆 📊 ⏭ 🚶♀️ ⚫️ 📨:
-```Python hl_lines="6-7 21-22"
-{!../../../docs_src/response_directly/tutorial001.py!}
-```
+{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *}
-!!! note "📡 ℹ"
- 👆 💪 ⚙️ `from starlette.responses import JSONResponse`.
+/// note | 📡 ℹ
- **FastAPI** 🚚 🎏 `starlette.responses` `fastapi.responses` 🏪 👆, 👩💻. ✋️ 🌅 💪 📨 👟 🔗 ⚪️➡️ 💃.
+👆 💪 ⚙️ `from starlette.responses import JSONResponse`.
+
+**FastAPI** 🚚 🎏 `starlette.responses` `fastapi.responses` 🏪 👆, 👩💻. ✋️ 🌅 💪 📨 👟 🔗 ⚪️➡️ 💃.
+
+///
## 🛬 🛃 `Response`
@@ -50,9 +54,7 @@
👆 💪 🚮 👆 📂 🎚 🎻, 🚮 ⚫️ `Response`, & 📨 ⚫️:
-```Python hl_lines="1 18"
-{!../../../docs_src/response_directly/tutorial002.py!}
-```
+{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
## 🗒
diff --git a/docs/em/docs/advanced/response-headers.md b/docs/em/docs/advanced/response-headers.md
index de798982a..e9e1b62d2 100644
--- a/docs/em/docs/advanced/response-headers.md
+++ b/docs/em/docs/advanced/response-headers.md
@@ -6,9 +6,7 @@
& ⤴️ 👆 💪 ⚒ 🎚 👈 *🔀* 📨 🎚.
-```Python hl_lines="1 7-8"
-{!../../../docs_src/response_headers/tutorial002.py!}
-```
+{* ../../docs_src/response_headers/tutorial002.py hl[1,7:8] *}
& ⤴️ 👆 💪 📨 🙆 🎚 👆 💪, 👆 🛎 🔜 ( `dict`, 💽 🏷, ♒️).
@@ -24,16 +22,17 @@
✍ 📨 🔬 [📨 📨 🔗](response-directly.md){.internal-link target=_blank} & 🚶♀️ 🎚 🌖 🔢:
-```Python hl_lines="10-12"
-{!../../../docs_src/response_headers/tutorial001.py!}
-```
+{* ../../docs_src/response_headers/tutorial001.py hl[10:12] *}
-!!! note "📡 ℹ"
- 👆 💪 ⚙️ `from starlette.responses import Response` ⚖️ `from starlette.responses import JSONResponse`.
+/// note | 📡 ℹ
- **FastAPI** 🚚 🎏 `starlette.responses` `fastapi.responses` 🏪 👆, 👩💻. ✋️ 🌅 💪 📨 👟 🔗 ⚪️➡️ 💃.
+👆 💪 ⚙️ `from starlette.responses import Response` ⚖️ `from starlette.responses import JSONResponse`.
- & `Response` 💪 ⚙️ 🛎 ⚒ 🎚 & 🍪, **FastAPI** 🚚 ⚫️ `fastapi.Response`.
+**FastAPI** 🚚 🎏 `starlette.responses` `fastapi.responses` 🏪 👆, 👩💻. ✋️ 🌅 💪 📨 👟 🔗 ⚪️➡️ 💃.
+
+ & `Response` 💪 ⚙️ 🛎 ⚒ 🎚 & 🍪, **FastAPI** 🚚 ⚫️ `fastapi.Response`.
+
+///
## 🛃 🎚
diff --git a/docs/em/docs/advanced/security/http-basic-auth.md b/docs/em/docs/advanced/security/http-basic-auth.md
index 33470a726..73736f3b3 100644
--- a/docs/em/docs/advanced/security/http-basic-auth.md
+++ b/docs/em/docs/advanced/security/http-basic-auth.md
@@ -20,9 +20,7 @@
* ⚫️ 📨 🎚 🆎 `HTTPBasicCredentials`:
* ⚫️ 🔌 `username` & `password` 📨.
-```Python hl_lines="2 6 10"
-{!../../../docs_src/security/tutorial006.py!}
-```
+{* ../../docs_src/security/tutorial006.py hl[2,6,10] *}
🕐❔ 👆 🔄 📂 📛 🥇 🕰 (⚖️ 🖊 "🛠️" 🔼 🩺) 🖥 🔜 💭 👆 👆 🆔 & 🔐:
@@ -42,9 +40,7 @@
⤴️ 👥 💪 ⚙️ `secrets.compare_digest()` 🚚 👈 `credentials.username` `"stanleyjobson"`, & 👈 `credentials.password` `"swordfish"`.
-```Python hl_lines="1 11-21"
-{!../../../docs_src/security/tutorial007.py!}
-```
+{* ../../docs_src/security/tutorial007.py hl[1,11:21] *}
👉 🔜 🎏:
@@ -108,6 +104,4 @@ if "stanleyjobsox" == "stanleyjobson" and "love123" == "swordfish":
⏮️ 🔍 👈 🎓 ❌, 📨 `HTTPException` ⏮️ 👔 📟 4️⃣0️⃣1️⃣ (🎏 📨 🕐❔ 🙅♂ 🎓 🚚) & 🚮 🎚 `WWW-Authenticate` ⚒ 🖥 🎦 💳 📋 🔄:
-```Python hl_lines="23-27"
-{!../../../docs_src/security/tutorial007.py!}
-```
+{* ../../docs_src/security/tutorial007.py hl[23:27] *}
diff --git a/docs/em/docs/advanced/security/index.md b/docs/em/docs/advanced/security/index.md
index 10291338e..5cdc47505 100644
--- a/docs/em/docs/advanced/security/index.md
+++ b/docs/em/docs/advanced/security/index.md
@@ -4,10 +4,13 @@
📤 ➕ ⚒ 🍵 💂♂ ↖️ ⚪️➡️ 🕐 📔 [🔰 - 👩💻 🦮: 💂♂](../../tutorial/security/index.md){.internal-link target=_blank}.
-!!! tip
- ⏭ 📄 **🚫 🎯 "🏧"**.
+/// tip
- & ⚫️ 💪 👈 👆 ⚙️ 💼, ⚗ 1️⃣ 👫.
+⏭ 📄 **🚫 🎯 "🏧"**.
+
+ & ⚫️ 💪 👈 👆 ⚙️ 💼, ⚗ 1️⃣ 👫.
+
+///
## ✍ 🔰 🥇
diff --git a/docs/em/docs/advanced/security/oauth2-scopes.md b/docs/em/docs/advanced/security/oauth2-scopes.md
index d82fe152b..b8c49bd11 100644
--- a/docs/em/docs/advanced/security/oauth2-scopes.md
+++ b/docs/em/docs/advanced/security/oauth2-scopes.md
@@ -10,18 +10,21 @@ Oauth2️⃣ ⏮️ ↔ 🛠️ ⚙️ 📚 🦏 🤝 🐕🦺, 💖 👱📔
👉 📄 👆 🔜 👀 ❔ 🛠️ 🤝 & ✔ ⏮️ 🎏 Oauth2️⃣ ⏮️ ↔ 👆 **FastAPI** 🈸.
-!!! warning
- 👉 🌅 ⚖️ 🌘 🏧 📄. 🚥 👆 ▶️, 👆 💪 🚶 ⚫️.
+/// warning
- 👆 🚫 🎯 💪 Oauth2️⃣ ↔, & 👆 💪 🍵 🤝 & ✔ 👐 👆 💚.
+👉 🌅 ⚖️ 🌘 🏧 📄. 🚥 👆 ▶️, 👆 💪 🚶 ⚫️.
- ✋️ Oauth2️⃣ ⏮️ ↔ 💪 🎆 🛠️ 🔘 👆 🛠️ (⏮️ 🗄) & 👆 🛠️ 🩺.
+👆 🚫 🎯 💪 Oauth2️⃣ ↔, & 👆 💪 🍵 🤝 & ✔ 👐 👆 💚.
- 👐, 👆 🛠️ 📚 ↔, ⚖️ 🙆 🎏 💂♂/✔ 📄, 👐 👆 💪, 👆 📟.
+✋️ Oauth2️⃣ ⏮️ ↔ 💪 🎆 🛠️ 🔘 👆 🛠️ (⏮️ 🗄) & 👆 🛠️ 🩺.
- 📚 💼, Oauth2️⃣ ⏮️ ↔ 💪 👹.
+👐, 👆 🛠️ 📚 ↔, ⚖️ 🙆 🎏 💂♂/✔ 📄, 👐 👆 💪, 👆 📟.
- ✋️ 🚥 👆 💭 👆 💪 ⚫️, ⚖️ 👆 😟, 🚧 👂.
+📚 💼, Oauth2️⃣ ⏮️ ↔ 💪 👹.
+
+✋️ 🚥 👆 💭 👆 💪 ⚫️, ⚖️ 👆 😟, 🚧 👂.
+
+///
## Oauth2️⃣ ↔ & 🗄
@@ -43,22 +46,23 @@ Oauth2️⃣ 🔧 🔬 "↔" 📇 🎻 🎏 🚀.
* `instagram_basic` ⚙️ 👱📔 / 👱📔.
* `https://www.googleapis.com/auth/drive` ⚙️ 🇺🇸🔍.
-!!! info
- Oauth2️⃣ "↔" 🎻 👈 📣 🎯 ✔ ✔.
+/// info
- ⚫️ 🚫 🤔 🚥 ⚫️ ✔️ 🎏 🦹 💖 `:` ⚖️ 🚥 ⚫️ 📛.
+Oauth2️⃣ "↔" 🎻 👈 📣 🎯 ✔ ✔.
- 👈 ℹ 🛠️ 🎯.
+⚫️ 🚫 🤔 🚥 ⚫️ ✔️ 🎏 🦹 💖 `:` ⚖️ 🚥 ⚫️ 📛.
- Oauth2️⃣ 👫 🎻.
+👈 ℹ 🛠️ 🎯.
+
+Oauth2️⃣ 👫 🎻.
+
+///
## 🌐 🎑
🥇, ➡️ 🔜 👀 🍕 👈 🔀 ⚪️➡️ 🖼 👑 **🔰 - 👩💻 🦮** [Oauth2️⃣ ⏮️ 🔐 (& 🔁), 📨 ⏮️ 🥙 🤝](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank}. 🔜 ⚙️ Oauth2️⃣ ↔:
-```Python hl_lines="2 4 8 12 46 64 105 107-115 121-124 128-134 139 155"
-{!../../../docs_src/security/tutorial005.py!}
-```
+{* ../../docs_src/security/tutorial005.py hl[2,4,8,12,46,64,105,107:115,121:124,128:134,139,155] *}
🔜 ➡️ 📄 👈 🔀 🔁 🔁.
@@ -68,9 +72,7 @@ Oauth2️⃣ 🔧 🔬 "↔" 📇 🎻 🎏 🚀.
`scopes` 🔢 📨 `dict` ⏮️ 🔠 ↔ 🔑 & 📛 💲:
-```Python hl_lines="62-65"
-{!../../../docs_src/security/tutorial005.py!}
-```
+{* ../../docs_src/security/tutorial005.py hl[62:65] *}
↩️ 👥 🔜 📣 📚 ↔, 👫 🔜 🎦 🆙 🛠️ 🩺 🕐❔ 👆 🕹-/✔.
@@ -88,14 +90,15 @@ Oauth2️⃣ 🔧 🔬 "↔" 📇 🎻 🎏 🚀.
& 👥 📨 ↔ 🍕 🥙 🤝.
-!!! danger
- 🦁, 📥 👥 ❎ ↔ 📨 🔗 🤝.
+/// danger
- ✋️ 👆 🈸, 💂♂, 👆 🔜 ⚒ 💭 👆 🕴 🚮 ↔ 👈 👩💻 🤙 💪 ✔️, ⚖️ 🕐 👆 ✔️ 🔁.
+🦁, 📥 👥 ❎ ↔ 📨 🔗 🤝.
-```Python hl_lines="155"
-{!../../../docs_src/security/tutorial005.py!}
-```
+✋️ 👆 🈸, 💂♂, 👆 🔜 ⚒ 💭 👆 🕴 🚮 ↔ 👈 👩💻 🤙 💪 ✔️, ⚖️ 🕐 👆 ✔️ 🔁.
+
+///
+
+{* ../../docs_src/security/tutorial005.py hl[155] *}
## 📣 ↔ *➡ 🛠️* & 🔗
@@ -113,21 +116,25 @@ Oauth2️⃣ 🔧 🔬 "↔" 📇 🎻 🎏 🚀.
👉 💼, ⚫️ 🚚 ↔ `me` (⚫️ 💪 🚚 🌅 🌘 1️⃣ ↔).
-!!! note
- 👆 🚫 🎯 💪 🚮 🎏 ↔ 🎏 🥉.
+/// note
- 👥 🔨 ⚫️ 📥 🎦 ❔ **FastAPI** 🍵 ↔ 📣 🎏 🎚.
+👆 🚫 🎯 💪 🚮 🎏 ↔ 🎏 🥉.
-```Python hl_lines="4 139 168"
-{!../../../docs_src/security/tutorial005.py!}
-```
+👥 🔨 ⚫️ 📥 🎦 ❔ **FastAPI** 🍵 ↔ 📣 🎏 🎚.
-!!! info "📡 ℹ"
- `Security` 🤙 🏿 `Depends`, & ⚫️ ✔️ 1️⃣ ➕ 🔢 👈 👥 🔜 👀 ⏪.
+///
- ✋️ ⚙️ `Security` ↩️ `Depends`, **FastAPI** 🔜 💭 👈 ⚫️ 💪 📣 💂♂ ↔, ⚙️ 👫 🔘, & 📄 🛠️ ⏮️ 🗄.
+{* ../../docs_src/security/tutorial005.py hl[4,139,168] *}
- ✋️ 🕐❔ 👆 🗄 `Query`, `Path`, `Depends`, `Security` & 🎏 ⚪️➡️ `fastapi`, 👈 🤙 🔢 👈 📨 🎁 🎓.
+/// info | 📡 ℹ
+
+`Security` 🤙 🏿 `Depends`, & ⚫️ ✔️ 1️⃣ ➕ 🔢 👈 👥 🔜 👀 ⏪.
+
+✋️ ⚙️ `Security` ↩️ `Depends`, **FastAPI** 🔜 💭 👈 ⚫️ 💪 📣 💂♂ ↔, ⚙️ 👫 🔘, & 📄 🛠️ ⏮️ 🗄.
+
+✋️ 🕐❔ 👆 🗄 `Query`, `Path`, `Depends`, `Security` & 🎏 ⚪️➡️ `fastapi`, 👈 🤙 🔢 👈 📨 🎁 🎓.
+
+///
## ⚙️ `SecurityScopes`
@@ -143,9 +150,7 @@ Oauth2️⃣ 🔧 🔬 "↔" 📇 🎻 🎏 🚀.
👉 `SecurityScopes` 🎓 🎏 `Request` (`Request` ⚙️ 🤚 📨 🎚 🔗).
-```Python hl_lines="8 105"
-{!../../../docs_src/security/tutorial005.py!}
-```
+{* ../../docs_src/security/tutorial005.py hl[8,105] *}
## ⚙️ `scopes`
@@ -159,9 +164,7 @@ Oauth2️⃣ 🔧 🔬 "↔" 📇 🎻 🎏 🚀.
👉 ⚠, 👥 🔌 ↔ 🚚 (🚥 🙆) 🎻 👽 🚀 (⚙️ `scope_str`). 👥 🚮 👈 🎻 ⚗ ↔ `WWW-Authenticate` 🎚 (👉 🍕 🔌).
-```Python hl_lines="105 107-115"
-{!../../../docs_src/security/tutorial005.py!}
-```
+{* ../../docs_src/security/tutorial005.py hl[105,107:115] *}
## ✔ `username` & 💽 💠
@@ -177,9 +180,7 @@ Oauth2️⃣ 🔧 🔬 "↔" 📇 🎻 🎏 🚀.
👥 ✔ 👈 👥 ✔️ 👩💻 ⏮️ 👈 🆔, & 🚥 🚫, 👥 🤚 👈 🎏 ⚠ 👥 ✍ ⏭.
-```Python hl_lines="46 116-127"
-{!../../../docs_src/security/tutorial005.py!}
-```
+{* ../../docs_src/security/tutorial005.py hl[46,116:127] *}
## ✔ `scopes`
@@ -187,9 +188,7 @@ Oauth2️⃣ 🔧 🔬 "↔" 📇 🎻 🎏 🚀.
👉, 👥 ⚙️ `security_scopes.scopes`, 👈 🔌 `list` ⏮️ 🌐 👫 ↔ `str`.
-```Python hl_lines="128-134"
-{!../../../docs_src/security/tutorial005.py!}
-```
+{* ../../docs_src/security/tutorial005.py hl[128:134] *}
## 🔗 🌲 & ↔
@@ -216,10 +215,13 @@ Oauth2️⃣ 🔧 🔬 "↔" 📇 🎻 🎏 🚀.
* `security_scopes.scopes` 🔜 🔌 `["me"]` *➡ 🛠️* `read_users_me`, ↩️ ⚫️ 📣 🔗 `get_current_active_user`.
* `security_scopes.scopes` 🔜 🔌 `[]` (🕳) *➡ 🛠️* `read_system_status`, ↩️ ⚫️ 🚫 📣 🙆 `Security` ⏮️ `scopes`, & 🚮 🔗, `get_current_user`, 🚫 📣 🙆 `scope` 👯♂️.
-!!! tip
- ⚠ & "🎱" 👜 📥 👈 `get_current_user` 🔜 ✔️ 🎏 📇 `scopes` ✅ 🔠 *➡ 🛠️*.
+/// tip
- 🌐 ⚓️ 🔛 `scopes` 📣 🔠 *➡ 🛠️* & 🔠 🔗 🔗 🌲 👈 🎯 *➡ 🛠️*.
+⚠ & "🎱" 👜 📥 👈 `get_current_user` 🔜 ✔️ 🎏 📇 `scopes` ✅ 🔠 *➡ 🛠️*.
+
+🌐 ⚓️ 🔛 `scopes` 📣 🔠 *➡ 🛠️* & 🔠 🔗 🔗 🌲 👈 🎯 *➡ 🛠️*.
+
+///
## 🌖 ℹ 🔃 `SecurityScopes`
@@ -257,10 +259,13 @@ Oauth2️⃣ 🔧 🔬 "↔" 📇 🎻 🎏 🚀.
🏆 🔐 📟 💧, ✋️ 🌖 🏗 🛠️ ⚫️ 🚚 🌅 📶. ⚫️ 🌅 🏗, 📚 🐕🦺 🔚 🆙 ✔ 🔑 💧.
-!!! note
- ⚫️ ⚠ 👈 🔠 🤝 🐕🦺 📛 👫 💧 🎏 🌌, ⚒ ⚫️ 🍕 👫 🏷.
+/// note
- ✋️ 🔚, 👫 🛠️ 🎏 Oauth2️⃣ 🐩.
+⚫️ ⚠ 👈 🔠 🤝 🐕🦺 📛 👫 💧 🎏 🌌, ⚒ ⚫️ 🍕 👫 🏷.
+
+✋️ 🔚, 👫 🛠️ 🎏 Oauth2️⃣ 🐩.
+
+///
**FastAPI** 🔌 🚙 🌐 👫 Oauth2️⃣ 🤝 💧 `fastapi.security.oauth2`.
diff --git a/docs/em/docs/advanced/settings.md b/docs/em/docs/advanced/settings.md
index c17212023..7fdd0d68a 100644
--- a/docs/em/docs/advanced/settings.md
+++ b/docs/em/docs/advanced/settings.md
@@ -8,44 +8,51 @@
## 🌐 🔢
-!!! tip
- 🚥 👆 ⏪ 💭 ⚫️❔ "🌐 🔢" & ❔ ⚙️ 👫, 💭 🆓 🚶 ⏭ 📄 🔛.
+/// tip
+
+🚥 👆 ⏪ 💭 ⚫️❔ "🌐 🔢" & ❔ ⚙️ 👫, 💭 🆓 🚶 ⏭ 📄 🔛.
+
+///
🌐 🔢 (💭 "🇨🇻 {") 🔢 👈 🖖 🏞 🐍 📟, 🏃♂ ⚙️, & 💪 ✍ 👆 🐍 📟 (⚖️ 🎏 📋 👍).
👆 💪 ✍ & ⚙️ 🌐 🔢 🐚, 🍵 💆♂ 🐍:
-=== "💾, 🇸🇻, 🚪 🎉"
+//// tab | 💾, 🇸🇻, 🚪 🎉
-
-!!! info
- 🌹 🖼 👯 🍏. 👶
+/// info
+
+🌹 🖼 👯 🍏. 👶
+
+///
---
@@ -199,8 +205,11 @@ def results():
📤 🚫 🌅 💬 ⚖️ 😏 🌅 🕰 💸 ⌛ 👶 🚪 ⏲. 👶
-!!! info
- 🌹 🖼 👯 🍏. 👶
+/// info
+
+🌹 🖼 👯 🍏. 👶
+
+///
---
@@ -392,12 +401,15 @@ async def read_burgers():
## 📶 📡 ℹ
-!!! warning
- 👆 💪 🎲 🚶 👉.
+/// warning
- 👉 📶 📡 ℹ ❔ **FastAPI** 👷 🔘.
+👆 💪 🎲 🚶 👉.
- 🚥 👆 ✔️ 📡 💡 (🈶-🏋, 🧵, 🍫, ♒️.) & 😟 🔃 ❔ FastAPI 🍵 `async def` 🆚 😐 `def`, 🚶 ⤴️.
+👉 📶 📡 ℹ ❔ **FastAPI** 👷 🔘.
+
+🚥 👆 ✔️ 📡 💡 (🈶-🏋, 🧵, 🍫, ♒️.) & 😟 🔃 ❔ FastAPI 🍵 `async def` 🆚 😐 `def`, 🚶 ⤴️.
+
+///
### ➡ 🛠️ 🔢
diff --git a/docs/em/docs/contributing.md b/docs/em/docs/contributing.md
deleted file mode 100644
index 08561d8f8..000000000
--- a/docs/em/docs/contributing.md
+++ /dev/null
@@ -1,465 +0,0 @@
-# 🛠️ - 📉
-
-🥇, 👆 💪 💚 👀 🔰 🌌 [ℹ FastAPI & 🤚 ℹ](help-fastapi.md){.internal-link target=_blank}.
-
-## 🛠️
-
-🚥 👆 ⏪ 🖖 🗃 & 👆 💭 👈 👆 💪 ⏬ 🤿 📟, 📥 📄 ⚒ 🆙 👆 🌐.
-
-### 🕹 🌐 ⏮️ `venv`
-
-👆 💪 ✍ 🕹 🌐 📁 ⚙️ 🐍 `venv` 🕹:
-
-
+
& ↗️, 🎏 🎰 🔜 🎲 ✔️ **🎏 🛠️** 🏃 👍, ↖️ ⚪️➡️ 👆 🈸.
@@ -238,10 +241,13 @@
* **☁ 🐕🦺** 👈 🍵 👉 👆
* ☁ 🐕🦺 🔜 🎲 **🍵 🧬 👆**. ⚫️ 🔜 🎲 ➡️ 👆 🔬 **🛠️ 🏃**, ⚖️ **📦 🖼** ⚙️, 🙆 💼, ⚫️ 🔜 🌅 🎲 **👁 Uvicorn 🛠️**, & ☁ 🐕🦺 🔜 🈚 🔁 ⚫️.
-!!! tip
- 🚫 😟 🚥 👫 🏬 🔃 **📦**, ☁, ⚖️ Kubernetes 🚫 ⚒ 📚 🔑.
+/// tip
- 👤 🔜 💬 👆 🌅 🔃 📦 🖼, ☁, Kubernetes, ♒️. 🔮 📃: [FastAPI 📦 - ☁](docker.md){.internal-link target=_blank}.
+🚫 😟 🚥 👫 🏬 🔃 **📦**, ☁, ⚖️ Kubernetes 🚫 ⚒ 📚 🔑.
+
+👤 🔜 💬 👆 🌅 🔃 📦 🖼, ☁, Kubernetes, ♒️. 🔮 📃: [FastAPI 📦 - ☁](docker.md){.internal-link target=_blank}.
+
+///
## ⏮️ 🔁 ⏭ ▶️
@@ -257,10 +263,13 @@
↗️, 📤 💼 🌐❔ 📤 🙅♂ ⚠ 🏃 ⏮️ 🔁 💗 🕰, 👈 💼, ⚫️ 📚 ⏩ 🍵.
-!!! tip
- , ✔️ 🤯 👈 ⚓️ 🔛 👆 🖥, 💼 👆 **5️⃣📆 🚫 💪 🙆 ⏮️ 🔁** ⏭ ▶️ 👆 🈸.
+/// tip
- 👈 💼, 👆 🚫🔜 ✔️ 😟 🔃 🙆 👉. 🤷
+, ✔️ 🤯 👈 ⚓️ 🔛 👆 🖥, 💼 👆 **5️⃣📆 🚫 💪 🙆 ⏮️ 🔁** ⏭ ▶️ 👆 🈸.
+
+👈 💼, 👆 🚫🔜 ✔️ 😟 🔃 🙆 👉. 🤷
+
+///
### 🖼 ⏮️ 🔁 🎛
@@ -272,8 +281,11 @@
* 🎉 ✍ 👈 🏃 ⏮️ 🔁 & ⤴️ ▶️ 👆 🈸
* 👆 🔜 💪 🌌 ▶️/⏏ *👈* 🎉 ✍, 🔍 ❌, ♒️.
-!!! tip
- 👤 🔜 🤝 👆 🌅 🧱 🖼 🔨 👉 ⏮️ 📦 🔮 📃: [FastAPI 📦 - ☁](docker.md){.internal-link target=_blank}.
+/// tip
+
+👤 🔜 🤝 👆 🌅 🧱 🖼 🔨 👉 ⏮️ 📦 🔮 📃: [FastAPI 📦 - ☁](docker.md){.internal-link target=_blank}.
+
+///
## ℹ 🛠️
diff --git a/docs/em/docs/deployment/docker.md b/docs/em/docs/deployment/docker.md
index 091eb3bab..2152f1a0e 100644
--- a/docs/em/docs/deployment/docker.md
+++ b/docs/em/docs/deployment/docker.md
@@ -4,8 +4,11 @@
⚙️ 💾 📦 ✔️ 📚 📈 ✅ **💂♂**, **🔬**, **🦁**, & 🎏.
-!!! tip
- 🏃 & ⏪ 💭 👉 💩 ❓ 🦘 [`Dockerfile` 🔛 👶](#fastapi).
+/// tip
+
+🏃 & ⏪ 💭 👉 💩 ❓ 🦘 [`Dockerfile` 🔛 👶](#fastapi).
+
+///
📁 🎮 👶
@@ -130,10 +133,13 @@ Successfully installed fastapi pydantic uvicorn
-!!! info
- 📤 🎏 📁 & 🧰 🔬 & ❎ 📦 🔗.
+/// info
- 👤 🔜 🎦 👆 🖼 ⚙️ 🎶 ⏪ 📄 🔛. 👶
+📤 🎏 📁 & 🧰 🔬 & ❎ 📦 🔗.
+
+👤 🔜 🎦 👆 🖼 ⚙️ 🎶 ⏪ 📄 🔛. 👶
+
+///
### ✍ **FastAPI** 📟
@@ -199,8 +205,11 @@ CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"]
`--no-cache-dir` 🎛 💬 `pip` 🚫 🖊 ⏬ 📦 🌐, 👈 🕴 🚥 `pip` 🔜 🏃 🔄 ❎ 🎏 📦, ✋️ 👈 🚫 💼 🕐❔ 👷 ⏮️ 📦.
- !!! note
- `--no-cache-dir` 🕴 🔗 `pip`, ⚫️ ✔️ 🕳 ⏮️ ☁ ⚖️ 📦.
+ /// note
+
+ `--no-cache-dir` 🕴 🔗 `pip`, ⚫️ ✔️ 🕳 ⏮️ ☁ ⚖️ 📦.
+
+ ///
`--upgrade` 🎛 💬 `pip` ♻ 📦 🚥 👫 ⏪ ❎.
@@ -222,8 +231,11 @@ CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"]
↩️ 📋 🔜 ▶️ `/code` & 🔘 ⚫️ 📁 `./app` ⏮️ 👆 📟, **Uvicorn** 🔜 💪 👀 & **🗄** `app` ⚪️➡️ `app.main`.
-!!! tip
- 📄 ⚫️❔ 🔠 ⏸ 🔨 🖊 🔠 🔢 💭 📟. 👶
+/// tip
+
+📄 ⚫️❔ 🔠 ⏸ 🔨 🖊 🔠 🔢 💭 📟. 👶
+
+///
👆 🔜 🔜 ✔️ 📁 📊 💖:
@@ -293,10 +305,13 @@ $ docker build -t myimage .
-!!! tip
- 👀 `.` 🔚, ⚫️ 🌓 `./`, ⚫️ 💬 ☁ 📁 ⚙️ 🏗 📦 🖼.
+/// tip
- 👉 💼, ⚫️ 🎏 ⏮️ 📁 (`.`).
+👀 `.` 🔚, ⚫️ 🌓 `./`, ⚫️ 💬 ☁ 📁 ⚙️ 🏗 📦 🖼.
+
+👉 💼, ⚫️ 🎏 ⏮️ 📁 (`.`).
+
+///
### ▶️ ☁ 📦
@@ -394,8 +409,11 @@ CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"]
⚫️ 💪 ➕1️⃣ 📦, 🖼 ⏮️ Traefik, 🚚 **🇺🇸🔍** & **🏧** 🛠️ **📄**.
-!!! tip
- Traefik ✔️ 🛠️ ⏮️ ☁, Kubernetes, & 🎏, ⚫️ 📶 ⏩ ⚒ 🆙 & 🔗 🇺🇸🔍 👆 📦 ⏮️ ⚫️.
+/// tip
+
+Traefik ✔️ 🛠️ ⏮️ ☁, Kubernetes, & 🎏, ⚫️ 📶 ⏩ ⚒ 🆙 & 🔗 🇺🇸🔍 👆 📦 ⏮️ ⚫️.
+
+///
👐, 🇺🇸🔍 💪 🍵 ☁ 🐕🦺 1️⃣ 👫 🐕🦺 (⏪ 🏃 🈸 📦).
@@ -423,8 +441,11 @@ CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"]
👉 🦲 🔜 ✊ **📐** 📨 & 📎 👈 👪 👨🏭 (🤞) **⚖** 🌌, ⚫️ 🛎 🤙 **📐 ⚙**.
-!!! tip
- 🎏 **🤝 ❎ 🗳** 🦲 ⚙️ 🇺🇸🔍 🔜 🎲 **📐 ⚙**.
+/// tip
+
+🎏 **🤝 ❎ 🗳** 🦲 ⚙️ 🇺🇸🔍 🔜 🎲 **📐 ⚙**.
+
+///
& 🕐❔ 👷 ⏮️ 📦, 🎏 ⚙️ 👆 ⚙️ ▶️ & 🛠️ 👫 🔜 ⏪ ✔️ 🔗 🧰 📶 **🕸 📻** (✅ 🇺🇸🔍 📨) ⚪️➡️ 👈 **📐 ⚙** (👈 💪 **🤝 ❎ 🗳**) 📦(Ⓜ) ⏮️ 👆 📱.
@@ -503,8 +524,11 @@ CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"]
🚥 👆 ✔️ **💗 📦**, 🎲 🔠 1️⃣ 🏃 **👁 🛠️** (🖼, **Kubernetes** 🌑), ⤴️ 👆 🔜 🎲 💚 ✔️ **🎏 📦** 🔨 👷 **⏮️ 📶** 👁 📦, 🏃 👁 🛠️, **⏭** 🏃 🔁 👨🏭 📦.
-!!! info
- 🚥 👆 ⚙️ Kubernetes, 👉 🔜 🎲 🕑 📦.
+/// info
+
+🚥 👆 ⚙️ Kubernetes, 👉 🔜 🎲 🕑 📦.
+
+///
🚥 👆 ⚙️ 💼 📤 🙅♂ ⚠ 🏃♂ 👈 ⏮️ 📶 **💗 🕰 🔗** (🖼 🚥 👆 🚫 🏃 💽 🛠️, ✋️ ✅ 🚥 💽 🔜), ⤴️ 👆 💪 🚮 👫 🔠 📦 ▶️️ ⏭ ▶️ 👑 🛠️.
@@ -520,8 +544,11 @@ CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"]
* tiangolo/uvicorn-🐁-fastapi.
-!!! warning
- 📤 ↕ 🤞 👈 👆 **🚫** 💪 👉 🧢 🖼 ⚖️ 🙆 🎏 🎏 1️⃣, & 🔜 👻 📆 🏗 🖼 ⚪️➡️ 🖌 [🔬 🔛: 🏗 ☁ 🖼 FastAPI](#fastapi).
+/// warning
+
+📤 ↕ 🤞 👈 👆 **🚫** 💪 👉 🧢 🖼 ⚖️ 🙆 🎏 🎏 1️⃣, & 🔜 👻 📆 🏗 🖼 ⚪️➡️ 🖌 [🔬 🔛: 🏗 ☁ 🖼 FastAPI](#fastapi).
+
+///
👉 🖼 ✔️ **🚘-📳** 🛠️ 🔌 ⚒ **🔢 👨🏭 🛠️** ⚓️ 🔛 💽 🐚 💪.
@@ -529,8 +556,11 @@ CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"]
⚫️ 🐕🦺 🏃 **⏮️ 🔁 ⏭ ▶️** ⏮️ ✍.
-!!! tip
- 👀 🌐 📳 & 🎛, 🚶 ☁ 🖼 📃: Tiangolo/uvicorn-🐁-fastapi.
+/// tip
+
+👀 🌐 📳 & 🎛, 🚶 ☁ 🖼 📃: Tiangolo/uvicorn-🐁-fastapi.
+
+///
### 🔢 🛠️ 🔛 🛂 ☁ 🖼
@@ -657,8 +687,11 @@ CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"]
1️⃣1️⃣. 🏃 `uvicorn` 📋, 💬 ⚫️ ⚙️ `app` 🎚 🗄 ⚪️➡️ `app.main`.
-!!! tip
- 🖊 💭 🔢 👀 ⚫️❔ 🔠 ⏸ 🔨.
+/// tip
+
+🖊 💭 🔢 👀 ⚫️❔ 🔠 ⏸ 🔨.
+
+///
**☁ ▶️** 🍕 `Dockerfile` 👈 👷 **🍕 📦 🖼** 👈 🕴 ⚙️ 🏗 📁 ⚙️ ⏪.
diff --git a/docs/em/docs/deployment/https.md b/docs/em/docs/deployment/https.md
index 3feb3a2c2..6d2641a92 100644
--- a/docs/em/docs/deployment/https.md
+++ b/docs/em/docs/deployment/https.md
@@ -4,8 +4,11 @@
✋️ ⚫️ 🌌 🌖 🏗 🌘 👈.
-!!! tip
- 🚥 👆 🏃 ⚖️ 🚫 💅, 😣 ⏮️ ⏭ 📄 🔁 🔁 👩🌾 ⚒ 🌐 🆙 ⏮️ 🎏 ⚒.
+/// tip
+
+🚥 👆 🏃 ⚖️ 🚫 💅, 😣 ⏮️ ⏭ 📄 🔁 🔁 👩🌾 ⚒ 🌐 🆙 ⏮️ 🎏 ⚒.
+
+///
**💡 🔰 🇺🇸🔍**, ⚪️➡️ 🏬 🤔, ✅ https://howhttps.works/.
@@ -68,8 +71,11 @@
👆 🔜 🎲 👉 🕐, 🥇 🕰, 🕐❔ ⚒ 🌐 🆙.
-!!! tip
- 👉 🆔 📛 🍕 🌌 ⏭ 🇺🇸🔍, ✋️ 🌐 🪀 🔛 🆔 & 📢 📢, ⚫️ 💸 💬 ⚫️ 📥.
+/// tip
+
+👉 🆔 📛 🍕 🌌 ⏭ 🇺🇸🔍, ✋️ 🌐 🪀 🔛 🆔 & 📢 📢, ⚫️ 💸 💬 ⚫️ 📥.
+
+///
### 🏓
@@ -79,7 +85,7 @@
🏓 💽 🔜 💬 🖥 ⚙️ 🎯 **📢 📢**. 👈 🔜 📢 📢 📢 ⚙️ 👆 💽, 👈 👆 🔗 🏓 💽.
-
+
### 🤝 🤝 ▶️
@@ -87,7 +93,7 @@
🥇 🍕 📻 🛠️ 🔗 🖖 👩💻 & 💽 & 💭 🔐 🔑 👫 🔜 ⚙️, ♒️.
-
+
👉 🔗 🖖 👩💻 & 💽 🛠️ 🤝 🔗 🤙 **🤝 🤝**.
@@ -105,7 +111,7 @@
👉 💼, ⚫️ 🔜 ⚙️ 📄 `someapp.example.com`.
-
+
👩💻 ⏪ **💙** 👨💼 👈 🏗 👈 🤝 📄 (👉 💼 ➡️ 🗜, ✋️ 👥 🔜 👀 🔃 👈 ⏪), ⚫️ 💪 **✔** 👈 📄 ☑.
@@ -115,8 +121,11 @@
& 👈 ⚫️❔ **🇺🇸🔍** , ⚫️ ✅ **🇺🇸🔍** 🔘 **🔐 🤝 🔗** ↩️ 😁 (💽) 🕸 🔗.
-!!! tip
- 👀 👈 🔐 📻 🔨 **🕸 🎚**, 🚫 🇺🇸🔍 🎚.
+/// tip
+
+👀 👈 🔐 📻 🔨 **🕸 🎚**, 🚫 🇺🇸🔍 🎚.
+
+///
### 🇺🇸🔍 📨
@@ -124,19 +133,19 @@
, 👩💻 📨 **🇺🇸🔍 📨**. 👉 🇺🇸🔍 📨 🔘 🗜 🤝 🔗.
-
+
### 🗜 📨
🤝 ❎ 🗳 🔜 ⚙️ 🔐 ✔ **🗜 📨**, & 🔜 📶 **✅ (🗜) 🇺🇸🔍 📨** 🛠️ 🏃 🈸 (🖼 🛠️ ⏮️ Uvicorn 🏃♂ FastAPI 🈸).
-
+
### 🇺🇸🔍 📨
🈸 🔜 🛠️ 📨 & 📨 **✅ (💽) 🇺🇸🔍 📨** 🤝 ❎ 🗳.
-
+
### 🇺🇸🔍 📨
@@ -144,7 +153,7 @@
⏭, 🖥 🔜 ✔ 👈 📨 ☑ & 🗜 ⏮️ ▶️️ 🔐 🔑, ♒️. ⚫️ 🔜 ⤴️ **🗜 📨** & 🛠️ ⚫️.
-
+
👩💻 (🖥) 🔜 💭 👈 📨 👟 ⚪️➡️ ☑ 💽 ↩️ ⚫️ ⚙️ ⚛ 👫 ✔ ⚙️ **🇺🇸🔍 📄** ⏭.
@@ -154,7 +163,7 @@
🕴 1️⃣ 🛠️ 💪 🚚 🎯 📢 & ⛴ (🤝 ❎ 🗳 👆 🖼) ✋️ 🎏 🈸/🛠️ 💪 🏃 🔛 💽(Ⓜ) 💁♂️, 📏 👫 🚫 🔄 ⚙️ 🎏 **🌀 📢 📢 & ⛴**.
-
+
👈 🌌, 🤝 ❎ 🗳 💪 🍵 🇺🇸🔍 & 📄 **💗 🆔**, 💗 🈸, & ⤴️ 📶 📨 ▶️️ 🈸 🔠 💼.
@@ -164,7 +173,7 @@
& ⤴️, 📤 🔜 ➕1️⃣ 📋 (💼 ⚫️ ➕1️⃣ 📋, 💼 ⚫️ 💪 🎏 🤝 ❎ 🗳) 👈 🔜 💬 ➡️ 🗜, & ♻ 📄(Ⓜ).
-
+
**🤝 📄** **🔗 ⏮️ 🆔 📛**, 🚫 ⏮️ 📢 📢.
diff --git a/docs/em/docs/deployment/manually.md b/docs/em/docs/deployment/manually.md
index 43cbc9409..8ebe00c7c 100644
--- a/docs/em/docs/deployment/manually.md
+++ b/docs/em/docs/deployment/manually.md
@@ -22,75 +22,89 @@
👆 💪 ❎ 🔫 🔗 💽 ⏮️:
-=== "Uvicorn"
+//// tab | Uvicorn
- * Uvicorn, 🌩-⏩ 🔫 💽, 🏗 🔛 uvloop & httptool.
+* Uvicorn, 🌩-⏩ 🔫 💽, 🏗 🔛 uvloop & httptool.
-
-{% endfor %}
-{% endif %}
-
-{% if sponsors.silver %}
-
-### 🥇1st 💰
-
-{% for sponsor in sponsors.silver -%}
-
-{% endfor %}
-{% endif %}
-
-{% if sponsors.bronze %}
-
-### 🥈2nd 💰
-
-{% for sponsor in sponsors.bronze -%}
-
-{% endfor %}
-{% endif %}
-
-{% endif %}
-
-### 🎯 💰
-
-{% if github_sponsors %}
-{% for group in github_sponsors.sponsors %}
-
-
-
+
@@ -93,7 +93,7 @@ FastAPI 🏛, ⏩ (↕-🎭), 🕸 🛠️ 🏗 🛠️ ⏮️ 🐍 3️⃣.8️
"_🤙, ⚫️❔ 👆 ✔️ 🏗 👀 💎 💠 & 🇵🇱. 📚 🌌, ⚫️ ⚫️❔ 👤 💚 **🤗** - ⚫️ 🤙 😍 👀 👱 🏗 👈._"
-
+
---
@@ -133,7 +133,7 @@ FastAPI 🧍 🔛 ⌚ 🐘:
email_validator - 📧 🔬.
+* email-validator - 📧 🔬.
⚙️ 💃:
diff --git a/docs/em/docs/python-types.md b/docs/em/docs/python-types.md
index b3026917a..d2af23bb9 100644
--- a/docs/em/docs/python-types.md
+++ b/docs/em/docs/python-types.md
@@ -12,15 +12,18 @@
✋️ 🚥 👆 🙅 ⚙️ **FastAPI**, 👆 🔜 💰 ⚪️➡️ 🏫 🍖 🔃 👫.
-!!! note
- 🚥 👆 🐍 🕴, & 👆 ⏪ 💭 🌐 🔃 🆎 🔑, 🚶 ⏭ 📃.
+/// note
+
+🚥 👆 🐍 🕴, & 👆 ⏪ 💭 🌐 🔃 🆎 🔑, 🚶 ⏭ 📃.
+
+///
## 🎯
➡️ ▶️ ⏮️ 🙅 🖼:
```Python
-{!../../../docs_src/python_types/tutorial001.py!}
+{!../../docs_src/python_types/tutorial001.py!}
```
🤙 👉 📋 🔢:
@@ -36,7 +39,7 @@ John Doe
* 🔢 👫 ⏮️ 🚀 🖕.
```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial001.py!}
+{!../../docs_src/python_types/tutorial001.py!}
```
### ✍ ⚫️
@@ -80,7 +83,7 @@ John Doe
👈 "🆎 🔑":
```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial002.py!}
+{!../../docs_src/python_types/tutorial002.py!}
```
👈 🚫 🎏 📣 🔢 💲 💖 🔜 ⏮️:
@@ -110,7 +113,7 @@ John Doe
✅ 👉 🔢, ⚫️ ⏪ ✔️ 🆎 🔑:
```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial003.py!}
+{!../../docs_src/python_types/tutorial003.py!}
```
↩️ 👨🎨 💭 🆎 🔢, 👆 🚫 🕴 🤚 🛠️, 👆 🤚 ❌ ✅:
@@ -120,7 +123,7 @@ John Doe
🔜 👆 💭 👈 👆 ✔️ 🔧 ⚫️, 🗜 `age` 🎻 ⏮️ `str(age)`:
```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial004.py!}
+{!../../docs_src/python_types/tutorial004.py!}
```
## 📣 🆎
@@ -141,7 +144,7 @@ John Doe
* `bytes`
```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial005.py!}
+{!../../docs_src/python_types/tutorial005.py!}
```
### 💊 🆎 ⏮️ 🆎 🔢
@@ -164,45 +167,55 @@ John Doe
🖼, ➡️ 🔬 🔢 `list` `str`.
-=== "🐍 3️⃣.6️⃣ & 🔛"
+//// tab | 🐍 3️⃣.6️⃣ & 🔛
- ⚪️➡️ `typing`, 🗄 `List` (⏮️ 🔠 `L`):
+⚪️➡️ `typing`, 🗄 `List` (⏮️ 🔠 `L`):
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial006.py!}
- ```
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial006.py!}
+```
- 📣 🔢, ⏮️ 🎏 ❤ (`:`) ❕.
+📣 🔢, ⏮️ 🎏 ❤ (`:`) ❕.
- 🆎, 🚮 `List` 👈 👆 🗄 ⚪️➡️ `typing`.
+🆎, 🚮 `List` 👈 👆 🗄 ⚪️➡️ `typing`.
- 📇 🆎 👈 🔌 🔗 🆎, 👆 🚮 👫 ⬜ 🗜:
+📇 🆎 👈 🔌 🔗 🆎, 👆 🚮 👫 ⬜ 🗜:
- ```Python hl_lines="4"
- {!> ../../../docs_src/python_types/tutorial006.py!}
- ```
+```Python hl_lines="4"
+{!> ../../docs_src/python_types/tutorial006.py!}
+```
-=== "🐍 3️⃣.9️⃣ & 🔛"
+////
- 📣 🔢, ⏮️ 🎏 ❤ (`:`) ❕.
+//// tab | 🐍 3️⃣.9️⃣ & 🔛
- 🆎, 🚮 `list`.
+📣 🔢, ⏮️ 🎏 ❤ (`:`) ❕.
- 📇 🆎 👈 🔌 🔗 🆎, 👆 🚮 👫 ⬜ 🗜:
+🆎, 🚮 `list`.
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial006_py39.py!}
- ```
+📇 🆎 👈 🔌 🔗 🆎, 👆 🚮 👫 ⬜ 🗜:
-!!! info
- 👈 🔗 🆎 ⬜ 🗜 🤙 "🆎 🔢".
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial006_py39.py!}
+```
- 👉 💼, `str` 🆎 🔢 🚶♀️ `List` (⚖️ `list` 🐍 3️⃣.9️⃣ & 🔛).
+////
+
+/// info
+
+👈 🔗 🆎 ⬜ 🗜 🤙 "🆎 🔢".
+
+👉 💼, `str` 🆎 🔢 🚶♀️ `List` (⚖️ `list` 🐍 3️⃣.9️⃣ & 🔛).
+
+///
👈 ⛓: "🔢 `items` `list`, & 🔠 🏬 👉 📇 `str`".
-!!! tip
- 🚥 👆 ⚙️ 🐍 3️⃣.9️⃣ ⚖️ 🔛, 👆 🚫 ✔️ 🗄 `List` ⚪️➡️ `typing`, 👆 💪 ⚙️ 🎏 🥔 `list` 🆎 ↩️.
+/// tip
+
+🚥 👆 ⚙️ 🐍 3️⃣.9️⃣ ⚖️ 🔛, 👆 🚫 ✔️ 🗄 `List` ⚪️➡️ `typing`, 👆 💪 ⚙️ 🎏 🥔 `list` 🆎 ↩️.
+
+///
🔨 👈, 👆 👨🎨 💪 🚚 🐕🦺 ⏪ 🏭 🏬 ⚪️➡️ 📇:
@@ -218,17 +231,21 @@ John Doe
👆 🔜 🎏 📣 `tuple`Ⓜ & `set`Ⓜ:
-=== "🐍 3️⃣.6️⃣ & 🔛"
+//// tab | 🐍 3️⃣.6️⃣ & 🔛
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial007.py!}
- ```
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial007.py!}
+```
-=== "🐍 3️⃣.9️⃣ & 🔛"
+////
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial007_py39.py!}
- ```
+//// tab | 🐍 3️⃣.9️⃣ & 🔛
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial007_py39.py!}
+```
+
+////
👉 ⛓:
@@ -243,17 +260,21 @@ John Doe
🥈 🆎 🔢 💲 `dict`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
+//// tab | 🐍 3️⃣.6️⃣ & 🔛
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial008.py!}
- ```
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial008.py!}
+```
-=== "🐍 3️⃣.9️⃣ & 🔛"
+////
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial008_py39.py!}
- ```
+//// tab | 🐍 3️⃣.9️⃣ & 🔛
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008_py39.py!}
+```
+
+////
👉 ⛓:
@@ -269,17 +290,21 @@ John Doe
🐍 3️⃣.1️⃣0️⃣ 📤 **🎛 ❕** 🌐❔ 👆 💪 🚮 💪 🆎 👽 ⏸ ⏸ (`|`).
-=== "🐍 3️⃣.6️⃣ & 🔛"
+//// tab | 🐍 3️⃣.6️⃣ & 🔛
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial008b.py!}
- ```
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial008b.py!}
+```
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
+////
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial008b_py310.py!}
- ```
+//// tab | 🐍 3️⃣.1️⃣0️⃣ & 🔛
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008b_py310.py!}
+```
+
+////
👯♂️ 💼 👉 ⛓ 👈 `item` 💪 `int` ⚖️ `str`.
@@ -290,7 +315,7 @@ John Doe
🐍 3️⃣.6️⃣ & 🔛 (✅ 🐍 3️⃣.1️⃣0️⃣) 👆 💪 📣 ⚫️ 🏭 & ⚙️ `Optional` ⚪️➡️ `typing` 🕹.
```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial009.py!}
+{!../../docs_src/python_types/tutorial009.py!}
```
⚙️ `Optional[str]` ↩️ `str` 🔜 ➡️ 👨🎨 ℹ 👆 🔍 ❌ 🌐❔ 👆 💪 🤔 👈 💲 🕧 `str`, 🕐❔ ⚫️ 💪 🤙 `None` 💁♂️.
@@ -299,23 +324,29 @@ John Doe
👉 ⛓ 👈 🐍 3️⃣.1️⃣0️⃣, 👆 💪 ⚙️ `Something | None`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
+//// tab | 🐍 3️⃣.6️⃣ & 🔛
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial009.py!}
- ```
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial009.py!}
+```
-=== "🐍 3️⃣.6️⃣ & 🔛 - 🎛"
+////
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial009b.py!}
- ```
+//// tab | 🐍 3️⃣.6️⃣ & 🔛 - 🎛
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial009b.py!}
+```
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial009_py310.py!}
- ```
+////
+
+//// tab | 🐍 3️⃣.1️⃣0️⃣ & 🔛
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial009_py310.py!}
+```
+
+////
#### ⚙️ `Union` ⚖️ `Optional`
@@ -333,7 +364,7 @@ John Doe
🖼, ➡️ ✊ 👉 🔢:
```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial009c.py!}
+{!../../docs_src/python_types/tutorial009c.py!}
```
🔢 `name` 🔬 `Optional[str]`, ✋️ ⚫️ **🚫 📦**, 👆 🚫🔜 🤙 🔢 🍵 🔢:
@@ -351,7 +382,7 @@ say_hi(name=None) # This works, None is valid 🎉
👍 📰, 🕐 👆 🔛 🐍 3️⃣.1️⃣0️⃣ 👆 🏆 🚫 ✔️ 😟 🔃 👈, 👆 🔜 💪 🎯 ⚙️ `|` 🔬 🇪🇺 🆎:
```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial009c_py310.py!}
+{!../../docs_src/python_types/tutorial009c_py310.py!}
```
& ⤴️ 👆 🏆 🚫 ✔️ 😟 🔃 📛 💖 `Optional` & `Union`. 👶
@@ -360,47 +391,53 @@ say_hi(name=None) # This works, None is valid 🎉
👉 🆎 👈 ✊ 🆎 🔢 ⬜ 🗜 🤙 **💊 🆎** ⚖️ **💊**, 🖼:
-=== "🐍 3️⃣.6️⃣ & 🔛"
+//// tab | 🐍 3️⃣.6️⃣ & 🔛
- * `List`
- * `Tuple`
- * `Set`
- * `Dict`
- * `Union`
- * `Optional`
- * ...& 🎏.
+* `List`
+* `Tuple`
+* `Set`
+* `Dict`
+* `Union`
+* `Optional`
+* ...& 🎏.
-=== "🐍 3️⃣.9️⃣ & 🔛"
+////
- 👆 💪 ⚙️ 🎏 💽 🆎 💊 (⏮️ ⬜ 🗜 & 🆎 🔘):
+//// tab | 🐍 3️⃣.9️⃣ & 🔛
- * `list`
- * `tuple`
- * `set`
- * `dict`
+👆 💪 ⚙️ 🎏 💽 🆎 💊 (⏮️ ⬜ 🗜 & 🆎 🔘):
- & 🎏 ⏮️ 🐍 3️⃣.6️⃣, ⚪️➡️ `typing` 🕹:
+* `list`
+* `tuple`
+* `set`
+* `dict`
- * `Union`
- * `Optional`
- * ...& 🎏.
+ & 🎏 ⏮️ 🐍 3️⃣.6️⃣, ⚪️➡️ `typing` 🕹:
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
+* `Union`
+* `Optional`
+* ...& 🎏.
- 👆 💪 ⚙️ 🎏 💽 🆎 💊 (⏮️ ⬜ 🗜 & 🆎 🔘):
+////
- * `list`
- * `tuple`
- * `set`
- * `dict`
+//// tab | 🐍 3️⃣.1️⃣0️⃣ & 🔛
- & 🎏 ⏮️ 🐍 3️⃣.6️⃣, ⚪️➡️ `typing` 🕹:
+👆 💪 ⚙️ 🎏 💽 🆎 💊 (⏮️ ⬜ 🗜 & 🆎 🔘):
- * `Union`
- * `Optional` (🎏 ⏮️ 🐍 3️⃣.6️⃣)
- * ...& 🎏.
+* `list`
+* `tuple`
+* `set`
+* `dict`
- 🐍 3️⃣.1️⃣0️⃣, 🎛 ⚙️ 💊 `Union` & `Optional`, 👆 💪 ⚙️ ⏸ ⏸ (`|`) 📣 🇪🇺 🆎.
+ & 🎏 ⏮️ 🐍 3️⃣.6️⃣, ⚪️➡️ `typing` 🕹:
+
+* `Union`
+* `Optional` (🎏 ⏮️ 🐍 3️⃣.6️⃣)
+* ...& 🎏.
+
+🐍 3️⃣.1️⃣0️⃣, 🎛 ⚙️ 💊 `Union` & `Optional`, 👆 💪 ⚙️ ⏸ ⏸ (`|`) 📣 🇪🇺 🆎.
+
+////
### 🎓 🆎
@@ -409,13 +446,13 @@ say_hi(name=None) # This works, None is valid 🎉
➡️ 💬 👆 ✔️ 🎓 `Person`, ⏮️ 📛:
```Python hl_lines="1-3"
-{!../../../docs_src/python_types/tutorial010.py!}
+{!../../docs_src/python_types/tutorial010.py!}
```
⤴️ 👆 💪 📣 🔢 🆎 `Person`:
```Python hl_lines="6"
-{!../../../docs_src/python_types/tutorial010.py!}
+{!../../docs_src/python_types/tutorial010.py!}
```
& ⤴️, 🔄, 👆 🤚 🌐 👨🎨 🐕🦺:
@@ -436,33 +473,45 @@ say_hi(name=None) # This works, None is valid 🎉
🖼 ⚪️➡️ 🛂 Pydantic 🩺:
-=== "🐍 3️⃣.6️⃣ & 🔛"
+//// tab | 🐍 3️⃣.6️⃣ & 🔛
- ```Python
- {!> ../../../docs_src/python_types/tutorial011.py!}
- ```
+```Python
+{!> ../../docs_src/python_types/tutorial011.py!}
+```
-=== "🐍 3️⃣.9️⃣ & 🔛"
+////
- ```Python
- {!> ../../../docs_src/python_types/tutorial011_py39.py!}
- ```
+//// tab | 🐍 3️⃣.9️⃣ & 🔛
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
+```Python
+{!> ../../docs_src/python_types/tutorial011_py39.py!}
+```
- ```Python
- {!> ../../../docs_src/python_types/tutorial011_py310.py!}
- ```
+////
-!!! info
- 💡 🌖 🔃 Pydantic, ✅ 🚮 🩺.
+//// tab | 🐍 3️⃣.1️⃣0️⃣ & 🔛
+
+```Python
+{!> ../../docs_src/python_types/tutorial011_py310.py!}
+```
+
+////
+
+/// info
+
+💡 🌖 🔃 Pydantic, ✅ 🚮 🩺.
+
+///
**FastAPI** 🌐 ⚓️ 🔛 Pydantic.
👆 🔜 👀 📚 🌅 🌐 👉 💡 [🔰 - 👩💻 🦮](tutorial/index.md){.internal-link target=_blank}.
-!!! tip
- Pydantic ✔️ 🎁 🎭 🕐❔ 👆 ⚙️ `Optional` ⚖️ `Union[Something, None]` 🍵 🔢 💲, 👆 💪 ✍ 🌅 🔃 ⚫️ Pydantic 🩺 🔃 ✔ 📦 🏑.
+/// tip
+
+Pydantic ✔️ 🎁 🎭 🕐❔ 👆 ⚙️ `Optional` ⚖️ `Union[Something, None]` 🍵 🔢 💲, 👆 💪 ✍ 🌅 🔃 ⚫️ Pydantic 🩺 🔃 ✔ 📦 🏑.
+
+///
## 🆎 🔑 **FastAPI**
@@ -486,5 +535,8 @@ say_hi(name=None) # This works, None is valid 🎉
⚠ 👜 👈 ⚙️ 🐩 🐍 🆎, 👁 🥉 (↩️ ❎ 🌖 🎓, 👨🎨, ♒️), **FastAPI** 🔜 📚 👷 👆.
-!!! info
- 🚥 👆 ⏪ 🚶 🔘 🌐 🔰 & 👟 🔙 👀 🌅 🔃 🆎, 👍 ℹ "🎮 🎼" ⚪️➡️ `mypy`.
+/// info
+
+🚥 👆 ⏪ 🚶 🔘 🌐 🔰 & 👟 🔙 👀 🌅 🔃 🆎, 👍 ℹ "🎮 🎼" ⚪️➡️ `mypy`.
+
+///
diff --git a/docs/em/docs/tutorial/background-tasks.md b/docs/em/docs/tutorial/background-tasks.md
index e28ead415..aed60c754 100644
--- a/docs/em/docs/tutorial/background-tasks.md
+++ b/docs/em/docs/tutorial/background-tasks.md
@@ -15,9 +15,7 @@
🥇, 🗄 `BackgroundTasks` & 🔬 🔢 👆 *➡ 🛠️ 🔢* ⏮️ 🆎 📄 `BackgroundTasks`:
-```Python hl_lines="1 13"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *}
**FastAPI** 🔜 ✍ 🎚 🆎 `BackgroundTasks` 👆 & 🚶♀️ ⚫️ 👈 🔢.
@@ -33,17 +31,13 @@
& ✍ 🛠️ 🚫 ⚙️ `async` & `await`, 👥 🔬 🔢 ⏮️ 😐 `def`:
-```Python hl_lines="6-9"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *}
## 🚮 🖥 📋
🔘 👆 *➡ 🛠️ 🔢*, 🚶♀️ 👆 📋 🔢 *🖥 📋* 🎚 ⏮️ 👩🔬 `.add_task()`:
-```Python hl_lines="14"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[14] *}
`.add_task()` 📨 ❌:
@@ -57,17 +51,7 @@
**FastAPI** 💭 ⚫️❔ 🔠 💼 & ❔ 🏤-⚙️ 🎏 🎚, 👈 🌐 🖥 📋 🔗 👯♂️ & 🏃 🖥 ⏮️:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="13 15 22 25"
- {!> ../../../docs_src/background_tasks/tutorial002.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="11 13 20 23"
- {!> ../../../docs_src/background_tasks/tutorial002_py310.py!}
- ```
+{* ../../docs_src/background_tasks/tutorial002.py hl[13,15,22,25] *}
👉 🖼, 📧 🔜 ✍ `log.txt` 📁 *⏮️* 📨 📨.
@@ -93,8 +77,6 @@
👫 😑 🚚 🌖 🏗 📳, 📧/👨🏭 📤 👨💼, 💖 ✳ ⚖️ ✳, ✋️ 👫 ✔ 👆 🏃 🖥 📋 💗 🛠️, & ✴️, 💗 💽.
-👀 🖼, ✅ [🏗 🚂](../project-generation.md){.internal-link target=_blank}, 👫 🌐 🔌 🥒 ⏪ 📶.
-
✋️ 🚥 👆 💪 🔐 🔢 & 🎚 ⚪️➡️ 🎏 **FastAPI** 📱, ⚖️ 👆 💪 🎭 🤪 🖥 📋 (💖 📨 📧 📨), 👆 💪 🎯 ⚙️ `BackgroundTasks`.
## 🌃
diff --git a/docs/em/docs/tutorial/bigger-applications.md b/docs/em/docs/tutorial/bigger-applications.md
index fc9076aa8..78a321ae6 100644
--- a/docs/em/docs/tutorial/bigger-applications.md
+++ b/docs/em/docs/tutorial/bigger-applications.md
@@ -4,8 +4,11 @@
**FastAPI** 🚚 🏪 🧰 📊 👆 🈸 ⏪ 🚧 🌐 💪.
-!!! info
- 🚥 👆 👟 ⚪️➡️ 🏺, 👉 🔜 🌓 🏺 📗.
+/// info
+
+🚥 👆 👟 ⚪️➡️ 🏺, 👉 🔜 🌓 🏺 📗.
+
+///
## 🖼 📁 📊
@@ -26,16 +29,19 @@
│ └── admin.py
```
-!!! tip
- 📤 📚 `__init__.py` 📁: 1️⃣ 🔠 📁 ⚖️ 📁.
+/// tip
- 👉 ⚫️❔ ✔ 🏭 📟 ⚪️➡️ 1️⃣ 📁 🔘 ➕1️⃣.
+📤 📚 `__init__.py` 📁: 1️⃣ 🔠 📁 ⚖️ 📁.
- 🖼, `app/main.py` 👆 💪 ✔️ ⏸ 💖:
+👉 ⚫️❔ ✔ 🏭 📟 ⚪️➡️ 1️⃣ 📁 🔘 ➕1️⃣.
- ```
- from app.routers import items
- ```
+🖼, `app/main.py` 👆 💪 ✔️ ⏸ 💖:
+
+```
+from app.routers import items
+```
+
+///
* `app` 📁 🔌 🌐. & ⚫️ ✔️ 🛁 📁 `app/__init__.py`, ⚫️ "🐍 📦" (🗃 "🐍 🕹"): `app`.
* ⚫️ 🔌 `app/main.py` 📁. ⚫️ 🔘 🐍 📦 (📁 ⏮️ 📁 `__init__.py`), ⚫️ "🕹" 👈 📦: `app.main`.
@@ -46,7 +52,7 @@
* 📤 📁 `app/internal/` ⏮️ ➕1️⃣ 📁 `__init__.py`, ⚫️ ➕1️⃣ "🐍 📦": `app.internal`.
* & 📁 `app/internal/admin.py` ➕1️⃣ 🔁: `app.internal.admin`.
-
+
🎏 📁 📊 ⏮️ 🏤:
@@ -80,7 +86,7 @@
👆 🗄 ⚫️ & ✍ "👐" 🎏 🌌 👆 🔜 ⏮️ 🎓 `FastAPI`:
```Python hl_lines="1 3" title="app/routers/users.py"
-{!../../../docs_src/bigger_applications/app/routers/users.py!}
+{!../../docs_src/bigger_applications/app/routers/users.py!}
```
### *➡ 🛠️* ⏮️ `APIRouter`
@@ -90,7 +96,7 @@
⚙️ ⚫️ 🎏 🌌 👆 🔜 ⚙️ `FastAPI` 🎓:
```Python hl_lines="6 11 16" title="app/routers/users.py"
-{!../../../docs_src/bigger_applications/app/routers/users.py!}
+{!../../docs_src/bigger_applications/app/routers/users.py!}
```
👆 💪 💭 `APIRouter` "🐩 `FastAPI`" 🎓.
@@ -99,8 +105,11 @@
🌐 🎏 `parameters`, `responses`, `dependencies`, `tags`, ♒️.
-!!! tip
- 👉 🖼, 🔢 🤙 `router`, ✋️ 👆 💪 📛 ⚫️ 👐 👆 💚.
+/// tip
+
+👉 🖼, 🔢 🤙 `router`, ✋️ 👆 💪 📛 ⚫️ 👐 👆 💚.
+
+///
👥 🔜 🔌 👉 `APIRouter` 👑 `FastAPI` 📱, ✋️ 🥇, ➡️ ✅ 🔗 & ➕1️⃣ `APIRouter`.
@@ -113,13 +122,16 @@
👥 🔜 🔜 ⚙️ 🙅 🔗 ✍ 🛃 `X-Token` 🎚:
```Python hl_lines="1 4-6" title="app/dependencies.py"
-{!../../../docs_src/bigger_applications/app/dependencies.py!}
+{!../../docs_src/bigger_applications/app/dependencies.py!}
```
-!!! tip
- 👥 ⚙️ 💭 🎚 📉 👉 🖼.
+/// tip
- ✋️ 🎰 💼 👆 🔜 🤚 👍 🏁 ⚙️ 🛠️ [💂♂ 🚙](security/index.md){.internal-link target=_blank}.
+👥 ⚙️ 💭 🎚 📉 👉 🖼.
+
+✋️ 🎰 💼 👆 🔜 🤚 👍 🏁 ⚙️ 🛠️ [💂♂ 🚙](security/index.md){.internal-link target=_blank}.
+
+///
## ➕1️⃣ 🕹 ⏮️ `APIRouter`
@@ -144,7 +156,7 @@
, ↩️ ❎ 🌐 👈 🔠 *➡ 🛠️*, 👥 💪 🚮 ⚫️ `APIRouter`.
```Python hl_lines="5-10 16 21" title="app/routers/items.py"
-{!../../../docs_src/bigger_applications/app/routers/items.py!}
+{!../../docs_src/bigger_applications/app/routers/items.py!}
```
➡ 🔠 *➡ 🛠️* ✔️ ▶️ ⏮️ `/`, 💖:
@@ -163,8 +175,11 @@ async def read_item(item_id: str):
& 👥 💪 🚮 📇 `dependencies` 👈 🔜 🚮 🌐 *➡ 🛠️* 📻 & 🔜 🛠️/❎ 🔠 📨 ⚒ 👫.
-!!! tip
- 🗒 👈, 🌅 💖 [🔗 *➡ 🛠️ 👨🎨*](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, 🙅♂ 💲 🔜 🚶♀️ 👆 *➡ 🛠️ 🔢*.
+/// tip
+
+🗒 👈, 🌅 💖 [🔗 *➡ 🛠️ 👨🎨*](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, 🙅♂ 💲 🔜 🚶♀️ 👆 *➡ 🛠️ 🔢*.
+
+///
🔚 🏁 👈 🏬 ➡ 🔜:
@@ -181,11 +196,17 @@ async def read_item(item_id: str):
* 📻 🔗 🛠️ 🥇, ⤴️ [`dependencies` 👨🎨](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, & ⤴️ 😐 🔢 🔗.
* 👆 💪 🚮 [`Security` 🔗 ⏮️ `scopes`](../advanced/security/oauth2-scopes.md){.internal-link target=_blank}.
-!!! tip
- ✔️ `dependencies` `APIRouter` 💪 ⚙️, 🖼, 🚚 🤝 🎂 👪 *➡ 🛠️*. 🚥 🔗 🚫 🚮 📦 🔠 1️⃣ 👫.
+/// tip
-!!! check
- `prefix`, `tags`, `responses`, & `dependencies` 🔢 (📚 🎏 💼) ⚒ ⚪️➡️ **FastAPI** ℹ 👆 ❎ 📟 ❎.
+✔️ `dependencies` `APIRouter` 💪 ⚙️, 🖼, 🚚 🤝 🎂 👪 *➡ 🛠️*. 🚥 🔗 🚫 🚮 📦 🔠 1️⃣ 👫.
+
+///
+
+/// check
+
+`prefix`, `tags`, `responses`, & `dependencies` 🔢 (📚 🎏 💼) ⚒ ⚪️➡️ **FastAPI** ℹ 👆 ❎ 📟 ❎.
+
+///
### 🗄 🔗
@@ -196,13 +217,16 @@ async def read_item(item_id: str):
👥 ⚙️ ⚖ 🗄 ⏮️ `..` 🔗:
```Python hl_lines="3" title="app/routers/items.py"
-{!../../../docs_src/bigger_applications/app/routers/items.py!}
+{!../../docs_src/bigger_applications/app/routers/items.py!}
```
#### ❔ ⚖ 🗄 👷
-!!! tip
- 🚥 👆 💭 👌 ❔ 🗄 👷, 😣 ⏭ 📄 🔛.
+/// tip
+
+🚥 👆 💭 👌 ❔ 🗄 👷, 😣 ⏭ 📄 🔛.
+
+///
👁 ❣ `.`, 💖:
@@ -220,7 +244,7 @@ from .dependencies import get_token_header
💭 ❔ 👆 📱/📁 📊 👀 💖:
-
+
---
@@ -266,13 +290,16 @@ that 🔜 ⛓:
✋️ 👥 💪 🚮 _🌅_ `tags` 👈 🔜 ✔ 🎯 *➡ 🛠️*, & ➕ `responses` 🎯 👈 *➡ 🛠️*:
```Python hl_lines="30-31" title="app/routers/items.py"
-{!../../../docs_src/bigger_applications/app/routers/items.py!}
+{!../../docs_src/bigger_applications/app/routers/items.py!}
```
-!!! tip
- 👉 🏁 ➡ 🛠️ 🔜 ✔️ 🌀 🔖: `["items", "custom"]`.
+/// tip
- & ⚫️ 🔜 ✔️ 👯♂️ 📨 🧾, 1️⃣ `404` & 1️⃣ `403`.
+👉 🏁 ➡ 🛠️ 🔜 ✔️ 🌀 🔖: `["items", "custom"]`.
+
+ & ⚫️ 🔜 ✔️ 👯♂️ 📨 🧾, 1️⃣ `404` & 1️⃣ `403`.
+
+///
## 👑 `FastAPI`
@@ -291,7 +318,7 @@ that 🔜 ⛓:
& 👥 💪 📣 [🌐 🔗](dependencies/global-dependencies.md){.internal-link target=_blank} 👈 🔜 🌀 ⏮️ 🔗 🔠 `APIRouter`:
```Python hl_lines="1 3 7" title="app/main.py"
-{!../../../docs_src/bigger_applications/app/main.py!}
+{!../../docs_src/bigger_applications/app/main.py!}
```
### 🗄 `APIRouter`
@@ -299,7 +326,7 @@ that 🔜 ⛓:
🔜 👥 🗄 🎏 🔁 👈 ✔️ `APIRouter`Ⓜ:
```Python hl_lines="5" title="app/main.py"
-{!../../../docs_src/bigger_applications/app/main.py!}
+{!../../docs_src/bigger_applications/app/main.py!}
```
📁 `app/routers/users.py` & `app/routers/items.py` 🔁 👈 🍕 🎏 🐍 📦 `app`, 👥 💪 ⚙️ 👁 ❣ `.` 🗄 👫 ⚙️ "⚖ 🗄".
@@ -328,20 +355,23 @@ from .routers import items, users
from app.routers import items, users
```
-!!! info
- 🥇 ⏬ "⚖ 🗄":
+/// info
- ```Python
- from .routers import items, users
- ```
+🥇 ⏬ "⚖ 🗄":
- 🥈 ⏬ "🎆 🗄":
+```Python
+from .routers import items, users
+```
- ```Python
- from app.routers import items, users
- ```
+🥈 ⏬ "🎆 🗄":
- 💡 🌅 🔃 🐍 📦 & 🕹, ✍ 🛂 🐍 🧾 🔃 🕹.
+```Python
+from app.routers import items, users
+```
+
+💡 🌅 🔃 🐍 📦 & 🕹, ✍ 🛂 🐍 🧾 🔃 🕹.
+
+///
### ❎ 📛 💥
@@ -361,7 +391,7 @@ from .routers.users import router
, 💪 ⚙️ 👯♂️ 👫 🎏 📁, 👥 🗄 🔁 🔗:
```Python hl_lines="5" title="app/main.py"
-{!../../../docs_src/bigger_applications/app/main.py!}
+{!../../docs_src/bigger_applications/app/main.py!}
```
### 🔌 `APIRouter`Ⓜ `users` & `items`
@@ -369,29 +399,38 @@ from .routers.users import router
🔜, ➡️ 🔌 `router`Ⓜ ⚪️➡️ 🔁 `users` & `items`:
```Python hl_lines="10-11" title="app/main.py"
-{!../../../docs_src/bigger_applications/app/main.py!}
+{!../../docs_src/bigger_applications/app/main.py!}
```
-!!! info
- `users.router` 🔌 `APIRouter` 🔘 📁 `app/routers/users.py`.
+/// info
- & `items.router` 🔌 `APIRouter` 🔘 📁 `app/routers/items.py`.
+`users.router` 🔌 `APIRouter` 🔘 📁 `app/routers/users.py`.
+
+ & `items.router` 🔌 `APIRouter` 🔘 📁 `app/routers/items.py`.
+
+///
⏮️ `app.include_router()` 👥 💪 🚮 🔠 `APIRouter` 👑 `FastAPI` 🈸.
⚫️ 🔜 🔌 🌐 🛣 ⚪️➡️ 👈 📻 🍕 ⚫️.
-!!! note "📡 ℹ"
- ⚫️ 🔜 🤙 🔘 ✍ *➡ 🛠️* 🔠 *➡ 🛠️* 👈 📣 `APIRouter`.
+/// note | 📡 ℹ
- , ⛅ 🎑, ⚫️ 🔜 🤙 👷 🚥 🌐 🎏 👁 📱.
+⚫️ 🔜 🤙 🔘 ✍ *➡ 🛠️* 🔠 *➡ 🛠️* 👈 📣 `APIRouter`.
-!!! check
- 👆 🚫 ✔️ 😟 🔃 🎭 🕐❔ ✅ 📻.
+, ⛅ 🎑, ⚫️ 🔜 🤙 👷 🚥 🌐 🎏 👁 📱.
- 👉 🔜 ✊ ⏲ & 🔜 🕴 🔨 🕴.
+///
- ⚫️ 🏆 🚫 📉 🎭. 👶
+/// check
+
+👆 🚫 ✔️ 😟 🔃 🎭 🕐❔ ✅ 📻.
+
+👉 🔜 ✊ ⏲ & 🔜 🕴 🔨 🕴.
+
+⚫️ 🏆 🚫 📉 🎭. 👶
+
+///
### 🔌 `APIRouter` ⏮️ 🛃 `prefix`, `tags`, `responses`, & `dependencies`
@@ -402,7 +441,7 @@ from .routers.users import router
👉 🖼 ⚫️ 🔜 💎 🙅. ✋️ ➡️ 💬 👈 ↩️ ⚫️ 💰 ⏮️ 🎏 🏗 🏢, 👥 🚫🔜 🔀 ⚫️ & 🚮 `prefix`, `dependencies`, `tags`, ♒️. 🔗 `APIRouter`:
```Python hl_lines="3" title="app/internal/admin.py"
-{!../../../docs_src/bigger_applications/app/internal/admin.py!}
+{!../../docs_src/bigger_applications/app/internal/admin.py!}
```
✋️ 👥 💚 ⚒ 🛃 `prefix` 🕐❔ ✅ `APIRouter` 👈 🌐 🚮 *➡ 🛠️* ▶️ ⏮️ `/admin`, 👥 💚 🔐 ⚫️ ⏮️ `dependencies` 👥 ⏪ ✔️ 👉 🏗, & 👥 💚 🔌 `tags` & `responses`.
@@ -410,7 +449,7 @@ from .routers.users import router
👥 💪 📣 🌐 👈 🍵 ✔️ 🔀 ⏮️ `APIRouter` 🚶♀️ 👈 🔢 `app.include_router()`:
```Python hl_lines="14-17" title="app/main.py"
-{!../../../docs_src/bigger_applications/app/main.py!}
+{!../../docs_src/bigger_applications/app/main.py!}
```
👈 🌌, ⏮️ `APIRouter` 🔜 🚧 ⚗, 👥 💪 💰 👈 🎏 `app/internal/admin.py` 📁 ⏮️ 🎏 🏗 🏢.
@@ -433,21 +472,24 @@ from .routers.users import router
📥 👥 ⚫️... 🎦 👈 👥 💪 🤷:
```Python hl_lines="21-23" title="app/main.py"
-{!../../../docs_src/bigger_applications/app/main.py!}
+{!../../docs_src/bigger_applications/app/main.py!}
```
& ⚫️ 🔜 👷 ☑, 👯♂️ ⏮️ 🌐 🎏 *➡ 🛠️* 🚮 ⏮️ `app.include_router()`.
-!!! info "📶 📡 ℹ"
- **🗒**: 👉 📶 📡 ℹ 👈 👆 🎲 💪 **🚶**.
+/// info | 📶 📡 ℹ
- ---
+**🗒**: 👉 📶 📡 ℹ 👈 👆 🎲 💪 **🚶**.
- `APIRouter`Ⓜ 🚫 "🗻", 👫 🚫 👽 ⚪️➡️ 🎂 🈸.
+---
- 👉 ↩️ 👥 💚 🔌 👫 *➡ 🛠️* 🗄 🔗 & 👩💻 🔢.
+ `APIRouter`Ⓜ 🚫 "🗻", 👫 🚫 👽 ⚪️➡️ 🎂 🈸.
- 👥 🚫🔜 ❎ 👫 & "🗻" 👫 ➡ 🎂, *➡ 🛠️* "🖖" (🏤-✍), 🚫 🔌 🔗.
+👉 ↩️ 👥 💚 🔌 👫 *➡ 🛠️* 🗄 🔗 & 👩💻 🔢.
+
+👥 🚫🔜 ❎ 👫 & "🗻" 👫 ➡ 🎂, *➡ 🛠️* "🖖" (🏤-✍), 🚫 🔌 🔗.
+
+///
## ✅ 🏧 🛠️ 🩺
diff --git a/docs/em/docs/tutorial/body-fields.md b/docs/em/docs/tutorial/body-fields.md
index 9f2c914f4..f202284b5 100644
--- a/docs/em/docs/tutorial/body-fields.md
+++ b/docs/em/docs/tutorial/body-fields.md
@@ -6,50 +6,39 @@
🥇, 👆 ✔️ 🗄 ⚫️:
-=== "🐍 3️⃣.6️⃣ & 🔛"
+{* ../../docs_src/body_fields/tutorial001.py hl[4] *}
- ```Python hl_lines="4"
- {!> ../../../docs_src/body_fields/tutorial001.py!}
- ```
+/// warning
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
+👀 👈 `Field` 🗄 🔗 ⚪️➡️ `pydantic`, 🚫 ⚪️➡️ `fastapi` 🌐 🎂 (`Query`, `Path`, `Body`, ♒️).
- ```Python hl_lines="2"
- {!> ../../../docs_src/body_fields/tutorial001_py310.py!}
- ```
-
-!!! warning
- 👀 👈 `Field` 🗄 🔗 ⚪️➡️ `pydantic`, 🚫 ⚪️➡️ `fastapi` 🌐 🎂 (`Query`, `Path`, `Body`, ♒️).
+///
## 📣 🏷 🔢
👆 💪 ⤴️ ⚙️ `Field` ⏮️ 🏷 🔢:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="11-14"
- {!> ../../../docs_src/body_fields/tutorial001.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="9-12"
- {!> ../../../docs_src/body_fields/tutorial001_py310.py!}
- ```
+{* ../../docs_src/body_fields/tutorial001.py hl[11:14] *}
`Field` 👷 🎏 🌌 `Query`, `Path` & `Body`, ⚫️ ✔️ 🌐 🎏 🔢, ♒️.
-!!! note "📡 ℹ"
- 🤙, `Query`, `Path` & 🎏 👆 🔜 👀 ⏭ ✍ 🎚 🏿 ⚠ `Param` 🎓, ❔ ⚫️ 🏿 Pydantic `FieldInfo` 🎓.
+/// note | 📡 ℹ
- & Pydantic `Field` 📨 👐 `FieldInfo` 👍.
+🤙, `Query`, `Path` & 🎏 👆 🔜 👀 ⏭ ✍ 🎚 🏿 ⚠ `Param` 🎓, ❔ ⚫️ 🏿 Pydantic `FieldInfo` 🎓.
- `Body` 📨 🎚 🏿 `FieldInfo` 🔗. & 📤 🎏 👆 🔜 👀 ⏪ 👈 🏿 `Body` 🎓.
+ & Pydantic `Field` 📨 👐 `FieldInfo` 👍.
- 💭 👈 🕐❔ 👆 🗄 `Query`, `Path`, & 🎏 ⚪️➡️ `fastapi`, 👈 🤙 🔢 👈 📨 🎁 🎓.
+`Body` 📨 🎚 🏿 `FieldInfo` 🔗. & 📤 🎏 👆 🔜 👀 ⏪ 👈 🏿 `Body` 🎓.
-!!! tip
- 👀 ❔ 🔠 🏷 🔢 ⏮️ 🆎, 🔢 💲 & `Field` ✔️ 🎏 📊 *➡ 🛠️ 🔢* 🔢, ⏮️ `Field` ↩️ `Path`, `Query` & `Body`.
+💭 👈 🕐❔ 👆 🗄 `Query`, `Path`, & 🎏 ⚪️➡️ `fastapi`, 👈 🤙 🔢 👈 📨 🎁 🎓.
+
+///
+
+/// tip
+
+👀 ❔ 🔠 🏷 🔢 ⏮️ 🆎, 🔢 💲 & `Field` ✔️ 🎏 📊 *➡ 🛠️ 🔢* 🔢, ⏮️ `Field` ↩️ `Path`, `Query` & `Body`.
+
+///
## 🚮 ➕ ℹ
@@ -57,9 +46,12 @@
👆 🔜 💡 🌅 🔃 ❎ ➕ ℹ ⏪ 🩺, 🕐❔ 🏫 📣 🖼.
-!!! warning
- ➕ 🔑 🚶♀️ `Field` 🔜 🎁 📉 🗄 🔗 👆 🈸.
- 👫 🔑 5️⃣📆 🚫 🎯 🍕 🗄 🔧, 🗄 🧰, 🖼 [🗄 💳](https://validator.swagger.io/), 5️⃣📆 🚫 👷 ⏮️ 👆 🏗 🔗.
+/// warning
+
+➕ 🔑 🚶♀️ `Field` 🔜 🎁 📉 🗄 🔗 👆 🈸.
+👫 🔑 5️⃣📆 🚫 🎯 🍕 🗄 🔧, 🗄 🧰, 🖼 [🗄 💳](https://validator.swagger.io/), 5️⃣📆 🚫 👷 ⏮️ 👆 🏗 🔗.
+
+///
## 🌃
diff --git a/docs/em/docs/tutorial/body-multiple-params.md b/docs/em/docs/tutorial/body-multiple-params.md
index 9ada7dee1..3a2f2bd54 100644
--- a/docs/em/docs/tutorial/body-multiple-params.md
+++ b/docs/em/docs/tutorial/body-multiple-params.md
@@ -8,20 +8,13 @@
& 👆 💪 📣 💪 🔢 📦, ⚒ 🔢 `None`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
+{* ../../docs_src/body_multiple_params/tutorial001.py hl[19:21] *}
- ```Python hl_lines="19-21"
- {!> ../../../docs_src/body_multiple_params/tutorial001.py!}
- ```
+/// note
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
+👀 👈, 👉 💼, `item` 👈 🔜 ✊ ⚪️➡️ 💪 📦. ⚫️ ✔️ `None` 🔢 💲.
- ```Python hl_lines="17-19"
- {!> ../../../docs_src/body_multiple_params/tutorial001_py310.py!}
- ```
-
-!!! note
- 👀 👈, 👉 💼, `item` 👈 🔜 ✊ ⚪️➡️ 💪 📦. ⚫️ ✔️ `None` 🔢 💲.
+///
## 💗 💪 🔢
@@ -38,17 +31,7 @@
✋️ 👆 💪 📣 💗 💪 🔢, ✅ `item` & `user`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/body_multiple_params/tutorial002.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_multiple_params/tutorial002_py310.py!}
- ```
+{* ../../docs_src/body_multiple_params/tutorial002.py hl[22] *}
👉 💼, **FastAPI** 🔜 👀 👈 📤 🌅 🌘 1️⃣ 💪 🔢 🔢 (2️⃣ 🔢 👈 Pydantic 🏷).
@@ -69,9 +52,11 @@
}
```
-!!! note
- 👀 👈 ✋️ `item` 📣 🎏 🌌 ⏭, ⚫️ 🔜 ⌛ 🔘 💪 ⏮️ 🔑 `item`.
+/// note
+👀 👈 ✋️ `item` 📣 🎏 🌌 ⏭, ⚫️ 🔜 ⌛ 🔘 💪 ⏮️ 🔑 `item`.
+
+///
**FastAPI** 🔜 🏧 🛠️ ⚪️➡️ 📨, 👈 🔢 `item` 📨 ⚫️ 🎯 🎚 & 🎏 `user`.
@@ -87,17 +72,7 @@
✋️ 👆 💪 💡 **FastAPI** 😥 ⚫️ ➕1️⃣ 💪 🔑 ⚙️ `Body`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/body_multiple_params/tutorial003.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_multiple_params/tutorial003_py310.py!}
- ```
+{* ../../docs_src/body_multiple_params/tutorial003.py hl[22] *}
👉 💼, **FastAPI** 🔜 ⌛ 💪 💖:
@@ -137,20 +112,13 @@ q: str | None = None
🖼:
-=== "🐍 3️⃣.6️⃣ & 🔛"
+{* ../../docs_src/body_multiple_params/tutorial004.py hl[27] *}
- ```Python hl_lines="27"
- {!> ../../../docs_src/body_multiple_params/tutorial004.py!}
- ```
+/// info
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
+`Body` ✔️ 🌐 🎏 ➕ 🔬 & 🗃 🔢 `Query`,`Path` & 🎏 👆 🔜 👀 ⏪.
- ```Python hl_lines="26"
- {!> ../../../docs_src/body_multiple_params/tutorial004_py310.py!}
- ```
-
-!!! info
- `Body` ✔️ 🌐 🎏 ➕ 🔬 & 🗃 🔢 `Query`,`Path` & 🎏 👆 🔜 👀 ⏪.
+///
## ⏯ 👁 💪 🔢
@@ -166,17 +134,7 @@ item: Item = Body(embed=True)
:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="17"
- {!> ../../../docs_src/body_multiple_params/tutorial005.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="15"
- {!> ../../../docs_src/body_multiple_params/tutorial005_py310.py!}
- ```
+{* ../../docs_src/body_multiple_params/tutorial005.py hl[17] *}
👉 💼 **FastAPI** 🔜 ⌛ 💪 💖:
diff --git a/docs/em/docs/tutorial/body-nested-models.md b/docs/em/docs/tutorial/body-nested-models.md
index c941fa08a..6c8d5a610 100644
--- a/docs/em/docs/tutorial/body-nested-models.md
+++ b/docs/em/docs/tutorial/body-nested-models.md
@@ -6,17 +6,7 @@
👆 💪 🔬 🔢 🏾. 🖼, 🐍 `list`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="14"
- {!> ../../../docs_src/body_nested_models/tutorial001.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/body_nested_models/tutorial001_py310.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial001.py hl[14] *}
👉 🔜 ⚒ `tags` 📇, 👐 ⚫️ 🚫 📣 🆎 🔣 📇.
@@ -30,9 +20,7 @@
✋️ 🐍 ⏬ ⏭ 3️⃣.9️⃣ (3️⃣.6️⃣ & 🔛), 👆 🥇 💪 🗄 `List` ⚪️➡️ 🐩 🐍 `typing` 🕹:
-```Python hl_lines="1"
-{!> ../../../docs_src/body_nested_models/tutorial002.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *}
### 📣 `list` ⏮️ 🆎 🔢
@@ -61,23 +49,7 @@ my_list: List[str]
, 👆 🖼, 👥 💪 ⚒ `tags` 🎯 "📇 🎻":
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="14"
- {!> ../../../docs_src/body_nested_models/tutorial002.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="14"
- {!> ../../../docs_src/body_nested_models/tutorial002_py39.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/body_nested_models/tutorial002_py310.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial002.py hl[14] *}
## ⚒ 🆎
@@ -87,23 +59,7 @@ my_list: List[str]
⤴️ 👥 💪 📣 `tags` ⚒ 🎻:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="1 14"
- {!> ../../../docs_src/body_nested_models/tutorial003.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="14"
- {!> ../../../docs_src/body_nested_models/tutorial003_py39.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/body_nested_models/tutorial003_py310.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial003.py hl[1,14] *}
⏮️ 👉, 🚥 👆 📨 📨 ⏮️ ❎ 📊, ⚫️ 🔜 🗜 ⚒ 😍 🏬.
@@ -125,45 +81,13 @@ my_list: List[str]
🖼, 👥 💪 🔬 `Image` 🏷:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="9-11"
- {!> ../../../docs_src/body_nested_models/tutorial004.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="9-11"
- {!> ../../../docs_src/body_nested_models/tutorial004_py39.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="7-9"
- {!> ../../../docs_src/body_nested_models/tutorial004_py310.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial004.py hl[9:11] *}
### ⚙️ 📊 🆎
& ⤴️ 👥 💪 ⚙️ ⚫️ 🆎 🔢:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_nested_models/tutorial004.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_nested_models/tutorial004_py39.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body_nested_models/tutorial004_py310.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial004.py hl[20] *}
👉 🔜 ⛓ 👈 **FastAPI** 🔜 ⌛ 💪 🎏:
@@ -196,23 +120,7 @@ my_list: List[str]
🖼, `Image` 🏷 👥 ✔️ `url` 🏑, 👥 💪 📣 ⚫️ ↩️ `str`, Pydantic `HttpUrl`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="4 10"
- {!> ../../../docs_src/body_nested_models/tutorial005.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="4 10"
- {!> ../../../docs_src/body_nested_models/tutorial005_py39.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="2 8"
- {!> ../../../docs_src/body_nested_models/tutorial005_py310.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial005.py hl[4,10] *}
🎻 🔜 ✅ ☑ 📛, & 📄 🎻 🔗 / 🗄 ✅.
@@ -220,23 +128,7 @@ my_list: List[str]
👆 💪 ⚙️ Pydantic 🏷 🏾 `list`, `set`, ♒️:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_nested_models/tutorial006.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_nested_models/tutorial006_py39.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body_nested_models/tutorial006_py310.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial006.py hl[20] *}
👉 🔜 ⌛ (🗜, ✔, 📄, ♒️) 🎻 💪 💖:
@@ -264,33 +156,23 @@ my_list: List[str]
}
```
-!!! info
- 👀 ❔ `images` 🔑 🔜 ✔️ 📇 🖼 🎚.
+/// info
+
+👀 ❔ `images` 🔑 🔜 ✔️ 📇 🖼 🎚.
+
+///
## 🙇 🐦 🏷
👆 💪 🔬 🎲 🙇 🐦 🏷:
-=== "🐍 3️⃣.6️⃣ & 🔛"
+{* ../../docs_src/body_nested_models/tutorial007.py hl[9,14,20,23,27] *}
- ```Python hl_lines="9 14 20 23 27"
- {!> ../../../docs_src/body_nested_models/tutorial007.py!}
- ```
+/// info
-=== "🐍 3️⃣.9️⃣ & 🔛"
+👀 ❔ `Offer` ✔️ 📇 `Item`Ⓜ, ❔ 🔄 ✔️ 📦 📇 `Image`Ⓜ
- ```Python hl_lines="9 14 20 23 27"
- {!> ../../../docs_src/body_nested_models/tutorial007_py39.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="7 12 18 21 25"
- {!> ../../../docs_src/body_nested_models/tutorial007_py310.py!}
- ```
-
-!!! info
- 👀 ❔ `Offer` ✔️ 📇 `Item`Ⓜ, ❔ 🔄 ✔️ 📦 📇 `Image`Ⓜ
+///
## 💪 😁 📇
@@ -308,17 +190,7 @@ images: list[Image]
:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="15"
- {!> ../../../docs_src/body_nested_models/tutorial008.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="13"
- {!> ../../../docs_src/body_nested_models/tutorial008_py39.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial008.py hl[15] *}
## 👨🎨 🐕🦺 🌐
@@ -348,26 +220,19 @@ images: list[Image]
👉 💼, 👆 🔜 🚫 🙆 `dict` 📏 ⚫️ ✔️ `int` 🔑 ⏮️ `float` 💲:
-=== "🐍 3️⃣.6️⃣ & 🔛"
+{* ../../docs_src/body_nested_models/tutorial009.py hl[9] *}
- ```Python hl_lines="9"
- {!> ../../../docs_src/body_nested_models/tutorial009.py!}
- ```
+/// tip
-=== "🐍 3️⃣.9️⃣ & 🔛"
+✔️ 🤯 👈 🎻 🕴 🐕🦺 `str` 🔑.
- ```Python hl_lines="7"
- {!> ../../../docs_src/body_nested_models/tutorial009_py39.py!}
- ```
+✋️ Pydantic ✔️ 🏧 💽 🛠️.
-!!! tip
- ✔️ 🤯 👈 🎻 🕴 🐕🦺 `str` 🔑.
+👉 ⛓ 👈, ✋️ 👆 🛠️ 👩💻 💪 🕴 📨 🎻 🔑, 📏 👈 🎻 🔌 😁 🔢, Pydantic 🔜 🗜 👫 & ✔ 👫.
- ✋️ Pydantic ✔️ 🏧 💽 🛠️.
+ & `dict` 👆 📨 `weights` 🔜 🤙 ✔️ `int` 🔑 & `float` 💲.
- 👉 ⛓ 👈, ✋️ 👆 🛠️ 👩💻 💪 🕴 📨 🎻 🔑, 📏 👈 🎻 🔌 😁 🔢, Pydantic 🔜 🗜 👫 & ✔ 👫.
-
- & `dict` 👆 📨 `weights` 🔜 🤙 ✔️ `int` 🔑 & `float` 💲.
+///
## 🌃
diff --git a/docs/em/docs/tutorial/body-updates.md b/docs/em/docs/tutorial/body-updates.md
index 89bb615f6..7e2fbfaf7 100644
--- a/docs/em/docs/tutorial/body-updates.md
+++ b/docs/em/docs/tutorial/body-updates.md
@@ -6,23 +6,7 @@
👆 💪 ⚙️ `jsonable_encoder` 🗜 🔢 💽 📊 👈 💪 🏪 🎻 (✅ ⏮️ ☁ 💽). 🖼, 🏭 `datetime` `str`.
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="30-35"
- {!> ../../../docs_src/body_updates/tutorial001.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="30-35"
- {!> ../../../docs_src/body_updates/tutorial001_py39.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="28-33"
- {!> ../../../docs_src/body_updates/tutorial001_py310.py!}
- ```
+{* ../../docs_src/body_updates/tutorial001.py hl[30:35] *}
`PUT` ⚙️ 📨 💽 👈 🔜 ❎ ♻ 💽.
@@ -48,14 +32,17 @@
👉 ⛓ 👈 👆 💪 📨 🕴 💽 👈 👆 💚 ℹ, 🍂 🎂 🐣.
-!!! note
- `PATCH` 🌘 🛎 ⚙️ & 💭 🌘 `PUT`.
+/// note
- & 📚 🏉 ⚙️ 🕴 `PUT`, 🍕 ℹ.
+`PATCH` 🌘 🛎 ⚙️ & 💭 🌘 `PUT`.
- 👆 **🆓** ⚙️ 👫 👐 👆 💚, **FastAPI** 🚫 🚫 🙆 🚫.
+ & 📚 🏉 ⚙️ 🕴 `PUT`, 🍕 ℹ.
- ✋️ 👉 🦮 🎦 👆, 🌖 ⚖️ 🌘, ❔ 👫 🎯 ⚙️.
+👆 **🆓** ⚙️ 👫 👐 👆 💚, **FastAPI** 🚫 🚫 🙆 🚫.
+
+✋️ 👉 🦮 🎦 👆, 🌖 ⚖️ 🌘, ❔ 👫 🎯 ⚙️.
+
+///
### ⚙️ Pydantic `exclude_unset` 🔢
@@ -67,23 +54,7 @@
⤴️ 👆 💪 ⚙️ 👉 🏗 `dict` ⏮️ 🕴 💽 👈 ⚒ (📨 📨), 🚫 🔢 💲:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="34"
- {!> ../../../docs_src/body_updates/tutorial002.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="34"
- {!> ../../../docs_src/body_updates/tutorial002_py39.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="32"
- {!> ../../../docs_src/body_updates/tutorial002_py310.py!}
- ```
+{* ../../docs_src/body_updates/tutorial002.py hl[34] *}
### ⚙️ Pydantic `update` 🔢
@@ -91,23 +62,7 @@
💖 `stored_item_model.copy(update=update_data)`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="35"
- {!> ../../../docs_src/body_updates/tutorial002.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="35"
- {!> ../../../docs_src/body_updates/tutorial002_py39.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="33"
- {!> ../../../docs_src/body_updates/tutorial002_py310.py!}
- ```
+{* ../../docs_src/body_updates/tutorial002.py hl[35] *}
### 🍕 ℹ 🌃
@@ -124,32 +79,22 @@
* 🖊 💽 👆 💽.
* 📨 ℹ 🏷.
-=== "🐍 3️⃣.6️⃣ & 🔛"
+{* ../../docs_src/body_updates/tutorial002.py hl[30:37] *}
- ```Python hl_lines="30-37"
- {!> ../../../docs_src/body_updates/tutorial002.py!}
- ```
+/// tip
-=== "🐍 3️⃣.9️⃣ & 🔛"
+👆 💪 🤙 ⚙️ 👉 🎏 ⚒ ⏮️ 🇺🇸🔍 `PUT` 🛠️.
- ```Python hl_lines="30-37"
- {!> ../../../docs_src/body_updates/tutorial002_py39.py!}
- ```
+✋️ 🖼 📥 ⚙️ `PATCH` ↩️ ⚫️ ✍ 👫 ⚙️ 💼.
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
+///
- ```Python hl_lines="28-35"
- {!> ../../../docs_src/body_updates/tutorial002_py310.py!}
- ```
+/// note
-!!! tip
- 👆 💪 🤙 ⚙️ 👉 🎏 ⚒ ⏮️ 🇺🇸🔍 `PUT` 🛠️.
+👀 👈 🔢 🏷 ✔.
- ✋️ 🖼 📥 ⚙️ `PATCH` ↩️ ⚫️ ✍ 👫 ⚙️ 💼.
+, 🚥 👆 💚 📨 🍕 ℹ 👈 💪 🚫 🌐 🔢, 👆 💪 ✔️ 🏷 ⏮️ 🌐 🔢 ™ 📦 (⏮️ 🔢 💲 ⚖️ `None`).
-!!! note
- 👀 👈 🔢 🏷 ✔.
+🔬 ⚪️➡️ 🏷 ⏮️ 🌐 📦 💲 **ℹ** & 🏷 ⏮️ ✔ 💲 **🏗**, 👆 💪 ⚙️ 💭 🔬 [➕ 🏷](extra-models.md){.internal-link target=_blank}.
- , 🚥 👆 💚 📨 🍕 ℹ 👈 💪 🚫 🌐 🔢, 👆 💪 ✔️ 🏷 ⏮️ 🌐 🔢 ™ 📦 (⏮️ 🔢 💲 ⚖️ `None`).
-
- 🔬 ⚪️➡️ 🏷 ⏮️ 🌐 📦 💲 **ℹ** & 🏷 ⏮️ ✔ 💲 **🏗**, 👆 💪 ⚙️ 💭 🔬 [➕ 🏷](extra-models.md){.internal-link target=_blank}.
+///
diff --git a/docs/em/docs/tutorial/body.md b/docs/em/docs/tutorial/body.md
index 12f5a6315..09e1d7cca 100644
--- a/docs/em/docs/tutorial/body.md
+++ b/docs/em/docs/tutorial/body.md
@@ -8,28 +8,21 @@
📣 **📨** 💪, 👆 ⚙️ Pydantic 🏷 ⏮️ 🌐 👫 🏋️ & 💰.
-!!! info
- 📨 💽, 👆 🔜 ⚙️ 1️⃣: `POST` (🌅 ⚠), `PUT`, `DELETE` ⚖️ `PATCH`.
+/// info
- 📨 💪 ⏮️ `GET` 📨 ✔️ ⚠ 🎭 🔧, 👐, ⚫️ 🐕🦺 FastAPI, 🕴 📶 🏗/😕 ⚙️ 💼.
+📨 💽, 👆 🔜 ⚙️ 1️⃣: `POST` (🌅 ⚠), `PUT`, `DELETE` ⚖️ `PATCH`.
- ⚫️ 🚫, 🎓 🩺 ⏮️ 🦁 🎚 🏆 🚫 🎦 🧾 💪 🕐❔ ⚙️ `GET`, & 🗳 🖕 💪 🚫 🐕🦺 ⚫️.
+📨 💪 ⏮️ `GET` 📨 ✔️ ⚠ 🎭 🔧, 👐, ⚫️ 🐕🦺 FastAPI, 🕴 📶 🏗/😕 ⚙️ 💼.
+
+⚫️ 🚫, 🎓 🩺 ⏮️ 🦁 🎚 🏆 🚫 🎦 🧾 💪 🕐❔ ⚙️ `GET`, & 🗳 🖕 💪 🚫 🐕🦺 ⚫️.
+
+///
## 🗄 Pydantic `BaseModel`
🥇, 👆 💪 🗄 `BaseModel` ⚪️➡️ `pydantic`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="4"
- {!> ../../../docs_src/body/tutorial001.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="2"
- {!> ../../../docs_src/body/tutorial001_py310.py!}
- ```
+{* ../../docs_src/body/tutorial001.py hl[4] *}
## ✍ 👆 💽 🏷
@@ -37,17 +30,7 @@
⚙️ 🐩 🐍 🆎 🌐 🔢:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="7-11"
- {!> ../../../docs_src/body/tutorial001.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="5-9"
- {!> ../../../docs_src/body/tutorial001_py310.py!}
- ```
+{* ../../docs_src/body/tutorial001.py hl[7:11] *}
🎏 🕐❔ 📣 🔢 🔢, 🕐❔ 🏷 🔢 ✔️ 🔢 💲, ⚫️ 🚫 ✔. ⏪, ⚫️ ✔. ⚙️ `None` ⚒ ⚫️ 📦.
@@ -75,17 +58,7 @@
🚮 ⚫️ 👆 *➡ 🛠️*, 📣 ⚫️ 🎏 🌌 👆 📣 ➡ & 🔢 🔢:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body/tutorial001.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="16"
- {!> ../../../docs_src/body/tutorial001_py310.py!}
- ```
+{* ../../docs_src/body/tutorial001.py hl[18] *}
...& 📣 🚮 🆎 🏷 👆 ✍, `Item`.
@@ -134,32 +107,25 @@
-!!! tip
- 🚥 👆 ⚙️ 🗒 👆 👨🎨, 👆 💪 ⚙️ Pydantic 🗒 📁.
+/// tip
- ⚫️ 📉 👨🎨 🐕🦺 Pydantic 🏷, ⏮️:
+🚥 👆 ⚙️ 🗒 👆 👨🎨, 👆 💪 ⚙️ Pydantic 🗒 📁.
- * 🚘-🛠️
- * 🆎 ✅
- * 🛠️
- * 🔎
- * 🔬
+⚫️ 📉 👨🎨 🐕🦺 Pydantic 🏷, ⏮️:
+
+* 🚘-🛠️
+* 🆎 ✅
+* 🛠️
+* 🔎
+* 🔬
+
+///
## ⚙️ 🏷
🔘 🔢, 👆 💪 🔐 🌐 🔢 🏷 🎚 🔗:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="21"
- {!> ../../../docs_src/body/tutorial002.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="19"
- {!> ../../../docs_src/body/tutorial002_py310.py!}
- ```
+{* ../../docs_src/body/tutorial002.py hl[21] *}
## 📨 💪 ➕ ➡ 🔢
@@ -167,17 +133,7 @@
**FastAPI** 🔜 🤔 👈 🔢 🔢 👈 🏏 ➡ 🔢 🔜 **✊ ⚪️➡️ ➡**, & 👈 🔢 🔢 👈 📣 Pydantic 🏷 🔜 **✊ ⚪️➡️ 📨 💪**.
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="17-18"
- {!> ../../../docs_src/body/tutorial003.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="15-16"
- {!> ../../../docs_src/body/tutorial003_py310.py!}
- ```
+{* ../../docs_src/body/tutorial003.py hl[17:18] *}
## 📨 💪 ➕ ➡ ➕ 🔢 🔢
@@ -185,17 +141,7 @@
**FastAPI** 🔜 🤔 🔠 👫 & ✊ 📊 ⚪️➡️ ☑ 🥉.
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body/tutorial004.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="16"
- {!> ../../../docs_src/body/tutorial004_py310.py!}
- ```
+{* ../../docs_src/body/tutorial004.py hl[18] *}
🔢 🔢 🔜 🤔 ⏩:
@@ -203,10 +149,13 @@
* 🚥 🔢 **⭐ 🆎** (💖 `int`, `float`, `str`, `bool`, ♒️) ⚫️ 🔜 🔬 **🔢** 🔢.
* 🚥 🔢 📣 🆎 **Pydantic 🏷**, ⚫️ 🔜 🔬 📨 **💪**.
-!!! note
- FastAPI 🔜 💭 👈 💲 `q` 🚫 ✔ ↩️ 🔢 💲 `= None`.
+/// note
- `Union` `Union[str, None]` 🚫 ⚙️ FastAPI, ✋️ 🔜 ✔ 👆 👨🎨 🤝 👆 👍 🐕🦺 & 🔍 ❌.
+FastAPI 🔜 💭 👈 💲 `q` 🚫 ✔ ↩️ 🔢 💲 `= None`.
+
+ `Union` `Union[str, None]` 🚫 ⚙️ FastAPI, ✋️ 🔜 ✔ 👆 👨🎨 🤝 👆 👍 🐕🦺 & 🔍 ❌.
+
+///
## 🍵 Pydantic
diff --git a/docs/em/docs/tutorial/cookie-params.md b/docs/em/docs/tutorial/cookie-params.md
index 47f4a62f5..4699fe2a5 100644
--- a/docs/em/docs/tutorial/cookie-params.md
+++ b/docs/em/docs/tutorial/cookie-params.md
@@ -6,17 +6,7 @@
🥇 🗄 `Cookie`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="3"
- {!> ../../../docs_src/cookie_params/tutorial001.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="1"
- {!> ../../../docs_src/cookie_params/tutorial001_py310.py!}
- ```
+{* ../../docs_src/cookie_params/tutorial001.py hl[3] *}
## 📣 `Cookie` 🔢
@@ -24,25 +14,21 @@
🥇 💲 🔢 💲, 👆 💪 🚶♀️ 🌐 ➕ 🔬 ⚖️ ✍ 🔢:
-=== "🐍 3️⃣.6️⃣ & 🔛"
+{* ../../docs_src/cookie_params/tutorial001.py hl[9] *}
- ```Python hl_lines="9"
- {!> ../../../docs_src/cookie_params/tutorial001.py!}
- ```
+/// note | 📡 ℹ
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
+`Cookie` "👭" 🎓 `Path` & `Query`. ⚫️ 😖 ⚪️➡️ 🎏 ⚠ `Param` 🎓.
- ```Python hl_lines="7"
- {!> ../../../docs_src/cookie_params/tutorial001_py310.py!}
- ```
+✋️ 💭 👈 🕐❔ 👆 🗄 `Query`, `Path`, `Cookie` & 🎏 ⚪️➡️ `fastapi`, 👈 🤙 🔢 👈 📨 🎁 🎓.
-!!! note "📡 ℹ"
- `Cookie` "👭" 🎓 `Path` & `Query`. ⚫️ 😖 ⚪️➡️ 🎏 ⚠ `Param` 🎓.
+///
- ✋️ 💭 👈 🕐❔ 👆 🗄 `Query`, `Path`, `Cookie` & 🎏 ⚪️➡️ `fastapi`, 👈 🤙 🔢 👈 📨 🎁 🎓.
+/// info
-!!! info
- 📣 🍪, 👆 💪 ⚙️ `Cookie`, ↩️ ⏪ 🔢 🔜 🔬 🔢 🔢.
+📣 🍪, 👆 💪 ⚙️ `Cookie`, ↩️ ⏪ 🔢 🔜 🔬 🔢 🔢.
+
+///
## 🌃
diff --git a/docs/em/docs/tutorial/cors.md b/docs/em/docs/tutorial/cors.md
index 8c5e33ed7..44ab4adc5 100644
--- a/docs/em/docs/tutorial/cors.md
+++ b/docs/em/docs/tutorial/cors.md
@@ -46,9 +46,7 @@
* 🎯 🇺🇸🔍 👩🔬 (`POST`, `PUT`) ⚖️ 🌐 👫 ⏮️ 🃏 `"*"`.
* 🎯 🇺🇸🔍 🎚 ⚖️ 🌐 👫 ⏮️ 🃏 `"*"`.
-```Python hl_lines="2 6-11 13-19"
-{!../../../docs_src/cors/tutorial001.py!}
-```
+{* ../../docs_src/cors/tutorial001.py hl[2,6:11,13:19] *}
🔢 🔢 ⚙️ `CORSMiddleware` 🛠️ 🚫 🔢, 👆 🔜 💪 🎯 🛠️ 🎯 🇨🇳, 👩🔬, ⚖️ 🎚, ✔ 🖥 ✔ ⚙️ 👫 ✖️-🆔 🔑.
@@ -78,7 +76,10 @@
🌖 ℹ 🔃 ⚜, ✅ 🦎 ⚜ 🧾.
-!!! note "📡 ℹ"
- 👆 💪 ⚙️ `from starlette.middleware.cors import CORSMiddleware`.
+/// note | 📡 ℹ
- **FastAPI** 🚚 📚 🛠️ `fastapi.middleware` 🏪 👆, 👩💻. ✋️ 🌅 💪 🛠️ 👟 🔗 ⚪️➡️ 💃.
+👆 💪 ⚙️ `from starlette.middleware.cors import CORSMiddleware`.
+
+**FastAPI** 🚚 📚 🛠️ `fastapi.middleware` 🏪 👆, 👩💻. ✋️ 🌅 💪 🛠️ 👟 🔗 ⚪️➡️ 💃.
+
+///
diff --git a/docs/em/docs/tutorial/debugging.md b/docs/em/docs/tutorial/debugging.md
index c7c11b5ce..97e61a763 100644
--- a/docs/em/docs/tutorial/debugging.md
+++ b/docs/em/docs/tutorial/debugging.md
@@ -6,9 +6,7 @@
👆 FastAPI 🈸, 🗄 & 🏃 `uvicorn` 🔗:
-```Python hl_lines="1 15"
-{!../../../docs_src/debugging/tutorial001.py!}
-```
+{* ../../docs_src/debugging/tutorial001.py hl[1,15] *}
### 🔃 `__name__ == "__main__"`
@@ -74,8 +72,11 @@ from myapp import app
🔜 🚫 🛠️.
-!!! info
- 🌅 ℹ, ✅ 🛂 🐍 🩺.
+/// info
+
+🌅 ℹ, ✅ 🛂 🐍 🩺.
+
+///
## 🏃 👆 📟 ⏮️ 👆 🕹
diff --git a/docs/em/docs/tutorial/dependencies/classes-as-dependencies.md b/docs/em/docs/tutorial/dependencies/classes-as-dependencies.md
index e2d2686d3..41938bc7b 100644
--- a/docs/em/docs/tutorial/dependencies/classes-as-dependencies.md
+++ b/docs/em/docs/tutorial/dependencies/classes-as-dependencies.md
@@ -6,17 +6,7 @@
⏮️ 🖼, 👥 🛬 `dict` ⚪️➡️ 👆 🔗 ("☑"):
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/dependencies/tutorial001.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/dependencies/tutorial001_py310.py!}
- ```
+{* ../../docs_src/dependencies/tutorial001.py hl[9] *}
✋️ ⤴️ 👥 🤚 `dict` 🔢 `commons` *➡ 🛠️ 🔢*.
@@ -79,45 +69,15 @@ fluffy = Cat(name="Mr Fluffy")
⤴️, 👥 💪 🔀 🔗 "☑" `common_parameters` ⚪️➡️ 🔛 🎓 `CommonQueryParams`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="11-15"
- {!> ../../../docs_src/dependencies/tutorial002.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="9-13"
- {!> ../../../docs_src/dependencies/tutorial002_py310.py!}
- ```
+{* ../../docs_src/dependencies/tutorial002.py hl[11:15] *}
💸 🙋 `__init__` 👩🔬 ⚙️ ✍ 👐 🎓:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/dependencies/tutorial002.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/dependencies/tutorial002_py310.py!}
- ```
+{* ../../docs_src/dependencies/tutorial002.py hl[12] *}
...⚫️ ✔️ 🎏 🔢 👆 ⏮️ `common_parameters`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/dependencies/tutorial001.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="6"
- {!> ../../../docs_src/dependencies/tutorial001_py310.py!}
- ```
+{* ../../docs_src/dependencies/tutorial001.py hl[9] *}
📚 🔢 ⚫️❔ **FastAPI** 🔜 ⚙️ "❎" 🔗.
@@ -133,17 +93,7 @@ fluffy = Cat(name="Mr Fluffy")
🔜 👆 💪 📣 👆 🔗 ⚙️ 👉 🎓.
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="19"
- {!> ../../../docs_src/dependencies/tutorial002.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="17"
- {!> ../../../docs_src/dependencies/tutorial002_py310.py!}
- ```
+{* ../../docs_src/dependencies/tutorial002.py hl[19] *}
**FastAPI** 🤙 `CommonQueryParams` 🎓. 👉 ✍ "👐" 👈 🎓 & 👐 🔜 🚶♀️ 🔢 `commons` 👆 🔢.
@@ -183,17 +133,7 @@ commons = Depends(CommonQueryParams)
...:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="19"
- {!> ../../../docs_src/dependencies/tutorial003.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="17"
- {!> ../../../docs_src/dependencies/tutorial003_py310.py!}
- ```
+{* ../../docs_src/dependencies/tutorial003.py hl[19] *}
✋️ 📣 🆎 💡 👈 🌌 👆 👨🎨 🔜 💭 ⚫️❔ 🔜 🚶♀️ 🔢 `commons`, & ⤴️ ⚫️ 💪 ℹ 👆 ⏮️ 📟 🛠️, 🆎 ✅, ♒️:
@@ -227,21 +167,14 @@ commons: CommonQueryParams = Depends()
🎏 🖼 🔜 ⤴️ 👀 💖:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="19"
- {!> ../../../docs_src/dependencies/tutorial004.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="17"
- {!> ../../../docs_src/dependencies/tutorial004_py310.py!}
- ```
+{* ../../docs_src/dependencies/tutorial004.py hl[19] *}
...& **FastAPI** 🔜 💭 ⚫️❔.
-!!! tip
- 🚥 👈 😑 🌅 😨 🌘 👍, 🤷♂ ⚫️, 👆 🚫 *💪* ⚫️.
+/// tip
- ⚫️ ⌨. ↩️ **FastAPI** 💅 🔃 🤝 👆 📉 📟 🔁.
+🚥 👈 😑 🌅 😨 🌘 👍, 🤷♂ ⚫️, 👆 🚫 *💪* ⚫️.
+
+⚫️ ⌨. ↩️ **FastAPI** 💅 🔃 🤝 👆 📉 📟 🔁.
+
+///
diff --git a/docs/em/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md b/docs/em/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
index 4d54b91c7..ab144a497 100644
--- a/docs/em/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
+++ b/docs/em/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
@@ -14,23 +14,27 @@
⚫️ 🔜 `list` `Depends()`:
-```Python hl_lines="17"
-{!../../../docs_src/dependencies/tutorial006.py!}
-```
+{* ../../docs_src/dependencies/tutorial006.py hl[17] *}
👉 🔗 🔜 🛠️/❎ 🎏 🌌 😐 🔗. ✋️ 👫 💲 (🚥 👫 📨 🙆) 🏆 🚫 🚶♀️ 👆 *➡ 🛠️ 🔢*.
-!!! tip
- 👨🎨 ✅ ♻ 🔢 🔢, & 🎦 👫 ❌.
+/// tip
- ⚙️ 👉 `dependencies` *➡ 🛠️ 👨🎨* 👆 💪 ⚒ 💭 👫 🛠️ ⏪ ❎ 👨🎨/🏭 ❌.
+👨🎨 ✅ ♻ 🔢 🔢, & 🎦 👫 ❌.
- ⚫️ 💪 ℹ ❎ 😨 🆕 👩💻 👈 👀 ♻ 🔢 👆 📟 & 💪 💭 ⚫️ 🙃.
+⚙️ 👉 `dependencies` *➡ 🛠️ 👨🎨* 👆 💪 ⚒ 💭 👫 🛠️ ⏪ ❎ 👨🎨/🏭 ❌.
-!!! info
- 👉 🖼 👥 ⚙️ 💭 🛃 🎚 `X-Key` & `X-Token`.
+⚫️ 💪 ℹ ❎ 😨 🆕 👩💻 👈 👀 ♻ 🔢 👆 📟 & 💪 💭 ⚫️ 🙃.
- ✋️ 🎰 💼, 🕐❔ 🛠️ 💂♂, 👆 🔜 🤚 🌖 💰 ⚪️➡️ ⚙️ 🛠️ [💂♂ 🚙 (⏭ 📃)](../security/index.md){.internal-link target=_blank}.
+///
+
+/// info
+
+👉 🖼 👥 ⚙️ 💭 🛃 🎚 `X-Key` & `X-Token`.
+
+✋️ 🎰 💼, 🕐❔ 🛠️ 💂♂, 👆 🔜 🤚 🌖 💰 ⚪️➡️ ⚙️ 🛠️ [💂♂ 🚙 (⏭ 📃)](../security/index.md){.internal-link target=_blank}.
+
+///
## 🔗 ❌ & 📨 💲
@@ -40,17 +44,13 @@
👫 💪 📣 📨 📄 (💖 🎚) ⚖️ 🎏 🎧-🔗:
-```Python hl_lines="6 11"
-{!../../../docs_src/dependencies/tutorial006.py!}
-```
+{* ../../docs_src/dependencies/tutorial006.py hl[6,11] *}
### 🤚 ⚠
👫 🔗 💪 `raise` ⚠, 🎏 😐 🔗:
-```Python hl_lines="8 13"
-{!../../../docs_src/dependencies/tutorial006.py!}
-```
+{* ../../docs_src/dependencies/tutorial006.py hl[8,13] *}
### 📨 💲
@@ -58,9 +58,7 @@
, 👆 💪 🏤-⚙️ 😐 🔗 (👈 📨 💲) 👆 ⏪ ⚙️ 👱 🙆, & ✋️ 💲 🏆 🚫 ⚙️, 🔗 🔜 🛠️:
-```Python hl_lines="9 14"
-{!../../../docs_src/dependencies/tutorial006.py!}
-```
+{* ../../docs_src/dependencies/tutorial006.py hl[9,14] *}
## 🔗 👪 *➡ 🛠️*
diff --git a/docs/em/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/em/docs/tutorial/dependencies/dependencies-with-yield.md
index 3ed5aeba5..1b37b1cf2 100644
--- a/docs/em/docs/tutorial/dependencies/dependencies-with-yield.md
+++ b/docs/em/docs/tutorial/dependencies/dependencies-with-yield.md
@@ -4,18 +4,24 @@ FastAPI 🐕🦺 🔗 👈 🔑 👨💼.
+/// note | 📡 ℹ
- **FastAPI** ⚙️ 👫 🔘 🏆 👉.
+👉 👷 👏 🐍 🔑 👨💼.
+
+**FastAPI** ⚙️ 👫 🔘 🏆 👉.
+
+///
## 🔗 ⏮️ `yield` & `HTTPException`
@@ -113,8 +113,11 @@ FastAPI 🐕🦺 🔗 👈 .
+/// tip
- ✋️ 🚥 👆 ✔️ 🛃 🎚 👈 👆 💚 👩💻 🖥 💪 👀, 👆 💪 🚮 👫 👆 ⚜ 📳 ([⚜ (✖️-🇨🇳 ℹ 🤝)](cors.md){.internal-link target=_blank}) ⚙️ 🔢 `expose_headers` 📄 💃 ⚜ 🩺.
+✔️ 🤯 👈 🛃 © 🎚 💪 🚮 ⚙️ '✖-' 🔡.
-!!! note "📡 ℹ"
- 👆 💪 ⚙️ `from starlette.requests import Request`.
+✋️ 🚥 👆 ✔️ 🛃 🎚 👈 👆 💚 👩💻 🖥 💪 👀, 👆 💪 🚮 👫 👆 ⚜ 📳 ([⚜ (✖️-🇨🇳 ℹ 🤝)](cors.md){.internal-link target=_blank}) ⚙️ 🔢 `expose_headers` 📄 💃 ⚜ 🩺.
- **FastAPI** 🚚 ⚫️ 🏪 👆, 👩💻. ✋️ ⚫️ 👟 🔗 ⚪️➡️ 💃.
+///
+
+/// note | 📡 ℹ
+
+👆 💪 ⚙️ `from starlette.requests import Request`.
+
+**FastAPI** 🚚 ⚫️ 🏪 👆, 👩💻. ✋️ ⚫️ 👟 🔗 ⚪️➡️ 💃.
+
+///
### ⏭ & ⏮️ `response`
@@ -50,9 +57,7 @@
🖼, 👆 💪 🚮 🛃 🎚 `X-Process-Time` ⚗ 🕰 🥈 👈 ⚫️ ✊ 🛠️ 📨 & 🏗 📨:
-```Python hl_lines="10 12-13"
-{!../../../docs_src/middleware/tutorial001.py!}
-```
+{* ../../docs_src/middleware/tutorial001.py hl[10,12:13] *}
## 🎏 🛠️
diff --git a/docs/em/docs/tutorial/path-operation-configuration.md b/docs/em/docs/tutorial/path-operation-configuration.md
index 916529258..c6030c089 100644
--- a/docs/em/docs/tutorial/path-operation-configuration.md
+++ b/docs/em/docs/tutorial/path-operation-configuration.md
@@ -2,8 +2,11 @@
📤 📚 🔢 👈 👆 💪 🚶♀️ 👆 *➡ 🛠️ 👨🎨* 🔗 ⚫️.
-!!! warning
- 👀 👈 👫 🔢 🚶♀️ 🔗 *➡ 🛠️ 👨🎨*, 🚫 👆 *➡ 🛠️ 🔢*.
+/// warning
+
+👀 👈 👫 🔢 🚶♀️ 🔗 *➡ 🛠️ 👨🎨*, 🚫 👆 *➡ 🛠️ 🔢*.
+
+///
## 📨 👔 📟
@@ -13,52 +16,23 @@
✋️ 🚥 👆 🚫 💭 ⚫️❔ 🔠 🔢 📟, 👆 💪 ⚙️ ⌨ 📉 `status`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="3 17"
- {!> ../../../docs_src/path_operation_configuration/tutorial001.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="3 17"
- {!> ../../../docs_src/path_operation_configuration/tutorial001_py39.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="1 15"
- {!> ../../../docs_src/path_operation_configuration/tutorial001_py310.py!}
- ```
+{* ../../docs_src/path_operation_configuration/tutorial001.py hl[3,17] *}
👈 👔 📟 🔜 ⚙️ 📨 & 🔜 🚮 🗄 🔗.
-!!! note "📡 ℹ"
- 👆 💪 ⚙️ `from starlette import status`.
+/// note | 📡 ℹ
- **FastAPI** 🚚 🎏 `starlette.status` `fastapi.status` 🏪 👆, 👩💻. ✋️ ⚫️ 👟 🔗 ⚪️➡️ 💃.
+👆 💪 ⚙️ `from starlette import status`.
+
+**FastAPI** 🚚 🎏 `starlette.status` `fastapi.status` 🏪 👆, 👩💻. ✋️ ⚫️ 👟 🔗 ⚪️➡️ 💃.
+
+///
## 🔖
👆 💪 🚮 🔖 👆 *➡ 🛠️*, 🚶♀️ 🔢 `tags` ⏮️ `list` `str` (🛎 1️⃣ `str`):
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="17 22 27"
- {!> ../../../docs_src/path_operation_configuration/tutorial002.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="17 22 27"
- {!> ../../../docs_src/path_operation_configuration/tutorial002_py39.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="15 20 25"
- {!> ../../../docs_src/path_operation_configuration/tutorial002_py310.py!}
- ```
+{* ../../docs_src/path_operation_configuration/tutorial002.py hl[17,22,27] *}
👫 🔜 🚮 🗄 🔗 & ⚙️ 🏧 🧾 🔢:
@@ -72,31 +46,13 @@
**FastAPI** 🐕🦺 👈 🎏 🌌 ⏮️ ✅ 🎻:
-```Python hl_lines="1 8-10 13 18"
-{!../../../docs_src/path_operation_configuration/tutorial002b.py!}
-```
+{* ../../docs_src/path_operation_configuration/tutorial002b.py hl[1,8:10,13,18] *}
## 📄 & 📛
👆 💪 🚮 `summary` & `description`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="20-21"
- {!> ../../../docs_src/path_operation_configuration/tutorial003.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="20-21"
- {!> ../../../docs_src/path_operation_configuration/tutorial003_py39.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="18-19"
- {!> ../../../docs_src/path_operation_configuration/tutorial003_py310.py!}
- ```
+{* ../../docs_src/path_operation_configuration/tutorial003.py hl[20:21] *}
## 📛 ⚪️➡️ #️⃣
@@ -104,23 +60,7 @@
👆 💪 ✍ ✍ #️⃣ , ⚫️ 🔜 🔬 & 🖥 ☑ (✊ 🔘 🏧 #️⃣ 📐).
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="19-27"
- {!> ../../../docs_src/path_operation_configuration/tutorial004.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="19-27"
- {!> ../../../docs_src/path_operation_configuration/tutorial004_py39.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="17-25"
- {!> ../../../docs_src/path_operation_configuration/tutorial004_py310.py!}
- ```
+{* ../../docs_src/path_operation_configuration/tutorial004.py hl[19:27] *}
⚫️ 🔜 ⚙️ 🎓 🩺:
@@ -130,31 +70,21 @@
👆 💪 ✔ 📨 📛 ⏮️ 🔢 `response_description`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
+{* ../../docs_src/path_operation_configuration/tutorial005.py hl[21] *}
- ```Python hl_lines="21"
- {!> ../../../docs_src/path_operation_configuration/tutorial005.py!}
- ```
+/// info
-=== "🐍 3️⃣.9️⃣ & 🔛"
+👀 👈 `response_description` 🔗 🎯 📨, `description` 🔗 *➡ 🛠️* 🏢.
- ```Python hl_lines="21"
- {!> ../../../docs_src/path_operation_configuration/tutorial005_py39.py!}
- ```
+///
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
+/// check
- ```Python hl_lines="19"
- {!> ../../../docs_src/path_operation_configuration/tutorial005_py310.py!}
- ```
+🗄 ✔ 👈 🔠 *➡ 🛠️* 🚚 📨 📛.
-!!! info
- 👀 👈 `response_description` 🔗 🎯 📨, `description` 🔗 *➡ 🛠️* 🏢.
+, 🚥 👆 🚫 🚚 1️⃣, **FastAPI** 🔜 🔁 🏗 1️⃣ "🏆 📨".
-!!! check
- 🗄 ✔ 👈 🔠 *➡ 🛠️* 🚚 📨 📛.
-
- , 🚥 👆 🚫 🚚 1️⃣, **FastAPI** 🔜 🔁 🏗 1️⃣ "🏆 📨".
+///
@@ -162,9 +92,7 @@
🚥 👆 💪 ™ *➡ 🛠️* 😢, ✋️ 🍵 ❎ ⚫️, 🚶♀️ 🔢 `deprecated`:
-```Python hl_lines="16"
-{!../../../docs_src/path_operation_configuration/tutorial006.py!}
-```
+{* ../../docs_src/path_operation_configuration/tutorial006.py hl[16] *}
⚫️ 🔜 🎯 ™ 😢 🎓 🩺:
diff --git a/docs/em/docs/tutorial/path-params-numeric-validations.md b/docs/em/docs/tutorial/path-params-numeric-validations.md
index b1ba2670b..b45e0557b 100644
--- a/docs/em/docs/tutorial/path-params-numeric-validations.md
+++ b/docs/em/docs/tutorial/path-params-numeric-validations.md
@@ -6,17 +6,7 @@
🥇, 🗄 `Path` ⚪️➡️ `fastapi`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="3"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="1"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_py310.py!}
- ```
+{* ../../docs_src/path_params_numeric_validations/tutorial001.py hl[3] *}
## 📣 🗃
@@ -24,24 +14,17 @@
🖼, 📣 `title` 🗃 💲 ➡ 🔢 `item_id` 👆 💪 🆎:
-=== "🐍 3️⃣.6️⃣ & 🔛"
+{* ../../docs_src/path_params_numeric_validations/tutorial001.py hl[10] *}
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001.py!}
- ```
+/// note
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
+➡ 🔢 🕧 ✔ ⚫️ ✔️ 🍕 ➡.
- ```Python hl_lines="8"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_py310.py!}
- ```
+, 👆 🔜 📣 ⚫️ ⏮️ `...` ™ ⚫️ ✔.
-!!! note
- ➡ 🔢 🕧 ✔ ⚫️ ✔️ 🍕 ➡.
+👐, 🚥 👆 📣 ⚫️ ⏮️ `None` ⚖️ ⚒ 🔢 💲, ⚫️ 🔜 🚫 📉 🕳, ⚫️ 🔜 🕧 🚚.
- , 👆 🔜 📣 ⚫️ ⏮️ `...` ™ ⚫️ ✔.
-
- 👐, 🚥 👆 📣 ⚫️ ⏮️ `None` ⚖️ ⚒ 🔢 💲, ⚫️ 🔜 🚫 📉 🕳, ⚫️ 🔜 🕧 🚚.
+///
## ✔ 🔢 👆 💪
@@ -59,9 +42,7 @@
, 👆 💪 📣 👆 🔢:
-```Python hl_lines="7"
-{!../../../docs_src/path_params_numeric_validations/tutorial002.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial002.py hl[7] *}
## ✔ 🔢 👆 💪, 🎱
@@ -71,9 +52,7 @@
🐍 🏆 🚫 🕳 ⏮️ 👈 `*`, ✋️ ⚫️ 🔜 💭 👈 🌐 📄 🔢 🔜 🤙 🇨🇻 ❌ (🔑-💲 👫), 💭 kwargs. 🚥 👫 🚫 ✔️ 🔢 💲.
-```Python hl_lines="7"
-{!../../../docs_src/path_params_numeric_validations/tutorial003.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *}
## 🔢 🔬: 👑 🌘 ⚖️ 🌓
@@ -81,9 +60,7 @@
📥, ⏮️ `ge=1`, `item_id` 🔜 💪 🔢 🔢 "`g`🅾 🌘 ⚖️ `e`🅾" `1`.
-```Python hl_lines="8"
-{!../../../docs_src/path_params_numeric_validations/tutorial004.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial004.py hl[8] *}
## 🔢 🔬: 🌘 🌘 & 🌘 🌘 ⚖️ 🌓
@@ -92,9 +69,7 @@
* `gt`: `g`🅾 `t`👲
* `le`: `l`👭 🌘 ⚖️ `e`🅾
-```Python hl_lines="9"
-{!../../../docs_src/path_params_numeric_validations/tutorial005.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial005.py hl[9] *}
## 🔢 🔬: 🎈, 🌘 🌘 & 🌘 🌘
@@ -106,9 +81,7 @@
& 🎏 lt.
-```Python hl_lines="11"
-{!../../../docs_src/path_params_numeric_validations/tutorial006.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial006.py hl[11] *}
## 🌃
@@ -121,18 +94,24 @@
* `lt`: `l`👭 `t`👲
* `le`: `l`👭 🌘 ⚖️ `e`🅾
-!!! info
- `Query`, `Path`, & 🎏 🎓 👆 🔜 👀 ⏪ 🏿 ⚠ `Param` 🎓.
+/// info
- 🌐 👫 💰 🎏 🔢 🌖 🔬 & 🗃 👆 ✔️ 👀.
+`Query`, `Path`, & 🎏 🎓 👆 🔜 👀 ⏪ 🏿 ⚠ `Param` 🎓.
-!!! note "📡 ℹ"
- 🕐❔ 👆 🗄 `Query`, `Path` & 🎏 ⚪️➡️ `fastapi`, 👫 🤙 🔢.
+🌐 👫 💰 🎏 🔢 🌖 🔬 & 🗃 👆 ✔️ 👀.
- 👈 🕐❔ 🤙, 📨 👐 🎓 🎏 📛.
+///
- , 👆 🗄 `Query`, ❔ 🔢. & 🕐❔ 👆 🤙 ⚫️, ⚫️ 📨 👐 🎓 🌟 `Query`.
+/// note | 📡 ℹ
- 👫 🔢 📤 (↩️ ⚙️ 🎓 🔗) 👈 👆 👨🎨 🚫 ™ ❌ 🔃 👫 🆎.
+🕐❔ 👆 🗄 `Query`, `Path` & 🎏 ⚪️➡️ `fastapi`, 👫 🤙 🔢.
- 👈 🌌 👆 💪 ⚙️ 👆 😐 👨🎨 & 🛠️ 🧰 🍵 ✔️ 🚮 🛃 📳 🤷♂ 📚 ❌.
+👈 🕐❔ 🤙, 📨 👐 🎓 🎏 📛.
+
+, 👆 🗄 `Query`, ❔ 🔢. & 🕐❔ 👆 🤙 ⚫️, ⚫️ 📨 👐 🎓 🌟 `Query`.
+
+👫 🔢 📤 (↩️ ⚙️ 🎓 🔗) 👈 👆 👨🎨 🚫 ™ ❌ 🔃 👫 🆎.
+
+👈 🌌 👆 💪 ⚙️ 👆 😐 👨🎨 & 🛠️ 🧰 🍵 ✔️ 🚮 🛃 📳 🤷♂ 📚 ❌.
+
+///
diff --git a/docs/em/docs/tutorial/path-params.md b/docs/em/docs/tutorial/path-params.md
index ac64d2ebb..a914dc905 100644
--- a/docs/em/docs/tutorial/path-params.md
+++ b/docs/em/docs/tutorial/path-params.md
@@ -2,9 +2,7 @@
👆 💪 📣 ➡ "🔢" ⚖️ "🔢" ⏮️ 🎏 ❕ ⚙️ 🐍 📁 🎻:
-```Python hl_lines="6-7"
-{!../../../docs_src/path_params/tutorial001.py!}
-```
+{* ../../docs_src/path_params/tutorial001.py hl[6:7] *}
💲 ➡ 🔢 `item_id` 🔜 🚶♀️ 👆 🔢 ❌ `item_id`.
@@ -18,14 +16,15 @@
👆 💪 📣 🆎 ➡ 🔢 🔢, ⚙️ 🐩 🐍 🆎 ✍:
-```Python hl_lines="7"
-{!../../../docs_src/path_params/tutorial002.py!}
-```
+{* ../../docs_src/path_params/tutorial002.py hl[7] *}
👉 💼, `item_id` 📣 `int`.
-!!! check
- 👉 🔜 🤝 👆 👨🎨 🐕🦺 🔘 👆 🔢, ⏮️ ❌ ✅, 🛠️, ♒️.
+/// check
+
+👉 🔜 🤝 👆 👨🎨 🐕🦺 🔘 👆 🔢, ⏮️ ❌ ✅, 🛠️, ♒️.
+
+///
## 💽 🛠️
@@ -35,10 +34,13 @@
{"item_id":3}
```
-!!! check
- 👀 👈 💲 👆 🔢 📨 (& 📨) `3`, 🐍 `int`, 🚫 🎻 `"3"`.
+/// check
- , ⏮️ 👈 🆎 📄, **FastAPI** 🤝 👆 🏧 📨 "✍".
+👀 👈 💲 👆 🔢 📨 (& 📨) `3`, 🐍 `int`, 🚫 🎻 `"3"`.
+
+, ⏮️ 👈 🆎 📄, **FastAPI** 🤝 👆 🏧 📨 "✍".
+
+///
## 💽 🔬
@@ -63,12 +65,15 @@
🎏 ❌ 🔜 😑 🚥 👆 🚚 `float` ↩️ `int`,: http://127.0.0.1:8000/items/4.2
-!!! check
- , ⏮️ 🎏 🐍 🆎 📄, **FastAPI** 🤝 👆 💽 🔬.
+/// check
- 👀 👈 ❌ 🎯 🇵🇸 ⚫️❔ ☝ 🌐❔ 🔬 🚫 🚶♀️.
+, ⏮️ 🎏 🐍 🆎 📄, **FastAPI** 🤝 👆 💽 🔬.
- 👉 🙃 👍 ⏪ 🛠️ & 🛠️ 📟 👈 🔗 ⏮️ 👆 🛠️.
+👀 👈 ❌ 🎯 🇵🇸 ⚫️❔ ☝ 🌐❔ 🔬 🚫 🚶♀️.
+
+👉 🙃 👍 ⏪ 🛠️ & 🛠️ 📟 👈 🔗 ⏮️ 👆 🛠️.
+
+///
## 🧾
@@ -76,10 +81,13 @@
-!!! check
- 🔄, ⏮️ 👈 🎏 🐍 🆎 📄, **FastAPI** 🤝 👆 🏧, 🎓 🧾 (🛠️ 🦁 🎚).
+/// check
- 👀 👈 ➡ 🔢 📣 🔢.
+🔄, ⏮️ 👈 🎏 🐍 🆎 📄, **FastAPI** 🤝 👆 🏧, 🎓 🧾 (🛠️ 🦁 🎚).
+
+👀 👈 ➡ 🔢 📣 🔢.
+
+///
## 🐩-⚓️ 💰, 🎛 🧾
@@ -109,17 +117,13 @@
↩️ *➡ 🛠️* 🔬 ✔, 👆 💪 ⚒ 💭 👈 ➡ `/users/me` 📣 ⏭ 1️⃣ `/users/{user_id}`:
-```Python hl_lines="6 11"
-{!../../../docs_src/path_params/tutorial003.py!}
-```
+{* ../../docs_src/path_params/tutorial003.py hl[6,11] *}
⏪, ➡ `/users/{user_id}` 🔜 🏏 `/users/me`, "💭" 👈 ⚫️ 📨 🔢 `user_id` ⏮️ 💲 `"me"`.
➡, 👆 🚫🔜 ↔ ➡ 🛠️:
-```Python hl_lines="6 11"
-{!../../../docs_src/path_params/tutorial003b.py!}
-```
+{* ../../docs_src/path_params/tutorial003b.py hl[6,11] *}
🥇 🕐 🔜 🕧 ⚙️ ↩️ ➡ 🏏 🥇.
@@ -135,23 +139,25 @@
⤴️ ✍ 🎓 🔢 ⏮️ 🔧 💲, ❔ 🔜 💪 ☑ 💲:
-```Python hl_lines="1 6-9"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[1,6:9] *}
-!!! info
- 🔢 (⚖️ 🔢) 💪 🐍 ↩️ ⏬ 3️⃣.4️⃣.
+/// info
-!!! tip
- 🚥 👆 💭, "📊", "🎓", & "🍏" 📛 🎰 🏫 🏷.
+🔢 (⚖️ 🔢) 💪 🐍 ↩️ ⏬ 3️⃣.4️⃣.
+
+///
+
+/// tip
+
+🚥 👆 💭, "📊", "🎓", & "🍏" 📛 🎰 🏫 🏷.
+
+///
### 📣 *➡ 🔢*
⤴️ ✍ *➡ 🔢* ⏮️ 🆎 ✍ ⚙️ 🔢 🎓 👆 ✍ (`ModelName`):
-```Python hl_lines="16"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[16] *}
### ✅ 🩺
@@ -167,20 +173,19 @@
👆 💪 🔬 ⚫️ ⏮️ *🔢 👨🎓* 👆 ✍ 🔢 `ModelName`:
-```Python hl_lines="17"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[17] *}
#### 🤚 *🔢 💲*
👆 💪 🤚 ☑ 💲 ( `str` 👉 💼) ⚙️ `model_name.value`, ⚖️ 🏢, `your_enum_member.value`:
-```Python hl_lines="20"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[20] *}
-!!! tip
- 👆 💪 🔐 💲 `"lenet"` ⏮️ `ModelName.lenet.value`.
+/// tip
+
+👆 💪 🔐 💲 `"lenet"` ⏮️ `ModelName.lenet.value`.
+
+///
#### 📨 *🔢 👨🎓*
@@ -188,9 +193,7 @@
👫 🔜 🗜 👫 🔗 💲 (🎻 👉 💼) ⏭ 🛬 👫 👩💻:
-```Python hl_lines="18 21 23"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[18,21,23] *}
👆 👩💻 👆 🔜 🤚 🎻 📨 💖:
@@ -229,14 +232,15 @@
, 👆 💪 ⚙️ ⚫️ ⏮️:
-```Python hl_lines="6"
-{!../../../docs_src/path_params/tutorial004.py!}
-```
+{* ../../docs_src/path_params/tutorial004.py hl[6] *}
-!!! tip
- 👆 💪 💪 🔢 🔌 `/home/johndoe/myfile.txt`, ⏮️ 🏁 🔪 (`/`).
+/// tip
- 👈 💼, 📛 🔜: `/files//home/johndoe/myfile.txt`, ⏮️ 2️⃣✖️ 🔪 (`//`) 🖖 `files` & `home`.
+👆 💪 💪 🔢 🔌 `/home/johndoe/myfile.txt`, ⏮️ 🏁 🔪 (`/`).
+
+👈 💼, 📛 🔜: `/files//home/johndoe/myfile.txt`, ⏮️ 2️⃣✖️ 🔪 (`//`) 🖖 `files` & `home`.
+
+///
## 🌃
diff --git a/docs/em/docs/tutorial/query-params-str-validations.md b/docs/em/docs/tutorial/query-params-str-validations.md
index 1268c0d6e..fd077bf8f 100644
--- a/docs/em/docs/tutorial/query-params-str-validations.md
+++ b/docs/em/docs/tutorial/query-params-str-validations.md
@@ -4,24 +4,17 @@
➡️ ✊ 👉 🈸 🖼:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial001.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params_str_validations/tutorial001_py310.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial001.py hl[9] *}
🔢 🔢 `q` 🆎 `Union[str, None]` (⚖️ `str | None` 🐍 3️⃣.1️⃣0️⃣), 👈 ⛓ 👈 ⚫️ 🆎 `str` ✋️ 💪 `None`, & 👐, 🔢 💲 `None`, FastAPI 🔜 💭 ⚫️ 🚫 ✔.
-!!! note
- FastAPI 🔜 💭 👈 💲 `q` 🚫 ✔ ↩️ 🔢 💲 `= None`.
+/// note
- `Union` `Union[str, None]` 🔜 ✔ 👆 👨🎨 🤝 👆 👍 🐕🦺 & 🔍 ❌.
+FastAPI 🔜 💭 👈 💲 `q` 🚫 ✔ ↩️ 🔢 💲 `= None`.
+
+ `Union` `Union[str, None]` 🔜 ✔ 👆 👨🎨 🤝 👆 👍 🐕🦺 & 🔍 ❌.
+
+///
## 🌖 🔬
@@ -31,33 +24,13 @@
🏆 👈, 🥇 🗄 `Query` ⚪️➡️ `fastapi`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="3"
- {!> ../../../docs_src/query_params_str_validations/tutorial002.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="1"
- {!> ../../../docs_src/query_params_str_validations/tutorial002_py310.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial002.py hl[3] *}
## ⚙️ `Query` 🔢 💲
& 🔜 ⚙️ ⚫️ 🔢 💲 👆 🔢, ⚒ 🔢 `max_length` 5️⃣0️⃣:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial002.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params_str_validations/tutorial002_py310.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial002.py hl[9] *}
👥 ✔️ ❎ 🔢 💲 `None` 🔢 ⏮️ `Query()`, 👥 💪 🔜 ⚒ 🔢 💲 ⏮️ 🔢 `Query(default=None)`, ⚫️ 🍦 🎏 🎯 ⚖ 👈 🔢 💲.
@@ -87,22 +60,25 @@ q: str | None = None
✋️ ⚫️ 📣 ⚫️ 🎯 💆♂ 🔢 🔢.
-!!! info
- ✔️ 🤯 👈 🌅 ⚠ 🍕 ⚒ 🔢 📦 🍕:
+/// info
- ```Python
- = None
- ```
+✔️ 🤯 👈 🌅 ⚠ 🍕 ⚒ 🔢 📦 🍕:
- ⚖️:
+```Python
+= None
+```
- ```Python
- = Query(default=None)
- ```
+⚖️:
- ⚫️ 🔜 ⚙️ 👈 `None` 🔢 💲, & 👈 🌌 ⚒ 🔢 **🚫 ✔**.
+```Python
+= Query(default=None)
+```
- `Union[str, None]` 🍕 ✔ 👆 👨🎨 🚚 👻 🐕🦺, ✋️ ⚫️ 🚫 ⚫️❔ 💬 FastAPI 👈 👉 🔢 🚫 ✔.
+⚫️ 🔜 ⚙️ 👈 `None` 🔢 💲, & 👈 🌌 ⚒ 🔢 **🚫 ✔**.
+
+ `Union[str, None]` 🍕 ✔ 👆 👨🎨 🚚 👻 🐕🦺, ✋️ ⚫️ 🚫 ⚫️❔ 💬 FastAPI 👈 👉 🔢 🚫 ✔.
+
+///
⤴️, 👥 💪 🚶♀️ 🌅 🔢 `Query`. 👉 💼, `max_length` 🔢 👈 ✔ 🎻:
@@ -116,33 +92,13 @@ q: Union[str, None] = Query(default=None, max_length=50)
👆 💪 🚮 🔢 `min_length`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params_str_validations/tutorial003.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params_str_validations/tutorial003_py310.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial003.py hl[10] *}
## 🚮 🥔 🧬
👆 💪 🔬 🥔 🧬 👈 🔢 🔜 🏏:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/query_params_str_validations/tutorial004.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial004_py310.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial004.py hl[11] *}
👉 🎯 🥔 🧬 ✅ 👈 📨 🔢 💲:
@@ -160,12 +116,13 @@ q: Union[str, None] = Query(default=None, max_length=50)
➡️ 💬 👈 👆 💚 📣 `q` 🔢 🔢 ✔️ `min_length` `3`, & ✔️ 🔢 💲 `"fixedquery"`:
-```Python hl_lines="7"
-{!../../../docs_src/query_params_str_validations/tutorial005.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial005.py hl[7] *}
-!!! note
- ✔️ 🔢 💲 ⚒ 🔢 📦.
+/// note
+
+✔️ 🔢 💲 ⚒ 🔢 📦.
+
+///
## ⚒ ⚫️ ✔
@@ -189,24 +146,7 @@ q: Union[str, None] = Query(default=None, min_length=3)
, 🕐❔ 👆 💪 📣 💲 ✔ ⏪ ⚙️ `Query`, 👆 💪 🎯 🚫 📣 🔢 💲:
-```Python hl_lines="7"
-{!../../../docs_src/query_params_str_validations/tutorial006.py!}
-```
-
-### ✔ ⏮️ ❕ (`...`)
-
-📤 🎛 🌌 🎯 📣 👈 💲 ✔. 👆 💪 ⚒ `default` 🔢 🔑 💲 `...`:
-
-```Python hl_lines="7"
-{!../../../docs_src/query_params_str_validations/tutorial006b.py!}
-```
-
-!!! info
- 🚥 👆 🚫 👀 👈 `...` ⏭: ⚫️ 🎁 👁 💲, ⚫️ 🍕 🐍 & 🤙 "❕".
-
- ⚫️ ⚙️ Pydantic & FastAPI 🎯 📣 👈 💲 ✔.
-
-👉 🔜 ➡️ **FastAPI** 💭 👈 👉 🔢 ✔.
+{* ../../docs_src/query_params_str_validations/tutorial006.py hl[7] *}
### ✔ ⏮️ `None`
@@ -214,31 +154,13 @@ q: Union[str, None] = Query(default=None, min_length=3)
👈, 👆 💪 📣 👈 `None` ☑ 🆎 ✋️ ⚙️ `default=...`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
+{* ../../docs_src/query_params_str_validations/tutorial006c.py hl[9] *}
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial006c.py!}
- ```
+/// tip
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
+Pydantic, ❔ ⚫️❔ 🏋️ 🌐 💽 🔬 & 🛠️ FastAPI, ✔️ 🎁 🎭 🕐❔ 👆 ⚙️ `Optional` ⚖️ `Union[Something, None]` 🍵 🔢 💲, 👆 💪 ✍ 🌅 🔃 ⚫️ Pydantic 🩺 🔃 ✔ 📦 🏑.
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params_str_validations/tutorial006c_py310.py!}
- ```
-
-!!! tip
- Pydantic, ❔ ⚫️❔ 🏋️ 🌐 💽 🔬 & 🛠️ FastAPI, ✔️ 🎁 🎭 🕐❔ 👆 ⚙️ `Optional` ⚖️ `Union[Something, None]` 🍵 🔢 💲, 👆 💪 ✍ 🌅 🔃 ⚫️ Pydantic 🩺 🔃 ✔ 📦 🏑.
-
-### ⚙️ Pydantic `Required` ↩️ ❕ (`...`)
-
-🚥 👆 💭 😬 ⚙️ `...`, 👆 💪 🗄 & ⚙️ `Required` ⚪️➡️ Pydantic:
-
-```Python hl_lines="2 8"
-{!../../../docs_src/query_params_str_validations/tutorial006d.py!}
-```
-
-!!! tip
- 💭 👈 🌅 💼, 🕐❔ 🕳 🚚, 👆 💪 🎯 🚫 `default` 🔢, 👆 🛎 🚫 ✔️ ⚙️ `...` 🚫 `Required`.
+///
## 🔢 🔢 📇 / 💗 💲
@@ -246,23 +168,7 @@ q: Union[str, None] = Query(default=None, min_length=3)
🖼, 📣 🔢 🔢 `q` 👈 💪 😑 💗 🕰 📛, 👆 💪 ✍:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial011.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial011_py39.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params_str_validations/tutorial011_py310.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial011.py hl[9] *}
⤴️, ⏮️ 📛 💖:
@@ -283,8 +189,11 @@ http://localhost:8000/items/?q=foo&q=bar
}
```
-!!! tip
- 📣 🔢 🔢 ⏮️ 🆎 `list`, 💖 🖼 🔛, 👆 💪 🎯 ⚙️ `Query`, ⏪ ⚫️ 🔜 🔬 📨 💪.
+/// tip
+
+📣 🔢 🔢 ⏮️ 🆎 `list`, 💖 🖼 🔛, 👆 💪 🎯 ⚙️ `Query`, ⏪ ⚫️ 🔜 🔬 📨 💪.
+
+///
🎓 🛠️ 🩺 🔜 ℹ ➡️, ✔ 💗 💲:
@@ -294,17 +203,7 @@ http://localhost:8000/items/?q=foo&q=bar
& 👆 💪 🔬 🔢 `list` 💲 🚥 👌 🚚:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial012.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params_str_validations/tutorial012_py39.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial012.py hl[9] *}
🚥 👆 🚶:
@@ -327,14 +226,15 @@ http://localhost:8000/items/
👆 💪 ⚙️ `list` 🔗 ↩️ `List[str]` (⚖️ `list[str]` 🐍 3️⃣.9️⃣ ➕):
-```Python hl_lines="7"
-{!../../../docs_src/query_params_str_validations/tutorial013.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial013.py hl[7] *}
-!!! note
- ✔️ 🤯 👈 👉 💼, FastAPI 🏆 🚫 ✅ 🎚 📇.
+/// note
- 🖼, `List[int]` 🔜 ✅ (& 📄) 👈 🎚 📇 🔢. ✋️ `list` 😞 🚫🔜.
+✔️ 🤯 👈 👉 💼, FastAPI 🏆 🚫 ✅ 🎚 📇.
+
+🖼, `List[int]` 🔜 ✅ (& 📄) 👈 🎚 📇 🔢. ✋️ `list` 😞 🚫🔜.
+
+///
## 📣 🌅 🗃
@@ -342,38 +242,21 @@ http://localhost:8000/items/
👈 ℹ 🔜 🔌 🏗 🗄 & ⚙️ 🧾 👩💻 🔢 & 🔢 🧰.
-!!! note
- ✔️ 🤯 👈 🎏 🧰 5️⃣📆 ✔️ 🎏 🎚 🗄 🐕🦺.
+/// note
- 👫 💪 🚫 🎦 🌐 ➕ ℹ 📣, 👐 🌅 💼, ❌ ⚒ ⏪ 📄 🛠️.
+✔️ 🤯 👈 🎏 🧰 5️⃣📆 ✔️ 🎏 🎚 🗄 🐕🦺.
+
+👫 💪 🚫 🎦 🌐 ➕ ℹ 📣, 👐 🌅 💼, ❌ ⚒ ⏪ 📄 🛠️.
+
+///
👆 💪 🚮 `title`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params_str_validations/tutorial007.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/query_params_str_validations/tutorial007_py310.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial007.py hl[10] *}
& `description`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="13"
- {!> ../../../docs_src/query_params_str_validations/tutorial008.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/query_params_str_validations/tutorial008_py310.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial008.py hl[13] *}
## 📛 🔢
@@ -393,17 +276,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems
⤴️ 👆 💪 📣 `alias`, & 👈 📛 ⚫️❔ 🔜 ⚙️ 🔎 🔢 💲:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial009.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params_str_validations/tutorial009_py310.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial009.py hl[9] *}
## 😛 🔢
@@ -413,17 +286,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems
⤴️ 🚶♀️ 🔢 `deprecated=True` `Query`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/query_params_str_validations/tutorial010.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="16"
- {!> ../../../docs_src/query_params_str_validations/tutorial010_py310.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial010.py hl[18] *}
🩺 🔜 🎦 ⚫️ 💖 👉:
@@ -433,17 +296,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems
🚫 🔢 🔢 ⚪️➡️ 🏗 🗄 🔗 (& ➡️, ⚪️➡️ 🏧 🧾 ⚙️), ⚒ 🔢 `include_in_schema` `Query` `False`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params_str_validations/tutorial014.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/query_params_str_validations/tutorial014_py310.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial014.py hl[10] *}
## 🌃
diff --git a/docs/em/docs/tutorial/query-params.md b/docs/em/docs/tutorial/query-params.md
index 746b0af9e..5c8d868a9 100644
--- a/docs/em/docs/tutorial/query-params.md
+++ b/docs/em/docs/tutorial/query-params.md
@@ -2,9 +2,7 @@
🕐❔ 👆 📣 🎏 🔢 🔢 👈 🚫 🍕 ➡ 🔢, 👫 🔁 🔬 "🔢" 🔢.
-```Python hl_lines="9"
-{!../../../docs_src/query_params/tutorial001.py!}
-```
+{* ../../docs_src/query_params/tutorial001.py hl[9] *}
🔢 ⚒ 🔑-💲 👫 👈 🚶 ⏮️ `?` 📛, 🎏 `&` 🦹.
@@ -63,38 +61,21 @@ http://127.0.0.1:8000/items/?skip=20
🎏 🌌, 👆 💪 📣 📦 🔢 🔢, ⚒ 👫 🔢 `None`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params/tutorial002.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params/tutorial002_py310.py!}
- ```
+{* ../../docs_src/query_params/tutorial002.py hl[9] *}
👉 💼, 🔢 🔢 `q` 🔜 📦, & 🔜 `None` 🔢.
-!!! check
- 👀 👈 **FastAPI** 🙃 🥃 👀 👈 ➡ 🔢 `item_id` ➡ 🔢 & `q` 🚫,, ⚫️ 🔢 🔢.
+/// check
+
+👀 👈 **FastAPI** 🙃 🥃 👀 👈 ➡ 🔢 `item_id` ➡ 🔢 & `q` 🚫,, ⚫️ 🔢 🔢.
+
+///
## 🔢 🔢 🆎 🛠️
👆 💪 📣 `bool` 🆎, & 👫 🔜 🗜:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params/tutorial003.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params/tutorial003_py310.py!}
- ```
+{* ../../docs_src/query_params/tutorial003.py hl[9] *}
👉 💼, 🚥 👆 🚶:
@@ -137,17 +118,7 @@ http://127.0.0.1:8000/items/foo?short=yes
👫 🔜 🔬 📛:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="8 10"
- {!> ../../../docs_src/query_params/tutorial004.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="6 8"
- {!> ../../../docs_src/query_params/tutorial004_py310.py!}
- ```
+{* ../../docs_src/query_params/tutorial004.py hl[8,10] *}
## ✔ 🔢 🔢
@@ -157,9 +128,7 @@ http://127.0.0.1:8000/items/foo?short=yes
✋️ 🕐❔ 👆 💚 ⚒ 🔢 🔢 ✔, 👆 💪 🚫 📣 🙆 🔢 💲:
-```Python hl_lines="6-7"
-{!../../../docs_src/query_params/tutorial005.py!}
-```
+{* ../../docs_src/query_params/tutorial005.py hl[6:7] *}
📥 🔢 🔢 `needy` ✔ 🔢 🔢 🆎 `str`.
@@ -203,17 +172,7 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
& ↗️, 👆 💪 🔬 🔢 ✔, ✔️ 🔢 💲, & 🍕 📦:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params/tutorial006.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/query_params/tutorial006_py310.py!}
- ```
+{* ../../docs_src/query_params/tutorial006.py hl[10] *}
👉 💼, 📤 3️⃣ 🔢 🔢:
@@ -221,5 +180,8 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
* `skip`, `int` ⏮️ 🔢 💲 `0`.
* `limit`, 📦 `int`.
-!!! tip
- 👆 💪 ⚙️ `Enum`Ⓜ 🎏 🌌 ⏮️ [➡ 🔢](path-params.md#_7){.internal-link target=_blank}.
+/// tip
+
+👆 💪 ⚙️ `Enum`Ⓜ 🎏 🌌 ⏮️ [➡ 🔢](path-params.md#_7){.internal-link target=_blank}.
+
+///
diff --git a/docs/em/docs/tutorial/request-files.md b/docs/em/docs/tutorial/request-files.md
index be2218f89..c3bdeafd4 100644
--- a/docs/em/docs/tutorial/request-files.md
+++ b/docs/em/docs/tutorial/request-files.md
@@ -2,36 +2,41 @@
👆 💪 🔬 📁 📂 👩💻 ⚙️ `File`.
-!!! info
- 📨 📂 📁, 🥇 ❎ `python-multipart`.
+/// info
- 🤶 Ⓜ. `pip install python-multipart`.
+📨 📂 📁, 🥇 ❎ `python-multipart`.
- 👉 ↩️ 📂 📁 📨 "📨 💽".
+🤶 Ⓜ. `pip install python-multipart`.
+
+👉 ↩️ 📂 📁 📨 "📨 💽".
+
+///
## 🗄 `File`
🗄 `File` & `UploadFile` ⚪️➡️ `fastapi`:
-```Python hl_lines="1"
-{!../../../docs_src/request_files/tutorial001.py!}
-```
+{* ../../docs_src/request_files/tutorial001.py hl[1] *}
## 🔬 `File` 🔢
✍ 📁 🔢 🎏 🌌 👆 🔜 `Body` ⚖️ `Form`:
-```Python hl_lines="7"
-{!../../../docs_src/request_files/tutorial001.py!}
-```
+{* ../../docs_src/request_files/tutorial001.py hl[7] *}
-!!! info
- `File` 🎓 👈 😖 🔗 ⚪️➡️ `Form`.
+/// info
- ✋️ 💭 👈 🕐❔ 👆 🗄 `Query`, `Path`, `File` & 🎏 ⚪️➡️ `fastapi`, 👈 🤙 🔢 👈 📨 🎁 🎓.
+`File` 🎓 👈 😖 🔗 ⚪️➡️ `Form`.
-!!! tip
- 📣 📁 💪, 👆 💪 ⚙️ `File`, ↩️ ⏪ 🔢 🔜 🔬 🔢 🔢 ⚖️ 💪 (🎻) 🔢.
+✋️ 💭 👈 🕐❔ 👆 🗄 `Query`, `Path`, `File` & 🎏 ⚪️➡️ `fastapi`, 👈 🤙 🔢 👈 📨 🎁 🎓.
+
+///
+
+/// tip
+
+📣 📁 💪, 👆 💪 ⚙️ `File`, ↩️ ⏪ 🔢 🔜 🔬 🔢 🔢 ⚖️ 💪 (🎻) 🔢.
+
+///
📁 🔜 📂 "📨 💽".
@@ -45,9 +50,7 @@
🔬 📁 🔢 ⏮️ 🆎 `UploadFile`:
-```Python hl_lines="12"
-{!../../../docs_src/request_files/tutorial001.py!}
-```
+{* ../../docs_src/request_files/tutorial001.py hl[12] *}
⚙️ `UploadFile` ✔️ 📚 📈 🤭 `bytes`:
@@ -90,11 +93,17 @@ contents = await myfile.read()
contents = myfile.file.read()
```
-!!! note "`async` 📡 ℹ"
- 🕐❔ 👆 ⚙️ `async` 👩🔬, **FastAPI** 🏃 📁 👩🔬 🧵 & ⌛ 👫.
+/// note | `async` 📡 ℹ
-!!! note "💃 📡 ℹ"
- **FastAPI**'Ⓜ `UploadFile` 😖 🔗 ⚪️➡️ **💃**'Ⓜ `UploadFile`, ✋️ 🚮 💪 🍕 ⚒ ⚫️ 🔗 ⏮️ **Pydantic** & 🎏 🍕 FastAPI.
+🕐❔ 👆 ⚙️ `async` 👩🔬, **FastAPI** 🏃 📁 👩🔬 🧵 & ⌛ 👫.
+
+///
+
+/// note | 💃 📡 ℹ
+
+**FastAPI**'Ⓜ `UploadFile` 😖 🔗 ⚪️➡️ **💃**'Ⓜ `UploadFile`, ✋️ 🚮 💪 🍕 ⚒ ⚫️ 🔗 ⏮️ **Pydantic** & 🎏 🍕 FastAPI.
+
+///
## ⚫️❔ "📨 💽"
@@ -102,41 +111,35 @@ contents = myfile.file.read()
**FastAPI** 🔜 ⚒ 💭 ✍ 👈 📊 ⚪️➡️ ▶️️ 🥉 ↩️ 🎻.
-!!! note "📡 ℹ"
- 📊 ⚪️➡️ 📨 🛎 🗜 ⚙️ "📻 🆎" `application/x-www-form-urlencoded` 🕐❔ ⚫️ 🚫 🔌 📁.
+/// note | 📡 ℹ
- ✋️ 🕐❔ 📨 🔌 📁, ⚫️ 🗜 `multipart/form-data`. 🚥 👆 ⚙️ `File`, **FastAPI** 🔜 💭 ⚫️ ✔️ 🤚 📁 ⚪️➡️ ☑ 🍕 💪.
+📊 ⚪️➡️ 📨 🛎 🗜 ⚙️ "📻 🆎" `application/x-www-form-urlencoded` 🕐❔ ⚫️ 🚫 🔌 📁.
- 🚥 👆 💚 ✍ 🌖 🔃 👉 🔢 & 📨 🏑, 👳 🏇 🕸 🩺 POST.
+✋️ 🕐❔ 📨 🔌 📁, ⚫️ 🗜 `multipart/form-data`. 🚥 👆 ⚙️ `File`, **FastAPI** 🔜 💭 ⚫️ ✔️ 🤚 📁 ⚪️➡️ ☑ 🍕 💪.
-!!! warning
- 👆 💪 📣 💗 `File` & `Form` 🔢 *➡ 🛠️*, ✋️ 👆 💪 🚫 📣 `Body` 🏑 👈 👆 ⌛ 📨 🎻, 📨 🔜 ✔️ 💪 🗜 ⚙️ `multipart/form-data` ↩️ `application/json`.
+🚥 👆 💚 ✍ 🌖 🔃 👉 🔢 & 📨 🏑, 👳 🏇 🕸 🩺 POST.
- 👉 🚫 🚫 **FastAPI**, ⚫️ 🍕 🇺🇸🔍 🛠️.
+///
+
+/// warning
+
+👆 💪 📣 💗 `File` & `Form` 🔢 *➡ 🛠️*, ✋️ 👆 💪 🚫 📣 `Body` 🏑 👈 👆 ⌛ 📨 🎻, 📨 🔜 ✔️ 💪 🗜 ⚙️ `multipart/form-data` ↩️ `application/json`.
+
+👉 🚫 🚫 **FastAPI**, ⚫️ 🍕 🇺🇸🔍 🛠️.
+
+///
## 📦 📁 📂
👆 💪 ⚒ 📁 📦 ⚙️ 🐩 🆎 ✍ & ⚒ 🔢 💲 `None`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="9 17"
- {!> ../../../docs_src/request_files/tutorial001_02.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="7 14"
- {!> ../../../docs_src/request_files/tutorial001_02_py310.py!}
- ```
+{* ../../docs_src/request_files/tutorial001_02.py hl[9,17] *}
## `UploadFile` ⏮️ 🌖 🗃
👆 💪 ⚙️ `File()` ⏮️ `UploadFile`, 🖼, ⚒ 🌖 🗃:
-```Python hl_lines="13"
-{!../../../docs_src/request_files/tutorial001_03.py!}
-```
+{* ../../docs_src/request_files/tutorial001_03.py hl[13] *}
## 💗 📁 📂
@@ -146,40 +149,23 @@ contents = myfile.file.read()
⚙️ 👈, 📣 📇 `bytes` ⚖️ `UploadFile`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="10 15"
- {!> ../../../docs_src/request_files/tutorial002.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="8 13"
- {!> ../../../docs_src/request_files/tutorial002_py39.py!}
- ```
+{* ../../docs_src/request_files/tutorial002.py hl[10,15] *}
👆 🔜 📨, 📣, `list` `bytes` ⚖️ `UploadFile`Ⓜ.
-!!! note "📡 ℹ"
- 👆 💪 ⚙️ `from starlette.responses import HTMLResponse`.
+/// note | 📡 ℹ
- **FastAPI** 🚚 🎏 `starlette.responses` `fastapi.responses` 🏪 👆, 👩💻. ✋️ 🌅 💪 📨 👟 🔗 ⚪️➡️ 💃.
+👆 💪 ⚙️ `from starlette.responses import HTMLResponse`.
+
+**FastAPI** 🚚 🎏 `starlette.responses` `fastapi.responses` 🏪 👆, 👩💻. ✋️ 🌅 💪 📨 👟 🔗 ⚪️➡️ 💃.
+
+///
### 💗 📁 📂 ⏮️ 🌖 🗃
& 🎏 🌌 ⏭, 👆 💪 ⚙️ `File()` ⚒ 🌖 🔢, `UploadFile`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/request_files/tutorial003.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="16"
- {!> ../../../docs_src/request_files/tutorial003_py39.py!}
- ```
+{* ../../docs_src/request_files/tutorial003.py hl[18] *}
## 🌃
diff --git a/docs/em/docs/tutorial/request-forms-and-files.md b/docs/em/docs/tutorial/request-forms-and-files.md
index 0415dbf01..680b1a96a 100644
--- a/docs/em/docs/tutorial/request-forms-and-files.md
+++ b/docs/em/docs/tutorial/request-forms-and-files.md
@@ -2,33 +2,35 @@
👆 💪 🔬 📁 & 📨 🏑 🎏 🕰 ⚙️ `File` & `Form`.
-!!! info
- 📨 📂 📁 & /⚖️ 📨 📊, 🥇 ❎ `python-multipart`.
+/// info
- 🤶 Ⓜ. `pip install python-multipart`.
+📨 📂 📁 & /⚖️ 📨 📊, 🥇 ❎ `python-multipart`.
+
+🤶 Ⓜ. `pip install python-multipart`.
+
+///
## 🗄 `File` & `Form`
-```Python hl_lines="1"
-{!../../../docs_src/request_forms_and_files/tutorial001.py!}
-```
+{* ../../docs_src/request_forms_and_files/tutorial001.py hl[1] *}
## 🔬 `File` & `Form` 🔢
✍ 📁 & 📨 🔢 🎏 🌌 👆 🔜 `Body` ⚖️ `Query`:
-```Python hl_lines="8"
-{!../../../docs_src/request_forms_and_files/tutorial001.py!}
-```
+{* ../../docs_src/request_forms_and_files/tutorial001.py hl[8] *}
📁 & 📨 🏑 🔜 📂 📨 📊 & 👆 🔜 📨 📁 & 📨 🏑.
& 👆 💪 📣 📁 `bytes` & `UploadFile`.
-!!! warning
- 👆 💪 📣 💗 `File` & `Form` 🔢 *➡ 🛠️*, ✋️ 👆 💪 🚫 📣 `Body` 🏑 👈 👆 ⌛ 📨 🎻, 📨 🔜 ✔️ 💪 🗜 ⚙️ `multipart/form-data` ↩️ `application/json`.
+/// warning
- 👉 🚫 🚫 **FastAPI**, ⚫️ 🍕 🇺🇸🔍 🛠️.
+👆 💪 📣 💗 `File` & `Form` 🔢 *➡ 🛠️*, ✋️ 👆 💪 🚫 📣 `Body` 🏑 👈 👆 ⌛ 📨 🎻, 📨 🔜 ✔️ 💪 🗜 ⚙️ `multipart/form-data` ↩️ `application/json`.
+
+👉 🚫 🚫 **FastAPI**, ⚫️ 🍕 🇺🇸🔍 🛠️.
+
+///
## 🌃
diff --git a/docs/em/docs/tutorial/request-forms.md b/docs/em/docs/tutorial/request-forms.md
index f12d6e650..1cc1ea5dc 100644
--- a/docs/em/docs/tutorial/request-forms.md
+++ b/docs/em/docs/tutorial/request-forms.md
@@ -2,26 +2,25 @@
🕐❔ 👆 💪 📨 📨 🏑 ↩️ 🎻, 👆 💪 ⚙️ `Form`.
-!!! info
- ⚙️ 📨, 🥇 ❎ `python-multipart`.
+/// info
- 🤶 Ⓜ. `pip install python-multipart`.
+⚙️ 📨, 🥇 ❎ `python-multipart`.
+
+🤶 Ⓜ. `pip install python-multipart`.
+
+///
## 🗄 `Form`
🗄 `Form` ⚪️➡️ `fastapi`:
-```Python hl_lines="1"
-{!../../../docs_src/request_forms/tutorial001.py!}
-```
+{* ../../docs_src/request_forms/tutorial001.py hl[1] *}
## 🔬 `Form` 🔢
✍ 📨 🔢 🎏 🌌 👆 🔜 `Body` ⚖️ `Query`:
-```Python hl_lines="7"
-{!../../../docs_src/request_forms/tutorial001.py!}
-```
+{* ../../docs_src/request_forms/tutorial001.py hl[7] *}
🖼, 1️⃣ 🌌 Oauth2️⃣ 🔧 💪 ⚙️ (🤙 "🔐 💧") ⚫️ ✔ 📨 `username` & `password` 📨 🏑.
@@ -29,11 +28,17 @@
⏮️ `Form` 👆 💪 📣 🎏 📳 ⏮️ `Body` (& `Query`, `Path`, `Cookie`), 🔌 🔬, 🖼, 📛 (✅ `user-name` ↩️ `username`), ♒️.
-!!! info
- `Form` 🎓 👈 😖 🔗 ⚪️➡️ `Body`.
+/// info
-!!! tip
- 📣 📨 💪, 👆 💪 ⚙️ `Form` 🎯, ↩️ 🍵 ⚫️ 🔢 🔜 🔬 🔢 🔢 ⚖️ 💪 (🎻) 🔢.
+`Form` 🎓 👈 😖 🔗 ⚪️➡️ `Body`.
+
+///
+
+/// tip
+
+📣 📨 💪, 👆 💪 ⚙️ `Form` 🎯, ↩️ 🍵 ⚫️ 🔢 🔜 🔬 🔢 🔢 ⚖️ 💪 (🎻) 🔢.
+
+///
## 🔃 "📨 🏑"
@@ -41,17 +46,23 @@
**FastAPI** 🔜 ⚒ 💭 ✍ 👈 📊 ⚪️➡️ ▶️️ 🥉 ↩️ 🎻.
-!!! note "📡 ℹ"
- 📊 ⚪️➡️ 📨 🛎 🗜 ⚙️ "📻 🆎" `application/x-www-form-urlencoded`.
+/// note | 📡 ℹ
- ✋️ 🕐❔ 📨 🔌 📁, ⚫️ 🗜 `multipart/form-data`. 👆 🔜 ✍ 🔃 🚚 📁 ⏭ 📃.
+📊 ⚪️➡️ 📨 🛎 🗜 ⚙️ "📻 🆎" `application/x-www-form-urlencoded`.
- 🚥 👆 💚 ✍ 🌖 🔃 👉 🔢 & 📨 🏑, 👳 🏇 🕸 🩺 POST.
+✋️ 🕐❔ 📨 🔌 📁, ⚫️ 🗜 `multipart/form-data`. 👆 🔜 ✍ 🔃 🚚 📁 ⏭ 📃.
-!!! warning
- 👆 💪 📣 💗 `Form` 🔢 *➡ 🛠️*, ✋️ 👆 💪 🚫 📣 `Body` 🏑 👈 👆 ⌛ 📨 🎻, 📨 🔜 ✔️ 💪 🗜 ⚙️ `application/x-www-form-urlencoded` ↩️ `application/json`.
+🚥 👆 💚 ✍ 🌖 🔃 👉 🔢 & 📨 🏑, 👳 🏇 🕸 🩺 POST.
- 👉 🚫 🚫 **FastAPI**, ⚫️ 🍕 🇺🇸🔍 🛠️.
+///
+
+/// warning
+
+👆 💪 📣 💗 `Form` 🔢 *➡ 🛠️*, ✋️ 👆 💪 🚫 📣 `Body` 🏑 👈 👆 ⌛ 📨 🎻, 📨 🔜 ✔️ 💪 🗜 ⚙️ `application/x-www-form-urlencoded` ↩️ `application/json`.
+
+👉 🚫 🚫 **FastAPI**, ⚫️ 🍕 🇺🇸🔍 🛠️.
+
+///
## 🌃
diff --git a/docs/em/docs/tutorial/response-model.md b/docs/em/docs/tutorial/response-model.md
index 7103e9176..477376458 100644
--- a/docs/em/docs/tutorial/response-model.md
+++ b/docs/em/docs/tutorial/response-model.md
@@ -4,23 +4,7 @@
👆 💪 ⚙️ **🆎 ✍** 🎏 🌌 👆 🔜 🔢 💽 🔢 **🔢**, 👆 💪 ⚙️ Pydantic 🏷, 📇, 📖, 📊 💲 💖 🔢, 🎻, ♒️.
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="18 23"
- {!> ../../../docs_src/response_model/tutorial001_01.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="18 23"
- {!> ../../../docs_src/response_model/tutorial001_01_py39.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="16 21"
- {!> ../../../docs_src/response_model/tutorial001_01_py310.py!}
- ```
+{* ../../docs_src/response_model/tutorial001_01.py hl[18,23] *}
FastAPI 🔜 ⚙️ 👉 📨 🆎:
@@ -53,35 +37,25 @@ FastAPI 🔜 ⚙️ 👉 📨 🆎:
* `@app.delete()`
* ♒️.
-=== "🐍 3️⃣.6️⃣ & 🔛"
+{* ../../docs_src/response_model/tutorial001.py hl[17,22,24:27] *}
- ```Python hl_lines="17 22 24-27"
- {!> ../../../docs_src/response_model/tutorial001.py!}
- ```
+/// note
-=== "🐍 3️⃣.9️⃣ & 🔛"
+👀 👈 `response_model` 🔢 "👨🎨" 👩🔬 (`get`, `post`, ♒️). 🚫 👆 *➡ 🛠️ 🔢*, 💖 🌐 🔢 & 💪.
- ```Python hl_lines="17 22 24-27"
- {!> ../../../docs_src/response_model/tutorial001_py39.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="17 22 24-27"
- {!> ../../../docs_src/response_model/tutorial001_py310.py!}
- ```
-
-!!! note
- 👀 👈 `response_model` 🔢 "👨🎨" 👩🔬 (`get`, `post`, ♒️). 🚫 👆 *➡ 🛠️ 🔢*, 💖 🌐 🔢 & 💪.
+///
`response_model` 📨 🎏 🆎 👆 🔜 📣 Pydantic 🏷 🏑,, ⚫️ 💪 Pydantic 🏷, ✋️ ⚫️ 💪, ✅ `list` Pydantic 🏷, 💖 `List[Item]`.
FastAPI 🔜 ⚙️ 👉 `response_model` 🌐 💽 🧾, 🔬, ♒️. & **🗜 & ⛽ 🔢 📊** 🚮 🆎 📄.
-!!! tip
- 🚥 👆 ✔️ ⚠ 🆎 ✅ 👆 👨🎨, ✍, ♒️, 👆 💪 📣 🔢 📨 🆎 `Any`.
+/// tip
- 👈 🌌 👆 💬 👨🎨 👈 👆 😫 🛬 🕳. ✋️ FastAPI 🔜 💽 🧾, 🔬, 🖥, ♒️. ⏮️ `response_model`.
+🚥 👆 ✔️ ⚠ 🆎 ✅ 👆 👨🎨, ✍, ♒️, 👆 💪 📣 🔢 📨 🆎 `Any`.
+
+👈 🌌 👆 💬 👨🎨 👈 👆 😫 🛬 🕳. ✋️ FastAPI 🔜 💽 🧾, 🔬, 🖥, ♒️. ⏮️ `response_model`.
+
+///
### `response_model` 📫
@@ -95,37 +69,20 @@ FastAPI 🔜 ⚙️ 👉 `response_model` 🌐 💽 🧾, 🔬, ♒️. & **
📥 👥 📣 `UserIn` 🏷, ⚫️ 🔜 🔌 🔢 🔐:
-=== "🐍 3️⃣.6️⃣ & 🔛"
+{* ../../docs_src/response_model/tutorial002.py hl[9,11] *}
- ```Python hl_lines="9 11"
- {!> ../../../docs_src/response_model/tutorial002.py!}
- ```
+/// info
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
+⚙️ `EmailStr`, 🥇 ❎ `email-validator`.
- ```Python hl_lines="7 9"
- {!> ../../../docs_src/response_model/tutorial002_py310.py!}
- ```
+🤶 Ⓜ. `pip install email-validator`
+⚖️ `pip install pydantic[email]`.
-!!! info
- ⚙️ `EmailStr`, 🥇 ❎ `email_validator`.
-
- 🤶 Ⓜ. `pip install email-validator`
- ⚖️ `pip install pydantic[email]`.
+///
& 👥 ⚙️ 👉 🏷 📣 👆 🔢 & 🎏 🏷 📣 👆 🔢:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/response_model/tutorial002.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="16"
- {!> ../../../docs_src/response_model/tutorial002_py310.py!}
- ```
+{* ../../docs_src/response_model/tutorial002.py hl[18] *}
🔜, 🕐❔ 🖥 🏗 👩💻 ⏮️ 🔐, 🛠️ 🔜 📨 🎏 🔐 📨.
@@ -133,52 +90,25 @@ FastAPI 🔜 ⚙️ 👉 `response_model` 🌐 💽 🧾, 🔬, ♒️. & **
✋️ 🚥 👥 ⚙️ 🎏 🏷 ➕1️⃣ *➡ 🛠️*, 👥 💪 📨 👆 👩💻 🔐 🔠 👩💻.
-!!! danger
- 🙅 🏪 ✅ 🔐 👩💻 ⚖️ 📨 ⚫️ 📨 💖 👉, 🚥 👆 💭 🌐 ⚠ & 👆 💭 ⚫️❔ 👆 🔨.
+/// danger
+
+🙅 🏪 ✅ 🔐 👩💻 ⚖️ 📨 ⚫️ 📨 💖 👉, 🚥 👆 💭 🌐 ⚠ & 👆 💭 ⚫️❔ 👆 🔨.
+
+///
## 🚮 🔢 🏷
👥 💪 ↩️ ✍ 🔢 🏷 ⏮️ 🔢 🔐 & 🔢 🏷 🍵 ⚫️:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="9 11 16"
- {!> ../../../docs_src/response_model/tutorial003.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="9 11 16"
- {!> ../../../docs_src/response_model/tutorial003_py310.py!}
- ```
+{* ../../docs_src/response_model/tutorial003.py hl[9,11,16] *}
📥, ✋️ 👆 *➡ 🛠️ 🔢* 🛬 🎏 🔢 👩💻 👈 🔌 🔐:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="24"
- {!> ../../../docs_src/response_model/tutorial003.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="24"
- {!> ../../../docs_src/response_model/tutorial003_py310.py!}
- ```
+{* ../../docs_src/response_model/tutorial003.py hl[24] *}
...👥 📣 `response_model` 👆 🏷 `UserOut`, 👈 🚫 🔌 🔐:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/response_model/tutorial003.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/response_model/tutorial003_py310.py!}
- ```
+{* ../../docs_src/response_model/tutorial003.py hl[22] *}
, **FastAPI** 🔜 ✊ 💅 🖥 👅 🌐 💽 👈 🚫 📣 🔢 🏷 (⚙️ Pydantic).
@@ -202,17 +132,7 @@ FastAPI 🔜 ⚙️ 👉 `response_model` 🌐 💽 🧾, 🔬, ♒️. & **
& 👈 💼, 👥 💪 ⚙️ 🎓 & 🧬 ✊ 📈 🔢 **🆎 ✍** 🤚 👍 🐕🦺 👨🎨 & 🧰, & 🤚 FastAPI **💽 🖥**.
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="9-13 15-16 20"
- {!> ../../../docs_src/response_model/tutorial003_01.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="7-10 13-14 18"
- {!> ../../../docs_src/response_model/tutorial003_01_py310.py!}
- ```
+{* ../../docs_src/response_model/tutorial003_01.py hl[9:13,15:16,20] *}
⏮️ 👉, 👥 🤚 🏭 🐕🦺, ⚪️➡️ 👨🎨 & ✍ 👉 📟 ☑ ⚖ 🆎, ✋️ 👥 🤚 💽 🖥 ⚪️➡️ FastAPI.
@@ -254,9 +174,7 @@ FastAPI 🔨 📚 👜 🔘 ⏮️ Pydantic ⚒ 💭 👈 📚 🎏 🚫 🎓
🏆 ⚠ 💼 🔜 [🛬 📨 🔗 🔬 ⏪ 🏧 🩺](../advanced/response-directly.md){.internal-link target=_blank}.
-```Python hl_lines="8 10-11"
-{!> ../../../docs_src/response_model/tutorial003_02.py!}
-```
+{* ../../docs_src/response_model/tutorial003_02.py hl[8,10:11] *}
👉 🙅 💼 🍵 🔁 FastAPI ↩️ 📨 🆎 ✍ 🎓 (⚖️ 🏿) `Response`.
@@ -266,9 +184,7 @@ FastAPI 🔨 📚 👜 🔘 ⏮️ Pydantic ⚒ 💭 👈 📚 🎏 🚫 🎓
👆 💪 ⚙️ 🏿 `Response` 🆎 ✍:
-```Python hl_lines="8-9"
-{!> ../../../docs_src/response_model/tutorial003_03.py!}
-```
+{* ../../docs_src/response_model/tutorial003_03.py hl[8:9] *}
👉 🔜 👷 ↩️ `RedirectResponse` 🏿 `Response`, & FastAPI 🔜 🔁 🍵 👉 🙅 💼.
@@ -278,17 +194,7 @@ FastAPI 🔨 📚 👜 🔘 ⏮️ Pydantic ⚒ 💭 👈 📚 🎏 🚫 🎓
🎏 🔜 🔨 🚥 👆 ✔️ 🕳 💖 🇪🇺 🖖 🎏 🆎 🌐❔ 1️⃣ ⚖️ 🌅 👫 🚫 ☑ Pydantic 🆎, 🖼 👉 🔜 ❌ 👶:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/response_model/tutorial003_04.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/response_model/tutorial003_04_py310.py!}
- ```
+{* ../../docs_src/response_model/tutorial003_04.py hl[10] *}
...👉 ❌ ↩️ 🆎 ✍ 🚫 Pydantic 🆎 & 🚫 👁 `Response` 🎓 ⚖️ 🏿, ⚫️ 🇪🇺 (🙆 2️⃣) 🖖 `Response` & `dict`.
@@ -300,17 +206,7 @@ FastAPI 🔨 📚 👜 🔘 ⏮️ Pydantic ⚒ 💭 👈 📚 🎏 🚫 🎓
👉 💼, 👆 💪 ❎ 📨 🏷 ⚡ ⚒ `response_model=None`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/response_model/tutorial003_05.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/response_model/tutorial003_05_py310.py!}
- ```
+{* ../../docs_src/response_model/tutorial003_05.py hl[9] *}
👉 🔜 ⚒ FastAPI 🚶 📨 🏷 ⚡ & 👈 🌌 👆 💪 ✔️ 🙆 📨 🆎 ✍ 👆 💪 🍵 ⚫️ 🤕 👆 FastAPI 🈸. 👶
@@ -318,23 +214,7 @@ FastAPI 🔨 📚 👜 🔘 ⏮️ Pydantic ⚒ 💭 👈 📚 🎏 🚫 🎓
👆 📨 🏷 💪 ✔️ 🔢 💲, 💖:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="11 13-14"
- {!> ../../../docs_src/response_model/tutorial004.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="11 13-14"
- {!> ../../../docs_src/response_model/tutorial004_py39.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="9 11-12"
- {!> ../../../docs_src/response_model/tutorial004_py310.py!}
- ```
+{* ../../docs_src/response_model/tutorial004.py hl[11,13:14] *}
* `description: Union[str, None] = None` (⚖️ `str | None = None` 🐍 3️⃣.1️⃣0️⃣) ✔️ 🔢 `None`.
* `tax: float = 10.5` ✔️ 🔢 `10.5`.
@@ -348,23 +228,7 @@ FastAPI 🔨 📚 👜 🔘 ⏮️ Pydantic ⚒ 💭 👈 📚 🎏 🚫 🎓
👆 💪 ⚒ *➡ 🛠️ 👨🎨* 🔢 `response_model_exclude_unset=True`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="24"
- {!> ../../../docs_src/response_model/tutorial004.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="24"
- {!> ../../../docs_src/response_model/tutorial004_py39.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/response_model/tutorial004_py310.py!}
- ```
+{* ../../docs_src/response_model/tutorial004.py hl[24] *}
& 👈 🔢 💲 🏆 🚫 🔌 📨, 🕴 💲 🤙 ⚒.
@@ -377,16 +241,22 @@ FastAPI 🔨 📚 👜 🔘 ⏮️ Pydantic ⚒ 💭 👈 📚 🎏 🚫 🎓
}
```
-!!! info
- FastAPI ⚙️ Pydantic 🏷 `.dict()` ⏮️ 🚮 `exclude_unset` 🔢 🏆 👉.
+/// info
-!!! info
- 👆 💪 ⚙️:
+FastAPI ⚙️ Pydantic 🏷 `.dict()` ⏮️ 🚮 `exclude_unset` 🔢 🏆 👉.
- * `response_model_exclude_defaults=True`
- * `response_model_exclude_none=True`
+///
- 🔬 Pydantic 🩺 `exclude_defaults` & `exclude_none`.
+/// info
+
+👆 💪 ⚙️:
+
+* `response_model_exclude_defaults=True`
+* `response_model_exclude_none=True`
+
+🔬 Pydantic 🩺 `exclude_defaults` & `exclude_none`.
+
+///
#### 📊 ⏮️ 💲 🏑 ⏮️ 🔢
@@ -421,10 +291,13 @@ FastAPI 🙃 🥃 (🤙, Pydantic 🙃 🥃) 🤔 👈, ✋️ `description`, `t
, 👫 🔜 🔌 🎻 📨.
-!!! tip
- 👀 👈 🔢 💲 💪 🕳, 🚫 🕴 `None`.
+/// tip
- 👫 💪 📇 (`[]`), `float` `10.5`, ♒️.
+👀 👈 🔢 💲 💪 🕳, 🚫 🕴 `None`.
+
+👫 💪 📇 (`[]`), `float` `10.5`, ♒️.
+
+///
### `response_model_include` & `response_model_exclude`
@@ -434,45 +307,31 @@ FastAPI 🙃 🥃 (🤙, Pydantic 🙃 🥃) 🤔 👈, ✋️ `description`, `t
👉 💪 ⚙️ ⏩ ⌨ 🚥 👆 ✔️ 🕴 1️⃣ Pydantic 🏷 & 💚 ❎ 💽 ⚪️➡️ 🔢.
-!!! tip
- ✋️ ⚫️ 👍 ⚙️ 💭 🔛, ⚙️ 💗 🎓, ↩️ 👫 🔢.
+/// tip
- 👉 ↩️ 🎻 🔗 🏗 👆 📱 🗄 (& 🩺) 🔜 1️⃣ 🏁 🏷, 🚥 👆 ⚙️ `response_model_include` ⚖️ `response_model_exclude` 🚫 🔢.
+✋️ ⚫️ 👍 ⚙️ 💭 🔛, ⚙️ 💗 🎓, ↩️ 👫 🔢.
- 👉 ✔ `response_model_by_alias` 👈 👷 ➡.
+👉 ↩️ 🎻 🔗 🏗 👆 📱 🗄 (& 🩺) 🔜 1️⃣ 🏁 🏷, 🚥 👆 ⚙️ `response_model_include` ⚖️ `response_model_exclude` 🚫 🔢.
-=== "🐍 3️⃣.6️⃣ & 🔛"
+👉 ✔ `response_model_by_alias` 👈 👷 ➡.
- ```Python hl_lines="31 37"
- {!> ../../../docs_src/response_model/tutorial005.py!}
- ```
+///
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
+{* ../../docs_src/response_model/tutorial005.py hl[31,37] *}
- ```Python hl_lines="29 35"
- {!> ../../../docs_src/response_model/tutorial005_py310.py!}
- ```
+/// tip
-!!! tip
- ❕ `{"name", "description"}` ✍ `set` ⏮️ 📚 2️⃣ 💲.
+❕ `{"name", "description"}` ✍ `set` ⏮️ 📚 2️⃣ 💲.
- ⚫️ 🌓 `set(["name", "description"])`.
+⚫️ 🌓 `set(["name", "description"])`.
+
+///
#### ⚙️ `list`Ⓜ ↩️ `set`Ⓜ
🚥 👆 💭 ⚙️ `set` & ⚙️ `list` ⚖️ `tuple` ↩️, FastAPI 🔜 🗜 ⚫️ `set` & ⚫️ 🔜 👷 ☑:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="31 37"
- {!> ../../../docs_src/response_model/tutorial006.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="29 35"
- {!> ../../../docs_src/response_model/tutorial006_py310.py!}
- ```
+{* ../../docs_src/response_model/tutorial006.py hl[31,37] *}
## 🌃
diff --git a/docs/em/docs/tutorial/response-status-code.md b/docs/em/docs/tutorial/response-status-code.md
index e5149de7d..413ceb916 100644
--- a/docs/em/docs/tutorial/response-status-code.md
+++ b/docs/em/docs/tutorial/response-status-code.md
@@ -8,17 +8,21 @@
* `@app.delete()`
* ♒️.
-```Python hl_lines="6"
-{!../../../docs_src/response_status_code/tutorial001.py!}
-```
+{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
-!!! note
- 👀 👈 `status_code` 🔢 "👨🎨" 👩🔬 (`get`, `post`, ♒️). 🚫 👆 *➡ 🛠️ 🔢*, 💖 🌐 🔢 & 💪.
+/// note
+
+👀 👈 `status_code` 🔢 "👨🎨" 👩🔬 (`get`, `post`, ♒️). 🚫 👆 *➡ 🛠️ 🔢*, 💖 🌐 🔢 & 💪.
+
+///
`status_code` 🔢 📨 🔢 ⏮️ 🇺🇸🔍 👔 📟.
-!!! info
- `status_code` 💪 👐 📨 `IntEnum`, ✅ 🐍 `http.HTTPStatus`.
+/// info
+
+`status_code` 💪 👐 📨 `IntEnum`, ✅ 🐍 `http.HTTPStatus`.
+
+///
⚫️ 🔜:
@@ -27,15 +31,21 @@
-!!! note
- 📨 📟 (👀 ⏭ 📄) 🎦 👈 📨 🔨 🚫 ✔️ 💪.
+/// note
- FastAPI 💭 👉, & 🔜 🏭 🗄 🩺 👈 🇵🇸 📤 🙅♂ 📨 💪.
+📨 📟 (👀 ⏭ 📄) 🎦 👈 📨 🔨 🚫 ✔️ 💪.
+
+FastAPI 💭 👉, & 🔜 🏭 🗄 🩺 👈 🇵🇸 📤 🙅♂ 📨 💪.
+
+///
## 🔃 🇺🇸🔍 👔 📟
-!!! note
- 🚥 👆 ⏪ 💭 ⚫️❔ 🇺🇸🔍 👔 📟, 🚶 ⏭ 📄.
+/// note
+
+🚥 👆 ⏪ 💭 ⚫️❔ 🇺🇸🔍 👔 📟, 🚶 ⏭ 📄.
+
+///
🇺🇸🔍, 👆 📨 🔢 👔 📟 3️⃣ 9️⃣ 🍕 📨.
@@ -54,16 +64,17 @@
* 💊 ❌ ⚪️➡️ 👩💻, 👆 💪 ⚙️ `400`.
* `500` & 🔛 💽 ❌. 👆 🌖 🙅 ⚙️ 👫 🔗. 🕐❔ 🕳 🚶 ❌ 🍕 👆 🈸 📟, ⚖️ 💽, ⚫️ 🔜 🔁 📨 1️⃣ 👫 👔 📟.
-!!! tip
- 💭 🌅 🔃 🔠 👔 📟 & ❔ 📟 ⚫️❔, ✅ 🏇 🧾 🔃 🇺🇸🔍 👔 📟.
+/// tip
+
+💭 🌅 🔃 🔠 👔 📟 & ❔ 📟 ⚫️❔, ✅ 🏇 🧾 🔃 🇺🇸🔍 👔 📟.
+
+///
## ⌨ 💭 📛
➡️ 👀 ⏮️ 🖼 🔄:
-```Python hl_lines="6"
-{!../../../docs_src/response_status_code/tutorial001.py!}
-```
+{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
`201` 👔 📟 "✍".
@@ -71,18 +82,19 @@
👆 💪 ⚙️ 🏪 🔢 ⚪️➡️ `fastapi.status`.
-```Python hl_lines="1 6"
-{!../../../docs_src/response_status_code/tutorial002.py!}
-```
+{* ../../docs_src/response_status_code/tutorial002.py hl[1,6] *}
👫 🏪, 👫 🧑🤝🧑 🎏 🔢, ✋️ 👈 🌌 👆 💪 ⚙️ 👨🎨 📋 🔎 👫:
-!!! note "📡 ℹ"
- 👆 💪 ⚙️ `from starlette import status`.
+/// note | 📡 ℹ
- **FastAPI** 🚚 🎏 `starlette.status` `fastapi.status` 🏪 👆, 👩💻. ✋️ ⚫️ 👟 🔗 ⚪️➡️ 💃.
+👆 💪 ⚙️ `from starlette import status`.
+
+**FastAPI** 🚚 🎏 `starlette.status` `fastapi.status` 🏪 👆, 👩💻. ✋️ ⚫️ 👟 🔗 ⚪️➡️ 💃.
+
+///
## 🔀 🔢
diff --git a/docs/em/docs/tutorial/schema-extra-example.md b/docs/em/docs/tutorial/schema-extra-example.md
index 114d5a84a..1bd314c51 100644
--- a/docs/em/docs/tutorial/schema-extra-example.md
+++ b/docs/em/docs/tutorial/schema-extra-example.md
@@ -8,24 +8,17 @@
👆 💪 📣 `example` Pydantic 🏷 ⚙️ `Config` & `schema_extra`, 🔬 Pydantic 🩺: 🔗 🛃:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="15-23"
- {!> ../../../docs_src/schema_extra_example/tutorial001.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="13-21"
- {!> ../../../docs_src/schema_extra_example/tutorial001_py310.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial001.py hl[15:23] *}
👈 ➕ ℹ 🔜 🚮-🔢 **🎻 🔗** 👈 🏷, & ⚫️ 🔜 ⚙️ 🛠️ 🩺.
-!!! tip
- 👆 💪 ⚙️ 🎏 ⚒ ↔ 🎻 🔗 & 🚮 👆 👍 🛃 ➕ ℹ.
+/// tip
- 🖼 👆 💪 ⚙️ ⚫️ 🚮 🗃 🕸 👩💻 🔢, ♒️.
+👆 💪 ⚙️ 🎏 ⚒ ↔ 🎻 🔗 & 🚮 👆 👍 🛃 ➕ ℹ.
+
+🖼 👆 💪 ⚙️ ⚫️ 🚮 🗃 🕸 👩💻 🔢, ♒️.
+
+///
## `Field` 🌖 ❌
@@ -33,20 +26,13 @@
👆 💪 ⚙️ 👉 🚮 `example` 🔠 🏑:
-=== "🐍 3️⃣.6️⃣ & 🔛"
+{* ../../docs_src/schema_extra_example/tutorial002.py hl[4,10:13] *}
- ```Python hl_lines="4 10-13"
- {!> ../../../docs_src/schema_extra_example/tutorial002.py!}
- ```
+/// warning
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
+🚧 🤯 👈 📚 ➕ ❌ 🚶♀️ 🏆 🚫 🚮 🙆 🔬, 🕴 ➕ ℹ, 🧾 🎯.
- ```Python hl_lines="2 8-11"
- {!> ../../../docs_src/schema_extra_example/tutorial002_py310.py!}
- ```
-
-!!! warning
- 🚧 🤯 👈 📚 ➕ ❌ 🚶♀️ 🏆 🚫 🚮 🙆 🔬, 🕴 ➕ ℹ, 🧾 🎯.
+///
## `example` & `examples` 🗄
@@ -66,17 +52,7 @@
📥 👥 🚶♀️ `example` 📊 ⌛ `Body()`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="20-25"
- {!> ../../../docs_src/schema_extra_example/tutorial003.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="18-23"
- {!> ../../../docs_src/schema_extra_example/tutorial003_py310.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial003.py hl[20:25] *}
### 🖼 🩺 🎚
@@ -97,17 +73,7 @@
* `value`: 👉 ☑ 🖼 🎦, ✅ `dict`.
* `externalValue`: 🎛 `value`, 📛 ☝ 🖼. 👐 👉 5️⃣📆 🚫 🐕🦺 📚 🧰 `value`.
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="21-47"
- {!> ../../../docs_src/schema_extra_example/tutorial004.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="19-45"
- {!> ../../../docs_src/schema_extra_example/tutorial004_py310.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial004.py hl[21:47] *}
### 🖼 🩺 🎚
@@ -117,10 +83,13 @@
## 📡 ℹ
-!!! warning
- 👉 📶 📡 ℹ 🔃 🐩 **🎻 🔗** & **🗄**.
+/// warning
- 🚥 💭 🔛 ⏪ 👷 👆, 👈 💪 🥃, & 👆 🎲 🚫 💪 👉 ℹ, 💭 🆓 🚶 👫.
+👉 📶 📡 ℹ 🔃 🐩 **🎻 🔗** & **🗄**.
+
+🚥 💭 🔛 ⏪ 👷 👆, 👈 💪 🥃, & 👆 🎲 🚫 💪 👉 ℹ, 💭 🆓 🚶 👫.
+
+///
🕐❔ 👆 🚮 🖼 🔘 Pydantic 🏷, ⚙️ `schema_extra` ⚖️ `Field(example="something")` 👈 🖼 🚮 **🎻 🔗** 👈 Pydantic 🏷.
diff --git a/docs/em/docs/tutorial/security/first-steps.md b/docs/em/docs/tutorial/security/first-steps.md
index 8c2c95cfd..8fb459a65 100644
--- a/docs/em/docs/tutorial/security/first-steps.md
+++ b/docs/em/docs/tutorial/security/first-steps.md
@@ -20,18 +20,19 @@
📁 🖼 📁 `main.py`:
-```Python
-{!../../../docs_src/security/tutorial001.py!}
-```
+{* ../../docs_src/security/tutorial001.py *}
## 🏃 ⚫️
-!!! info
- 🥇 ❎ `python-multipart`.
+/// info
- 🤶 Ⓜ. `pip install python-multipart`.
+🥇 ❎ `python-multipart`.
- 👉 ↩️ **Oauth2️⃣** ⚙️ "📨 📊" 📨 `username` & `password`.
+🤶 Ⓜ. `pip install python-multipart`.
+
+👉 ↩️ **Oauth2️⃣** ⚙️ "📨 📊" 📨 `username` & `password`.
+
+///
🏃 🖼 ⏮️:
@@ -53,17 +54,23 @@ $ uvicorn main:app --reload
-!!! check "✔ 🔼 ❗"
- 👆 ⏪ ✔️ ✨ 🆕 "✔" 🔼.
+/// check | ✔ 🔼 ❗
- & 👆 *➡ 🛠️* ✔️ 🐥 🔒 🔝-▶️️ ↩ 👈 👆 💪 🖊.
+👆 ⏪ ✔️ ✨ 🆕 "✔" 🔼.
+
+ & 👆 *➡ 🛠️* ✔️ 🐥 🔒 🔝-▶️️ ↩ 👈 👆 💪 🖊.
+
+///
& 🚥 👆 🖊 ⚫️, 👆 ✔️ 🐥 ✔ 📨 🆎 `username` & `password` (& 🎏 📦 🏑):
-!!! note
- ⚫️ 🚫 🤔 ⚫️❔ 👆 🆎 📨, ⚫️ 🏆 🚫 👷. ✋️ 👥 🔜 🤚 📤.
+/// note
+
+⚫️ 🚫 🤔 ⚫️❔ 👆 🆎 📨, ⚫️ 🏆 🚫 👷. ✋️ 👥 🔜 🤚 📤.
+
+///
👉 ↗️ 🚫 🕸 🏁 👩💻, ✋️ ⚫️ 👑 🏧 🧰 📄 🖥 🌐 👆 🛠️.
@@ -105,36 +112,43 @@ Oauth2️⃣ 🔧 👈 👩💻 ⚖️ 🛠️ 💪 🔬 💽 👈 🔓 👩
👉 🖼 👥 🔜 ⚙️ **Oauth2️⃣**, ⏮️ **🔐** 💧, ⚙️ **📨** 🤝. 👥 👈 ⚙️ `OAuth2PasswordBearer` 🎓.
-!!! info
- "📨" 🤝 🚫 🕴 🎛.
+/// info
- ✋️ ⚫️ 🏆 1️⃣ 👆 ⚙️ 💼.
+"📨" 🤝 🚫 🕴 🎛.
- & ⚫️ 💪 🏆 🏆 ⚙️ 💼, 🚥 👆 Oauth2️⃣ 🕴 & 💭 ⚫️❔ ⚫️❔ 📤 ➕1️⃣ 🎛 👈 ♣ 👻 👆 💪.
+✋️ ⚫️ 🏆 1️⃣ 👆 ⚙️ 💼.
- 👈 💼, **FastAPI** 🚚 👆 ⏮️ 🧰 🏗 ⚫️.
+ & ⚫️ 💪 🏆 🏆 ⚙️ 💼, 🚥 👆 Oauth2️⃣ 🕴 & 💭 ⚫️❔ ⚫️❔ 📤 ➕1️⃣ 🎛 👈 ♣ 👻 👆 💪.
+
+👈 💼, **FastAPI** 🚚 👆 ⏮️ 🧰 🏗 ⚫️.
+
+///
🕐❔ 👥 ✍ 👐 `OAuth2PasswordBearer` 🎓 👥 🚶♀️ `tokenUrl` 🔢. 👉 🔢 🔌 📛 👈 👩💻 (🕸 🏃 👩💻 🖥) 🔜 ⚙️ 📨 `username` & `password` ✔ 🤚 🤝.
-```Python hl_lines="6"
-{!../../../docs_src/security/tutorial001.py!}
-```
+{* ../../docs_src/security/tutorial001.py hl[6] *}
-!!! tip
- 📥 `tokenUrl="token"` 🔗 ⚖ 📛 `token` 👈 👥 🚫 ✍. ⚫️ ⚖ 📛, ⚫️ 🌓 `./token`.
+/// tip
- ↩️ 👥 ⚙️ ⚖ 📛, 🚥 👆 🛠️ 🔎 `https://example.com/`, ⤴️ ⚫️ 🔜 🔗 `https://example.com/token`. ✋️ 🚥 👆 🛠️ 🔎 `https://example.com/api/v1/`, ⤴️ ⚫️ 🔜 🔗 `https://example.com/api/v1/token`.
+📥 `tokenUrl="token"` 🔗 ⚖ 📛 `token` 👈 👥 🚫 ✍. ⚫️ ⚖ 📛, ⚫️ 🌓 `./token`.
- ⚙️ ⚖ 📛 ⚠ ⚒ 💭 👆 🈸 🚧 👷 🏧 ⚙️ 💼 💖 [⛅ 🗳](../../advanced/behind-a-proxy.md){.internal-link target=_blank}.
+↩️ 👥 ⚙️ ⚖ 📛, 🚥 👆 🛠️ 🔎 `https://example.com/`, ⤴️ ⚫️ 🔜 🔗 `https://example.com/token`. ✋️ 🚥 👆 🛠️ 🔎 `https://example.com/api/v1/`, ⤴️ ⚫️ 🔜 🔗 `https://example.com/api/v1/token`.
+
+⚙️ ⚖ 📛 ⚠ ⚒ 💭 👆 🈸 🚧 👷 🏧 ⚙️ 💼 💖 [⛅ 🗳](../../advanced/behind-a-proxy.md){.internal-link target=_blank}.
+
+///
👉 🔢 🚫 ✍ 👈 🔗 / *➡ 🛠️*, ✋️ 📣 👈 📛 `/token` 🔜 1️⃣ 👈 👩💻 🔜 ⚙️ 🤚 🤝. 👈 ℹ ⚙️ 🗄, & ⤴️ 🎓 🛠️ 🧾 ⚙️.
👥 🔜 🔜 ✍ ☑ ➡ 🛠️.
-!!! info
- 🚥 👆 📶 ⚠ "✍" 👆 💪 👎 👗 🔢 📛 `tokenUrl` ↩️ `token_url`.
+/// info
- 👈 ↩️ ⚫️ ⚙️ 🎏 📛 🗄 🔌. 👈 🚥 👆 💪 🔬 🌅 🔃 🙆 👫 💂♂ ⚖ 👆 💪 📁 & 📋 ⚫️ 🔎 🌖 ℹ 🔃 ⚫️.
+🚥 👆 📶 ⚠ "✍" 👆 💪 👎 👗 🔢 📛 `tokenUrl` ↩️ `token_url`.
+
+👈 ↩️ ⚫️ ⚙️ 🎏 📛 🗄 🔌. 👈 🚥 👆 💪 🔬 🌅 🔃 🙆 👫 💂♂ ⚖ 👆 💪 📁 & 📋 ⚫️ 🔎 🌖 ℹ 🔃 ⚫️.
+
+///
`oauth2_scheme` 🔢 👐 `OAuth2PasswordBearer`, ✋️ ⚫️ "🇧🇲".
@@ -150,18 +164,19 @@ oauth2_scheme(some, parameters)
🔜 👆 💪 🚶♀️ 👈 `oauth2_scheme` 🔗 ⏮️ `Depends`.
-```Python hl_lines="10"
-{!../../../docs_src/security/tutorial001.py!}
-```
+{* ../../docs_src/security/tutorial001.py hl[10] *}
👉 🔗 🔜 🚚 `str` 👈 🛠️ 🔢 `token` *➡ 🛠️ 🔢*.
**FastAPI** 🔜 💭 👈 ⚫️ 💪 ⚙️ 👉 🔗 🔬 "💂♂ ⚖" 🗄 🔗 (& 🏧 🛠️ 🩺).
-!!! info "📡 ℹ"
- **FastAPI** 🔜 💭 👈 ⚫️ 💪 ⚙️ 🎓 `OAuth2PasswordBearer` (📣 🔗) 🔬 💂♂ ⚖ 🗄 ↩️ ⚫️ 😖 ⚪️➡️ `fastapi.security.oauth2.OAuth2`, ❔ 🔄 😖 ⚪️➡️ `fastapi.security.base.SecurityBase`.
+/// info | 📡 ℹ
- 🌐 💂♂ 🚙 👈 🛠️ ⏮️ 🗄 (& 🏧 🛠️ 🩺) 😖 ⚪️➡️ `SecurityBase`, 👈 ❔ **FastAPI** 💪 💭 ❔ 🛠️ 👫 🗄.
+**FastAPI** 🔜 💭 👈 ⚫️ 💪 ⚙️ 🎓 `OAuth2PasswordBearer` (📣 🔗) 🔬 💂♂ ⚖ 🗄 ↩️ ⚫️ 😖 ⚪️➡️ `fastapi.security.oauth2.OAuth2`, ❔ 🔄 😖 ⚪️➡️ `fastapi.security.base.SecurityBase`.
+
+🌐 💂♂ 🚙 👈 🛠️ ⏮️ 🗄 (& 🏧 🛠️ 🩺) 😖 ⚪️➡️ `SecurityBase`, 👈 ❔ **FastAPI** 💪 💭 ❔ 🛠️ 👫 🗄.
+
+///
## ⚫️❔ ⚫️ 🔨
diff --git a/docs/em/docs/tutorial/security/get-current-user.md b/docs/em/docs/tutorial/security/get-current-user.md
index 455cb4f46..2f4a26f35 100644
--- a/docs/em/docs/tutorial/security/get-current-user.md
+++ b/docs/em/docs/tutorial/security/get-current-user.md
@@ -2,9 +2,7 @@
⏮️ 📃 💂♂ ⚙️ (❔ 🧢 🔛 🔗 💉 ⚙️) 🤝 *➡ 🛠️ 🔢* `token` `str`:
-```Python hl_lines="10"
-{!../../../docs_src/security/tutorial001.py!}
-```
+{* ../../docs_src/security/tutorial001.py hl[10] *}
✋️ 👈 🚫 👈 ⚠.
@@ -16,17 +14,7 @@
🎏 🌌 👥 ⚙️ Pydantic 📣 💪, 👥 💪 ⚙️ ⚫️ 🙆 🙆:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="5 12-16"
- {!> ../../../docs_src/security/tutorial002.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="3 10-14"
- {!> ../../../docs_src/security/tutorial002_py310.py!}
- ```
+{* ../../docs_src/security/tutorial002.py hl[5,12:16] *}
## ✍ `get_current_user` 🔗
@@ -38,63 +26,39 @@
🎏 👥 🔨 ⏭ *➡ 🛠️* 🔗, 👆 🆕 🔗 `get_current_user` 🔜 📨 `token` `str` ⚪️➡️ 🎧-🔗 `oauth2_scheme`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="25"
- {!> ../../../docs_src/security/tutorial002.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="23"
- {!> ../../../docs_src/security/tutorial002_py310.py!}
- ```
+{* ../../docs_src/security/tutorial002.py hl[25] *}
## 🤚 👩💻
`get_current_user` 🔜 ⚙️ (❌) 🚙 🔢 👥 ✍, 👈 ✊ 🤝 `str` & 📨 👆 Pydantic `User` 🏷:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="19-22 26-27"
- {!> ../../../docs_src/security/tutorial002.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="17-20 24-25"
- {!> ../../../docs_src/security/tutorial002_py310.py!}
- ```
+{* ../../docs_src/security/tutorial002.py hl[19:22,26:27] *}
## 💉 ⏮️ 👩💻
🔜 👥 💪 ⚙️ 🎏 `Depends` ⏮️ 👆 `get_current_user` *➡ 🛠️*:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="31"
- {!> ../../../docs_src/security/tutorial002.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="29"
- {!> ../../../docs_src/security/tutorial002_py310.py!}
- ```
+{* ../../docs_src/security/tutorial002.py hl[31] *}
👀 👈 👥 📣 🆎 `current_user` Pydantic 🏷 `User`.
👉 🔜 ℹ 🇺🇲 🔘 🔢 ⏮️ 🌐 🛠️ & 🆎 ✅.
-!!! tip
- 👆 5️⃣📆 💭 👈 📨 💪 📣 ⏮️ Pydantic 🏷.
+/// tip
- 📥 **FastAPI** 🏆 🚫 🤚 😨 ↩️ 👆 ⚙️ `Depends`.
+👆 5️⃣📆 💭 👈 📨 💪 📣 ⏮️ Pydantic 🏷.
-!!! check
- 🌌 👉 🔗 ⚙️ 🏗 ✔ 👥 ✔️ 🎏 🔗 (🎏 "☑") 👈 🌐 📨 `User` 🏷.
+📥 **FastAPI** 🏆 🚫 🤚 😨 ↩️ 👆 ⚙️ `Depends`.
- 👥 🚫 🚫 ✔️ 🕴 1️⃣ 🔗 👈 💪 📨 👈 🆎 💽.
+///
+
+/// check
+
+🌌 👉 🔗 ⚙️ 🏗 ✔ 👥 ✔️ 🎏 🔗 (🎏 "☑") 👈 🌐 📨 `User` 🏷.
+
+👥 🚫 🚫 ✔️ 🕴 1️⃣ 🔗 👈 💪 📨 👈 🆎 💽.
+
+///
## 🎏 🏷
@@ -128,17 +92,7 @@
& 🌐 👉 💯 *➡ 🛠️* 💪 🤪 3️⃣ ⏸:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="30-32"
- {!> ../../../docs_src/security/tutorial002.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="28-30"
- {!> ../../../docs_src/security/tutorial002_py310.py!}
- ```
+{* ../../docs_src/security/tutorial002.py hl[30:32] *}
## 🌃
diff --git a/docs/em/docs/tutorial/security/index.md b/docs/em/docs/tutorial/security/index.md
index d76f7203f..1a47e5510 100644
--- a/docs/em/docs/tutorial/security/index.md
+++ b/docs/em/docs/tutorial/security/index.md
@@ -32,9 +32,11 @@ Oauth2️⃣ 🔧 👈 🔬 📚 🌌 🍵 🤝 & ✔.
Oauth2️⃣ 🚫 ✔ ❔ 🗜 📻, ⚫️ ⌛ 👆 ✔️ 👆 🈸 🍦 ⏮️ 🇺🇸🔍.
-!!! tip
- 📄 🔃 **🛠️** 👆 🔜 👀 ❔ ⚒ 🆙 🇺🇸🔍 🆓, ⚙️ Traefik & ➡️ 🗜.
+/// tip
+📄 🔃 **🛠️** 👆 🔜 👀 ❔ ⚒ 🆙 🇺🇸🔍 🆓, ⚙️ Traefik & ➡️ 🗜.
+
+///
## 👩💻 🔗
@@ -87,10 +89,13 @@ Oauth2️⃣ 🚫 ✔ ❔ 🗜 📻, ⚫️ ⌛ 👆 ✔️ 👆 🈸 🍦 ⏮
* 👉 🏧 🔍 ⚫️❔ 🔬 👩💻 🔗 🔧.
-!!! tip
- 🛠️ 🎏 🤝/✔ 🐕🦺 💖 🇺🇸🔍, 👱📔, 👱📔, 📂, ♒️. 💪 & 📶 ⏩.
+/// tip
- 🌅 🏗 ⚠ 🏗 🤝/✔ 🐕🦺 💖 👈, ✋️ **FastAPI** 🤝 👆 🧰 ⚫️ 💪, ⏪ 🔨 🏋️ 🏋♂ 👆.
+🛠️ 🎏 🤝/✔ 🐕🦺 💖 🇺🇸🔍, 👱📔, 👱📔, 📂, ♒️. 💪 & 📶 ⏩.
+
+🌅 🏗 ⚠ 🏗 🤝/✔ 🐕🦺 💖 👈, ✋️ **FastAPI** 🤝 👆 🧰 ⚫️ 💪, ⏪ 🔨 🏋️ 🏋♂ 👆.
+
+///
## **FastAPI** 🚙
diff --git a/docs/em/docs/tutorial/security/oauth2-jwt.md b/docs/em/docs/tutorial/security/oauth2-jwt.md
index bc3c943f8..ee7bc2d28 100644
--- a/docs/em/docs/tutorial/security/oauth2-jwt.md
+++ b/docs/em/docs/tutorial/security/oauth2-jwt.md
@@ -44,10 +44,13 @@ $ pip install "python-jose[cryptography]"
📥 👥 ⚙️ 👍 1️⃣: )/⚛.
-!!! tip
- 👉 🔰 ⏪ ⚙️ PyJWT.
+/// tip
- ✋️ ⚫️ ℹ ⚙️ 🐍-🇩🇬 ↩️ ⚫️ 🚚 🌐 ⚒ ⚪️➡️ PyJWT ➕ ➕ 👈 👆 💪 💪 ⏪ 🕐❔ 🏗 🛠️ ⏮️ 🎏 🧰.
+👉 🔰 ⏪ ⚙️ PyJWT.
+
+✋️ ⚫️ ℹ ⚙️ 🐍-🇩🇬 ↩️ ⚫️ 🚚 🌐 ⚒ ⚪️➡️ PyJWT ➕ ➕ 👈 👆 💪 💪 ⏪ 🕐❔ 🏗 🛠️ ⏮️ 🎏 🧰.
+
+///
## 🔐 🔁
@@ -83,12 +86,15 @@ $ pip install "passlib[bcrypt]"
@@ -261,8 +236,11 @@ $ openssl rand -hex 32
-!!! note
- 👀 🎚 `Authorization`, ⏮️ 💲 👈 ▶️ ⏮️ `Bearer `.
+/// note
+
+👀 🎚 `Authorization`, ⏮️ 💲 👈 ▶️ ⏮️ `Bearer `.
+
+///
## 🏧 ⚙️ ⏮️ `scopes`
diff --git a/docs/em/docs/tutorial/security/simple-oauth2.md b/docs/em/docs/tutorial/security/simple-oauth2.md
index b9e3deb3c..1fd513d48 100644
--- a/docs/em/docs/tutorial/security/simple-oauth2.md
+++ b/docs/em/docs/tutorial/security/simple-oauth2.md
@@ -32,14 +32,17 @@ Oauth2️⃣ ✔ 👈 🕐❔ ⚙️ "🔐 💧" (👈 👥 ⚙️) 👩💻/
* `instagram_basic` ⚙️ 👱📔 / 👱📔.
* `https://www.googleapis.com/auth/drive` ⚙️ 🇺🇸🔍.
-!!! info
- Oauth2️⃣ "↔" 🎻 👈 📣 🎯 ✔ ✔.
+/// info
- ⚫️ 🚫 🤔 🚥 ⚫️ ✔️ 🎏 🦹 💖 `:` ⚖️ 🚥 ⚫️ 📛.
+Oauth2️⃣ "↔" 🎻 👈 📣 🎯 ✔ ✔.
- 👈 ℹ 🛠️ 🎯.
+⚫️ 🚫 🤔 🚥 ⚫️ ✔️ 🎏 🦹 💖 `:` ⚖️ 🚥 ⚫️ 📛.
- Oauth2️⃣ 👫 🎻.
+👈 ℹ 🛠️ 🎯.
+
+Oauth2️⃣ 👫 🎻.
+
+///
## 📟 🤚 `username` & `password`
@@ -49,17 +52,7 @@ Oauth2️⃣ ✔ 👈 🕐❔ ⚙️ "🔐 💧" (👈 👥 ⚙️) 👩💻/
🥇, 🗄 `OAuth2PasswordRequestForm`, & ⚙️ ⚫️ 🔗 ⏮️ `Depends` *➡ 🛠️* `/token`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="4 76"
- {!> ../../../docs_src/security/tutorial003.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="2 74"
- {!> ../../../docs_src/security/tutorial003_py310.py!}
- ```
+{* ../../docs_src/security/tutorial003.py hl[4,76] *}
`OAuth2PasswordRequestForm` 🎓 🔗 👈 📣 📨 💪 ⏮️:
@@ -68,29 +61,38 @@ Oauth2️⃣ ✔ 👈 🕐❔ ⚙️ "🔐 💧" (👈 👥 ⚙️) 👩💻/
* 📦 `scope` 🏑 🦏 🎻, ✍ 🎻 🎏 🚀.
* 📦 `grant_type`.
-!!! tip
- Oauth2️⃣ 🔌 🤙 *🚚* 🏑 `grant_type` ⏮️ 🔧 💲 `password`, ✋️ `OAuth2PasswordRequestForm` 🚫 🛠️ ⚫️.
+/// tip
- 🚥 👆 💪 🛠️ ⚫️, ⚙️ `OAuth2PasswordRequestFormStrict` ↩️ `OAuth2PasswordRequestForm`.
+Oauth2️⃣ 🔌 🤙 *🚚* 🏑 `grant_type` ⏮️ 🔧 💲 `password`, ✋️ `OAuth2PasswordRequestForm` 🚫 🛠️ ⚫️.
+
+🚥 👆 💪 🛠️ ⚫️, ⚙️ `OAuth2PasswordRequestFormStrict` ↩️ `OAuth2PasswordRequestForm`.
+
+///
* 📦 `client_id` (👥 🚫 💪 ⚫️ 👆 🖼).
* 📦 `client_secret` (👥 🚫 💪 ⚫️ 👆 🖼).
-!!! info
- `OAuth2PasswordRequestForm` 🚫 🎁 🎓 **FastAPI** `OAuth2PasswordBearer`.
+/// info
- `OAuth2PasswordBearer` ⚒ **FastAPI** 💭 👈 ⚫️ 💂♂ ⚖. ⚫️ 🚮 👈 🌌 🗄.
+`OAuth2PasswordRequestForm` 🚫 🎁 🎓 **FastAPI** `OAuth2PasswordBearer`.
- ✋️ `OAuth2PasswordRequestForm` 🎓 🔗 👈 👆 💪 ✔️ ✍ 👆, ⚖️ 👆 💪 ✔️ 📣 `Form` 🔢 🔗.
+`OAuth2PasswordBearer` ⚒ **FastAPI** 💭 👈 ⚫️ 💂♂ ⚖. ⚫️ 🚮 👈 🌌 🗄.
- ✋️ ⚫️ ⚠ ⚙️ 💼, ⚫️ 🚚 **FastAPI** 🔗, ⚒ ⚫️ ⏩.
+✋️ `OAuth2PasswordRequestForm` 🎓 🔗 👈 👆 💪 ✔️ ✍ 👆, ⚖️ 👆 💪 ✔️ 📣 `Form` 🔢 🔗.
+
+✋️ ⚫️ ⚠ ⚙️ 💼, ⚫️ 🚚 **FastAPI** 🔗, ⚒ ⚫️ ⏩.
+
+///
### ⚙️ 📨 💽
-!!! tip
- 👐 🔗 🎓 `OAuth2PasswordRequestForm` 🏆 🚫 ✔️ 🔢 `scope` ⏮️ 📏 🎻 👽 🚀, ↩️, ⚫️ 🔜 ✔️ `scopes` 🔢 ⏮️ ☑ 📇 🎻 🔠 ↔ 📨.
+/// tip
- 👥 🚫 ⚙️ `scopes` 👉 🖼, ✋️ 🛠️ 📤 🚥 👆 💪 ⚫️.
+👐 🔗 🎓 `OAuth2PasswordRequestForm` 🏆 🚫 ✔️ 🔢 `scope` ⏮️ 📏 🎻 👽 🚀, ↩️, ⚫️ 🔜 ✔️ `scopes` 🔢 ⏮️ ☑ 📇 🎻 🔠 ↔ 📨.
+
+👥 🚫 ⚙️ `scopes` 👉 🖼, ✋️ 🛠️ 📤 🚥 👆 💪 ⚫️.
+
+///
🔜, 🤚 👩💻 📊 ⚪️➡️ (❌) 💽, ⚙️ `username` ⚪️➡️ 📨 🏑.
@@ -98,17 +100,7 @@ Oauth2️⃣ ✔ 👈 🕐❔ ⚙️ "🔐 💧" (👈 👥 ⚙️) 👩💻/
❌, 👥 ⚙️ ⚠ `HTTPException`:
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="3 77-79"
- {!> ../../../docs_src/security/tutorial003.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="1 75-77"
- {!> ../../../docs_src/security/tutorial003_py310.py!}
- ```
+{* ../../docs_src/security/tutorial003.py hl[3,77:79] *}
### ✅ 🔐
@@ -134,17 +126,7 @@ Oauth2️⃣ ✔ 👈 🕐❔ ⚙️ "🔐 💧" (👈 👥 ⚙️) 👩💻/
, 🧙♀ 🏆 🚫 💪 🔄 ⚙️ 👈 🎏 🔐 ➕1️⃣ ⚙️ (📚 👩💻 ⚙️ 🎏 🔐 🌐, 👉 🔜 ⚠).
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="80-83"
- {!> ../../../docs_src/security/tutorial003.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python hl_lines="78-81"
- {!> ../../../docs_src/security/tutorial003_py310.py!}
- ```
+{* ../../docs_src/security/tutorial003.py hl[80:83] *}
#### 🔃 `**user_dict`
@@ -162,8 +144,11 @@ UserInDB(
)
```
-!!! info
- 🌅 🏁 🔑 `**👩💻_ #️⃣ ` ✅ 🔙 [🧾 **➕ 🏷**](../extra-models.md#user_indict){.internal-link target=_blank}.
+/// info
+
+🌅 🏁 🔑 `**👩💻_ #️⃣ ` ✅ 🔙 [🧾 **➕ 🏷**](../extra-models.md#user_indict){.internal-link target=_blank}.
+
+///
## 📨 🤝
@@ -175,31 +160,27 @@ UserInDB(
👉 🙅 🖼, 👥 🔜 🍕 😟 & 📨 🎏 `username` 🤝.
-!!! tip
- ⏭ 📃, 👆 🔜 👀 🎰 🔐 🛠️, ⏮️ 🔐 #️⃣ & 🥙 🤝.
+/// tip
- ✋️ 🔜, ➡️ 🎯 🔛 🎯 ℹ 👥 💪.
+⏭ 📃, 👆 🔜 👀 🎰 🔐 🛠️, ⏮️ 🔐 #️⃣ & 🥙 🤝.
-=== "🐍 3️⃣.6️⃣ & 🔛"
+✋️ 🔜, ➡️ 🎯 🔛 🎯 ℹ 👥 💪.
- ```Python hl_lines="85"
- {!> ../../../docs_src/security/tutorial003.py!}
- ```
+///
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
+{* ../../docs_src/security/tutorial003.py hl[85] *}
- ```Python hl_lines="83"
- {!> ../../../docs_src/security/tutorial003_py310.py!}
- ```
+/// tip
-!!! tip
- 🔌, 👆 🔜 📨 🎻 ⏮️ `access_token` & `token_type`, 🎏 👉 🖼.
+🔌, 👆 🔜 📨 🎻 ⏮️ `access_token` & `token_type`, 🎏 👉 🖼.
- 👉 🕳 👈 👆 ✔️ 👆 👆 📟, & ⚒ 💭 👆 ⚙️ 📚 🎻 🔑.
+👉 🕳 👈 👆 ✔️ 👆 👆 📟, & ⚒ 💭 👆 ⚙️ 📚 🎻 🔑.
- ⚫️ 🌖 🕴 👜 👈 👆 ✔️ 💭 ☑ 👆, 🛠️ ⏮️ 🔧.
+⚫️ 🌖 🕴 👜 👈 👆 ✔️ 💭 ☑ 👆, 🛠️ ⏮️ 🔧.
- 🎂, **FastAPI** 🍵 ⚫️ 👆.
+🎂, **FastAPI** 🍵 ⚫️ 👆.
+
+///
## ℹ 🔗
@@ -213,32 +194,25 @@ UserInDB(
, 👆 🔗, 👥 🔜 🕴 🤚 👩💻 🚥 👩💻 🔀, ☑ 🔓, & 🦁:
-=== "🐍 3️⃣.6️⃣ & 🔛"
+{* ../../docs_src/security/tutorial003.py hl[58:66,69:72,90] *}
- ```Python hl_lines="58-66 69-72 90"
- {!> ../../../docs_src/security/tutorial003.py!}
- ```
+/// info
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
+🌖 🎚 `WWW-Authenticate` ⏮️ 💲 `Bearer` 👥 🛬 📥 🍕 🔌.
- ```Python hl_lines="55-64 67-70 88"
- {!> ../../../docs_src/security/tutorial003_py310.py!}
- ```
+🙆 🇺🇸🔍 (❌) 👔 📟 4️⃣0️⃣1️⃣ "⛔" 🤔 📨 `WWW-Authenticate` 🎚.
-!!! info
- 🌖 🎚 `WWW-Authenticate` ⏮️ 💲 `Bearer` 👥 🛬 📥 🍕 🔌.
+💼 📨 🤝 (👆 💼), 💲 👈 🎚 🔜 `Bearer`.
- 🙆 🇺🇸🔍 (❌) 👔 📟 4️⃣0️⃣1️⃣ "⛔" 🤔 📨 `WWW-Authenticate` 🎚.
+👆 💪 🤙 🚶 👈 ➕ 🎚 & ⚫️ 🔜 👷.
- 💼 📨 🤝 (👆 💼), 💲 👈 🎚 🔜 `Bearer`.
+✋️ ⚫️ 🚚 📥 🛠️ ⏮️ 🔧.
- 👆 💪 🤙 🚶 👈 ➕ 🎚 & ⚫️ 🔜 👷.
+, 📤 5️⃣📆 🧰 👈 ⌛ & ⚙️ ⚫️ (🔜 ⚖️ 🔮) & 👈 💪 ⚠ 👆 ⚖️ 👆 👩💻, 🔜 ⚖️ 🔮.
- ✋️ ⚫️ 🚚 📥 🛠️ ⏮️ 🔧.
+👈 💰 🐩...
- , 📤 5️⃣📆 🧰 👈 ⌛ & ⚙️ ⚫️ (🔜 ⚖️ 🔮) & 👈 💪 ⚠ 👆 ⚖️ 👆 👩💻, 🔜 ⚖️ 🔮.
-
- 👈 💰 🐩...
+///
## 👀 ⚫️ 🎯
diff --git a/docs/em/docs/tutorial/sql-databases.md b/docs/em/docs/tutorial/sql-databases.md
deleted file mode 100644
index 5a5227352..000000000
--- a/docs/em/docs/tutorial/sql-databases.md
+++ /dev/null
@@ -1,786 +0,0 @@
-# 🗄 (🔗) 💽
-
-**FastAPI** 🚫 🚚 👆 ⚙️ 🗄 (🔗) 💽.
-
-✋️ 👆 💪 ⚙️ 🙆 🔗 💽 👈 👆 💚.
-
-📥 👥 🔜 👀 🖼 ⚙️ 🇸🇲.
-
-👆 💪 💪 🛠️ ⚫️ 🙆 💽 🐕🦺 🇸🇲, 💖:
-
-* ✳
-* ✳
-* 🗄
-* 🐸
-* 🤸♂ 🗄 💽, ♒️.
-
-👉 🖼, 👥 🔜 ⚙️ **🗄**, ↩️ ⚫️ ⚙️ 👁 📁 & 🐍 ✔️ 🛠️ 🐕🦺. , 👆 💪 📁 👉 🖼 & 🏃 ⚫️.
-
-⏪, 👆 🏭 🈸, 👆 💪 💚 ⚙️ 💽 💽 💖 **✳**.
-
-!!! tip
- 📤 🛂 🏗 🚂 ⏮️ **FastAPI** & **✳**, 🌐 ⚓️ 🔛 **☁**, 🔌 🕸 & 🌖 🧰: https://github.com/tiangolo/full-stack-fastapi-postgresql
-
-!!! note
- 👀 👈 📚 📟 🐩 `SQLAlchemy` 📟 👆 🔜 ⚙️ ⏮️ 🙆 🛠️.
-
- **FastAPI** 🎯 📟 🤪 🕧.
-
-## 🐜
-
-**FastAPI** 👷 ⏮️ 🙆 💽 & 🙆 👗 🗃 💬 💽.
-
-⚠ ⚓ ⚙️ "🐜": "🎚-🔗 🗺" 🗃.
-
-🐜 ✔️ 🧰 🗜 ("*🗺*") 🖖 *🎚* 📟 & 💽 🏓 ("*🔗*").
-
-⏮️ 🐜, 👆 🛎 ✍ 🎓 👈 🎨 🏓 🗄 💽, 🔠 🔢 🎓 🎨 🏓, ⏮️ 📛 & 🆎.
-
-🖼 🎓 `Pet` 💪 🎨 🗄 🏓 `pets`.
-
-& 🔠 *👐* 🎚 👈 🎓 🎨 ⏭ 💽.
-
-🖼 🎚 `orion_cat` (👐 `Pet`) 💪 ✔️ 🔢 `orion_cat.type`, 🏓 `type`. & 💲 👈 🔢 💪, ✅ `"cat"`.
-
-👫 🐜 ✔️ 🧰 ⚒ 🔗 ⚖️ 🔗 🖖 🏓 ⚖️ 👨💼.
-
-👉 🌌, 👆 💪 ✔️ 🔢 `orion_cat.owner` & 👨💼 🔜 🔌 💽 👉 🐶 👨💼, ✊ ⚪️➡️ 🏓 *👨💼*.
-
-, `orion_cat.owner.name` 💪 📛 (⚪️➡️ `name` 🏓 `owners` 🏓) 👉 🐶 👨💼.
-
-⚫️ 💪 ✔️ 💲 💖 `"Arquilian"`.
-
-& 🐜 🔜 🌐 👷 🤚 ℹ ⚪️➡️ 🔗 🏓 *👨💼* 🕐❔ 👆 🔄 🔐 ⚫️ ⚪️➡️ 👆 🐶 🎚.
-
-⚠ 🐜 🖼: ✳-🐜 (🍕 ✳ 🛠️), 🇸🇲 🐜 (🍕 🇸🇲, 🔬 🛠️) & 🏒 (🔬 🛠️), 👪 🎏.
-
-📥 👥 🔜 👀 ❔ 👷 ⏮️ **🇸🇲 🐜**.
-
-🎏 🌌 👆 💪 ⚙️ 🙆 🎏 🐜.
-
-!!! tip
- 📤 🌓 📄 ⚙️ 🏒 📥 🩺.
-
-## 📁 📊
-
-👫 🖼, ➡️ 💬 👆 ✔️ 📁 📛 `my_super_project` 👈 🔌 🎧-📁 🤙 `sql_app` ⏮️ 📊 💖 👉:
-
-```
-.
-└── sql_app
- ├── __init__.py
- ├── crud.py
- ├── database.py
- ├── main.py
- ├── models.py
- └── schemas.py
-```
-
-📁 `__init__.py` 🛁 📁, ✋️ ⚫️ 💬 🐍 👈 `sql_app` ⏮️ 🌐 🚮 🕹 (🐍 📁) 📦.
-
-🔜 ➡️ 👀 ⚫️❔ 🔠 📁/🕹 🔨.
-
-## ❎ `SQLAlchemy`
-
-🥇 👆 💪 ❎ `SQLAlchemy`:
-
-
-
-## 🔗 ⏮️ 💽 🔗
-
-🚥 👆 💚 🔬 🗄 💽 (📁) 🔗, ➡ FastAPI, ℹ 🚮 🎚, 🚮 🏓, 🏓, ⏺, 🔀 📊, ♒️. 👆 💪 ⚙️ 💽 🖥 🗄.
-
-⚫️ 🔜 👀 💖 👉:
-
-
-
-👆 💪 ⚙️ 💳 🗄 🖥 💖 🗄 📋 ⚖️ ExtendsClass.
-
-## 🎛 💽 🎉 ⏮️ 🛠️
-
-🚥 👆 💪 🚫 ⚙️ 🔗 ⏮️ `yield` - 🖼, 🚥 👆 🚫 ⚙️ **🐍 3️⃣.7️⃣** & 💪 🚫 ❎ "🐛" 🤔 🔛 **🐍 3️⃣.6️⃣** - 👆 💪 ⚒ 🆙 🎉 "🛠️" 🎏 🌌.
-
-"🛠️" 🌖 🔢 👈 🕧 🛠️ 🔠 📨, ⏮️ 📟 🛠️ ⏭, & 📟 🛠️ ⏮️ 🔗 🔢.
-
-### ✍ 🛠️
-
-🛠️ 👥 🔜 🚮 (🔢) 🔜 ✍ 🆕 🇸🇲 `SessionLocal` 🔠 📨, 🚮 ⚫️ 📨 & ⤴️ 🔐 ⚫️ 🕐 📨 🏁.
-
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python hl_lines="14-22"
- {!> ../../../docs_src/sql_databases/sql_app/alt_main.py!}
- ```
-
-=== "🐍 3️⃣.9️⃣ & 🔛"
-
- ```Python hl_lines="12-20"
- {!> ../../../docs_src/sql_databases/sql_app_py39/alt_main.py!}
- ```
-
-!!! info
- 👥 🚮 🏗 `SessionLocal()` & 🚚 📨 `try` 🍫.
-
- & ⤴️ 👥 🔐 ⚫️ `finally` 🍫.
-
- 👉 🌌 👥 ⚒ 💭 💽 🎉 🕧 📪 ⏮️ 📨. 🚥 📤 ⚠ ⏪ 🏭 📨.
-
-### 🔃 `request.state`
-
-`request.state` 🏠 🔠 `Request` 🎚. ⚫️ 📤 🏪 ❌ 🎚 📎 📨 ⚫️, 💖 💽 🎉 👉 💼. 👆 💪 ✍ 🌅 🔃 ⚫️ 💃 🩺 🔃 `Request` 🇵🇸.
-
-👥 👉 💼, ⚫️ ℹ 👥 🚚 👁 💽 🎉 ⚙️ 🔘 🌐 📨, & ⤴️ 🔐 ⏮️ (🛠️).
-
-### 🔗 ⏮️ `yield` ⚖️ 🛠️
-
-❎ **🛠️** 📥 🎏 ⚫️❔ 🔗 ⏮️ `yield` 🔨, ⏮️ 🔺:
-
-* ⚫️ 🚚 🌖 📟 & 👄 🌅 🏗.
-* 🛠️ ✔️ `async` 🔢.
- * 🚥 📤 📟 ⚫️ 👈 ✔️ "⌛" 🕸, ⚫️ 💪 "🍫" 👆 🈸 📤 & 📉 🎭 🍖.
- * 👐 ⚫️ 🎲 🚫 📶 ⚠ 📥 ⏮️ 🌌 `SQLAlchemy` 👷.
- * ✋️ 🚥 👆 🚮 🌖 📟 🛠️ 👈 ✔️ 📚 👤/🅾 ⌛, ⚫️ 💪 ⤴️ ⚠.
-* 🛠️ 🏃 *🔠* 📨.
- * , 🔗 🔜 ✍ 🔠 📨.
- * 🕐❔ *➡ 🛠️* 👈 🍵 👈 📨 🚫 💪 💽.
-
-!!! tip
- ⚫️ 🎲 👍 ⚙️ 🔗 ⏮️ `yield` 🕐❔ 👫 🥃 ⚙️ 💼.
-
-!!! info
- 🔗 ⏮️ `yield` 🚮 ⏳ **FastAPI**.
-
- ⏮️ ⏬ 👉 🔰 🕴 ✔️ 🖼 ⏮️ 🛠️ & 📤 🎲 📚 🈸 ⚙️ 🛠️ 💽 🎉 🧾.
diff --git a/docs/em/docs/tutorial/static-files.md b/docs/em/docs/tutorial/static-files.md
index 6090c5338..6ff6e37a9 100644
--- a/docs/em/docs/tutorial/static-files.md
+++ b/docs/em/docs/tutorial/static-files.md
@@ -7,14 +7,15 @@
* 🗄 `StaticFiles`.
* "🗻" `StaticFiles()` 👐 🎯 ➡.
-```Python hl_lines="2 6"
-{!../../../docs_src/static_files/tutorial001.py!}
-```
+{* ../../docs_src/static_files/tutorial001.py hl[2,6] *}
-!!! note "📡 ℹ"
- 👆 💪 ⚙️ `from starlette.staticfiles import StaticFiles`.
+/// note | 📡 ℹ
- **FastAPI** 🚚 🎏 `starlette.staticfiles` `fastapi.staticfiles` 🏪 👆, 👩💻. ✋️ ⚫️ 🤙 👟 🔗 ⚪️➡️ 💃.
+👆 💪 ⚙️ `from starlette.staticfiles import StaticFiles`.
+
+**FastAPI** 🚚 🎏 `starlette.staticfiles` `fastapi.staticfiles` 🏪 👆, 👩💻. ✋️ ⚫️ 🤙 👟 🔗 ⚪️➡️ 💃.
+
+///
### ⚫️❔ "🗜"
diff --git a/docs/em/docs/tutorial/testing.md b/docs/em/docs/tutorial/testing.md
index 3ae51e298..cb4a1ca21 100644
--- a/docs/em/docs/tutorial/testing.md
+++ b/docs/em/docs/tutorial/testing.md
@@ -8,10 +8,13 @@
## ⚙️ `TestClient`
-!!! info
- ⚙️ `TestClient`, 🥇 ❎ `httpx`.
+/// info
- 🤶 Ⓜ. `pip install httpx`.
+⚙️ `TestClient`, 🥇 ❎ `httpx`.
+
+🤶 Ⓜ. `pip install httpx`.
+
+///
🗄 `TestClient`.
@@ -23,24 +26,31 @@
✍ 🙅 `assert` 📄 ⏮️ 🐩 🐍 🧬 👈 👆 💪 ✅ (🔄, 🐩 `pytest`).
-```Python hl_lines="2 12 15-18"
-{!../../../docs_src/app_testing/tutorial001.py!}
-```
+{* ../../docs_src/app_testing/tutorial001.py hl[2,12,15:18] *}
-!!! tip
- 👀 👈 🔬 🔢 😐 `def`, 🚫 `async def`.
+/// tip
- & 🤙 👩💻 😐 🤙, 🚫 ⚙️ `await`.
+👀 👈 🔬 🔢 😐 `def`, 🚫 `async def`.
- 👉 ✔ 👆 ⚙️ `pytest` 🔗 🍵 🤢.
+ & 🤙 👩💻 😐 🤙, 🚫 ⚙️ `await`.
-!!! note "📡 ℹ"
- 👆 💪 ⚙️ `from starlette.testclient import TestClient`.
+👉 ✔ 👆 ⚙️ `pytest` 🔗 🍵 🤢.
- **FastAPI** 🚚 🎏 `starlette.testclient` `fastapi.testclient` 🏪 👆, 👩💻. ✋️ ⚫️ 👟 🔗 ⚪️➡️ 💃.
+///
-!!! tip
- 🚥 👆 💚 🤙 `async` 🔢 👆 💯 ↖️ ⚪️➡️ 📨 📨 👆 FastAPI 🈸 (✅ 🔁 💽 🔢), ✔️ 👀 [🔁 💯](../advanced/async-tests.md){.internal-link target=_blank} 🏧 🔰.
+/// note | 📡 ℹ
+
+👆 💪 ⚙️ `from starlette.testclient import TestClient`.
+
+**FastAPI** 🚚 🎏 `starlette.testclient` `fastapi.testclient` 🏪 👆, 👩💻. ✋️ ⚫️ 👟 🔗 ⚪️➡️ 💃.
+
+///
+
+/// tip
+
+🚥 👆 💚 🤙 `async` 🔢 👆 💯 ↖️ ⚪️➡️ 📨 📨 👆 FastAPI 🈸 (✅ 🔁 💽 🔢), ✔️ 👀 [🔁 💯](../advanced/async-tests.md){.internal-link target=_blank} 🏧 🔰.
+
+///
## 🎏 💯
@@ -62,9 +72,7 @@
📁 `main.py` 👆 ✔️ 👆 **FastAPI** 📱:
-```Python
-{!../../../docs_src/app_testing/main.py!}
-```
+{* ../../docs_src/app_testing/main.py *}
### 🔬 📁
@@ -80,9 +88,7 @@
↩️ 👉 📁 🎏 📦, 👆 💪 ⚙️ ⚖ 🗄 🗄 🎚 `app` ⚪️➡️ `main` 🕹 (`main.py`):
-```Python hl_lines="3"
-{!../../../docs_src/app_testing/test_main.py!}
-```
+{* ../../docs_src/app_testing/test_main.py hl[3] *}
...& ✔️ 📟 💯 💖 ⏭.
@@ -110,25 +116,13 @@
👯♂️ *➡ 🛠️* 🚚 `X-Token` 🎚.
-=== "🐍 3️⃣.6️⃣ & 🔛"
-
- ```Python
- {!> ../../../docs_src/app_testing/app_b/main.py!}
- ```
-
-=== "🐍 3️⃣.1️⃣0️⃣ & 🔛"
-
- ```Python
- {!> ../../../docs_src/app_testing/app_b_py310/main.py!}
- ```
+{* ../../docs_src/app_testing/app_b/main.py *}
### ↔ 🔬 📁
👆 💪 ⤴️ ℹ `test_main.py` ⏮️ ↔ 💯:
-```Python
-{!> ../../../docs_src/app_testing/app_b/test_main.py!}
-```
+{* ../../docs_src/app_testing/app_b/test_main.py *}
🕐❔ 👆 💪 👩💻 🚶♀️ ℹ 📨 & 👆 🚫 💭 ❔, 👆 💪 🔎 (🇺🇸🔍) ❔ ⚫️ `httpx`, ⚖️ ❔ ⚫️ ⏮️ `requests`, 🇸🇲 🔧 ⚓️ 🔛 📨' 🔧.
@@ -144,10 +138,13 @@
🌖 ℹ 🔃 ❔ 🚶♀️ 💽 👩💻 (⚙️ `httpx` ⚖️ `TestClient`) ✅ 🇸🇲 🧾.
-!!! info
- 🗒 👈 `TestClient` 📨 💽 👈 💪 🗜 🎻, 🚫 Pydantic 🏷.
+/// info
- 🚥 👆 ✔️ Pydantic 🏷 👆 💯 & 👆 💚 📨 🚮 💽 🈸 ⏮️ 🔬, 👆 💪 ⚙️ `jsonable_encoder` 🔬 [🎻 🔗 🔢](encoder.md){.internal-link target=_blank}.
+🗒 👈 `TestClient` 📨 💽 👈 💪 🗜 🎻, 🚫 Pydantic 🏷.
+
+🚥 👆 ✔️ Pydantic 🏷 👆 💯 & 👆 💚 📨 🚮 💽 🈸 ⏮️ 🔬, 👆 💪 ⚙️ `jsonable_encoder` 🔬 [🎻 🔗 🔢](encoder.md){.internal-link target=_blank}.
+
+///
## 🏃 ⚫️
diff --git a/docs/en/data/contributors.yml b/docs/en/data/contributors.yml
new file mode 100644
index 000000000..f3f7c9133
--- /dev/null
+++ b/docs/en/data/contributors.yml
@@ -0,0 +1,545 @@
+tiangolo:
+ login: tiangolo
+ count: 747
+ avatarUrl: https://avatars.githubusercontent.com/u/1326112?u=cb5d06e73a9e1998141b1641aa88e443c6717651&v=4
+ url: https://github.com/tiangolo
+dependabot:
+ login: dependabot
+ count: 102
+ avatarUrl: https://avatars.githubusercontent.com/in/29110?v=4
+ url: https://github.com/apps/dependabot
+alejsdev:
+ login: alejsdev
+ count: 47
+ avatarUrl: https://avatars.githubusercontent.com/u/90076947?u=638c65283ac9e9e2c3a0f9d1e3370db4b8a2c58d&v=4
+ url: https://github.com/alejsdev
+pre-commit-ci:
+ login: pre-commit-ci
+ count: 30
+ avatarUrl: https://avatars.githubusercontent.com/in/68672?v=4
+ url: https://github.com/apps/pre-commit-ci
+github-actions:
+ login: github-actions
+ count: 26
+ avatarUrl: https://avatars.githubusercontent.com/in/15368?v=4
+ url: https://github.com/apps/github-actions
+Kludex:
+ login: Kludex
+ count: 23
+ avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=df8a3f06ba8f55ae1967a3e2d5ed882903a4e330&v=4
+ url: https://github.com/Kludex
+dmontagu:
+ login: dmontagu
+ count: 17
+ avatarUrl: https://avatars.githubusercontent.com/u/35119617?u=540f30c937a6450812628b9592a1dfe91bbe148e&v=4
+ url: https://github.com/dmontagu
+euri10:
+ login: euri10
+ count: 13
+ avatarUrl: https://avatars.githubusercontent.com/u/1104190?u=321a2e953e6645a7d09b732786c7a8061e0f8a8b&v=4
+ url: https://github.com/euri10
+kantandane:
+ login: kantandane
+ count: 13
+ avatarUrl: https://avatars.githubusercontent.com/u/3978368?u=cccc199291f991a73b1ebba5abc735a948e0bd16&v=4
+ url: https://github.com/kantandane
+nilslindemann:
+ login: nilslindemann
+ count: 11
+ avatarUrl: https://avatars.githubusercontent.com/u/6892179?u=1dca6a22195d6cd1ab20737c0e19a4c55d639472&v=4
+ url: https://github.com/nilslindemann
+zhaohan-dong:
+ login: zhaohan-dong
+ count: 11
+ avatarUrl: https://avatars.githubusercontent.com/u/65422392?u=8260f8781f50248410ebfa4c9bf70e143fe5c9f2&v=4
+ url: https://github.com/zhaohan-dong
+mariacamilagl:
+ login: mariacamilagl
+ count: 9
+ avatarUrl: https://avatars.githubusercontent.com/u/11489395?u=4adb6986bf3debfc2b8216ae701f2bd47d73da7d&v=4
+ url: https://github.com/mariacamilagl
+handabaldeep:
+ login: handabaldeep
+ count: 9
+ avatarUrl: https://avatars.githubusercontent.com/u/12239103?u=6c39ef15d14c6d5211f5dd775cc4842f8d7f2f3a&v=4
+ url: https://github.com/handabaldeep
+vishnuvskvkl:
+ login: vishnuvskvkl
+ count: 8
+ avatarUrl: https://avatars.githubusercontent.com/u/84698110?u=8af5de0520dd4fa195f53c2850a26f57c0f6bc64&v=4
+ url: https://github.com/vishnuvskvkl
+svlandeg:
+ login: svlandeg
+ count: 7
+ avatarUrl: https://avatars.githubusercontent.com/u/8796347?u=556c97650c27021911b0b9447ec55e75987b0e8a&v=4
+ url: https://github.com/svlandeg
+alissadb:
+ login: alissadb
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/96190409?u=be42d85938c241be781505a5a872575be28b2906&v=4
+ url: https://github.com/alissadb
+wshayes:
+ login: wshayes
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/365303?u=07ca03c5ee811eb0920e633cc3c3db73dbec1aa5&v=4
+ url: https://github.com/wshayes
+samuelcolvin:
+ login: samuelcolvin
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/4039449?u=42eb3b833047c8c4b4f647a031eaef148c16d93f&v=4
+ url: https://github.com/samuelcolvin
+waynerv:
+ login: waynerv
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/39515546?u=ec35139777597cdbbbddda29bf8b9d4396b429a9&v=4
+ url: https://github.com/waynerv
+krishnamadhavan:
+ login: krishnamadhavan
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/31798870?u=950693b28f3ae01105fd545c046e46ca3d31ab06&v=4
+ url: https://github.com/krishnamadhavan
+alv2017:
+ login: alv2017
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/31544722?v=4
+ url: https://github.com/alv2017
+jekirl:
+ login: jekirl
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/2546697?u=a027452387d85bd4a14834e19d716c99255fb3b7&v=4
+ url: https://github.com/jekirl
+hitrust:
+ login: hitrust
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/3360631?u=5fa1f475ad784d64eb9666bdd43cc4d285dcc773&v=4
+ url: https://github.com/hitrust
+ShahriyarR:
+ login: ShahriyarR
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/3852029?u=c9a1691e5ebdc94cbf543086099a6ed705cdb873&v=4
+ url: https://github.com/ShahriyarR
+adriangb:
+ login: adriangb
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/1755071?u=612704256e38d6ac9cbed24f10e4b6ac2da74ecb&v=4
+ url: https://github.com/adriangb
+iudeen:
+ login: iudeen
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/10519440?u=f09cdd745e5bf16138f29b42732dd57c7f02bee1&v=4
+ url: https://github.com/iudeen
+philipokiokio:
+ login: philipokiokio
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/55271518?u=d30994d339aaaf1f6bf1b8fc810132016fbd4fdc&v=4
+ url: https://github.com/philipokiokio
+AlexWendland:
+ login: AlexWendland
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/3949212?u=c4c0c615e0ea33d00bfe16b779cf6ebc0f58071c&v=4
+ url: https://github.com/AlexWendland
+divums:
+ login: divums
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/1397556?v=4
+ url: https://github.com/divums
+prostomarkeloff:
+ login: prostomarkeloff
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/28061158?u=6918e39a1224194ba636e897461a02a20126d7ad&v=4
+ url: https://github.com/prostomarkeloff
+nsidnev:
+ login: nsidnev
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/22559461?u=a9cc3238217e21dc8796a1a500f01b722adb082c&v=4
+ url: https://github.com/nsidnev
+pawamoy:
+ login: pawamoy
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/3999221?u=b030e4c89df2f3a36bc4710b925bdeb6745c9856&v=4
+ url: https://github.com/pawamoy
+patrickmckenna:
+ login: patrickmckenna
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/3589536?u=53aef07250d226d35e526768e26891964907b41a&v=4
+ url: https://github.com/patrickmckenna
+hukkin:
+ login: hukkin
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/3275109?u=77bb83759127965eacbfe67e2ca983066e964fde&v=4
+ url: https://github.com/hukkin
+marcosmmb:
+ login: marcosmmb
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/6181089?u=03c50eec631857d84df5232890780d00a3f76903&v=4
+ url: https://github.com/marcosmmb
+Serrones:
+ login: Serrones
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/22691749?u=4795b880e13ca33a73e52fc0ef7dc9c60c8fce47&v=4
+ url: https://github.com/Serrones
+uriyyo:
+ login: uriyyo
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/32038156?u=a27b65a9ec3420586a827a0facccbb8b6df1ffb3&v=4
+ url: https://github.com/uriyyo
+andrew222651:
+ login: andrew222651
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/889657?u=d70187989940b085bcbfa3bedad8dbc5f3ab1fe7&v=4
+ url: https://github.com/andrew222651
+rkbeatss:
+ login: rkbeatss
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/23391143?u=56ab6bff50be950fa8cae5cf736f2ae66e319ff3&v=4
+ url: https://github.com/rkbeatss
+asheux:
+ login: asheux
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/22955146?u=4553ebf5b5a7c7fe031a46182083aa224faba2e1&v=4
+ url: https://github.com/asheux
+n25a:
+ login: n25a
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/49960770?u=7d8a6d5f0a75a5e9a865a2527edfd48895ea27ae&v=4
+ url: https://github.com/n25a
+ghandic:
+ login: ghandic
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/23500353?u=e2e1d736f924d9be81e8bfc565b6d8836ba99773&v=4
+ url: https://github.com/ghandic
+TeoZosa:
+ login: TeoZosa
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/13070236?u=96fdae85800ef85dcfcc4b5f8281dc8778c8cb7d&v=4
+ url: https://github.com/TeoZosa
+graingert:
+ login: graingert
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/413772?v=4
+ url: https://github.com/graingert
+jaystone776:
+ login: jaystone776
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/11191137?u=299205a95e9b6817a43144a48b643346a5aac5cc&v=4
+ url: https://github.com/jaystone776
+zanieb:
+ login: zanieb
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/2586601?u=e5c86f7ff3b859e7e183187ac2b17fd6ee32b3ab&v=4
+ url: https://github.com/zanieb
+MicaelJarniac:
+ login: MicaelJarniac
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/19514231?u=158c91874ea98d6e9e6f0c6db37ee2ce60c55ff2&v=4
+ url: https://github.com/MicaelJarniac
+papb:
+ login: papb
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/20914054?u=890511fae7ea90d887e2a65ce44a1775abba38d5&v=4
+ url: https://github.com/papb
+musicinmybrain:
+ login: musicinmybrain
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/6898909?u=9010312053e7141383b9bdf538036c7f37fbaba0&v=4
+ url: https://github.com/musicinmybrain
+gitworkflows:
+ login: gitworkflows
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/118260833?v=4
+ url: https://github.com/gitworkflows
+Nimitha-jagadeesha:
+ login: Nimitha-jagadeesha
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/58389915?v=4
+ url: https://github.com/Nimitha-jagadeesha
+lucaromagnoli:
+ login: lucaromagnoli
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/38782977?u=e66396859f493b4ddcb3a837a1b2b2039c805417&v=4
+ url: https://github.com/lucaromagnoli
+salmantec:
+ login: salmantec
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/41512228?u=443551b893ff2425c59d5d021644f098cf7c68d5&v=4
+ url: https://github.com/salmantec
+OCE1960:
+ login: OCE1960
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/45076670?u=0e9a44712b92ffa89ddfbaa83c112f3f8e1d68e2&v=4
+ url: https://github.com/OCE1960
+hamidrasti:
+ login: hamidrasti
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/43915620?v=4
+ url: https://github.com/hamidrasti
+kkinder:
+ login: kkinder
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/1115018?u=c5e90284a9f5c5049eae1bb029e3655c7dc913ed&v=4
+ url: https://github.com/kkinder
+kabirkhan:
+ login: kabirkhan
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/13891834?u=e0eabf792376443ac853e7dca6f550db4166fe35&v=4
+ url: https://github.com/kabirkhan
+zamiramir:
+ login: zamiramir
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/40475662?u=e58ef61034e8d0d6a312cc956fb09b9c3332b449&v=4
+ url: https://github.com/zamiramir
+trim21:
+ login: trim21
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/13553903?u=3cadf0f02095c9621aa29df6875f53a80ca4fbfb&v=4
+ url: https://github.com/trim21
+koxudaxi:
+ login: koxudaxi
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/630670?u=507d8577b4b3670546b449c4c2ccbc5af40d72f7&v=4
+ url: https://github.com/koxudaxi
+pablogamboa:
+ login: pablogamboa
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/12892536?u=326a57059ee0c40c4eb1b38413957236841c631b&v=4
+ url: https://github.com/pablogamboa
+dconathan:
+ login: dconathan
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/15098095?v=4
+ url: https://github.com/dconathan
+Jamim:
+ login: Jamim
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/5607572?u=9ce0b6a6d1a5124e28b3c04d8d26827ca328713a&v=4
+ url: https://github.com/Jamim
+svalouch:
+ login: svalouch
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/54674660?v=4
+ url: https://github.com/svalouch
+frankie567:
+ login: frankie567
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/1144727?u=c159fe047727aedecbbeeaa96a1b03ceb9d39add&v=4
+ url: https://github.com/frankie567
+marier-nico:
+ login: marier-nico
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/30477068?u=c7df6af853c8f4163d1517814f3e9a0715c82713&v=4
+ url: https://github.com/marier-nico
+Dustyposa:
+ login: Dustyposa
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/27180793?u=5cf2877f50b3eb2bc55086089a78a36f07042889&v=4
+ url: https://github.com/Dustyposa
+aviramha:
+ login: aviramha
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/41201924?u=6883cc4fc13a7b2e60d4deddd4be06f9c5287880&v=4
+ url: https://github.com/aviramha
+iwpnd:
+ login: iwpnd
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/6152183?u=ec59396e9437fff488791c5ecdf6d23f1f1ebf3a&v=4
+ url: https://github.com/iwpnd
+raphaelauv:
+ login: raphaelauv
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/10202690?u=e6f86f5c0c3026a15d6b51792fa3e532b12f1371&v=4
+ url: https://github.com/raphaelauv
+windson:
+ login: windson
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/1826682?u=8b28dcd716c46289f191f8828e01d74edd058bef&v=4
+ url: https://github.com/windson
+sm-Fifteen:
+ login: sm-Fifteen
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/516999?u=437c0c5038558c67e887ccd863c1ba0f846c03da&v=4
+ url: https://github.com/sm-Fifteen
+sattosan:
+ login: sattosan
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/20574756?u=b0d8474d2938189c6954423ae8d81d91013f80a8&v=4
+ url: https://github.com/sattosan
+michaeloliverx:
+ login: michaeloliverx
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/55017335?u=efb0cb6e261ff64d862fafb91ee80fc2e1f8a2ed&v=4
+ url: https://github.com/michaeloliverx
+voegtlel:
+ login: voegtlel
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/5764745?u=db8df3d70d427928ab6d7dbfc395a4a7109c1d1b&v=4
+ url: https://github.com/voegtlel
+HarshaLaxman:
+ login: HarshaLaxman
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/19939186?u=a112f38b0f6b4d4402dc8b51978b5a0b2e5c5970&v=4
+ url: https://github.com/HarshaLaxman
+RunningIkkyu:
+ login: RunningIkkyu
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/31848542?u=494ecc298e3f26197495bb357ad0f57cfd5f7a32&v=4
+ url: https://github.com/RunningIkkyu
+cassiobotaro:
+ login: cassiobotaro
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/3127847?u=a08022b191ddbd0a6159b2981d9d878b6d5bb71f&v=4
+ url: https://github.com/cassiobotaro
+chenl:
+ login: chenl
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/1677651?u=c618508eaad6d596cea36c8ea784b424288f6857&v=4
+ url: https://github.com/chenl
+retnikt:
+ login: retnikt
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/24581770?v=4
+ url: https://github.com/retnikt
+yankeexe:
+ login: yankeexe
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/13623913?u=f970e66421775a8d3cdab89c0c752eaead186f6d&v=4
+ url: https://github.com/yankeexe
+patrickkwang:
+ login: patrickkwang
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/1263870?u=4bf74020e15be490f19ef8322a76eec882220b96&v=4
+ url: https://github.com/patrickkwang
+victorphoenix3:
+ login: victorphoenix3
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/48182195?u=e4875bd088623cb4ddeb7be194ec54b453aff035&v=4
+ url: https://github.com/victorphoenix3
+davidefiocco:
+ login: davidefiocco
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/4547987?v=4
+ url: https://github.com/davidefiocco
+adriencaccia:
+ login: adriencaccia
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/19605940?u=980b0b366a02791a5600b2e9f9ac2037679acaa8&v=4
+ url: https://github.com/adriencaccia
+jamescurtin:
+ login: jamescurtin
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/10189269?u=0b491fc600ca51f41cf1d95b49fa32a3eba1de57&v=4
+ url: https://github.com/jamescurtin
+jmriebold:
+ login: jmriebold
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/6983392?u=4efdc97bf2422dcc7e9ff65b9ff80087c8eb2a20&v=4
+ url: https://github.com/jmriebold
+nukopy:
+ login: nukopy
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/42367320?u=6061be0bd060506f6d564a8df3ae73fab048cdfe&v=4
+ url: https://github.com/nukopy
+imba-tjd:
+ login: imba-tjd
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/24759802?u=01e901a4fe004b4b126549d3ff1c4000fe3720b5&v=4
+ url: https://github.com/imba-tjd
+johnthagen:
+ login: johnthagen
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/10340167?u=47147fc4e4db1f573bee3fe428deeacb3197bc5f&v=4
+ url: https://github.com/johnthagen
+paxcodes:
+ login: paxcodes
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/13646646?u=e7429cc7ab11211ef762f4cd3efea7db6d9ef036&v=4
+ url: https://github.com/paxcodes
+kaustubhgupta:
+ login: kaustubhgupta
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/43691873?u=8dd738718ac7ffad4ef31e86b5d780a1141c695d&v=4
+ url: https://github.com/kaustubhgupta
+kinuax:
+ login: kinuax
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/13321374?u=22dc9873d6d9f2c7e4fc44c6480c3505efb1531f&v=4
+ url: https://github.com/kinuax
+wakabame:
+ login: wakabame
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/35513518?u=41ef6b0a55076e5c540620d68fb006e386c2ddb0&v=4
+ url: https://github.com/wakabame
+nzig:
+ login: nzig
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/7372858?u=e769add36ed73c778cdb136eb10bf96b1e119671&v=4
+ url: https://github.com/nzig
+yezz123:
+ login: yezz123
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/52716203?u=d7062cbc6eb7671d5dc9cc0e32a24ae335e0f225&v=4
+ url: https://github.com/yezz123
+softwarebloat:
+ login: softwarebloat
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/16540684?v=4
+ url: https://github.com/softwarebloat
+Lancetnik:
+ login: Lancetnik
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/44573917?u=f9a18be7324333daf9cc314c35c3051f0a20a7a6&v=4
+ url: https://github.com/Lancetnik
+joakimnordling:
+ login: joakimnordling
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/6637576?u=df5d99db9b899b399effd429f4358baaa6f7199c&v=4
+ url: https://github.com/joakimnordling
+yogabonito:
+ login: yogabonito
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/7026269?v=4
+ url: https://github.com/yogabonito
+s111d:
+ login: s111d
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/4954856?v=4
+ url: https://github.com/s111d
+estebanx64:
+ login: estebanx64
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/10840422?u=45f015f95e1c0f06df602be4ab688d4b854cc8a8&v=4
+ url: https://github.com/estebanx64
+tamird:
+ login: tamird
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/1535036?v=4
+ url: https://github.com/tamird
+rabinlamadong:
+ login: rabinlamadong
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/170439781?v=4
+ url: https://github.com/rabinlamadong
+AyushSinghal1794:
+ login: AyushSinghal1794
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/89984761?v=4
+ url: https://github.com/AyushSinghal1794
+gsheni:
+ login: gsheni
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/8726321?u=ee3bd9ff6320f4715d1dd9671a3d55cccb65b984&v=4
+ url: https://github.com/gsheni
+DanielKusyDev:
+ login: DanielKusyDev
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/36250676?u=2ea6114ff751fc48b55f231987a0e2582c6b1bd2&v=4
+ url: https://github.com/DanielKusyDev
+DanielYang59:
+ login: DanielYang59
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/80093591?u=63873f701c7c74aac83c906800a1dddc0bc8c92f&v=4
+ url: https://github.com/DanielYang59
+blueswen:
+ login: blueswen
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/1564148?u=6d6b8cc8f2b5cef715e68d6175154a8a94d518ee&v=4
+ url: https://github.com/blueswen
diff --git a/docs/en/data/external_links.yml b/docs/en/data/external_links.yml
index 15f6169ee..50f84ecbf 100644
--- a/docs/en/data/external_links.yml
+++ b/docs/en/data/external_links.yml
@@ -1,5 +1,9 @@
Articles:
English:
+ - author: Balthazar Rouberol
+ author_link: https://balthazar-rouberol.com
+ link: https://blog.balthazar-rouberol.com/how-to-profile-a-fastapi-asynchronous-request
+ title: How to profile a FastAPI asynchronous request
- author: Stephen Siegert - Neon
link: https://neon.tech/blog/deploy-a-serverless-fastapi-app-with-neon-postgres-and-aws-app-runner-at-any-scale
title: Deploy a Serverless FastAPI App with Neon Postgres and AWS App Runner at any scale
@@ -264,6 +268,14 @@ Articles:
author_link: https://devonray.com
link: https://devonray.com/blog/deploying-a-fastapi-project-using-aws-lambda-aurora-cdk
title: Deployment using Docker, Lambda, Aurora, CDK & GH Actions
+ - author: Shubhendra Kushwaha
+ author_link: https://www.linkedin.com/in/theshubhendra/
+ link: https://theshubhendra.medium.com/mastering-soft-delete-advanced-sqlalchemy-techniques-4678f4738947
+ title: 'Mastering Soft Delete: Advanced SQLAlchemy Techniques'
+ - author: Shubhendra Kushwaha
+ author_link: https://www.linkedin.com/in/theshubhendra/
+ link: https://theshubhendra.medium.com/role-based-row-filtering-advanced-sqlalchemy-techniques-733e6b1328f6
+ title: 'Role based row filtering: Advanced SQLAlchemy Techniques'
German:
- author: Marcel Sander (actidoo)
author_link: https://www.actidoo.com
@@ -327,6 +339,10 @@ Articles:
link: https://qiita.com/mtitg/items/47770e9a562dd150631d
title: FastAPI|DB接続してCRUDするPython製APIサーバーを構築
Portuguese:
+ - author: Eduardo Mendes
+ author_link: https://bolha.us/@dunossauro
+ link: https://fastapidozero.dunossauro.com/
+ title: FastAPI do ZERO
- author: Jessica Temporal
author_link: https://jtemporal.com/socials
link: https://jtemporal.com/dicas-para-migrar-de-flask-para-fastapi-e-vice-versa/
@@ -395,3 +411,8 @@ Talks:
author_link: https://twitter.com/chriswithers13
link: https://www.youtube.com/watch?v=3DLwPcrE5mA
title: 'PyCon UK 2019: FastAPI from the ground up'
+ Taiwanese:
+ - author: Blueswen
+ author_link: https://github.com/blueswen
+ link: https://www.youtube.com/watch?v=y3sumuoDq4w
+ title: 'PyCon TW 2024: 全方位強化 Python 服務可觀測性:以 FastAPI 和 Grafana Stack 為例'
diff --git a/docs/en/data/github_sponsors.yml b/docs/en/data/github_sponsors.yml
index 5f0be61c2..efc5cbfcc 100644
--- a/docs/en/data/github_sponsors.yml
+++ b/docs/en/data/github_sponsors.yml
@@ -1,58 +1,70 @@
sponsors:
-- - login: bump-sh
- avatarUrl: https://avatars.githubusercontent.com/u/33217836?v=4
- url: https://github.com/bump-sh
+- - login: renderinc
+ avatarUrl: https://avatars.githubusercontent.com/u/36424661?v=4
+ url: https://github.com/renderinc
+ - login: Nixtla
+ avatarUrl: https://avatars.githubusercontent.com/u/79945230?v=4
+ url: https://github.com/Nixtla
+ - login: andrew-propelauth
+ avatarUrl: https://avatars.githubusercontent.com/u/89474256?u=c98993dec8553c09d424ede67bbe86e5c35f48c9&v=4
+ url: https://github.com/andrew-propelauth
+ - login: blockbee-io
+ avatarUrl: https://avatars.githubusercontent.com/u/115143449?u=1b8620c2d6567c4df2111a371b85a51f448f9b85&v=4
+ url: https://github.com/blockbee-io
+ - login: zuplo
+ avatarUrl: https://avatars.githubusercontent.com/u/85497839?v=4
+ url: https://github.com/zuplo
+ - login: coderabbitai
+ avatarUrl: https://avatars.githubusercontent.com/u/132028505?v=4
+ url: https://github.com/coderabbitai
+ - login: subtotal
+ avatarUrl: https://avatars.githubusercontent.com/u/176449348?v=4
+ url: https://github.com/subtotal
- login: porter-dev
avatarUrl: https://avatars.githubusercontent.com/u/62078005?v=4
url: https://github.com/porter-dev
- - login: andrew-propelauth
- avatarUrl: https://avatars.githubusercontent.com/u/89474256?u=1188c27cb744bbec36447a2cfd4453126b2ddb5c&v=4
- url: https://github.com/andrew-propelauth
- - login: zanfaruqui
- avatarUrl: https://avatars.githubusercontent.com/u/104461687?v=4
- url: https://github.com/zanfaruqui
- - login: Alek99
- avatarUrl: https://avatars.githubusercontent.com/u/38776361?u=bd6c163fe787c2de1a26c881598e54b67e2482dd&v=4
- url: https://github.com/Alek99
- - login: cryptapi
- avatarUrl: https://avatars.githubusercontent.com/u/44925437?u=61369138589bc7fee6c417f3fbd50fbd38286cc4&v=4
- url: https://github.com/cryptapi
- - login: Kong
- avatarUrl: https://avatars.githubusercontent.com/u/962416?v=4
- url: https://github.com/Kong
- - login: codacy
- avatarUrl: https://avatars.githubusercontent.com/u/1834093?v=4
- url: https://github.com/codacy
- login: scalar
avatarUrl: https://avatars.githubusercontent.com/u/301879?v=4
url: https://github.com/scalar
- - login: ObliviousAI
avatarUrl: https://avatars.githubusercontent.com/u/65656077?v=4
url: https://github.com/ObliviousAI
-- - login: databento
- avatarUrl: https://avatars.githubusercontent.com/u/64141749?v=4
- url: https://github.com/databento
+- - login: dribia
+ avatarUrl: https://avatars.githubusercontent.com/u/41189616?v=4
+ url: https://github.com/dribia
- login: svix
avatarUrl: https://avatars.githubusercontent.com/u/80175132?v=4
url: https://github.com/svix
- - login: deepset-ai
- avatarUrl: https://avatars.githubusercontent.com/u/51827949?v=4
- url: https://github.com/deepset-ai
- - login: mikeckennedy
- avatarUrl: https://avatars.githubusercontent.com/u/2035561?u=ce6165b799ea3164cb6f5ff54ea08042057442af&v=4
- url: https://github.com/mikeckennedy
- - login: ndimares
- avatarUrl: https://avatars.githubusercontent.com/u/6267663?u=cfb27efde7a7212be8142abb6c058a1aeadb41b1&v=4
- url: https://github.com/ndimares
-- - login: takashi-yoneya
- avatarUrl: https://avatars.githubusercontent.com/u/33813153?u=2d0522bceba0b8b69adf1f2db866503bd96f944e&v=4
- url: https://github.com/takashi-yoneya
+ - login: stainless-api
+ avatarUrl: https://avatars.githubusercontent.com/u/88061651?v=4
+ url: https://github.com/stainless-api
+ - login: speakeasy-api
+ avatarUrl: https://avatars.githubusercontent.com/u/91446104?v=4
+ url: https://github.com/speakeasy-api
+ - login: snapit-cypher
+ avatarUrl: https://avatars.githubusercontent.com/u/115662654?v=4
+ url: https://github.com/snapit-cypher
+ - login: databento
+ avatarUrl: https://avatars.githubusercontent.com/u/64141749?v=4
+ url: https://github.com/databento
+ - login: permitio
+ avatarUrl: https://avatars.githubusercontent.com/u/71775833?v=4
+ url: https://github.com/permitio
+- - login: mercedes-benz
+ avatarUrl: https://avatars.githubusercontent.com/u/34240465?v=4
+ url: https://github.com/mercedes-benz
- login: xoflare
avatarUrl: https://avatars.githubusercontent.com/u/74335107?v=4
url: https://github.com/xoflare
- login: marvin-robot
avatarUrl: https://avatars.githubusercontent.com/u/41086007?u=b9fcab402d0cd0aec738b6574fe60855cb0cd36d&v=4
url: https://github.com/marvin-robot
+ - login: Ponte-Energy-Partners
+ avatarUrl: https://avatars.githubusercontent.com/u/114745848?v=4
+ url: https://github.com/Ponte-Energy-Partners
+ - login: LambdaTest-Inc
+ avatarUrl: https://avatars.githubusercontent.com/u/171592363?u=96606606a45fa170427206199014f2a5a2a4920b&v=4
+ url: https://github.com/LambdaTest-Inc
- login: BoostryJP
avatarUrl: https://avatars.githubusercontent.com/u/57932412?v=4
url: https://github.com/BoostryJP
@@ -62,50 +74,47 @@ sponsors:
- - login: Trivie
avatarUrl: https://avatars.githubusercontent.com/u/8161763?v=4
url: https://github.com/Trivie
-- - login: americanair
- avatarUrl: https://avatars.githubusercontent.com/u/12281813?v=4
- url: https://github.com/americanair
- - login: CanoaPBC
- avatarUrl: https://avatars.githubusercontent.com/u/64223768?v=4
- url: https://github.com/CanoaPBC
- - login: mainframeindustries
+- - login: takashi-yoneya
+ avatarUrl: https://avatars.githubusercontent.com/u/33813153?u=2d0522bceba0b8b69adf1f2db866503bd96f944e&v=4
+ url: https://github.com/takashi-yoneya
+ - login: Doist
+ avatarUrl: https://avatars.githubusercontent.com/u/2565372?v=4
+ url: https://github.com/Doist
+- - login: mainframeindustries
avatarUrl: https://avatars.githubusercontent.com/u/55092103?v=4
url: https://github.com/mainframeindustries
- - login: mangualero
- avatarUrl: https://avatars.githubusercontent.com/u/3422968?u=c59272d7b5a912d6126fd6c6f17db71e20f506eb&v=4
- url: https://github.com/mangualero
- - login: birkjernstrom
- avatarUrl: https://avatars.githubusercontent.com/u/281715?u=4be14b43f76b4bd497b1941309bb390250b405e6&v=4
- url: https://github.com/birkjernstrom
- login: yasyf
avatarUrl: https://avatars.githubusercontent.com/u/709645?u=f36736b3c6a85f578886ecc42a740e7b436e7a01&v=4
url: https://github.com/yasyf
+- - login: alixlahuec
+ avatarUrl: https://avatars.githubusercontent.com/u/29543316?u=44357eb2a93bccf30fb9d389b8befe94a3d00985&v=4
+ url: https://github.com/alixlahuec
- - login: primer-io
avatarUrl: https://avatars.githubusercontent.com/u/62146168?v=4
url: https://github.com/primer-io
- - login: povilasb
- avatarUrl: https://avatars.githubusercontent.com/u/1213442?u=b11f58ed6ceea6e8297c9b310030478ebdac894d&v=4
- url: https://github.com/povilasb
-- - login: jhundman
- avatarUrl: https://avatars.githubusercontent.com/u/24263908?v=4
- url: https://github.com/jhundman
- - login: upciti
+- - login: upciti
avatarUrl: https://avatars.githubusercontent.com/u/43346262?v=4
url: https://github.com/upciti
- - login: samuelcolvin
avatarUrl: https://avatars.githubusercontent.com/u/4039449?u=42eb3b833047c8c4b4f647a031eaef148c16d93f&v=4
url: https://github.com/samuelcolvin
- - login: Kludex
- avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=62adc405ef418f4b6c8caa93d3eb8ab107bc4927&v=4
- url: https://github.com/Kludex
- - login: b-rad-c
- avatarUrl: https://avatars.githubusercontent.com/u/25362581?u=5bb10629f4015b62bec1f9a366675d5085551af9&v=4
- url: https://github.com/b-rad-c
+ - login: otosky
+ avatarUrl: https://avatars.githubusercontent.com/u/42260747?u=69d089387c743d89427aa4ad8740cfb34045a9e0&v=4
+ url: https://github.com/otosky
+ - login: ramonalmeidam
+ avatarUrl: https://avatars.githubusercontent.com/u/45269580?u=3358750b3a5854d7c3ed77aaca7dd20a0f529d32&v=4
+ url: https://github.com/ramonalmeidam
+ - login: ashi-agrawal
+ avatarUrl: https://avatars.githubusercontent.com/u/17105294?u=99c7a854035e5398d8e7b674f2d42baae6c957f8&v=4
+ url: https://github.com/ashi-agrawal
+ - login: RaamEEIL
+ avatarUrl: https://avatars.githubusercontent.com/u/20320552?v=4
+ url: https://github.com/RaamEEIL
- login: ehaca
avatarUrl: https://avatars.githubusercontent.com/u/25950317?u=cec1a3e0643b785288ae8260cc295a85ab344995&v=4
url: https://github.com/ehaca
- login: raphaellaude
- avatarUrl: https://avatars.githubusercontent.com/u/28026311?u=9ae4b158c0d2cb29ebd46df6b6edb7de08a67566&v=4
+ avatarUrl: https://avatars.githubusercontent.com/u/28026311?u=91e1c00d9ac4f8045527e13de8050d504531cbc0&v=4
url: https://github.com/raphaellaude
- login: timlrx
avatarUrl: https://avatars.githubusercontent.com/u/28362229?u=9a745ca31372ee324af682715ae88ce8522f9094&v=4
@@ -113,84 +122,45 @@ sponsors:
- login: Leay15
avatarUrl: https://avatars.githubusercontent.com/u/32212558?u=c4aa9c1737e515959382a5515381757b1fd86c53&v=4
url: https://github.com/Leay15
- - login: ygorpontelo
- avatarUrl: https://avatars.githubusercontent.com/u/32963605?u=35f7103f9c4c4c2589ae5737ee882e9375ef072e&v=4
- url: https://github.com/ygorpontelo
- login: ProteinQure
avatarUrl: https://avatars.githubusercontent.com/u/33707203?v=4
url: https://github.com/ProteinQure
- - login: catherinenelson1
- avatarUrl: https://avatars.githubusercontent.com/u/11951946?u=e714b957185b8cf3d301cced7fc3ad2842122c6a&v=4
- url: https://github.com/catherinenelson1
- - login: jsoques
- avatarUrl: https://avatars.githubusercontent.com/u/12414216?u=620921d94196546cc8b9eae2cc4cbc3f95bab42f&v=4
- url: https://github.com/jsoques
- - login: joeds13
- avatarUrl: https://avatars.githubusercontent.com/u/13631604?u=628eb122e08bef43767b3738752b883e8e7f6259&v=4
- url: https://github.com/joeds13
- - login: dannywade
- avatarUrl: https://avatars.githubusercontent.com/u/13680237?u=418ee985bd41577b20fde81417fb2d901e875e8a&v=4
- url: https://github.com/dannywade
- - login: khadrawy
- avatarUrl: https://avatars.githubusercontent.com/u/13686061?u=59f25ef42ecf04c22657aac4238ce0e2d3d30304&v=4
- url: https://github.com/khadrawy
- - login: mjohnsey
- avatarUrl: https://avatars.githubusercontent.com/u/16784016?u=38fad2e6b411244560b3af99c5f5a4751bc81865&v=4
- url: https://github.com/mjohnsey
- - login: ashi-agrawal
- avatarUrl: https://avatars.githubusercontent.com/u/17105294?u=99c7a854035e5398d8e7b674f2d42baae6c957f8&v=4
- url: https://github.com/ashi-agrawal
- - login: sepsi77
- avatarUrl: https://avatars.githubusercontent.com/u/18682303?v=4
- url: https://github.com/sepsi77
- - login: wedwardbeck
- avatarUrl: https://avatars.githubusercontent.com/u/19333237?u=1de4ae2bf8d59eb4c013f21d863cbe0f2010575f&v=4
- url: https://github.com/wedwardbeck
- - login: RaamEEIL
- avatarUrl: https://avatars.githubusercontent.com/u/20320552?v=4
- url: https://github.com/RaamEEIL
- - login: anthonycepeda
- avatarUrl: https://avatars.githubusercontent.com/u/72019805?u=60bdf46240cff8fca482ff0fc07d963fd5e1a27c&v=4
- url: https://github.com/anthonycepeda
- - login: patricioperezv
- avatarUrl: https://avatars.githubusercontent.com/u/73832292?u=5f471f156e19ee7920e62ae0f4a47b95580e61cf&v=4
- url: https://github.com/patricioperezv
- login: kaoru0310
avatarUrl: https://avatars.githubusercontent.com/u/80977929?u=1b61d10142b490e56af932ddf08a390fae8ee94f&v=4
url: https://github.com/kaoru0310
- login: DelfinaCare
avatarUrl: https://avatars.githubusercontent.com/u/83734439?v=4
url: https://github.com/DelfinaCare
- - login: Eruditis
+ - login: Karine-Bauch
+ avatarUrl: https://avatars.githubusercontent.com/u/90465103?u=7feb1018abb1a5631cfd9a91fea723d1ceb5f49b&v=4
+ url: https://github.com/Karine-Bauch
+ - login: eruditis
avatarUrl: https://avatars.githubusercontent.com/u/95244703?v=4
- url: https://github.com/Eruditis
+ url: https://github.com/eruditis
- login: jugeeem
avatarUrl: https://avatars.githubusercontent.com/u/116043716?u=ae590d79c38ac79c91b9c5caa6887d061e865a3d&v=4
url: https://github.com/jugeeem
- - login: apitally
- avatarUrl: https://avatars.githubusercontent.com/u/138365043?v=4
- url: https://github.com/apitally
- login: logic-automation
avatarUrl: https://avatars.githubusercontent.com/u/144732884?v=4
url: https://github.com/logic-automation
- - login: ddilidili
- avatarUrl: https://avatars.githubusercontent.com/u/42176885?u=c0a849dde06987434653197b5f638d3deb55fc6c&v=4
- url: https://github.com/ddilidili
- - login: ramonalmeidam
- avatarUrl: https://avatars.githubusercontent.com/u/45269580?u=3358750b3a5854d7c3ed77aaca7dd20a0f529d32&v=4
- url: https://github.com/ramonalmeidam
+ - login: roboflow
+ avatarUrl: https://avatars.githubusercontent.com/u/53104118?v=4
+ url: https://github.com/roboflow
- login: dudikbender
avatarUrl: https://avatars.githubusercontent.com/u/53487583?u=3a57542938ebfd57579a0111db2b297e606d9681&v=4
url: https://github.com/dudikbender
- - login: prodhype
- avatarUrl: https://avatars.githubusercontent.com/u/60444672?u=3f278cff25ea37ead487d7861d4a984795de819e&v=4
- url: https://github.com/prodhype
- login: patsatsia
avatarUrl: https://avatars.githubusercontent.com/u/61111267?u=3271b85f7a37b479c8d0ae0a235182e83c166edf&v=4
url: https://github.com/patsatsia
- - login: tcsmith
- avatarUrl: https://avatars.githubusercontent.com/u/989034?u=7d8d741552b3279e8f4d3878679823a705a46f8f&v=4
- url: https://github.com/tcsmith
+ - login: anthonycepeda
+ avatarUrl: https://avatars.githubusercontent.com/u/72019805?u=60bdf46240cff8fca482ff0fc07d963fd5e1a27c&v=4
+ url: https://github.com/anthonycepeda
+ - login: patricioperezv
+ avatarUrl: https://avatars.githubusercontent.com/u/73832292?u=5f471f156e19ee7920e62ae0f4a47b95580e61cf&v=4
+ url: https://github.com/patricioperezv
+ - login: chickenandstats
+ avatarUrl: https://avatars.githubusercontent.com/u/79477966?u=ae2b894aa954070db1d7830dab99b49eba4e4567&v=4
+ url: https://github.com/chickenandstats
- login: dodo5522
avatarUrl: https://avatars.githubusercontent.com/u/1362607?u=9bf1e0e520cccc547c046610c468ce6115bbcf9f&v=4
url: https://github.com/dodo5522
@@ -200,12 +170,6 @@ sponsors:
- login: knallgelb
avatarUrl: https://avatars.githubusercontent.com/u/2358812?u=c48cb6362b309d74cbf144bd6ad3aed3eb443e82&v=4
url: https://github.com/knallgelb
- - login: johannquerne
- avatarUrl: https://avatars.githubusercontent.com/u/2736484?u=9b3381546a25679913a2b08110e4373c98840821&v=4
- url: https://github.com/johannquerne
- - login: Shark009
- avatarUrl: https://avatars.githubusercontent.com/u/3163309?u=0c6f4091b0eda05c44c390466199826e6dc6e431&v=4
- url: https://github.com/Shark009
- login: dblackrun
avatarUrl: https://avatars.githubusercontent.com/u/3528486?v=4
url: https://github.com/dblackrun
@@ -215,15 +179,30 @@ sponsors:
- login: kennywakeland
avatarUrl: https://avatars.githubusercontent.com/u/3631417?u=7c8f743f1ae325dfadea7c62bbf1abd6a824fc55&v=4
url: https://github.com/kennywakeland
- - login: simw
- avatarUrl: https://avatars.githubusercontent.com/u/6322526?v=4
- url: https://github.com/simw
- - login: koconder
- avatarUrl: https://avatars.githubusercontent.com/u/25068?u=582657b23622aaa3dfe68bd028a780f272f456fa&v=4
- url: https://github.com/koconder
+ - login: aacayaco
+ avatarUrl: https://avatars.githubusercontent.com/u/3634801?u=eaadda178c964178fcb64886f6c732172c8f8219&v=4
+ url: https://github.com/aacayaco
+ - login: anomaly
+ avatarUrl: https://avatars.githubusercontent.com/u/3654837?v=4
+ url: https://github.com/anomaly
+ - login: mj0331
+ avatarUrl: https://avatars.githubusercontent.com/u/3890353?u=1c627ac1a024515b4871de5c3ebbfaa1a57f65d4&v=4
+ url: https://github.com/mj0331
+ - login: gorhack
+ avatarUrl: https://avatars.githubusercontent.com/u/4141690?u=ec119ebc4bdf00a7bc84657a71aa17834f4f27f3&v=4
+ url: https://github.com/gorhack
+ - login: Ryandaydev
+ avatarUrl: https://avatars.githubusercontent.com/u/4292423?u=679ff84cb7b988c5795a5fa583857f574a055763&v=4
+ url: https://github.com/Ryandaydev
+ - login: vincentkoc
+ avatarUrl: https://avatars.githubusercontent.com/u/25068?u=fbd5b2d51142daa4bdbc21e21953a3b8b8188a4a&v=4
+ url: https://github.com/vincentkoc
- login: jstanden
avatarUrl: https://avatars.githubusercontent.com/u/63288?u=c3658d57d2862c607a0e19c2101c3c51876e36ad&v=4
url: https://github.com/jstanden
+ - login: paulcwatts
+ avatarUrl: https://avatars.githubusercontent.com/u/150269?u=1819e145d573b44f0ad74b87206d21cd60331d4e&v=4
+ url: https://github.com/paulcwatts
- login: andreaso
avatarUrl: https://avatars.githubusercontent.com/u/285964?u=837265cc7562c0685f25b2d81cd9de0434fe107c&v=4
url: https://github.com/andreaso
@@ -248,39 +227,36 @@ sponsors:
- login: mintuhouse
avatarUrl: https://avatars.githubusercontent.com/u/769950?u=ecfbd79a97d33177e0d093ddb088283cf7fe8444&v=4
url: https://github.com/mintuhouse
- - login: Rehket
- avatarUrl: https://avatars.githubusercontent.com/u/7015688?u=3afb0ba200feebbc7f958950e92db34df2a3c172&v=4
- url: https://github.com/Rehket
- - login: hiancdtrsnm
- avatarUrl: https://avatars.githubusercontent.com/u/7343177?v=4
- url: https://github.com/hiancdtrsnm
- login: TrevorBenson
- avatarUrl: https://avatars.githubusercontent.com/u/9167887?u=afdd1766fdb79e04e59094cc6a54cd011ee7f686&v=4
+ avatarUrl: https://avatars.githubusercontent.com/u/9167887?u=dccbea3327a57750923333d8ebf1a0b3f1948949&v=4
url: https://github.com/TrevorBenson
- login: wdwinslow
avatarUrl: https://avatars.githubusercontent.com/u/11562137?u=dc01daafb354135603a263729e3d26d939c0c452&v=4
url: https://github.com/wdwinslow
- - login: aacayaco
- avatarUrl: https://avatars.githubusercontent.com/u/3634801?u=eaadda178c964178fcb64886f6c732172c8f8219&v=4
- url: https://github.com/aacayaco
- - login: anomaly
- avatarUrl: https://avatars.githubusercontent.com/u/3654837?v=4
- url: https://github.com/anomaly
- - login: jgreys
- avatarUrl: https://avatars.githubusercontent.com/u/4136890?u=096820d1ef89877d57d0f68e669ead8b0fde84df&v=4
- url: https://github.com/jgreys
- - login: Ryandaydev
- avatarUrl: https://avatars.githubusercontent.com/u/4292423?u=48f68868db8886fce31a1d802c1003914c6cd7c6&v=4
- url: https://github.com/Ryandaydev
+ - login: catherinenelson1
+ avatarUrl: https://avatars.githubusercontent.com/u/11951946?u=fe11bc35d36b6038cd46a946e4e46ef8aa5688ab&v=4
+ url: https://github.com/catherinenelson1
+ - login: jsoques
+ avatarUrl: https://avatars.githubusercontent.com/u/12414216?u=620921d94196546cc8b9eae2cc4cbc3f95bab42f&v=4
+ url: https://github.com/jsoques
+ - login: joeds13
+ avatarUrl: https://avatars.githubusercontent.com/u/13631604?u=628eb122e08bef43767b3738752b883e8e7f6259&v=4
+ url: https://github.com/joeds13
+ - login: dannywade
+ avatarUrl: https://avatars.githubusercontent.com/u/13680237?u=418ee985bd41577b20fde81417fb2d901e875e8a&v=4
+ url: https://github.com/dannywade
+ - login: khadrawy
+ avatarUrl: https://avatars.githubusercontent.com/u/13686061?u=59f25ef42ecf04c22657aac4238ce0e2d3d30304&v=4
+ url: https://github.com/khadrawy
+ - login: mjohnsey
+ avatarUrl: https://avatars.githubusercontent.com/u/16784016?u=38fad2e6b411244560b3af99c5f5a4751bc81865&v=4
+ url: https://github.com/mjohnsey
- login: jaredtrog
avatarUrl: https://avatars.githubusercontent.com/u/4381365?v=4
url: https://github.com/jaredtrog
- login: oliverxchen
avatarUrl: https://avatars.githubusercontent.com/u/4471774?u=534191f25e32eeaadda22dfab4b0a428733d5489&v=4
url: https://github.com/oliverxchen
- - login: ennui93
- avatarUrl: https://avatars.githubusercontent.com/u/5300907?u=5b5452725ddb391b2caaebf34e05aba873591c3a&v=4
- url: https://github.com/ennui93
- login: ternaus
avatarUrl: https://avatars.githubusercontent.com/u/5481618?u=513a26b02a39e7a28d587cd37c6cc877ea368e6e&v=4
url: https://github.com/ternaus
@@ -288,14 +264,47 @@ sponsors:
avatarUrl: https://avatars.githubusercontent.com/u/5920492?u=208d419cf667b8ac594c82a8db01932c7e50d057&v=4
url: https://github.com/eseglem
- login: FernandoCelmer
- avatarUrl: https://avatars.githubusercontent.com/u/6262214?u=d29fff3fd862fda4ca752079f13f32e84c762ea4&v=4
+ avatarUrl: https://avatars.githubusercontent.com/u/6262214?u=58ba6d5888fa7f355934e52db19f950e20b38162&v=4
url: https://github.com/FernandoCelmer
-- - login: getsentry
- avatarUrl: https://avatars.githubusercontent.com/u/1396951?v=4
- url: https://github.com/getsentry
+ - login: Rehket
+ avatarUrl: https://avatars.githubusercontent.com/u/7015688?u=3afb0ba200feebbc7f958950e92db34df2a3c172&v=4
+ url: https://github.com/Rehket
+ - login: hiancdtrsnm
+ avatarUrl: https://avatars.githubusercontent.com/u/7343177?v=4
+ url: https://github.com/hiancdtrsnm
+- - login: jpizquierdo
+ avatarUrl: https://avatars.githubusercontent.com/u/6716239?v=4
+ url: https://github.com/jpizquierdo
- - login: pawamoy
avatarUrl: https://avatars.githubusercontent.com/u/3999221?u=b030e4c89df2f3a36bc4710b925bdeb6745c9856&v=4
url: https://github.com/pawamoy
+ - login: bnkc
+ avatarUrl: https://avatars.githubusercontent.com/u/34930566?u=db5e6f4f87836cad26c2aa90ce390ce49041c5a9&v=4
+ url: https://github.com/bnkc
+ - login: petercool
+ avatarUrl: https://avatars.githubusercontent.com/u/37613029?u=81c525232bb35780945a68e88afd96bb2cdad9c4&v=4
+ url: https://github.com/petercool
+ - login: siavashyj
+ avatarUrl: https://avatars.githubusercontent.com/u/43583410?u=562005ddc7901cd27a1219a118a2363817b14977&v=4
+ url: https://github.com/siavashyj
+ - login: mobyw
+ avatarUrl: https://avatars.githubusercontent.com/u/44370805?v=4
+ url: https://github.com/mobyw
+ - login: ArtyomVancyan
+ avatarUrl: https://avatars.githubusercontent.com/u/44609997?v=4
+ url: https://github.com/ArtyomVancyan
+ - login: caviri
+ avatarUrl: https://avatars.githubusercontent.com/u/45425937?u=4e14bd64282bad8f385eafbdb004b5a279366d6e&v=4
+ url: https://github.com/caviri
+ - login: hgalytoby
+ avatarUrl: https://avatars.githubusercontent.com/u/50397689?u=62c7ff3519858423579676cd0efbd7e3f1ffe63a&v=4
+ url: https://github.com/hgalytoby
+ - login: browniebroke
+ avatarUrl: https://avatars.githubusercontent.com/u/861044?u=5abfca5588f3e906b31583d7ee62f6de4b68aa24&v=4
+ url: https://github.com/browniebroke
+ - login: joshuatz
+ avatarUrl: https://avatars.githubusercontent.com/u/17817563?u=f1bf05b690d1fc164218f0b420cdd3acb7913e21&v=4
+ url: https://github.com/joshuatz
- login: SebTota
avatarUrl: https://avatars.githubusercontent.com/u/25122511?v=4
url: https://github.com/SebTota
@@ -314,92 +323,26 @@ sponsors:
- login: engineerjoe440
avatarUrl: https://avatars.githubusercontent.com/u/33275230?u=eb223cad27017bb1e936ee9b429b450d092d0236&v=4
url: https://github.com/engineerjoe440
- - login: bnkc
- avatarUrl: https://avatars.githubusercontent.com/u/34930566?u=db5e6f4f87836cad26c2aa90ce390ce49041c5a9&v=4
- url: https://github.com/bnkc
- - login: DevOpsKev
- avatarUrl: https://avatars.githubusercontent.com/u/36336550?u=6ccd5978fdaab06f37e22f2a14a7439341df7f67&v=4
- url: https://github.com/DevOpsKev
- - login: petercool
- avatarUrl: https://avatars.githubusercontent.com/u/37613029?u=81c525232bb35780945a68e88afd96bb2cdad9c4&v=4
- url: https://github.com/petercool
- - login: JimFawkes
- avatarUrl: https://avatars.githubusercontent.com/u/12075115?u=dc58ecfd064d72887c34bf500ddfd52592509acd&v=4
- url: https://github.com/JimFawkes
- - login: artempronevskiy
- avatarUrl: https://avatars.githubusercontent.com/u/12235104?u=03df6e1e55c9c6fe5d230adabb8dd7d43d8bbe8f&v=4
- url: https://github.com/artempronevskiy
- - login: TheR1D
- avatarUrl: https://avatars.githubusercontent.com/u/16740832?u=b0dfdbdb27b79729430c71c6128962f77b7b53f7&v=4
- url: https://github.com/TheR1D
- - login: joshuatz
- avatarUrl: https://avatars.githubusercontent.com/u/17817563?u=f1bf05b690d1fc164218f0b420cdd3acb7913e21&v=4
- url: https://github.com/joshuatz
- - login: jangia
- avatarUrl: https://avatars.githubusercontent.com/u/17927101?u=9261b9bb0c3e3bb1ecba43e8915dc58d8c9a077e&v=4
- url: https://github.com/jangia
- - login: jackleeio
- avatarUrl: https://avatars.githubusercontent.com/u/20477587?u=c5184dab6d021733d10c8f975b20e391856303d6&v=4
- url: https://github.com/jackleeio
- - login: shuheng-liu
- avatarUrl: https://avatars.githubusercontent.com/u/22414322?u=813c45f30786c6b511b21a661def025d8f7b609e&v=4
- url: https://github.com/shuheng-liu
- - login: pers0n4
- avatarUrl: https://avatars.githubusercontent.com/u/24864600?u=f211a13a7b572cbbd7779b9c8d8cb428cc7ba07e&v=4
- url: https://github.com/pers0n4
- - login: curegit
- avatarUrl: https://avatars.githubusercontent.com/u/37978051?u=1733c322079118c0cdc573c03d92813f50a9faec&v=4
- url: https://github.com/curegit
- - login: fernandosmither
- avatarUrl: https://avatars.githubusercontent.com/u/66154723?u=f79753eb207d01cca5bbb91ac62db6123e7622d1&v=4
- url: https://github.com/fernandosmither
+ - login: lukzmu
+ avatarUrl: https://avatars.githubusercontent.com/u/175964415?u=83ea9b0b7b7b0f15bcb5747d93f303447a19a00b&v=4
+ url: https://github.com/lukzmu
+ - login: conservative-dude
+ avatarUrl: https://avatars.githubusercontent.com/u/55538308?u=f250c44942ea6e73a6bd90739b381c470c192c11&v=4
+ url: https://github.com/conservative-dude
+ - login: CR1337
+ avatarUrl: https://avatars.githubusercontent.com/u/62649536?u=57a6aab10d2421a497306da8bcded01b826c54ae&v=4
+ url: https://github.com/CR1337
- login: PunRabbit
avatarUrl: https://avatars.githubusercontent.com/u/70463212?u=1a835cfbc99295a60c8282f6aa6199d1b42241a5&v=4
url: https://github.com/PunRabbit
- login: PelicanQ
avatarUrl: https://avatars.githubusercontent.com/u/77930606?v=4
url: https://github.com/PelicanQ
- - login: tahmarrrr23
- avatarUrl: https://avatars.githubusercontent.com/u/138208610?u=465a46b0ff72a74252d3e3a71ac7d2f1919cda28&v=4
- url: https://github.com/tahmarrrr23
- - login: zk-Call
- avatarUrl: https://avatars.githubusercontent.com/u/147117264?v=4
- url: https://github.com/zk-Call
- - login: kristiangronberg
- avatarUrl: https://avatars.githubusercontent.com/u/42678548?v=4
- url: https://github.com/kristiangronberg
- - login: leonardo-holguin
- avatarUrl: https://avatars.githubusercontent.com/u/43093055?u=b59013d52fb6c4e0954aaaabc0882bd844985b38&v=4
- url: https://github.com/leonardo-holguin
- - login: arrrrrmin
- avatarUrl: https://avatars.githubusercontent.com/u/43553423?u=36a3880a6eb29309c19e6cadbb173bafbe91deb1&v=4
- url: https://github.com/arrrrrmin
- - login: mobyw
- avatarUrl: https://avatars.githubusercontent.com/u/44370805?v=4
- url: https://github.com/mobyw
- - login: ArtyomVancyan
- avatarUrl: https://avatars.githubusercontent.com/u/44609997?v=4
- url: https://github.com/ArtyomVancyan
- - login: harol97
- avatarUrl: https://avatars.githubusercontent.com/u/49042862?u=2b18e115ab73f5f09a280be2850f93c58a12e3d2&v=4
- url: https://github.com/harol97
- - login: hgalytoby
- avatarUrl: https://avatars.githubusercontent.com/u/50397689?u=62c7ff3519858423579676cd0efbd7e3f1ffe63a&v=4
- url: https://github.com/hgalytoby
- - login: conservative-dude
- avatarUrl: https://avatars.githubusercontent.com/u/55538308?u=f250c44942ea6e73a6bd90739b381c470c192c11&v=4
- url: https://github.com/conservative-dude
- - login: Joaopcamposs
- avatarUrl: https://avatars.githubusercontent.com/u/57376574?u=699d5ba5ee66af1d089df6b5e532b97169e73650&v=4
- url: https://github.com/Joaopcamposs
- - login: browniebroke
- avatarUrl: https://avatars.githubusercontent.com/u/861044?u=5abfca5588f3e906b31583d7ee62f6de4b68aa24&v=4
- url: https://github.com/browniebroke
- login: miguelgr
avatarUrl: https://avatars.githubusercontent.com/u/1484589?u=54556072b8136efa12ae3b6902032ea2a39ace4b&v=4
url: https://github.com/miguelgr
- login: WillHogan
- avatarUrl: https://avatars.githubusercontent.com/u/1661551?u=7036c064cf29781470573865264ec8e60b6b809f&v=4
+ avatarUrl: https://avatars.githubusercontent.com/u/1661551?u=8a80356e3e7d5a417157aba7ea565dabc8678327&v=4
url: https://github.com/WillHogan
- login: my3
avatarUrl: https://avatars.githubusercontent.com/u/1825270?v=4
@@ -407,9 +350,9 @@ sponsors:
- login: leobiscassi
avatarUrl: https://avatars.githubusercontent.com/u/1977418?u=f9f82445a847ab479bd7223debd677fcac6c49a0&v=4
url: https://github.com/leobiscassi
- - login: cbonoz
- avatarUrl: https://avatars.githubusercontent.com/u/2351087?u=fd3e8030b2cc9fbfbb54a65e9890c548a016f58b&v=4
- url: https://github.com/cbonoz
+ - login: Alisa-lisa
+ avatarUrl: https://avatars.githubusercontent.com/u/4137964?u=e7e393504f554f4ff15863a1e01a5746863ef9ce&v=4
+ url: https://github.com/Alisa-lisa
- login: ddanier
avatarUrl: https://avatars.githubusercontent.com/u/113563?u=ed1dc79de72f93bd78581f88ebc6952b62f472da&v=4
url: https://github.com/ddanier
@@ -419,33 +362,12 @@ sponsors:
- login: slafs
avatarUrl: https://avatars.githubusercontent.com/u/210173?v=4
url: https://github.com/slafs
- - login: adamghill
- avatarUrl: https://avatars.githubusercontent.com/u/317045?u=f1349d5ffe84a19f324e204777859fbf69ddf633&v=4
- url: https://github.com/adamghill
- - login: eteq
- avatarUrl: https://avatars.githubusercontent.com/u/346587?v=4
- url: https://github.com/eteq
- - login: dmig
- avatarUrl: https://avatars.githubusercontent.com/u/388564?v=4
- url: https://github.com/dmig
- - login: securancy
- avatarUrl: https://avatars.githubusercontent.com/u/606673?v=4
- url: https://github.com/securancy
+ - login: ceb10n
+ avatarUrl: https://avatars.githubusercontent.com/u/235213?u=edcce471814a1eba9f0cdaa4cd0de18921a940a6&v=4
+ url: https://github.com/ceb10n
- login: tochikuji
avatarUrl: https://avatars.githubusercontent.com/u/851759?v=4
url: https://github.com/tochikuji
- - login: KentShikama
- avatarUrl: https://avatars.githubusercontent.com/u/6329898?u=8b236810db9b96333230430837e1f021f9246da1&v=4
- url: https://github.com/KentShikama
- - login: katnoria
- avatarUrl: https://avatars.githubusercontent.com/u/7674948?u=09767eb13e07e09496c5fee4e5ce21d9eac34a56&v=4
- url: https://github.com/katnoria
- - login: harsh183
- avatarUrl: https://avatars.githubusercontent.com/u/7780198?v=4
- url: https://github.com/harsh183
- - login: hcristea
- avatarUrl: https://avatars.githubusercontent.com/u/7814406?u=61d7a4fcf846983a4606788eac25e1c6c1209ba8&v=4
- url: https://github.com/hcristea
- login: moonape1226
avatarUrl: https://avatars.githubusercontent.com/u/8532038?u=d9f8b855a429fff9397c3833c2ff83849ebf989d&v=4
url: https://github.com/moonape1226
@@ -453,10 +375,10 @@ sponsors:
avatarUrl: https://avatars.githubusercontent.com/u/9369632?u=8c988f1b008a3f601385a3616f9327820f66e3a5&v=4
url: https://github.com/msehnout
- login: xncbf
- avatarUrl: https://avatars.githubusercontent.com/u/9462045?u=2ef1ede118a72c170805f50b9ad07341fd16a354&v=4
+ avatarUrl: https://avatars.githubusercontent.com/u/9462045?u=a80a7bb349555b277645632ed66639ff43400614&v=4
url: https://github.com/xncbf
- login: DMantis
- avatarUrl: https://avatars.githubusercontent.com/u/9536869?v=4
+ avatarUrl: https://avatars.githubusercontent.com/u/9536869?u=652dd0d49717803c0cbcbf44f7740e53cf2d4892&v=4
url: https://github.com/DMantis
- login: hard-coders
avatarUrl: https://avatars.githubusercontent.com/u/9651103?u=95db33927bbff1ed1c07efddeb97ac2ff33068ed&v=4
@@ -464,32 +386,26 @@ sponsors:
- login: supdann
avatarUrl: https://avatars.githubusercontent.com/u/9986994?u=9671810f4ae9504c063227fee34fd47567ff6954&v=4
url: https://github.com/supdann
- - login: satwikkansal
- avatarUrl: https://avatars.githubusercontent.com/u/10217535?u=b12d6ef74ea297de9e46da6933b1a5b7ba9e6a61&v=4
- url: https://github.com/satwikkansal
- login: mntolia
avatarUrl: https://avatars.githubusercontent.com/u/10390224?v=4
url: https://github.com/mntolia
- login: pheanex
avatarUrl: https://avatars.githubusercontent.com/u/10408624?u=5b6bab6ee174aa6e991333e06eb29f628741013d&v=4
url: https://github.com/pheanex
- - login: dzoladz
- avatarUrl: https://avatars.githubusercontent.com/u/10561752?u=5ee314d54aa79592c18566827ad8914debd5630d&v=4
- url: https://github.com/dzoladz
- login: Zuzah
avatarUrl: https://avatars.githubusercontent.com/u/10934846?u=1ef43e075ddc87bd1178372bf4d95ee6175cae27&v=4
url: https://github.com/Zuzah
- - login: Alisa-lisa
- avatarUrl: https://avatars.githubusercontent.com/u/4137964?u=e7e393504f554f4ff15863a1e01a5746863ef9ce&v=4
- url: https://github.com/Alisa-lisa
- - login: Graeme22
- avatarUrl: https://avatars.githubusercontent.com/u/4185684?u=498182a42300d7bcd4de1215190cb17eb501136c&v=4
- url: https://github.com/Graeme22
+ - login: artempronevskiy
+ avatarUrl: https://avatars.githubusercontent.com/u/12235104?u=03df6e1e55c9c6fe5d230adabb8dd7d43d8bbe8f&v=4
+ url: https://github.com/artempronevskiy
+ - login: TheR1D
+ avatarUrl: https://avatars.githubusercontent.com/u/16740832?u=b0dfdbdb27b79729430c71c6128962f77b7b53f7&v=4
+ url: https://github.com/TheR1D
- login: danielunderwood
avatarUrl: https://avatars.githubusercontent.com/u/4472301?v=4
url: https://github.com/danielunderwood
- login: rangulvers
- avatarUrl: https://avatars.githubusercontent.com/u/5235430?v=4
+ avatarUrl: https://avatars.githubusercontent.com/u/5235430?u=e254d4af4ace5a05fa58372ae677c7d26f0d5a53&v=4
url: https://github.com/rangulvers
- login: sdevkota
avatarUrl: https://avatars.githubusercontent.com/u/5250987?u=4ed9a120c89805a8aefda1cbdc0cf6512e64d1b4&v=4
@@ -500,33 +416,45 @@ sponsors:
- login: Baghdady92
avatarUrl: https://avatars.githubusercontent.com/u/5708590?v=4
url: https://github.com/Baghdady92
- - login: jakeecolution
- avatarUrl: https://avatars.githubusercontent.com/u/5884696?u=4a7c7883fb064b593b50cb6697b54687e6f7aafe&v=4
- url: https://github.com/jakeecolution
- - login: stephane-rbn
- avatarUrl: https://avatars.githubusercontent.com/u/5939522?u=eb7ffe768fa3bcbcd04de14fe4a47444cc00ec4c&v=4
- url: https://github.com/stephane-rbn
-- - login: danburonline
- avatarUrl: https://avatars.githubusercontent.com/u/34251194?u=94935cccfbec58083ab1e535212d54f1bf2c978a&v=4
- url: https://github.com/danburonline
- - login: AliYmn
- avatarUrl: https://avatars.githubusercontent.com/u/18416653?u=0de5a262e8b4dc0a08d065f30f7a39941e246530&v=4
- url: https://github.com/AliYmn
- - login: sadikkuzu
- avatarUrl: https://avatars.githubusercontent.com/u/23168063?u=d179c06bb9f65c4167fcab118526819f8e0dac17&v=4
- url: https://github.com/sadikkuzu
- - login: tran-hai-long
- avatarUrl: https://avatars.githubusercontent.com/u/119793901?u=3b173a845dcf099b275bdc9713a69cbbc36040ce&v=4
- url: https://github.com/tran-hai-long
+ - login: KentShikama
+ avatarUrl: https://avatars.githubusercontent.com/u/6329898?u=8b236810db9b96333230430837e1f021f9246da1&v=4
+ url: https://github.com/KentShikama
+ - login: katnoria
+ avatarUrl: https://avatars.githubusercontent.com/u/7674948?u=09767eb13e07e09496c5fee4e5ce21d9eac34a56&v=4
+ url: https://github.com/katnoria
+ - login: harsh183
+ avatarUrl: https://avatars.githubusercontent.com/u/7780198?v=4
+ url: https://github.com/harsh183
+ - login: hcristea
+ avatarUrl: https://avatars.githubusercontent.com/u/7814406?u=19092923a4ea5b338567961c8270b9206a6d81bb&v=4
+ url: https://github.com/hcristea
+- - login: andrecorumba
+ avatarUrl: https://avatars.githubusercontent.com/u/37807517?u=9b9be3b41da9bda60957da9ef37b50dbf65baa61&v=4
+ url: https://github.com/andrecorumba
- login: rwxd
avatarUrl: https://avatars.githubusercontent.com/u/40308458?u=cd04a39e3655923be4f25c2ba8a5a07b3da3230a&v=4
url: https://github.com/rwxd
- - login: ssbarnea
- avatarUrl: https://avatars.githubusercontent.com/u/102495?u=c2efbf6fea2737e21dfc6b1113c4edc9644e9eaa&v=4
- url: https://github.com/ssbarnea
- - login: yuawn
- avatarUrl: https://avatars.githubusercontent.com/u/5111198?u=5315576f3fe1a70fd2d0f02181588f4eea5d353d&v=4
- url: https://github.com/yuawn
- - login: dongzhenye
- avatarUrl: https://avatars.githubusercontent.com/u/5765843?u=fe420c9a4c41e5b060faaf44029f5485616b470d&v=4
- url: https://github.com/dongzhenye
+ - login: morzan1001
+ avatarUrl: https://avatars.githubusercontent.com/u/47593005?u=c30ab7230f82a12a9b938dcb54f84a996931409a&v=4
+ url: https://github.com/morzan1001
+ - login: sadikkuzu
+ avatarUrl: https://avatars.githubusercontent.com/u/23168063?u=d179c06bb9f65c4167fcab118526819f8e0dac17&v=4
+ url: https://github.com/sadikkuzu
+ - login: Olegt0rr
+ avatarUrl: https://avatars.githubusercontent.com/u/25399456?u=3e87b5239a2f4600975ba13be73054f8567c6060&v=4
+ url: https://github.com/Olegt0rr
+ - login: larsyngvelundin
+ avatarUrl: https://avatars.githubusercontent.com/u/34173819?u=74958599695bf83ac9f1addd935a51548a10c6b0&v=4
+ url: https://github.com/larsyngvelundin
+ - login: one-st-one
+ avatarUrl: https://avatars.githubusercontent.com/u/62360849?u=746dd21c34e7e06eefb11b03e8bb01aaae3c2a4f&v=4
+ url: https://github.com/one-st-one
+ - login: federicsp
+ avatarUrl: https://avatars.githubusercontent.com/u/62903636?u=05004f4a2c590f1d18c200e17978bf2e17acb632&v=4
+ url: https://github.com/federicsp
+ - login: Toothwitch
+ avatarUrl: https://avatars.githubusercontent.com/u/1710406?u=5eebb23b46cd26e48643b9e5179536cad491c17a&v=4
+ url: https://github.com/Toothwitch
+ - login: andreagrandi
+ avatarUrl: https://avatars.githubusercontent.com/u/636391?u=13d90cb8ec313593a5b71fbd4e33b78d6da736f5&v=4
+ url: https://github.com/andreagrandi
diff --git a/docs/en/data/members.yml b/docs/en/data/members.yml
index 0b9e7b94c..7ec16e917 100644
--- a/docs/en/data/members.yml
+++ b/docs/en/data/members.yml
@@ -1,19 +1,22 @@
members:
- login: tiangolo
- avatar_url: https://github.com/tiangolo.png
+ avatar_url: https://avatars.githubusercontent.com/u/1326112
url: https://github.com/tiangolo
- login: Kludex
- avatar_url: https://github.com/Kludex.png
+ avatar_url: https://avatars.githubusercontent.com/u/7353520
url: https://github.com/Kludex
- login: alejsdev
- avatar_url: https://github.com/alejsdev.png
+ avatar_url: https://avatars.githubusercontent.com/u/90076947
url: https://github.com/alejsdev
- login: svlandeg
- avatar_url: https://github.com/svlandeg.png
+ avatar_url: https://avatars.githubusercontent.com/u/8796347
url: https://github.com/svlandeg
-- login: estebanx64
- avatar_url: https://github.com/estebanx64.png
- url: https://github.com/estebanx64
+- login: YuriiMotov
+ avatar_url: https://avatars.githubusercontent.com/u/109919500
+ url: https://github.com/YuriiMotov
- login: patrick91
- avatar_url: https://github.com/patrick91.png
+ avatar_url: https://avatars.githubusercontent.com/u/667029
url: https://github.com/patrick91
+- login: luzzodev
+ avatar_url: https://avatars.githubusercontent.com/u/27291415
+ url: https://github.com/luzzodev
diff --git a/docs/en/data/people.yml b/docs/en/data/people.yml
index 02d1779e0..a94c7c63c 100644
--- a/docs/en/data/people.yml
+++ b/docs/en/data/people.yml
@@ -1,32 +1,43 @@
maintainers:
- login: tiangolo
- answers: 1885
- prs: 577
- avatarUrl: https://avatars.githubusercontent.com/u/1326112?u=740f11212a731f56798f558ceddb0bd07642afa7&v=4
+ answers: 1898
+ avatarUrl: https://avatars.githubusercontent.com/u/1326112?u=cb5d06e73a9e1998141b1641aa88e443c6717651&v=4
url: https://github.com/tiangolo
experts:
+- login: tiangolo
+ count: 1898
+ avatarUrl: https://avatars.githubusercontent.com/u/1326112?u=cb5d06e73a9e1998141b1641aa88e443c6717651&v=4
+ url: https://github.com/tiangolo
+- login: github-actions
+ count: 770
+ avatarUrl: https://avatars.githubusercontent.com/in/15368?v=4
+ url: https://github.com/apps/github-actions
- login: Kludex
- count: 608
- avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=62adc405ef418f4b6c8caa93d3eb8ab107bc4927&v=4
+ count: 655
+ avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=df8a3f06ba8f55ae1967a3e2d5ed882903a4e330&v=4
url: https://github.com/Kludex
-- login: dmontagu
- count: 241
- avatarUrl: https://avatars.githubusercontent.com/u/35119617?u=540f30c937a6450812628b9592a1dfe91bbe148e&v=4
- url: https://github.com/dmontagu
- login: jgould22
- count: 241
+ count: 263
avatarUrl: https://avatars.githubusercontent.com/u/4335847?u=ed77f67e0bb069084639b24d812dbb2a2b1dc554&v=4
url: https://github.com/jgould22
+- login: YuriiMotov
+ count: 247
+ avatarUrl: https://avatars.githubusercontent.com/u/109919500?u=e83a39697a2d33ab2ec9bfbced794ee48bc29cec&v=4
+ url: https://github.com/YuriiMotov
+- login: dmontagu
+ count: 240
+ avatarUrl: https://avatars.githubusercontent.com/u/35119617?u=540f30c937a6450812628b9592a1dfe91bbe148e&v=4
+ url: https://github.com/dmontagu
- login: Mause
- count: 220
+ count: 219
avatarUrl: https://avatars.githubusercontent.com/u/1405026?v=4
url: https://github.com/Mause
- login: ycd
count: 217
- avatarUrl: https://avatars.githubusercontent.com/u/62724709?u=29682e4b6ac7d5293742ccf818188394b9a82972&v=4
+ avatarUrl: https://avatars.githubusercontent.com/u/62724709?u=f1e7bae394a315da950912c92dc861a8eaf95d4c&v=4
url: https://github.com/ycd
- login: JarroVGIT
- count: 193
+ count: 192
avatarUrl: https://avatars.githubusercontent.com/u/13659033?u=e8bea32d07a5ef72f7dde3b2079ceb714923ca05&v=4
url: https://github.com/JarroVGIT
- login: euri10
@@ -35,40 +46,40 @@ experts:
url: https://github.com/euri10
- login: iudeen
count: 128
- avatarUrl: https://avatars.githubusercontent.com/u/10519440?u=2843b3303282bff8b212dcd4d9d6689452e4470c&v=4
+ avatarUrl: https://avatars.githubusercontent.com/u/10519440?u=f09cdd745e5bf16138f29b42732dd57c7f02bee1&v=4
url: https://github.com/iudeen
- login: phy25
count: 126
avatarUrl: https://avatars.githubusercontent.com/u/331403?v=4
url: https://github.com/phy25
-- login: YuriiMotov
- count: 104
- avatarUrl: https://avatars.githubusercontent.com/u/109919500?u=e83a39697a2d33ab2ec9bfbced794ee48bc29cec&v=4
- url: https://github.com/YuriiMotov
+- login: JavierSanchezCastro
+ count: 91
+ avatarUrl: https://avatars.githubusercontent.com/u/72013291?u=ae5679e6bd971d9d98cd5e76e8683f83642ba950&v=4
+ url: https://github.com/JavierSanchezCastro
- login: raphaelauv
count: 83
avatarUrl: https://avatars.githubusercontent.com/u/10202690?u=e6f86f5c0c3026a15d6b51792fa3e532b12f1371&v=4
url: https://github.com/raphaelauv
-- login: ArcLightSlavik
- count: 71
- avatarUrl: https://avatars.githubusercontent.com/u/31127044?u=b0f2c37142f4b762e41ad65dc49581813422bd71&v=4
- url: https://github.com/ArcLightSlavik
- login: ghandic
count: 71
avatarUrl: https://avatars.githubusercontent.com/u/23500353?u=e2e1d736f924d9be81e8bfc565b6d8836ba99773&v=4
url: https://github.com/ghandic
-- login: JavierSanchezCastro
- count: 64
- avatarUrl: https://avatars.githubusercontent.com/u/72013291?u=ae5679e6bd971d9d98cd5e76e8683f83642ba950&v=4
- url: https://github.com/JavierSanchezCastro
+- login: ArcLightSlavik
+ count: 71
+ avatarUrl: https://avatars.githubusercontent.com/u/31127044?u=b0f2c37142f4b762e41ad65dc49581813422bd71&v=4
+ url: https://github.com/ArcLightSlavik
+- login: n8sty
+ count: 67
+ avatarUrl: https://avatars.githubusercontent.com/u/2964996?v=4
+ url: https://github.com/n8sty
+- login: luzzodev
+ count: 61
+ avatarUrl: https://avatars.githubusercontent.com/u/27291415?u=5607ae1ce75c5f54f09500ca854227f7bfd2033b&v=4
+ url: https://github.com/luzzodev
- login: falkben
count: 59
avatarUrl: https://avatars.githubusercontent.com/u/653031?u=ad9838e089058c9e5a0bab94c0eec7cc181e0cd0&v=4
url: https://github.com/falkben
-- login: n8sty
- count: 56
- avatarUrl: https://avatars.githubusercontent.com/u/2964996?v=4
- url: https://github.com/n8sty
- login: acidjunk
count: 50
avatarUrl: https://avatars.githubusercontent.com/u/685002?u=b5094ab4527fc84b006c0ac9ff54367bdebb2267&v=4
@@ -81,6 +92,10 @@ experts:
count: 49
avatarUrl: https://avatars.githubusercontent.com/u/516999?u=437c0c5038558c67e887ccd863c1ba0f846c03da&v=4
url: https://github.com/sm-Fifteen
+- login: adriangb
+ count: 46
+ avatarUrl: https://avatars.githubusercontent.com/u/1755071?u=612704256e38d6ac9cbed24f10e4b6ac2da74ecb&v=4
+ url: https://github.com/adriangb
- login: insomnes
count: 45
avatarUrl: https://avatars.githubusercontent.com/u/16958893?u=f8be7088d5076d963984a21f95f44e559192d912&v=4
@@ -89,24 +104,24 @@ experts:
count: 45
avatarUrl: https://avatars.githubusercontent.com/u/27180793?u=5cf2877f50b3eb2bc55086089a78a36f07042889&v=4
url: https://github.com/Dustyposa
-- login: adriangb
- count: 45
- avatarUrl: https://avatars.githubusercontent.com/u/1755071?u=612704256e38d6ac9cbed24f10e4b6ac2da74ecb&v=4
- url: https://github.com/adriangb
-- login: frankie567
- count: 43
- avatarUrl: https://avatars.githubusercontent.com/u/1144727?u=c159fe047727aedecbbeeaa96a1b03ceb9d39add&v=4
- url: https://github.com/frankie567
- login: odiseo0
count: 43
avatarUrl: https://avatars.githubusercontent.com/u/87550035?u=241a71f6b7068738b81af3e57f45ffd723538401&v=4
url: https://github.com/odiseo0
+- login: frankie567
+ count: 43
+ avatarUrl: https://avatars.githubusercontent.com/u/1144727?u=c159fe047727aedecbbeeaa96a1b03ceb9d39add&v=4
+ url: https://github.com/frankie567
+- login: sinisaos
+ count: 41
+ avatarUrl: https://avatars.githubusercontent.com/u/30960668?v=4
+ url: https://github.com/sinisaos
- login: includeamin
count: 40
avatarUrl: https://avatars.githubusercontent.com/u/11836741?u=8bd5ef7e62fe6a82055e33c4c0e0a7879ff8cfb6&v=4
url: https://github.com/includeamin
- login: chbndrhnns
- count: 38
+ count: 37
avatarUrl: https://avatars.githubusercontent.com/u/7534547?v=4
url: https://github.com/chbndrhnns
- login: STeveShary
@@ -123,7 +138,7 @@ experts:
url: https://github.com/panla
- login: prostomarkeloff
count: 28
- avatarUrl: https://avatars.githubusercontent.com/u/28061158?u=72309cc1f2e04e40fa38b29969cb4e9d3f722e7b&v=4
+ avatarUrl: https://avatars.githubusercontent.com/u/28061158?u=6918e39a1224194ba636e897461a02a20126d7ad&v=4
url: https://github.com/prostomarkeloff
- login: hasansezertasan
count: 27
@@ -131,20 +146,24 @@ experts:
url: https://github.com/hasansezertasan
- login: dbanty
count: 26
- avatarUrl: https://avatars.githubusercontent.com/u/43723790?u=9bcce836bbce55835291c5b2ac93a4e311f4b3c3&v=4
+ avatarUrl: https://avatars.githubusercontent.com/u/43723790?u=9d726785d08e50b1e1cd96505800c8ea8405bce2&v=4
url: https://github.com/dbanty
+- login: alv2017
+ count: 25
+ avatarUrl: https://avatars.githubusercontent.com/u/31544722?v=4
+ url: https://github.com/alv2017
- login: wshayes
count: 25
avatarUrl: https://avatars.githubusercontent.com/u/365303?u=07ca03c5ee811eb0920e633cc3c3db73dbec1aa5&v=4
url: https://github.com/wshayes
-- login: acnebs
- count: 23
- avatarUrl: https://avatars.githubusercontent.com/u/9054108?v=4
- url: https://github.com/acnebs
- login: SirTelemak
count: 23
avatarUrl: https://avatars.githubusercontent.com/u/9435877?u=719327b7d2c4c62212456d771bfa7c6b8dbb9eac&v=4
url: https://github.com/SirTelemak
+- login: connebs
+ count: 22
+ avatarUrl: https://avatars.githubusercontent.com/u/9054108?u=e151d5f545a3395136d711c227c22032fda67cfa&v=4
+ url: https://github.com/connebs
- login: nymous
count: 22
avatarUrl: https://avatars.githubusercontent.com/u/4216559?u=360a36fb602cded27273cbfc0afc296eece90662&v=4
@@ -157,30 +176,38 @@ experts:
count: 21
avatarUrl: https://avatars.githubusercontent.com/u/51059348?u=5fe59a56e1f2f9ccd8005d71752a8276f133ae1a&v=4
url: https://github.com/rafsaf
+- login: ebottos94
+ count: 20
+ avatarUrl: https://avatars.githubusercontent.com/u/100039558?u=8b91053b3abe4a9209375e3651e1c1ef192d884b&v=4
+ url: https://github.com/ebottos94
- login: nsidnev
count: 20
avatarUrl: https://avatars.githubusercontent.com/u/22559461?u=a9cc3238217e21dc8796a1a500f01b722adb082c&v=4
url: https://github.com/nsidnev
-- login: ebottos94
- count: 20
- avatarUrl: https://avatars.githubusercontent.com/u/100039558?u=e2c672da5a7977fd24d87ce6ab35f8bf5b1ed9fa&v=4
- url: https://github.com/ebottos94
- login: chris-allnutt
count: 20
avatarUrl: https://avatars.githubusercontent.com/u/565544?v=4
url: https://github.com/chris-allnutt
-- login: retnikt
- count: 18
- avatarUrl: https://avatars.githubusercontent.com/u/24581770?v=4
- url: https://github.com/retnikt
+- login: estebanx64
+ count: 19
+ avatarUrl: https://avatars.githubusercontent.com/u/10840422?u=45f015f95e1c0f06df602be4ab688d4b854cc8a8&v=4
+ url: https://github.com/estebanx64
- login: zoliknemet
count: 18
avatarUrl: https://avatars.githubusercontent.com/u/22326718?u=31ba446ac290e23e56eea8e4f0c558aaf0b40779&v=4
url: https://github.com/zoliknemet
-- login: nkhitrov
+- login: sehraramiz
+ count: 18
+ avatarUrl: https://avatars.githubusercontent.com/u/14166324?u=8fac65e84dfff24245d304a5b5b09f7b5bd69dc9&v=4
+ url: https://github.com/sehraramiz
+- login: retnikt
+ count: 18
+ avatarUrl: https://avatars.githubusercontent.com/u/24581770?v=4
+ url: https://github.com/retnikt
+- login: caeser1996
count: 17
- avatarUrl: https://avatars.githubusercontent.com/u/28262306?u=66ee21316275ef356081c2efc4ed7a4572e690dc&v=4
- url: https://github.com/nkhitrov
+ avatarUrl: https://avatars.githubusercontent.com/u/16540232?u=05d2beb8e034d584d0a374b99d8826327bd7f614&v=4
+ url: https://github.com/caeser1996
- login: Hultner
count: 17
avatarUrl: https://avatars.githubusercontent.com/u/2669034?u=115e53df959309898ad8dc9443fbb35fee71df07&v=4
@@ -189,1170 +216,511 @@ experts:
count: 17
avatarUrl: https://avatars.githubusercontent.com/u/1765494?u=5b1ab7c582db4b4016fa31affe977d10af108ad4&v=4
url: https://github.com/harunyasar
-- login: caeser1996
+- login: nkhitrov
count: 17
- avatarUrl: https://avatars.githubusercontent.com/u/16540232?u=05d2beb8e034d584d0a374b99d8826327bd7f614&v=4
- url: https://github.com/caeser1996
+ avatarUrl: https://avatars.githubusercontent.com/u/28262306?u=e19427d8dc296d6950e9c424adacc92d37496fe9&v=4
+ url: https://github.com/nkhitrov
+- login: jonatasoli
+ count: 16
+ avatarUrl: https://avatars.githubusercontent.com/u/26334101?u=f601c3f111f2148bd9244c2cb3ebbd57b592e674&v=4
+ url: https://github.com/jonatasoli
- login: dstlny
count: 16
avatarUrl: https://avatars.githubusercontent.com/u/41964673?u=9f2174f9d61c15c6e3a4c9e3aeee66f711ce311f&v=4
url: https://github.com/dstlny
-last_month_experts:
-- login: YuriiMotov
- count: 29
- avatarUrl: https://avatars.githubusercontent.com/u/109919500?u=e83a39697a2d33ab2ec9bfbced794ee48bc29cec&v=4
- url: https://github.com/YuriiMotov
-- login: killjoy1221
- count: 8
- avatarUrl: https://avatars.githubusercontent.com/u/3409962?u=723662989f2027755e67d200137c13c53ae154ac&v=4
- url: https://github.com/killjoy1221
-- login: Kludex
- count: 7
- avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=62adc405ef418f4b6c8caa93d3eb8ab107bc4927&v=4
- url: https://github.com/Kludex
-- login: JavierSanchezCastro
- count: 5
- avatarUrl: https://avatars.githubusercontent.com/u/72013291?u=ae5679e6bd971d9d98cd5e76e8683f83642ba950&v=4
- url: https://github.com/JavierSanchezCastro
-- login: hasansezertasan
- count: 5
- avatarUrl: https://avatars.githubusercontent.com/u/13135006?u=99f0b0f0fc47e88e8abb337b4447357939ef93e7&v=4
- url: https://github.com/hasansezertasan
-- login: PhysicallyActive
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/160476156?u=7a8e44f4a43d3bba636f795bb7d9476c9233b4d8&v=4
- url: https://github.com/PhysicallyActive
-- login: n8sty
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/2964996?v=4
- url: https://github.com/n8sty
-- login: pedroconceicao
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/32837064?u=5a0e6559bc391442629a28b6923790b54deb4464&v=4
- url: https://github.com/pedroconceicao
-- login: PREPONDERANCE
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/112809059?u=30ab12dc9ddba2f94ab90e6ad4ad8bc5cfa7fccd&v=4
- url: https://github.com/PREPONDERANCE
-- login: aanchlia
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/2835374?u=3c3ed29aa8b09ccaf8d66def0ce82bc2f7e5aab6&v=4
- url: https://github.com/aanchlia
-- login: 0sahil
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/58521386?u=ac00b731c07c712d0baa57b8b70ac8422acf183c&v=4
- url: https://github.com/0sahil
-- login: jgould22
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/4335847?u=ed77f67e0bb069084639b24d812dbb2a2b1dc554&v=4
- url: https://github.com/jgould22
-three_months_experts:
-- login: YuriiMotov
- count: 101
- avatarUrl: https://avatars.githubusercontent.com/u/109919500?u=e83a39697a2d33ab2ec9bfbced794ee48bc29cec&v=4
- url: https://github.com/YuriiMotov
-- login: JavierSanchezCastro
- count: 20
- avatarUrl: https://avatars.githubusercontent.com/u/72013291?u=ae5679e6bd971d9d98cd5e76e8683f83642ba950&v=4
- url: https://github.com/JavierSanchezCastro
-- login: Kludex
- count: 17
- avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=62adc405ef418f4b6c8caa93d3eb8ab107bc4927&v=4
- url: https://github.com/Kludex
-- login: jgould22
- count: 14
- avatarUrl: https://avatars.githubusercontent.com/u/4335847?u=ed77f67e0bb069084639b24d812dbb2a2b1dc554&v=4
- url: https://github.com/jgould22
-- login: killjoy1221
- count: 8
- avatarUrl: https://avatars.githubusercontent.com/u/3409962?u=723662989f2027755e67d200137c13c53ae154ac&v=4
- url: https://github.com/killjoy1221
-- login: hasansezertasan
- count: 8
- avatarUrl: https://avatars.githubusercontent.com/u/13135006?u=99f0b0f0fc47e88e8abb337b4447357939ef93e7&v=4
- url: https://github.com/hasansezertasan
-- login: PhysicallyActive
- count: 6
- avatarUrl: https://avatars.githubusercontent.com/u/160476156?u=7a8e44f4a43d3bba636f795bb7d9476c9233b4d8&v=4
- url: https://github.com/PhysicallyActive
-- login: n8sty
- count: 5
- avatarUrl: https://avatars.githubusercontent.com/u/2964996?v=4
- url: https://github.com/n8sty
-- login: sehraramiz
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/14166324?v=4
- url: https://github.com/sehraramiz
-- login: acidjunk
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/685002?u=b5094ab4527fc84b006c0ac9ff54367bdebb2267&v=4
- url: https://github.com/acidjunk
-- login: estebanx64
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/10840422?u=45f015f95e1c0f06df602be4ab688d4b854cc8a8&v=4
- url: https://github.com/estebanx64
-- login: PREPONDERANCE
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/112809059?u=30ab12dc9ddba2f94ab90e6ad4ad8bc5cfa7fccd&v=4
- url: https://github.com/PREPONDERANCE
-- login: chrisK824
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/79946379?u=03d85b22d696a58a9603e55fbbbe2de6b0f4face&v=4
- url: https://github.com/chrisK824
-- login: ryanisn
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/53449841?v=4
- url: https://github.com/ryanisn
-- login: pythonweb2
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/32141163?v=4
- url: https://github.com/pythonweb2
-- login: omarcruzpantoja
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/15116058?u=4b64c643fad49225d854e1aaecd1ffc6f9071a1b&v=4
- url: https://github.com/omarcruzpantoja
-- login: mskrip
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/17459600?u=10019d5c38ae3374dd4a6743b0223e56a78d4855&v=4
- url: https://github.com/mskrip
-- login: pedroconceicao
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/32837064?u=5a0e6559bc391442629a28b6923790b54deb4464&v=4
- url: https://github.com/pedroconceicao
-- login: Jackiexiao
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/18050469?u=a2003e21a7780477ba00bf87a9abef8af58e91d1&v=4
- url: https://github.com/Jackiexiao
-- login: aanchlia
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/2835374?u=3c3ed29aa8b09ccaf8d66def0ce82bc2f7e5aab6&v=4
- url: https://github.com/aanchlia
-- login: moreno-p
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/164261630?v=4
- url: https://github.com/moreno-p
-- login: 0sahil
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/58521386?u=ac00b731c07c712d0baa57b8b70ac8422acf183c&v=4
- url: https://github.com/0sahil
-- login: patrick91
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/667029?u=e35958a75ac1f99c81b4bc99e22db8cd665ae7f0&v=4
- url: https://github.com/patrick91
-- login: pprunty
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/58374462?u=5736576e586429abc97a803b8bcd4a6d828b8a2f&v=4
- url: https://github.com/pprunty
-- login: angely-dev
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/4362224?v=4
- url: https://github.com/angely-dev
-- login: mastizada
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/1975818?u=0751a06d7271c8bf17cb73b1b845644ab4d2c6dc&v=4
- url: https://github.com/mastizada
-- login: sm-Fifteen
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/516999?u=437c0c5038558c67e887ccd863c1ba0f846c03da&v=4
- url: https://github.com/sm-Fifteen
-- login: methane
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/199592?v=4
- url: https://github.com/methane
-- login: konstantinos1981
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/39465388?v=4
- url: https://github.com/konstantinos1981
-- login: druidance
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/160344534?v=4
- url: https://github.com/druidance
-- login: fabianfalon
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/3700760?u=95f69e31280b17ac22299cdcd345323b142fe0af&v=4
- url: https://github.com/fabianfalon
-- login: VatsalJagani
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/20964366?u=43552644be05c9107c029e26d5ab3be5a1920f45&v=4
- url: https://github.com/VatsalJagani
-- login: khaledadrani
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/45245894?u=49ed5056426a149a5af29d385d8bd3847101d3a4&v=4
- url: https://github.com/khaledadrani
-- login: ThirVondukr
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/50728601?u=167c0bd655e52817082e50979a86d2f98f95b1a3&v=4
- url: https://github.com/ThirVondukr
-six_months_experts:
-- login: YuriiMotov
- count: 104
- avatarUrl: https://avatars.githubusercontent.com/u/109919500?u=e83a39697a2d33ab2ec9bfbced794ee48bc29cec&v=4
- url: https://github.com/YuriiMotov
-- login: Kludex
- count: 104
- avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=62adc405ef418f4b6c8caa93d3eb8ab107bc4927&v=4
- url: https://github.com/Kludex
-- login: JavierSanchezCastro
- count: 40
- avatarUrl: https://avatars.githubusercontent.com/u/72013291?u=ae5679e6bd971d9d98cd5e76e8683f83642ba950&v=4
- url: https://github.com/JavierSanchezCastro
-- login: jgould22
- count: 40
- avatarUrl: https://avatars.githubusercontent.com/u/4335847?u=ed77f67e0bb069084639b24d812dbb2a2b1dc554&v=4
- url: https://github.com/jgould22
-- login: hasansezertasan
- count: 21
- avatarUrl: https://avatars.githubusercontent.com/u/13135006?u=99f0b0f0fc47e88e8abb337b4447357939ef93e7&v=4
- url: https://github.com/hasansezertasan
-- login: n8sty
- count: 19
- avatarUrl: https://avatars.githubusercontent.com/u/2964996?v=4
- url: https://github.com/n8sty
-- login: killjoy1221
- count: 9
- avatarUrl: https://avatars.githubusercontent.com/u/3409962?u=723662989f2027755e67d200137c13c53ae154ac&v=4
- url: https://github.com/killjoy1221
-- login: aanchlia
- count: 8
- avatarUrl: https://avatars.githubusercontent.com/u/2835374?u=3c3ed29aa8b09ccaf8d66def0ce82bc2f7e5aab6&v=4
- url: https://github.com/aanchlia
-- login: estebanx64
- count: 7
- avatarUrl: https://avatars.githubusercontent.com/u/10840422?u=45f015f95e1c0f06df602be4ab688d4b854cc8a8&v=4
- url: https://github.com/estebanx64
-- login: PhysicallyActive
- count: 6
- avatarUrl: https://avatars.githubusercontent.com/u/160476156?u=7a8e44f4a43d3bba636f795bb7d9476c9233b4d8&v=4
- url: https://github.com/PhysicallyActive
-- login: dolfinus
- count: 6
- avatarUrl: https://avatars.githubusercontent.com/u/4661021?u=a51b39001a2e5e7529b45826980becf786de2327&v=4
- url: https://github.com/dolfinus
-- login: Ventura94
- count: 6
- avatarUrl: https://avatars.githubusercontent.com/u/43103937?u=ccb837005aaf212a449c374618c4339089e2f733&v=4
- url: https://github.com/Ventura94
-- login: sehraramiz
- count: 5
- avatarUrl: https://avatars.githubusercontent.com/u/14166324?v=4
- url: https://github.com/sehraramiz
-- login: acidjunk
- count: 5
- avatarUrl: https://avatars.githubusercontent.com/u/685002?u=b5094ab4527fc84b006c0ac9ff54367bdebb2267&v=4
- url: https://github.com/acidjunk
-- login: shashstormer
- count: 5
- avatarUrl: https://avatars.githubusercontent.com/u/90090313?v=4
- url: https://github.com/shashstormer
-- login: GodMoonGoodman
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/29688727?u=7b251da620d999644c37c1feeb292d033eed7ad6&v=4
- url: https://github.com/GodMoonGoodman
-- login: flo-at
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/564288?v=4
- url: https://github.com/flo-at
-- login: PREPONDERANCE
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/112809059?u=30ab12dc9ddba2f94ab90e6ad4ad8bc5cfa7fccd&v=4
- url: https://github.com/PREPONDERANCE
-- login: chrisK824
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/79946379?u=03d85b22d696a58a9603e55fbbbe2de6b0f4face&v=4
- url: https://github.com/chrisK824
-- login: angely-dev
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/4362224?v=4
- url: https://github.com/angely-dev
-- login: fmelihh
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/99879453?u=671117dba9022db2237e3da7a39cbc2efc838db0&v=4
- url: https://github.com/fmelihh
-- login: ryanisn
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/53449841?v=4
- url: https://github.com/ryanisn
-- login: JoshYuJump
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/5901894?u=cdbca6296ac4cdcdf6945c112a1ce8d5342839ea&v=4
- url: https://github.com/JoshYuJump
-- login: pythonweb2
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/32141163?v=4
- url: https://github.com/pythonweb2
-- login: omarcruzpantoja
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/15116058?u=4b64c643fad49225d854e1aaecd1ffc6f9071a1b&v=4
- url: https://github.com/omarcruzpantoja
-- login: bogdan-coman-uv
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/92912507?v=4
- url: https://github.com/bogdan-coman-uv
-- login: ahmedabdou14
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/104530599?u=05365b155a1ff911532e8be316acfad2e0736f98&v=4
- url: https://github.com/ahmedabdou14
-- login: mskrip
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/17459600?u=10019d5c38ae3374dd4a6743b0223e56a78d4855&v=4
- url: https://github.com/mskrip
-- login: leonidktoto
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/159561986?v=4
- url: https://github.com/leonidktoto
-- login: pedroconceicao
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/32837064?u=5a0e6559bc391442629a28b6923790b54deb4464&v=4
- url: https://github.com/pedroconceicao
-- login: hwong557
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/460259?u=7d2f1b33ea5bda4d8e177ab3cb924a673d53087e&v=4
- url: https://github.com/hwong557
-- login: Jackiexiao
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/18050469?u=a2003e21a7780477ba00bf87a9abef8af58e91d1&v=4
- url: https://github.com/Jackiexiao
-- login: admo1
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/14835916?v=4
- url: https://github.com/admo1
-- login: binbjz
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/8213913?u=22b68b7a0d5bf5e09c02084c0f5f53d7503114cd&v=4
- url: https://github.com/binbjz
-- login: nameer
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/3931725?u=6199fb065df098fc13ac0a5e649f89672b586732&v=4
- url: https://github.com/nameer
-- login: moreno-p
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/164261630?v=4
- url: https://github.com/moreno-p
-- login: 0sahil
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/58521386?u=ac00b731c07c712d0baa57b8b70ac8422acf183c&v=4
- url: https://github.com/0sahil
-- login: nymous
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/4216559?u=360a36fb602cded27273cbfc0afc296eece90662&v=4
- url: https://github.com/nymous
-- login: patrick91
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/667029?u=e35958a75ac1f99c81b4bc99e22db8cd665ae7f0&v=4
- url: https://github.com/patrick91
-- login: pprunty
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/58374462?u=5736576e586429abc97a803b8bcd4a6d828b8a2f&v=4
- url: https://github.com/pprunty
-- login: JonnyBootsNpants
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/155071540?u=2d3a72b74a2c4c8eaacdb625c7ac850369579352&v=4
- url: https://github.com/JonnyBootsNpants
-- login: richin13
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/8370058?u=8e37a4cdbc78983a5f4b4847f6d1879fb39c851c&v=4
- url: https://github.com/richin13
-- login: mastizada
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/1975818?u=0751a06d7271c8bf17cb73b1b845644ab4d2c6dc&v=4
- url: https://github.com/mastizada
-- login: sm-Fifteen
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/516999?u=437c0c5038558c67e887ccd863c1ba0f846c03da&v=4
- url: https://github.com/sm-Fifteen
-- login: amacfie
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/889657?u=d70187989940b085bcbfa3bedad8dbc5f3ab1fe7&v=4
- url: https://github.com/amacfie
-- login: garg10may
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/8787120?u=7028d2b3a2a26534c1806eb76c7425a3fac9732f&v=4
- url: https://github.com/garg10may
-- login: methane
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/199592?v=4
- url: https://github.com/methane
-- login: konstantinos1981
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/39465388?v=4
- url: https://github.com/konstantinos1981
-- login: druidance
- count: 2
- avatarUrl: https://avatars.githubusercontent.com/u/160344534?v=4
- url: https://github.com/druidance
-one_year_experts:
-- login: Kludex
- count: 207
- avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=62adc405ef418f4b6c8caa93d3eb8ab107bc4927&v=4
- url: https://github.com/Kludex
-- login: jgould22
- count: 118
- avatarUrl: https://avatars.githubusercontent.com/u/4335847?u=ed77f67e0bb069084639b24d812dbb2a2b1dc554&v=4
- url: https://github.com/jgould22
-- login: YuriiMotov
- count: 104
- avatarUrl: https://avatars.githubusercontent.com/u/109919500?u=e83a39697a2d33ab2ec9bfbced794ee48bc29cec&v=4
- url: https://github.com/YuriiMotov
-- login: JavierSanchezCastro
- count: 59
- avatarUrl: https://avatars.githubusercontent.com/u/72013291?u=ae5679e6bd971d9d98cd5e76e8683f83642ba950&v=4
- url: https://github.com/JavierSanchezCastro
-- login: n8sty
- count: 40
- avatarUrl: https://avatars.githubusercontent.com/u/2964996?v=4
- url: https://github.com/n8sty
-- login: hasansezertasan
- count: 27
- avatarUrl: https://avatars.githubusercontent.com/u/13135006?u=99f0b0f0fc47e88e8abb337b4447357939ef93e7&v=4
- url: https://github.com/hasansezertasan
-- login: chrisK824
- count: 16
- avatarUrl: https://avatars.githubusercontent.com/u/79946379?u=03d85b22d696a58a9603e55fbbbe2de6b0f4face&v=4
- url: https://github.com/chrisK824
-- login: ahmedabdou14
- count: 13
- avatarUrl: https://avatars.githubusercontent.com/u/104530599?u=05365b155a1ff911532e8be316acfad2e0736f98&v=4
- url: https://github.com/ahmedabdou14
-- login: arjwilliams
- count: 12
- avatarUrl: https://avatars.githubusercontent.com/u/22227620?v=4
- url: https://github.com/arjwilliams
-- login: killjoy1221
- count: 10
- avatarUrl: https://avatars.githubusercontent.com/u/3409962?u=723662989f2027755e67d200137c13c53ae154ac&v=4
- url: https://github.com/killjoy1221
-- login: WilliamStam
- count: 10
- avatarUrl: https://avatars.githubusercontent.com/u/182800?v=4
- url: https://github.com/WilliamStam
-- login: iudeen
- count: 10
- avatarUrl: https://avatars.githubusercontent.com/u/10519440?u=2843b3303282bff8b212dcd4d9d6689452e4470c&v=4
- url: https://github.com/iudeen
-- login: nymous
- count: 9
- avatarUrl: https://avatars.githubusercontent.com/u/4216559?u=360a36fb602cded27273cbfc0afc296eece90662&v=4
- url: https://github.com/nymous
-- login: aanchlia
- count: 8
- avatarUrl: https://avatars.githubusercontent.com/u/2835374?u=3c3ed29aa8b09ccaf8d66def0ce82bc2f7e5aab6&v=4
- url: https://github.com/aanchlia
-- login: estebanx64
- count: 7
- avatarUrl: https://avatars.githubusercontent.com/u/10840422?u=45f015f95e1c0f06df602be4ab688d4b854cc8a8&v=4
- url: https://github.com/estebanx64
-- login: pythonweb2
- count: 7
- avatarUrl: https://avatars.githubusercontent.com/u/32141163?v=4
- url: https://github.com/pythonweb2
-- login: romabozhanovgithub
- count: 6
- avatarUrl: https://avatars.githubusercontent.com/u/67696229?u=e4b921eef096415300425aca249348f8abb78ad7&v=4
- url: https://github.com/romabozhanovgithub
-- login: PhysicallyActive
- count: 6
- avatarUrl: https://avatars.githubusercontent.com/u/160476156?u=7a8e44f4a43d3bba636f795bb7d9476c9233b4d8&v=4
- url: https://github.com/PhysicallyActive
-- login: mikeedjones
- count: 6
- avatarUrl: https://avatars.githubusercontent.com/u/4087139?u=cc4a242896ac2fcf88a53acfaf190d0fe0a1f0c9&v=4
- url: https://github.com/mikeedjones
-- login: dolfinus
- count: 6
- avatarUrl: https://avatars.githubusercontent.com/u/4661021?u=a51b39001a2e5e7529b45826980becf786de2327&v=4
- url: https://github.com/dolfinus
-- login: ebottos94
- count: 6
- avatarUrl: https://avatars.githubusercontent.com/u/100039558?u=e2c672da5a7977fd24d87ce6ab35f8bf5b1ed9fa&v=4
- url: https://github.com/ebottos94
-- login: Ventura94
- count: 6
- avatarUrl: https://avatars.githubusercontent.com/u/43103937?u=ccb837005aaf212a449c374618c4339089e2f733&v=4
- url: https://github.com/Ventura94
-- login: White-Mask
- count: 6
- avatarUrl: https://avatars.githubusercontent.com/u/31826970?u=8625355dc25ddf9c85a8b2b0b9932826c4c8f44c&v=4
- url: https://github.com/White-Mask
-- login: sehraramiz
- count: 5
- avatarUrl: https://avatars.githubusercontent.com/u/14166324?v=4
- url: https://github.com/sehraramiz
-- login: acidjunk
- count: 5
- avatarUrl: https://avatars.githubusercontent.com/u/685002?u=b5094ab4527fc84b006c0ac9ff54367bdebb2267&v=4
- url: https://github.com/acidjunk
-- login: JoshYuJump
- count: 5
- avatarUrl: https://avatars.githubusercontent.com/u/5901894?u=cdbca6296ac4cdcdf6945c112a1ce8d5342839ea&v=4
- url: https://github.com/JoshYuJump
-- login: alex-pobeditel-2004
- count: 5
- avatarUrl: https://avatars.githubusercontent.com/u/14791483?v=4
- url: https://github.com/alex-pobeditel-2004
-- login: shashstormer
- count: 5
- avatarUrl: https://avatars.githubusercontent.com/u/90090313?v=4
- url: https://github.com/shashstormer
-- login: wu-clan
- count: 5
- avatarUrl: https://avatars.githubusercontent.com/u/52145145?u=f8c9e5c8c259d248e1683fedf5027b4ee08a0967&v=4
- url: https://github.com/wu-clan
- login: abhint
- count: 5
+ count: 15
avatarUrl: https://avatars.githubusercontent.com/u/25699289?u=b5d219277b4d001ac26fb8be357fddd88c29d51b&v=4
url: https://github.com/abhint
-- login: anthonycepeda
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/72019805?u=60bdf46240cff8fca482ff0fc07d963fd5e1a27c&v=4
- url: https://github.com/anthonycepeda
-- login: GodMoonGoodman
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/29688727?u=7b251da620d999644c37c1feeb292d033eed7ad6&v=4
- url: https://github.com/GodMoonGoodman
-- login: flo-at
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/564288?v=4
- url: https://github.com/flo-at
-- login: yinziyan1206
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/37829370?u=da44ca53aefd5c23f346fab8e9fd2e108294c179&v=4
- url: https://github.com/yinziyan1206
-- login: amacfie
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/889657?u=d70187989940b085bcbfa3bedad8dbc5f3ab1fe7&v=4
- url: https://github.com/amacfie
-- login: commonism
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/164513?v=4
- url: https://github.com/commonism
-- login: dmontagu
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/35119617?u=540f30c937a6450812628b9592a1dfe91bbe148e&v=4
- url: https://github.com/dmontagu
-- login: sanzoghenzo
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/977953?v=4
- url: https://github.com/sanzoghenzo
-- login: lucasgadams
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/36425095?v=4
- url: https://github.com/lucasgadams
-- login: NeilBotelho
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/39030675?u=16fea2ff90a5c67b974744528a38832a6d1bb4f7&v=4
- url: https://github.com/NeilBotelho
-- login: hhartzer
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/100533792?v=4
- url: https://github.com/hhartzer
-- login: binbjz
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/8213913?u=22b68b7a0d5bf5e09c02084c0f5f53d7503114cd&v=4
- url: https://github.com/binbjz
-- login: PREPONDERANCE
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/112809059?u=30ab12dc9ddba2f94ab90e6ad4ad8bc5cfa7fccd&v=4
- url: https://github.com/PREPONDERANCE
-- login: nameer
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/3931725?u=6199fb065df098fc13ac0a5e649f89672b586732&v=4
- url: https://github.com/nameer
-- login: angely-dev
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/4362224?v=4
- url: https://github.com/angely-dev
-- login: fmelihh
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/99879453?u=671117dba9022db2237e3da7a39cbc2efc838db0&v=4
- url: https://github.com/fmelihh
-- login: ryanisn
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/53449841?v=4
- url: https://github.com/ryanisn
-- login: theobouwman
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/16098190?u=dc70db88a7a99b764c9a89a6e471e0b7ca478a35&v=4
- url: https://github.com/theobouwman
-- login: methane
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/199592?v=4
- url: https://github.com/methane
-top_contributors:
-- login: nilslindemann
- count: 130
- avatarUrl: https://avatars.githubusercontent.com/u/6892179?u=1dca6a22195d6cd1ab20737c0e19a4c55d639472&v=4
- url: https://github.com/nilslindemann
-- login: jaystone776
- count: 49
- avatarUrl: https://avatars.githubusercontent.com/u/11191137?u=299205a95e9b6817a43144a48b643346a5aac5cc&v=4
- url: https://github.com/jaystone776
-- login: waynerv
- count: 25
- avatarUrl: https://avatars.githubusercontent.com/u/39515546?u=ec35139777597cdbbbddda29bf8b9d4396b429a9&v=4
- url: https://github.com/waynerv
-- login: tokusumi
- count: 24
- avatarUrl: https://avatars.githubusercontent.com/u/41147016?u=55010621aece725aa702270b54fed829b6a1fe60&v=4
- url: https://github.com/tokusumi
-- login: SwftAlpc
- count: 23
- avatarUrl: https://avatars.githubusercontent.com/u/52768429?u=6a3aa15277406520ad37f6236e89466ed44bc5b8&v=4
- url: https://github.com/SwftAlpc
-- login: Kludex
- count: 22
- avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=62adc405ef418f4b6c8caa93d3eb8ab107bc4927&v=4
- url: https://github.com/Kludex
-- login: hasansezertasan
- count: 22
- avatarUrl: https://avatars.githubusercontent.com/u/13135006?u=99f0b0f0fc47e88e8abb337b4447357939ef93e7&v=4
- url: https://github.com/hasansezertasan
-- login: dmontagu
- count: 17
- avatarUrl: https://avatars.githubusercontent.com/u/35119617?u=540f30c937a6450812628b9592a1dfe91bbe148e&v=4
- url: https://github.com/dmontagu
-- login: Xewus
- count: 14
- avatarUrl: https://avatars.githubusercontent.com/u/85196001?u=f8e2dc7e5104f109cef944af79050ea8d1b8f914&v=4
- url: https://github.com/Xewus
-- login: euri10
- count: 13
- avatarUrl: https://avatars.githubusercontent.com/u/1104190?u=321a2e953e6645a7d09b732786c7a8061e0f8a8b&v=4
- url: https://github.com/euri10
-- login: mariacamilagl
- count: 12
- avatarUrl: https://avatars.githubusercontent.com/u/11489395?u=4adb6986bf3debfc2b8216ae701f2bd47d73da7d&v=4
- url: https://github.com/mariacamilagl
-- login: AlertRED
- count: 12
- avatarUrl: https://avatars.githubusercontent.com/u/15695000?u=f5a4944c6df443030409c88da7d7fa0b7ead985c&v=4
- url: https://github.com/AlertRED
-- login: Smlep
- count: 11
- avatarUrl: https://avatars.githubusercontent.com/u/16785985?v=4
- url: https://github.com/Smlep
-- login: alejsdev
- count: 11
- avatarUrl: https://avatars.githubusercontent.com/u/90076947?u=9ca449ad5161af12766ddd1a22988e9b14315f5c&v=4
- url: https://github.com/alejsdev
-- login: hard-coders
- count: 10
- avatarUrl: https://avatars.githubusercontent.com/u/9651103?u=95db33927bbff1ed1c07efddeb97ac2ff33068ed&v=4
- url: https://github.com/hard-coders
-- login: KaniKim
- count: 10
- avatarUrl: https://avatars.githubusercontent.com/u/19832624?u=40f8f7f3f36d5f2365ba2ad0b40693e60958ce70&v=4
- url: https://github.com/KaniKim
-- login: xzmeng
- count: 9
- avatarUrl: https://avatars.githubusercontent.com/u/40202897?v=4
- url: https://github.com/xzmeng
-- login: Serrones
- count: 8
- avatarUrl: https://avatars.githubusercontent.com/u/22691749?u=4795b880e13ca33a73e52fc0ef7dc9c60c8fce47&v=4
- url: https://github.com/Serrones
-- login: rjNemo
- count: 8
- avatarUrl: https://avatars.githubusercontent.com/u/56785022?u=d5c3a02567c8649e146fcfc51b6060ccaf8adef8&v=4
- url: https://github.com/rjNemo
-- login: pablocm83
- count: 8
- avatarUrl: https://avatars.githubusercontent.com/u/28315068?u=3310fbb05bb8bfc50d2c48b6cb64ac9ee4a14549&v=4
- url: https://github.com/pablocm83
-- login: RunningIkkyu
- count: 7
- avatarUrl: https://avatars.githubusercontent.com/u/31848542?u=494ecc298e3f26197495bb357ad0f57cfd5f7a32&v=4
- url: https://github.com/RunningIkkyu
-- login: Alexandrhub
- count: 7
- avatarUrl: https://avatars.githubusercontent.com/u/119126536?u=9fc0d48f3307817bafecc5861eb2168401a6cb04&v=4
- url: https://github.com/Alexandrhub
-- login: NinaHwang
- count: 6
- avatarUrl: https://avatars.githubusercontent.com/u/79563565?u=eee6bfe9224c71193025ab7477f4f96ceaa05c62&v=4
- url: https://github.com/NinaHwang
-- login: batlopes
- count: 6
- avatarUrl: https://avatars.githubusercontent.com/u/33462923?u=0fb3d7acb316764616f11e4947faf080e49ad8d9&v=4
- url: https://github.com/batlopes
-- login: wshayes
- count: 5
- avatarUrl: https://avatars.githubusercontent.com/u/365303?u=07ca03c5ee811eb0920e633cc3c3db73dbec1aa5&v=4
- url: https://github.com/wshayes
-- login: samuelcolvin
- count: 5
- avatarUrl: https://avatars.githubusercontent.com/u/4039449?u=42eb3b833047c8c4b4f647a031eaef148c16d93f&v=4
- url: https://github.com/samuelcolvin
-- login: Attsun1031
- count: 5
- avatarUrl: https://avatars.githubusercontent.com/u/1175560?v=4
- url: https://github.com/Attsun1031
-- login: ComicShrimp
- count: 5
- avatarUrl: https://avatars.githubusercontent.com/u/43503750?u=d2fbf412e7730183ce91686ca48d4147e1b7dc74&v=4
- url: https://github.com/ComicShrimp
-- login: rostik1410
- count: 5
- avatarUrl: https://avatars.githubusercontent.com/u/11443899?u=e26a635c2ba220467b308a326a579b8ccf4a8701&v=4
- url: https://github.com/rostik1410
-- login: tamtam-fitness
- count: 5
- avatarUrl: https://avatars.githubusercontent.com/u/62091034?u=8da19a6bd3d02f5d6ba30c7247d5b46c98dd1403&v=4
- url: https://github.com/tamtam-fitness
-- login: jekirl
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/2546697?u=a027452387d85bd4a14834e19d716c99255fb3b7&v=4
- url: https://github.com/jekirl
-- login: jfunez
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/805749?v=4
- url: https://github.com/jfunez
-- login: ycd
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/62724709?u=29682e4b6ac7d5293742ccf818188394b9a82972&v=4
- url: https://github.com/ycd
-- login: komtaki
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/39375566?u=260ad6b1a4b34c07dbfa728da5e586f16f6d1824&v=4
- url: https://github.com/komtaki
-- login: hitrust
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/3360631?u=5fa1f475ad784d64eb9666bdd43cc4d285dcc773&v=4
- url: https://github.com/hitrust
-- login: JulianMaurin
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/63545168?u=b7d15ac865268cbefc2d739e2f23d9aeeac1a622&v=4
- url: https://github.com/JulianMaurin
-- login: lsglucas
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/61513630?u=320e43fe4dc7bc6efc64e9b8f325f8075634fd20&v=4
- url: https://github.com/lsglucas
-- login: BilalAlpaslan
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/47563997?u=63ed66e304fe8d765762c70587d61d9196e5c82d&v=4
- url: https://github.com/BilalAlpaslan
-- login: adriangb
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/1755071?u=612704256e38d6ac9cbed24f10e4b6ac2da74ecb&v=4
- url: https://github.com/adriangb
-- login: iudeen
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/10519440?u=2843b3303282bff8b212dcd4d9d6689452e4470c&v=4
- url: https://github.com/iudeen
-- login: axel584
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/1334088?u=9667041f5b15dc002b6f9665fda8c0412933ac04&v=4
- url: https://github.com/axel584
-- login: ivan-abc
- count: 4
- avatarUrl: https://avatars.githubusercontent.com/u/36765187?u=c6e0ba571c1ccb6db9d94e62e4b8b5eda811a870&v=4
- url: https://github.com/ivan-abc
-- login: divums
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/1397556?v=4
- url: https://github.com/divums
-- login: prostomarkeloff
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/28061158?u=72309cc1f2e04e40fa38b29969cb4e9d3f722e7b&v=4
- url: https://github.com/prostomarkeloff
-- login: nsidnev
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/22559461?u=a9cc3238217e21dc8796a1a500f01b722adb082c&v=4
- url: https://github.com/nsidnev
-- login: pawamoy
- count: 3
- avatarUrl: https://avatars.githubusercontent.com/u/3999221?u=b030e4c89df2f3a36bc4710b925bdeb6745c9856&v=4
- url: https://github.com/pawamoy
-top_reviewers:
-- login: Kludex
- count: 158
- avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=62adc405ef418f4b6c8caa93d3eb8ab107bc4927&v=4
- url: https://github.com/Kludex
-- login: BilalAlpaslan
- count: 86
- avatarUrl: https://avatars.githubusercontent.com/u/47563997?u=63ed66e304fe8d765762c70587d61d9196e5c82d&v=4
- url: https://github.com/BilalAlpaslan
-- login: yezz123
- count: 85
- avatarUrl: https://avatars.githubusercontent.com/u/52716203?u=d7062cbc6eb7671d5dc9cc0e32a24ae335e0f225&v=4
- url: https://github.com/yezz123
-- login: iudeen
- count: 55
- avatarUrl: https://avatars.githubusercontent.com/u/10519440?u=2843b3303282bff8b212dcd4d9d6689452e4470c&v=4
- url: https://github.com/iudeen
-- login: tokusumi
- count: 51
- avatarUrl: https://avatars.githubusercontent.com/u/41147016?u=55010621aece725aa702270b54fed829b6a1fe60&v=4
- url: https://github.com/tokusumi
-- login: Xewus
- count: 50
- avatarUrl: https://avatars.githubusercontent.com/u/85196001?u=f8e2dc7e5104f109cef944af79050ea8d1b8f914&v=4
- url: https://github.com/Xewus
-- login: hasansezertasan
- count: 50
- avatarUrl: https://avatars.githubusercontent.com/u/13135006?u=99f0b0f0fc47e88e8abb337b4447357939ef93e7&v=4
- url: https://github.com/hasansezertasan
-- login: waynerv
- count: 47
- avatarUrl: https://avatars.githubusercontent.com/u/39515546?u=ec35139777597cdbbbddda29bf8b9d4396b429a9&v=4
- url: https://github.com/waynerv
-- login: Laineyzhang55
- count: 47
- avatarUrl: https://avatars.githubusercontent.com/u/59285379?v=4
- url: https://github.com/Laineyzhang55
-- login: ycd
- count: 45
- avatarUrl: https://avatars.githubusercontent.com/u/62724709?u=29682e4b6ac7d5293742ccf818188394b9a82972&v=4
- url: https://github.com/ycd
-- login: cikay
- count: 41
- avatarUrl: https://avatars.githubusercontent.com/u/24587499?u=e772190a051ab0eaa9c8542fcff1892471638f2b&v=4
- url: https://github.com/cikay
-- login: alejsdev
- count: 38
- avatarUrl: https://avatars.githubusercontent.com/u/90076947?u=9ca449ad5161af12766ddd1a22988e9b14315f5c&v=4
- url: https://github.com/alejsdev
-- login: JarroVGIT
- count: 34
- avatarUrl: https://avatars.githubusercontent.com/u/13659033?u=e8bea32d07a5ef72f7dde3b2079ceb714923ca05&v=4
- url: https://github.com/JarroVGIT
-- login: AdrianDeAnda
- count: 33
- avatarUrl: https://avatars.githubusercontent.com/u/1024932?u=b2ea249c6b41ddf98679c8d110d0f67d4a3ebf93&v=4
- url: https://github.com/AdrianDeAnda
-- login: ArcLightSlavik
- count: 31
- avatarUrl: https://avatars.githubusercontent.com/u/31127044?u=b0f2c37142f4b762e41ad65dc49581813422bd71&v=4
- url: https://github.com/ArcLightSlavik
-- login: cassiobotaro
- count: 28
- avatarUrl: https://avatars.githubusercontent.com/u/3127847?u=a08022b191ddbd0a6159b2981d9d878b6d5bb71f&v=4
- url: https://github.com/cassiobotaro
-- login: lsglucas
- count: 27
- avatarUrl: https://avatars.githubusercontent.com/u/61513630?u=320e43fe4dc7bc6efc64e9b8f325f8075634fd20&v=4
- url: https://github.com/lsglucas
-- login: komtaki
- count: 27
- avatarUrl: https://avatars.githubusercontent.com/u/39375566?u=260ad6b1a4b34c07dbfa728da5e586f16f6d1824&v=4
- url: https://github.com/komtaki
+- login: ceb10n
+ count: 15
+ avatarUrl: https://avatars.githubusercontent.com/u/235213?u=edcce471814a1eba9f0cdaa4cd0de18921a940a6&v=4
+ url: https://github.com/ceb10n
+- login: jorgerpo
+ count: 15
+ avatarUrl: https://avatars.githubusercontent.com/u/12537771?u=7444d20019198e34911082780cc7ad73f2b97cb3&v=4
+ url: https://github.com/jorgerpo
+- login: simondale00
+ count: 15
+ avatarUrl: https://avatars.githubusercontent.com/u/33907262?u=2721fb37014d50daf473267c808aa678ecaefe09&v=4
+ url: https://github.com/simondale00
+last_month_experts:
- login: YuriiMotov
- count: 25
+ count: 9
avatarUrl: https://avatars.githubusercontent.com/u/109919500?u=e83a39697a2d33ab2ec9bfbced794ee48bc29cec&v=4
url: https://github.com/YuriiMotov
-- login: Ryandaydev
+- login: luzzodev
+ count: 8
+ avatarUrl: https://avatars.githubusercontent.com/u/27291415?u=5607ae1ce75c5f54f09500ca854227f7bfd2033b&v=4
+ url: https://github.com/luzzodev
+- login: alv2017
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/31544722?v=4
+ url: https://github.com/alv2017
+- login: sachinh35
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/21972708?u=8560b97b8b41e175f476270b56de8a493b84f302&v=4
+ url: https://github.com/sachinh35
+- login: KianAnbarestani
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/145364424?u=dcc3d8fb4ca07d36fb52a17f38b6650565de40be&v=4
+ url: https://github.com/KianAnbarestani
+- login: tiangolo
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/1326112?u=cb5d06e73a9e1998141b1641aa88e443c6717651&v=4
+ url: https://github.com/tiangolo
+three_months_experts:
+- login: luzzodev
count: 25
- avatarUrl: https://avatars.githubusercontent.com/u/4292423?u=48f68868db8886fce31a1d802c1003914c6cd7c6&v=4
- url: https://github.com/Ryandaydev
-- login: LorhanSohaky
+ avatarUrl: https://avatars.githubusercontent.com/u/27291415?u=5607ae1ce75c5f54f09500ca854227f7bfd2033b&v=4
+ url: https://github.com/luzzodev
+- login: YuriiMotov
count: 24
- avatarUrl: https://avatars.githubusercontent.com/u/16273730?u=095b66f243a2cd6a0aadba9a095009f8aaf18393&v=4
- url: https://github.com/LorhanSohaky
-- login: dmontagu
- count: 23
- avatarUrl: https://avatars.githubusercontent.com/u/35119617?u=540f30c937a6450812628b9592a1dfe91bbe148e&v=4
- url: https://github.com/dmontagu
-- login: nilslindemann
- count: 23
- avatarUrl: https://avatars.githubusercontent.com/u/6892179?u=1dca6a22195d6cd1ab20737c0e19a4c55d639472&v=4
- url: https://github.com/nilslindemann
-- login: hard-coders
- count: 23
- avatarUrl: https://avatars.githubusercontent.com/u/9651103?u=95db33927bbff1ed1c07efddeb97ac2ff33068ed&v=4
- url: https://github.com/hard-coders
-- login: rjNemo
- count: 21
- avatarUrl: https://avatars.githubusercontent.com/u/56785022?u=d5c3a02567c8649e146fcfc51b6060ccaf8adef8&v=4
- url: https://github.com/rjNemo
-- login: odiseo0
- count: 20
- avatarUrl: https://avatars.githubusercontent.com/u/87550035?u=241a71f6b7068738b81af3e57f45ffd723538401&v=4
- url: https://github.com/odiseo0
-- login: 0417taehyun
- count: 19
- avatarUrl: https://avatars.githubusercontent.com/u/63915557?u=47debaa860fd52c9b98c97ef357ddcec3b3fb399&v=4
- url: https://github.com/0417taehyun
+ avatarUrl: https://avatars.githubusercontent.com/u/109919500?u=e83a39697a2d33ab2ec9bfbced794ee48bc29cec&v=4
+ url: https://github.com/YuriiMotov
+- login: alv2017
+ count: 22
+ avatarUrl: https://avatars.githubusercontent.com/u/31544722?v=4
+ url: https://github.com/alv2017
+- login: jgould22
+ count: 13
+ avatarUrl: https://avatars.githubusercontent.com/u/4335847?u=ed77f67e0bb069084639b24d812dbb2a2b1dc554&v=4
+ url: https://github.com/jgould22
+- login: Kludex
+ count: 10
+ avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=df8a3f06ba8f55ae1967a3e2d5ed882903a4e330&v=4
+ url: https://github.com/Kludex
+- login: yauhen-sobaleu
+ count: 9
+ avatarUrl: https://avatars.githubusercontent.com/u/51629535?u=fc1817060daf2df438bfca86c44f33da5cd667db&v=4
+ url: https://github.com/yauhen-sobaleu
- login: JavierSanchezCastro
- count: 19
+ count: 7
avatarUrl: https://avatars.githubusercontent.com/u/72013291?u=ae5679e6bd971d9d98cd5e76e8683f83642ba950&v=4
url: https://github.com/JavierSanchezCastro
-- login: Smlep
+- login: tiangolo
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/1326112?u=cb5d06e73a9e1998141b1641aa88e443c6717651&v=4
+ url: https://github.com/tiangolo
+- login: sachinh35
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/21972708?u=8560b97b8b41e175f476270b56de8a493b84f302&v=4
+ url: https://github.com/sachinh35
+- login: SobikXexe
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/87701130?v=4
+ url: https://github.com/SobikXexe
+- login: KianAnbarestani
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/145364424?u=dcc3d8fb4ca07d36fb52a17f38b6650565de40be&v=4
+ url: https://github.com/KianAnbarestani
+- login: sinisaos
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/30960668?v=4
+ url: https://github.com/sinisaos
+- login: Ale-Cas
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/64859146?u=d52a6ecf8d83d2927e2ae270bdfcc83495dba8c9&v=4
+ url: https://github.com/Ale-Cas
+- login: adsouza
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/275832?v=4
+ url: https://github.com/adsouza
+- login: marsboy02
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/86903678?u=fa4a6b91eea3a11ae93c162616ca5edf51c68572&v=4
+ url: https://github.com/marsboy02
+- login: EverStarck
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/51029456?u=343409b7cb6b3ea6a59359f4e8370d9c3f140ecd&v=4
+ url: https://github.com/EverStarck
+- login: vtgn
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/112889052?v=4
+ url: https://github.com/vtgn
+six_months_experts:
+- login: luzzodev
+ count: 57
+ avatarUrl: https://avatars.githubusercontent.com/u/27291415?u=5607ae1ce75c5f54f09500ca854227f7bfd2033b&v=4
+ url: https://github.com/luzzodev
+- login: YuriiMotov
+ count: 56
+ avatarUrl: https://avatars.githubusercontent.com/u/109919500?u=e83a39697a2d33ab2ec9bfbced794ee48bc29cec&v=4
+ url: https://github.com/YuriiMotov
+- login: Kludex
+ count: 34
+ avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=df8a3f06ba8f55ae1967a3e2d5ed882903a4e330&v=4
+ url: https://github.com/Kludex
+- login: alv2017
+ count: 25
+ avatarUrl: https://avatars.githubusercontent.com/u/31544722?v=4
+ url: https://github.com/alv2017
+- login: jgould22
count: 17
- avatarUrl: https://avatars.githubusercontent.com/u/16785985?v=4
- url: https://github.com/Smlep
-- login: zy7y
- count: 17
- avatarUrl: https://avatars.githubusercontent.com/u/67154681?u=5d634834cc514028ea3f9115f7030b99a1f4d5a4&v=4
- url: https://github.com/zy7y
-- login: junah201
- count: 17
- avatarUrl: https://avatars.githubusercontent.com/u/75025529?u=2451c256e888fa2a06bcfc0646d09b87ddb6a945&v=4
- url: https://github.com/junah201
-- login: peidrao
- count: 17
- avatarUrl: https://avatars.githubusercontent.com/u/32584628?u=a66902b40c13647d0ed0e573d598128240a4dd04&v=4
- url: https://github.com/peidrao
-- login: yanever
- count: 16
- avatarUrl: https://avatars.githubusercontent.com/u/21978760?v=4
- url: https://github.com/yanever
-- login: SwftAlpc
- count: 16
- avatarUrl: https://avatars.githubusercontent.com/u/52768429?u=6a3aa15277406520ad37f6236e89466ed44bc5b8&v=4
- url: https://github.com/SwftAlpc
-- login: axel584
- count: 16
- avatarUrl: https://avatars.githubusercontent.com/u/1334088?u=9667041f5b15dc002b6f9665fda8c0412933ac04&v=4
- url: https://github.com/axel584
-- login: codespearhead
- count: 16
- avatarUrl: https://avatars.githubusercontent.com/u/72931357?u=0fce6b82219b604d58adb614a761556425579cb5&v=4
- url: https://github.com/codespearhead
-- login: Alexandrhub
- count: 16
- avatarUrl: https://avatars.githubusercontent.com/u/119126536?u=9fc0d48f3307817bafecc5861eb2168401a6cb04&v=4
- url: https://github.com/Alexandrhub
-- login: DevDae
- count: 16
- avatarUrl: https://avatars.githubusercontent.com/u/87962045?u=08e10fa516e844934f4b3fc7c38b33c61697e4a1&v=4
- url: https://github.com/DevDae
-- login: Aruelius
- count: 16
- avatarUrl: https://avatars.githubusercontent.com/u/25380989?u=574f8cfcda3ea77a3f81884f6b26a97068e36a9d&v=4
- url: https://github.com/Aruelius
-- login: OzgunCaglarArslan
- count: 16
- avatarUrl: https://avatars.githubusercontent.com/u/86166426?v=4
- url: https://github.com/OzgunCaglarArslan
-- login: pedabraham
- count: 15
- avatarUrl: https://avatars.githubusercontent.com/u/16860088?u=abf922a7b920bf8fdb7867d8b43e091f1e796178&v=4
- url: https://github.com/pedabraham
-- login: delhi09
- count: 15
- avatarUrl: https://avatars.githubusercontent.com/u/63476957?u=6c86e59b48e0394d4db230f37fc9ad4d7e2c27c7&v=4
- url: https://github.com/delhi09
-- login: wdh99
- count: 14
- avatarUrl: https://avatars.githubusercontent.com/u/108172295?u=8a8fb95d5afe3e0fa33257b2aecae88d436249eb&v=4
- url: https://github.com/wdh99
-- login: sh0nk
- count: 13
- avatarUrl: https://avatars.githubusercontent.com/u/6478810?u=af15d724875cec682ed8088a86d36b2798f981c0&v=4
- url: https://github.com/sh0nk
-- login: r0b2g1t
- count: 13
- avatarUrl: https://avatars.githubusercontent.com/u/5357541?u=6428442d875d5d71aaa1bb38bb11c4be1a526bc2&v=4
- url: https://github.com/r0b2g1t
-- login: RunningIkkyu
- count: 12
- avatarUrl: https://avatars.githubusercontent.com/u/31848542?u=494ecc298e3f26197495bb357ad0f57cfd5f7a32&v=4
- url: https://github.com/RunningIkkyu
-- login: ivan-abc
- count: 12
- avatarUrl: https://avatars.githubusercontent.com/u/36765187?u=c6e0ba571c1ccb6db9d94e62e4b8b5eda811a870&v=4
- url: https://github.com/ivan-abc
-- login: AlertRED
- count: 12
- avatarUrl: https://avatars.githubusercontent.com/u/15695000?u=f5a4944c6df443030409c88da7d7fa0b7ead985c&v=4
- url: https://github.com/AlertRED
-- login: solomein-sv
+ avatarUrl: https://avatars.githubusercontent.com/u/4335847?u=ed77f67e0bb069084639b24d812dbb2a2b1dc554&v=4
+ url: https://github.com/jgould22
+- login: sehraramiz
count: 11
- avatarUrl: https://avatars.githubusercontent.com/u/46193920?u=789927ee09cfabd752d3bd554fa6baf4850d2777&v=4
- url: https://github.com/solomein-sv
-top_translations_reviewers:
-- login: s111d
- count: 146
- avatarUrl: https://avatars.githubusercontent.com/u/4954856?v=4
- url: https://github.com/s111d
-- login: Xewus
- count: 128
- avatarUrl: https://avatars.githubusercontent.com/u/85196001?u=f8e2dc7e5104f109cef944af79050ea8d1b8f914&v=4
- url: https://github.com/Xewus
-- login: tokusumi
- count: 104
- avatarUrl: https://avatars.githubusercontent.com/u/41147016?u=55010621aece725aa702270b54fed829b6a1fe60&v=4
- url: https://github.com/tokusumi
+ avatarUrl: https://avatars.githubusercontent.com/u/14166324?u=8fac65e84dfff24245d304a5b5b09f7b5bd69dc9&v=4
+ url: https://github.com/sehraramiz
+- login: JavierSanchezCastro
+ count: 9
+ avatarUrl: https://avatars.githubusercontent.com/u/72013291?u=ae5679e6bd971d9d98cd5e76e8683f83642ba950&v=4
+ url: https://github.com/JavierSanchezCastro
+- login: yauhen-sobaleu
+ count: 9
+ avatarUrl: https://avatars.githubusercontent.com/u/51629535?u=fc1817060daf2df438bfca86c44f33da5cd667db&v=4
+ url: https://github.com/yauhen-sobaleu
+- login: estebanx64
+ count: 7
+ avatarUrl: https://avatars.githubusercontent.com/u/10840422?u=45f015f95e1c0f06df602be4ab688d4b854cc8a8&v=4
+ url: https://github.com/estebanx64
+- login: yvallois
+ count: 7
+ avatarUrl: https://avatars.githubusercontent.com/u/36999744?v=4
+ url: https://github.com/yvallois
+- login: tiangolo
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/1326112?u=cb5d06e73a9e1998141b1641aa88e443c6717651&v=4
+ url: https://github.com/tiangolo
+- login: yokwejuste
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/71908316?u=592c1e42aa0ee5cb94890e0b863e2acc78cc3bbc&v=4
+ url: https://github.com/yokwejuste
+- login: sachinh35
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/21972708?u=8560b97b8b41e175f476270b56de8a493b84f302&v=4
+ url: https://github.com/sachinh35
+- login: viniciusCalcantara
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/108818737?u=3d7ffe5808843ee4372f9cc5a559ff1674cf1792&v=4
+ url: https://github.com/viniciusCalcantara
+- login: SobikXexe
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/87701130?v=4
+ url: https://github.com/SobikXexe
+- login: chaitanyarahalkar
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/24942959?u=d3fbbc622540cb50b956585d5aec5037e01e4b1f&v=4
+ url: https://github.com/chaitanyarahalkar
+- login: KianAnbarestani
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/145364424?u=dcc3d8fb4ca07d36fb52a17f38b6650565de40be&v=4
+ url: https://github.com/KianAnbarestani
+- login: sinisaos
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/30960668?v=4
+ url: https://github.com/sinisaos
+- login: Ale-Cas
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/64859146?u=d52a6ecf8d83d2927e2ae270bdfcc83495dba8c9&v=4
+ url: https://github.com/Ale-Cas
+- login: adsouza
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/275832?v=4
+ url: https://github.com/adsouza
+- login: Synrom
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/30272537?v=4
+ url: https://github.com/Synrom
+- login: PREPONDERANCE
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/112809059?u=30ab12dc9ddba2f94ab90e6ad4ad8bc5cfa7fccd&v=4
+ url: https://github.com/PREPONDERANCE
+- login: nbx3
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/34649527?u=943812f69e0d40adbd3fa1c9b8ef50dd971a2a45&v=4
+ url: https://github.com/nbx3
+- login: marsboy02
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/86903678?u=fa4a6b91eea3a11ae93c162616ca5edf51c68572&v=4
+ url: https://github.com/marsboy02
+- login: EverStarck
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/51029456?u=343409b7cb6b3ea6a59359f4e8370d9c3f140ecd&v=4
+ url: https://github.com/EverStarck
+- login: vtgn
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/112889052?v=4
+ url: https://github.com/vtgn
+- login: Trinkes
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/9466879?v=4
+ url: https://github.com/Trinkes
+- login: XiaoXinYo
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/56395004?u=1eebf5ce25a8067f7bfa6251a24f667be492d9d6&v=4
+ url: https://github.com/XiaoXinYo
+- login: iloveitaly
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/150855?v=4
+ url: https://github.com/iloveitaly
+- login: LincolnPuzey
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/18750802?v=4
+ url: https://github.com/LincolnPuzey
+- login: Knighthawk-Leo
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/72437494?u=27c68db94a3107b605e603cc136f4ba83f0106d5&v=4
+ url: https://github.com/Knighthawk-Leo
+- login: gelezo43
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/40732698?u=611f39d3c1d2f4207a590937a78c1f10eed6232c&v=4
+ url: https://github.com/gelezo43
+- login: AliYmn
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/18416653?u=98c1fca46c7e4dabe8c39d17b5e55d1511d41cf9&v=4
+ url: https://github.com/AliYmn
+- login: RichieB2B
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/1461970?u=edaa57d1077705244ea5c9244f4783d94ff11f12&v=4
+ url: https://github.com/RichieB2B
+- login: iiotsrc
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/131771119?u=bcaf2559ef6266af70b151b7fda31a1ee3dbecb3&v=4
+ url: https://github.com/iiotsrc
+- login: Kfir-G
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/57500876?u=0cd29db046a17f12f382d398141319fca7ff230a&v=4
+ url: https://github.com/Kfir-G
+one_year_experts:
+- login: YuriiMotov
+ count: 172
+ avatarUrl: https://avatars.githubusercontent.com/u/109919500?u=e83a39697a2d33ab2ec9bfbced794ee48bc29cec&v=4
+ url: https://github.com/YuriiMotov
+- login: Kludex
+ count: 63
+ avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=df8a3f06ba8f55ae1967a3e2d5ed882903a4e330&v=4
+ url: https://github.com/Kludex
+- login: luzzodev
+ count: 61
+ avatarUrl: https://avatars.githubusercontent.com/u/27291415?u=5607ae1ce75c5f54f09500ca854227f7bfd2033b&v=4
+ url: https://github.com/luzzodev
+- login: sinisaos
+ count: 41
+ avatarUrl: https://avatars.githubusercontent.com/u/30960668?v=4
+ url: https://github.com/sinisaos
+- login: JavierSanchezCastro
+ count: 33
+ avatarUrl: https://avatars.githubusercontent.com/u/72013291?u=ae5679e6bd971d9d98cd5e76e8683f83642ba950&v=4
+ url: https://github.com/JavierSanchezCastro
+- login: jgould22
+ count: 27
+ avatarUrl: https://avatars.githubusercontent.com/u/4335847?u=ed77f67e0bb069084639b24d812dbb2a2b1dc554&v=4
+ url: https://github.com/jgould22
+- login: alv2017
+ count: 25
+ avatarUrl: https://avatars.githubusercontent.com/u/31544722?v=4
+ url: https://github.com/alv2017
+- login: tiangolo
+ count: 24
+ avatarUrl: https://avatars.githubusercontent.com/u/1326112?u=cb5d06e73a9e1998141b1641aa88e443c6717651&v=4
+ url: https://github.com/tiangolo
+- login: ceb10n
+ count: 15
+ avatarUrl: https://avatars.githubusercontent.com/u/235213?u=edcce471814a1eba9f0cdaa4cd0de18921a940a6&v=4
+ url: https://github.com/ceb10n
+- login: estebanx64
+ count: 13
+ avatarUrl: https://avatars.githubusercontent.com/u/10840422?u=45f015f95e1c0f06df602be4ab688d4b854cc8a8&v=4
+ url: https://github.com/estebanx64
+- login: n8sty
+ count: 13
+ avatarUrl: https://avatars.githubusercontent.com/u/2964996?v=4
+ url: https://github.com/n8sty
+- login: Kfir-G
+ count: 13
+ avatarUrl: https://avatars.githubusercontent.com/u/57500876?u=0cd29db046a17f12f382d398141319fca7ff230a&v=4
+ url: https://github.com/Kfir-G
+- login: sehraramiz
+ count: 11
+ avatarUrl: https://avatars.githubusercontent.com/u/14166324?u=8fac65e84dfff24245d304a5b5b09f7b5bd69dc9&v=4
+ url: https://github.com/sehraramiz
+- login: PhysicallyActive
+ count: 11
+ avatarUrl: https://avatars.githubusercontent.com/u/160476156?u=7a8e44f4a43d3bba636f795bb7d9476c9233b4d8&v=4
+ url: https://github.com/PhysicallyActive
+- login: mattmess1221
+ count: 11
+ avatarUrl: https://avatars.githubusercontent.com/u/3409962?u=d22ea18aa8ea688af25a45df306134d593621a44&v=4
+ url: https://github.com/mattmess1221
+- login: yauhen-sobaleu
+ count: 9
+ avatarUrl: https://avatars.githubusercontent.com/u/51629535?u=fc1817060daf2df438bfca86c44f33da5cd667db&v=4
+ url: https://github.com/yauhen-sobaleu
+- login: AIdjis
+ count: 8
+ avatarUrl: https://avatars.githubusercontent.com/u/88404339?u=2a80d80b054e9228391e32fb9bb39571509dab6a&v=4
+ url: https://github.com/AIdjis
+- login: yvallois
+ count: 7
+ avatarUrl: https://avatars.githubusercontent.com/u/36999744?v=4
+ url: https://github.com/yvallois
- login: hasansezertasan
- count: 91
+ count: 5
avatarUrl: https://avatars.githubusercontent.com/u/13135006?u=99f0b0f0fc47e88e8abb337b4447357939ef93e7&v=4
url: https://github.com/hasansezertasan
-- login: AlertRED
- count: 70
- avatarUrl: https://avatars.githubusercontent.com/u/15695000?u=f5a4944c6df443030409c88da7d7fa0b7ead985c&v=4
- url: https://github.com/AlertRED
-- login: Alexandrhub
- count: 68
- avatarUrl: https://avatars.githubusercontent.com/u/119126536?u=9fc0d48f3307817bafecc5861eb2168401a6cb04&v=4
- url: https://github.com/Alexandrhub
-- login: waynerv
- count: 63
- avatarUrl: https://avatars.githubusercontent.com/u/39515546?u=ec35139777597cdbbbddda29bf8b9d4396b429a9&v=4
- url: https://github.com/waynerv
-- login: hard-coders
- count: 53
- avatarUrl: https://avatars.githubusercontent.com/u/9651103?u=95db33927bbff1ed1c07efddeb97ac2ff33068ed&v=4
- url: https://github.com/hard-coders
-- login: Laineyzhang55
- count: 48
- avatarUrl: https://avatars.githubusercontent.com/u/59285379?v=4
- url: https://github.com/Laineyzhang55
-- login: Kludex
- count: 46
- avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=62adc405ef418f4b6c8caa93d3eb8ab107bc4927&v=4
- url: https://github.com/Kludex
-- login: komtaki
- count: 45
- avatarUrl: https://avatars.githubusercontent.com/u/39375566?u=260ad6b1a4b34c07dbfa728da5e586f16f6d1824&v=4
- url: https://github.com/komtaki
-- login: alperiox
- count: 42
- avatarUrl: https://avatars.githubusercontent.com/u/34214152?u=2c5acad3461d4dbc2d48371ba86cac56ae9b25cc&v=4
- url: https://github.com/alperiox
-- login: Winand
- count: 40
- avatarUrl: https://avatars.githubusercontent.com/u/53390?u=bb0e71a2fc3910a8e0ee66da67c33de40ea695f8&v=4
- url: https://github.com/Winand
-- login: solomein-sv
- count: 38
- avatarUrl: https://avatars.githubusercontent.com/u/46193920?u=789927ee09cfabd752d3bd554fa6baf4850d2777&v=4
- url: https://github.com/solomein-sv
-- login: lsglucas
- count: 36
- avatarUrl: https://avatars.githubusercontent.com/u/61513630?u=320e43fe4dc7bc6efc64e9b8f325f8075634fd20&v=4
- url: https://github.com/lsglucas
-- login: SwftAlpc
- count: 36
- avatarUrl: https://avatars.githubusercontent.com/u/52768429?u=6a3aa15277406520ad37f6236e89466ed44bc5b8&v=4
- url: https://github.com/SwftAlpc
-- login: nilslindemann
- count: 35
- avatarUrl: https://avatars.githubusercontent.com/u/6892179?u=1dca6a22195d6cd1ab20737c0e19a4c55d639472&v=4
- url: https://github.com/nilslindemann
-- login: rjNemo
- count: 34
- avatarUrl: https://avatars.githubusercontent.com/u/56785022?u=d5c3a02567c8649e146fcfc51b6060ccaf8adef8&v=4
- url: https://github.com/rjNemo
-- login: akarev0
- count: 33
- avatarUrl: https://avatars.githubusercontent.com/u/53393089?u=6e528bb4789d56af887ce6fe237bea4010885406&v=4
- url: https://github.com/akarev0
-- login: romashevchenko
- count: 32
- avatarUrl: https://avatars.githubusercontent.com/u/132477732?v=4
- url: https://github.com/romashevchenko
-- login: wdh99
- count: 31
- avatarUrl: https://avatars.githubusercontent.com/u/108172295?u=8a8fb95d5afe3e0fa33257b2aecae88d436249eb&v=4
- url: https://github.com/wdh99
-- login: LorhanSohaky
- count: 30
- avatarUrl: https://avatars.githubusercontent.com/u/16273730?u=095b66f243a2cd6a0aadba9a095009f8aaf18393&v=4
- url: https://github.com/LorhanSohaky
-- login: cassiobotaro
- count: 29
- avatarUrl: https://avatars.githubusercontent.com/u/3127847?u=a08022b191ddbd0a6159b2981d9d878b6d5bb71f&v=4
- url: https://github.com/cassiobotaro
-- login: pedabraham
- count: 28
- avatarUrl: https://avatars.githubusercontent.com/u/16860088?u=abf922a7b920bf8fdb7867d8b43e091f1e796178&v=4
- url: https://github.com/pedabraham
-- login: Smlep
- count: 28
- avatarUrl: https://avatars.githubusercontent.com/u/16785985?v=4
- url: https://github.com/Smlep
-- login: dedkot01
- count: 28
- avatarUrl: https://avatars.githubusercontent.com/u/26196675?u=e2966887124e67932853df4f10f86cb526edc7b0&v=4
- url: https://github.com/dedkot01
-- login: hsuanchi
- count: 28
- avatarUrl: https://avatars.githubusercontent.com/u/24913710?u=0b094ae292292fee093818e37ceb645c114d2bff&v=4
- url: https://github.com/hsuanchi
-- login: dpinezich
- count: 28
- avatarUrl: https://avatars.githubusercontent.com/u/3204540?u=a2e1465e3ee10d537614d513589607eddefde09f&v=4
- url: https://github.com/dpinezich
-- login: maoyibo
- count: 27
- avatarUrl: https://avatars.githubusercontent.com/u/7887703?v=4
- url: https://github.com/maoyibo
-- login: 0417taehyun
- count: 27
- avatarUrl: https://avatars.githubusercontent.com/u/63915557?u=47debaa860fd52c9b98c97ef357ddcec3b3fb399&v=4
- url: https://github.com/0417taehyun
-- login: BilalAlpaslan
- count: 26
- avatarUrl: https://avatars.githubusercontent.com/u/47563997?u=63ed66e304fe8d765762c70587d61d9196e5c82d&v=4
- url: https://github.com/BilalAlpaslan
-- login: zy7y
- count: 25
- avatarUrl: https://avatars.githubusercontent.com/u/67154681?u=5d634834cc514028ea3f9115f7030b99a1f4d5a4&v=4
- url: https://github.com/zy7y
-- login: mycaule
- count: 25
- avatarUrl: https://avatars.githubusercontent.com/u/6161385?u=e3cec75bd6d938a0d73fae0dc5534d1ab2ed1b0e&v=4
- url: https://github.com/mycaule
-- login: sh0nk
- count: 23
- avatarUrl: https://avatars.githubusercontent.com/u/6478810?u=af15d724875cec682ed8088a86d36b2798f981c0&v=4
- url: https://github.com/sh0nk
-- login: axel584
- count: 23
- avatarUrl: https://avatars.githubusercontent.com/u/1334088?u=9667041f5b15dc002b6f9665fda8c0412933ac04&v=4
- url: https://github.com/axel584
-- login: AGolicyn
- count: 21
- avatarUrl: https://avatars.githubusercontent.com/u/86262613?u=3c21606ab8d210a061a1673decff1e7d5592b380&v=4
- url: https://github.com/AGolicyn
-- login: OzgunCaglarArslan
- count: 21
- avatarUrl: https://avatars.githubusercontent.com/u/86166426?v=4
- url: https://github.com/OzgunCaglarArslan
-- login: Attsun1031
- count: 20
- avatarUrl: https://avatars.githubusercontent.com/u/1175560?v=4
- url: https://github.com/Attsun1031
-- login: ycd
- count: 20
- avatarUrl: https://avatars.githubusercontent.com/u/62724709?u=29682e4b6ac7d5293742ccf818188394b9a82972&v=4
- url: https://github.com/ycd
-- login: delhi09
- count: 20
- avatarUrl: https://avatars.githubusercontent.com/u/63476957?u=6c86e59b48e0394d4db230f37fc9ad4d7e2c27c7&v=4
- url: https://github.com/delhi09
-- login: rogerbrinkmann
- count: 20
- avatarUrl: https://avatars.githubusercontent.com/u/5690226?v=4
- url: https://github.com/rogerbrinkmann
-- login: DevDae
- count: 20
- avatarUrl: https://avatars.githubusercontent.com/u/87962045?u=08e10fa516e844934f4b3fc7c38b33c61697e4a1&v=4
- url: https://github.com/DevDae
-- login: sattosan
- count: 19
- avatarUrl: https://avatars.githubusercontent.com/u/20574756?u=b0d8474d2938189c6954423ae8d81d91013f80a8&v=4
- url: https://github.com/sattosan
-- login: ComicShrimp
- count: 18
- avatarUrl: https://avatars.githubusercontent.com/u/43503750?u=d2fbf412e7730183ce91686ca48d4147e1b7dc74&v=4
- url: https://github.com/ComicShrimp
-- login: junah201
- count: 18
- avatarUrl: https://avatars.githubusercontent.com/u/75025529?u=2451c256e888fa2a06bcfc0646d09b87ddb6a945&v=4
- url: https://github.com/junah201
-- login: simatheone
- count: 18
- avatarUrl: https://avatars.githubusercontent.com/u/78508673?u=1b9658d9ee0bde33f56130dd52275493ddd38690&v=4
- url: https://github.com/simatheone
-- login: ivan-abc
- count: 18
- avatarUrl: https://avatars.githubusercontent.com/u/36765187?u=c6e0ba571c1ccb6db9d94e62e4b8b5eda811a870&v=4
- url: https://github.com/ivan-abc
-- login: JavierSanchezCastro
- count: 18
- avatarUrl: https://avatars.githubusercontent.com/u/72013291?u=ae5679e6bd971d9d98cd5e76e8683f83642ba950&v=4
- url: https://github.com/JavierSanchezCastro
-- login: bezaca
- count: 17
- avatarUrl: https://avatars.githubusercontent.com/u/69092910?u=4ac58eab99bd37d663f3d23551df96d4fbdbf760&v=4
- url: https://github.com/bezaca
+- login: gustavosett
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/99373133?u=1382fe27034a0179f07cf989f63c4f23017f043c&v=4
+ url: https://github.com/gustavosett
+- login: chyok
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/32629225?u=3b7c30e8a09426a1b9284f6e8a0ae53a525596bf&v=4
+ url: https://github.com/chyok
+- login: PREPONDERANCE
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/112809059?u=30ab12dc9ddba2f94ab90e6ad4ad8bc5cfa7fccd&v=4
+ url: https://github.com/PREPONDERANCE
+- login: svlandeg
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/8796347?u=556c97650c27021911b0b9447ec55e75987b0e8a&v=4
+ url: https://github.com/svlandeg
+- login: TomFaulkner
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/14956620?v=4
+ url: https://github.com/TomFaulkner
+- login: yokwejuste
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/71908316?u=592c1e42aa0ee5cb94890e0b863e2acc78cc3bbc&v=4
+ url: https://github.com/yokwejuste
+- login: binbjz
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/8213913?u=40b777c625cf53dcdc6afc4aa127de67c48bf610&v=4
+ url: https://github.com/binbjz
+- login: dbfreem
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/9778569?u=f2f1e9135b5e4f1b0c6821a548b17f97572720fc&v=4
+ url: https://github.com/dbfreem
+- login: sachinh35
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/21972708?u=8560b97b8b41e175f476270b56de8a493b84f302&v=4
+ url: https://github.com/sachinh35
+- login: viniciusCalcantara
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/108818737?u=3d7ffe5808843ee4372f9cc5a559ff1674cf1792&v=4
+ url: https://github.com/viniciusCalcantara
+- login: SobikXexe
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/87701130?v=4
+ url: https://github.com/SobikXexe
+- login: DeoLeung
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/3764720?u=4c222ef513814de4c7fb3736d0a7adf11d953d43&v=4
+ url: https://github.com/DeoLeung
+- login: pawelad
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/7062874?u=d27dc220545a8401ad21840590a97d474d7101e6&v=4
+ url: https://github.com/pawelad
+- login: Isuxiz
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/48672727?u=34d7b4ade252687d22a27cf53037b735b244bfc1&v=4
+ url: https://github.com/Isuxiz
+- login: bertomaniac
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/10235051?u=14484a96833228a7b29fee4a7916d411c242c4f6&v=4
+ url: https://github.com/bertomaniac
+- login: deight93
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/37678115?u=a608798b5bd0034183a9c430ebb42fb266db86ce&v=4
+ url: https://github.com/deight93
+- login: Minibrams
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/8108085?u=b028dbc308fa8485e0e2e9402b3d03d8deb22bf9&v=4
+ url: https://github.com/Minibrams
+- login: alexandercronin
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/8014288?u=69580504c51a0cdd756fc47b23bb7f404bd694e7&v=4
+ url: https://github.com/alexandercronin
+- login: yanggeorge
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/2434407?v=4
+ url: https://github.com/yanggeorge
+- login: chaitanyarahalkar
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/24942959?u=d3fbbc622540cb50b956585d5aec5037e01e4b1f&v=4
+ url: https://github.com/chaitanyarahalkar
+- login: KianAnbarestani
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/145364424?u=dcc3d8fb4ca07d36fb52a17f38b6650565de40be&v=4
+ url: https://github.com/KianAnbarestani
+- login: rustonaut
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/7632017?u=652bb86c1399727082c929fd4666fd7fa65923b1&v=4
+ url: https://github.com/rustonaut
+- login: Ale-Cas
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/64859146?u=d52a6ecf8d83d2927e2ae270bdfcc83495dba8c9&v=4
+ url: https://github.com/Ale-Cas
+- login: CharlesPerrotMinotHCHB
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/112571330?u=a9628848d6096b491135727435a2a253152995a1&v=4
+ url: https://github.com/CharlesPerrotMinotHCHB
+- login: adsouza
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/275832?v=4
+ url: https://github.com/adsouza
+- login: Synrom
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/30272537?v=4
+ url: https://github.com/Synrom
+- login: gaby
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/835733?u=8c72dec16fa560bdc81113354f2ffd79ad062bde&v=4
+ url: https://github.com/gaby
+- login: nbx3
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/34649527?u=943812f69e0d40adbd3fa1c9b8ef50dd971a2a45&v=4
+ url: https://github.com/nbx3
+- login: marsboy02
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/86903678?u=fa4a6b91eea3a11ae93c162616ca5edf51c68572&v=4
+ url: https://github.com/marsboy02
+- login: EverStarck
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/51029456?u=343409b7cb6b3ea6a59359f4e8370d9c3f140ecd&v=4
+ url: https://github.com/EverStarck
+- login: Trolldemorted
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/10261186?v=4
+ url: https://github.com/Trolldemorted
+- login: anantgupta129
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/66518357?u=6e25dcd84638f17d2c6df5dc26f07fd7c6dc118e&v=4
+ url: https://github.com/anantgupta129
+- login: slafs
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/210173?v=4
+ url: https://github.com/slafs
+- login: ddahan
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/1933516?u=1d200a620e8d6841df017e9f2bb7efb58b580f40&v=4
+ url: https://github.com/ddahan
+- login: vtgn
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/112889052?v=4
+ url: https://github.com/vtgn
+- login: redb0
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/30475117?v=4
+ url: https://github.com/redb0
+- login: pedroconceicao
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/32837064?u=5a0e6559bc391442629a28b6923790b54deb4464&v=4
+ url: https://github.com/pedroconceicao
+- login: msukmanowsky
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/362755?u=782e6bf5b9f0356c3f74b4d894fda9f179252086&v=4
+ url: https://github.com/msukmanowsky
+- login: rishabhc32
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/15983714?u=147776509107af8bdf099223e1840d3f40f944da&v=4
+ url: https://github.com/rishabhc32
+- login: meower1
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/109747197?u=0a5cc2a6ae74e558f0afc2874da85132e5953d8b&v=4
+ url: https://github.com/meower1
+- login: Trinkes
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/9466879?v=4
+ url: https://github.com/Trinkes
diff --git a/docs/en/data/skip_users.yml b/docs/en/data/skip_users.yml
new file mode 100644
index 000000000..cf24003af
--- /dev/null
+++ b/docs/en/data/skip_users.yml
@@ -0,0 +1,5 @@
+- tiangolo
+- codecov
+- github-actions
+- pre-commit-ci
+- dependabot
diff --git a/docs/en/data/sponsors.yml b/docs/en/data/sponsors.yml
index 39654a361..f712b6179 100644
--- a/docs/en/data/sponsors.yml
+++ b/docs/en/data/sponsors.yml
@@ -1,60 +1,60 @@
gold:
- - url: https://cryptapi.io/
- title: "CryptAPI: Your easy to use, secure and privacy oriented payment gateway."
- img: https://fastapi.tiangolo.com/img/sponsors/cryptapi.svg
+ - url: https://blockbee.io?ref=fastapi
+ title: BlockBee Cryptocurrency Payment Gateway
+ img: https://fastapi.tiangolo.com/img/sponsors/blockbee.png
- url: https://platform.sh/try-it-now/?utm_source=fastapi-signup&utm_medium=banner&utm_campaign=FastAPI-signup-June-2023
title: "Build, run and scale your apps on a modern, reliable, and secure PaaS."
img: https://fastapi.tiangolo.com/img/sponsors/platform-sh.png
- - url: https://www.porter.run
- title: Deploy FastAPI on AWS with a few clicks
- 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.svg
- url: https://github.com/scalar/scalar/?utm_source=fastapi&utm_medium=website&utm_campaign=main-badge
title: "Scalar: Beautiful Open-Source API References from Swagger/OpenAPI files"
img: https://fastapi.tiangolo.com/img/sponsors/scalar.svg
- url: https://www.propelauth.com/?utm_source=fastapi&utm_campaign=1223&utm_medium=mainbadge
title: Auth, user management and more for your B2B product
img: https://fastapi.tiangolo.com/img/sponsors/propelauth.png
- - url: https://docs.withcoherence.com/configuration/frameworks/?utm_medium=advertising&utm_source=fastapi&utm_campaign=docs#fastapi-example
- title: Coherence
- img: https://fastapi.tiangolo.com/img/sponsors/coherence.png
- - url: https://www.mongodb.com/developer/languages/python/python-quickstart-fastapi/?utm_campaign=fastapi_framework&utm_source=fastapi_sponsorship&utm_medium=web_referral
- title: Simplify Full Stack Development with FastAPI & MongoDB
- img: https://fastapi.tiangolo.com/img/sponsors/mongodb.png
- - url: https://konghq.com/products/kong-konnect?utm_medium=referral&utm_source=github&utm_campaign=platform&utm_content=fast-api
- title: Kong Konnect - API management platform
- img: https://fastapi.tiangolo.com/img/sponsors/kong.png
- url: https://zuplo.link/fastapi-gh
- title: 'Zuplo: Scale, Protect, Document, and Monetize your FastAPI'
+ title: 'Zuplo: Deploy, Secure, Document, and Monetize your FastAPI'
img: https://fastapi.tiangolo.com/img/sponsors/zuplo.png
- - url: https://fine.dev?ref=fastapibadge
- title: "Fine's AI FastAPI Workflow: Effortlessly Deploy and Integrate FastAPI into Your Project"
- img: https://fastapi.tiangolo.com/img/sponsors/fine.png
+ - url: https://liblab.com?utm_source=fastapi
+ title: liblab - Generate SDKs from FastAPI
+ img: https://fastapi.tiangolo.com/img/sponsors/liblab.png
+ - url: https://docs.render.com/deploy-fastapi?utm_source=deploydoc&utm_medium=referral&utm_campaign=fastapi
+ title: Deploy & scale any full-stack web app on Render. Focus on building apps, not infra.
+ img: https://fastapi.tiangolo.com/img/sponsors/render.svg
+ - url: https://www.coderabbit.ai/?utm_source=fastapi&utm_medium=badge&utm_campaign=fastapi
+ title: Cut Code Review Time & Bugs in Half with CodeRabbit
+ img: https://fastapi.tiangolo.com/img/sponsors/coderabbit.png
+ - url: https://subtotal.com/?utm_source=fastapi&utm_medium=sponsorship&utm_campaign=open-source
+ title: The Gold Standard in Retail Account Linking
+ img: https://fastapi.tiangolo.com/img/sponsors/subtotal.svg
silver:
- - url: https://github.com/deepset-ai/haystack/
- title: Build powerful search from composable, open source building blocks
- img: https://fastapi.tiangolo.com/img/sponsors/haystack-fastapi.svg
- url: https://databento.com/
title: Pay as you go for market data
img: https://fastapi.tiangolo.com/img/sponsors/databento.svg
- - url: https://speakeasy.com?utm_source=fastapi+repo&utm_medium=github+sponsorship
+ - url: https://speakeasy.com/editor?utm_source=fastapi+repo&utm_medium=github+sponsorship
title: SDKs for your API | Speakeasy
img: https://fastapi.tiangolo.com/img/sponsors/speakeasy.png
- url: https://www.svix.com/
title: Svix - Webhooks as a service
img: https://fastapi.tiangolo.com/img/sponsors/svix.svg
- - url: https://www.codacy.com/?utm_source=github&utm_medium=sponsors&utm_id=pioneers
- title: Take code reviews from hours to minutes
- img: https://fastapi.tiangolo.com/img/sponsors/codacy.png
- url: https://www.stainlessapi.com/?utm_source=fastapi&utm_medium=referral
title: Stainless | Generate best-in-class SDKs
img: https://fastapi.tiangolo.com/img/sponsors/stainless.png
+ - url: https://www.permit.io/blog/implement-authorization-in-fastapi?utm_source=github&utm_medium=referral&utm_campaign=fastapi
+ title: Fine-Grained Authorization for FastAPI
+ img: https://fastapi.tiangolo.com/img/sponsors/permit.png
+ - url: https://www.interviewpal.com/?utm_source=fastapi&utm_medium=open-source&utm_campaign=dev-hiring
+ title: InterviewPal - AI Interview Coach for Engineers and Devs
+ img: https://fastapi.tiangolo.com/img/sponsors/interviewpal.png
+ - url: https://dribia.com/en/
+ title: Dribia - Data Science within your reach
+ img: https://fastapi.tiangolo.com/img/sponsors/dribia.png
bronze:
- url: https://www.exoflare.com/open-source/?utm_source=FastAPI&utm_campaign=open_source
title: Biosecurity risk assessments made easy.
img: https://fastapi.tiangolo.com/img/sponsors/exoflare.png
- - url: https://testdriven.io/courses/tdd-fastapi/
- title: Learn to build high-quality web apps with best practices
- img: https://fastapi.tiangolo.com/img/sponsors/testdriven.svg
+ # - url: https://testdriven.io/courses/tdd-fastapi/
+ # title: Learn to build high-quality web apps with best practices
+ # img: https://fastapi.tiangolo.com/img/sponsors/testdriven.svg
+ - url: https://lambdatest.com/?utm_source=fastapi&utm_medium=partner&utm_campaign=sponsor&utm_term=opensource&utm_content=webpage
+ title: LambdaTest, AI-Powered Cloud-based Test Orchestration Platform
+ img: https://fastapi.tiangolo.com/img/sponsors/lambdatest.png
diff --git a/docs/en/data/sponsors_badge.yml b/docs/en/data/sponsors_badge.yml
index d8a41fbcb..d145e7372 100644
--- a/docs/en/data/sponsors_badge.yml
+++ b/docs/en/data/sponsors_badge.yml
@@ -29,4 +29,17 @@ logins:
- andrew-propelauth
- svix
- zuplo-oss
+ - zuplo
- Kong
+ - speakeasy-api
+ - jess-render
+ - blockbee-io
+ - liblaber
+ - render-sponsorships
+ - renderinc
+ - stainless-api
+ - snapit-cypher
+ - coderabbitai
+ - permitio
+ - LambdaTest-Inc
+ - dribia
diff --git a/docs/en/data/topic_repos.yml b/docs/en/data/topic_repos.yml
new file mode 100644
index 000000000..1f6ae55bd
--- /dev/null
+++ b/docs/en/data/topic_repos.yml
@@ -0,0 +1,495 @@
+- name: full-stack-fastapi-template
+ html_url: https://github.com/fastapi/full-stack-fastapi-template
+ stars: 33079
+ owner_login: fastapi
+ owner_html_url: https://github.com/fastapi
+- name: Hello-Python
+ html_url: https://github.com/mouredev/Hello-Python
+ stars: 30350
+ owner_login: mouredev
+ owner_html_url: https://github.com/mouredev
+- name: serve
+ html_url: https://github.com/jina-ai/serve
+ stars: 21593
+ owner_login: jina-ai
+ owner_html_url: https://github.com/jina-ai
+- name: HivisionIDPhotos
+ html_url: https://github.com/Zeyi-Lin/HivisionIDPhotos
+ stars: 17229
+ owner_login: Zeyi-Lin
+ owner_html_url: https://github.com/Zeyi-Lin
+- name: sqlmodel
+ html_url: https://github.com/fastapi/sqlmodel
+ stars: 16068
+ owner_login: fastapi
+ owner_html_url: https://github.com/fastapi
+- name: Douyin_TikTok_Download_API
+ html_url: https://github.com/Evil0ctal/Douyin_TikTok_Download_API
+ stars: 12689
+ owner_login: Evil0ctal
+ owner_html_url: https://github.com/Evil0ctal
+- name: fastapi-best-practices
+ html_url: https://github.com/zhanymkanov/fastapi-best-practices
+ stars: 11965
+ owner_login: zhanymkanov
+ owner_html_url: https://github.com/zhanymkanov
+- name: awesome-fastapi
+ html_url: https://github.com/mjhea0/awesome-fastapi
+ stars: 9773
+ owner_login: mjhea0
+ owner_html_url: https://github.com/mjhea0
+- name: FastUI
+ html_url: https://github.com/pydantic/FastUI
+ stars: 8829
+ owner_login: pydantic
+ owner_html_url: https://github.com/pydantic
+- name: nonebot2
+ html_url: https://github.com/nonebot/nonebot2
+ stars: 6779
+ owner_login: nonebot
+ owner_html_url: https://github.com/nonebot
+- name: FileCodeBox
+ html_url: https://github.com/vastsa/FileCodeBox
+ stars: 6652
+ owner_login: vastsa
+ owner_html_url: https://github.com/vastsa
+- name: serge
+ html_url: https://github.com/serge-chat/serge
+ stars: 5722
+ owner_login: serge-chat
+ owner_html_url: https://github.com/serge-chat
+- name: hatchet
+ html_url: https://github.com/hatchet-dev/hatchet
+ stars: 5607
+ owner_login: hatchet-dev
+ owner_html_url: https://github.com/hatchet-dev
+- name: polar
+ html_url: https://github.com/polarsource/polar
+ stars: 5327
+ owner_login: polarsource
+ owner_html_url: https://github.com/polarsource
+- name: fastapi-users
+ html_url: https://github.com/fastapi-users/fastapi-users
+ stars: 5235
+ owner_login: fastapi-users
+ owner_html_url: https://github.com/fastapi-users
+- name: fastapi_mcp
+ html_url: https://github.com/tadata-org/fastapi_mcp
+ stars: 5193
+ owner_login: tadata-org
+ owner_html_url: https://github.com/tadata-org
+- name: SurfSense
+ html_url: https://github.com/MODSetter/SurfSense
+ stars: 4833
+ owner_login: MODSetter
+ owner_html_url: https://github.com/MODSetter
+- name: chatgpt-web-share
+ html_url: https://github.com/chatpire/chatgpt-web-share
+ stars: 4307
+ owner_login: chatpire
+ owner_html_url: https://github.com/chatpire
+- name: strawberry
+ html_url: https://github.com/strawberry-graphql/strawberry
+ stars: 4281
+ owner_login: strawberry-graphql
+ owner_html_url: https://github.com/strawberry-graphql
+- name: atrilabs-engine
+ html_url: https://github.com/Atri-Labs/atrilabs-engine
+ stars: 4110
+ owner_login: Atri-Labs
+ owner_html_url: https://github.com/Atri-Labs
+- name: dynaconf
+ html_url: https://github.com/dynaconf/dynaconf
+ stars: 4008
+ owner_login: dynaconf
+ owner_html_url: https://github.com/dynaconf
+- name: poem
+ html_url: https://github.com/poem-web/poem
+ stars: 3977
+ owner_login: poem-web
+ owner_html_url: https://github.com/poem-web
+- name: farfalle
+ html_url: https://github.com/rashadphz/farfalle
+ stars: 3317
+ owner_login: rashadphz
+ owner_html_url: https://github.com/rashadphz
+- name: fastapi-admin
+ html_url: https://github.com/fastapi-admin/fastapi-admin
+ stars: 3253
+ owner_login: fastapi-admin
+ owner_html_url: https://github.com/fastapi-admin
+- name: datamodel-code-generator
+ html_url: https://github.com/koxudaxi/datamodel-code-generator
+ stars: 3228
+ owner_login: koxudaxi
+ owner_html_url: https://github.com/koxudaxi
+- name: LitServe
+ html_url: https://github.com/Lightning-AI/LitServe
+ stars: 3175
+ owner_login: Lightning-AI
+ owner_html_url: https://github.com/Lightning-AI
+- name: logfire
+ html_url: https://github.com/pydantic/logfire
+ stars: 3172
+ owner_login: pydantic
+ owner_html_url: https://github.com/pydantic
+- name: opyrator
+ html_url: https://github.com/ml-tooling/opyrator
+ stars: 3122
+ owner_login: ml-tooling
+ owner_html_url: https://github.com/ml-tooling
+- name: huma
+ html_url: https://github.com/danielgtaylor/huma
+ stars: 3110
+ owner_login: danielgtaylor
+ owner_html_url: https://github.com/danielgtaylor
+- name: docarray
+ html_url: https://github.com/docarray/docarray
+ stars: 3068
+ owner_login: docarray
+ owner_html_url: https://github.com/docarray
+- name: fastapi-realworld-example-app
+ html_url: https://github.com/nsidnev/fastapi-realworld-example-app
+ stars: 2892
+ owner_login: nsidnev
+ owner_html_url: https://github.com/nsidnev
+- name: Kokoro-FastAPI
+ html_url: https://github.com/remsky/Kokoro-FastAPI
+ stars: 2883
+ owner_login: remsky
+ owner_html_url: https://github.com/remsky
+- name: uvicorn-gunicorn-fastapi-docker
+ html_url: https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker
+ stars: 2770
+ owner_login: tiangolo
+ owner_html_url: https://github.com/tiangolo
+- name: tracecat
+ html_url: https://github.com/TracecatHQ/tracecat
+ stars: 2740
+ owner_login: TracecatHQ
+ owner_html_url: https://github.com/TracecatHQ
+- name: best-of-web-python
+ html_url: https://github.com/ml-tooling/best-of-web-python
+ stars: 2517
+ owner_login: ml-tooling
+ owner_html_url: https://github.com/ml-tooling
+- name: RasaGPT
+ html_url: https://github.com/paulpierre/RasaGPT
+ stars: 2423
+ owner_login: paulpierre
+ owner_html_url: https://github.com/paulpierre
+- name: fastapi-react
+ html_url: https://github.com/Buuntu/fastapi-react
+ stars: 2376
+ owner_login: Buuntu
+ owner_html_url: https://github.com/Buuntu
+- name: FastAPI-template
+ html_url: https://github.com/s3rius/FastAPI-template
+ stars: 2301
+ owner_login: s3rius
+ owner_html_url: https://github.com/s3rius
+- name: nextpy
+ html_url: https://github.com/dot-agent/nextpy
+ stars: 2289
+ owner_login: dot-agent
+ owner_html_url: https://github.com/dot-agent
+- name: sqladmin
+ html_url: https://github.com/aminalaee/sqladmin
+ stars: 2196
+ owner_login: aminalaee
+ owner_html_url: https://github.com/aminalaee
+- name: 30-Days-of-Python
+ html_url: https://github.com/codingforentrepreneurs/30-Days-of-Python
+ stars: 2179
+ owner_login: codingforentrepreneurs
+ owner_html_url: https://github.com/codingforentrepreneurs
+- name: langserve
+ html_url: https://github.com/langchain-ai/langserve
+ stars: 2098
+ owner_login: langchain-ai
+ owner_html_url: https://github.com/langchain-ai
+- name: fastapi-utils
+ html_url: https://github.com/fastapiutils/fastapi-utils
+ stars: 2077
+ owner_login: fastapiutils
+ owner_html_url: https://github.com/fastapiutils
+- name: supabase-py
+ html_url: https://github.com/supabase/supabase-py
+ stars: 2047
+ owner_login: supabase
+ owner_html_url: https://github.com/supabase
+- name: solara
+ html_url: https://github.com/widgetti/solara
+ stars: 2044
+ owner_login: widgetti
+ owner_html_url: https://github.com/widgetti
+- name: mangum
+ html_url: https://github.com/Kludex/mangum
+ stars: 1905
+ owner_login: Kludex
+ owner_html_url: https://github.com/Kludex
+- name: python-week-2022
+ html_url: https://github.com/rochacbruno/python-week-2022
+ stars: 1823
+ owner_login: rochacbruno
+ owner_html_url: https://github.com/rochacbruno
+- name: manage-fastapi
+ html_url: https://github.com/ycd/manage-fastapi
+ stars: 1754
+ owner_login: ycd
+ owner_html_url: https://github.com/ycd
+- name: agentkit
+ html_url: https://github.com/BCG-X-Official/agentkit
+ stars: 1746
+ owner_login: BCG-X-Official
+ owner_html_url: https://github.com/BCG-X-Official
+- name: ormar
+ html_url: https://github.com/collerek/ormar
+ stars: 1742
+ owner_login: collerek
+ owner_html_url: https://github.com/collerek
+- name: langchain-serve
+ html_url: https://github.com/jina-ai/langchain-serve
+ stars: 1630
+ owner_login: jina-ai
+ owner_html_url: https://github.com/jina-ai
+- name: termpair
+ html_url: https://github.com/cs01/termpair
+ stars: 1611
+ owner_login: cs01
+ owner_html_url: https://github.com/cs01
+- name: piccolo
+ html_url: https://github.com/piccolo-orm/piccolo
+ stars: 1609
+ owner_login: piccolo-orm
+ owner_html_url: https://github.com/piccolo-orm
+- name: coronavirus-tracker-api
+ html_url: https://github.com/ExpDev07/coronavirus-tracker-api
+ stars: 1587
+ owner_login: ExpDev07
+ owner_html_url: https://github.com/ExpDev07
+- name: fastapi-cache
+ html_url: https://github.com/long2ice/fastapi-cache
+ stars: 1575
+ owner_login: long2ice
+ owner_html_url: https://github.com/long2ice
+- name: openapi-python-client
+ html_url: https://github.com/openapi-generators/openapi-python-client
+ stars: 1568
+ owner_login: openapi-generators
+ owner_html_url: https://github.com/openapi-generators
+- name: fastapi-crudrouter
+ html_url: https://github.com/awtkns/fastapi-crudrouter
+ stars: 1508
+ owner_login: awtkns
+ owner_html_url: https://github.com/awtkns
+- name: slowapi
+ html_url: https://github.com/laurentS/slowapi
+ stars: 1501
+ owner_login: laurentS
+ owner_html_url: https://github.com/laurentS
+- name: awesome-fastapi-projects
+ html_url: https://github.com/Kludex/awesome-fastapi-projects
+ stars: 1453
+ owner_login: Kludex
+ owner_html_url: https://github.com/Kludex
+- name: awesome-python-resources
+ html_url: https://github.com/DjangoEx/awesome-python-resources
+ stars: 1390
+ owner_login: DjangoEx
+ owner_html_url: https://github.com/DjangoEx
+- name: fastapi-pagination
+ html_url: https://github.com/uriyyo/fastapi-pagination
+ stars: 1353
+ owner_login: uriyyo
+ owner_html_url: https://github.com/uriyyo
+- name: budgetml
+ html_url: https://github.com/ebhy/budgetml
+ stars: 1342
+ owner_login: ebhy
+ owner_html_url: https://github.com/ebhy
+- name: fastapi-boilerplate
+ html_url: https://github.com/teamhide/fastapi-boilerplate
+ stars: 1325
+ owner_login: teamhide
+ owner_html_url: https://github.com/teamhide
+- name: vue-fastapi-admin
+ html_url: https://github.com/mizhexiaoxiao/vue-fastapi-admin
+ stars: 1306
+ owner_login: mizhexiaoxiao
+ owner_html_url: https://github.com/mizhexiaoxiao
+- name: fastapi-amis-admin
+ html_url: https://github.com/amisadmin/fastapi-amis-admin
+ stars: 1256
+ owner_login: amisadmin
+ owner_html_url: https://github.com/amisadmin
+- name: fastapi-tutorial
+ html_url: https://github.com/liaogx/fastapi-tutorial
+ stars: 1245
+ owner_login: liaogx
+ owner_html_url: https://github.com/liaogx
+- name: fastapi-code-generator
+ html_url: https://github.com/koxudaxi/fastapi-code-generator
+ stars: 1201
+ owner_login: koxudaxi
+ owner_html_url: https://github.com/koxudaxi
+- name: bracket
+ html_url: https://github.com/evroon/bracket
+ stars: 1201
+ owner_login: evroon
+ owner_html_url: https://github.com/evroon
+- name: bolt-python
+ html_url: https://github.com/slackapi/bolt-python
+ stars: 1179
+ owner_login: slackapi
+ owner_html_url: https://github.com/slackapi
+- name: fastapi_production_template
+ html_url: https://github.com/zhanymkanov/fastapi_production_template
+ stars: 1147
+ owner_login: zhanymkanov
+ owner_html_url: https://github.com/zhanymkanov
+- name: prometheus-fastapi-instrumentator
+ html_url: https://github.com/trallnag/prometheus-fastapi-instrumentator
+ stars: 1145
+ owner_login: trallnag
+ owner_html_url: https://github.com/trallnag
+- name: bedrock-chat
+ html_url: https://github.com/aws-samples/bedrock-chat
+ stars: 1143
+ owner_login: aws-samples
+ owner_html_url: https://github.com/aws-samples
+- name: langchain-extract
+ html_url: https://github.com/langchain-ai/langchain-extract
+ stars: 1134
+ owner_login: langchain-ai
+ owner_html_url: https://github.com/langchain-ai
+- name: odmantic
+ html_url: https://github.com/art049/odmantic
+ stars: 1118
+ owner_login: art049
+ owner_html_url: https://github.com/art049
+- name: fastapi-alembic-sqlmodel-async
+ html_url: https://github.com/jonra1993/fastapi-alembic-sqlmodel-async
+ stars: 1110
+ owner_login: jonra1993
+ owner_html_url: https://github.com/jonra1993
+- name: fastcrud
+ html_url: https://github.com/benavlabs/fastcrud
+ stars: 1080
+ owner_login: benavlabs
+ owner_html_url: https://github.com/benavlabs
+- name: restish
+ html_url: https://github.com/rest-sh/restish
+ stars: 1056
+ owner_login: rest-sh
+ owner_html_url: https://github.com/rest-sh
+- name: fastapi_best_architecture
+ html_url: https://github.com/fastapi-practices/fastapi_best_architecture
+ stars: 1050
+ owner_login: fastapi-practices
+ owner_html_url: https://github.com/fastapi-practices
+- name: runhouse
+ html_url: https://github.com/run-house/runhouse
+ stars: 1034
+ owner_login: run-house
+ owner_html_url: https://github.com/run-house
+- name: autollm
+ html_url: https://github.com/viddexa/autollm
+ stars: 992
+ owner_login: viddexa
+ owner_html_url: https://github.com/viddexa
+- name: lanarky
+ html_url: https://github.com/ajndkr/lanarky
+ stars: 990
+ owner_login: ajndkr
+ owner_html_url: https://github.com/ajndkr
+- name: FastAPI-boilerplate
+ html_url: https://github.com/benavlabs/FastAPI-boilerplate
+ stars: 985
+ owner_login: benavlabs
+ owner_html_url: https://github.com/benavlabs
+- name: authx
+ html_url: https://github.com/yezz123/authx
+ stars: 938
+ owner_login: yezz123
+ owner_html_url: https://github.com/yezz123
+- name: secure
+ html_url: https://github.com/TypeError/secure
+ stars: 935
+ owner_login: TypeError
+ owner_html_url: https://github.com/TypeError
+- name: langcorn
+ html_url: https://github.com/msoedov/langcorn
+ stars: 925
+ owner_login: msoedov
+ owner_html_url: https://github.com/msoedov
+- name: energy-forecasting
+ html_url: https://github.com/iusztinpaul/energy-forecasting
+ stars: 913
+ owner_login: iusztinpaul
+ owner_html_url: https://github.com/iusztinpaul
+- name: titiler
+ html_url: https://github.com/developmentseed/titiler
+ stars: 886
+ owner_login: developmentseed
+ owner_html_url: https://github.com/developmentseed
+- name: flock
+ html_url: https://github.com/Onelevenvy/flock
+ stars: 866
+ owner_login: Onelevenvy
+ owner_html_url: https://github.com/Onelevenvy
+- name: httpdbg
+ html_url: https://github.com/cle-b/httpdbg
+ stars: 863
+ owner_login: cle-b
+ owner_html_url: https://github.com/cle-b
+- name: marker-api
+ html_url: https://github.com/adithya-s-k/marker-api
+ stars: 859
+ owner_login: adithya-s-k
+ owner_html_url: https://github.com/adithya-s-k
+- name: ludic
+ html_url: https://github.com/getludic/ludic
+ stars: 845
+ owner_login: getludic
+ owner_html_url: https://github.com/getludic
+- name: fastapi-do-zero
+ html_url: https://github.com/dunossauro/fastapi-do-zero
+ stars: 827
+ owner_login: dunossauro
+ owner_html_url: https://github.com/dunossauro
+- name: fastapi-observability
+ html_url: https://github.com/blueswen/fastapi-observability
+ stars: 823
+ owner_login: blueswen
+ owner_html_url: https://github.com/blueswen
+- name: fastapi-langgraph-agent-production-ready-template
+ html_url: https://github.com/wassim249/fastapi-langgraph-agent-production-ready-template
+ stars: 803
+ owner_login: wassim249
+ owner_html_url: https://github.com/wassim249
+- name: fastapi-mail
+ html_url: https://github.com/sabuhish/fastapi-mail
+ stars: 798
+ owner_login: sabuhish
+ owner_html_url: https://github.com/sabuhish
+- name: starlette-admin
+ html_url: https://github.com/jowilf/starlette-admin
+ stars: 785
+ owner_login: jowilf
+ owner_html_url: https://github.com/jowilf
+- name: lccn_predictor
+ html_url: https://github.com/baoliay2008/lccn_predictor
+ stars: 767
+ owner_login: baoliay2008
+ owner_html_url: https://github.com/baoliay2008
+- name: aktools
+ html_url: https://github.com/akfamily/aktools
+ stars: 759
+ owner_login: akfamily
+ owner_html_url: https://github.com/akfamily
+- name: KonomiTV
+ html_url: https://github.com/tsukumijima/KonomiTV
+ stars: 748
+ owner_login: tsukumijima
+ owner_html_url: https://github.com/tsukumijima
diff --git a/docs/en/data/translation_reviewers.yml b/docs/en/data/translation_reviewers.yml
new file mode 100644
index 000000000..aad3e4fac
--- /dev/null
+++ b/docs/en/data/translation_reviewers.yml
@@ -0,0 +1,1785 @@
+s111d:
+ login: s111d
+ count: 147
+ avatarUrl: https://avatars.githubusercontent.com/u/4954856?v=4
+ url: https://github.com/s111d
+Xewus:
+ login: Xewus
+ count: 140
+ avatarUrl: https://avatars.githubusercontent.com/u/85196001?u=f8e2dc7e5104f109cef944af79050ea8d1b8f914&v=4
+ url: https://github.com/Xewus
+sodaMelon:
+ login: sodaMelon
+ count: 125
+ avatarUrl: https://avatars.githubusercontent.com/u/66295123?u=be939db90f1119efee9e6110cc05066ff1f40f00&v=4
+ url: https://github.com/sodaMelon
+ceb10n:
+ login: ceb10n
+ count: 112
+ avatarUrl: https://avatars.githubusercontent.com/u/235213?u=edcce471814a1eba9f0cdaa4cd0de18921a940a6&v=4
+ url: https://github.com/ceb10n
+tokusumi:
+ login: tokusumi
+ count: 104
+ avatarUrl: https://avatars.githubusercontent.com/u/41147016?u=55010621aece725aa702270b54fed829b6a1fe60&v=4
+ url: https://github.com/tokusumi
+hasansezertasan:
+ login: hasansezertasan
+ count: 95
+ avatarUrl: https://avatars.githubusercontent.com/u/13135006?u=99f0b0f0fc47e88e8abb337b4447357939ef93e7&v=4
+ url: https://github.com/hasansezertasan
+hard-coders:
+ login: hard-coders
+ count: 92
+ avatarUrl: https://avatars.githubusercontent.com/u/9651103?u=95db33927bbff1ed1c07efddeb97ac2ff33068ed&v=4
+ url: https://github.com/hard-coders
+alv2017:
+ login: alv2017
+ count: 88
+ avatarUrl: https://avatars.githubusercontent.com/u/31544722?v=4
+ url: https://github.com/alv2017
+nazarepiedady:
+ login: nazarepiedady
+ count: 83
+ avatarUrl: https://avatars.githubusercontent.com/u/31008635?u=8dc25777dc9cb51fb0dbba2f137988953d330b78&v=4
+ url: https://github.com/nazarepiedady
+AlertRED:
+ login: AlertRED
+ count: 81
+ avatarUrl: https://avatars.githubusercontent.com/u/15695000?u=f5a4944c6df443030409c88da7d7fa0b7ead985c&v=4
+ url: https://github.com/AlertRED
+Alexandrhub:
+ login: Alexandrhub
+ count: 68
+ avatarUrl: https://avatars.githubusercontent.com/u/119126536?u=9fc0d48f3307817bafecc5861eb2168401a6cb04&v=4
+ url: https://github.com/Alexandrhub
+waynerv:
+ login: waynerv
+ count: 63
+ avatarUrl: https://avatars.githubusercontent.com/u/39515546?u=ec35139777597cdbbbddda29bf8b9d4396b429a9&v=4
+ url: https://github.com/waynerv
+cassiobotaro:
+ login: cassiobotaro
+ count: 62
+ avatarUrl: https://avatars.githubusercontent.com/u/3127847?u=a08022b191ddbd0a6159b2981d9d878b6d5bb71f&v=4
+ url: https://github.com/cassiobotaro
+mattwang44:
+ login: mattwang44
+ count: 59
+ avatarUrl: https://avatars.githubusercontent.com/u/24987826?u=58e37fb3927b9124b458945ac4c97aa0f1062d85&v=4
+ url: https://github.com/mattwang44
+tiangolo:
+ login: tiangolo
+ count: 52
+ avatarUrl: https://avatars.githubusercontent.com/u/1326112?u=cb5d06e73a9e1998141b1641aa88e443c6717651&v=4
+ url: https://github.com/tiangolo
+Laineyzhang55:
+ login: Laineyzhang55
+ count: 48
+ avatarUrl: https://avatars.githubusercontent.com/u/59285379?v=4
+ url: https://github.com/Laineyzhang55
+Kludex:
+ login: Kludex
+ count: 47
+ avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=df8a3f06ba8f55ae1967a3e2d5ed882903a4e330&v=4
+ url: https://github.com/Kludex
+komtaki:
+ login: komtaki
+ count: 45
+ avatarUrl: https://avatars.githubusercontent.com/u/39375566?u=260ad6b1a4b34c07dbfa728da5e586f16f6d1824&v=4
+ url: https://github.com/komtaki
+rostik1410:
+ login: rostik1410
+ count: 42
+ avatarUrl: https://avatars.githubusercontent.com/u/11443899?u=e26a635c2ba220467b308a326a579b8ccf4a8701&v=4
+ url: https://github.com/rostik1410
+svlandeg:
+ login: svlandeg
+ count: 42
+ avatarUrl: https://avatars.githubusercontent.com/u/8796347?u=556c97650c27021911b0b9447ec55e75987b0e8a&v=4
+ url: https://github.com/svlandeg
+alperiox:
+ login: alperiox
+ count: 42
+ avatarUrl: https://avatars.githubusercontent.com/u/34214152?u=2c5acad3461d4dbc2d48371ba86cac56ae9b25cc&v=4
+ url: https://github.com/alperiox
+Rishat-F:
+ login: Rishat-F
+ count: 42
+ avatarUrl: https://avatars.githubusercontent.com/u/66554797?v=4
+ url: https://github.com/Rishat-F
+Winand:
+ login: Winand
+ count: 40
+ avatarUrl: https://avatars.githubusercontent.com/u/53390?u=bb0e71a2fc3910a8e0ee66da67c33de40ea695f8&v=4
+ url: https://github.com/Winand
+solomein-sv:
+ login: solomein-sv
+ count: 38
+ avatarUrl: https://avatars.githubusercontent.com/u/46193920?u=789927ee09cfabd752d3bd554fa6baf4850d2777&v=4
+ url: https://github.com/solomein-sv
+JavierSanchezCastro:
+ login: JavierSanchezCastro
+ count: 38
+ avatarUrl: https://avatars.githubusercontent.com/u/72013291?u=ae5679e6bd971d9d98cd5e76e8683f83642ba950&v=4
+ url: https://github.com/JavierSanchezCastro
+stlucasgarcia:
+ login: stlucasgarcia
+ count: 36
+ avatarUrl: https://avatars.githubusercontent.com/u/61513630?u=c22d8850e9dc396a8820766a59837f967e14f9a0&v=4
+ url: https://github.com/stlucasgarcia
+SwftAlpc:
+ login: SwftAlpc
+ count: 36
+ avatarUrl: https://avatars.githubusercontent.com/u/52768429?u=6a3aa15277406520ad37f6236e89466ed44bc5b8&v=4
+ url: https://github.com/SwftAlpc
+alejsdev:
+ login: alejsdev
+ count: 36
+ avatarUrl: https://avatars.githubusercontent.com/u/90076947?u=638c65283ac9e9e2c3a0f9d1e3370db4b8a2c58d&v=4
+ url: https://github.com/alejsdev
+timothy-jeong:
+ login: timothy-jeong
+ count: 36
+ avatarUrl: https://avatars.githubusercontent.com/u/53824764?u=db3d0cea2f5fab64d810113c5039a369699a2774&v=4
+ url: https://github.com/timothy-jeong
+nilslindemann:
+ login: nilslindemann
+ count: 35
+ avatarUrl: https://avatars.githubusercontent.com/u/6892179?u=1dca6a22195d6cd1ab20737c0e19a4c55d639472&v=4
+ url: https://github.com/nilslindemann
+rjNemo:
+ login: rjNemo
+ count: 34
+ avatarUrl: https://avatars.githubusercontent.com/u/56785022?u=d5c3a02567c8649e146fcfc51b6060ccaf8adef8&v=4
+ url: https://github.com/rjNemo
+codingjenny:
+ login: codingjenny
+ count: 34
+ avatarUrl: https://avatars.githubusercontent.com/u/103817302?u=3a042740dc0ff58615da0d8679230966fd7693e8&v=4
+ url: https://github.com/codingjenny
+mezgoodle:
+ login: mezgoodle
+ count: 33
+ avatarUrl: https://avatars.githubusercontent.com/u/41520940?u=4a9c765af688389d54296845d18b8f6cd6ddf09a&v=4
+ url: https://github.com/mezgoodle
+akarev0:
+ login: akarev0
+ count: 33
+ avatarUrl: https://avatars.githubusercontent.com/u/53393089?u=6e528bb4789d56af887ce6fe237bea4010885406&v=4
+ url: https://github.com/akarev0
+romashevchenko:
+ login: romashevchenko
+ count: 32
+ avatarUrl: https://avatars.githubusercontent.com/u/132477732?v=4
+ url: https://github.com/romashevchenko
+LorhanSohaky:
+ login: LorhanSohaky
+ count: 30
+ avatarUrl: https://avatars.githubusercontent.com/u/16273730?u=095b66f243a2cd6a0aadba9a095009f8aaf18393&v=4
+ url: https://github.com/LorhanSohaky
+Vincy1230:
+ login: Vincy1230
+ count: 30
+ avatarUrl: https://avatars.githubusercontent.com/u/81342412?u=ab5e256a4077a4a91f3f9cd2115ba80780454cbe&v=4
+ url: https://github.com/Vincy1230
+black-redoc:
+ login: black-redoc
+ count: 29
+ avatarUrl: https://avatars.githubusercontent.com/u/18581590?u=7b6336166d0797fbbd44ea70c1c3ecadfc89af9e&v=4
+ url: https://github.com/black-redoc
+pedabraham:
+ login: pedabraham
+ count: 28
+ avatarUrl: https://avatars.githubusercontent.com/u/16860088?u=abf922a7b920bf8fdb7867d8b43e091f1e796178&v=4
+ url: https://github.com/pedabraham
+Smlep:
+ login: Smlep
+ count: 28
+ avatarUrl: https://avatars.githubusercontent.com/u/16785985?u=ffe99fa954c8e774ef1117e58d34aece92051e27&v=4
+ url: https://github.com/Smlep
+dedkot01:
+ login: dedkot01
+ count: 28
+ avatarUrl: https://avatars.githubusercontent.com/u/26196675?u=e2966887124e67932853df4f10f86cb526edc7b0&v=4
+ url: https://github.com/dedkot01
+hsuanchi:
+ login: hsuanchi
+ count: 28
+ avatarUrl: https://avatars.githubusercontent.com/u/24913710?u=7d25a398e478b6e63503bf6f26c54efa9e0da07b&v=4
+ url: https://github.com/hsuanchi
+dpinezich:
+ login: dpinezich
+ count: 28
+ avatarUrl: https://avatars.githubusercontent.com/u/3204540?u=a2e1465e3ee10d537614d513589607eddefde09f&v=4
+ url: https://github.com/dpinezich
+maoyibo:
+ login: maoyibo
+ count: 27
+ avatarUrl: https://avatars.githubusercontent.com/u/7887703?v=4
+ url: https://github.com/maoyibo
+0417taehyun:
+ login: 0417taehyun
+ count: 27
+ avatarUrl: https://avatars.githubusercontent.com/u/63915557?u=47debaa860fd52c9b98c97ef357ddcec3b3fb399&v=4
+ url: https://github.com/0417taehyun
+BilalAlpaslan:
+ login: BilalAlpaslan
+ count: 26
+ avatarUrl: https://avatars.githubusercontent.com/u/47563997?u=63ed66e304fe8d765762c70587d61d9196e5c82d&v=4
+ url: https://github.com/BilalAlpaslan
+junah201:
+ login: junah201
+ count: 26
+ avatarUrl: https://avatars.githubusercontent.com/u/75025529?u=2451c256e888fa2a06bcfc0646d09b87ddb6a945&v=4
+ url: https://github.com/junah201
+zy7y:
+ login: zy7y
+ count: 25
+ avatarUrl: https://avatars.githubusercontent.com/u/67154681?u=5d634834cc514028ea3f9115f7030b99a1f4d5a4&v=4
+ url: https://github.com/zy7y
+mycaule:
+ login: mycaule
+ count: 25
+ avatarUrl: https://avatars.githubusercontent.com/u/6161385?u=e3cec75bd6d938a0d73fae0dc5534d1ab2ed1b0e&v=4
+ url: https://github.com/mycaule
+Aruelius:
+ login: Aruelius
+ count: 24
+ avatarUrl: https://avatars.githubusercontent.com/u/25380989?u=574f8cfcda3ea77a3f81884f6b26a97068e36a9d&v=4
+ url: https://github.com/Aruelius
+wisderfin:
+ login: wisderfin
+ count: 24
+ avatarUrl: https://avatars.githubusercontent.com/u/77553770?u=9a23740d520d65dc0051cdc1ecd87f31cb900313&v=4
+ url: https://github.com/wisderfin
+OzgunCaglarArslan:
+ login: OzgunCaglarArslan
+ count: 24
+ avatarUrl: https://avatars.githubusercontent.com/u/86166426?v=4
+ url: https://github.com/OzgunCaglarArslan
+sh0nk:
+ login: sh0nk
+ count: 23
+ avatarUrl: https://avatars.githubusercontent.com/u/6478810?u=af15d724875cec682ed8088a86d36b2798f981c0&v=4
+ url: https://github.com/sh0nk
+axel584:
+ login: axel584
+ count: 23
+ avatarUrl: https://avatars.githubusercontent.com/u/1334088?u=9667041f5b15dc002b6f9665fda8c0412933ac04&v=4
+ url: https://github.com/axel584
+AGolicyn:
+ login: AGolicyn
+ count: 21
+ avatarUrl: https://avatars.githubusercontent.com/u/86262613?u=3c21606ab8d210a061a1673decff1e7d5592b380&v=4
+ url: https://github.com/AGolicyn
+Attsun1031:
+ login: Attsun1031
+ count: 20
+ avatarUrl: https://avatars.githubusercontent.com/u/1175560?v=4
+ url: https://github.com/Attsun1031
+ycd:
+ login: ycd
+ count: 20
+ avatarUrl: https://avatars.githubusercontent.com/u/62724709?u=f1e7bae394a315da950912c92dc861a8eaf95d4c&v=4
+ url: https://github.com/ycd
+delhi09:
+ login: delhi09
+ count: 20
+ avatarUrl: https://avatars.githubusercontent.com/u/63476957?u=6c86e59b48e0394d4db230f37fc9ad4d7e2c27c7&v=4
+ url: https://github.com/delhi09
+rogerbrinkmann:
+ login: rogerbrinkmann
+ count: 20
+ avatarUrl: https://avatars.githubusercontent.com/u/5690226?v=4
+ url: https://github.com/rogerbrinkmann
+DevDae:
+ login: DevDae
+ count: 20
+ avatarUrl: https://avatars.githubusercontent.com/u/87962045?u=08e10fa516e844934f4b3fc7c38b33c61697e4a1&v=4
+ url: https://github.com/DevDae
+sattosan:
+ login: sattosan
+ count: 19
+ avatarUrl: https://avatars.githubusercontent.com/u/20574756?u=b0d8474d2938189c6954423ae8d81d91013f80a8&v=4
+ url: https://github.com/sattosan
+yes0ng:
+ login: yes0ng
+ count: 19
+ avatarUrl: https://avatars.githubusercontent.com/u/25501794?u=3aed18b0d491e0220a167a1e9e58bea3638c6707&v=4
+ url: https://github.com/yes0ng
+ComicShrimp:
+ login: ComicShrimp
+ count: 18
+ avatarUrl: https://avatars.githubusercontent.com/u/43503750?u=d2fbf412e7730183ce91686ca48d4147e1b7dc74&v=4
+ url: https://github.com/ComicShrimp
+simatheone:
+ login: simatheone
+ count: 18
+ avatarUrl: https://avatars.githubusercontent.com/u/78508673?u=1b9658d9ee0bde33f56130dd52275493ddd38690&v=4
+ url: https://github.com/simatheone
+ivan-abc:
+ login: ivan-abc
+ count: 18
+ avatarUrl: https://avatars.githubusercontent.com/u/36765187?u=c6e0ba571c1ccb6db9d94e62e4b8b5eda811a870&v=4
+ url: https://github.com/ivan-abc
+Limsunoh:
+ login: Limsunoh
+ count: 18
+ avatarUrl: https://avatars.githubusercontent.com/u/90311848?u=f456e0c5709fd50c8cd2898b551558eda14e5f21&v=4
+ url: https://github.com/Limsunoh
+bezaca:
+ login: bezaca
+ count: 17
+ avatarUrl: https://avatars.githubusercontent.com/u/69092910?u=4ac58eab99bd37d663f3d23551df96d4fbdbf760&v=4
+ url: https://github.com/bezaca
+lbmendes:
+ login: lbmendes
+ count: 17
+ avatarUrl: https://avatars.githubusercontent.com/u/80999926?u=646619e2f07ac5a7c3f65fe7834197461a4fff9f&v=4
+ url: https://github.com/lbmendes
+spacesphere:
+ login: spacesphere
+ count: 17
+ avatarUrl: https://avatars.githubusercontent.com/u/34628304?u=cde91f6002dd33156e1bf8005f11a7a3ed76b790&v=4
+ url: https://github.com/spacesphere
+panko:
+ login: panko
+ count: 17
+ avatarUrl: https://avatars.githubusercontent.com/u/1569515?u=a84a5d255621ed82f8e1ca052f5f2eeb75997da2&v=4
+ url: https://github.com/panko
+jeison-araya:
+ login: jeison-araya
+ count: 17
+ avatarUrl: https://avatars.githubusercontent.com/u/57369279?u=17001e68af7d8e5b8c343e5e9df4050f419998d5&v=4
+ url: https://github.com/jeison-araya
+yanever:
+ login: yanever
+ count: 16
+ avatarUrl: https://avatars.githubusercontent.com/u/21978760?v=4
+ url: https://github.com/yanever
+mastizada:
+ login: mastizada
+ count: 16
+ avatarUrl: https://avatars.githubusercontent.com/u/1975818?u=0751a06d7271c8bf17cb73b1b845644ab4d2c6dc&v=4
+ url: https://github.com/mastizada
+Joao-Pedro-P-Holanda:
+ login: Joao-Pedro-P-Holanda
+ count: 16
+ avatarUrl: https://avatars.githubusercontent.com/u/110267046?u=331bd016326dac4cf3df4848f6db2dbbf8b5f978&v=4
+ url: https://github.com/Joao-Pedro-P-Holanda
+JaeHyuckSa:
+ login: JaeHyuckSa
+ count: 16
+ avatarUrl: https://avatars.githubusercontent.com/u/104830931?u=6e352201714a05154e5d0ccf91b4715a951c622e&v=4
+ url: https://github.com/JaeHyuckSa
+SofiiaTrufanova:
+ login: SofiiaTrufanova
+ count: 16
+ avatarUrl: https://avatars.githubusercontent.com/u/63260929?u=483e0b64fabc76343b3be39b7e1dcb930a95e1bb&v=4
+ url: https://github.com/SofiiaTrufanova
+Jedore:
+ login: Jedore
+ count: 15
+ avatarUrl: https://avatars.githubusercontent.com/u/17944025?u=81d503e1c800eb666b3861ca47a3a773bbc3f539&v=4
+ url: https://github.com/Jedore
+kim-sangah:
+ login: kim-sangah
+ count: 15
+ avatarUrl: https://avatars.githubusercontent.com/u/173775778?v=4
+ url: https://github.com/kim-sangah
+DianaTrufanova:
+ login: DianaTrufanova
+ count: 15
+ avatarUrl: https://avatars.githubusercontent.com/u/119067607?u=1cd55f841b68b4a187fa6d06a7dafa5f070195aa&v=4
+ url: https://github.com/DianaTrufanova
+PandaHun:
+ login: PandaHun
+ count: 14
+ avatarUrl: https://avatars.githubusercontent.com/u/13096845?u=646eba44db720e37d0dbe8e98e77ab534ea78a20&v=4
+ url: https://github.com/PandaHun
+dukkee:
+ login: dukkee
+ count: 14
+ avatarUrl: https://avatars.githubusercontent.com/u/36825394?u=ccfd86e6a4f2d093dad6f7544cc875af67fa2df8&v=4
+ url: https://github.com/dukkee
+BORA040126:
+ login: BORA040126
+ count: 14
+ avatarUrl: https://avatars.githubusercontent.com/u/88664069?u=98e382727a485971e04aaa7c873d9a75a17ee3be&v=4
+ url: https://github.com/BORA040126
+mattkoehne:
+ login: mattkoehne
+ count: 14
+ avatarUrl: https://avatars.githubusercontent.com/u/80362153?v=4
+ url: https://github.com/mattkoehne
+jovicon:
+ login: jovicon
+ count: 13
+ avatarUrl: https://avatars.githubusercontent.com/u/21287303?u=b049eac3e51a4c0473c2efe66b4d28a7d8f2b572&v=4
+ url: https://github.com/jovicon
+izaguerreiro:
+ login: izaguerreiro
+ count: 13
+ avatarUrl: https://avatars.githubusercontent.com/u/2241504?v=4
+ url: https://github.com/izaguerreiro
+jburckel:
+ login: jburckel
+ count: 13
+ avatarUrl: https://avatars.githubusercontent.com/u/11768758?u=044462e4130e086a0621f4abb45f0d7a289ab7fa&v=4
+ url: https://github.com/jburckel
+peidrao:
+ login: peidrao
+ count: 13
+ avatarUrl: https://avatars.githubusercontent.com/u/32584628?u=64c634bb10381905038ff7faf3c8c3df47fb799a&v=4
+ url: https://github.com/peidrao
+impocode:
+ login: impocode
+ count: 13
+ avatarUrl: https://avatars.githubusercontent.com/u/109408819?u=9cdfc5ccb31a2094c520f41b6087012fa9048982&v=4
+ url: https://github.com/impocode
+wesinalves:
+ login: wesinalves
+ count: 13
+ avatarUrl: https://avatars.githubusercontent.com/u/13563128?u=9eb17ed50645dd684bfec47e75dba4e9772ec9c1&v=4
+ url: https://github.com/wesinalves
+NastasiaSaby:
+ login: NastasiaSaby
+ count: 12
+ avatarUrl: https://avatars.githubusercontent.com/u/8245071?u=b3afd005f9e4bf080c219ef61a592b3a8004b764&v=4
+ url: https://github.com/NastasiaSaby
+oandersonmagalhaes:
+ login: oandersonmagalhaes
+ count: 12
+ avatarUrl: https://avatars.githubusercontent.com/u/83456692?v=4
+ url: https://github.com/oandersonmagalhaes
+mkdir700:
+ login: mkdir700
+ count: 12
+ avatarUrl: https://avatars.githubusercontent.com/u/56359329?u=3d6ea8714f5000829b60dcf7b13a75b1e73aaf47&v=4
+ url: https://github.com/mkdir700
+batlopes:
+ login: batlopes
+ count: 12
+ avatarUrl: https://avatars.githubusercontent.com/u/33462923?u=0fb3d7acb316764616f11e4947faf080e49ad8d9&v=4
+ url: https://github.com/batlopes
+joonas-yoon:
+ login: joonas-yoon
+ count: 12
+ avatarUrl: https://avatars.githubusercontent.com/u/9527681?u=0166d22ef4749e617c6516e79f833cd8d73f1949&v=4
+ url: https://github.com/joonas-yoon
+baseplate-admin:
+ login: baseplate-admin
+ count: 12
+ avatarUrl: https://avatars.githubusercontent.com/u/61817579?u=ce4c268fa949ae9a0290996e7949195302055812&v=4
+ url: https://github.com/baseplate-admin
+KaniKim:
+ login: KaniKim
+ count: 12
+ avatarUrl: https://avatars.githubusercontent.com/u/19832624?u=296dbdd490e0eb96e3d45a2608c065603b17dc31&v=4
+ url: https://github.com/KaniKim
+andersonrocha0:
+ login: andersonrocha0
+ count: 12
+ avatarUrl: https://avatars.githubusercontent.com/u/22346169?u=93a1359c8c5461d894802c0cc65bcd09217e7a02&v=4
+ url: https://github.com/andersonrocha0
+gitgernit:
+ login: gitgernit
+ count: 12
+ avatarUrl: https://avatars.githubusercontent.com/u/129539613?u=d04f10143ab32c93f563ea14bf242d1d2bc991b0&v=4
+ url: https://github.com/gitgernit
+kwang1215:
+ login: kwang1215
+ count: 12
+ avatarUrl: https://avatars.githubusercontent.com/u/74170199?u=2a63ff6692119dde3f5e5693365b9fcd6f977b08&v=4
+ url: https://github.com/kwang1215
+AdrianDeAnda:
+ login: AdrianDeAnda
+ count: 11
+ avatarUrl: https://avatars.githubusercontent.com/u/1024932?u=b2ea249c6b41ddf98679c8d110d0f67d4a3ebf93&v=4
+ url: https://github.com/AdrianDeAnda
+blt232018:
+ login: blt232018
+ count: 11
+ avatarUrl: https://avatars.githubusercontent.com/u/43393471?u=172b0e0391db1aa6c1706498d6dfcb003c8a4857&v=4
+ url: https://github.com/blt232018
+NinaHwang:
+ login: NinaHwang
+ count: 11
+ avatarUrl: https://avatars.githubusercontent.com/u/79563565?u=241f2cb6d38a2d379536608a8ea5a22ed4b1a3ea&v=4
+ url: https://github.com/NinaHwang
+glsglsgls:
+ login: glsglsgls
+ count: 11
+ avatarUrl: https://avatars.githubusercontent.com/u/76133879?v=4
+ url: https://github.com/glsglsgls
+k94-ishi:
+ login: k94-ishi
+ count: 11
+ avatarUrl: https://avatars.githubusercontent.com/u/32672580?u=bc7c5c07af0656be9fe4f1784a444af8d81ded89&v=4
+ url: https://github.com/k94-ishi
+codespearhead:
+ login: codespearhead
+ count: 11
+ avatarUrl: https://avatars.githubusercontent.com/u/72931357?u=0fce6b82219b604d58adb614a761556425579cb5&v=4
+ url: https://github.com/codespearhead
+emrhnsyts:
+ login: emrhnsyts
+ count: 11
+ avatarUrl: https://avatars.githubusercontent.com/u/42899027?u=ad26798e3f8feed2041c5dd5f87e58933d6c3283&v=4
+ url: https://github.com/emrhnsyts
+Lufa1u:
+ login: Lufa1u
+ count: 11
+ avatarUrl: https://avatars.githubusercontent.com/u/112495876?u=087658920ed9e74311597bdd921d8d2de939d276&v=4
+ url: https://github.com/Lufa1u
+KNChiu:
+ login: KNChiu
+ count: 11
+ avatarUrl: https://avatars.githubusercontent.com/u/36751646?v=4
+ url: https://github.com/KNChiu
+mariacamilagl:
+ login: mariacamilagl
+ count: 10
+ avatarUrl: https://avatars.githubusercontent.com/u/11489395?u=4adb6986bf3debfc2b8216ae701f2bd47d73da7d&v=4
+ url: https://github.com/mariacamilagl
+ryuckel:
+ login: ryuckel
+ count: 10
+ avatarUrl: https://avatars.githubusercontent.com/u/36391432?u=094eec0cfddd5013f76f31e55e56147d78b19553&v=4
+ url: https://github.com/ryuckel
+umitkaanusta:
+ login: umitkaanusta
+ count: 10
+ avatarUrl: https://avatars.githubusercontent.com/u/53405015?v=4
+ url: https://github.com/umitkaanusta
+kty4119:
+ login: kty4119
+ count: 10
+ avatarUrl: https://avatars.githubusercontent.com/u/49435654?v=4
+ url: https://github.com/kty4119
+RobotToI:
+ login: RobotToI
+ count: 10
+ avatarUrl: https://avatars.githubusercontent.com/u/44951382?u=e41dbc19191ce7abed86694b1a44ea0523e1c60e&v=4
+ url: https://github.com/RobotToI
+vitumenezes:
+ login: vitumenezes
+ count: 10
+ avatarUrl: https://avatars.githubusercontent.com/u/9680878?u=05fd25cfafdc09382bf8907c37293a696c205754&v=4
+ url: https://github.com/vitumenezes
+fcrozetta:
+ login: fcrozetta
+ count: 10
+ avatarUrl: https://avatars.githubusercontent.com/u/8006246?u=fa2a743e803de2c3a84d3ed8042faefed16c5e43&v=4
+ url: https://github.com/fcrozetta
+sUeharaE4:
+ login: sUeharaE4
+ count: 10
+ avatarUrl: https://avatars.githubusercontent.com/u/44468359?v=4
+ url: https://github.com/sUeharaE4
+Ernilia:
+ login: Ernilia
+ count: 10
+ avatarUrl: https://avatars.githubusercontent.com/u/125735800?u=13bfaac417a53fd5b5cf992efea363ca72598813&v=4
+ url: https://github.com/Ernilia
+socket-socket:
+ login: socket-socket
+ count: 10
+ avatarUrl: https://avatars.githubusercontent.com/u/121552599?u=104df6503242e8d762fe293e7036f7260f245d49&v=4
+ url: https://github.com/socket-socket
+nick-cjyx9:
+ login: nick-cjyx9
+ count: 10
+ avatarUrl: https://avatars.githubusercontent.com/u/119087246?u=c35aab03f082430be8a1edd80f5625b44819a0d8&v=4
+ url: https://github.com/nick-cjyx9
+waketzheng:
+ login: waketzheng
+ count: 10
+ avatarUrl: https://avatars.githubusercontent.com/u/35413830?u=df19e4fd5bb928e7d086e053ef26a46aad23bf84&v=4
+ url: https://github.com/waketzheng
+lucasbalieiro:
+ login: lucasbalieiro
+ count: 10
+ avatarUrl: https://avatars.githubusercontent.com/u/37416577?u=eabaf4aebbaa88a94a4886273edba689012cee70&v=4
+ url: https://github.com/lucasbalieiro
+RunningIkkyu:
+ login: RunningIkkyu
+ count: 9
+ avatarUrl: https://avatars.githubusercontent.com/u/31848542?u=494ecc298e3f26197495bb357ad0f57cfd5f7a32&v=4
+ url: https://github.com/RunningIkkyu
+JulianMaurin:
+ login: JulianMaurin
+ count: 9
+ avatarUrl: https://avatars.githubusercontent.com/u/63545168?u=b7d15ac865268cbefc2d739e2f23d9aeeac1a622&v=4
+ url: https://github.com/JulianMaurin
+JeongHyeongKim:
+ login: JeongHyeongKim
+ count: 9
+ avatarUrl: https://avatars.githubusercontent.com/u/26577800?u=77f060f4686f32c248907b81b16ee2b3177ca44c&v=4
+ url: https://github.com/JeongHyeongKim
+arthurio:
+ login: arthurio
+ count: 9
+ avatarUrl: https://avatars.githubusercontent.com/u/950449?u=76b997138273ce5e1990b971c4f27c9aff979fd5&v=4
+ url: https://github.com/arthurio
+Lenclove:
+ login: Lenclove
+ count: 9
+ avatarUrl: https://avatars.githubusercontent.com/u/32355298?u=d0065e01650c63c2b2413f42d983634b2ea85481&v=4
+ url: https://github.com/Lenclove
+eVery1337:
+ login: eVery1337
+ count: 9
+ avatarUrl: https://avatars.githubusercontent.com/u/84917945?u=7af243f05ecfba59191199a70d8ba365c1327768&v=4
+ url: https://github.com/eVery1337
+aykhans:
+ login: aykhans
+ count: 9
+ avatarUrl: https://avatars.githubusercontent.com/u/88669260?u=798da457cc3276d3c6dd7fd628d0005ad8b298cc&v=4
+ url: https://github.com/aykhans
+riroan:
+ login: riroan
+ count: 9
+ avatarUrl: https://avatars.githubusercontent.com/u/33053284?u=2d18e3771506ee874b66d6aa2b3b1107fd95c38f&v=4
+ url: https://github.com/riroan
+MinLee0210:
+ login: MinLee0210
+ count: 9
+ avatarUrl: https://avatars.githubusercontent.com/u/57653278?u=3c4b6e9d69bff148d09fe022ddf867e564acaa44&v=4
+ url: https://github.com/MinLee0210
+yodai-yodai:
+ login: yodai-yodai
+ count: 9
+ avatarUrl: https://avatars.githubusercontent.com/u/7031039?u=4f3593f5931892b931a745cfab846eff6e9332e7&v=4
+ url: https://github.com/yodai-yodai
+marcelomarkus:
+ login: marcelomarkus
+ count: 9
+ avatarUrl: https://avatars.githubusercontent.com/u/20115018?u=dda090ce9160ef0cd2ff69b1e5ea741283425cba&v=4
+ url: https://github.com/marcelomarkus
+JoaoGustavoRogel:
+ login: JoaoGustavoRogel
+ count: 9
+ avatarUrl: https://avatars.githubusercontent.com/u/29525510?u=a0a91251f5e43e132608d55d28ccb8645c5ea405&v=4
+ url: https://github.com/JoaoGustavoRogel
+Zhongheng-Cheng:
+ login: Zhongheng-Cheng
+ count: 9
+ avatarUrl: https://avatars.githubusercontent.com/u/95612344?u=a0f7730a3cc7486827965e01a119ad610bda4b0a&v=4
+ url: https://github.com/Zhongheng-Cheng
+Yarous:
+ login: Yarous
+ count: 9
+ avatarUrl: https://avatars.githubusercontent.com/u/61277193?u=5b462347458a373b2d599c6f416d2b75eddbffad&v=4
+ url: https://github.com/Yarous
+dimaqq:
+ login: dimaqq
+ count: 8
+ avatarUrl: https://avatars.githubusercontent.com/u/662249?u=15313dec91bae789685e4abb3c2152251de41948&v=4
+ url: https://github.com/dimaqq
+julianofischer:
+ login: julianofischer
+ count: 8
+ avatarUrl: https://avatars.githubusercontent.com/u/158303?u=d91662eb949d4cc7368831cf37a5cdfd90b7010c&v=4
+ url: https://github.com/julianofischer
+bnzone:
+ login: bnzone
+ count: 8
+ avatarUrl: https://avatars.githubusercontent.com/u/39371503?u=c16f00c41d88479fa2d57b0d7d233b758eacce2d&v=4
+ url: https://github.com/bnzone
+shamosishen:
+ login: shamosishen
+ count: 8
+ avatarUrl: https://avatars.githubusercontent.com/u/9498321?u=c83c20c79e019a0b555a125adf20fc4fb7a882c8&v=4
+ url: https://github.com/shamosishen
+mertssmnoglu:
+ login: mertssmnoglu
+ count: 8
+ avatarUrl: https://avatars.githubusercontent.com/u/61623638?u=59dd885b68ff1832f9ab3b4a4446896358c23442&v=4
+ url: https://github.com/mertssmnoglu
+mahone3297:
+ login: mahone3297
+ count: 8
+ avatarUrl: https://avatars.githubusercontent.com/u/1701379?u=20588ff0e456d13e8017333eb237595d11410234&v=4
+ url: https://github.com/mahone3297
+KimJoonSeo:
+ login: KimJoonSeo
+ count: 8
+ avatarUrl: https://avatars.githubusercontent.com/u/17760162?u=a58cdc77ae1c069a64166f7ecc4d42eecfd9a468&v=4
+ url: https://github.com/KimJoonSeo
+camigomezdev:
+ login: camigomezdev
+ count: 8
+ avatarUrl: https://avatars.githubusercontent.com/u/16061815?u=25b5ebc042fff53fa03dc107ded10e36b1b7a5b9&v=4
+ url: https://github.com/camigomezdev
+maru0123-2004:
+ login: maru0123-2004
+ count: 8
+ avatarUrl: https://avatars.githubusercontent.com/u/43961566?u=16ed8603a4d6a4665cb6c53a7aece6f31379b769&v=4
+ url: https://github.com/maru0123-2004
+minaton-ru:
+ login: minaton-ru
+ count: 8
+ avatarUrl: https://avatars.githubusercontent.com/u/53541518?u=67336ca11a85493f75031508aade588dad3b9910&v=4
+ url: https://github.com/minaton-ru
+sungchan1:
+ login: sungchan1
+ count: 8
+ avatarUrl: https://avatars.githubusercontent.com/u/28076127?u=a816d86ef3e60450a7225f128caf9a394c9320f9&v=4
+ url: https://github.com/sungchan1
+Serrones:
+ login: Serrones
+ count: 7
+ avatarUrl: https://avatars.githubusercontent.com/u/22691749?u=4795b880e13ca33a73e52fc0ef7dc9c60c8fce47&v=4
+ url: https://github.com/Serrones
+israteneda:
+ login: israteneda
+ count: 7
+ avatarUrl: https://avatars.githubusercontent.com/u/20668624?u=67574648f89019d1c73b16a6a009da659557f9e5&v=4
+ url: https://github.com/israteneda
+krocdort:
+ login: krocdort
+ count: 7
+ avatarUrl: https://avatars.githubusercontent.com/u/34248814?v=4
+ url: https://github.com/krocdort
+anthonycepeda:
+ login: anthonycepeda
+ count: 7
+ avatarUrl: https://avatars.githubusercontent.com/u/72019805?u=60bdf46240cff8fca482ff0fc07d963fd5e1a27c&v=4
+ url: https://github.com/anthonycepeda
+fabioueno:
+ login: fabioueno
+ count: 7
+ avatarUrl: https://avatars.githubusercontent.com/u/14273852?u=edd700982b16317ac6ebfd24c47bc0029b21d360&v=4
+ url: https://github.com/fabioueno
+cfraboulet:
+ login: cfraboulet
+ count: 7
+ avatarUrl: https://avatars.githubusercontent.com/u/62244267?u=ed0e286ba48fa1dafd64a08e50f3364b8e12df34&v=4
+ url: https://github.com/cfraboulet
+HiemalBeryl:
+ login: HiemalBeryl
+ count: 7
+ avatarUrl: https://avatars.githubusercontent.com/u/63165207?u=276f4af2829baf28b912c718675852bfccb0e7b4&v=4
+ url: https://github.com/HiemalBeryl
+pablocm83:
+ login: pablocm83
+ count: 7
+ avatarUrl: https://avatars.githubusercontent.com/u/28315068?u=3310fbb05bb8bfc50d2c48b6cb64ac9ee4a14549&v=4
+ url: https://github.com/pablocm83
+d2a-raudenaerde:
+ login: d2a-raudenaerde
+ count: 7
+ avatarUrl: https://avatars.githubusercontent.com/u/5213150?v=4
+ url: https://github.com/d2a-raudenaerde
+Zerohertz:
+ login: Zerohertz
+ count: 7
+ avatarUrl: https://avatars.githubusercontent.com/u/42334717?u=5ebf4d33e73b1ad373154f6cdee44f7cab4d05ba&v=4
+ url: https://github.com/Zerohertz
+deniscapeto:
+ login: deniscapeto
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/12864353?u=dbc20c5c1171feab5df4db46488b675d53cb5b07&v=4
+ url: https://github.com/deniscapeto
+bsab:
+ login: bsab
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/9799799?u=c4a09b1abb794cd8280c4793d43d0e2eb963ecda&v=4
+ url: https://github.com/bsab
+ArcLightSlavik:
+ login: ArcLightSlavik
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/31127044?u=b0f2c37142f4b762e41ad65dc49581813422bd71&v=4
+ url: https://github.com/ArcLightSlavik
+Cajuteq:
+ login: Cajuteq
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/26676532?u=8ee0422981810e51480855de1c0d67b6b79cd3f2&v=4
+ url: https://github.com/Cajuteq
+emmrichard:
+ login: emmrichard
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/1328018?u=8114d8fc0e8e42a092e4283013a1c54b792c466b&v=4
+ url: https://github.com/emmrichard
+wakabame:
+ login: wakabame
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/35513518?u=41ef6b0a55076e5c540620d68fb006e386c2ddb0&v=4
+ url: https://github.com/wakabame
+mawassk:
+ login: mawassk
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/84179197?v=4
+ url: https://github.com/mawassk
+diogoduartec:
+ login: diogoduartec
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/31852339?u=7514a5f05fcbeccc62f8c5dc25879efeb1ef9335&v=4
+ url: https://github.com/diogoduartec
+aqcool:
+ login: aqcool
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/52229895?v=4
+ url: https://github.com/aqcool
+'1320555911':
+ login: '1320555911'
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/58590086?u=6d8f4fbf08d5ac72c1c895892c461c5e0b013dc3&v=4
+ url: https://github.com/1320555911
+mcthesw:
+ login: mcthesw
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/61224072?u=82a1b106298348f060c3f4f39817e0cae5ce2b7c&v=4
+ url: https://github.com/mcthesw
+xzmeng:
+ login: xzmeng
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/40202897?v=4
+ url: https://github.com/xzmeng
+negadive:
+ login: negadive
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/47322392?u=c1be2e9b9b346b4a77d9157da2a5739ab25ce0f8&v=4
+ url: https://github.com/negadive
+mbroton:
+ login: mbroton
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/50829834?u=a48610bf1bffaa9c75d03228926e2eb08a2e24ee&v=4
+ url: https://github.com/mbroton
+Kirilex:
+ login: Kirilex
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/100281552?v=4
+ url: https://github.com/Kirilex
+arunppsg:
+ login: arunppsg
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/26398753?v=4
+ url: https://github.com/arunppsg
+dimastbk:
+ login: dimastbk
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/3132181?u=66587398d43466a1dc75c238df5f048e0afc77ed&v=4
+ url: https://github.com/dimastbk
+dudyaosuplayer:
+ login: dudyaosuplayer
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/62661898?u=7864cc5f01b1c845ae8ad49acf45dec6faca0c57&v=4
+ url: https://github.com/dudyaosuplayer
+talhaumer:
+ login: talhaumer
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/46643702?u=5d1fd7057ea9534fb3221931b809a3d750157212&v=4
+ url: https://github.com/talhaumer
+bankofsardine:
+ login: bankofsardine
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/44944207?u=0368e1b698ffab6bf29e202f9fd2dddd352429f1&v=4
+ url: https://github.com/bankofsardine
+valentinDruzhinin:
+ login: valentinDruzhinin
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/12831905?u=aae1ebc675c91e8fa582df4fcc4fc4128106344d&v=4
+ url: https://github.com/valentinDruzhinin
+rsip22:
+ login: rsip22
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/16676222?v=4
+ url: https://github.com/rsip22
+jessicapaz:
+ login: jessicapaz
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/20428941?u=6ffdaab5a85bf77a2d8870dade5e53555f34577b&v=4
+ url: https://github.com/jessicapaz
+mohsen-mahmoodi:
+ login: mohsen-mahmoodi
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/2872586?u=3a9fc1aa16a3a0ab93a1f8550de82a940592857d&v=4
+ url: https://github.com/mohsen-mahmoodi
+jeesang7:
+ login: jeesang7
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/30719956?u=35fc8bca04d32d3c4ce085956f0636b959ba30f6&v=4
+ url: https://github.com/jeesang7
+TemaSpb:
+ login: TemaSpb
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/20205738?u=d7dce0718720a7107803a573d628d8dd3d5c2fb4&v=4
+ url: https://github.com/TemaSpb
+BugLight:
+ login: BugLight
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/13618366?u=7d733749f80e5f7e66a434cf42aedcfc60340f43&v=4
+ url: https://github.com/BugLight
+0x4Dark:
+ login: 0x4Dark
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/7569289?v=4
+ url: https://github.com/0x4Dark
+Wuerike:
+ login: Wuerike
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/35462243?u=80c753dedf4a78db12ef66316dbdebbe6d84a2b9&v=4
+ url: https://github.com/Wuerike
+jvmazagao:
+ login: jvmazagao
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/22477816?u=2b57addf5830906bf6ae5f25cd4c8c2fa5c2d68e&v=4
+ url: https://github.com/jvmazagao
+cun3yt:
+ login: cun3yt
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/24409240?u=06abfd77786db859b0602d5369d2ae18c932c17c&v=4
+ url: https://github.com/cun3yt
+Mordson:
+ login: Mordson
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/39025897?u=b94ea96ef35bbe43bc85359cfb31d28ac16d470c&v=4
+ url: https://github.com/Mordson
+aminkhani:
+ login: aminkhani
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/51851950?u=051896c4933816bc61d11091d887f6e8dfd1d27b&v=4
+ url: https://github.com/aminkhani
+nifadyev:
+ login: nifadyev
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/36514612?u=e101da8641d5a09901d2155255a93f8ab3d9c468&v=4
+ url: https://github.com/nifadyev
+LaurEars:
+ login: LaurEars
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/4914725?v=4
+ url: https://github.com/LaurEars
+Chushine:
+ login: Chushine
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/135534400?v=4
+ url: https://github.com/Chushine
+ChuyuChoyeon:
+ login: ChuyuChoyeon
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/129537877?u=f0c76f3327817a8b86b422d62e04a34bf2827f2b&v=4
+ url: https://github.com/ChuyuChoyeon
+frwl404:
+ login: frwl404
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/42642656?u=572a5a33762e07eaa6ebd58d9d773abdb1de41c3&v=4
+ url: https://github.com/frwl404
+esrefzeki:
+ login: esrefzeki
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/54935247?u=193cf5a169ca05fc54995a4dceabc82c7dc6e5ea&v=4
+ url: https://github.com/esrefzeki
+dtleal:
+ login: dtleal
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/31096951?v=4
+ url: https://github.com/dtleal
+art3xa:
+ login: art3xa
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/92092049?v=4
+ url: https://github.com/art3xa
+SamuelBFavarin:
+ login: SamuelBFavarin
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/17628602?u=5aac13ae492fa9a86e397a70803ac723dba2efe7&v=4
+ url: https://github.com/SamuelBFavarin
+takacs:
+ login: takacs
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/44911031?u=f6c6b70b3ba86ceb93b0f9bcab609bf9328b2305&v=4
+ url: https://github.com/takacs
+anton2yakovlev:
+ login: anton2yakovlev
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/44229180?u=bdd445ba99074b378e7298d23c4bf6d707d2c282&v=4
+ url: https://github.com/anton2yakovlev
+ILoveSorasakiHina:
+ login: ILoveSorasakiHina
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/114038930?u=3d3ed8dc3bf57e641d1b26badee5bc79ef34f25b&v=4
+ url: https://github.com/ILoveSorasakiHina
+devluisrodrigues:
+ login: devluisrodrigues
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/103431660?u=d9674a3249edc4601d2c712cdebf899918503c3a&v=4
+ url: https://github.com/devluisrodrigues
+11kkw:
+ login: 11kkw
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/21125286?v=4
+ url: https://github.com/11kkw
+lpdswing:
+ login: lpdswing
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/20874036?u=7a4fc3e4d0719e37b305deb7af234a7b63200787&v=4
+ url: https://github.com/lpdswing
+SepehrRasouli:
+ login: SepehrRasouli
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/81516241?u=3987e880c77d653dd85963302150e07bb7c0ef99&v=4
+ url: https://github.com/SepehrRasouli
+Zxilly:
+ login: Zxilly
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/31370133?u=c5359b8d9d80a7cdc23d5295d179ed90174996c8&v=4
+ url: https://github.com/Zxilly
+eavv:
+ login: eavv
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/18273429?u=c05e8b4ea62810ee7889ca049e510cdd0a66fd26&v=4
+ url: https://github.com/eavv
+AlexandreBiguet:
+ login: AlexandreBiguet
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/1483079?u=ff926455cd4cab03c6c49441aa5dc2b21df3e266&v=4
+ url: https://github.com/AlexandreBiguet
+FelipeSilva93:
+ login: FelipeSilva93
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/66804965?u=e7cb4b580e46f2e04ecb4cd4d7a12acdddd3c6c1&v=4
+ url: https://github.com/FelipeSilva93
+peacekimjapan:
+ login: peacekimjapan
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/33534175?u=e4219bcebc3773a7068cc34c3eb268ef77cec31b&v=4
+ url: https://github.com/peacekimjapan
+bas-baskara:
+ login: bas-baskara
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/41407847?u=cdabfaff7481c3323f24a76d9350393b964f2b89&v=4
+ url: https://github.com/bas-baskara
+odiseo0:
+ login: odiseo0
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/87550035?u=241a71f6b7068738b81af3e57f45ffd723538401&v=4
+ url: https://github.com/odiseo0
+eryknn:
+ login: eryknn
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/87120651?v=4
+ url: https://github.com/eryknn
+personage-hub:
+ login: personage-hub
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/76659786?v=4
+ url: https://github.com/personage-hub
+aminalaee:
+ login: aminalaee
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/19784933?v=4
+ url: https://github.com/aminalaee
+erfan-rfmhr:
+ login: erfan-rfmhr
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/98986056?u=0acda1ff1df0989f3f3eb79977baa35da4cb6c8c&v=4
+ url: https://github.com/erfan-rfmhr
+Scorpionchiques:
+ login: Scorpionchiques
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/15703294?v=4
+ url: https://github.com/Scorpionchiques
+lordqyxz:
+ login: lordqyxz
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/31722468?u=974553c0ba53526d9be7e9876544283291be3b0d&v=4
+ url: https://github.com/lordqyxz
+heysaeid:
+ login: heysaeid
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/63112273?u=5397ead391319a147a18b70cc04d1a334f235ef3&v=4
+ url: https://github.com/heysaeid
+Yois4101:
+ login: Yois4101
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/119609381?v=4
+ url: https://github.com/Yois4101
+tamtam-fitness:
+ login: tamtam-fitness
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/62091034?u=8da19a6bd3d02f5d6ba30c7247d5b46c98dd1403&v=4
+ url: https://github.com/tamtam-fitness
+mpmeleshko:
+ login: mpmeleshko
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/34425664?v=4
+ url: https://github.com/mpmeleshko
+SonnyYou:
+ login: SonnyYou
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/18657569?v=4
+ url: https://github.com/SonnyYou
+matiasbertani:
+ login: matiasbertani
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/65260383?u=d5edd86a6e2ab4fb1aab7751931fe045a963afd7&v=4
+ url: https://github.com/matiasbertani
+thiennc254:
+ login: thiennc254
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/97406628?u=1b2860679694b9a552764d0fa81dbd7a016322ec&v=4
+ url: https://github.com/thiennc254
+javillegasna:
+ login: javillegasna
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/38879192?u=df9ab0d628f8c1f1c849db7b3c0939337f42c3f1&v=4
+ url: https://github.com/javillegasna
+9zimin9:
+ login: 9zimin9
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/174453744?v=4
+ url: https://github.com/9zimin9
+ilhamfadillah:
+ login: ilhamfadillah
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/20577838?u=c56192cf99b55affcaad408b240259c62e633450&v=4
+ url: https://github.com/ilhamfadillah
+gerry-sabar:
+ login: gerry-sabar
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/1120123?v=4
+ url: https://github.com/gerry-sabar
+cookie-byte217:
+ login: cookie-byte217
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/57880178?v=4
+ url: https://github.com/cookie-byte217
+tyronedamasceno:
+ login: tyronedamasceno
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/12273721?u=913bca6bab96d9416ad8c9874c80de0833782050&v=4
+ url: https://github.com/tyronedamasceno
+LikoIlya:
+ login: LikoIlya
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/15039930?v=4
+ url: https://github.com/LikoIlya
+ss-o-furda:
+ login: ss-o-furda
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/56111536?u=d2326baa464a3778c280ed85fd14c00f87eb1080&v=4
+ url: https://github.com/ss-o-furda
+Frans06:
+ login: Frans06
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/5842109?u=77529d5517ae80438249b1a45f2d59372a31a212&v=4
+ url: https://github.com/Frans06
+Jefidev:
+ login: Jefidev
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/9964497?u=1da6eee587a8b425ca4afbfdfc6c3a639fe85d02&v=4
+ url: https://github.com/Jefidev
+Xaraxx:
+ login: Xaraxx
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/29824698?u=dde2e233e22bb5ca1f8bb0c6e353ccd0d06e6066&v=4
+ url: https://github.com/Xaraxx
+Suyoung789:
+ login: Suyoung789
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/31277231?u=744bd3e641413e19bfad6b06a90bb0887c3f9332&v=4
+ url: https://github.com/Suyoung789
+akagaeng:
+ login: akagaeng
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/17076841?u=9ada2eb6a33dc705ba96d58f802c787dea3859b8&v=4
+ url: https://github.com/akagaeng
+phamquanganh31101998:
+ login: phamquanganh31101998
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/43257497?u=36fa4ee689415d869a98453083a7c4213d2136ee&v=4
+ url: https://github.com/phamquanganh31101998
+peebbv6364:
+ login: peebbv6364
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/26784747?u=75583df215ee01a5cd2dc646aecb81e7dbd33d06&v=4
+ url: https://github.com/peebbv6364
+mrparalon:
+ login: mrparalon
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/19637629?u=6339508ceb665717cae862a4d33816ac874cbb8f&v=4
+ url: https://github.com/mrparalon
+creyD:
+ login: creyD
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/15138480?u=51cd2873cd93807beb578af8e23975856fdbc945&v=4
+ url: https://github.com/creyD
+zhoonit:
+ login: zhoonit
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/17230883?u=698cb26dcce4770374b592aad3b7489e91c07fc6&v=4
+ url: https://github.com/zhoonit
+Sefank:
+ login: Sefank
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/12670778?u=ca16995c68a82cabc7435c54ac0564930f62dd59&v=4
+ url: https://github.com/Sefank
+RuslanTer:
+ login: RuslanTer
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/48125303?v=4
+ url: https://github.com/RuslanTer
+FedorGN:
+ login: FedorGN
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/66411909?u=22382380e7d66ee57ffbfc2ae6bd5efd0cdb672e&v=4
+ url: https://github.com/FedorGN
+rafsaf:
+ login: rafsaf
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/51059348?u=5fe59a56e1f2f9ccd8005d71752a8276f133ae1a&v=4
+ url: https://github.com/rafsaf
+frnsimoes:
+ login: frnsimoes
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/66239468?u=a405e8f10654251e239a4a1d9dd5bda59216727d&v=4
+ url: https://github.com/frnsimoes
+lieryan:
+ login: lieryan
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/1006989?v=4
+ url: https://github.com/lieryan
+ValeryVal:
+ login: ValeryVal
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/85856176?v=4
+ url: https://github.com/ValeryVal
+chesstrian:
+ login: chesstrian
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/3923412?u=8ea9bea6cfb5e6c64dc81be65ac2a9aaf23c5d47&v=4
+ url: https://github.com/chesstrian
+PabloEmidio:
+ login: PabloEmidio
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/69937719?u=f4d04cb78da68bb93a641f0b793ff665162e712a&v=4
+ url: https://github.com/PabloEmidio
+PraveenNanda124:
+ login: PraveenNanda124
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/116082827?u=b40c4f23c191692e88f676dc3bf33fc7f315edd4&v=4
+ url: https://github.com/PraveenNanda124
+guites:
+ login: guites
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/71985299?u=5dab5eb82b0a67fe709fc893f47a423df4de5d46&v=4
+ url: https://github.com/guites
+Junhyung21:
+ login: Junhyung21
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/138214497?u=66377988eaad4f57004decb183f396560407a73f&v=4
+ url: https://github.com/Junhyung21
+rinaatt:
+ login: rinaatt
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/6111202?u=9f62ebd2a72879db54d0b51c07c1d1e7203a4813&v=4
+ url: https://github.com/rinaatt
+Slijeff:
+ login: Slijeff
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/31459252?u=083776331690bbcf427766071e33ac28bb8d271d&v=4
+ url: https://github.com/Slijeff
+GeorchW:
+ login: GeorchW
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/8687777?u=ae4160f1d88f32692760003f3be9b5fc40a6e00d&v=4
+ url: https://github.com/GeorchW
+Vlad0395:
+ login: Vlad0395
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/37487589?u=57dc6660b9904cc0bc59b73569bbfb1ac871a4a1&v=4
+ url: https://github.com/Vlad0395
+bisibuka:
+ login: bisibuka
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/221887?v=4
+ url: https://github.com/bisibuka
+aimasheraz1:
+ login: aimasheraz1
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/132935019?v=4
+ url: https://github.com/aimasheraz1
+whysage:
+ login: whysage
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/67018871?u=a05d63a1b315dcf56a4c0dda3c0ca84ce3d6c87f&v=4
+ url: https://github.com/whysage
+Chake9928:
+ login: Chake9928
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/62596047?u=7aa2c0aad46911934ce3d22f83a895d05fa54e09&v=4
+ url: https://github.com/Chake9928
+qaerial:
+ login: qaerial
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/41595550?v=4
+ url: https://github.com/qaerial
+bluefish6:
+ login: bluefish6
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/3324881?u=d107f6d0017927191644829fb845a8ceb8ac20ee&v=4
+ url: https://github.com/bluefish6
+Sion99:
+ login: Sion99
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/82511301?v=4
+ url: https://github.com/Sion99
+EpsilonRationes:
+ login: EpsilonRationes
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/148639079?v=4
+ url: https://github.com/EpsilonRationes
+SametEmin:
+ login: SametEmin
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/115692383?u=bda9052f698e50b0df6657fb9436d07e8496fe2f&v=4
+ url: https://github.com/SametEmin
+fhabers21:
+ login: fhabers21
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/58401847?v=4
+ url: https://github.com/fhabers21
+kohiry:
+ login: kohiry
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/57669492?u=f6ab0a062740261e882879269a41a47788c84043&v=4
+ url: https://github.com/kohiry
+ptt3199:
+ login: ptt3199
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/51350651?u=2c3d947a80283e32bf616d4c3af139a6be69680f&v=4
+ url: https://github.com/ptt3199
+arynoot:
+ login: arynoot
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/73756088?v=4
+ url: https://github.com/arynoot
+GDemay:
+ login: GDemay
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/7033942?u=bbdcb4e2a67df4ec9caa2440362d8cebc44d65e8&v=4
+ url: https://github.com/GDemay
+maxscheijen:
+ login: maxscheijen
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/47034840?u=eb98f37882528ea349ca4e5255fa64ac3fef0294&v=4
+ url: https://github.com/maxscheijen
+celestywang:
+ login: celestywang
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/184830753?v=4
+ url: https://github.com/celestywang
+RyaWcksn:
+ login: RyaWcksn
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/42831964?u=0cb4265faf3e3425a89e59b6fddd3eb2de180af0&v=4
+ url: https://github.com/RyaWcksn
+tienduong-21:
+ login: tienduong-21
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/80129618?v=4
+ url: https://github.com/tienduong-21
+soroushgh1:
+ login: soroushgh1
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/178516095?u=5e26f6a5f66cdb32d7b56e6ab362bf18ba7858b9&v=4
+ url: https://github.com/soroushgh1
+zbellos:
+ login: zbellos
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/204500646?v=4
+ url: https://github.com/zbellos
+blaisep:
+ login: blaisep
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/254456?u=97d584b7c0a6faf583aa59975df4f993f671d121&v=4
+ url: https://github.com/blaisep
+SirTelemak:
+ login: SirTelemak
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/9435877?u=719327b7d2c4c62212456d771bfa7c6b8dbb9eac&v=4
+ url: https://github.com/SirTelemak
+ovezovs:
+ login: ovezovs
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/44060682?u=9cb4d738b15e64157cb65afbe2e31bd0c8f3f6e6&v=4
+ url: https://github.com/ovezovs
+neatek:
+ login: neatek
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/3075678?u=3001e778e4aa0bf6d3142d09f0b9d13b2c55066f&v=4
+ url: https://github.com/neatek
+sprytnyk:
+ login: sprytnyk
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/16718258?u=4893ea96bfebfbdbde8abd9e06851eca12b01bc9&v=4
+ url: https://github.com/sprytnyk
+wfpinedar:
+ login: wfpinedar
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/5309214?u=4af7b6b3907b015699a9994d0808137dd68f7658&v=4
+ url: https://github.com/wfpinedar
+italopenaforte:
+ login: italopenaforte
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/7786881?u=e64a8f24b1ba95eb82f283be8ab90892e40c5465&v=4
+ url: https://github.com/italopenaforte
+hackerneocom:
+ login: hackerneocom
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/67042948?u=ca365045bd261cec5a64059aa23cf80065148c3c&v=4
+ url: https://github.com/hackerneocom
+dmas-at-wiris:
+ login: dmas-at-wiris
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/24917162?u=0df147936a375b4b64232c650de31a227a6b59a0&v=4
+ url: https://github.com/dmas-at-wiris
+TorhamDev:
+ login: TorhamDev
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/87639984?u=07e5429fbd9c5d63c5ca55a0f31ef541216f0ce6&v=4
+ url: https://github.com/TorhamDev
+jaystone776:
+ login: jaystone776
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/11191137?u=299205a95e9b6817a43144a48b643346a5aac5cc&v=4
+ url: https://github.com/jaystone776
+AaronDewes:
+ login: AaronDewes
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/67546953?v=4
+ url: https://github.com/AaronDewes
+kunansy:
+ login: kunansy
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/20476946?u=d8321cd00787d5ee29bfdd8ff6fde23ad783a581&v=4
+ url: https://github.com/kunansy
+TimorChow:
+ login: TimorChow
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/18365403?u=bcbb357be0a447bc682a161932eab5032cede4af&v=4
+ url: https://github.com/TimorChow
+ataberkciftlikli:
+ login: ataberkciftlikli
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/64265169?u=ca7c1348242559f70bc1dc027a4be277c464676f&v=4
+ url: https://github.com/ataberkciftlikli
+leandrodesouzadev:
+ login: leandrodesouzadev
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/85115541?u=4eb25f43f1fe23727d61e986cf83b73b86e2a95a&v=4
+ url: https://github.com/leandrodesouzadev
+dutkiewicz:
+ login: dutkiewicz
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/6649846?u=e941be6e1ab2ffdf41cea227a73f0ffbef20628f&v=4
+ url: https://github.com/dutkiewicz
+mirusu400:
+ login: mirusu400
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/25397908?u=deda776115e4ee6f76fa526bb5127bd1a6c4b231&v=4
+ url: https://github.com/mirusu400
+its0x08:
+ login: its0x08
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/15280042?u=d7c2058f29d4e8fbdae09b194e04c5e410350211&v=4
+ url: https://github.com/its0x08
+lindsayzhou:
+ login: lindsayzhou
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/23748021?u=4db169ce262b69aa7292f82b785436544f69fb88&v=4
+ url: https://github.com/lindsayzhou
+0xflotus:
+ login: 0xflotus
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/26602940?u=3c52ce6393bb547c97e6380ccdee03e0c64152c6&v=4
+ url: https://github.com/0xflotus
+jonatasoli:
+ login: jonatasoli
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/26334101?u=f601c3f111f2148bd9244c2cb3ebbd57b592e674&v=4
+ url: https://github.com/jonatasoli
+tyzh-dev:
+ login: tyzh-dev
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/51972581?u=ba3882da7c009918a8e2d6b9ead31c89f09c922d&v=4
+ url: https://github.com/tyzh-dev
+yurkevich-dev:
+ login: yurkevich-dev
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/45145188?u=db2de8c186073d95693279dcf085fcebffab57d0&v=4
+ url: https://github.com/yurkevich-dev
+emp7yhead:
+ login: emp7yhead
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/20521260?u=9494c74cb9e1601d734b1f2726e292e257777d98&v=4
+ url: https://github.com/emp7yhead
+BartoszCki:
+ login: BartoszCki
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/17833351?u=40025e1182c32a9664834baec268dadad127703d&v=4
+ url: https://github.com/BartoszCki
+hakancelikdev:
+ login: hakancelikdev
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/19157033?u=095ea8e0af1de642edd92e5f806c70359e00c977&v=4
+ url: https://github.com/hakancelikdev
+KaterinaSolovyeva:
+ login: KaterinaSolovyeva
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/85114725?u=1fe81463cb6b1fd01ac047172fa4895e2a3cecaa&v=4
+ url: https://github.com/KaterinaSolovyeva
+zhanymkanov:
+ login: zhanymkanov
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/22341602?u=aa1c47285a4f5692d165ccb2a441c5553f23ef83&v=4
+ url: https://github.com/zhanymkanov
+felipebpl:
+ login: felipebpl
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/62957465?u=3c05f0f358b9575503c03122daefb115b6ac1414&v=4
+ url: https://github.com/felipebpl
+iudeen:
+ login: iudeen
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/10519440?u=f09cdd745e5bf16138f29b42732dd57c7f02bee1&v=4
+ url: https://github.com/iudeen
+dwisulfahnur:
+ login: dwisulfahnur
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/12431528?v=4
+ url: https://github.com/dwisulfahnur
+ayr-ton:
+ login: ayr-ton
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/1090517?u=5cf70a0e0f0dbf084e074e494aa94d7c91a46ba6&v=4
+ url: https://github.com/ayr-ton
+raphaelauv:
+ login: raphaelauv
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/10202690?u=e6f86f5c0c3026a15d6b51792fa3e532b12f1371&v=4
+ url: https://github.com/raphaelauv
+Fahad-Md-Kamal:
+ login: Fahad-Md-Kamal
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/34704464?u=f96c6cbd25b06274e3ff96bc961ca91b3f876481&v=4
+ url: https://github.com/Fahad-Md-Kamal
+zxcq544:
+ login: zxcq544
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/5781268?u=25959ea03803742c3b28220b27fc07923a491dcb&v=4
+ url: https://github.com/zxcq544
+AlexandrMaltsevYDX:
+ login: AlexandrMaltsevYDX
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/109986802?u=ed275d72bfcdb4d15abdd54e7be026adbb9ca098&v=4
+ url: https://github.com/AlexandrMaltsevYDX
+realFranco:
+ login: realFranco
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/45880759?u=22fea3007d3e2d4c8c82d6ccfbde71454c4c6dd8&v=4
+ url: https://github.com/realFranco
+piaria:
+ login: piaria
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/110835535?u=5af3d56254faa05bbca4258a46c5723489480f90&v=4
+ url: https://github.com/piaria
+mojtabapaso:
+ login: mojtabapaso
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/121169359?u=ced1d5ad673bcd9e949ebf967a4ab50185637443&v=4
+ url: https://github.com/mojtabapaso
+eghbalpoorMH:
+ login: eghbalpoorMH
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/36267498?v=4
+ url: https://github.com/eghbalpoorMH
+Tiazen:
+ login: Tiazen
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/16170159?u=0ce5e32f76e3f10733c8f25d97db9e31b753838c&v=4
+ url: https://github.com/Tiazen
+jfunez:
+ login: jfunez
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/805749?v=4
+ url: https://github.com/jfunez
+s-rigaud:
+ login: s-rigaud
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/46346622?u=eee0adaa9fdff9e312d52526fbd4020dd6860c27&v=4
+ url: https://github.com/s-rigaud
+Artem4es:
+ login: Artem4es
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/110793967?u=0f9d4e80e055adc1aa8b548e951f6b4989fa2e78&v=4
+ url: https://github.com/Artem4es
+sulemanhelp:
+ login: sulemanhelp
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/22400366?u=3e8e68750655c7f5b2e0ba1d54f5779ee526707d&v=4
+ url: https://github.com/sulemanhelp
+theRealNonso:
+ login: theRealNonso
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/29557286?u=6f062680edccfeb4c802daf3b1d8b2a9e21ae013&v=4
+ url: https://github.com/theRealNonso
+AhsanSheraz:
+ login: AhsanSheraz
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/51913596?u=08e31cacb3048be30722c94010ddd028f3fdbec4&v=4
+ url: https://github.com/AhsanSheraz
+HealerNguyen:
+ login: HealerNguyen
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/29653304?u=6ab095689054c63b1f4ceb26dd66847450225c87&v=4
+ url: https://github.com/HealerNguyen
+isulim:
+ login: isulim
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/30448496?u=44c47838defa48a16606b895dce08890fca8482f&v=4
+ url: https://github.com/isulim
+siavashyj:
+ login: siavashyj
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/43583410?u=562005ddc7901cd27a1219a118a2363817b14977&v=4
+ url: https://github.com/siavashyj
+DevSpace88:
+ login: DevSpace88
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/102557040?u=6b356e3e1b9b6bc6a208b363988d4089ef94193f&v=4
+ url: https://github.com/DevSpace88
+Yum-git:
+ login: Yum-git
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/56100888?u=7c6ae21af081488b5fb703ab096fb1926025fd50&v=4
+ url: https://github.com/Yum-git
+oubush:
+ login: oubush
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/7489099?u=c86448bc61f5e7f03a1f14a768beeb09c33899d4&v=4
+ url: https://github.com/oubush
+KAZAMA-DREAM:
+ login: KAZAMA-DREAM
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/73453137?u=5108c757a3842733a448d9a16cdc65d82899eee1&v=4
+ url: https://github.com/KAZAMA-DREAM
+aprilcoskun:
+ login: aprilcoskun
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/17393603?u=18177d5bdba3a4567b8664587c882fb734e5fa09&v=4
+ url: https://github.com/aprilcoskun
+zhiquanchi:
+ login: zhiquanchi
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/29973289?u=744c74bc2635f839235ec32a0a934c5cef9a156d&v=4
+ url: https://github.com/zhiquanchi
+Jamim:
+ login: Jamim
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/5607572?u=9ce0b6a6d1a5124e28b3c04d8d26827ca328713a&v=4
+ url: https://github.com/Jamim
+alvinkhalil:
+ login: alvinkhalil
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/84583022?u=ab0eeb9ce6ffe93fd9bb23daf782b9867b864149&v=4
+ url: https://github.com/alvinkhalil
+leylaeminova:
+ login: leylaeminova
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/100516839?u=0b0dab9e31742076b22812b14a39b4e6d8f6de4a&v=4
+ url: https://github.com/leylaeminova
+UN-9BOT:
+ login: UN-9BOT
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/111110804?u=39e158937ed795972c2d0400fc521c50e9bfb9e7&v=4
+ url: https://github.com/UN-9BOT
+flasonme:
+ login: flasonme
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/30571019?v=4
+ url: https://github.com/flasonme
+gustavoprezoto:
+ login: gustavoprezoto
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/62812585?u=2e936a0c6a2f11ecf3a735ebd33386100bcfebf8&v=4
+ url: https://github.com/gustavoprezoto
+johnny630:
+ login: johnny630
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/2870590?v=4
+ url: https://github.com/johnny630
+JCTrapero:
+ login: JCTrapero
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/109148166?u=bea607a04058176c4c2ae0d7c2e9ec647ccef002&v=4
+ url: https://github.com/JCTrapero
+ZhibangYue:
+ login: ZhibangYue
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/93324586?u=20fb23e3718e0364bb217966470d35e0637dd4fe&v=4
+ url: https://github.com/ZhibangYue
+saeye:
+ login: saeye
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/62229734?u=312d619db2588b60d5d5bde65260a2f44fdc6c76&v=4
+ url: https://github.com/saeye
+Heumhub:
+ login: Heumhub
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/173761521?v=4
+ url: https://github.com/Heumhub
+manumolina:
+ login: manumolina
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/2404208?u=fdc5502910f8dec814b2477f89587b9e45fac846&v=4
+ url: https://github.com/manumolina
+logan2d5:
+ login: logan2d5
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/146642263?u=dbd6621f8b0330d6919f6a7131277b92e26fbe87&v=4
+ url: https://github.com/logan2d5
+tiaggo16:
+ login: tiaggo16
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/62227573?u=359f4e2c51a4b13c8553ac5af405d635b07bb61f&v=4
+ url: https://github.com/tiaggo16
+kiharito:
+ login: kiharito
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/38311245?v=4
+ url: https://github.com/kiharito
+J-Fuji:
+ login: J-Fuji
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/101452903?v=4
+ url: https://github.com/J-Fuji
+MrL8199:
+ login: MrL8199
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/39489075?u=3fc4f89c86973e40b5970d838c801bdbc13ac828&v=4
+ url: https://github.com/MrL8199
+ivintoiu:
+ login: ivintoiu
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/1853336?u=5e3d0977f44661fb9712fa297cc8f7608ea6ce48&v=4
+ url: https://github.com/ivintoiu
+EgorOnishchuk:
+ login: EgorOnishchuk
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/120256301?v=4
+ url: https://github.com/EgorOnishchuk
+iamantonreznik:
+ login: iamantonreznik
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/112612414?u=bf6de9a1ab17326fe14de0709719fff3826526d0&v=4
+ url: https://github.com/iamantonreznik
+Azazul123:
+ login: Azazul123
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/102759111?u=b48ce6e30a81a23467cc30e0c011bcc57f0326ab&v=4
+ url: https://github.com/Azazul123
diff --git a/docs/en/data/translators.yml b/docs/en/data/translators.yml
new file mode 100644
index 000000000..51d05003b
--- /dev/null
+++ b/docs/en/data/translators.yml
@@ -0,0 +1,525 @@
+nilslindemann:
+ login: nilslindemann
+ count: 120
+ avatarUrl: https://avatars.githubusercontent.com/u/6892179?u=1dca6a22195d6cd1ab20737c0e19a4c55d639472&v=4
+ url: https://github.com/nilslindemann
+jaystone776:
+ login: jaystone776
+ count: 46
+ avatarUrl: https://avatars.githubusercontent.com/u/11191137?u=299205a95e9b6817a43144a48b643346a5aac5cc&v=4
+ url: https://github.com/jaystone776
+ceb10n:
+ login: ceb10n
+ count: 27
+ avatarUrl: https://avatars.githubusercontent.com/u/235213?u=edcce471814a1eba9f0cdaa4cd0de18921a940a6&v=4
+ url: https://github.com/ceb10n
+valentinDruzhinin:
+ login: valentinDruzhinin
+ count: 24
+ avatarUrl: https://avatars.githubusercontent.com/u/12831905?u=aae1ebc675c91e8fa582df4fcc4fc4128106344d&v=4
+ url: https://github.com/valentinDruzhinin
+tokusumi:
+ login: tokusumi
+ count: 23
+ avatarUrl: https://avatars.githubusercontent.com/u/41147016?u=55010621aece725aa702270b54fed829b6a1fe60&v=4
+ url: https://github.com/tokusumi
+SwftAlpc:
+ login: SwftAlpc
+ count: 23
+ avatarUrl: https://avatars.githubusercontent.com/u/52768429?u=6a3aa15277406520ad37f6236e89466ed44bc5b8&v=4
+ url: https://github.com/SwftAlpc
+hasansezertasan:
+ login: hasansezertasan
+ count: 22
+ avatarUrl: https://avatars.githubusercontent.com/u/13135006?u=99f0b0f0fc47e88e8abb337b4447357939ef93e7&v=4
+ url: https://github.com/hasansezertasan
+waynerv:
+ login: waynerv
+ count: 20
+ avatarUrl: https://avatars.githubusercontent.com/u/39515546?u=ec35139777597cdbbbddda29bf8b9d4396b429a9&v=4
+ url: https://github.com/waynerv
+AlertRED:
+ login: AlertRED
+ count: 16
+ avatarUrl: https://avatars.githubusercontent.com/u/15695000?u=f5a4944c6df443030409c88da7d7fa0b7ead985c&v=4
+ url: https://github.com/AlertRED
+hard-coders:
+ login: hard-coders
+ count: 15
+ avatarUrl: https://avatars.githubusercontent.com/u/9651103?u=95db33927bbff1ed1c07efddeb97ac2ff33068ed&v=4
+ url: https://github.com/hard-coders
+Joao-Pedro-P-Holanda:
+ login: Joao-Pedro-P-Holanda
+ count: 14
+ avatarUrl: https://avatars.githubusercontent.com/u/110267046?u=331bd016326dac4cf3df4848f6db2dbbf8b5f978&v=4
+ url: https://github.com/Joao-Pedro-P-Holanda
+codingjenny:
+ login: codingjenny
+ count: 14
+ avatarUrl: https://avatars.githubusercontent.com/u/103817302?u=3a042740dc0ff58615da0d8679230966fd7693e8&v=4
+ url: https://github.com/codingjenny
+Xewus:
+ login: Xewus
+ count: 13
+ avatarUrl: https://avatars.githubusercontent.com/u/85196001?u=f8e2dc7e5104f109cef944af79050ea8d1b8f914&v=4
+ url: https://github.com/Xewus
+Zhongheng-Cheng:
+ login: Zhongheng-Cheng
+ count: 13
+ avatarUrl: https://avatars.githubusercontent.com/u/95612344?u=a0f7730a3cc7486827965e01a119ad610bda4b0a&v=4
+ url: https://github.com/Zhongheng-Cheng
+Smlep:
+ login: Smlep
+ count: 11
+ avatarUrl: https://avatars.githubusercontent.com/u/16785985?u=ffe99fa954c8e774ef1117e58d34aece92051e27&v=4
+ url: https://github.com/Smlep
+marcelomarkus:
+ login: marcelomarkus
+ count: 11
+ avatarUrl: https://avatars.githubusercontent.com/u/20115018?u=dda090ce9160ef0cd2ff69b1e5ea741283425cba&v=4
+ url: https://github.com/marcelomarkus
+KaniKim:
+ login: KaniKim
+ count: 10
+ avatarUrl: https://avatars.githubusercontent.com/u/19832624?u=296dbdd490e0eb96e3d45a2608c065603b17dc31&v=4
+ url: https://github.com/KaniKim
+Vincy1230:
+ login: Vincy1230
+ count: 9
+ avatarUrl: https://avatars.githubusercontent.com/u/81342412?u=ab5e256a4077a4a91f3f9cd2115ba80780454cbe&v=4
+ url: https://github.com/Vincy1230
+rjNemo:
+ login: rjNemo
+ count: 8
+ avatarUrl: https://avatars.githubusercontent.com/u/56785022?u=d5c3a02567c8649e146fcfc51b6060ccaf8adef8&v=4
+ url: https://github.com/rjNemo
+xzmeng:
+ login: xzmeng
+ count: 8
+ avatarUrl: https://avatars.githubusercontent.com/u/40202897?v=4
+ url: https://github.com/xzmeng
+pablocm83:
+ login: pablocm83
+ count: 8
+ avatarUrl: https://avatars.githubusercontent.com/u/28315068?u=3310fbb05bb8bfc50d2c48b6cb64ac9ee4a14549&v=4
+ url: https://github.com/pablocm83
+ptt3199:
+ login: ptt3199
+ count: 7
+ avatarUrl: https://avatars.githubusercontent.com/u/51350651?u=2c3d947a80283e32bf616d4c3af139a6be69680f&v=4
+ url: https://github.com/ptt3199
+batlopes:
+ login: batlopes
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/33462923?u=0fb3d7acb316764616f11e4947faf080e49ad8d9&v=4
+ url: https://github.com/batlopes
+lucasbalieiro:
+ login: lucasbalieiro
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/37416577?u=eabaf4aebbaa88a94a4886273edba689012cee70&v=4
+ url: https://github.com/lucasbalieiro
+Alexandrhub:
+ login: Alexandrhub
+ count: 6
+ avatarUrl: https://avatars.githubusercontent.com/u/119126536?u=9fc0d48f3307817bafecc5861eb2168401a6cb04&v=4
+ url: https://github.com/Alexandrhub
+Serrones:
+ login: Serrones
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/22691749?u=4795b880e13ca33a73e52fc0ef7dc9c60c8fce47&v=4
+ url: https://github.com/Serrones
+RunningIkkyu:
+ login: RunningIkkyu
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/31848542?u=494ecc298e3f26197495bb357ad0f57cfd5f7a32&v=4
+ url: https://github.com/RunningIkkyu
+Attsun1031:
+ login: Attsun1031
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/1175560?v=4
+ url: https://github.com/Attsun1031
+NinaHwang:
+ login: NinaHwang
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/79563565?u=241f2cb6d38a2d379536608a8ea5a22ed4b1a3ea&v=4
+ url: https://github.com/NinaHwang
+tiangolo:
+ login: tiangolo
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/1326112?u=cb5d06e73a9e1998141b1641aa88e443c6717651&v=4
+ url: https://github.com/tiangolo
+rostik1410:
+ login: rostik1410
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/11443899?u=e26a635c2ba220467b308a326a579b8ccf4a8701&v=4
+ url: https://github.com/rostik1410
+alv2017:
+ login: alv2017
+ count: 5
+ avatarUrl: https://avatars.githubusercontent.com/u/31544722?v=4
+ url: https://github.com/alv2017
+komtaki:
+ login: komtaki
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/39375566?u=260ad6b1a4b34c07dbfa728da5e586f16f6d1824&v=4
+ url: https://github.com/komtaki
+JulianMaurin:
+ login: JulianMaurin
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/63545168?u=b7d15ac865268cbefc2d739e2f23d9aeeac1a622&v=4
+ url: https://github.com/JulianMaurin
+stlucasgarcia:
+ login: stlucasgarcia
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/61513630?u=c22d8850e9dc396a8820766a59837f967e14f9a0&v=4
+ url: https://github.com/stlucasgarcia
+ComicShrimp:
+ login: ComicShrimp
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/43503750?u=d2fbf412e7730183ce91686ca48d4147e1b7dc74&v=4
+ url: https://github.com/ComicShrimp
+BilalAlpaslan:
+ login: BilalAlpaslan
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/47563997?u=63ed66e304fe8d765762c70587d61d9196e5c82d&v=4
+ url: https://github.com/BilalAlpaslan
+axel584:
+ login: axel584
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/1334088?u=9667041f5b15dc002b6f9665fda8c0412933ac04&v=4
+ url: https://github.com/axel584
+tamtam-fitness:
+ login: tamtam-fitness
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/62091034?u=8da19a6bd3d02f5d6ba30c7247d5b46c98dd1403&v=4
+ url: https://github.com/tamtam-fitness
+Limsunoh:
+ login: Limsunoh
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/90311848?u=f456e0c5709fd50c8cd2898b551558eda14e5f21&v=4
+ url: https://github.com/Limsunoh
+kwang1215:
+ login: kwang1215
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/74170199?u=2a63ff6692119dde3f5e5693365b9fcd6f977b08&v=4
+ url: https://github.com/kwang1215
+k94-ishi:
+ login: k94-ishi
+ count: 4
+ avatarUrl: https://avatars.githubusercontent.com/u/32672580?u=bc7c5c07af0656be9fe4f1784a444af8d81ded89&v=4
+ url: https://github.com/k94-ishi
+jfunez:
+ login: jfunez
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/805749?v=4
+ url: https://github.com/jfunez
+ycd:
+ login: ycd
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/62724709?u=f1e7bae394a315da950912c92dc861a8eaf95d4c&v=4
+ url: https://github.com/ycd
+mariacamilagl:
+ login: mariacamilagl
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/11489395?u=4adb6986bf3debfc2b8216ae701f2bd47d73da7d&v=4
+ url: https://github.com/mariacamilagl
+maoyibo:
+ login: maoyibo
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/7887703?v=4
+ url: https://github.com/maoyibo
+blt232018:
+ login: blt232018
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/43393471?u=172b0e0391db1aa6c1706498d6dfcb003c8a4857&v=4
+ url: https://github.com/blt232018
+magiskboy:
+ login: magiskboy
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/13352088?u=18b6d672523f9e9d98401f31dd50e28bb27d826f&v=4
+ url: https://github.com/magiskboy
+luccasmmg:
+ login: luccasmmg
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/11317382?u=65099a5a0d492b89119471f8a7014637cc2e04da&v=4
+ url: https://github.com/luccasmmg
+lbmendes:
+ login: lbmendes
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/80999926?u=646619e2f07ac5a7c3f65fe7834197461a4fff9f&v=4
+ url: https://github.com/lbmendes
+Zssaer:
+ login: Zssaer
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/45691504?u=4c0c195f25cb5ac6af32acfb0ab35427682938d2&v=4
+ url: https://github.com/Zssaer
+ChuyuChoyeon:
+ login: ChuyuChoyeon
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/129537877?u=f0c76f3327817a8b86b422d62e04a34bf2827f2b&v=4
+ url: https://github.com/ChuyuChoyeon
+ivan-abc:
+ login: ivan-abc
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/36765187?u=c6e0ba571c1ccb6db9d94e62e4b8b5eda811a870&v=4
+ url: https://github.com/ivan-abc
+mojtabapaso:
+ login: mojtabapaso
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/121169359?u=ced1d5ad673bcd9e949ebf967a4ab50185637443&v=4
+ url: https://github.com/mojtabapaso
+hsuanchi:
+ login: hsuanchi
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/24913710?u=7d25a398e478b6e63503bf6f26c54efa9e0da07b&v=4
+ url: https://github.com/hsuanchi
+alejsdev:
+ login: alejsdev
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/90076947?u=638c65283ac9e9e2c3a0f9d1e3370db4b8a2c58d&v=4
+ url: https://github.com/alejsdev
+riroan:
+ login: riroan
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/33053284?u=2d18e3771506ee874b66d6aa2b3b1107fd95c38f&v=4
+ url: https://github.com/riroan
+nayeonkinn:
+ login: nayeonkinn
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/98254573?u=64a75ac99b320d4935eff8d1fceea9680fa07473&v=4
+ url: https://github.com/nayeonkinn
+pe-brian:
+ login: pe-brian
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/1783138?u=7e6242eb9e85bcf673fa88bbac9dd6dc3f03b1b5&v=4
+ url: https://github.com/pe-brian
+maxscheijen:
+ login: maxscheijen
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/47034840?u=eb98f37882528ea349ca4e5255fa64ac3fef0294&v=4
+ url: https://github.com/maxscheijen
+ilacftemp:
+ login: ilacftemp
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/159066669?v=4
+ url: https://github.com/ilacftemp
+devluisrodrigues:
+ login: devluisrodrigues
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/103431660?u=d9674a3249edc4601d2c712cdebf899918503c3a&v=4
+ url: https://github.com/devluisrodrigues
+devfernandoa:
+ login: devfernandoa
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/28360583?u=c4308abd62e8847c9e572e1bb9fe6b9dc9ef8e50&v=4
+ url: https://github.com/devfernandoa
+kim-sangah:
+ login: kim-sangah
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/173775778?v=4
+ url: https://github.com/kim-sangah
+9zimin9:
+ login: 9zimin9
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/174453744?v=4
+ url: https://github.com/9zimin9
+nahyunkeem:
+ login: nahyunkeem
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/174440096?u=e12401d492eee58570f8914d0872b52e421a776e&v=4
+ url: https://github.com/nahyunkeem
+timothy-jeong:
+ login: timothy-jeong
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/53824764?u=db3d0cea2f5fab64d810113c5039a369699a2774&v=4
+ url: https://github.com/timothy-jeong
+gerry-sabar:
+ login: gerry-sabar
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/1120123?v=4
+ url: https://github.com/gerry-sabar
+Rishat-F:
+ login: Rishat-F
+ count: 3
+ avatarUrl: https://avatars.githubusercontent.com/u/66554797?v=4
+ url: https://github.com/Rishat-F
+izaguerreiro:
+ login: izaguerreiro
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/2241504?v=4
+ url: https://github.com/izaguerreiro
+Xaraxx:
+ login: Xaraxx
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/29824698?u=dde2e233e22bb5ca1f8bb0c6e353ccd0d06e6066&v=4
+ url: https://github.com/Xaraxx
+sh0nk:
+ login: sh0nk
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/6478810?u=af15d724875cec682ed8088a86d36b2798f981c0&v=4
+ url: https://github.com/sh0nk
+dukkee:
+ login: dukkee
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/36825394?u=ccfd86e6a4f2d093dad6f7544cc875af67fa2df8&v=4
+ url: https://github.com/dukkee
+oandersonmagalhaes:
+ login: oandersonmagalhaes
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/83456692?v=4
+ url: https://github.com/oandersonmagalhaes
+leandrodesouzadev:
+ login: leandrodesouzadev
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/85115541?u=4eb25f43f1fe23727d61e986cf83b73b86e2a95a&v=4
+ url: https://github.com/leandrodesouzadev
+kty4119:
+ login: kty4119
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/49435654?v=4
+ url: https://github.com/kty4119
+ASpathfinder:
+ login: ASpathfinder
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/31813636?u=2090bd1b7abb65cfeff0c618f99f11afa82c0548&v=4
+ url: https://github.com/ASpathfinder
+jujumilk3:
+ login: jujumilk3
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/41659814?u=538f7dfef03b59f25e43f10d59a31c19ef538a0c&v=4
+ url: https://github.com/jujumilk3
+ayr-ton:
+ login: ayr-ton
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/1090517?u=5cf70a0e0f0dbf084e074e494aa94d7c91a46ba6&v=4
+ url: https://github.com/ayr-ton
+KdHyeon0661:
+ login: KdHyeon0661
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/20253352?u=5ae1aae34b091a39f22cbe60a02b79dcbdbea031&v=4
+ url: https://github.com/KdHyeon0661
+LorhanSohaky:
+ login: LorhanSohaky
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/16273730?u=095b66f243a2cd6a0aadba9a095009f8aaf18393&v=4
+ url: https://github.com/LorhanSohaky
+cfraboulet:
+ login: cfraboulet
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/62244267?u=ed0e286ba48fa1dafd64a08e50f3364b8e12df34&v=4
+ url: https://github.com/cfraboulet
+dedkot01:
+ login: dedkot01
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/26196675?u=e2966887124e67932853df4f10f86cb526edc7b0&v=4
+ url: https://github.com/dedkot01
+AGolicyn:
+ login: AGolicyn
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/86262613?u=3c21606ab8d210a061a1673decff1e7d5592b380&v=4
+ url: https://github.com/AGolicyn
+fhabers21:
+ login: fhabers21
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/58401847?v=4
+ url: https://github.com/fhabers21
+TabarakoAkula:
+ login: TabarakoAkula
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/113298631?u=add801e370dbc502cd94ce6d3484760d7fef5406&v=4
+ url: https://github.com/TabarakoAkula
+AhsanSheraz:
+ login: AhsanSheraz
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/51913596?u=08e31cacb3048be30722c94010ddd028f3fdbec4&v=4
+ url: https://github.com/AhsanSheraz
+ArtemKhymenko:
+ login: ArtemKhymenko
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/14346625?u=f2fa553d9e5ec5e0f05d66bd649f7be347169631&v=4
+ url: https://github.com/ArtemKhymenko
+hasnatsajid:
+ login: hasnatsajid
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/86589885?u=49958789e6385be624f2c6a55a860c599eb05e2c&v=4
+ url: https://github.com/hasnatsajid
+alperiox:
+ login: alperiox
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/34214152?u=2c5acad3461d4dbc2d48371ba86cac56ae9b25cc&v=4
+ url: https://github.com/alperiox
+emrhnsyts:
+ login: emrhnsyts
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/42899027?u=ad26798e3f8feed2041c5dd5f87e58933d6c3283&v=4
+ url: https://github.com/emrhnsyts
+vusallyv:
+ login: vusallyv
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/85983771?u=53a7b755cb338d9313966dbf2e4e68b512565186&v=4
+ url: https://github.com/vusallyv
+jackleeio:
+ login: jackleeio
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/20477587?u=c5184dab6d021733d10c8f975b20e391856303d6&v=4
+ url: https://github.com/jackleeio
+choi-haram:
+ login: choi-haram
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/62204475?v=4
+ url: https://github.com/choi-haram
+imtiaz101325:
+ login: imtiaz101325
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/54007087?u=194d972b501b9ea9d2ddeaed757c492936e0121a&v=4
+ url: https://github.com/imtiaz101325
+fabianfalon:
+ login: fabianfalon
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/3700760?u=95f69e31280b17ac22299cdcd345323b142fe0af&v=4
+ url: https://github.com/fabianfalon
+waketzheng:
+ login: waketzheng
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/35413830?u=df19e4fd5bb928e7d086e053ef26a46aad23bf84&v=4
+ url: https://github.com/waketzheng
+billzhong:
+ login: billzhong
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/1644011?v=4
+ url: https://github.com/billzhong
+chaoless:
+ login: chaoless
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/64477804?v=4
+ url: https://github.com/chaoless
+logan2d5:
+ login: logan2d5
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/146642263?u=dbd6621f8b0330d6919f6a7131277b92e26fbe87&v=4
+ url: https://github.com/logan2d5
+andersonrocha0:
+ login: andersonrocha0
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/22346169?u=93a1359c8c5461d894802c0cc65bcd09217e7a02&v=4
+ url: https://github.com/andersonrocha0
+saeye:
+ login: saeye
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/62229734?u=312d619db2588b60d5d5bde65260a2f44fdc6c76&v=4
+ url: https://github.com/saeye
+11kkw:
+ login: 11kkw
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/21125286?v=4
+ url: https://github.com/11kkw
+yes0ng:
+ login: yes0ng
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/25501794?u=3aed18b0d491e0220a167a1e9e58bea3638c6707&v=4
+ url: https://github.com/yes0ng
+EgorOnishchuk:
+ login: EgorOnishchuk
+ count: 2
+ avatarUrl: https://avatars.githubusercontent.com/u/120256301?v=4
+ url: https://github.com/EgorOnishchuk
diff --git a/docs/en/docs/advanced/additional-responses.md b/docs/en/docs/advanced/additional-responses.md
index 88d27018c..03d48c2a7 100644
--- a/docs/en/docs/advanced/additional-responses.md
+++ b/docs/en/docs/advanced/additional-responses.md
@@ -1,9 +1,12 @@
# Additional Responses in OpenAPI
-!!! warning
- This is a rather advanced topic.
+/// warning
- If you are starting with **FastAPI**, you might not need this.
+This is a rather advanced topic.
+
+If you are starting with **FastAPI**, you might not need this.
+
+///
You can declare additional responses, with additional status codes, media types, descriptions, etc.
@@ -15,7 +18,7 @@ But for those additional responses you have to make sure you return a `Response`
You can pass to your *path operation decorators* a parameter `responses`.
-It receives a `dict`, the keys are status codes for each response, like `200`, and the values are other `dict`s with the information for each of them.
+It receives a `dict`: the keys are status codes for each response (like `200`), and the values are other `dict`s with the information for each of them.
Each of those response `dict`s can have a key `model`, containing a Pydantic model, just like `response_model`.
@@ -23,24 +26,28 @@ Each of those response `dict`s can have a key `model`, containing a Pydantic mod
For example, to declare another response with a status code `404` and a Pydantic model `Message`, you can write:
-```Python hl_lines="18 22"
-{!../../../docs_src/additional_responses/tutorial001.py!}
-```
+{* ../../docs_src/additional_responses/tutorial001.py hl[18,22] *}
-!!! note
- Keep in mind that you have to return the `JSONResponse` directly.
+/// note
-!!! info
- The `model` key is not part of OpenAPI.
+Keep in mind that you have to return the `JSONResponse` directly.
- **FastAPI** will take the Pydantic model from there, generate the `JSON Schema`, and put it in the correct place.
+///
- The correct place is:
+/// info
- * In the key `content`, that has as value another JSON object (`dict`) that contains:
- * A key with the media type, e.g. `application/json`, that contains as value another JSON object, that contains:
- * A key `schema`, that has as the value the JSON Schema from the model, here's the correct place.
- * **FastAPI** adds a reference here to the global JSON Schemas in another place in your OpenAPI instead of including it directly. This way, other applications and clients can use those JSON Schemas directly, provide better code generation tools, etc.
+The `model` key is not part of OpenAPI.
+
+**FastAPI** will take the Pydantic model from there, generate the JSON Schema, and put it in the correct place.
+
+The correct place is:
+
+* In the key `content`, that has as value another JSON object (`dict`) that contains:
+ * A key with the media type, e.g. `application/json`, that contains as value another JSON object, that contains:
+ * A key `schema`, that has as the value the JSON Schema from the model, here's the correct place.
+ * **FastAPI** adds a reference here to the global JSON Schemas in another place in your OpenAPI instead of including it directly. This way, other applications and clients can use those JSON Schemas directly, provide better code generation tools, etc.
+
+///
The generated responses in the OpenAPI for this *path operation* will be:
@@ -168,17 +175,21 @@ You can use this same `responses` parameter to add different media types for the
For example, you can add an additional media type of `image/png`, declaring that your *path operation* can return a JSON object (with media type `application/json`) or a PNG image:
-```Python hl_lines="19-24 28"
-{!../../../docs_src/additional_responses/tutorial002.py!}
-```
+{* ../../docs_src/additional_responses/tutorial002.py hl[19:24,28] *}
-!!! note
- Notice that you have to return the image using a `FileResponse` directly.
+/// note
-!!! info
- Unless you specify a different media type explicitly in your `responses` parameter, FastAPI will assume the response has the same media type as the main response class (default `application/json`).
+Notice that you have to return the image using a `FileResponse` directly.
- But if you have specified a custom response class with `None` as its media type, FastAPI will use `application/json` for any additional response that has an associated model.
+///
+
+/// info
+
+Unless you specify a different media type explicitly in your `responses` parameter, FastAPI will assume the response has the same media type as the main response class (default `application/json`).
+
+But if you have specified a custom response class with `None` as its media type, FastAPI will use `application/json` for any additional response that has an associated model.
+
+///
## Combining information
@@ -192,9 +203,7 @@ For example, you can declare a response with a status code `404` that uses a Pyd
And a response with a status code `200` that uses your `response_model`, but includes a custom `example`:
-```Python hl_lines="20-31"
-{!../../../docs_src/additional_responses/tutorial003.py!}
-```
+{* ../../docs_src/additional_responses/tutorial003.py hl[20:31] *}
It will all be combined and included in your OpenAPI, and shown in the API docs:
@@ -228,13 +237,11 @@ You can use that technique to reuse some predefined responses in your *path oper
For example:
-```Python hl_lines="13-17 26"
-{!../../../docs_src/additional_responses/tutorial004.py!}
-```
+{* ../../docs_src/additional_responses/tutorial004.py hl[13:17,26] *}
## More information about OpenAPI responses
To see what exactly you can include in the responses, you can check these sections in the OpenAPI specification:
-* OpenAPI Responses Object, it includes the `Response Object`.
-* OpenAPI Response Object, you can include anything from this directly in each response inside your `responses` parameter. Including `description`, `headers`, `content` (inside of this is that you declare different media types and JSON Schemas), and `links`.
+* OpenAPI Responses Object, it includes the `Response Object`.
+* OpenAPI Response Object, you can include anything from this directly in each response inside your `responses` parameter. Including `description`, `headers`, `content` (inside of this is that you declare different media types and JSON Schemas), and `links`.
diff --git a/docs/en/docs/advanced/additional-status-codes.md b/docs/en/docs/advanced/additional-status-codes.md
index 0ce275343..077a00488 100644
--- a/docs/en/docs/advanced/additional-status-codes.md
+++ b/docs/en/docs/advanced/additional-status-codes.md
@@ -14,53 +14,25 @@ But you also want it to accept new items. And when the items didn't exist before
To achieve that, import `JSONResponse`, and return your content there directly, setting the `status_code` that you want:
-=== "Python 3.10+"
+{* ../../docs_src/additional_status_codes/tutorial001_an_py310.py hl[4,25] *}
- ```Python hl_lines="4 25"
- {!> ../../../docs_src/additional_status_codes/tutorial001_an_py310.py!}
- ```
+/// warning
-=== "Python 3.9+"
+When you return a `Response` directly, like in the example above, it will be returned directly.
- ```Python hl_lines="4 25"
- {!> ../../../docs_src/additional_status_codes/tutorial001_an_py39.py!}
- ```
+It won't be serialized with a model, etc.
-=== "Python 3.8+"
+Make sure it has the data you want it to have, and that the values are valid JSON (if you are using `JSONResponse`).
- ```Python hl_lines="4 26"
- {!> ../../../docs_src/additional_status_codes/tutorial001_an.py!}
- ```
+///
-=== "Python 3.10+ non-Annotated"
+/// note | Technical Details
- !!! tip
- Prefer to use the `Annotated` version if possible.
+You could also use `from starlette.responses import JSONResponse`.
- ```Python hl_lines="2 23"
- {!> ../../../docs_src/additional_status_codes/tutorial001_py310.py!}
- ```
+**FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette. The same with `status`.
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="4 25"
- {!> ../../../docs_src/additional_status_codes/tutorial001.py!}
- ```
-
-!!! warning
- When you return a `Response` directly, like in the example above, it will be returned directly.
-
- It won't be serialized with a model, etc.
-
- Make sure it has the data you want it to have, and that the values are valid JSON (if you are using `JSONResponse`).
-
-!!! note "Technical Details"
- You could also use `from starlette.responses import JSONResponse`.
-
- **FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette. The same with `status`.
+///
## OpenAPI and API docs
diff --git a/docs/en/docs/advanced/advanced-dependencies.md b/docs/en/docs/advanced/advanced-dependencies.md
index 0cffab56d..f933fd264 100644
--- a/docs/en/docs/advanced/advanced-dependencies.md
+++ b/docs/en/docs/advanced/advanced-dependencies.md
@@ -18,26 +18,7 @@ Not the class itself (which is already a callable), but an instance of that clas
To do that, we declare a method `__call__`:
-=== "Python 3.9+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/dependencies/tutorial011_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/dependencies/tutorial011_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/dependencies/tutorial011.py!}
- ```
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[12] *}
In this case, this `__call__` is what **FastAPI** will use to check for additional parameters and sub-dependencies, and this is what will be called to pass a value to the parameter in your *path operation function* later.
@@ -45,26 +26,7 @@ In this case, this `__call__` is what **FastAPI** will use to check for addition
And now, we can use `__init__` to declare the parameters of the instance that we can use to "parameterize" the dependency:
-=== "Python 3.9+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/dependencies/tutorial011_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/dependencies/tutorial011_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/dependencies/tutorial011.py!}
- ```
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[9] *}
In this case, **FastAPI** won't ever touch or care about `__init__`, we will use it directly in our code.
@@ -72,26 +34,7 @@ In this case, **FastAPI** won't ever touch or care about `__init__`, we will use
We could create an instance of this class with:
-=== "Python 3.9+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/dependencies/tutorial011_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="17"
- {!> ../../../docs_src/dependencies/tutorial011_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="16"
- {!> ../../../docs_src/dependencies/tutorial011.py!}
- ```
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[18] *}
And that way we are able to "parameterize" our dependency, that now has `"bar"` inside of it, as the attribute `checker.fixed_content`.
@@ -107,32 +50,16 @@ checker(q="somequery")
...and pass whatever that returns as the value of the dependency in our *path operation function* as the parameter `fixed_content_included`:
-=== "Python 3.9+"
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[22] *}
- ```Python hl_lines="22"
- {!> ../../../docs_src/dependencies/tutorial011_an_py39.py!}
- ```
+/// tip
-=== "Python 3.8+"
+All this might seem contrived. And it might not be very clear how is it useful yet.
- ```Python hl_lines="21"
- {!> ../../../docs_src/dependencies/tutorial011_an.py!}
- ```
+These examples are intentionally simple, but show how it all works.
-=== "Python 3.8+ non-Annotated"
+In the chapters about security, there are utility functions that are implemented in this same way.
- !!! tip
- Prefer to use the `Annotated` version if possible.
+If you understood all this, you already know how those utility tools for security work underneath.
- ```Python hl_lines="20"
- {!> ../../../docs_src/dependencies/tutorial011.py!}
- ```
-
-!!! tip
- All this might seem contrived. And it might not be very clear how is it useful yet.
-
- These examples are intentionally simple, but show how it all works.
-
- In the chapters about security, there are utility functions that are implemented in this same way.
-
- If you understood all this, you already know how those utility tools for security work underneath.
+///
diff --git a/docs/en/docs/advanced/async-tests.md b/docs/en/docs/advanced/async-tests.md
index f9c82e6ab..8d6929222 100644
--- a/docs/en/docs/advanced/async-tests.md
+++ b/docs/en/docs/advanced/async-tests.md
@@ -32,15 +32,11 @@ For a simple example, let's consider a file structure similar to the one describ
The file `main.py` would have:
-```Python
-{!../../../docs_src/async_tests/main.py!}
-```
+{* ../../docs_src/async_tests/main.py *}
The file `test_main.py` would have the tests for `main.py`, it could look like this now:
-```Python
-{!../../../docs_src/async_tests/test_main.py!}
-```
+{* ../../docs_src/async_tests/test_main.py *}
## Run it
@@ -60,18 +56,17 @@ $ pytest
The marker `@pytest.mark.anyio` tells pytest that this test function should be called asynchronously:
-```Python hl_lines="7"
-{!../../../docs_src/async_tests/test_main.py!}
-```
+{* ../../docs_src/async_tests/test_main.py hl[7] *}
-!!! tip
- Note that the test function is now `async def` instead of just `def` as before when using the `TestClient`.
+/// tip
+
+Note that the test function is now `async def` instead of just `def` as before when using the `TestClient`.
+
+///
Then we can create an `AsyncClient` with the app, and send async requests to it, using `await`.
-```Python hl_lines="9-10"
-{!../../../docs_src/async_tests/test_main.py!}
-```
+{* ../../docs_src/async_tests/test_main.py hl[9:12] *}
This is the equivalent to:
@@ -81,15 +76,24 @@ response = client.get('/')
...that we used to make our requests with the `TestClient`.
-!!! tip
- Note that we're using async/await with the new `AsyncClient` - the request is asynchronous.
+/// tip
-!!! warning
- If your application relies on lifespan events, the `AsyncClient` won't trigger these events. To ensure they are triggered, use `LifespanManager` from florimondmanca/asgi-lifespan.
+Note that we're using async/await with the new `AsyncClient` - the request is asynchronous.
+
+///
+
+/// warning
+
+If your application relies on lifespan events, the `AsyncClient` won't trigger these events. To ensure they are triggered, use `LifespanManager` from florimondmanca/asgi-lifespan.
+
+///
## Other Asynchronous Function Calls
As the testing function is now asynchronous, you can now also call (and `await`) other `async` functions apart from sending requests to your FastAPI application in your tests, exactly as you would call them anywhere else in your code.
-!!! tip
- If you encounter a `RuntimeError: Task attached to a different loop` when integrating asynchronous function calls in your tests (e.g. when using MongoDB's MotorClient) Remember to instantiate objects that need an event loop only within async functions, e.g. an `'@app.on_event("startup")` callback.
+/// tip
+
+If you encounter a `RuntimeError: Task attached to a different loop` when integrating asynchronous function calls in your tests (e.g. when using MongoDB's MotorClient), remember to instantiate objects that need an event loop only within async functions, e.g. an `'@app.on_event("startup")` callback.
+
+///
diff --git a/docs/en/docs/advanced/behind-a-proxy.md b/docs/en/docs/advanced/behind-a-proxy.md
index c17b024f9..1f0d0fd9f 100644
--- a/docs/en/docs/advanced/behind-a-proxy.md
+++ b/docs/en/docs/advanced/behind-a-proxy.md
@@ -18,9 +18,7 @@ In this case, the original path `/app` would actually be served at `/api/v1/app`
Even though all your code is written assuming there's just `/app`.
-```Python hl_lines="6"
-{!../../../docs_src/behind_a_proxy/tutorial001.py!}
-```
+{* ../../docs_src/behind_a_proxy/tutorial001.py hl[6] *}
And the proxy would be **"stripping"** the **path prefix** on the fly before transmitting the request to the app server (probably Uvicorn via FastAPI CLI), keeping your application convinced that it is being served at `/app`, so that you don't have to update all your code to include the prefix `/api/v1`.
@@ -43,8 +41,11 @@ browser --> proxy
proxy --> server
```
-!!! tip
- The IP `0.0.0.0` is commonly used to mean that the program listens on all the IPs available in that machine/server.
+/// tip
+
+The IP `0.0.0.0` is commonly used to mean that the program listens on all the IPs available in that machine/server.
+
+///
The docs UI would also need the OpenAPI schema to declare that this API `server` is located at `/api/v1` (behind the proxy). For example:
@@ -81,10 +82,13 @@ $ fastapi run main.py --root-path /api/v1
If you use Hypercorn, it also has the option `--root-path`.
-!!! note "Technical Details"
- The ASGI specification defines a `root_path` for this use case.
+/// note | Technical Details
- And the `--root-path` command line option provides that `root_path`.
+The ASGI specification defines a `root_path` for this use case.
+
+And the `--root-path` command line option provides that `root_path`.
+
+///
### Checking the current `root_path`
@@ -92,9 +96,7 @@ You can get the current `root_path` used by your application for each request, i
Here we are including it in the message just for demonstration purposes.
-```Python hl_lines="8"
-{!../../../docs_src/behind_a_proxy/tutorial001.py!}
-```
+{* ../../docs_src/behind_a_proxy/tutorial001.py hl[8] *}
Then, if you start Uvicorn with:
@@ -121,9 +123,7 @@ The response would be something like:
Alternatively, if you don't have a way to provide a command line option like `--root-path` or equivalent, you can set the `root_path` parameter when creating your FastAPI app:
-```Python hl_lines="3"
-{!../../../docs_src/behind_a_proxy/tutorial002.py!}
-```
+{* ../../docs_src/behind_a_proxy/tutorial002.py hl[3] *}
Passing the `root_path` to `FastAPI` would be the equivalent of passing the `--root-path` command line option to Uvicorn or Hypercorn.
@@ -172,8 +172,11 @@ Then create a file `traefik.toml` with:
This tells Traefik to listen on port 9999 and to use another file `routes.toml`.
-!!! tip
- We are using port 9999 instead of the standard HTTP port 80 so that you don't have to run it with admin (`sudo`) privileges.
+/// tip
+
+We are using port 9999 instead of the standard HTTP port 80 so that you don't have to run it with admin (`sudo`) privileges.
+
+///
Now create that other file `routes.toml`:
@@ -202,7 +205,7 @@ Now create that other file `routes.toml`:
This file configures Traefik to use the path prefix `/api/v1`.
-And then it will redirect its requests to your Uvicorn running on `http://127.0.0.1:8000`.
+And then Traefik will redirect its requests to your Uvicorn running on `http://127.0.0.1:8000`.
Now start Traefik:
@@ -239,8 +242,11 @@ Now, if you go to the URL with the port for Uvicorn: http://127.0.0.1:9999/api/v1/app.
@@ -283,20 +289,21 @@ This is because FastAPI uses this `root_path` to create the default `server` in
## Additional servers
-!!! warning
- This is a more advanced use case. Feel free to skip it.
+/// warning
+
+This is a more advanced use case. Feel free to skip it.
+
+///
By default, **FastAPI** will create a `server` in the OpenAPI schema with the URL for the `root_path`.
-But you can also provide other alternative `servers`, for example if you want *the same* docs UI to interact with a staging and production environments.
+But you can also provide other alternative `servers`, for example if you want *the same* docs UI to interact with both a staging and a production environment.
If you pass a custom list of `servers` and there's a `root_path` (because your API lives behind a proxy), **FastAPI** will insert a "server" with this `root_path` at the beginning of the list.
For example:
-```Python hl_lines="4-7"
-{!../../../docs_src/behind_a_proxy/tutorial003.py!}
-```
+{* ../../docs_src/behind_a_proxy/tutorial003.py hl[4:7] *}
Will generate an OpenAPI schema like:
@@ -323,23 +330,27 @@ Will generate an OpenAPI schema like:
}
```
-!!! tip
- Notice the auto-generated server with a `url` value of `/api/v1`, taken from the `root_path`.
+/// tip
+
+Notice the auto-generated server with a `url` value of `/api/v1`, taken from the `root_path`.
+
+///
In the docs UI at http://127.0.0.1:9999/api/v1/docs it would look like:
-!!! tip
- The docs UI will interact with the server that you select.
+/// tip
+
+The docs UI will interact with the server that you select.
+
+///
### Disable automatic server from `root_path`
If you don't want **FastAPI** to include an automatic server using the `root_path`, you can use the parameter `root_path_in_servers=False`:
-```Python hl_lines="9"
-{!../../../docs_src/behind_a_proxy/tutorial004.py!}
-```
+{* ../../docs_src/behind_a_proxy/tutorial004.py hl[9] *}
and then it won't include it in the OpenAPI schema.
diff --git a/docs/en/docs/advanced/custom-response.md b/docs/en/docs/advanced/custom-response.md
index 1d12173a1..8268dd81a 100644
--- a/docs/en/docs/advanced/custom-response.md
+++ b/docs/en/docs/advanced/custom-response.md
@@ -4,16 +4,19 @@ By default, **FastAPI** will return the responses using `JSONResponse`.
You can override it by returning a `Response` directly as seen in [Return a Response directly](response-directly.md){.internal-link target=_blank}.
-But if you return a `Response` directly, the data won't be automatically converted, and the documentation won't be automatically generated (for example, including the specific "media type", in the HTTP header `Content-Type` as part of the generated OpenAPI).
+But if you return a `Response` directly (or any subclass, like `JSONResponse`), the data won't be automatically converted (even if you declare a `response_model`), and the documentation won't be automatically generated (for example, including the specific "media type", in the HTTP header `Content-Type` as part of the generated OpenAPI).
-But you can also declare the `Response` that you want to be used, in the *path operation decorator*.
+But you can also declare the `Response` that you want to be used (e.g. any `Response` subclass), in the *path operation decorator* using the `response_class` parameter.
The contents that you return from your *path operation function* will be put inside of that `Response`.
And if that `Response` has a JSON media type (`application/json`), like is the case with the `JSONResponse` and `UJSONResponse`, the data you return will be automatically converted (and filtered) with any Pydantic `response_model` that you declared in the *path operation decorator*.
-!!! note
- If you use a response class with no media type, FastAPI will expect your response to have no content, so it will not document the response format in its generated OpenAPI docs.
+/// note
+
+If you use a response class with no media type, FastAPI will expect your response to have no content, so it will not document the response format in its generated OpenAPI docs.
+
+///
## Use `ORJSONResponse`
@@ -27,19 +30,23 @@ This is because by default, FastAPI will inspect every item inside and make sure
But if you are certain that the content that you are returning is **serializable with JSON**, you can pass it directly to the response class and avoid the extra overhead that FastAPI would have by passing your return content through the `jsonable_encoder` before passing it to the response class.
-```Python hl_lines="2 7"
-{!../../../docs_src/custom_response/tutorial001b.py!}
-```
+{* ../../docs_src/custom_response/tutorial001b.py hl[2,7] *}
-!!! info
- The parameter `response_class` will also be used to define the "media type" of the response.
+/// info
- In this case, the HTTP header `Content-Type` will be set to `application/json`.
+The parameter `response_class` will also be used to define the "media type" of the response.
- And it will be documented as such in OpenAPI.
+In this case, the HTTP header `Content-Type` will be set to `application/json`.
-!!! tip
- The `ORJSONResponse` is only available in FastAPI, not in Starlette.
+And it will be documented as such in OpenAPI.
+
+///
+
+/// tip
+
+The `ORJSONResponse` is only available in FastAPI, not in Starlette.
+
+///
## HTML Response
@@ -48,16 +55,17 @@ To return a response with HTML directly from **FastAPI**, use `HTMLResponse`.
* Import `HTMLResponse`.
* Pass `HTMLResponse` as the parameter `response_class` of your *path operation decorator*.
-```Python hl_lines="2 7"
-{!../../../docs_src/custom_response/tutorial002.py!}
-```
+{* ../../docs_src/custom_response/tutorial002.py hl[2,7] *}
-!!! info
- The parameter `response_class` will also be used to define the "media type" of the response.
+/// info
- In this case, the HTTP header `Content-Type` will be set to `text/html`.
+The parameter `response_class` will also be used to define the "media type" of the response.
- And it will be documented as such in OpenAPI.
+In this case, the HTTP header `Content-Type` will be set to `text/html`.
+
+And it will be documented as such in OpenAPI.
+
+///
### Return a `Response`
@@ -65,15 +73,19 @@ As seen in [Return a Response directly](response-directly.md){.internal-link tar
The same example from above, returning an `HTMLResponse`, could look like:
-```Python hl_lines="2 7 19"
-{!../../../docs_src/custom_response/tutorial003.py!}
-```
+{* ../../docs_src/custom_response/tutorial003.py hl[2,7,19] *}
-!!! warning
- A `Response` returned directly by your *path operation function* won't be documented in OpenAPI (for example, the `Content-Type` won't be documented) and won't be visible in the automatic interactive docs.
+/// warning
-!!! info
- Of course, the actual `Content-Type` header, status code, etc, will come from the `Response` object you returned.
+A `Response` returned directly by your *path operation function* won't be documented in OpenAPI (for example, the `Content-Type` won't be documented) and won't be visible in the automatic interactive docs.
+
+///
+
+/// info
+
+Of course, the actual `Content-Type` header, status code, etc, will come from the `Response` object you returned.
+
+///
### Document in OpenAPI and override `Response`
@@ -85,9 +97,7 @@ The `response_class` will then be used only to document the OpenAPI *path operat
For example, it could be something like:
-```Python hl_lines="7 21 23"
-{!../../../docs_src/custom_response/tutorial004.py!}
-```
+{* ../../docs_src/custom_response/tutorial004.py hl[7,21,23] *}
In this example, the function `generate_html_response()` already generates and returns a `Response` instead of returning the HTML in a `str`.
@@ -103,10 +113,13 @@ Here are some of the available responses.
Keep in mind that you can use `Response` to return anything else, or even create a custom sub-class.
-!!! note "Technical Details"
- You could also use `from starlette.responses import HTMLResponse`.
+/// note | Technical Details
- **FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.
+You could also use `from starlette.responses import HTMLResponse`.
+
+**FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.
+
+///
### `Response`
@@ -121,11 +134,9 @@ It accepts the following parameters:
* `headers` - A `dict` of strings.
* `media_type` - A `str` giving the media type. E.g. `"text/html"`.
-FastAPI (actually Starlette) will automatically include a Content-Length header. It will also include a Content-Type header, based on the media_type and appending a charset for text types.
+FastAPI (actually Starlette) will automatically include a Content-Length header. It will also include a Content-Type header, based on the `media_type` and appending a charset for text types.
-```Python hl_lines="1 18"
-{!../../../docs_src/response_directly/tutorial002.py!}
-```
+{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
### `HTMLResponse`
@@ -133,11 +144,9 @@ Takes some text or bytes and returns an HTML response, as you read above.
### `PlainTextResponse`
-Takes some text or bytes and returns an plain text response.
+Takes some text or bytes and returns a plain text response.
-```Python hl_lines="2 7 9"
-{!../../../docs_src/custom_response/tutorial005.py!}
-```
+{* ../../docs_src/custom_response/tutorial005.py hl[2,7,9] *}
### `JSONResponse`
@@ -149,25 +158,35 @@ This is the default response used in **FastAPI**, as you read above.
A fast alternative JSON response using `orjson`, as you read above.
-!!! info
- This requires installing `orjson` for example with `pip install orjson`.
+/// info
+
+This requires installing `orjson` for example with `pip install orjson`.
+
+///
### `UJSONResponse`
An alternative JSON response using `ujson`.
-!!! info
- This requires installing `ujson` for example with `pip install ujson`.
+/// info
-!!! warning
- `ujson` is less careful than Python's built-in implementation in how it handles some edge-cases.
+This requires installing `ujson` for example with `pip install ujson`.
-```Python hl_lines="2 7"
-{!../../../docs_src/custom_response/tutorial001.py!}
-```
+///
-!!! tip
- It's possible that `ORJSONResponse` might be a faster alternative.
+/// warning
+
+`ujson` is less careful than Python's built-in implementation in how it handles some edge-cases.
+
+///
+
+{* ../../docs_src/custom_response/tutorial001.py hl[2,7] *}
+
+/// tip
+
+It's possible that `ORJSONResponse` might be a faster alternative.
+
+///
### `RedirectResponse`
@@ -175,18 +194,14 @@ Returns an HTTP redirect. Uses a 307 status code (Temporary Redirect) by default
You can return a `RedirectResponse` directly:
-```Python hl_lines="2 9"
-{!../../../docs_src/custom_response/tutorial006.py!}
-```
+{* ../../docs_src/custom_response/tutorial006.py hl[2,9] *}
---
Or you can use it in the `response_class` parameter:
-```Python hl_lines="2 7 9"
-{!../../../docs_src/custom_response/tutorial006b.py!}
-```
+{* ../../docs_src/custom_response/tutorial006b.py hl[2,7,9] *}
If you do that, then you can return the URL directly from your *path operation* function.
@@ -196,17 +211,13 @@ In this case, the `status_code` used will be the default one for the `RedirectRe
You can also use the `status_code` parameter combined with the `response_class` parameter:
-```Python hl_lines="2 7 9"
-{!../../../docs_src/custom_response/tutorial006c.py!}
-```
+{* ../../docs_src/custom_response/tutorial006c.py hl[2,7,9] *}
### `StreamingResponse`
Takes an async generator or a normal generator/iterator and streams the response body.
-```Python hl_lines="2 14"
-{!../../../docs_src/custom_response/tutorial007.py!}
-```
+{* ../../docs_src/custom_response/tutorial007.py hl[2,14] *}
#### Using `StreamingResponse` with file-like objects
@@ -216,20 +227,21 @@ That way, you don't have to read it all first in memory, and you can pass that g
This includes many libraries to interact with cloud storage, video processing, and others.
-```{ .python .annotate hl_lines="2 10-12 14" }
-{!../../../docs_src/custom_response/tutorial008.py!}
-```
+{* ../../docs_src/custom_response/tutorial008.py hl[2,10:12,14] *}
1. This is the generator function. It's a "generator function" because it contains `yield` statements inside.
2. By using a `with` block, we make sure that the file-like object is closed after the generator function is done. So, after it finishes sending the response.
-3. This `yield from` tells the function to iterate over that thing named `file_like`. And then, for each part iterated, yield that part as coming from this generator function.
+3. This `yield from` tells the function to iterate over that thing named `file_like`. And then, for each part iterated, yield that part as coming from this generator function (`iterfile`).
So, it is a generator function that transfers the "generating" work to something else internally.
- By doing it this way, we can put it in a `with` block, and that way, ensure that it is closed after finishing.
+ By doing it this way, we can put it in a `with` block, and that way, ensure that the file-like object is closed after finishing.
-!!! tip
- Notice that here as we are using standard `open()` that doesn't support `async` and `await`, we declare the path operation with normal `def`.
+/// tip
+
+Notice that here as we are using standard `open()` that doesn't support `async` and `await`, we declare the path operation with normal `def`.
+
+///
### `FileResponse`
@@ -237,22 +249,18 @@ Asynchronously streams a file as the response.
Takes a different set of arguments to instantiate than the other response types:
-* `path` - The filepath to the file to stream.
+* `path` - The file path to the file to stream.
* `headers` - Any custom headers to include, as a dictionary.
* `media_type` - A string giving the media type. If unset, the filename or path will be used to infer a media type.
* `filename` - If set, this will be included in the response `Content-Disposition`.
File responses will include appropriate `Content-Length`, `Last-Modified` and `ETag` headers.
-```Python hl_lines="2 10"
-{!../../../docs_src/custom_response/tutorial009.py!}
-```
+{* ../../docs_src/custom_response/tutorial009.py hl[2,10] *}
You can also use the `response_class` parameter:
-```Python hl_lines="2 8 10"
-{!../../../docs_src/custom_response/tutorial009b.py!}
-```
+{* ../../docs_src/custom_response/tutorial009b.py hl[2,8,10] *}
In this case, you can return the file path directly from your *path operation* function.
@@ -266,9 +274,7 @@ Let's say you want it to return indented and formatted JSON, so you want to use
You could create a `CustomORJSONResponse`. The main thing you have to do is create a `Response.render(content)` method that returns the content as `bytes`:
-```Python hl_lines="9-14 17"
-{!../../../docs_src/custom_response/tutorial009c.py!}
-```
+{* ../../docs_src/custom_response/tutorial009c.py hl[9:14,17] *}
Now instead of returning:
@@ -294,12 +300,13 @@ The parameter that defines this is `default_response_class`.
In the example below, **FastAPI** will use `ORJSONResponse` by default, in all *path operations*, instead of `JSONResponse`.
-```Python hl_lines="2 4"
-{!../../../docs_src/custom_response/tutorial010.py!}
-```
+{* ../../docs_src/custom_response/tutorial010.py hl[2,4] *}
-!!! tip
- You can still override `response_class` in *path operations* as before.
+/// tip
+
+You can still override `response_class` in *path operations* as before.
+
+///
## Additional documentation
diff --git a/docs/en/docs/advanced/dataclasses.md b/docs/en/docs/advanced/dataclasses.md
index 286e8f93f..2936c6d5d 100644
--- a/docs/en/docs/advanced/dataclasses.md
+++ b/docs/en/docs/advanced/dataclasses.md
@@ -4,9 +4,7 @@ FastAPI is built on top of **Pydantic**, and I have been showing you how to use
But FastAPI also supports using `dataclasses` the same way:
-```Python hl_lines="1 7-12 19-20"
-{!../../../docs_src/dataclasses/tutorial001.py!}
-```
+{* ../../docs_src/dataclasses/tutorial001.py hl[1,7:12,19:20] *}
This is still supported thanks to **Pydantic**, as it has internal support for `dataclasses`.
@@ -20,20 +18,21 @@ And of course, it supports the same:
This works the same way as with Pydantic models. And it is actually achieved in the same way underneath, using Pydantic.
-!!! info
- Keep in mind that dataclasses can't do everything Pydantic models can do.
+/// info
- So, you might still need to use Pydantic models.
+Keep in mind that dataclasses can't do everything Pydantic models can do.
- But if you have a bunch of dataclasses laying around, this is a nice trick to use them to power a web API using FastAPI. 🤓
+So, you might still need to use Pydantic models.
+
+But if you have a bunch of dataclasses laying around, this is a nice trick to use them to power a web API using FastAPI. 🤓
+
+///
## Dataclasses in `response_model`
You can also use `dataclasses` in the `response_model` parameter:
-```Python hl_lines="1 7-13 19"
-{!../../../docs_src/dataclasses/tutorial002.py!}
-```
+{* ../../docs_src/dataclasses/tutorial002.py hl[1,7:13,19] *}
The dataclass will be automatically converted to a Pydantic dataclass.
@@ -49,9 +48,7 @@ In some cases, you might still have to use Pydantic's version of `dataclasses`.
In that case, you can simply swap the standard `dataclasses` with `pydantic.dataclasses`, which is a drop-in replacement:
-```{ .python .annotate hl_lines="1 5 8-11 14-17 23-25 28" }
-{!../../../docs_src/dataclasses/tutorial003.py!}
-```
+{* ../../docs_src/dataclasses/tutorial003.py hl[1,5,8:11,14:17,23:25,28] *}
1. We still import `field` from standard `dataclasses`.
diff --git a/docs/en/docs/advanced/events.md b/docs/en/docs/advanced/events.md
index 703fcb7ae..19465d891 100644
--- a/docs/en/docs/advanced/events.md
+++ b/docs/en/docs/advanced/events.md
@@ -30,26 +30,25 @@ Let's start with an example and then see it in detail.
We create an async function `lifespan()` with `yield` like this:
-```Python hl_lines="16 19"
-{!../../../docs_src/events/tutorial003.py!}
-```
+{* ../../docs_src/events/tutorial003.py hl[16,19] *}
Here we are simulating the expensive *startup* operation of loading the model by putting the (fake) model function in the dictionary with machine learning models before the `yield`. This code will be executed **before** the application **starts taking requests**, during the *startup*.
And then, right after the `yield`, we unload the model. This code will be executed **after** the application **finishes handling requests**, right before the *shutdown*. This could, for example, release resources like memory or a GPU.
-!!! tip
- The `shutdown` would happen when you are **stopping** the application.
+/// tip
- Maybe you need to start a new version, or you just got tired of running it. 🤷
+The `shutdown` would happen when you are **stopping** the application.
+
+Maybe you need to start a new version, or you just got tired of running it. 🤷
+
+///
### Lifespan function
The first thing to notice, is that we are defining an async function with `yield`. This is very similar to Dependencies with `yield`.
-```Python hl_lines="14-19"
-{!../../../docs_src/events/tutorial003.py!}
-```
+{* ../../docs_src/events/tutorial003.py hl[14:19] *}
The first part of the function, before the `yield`, will be executed **before** the application starts.
@@ -61,9 +60,7 @@ If you check, the function is decorated with an `@asynccontextmanager`.
That converts the function into something called an "**async context manager**".
-```Python hl_lines="1 13"
-{!../../../docs_src/events/tutorial003.py!}
-```
+{* ../../docs_src/events/tutorial003.py hl[1,13] *}
A **context manager** in Python is something that you can use in a `with` statement, for example, `open()` can be used as a context manager:
@@ -85,16 +82,17 @@ In our code example above, we don't use it directly, but we pass it to FastAPI f
The `lifespan` parameter of the `FastAPI` app takes an **async context manager**, so we can pass our new `lifespan` async context manager to it.
-```Python hl_lines="22"
-{!../../../docs_src/events/tutorial003.py!}
-```
+{* ../../docs_src/events/tutorial003.py hl[22] *}
## Alternative Events (deprecated)
-!!! warning
- The recommended way to handle the *startup* and *shutdown* is using the `lifespan` parameter of the `FastAPI` app as described above. If you provide a `lifespan` parameter, `startup` and `shutdown` event handlers will no longer be called. It's all `lifespan` or all events, not both.
+/// warning
- You can probably skip this part.
+The recommended way to handle the *startup* and *shutdown* is using the `lifespan` parameter of the `FastAPI` app as described above. If you provide a `lifespan` parameter, `startup` and `shutdown` event handlers will no longer be called. It's all `lifespan` or all events, not both.
+
+You can probably skip this part.
+
+///
There's an alternative way to define this logic to be executed during *startup* and during *shutdown*.
@@ -106,9 +104,7 @@ These functions can be declared with `async def` or normal `def`.
To add a function that should be run before the application starts, declare it with the event `"startup"`:
-```Python hl_lines="8"
-{!../../../docs_src/events/tutorial001.py!}
-```
+{* ../../docs_src/events/tutorial001.py hl[8] *}
In this case, the `startup` event handler function will initialize the items "database" (just a `dict`) with some values.
@@ -120,23 +116,27 @@ And your application won't start receiving requests until all the `startup` even
To add a function that should be run when the application is shutting down, declare it with the event `"shutdown"`:
-```Python hl_lines="6"
-{!../../../docs_src/events/tutorial002.py!}
-```
+{* ../../docs_src/events/tutorial002.py hl[6] *}
Here, the `shutdown` event handler function will write a text line `"Application shutdown"` to a file `log.txt`.
-!!! info
- In the `open()` function, the `mode="a"` means "append", so, the line will be added after whatever is on that file, without overwriting the previous contents.
+/// info
-!!! tip
- Notice that in this case we are using a standard Python `open()` function that interacts with a file.
+In the `open()` function, the `mode="a"` means "append", so, the line will be added after whatever is on that file, without overwriting the previous contents.
- So, it involves I/O (input/output), that requires "waiting" for things to be written to disk.
+///
- But `open()` doesn't use `async` and `await`.
+/// tip
- So, we declare the event handler function with standard `def` instead of `async def`.
+Notice that in this case we are using a standard Python `open()` function that interacts with a file.
+
+So, it involves I/O (input/output), that requires "waiting" for things to be written to disk.
+
+But `open()` doesn't use `async` and `await`.
+
+So, we declare the event handler function with standard `def` instead of `async def`.
+
+///
### `startup` and `shutdown` together
@@ -152,10 +152,13 @@ Just a technical detail for the curious nerds. 🤓
Underneath, in the ASGI technical specification, this is part of the Lifespan Protocol, and it defines events called `startup` and `shutdown`.
-!!! info
- You can read more about the Starlette `lifespan` handlers in Starlette's Lifespan' docs.
+/// info
- Including how to handle lifespan state that can be used in other areas of your code.
+You can read more about the Starlette `lifespan` handlers in Starlette's Lifespan' docs.
+
+Including how to handle lifespan state that can be used in other areas of your code.
+
+///
## Sub Applications
diff --git a/docs/en/docs/advanced/generate-clients.md b/docs/en/docs/advanced/generate-clients.md
index 136ddb064..55e6a08b1 100644
--- a/docs/en/docs/advanced/generate-clients.md
+++ b/docs/en/docs/advanced/generate-clients.md
@@ -20,7 +20,11 @@ Some of them also ✨ [**sponsor FastAPI**](../help-fastapi.md#sponsor-the-autho
And it shows their true commitment to FastAPI and its **community** (you), as they not only want to provide you a **good service** but also want to make sure you have a **good and healthy framework**, FastAPI. 🙇
-For example, you might want to try Speakeasy and Stainless.
+For example, you might want to try:
+
+* Speakeasy
+* Stainless
+* liblab
There are also several other companies offering similar services that you can search and find online. 🤓
@@ -28,17 +32,7 @@ There are also several other companies offering similar services that you can se
Let's start with a simple FastAPI application:
-=== "Python 3.9+"
-
- ```Python hl_lines="7-9 12-13 16-17 21"
- {!> ../../../docs_src/generate_clients/tutorial001_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9-11 14-15 18 19 23"
- {!> ../../../docs_src/generate_clients/tutorial001.py!}
- ```
+{* ../../docs_src/generate_clients/tutorial001_py39.py hl[7:9,12:13,16:17,21] *}
Notice that the *path operations* define the models they use for request payload and response payload, using the models `Item` and `ResponseMessage`.
@@ -123,8 +117,11 @@ You will also get autocompletion for the payload to send:
-!!! tip
- Notice the autocompletion for `name` and `price`, that was defined in the FastAPI application, in the `Item` model.
+/// tip
+
+Notice the autocompletion for `name` and `price`, that was defined in the FastAPI application, in the `Item` model.
+
+///
You will have inline errors for the data that you send:
@@ -140,17 +137,7 @@ In many cases your FastAPI app will be bigger, and you will probably use tags to
For example, you could have a section for **items** and another section for **users**, and they could be separated by tags:
-=== "Python 3.9+"
-
- ```Python hl_lines="21 26 34"
- {!> ../../../docs_src/generate_clients/tutorial002_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="23 28 36"
- {!> ../../../docs_src/generate_clients/tutorial002.py!}
- ```
+{* ../../docs_src/generate_clients/tutorial002_py39.py hl[21,26,34] *}
### Generate a TypeScript Client with Tags
@@ -197,17 +184,7 @@ For example, here it is using the first tag (you will probably have only one tag
You can then pass that custom function to **FastAPI** as the `generate_unique_id_function` parameter:
-=== "Python 3.9+"
-
- ```Python hl_lines="6-7 10"
- {!> ../../../docs_src/generate_clients/tutorial003_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="8-9 12"
- {!> ../../../docs_src/generate_clients/tutorial003.py!}
- ```
+{* ../../docs_src/generate_clients/tutorial003_py39.py hl[6:7,10] *}
### Generate a TypeScript Client with Custom Operation IDs
@@ -229,17 +206,15 @@ But for the generated client we could **modify** the OpenAPI operation IDs right
We could download the OpenAPI JSON to a file `openapi.json` and then we could **remove that prefixed tag** with a script like this:
-=== "Python"
+{* ../../docs_src/generate_clients/tutorial004.py *}
- ```Python
- {!> ../../../docs_src/generate_clients/tutorial004.py!}
- ```
+//// tab | Node.js
-=== "Node.js"
+```Javascript
+{!> ../../docs_src/generate_clients/tutorial004.js!}
+```
- ```Javascript
- {!> ../../../docs_src/generate_clients/tutorial004.js!}
- ```
+////
With that, the operation IDs would be renamed from things like `items-get_items` to just `get_items`, that way the client generator can generate simpler method names.
diff --git a/docs/en/docs/advanced/index.md b/docs/en/docs/advanced/index.md
index 86e42fba0..47385e2c6 100644
--- a/docs/en/docs/advanced/index.md
+++ b/docs/en/docs/advanced/index.md
@@ -6,28 +6,16 @@ The main [Tutorial - User Guide](../tutorial/index.md){.internal-link target=_bl
In the next sections you will see other options, configurations, and additional features.
-!!! tip
- The next sections are **not necessarily "advanced"**.
+/// tip
- And it's possible that for your use case, the solution is in one of them.
+The next sections are **not necessarily "advanced"**.
+
+And it's possible that for your use case, the solution is in one of them.
+
+///
## Read the Tutorial first
You could still use most of the features in **FastAPI** with the knowledge from the main [Tutorial - User Guide](../tutorial/index.md){.internal-link target=_blank}.
And the next sections assume you already read it, and assume that you know those main ideas.
-
-## External Courses
-
-Although the [Tutorial - User Guide](../tutorial/index.md){.internal-link target=_blank} and this **Advanced User Guide** are written as a guided tutorial (like a book) and should be enough for you to **learn FastAPI**, you might want to complement it with additional courses.
-
-Or it might be the case that you just prefer to take other courses because they adapt better to your learning style.
-
-Some course providers ✨ [**sponsor FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨, this ensures the continued and healthy **development** of FastAPI and its **ecosystem**.
-
-And it shows their true commitment to FastAPI and its **community** (you), as they not only want to provide you a **good learning experience** but also want to make sure you have a **good and healthy framework**, FastAPI. 🙇
-
-You might want to try their courses:
-
-* Talk Python Training
-* Test-Driven Development
diff --git a/docs/en/docs/advanced/middleware.md b/docs/en/docs/advanced/middleware.md
index 9219f1d2c..1d40b1c8f 100644
--- a/docs/en/docs/advanced/middleware.md
+++ b/docs/en/docs/advanced/middleware.md
@@ -24,7 +24,7 @@ app = SomeASGIApp()
new_app = UnicornMiddleware(app, some_config="rainbow")
```
-But FastAPI (actually Starlette) provides a simpler way to do it that makes sure that the internal middlewares to handle server errors and custom exception handlers work properly.
+But FastAPI (actually Starlette) provides a simpler way to do it that makes sure that the internal middlewares handle server errors and custom exception handlers work properly.
For that, you use `app.add_middleware()` (as in the example for CORS).
@@ -43,28 +43,27 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow")
**FastAPI** includes several middlewares for common use cases, we'll see next how to use them.
-!!! note "Technical Details"
- For the next examples, you could also use `from starlette.middleware.something import SomethingMiddleware`.
+/// note | Technical Details
- **FastAPI** provides several middlewares in `fastapi.middleware` just as a convenience for you, the developer. But most of the available middlewares come directly from Starlette.
+For the next examples, you could also use `from starlette.middleware.something import SomethingMiddleware`.
+
+**FastAPI** provides several middlewares in `fastapi.middleware` just as a convenience for you, the developer. But most of the available middlewares come directly from Starlette.
+
+///
## `HTTPSRedirectMiddleware`
Enforces that all incoming requests must either be `https` or `wss`.
-Any incoming requests to `http` or `ws` will be redirected to the secure scheme instead.
+Any incoming request to `http` or `ws` will be redirected to the secure scheme instead.
-```Python hl_lines="2 6"
-{!../../../docs_src/advanced_middleware/tutorial001.py!}
-```
+{* ../../docs_src/advanced_middleware/tutorial001.py hl[2,6] *}
## `TrustedHostMiddleware`
Enforces that all incoming requests have a correctly set `Host` header, in order to guard against HTTP Host Header attacks.
-```Python hl_lines="2 6-8"
-{!../../../docs_src/advanced_middleware/tutorial002.py!}
-```
+{* ../../docs_src/advanced_middleware/tutorial002.py hl[2,6:8] *}
The following arguments are supported:
@@ -78,13 +77,12 @@ Handles GZip responses for any request that includes `"gzip"` in the `Accept-Enc
The middleware will handle both standard and streaming responses.
-```Python hl_lines="2 6"
-{!../../../docs_src/advanced_middleware/tutorial003.py!}
-```
+{* ../../docs_src/advanced_middleware/tutorial003.py hl[2,6] *}
The following arguments are supported:
* `minimum_size` - Do not GZip responses that are smaller than this minimum size in bytes. Defaults to `500`.
+* `compresslevel` - Used during GZip compression. It is an integer ranging from 1 to 9. Defaults to `9`. Lower value results in faster compression but larger file sizes, while higher value results in slower compression but smaller file sizes.
## Other middlewares
@@ -92,7 +90,6 @@ There are many other ASGI middlewares.
For example:
-* Sentry
* Uvicorn's `ProxyHeadersMiddleware`
* MessagePack
diff --git a/docs/en/docs/advanced/openapi-callbacks.md b/docs/en/docs/advanced/openapi-callbacks.md
index 1ff51f077..ca9065a89 100644
--- a/docs/en/docs/advanced/openapi-callbacks.md
+++ b/docs/en/docs/advanced/openapi-callbacks.md
@@ -31,12 +31,13 @@ It will have a *path operation* that will receive an `Invoice` body, and a query
This part is pretty normal, most of the code is probably already familiar to you:
-```Python hl_lines="9-13 36-53"
-{!../../../docs_src/openapi_callbacks/tutorial001.py!}
-```
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[9:13,36:53] *}
-!!! tip
- The `callback_url` query parameter uses a Pydantic URL type.
+/// tip
+
+The `callback_url` query parameter uses a Pydantic Url type.
+
+///
The only new thing is the `callbacks=invoices_callback_router.routes` as an argument to the *path operation decorator*. We'll see what that is next.
@@ -61,10 +62,13 @@ That documentation will show up in the Swagger UI at `/docs` in your API, and it
This example doesn't implement the callback itself (that could be just a line of code), only the documentation part.
-!!! tip
- The actual callback is just an HTTP request.
+/// tip
- When implementing the callback yourself, you could use something like HTTPX or Requests.
+The actual callback is just an HTTP request.
+
+When implementing the callback yourself, you could use something like HTTPX or Requests.
+
+///
## Write the callback documentation code
@@ -74,18 +78,19 @@ But, you already know how to easily create automatic documentation for an API wi
So we are going to use that same knowledge to document how the *external API* should look like... by creating the *path operation(s)* that the external API should implement (the ones your API will call).
-!!! tip
- When writing the code to document a callback, it might be useful to imagine that you are that *external developer*. And that you are currently implementing the *external API*, not *your API*.
+/// tip
- Temporarily adopting this point of view (of the *external developer*) can help you feel like it's more obvious where to put the parameters, the Pydantic model for the body, for the response, etc. for that *external API*.
+When writing the code to document a callback, it might be useful to imagine that you are that *external developer*. And that you are currently implementing the *external API*, not *your API*.
+
+Temporarily adopting this point of view (of the *external developer*) can help you feel like it's more obvious where to put the parameters, the Pydantic model for the body, for the response, etc. for that *external API*.
+
+///
### Create a callback `APIRouter`
First create a new `APIRouter` that will contain one or more callbacks.
-```Python hl_lines="3 25"
-{!../../../docs_src/openapi_callbacks/tutorial001.py!}
-```
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[3,25] *}
### Create the callback *path operation*
@@ -96,9 +101,7 @@ It should look just like a normal FastAPI *path operation*:
* It should probably have a declaration of the body it should receive, e.g. `body: InvoiceEvent`.
* And it could also have a declaration of the response it should return, e.g. `response_model=InvoiceEventReceived`.
-```Python hl_lines="16-18 21-22 28-32"
-{!../../../docs_src/openapi_callbacks/tutorial001.py!}
-```
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[16:18,21:22,28:32] *}
There are 2 main differences from a normal *path operation*:
@@ -154,8 +157,11 @@ and it would expect a response from that *external API* with a JSON body like:
}
```
-!!! tip
- Notice how the callback URL used contains the URL received as a query parameter in `callback_url` (`https://www.external.org/events`) and also the invoice `id` from inside of the JSON body (`2expen51ve`).
+/// tip
+
+Notice how the callback URL used contains the URL received as a query parameter in `callback_url` (`https://www.external.org/events`) and also the invoice `id` from inside of the JSON body (`2expen51ve`).
+
+///
### Add the callback router
@@ -163,12 +169,13 @@ At this point you have the *callback path operation(s)* needed (the one(s) that
Now use the parameter `callbacks` in *your API's path operation decorator* to pass the attribute `.routes` (that's actually just a `list` of routes/*path operations*) from that callback router:
-```Python hl_lines="35"
-{!../../../docs_src/openapi_callbacks/tutorial001.py!}
-```
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[35] *}
-!!! tip
- Notice that you are not passing the router itself (`invoices_callback_router`) to `callback=`, but the attribute `.routes`, as in `invoices_callback_router.routes`.
+/// tip
+
+Notice that you are not passing the router itself (`invoices_callback_router`) to `callback=`, but the attribute `.routes`, as in `invoices_callback_router.routes`.
+
+///
### Check the docs
diff --git a/docs/en/docs/advanced/openapi-webhooks.md b/docs/en/docs/advanced/openapi-webhooks.md
index f7f43b357..97aaa41af 100644
--- a/docs/en/docs/advanced/openapi-webhooks.md
+++ b/docs/en/docs/advanced/openapi-webhooks.md
@@ -22,21 +22,25 @@ With **FastAPI**, using OpenAPI, you can define the names of these webhooks, the
This can make it a lot easier for your users to **implement their APIs** to receive your **webhook** requests, they might even be able to autogenerate some of their own API code.
-!!! info
- Webhooks are available in OpenAPI 3.1.0 and above, supported by FastAPI `0.99.0` and above.
+/// info
+
+Webhooks are available in OpenAPI 3.1.0 and above, supported by FastAPI `0.99.0` and above.
+
+///
## An app with webhooks
When you create a **FastAPI** application, there is a `webhooks` attribute that you can use to define *webhooks*, the same way you would define *path operations*, for example with `@app.webhooks.post()`.
-```Python hl_lines="9-13 36-53"
-{!../../../docs_src/openapi_webhooks/tutorial001.py!}
-```
+{* ../../docs_src/openapi_webhooks/tutorial001.py hl[9:13,36:53] *}
The webhooks that you define will end up in the **OpenAPI** schema and the automatic **docs UI**.
-!!! info
- The `app.webhooks` object is actually just an `APIRouter`, the same type you would use when structuring your app with multiple files.
+/// info
+
+The `app.webhooks` object is actually just an `APIRouter`, the same type you would use when structuring your app with multiple files.
+
+///
Notice that with webhooks you are actually not declaring a *path* (like `/items/`), the text you pass there is just an **identifier** of the webhook (the name of the event), for example in `@app.webhooks.post("new-subscription")`, the webhook name is `new-subscription`.
diff --git a/docs/en/docs/advanced/path-operation-advanced-configuration.md b/docs/en/docs/advanced/path-operation-advanced-configuration.md
index 35f7d1b8d..c4814ebd2 100644
--- a/docs/en/docs/advanced/path-operation-advanced-configuration.md
+++ b/docs/en/docs/advanced/path-operation-advanced-configuration.md
@@ -2,16 +2,17 @@
## OpenAPI operationId
-!!! warning
- If you are not an "expert" in OpenAPI, you probably don't need this.
+/// warning
+
+If you are not an "expert" in OpenAPI, you probably don't need this.
+
+///
You can set the OpenAPI `operationId` to be used in your *path operation* with the parameter `operation_id`.
You would have to make sure that it is unique for each operation.
-```Python hl_lines="6"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial001.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial001.py hl[6] *}
### Using the *path operation function* name as the operationId
@@ -19,25 +20,27 @@ If you want to use your APIs' function names as `operationId`s, you can iterate
You should do it after adding all your *path operations*.
-```Python hl_lines="2 12-21 24"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial002.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial002.py hl[2, 12:21, 24] *}
-!!! tip
- If you manually call `app.openapi()`, you should update the `operationId`s before that.
+/// tip
-!!! warning
- If you do this, you have to make sure each one of your *path operation functions* has a unique name.
+If you manually call `app.openapi()`, you should update the `operationId`s before that.
- Even if they are in different modules (Python files).
+///
+
+/// warning
+
+If you do this, you have to make sure each one of your *path operation functions* has a unique name.
+
+Even if they are in different modules (Python files).
+
+///
## Exclude from OpenAPI
To exclude a *path operation* from the generated OpenAPI schema (and thus, from the automatic documentation systems), use the parameter `include_in_schema` and set it to `False`:
-```Python hl_lines="6"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial003.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial003.py hl[6] *}
## Advanced description from docstring
@@ -47,9 +50,7 @@ Adding an `\f` (an escaped "form feed" character) causes **FastAPI** to truncate
It won't show up in the documentation, but other tools (such as Sphinx) will be able to use the rest.
-```Python hl_lines="19-29"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial004.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial004.py hl[19:29] *}
## Additional Responses
@@ -65,8 +66,11 @@ There's a whole chapter here in the documentation about it, you can read it at [
When you declare a *path operation* in your application, **FastAPI** automatically generates the relevant metadata about that *path operation* to be included in the OpenAPI schema.
-!!! note "Technical details"
- In the OpenAPI specification it is called the Operation Object.
+/// note | Technical details
+
+In the OpenAPI specification it is called the Operation Object.
+
+///
It has all the information about the *path operation* and is used to generate the automatic documentation.
@@ -74,10 +78,13 @@ It includes the `tags`, `parameters`, `requestBody`, `responses`, etc.
This *path operation*-specific OpenAPI schema is normally generated automatically by **FastAPI**, but you can also extend it.
-!!! tip
- This is a low level extension point.
+/// tip
- If you only need to declare additional responses, a more convenient way to do it is with [Additional Responses in OpenAPI](additional-responses.md){.internal-link target=_blank}.
+This is a low level extension point.
+
+If you only need to declare additional responses, a more convenient way to do it is with [Additional Responses in OpenAPI](additional-responses.md){.internal-link target=_blank}.
+
+///
You can extend the OpenAPI schema for a *path operation* using the parameter `openapi_extra`.
@@ -85,9 +92,7 @@ You can extend the OpenAPI schema for a *path operation* using the parameter `op
This `openapi_extra` can be helpful, for example, to declare [OpenAPI Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions):
-```Python hl_lines="6"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial005.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial005.py hl[6] *}
If you open the automatic API docs, your extension will show up at the bottom of the specific *path operation*.
@@ -134,9 +139,7 @@ For example, you could decide to read and validate the request with your own cod
You could do that with `openapi_extra`:
-```Python hl_lines="20-37 39-40"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial006.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial006.py hl[19:36, 39:40] *}
In this example, we didn't declare any Pydantic model. In fact, the request body is not even parsed as JSON, it is read directly as `bytes`, and the function `magic_data_reader()` would be in charge of parsing it in some way.
@@ -150,20 +153,23 @@ And you could do this even if the data type in the request is not JSON.
For example, in this application we don't use FastAPI's integrated functionality to extract the JSON Schema from Pydantic models nor the automatic validation for JSON. In fact, we are declaring the request content type as YAML, not JSON:
-=== "Pydantic v2"
+//// tab | Pydantic v2
- ```Python hl_lines="17-22 24"
- {!> ../../../docs_src/path_operation_advanced_configuration/tutorial007.py!}
- ```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[17:22, 24] *}
-=== "Pydantic v1"
+////
- ```Python hl_lines="17-22 24"
- {!> ../../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py!}
- ```
+//// tab | Pydantic v1
-!!! info
- In Pydantic version 1 the method to get the JSON Schema for a model was called `Item.schema()`, in Pydantic version 2, the method is called `Item.model_json_schema()`.
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py hl[17:22, 24] *}
+
+////
+
+/// info
+
+In Pydantic version 1 the method to get the JSON Schema for a model was called `Item.schema()`, in Pydantic version 2, the method is called `Item.model_json_schema()`.
+
+///
Nevertheless, although we are not using the default integrated functionality, we are still using a Pydantic model to manually generate the JSON Schema for the data that we want to receive in YAML.
@@ -171,22 +177,28 @@ Then we use the request directly, and extract the body as `bytes`. This means th
And then in our code, we parse that YAML content directly, and then we are again using the same Pydantic model to validate the YAML content:
-=== "Pydantic v2"
+//// tab | Pydantic v2
- ```Python hl_lines="26-33"
- {!> ../../../docs_src/path_operation_advanced_configuration/tutorial007.py!}
- ```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[26:33] *}
-=== "Pydantic v1"
+////
- ```Python hl_lines="26-33"
- {!> ../../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py!}
- ```
+//// tab | Pydantic v1
-!!! info
- In Pydantic version 1 the method to parse and validate an object was `Item.parse_obj()`, in Pydantic version 2, the method is called `Item.model_validate()`.
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py hl[26:33] *}
-!!! tip
- Here we reuse the same Pydantic model.
+////
- But the same way, we could have validated it in some other way.
+/// info
+
+In Pydantic version 1 the method to parse and validate an object was `Item.parse_obj()`, in Pydantic version 2, the method is called `Item.model_validate()`.
+
+///
+
+/// tip
+
+Here we reuse the same Pydantic model.
+
+But the same way, we could have validated it in some other way.
+
+///
diff --git a/docs/en/docs/advanced/response-change-status-code.md b/docs/en/docs/advanced/response-change-status-code.md
index b88d74a8a..6d3f9f3e8 100644
--- a/docs/en/docs/advanced/response-change-status-code.md
+++ b/docs/en/docs/advanced/response-change-status-code.md
@@ -20,9 +20,7 @@ You can declare a parameter of type `Response` in your *path operation function*
And then you can set the `status_code` in that *temporal* response object.
-```Python hl_lines="1 9 12"
-{!../../../docs_src/response_change_status_code/tutorial001.py!}
-```
+{* ../../docs_src/response_change_status_code/tutorial001.py hl[1,9,12] *}
And then you can return any object you need, as you normally would (a `dict`, a database model, etc).
diff --git a/docs/en/docs/advanced/response-cookies.md b/docs/en/docs/advanced/response-cookies.md
index d53985dbb..f6d17f35d 100644
--- a/docs/en/docs/advanced/response-cookies.md
+++ b/docs/en/docs/advanced/response-cookies.md
@@ -6,9 +6,7 @@ You can declare a parameter of type `Response` in your *path operation function*
And then you can set cookies in that *temporal* response object.
-```Python hl_lines="1 8-9"
-{!../../../docs_src/response_cookies/tutorial002.py!}
-```
+{* ../../docs_src/response_cookies/tutorial002.py hl[1, 8:9] *}
And then you can return any object you need, as you normally would (a `dict`, a database model, etc).
@@ -26,24 +24,28 @@ To do that, you can create a response as described in [Return a Response Directl
Then set Cookies in it, and then return it:
-```Python hl_lines="10-12"
-{!../../../docs_src/response_cookies/tutorial001.py!}
-```
+{* ../../docs_src/response_cookies/tutorial001.py hl[10:12] *}
-!!! tip
- Keep in mind that if you return a response directly instead of using the `Response` parameter, FastAPI will return it directly.
+/// tip
- So, you will have to make sure your data is of the correct type. E.g. it is compatible with JSON, if you are returning a `JSONResponse`.
+Keep in mind that if you return a response directly instead of using the `Response` parameter, FastAPI will return it directly.
- And also that you are not sending any data that should have been filtered by a `response_model`.
+So, you will have to make sure your data is of the correct type. E.g. it is compatible with JSON, if you are returning a `JSONResponse`.
+
+And also that you are not sending any data that should have been filtered by a `response_model`.
+
+///
### More info
-!!! note "Technical Details"
- You could also use `from starlette.responses import Response` or `from starlette.responses import JSONResponse`.
+/// note | Technical Details
- **FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.
+You could also use `from starlette.responses import Response` or `from starlette.responses import JSONResponse`.
- And as the `Response` can be used frequently to set headers and cookies, **FastAPI** also provides it at `fastapi.Response`.
+**FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.
+
+And as the `Response` can be used frequently to set headers and cookies, **FastAPI** also provides it at `fastapi.Response`.
+
+///
To see all the available parameters and options, check the documentation in Starlette.
diff --git a/docs/en/docs/advanced/response-directly.md b/docs/en/docs/advanced/response-directly.md
index 8836140ec..759b762b5 100644
--- a/docs/en/docs/advanced/response-directly.md
+++ b/docs/en/docs/advanced/response-directly.md
@@ -14,8 +14,11 @@ It might be useful, for example, to return custom headers or cookies.
In fact, you can return any `Response` or any sub-class of it.
-!!! tip
- `JSONResponse` itself is a sub-class of `Response`.
+/// tip
+
+`JSONResponse` itself is a sub-class of `Response`.
+
+///
And when you return a `Response`, **FastAPI** will pass it directly.
@@ -25,20 +28,21 @@ This gives you a lot of flexibility. You can return any data type, override any
## Using the `jsonable_encoder` in a `Response`
-Because **FastAPI** doesn't do any change to a `Response` you return, you have to make sure it's contents are ready for it.
+Because **FastAPI** doesn't make any changes to a `Response` you return, you have to make sure its contents are ready for it.
For example, you cannot put a Pydantic model in a `JSONResponse` without first converting it to a `dict` with all the data types (like `datetime`, `UUID`, etc) converted to JSON-compatible types.
For those cases, you can use the `jsonable_encoder` to convert your data before passing it to a response:
-```Python hl_lines="6-7 21-22"
-{!../../../docs_src/response_directly/tutorial001.py!}
-```
+{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *}
-!!! note "Technical Details"
- You could also use `from starlette.responses import JSONResponse`.
+/// note | Technical Details
- **FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.
+You could also use `from starlette.responses import JSONResponse`.
+
+**FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.
+
+///
## Returning a custom `Response`
@@ -48,15 +52,13 @@ Now, let's see how you could use that to return a custom response.
Let's say that you want to return an XML response.
-You could put your XML content in a string, put it in a `Response`, and return it:
+You could put your XML content in a string, put that in a `Response`, and return it:
-```Python hl_lines="1 18"
-{!../../../docs_src/response_directly/tutorial002.py!}
-```
+{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
## Notes
-When you return a `Response` directly its data is not validated, converted (serialized), nor documented automatically.
+When you return a `Response` directly its data is not validated, converted (serialized), or documented automatically.
But you can still document it as described in [Additional Responses in OpenAPI](additional-responses.md){.internal-link target=_blank}.
diff --git a/docs/en/docs/advanced/response-headers.md b/docs/en/docs/advanced/response-headers.md
index 49b5fe476..97e888983 100644
--- a/docs/en/docs/advanced/response-headers.md
+++ b/docs/en/docs/advanced/response-headers.md
@@ -6,9 +6,7 @@ You can declare a parameter of type `Response` in your *path operation function*
And then you can set headers in that *temporal* response object.
-```Python hl_lines="1 7-8"
-{!../../../docs_src/response_headers/tutorial002.py!}
-```
+{* ../../docs_src/response_headers/tutorial002.py hl[1, 7:8] *}
And then you can return any object you need, as you normally would (a `dict`, a database model, etc).
@@ -24,16 +22,17 @@ You can also add headers when you return a `Response` directly.
Create a response as described in [Return a Response Directly](response-directly.md){.internal-link target=_blank} and pass the headers as an additional parameter:
-```Python hl_lines="10-12"
-{!../../../docs_src/response_headers/tutorial001.py!}
-```
+{* ../../docs_src/response_headers/tutorial001.py hl[10:12] *}
-!!! note "Technical Details"
- You could also use `from starlette.responses import Response` or `from starlette.responses import JSONResponse`.
+/// note | Technical Details
- **FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.
+You could also use `from starlette.responses import Response` or `from starlette.responses import JSONResponse`.
- And as the `Response` can be used frequently to set headers and cookies, **FastAPI** also provides it at `fastapi.Response`.
+**FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.
+
+And as the `Response` can be used frequently to set headers and cookies, **FastAPI** also provides it at `fastapi.Response`.
+
+///
## Custom Headers
diff --git a/docs/en/docs/advanced/security/http-basic-auth.md b/docs/en/docs/advanced/security/http-basic-auth.md
index 680f4dff5..234e2f940 100644
--- a/docs/en/docs/advanced/security/http-basic-auth.md
+++ b/docs/en/docs/advanced/security/http-basic-auth.md
@@ -20,26 +20,7 @@ Then, when you type that username and password, the browser sends them in the he
* It returns an object of type `HTTPBasicCredentials`:
* It contains the `username` and `password` sent.
-=== "Python 3.9+"
-
- ```Python hl_lines="4 8 12"
- {!> ../../../docs_src/security/tutorial006_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="2 7 11"
- {!> ../../../docs_src/security/tutorial006_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="2 6 10"
- {!> ../../../docs_src/security/tutorial006.py!}
- ```
+{* ../../docs_src/security/tutorial006_an_py39.py hl[4,8,12] *}
When you try to open the URL for the first time (or click the "Execute" button in the docs) the browser will ask you for your username and password:
@@ -59,26 +40,7 @@ To handle that, we first convert the `username` and `password` to `bytes` encodi
Then we can use `secrets.compare_digest()` to ensure that `credentials.username` is `"stanleyjobson"`, and that `credentials.password` is `"swordfish"`.
-=== "Python 3.9+"
-
- ```Python hl_lines="1 12-24"
- {!> ../../../docs_src/security/tutorial007_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="1 12-24"
- {!> ../../../docs_src/security/tutorial007_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="1 11-21"
- {!> ../../../docs_src/security/tutorial007.py!}
- ```
+{* ../../docs_src/security/tutorial007_an_py39.py hl[1,12:24] *}
This would be similar to:
@@ -126,7 +88,7 @@ And then they can try again knowing that it's probably something more similar to
#### A "professional" attack
-Of course, the attackers would not try all this by hand, they would write a program to do it, possibly with thousands or millions of tests per second. And would get just one extra correct letter at a time.
+Of course, the attackers would not try all this by hand, they would write a program to do it, possibly with thousands or millions of tests per second. And they would get just one extra correct letter at a time.
But doing that, in some minutes or hours the attackers would have guessed the correct username and password, with the "help" of our application, just using the time taken to answer.
@@ -142,23 +104,4 @@ That way, using `secrets.compare_digest()` in your application code, it will be
After detecting that the credentials are incorrect, return an `HTTPException` with a status code 401 (the same returned when no credentials are provided) and add the header `WWW-Authenticate` to make the browser show the login prompt again:
-=== "Python 3.9+"
-
- ```Python hl_lines="26-30"
- {!> ../../../docs_src/security/tutorial007_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="26-30"
- {!> ../../../docs_src/security/tutorial007_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="23-27"
- {!> ../../../docs_src/security/tutorial007.py!}
- ```
+{* ../../docs_src/security/tutorial007_an_py39.py hl[26:30] *}
diff --git a/docs/en/docs/advanced/security/index.md b/docs/en/docs/advanced/security/index.md
index c9ede4231..edb42132e 100644
--- a/docs/en/docs/advanced/security/index.md
+++ b/docs/en/docs/advanced/security/index.md
@@ -4,10 +4,13 @@
There are some extra features to handle security apart from the ones covered in the [Tutorial - User Guide: Security](../../tutorial/security/index.md){.internal-link target=_blank}.
-!!! tip
- The next sections are **not necessarily "advanced"**.
+/// tip
- And it's possible that for your use case, the solution is in one of them.
+The next sections are **not necessarily "advanced"**.
+
+And it's possible that for your use case, the solution is in one of them.
+
+///
## Read the Tutorial first
diff --git a/docs/en/docs/advanced/security/oauth2-scopes.md b/docs/en/docs/advanced/security/oauth2-scopes.md
index 9a9c0dff9..4cb0b39bc 100644
--- a/docs/en/docs/advanced/security/oauth2-scopes.md
+++ b/docs/en/docs/advanced/security/oauth2-scopes.md
@@ -10,18 +10,21 @@ Every time you "log in with" Facebook, Google, GitHub, Microsoft, Twitter, that
In this section you will see how to manage authentication and authorization with the same OAuth2 with scopes in your **FastAPI** application.
-!!! warning
- This is a more or less advanced section. If you are just starting, you can skip it.
+/// warning
- You don't necessarily need OAuth2 scopes, and you can handle authentication and authorization however you want.
+This is a more or less advanced section. If you are just starting, you can skip it.
- But OAuth2 with scopes can be nicely integrated into your API (with OpenAPI) and your API docs.
+You don't necessarily need OAuth2 scopes, and you can handle authentication and authorization however you want.
- Nevertheless, you still enforce those scopes, or any other security/authorization requirement, however you need, in your code.
+But OAuth2 with scopes can be nicely integrated into your API (with OpenAPI) and your API docs.
- In many cases, OAuth2 with scopes can be an overkill.
+Nevertheless, you still enforce those scopes, or any other security/authorization requirement, however you need, in your code.
- But if you know you need it, or you are curious, keep reading.
+In many cases, OAuth2 with scopes can be an overkill.
+
+But if you know you need it, or you are curious, keep reading.
+
+///
## OAuth2 scopes and OpenAPI
@@ -43,63 +46,23 @@ They are normally used to declare specific security permissions, for example:
* `instagram_basic` is used by Facebook / Instagram.
* `https://www.googleapis.com/auth/drive` is used by Google.
-!!! info
- In OAuth2 a "scope" is just a string that declares a specific permission required.
+/// info
- It doesn't matter if it has other characters like `:` or if it is a URL.
+In OAuth2 a "scope" is just a string that declares a specific permission required.
- Those details are implementation specific.
+It doesn't matter if it has other characters like `:` or if it is a URL.
- For OAuth2 they are just strings.
+Those details are implementation specific.
+
+For OAuth2 they are just strings.
+
+///
## Global view
First, let's quickly see the parts that change from the examples in the main **Tutorial - User Guide** for [OAuth2 with Password (and hashing), Bearer with JWT tokens](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank}. Now using OAuth2 scopes:
-=== "Python 3.10+"
-
- ```Python hl_lines="5 9 13 47 65 106 108-116 122-125 129-135 140 156"
- {!> ../../../docs_src/security/tutorial005_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="2 5 9 13 47 65 106 108-116 122-125 129-135 140 156"
- {!> ../../../docs_src/security/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="2 5 9 13 48 66 107 109-117 123-126 130-136 141 157"
- {!> ../../../docs_src/security/tutorial005_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="4 8 12 46 64 105 107-115 121-124 128-134 139 155"
- {!> ../../../docs_src/security/tutorial005_py310.py!}
- ```
-
-=== "Python 3.9+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="2 5 9 13 47 65 106 108-116 122-125 129-135 140 156"
- {!> ../../../docs_src/security/tutorial005_py39.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="2 5 9 13 47 65 106 108-116 122-125 129-135 140 156"
- {!> ../../../docs_src/security/tutorial005.py!}
- ```
+{* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,65,106,108:116,122:125,129:135,140,156] *}
Now let's review those changes step by step.
@@ -109,51 +72,7 @@ The first change is that now we are declaring the OAuth2 security scheme with tw
The `scopes` parameter receives a `dict` with each scope as a key and the description as the value:
-=== "Python 3.10+"
-
- ```Python hl_lines="63-66"
- {!> ../../../docs_src/security/tutorial005_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="63-66"
- {!> ../../../docs_src/security/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="64-67"
- {!> ../../../docs_src/security/tutorial005_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="62-65"
- {!> ../../../docs_src/security/tutorial005_py310.py!}
- ```
-
-
-=== "Python 3.9+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="63-66"
- {!> ../../../docs_src/security/tutorial005_py39.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="63-66"
- {!> ../../../docs_src/security/tutorial005.py!}
- ```
+{* ../../docs_src/security/tutorial005_an_py310.py hl[63:66] *}
Because we are now declaring those scopes, they will show up in the API docs when you log-in/authorize.
@@ -171,55 +90,15 @@ We are still using the same `OAuth2PasswordRequestForm`. It includes a property
And we return the scopes as part of the JWT token.
-!!! danger
- For simplicity, here we are just adding the scopes received directly to the token.
+/// danger
- But in your application, for security, you should make sure you only add the scopes that the user is actually able to have, or the ones you have predefined.
+For simplicity, here we are just adding the scopes received directly to the token.
-=== "Python 3.10+"
+But in your application, for security, you should make sure you only add the scopes that the user is actually able to have, or the ones you have predefined.
- ```Python hl_lines="156"
- {!> ../../../docs_src/security/tutorial005_an_py310.py!}
- ```
+///
-=== "Python 3.9+"
-
- ```Python hl_lines="156"
- {!> ../../../docs_src/security/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="157"
- {!> ../../../docs_src/security/tutorial005_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="155"
- {!> ../../../docs_src/security/tutorial005_py310.py!}
- ```
-
-=== "Python 3.9+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="156"
- {!> ../../../docs_src/security/tutorial005_py39.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="156"
- {!> ../../../docs_src/security/tutorial005.py!}
- ```
+{* ../../docs_src/security/tutorial005_an_py310.py hl[156] *}
## Declare scopes in *path operations* and dependencies
@@ -237,62 +116,25 @@ And the dependency function `get_current_active_user` can also declare sub-depen
In this case, it requires the scope `me` (it could require more than one scope).
-!!! note
- You don't necessarily need to add different scopes in different places.
+/// note
- We are doing it here to demonstrate how **FastAPI** handles scopes declared at different levels.
+You don't necessarily need to add different scopes in different places.
-=== "Python 3.10+"
+We are doing it here to demonstrate how **FastAPI** handles scopes declared at different levels.
- ```Python hl_lines="5 140 171"
- {!> ../../../docs_src/security/tutorial005_an_py310.py!}
- ```
+///
-=== "Python 3.9+"
+{* ../../docs_src/security/tutorial005_an_py310.py hl[5,140,171] *}
- ```Python hl_lines="5 140 171"
- {!> ../../../docs_src/security/tutorial005_an_py39.py!}
- ```
+/// info | Technical Details
-=== "Python 3.8+"
+`Security` is actually a subclass of `Depends`, and it has just one extra parameter that we'll see later.
- ```Python hl_lines="5 141 172"
- {!> ../../../docs_src/security/tutorial005_an.py!}
- ```
+But by using `Security` instead of `Depends`, **FastAPI** will know that it can declare security scopes, use them internally, and document the API with OpenAPI.
-=== "Python 3.10+ non-Annotated"
+But when you import `Query`, `Path`, `Depends`, `Security` and others from `fastapi`, those are actually functions that return special classes.
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="4 139 168"
- {!> ../../../docs_src/security/tutorial005_py310.py!}
- ```
-
-=== "Python 3.9+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="5 140 169"
- {!> ../../../docs_src/security/tutorial005_py39.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="5 140 169"
- {!> ../../../docs_src/security/tutorial005.py!}
- ```
-
-!!! info "Technical Details"
- `Security` is actually a subclass of `Depends`, and it has just one extra parameter that we'll see later.
-
- But by using `Security` instead of `Depends`, **FastAPI** will know that it can declare security scopes, use them internally, and document the API with OpenAPI.
-
- But when you import `Query`, `Path`, `Depends`, `Security` and others from `fastapi`, those are actually functions that return special classes.
+///
## Use `SecurityScopes`
@@ -300,7 +142,7 @@ Now update the dependency `get_current_user`.
This is the one used by the dependencies above.
-Here's were we are using the same OAuth2 scheme we created before, declaring it as a dependency: `oauth2_scheme`.
+Here's where we are using the same OAuth2 scheme we created before, declaring it as a dependency: `oauth2_scheme`.
Because this dependency function doesn't have any scope requirements itself, we can use `Depends` with `oauth2_scheme`, we don't have to use `Security` when we don't need to specify security scopes.
@@ -308,50 +150,7 @@ We also declare a special parameter of type `SecurityScopes`, imported from `fas
This `SecurityScopes` class is similar to `Request` (`Request` was used to get the request object directly).
-=== "Python 3.10+"
-
- ```Python hl_lines="9 106"
- {!> ../../../docs_src/security/tutorial005_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="9 106"
- {!> ../../../docs_src/security/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9 107"
- {!> ../../../docs_src/security/tutorial005_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="8 105"
- {!> ../../../docs_src/security/tutorial005_py310.py!}
- ```
-
-=== "Python 3.9+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="9 106"
- {!> ../../../docs_src/security/tutorial005_py39.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="9 106"
- {!> ../../../docs_src/security/tutorial005.py!}
- ```
+{* ../../docs_src/security/tutorial005_an_py310.py hl[9,106] *}
## Use the `scopes`
@@ -365,50 +164,7 @@ We create an `HTTPException` that we can reuse (`raise`) later at several points
In this exception, we include the scopes required (if any) as a string separated by spaces (using `scope_str`). We put that string containing the scopes in the `WWW-Authenticate` header (this is part of the spec).
-=== "Python 3.10+"
-
- ```Python hl_lines="106 108-116"
- {!> ../../../docs_src/security/tutorial005_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="106 108-116"
- {!> ../../../docs_src/security/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="107 109-117"
- {!> ../../../docs_src/security/tutorial005_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="105 107-115"
- {!> ../../../docs_src/security/tutorial005_py310.py!}
- ```
-
-=== "Python 3.9+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="106 108-116"
- {!> ../../../docs_src/security/tutorial005_py39.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="106 108-116"
- {!> ../../../docs_src/security/tutorial005.py!}
- ```
+{* ../../docs_src/security/tutorial005_an_py310.py hl[106,108:116] *}
## Verify the `username` and data shape
@@ -424,50 +180,7 @@ Instead of, for example, a `dict`, or something else, as it could break the appl
We also verify that we have a user with that username, and if not, we raise that same exception we created before.
-=== "Python 3.10+"
-
- ```Python hl_lines="47 117-128"
- {!> ../../../docs_src/security/tutorial005_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="47 117-128"
- {!> ../../../docs_src/security/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="48 118-129"
- {!> ../../../docs_src/security/tutorial005_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="46 116-127"
- {!> ../../../docs_src/security/tutorial005_py310.py!}
- ```
-
-=== "Python 3.9+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="47 117-128"
- {!> ../../../docs_src/security/tutorial005_py39.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="47 117-128"
- {!> ../../../docs_src/security/tutorial005.py!}
- ```
+{* ../../docs_src/security/tutorial005_an_py310.py hl[47,117:128] *}
## Verify the `scopes`
@@ -475,50 +188,7 @@ We now verify that all the scopes required, by this dependency and all the depen
For this, we use `security_scopes.scopes`, that contains a `list` with all these scopes as `str`.
-=== "Python 3.10+"
-
- ```Python hl_lines="129-135"
- {!> ../../../docs_src/security/tutorial005_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="129-135"
- {!> ../../../docs_src/security/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="130-136"
- {!> ../../../docs_src/security/tutorial005_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="128-134"
- {!> ../../../docs_src/security/tutorial005_py310.py!}
- ```
-
-=== "Python 3.9+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="129-135"
- {!> ../../../docs_src/security/tutorial005_py39.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="129-135"
- {!> ../../../docs_src/security/tutorial005.py!}
- ```
+{* ../../docs_src/security/tutorial005_an_py310.py hl[129:135] *}
## Dependency tree and scopes
@@ -543,12 +213,15 @@ Here's how the hierarchy of dependencies and scopes looks like:
* This `security_scopes` parameter has a property `scopes` with a `list` containing all these scopes declared above, so:
* `security_scopes.scopes` will contain `["me", "items"]` for the *path operation* `read_own_items`.
* `security_scopes.scopes` will contain `["me"]` for the *path operation* `read_users_me`, because it is declared in the dependency `get_current_active_user`.
- * `security_scopes.scopes` will contain `[]` (nothing) for the *path operation* `read_system_status`, because it didn't declare any `Security` with `scopes`, and its dependency, `get_current_user`, doesn't declare any `scope` either.
+ * `security_scopes.scopes` will contain `[]` (nothing) for the *path operation* `read_system_status`, because it didn't declare any `Security` with `scopes`, and its dependency, `get_current_user`, doesn't declare any `scopes` either.
-!!! tip
- The important and "magic" thing here is that `get_current_user` will have a different list of `scopes` to check for each *path operation*.
+/// tip
- All depending on the `scopes` declared in each *path operation* and each dependency in the dependency tree for that specific *path operation*.
+The important and "magic" thing here is that `get_current_user` will have a different list of `scopes` to check for each *path operation*.
+
+All depending on the `scopes` declared in each *path operation* and each dependency in the dependency tree for that specific *path operation*.
+
+///
## More details about `SecurityScopes`
@@ -584,12 +257,15 @@ But if you are building an OAuth2 application that others would connect to (i.e.
The most common is the implicit flow.
-The most secure is the code flow, but is more complex to implement as it requires more steps. As it is more complex, many providers end up suggesting the implicit flow.
+The most secure is the code flow, but it's more complex to implement as it requires more steps. As it is more complex, many providers end up suggesting the implicit flow.
-!!! note
- It's common that each authentication provider names their flows in a different way, to make it part of their brand.
+/// note
- But in the end, they are implementing the same OAuth2 standard.
+It's common that each authentication provider names their flows in a different way, to make it part of their brand.
+
+But in the end, they are implementing the same OAuth2 standard.
+
+///
**FastAPI** includes utilities for all these OAuth2 authentication flows in `fastapi.security.oauth2`.
diff --git a/docs/en/docs/advanced/settings.md b/docs/en/docs/advanced/settings.md
index 56af4f441..1af19a045 100644
--- a/docs/en/docs/advanced/settings.md
+++ b/docs/en/docs/advanced/settings.md
@@ -6,130 +6,25 @@ Most of these settings are variable (can change), like database URLs. And many c
For this reason it's common to provide them in environment variables that are read by the application.
-## Environment Variables
+/// tip
-!!! tip
- If you already know what "environment variables" are and how to use them, feel free to skip to the next section below.
+To understand environment variables you can read [Environment Variables](../environment-variables.md){.internal-link target=_blank}.
-An environment variable (also known as "env var") is a variable that lives outside of the Python code, in the operating system, and could be read by your Python code (or by other programs as well).
+///
-You can create and use environment variables in the shell, without needing Python:
-
-=== "Linux, macOS, Windows Bash"
-
-
-!!! info
- Beautiful illustrations by Ketrina Thompson. 🎨
+/// info
+
+Beautiful illustrations by Ketrina Thompson. 🎨
+
+///
---
@@ -199,8 +205,11 @@ You just eat them, and you are done. ⏹
There was not much talk or flirting as most of the time was spent waiting 🕙 in front of the counter. 😞
-!!! info
- Beautiful illustrations by Ketrina Thompson. 🎨
+/// info
+
+Beautiful illustrations by Ketrina Thompson. 🎨
+
+///
---
@@ -283,7 +292,7 @@ For example:
### Concurrency + Parallelism: Web + Machine Learning
-With **FastAPI** you can take the advantage of concurrency that is very common for web development (the same main attraction of NodeJS).
+With **FastAPI** you can take advantage of concurrency that is very common for web development (the same main attraction of NodeJS).
But you can also exploit the benefits of parallelism and multiprocessing (having multiple processes running in parallel) for **CPU bound** workloads like those in Machine Learning systems.
@@ -360,6 +369,8 @@ In particular, you can directly use AnyIO to be highly compatible and get its benefits (e.g. *structured concurrency*).
+I created another library on top of AnyIO, as a thin layer on top, to improve a bit the type annotations and get better **autocompletion**, **inline errors**, etc. It also has a friendly introduction and tutorial to help you **understand** and write **your own async code**: Asyncer. It would be particularly useful if you need to **combine async code with regular** (blocking/synchronous) code.
+
### Other forms of asynchronous code
This style of using `async` and `await` is relatively new in the language.
@@ -376,7 +387,7 @@ In previous versions of NodeJS / Browser JavaScript, you would have used "callba
## Coroutines
-**Coroutine** is just the very fancy term for the thing returned by an `async def` function. Python knows that it is something like a function that it can start and that it will end at some point, but that it might be paused ⏸ internally too, whenever there is an `await` inside of it.
+**Coroutine** is just the very fancy term for the thing returned by an `async def` function. Python knows that it is something like a function, that it can start and that it will end at some point, but that it might be paused ⏸ internally too, whenever there is an `await` inside of it.
But all this functionality of using asynchronous code with `async` and `await` is many times summarized as using "coroutines". It is comparable to the main key feature of Go, the "Goroutines".
@@ -392,12 +403,15 @@ All that is what powers FastAPI (through Starlette) and what makes it have such
## Very Technical Details
-!!! warning
- You can probably skip this.
+/// warning
- These are very technical details of how **FastAPI** works underneath.
+You can probably skip this.
- If you have quite some technical knowledge (coroutines, threads, blocking, etc.) and are curious about how FastAPI handles `async def` vs normal `def`, go ahead.
+These are very technical details of how **FastAPI** works underneath.
+
+If you have quite some technical knowledge (coroutines, threads, blocking, etc.) and are curious about how FastAPI handles `async def` vs normal `def`, go ahead.
+
+///
### Path operation functions
diff --git a/docs/en/docs/contributing.md b/docs/en/docs/contributing.md
index d7ec25dea..1b70a0ea9 100644
--- a/docs/en/docs/contributing.md
+++ b/docs/en/docs/contributing.md
@@ -6,104 +6,13 @@ First, you might want to see the basic ways to [help FastAPI and get help](help-
If you already cloned the fastapi repository and you want to deep dive in the code, here are some guidelines to set up your environment.
-### Virtual environment with `venv`
+### Virtual environment
-You can create an isolated virtual local environment in a directory using Python's `venv` module. Let's do this in the cloned repository (where the `requirements.txt` is):
-
-
-
-## More info
-
-You can read more about `encode/databases` at its GitHub page.
diff --git a/docs/en/docs/how-to/conditional-openapi.md b/docs/en/docs/how-to/conditional-openapi.md
index add16fbec..bd6cad9a8 100644
--- a/docs/en/docs/how-to/conditional-openapi.md
+++ b/docs/en/docs/how-to/conditional-openapi.md
@@ -29,9 +29,7 @@ You can easily use the same Pydantic settings to configure your generated OpenAP
For example:
-```Python hl_lines="6 11"
-{!../../../docs_src/conditional_openapi/tutorial001.py!}
-```
+{* ../../docs_src/conditional_openapi/tutorial001.py hl[6,11] *}
Here we declare the setting `openapi_url` with the same default of `"/openapi.json"`.
diff --git a/docs/en/docs/how-to/configure-swagger-ui.md b/docs/en/docs/how-to/configure-swagger-ui.md
index 108afb929..a8a8de48f 100644
--- a/docs/en/docs/how-to/configure-swagger-ui.md
+++ b/docs/en/docs/how-to/configure-swagger-ui.md
@@ -1,6 +1,6 @@
# Configure Swagger UI
-You can configure some extra Swagger UI parameters.
+You can configure some extra Swagger UI parameters.
To configure them, pass the `swagger_ui_parameters` argument when creating the `FastAPI()` app object or to the `get_swagger_ui_html()` function.
@@ -18,9 +18,7 @@ Without changing the settings, syntax highlighting is enabled by default:
But you can disable it by setting `syntaxHighlight` to `False`:
-```Python hl_lines="3"
-{!../../../docs_src/configure_swagger_ui/tutorial001.py!}
-```
+{* ../../docs_src/configure_swagger_ui/tutorial001.py hl[3] *}
...and then Swagger UI won't show the syntax highlighting anymore:
@@ -30,9 +28,7 @@ But you can disable it by setting `syntaxHighlight` to `False`:
The same way you could set the syntax highlighting theme with the key `"syntaxHighlight.theme"` (notice that it has a dot in the middle):
-```Python hl_lines="3"
-{!../../../docs_src/configure_swagger_ui/tutorial002.py!}
-```
+{* ../../docs_src/configure_swagger_ui/tutorial002.py hl[3] *}
That configuration would change the syntax highlighting color theme:
@@ -44,21 +40,17 @@ FastAPI includes some default configuration parameters appropriate for most of t
It includes these default configurations:
-```Python
-{!../../../fastapi/openapi/docs.py[ln:7-23]!}
-```
+{* ../../fastapi/openapi/docs.py ln[8:23] hl[17:23] *}
You can override any of them by setting a different value in the argument `swagger_ui_parameters`.
For example, to disable `deepLinking` you could pass these settings to `swagger_ui_parameters`:
-```Python hl_lines="3"
-{!../../../docs_src/configure_swagger_ui/tutorial003.py!}
-```
+{* ../../docs_src/configure_swagger_ui/tutorial003.py hl[3] *}
## Other Swagger UI Parameters
-To see all the other possible configurations you can use, read the official docs for Swagger UI parameters.
+To see all the other possible configurations you can use, read the official docs for Swagger UI parameters.
## JavaScript-only settings
diff --git a/docs/en/docs/how-to/custom-docs-ui-assets.md b/docs/en/docs/how-to/custom-docs-ui-assets.md
index 053e5eacd..9d2238e4f 100644
--- a/docs/en/docs/how-to/custom-docs-ui-assets.md
+++ b/docs/en/docs/how-to/custom-docs-ui-assets.md
@@ -18,9 +18,7 @@ The first step is to disable the automatic docs, as by default, those use the de
To disable them, set their URLs to `None` when creating your `FastAPI` app:
-```Python hl_lines="8"
-{!../../../docs_src/custom_docs_ui/tutorial001.py!}
-```
+{* ../../docs_src/custom_docs_ui/tutorial001.py hl[8] *}
### Include the custom docs
@@ -36,24 +34,23 @@ You can reuse FastAPI's internal functions to create the HTML pages for the docs
And similarly for ReDoc...
-```Python hl_lines="2-6 11-19 22-24 27-33"
-{!../../../docs_src/custom_docs_ui/tutorial001.py!}
-```
+{* ../../docs_src/custom_docs_ui/tutorial001.py hl[2:6,11:19,22:24,27:33] *}
-!!! tip
- The *path operation* for `swagger_ui_redirect` is a helper for when you use OAuth2.
+/// tip
- If you integrate your API with an OAuth2 provider, you will be able to authenticate and come back to the API docs with the acquired credentials. And interact with it using the real OAuth2 authentication.
+The *path operation* for `swagger_ui_redirect` is a helper for when you use OAuth2.
- Swagger UI will handle it behind the scenes for you, but it needs this "redirect" helper.
+If you integrate your API with an OAuth2 provider, you will be able to authenticate and come back to the API docs with the acquired credentials. And interact with it using the real OAuth2 authentication.
+
+Swagger UI will handle it behind the scenes for you, but it needs this "redirect" helper.
+
+///
### Create a *path operation* to test it
Now, to be able to test that everything works, create a *path operation*:
-```Python hl_lines="36-38"
-{!../../../docs_src/custom_docs_ui/tutorial001.py!}
-```
+{* ../../docs_src/custom_docs_ui/tutorial001.py hl[36:38] *}
### Test it
@@ -101,7 +98,7 @@ You can probably right-click each link and select an option similar to `Save lin
And **ReDoc** uses the file:
-* `redoc.standalone.js`
+* `redoc.standalone.js`
After that, your file structure could look like:
@@ -121,9 +118,7 @@ After that, your file structure could look like:
* Import `StaticFiles`.
* "Mount" a `StaticFiles()` instance in a specific path.
-```Python hl_lines="7 11"
-{!../../../docs_src/custom_docs_ui/tutorial002.py!}
-```
+{* ../../docs_src/custom_docs_ui/tutorial002.py hl[7,11] *}
### Test the static files
@@ -134,14 +129,8 @@ You should see a very long JavaScript file for **ReDoc**.
It could start with something like:
```JavaScript
-/*!
- * ReDoc - OpenAPI/Swagger-generated API Reference Documentation
- * -------------------------------------------------------------
- * Version: "2.0.0-rc.18"
- * Repo: https://github.com/Redocly/redoc
- */
-!function(e,t){"object"==typeof exports&&"object"==typeof m
-
+/*! For license information please see redoc.standalone.js.LICENSE.txt */
+!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t(require("null")):
...
```
@@ -155,9 +144,7 @@ The same as when using a custom CDN, the first step is to disable the automatic
To disable them, set their URLs to `None` when creating your `FastAPI` app:
-```Python hl_lines="9"
-{!../../../docs_src/custom_docs_ui/tutorial002.py!}
-```
+{* ../../docs_src/custom_docs_ui/tutorial002.py hl[9] *}
### Include the custom docs for static files
@@ -173,24 +160,23 @@ Again, you can reuse FastAPI's internal functions to create the HTML pages for t
And similarly for ReDoc...
-```Python hl_lines="2-6 14-22 25-27 30-36"
-{!../../../docs_src/custom_docs_ui/tutorial002.py!}
-```
+{* ../../docs_src/custom_docs_ui/tutorial002.py hl[2:6,14:22,25:27,30:36] *}
-!!! tip
- The *path operation* for `swagger_ui_redirect` is a helper for when you use OAuth2.
+/// tip
- If you integrate your API with an OAuth2 provider, you will be able to authenticate and come back to the API docs with the acquired credentials. And interact with it using the real OAuth2 authentication.
+The *path operation* for `swagger_ui_redirect` is a helper for when you use OAuth2.
- Swagger UI will handle it behind the scenes for you, but it needs this "redirect" helper.
+If you integrate your API with an OAuth2 provider, you will be able to authenticate and come back to the API docs with the acquired credentials. And interact with it using the real OAuth2 authentication.
+
+Swagger UI will handle it behind the scenes for you, but it needs this "redirect" helper.
+
+///
### Create a *path operation* to test static files
Now, to be able to test that everything works, create a *path operation*:
-```Python hl_lines="39-41"
-{!../../../docs_src/custom_docs_ui/tutorial002.py!}
-```
+{* ../../docs_src/custom_docs_ui/tutorial002.py hl[39:41] *}
### Test Static Files UI
diff --git a/docs/en/docs/how-to/custom-request-and-route.md b/docs/en/docs/how-to/custom-request-and-route.md
index 3b9435004..9b4160d75 100644
--- a/docs/en/docs/how-to/custom-request-and-route.md
+++ b/docs/en/docs/how-to/custom-request-and-route.md
@@ -6,10 +6,13 @@ In particular, this may be a good alternative to logic in a middleware.
For example, if you want to read or manipulate the request body before it is processed by your application.
-!!! danger
- This is an "advanced" feature.
+/// danger
- If you are just starting with **FastAPI** you might want to skip this section.
+This is an "advanced" feature.
+
+If you are just starting with **FastAPI** you might want to skip this section.
+
+///
## Use cases
@@ -27,8 +30,11 @@ And an `APIRoute` subclass to use that custom request class.
### Create a custom `GzipRequest` class
-!!! tip
- This is a toy example to demonstrate how it works, if you need Gzip support, you can use the provided [`GzipMiddleware`](../advanced/middleware.md#gzipmiddleware){.internal-link target=_blank}.
+/// tip
+
+This is a toy example to demonstrate how it works, if you need Gzip support, you can use the provided [`GzipMiddleware`](../advanced/middleware.md#gzipmiddleware){.internal-link target=_blank}.
+
+///
First, we create a `GzipRequest` class, which will overwrite the `Request.body()` method to decompress the body in the presence of an appropriate header.
@@ -36,9 +42,7 @@ If there's no `gzip` in the header, it will not try to decompress the body.
That way, the same route class can handle gzip compressed or uncompressed requests.
-```Python hl_lines="8-15"
-{!../../../docs_src/custom_request_and_route/tutorial001.py!}
-```
+{* ../../docs_src/custom_request_and_route/tutorial001.py hl[8:15] *}
### Create a custom `GzipRoute` class
@@ -50,20 +54,21 @@ This method returns a function. And that function is what will receive a request
Here we use it to create a `GzipRequest` from the original request.
-```Python hl_lines="18-26"
-{!../../../docs_src/custom_request_and_route/tutorial001.py!}
-```
+{* ../../docs_src/custom_request_and_route/tutorial001.py hl[18:26] *}
-!!! note "Technical Details"
- A `Request` has a `request.scope` attribute, that's just a Python `dict` containing the metadata related to the request.
+/// note | Technical Details
- A `Request` also has a `request.receive`, that's a function to "receive" the body of the request.
+A `Request` has a `request.scope` attribute, that's just a Python `dict` containing the metadata related to the request.
- The `scope` `dict` and `receive` function are both part of the ASGI specification.
+A `Request` also has a `request.receive`, that's a function to "receive" the body of the request.
- And those two things, `scope` and `receive`, are what is needed to create a new `Request` instance.
+The `scope` `dict` and `receive` function are both part of the ASGI specification.
- To learn more about the `Request` check Starlette's docs about Requests.
+And those two things, `scope` and `receive`, are what is needed to create a new `Request` instance.
+
+To learn more about the `Request` check Starlette's docs about Requests.
+
+///
The only thing the function returned by `GzipRequest.get_route_handler` does differently is convert the `Request` to a `GzipRequest`.
@@ -75,35 +80,30 @@ But because of our changes in `GzipRequest.body`, the request body will be autom
## Accessing the request body in an exception handler
-!!! tip
- To solve this same problem, it's probably a lot easier to use the `body` in a custom handler for `RequestValidationError` ([Handling Errors](../tutorial/handling-errors.md#use-the-requestvalidationerror-body){.internal-link target=_blank}).
+/// tip
- But this example is still valid and it shows how to interact with the internal components.
+To solve this same problem, it's probably a lot easier to use the `body` in a custom handler for `RequestValidationError` ([Handling Errors](../tutorial/handling-errors.md#use-the-requestvalidationerror-body){.internal-link target=_blank}).
+
+But this example is still valid and it shows how to interact with the internal components.
+
+///
We can also use this same approach to access the request body in an exception handler.
All we need to do is handle the request inside a `try`/`except` block:
-```Python hl_lines="13 15"
-{!../../../docs_src/custom_request_and_route/tutorial002.py!}
-```
+{* ../../docs_src/custom_request_and_route/tutorial002.py hl[13,15] *}
If an exception occurs, the`Request` instance will still be in scope, so we can read and make use of the request body when handling the error:
-```Python hl_lines="16-18"
-{!../../../docs_src/custom_request_and_route/tutorial002.py!}
-```
+{* ../../docs_src/custom_request_and_route/tutorial002.py hl[16:18] *}
## Custom `APIRoute` class in a router
You can also set the `route_class` parameter of an `APIRouter`:
-```Python hl_lines="26"
-{!../../../docs_src/custom_request_and_route/tutorial003.py!}
-```
+{* ../../docs_src/custom_request_and_route/tutorial003.py hl[26] *}
In this example, the *path operations* under the `router` will use the custom `TimedRoute` class, and will have an extra `X-Response-Time` header in the response with the time it took to generate the response:
-```Python hl_lines="13-20"
-{!../../../docs_src/custom_request_and_route/tutorial003.py!}
-```
+{* ../../docs_src/custom_request_and_route/tutorial003.py hl[13:20] *}
diff --git a/docs/en/docs/how-to/extending-openapi.md b/docs/en/docs/how-to/extending-openapi.md
index a18fd737e..26c742c20 100644
--- a/docs/en/docs/how-to/extending-openapi.md
+++ b/docs/en/docs/how-to/extending-openapi.md
@@ -27,8 +27,11 @@ And that function `get_openapi()` receives as parameters:
* `description`: The description of your API, this can include markdown and will be shown in the docs.
* `routes`: A list of routes, these are each of the registered *path operations*. They are taken from `app.routes`.
-!!! info
- The parameter `summary` is available in OpenAPI 3.1.0 and above, supported by FastAPI 0.99.0 and above.
+/// info
+
+The parameter `summary` is available in OpenAPI 3.1.0 and above, supported by FastAPI 0.99.0 and above.
+
+///
## Overriding the defaults
@@ -40,25 +43,19 @@ For example, let's add Strawberry documentation.
@@ -46,8 +47,11 @@ Previous versions of Starlette included a `GraphQLApp` class to integrate with <
It was deprecated from Starlette, but if you have code that used it, you can easily **migrate** to starlette-graphene3, that covers the same use case and has an **almost identical interface**.
-!!! tip
- If you need GraphQL, I still would recommend you check out Strawberry, as it's based on type annotations instead of custom classes and types.
+/// tip
+
+If you need GraphQL, I still would recommend you check out Strawberry, as it's based on type annotations instead of custom classes and types.
+
+///
## Learn More
diff --git a/docs/en/docs/how-to/index.md b/docs/en/docs/how-to/index.md
index ec7fd38f8..730dce5d5 100644
--- a/docs/en/docs/how-to/index.md
+++ b/docs/en/docs/how-to/index.md
@@ -6,6 +6,8 @@ Most of these ideas would be more or less **independent**, and in most cases you
If something seems interesting and useful to your project, go ahead and check it, but otherwise, you might probably just skip them.
-!!! tip
+/// tip
- If you want to **learn FastAPI** in a structured way (recommended), go and read the [Tutorial - User Guide](../tutorial/index.md){.internal-link target=_blank} chapter by chapter instead.
+If you want to **learn FastAPI** in a structured way (recommended), go and read the [Tutorial - User Guide](../tutorial/index.md){.internal-link target=_blank} chapter by chapter instead.
+
+///
diff --git a/docs/en/docs/how-to/nosql-databases-couchbase.md b/docs/en/docs/how-to/nosql-databases-couchbase.md
deleted file mode 100644
index 18e3f4b7e..000000000
--- a/docs/en/docs/how-to/nosql-databases-couchbase.md
+++ /dev/null
@@ -1,166 +0,0 @@
-# ~~NoSQL (Distributed / Big Data) Databases with Couchbase~~ (deprecated)
-
-!!! info
- These docs are about to be updated. 🎉
-
- The current version assumes Pydantic v1.
-
- The new docs will hopefully use Pydantic v2 and will use ODMantic with MongoDB.
-
-!!! warning "Deprecated"
- This tutorial is deprecated and will be removed in a future version.
-
-**FastAPI** can also be integrated with any NoSQL.
-
-Here we'll see an example using **Couchbase**, a document based NoSQL database.
-
-You can adapt it to any other NoSQL database like:
-
-* **MongoDB**
-* **Cassandra**
-* **CouchDB**
-* **ArangoDB**
-* **ElasticSearch**, etc.
-
-!!! tip
- There is an official project generator with **FastAPI** and **Couchbase**, all based on **Docker**, including a frontend and more tools: https://github.com/tiangolo/full-stack-fastapi-couchbase
-
-## Import Couchbase components
-
-For now, don't pay attention to the rest, only the imports:
-
-```Python hl_lines="3-5"
-{!../../../docs_src/nosql_databases/tutorial001.py!}
-```
-
-## Define a constant to use as a "document type"
-
-We will use it later as a fixed field `type` in our documents.
-
-This is not required by Couchbase, but is a good practice that will help you afterwards.
-
-```Python hl_lines="9"
-{!../../../docs_src/nosql_databases/tutorial001.py!}
-```
-
-## Add a function to get a `Bucket`
-
-In **Couchbase**, a bucket is a set of documents, that can be of different types.
-
-They are generally all related to the same application.
-
-The analogy in the relational database world would be a "database" (a specific database, not the database server).
-
-The analogy in **MongoDB** would be a "collection".
-
-In the code, a `Bucket` represents the main entrypoint of communication with the database.
-
-This utility function will:
-
-* Connect to a **Couchbase** cluster (that might be a single machine).
- * Set defaults for timeouts.
-* Authenticate in the cluster.
-* Get a `Bucket` instance.
- * Set defaults for timeouts.
-* Return it.
-
-```Python hl_lines="12-21"
-{!../../../docs_src/nosql_databases/tutorial001.py!}
-```
-
-## Create Pydantic models
-
-As **Couchbase** "documents" are actually just "JSON objects", we can model them with Pydantic.
-
-### `User` model
-
-First, let's create a `User` model:
-
-```Python hl_lines="24-28"
-{!../../../docs_src/nosql_databases/tutorial001.py!}
-```
-
-We will use this model in our *path operation function*, so, we don't include in it the `hashed_password`.
-
-### `UserInDB` model
-
-Now, let's create a `UserInDB` model.
-
-This will have the data that is actually stored in the database.
-
-We don't create it as a subclass of Pydantic's `BaseModel` but as a subclass of our own `User`, because it will have all the attributes in `User` plus a couple more:
-
-```Python hl_lines="31-33"
-{!../../../docs_src/nosql_databases/tutorial001.py!}
-```
-
-!!! note
- Notice that we have a `hashed_password` and a `type` field that will be stored in the database.
-
- But it is not part of the general `User` model (the one we will return in the *path operation*).
-
-## Get the user
-
-Now create a function that will:
-
-* Take a username.
-* Generate a document ID from it.
-* Get the document with that ID.
-* Put the contents of the document in a `UserInDB` model.
-
-By creating a function that is only dedicated to getting your user from a `username` (or any other parameter) independent of your *path operation function*, you can more easily reuse it in multiple parts and also add unit tests for it:
-
-```Python hl_lines="36-42"
-{!../../../docs_src/nosql_databases/tutorial001.py!}
-```
-
-### f-strings
-
-If you are not familiar with the `f"userprofile::{username}"`, it is a Python "f-string".
-
-Any variable that is put inside of `{}` in an f-string will be expanded / injected in the string.
-
-### `dict` unpacking
-
-If you are not familiar with the `UserInDB(**result.value)`, it is using `dict` "unpacking".
-
-It will take the `dict` at `result.value`, and take each of its keys and values and pass them as key-values to `UserInDB` as keyword arguments.
-
-So, if the `dict` contains:
-
-```Python
-{
- "username": "johndoe",
- "hashed_password": "some_hash",
-}
-```
-
-It will be passed to `UserInDB` as:
-
-```Python
-UserInDB(username="johndoe", hashed_password="some_hash")
-```
-
-## Create your **FastAPI** code
-
-### Create the `FastAPI` app
-
-```Python hl_lines="46"
-{!../../../docs_src/nosql_databases/tutorial001.py!}
-```
-
-### Create the *path operation function*
-
-As our code is calling Couchbase and we are not using the experimental Python await support, we should declare our function with normal `def` instead of `async def`.
-
-Also, Couchbase recommends not using a single `Bucket` object in multiple "threads", so, we can just get the bucket directly and pass it to our utility functions:
-
-```Python hl_lines="49-53"
-{!../../../docs_src/nosql_databases/tutorial001.py!}
-```
-
-## Recap
-
-You can integrate any third party NoSQL database, just using their standard packages.
-
-The same applies to any other external tool, system or API.
diff --git a/docs/en/docs/how-to/separate-openapi-schemas.md b/docs/en/docs/how-to/separate-openapi-schemas.md
index 10be1071a..9a27638fe 100644
--- a/docs/en/docs/how-to/separate-openapi-schemas.md
+++ b/docs/en/docs/how-to/separate-openapi-schemas.md
@@ -10,111 +10,13 @@ Let's see how that works and how to change it if you need to do that.
Let's say you have a Pydantic model with default values, like this one:
-=== "Python 3.10+"
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/separate_openapi_schemas/tutorial001_py310.py[ln:1-7]!}
-
- # Code below omitted 👇
- ```
-
-
-
+
@@ -93,7 +93,7 @@ The key features are:
"_Honestly, what you've built looks super solid and polished. In many ways, it's what I wanted **Hug** to be - it's really inspiring to see someone build that._"
-
+
---
@@ -128,21 +128,25 @@ FastAPI stands on the shoulders of giants:
## Installation
+Create and activate a virtual environment and then install FastAPI:
+
email_validator - for email validation.
-* pydantic-settings - for settings management.
-* pydantic-extra-types - for extra types to be used with Pydantic.
+* email-validator - for email validation.
Used by Starlette:
@@ -462,34 +470,27 @@ Used by Starlette:
Used by FastAPI / Starlette:
-* uvicorn - for the server that loads and serves your application.
+* uvicorn - for the server that loads and serves your application. This includes `uvicorn[standard]`, which includes some dependencies (e.g. `uvloop`) needed for high performance serving.
* `fastapi-cli` - to provide the `fastapi` command.
-When you install `fastapi` it comes these standard dependencies.
+### Without `standard` Dependencies
-Additional optional dependencies:
+If you don't want to include the `standard` optional dependencies, you can install with `pip install fastapi` instead of `pip install "fastapi[standard]"`.
+
+### Additional Optional Dependencies
+
+There are some additional dependencies you might want to install.
+
+Additional optional Pydantic dependencies:
+
+* pydantic-settings - for settings management.
+* pydantic-extra-types - for extra types to be used with Pydantic.
+
+Additional optional FastAPI dependencies:
* orjson - Required if you want to use `ORJSONResponse`.
* ujson - Required if you want to use `UJSONResponse`.
-## `fastapi-slim`
-
-If you don't want the extra standard optional dependencies, install `fastapi-slim` instead.
-
-When you install with:
-
-```bash
-pip install fastapi
-```
-
-...it includes the same code and dependencies as:
-
-```bash
-pip install "fastapi-slim[standard]"
-```
-
-The standard extra dependencies are the ones mentioned above.
-
## License
This project is licensed under the terms of the MIT license.
diff --git a/docs/en/docs/js/custom.js b/docs/en/docs/js/custom.js
index b7e5236f3..4c0ada312 100644
--- a/docs/en/docs/js/custom.js
+++ b/docs/en/docs/js/custom.js
@@ -1,25 +1,3 @@
-const div = document.querySelector('.github-topic-projects')
-
-async function getDataBatch(page) {
- const response = await fetch(`https://api.github.com/search/repositories?q=topic:fastapi&per_page=100&page=${page}`, { headers: { Accept: 'application/vnd.github.mercy-preview+json' } })
- const data = await response.json()
- return data
-}
-
-async function getData() {
- let page = 1
- let data = []
- let dataBatch = await getDataBatch(page)
- data = data.concat(dataBatch.items)
- const totalCount = dataBatch.total_count
- while (data.length < totalCount) {
- page += 1
- dataBatch = await getDataBatch(page)
- data = data.concat(dataBatch.items)
- }
- return data
-}
-
function setupTermynal() {
document.querySelectorAll(".use-termynal").forEach(node => {
node.style.display = "block";
@@ -147,7 +125,7 @@ async function showRandomAnnouncement(groupId, timeInterval) {
children = shuffle(children)
let index = 0
const announceRandom = () => {
- children.forEach((el, i) => {el.style.display = "none"});
+ children.forEach((el, i) => { el.style.display = "none" });
children[index].style.display = "block"
index = (index + 1) % children.length
}
@@ -158,23 +136,10 @@ async function showRandomAnnouncement(groupId, timeInterval) {
}
async function main() {
- if (div) {
- data = await getData()
- div.innerHTML = '
-And will be also used in the API docs inside each *path operation* that needs them:
+And will also be used in the API docs inside each *path operation* that needs them:
@@ -134,32 +108,25 @@ But you would get the same editor support with
-!!! tip
- If you use PyCharm as your editor, you can use the Pydantic PyCharm Plugin.
+/// tip
- It improves editor support for Pydantic models, with:
+If you use PyCharm as your editor, you can use the Pydantic PyCharm Plugin.
- * auto-completion
- * type checks
- * refactoring
- * searching
- * inspections
+It improves editor support for Pydantic models, with:
+
+* auto-completion
+* type checks
+* refactoring
+* searching
+* inspections
+
+///
## Use the model
Inside of the function, you can access all the attributes of the model object directly:
-=== "Python 3.10+"
-
- ```Python hl_lines="19"
- {!> ../../../docs_src/body/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="21"
- {!> ../../../docs_src/body/tutorial002.py!}
- ```
+{* ../../docs_src/body/tutorial002_py310.py *}
## Request body + path parameters
@@ -167,17 +134,8 @@ You can declare path parameters and request body at the same time.
**FastAPI** will recognize that the function parameters that match path parameters should be **taken from the path**, and that function parameters that are declared to be Pydantic models should be **taken from the request body**.
-=== "Python 3.10+"
+{* ../../docs_src/body/tutorial003_py310.py hl[15:16] *}
- ```Python hl_lines="15-16"
- {!> ../../../docs_src/body/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="17-18"
- {!> ../../../docs_src/body/tutorial003.py!}
- ```
## Request body + path + query parameters
@@ -185,17 +143,7 @@ You can also declare **body**, **path** and **query** parameters, all at the sam
**FastAPI** will recognize each of them and take the data from the correct place.
-=== "Python 3.10+"
-
- ```Python hl_lines="16"
- {!> ../../../docs_src/body/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body/tutorial004.py!}
- ```
+{* ../../docs_src/body/tutorial004_py310.py hl[16] *}
The function parameters will be recognized as follows:
@@ -203,10 +151,15 @@ The function parameters will be recognized as follows:
* If the parameter is of a **singular type** (like `int`, `float`, `str`, `bool`, etc) it will be interpreted as a **query** parameter.
* If the parameter is declared to be of the type of a **Pydantic model**, it will be interpreted as a request **body**.
-!!! note
- FastAPI will know that the value of `q` is not required because of the default value `= None`.
+/// note
- The `Union` in `Union[str, None]` is not used by FastAPI, but will allow your editor to give you better support and detect errors.
+FastAPI will know that the value of `q` is not required because of the default value `= None`.
+
+The `str | None` (Python 3.10+) or `Union` in `Union[str, None]` (Python 3.8+) is not used by FastAPI to determine that the value is not required, it will know it's not required because it has a default value of `= None`.
+
+But adding the type annotations will allow your editor to give you better support and detect errors.
+
+///
## Without Pydantic
diff --git a/docs/en/docs/tutorial/cookie-param-models.md b/docs/en/docs/tutorial/cookie-param-models.md
new file mode 100644
index 000000000..55a812852
--- /dev/null
+++ b/docs/en/docs/tutorial/cookie-param-models.md
@@ -0,0 +1,76 @@
+# Cookie Parameter Models
+
+If you have a group of **cookies** that are related, you can create a **Pydantic model** to declare them. 🍪
+
+This would allow you to **re-use the model** in **multiple places** and also to declare validations and metadata for all the parameters at once. 😎
+
+/// note
+
+This is supported since FastAPI version `0.115.0`. 🤓
+
+///
+
+/// tip
+
+This same technique applies to `Query`, `Cookie`, and `Header`. 😎
+
+///
+
+## Cookies with a Pydantic Model
+
+Declare the **cookie** parameters that you need in a **Pydantic model**, and then declare the parameter as `Cookie`:
+
+{* ../../docs_src/cookie_param_models/tutorial001_an_py310.py hl[9:12,16] *}
+
+**FastAPI** will **extract** the data for **each field** from the **cookies** received in the request and give you the Pydantic model you defined.
+
+## Check the Docs
+
+You can see the defined cookies in the docs UI at `/docs`:
+
+
+get operation
-!!! info "`@decorator` Info"
- That `@something` syntax in Python is called a "decorator".
+/// info | `@decorator` Info
- You put it on top of a function. Like a pretty decorative hat (I guess that's where the term came from).
+That `@something` syntax in Python is called a "decorator".
- A "decorator" takes the function below and does something with it.
+You put it on top of a function. Like a pretty decorative hat (I guess that's where the term came from).
- In our case, this decorator tells **FastAPI** that the function below corresponds to the **path** `/` with an **operation** `get`.
+A "decorator" takes the function below and does something with it.
- It is the "**path operation decorator**".
+In our case, this decorator tells **FastAPI** that the function below corresponds to the **path** `/` with an **operation** `get`.
+
+It is the "**path operation decorator**".
+
+///
You can also use the other operations:
@@ -271,14 +264,17 @@ And the more exotic ones:
* `@app.patch()`
* `@app.trace()`
-!!! tip
- You are free to use each operation (HTTP method) as you wish.
+/// tip
- **FastAPI** doesn't enforce any specific meaning.
+You are free to use each operation (HTTP method) as you wish.
- The information here is presented as a guideline, not a requirement.
+**FastAPI** doesn't enforce any specific meaning.
- For example, when using GraphQL you normally perform all the actions using only `POST` operations.
+The information here is presented as a guideline, not a requirement.
+
+For example, when using GraphQL you normally perform all the actions using only `POST` operations.
+
+///
### Step 4: define the **path operation function**
@@ -288,9 +284,7 @@ This is our "**path operation function**":
* **operation**: is `get`.
* **function**: is the function below the "decorator" (below `@app.get("/")`).
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[7] *}
This is a Python function.
@@ -302,18 +296,17 @@ In this case, it is an `async` function.
You could also define it as a normal function instead of `async def`:
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial003.py!}
-```
+{* ../../docs_src/first_steps/tutorial003.py hl[7] *}
-!!! note
- If you don't know the difference, check the [Async: *"In a hurry?"*](../async.md#in-a-hurry){.internal-link target=_blank}.
+/// note
+
+If you don't know the difference, check the [Async: *"In a hurry?"*](../async.md#in-a-hurry){.internal-link target=_blank}.
+
+///
### Step 5: return the content
-```Python hl_lines="8"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[8] *}
You can return a `dict`, `list`, singular values as `str`, `int`, etc.
diff --git a/docs/en/docs/tutorial/handling-errors.md b/docs/en/docs/tutorial/handling-errors.md
index 6133898e4..5b8e677e4 100644
--- a/docs/en/docs/tutorial/handling-errors.md
+++ b/docs/en/docs/tutorial/handling-errors.md
@@ -25,9 +25,7 @@ To return HTTP responses with errors to the client you use `HTTPException`.
### Import `HTTPException`
-```Python hl_lines="1"
-{!../../../docs_src/handling_errors/tutorial001.py!}
-```
+{* ../../docs_src/handling_errors/tutorial001.py hl[1] *}
### Raise an `HTTPException` in your code
@@ -37,13 +35,11 @@ Because it's a Python exception, you don't `return` it, you `raise` it.
This also means that if you are inside a utility function that you are calling inside of your *path operation function*, and you raise the `HTTPException` from inside of that utility function, it won't run the rest of the code in the *path operation function*, it will terminate that request right away and send the HTTP error from the `HTTPException` to the client.
-The benefit of raising an exception over `return`ing a value will be more evident in the section about Dependencies and Security.
+The benefit of raising an exception over returning a value will be more evident in the section about Dependencies and Security.
In this example, when the client requests an item by an ID that doesn't exist, raise an exception with a status code of `404`:
-```Python hl_lines="11"
-{!../../../docs_src/handling_errors/tutorial001.py!}
-```
+{* ../../docs_src/handling_errors/tutorial001.py hl[11] *}
### The resulting response
@@ -63,12 +59,15 @@ But if the client requests `http://example.com/items/bar` (a non-existent `item_
}
```
-!!! tip
- When raising an `HTTPException`, you can pass any value that can be converted to JSON as the parameter `detail`, not only `str`.
+/// tip
- You could pass a `dict`, a `list`, etc.
+When raising an `HTTPException`, you can pass any value that can be converted to JSON as the parameter `detail`, not only `str`.
- They are handled automatically by **FastAPI** and converted to JSON.
+You could pass a `dict`, a `list`, etc.
+
+They are handled automatically by **FastAPI** and converted to JSON.
+
+///
## Add custom headers
@@ -78,9 +77,7 @@ You probably won't need to use it directly in your code.
But in case you needed it for an advanced scenario, you can add custom headers:
-```Python hl_lines="14"
-{!../../../docs_src/handling_errors/tutorial002.py!}
-```
+{* ../../docs_src/handling_errors/tutorial002.py hl[14] *}
## Install custom exception handlers
@@ -92,9 +89,7 @@ And you want to handle this exception globally with FastAPI.
You could add a custom exception handler with `@app.exception_handler()`:
-```Python hl_lines="5-7 13-18 24"
-{!../../../docs_src/handling_errors/tutorial003.py!}
-```
+{* ../../docs_src/handling_errors/tutorial003.py hl[5:7,13:18,24] *}
Here, if you request `/unicorns/yolo`, the *path operation* will `raise` a `UnicornException`.
@@ -106,10 +101,13 @@ So, you will receive a clean error, with an HTTP status code of `418` and a JSON
{"message": "Oops! yolo did something. There goes a rainbow..."}
```
-!!! note "Technical Details"
- You could also use `from starlette.requests import Request` and `from starlette.responses import JSONResponse`.
+/// note | Technical Details
- **FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette. The same with `Request`.
+You could also use `from starlette.requests import Request` and `from starlette.responses import JSONResponse`.
+
+**FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette. The same with `Request`.
+
+///
## Override the default exception handlers
@@ -129,9 +127,7 @@ To override it, import the `RequestValidationError` and use it with `@app.except
The exception handler will receive a `Request` and the exception.
-```Python hl_lines="2 14-16"
-{!../../../docs_src/handling_errors/tutorial004.py!}
-```
+{* ../../docs_src/handling_errors/tutorial004.py hl[2,14:16] *}
Now, if you go to `/items/foo`, instead of getting the default JSON error with:
@@ -160,14 +156,17 @@ path -> item_id
#### `RequestValidationError` vs `ValidationError`
-!!! warning
- These are technical details that you might skip if it's not important for you now.
+/// warning
+
+These are technical details that you might skip if it's not important for you now.
+
+///
`RequestValidationError` is a sub-class of Pydantic's `ValidationError`.
**FastAPI** uses it so that, if you use a Pydantic model in `response_model`, and your data has an error, you will see the error in your log.
-But the client/user will not see it. Instead, the client will receive an "Internal Server Error" with a HTTP status code `500`.
+But the client/user will not see it. Instead, the client will receive an "Internal Server Error" with an HTTP status code `500`.
It should be this way because if you have a Pydantic `ValidationError` in your *response* or anywhere in your code (not in the client's *request*), it's actually a bug in your code.
@@ -179,14 +178,15 @@ The same way, you can override the `HTTPException` handler.
For example, you could want to return a plain text response instead of JSON for these errors:
-```Python hl_lines="3-4 9-11 22"
-{!../../../docs_src/handling_errors/tutorial004.py!}
-```
+{* ../../docs_src/handling_errors/tutorial004.py hl[3:4,9:11,22] *}
-!!! note "Technical Details"
- You could also use `from starlette.responses import PlainTextResponse`.
+/// note | Technical Details
- **FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.
+You could also use `from starlette.responses import PlainTextResponse`.
+
+**FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.
+
+///
### Use the `RequestValidationError` body
@@ -194,9 +194,7 @@ The `RequestValidationError` contains the `body` it received with invalid data.
You could use it while developing your app to log the body and debug it, return it to the user, etc.
-```Python hl_lines="14"
-{!../../../docs_src/handling_errors/tutorial005.py!}
-```
+{* ../../docs_src/handling_errors/tutorial005.py hl[14] *}
Now try sending an invalid item like:
@@ -250,10 +248,8 @@ from starlette.exceptions import HTTPException as StarletteHTTPException
### Reuse **FastAPI**'s exception handlers
-If you want to use the exception along with the same default exception handlers from **FastAPI**, You can import and reuse the default exception handlers from `fastapi.exception_handlers`:
+If you want to use the exception along with the same default exception handlers from **FastAPI**, you can import and reuse the default exception handlers from `fastapi.exception_handlers`:
-```Python hl_lines="2-5 15 21"
-{!../../../docs_src/handling_errors/tutorial006.py!}
-```
+{* ../../docs_src/handling_errors/tutorial006.py hl[2:5,15,21] *}
-In this example you are just `print`ing the error with a very expressive message, but you get the idea. You can use the exception and then just reuse the default exception handlers.
+In this example you are just printing the error with a very expressive message, but you get the idea. You can use the exception and then just reuse the default exception handlers.
diff --git a/docs/en/docs/tutorial/header-param-models.md b/docs/en/docs/tutorial/header-param-models.md
new file mode 100644
index 000000000..4cdf09705
--- /dev/null
+++ b/docs/en/docs/tutorial/header-param-models.md
@@ -0,0 +1,72 @@
+# Header Parameter Models
+
+If you have a group of related **header parameters**, you can create a **Pydantic model** to declare them.
+
+This would allow you to **re-use the model** in **multiple places** and also to declare validations and metadata for all the parameters at once. 😎
+
+/// note
+
+This is supported since FastAPI version `0.115.0`. 🤓
+
+///
+
+## Header Parameters with a Pydantic Model
+
+Declare the **header parameters** that you need in a **Pydantic model**, and then declare the parameter as `Header`:
+
+{* ../../docs_src/header_param_models/tutorial001_an_py310.py hl[9:14,18] *}
+
+**FastAPI** will **extract** the data for **each field** from the **headers** in the request and give you the Pydantic model you defined.
+
+## Check the Docs
+
+You can see the required headers in the docs UI at `/docs`:
+
+
+
@@ -162,9 +92,7 @@ You can specify the response description with the parameter `response_descriptio
If you need to mark a *path operation* as deprecated, but without removing it, pass the parameter `deprecated`:
-```Python hl_lines="16"
-{!../../../docs_src/path_operation_configuration/tutorial006.py!}
-```
+{* ../../docs_src/path_operation_configuration/tutorial006.py hl[16] *}
It will be clearly marked as deprecated in the interactive docs:
diff --git a/docs/en/docs/tutorial/path-params-numeric-validations.md b/docs/en/docs/tutorial/path-params-numeric-validations.md
index ca86ad226..9440bcc03 100644
--- a/docs/en/docs/tutorial/path-params-numeric-validations.md
+++ b/docs/en/docs/tutorial/path-params-numeric-validations.md
@@ -6,48 +6,17 @@ In the same way that you can declare more validations and metadata for query par
First, import `Path` from `fastapi`, and import `Annotated`:
-=== "Python 3.10+"
+{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[1,3] *}
- ```Python hl_lines="1 3"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py!}
- ```
+/// info
-=== "Python 3.9+"
+FastAPI added support for `Annotated` (and started recommending it) in version 0.95.0.
- ```Python hl_lines="1 3"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py39.py!}
- ```
+If you have an older version, you would get errors when trying to use `Annotated`.
-=== "Python 3.8+"
+Make sure you [Upgrade the FastAPI version](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank} to at least 0.95.1 before using `Annotated`.
- ```Python hl_lines="3-4"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="1"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="3"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001.py!}
- ```
-
-!!! info
- FastAPI added support for `Annotated` (and started recommending it) in version 0.95.0.
-
- If you have an older version, you would get errors when trying to use `Annotated`.
-
- Make sure you [Upgrade the FastAPI version](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank} to at least 0.95.1 before using `Annotated`.
+///
## Declare metadata
@@ -55,49 +24,21 @@ You can declare all the same parameters as for `Query`.
For example, to declare a `title` metadata value for the path parameter `item_id` you can type:
-=== "Python 3.10+"
+{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[10] *}
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py!}
- ```
+/// note
-=== "Python 3.9+"
+A path parameter is always required as it has to be part of the path. Even if you declared it with `None` or set a default value, it would not affect anything, it would still be always required.
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001.py!}
- ```
-
-!!! note
- A path parameter is always required as it has to be part of the path. Even if you declared it with `None` or set a default value, it would not affect anything, it would still be always required.
+///
## Order the parameters as you need
-!!! tip
- This is probably not as important or necessary if you use `Annotated`.
+/// tip
+
+This is probably not as important or necessary if you use `Annotated`.
+
+///
Let's say that you want to declare the query parameter `q` as a required `str`.
@@ -113,33 +54,29 @@ It doesn't matter for **FastAPI**. It will detect the parameters by their names,
So, you can declare your function as:
-=== "Python 3.8 non-Annotated"
+//// tab | Python 3.8 non-Annotated
- !!! tip
- Prefer to use the `Annotated` version if possible.
+/// tip
- ```Python hl_lines="7"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial002.py!}
- ```
+Prefer to use the `Annotated` version if possible.
+
+///
+
+{* ../../docs_src/path_params_numeric_validations/tutorial002.py hl[7] *}
+
+////
But keep in mind that if you use `Annotated`, you won't have this problem, it won't matter as you're not using the function parameter default values for `Query()` or `Path()`.
-=== "Python 3.9+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial002_an.py!}
- ```
+{* ../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py *}
## Order the parameters as you need, tricks
-!!! tip
- This is probably not as important or necessary if you use `Annotated`.
+/// tip
+
+This is probably not as important or necessary if you use `Annotated`.
+
+///
Here's a **small trick** that can be handy, but you won't need it often.
@@ -156,25 +93,13 @@ Pass `*`, as the first parameter of the function.
Python won't do anything with that `*`, but it will know that all the following parameters should be called as keyword arguments (key-value pairs), also known as kwargs. Even if they don't have a default value.
-```Python hl_lines="7"
-{!../../../docs_src/path_params_numeric_validations/tutorial003.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *}
### Better with `Annotated`
Keep in mind that if you use `Annotated`, as you are not using function parameter default values, you won't have this problem, and you probably won't need to use `*`.
-=== "Python 3.9+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial003_an.py!}
- ```
+{* ../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py hl[10] *}
## Number validations: greater than or equal
@@ -182,26 +107,7 @@ With `Query` and `Path` (and others you'll see later) you can declare number con
Here, with `ge=1`, `item_id` will need to be an integer number "`g`reater than or `e`qual" to `1`.
-=== "Python 3.9+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial004_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial004.py!}
- ```
+{* ../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py hl[10] *}
## Number validations: greater than and less than or equal
@@ -210,26 +116,7 @@ The same applies for:
* `gt`: `g`reater `t`han
* `le`: `l`ess than or `e`qual
-=== "Python 3.9+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial005_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial005.py!}
- ```
+{* ../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py hl[10] *}
## Number validations: floats, greater than and less than
@@ -241,26 +128,7 @@ So, `0.5` would be a valid value. But `0.0` or `0` would not.
And the same for lt.
-=== "Python 3.9+"
-
- ```Python hl_lines="13"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial006_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial006.py!}
- ```
+{* ../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py hl[13] *}
## Recap
@@ -273,18 +141,24 @@ And you can also declare numeric validations:
* `lt`: `l`ess `t`han
* `le`: `l`ess than or `e`qual
-!!! info
- `Query`, `Path`, and other classes you will see later are subclasses of a common `Param` class.
+/// info
- All of them share the same parameters for additional validation and metadata you have seen.
+`Query`, `Path`, and other classes you will see later are subclasses of a common `Param` class.
-!!! note "Technical Details"
- When you import `Query`, `Path` and others from `fastapi`, they are actually functions.
+All of them share the same parameters for additional validation and metadata you have seen.
- That when called, return instances of classes of the same name.
+///
- So, you import `Query`, which is a function. And when you call it, it returns an instance of a class also named `Query`.
+/// note | Technical Details
- These functions are there (instead of just using the classes directly) so that your editor doesn't mark errors about their types.
+When you import `Query`, `Path` and others from `fastapi`, they are actually functions.
- That way you can use your normal editor and coding tools without having to add custom configurations to disregard those errors.
+That when called, return instances of classes of the same name.
+
+So, you import `Query`, which is a function. And when you call it, it returns an instance of a class also named `Query`.
+
+These functions are there (instead of just using the classes directly) so that your editor doesn't mark errors about their types.
+
+That way you can use your normal editor and coding tools without having to add custom configurations to disregard those errors.
+
+///
diff --git a/docs/en/docs/tutorial/path-params.md b/docs/en/docs/tutorial/path-params.md
index 6246d6680..7e83d3ae5 100644
--- a/docs/en/docs/tutorial/path-params.md
+++ b/docs/en/docs/tutorial/path-params.md
@@ -2,9 +2,7 @@
You can declare path "parameters" or "variables" with the same syntax used by Python format strings:
-```Python hl_lines="6-7"
-{!../../../docs_src/path_params/tutorial001.py!}
-```
+{* ../../docs_src/path_params/tutorial001.py hl[6:7] *}
The value of the path parameter `item_id` will be passed to your function as the argument `item_id`.
@@ -18,14 +16,15 @@ So, if you run this example and go to conversion
@@ -35,10 +34,13 @@ If you run this example and open your browser at "parsing".
+Notice that the value your function received (and returned) is `3`, as a Python `int`, not a string `"3"`.
+
+So, with that type declaration, **FastAPI** gives you automatic request "parsing".
+
+///
## Data validation
@@ -65,12 +67,15 @@ because the path parameter `item_id` had a value of `"foo"`, which is not an `in
The same error would appear if you provided a `float` instead of an `int`, as in: http://127.0.0.1:8000/items/4.2
-!!! check
- So, with the same Python type declaration, **FastAPI** gives you data validation.
+/// check
- Notice that the error also clearly states exactly the point where the validation didn't pass.
+So, with the same Python type declaration, **FastAPI** gives you data validation.
- This is incredibly helpful while developing and debugging code that interacts with your API.
+Notice that the error also clearly states exactly the point where the validation didn't pass.
+
+This is incredibly helpful while developing and debugging code that interacts with your API.
+
+///
## Documentation
@@ -78,10 +83,13 @@ And when you open your browser at
-!!! check
- Again, just with that same Python type declaration, **FastAPI** gives you automatic, interactive documentation (integrating Swagger UI).
+/// check
- Notice that the path parameter is declared to be an integer.
+Again, just with that same Python type declaration, **FastAPI** gives you automatic, interactive documentation (integrating Swagger UI).
+
+Notice that the path parameter is declared to be an integer.
+
+///
## Standards-based benefits, alternative documentation
@@ -111,17 +119,13 @@ And then you can also have a path `/users/{user_id}` to get data about a specifi
Because *path operations* are evaluated in order, you need to make sure that the path for `/users/me` is declared before the one for `/users/{user_id}`:
-```Python hl_lines="6 11"
-{!../../../docs_src/path_params/tutorial003.py!}
-```
+{* ../../docs_src/path_params/tutorial003.py hl[6,11] *}
Otherwise, the path for `/users/{user_id}` would match also for `/users/me`, "thinking" that it's receiving a parameter `user_id` with a value of `"me"`.
Similarly, you cannot redefine a path operation:
-```Python hl_lines="6 11"
-{!../../../docs_src/path_params/tutorial003b.py!}
-```
+{* ../../docs_src/path_params/tutorial003b.py hl[6,11] *}
The first one will always be used since the path matches first.
@@ -137,23 +141,25 @@ By inheriting from `str` the API docs will be able to know that the values must
Then create class attributes with fixed values, which will be the available valid values:
-```Python hl_lines="1 6-9"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[1,6:9] *}
-!!! info
- Enumerations (or enums) are available in Python since version 3.4.
+/// info
-!!! tip
- If you are wondering, "AlexNet", "ResNet", and "LeNet" are just names of Machine Learning models.
+Enumerations (or enums) are available in Python since version 3.4.
+
+///
+
+/// tip
+
+If you are wondering, "AlexNet", "ResNet", and "LeNet" are just names of Machine Learning models.
+
+///
### Declare a *path parameter*
Then create a *path parameter* with a type annotation using the enum class you created (`ModelName`):
-```Python hl_lines="16"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[16] *}
### Check the docs
@@ -169,20 +175,19 @@ The value of the *path parameter* will be an *enumeration member*.
You can compare it with the *enumeration member* in your created enum `ModelName`:
-```Python hl_lines="17"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[17] *}
#### Get the *enumeration value*
You can get the actual value (a `str` in this case) using `model_name.value`, or in general, `your_enum_member.value`:
-```Python hl_lines="20"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[20] *}
-!!! tip
- You could also access the value `"lenet"` with `ModelName.lenet.value`.
+/// tip
+
+You could also access the value `"lenet"` with `ModelName.lenet.value`.
+
+///
#### Return *enumeration members*
@@ -190,9 +195,7 @@ You can return *enum members* from your *path operation*, even nested in a JSON
They will be converted to their corresponding values (strings in this case) before returning them to the client:
-```Python hl_lines="18 21 23"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[18,21,23] *}
In your client you will get a JSON response like:
@@ -231,14 +234,15 @@ In this case, the name of the parameter is `file_path`, and the last part, `:pat
So, you can use it with:
-```Python hl_lines="6"
-{!../../../docs_src/path_params/tutorial004.py!}
-```
+{* ../../docs_src/path_params/tutorial004.py hl[6] *}
-!!! tip
- You could need the parameter to contain `/home/johndoe/myfile.txt`, with a leading slash (`/`).
+/// tip
- In that case, the URL would be: `/files//home/johndoe/myfile.txt`, with a double slash (`//`) between `files` and `home`.
+You could need the parameter to contain `/home/johndoe/myfile.txt`, with a leading slash (`/`).
+
+In that case, the URL would be: `/files//home/johndoe/myfile.txt`, with a double slash (`//`) between `files` and `home`.
+
+///
## Recap
diff --git a/docs/en/docs/tutorial/query-param-models.md b/docs/en/docs/tutorial/query-param-models.md
new file mode 100644
index 000000000..84d82931a
--- /dev/null
+++ b/docs/en/docs/tutorial/query-param-models.md
@@ -0,0 +1,68 @@
+# Query Parameter Models
+
+If you have a group of **query parameters** that are related, you can create a **Pydantic model** to declare them.
+
+This would allow you to **re-use the model** in **multiple places** and also to declare validations and metadata for all the parameters at once. 😎
+
+/// note
+
+This is supported since FastAPI version `0.115.0`. 🤓
+
+///
+
+## Query Parameters with a Pydantic Model
+
+Declare the **query parameters** that you need in a **Pydantic model**, and then declare the parameter as `Query`:
+
+{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *}
+
+**FastAPI** will **extract** the data for **each field** from the **query parameters** in the request and give you the Pydantic model you defined.
+
+## Check the Docs
+
+You can see the query parameters in the docs UI at `/docs`:
+
+
+
-## Exclude from OpenAPI
+## Exclude parameters from OpenAPI
To exclude a query parameter from the generated OpenAPI schema (and thus, from the automatic documentation systems), set the parameter `include_in_schema` of `Query` to `False`:
-=== "Python 3.10+"
+{* ../../docs_src/query_params_str_validations/tutorial014_an_py310.py hl[10] *}
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params_str_validations/tutorial014_an_py310.py!}
- ```
+## Custom Validation
-=== "Python 3.9+"
+There could be cases where you need to do some **custom validation** that can't be done with the parameters shown above.
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params_str_validations/tutorial014_an_py39.py!}
- ```
+In those cases, you can use a **custom validator function** that is applied after the normal validation (e.g. after validating that the value is a `str`).
-=== "Python 3.8+"
+You can achieve that using Pydantic's `AfterValidator` inside of `Annotated`.
- ```Python hl_lines="11"
- {!> ../../../docs_src/query_params_str_validations/tutorial014_an.py!}
- ```
+/// tip
-=== "Python 3.10+ non-Annotated"
+Pydantic also has `BeforeValidator` and others. 🤓
- !!! tip
- Prefer to use the `Annotated` version if possible.
+///
- ```Python hl_lines="8"
- {!> ../../../docs_src/query_params_str_validations/tutorial014_py310.py!}
- ```
+For example, this custom validator checks that the item ID starts with `isbn-` for an ISBN book number or with `imdb-` for an IMDB movie URL ID:
-=== "Python 3.8+ non-Annotated"
+{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py hl[5,16:19,24] *}
- !!! tip
- Prefer to use the `Annotated` version if possible.
+/// info
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params_str_validations/tutorial014.py!}
- ```
+This is available with Pydantic version 2 or above. 😎
+
+///
+
+/// tip
+
+If you need to do any type of validation that requires communicating with any **external component**, like a database or another API, you should instead use **FastAPI Dependencies**, you will learn about them later.
+
+These custom validators are for things that can be checked with **only** the **same data** provided in the request.
+
+///
+
+### Understand that Code
+
+The important point is just using **`AfterValidator` with a function inside `Annotated`**. Feel free to skip this part. 🤸
+
+---
+
+But if you're curious about this specific code example and you're still entertained, here are some extra details.
+
+#### String with `value.startswith()`
+
+Did you notice? a string using `value.startswith()` can take a tuple, and it will check each value in the tuple:
+
+{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py ln[16:19] hl[17] *}
+
+#### A Random Item
+
+With `data.items()` we get an iterable object with tuples containing the key and value for each dictionary item.
+
+We convert this iterable object into a proper `list` with `list(data.items())`.
+
+Then with `random.choice()` we can get a **random value** from the list, so, we get a tuple with `(id, name)`. It will be something like `("imdb-tt0371724", "The Hitchhiker's Guide to the Galaxy")`.
+
+Then we **assign those two values** of the tuple to the variables `id` and `name`.
+
+So, if the user didn't provide an item ID, they will still receive a random suggestion.
+
+...we do all this in a **single simple line**. 🤯 Don't you love Python? 🐍
+
+{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py ln[22:30] hl[29] *}
## Recap
@@ -913,6 +485,8 @@ Validations specific for strings:
* `max_length`
* `pattern`
+Custom validations using `AfterValidator`.
+
In these examples you saw how to declare validations for `str` values.
-See the next chapters to see how to declare validations for other types, like numbers.
+See the next chapters to learn how to declare validations for other types, like numbers.
diff --git a/docs/en/docs/tutorial/query-params.md b/docs/en/docs/tutorial/query-params.md
index bc3b11948..c8477387c 100644
--- a/docs/en/docs/tutorial/query-params.md
+++ b/docs/en/docs/tutorial/query-params.md
@@ -2,9 +2,7 @@
When you declare other function parameters that are not part of the path parameters, they are automatically interpreted as "query" parameters.
-```Python hl_lines="9"
-{!../../../docs_src/query_params/tutorial001.py!}
-```
+{* ../../docs_src/query_params/tutorial001.py hl[9] *}
The query is the set of key-value pairs that go after the `?` in a URL, separated by `&` characters.
@@ -63,38 +61,21 @@ The parameter values in your function will be:
The same way, you can declare optional query parameters, by setting their default to `None`:
-=== "Python 3.10+"
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params/tutorial002.py!}
- ```
+{* ../../docs_src/query_params/tutorial002_py310.py hl[7] *}
In this case, the function parameter `q` will be optional, and will be `None` by default.
-!!! check
- Also notice that **FastAPI** is smart enough to notice that the path parameter `item_id` is a path parameter and `q` is not, so, it's a query parameter.
+/// check
+
+Also notice that **FastAPI** is smart enough to notice that the path parameter `item_id` is a path parameter and `q` is not, so, it's a query parameter.
+
+///
## Query parameter type conversion
You can also declare `bool` types, and they will be converted:
-=== "Python 3.10+"
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params/tutorial003.py!}
- ```
+{* ../../docs_src/query_params/tutorial003_py310.py hl[7] *}
In this case, if you go to:
@@ -137,17 +118,7 @@ And you don't have to declare them in any specific order.
They will be detected by name:
-=== "Python 3.10+"
-
- ```Python hl_lines="6 8"
- {!> ../../../docs_src/query_params/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="8 10"
- {!> ../../../docs_src/query_params/tutorial004.py!}
- ```
+{* ../../docs_src/query_params/tutorial004_py310.py hl[6,8] *}
## Required query parameters
@@ -157,9 +128,7 @@ If you don't want to add a specific value but just make it optional, set the def
But when you want to make a query parameter required, you can just not declare any default value:
-```Python hl_lines="6-7"
-{!../../../docs_src/query_params/tutorial005.py!}
-```
+{* ../../docs_src/query_params/tutorial005.py hl[6:7] *}
Here the query parameter `needy` is a required query parameter of type `str`.
@@ -205,17 +174,7 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
And of course, you can define some parameters as required, some as having a default value, and some entirely optional:
-=== "Python 3.10+"
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/query_params/tutorial006_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/query_params/tutorial006.py!}
- ```
+{* ../../docs_src/query_params/tutorial006_py310.py hl[8] *}
In this case, there are 3 query parameters:
@@ -223,5 +182,8 @@ In this case, there are 3 query parameters:
* `skip`, an `int` with a default value of `0`.
* `limit`, an optional `int`.
-!!! tip
- You could also use `Enum`s the same way as with [Path Parameters](path-params.md#predefined-values){.internal-link target=_blank}.
+/// tip
+
+You could also use `Enum`s the same way as with [Path Parameters](path-params.md#predefined-values){.internal-link target=_blank}.
+
+///
diff --git a/docs/en/docs/tutorial/request-files.md b/docs/en/docs/tutorial/request-files.md
index 17ac3b25d..0d57f3566 100644
--- a/docs/en/docs/tutorial/request-files.md
+++ b/docs/en/docs/tutorial/request-files.md
@@ -2,70 +2,45 @@
You can define files to be uploaded by the client using `File`.
-!!! info
- To receive uploaded files, first install `python-multipart`.
+/// info
- E.g. `pip install python-multipart`.
+To receive uploaded files, first install `python-multipart`.
- This is because uploaded files are sent as "form data".
+Make sure you create a [virtual environment](../virtual-environments.md){.internal-link target=_blank}, activate it, and then install it, for example:
+
+```console
+$ pip install python-multipart
+```
+
+This is because uploaded files are sent as "form data".
+
+///
## Import `File`
Import `File` and `UploadFile` from `fastapi`:
-=== "Python 3.9+"
-
- ```Python hl_lines="3"
- {!> ../../../docs_src/request_files/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="1"
- {!> ../../../docs_src/request_files/tutorial001_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="1"
- {!> ../../../docs_src/request_files/tutorial001.py!}
- ```
+{* ../../docs_src/request_files/tutorial001_an_py39.py hl[3] *}
## Define `File` Parameters
Create file parameters the same way you would for `Body` or `Form`:
-=== "Python 3.9+"
+{* ../../docs_src/request_files/tutorial001_an_py39.py hl[9] *}
- ```Python hl_lines="9"
- {!> ../../../docs_src/request_files/tutorial001_an_py39.py!}
- ```
+/// info
-=== "Python 3.8+"
+`File` is a class that inherits directly from `Form`.
- ```Python hl_lines="8"
- {!> ../../../docs_src/request_files/tutorial001_an.py!}
- ```
+But remember that when you import `Query`, `Path`, `File` and others from `fastapi`, those are actually functions that return special classes.
-=== "Python 3.8+ non-Annotated"
+///
- !!! tip
- Prefer to use the `Annotated` version if possible.
+/// tip
- ```Python hl_lines="7"
- {!> ../../../docs_src/request_files/tutorial001.py!}
- ```
+To declare File bodies, you need to use `File`, because otherwise the parameters would be interpreted as query parameters or body (JSON) parameters.
-!!! info
- `File` is a class that inherits directly from `Form`.
-
- But remember that when you import `Query`, `Path`, `File` and others from `fastapi`, those are actually functions that return special classes.
-
-!!! tip
- To declare File bodies, you need to use `File`, because otherwise the parameters would be interpreted as query parameters or body (JSON) parameters.
+///
The files will be uploaded as "form data".
@@ -79,26 +54,7 @@ But there are several cases in which you might benefit from using `UploadFile`.
Define a file parameter with a type of `UploadFile`:
-=== "Python 3.9+"
-
- ```Python hl_lines="14"
- {!> ../../../docs_src/request_files/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="13"
- {!> ../../../docs_src/request_files/tutorial001_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/request_files/tutorial001.py!}
- ```
+{* ../../docs_src/request_files/tutorial001_an_py39.py hl[14] *}
Using `UploadFile` has several advantages over `bytes`:
@@ -116,7 +72,7 @@ Using `UploadFile` has several advantages over `bytes`:
* `filename`: A `str` with the original file name that was uploaded (e.g. `myimage.jpg`).
* `content_type`: A `str` with the content type (MIME type / media type) (e.g. `image/jpeg`).
-* `file`: A `SpooledTemporaryFile` (a file-like object). This is the actual Python file that you can pass directly to other functions or libraries that expect a "file-like" object.
+* `file`: A `SpooledTemporaryFile` (a file-like object). This is the actual Python file object that you can pass directly to other functions or libraries that expect a "file-like" object.
`UploadFile` has the following `async` methods. They all call the corresponding file methods underneath (using the internal `SpooledTemporaryFile`).
@@ -141,11 +97,17 @@ If you are inside of a normal `def` *path operation function*, you can access th
contents = myfile.file.read()
```
-!!! note "`async` Technical Details"
- When you use the `async` methods, **FastAPI** runs the file methods in a threadpool and awaits for them.
+/// note | `async` Technical Details
-!!! note "Starlette Technical Details"
- **FastAPI**'s `UploadFile` inherits directly from **Starlette**'s `UploadFile`, but adds some necessary parts to make it compatible with **Pydantic** and the other parts of FastAPI.
+When you use the `async` methods, **FastAPI** runs the file methods in a threadpool and awaits for them.
+
+///
+
+/// note | Starlette Technical Details
+
+**FastAPI**'s `UploadFile` inherits directly from **Starlette**'s `UploadFile`, but adds some necessary parts to make it compatible with **Pydantic** and the other parts of FastAPI.
+
+///
## What is "Form Data"
@@ -153,82 +115,35 @@ The way HTML forms (``) sends the data to the server normally uses
**FastAPI** will make sure to read that data from the right place instead of JSON.
-!!! note "Technical Details"
- Data from forms is normally encoded using the "media type" `application/x-www-form-urlencoded` when it doesn't include files.
+/// note | Technical Details
- But when the form includes files, it is encoded as `multipart/form-data`. If you use `File`, **FastAPI** will know it has to get the files from the correct part of the body.
+Data from forms is normally encoded using the "media type" `application/x-www-form-urlencoded` when it doesn't include files.
- If you want to read more about these encodings and form fields, head to the MDN web docs for POST.
+But when the form includes files, it is encoded as `multipart/form-data`. If you use `File`, **FastAPI** will know it has to get the files from the correct part of the body.
-!!! warning
- You can declare multiple `File` and `Form` parameters in a *path operation*, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `multipart/form-data` instead of `application/json`.
+If you want to read more about these encodings and form fields, head to the MDN web docs for POST.
- This is not a limitation of **FastAPI**, it's part of the HTTP protocol.
+///
+
+/// warning
+
+You can declare multiple `File` and `Form` parameters in a *path operation*, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `multipart/form-data` instead of `application/json`.
+
+This is not a limitation of **FastAPI**, it's part of the HTTP protocol.
+
+///
## Optional File Upload
You can make a file optional by using standard type annotations and setting a default value of `None`:
-=== "Python 3.10+"
-
- ```Python hl_lines="9 17"
- {!> ../../../docs_src/request_files/tutorial001_02_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="9 17"
- {!> ../../../docs_src/request_files/tutorial001_02_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="10 18"
- {!> ../../../docs_src/request_files/tutorial001_02_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="7 15"
- {!> ../../../docs_src/request_files/tutorial001_02_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="9 17"
- {!> ../../../docs_src/request_files/tutorial001_02.py!}
- ```
+{* ../../docs_src/request_files/tutorial001_02_an_py310.py hl[9,17] *}
## `UploadFile` with Additional Metadata
You can also use `File()` with `UploadFile`, for example, to set additional metadata:
-=== "Python 3.9+"
-
- ```Python hl_lines="9 15"
- {!> ../../../docs_src/request_files/tutorial001_03_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="8 14"
- {!> ../../../docs_src/request_files/tutorial001_03_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="7 13"
- {!> ../../../docs_src/request_files/tutorial001_03.py!}
- ```
+{* ../../docs_src/request_files/tutorial001_03_an_py39.py hl[9,15] *}
## Multiple File Uploads
@@ -238,76 +153,23 @@ They would be associated to the same "form field" sent using "form data".
To use that, declare a list of `bytes` or `UploadFile`:
-=== "Python 3.9+"
-
- ```Python hl_lines="10 15"
- {!> ../../../docs_src/request_files/tutorial002_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="11 16"
- {!> ../../../docs_src/request_files/tutorial002_an.py!}
- ```
-
-=== "Python 3.9+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="8 13"
- {!> ../../../docs_src/request_files/tutorial002_py39.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="10 15"
- {!> ../../../docs_src/request_files/tutorial002.py!}
- ```
+{* ../../docs_src/request_files/tutorial002_an_py39.py hl[10,15] *}
You will receive, as declared, a `list` of `bytes` or `UploadFile`s.
-!!! note "Technical Details"
- You could also use `from starlette.responses import HTMLResponse`.
+/// note | Technical Details
- **FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.
+You could also use `from starlette.responses import HTMLResponse`.
+
+**FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.
+
+///
### Multiple File Uploads with Additional Metadata
And the same way as before, you can use `File()` to set additional parameters, even for `UploadFile`:
-=== "Python 3.9+"
-
- ```Python hl_lines="11 18-20"
- {!> ../../../docs_src/request_files/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="12 19-21"
- {!> ../../../docs_src/request_files/tutorial003_an.py!}
- ```
-
-=== "Python 3.9+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="9 16"
- {!> ../../../docs_src/request_files/tutorial003_py39.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="11 18"
- {!> ../../../docs_src/request_files/tutorial003.py!}
- ```
+{* ../../docs_src/request_files/tutorial003_an_py39.py hl[11,18:20] *}
## Recap
diff --git a/docs/en/docs/tutorial/request-form-models.md b/docs/en/docs/tutorial/request-form-models.md
new file mode 100644
index 000000000..79046a3f6
--- /dev/null
+++ b/docs/en/docs/tutorial/request-form-models.md
@@ -0,0 +1,78 @@
+# Form Models
+
+You can use **Pydantic models** to declare **form fields** in FastAPI.
+
+/// info
+
+To use forms, first install `python-multipart`.
+
+Make sure you create a [virtual environment](../virtual-environments.md){.internal-link target=_blank}, activate it, and then install it, for example:
+
+```console
+$ pip install python-multipart
+```
+
+///
+
+/// note
+
+This is supported since FastAPI version `0.113.0`. 🤓
+
+///
+
+## Pydantic Models for Forms
+
+You just need to declare a **Pydantic model** with the fields you want to receive as **form fields**, and then declare the parameter as `Form`:
+
+{* ../../docs_src/request_form_models/tutorial001_an_py39.py hl[9:11,15] *}
+
+**FastAPI** will **extract** the data for **each field** from the **form data** in the request and give you the Pydantic model you defined.
+
+## Check the Docs
+
+You can verify it in the docs UI at `/docs`:
+
+
+POST.
+But when the form includes files, it is encoded as `multipart/form-data`. You'll read about handling files in the next chapter.
-!!! warning
- You can declare multiple `Form` parameters in a *path operation*, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `application/x-www-form-urlencoded` instead of `application/json`.
+If you want to read more about these encodings and form fields, head to the MDN web docs for POST.
- This is not a limitation of **FastAPI**, it's part of the HTTP protocol.
+///
+
+/// warning
+
+You can declare multiple `Form` parameters in a *path operation*, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `application/x-www-form-urlencoded` instead of `application/json`.
+
+This is not a limitation of **FastAPI**, it's part of the HTTP protocol.
+
+///
## Recap
diff --git a/docs/en/docs/tutorial/response-model.md b/docs/en/docs/tutorial/response-model.md
index 75d5df106..e7837086f 100644
--- a/docs/en/docs/tutorial/response-model.md
+++ b/docs/en/docs/tutorial/response-model.md
@@ -4,23 +4,7 @@ You can declare the type used for the response by annotating the *path operation
You can use **type annotations** the same way you would for input data in function **parameters**, you can use Pydantic models, lists, dictionaries, scalar values like integers, booleans, etc.
-=== "Python 3.10+"
-
- ```Python hl_lines="16 21"
- {!> ../../../docs_src/response_model/tutorial001_01_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="18 23"
- {!> ../../../docs_src/response_model/tutorial001_01_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="18 23"
- {!> ../../../docs_src/response_model/tutorial001_01.py!}
- ```
+{* ../../docs_src/response_model/tutorial001_01_py310.py hl[16,21] *}
FastAPI will use this return type to:
@@ -53,35 +37,25 @@ You can use the `response_model` parameter in any of the *path operations*:
* `@app.delete()`
* etc.
-=== "Python 3.10+"
+{* ../../docs_src/response_model/tutorial001_py310.py hl[17,22,24:27] *}
- ```Python hl_lines="17 22 24-27"
- {!> ../../../docs_src/response_model/tutorial001_py310.py!}
- ```
+/// note
-=== "Python 3.9+"
+Notice that `response_model` is a parameter of the "decorator" method (`get`, `post`, etc). Not of your *path operation function*, like all the parameters and body.
- ```Python hl_lines="17 22 24-27"
- {!> ../../../docs_src/response_model/tutorial001_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="17 22 24-27"
- {!> ../../../docs_src/response_model/tutorial001.py!}
- ```
-
-!!! note
- Notice that `response_model` is a parameter of the "decorator" method (`get`, `post`, etc). Not of your *path operation function*, like all the parameters and body.
+///
`response_model` receives the same type you would declare for a Pydantic model field, so, it can be a Pydantic model, but it can also be, e.g. a `list` of Pydantic models, like `List[Item]`.
FastAPI will use this `response_model` to do all the data documentation, validation, etc. and also to **convert and filter the output data** to its type declaration.
-!!! tip
- If you have strict type checks in your editor, mypy, etc, you can declare the function return type as `Any`.
+/// tip
- That way you tell the editor that you are intentionally returning anything. But FastAPI will still do the data documentation, validation, filtering, etc. with the `response_model`.
+If you have strict type checks in your editor, mypy, etc, you can declare the function return type as `Any`.
+
+That way you tell the editor that you are intentionally returning anything. But FastAPI will still do the data documentation, validation, filtering, etc. with the `response_model`.
+
+///
### `response_model` Priority
@@ -95,37 +69,29 @@ You can also use `response_model=None` to disable creating a response model for
Here we are declaring a `UserIn` model, it will contain a plaintext password:
-=== "Python 3.10+"
+{* ../../docs_src/response_model/tutorial002_py310.py hl[7,9] *}
- ```Python hl_lines="7 9"
- {!> ../../../docs_src/response_model/tutorial002_py310.py!}
- ```
+/// info
-=== "Python 3.8+"
+To use `EmailStr`, first install `email-validator`.
- ```Python hl_lines="9 11"
- {!> ../../../docs_src/response_model/tutorial002.py!}
- ```
+Make sure you create a [virtual environment](../virtual-environments.md){.internal-link target=_blank}, activate it, and then install it, for example:
-!!! info
- To use `EmailStr`, first install `email_validator`.
+```console
+$ pip install email-validator
+```
- E.g. `pip install email-validator`
- or `pip install pydantic[email]`.
+or with:
+
+```console
+$ pip install "pydantic[email]"
+```
+
+///
And we are using this model to declare our input and the same model to declare our output:
-=== "Python 3.10+"
-
- ```Python hl_lines="16"
- {!> ../../../docs_src/response_model/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/response_model/tutorial002.py!}
- ```
+{* ../../docs_src/response_model/tutorial002_py310.py hl[16] *}
Now, whenever a browser is creating a user with a password, the API will return the same password in the response.
@@ -133,52 +99,25 @@ In this case, it might not be a problem, because it's the same user sending the
But if we use the same model for another *path operation*, we could be sending our user's passwords to every client.
-!!! danger
- Never store the plain password of a user or send it in a response like this, unless you know all the caveats and you know what you are doing.
+/// danger
+
+Never store the plain password of a user or send it in a response like this, unless you know all the caveats and you know what you are doing.
+
+///
## Add an output model
We can instead create an input model with the plaintext password and an output model without it:
-=== "Python 3.10+"
-
- ```Python hl_lines="9 11 16"
- {!> ../../../docs_src/response_model/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9 11 16"
- {!> ../../../docs_src/response_model/tutorial003.py!}
- ```
+{* ../../docs_src/response_model/tutorial003_py310.py hl[9,11,16] *}
Here, even though our *path operation function* is returning the same input user that contains the password:
-=== "Python 3.10+"
-
- ```Python hl_lines="24"
- {!> ../../../docs_src/response_model/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="24"
- {!> ../../../docs_src/response_model/tutorial003.py!}
- ```
+{* ../../docs_src/response_model/tutorial003_py310.py hl[24] *}
...we declared the `response_model` to be our model `UserOut`, that doesn't include the password:
-=== "Python 3.10+"
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/response_model/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/response_model/tutorial003.py!}
- ```
+{* ../../docs_src/response_model/tutorial003_py310.py hl[22] *}
So, **FastAPI** will take care of filtering out all the data that is not declared in the output model (using Pydantic).
@@ -192,9 +131,9 @@ That's why in this example we have to declare it in the `response_model` paramet
## Return Type and Data Filtering
-Let's continue from the previous example. We wanted to **annotate the function with one type** but return something that includes **more data**.
+Let's continue from the previous example. We wanted to **annotate the function with one type**, but we wanted to be able to return from the function something that actually includes **more data**.
-We want FastAPI to keep **filtering** the data using the response model.
+We want FastAPI to keep **filtering** the data using the response model. So that even though the function returns more data, the response will only include the fields declared in the response model.
In the previous example, because the classes were different, we had to use the `response_model` parameter. But that also means that we don't get the support from the editor and tools checking the function return type.
@@ -202,17 +141,7 @@ But in most of the cases where we need to do something like this, we want the mo
And in those cases, we can use classes and inheritance to take advantage of function **type annotations** to get better support in the editor and tools, and still get the FastAPI **data filtering**.
-=== "Python 3.10+"
-
- ```Python hl_lines="7-10 13-14 18"
- {!> ../../../docs_src/response_model/tutorial003_01_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9-13 15-16 20"
- {!> ../../../docs_src/response_model/tutorial003_01.py!}
- ```
+{* ../../docs_src/response_model/tutorial003_01_py310.py hl[7:10,13:14,18] *}
With this, we get tooling support, from editors and mypy as this code is correct in terms of types, but we also get the data filtering from FastAPI.
@@ -254,11 +183,9 @@ There might be cases where you return something that is not a valid Pydantic fie
The most common case would be [returning a Response directly as explained later in the advanced docs](../advanced/response-directly.md){.internal-link target=_blank}.
-```Python hl_lines="8 10-11"
-{!> ../../../docs_src/response_model/tutorial003_02.py!}
-```
+{* ../../docs_src/response_model/tutorial003_02.py hl[8,10:11] *}
-This simple case is handled automatically by FastAPI because the return type annotation is the class (or a subclass) of `Response`.
+This simple case is handled automatically by FastAPI because the return type annotation is the class (or a subclass of) `Response`.
And tools will also be happy because both `RedirectResponse` and `JSONResponse` are subclasses of `Response`, so the type annotation is correct.
@@ -266,9 +193,7 @@ And tools will also be happy because both `RedirectResponse` and `JSONResponse`
You can also use a subclass of `Response` in the type annotation:
-```Python hl_lines="8-9"
-{!> ../../../docs_src/response_model/tutorial003_03.py!}
-```
+{* ../../docs_src/response_model/tutorial003_03.py hl[8:9] *}
This will also work because `RedirectResponse` is a subclass of `Response`, and FastAPI will automatically handle this simple case.
@@ -278,17 +203,7 @@ But when you return some other arbitrary object that is not a valid Pydantic typ
The same would happen if you had something like a union between different types where one or more of them are not valid Pydantic types, for example this would fail 💥:
-=== "Python 3.10+"
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/response_model/tutorial003_04_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/response_model/tutorial003_04.py!}
- ```
+{* ../../docs_src/response_model/tutorial003_04_py310.py hl[8] *}
...this fails because the type annotation is not a Pydantic type and is not just a single `Response` class or subclass, it's a union (any of the two) between a `Response` and a `dict`.
@@ -300,17 +215,7 @@ But you might want to still keep the return type annotation in the function to g
In this case, you can disable the response model generation by setting `response_model=None`:
-=== "Python 3.10+"
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/response_model/tutorial003_05_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/response_model/tutorial003_05.py!}
- ```
+{* ../../docs_src/response_model/tutorial003_05_py310.py hl[7] *}
This will make FastAPI skip the response model generation and that way you can have any return type annotations you need without it affecting your FastAPI application. 🤓
@@ -318,23 +223,7 @@ This will make FastAPI skip the response model generation and that way you can h
Your response model could have default values, like:
-=== "Python 3.10+"
-
- ```Python hl_lines="9 11-12"
- {!> ../../../docs_src/response_model/tutorial004_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="11 13-14"
- {!> ../../../docs_src/response_model/tutorial004_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="11 13-14"
- {!> ../../../docs_src/response_model/tutorial004.py!}
- ```
+{* ../../docs_src/response_model/tutorial004_py310.py hl[9,11:12] *}
* `description: Union[str, None] = None` (or `str | None = None` in Python 3.10) has a default of `None`.
* `tax: float = 10.5` has a default of `10.5`.
@@ -348,23 +237,7 @@ For example, if you have models with many optional attributes in a NoSQL databas
You can set the *path operation decorator* parameter `response_model_exclude_unset=True`:
-=== "Python 3.10+"
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/response_model/tutorial004_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="24"
- {!> ../../../docs_src/response_model/tutorial004_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="24"
- {!> ../../../docs_src/response_model/tutorial004.py!}
- ```
+{* ../../docs_src/response_model/tutorial004_py310.py hl[22] *}
and those default values won't be included in the response, only the values actually set.
@@ -377,21 +250,30 @@ So, if you send a request to that *path operation* for the item with ID `foo`, t
}
```
-!!! info
- In Pydantic v1 the method was called `.dict()`, it was deprecated (but still supported) in Pydantic v2, and renamed to `.model_dump()`.
+/// info
- The examples here use `.dict()` for compatibility with Pydantic v1, but you should use `.model_dump()` instead if you can use Pydantic v2.
+In Pydantic v1 the method was called `.dict()`, it was deprecated (but still supported) in Pydantic v2, and renamed to `.model_dump()`.
-!!! info
- FastAPI uses Pydantic model's `.dict()` with its `exclude_unset` parameter to achieve this.
+The examples here use `.dict()` for compatibility with Pydantic v1, but you should use `.model_dump()` instead if you can use Pydantic v2.
-!!! info
- You can also use:
+///
- * `response_model_exclude_defaults=True`
- * `response_model_exclude_none=True`
+/// info
- as described in the Pydantic docs for `exclude_defaults` and `exclude_none`.
+FastAPI uses Pydantic model's `.dict()` with its `exclude_unset` parameter to achieve this.
+
+///
+
+/// info
+
+You can also use:
+
+* `response_model_exclude_defaults=True`
+* `response_model_exclude_none=True`
+
+as described in the Pydantic docs for `exclude_defaults` and `exclude_none`.
+
+///
#### Data with values for fields with defaults
@@ -426,10 +308,13 @@ FastAPI is smart enough (actually, Pydantic is smart enough) to realize that, ev
So, they will be included in the JSON response.
-!!! tip
- Notice that the default values can be anything, not only `None`.
+/// tip
- They can be a list (`[]`), a `float` of `10.5`, etc.
+Notice that the default values can be anything, not only `None`.
+
+They can be a list (`[]`), a `float` of `10.5`, etc.
+
+///
### `response_model_include` and `response_model_exclude`
@@ -439,45 +324,31 @@ They take a `set` of `str` with the name of the attributes to include (omitting
This can be used as a quick shortcut if you have only one Pydantic model and want to remove some data from the output.
-!!! tip
- But it is still recommended to use the ideas above, using multiple classes, instead of these parameters.
+/// tip
- This is because the JSON Schema generated in your app's OpenAPI (and the docs) will still be the one for the complete model, even if you use `response_model_include` or `response_model_exclude` to omit some attributes.
+But it is still recommended to use the ideas above, using multiple classes, instead of these parameters.
- This also applies to `response_model_by_alias` that works similarly.
+This is because the JSON Schema generated in your app's OpenAPI (and the docs) will still be the one for the complete model, even if you use `response_model_include` or `response_model_exclude` to omit some attributes.
-=== "Python 3.10+"
+This also applies to `response_model_by_alias` that works similarly.
- ```Python hl_lines="29 35"
- {!> ../../../docs_src/response_model/tutorial005_py310.py!}
- ```
+///
-=== "Python 3.8+"
+{* ../../docs_src/response_model/tutorial005_py310.py hl[29,35] *}
- ```Python hl_lines="31 37"
- {!> ../../../docs_src/response_model/tutorial005.py!}
- ```
+/// tip
-!!! tip
- The syntax `{"name", "description"}` creates a `set` with those two values.
+The syntax `{"name", "description"}` creates a `set` with those two values.
- It is equivalent to `set(["name", "description"])`.
+It is equivalent to `set(["name", "description"])`.
+
+///
#### Using `list`s instead of `set`s
If you forget to use a `set` and use a `list` or `tuple` instead, FastAPI will still convert it to a `set` and it will work correctly:
-=== "Python 3.10+"
-
- ```Python hl_lines="29 35"
- {!> ../../../docs_src/response_model/tutorial006_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="31 37"
- {!> ../../../docs_src/response_model/tutorial006.py!}
- ```
+{* ../../docs_src/response_model/tutorial006_py310.py hl[29,35] *}
## Recap
diff --git a/docs/en/docs/tutorial/response-status-code.md b/docs/en/docs/tutorial/response-status-code.md
index 646378aa1..41bf02a8f 100644
--- a/docs/en/docs/tutorial/response-status-code.md
+++ b/docs/en/docs/tutorial/response-status-code.md
@@ -8,17 +8,21 @@ The same way you can specify a response model, you can also declare the HTTP sta
* `@app.delete()`
* etc.
-```Python hl_lines="6"
-{!../../../docs_src/response_status_code/tutorial001.py!}
-```
+{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
-!!! note
- Notice that `status_code` is a parameter of the "decorator" method (`get`, `post`, etc). Not of your *path operation function*, like all the parameters and body.
+/// note
+
+Notice that `status_code` is a parameter of the "decorator" method (`get`, `post`, etc). Not of your *path operation function*, like all the parameters and body.
+
+///
The `status_code` parameter receives a number with the HTTP status code.
-!!! info
- `status_code` can alternatively also receive an `IntEnum`, such as Python's `http.HTTPStatus`.
+/// info
+
+`status_code` can alternatively also receive an `IntEnum`, such as Python's `http.HTTPStatus`.
+
+///
It will:
@@ -27,15 +31,21 @@ It will:
-!!! note
- Some response codes (see the next section) indicate that the response does not have a body.
+/// note
- FastAPI knows this, and will produce OpenAPI docs that state there is no response body.
+Some response codes (see the next section) indicate that the response does not have a body.
+
+FastAPI knows this, and will produce OpenAPI docs that state there is no response body.
+
+///
## About HTTP status codes
-!!! note
- If you already know what HTTP status codes are, skip to the next section.
+/// note
+
+If you already know what HTTP status codes are, skip to the next section.
+
+///
In HTTP, you send a numeric status code of 3 digits as part of the response.
@@ -43,27 +53,28 @@ These status codes have a name associated to recognize them, but the important p
In short:
-* `100` and above are for "Information". You rarely use them directly. Responses with these status codes cannot have a body.
-* **`200`** and above are for "Successful" responses. These are the ones you would use the most.
+* `100 - 199` are for "Information". You rarely use them directly. Responses with these status codes cannot have a body.
+* **`200 - 299`** are for "Successful" responses. These are the ones you would use the most.
* `200` is the default status code, which means everything was "OK".
* Another example would be `201`, "Created". It is commonly used after creating a new record in the database.
* A special case is `204`, "No Content". This response is used when there is no content to return to the client, and so the response must not have a body.
-* **`300`** and above are for "Redirection". Responses with these status codes may or may not have a body, except for `304`, "Not Modified", which must not have one.
-* **`400`** and above are for "Client error" responses. These are the second type you would probably use the most.
+* **`300 - 399`** are for "Redirection". Responses with these status codes may or may not have a body, except for `304`, "Not Modified", which must not have one.
+* **`400 - 499`** are for "Client error" responses. These are the second type you would probably use the most.
* An example is `404`, for a "Not Found" response.
* For generic errors from the client, you can just use `400`.
-* `500` and above are for server errors. You almost never use them directly. When something goes wrong at some part in your application code, or server, it will automatically return one of these status codes.
+* `500 - 599` are for server errors. You almost never use them directly. When something goes wrong at some part in your application code, or server, it will automatically return one of these status codes.
-!!! tip
- To know more about each status code and which code is for what, check the MDN documentation about HTTP status codes.
+/// tip
+
+To know more about each status code and which code is for what, check the MDN documentation about HTTP status codes.
+
+///
## Shortcut to remember the names
Let's see the previous example again:
-```Python hl_lines="6"
-{!../../../docs_src/response_status_code/tutorial001.py!}
-```
+{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
`201` is the status code for "Created".
@@ -71,18 +82,19 @@ But you don't have to memorize what each of these codes mean.
You can use the convenience variables from `fastapi.status`.
-```Python hl_lines="1 6"
-{!../../../docs_src/response_status_code/tutorial002.py!}
-```
+{* ../../docs_src/response_status_code/tutorial002.py hl[1,6] *}
They are just a convenience, they hold the same number, but that way you can use the editor's autocomplete to find them:
-!!! note "Technical Details"
- You could also use `from starlette import status`.
+/// note | Technical Details
- **FastAPI** provides the same `starlette.status` as `fastapi.status` just as a convenience for you, the developer. But it comes directly from Starlette.
+You could also use `from starlette import status`.
+
+**FastAPI** provides the same `starlette.status` as `fastapi.status` just as a convenience for you, the developer. But it comes directly from Starlette.
+
+///
## Changing the default
diff --git a/docs/en/docs/tutorial/schema-extra-example.md b/docs/en/docs/tutorial/schema-extra-example.md
index 40231dc0b..32a1f5ca2 100644
--- a/docs/en/docs/tutorial/schema-extra-example.md
+++ b/docs/en/docs/tutorial/schema-extra-example.md
@@ -8,71 +8,59 @@ Here are several ways to do it.
You can declare `examples` for a Pydantic model that will be added to the generated JSON Schema.
-=== "Python 3.10+ Pydantic v2"
+//// tab | Pydantic v2
- ```Python hl_lines="13-24"
- {!> ../../../docs_src/schema_extra_example/tutorial001_py310.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial001_py310.py hl[13:24] *}
-=== "Python 3.10+ Pydantic v1"
+////
- ```Python hl_lines="13-23"
- {!> ../../../docs_src/schema_extra_example/tutorial001_py310_pv1.py!}
- ```
+//// tab | Pydantic v1
-=== "Python 3.8+ Pydantic v2"
+{* ../../docs_src/schema_extra_example/tutorial001_pv1_py310.py hl[13:23] *}
- ```Python hl_lines="15-26"
- {!> ../../../docs_src/schema_extra_example/tutorial001.py!}
- ```
-
-=== "Python 3.8+ Pydantic v1"
-
- ```Python hl_lines="15-25"
- {!> ../../../docs_src/schema_extra_example/tutorial001_pv1.py!}
- ```
+////
That extra info will be added as-is to the output **JSON Schema** for that model, and it will be used in the API docs.
-=== "Pydantic v2"
+//// tab | Pydantic v2
- In Pydantic version 2, you would use the attribute `model_config`, that takes a `dict` as described in Pydantic's docs: Model Config.
+In Pydantic version 2, you would use the attribute `model_config`, that takes a `dict` as described in Pydantic's docs: Configuration.
- You can set `"json_schema_extra"` with a `dict` containing any additional data you would like to show up in the generated JSON Schema, including `examples`.
+You can set `"json_schema_extra"` with a `dict` containing any additional data you would like to show up in the generated JSON Schema, including `examples`.
-=== "Pydantic v1"
+////
- In Pydantic version 1, you would use an internal class `Config` and `schema_extra`, as described in Pydantic's docs: Schema customization.
+//// tab | Pydantic v1
- You can set `schema_extra` with a `dict` containing any additional data you would like to show up in the generated JSON Schema, including `examples`.
+In Pydantic version 1, you would use an internal class `Config` and `schema_extra`, as described in Pydantic's docs: Schema customization.
-!!! tip
- You could use the same technique to extend the JSON Schema and add your own custom extra info.
+You can set `schema_extra` with a `dict` containing any additional data you would like to show up in the generated JSON Schema, including `examples`.
- For example you could use it to add metadata for a frontend user interface, etc.
+////
-!!! info
- OpenAPI 3.1.0 (used since FastAPI 0.99.0) added support for `examples`, which is part of the **JSON Schema** standard.
+/// tip
- Before that, it only supported the keyword `example` with a single example. That is still supported by OpenAPI 3.1.0, but is deprecated and is not part of the JSON Schema standard. So you are encouraged to migrate `example` to `examples`. 🤓
+You could use the same technique to extend the JSON Schema and add your own custom extra info.
- You can read more at the end of this page.
+For example you could use it to add metadata for a frontend user interface, etc.
+
+///
+
+/// info
+
+OpenAPI 3.1.0 (used since FastAPI 0.99.0) added support for `examples`, which is part of the **JSON Schema** standard.
+
+Before that, it only supported the keyword `example` with a single example. That is still supported by OpenAPI 3.1.0, but is deprecated and is not part of the JSON Schema standard. So you are encouraged to migrate `example` to `examples`. 🤓
+
+You can read more at the end of this page.
+
+///
## `Field` additional arguments
When using `Field()` with Pydantic models, you can also declare additional `examples`:
-=== "Python 3.10+"
-
- ```Python hl_lines="2 8-11"
- {!> ../../../docs_src/schema_extra_example/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="4 10-13"
- {!> ../../../docs_src/schema_extra_example/tutorial002.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial002_py310.py hl[2,8:11] *}
## `examples` in JSON Schema - OpenAPI
@@ -92,41 +80,7 @@ you can also declare a group of `examples` with additional information that will
Here we pass `examples` containing one example of the data expected in `Body()`:
-=== "Python 3.10+"
-
- ```Python hl_lines="22-29"
- {!> ../../../docs_src/schema_extra_example/tutorial003_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="22-29"
- {!> ../../../docs_src/schema_extra_example/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="23-30"
- {!> ../../../docs_src/schema_extra_example/tutorial003_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="18-25"
- {!> ../../../docs_src/schema_extra_example/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="20-27"
- {!> ../../../docs_src/schema_extra_example/tutorial003.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial003_an_py310.py hl[22:29] *}
### Example in the docs UI
@@ -138,41 +92,7 @@ With any of the methods above it would look like this in the `/docs`:
You can of course also pass multiple `examples`:
-=== "Python 3.10+"
-
- ```Python hl_lines="23-38"
- {!> ../../../docs_src/schema_extra_example/tutorial004_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="23-38"
- {!> ../../../docs_src/schema_extra_example/tutorial004_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="24-39"
- {!> ../../../docs_src/schema_extra_example/tutorial004_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="19-34"
- {!> ../../../docs_src/schema_extra_example/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="21-36"
- {!> ../../../docs_src/schema_extra_example/tutorial004.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial004_an_py310.py hl[23:38] *}
When you do this, the examples will be part of the internal **JSON Schema** for that body data.
@@ -213,41 +133,7 @@ Each specific example `dict` in the `examples` can contain:
You can use it like this:
-=== "Python 3.10+"
-
- ```Python hl_lines="23-49"
- {!> ../../../docs_src/schema_extra_example/tutorial005_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="23-49"
- {!> ../../../docs_src/schema_extra_example/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="24-50"
- {!> ../../../docs_src/schema_extra_example/tutorial005_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="19-45"
- {!> ../../../docs_src/schema_extra_example/tutorial005_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="21-47"
- {!> ../../../docs_src/schema_extra_example/tutorial005.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial005_an_py310.py hl[23:49] *}
### OpenAPI Examples in the Docs UI
@@ -257,21 +143,27 @@ With `openapi_examples` added to `Body()` the `/docs` would look like:
## Technical Details
-!!! tip
- If you are already using **FastAPI** version **0.99.0 or above**, you can probably **skip** these details.
+/// tip
- They are more relevant for older versions, before OpenAPI 3.1.0 was available.
+If you are already using **FastAPI** version **0.99.0 or above**, you can probably **skip** these details.
- You can consider this a brief OpenAPI and JSON Schema **history lesson**. 🤓
+They are more relevant for older versions, before OpenAPI 3.1.0 was available.
-!!! warning
- These are very technical details about the standards **JSON Schema** and **OpenAPI**.
+You can consider this a brief OpenAPI and JSON Schema **history lesson**. 🤓
- If the ideas above already work for you, that might be enough, and you probably don't need these details, feel free to skip them.
+///
+
+/// warning
+
+These are very technical details about the standards **JSON Schema** and **OpenAPI**.
+
+If the ideas above already work for you, that might be enough, and you probably don't need these details, feel free to skip them.
+
+///
Before OpenAPI 3.1.0, OpenAPI used an older and modified version of **JSON Schema**.
-JSON Schema didn't have `examples`, so OpenAPI added it's own `example` field to its own modified version.
+JSON Schema didn't have `examples`, so OpenAPI added its own `example` field to its own modified version.
OpenAPI also added `example` and `examples` fields to other parts of the specification:
@@ -285,8 +177,11 @@ OpenAPI also added `example` and `examples` fields to other parts of the specifi
* `File()`
* `Form()`
-!!! info
- This old OpenAPI-specific `examples` parameter is now `openapi_examples` since FastAPI `0.103.0`.
+/// info
+
+This old OpenAPI-specific `examples` parameter is now `openapi_examples` since FastAPI `0.103.0`.
+
+///
### JSON Schema's `examples` field
@@ -298,10 +193,13 @@ And now this new `examples` field takes precedence over the old single (and cust
This new `examples` field in JSON Schema is **just a `list`** of examples, not a dict with extra metadata as in the other places in OpenAPI (described above).
-!!! info
- Even after OpenAPI 3.1.0 was released with this new simpler integration with JSON Schema, for a while, Swagger UI, the tool that provides the automatic docs, didn't support OpenAPI 3.1.0 (it does since version 5.0.0 🎉).
+/// info
- Because of that, versions of FastAPI previous to 0.99.0 still used versions of OpenAPI lower than 3.1.0.
+Even after OpenAPI 3.1.0 was released with this new simpler integration with JSON Schema, for a while, Swagger UI, the tool that provides the automatic docs, didn't support OpenAPI 3.1.0 (it does since version 5.0.0 🎉).
+
+Because of that, versions of FastAPI previous to 0.99.0 still used versions of OpenAPI lower than 3.1.0.
+
+///
### Pydantic and FastAPI `examples`
diff --git a/docs/en/docs/tutorial/security/first-steps.md b/docs/en/docs/tutorial/security/first-steps.md
index a769cc0e6..8f6578e12 100644
--- a/docs/en/docs/tutorial/security/first-steps.md
+++ b/docs/en/docs/tutorial/security/first-steps.md
@@ -20,38 +20,25 @@ Let's first just use the code and see how it works, and then we'll come back to
Copy the example in a file `main.py`:
-=== "Python 3.9+"
-
- ```Python
- {!> ../../../docs_src/security/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python
- {!> ../../../docs_src/security/tutorial001_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python
- {!> ../../../docs_src/security/tutorial001.py!}
- ```
-
+{* ../../docs_src/security/tutorial001_an_py39.py *}
## Run it
-!!! info
- The `python-multipart` package is automatically installed with **FastAPI** when you run the `pip install fastapi` command.
+/// info
- However, if you use the `pip install fastapi-slim` command, the `python-multipart` package is not included by default. To install it manually, use the following command:
+The `python-multipart` package is automatically installed with **FastAPI** when you run the `pip install "fastapi[standard]"` command.
- `pip install python-multipart`
+However, if you use the `pip install fastapi` command, the `python-multipart` package is not included by default.
- This is because **OAuth2** uses "form data" for sending the `username` and `password`.
+To install it manually, make sure you create a [virtual environment](../../virtual-environments.md){.internal-link target=_blank}, activate it, and then install it with:
+
+```console
+$ pip install python-multipart
+```
+
+This is because **OAuth2** uses "form data" for sending the `username` and `password`.
+
+///
Run the example with:
@@ -73,17 +60,23 @@ You will see something like this:
-!!! check "Authorize button!"
- You already have a shiny new "Authorize" button.
+/// check | Authorize button!
- And your *path operation* has a little lock in the top-right corner that you can click.
+You already have a shiny new "Authorize" button.
+
+And your *path operation* has a little lock in the top-right corner that you can click.
+
+///
And if you click it, you have a little authorization form to type a `username` and `password` (and other optional fields):
-!!! note
- It doesn't matter what you type in the form, it won't work yet. But we'll get there.
+/// note
+
+It doesn't matter what you type in the form, it won't work yet. But we'll get there.
+
+///
This is of course not the frontend for the final users, but it's a great automatic tool to document interactively all your API.
@@ -125,53 +118,43 @@ So, let's review it from that simplified point of view:
In this example we are going to use **OAuth2**, with the **Password** flow, using a **Bearer** token. We do that using the `OAuth2PasswordBearer` class.
-!!! info
- A "bearer" token is not the only option.
+/// info
- But it's the best one for our use case.
+A "bearer" token is not the only option.
- And it might be the best for most use cases, unless you are an OAuth2 expert and know exactly why there's another option that suits better your needs.
+But it's the best one for our use case.
- In that case, **FastAPI** also provides you with the tools to build it.
+And it might be the best for most use cases, unless you are an OAuth2 expert and know exactly why there's another option that better suits your needs.
+
+In that case, **FastAPI** also provides you with the tools to build it.
+
+///
When we create an instance of the `OAuth2PasswordBearer` class we pass in the `tokenUrl` parameter. This parameter contains the URL that the client (the frontend running in the user's browser) will use to send the `username` and `password` in order to get a token.
-=== "Python 3.9+"
+{* ../../docs_src/security/tutorial001_an_py39.py hl[8] *}
- ```Python hl_lines="8"
- {!> ../../../docs_src/security/tutorial001_an_py39.py!}
- ```
+/// tip
-=== "Python 3.8+"
+Here `tokenUrl="token"` refers to a relative URL `token` that we haven't created yet. As it's a relative URL, it's equivalent to `./token`.
- ```Python hl_lines="7"
- {!> ../../../docs_src/security/tutorial001_an.py!}
- ```
+Because we are using a relative URL, if your API was located at `https://example.com/`, then it would refer to `https://example.com/token`. But if your API was located at `https://example.com/api/v1/`, then it would refer to `https://example.com/api/v1/token`.
-=== "Python 3.8+ non-Annotated"
+Using a relative URL is important to make sure your application keeps working even in an advanced use case like [Behind a Proxy](../../advanced/behind-a-proxy.md){.internal-link target=_blank}.
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="6"
- {!> ../../../docs_src/security/tutorial001.py!}
- ```
-
-!!! tip
- Here `tokenUrl="token"` refers to a relative URL `token` that we haven't created yet. As it's a relative URL, it's equivalent to `./token`.
-
- Because we are using a relative URL, if your API was located at `https://example.com/`, then it would refer to `https://example.com/token`. But if your API was located at `https://example.com/api/v1/`, then it would refer to `https://example.com/api/v1/token`.
-
- Using a relative URL is important to make sure your application keeps working even in an advanced use case like [Behind a Proxy](../../advanced/behind-a-proxy.md){.internal-link target=_blank}.
+///
This parameter doesn't create that endpoint / *path operation*, but declares that the URL `/token` will be the one that the client should use to get the token. That information is used in OpenAPI, and then in the interactive API documentation systems.
We will soon also create the actual path operation.
-!!! info
- If you are a very strict "Pythonista" you might dislike the style of the parameter name `tokenUrl` instead of `token_url`.
+/// info
- That's because it is using the same name as in the OpenAPI spec. So that if you need to investigate more about any of these security schemes you can just copy and paste it to find more information about it.
+If you are a very strict "Pythonista" you might dislike the style of the parameter name `tokenUrl` instead of `token_url`.
+
+That's because it is using the same name as in the OpenAPI spec. So that if you need to investigate more about any of these security schemes you can just copy and paste it to find more information about it.
+
+///
The `oauth2_scheme` variable is an instance of `OAuth2PasswordBearer`, but it is also a "callable".
@@ -187,35 +170,19 @@ So, it can be used with `Depends`.
Now you can pass that `oauth2_scheme` in a dependency with `Depends`.
-=== "Python 3.9+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/security/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/security/tutorial001_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/security/tutorial001.py!}
- ```
+{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *}
This dependency will provide a `str` that is assigned to the parameter `token` of the *path operation function*.
**FastAPI** will know that it can use this dependency to define a "security scheme" in the OpenAPI schema (and the automatic API docs).
-!!! info "Technical Details"
- **FastAPI** will know that it can use the class `OAuth2PasswordBearer` (declared in a dependency) to define the security scheme in OpenAPI because it inherits from `fastapi.security.oauth2.OAuth2`, which in turn inherits from `fastapi.security.base.SecurityBase`.
+/// info | Technical Details
- All the security utilities that integrate with OpenAPI (and the automatic API docs) inherit from `SecurityBase`, that's how **FastAPI** can know how to integrate them in OpenAPI.
+**FastAPI** will know that it can use the class `OAuth2PasswordBearer` (declared in a dependency) to define the security scheme in OpenAPI because it inherits from `fastapi.security.oauth2.OAuth2`, which in turn inherits from `fastapi.security.base.SecurityBase`.
+
+All the security utilities that integrate with OpenAPI (and the automatic API docs) inherit from `SecurityBase`, that's how **FastAPI** can know how to integrate them in OpenAPI.
+
+///
## What it does
diff --git a/docs/en/docs/tutorial/security/get-current-user.md b/docs/en/docs/tutorial/security/get-current-user.md
index dc6d87c9c..5de3a8e7d 100644
--- a/docs/en/docs/tutorial/security/get-current-user.md
+++ b/docs/en/docs/tutorial/security/get-current-user.md
@@ -2,26 +2,7 @@
In the previous chapter the security system (which is based on the dependency injection system) was giving the *path operation function* a `token` as a `str`:
-=== "Python 3.9+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/security/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/security/tutorial001_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/security/tutorial001.py!}
- ```
+{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *}
But that is still not that useful.
@@ -33,41 +14,7 @@ First, let's create a Pydantic user model.
The same way we use Pydantic to declare bodies, we can use it anywhere else:
-=== "Python 3.10+"
-
- ```Python hl_lines="5 12-16"
- {!> ../../../docs_src/security/tutorial002_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="5 12-16"
- {!> ../../../docs_src/security/tutorial002_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="5 13-17"
- {!> ../../../docs_src/security/tutorial002_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="3 10-14"
- {!> ../../../docs_src/security/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="5 12-16"
- {!> ../../../docs_src/security/tutorial002.py!}
- ```
+{* ../../docs_src/security/tutorial002_an_py310.py hl[5,12:6] *}
## Create a `get_current_user` dependency
@@ -79,135 +26,39 @@ Remember that dependencies can have sub-dependencies?
The same as we were doing before in the *path operation* directly, our new dependency `get_current_user` will receive a `token` as a `str` from the sub-dependency `oauth2_scheme`:
-=== "Python 3.10+"
-
- ```Python hl_lines="25"
- {!> ../../../docs_src/security/tutorial002_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="25"
- {!> ../../../docs_src/security/tutorial002_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="26"
- {!> ../../../docs_src/security/tutorial002_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="23"
- {!> ../../../docs_src/security/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="25"
- {!> ../../../docs_src/security/tutorial002.py!}
- ```
+{* ../../docs_src/security/tutorial002_an_py310.py hl[25] *}
## Get the user
`get_current_user` will use a (fake) utility function we created, that takes a token as a `str` and returns our Pydantic `User` model:
-=== "Python 3.10+"
-
- ```Python hl_lines="19-22 26-27"
- {!> ../../../docs_src/security/tutorial002_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="19-22 26-27"
- {!> ../../../docs_src/security/tutorial002_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="20-23 27-28"
- {!> ../../../docs_src/security/tutorial002_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="17-20 24-25"
- {!> ../../../docs_src/security/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="19-22 26-27"
- {!> ../../../docs_src/security/tutorial002.py!}
- ```
+{* ../../docs_src/security/tutorial002_an_py310.py hl[19:22,26:27] *}
## Inject the current user
So now we can use the same `Depends` with our `get_current_user` in the *path operation*:
-=== "Python 3.10+"
-
- ```Python hl_lines="31"
- {!> ../../../docs_src/security/tutorial002_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="31"
- {!> ../../../docs_src/security/tutorial002_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="32"
- {!> ../../../docs_src/security/tutorial002_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="29"
- {!> ../../../docs_src/security/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="31"
- {!> ../../../docs_src/security/tutorial002.py!}
- ```
+{* ../../docs_src/security/tutorial002_an_py310.py hl[31] *}
Notice that we declare the type of `current_user` as the Pydantic model `User`.
This will help us inside of the function with all the completion and type checks.
-!!! tip
- You might remember that request bodies are also declared with Pydantic models.
+/// tip
- Here **FastAPI** won't get confused because you are using `Depends`.
+You might remember that request bodies are also declared with Pydantic models.
-!!! check
- The way this dependency system is designed allows us to have different dependencies (different "dependables") that all return a `User` model.
+Here **FastAPI** won't get confused because you are using `Depends`.
- We are not restricted to having only one dependency that can return that type of data.
+///
+
+/// check
+
+The way this dependency system is designed allows us to have different dependencies (different "dependables") that all return a `User` model.
+
+We are not restricted to having only one dependency that can return that type of data.
+
+///
## Other models
@@ -237,45 +88,11 @@ And you can make it as complex as you want. And still, have it written only once
But you can have thousands of endpoints (*path operations*) using the same security system.
-And all of them (or any portion of them that you want) can take the advantage of re-using these dependencies or any other dependencies you create.
+And all of them (or any portion of them that you want) can take advantage of re-using these dependencies or any other dependencies you create.
And all these thousands of *path operations* can be as small as 3 lines:
-=== "Python 3.10+"
-
- ```Python hl_lines="30-32"
- {!> ../../../docs_src/security/tutorial002_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="30-32"
- {!> ../../../docs_src/security/tutorial002_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="31-33"
- {!> ../../../docs_src/security/tutorial002_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="28-30"
- {!> ../../../docs_src/security/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="30-32"
- {!> ../../../docs_src/security/tutorial002.py!}
- ```
+{* ../../docs_src/security/tutorial002_an_py310.py hl[30:32] *}
## Recap
diff --git a/docs/en/docs/tutorial/security/index.md b/docs/en/docs/tutorial/security/index.md
index 659a94dc3..d33a2b14d 100644
--- a/docs/en/docs/tutorial/security/index.md
+++ b/docs/en/docs/tutorial/security/index.md
@@ -32,9 +32,11 @@ It is not very popular or used nowadays.
OAuth2 doesn't specify how to encrypt the communication, it expects you to have your application served with HTTPS.
-!!! tip
- In the section about **deployment** you will see how to set up HTTPS for free, using Traefik and Let's Encrypt.
+/// tip
+In the section about **deployment** you will see how to set up HTTPS for free, using Traefik and Let's Encrypt.
+
+///
## OpenID Connect
@@ -87,10 +89,13 @@ OpenAPI defines the following security schemes:
* This automatic discovery is what is defined in the OpenID Connect specification.
-!!! tip
- Integrating other authentication/authorization providers like Google, Facebook, Twitter, GitHub, etc. is also possible and relatively easy.
+/// tip
- The most complex problem is building an authentication/authorization provider like those, but **FastAPI** gives you the tools to do it easily, while doing the heavy lifting for you.
+Integrating other authentication/authorization providers like Google, Facebook, Twitter, GitHub, etc. is also possible and relatively easy.
+
+The most complex problem is building an authentication/authorization provider like those, but **FastAPI** gives you the tools to do it easily, while doing the heavy lifting for you.
+
+///
## **FastAPI** utilities
diff --git a/docs/en/docs/tutorial/security/oauth2-jwt.md b/docs/en/docs/tutorial/security/oauth2-jwt.md
index b011db67a..8644db45c 100644
--- a/docs/en/docs/tutorial/security/oauth2-jwt.md
+++ b/docs/en/docs/tutorial/security/oauth2-jwt.md
@@ -28,7 +28,9 @@ If you want to play with JWT tokens and see how they work, check
@@ -40,10 +42,13 @@ $ pip install pyjwt
@@ -353,8 +234,11 @@ If you open the developer tools, you could see how the data sent only includes t
-!!! note
- Notice the header `Authorization`, with a value that starts with `Bearer `.
+/// note
+
+Notice the header `Authorization`, with a value that starts with `Bearer `.
+
+///
## Advanced usage with `scopes`
diff --git a/docs/en/docs/tutorial/security/simple-oauth2.md b/docs/en/docs/tutorial/security/simple-oauth2.md
index 6f40531d7..1b70aa811 100644
--- a/docs/en/docs/tutorial/security/simple-oauth2.md
+++ b/docs/en/docs/tutorial/security/simple-oauth2.md
@@ -32,14 +32,17 @@ They are normally used to declare specific security permissions, for example:
* `instagram_basic` is used by Facebook / Instagram.
* `https://www.googleapis.com/auth/drive` is used by Google.
-!!! info
- In OAuth2 a "scope" is just a string that declares a specific permission required.
+/// info
- It doesn't matter if it has other characters like `:` or if it is a URL.
+In OAuth2 a "scope" is just a string that declares a specific permission required.
- Those details are implementation specific.
+It doesn't matter if it has other characters like `:` or if it is a URL.
- For OAuth2 they are just strings.
+Those details are implementation specific.
+
+For OAuth2 they are just strings.
+
+///
## Code to get the `username` and `password`
@@ -49,41 +52,7 @@ Now let's use the utilities provided by **FastAPI** to handle this.
First, import `OAuth2PasswordRequestForm`, and use it as a dependency with `Depends` in the *path operation* for `/token`:
-=== "Python 3.10+"
-
- ```Python hl_lines="4 78"
- {!> ../../../docs_src/security/tutorial003_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="4 78"
- {!> ../../../docs_src/security/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="4 79"
- {!> ../../../docs_src/security/tutorial003_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="2 74"
- {!> ../../../docs_src/security/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="4 76"
- {!> ../../../docs_src/security/tutorial003.py!}
- ```
+{* ../../docs_src/security/tutorial003_an_py310.py hl[4,78] *}
`OAuth2PasswordRequestForm` is a class dependency that declares a form body with:
@@ -92,29 +61,38 @@ First, import `OAuth2PasswordRequestForm`, and use it as a dependency with `Depe
* An optional `scope` field as a big string, composed of strings separated by spaces.
* An optional `grant_type`.
-!!! tip
- The OAuth2 spec actually *requires* a field `grant_type` with a fixed value of `password`, but `OAuth2PasswordRequestForm` doesn't enforce it.
+/// tip
- If you need to enforce it, use `OAuth2PasswordRequestFormStrict` instead of `OAuth2PasswordRequestForm`.
+The OAuth2 spec actually *requires* a field `grant_type` with a fixed value of `password`, but `OAuth2PasswordRequestForm` doesn't enforce it.
+
+If you need to enforce it, use `OAuth2PasswordRequestFormStrict` instead of `OAuth2PasswordRequestForm`.
+
+///
* An optional `client_id` (we don't need it for our example).
* An optional `client_secret` (we don't need it for our example).
-!!! info
- The `OAuth2PasswordRequestForm` is not a special class for **FastAPI** as is `OAuth2PasswordBearer`.
+/// info
- `OAuth2PasswordBearer` makes **FastAPI** know that it is a security scheme. So it is added that way to OpenAPI.
+The `OAuth2PasswordRequestForm` is not a special class for **FastAPI** as is `OAuth2PasswordBearer`.
- But `OAuth2PasswordRequestForm` is just a class dependency that you could have written yourself, or you could have declared `Form` parameters directly.
+`OAuth2PasswordBearer` makes **FastAPI** know that it is a security scheme. So it is added that way to OpenAPI.
- But as it's a common use case, it is provided by **FastAPI** directly, just to make it easier.
+But `OAuth2PasswordRequestForm` is just a class dependency that you could have written yourself, or you could have declared `Form` parameters directly.
+
+But as it's a common use case, it is provided by **FastAPI** directly, just to make it easier.
+
+///
### Use the form data
-!!! tip
- The instance of the dependency class `OAuth2PasswordRequestForm` won't have an attribute `scope` with the long string separated by spaces, instead, it will have a `scopes` attribute with the actual list of strings for each scope sent.
+/// tip
- We are not using `scopes` in this example, but the functionality is there if you need it.
+The instance of the dependency class `OAuth2PasswordRequestForm` won't have an attribute `scope` with the long string separated by spaces, instead, it will have a `scopes` attribute with the actual list of strings for each scope sent.
+
+We are not using `scopes` in this example, but the functionality is there if you need it.
+
+///
Now, get the user data from the (fake) database, using the `username` from the form field.
@@ -122,41 +100,7 @@ If there is no such user, we return an error saying "Incorrect username or passw
For the error, we use the exception `HTTPException`:
-=== "Python 3.10+"
-
- ```Python hl_lines="3 79-81"
- {!> ../../../docs_src/security/tutorial003_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="3 79-81"
- {!> ../../../docs_src/security/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="3 80-82"
- {!> ../../../docs_src/security/tutorial003_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="1 75-77"
- {!> ../../../docs_src/security/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="3 77-79"
- {!> ../../../docs_src/security/tutorial003.py!}
- ```
+{* ../../docs_src/security/tutorial003_an_py310.py hl[3,79:81] *}
### Check the password
@@ -182,41 +126,7 @@ If your database is stolen, the thief won't have your users' plaintext passwords
So, the thief won't be able to try to use those same passwords in another system (as many users use the same password everywhere, this would be dangerous).
-=== "Python 3.10+"
-
- ```Python hl_lines="82-85"
- {!> ../../../docs_src/security/tutorial003_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="82-85"
- {!> ../../../docs_src/security/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="83-86"
- {!> ../../../docs_src/security/tutorial003_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="78-81"
- {!> ../../../docs_src/security/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="80-83"
- {!> ../../../docs_src/security/tutorial003.py!}
- ```
+{* ../../docs_src/security/tutorial003_an_py310.py hl[82:85] *}
#### About `**user_dict`
@@ -234,8 +144,11 @@ UserInDB(
)
```
-!!! info
- For a more complete explanation of `**user_dict` check back in [the documentation for **Extra Models**](../extra-models.md#about-user_indict){.internal-link target=_blank}.
+/// info
+
+For a more complete explanation of `**user_dict` check back in [the documentation for **Extra Models**](../extra-models.md#about-user_indict){.internal-link target=_blank}.
+
+///
## Return the token
@@ -247,55 +160,27 @@ And it should have an `access_token`, with a string containing our access token.
For this simple example, we are going to just be completely insecure and return the same `username` as the token.
-!!! tip
- In the next chapter, you will see a real secure implementation, with password hashing and JWT tokens.
+/// tip
- But for now, let's focus on the specific details we need.
+In the next chapter, you will see a real secure implementation, with password hashing and JWT tokens.
-=== "Python 3.10+"
+But for now, let's focus on the specific details we need.
- ```Python hl_lines="87"
- {!> ../../../docs_src/security/tutorial003_an_py310.py!}
- ```
+///
-=== "Python 3.9+"
+{* ../../docs_src/security/tutorial003_an_py310.py hl[87] *}
- ```Python hl_lines="87"
- {!> ../../../docs_src/security/tutorial003_an_py39.py!}
- ```
+/// tip
-=== "Python 3.8+"
+By the spec, you should return a JSON with an `access_token` and a `token_type`, the same as in this example.
- ```Python hl_lines="88"
- {!> ../../../docs_src/security/tutorial003_an.py!}
- ```
+This is something that you have to do yourself in your code, and make sure you use those JSON keys.
-=== "Python 3.10+ non-Annotated"
+It's almost the only thing that you have to remember to do correctly yourself, to be compliant with the specifications.
- !!! tip
- Prefer to use the `Annotated` version if possible.
+For the rest, **FastAPI** handles it for you.
- ```Python hl_lines="83"
- {!> ../../../docs_src/security/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="85"
- {!> ../../../docs_src/security/tutorial003.py!}
- ```
-
-!!! tip
- By the spec, you should return a JSON with an `access_token` and a `token_type`, the same as in this example.
-
- This is something that you have to do yourself in your code, and make sure you use those JSON keys.
-
- It's almost the only thing that you have to remember to do correctly yourself, to be compliant with the specifications.
-
- For the rest, **FastAPI** handles it for you.
+///
## Update the dependencies
@@ -309,56 +194,25 @@ Both of these dependencies will just return an HTTP error if the user doesn't ex
So, in our endpoint, we will only get a user if the user exists, was correctly authenticated, and is active:
-=== "Python 3.10+"
+{* ../../docs_src/security/tutorial003_an_py310.py hl[58:66,69:74,94] *}
- ```Python hl_lines="58-66 69-74 94"
- {!> ../../../docs_src/security/tutorial003_an_py310.py!}
- ```
+/// info
-=== "Python 3.9+"
+The additional header `WWW-Authenticate` with value `Bearer` we are returning here is also part of the spec.
- ```Python hl_lines="58-66 69-74 94"
- {!> ../../../docs_src/security/tutorial003_an_py39.py!}
- ```
+Any HTTP (error) status code 401 "UNAUTHORIZED" is supposed to also return a `WWW-Authenticate` header.
-=== "Python 3.8+"
+In the case of bearer tokens (our case), the value of that header should be `Bearer`.
- ```Python hl_lines="59-67 70-75 95"
- {!> ../../../docs_src/security/tutorial003_an.py!}
- ```
+You can actually skip that extra header and it would still work.
-=== "Python 3.10+ non-Annotated"
+But it's provided here to be compliant with the specifications.
- !!! tip
- Prefer to use the `Annotated` version if possible.
+Also, there might be tools that expect and use it (now or in the future) and that might be useful for you or your users, now or in the future.
- ```Python hl_lines="56-64 67-70 88"
- {!> ../../../docs_src/security/tutorial003_py310.py!}
- ```
+That's the benefit of standards...
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="58-66 69-72 90"
- {!> ../../../docs_src/security/tutorial003.py!}
- ```
-
-!!! info
- The additional header `WWW-Authenticate` with value `Bearer` we are returning here is also part of the spec.
-
- Any HTTP (error) status code 401 "UNAUTHORIZED" is supposed to also return a `WWW-Authenticate` header.
-
- In the case of bearer tokens (our case), the value of that header should be `Bearer`.
-
- You can actually skip that extra header and it would still work.
-
- But it's provided here to be compliant with the specifications.
-
- Also, there might be tools that expect and use it (now or in the future) and that might be useful for you or your users, now or in the future.
-
- That's the benefit of standards...
+///
## See it in action
diff --git a/docs/en/docs/tutorial/sql-databases.md b/docs/en/docs/tutorial/sql-databases.md
index 1f0ebc08b..eac86f7fb 100644
--- a/docs/en/docs/tutorial/sql-databases.md
+++ b/docs/en/docs/tutorial/sql-databases.md
@@ -1,19 +1,18 @@
# SQL (Relational) Databases
-!!! info
- These docs are about to be updated. 🎉
+**FastAPI** doesn't require you to use a SQL (relational) database. But you can use **any database** that you want.
- The current version assumes Pydantic v1, and SQLAlchemy versions less than 2.0.
+Here we'll see an example using SQLModel.
- The new docs will include Pydantic v2 and will use SQLModel (which is also based on SQLAlchemy) once it is updated to use Pydantic v2 as well.
+**SQLModel** is built on top of SQLAlchemy and Pydantic. It was made by the same author of **FastAPI** to be the perfect match for FastAPI applications that need to use **SQL databases**.
-**FastAPI** doesn't require you to use a SQL (relational) database.
+/// tip
-But you can use any relational database that you want.
+You could use any other SQL or NoSQL database library you want (in some cases called "ORMs"), FastAPI doesn't force you to use anything. 😎
-Here we'll see an example using SQLAlchemy.
+///
-You can easily adapt it to any database supported by SQLAlchemy, like:
+As SQLModel is based on SQLAlchemy, you can easily use **any database supported** by SQLAlchemy (which makes them also supported by SQLModel), like:
* PostgreSQL
* MySQL
@@ -25,774 +24,334 @@ In this example, we'll use **SQLite**, because it uses a single file and Python
Later, for your production application, you might want to use a database server like **PostgreSQL**.
-!!! tip
- There is an official project generator with **FastAPI** and **PostgreSQL**, all based on **Docker**, including a frontend and more tools: https://github.com/tiangolo/full-stack-fastapi-postgresql
+/// tip
-!!! note
- Notice that most of the code is the standard `SQLAlchemy` code you would use with any framework.
+There is an official project generator with **FastAPI** and **PostgreSQL** including a frontend and more tools: https://github.com/fastapi/full-stack-fastapi-template
- The **FastAPI** specific code is as small as always.
+///
-## ORMs
+This is a very simple and short tutorial, if you want to learn about databases in general, about SQL, or more advanced features, go to the SQLModel docs.
-**FastAPI** works with any database and any style of library to talk to the database.
+## Install `SQLModel`
-A common pattern is to use an "ORM": an "object-relational mapping" library.
-
-An ORM has tools to convert ("*map*") between *objects* in code and database tables ("*relations*").
-
-With an ORM, you normally create a class that represents a table in a SQL database, each attribute of the class represents a column, with a name and a type.
-
-For example a class `Pet` could represent a SQL table `pets`.
-
-And each *instance* object of that class represents a row in the database.
-
-For example an object `orion_cat` (an instance of `Pet`) could have an attribute `orion_cat.type`, for the column `type`. And the value of that attribute could be, e.g. `"cat"`.
-
-These ORMs also have tools to make the connections or relations between tables or entities.
-
-This way, you could also have an attribute `orion_cat.owner` and the owner would contain the data for this pet's owner, taken from the table *owners*.
-
-So, `orion_cat.owner.name` could be the name (from the `name` column in the `owners` table) of this pet's owner.
-
-It could have a value like `"Arquilian"`.
-
-And the ORM will do all the work to get the information from the corresponding table *owners* when you try to access it from your pet object.
-
-Common ORMs are for example: Django-ORM (part of the Django framework), SQLAlchemy ORM (part of SQLAlchemy, independent of framework) and Peewee (independent of framework), among others.
-
-Here we will see how to work with **SQLAlchemy ORM**.
-
-In a similar way you could use any other ORM.
-
-!!! tip
- There's an equivalent article using Peewee here in the docs.
-
-## File structure
-
-For these examples, let's say you have a directory named `my_super_project` that contains a sub-directory called `sql_app` with a structure like this:
-
-```
-.
-└── sql_app
- ├── __init__.py
- ├── crud.py
- ├── database.py
- ├── main.py
- ├── models.py
- └── schemas.py
-```
-
-The file `__init__.py` is just an empty file, but it tells Python that `sql_app` with all its modules (Python files) is a package.
-
-Now let's see what each file/module does.
-
-## Install `SQLAlchemy`
-
-First you need to install `SQLAlchemy`:
+First, make sure you create your [virtual environment](../virtual-environments.md){.internal-link target=_blank}, activate it, and then install `sqlmodel`:
+
+
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+## Combina responses predefinidos y personalizados
+
+Es posible que desees tener algunos responses predefinidos que se apliquen a muchas *path operations*, pero que quieras combinarlos con responses personalizados necesarios por cada *path operation*.
+
+Para esos casos, puedes usar la técnica de Python de "desempaquetar" un `dict` con `**dict_to_unpack`:
+
+```Python
+old_dict = {
+ "old key": "old value",
+ "second old key": "second old value",
+}
+new_dict = {**old_dict, "new key": "new value"}
+```
+
+Aquí, `new_dict` contendrá todos los pares clave-valor de `old_dict` más el nuevo par clave-valor:
+
+```Python
+{
+ "old key": "old value",
+ "second old key": "second old value",
+ "new key": "new value",
+}
+```
+
+Puedes usar esa técnica para reutilizar algunos responses predefinidos en tus *path operations* y combinarlos con otros personalizados adicionales.
+
+Por ejemplo:
+
+{* ../../docs_src/additional_responses/tutorial004.py hl[13:17,26] *}
+
+## Más información sobre responses OpenAPI
+
+Para ver exactamente qué puedes incluir en los responses, puedes revisar estas secciones en la especificación OpenAPI:
+
+* Objeto de Responses de OpenAPI, incluye el `Response Object`.
+* Objeto de Response de OpenAPI, puedes incluir cualquier cosa de esto directamente en cada response dentro de tu parámetro `responses`. Incluyendo `description`, `headers`, `content` (dentro de este es que declaras diferentes media types y JSON Schemas), y `links`.
diff --git a/docs/es/docs/advanced/additional-status-codes.md b/docs/es/docs/advanced/additional-status-codes.md
index eaa3369eb..df7737aac 100644
--- a/docs/es/docs/advanced/additional-status-codes.md
+++ b/docs/es/docs/advanced/additional-status-codes.md
@@ -1,37 +1,41 @@
-# Códigos de estado adicionales
+# Códigos de Estado Adicionales
-Por defecto, **FastAPI** devolverá las respuestas utilizando una `JSONResponse`, poniendo el contenido que devuelves en tu *operación de path* dentro de esa `JSONResponse`.
+Por defecto, **FastAPI** devolverá los responses usando un `JSONResponse`, colocando el contenido que devuelves desde tu *path operation* dentro de ese `JSONResponse`.
-Utilizará el código de estado por defecto, o el que hayas asignado en tu *operación de path*.
+Usará el código de estado por defecto o el que configures en tu *path operation*.
## Códigos de estado adicionales
-Si quieres devolver códigos de estado adicionales además del principal, puedes hacerlo devolviendo directamente una `Response`, como una `JSONResponse`, y asignar directamente el código de estado adicional.
+Si quieres devolver códigos de estado adicionales aparte del principal, puedes hacerlo devolviendo un `Response` directamente, como un `JSONResponse`, y configurando el código de estado adicional directamente.
-Por ejemplo, digamos que quieres tener una *operación de path* que permita actualizar ítems y devolver códigos de estado HTTP 200 "OK" cuando sea exitosa.
+Por ejemplo, supongamos que quieres tener una *path operation* que permita actualizar elementos, y devuelva códigos de estado HTTP de 200 "OK" cuando sea exitoso.
-Pero también quieres que acepte nuevos ítems. Cuando los ítems no existan anteriormente, serán creados y devolverá un código de estado HTTP 201 "Created".
+Pero también quieres que acepte nuevos elementos. Y cuando los elementos no existían antes, los crea y devuelve un código de estado HTTP de 201 "Created".
-Para conseguir esto importa `JSONResponse` y devuelve ahí directamente tu contenido, asignando el `status_code` que quieras:
+Para lograr eso, importa `JSONResponse`, y devuelve tu contenido allí directamente, configurando el `status_code` que deseas:
-```Python hl_lines="4 25"
-{!../../../docs_src/additional_status_codes/tutorial001.py!}
-```
+{* ../../docs_src/additional_status_codes/tutorial001_an_py310.py hl[4,25] *}
-!!! warning "Advertencia"
- Cuando devuelves directamente una `Response`, como en los ejemplos anteriores, será devuelta directamente.
+/// warning | Advertencia
- No será serializado con el modelo, etc.
+Cuando devuelves un `Response` directamente, como en el ejemplo anterior, se devuelve directamente.
- Asegúrate de que la respuesta tenga los datos que quieras, y que los valores sean JSON válidos (si estás usando `JSONResponse`).
+No se serializará con un modelo, etc.
-!!! note "Detalles Técnicos"
- También podrías utilizar `from starlette.responses import JSONResponse`.
+Asegúrate de que tenga los datos que deseas que tenga y que los valores sean JSON válidos (si estás usando `JSONResponse`).
- **FastAPI** provee las mismas `starlette.responses` que `fastapi.responses` simplemente como una convención para ti, el desarrollador. Pero la mayoría de las respuestas disponibles vienen directamente de Starlette. Lo mismo con `status`.
+///
+
+/// note | Detalles Técnicos
+
+También podrías usar `from starlette.responses import JSONResponse`.
+
+**FastAPI** proporciona los mismos `starlette.responses` que `fastapi.responses` solo como una conveniencia para ti, el desarrollador. Pero la mayoría de los responses disponibles provienen directamente de Starlette. Lo mismo con `status`.
+
+///
## OpenAPI y documentación de API
-Si quieres devolver códigos de estado y respuestas adicionales directamente, estas no estarán incluidas en el schema de OpenAPI (documentación de API), porque FastAPI no tiene una manera de conocer de antemano lo que vas a devolver.
+Si devuelves códigos de estado adicionales y responses directamente, no se incluirán en el esquema de OpenAPI (la documentación de la API), porque FastAPI no tiene una forma de saber de antemano qué vas a devolver.
-Pero puedes documentar eso en tu código usando [Respuestas Adicionales](additional-responses.md){.internal-link target=_blank}.
+Pero puedes documentarlo en tu código, usando: [Responses Adicionales](additional-responses.md){.internal-link target=_blank}.
diff --git a/docs/es/docs/advanced/advanced-dependencies.md b/docs/es/docs/advanced/advanced-dependencies.md
new file mode 100644
index 000000000..dd3c63a37
--- /dev/null
+++ b/docs/es/docs/advanced/advanced-dependencies.md
@@ -0,0 +1,65 @@
+# Dependencias Avanzadas
+
+## Dependencias con parámetros
+
+Todas las dependencias que hemos visto son una función o clase fija.
+
+Pero podría haber casos en los que quieras poder establecer parámetros en la dependencia, sin tener que declarar muchas funciones o clases diferentes.
+
+Imaginemos que queremos tener una dependencia que revise si el parámetro de query `q` contiene algún contenido fijo.
+
+Pero queremos poder parametrizar ese contenido fijo.
+
+## Una *instance* "callable"
+
+En Python hay una forma de hacer que una instance de una clase sea un "callable".
+
+No la clase en sí (que ya es un callable), sino una instance de esa clase.
+
+Para hacer eso, declaramos un método `__call__`:
+
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[12] *}
+
+En este caso, este `__call__` es lo que **FastAPI** usará para comprobar parámetros adicionales y sub-dependencias, y es lo que llamará para pasar un valor al parámetro en tu *path operation function* más adelante.
+
+## Parametrizar la instance
+
+Y ahora, podemos usar `__init__` para declarar los parámetros de la instance que podemos usar para "parametrizar" la dependencia:
+
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[9] *}
+
+En este caso, **FastAPI** nunca tocará ni se preocupará por `__init__`, lo usaremos directamente en nuestro código.
+
+## Crear una instance
+
+Podríamos crear una instance de esta clase con:
+
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[18] *}
+
+Y de esa manera podemos "parametrizar" nuestra dependencia, que ahora tiene `"bar"` dentro de ella, como el atributo `checker.fixed_content`.
+
+## Usar la instance como una dependencia
+
+Luego, podríamos usar este `checker` en un `Depends(checker)`, en lugar de `Depends(FixedContentQueryChecker)`, porque la dependencia es la instance, `checker`, no la clase en sí.
+
+Y al resolver la dependencia, **FastAPI** llamará a este `checker` así:
+
+```Python
+checker(q="somequery")
+```
+
+...y pasará lo que eso retorne como el valor de la dependencia en nuestra *path operation function* como el parámetro `fixed_content_included`:
+
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[22] *}
+
+/// tip | Consejo
+
+Todo esto podría parecer complicado. Y puede que no esté muy claro cómo es útil aún.
+
+Estos ejemplos son intencionalmente simples, pero muestran cómo funciona todo.
+
+En los capítulos sobre seguridad, hay funciones utilitarias que se implementan de esta misma manera.
+
+Si entendiste todo esto, ya sabes cómo funcionan por debajo esas herramientas de utilidad para seguridad.
+
+///
diff --git a/docs/es/docs/advanced/async-tests.md b/docs/es/docs/advanced/async-tests.md
new file mode 100644
index 000000000..f89db1533
--- /dev/null
+++ b/docs/es/docs/advanced/async-tests.md
@@ -0,0 +1,99 @@
+# Tests Asíncronos
+
+Ya has visto cómo probar tus aplicaciones de **FastAPI** usando el `TestClient` proporcionado. Hasta ahora, solo has visto cómo escribir tests sincrónicos, sin usar funciones `async`.
+
+Poder usar funciones asíncronas en tus tests puede ser útil, por ejemplo, cuando consultas tu base de datos de forma asíncrona. Imagina que quieres probar el envío de requests a tu aplicación FastAPI y luego verificar que tu backend escribió exitosamente los datos correctos en la base de datos, mientras usas un paquete de base de datos asíncrono.
+
+Veamos cómo podemos hacer que esto funcione.
+
+## pytest.mark.anyio
+
+Si queremos llamar funciones asíncronas en nuestros tests, nuestras funciones de test tienen que ser asíncronas. AnyIO proporciona un plugin útil para esto, que nos permite especificar que algunas funciones de test deben ser llamadas de manera asíncrona.
+
+## HTTPX
+
+Incluso si tu aplicación de **FastAPI** usa funciones `def` normales en lugar de `async def`, sigue siendo una aplicación `async` por debajo.
+
+El `TestClient` hace algo de magia interna para llamar a la aplicación FastAPI asíncrona en tus funciones de test `def` normales, usando pytest estándar. Pero esa magia ya no funciona cuando lo usamos dentro de funciones asíncronas. Al ejecutar nuestros tests de manera asíncrona, ya no podemos usar el `TestClient` dentro de nuestras funciones de test.
+
+El `TestClient` está basado en HTTPX, y afortunadamente, podemos usarlo directamente para probar la API.
+
+## Ejemplo
+
+Para un ejemplo simple, consideremos una estructura de archivos similar a la descrita en [Aplicaciones Más Grandes](../tutorial/bigger-applications.md){.internal-link target=_blank} y [Testing](../tutorial/testing.md){.internal-link target=_blank}:
+
+```
+.
+├── app
+│ ├── __init__.py
+│ ├── main.py
+│ └── test_main.py
+```
+
+El archivo `main.py` tendría:
+
+{* ../../docs_src/async_tests/main.py *}
+
+El archivo `test_main.py` tendría los tests para `main.py`, podría verse así ahora:
+
+{* ../../docs_src/async_tests/test_main.py *}
+
+## Ejecútalo
+
+Puedes ejecutar tus tests como de costumbre vía:
+
+
+
+Pero si accedemos a la UI de los docs en la URL "oficial" usando el proxy con puerto `9999`, en `/api/v1/docs`, ¡funciona correctamente! 🎉
+
+Puedes verificarlo en http://127.0.0.1:9999/api/v1/docs:
+
+
+
+Justo como queríamos. ✔️
+
+Esto es porque FastAPI usa este `root_path` para crear el `server` por defecto en OpenAPI con la URL proporcionada por `root_path`.
+
+## Servidores adicionales
+
+/// warning | Advertencia
+
+Este es un caso de uso más avanzado. Siéntete libre de omitirlo.
+
+///
+
+Por defecto, **FastAPI** creará un `server` en el esquema de OpenAPI con la URL para el `root_path`.
+
+Pero también puedes proporcionar otros `servers` alternativos, por ejemplo, si deseas que *la misma* UI de los docs interactúe con un entorno de pruebas y de producción.
+
+Si pasas una lista personalizada de `servers` y hay un `root_path` (porque tu API existe detrás de un proxy), **FastAPI** insertará un "server" con este `root_path` al comienzo de la lista.
+
+Por ejemplo:
+
+{* ../../docs_src/behind_a_proxy/tutorial003.py hl[4:7] *}
+
+Generará un esquema de OpenAPI como:
+
+```JSON hl_lines="5-7"
+{
+ "openapi": "3.1.0",
+ // Más cosas aquí
+ "servers": [
+ {
+ "url": "/api/v1"
+ },
+ {
+ "url": "https://stag.example.com",
+ "description": "Entorno de pruebas"
+ },
+ {
+ "url": "https://prod.example.com",
+ "description": "Entorno de producción"
+ }
+ ],
+ "paths": {
+ // Más cosas aquí
+ }
+}
+```
+
+/// tip | Consejo
+
+Observa el server auto-generado con un valor `url` de `/api/v1`, tomado del `root_path`.
+
+///
+
+En la UI de los docs en http://127.0.0.1:9999/api/v1/docs se vería como:
+
+
+
+/// tip | Consejo
+
+La UI de los docs interactuará con el server que selecciones.
+
+///
+
+### Desactivar el server automático de `root_path`
+
+Si no quieres que **FastAPI** incluya un server automático usando el `root_path`, puedes usar el parámetro `root_path_in_servers=False`:
+
+{* ../../docs_src/behind_a_proxy/tutorial004.py hl[9] *}
+
+y entonces no lo incluirá en el esquema de OpenAPI.
+
+## Montando una sub-aplicación
+
+Si necesitas montar una sub-aplicación (como se describe en [Aplicaciones secundarias - Monturas](sub-applications.md){.internal-link target=_blank}) mientras usas un proxy con `root_path`, puedes hacerlo normalmente, como esperarías.
+
+FastAPI usará internamente el `root_path` de manera inteligente, así que simplemente funcionará. ✨
diff --git a/docs/es/docs/advanced/custom-response.md b/docs/es/docs/advanced/custom-response.md
new file mode 100644
index 000000000..f7bd81bcc
--- /dev/null
+++ b/docs/es/docs/advanced/custom-response.md
@@ -0,0 +1,312 @@
+# Response Personalizado - HTML, Stream, Archivo, otros
+
+Por defecto, **FastAPI** devolverá los responses usando `JSONResponse`.
+
+Puedes sobrescribirlo devolviendo un `Response` directamente como se ve en [Devolver una Response directamente](response-directly.md){.internal-link target=_blank}.
+
+Pero si devuelves un `Response` directamente (o cualquier subclase, como `JSONResponse`), los datos no se convertirán automáticamente (incluso si declaras un `response_model`), y la documentación no se generará automáticamente (por ejemplo, incluyendo el "media type" específico, en el HTTP header `Content-Type` como parte del OpenAPI generado).
+
+Pero también puedes declarar el `Response` que quieres usar (por ejemplo, cualquier subclase de `Response`), en el *path operation decorator* usando el parámetro `response_class`.
+
+Los contenidos que devuelvas desde tu *path operation function* se colocarán dentro de esa `Response`.
+
+Y si ese `Response` tiene un media type JSON (`application/json`), como es el caso con `JSONResponse` y `UJSONResponse`, los datos que devuelvas se convertirán automáticamente (y serán filtrados) con cualquier `response_model` de Pydantic que hayas declarado en el *path operation decorator*.
+
+/// note | Nota
+
+Si usas una clase de response sin media type, FastAPI esperará que tu response no tenga contenido, por lo que no documentará el formato del response en su OpenAPI generado.
+
+///
+
+## Usa `ORJSONResponse`
+
+Por ejemplo, si estás exprimendo el rendimiento, puedes instalar y usar `orjson` y establecer el response como `ORJSONResponse`.
+
+Importa la clase `Response` (sub-clase) que quieras usar y declárala en el *path operation decorator*.
+
+Para responses grandes, devolver una `Response` directamente es mucho más rápido que devolver un diccionario.
+
+Esto se debe a que, por defecto, FastAPI inspeccionará cada elemento dentro y se asegurará de que sea serializable como JSON, usando el mismo [Codificador Compatible con JSON](../tutorial/encoder.md){.internal-link target=_blank} explicado en el tutorial. Esto es lo que te permite devolver **objetos arbitrarios**, por ejemplo, modelos de bases de datos.
+
+Pero si estás seguro de que el contenido que estás devolviendo es **serializable con JSON**, puedes pasarlo directamente a la clase de response y evitar la sobrecarga extra que FastAPI tendría al pasar tu contenido de retorno a través de `jsonable_encoder` antes de pasarlo a la clase de response.
+
+{* ../../docs_src/custom_response/tutorial001b.py hl[2,7] *}
+
+/// info | Información
+
+El parámetro `response_class` también se utilizará para definir el "media type" del response.
+
+En este caso, el HTTP header `Content-Type` se establecerá en `application/json`.
+
+Y se documentará así en OpenAPI.
+
+///
+
+/// tip | Consejo
+
+El `ORJSONResponse` solo está disponible en FastAPI, no en Starlette.
+
+///
+
+## Response HTML
+
+Para devolver un response con HTML directamente desde **FastAPI**, usa `HTMLResponse`.
+
+* Importa `HTMLResponse`.
+* Pasa `HTMLResponse` como parámetro `response_class` de tu *path operation decorator*.
+
+{* ../../docs_src/custom_response/tutorial002.py hl[2,7] *}
+
+/// info | Información
+
+El parámetro `response_class` también se utilizará para definir el "media type" del response.
+
+En este caso, el HTTP header `Content-Type` se establecerá en `text/html`.
+
+Y se documentará así en OpenAPI.
+
+///
+
+### Devuelve una `Response`
+
+Como se ve en [Devolver una Response directamente](response-directly.md){.internal-link target=_blank}, también puedes sobrescribir el response directamente en tu *path operation*, devolviéndolo.
+
+El mismo ejemplo de arriba, devolviendo una `HTMLResponse`, podría verse así:
+
+{* ../../docs_src/custom_response/tutorial003.py hl[2,7,19] *}
+
+/// warning | Advertencia
+
+Una `Response` devuelta directamente por tu *path operation function* no se documentará en OpenAPI (por ejemplo, el `Content-Type` no se documentará) y no será visible en la documentación interactiva automática.
+
+///
+
+/// info | Información
+
+Por supuesto, el `Content-Type` header real, el código de estado, etc., provendrán del objeto `Response` que devolviste.
+
+///
+
+### Documenta en OpenAPI y sobrescribe `Response`
+
+Si quieres sobrescribir el response desde dentro de la función pero al mismo tiempo documentar el "media type" en OpenAPI, puedes usar el parámetro `response_class` Y devolver un objeto `Response`.
+
+El `response_class` solo se usará para documentar el OpenAPI *path operation*, pero tu `Response` se usará tal cual.
+
+#### Devuelve un `HTMLResponse` directamente
+
+Por ejemplo, podría ser algo así:
+
+{* ../../docs_src/custom_response/tutorial004.py hl[7,21,23] *}
+
+En este ejemplo, la función `generate_html_response()` ya genera y devuelve una `Response` en lugar de devolver el HTML en un `str`.
+
+Al devolver el resultado de llamar a `generate_html_response()`, ya estás devolviendo una `Response` que sobrescribirá el comportamiento predeterminado de **FastAPI**.
+
+Pero como pasaste `HTMLResponse` en el `response_class` también, **FastAPI** sabrá cómo documentarlo en OpenAPI y la documentación interactiva como HTML con `text/html`:
+
+
+
+## Responses disponibles
+
+Aquí hay algunos de los responses disponibles.
+
+Ten en cuenta que puedes usar `Response` para devolver cualquier otra cosa, o incluso crear una sub-clase personalizada.
+
+/// note | Nota Técnica
+
+También podrías usar `from starlette.responses import HTMLResponse`.
+
+**FastAPI** proporciona los mismos `starlette.responses` como `fastapi.responses` solo como una conveniencia para ti, el desarrollador. Pero la mayoría de los responses disponibles vienen directamente de Starlette.
+
+///
+
+### `Response`
+
+La clase principal `Response`, todos los otros responses heredan de ella.
+
+Puedes devolverla directamente.
+
+Acepta los siguientes parámetros:
+
+* `content` - Un `str` o `bytes`.
+* `status_code` - Un código de estado HTTP `int`.
+* `headers` - Un `dict` de strings.
+* `media_type` - Un `str` que da el media type. Por ejemplo, `"text/html"`.
+
+FastAPI (de hecho Starlette) incluirá automáticamente un header Content-Length. También incluirá un header Content-Type, basado en el `media_type` y añadiendo un conjunto de caracteres para tipos de texto.
+
+{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
+
+### `HTMLResponse`
+
+Toma algún texto o bytes y devuelve un response HTML, como leíste arriba.
+
+### `PlainTextResponse`
+
+Toma algún texto o bytes y devuelve un response de texto plano.
+
+{* ../../docs_src/custom_response/tutorial005.py hl[2,7,9] *}
+
+### `JSONResponse`
+
+Toma algunos datos y devuelve un response codificado como `application/json`.
+
+Este es el response predeterminado usado en **FastAPI**, como leíste arriba.
+
+### `ORJSONResponse`
+
+Un response JSON rápido alternativo usando `orjson`, como leíste arriba.
+
+/// info | Información
+
+Esto requiere instalar `orjson`, por ejemplo, con `pip install orjson`.
+
+///
+
+### `UJSONResponse`
+
+Un response JSON alternativo usando `ujson`.
+
+/// info | Información
+
+Esto requiere instalar `ujson`, por ejemplo, con `pip install ujson`.
+
+///
+
+/// warning | Advertencia
+
+`ujson` es menos cuidadoso que la implementación integrada de Python en cómo maneja algunos casos extremos.
+
+///
+
+{* ../../docs_src/custom_response/tutorial001.py hl[2,7] *}
+
+/// tip | Consejo
+
+Es posible que `ORJSONResponse` sea una alternativa más rápida.
+
+///
+
+### `RedirectResponse`
+
+Devuelve una redirección HTTP. Usa un código de estado 307 (Redirección Temporal) por defecto.
+
+Puedes devolver un `RedirectResponse` directamente:
+
+{* ../../docs_src/custom_response/tutorial006.py hl[2,9] *}
+
+---
+
+O puedes usarlo en el parámetro `response_class`:
+
+{* ../../docs_src/custom_response/tutorial006b.py hl[2,7,9] *}
+
+Si haces eso, entonces puedes devolver la URL directamente desde tu *path operation function*.
+
+En este caso, el `status_code` utilizado será el predeterminado para `RedirectResponse`, que es `307`.
+
+---
+
+También puedes usar el parámetro `status_code` combinado con el parámetro `response_class`:
+
+{* ../../docs_src/custom_response/tutorial006c.py hl[2,7,9] *}
+
+### `StreamingResponse`
+
+Toma un generador `async` o un generador/iterador normal y transmite el cuerpo del response.
+
+{* ../../docs_src/custom_response/tutorial007.py hl[2,14] *}
+
+#### Usando `StreamingResponse` con objetos similares a archivos
+
+Si tienes un objeto similar a un archivo (por ejemplo, el objeto devuelto por `open()`), puedes crear una función generadora para iterar sobre ese objeto similar a un archivo.
+
+De esa manera, no tienes que leerlo todo primero en memoria, y puedes pasar esa función generadora al `StreamingResponse`, y devolverlo.
+
+Esto incluye muchos paquetes para interactuar con almacenamiento en la nube, procesamiento de video y otros.
+
+{* ../../docs_src/custom_response/tutorial008.py hl[2,10:12,14] *}
+
+1. Esta es la función generadora. Es una "función generadora" porque contiene declaraciones `yield` dentro.
+2. Al usar un bloque `with`, nos aseguramos de que el objeto similar a un archivo se cierre después de que la función generadora termine. Así, después de que termina de enviar el response.
+3. Este `yield from` le dice a la función que itere sobre esa cosa llamada `file_like`. Y luego, para cada parte iterada, yield esa parte como proveniente de esta función generadora (`iterfile`).
+
+ Entonces, es una función generadora que transfiere el trabajo de "generar" a algo más internamente.
+
+ Al hacerlo de esta manera, podemos ponerlo en un bloque `with`, y de esa manera, asegurarnos de que el objeto similar a un archivo se cierre después de finalizar.
+
+/// tip | Consejo
+
+Nota que aquí como estamos usando `open()` estándar que no admite `async` y `await`, declaramos el path operation con `def` normal.
+
+///
+
+### `FileResponse`
+
+Transmite un archivo asincrónicamente como response.
+
+Toma un conjunto diferente de argumentos para crear un instance que los otros tipos de response:
+
+* `path` - La path del archivo para el archivo a transmitir.
+* `headers` - Cualquier header personalizado para incluir, como un diccionario.
+* `media_type` - Un string que da el media type. Si no se establece, se usará el nombre de archivo o la path para inferir un media type.
+* `filename` - Si se establece, se incluirá en el response `Content-Disposition`.
+
+Los responses de archivos incluirán los headers apropiados `Content-Length`, `Last-Modified` y `ETag`.
+
+{* ../../docs_src/custom_response/tutorial009.py hl[2,10] *}
+
+También puedes usar el parámetro `response_class`:
+
+{* ../../docs_src/custom_response/tutorial009b.py hl[2,8,10] *}
+
+En este caso, puedes devolver la path del archivo directamente desde tu *path operation* function.
+
+## Clase de response personalizada
+
+Puedes crear tu propia clase de response personalizada, heredando de `Response` y usándola.
+
+Por ejemplo, digamos que quieres usar `orjson`, pero con algunas configuraciones personalizadas no utilizadas en la clase `ORJSONResponse` incluida.
+
+Digamos que quieres que devuelva JSON con sangría y formato, por lo que quieres usar la opción de orjson `orjson.OPT_INDENT_2`.
+
+Podrías crear un `CustomORJSONResponse`. Lo principal que tienes que hacer es crear un método `Response.render(content)` que devuelva el contenido como `bytes`:
+
+{* ../../docs_src/custom_response/tutorial009c.py hl[9:14,17] *}
+
+Ahora en lugar de devolver:
+
+```json
+{"message": "Hello World"}
+```
+
+...este response devolverá:
+
+```json
+{
+ "message": "Hello World"
+}
+```
+
+Por supuesto, probablemente encontrarás formas mucho mejores de aprovechar esto que formatear JSON. 😉
+
+## Clase de response predeterminada
+
+Al crear una instance de la clase **FastAPI** o un `APIRouter`, puedes especificar qué clase de response usar por defecto.
+
+El parámetro que define esto es `default_response_class`.
+
+En el ejemplo a continuación, **FastAPI** usará `ORJSONResponse` por defecto, en todas las *path operations*, en lugar de `JSONResponse`.
+
+{* ../../docs_src/custom_response/tutorial010.py hl[2,4] *}
+
+/// tip | Consejo
+
+Todavía puedes sobrescribir `response_class` en *path operations* como antes.
+
+///
+
+## Documentación adicional
+
+También puedes declarar el media type y muchos otros detalles en OpenAPI usando `responses`: [Responses Adicionales en OpenAPI](additional-responses.md){.internal-link target=_blank}.
diff --git a/docs/es/docs/advanced/dataclasses.md b/docs/es/docs/advanced/dataclasses.md
new file mode 100644
index 000000000..0ca1fd3b6
--- /dev/null
+++ b/docs/es/docs/advanced/dataclasses.md
@@ -0,0 +1,95 @@
+# Usando Dataclasses
+
+FastAPI está construido sobre **Pydantic**, y te he estado mostrando cómo usar modelos de Pydantic para declarar requests y responses.
+
+Pero FastAPI también soporta el uso de `dataclasses` de la misma manera:
+
+{* ../../docs_src/dataclasses/tutorial001.py hl[1,7:12,19:20] *}
+
+Esto sigue siendo soportado gracias a **Pydantic**, ya que tiene soporte interno para `dataclasses`.
+
+Así que, incluso con el código anterior que no usa Pydantic explícitamente, FastAPI está usando Pydantic para convertir esos dataclasses estándar en su propia versión de dataclasses de Pydantic.
+
+Y por supuesto, soporta lo mismo:
+
+* validación de datos
+* serialización de datos
+* documentación de datos, etc.
+
+Esto funciona de la misma manera que con los modelos de Pydantic. Y en realidad se logra de la misma manera internamente, utilizando Pydantic.
+
+/// info | Información
+
+Ten en cuenta que los dataclasses no pueden hacer todo lo que los modelos de Pydantic pueden hacer.
+
+Así que, podrías necesitar seguir usando modelos de Pydantic.
+
+Pero si tienes un montón de dataclasses por ahí, este es un buen truco para usarlos para potenciar una API web usando FastAPI. 🤓
+
+///
+
+## Dataclasses en `response_model`
+
+También puedes usar `dataclasses` en el parámetro `response_model`:
+
+{* ../../docs_src/dataclasses/tutorial002.py hl[1,7:13,19] *}
+
+El dataclass será automáticamente convertido a un dataclass de Pydantic.
+
+De esta manera, su esquema aparecerá en la interfaz de usuario de la documentación de la API:
+
+
+
+## Dataclasses en Estructuras de Datos Anidadas
+
+También puedes combinar `dataclasses` con otras anotaciones de tipos para crear estructuras de datos anidadas.
+
+En algunos casos, todavía podrías tener que usar la versión de `dataclasses` de Pydantic. Por ejemplo, si tienes errores con la documentación de la API generada automáticamente.
+
+En ese caso, simplemente puedes intercambiar los `dataclasses` estándar con `pydantic.dataclasses`, que es un reemplazo directo:
+
+{* ../../docs_src/dataclasses/tutorial003.py hl[1,5,8:11,14:17,23:25,28] *}
+
+1. Todavía importamos `field` de los `dataclasses` estándar.
+
+2. `pydantic.dataclasses` es un reemplazo directo para `dataclasses`.
+
+3. El dataclass `Author` incluye una lista de dataclasses `Item`.
+
+4. El dataclass `Author` se usa como el parámetro `response_model`.
+
+5. Puedes usar otras anotaciones de tipos estándar con dataclasses como el request body.
+
+ En este caso, es una lista de dataclasses `Item`.
+
+6. Aquí estamos regresando un diccionario que contiene `items`, que es una lista de dataclasses.
+
+ FastAPI todavía es capaz de serializar los datos a JSON.
+
+7. Aquí el `response_model` está usando una anotación de tipo de una lista de dataclasses `Author`.
+
+ Nuevamente, puedes combinar `dataclasses` con anotaciones de tipos estándar.
+
+8. Nota que esta *path operation function* usa `def` regular en lugar de `async def`.
+
+ Como siempre, en FastAPI puedes combinar `def` y `async def` según sea necesario.
+
+ Si necesitas un repaso sobre cuándo usar cuál, revisa la sección _"¿Con prisa?"_ en la documentación sobre [`async` y `await`](../async.md#in-a-hurry){.internal-link target=_blank}.
+
+9. Esta *path operation function* no está devolviendo dataclasses (aunque podría), sino una lista de diccionarios con datos internos.
+
+ FastAPI usará el parámetro `response_model` (que incluye dataclasses) para convertir el response.
+
+Puedes combinar `dataclasses` con otras anotaciones de tipos en muchas combinaciones diferentes para formar estructuras de datos complejas.
+
+Revisa las anotaciones en el código arriba para ver más detalles específicos.
+
+## Aprende Más
+
+También puedes combinar `dataclasses` con otros modelos de Pydantic, heredar de ellos, incluirlos en tus propios modelos, etc.
+
+Para saber más, revisa la documentación de Pydantic sobre dataclasses.
+
+## Versión
+
+Esto está disponible desde la versión `0.67.0` de FastAPI. 🔖
diff --git a/docs/es/docs/advanced/events.md b/docs/es/docs/advanced/events.md
new file mode 100644
index 000000000..022fb5a42
--- /dev/null
+++ b/docs/es/docs/advanced/events.md
@@ -0,0 +1,165 @@
+# Eventos de Lifespan
+
+Puedes definir lógica (código) que debería ser ejecutada antes de que la aplicación **inicie**. Esto significa que este código será ejecutado **una vez**, **antes** de que la aplicación **comience a recibir requests**.
+
+De la misma manera, puedes definir lógica (código) que debería ser ejecutada cuando la aplicación esté **cerrándose**. En este caso, este código será ejecutado **una vez**, **después** de haber manejado posiblemente **muchos requests**.
+
+Debido a que este código se ejecuta antes de que la aplicación **comience** a tomar requests, y justo después de que **termine** de manejarlos, cubre todo el **lifespan** de la aplicación (la palabra "lifespan" será importante en un momento 😉).
+
+Esto puede ser muy útil para configurar **recursos** que necesitas usar para toda la app, y que son **compartidos** entre requests, y/o que necesitas **limpiar** después. Por ejemplo, un pool de conexiones a una base de datos, o cargando un modelo de machine learning compartido.
+
+## Caso de Uso
+
+Empecemos con un ejemplo de **caso de uso** y luego veamos cómo resolverlo con esto.
+
+Imaginemos que tienes algunos **modelos de machine learning** que quieres usar para manejar requests. 🤖
+
+Los mismos modelos son compartidos entre requests, por lo que no es un modelo por request, o uno por usuario o algo similar.
+
+Imaginemos que cargar el modelo puede **tomar bastante tiempo**, porque tiene que leer muchos **datos del disco**. Entonces no quieres hacerlo para cada request.
+
+Podrías cargarlo en el nivel superior del módulo/archivo, pero eso también significaría que **cargaría el modelo** incluso si solo estás ejecutando una simple prueba automatizada, entonces esa prueba sería **lenta** porque tendría que esperar a que el modelo se cargue antes de poder ejecutar una parte independiente del código.
+
+Eso es lo que resolveremos, vamos a cargar el modelo antes de que los requests sean manejados, pero solo justo antes de que la aplicación comience a recibir requests, no mientras el código se está cargando.
+
+## Lifespan
+
+Puedes definir esta lógica de *startup* y *shutdown* usando el parámetro `lifespan` de la app de `FastAPI`, y un "context manager" (te mostraré lo que es en un momento).
+
+Comencemos con un ejemplo y luego veámoslo en detalle.
+
+Creamos una función asíncrona `lifespan()` con `yield` así:
+
+{* ../../docs_src/events/tutorial003.py hl[16,19] *}
+
+Aquí estamos simulando la operación costosa de *startup* de cargar el modelo poniendo la función del (falso) modelo en el diccionario con modelos de machine learning antes del `yield`. Este código será ejecutado **antes** de que la aplicación **comience a tomar requests**, durante el *startup*.
+
+Y luego, justo después del `yield`, quitaremos el modelo de memoria. Este código será ejecutado **después** de que la aplicación **termine de manejar requests**, justo antes del *shutdown*. Esto podría, por ejemplo, liberar recursos como la memoria o una GPU.
+
+/// tip | Consejo
+
+El `shutdown` ocurriría cuando estás **deteniendo** la aplicación.
+
+Quizás necesites iniciar una nueva versión, o simplemente te cansaste de ejecutarla. 🤷
+
+///
+
+### Función de Lifespan
+
+Lo primero que hay que notar es que estamos definiendo una función asíncrona con `yield`. Esto es muy similar a las Dependencias con `yield`.
+
+{* ../../docs_src/events/tutorial003.py hl[14:19] *}
+
+La primera parte de la función, antes del `yield`, será ejecutada **antes** de que la aplicación comience.
+
+Y la parte después del `yield` será ejecutada **después** de que la aplicación haya terminado.
+
+### Async Context Manager
+
+Si revisas, la función está decorada con un `@asynccontextmanager`.
+
+Eso convierte a la función en algo llamado un "**async context manager**".
+
+{* ../../docs_src/events/tutorial003.py hl[1,13] *}
+
+Un **context manager** en Python es algo que puedes usar en una declaración `with`, por ejemplo, `open()` puede ser usado como un context manager:
+
+```Python
+with open("file.txt") as file:
+ file.read()
+```
+
+En versiones recientes de Python, también hay un **async context manager**. Lo usarías con `async with`:
+
+```Python
+async with lifespan(app):
+ await do_stuff()
+```
+
+Cuando creas un context manager o un async context manager como arriba, lo que hace es que, antes de entrar al bloque `with`, ejecutará el código antes del `yield`, y al salir del bloque `with`, ejecutará el código después del `yield`.
+
+En nuestro ejemplo de código arriba, no lo usamos directamente, pero se lo pasamos a FastAPI para que lo use.
+
+El parámetro `lifespan` de la app de `FastAPI` toma un **async context manager**, por lo que podemos pasar nuestro nuevo `lifespan` async context manager a él.
+
+{* ../../docs_src/events/tutorial003.py hl[22] *}
+
+## Eventos Alternativos (obsoleto)
+
+/// warning | Advertencia
+
+La forma recomendada de manejar el *startup* y el *shutdown* es usando el parámetro `lifespan` de la app de `FastAPI` como se describió arriba. Si proporcionas un parámetro `lifespan`, los manejadores de eventos `startup` y `shutdown` ya no serán llamados. Es solo `lifespan` o solo los eventos, no ambos.
+
+Probablemente puedas saltarte esta parte.
+
+///
+
+Hay una forma alternativa de definir esta lógica para ser ejecutada durante el *startup* y durante el *shutdown*.
+
+Puedes definir manejadores de eventos (funciones) que necesitan ser ejecutadas antes de que la aplicación se inicie, o cuando la aplicación se está cerrando.
+
+Estas funciones pueden ser declaradas con `async def` o `def` normal.
+
+### Evento `startup`
+
+Para añadir una función que debería ejecutarse antes de que la aplicación inicie, declárala con el evento `"startup"`:
+
+{* ../../docs_src/events/tutorial001.py hl[8] *}
+
+En este caso, la función manejadora del evento `startup` inicializará los ítems de la "base de datos" (solo un `dict`) con algunos valores.
+
+Puedes añadir más de un manejador de eventos.
+
+Y tu aplicación no comenzará a recibir requests hasta que todos los manejadores de eventos `startup` hayan completado.
+
+### Evento `shutdown`
+
+Para añadir una función que debería ejecutarse cuando la aplicación se esté cerrando, declárala con el evento `"shutdown"`:
+
+{* ../../docs_src/events/tutorial002.py hl[6] *}
+
+Aquí, la función manejadora del evento `shutdown` escribirá una línea de texto `"Application shutdown"` a un archivo `log.txt`.
+
+/// info | Información
+
+En la función `open()`, el `mode="a"` significa "añadir", por lo tanto, la línea será añadida después de lo que sea que esté en ese archivo, sin sobrescribir el contenido anterior.
+
+///
+
+/// tip | Consejo
+
+Nota que en este caso estamos usando una función estándar de Python `open()` que interactúa con un archivo.
+
+Entonces, involucra I/O (entrada/salida), que requiere "esperar" para que las cosas se escriban en el disco.
+
+Pero `open()` no usa `async` y `await`.
+
+Por eso, declaramos la función manejadora del evento con `def` estándar en vez de `async def`.
+
+///
+
+### `startup` y `shutdown` juntos
+
+Hay una gran posibilidad de que la lógica para tu *startup* y *shutdown* esté conectada, podrías querer iniciar algo y luego finalizarlo, adquirir un recurso y luego liberarlo, etc.
+
+Hacer eso en funciones separadas que no comparten lógica o variables juntas es más difícil ya que necesitarías almacenar valores en variables globales o trucos similares.
+
+Debido a eso, ahora se recomienda en su lugar usar el `lifespan` como se explicó arriba.
+
+## Detalles Técnicos
+
+Solo un detalle técnico para los nerds curiosos. 🤓
+
+Por debajo, en la especificación técnica ASGI, esto es parte del Protocolo de Lifespan, y define eventos llamados `startup` y `shutdown`.
+
+/// info | Información
+
+Puedes leer más sobre los manejadores `lifespan` de Starlette en la documentación de `Lifespan` de Starlette.
+
+Incluyendo cómo manejar el estado de lifespan que puede ser usado en otras áreas de tu código.
+
+///
+
+## Sub Aplicaciones
+
+🚨 Ten en cuenta que estos eventos de lifespan (startup y shutdown) solo serán ejecutados para la aplicación principal, no para [Sub Aplicaciones - Mounts](sub-applications.md){.internal-link target=_blank}.
diff --git a/docs/es/docs/advanced/generate-clients.md b/docs/es/docs/advanced/generate-clients.md
new file mode 100644
index 000000000..b664bceac
--- /dev/null
+++ b/docs/es/docs/advanced/generate-clients.md
@@ -0,0 +1,261 @@
+# Genera Clientes
+
+Como **FastAPI** está basado en la especificación OpenAPI, obtienes compatibilidad automática con muchas herramientas, incluyendo la documentación automática de la API (proporcionada por Swagger UI).
+
+Una ventaja particular que no es necesariamente obvia es que puedes **generar clientes** (a veces llamados **SDKs** ) para tu API, para muchos **lenguajes de programación** diferentes.
+
+## Generadores de Clientes OpenAPI
+
+Hay muchas herramientas para generar clientes desde **OpenAPI**.
+
+Una herramienta común es OpenAPI Generator.
+
+Si estás construyendo un **frontend**, una alternativa muy interesante es openapi-ts.
+
+## Generadores de Clientes y SDKs - Sponsor
+
+También hay algunos generadores de Clientes y SDKs **respaldados por empresas** basados en OpenAPI (FastAPI), en algunos casos pueden ofrecerte **funcionalidades adicionales** además de SDKs/clientes generados de alta calidad.
+
+Algunos de ellos también ✨ [**sponsorean FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨, esto asegura el **desarrollo** continuo y saludable de FastAPI y su **ecosistema**.
+
+Y muestra su verdadero compromiso con FastAPI y su **comunidad** (tú), ya que no solo quieren proporcionarte un **buen servicio** sino también asegurarse de que tengas un **buen y saludable framework**, FastAPI. 🙇
+
+Por ejemplo, podrías querer probar:
+
+* Speakeasy
+* Stainless
+* liblab
+
+También hay varias otras empresas que ofrecen servicios similares que puedes buscar y encontrar en línea. 🤓
+
+## Genera un Cliente Frontend en TypeScript
+
+Empecemos con una aplicación simple de FastAPI:
+
+{* ../../docs_src/generate_clients/tutorial001_py39.py hl[7:9,12:13,16:17,21] *}
+
+Nota que las *path operations* definen los modelos que usan para el payload de la petición y el payload del response, usando los modelos `Item` y `ResponseMessage`.
+
+### Documentación de la API
+
+Si vas a la documentación de la API, verás que tiene los **esquemas** para los datos que se enviarán en las peticiones y se recibirán en los responses:
+
+
+
+Puedes ver esos esquemas porque fueron declarados con los modelos en la aplicación.
+
+Esa información está disponible en el **JSON Schema** de OpenAPI de la aplicación, y luego se muestra en la documentación de la API (por Swagger UI).
+
+Y esa misma información de los modelos que está incluida en OpenAPI es lo que puede usarse para **generar el código del cliente**.
+
+### Genera un Cliente en TypeScript
+
+Ahora que tenemos la aplicación con los modelos, podemos generar el código del cliente para el frontend.
+
+#### Instalar `openapi-ts`
+
+Puedes instalar `openapi-ts` en tu código de frontend con:
+
+
+
+También obtendrás autocompletado para el payload a enviar:
+
+
+
+/// tip | Consejo
+
+Nota el autocompletado para `name` y `price`, que fue definido en la aplicación de FastAPI, en el modelo `Item`.
+
+///
+
+Tendrás errores en línea para los datos que envíes:
+
+
+
+El objeto de response también tendrá autocompletado:
+
+
+
+## App de FastAPI con Tags
+
+En muchos casos tu aplicación de FastAPI será más grande, y probablemente usarás tags para separar diferentes grupos de *path operations*.
+
+Por ejemplo, podrías tener una sección para **items** y otra sección para **usuarios**, y podrían estar separadas por tags:
+
+{* ../../docs_src/generate_clients/tutorial002_py39.py hl[21,26,34] *}
+
+### Genera un Cliente TypeScript con Tags
+
+Si generas un cliente para una aplicación de FastAPI usando tags, normalmente también separará el código del cliente basándose en los tags.
+
+De esta manera podrás tener las cosas ordenadas y agrupadas correctamente para el código del cliente:
+
+
+
+En este caso tienes:
+
+* `ItemsService`
+* `UsersService`
+
+### Nombres de los Métodos del Cliente
+
+Ahora mismo los nombres de los métodos generados como `createItemItemsPost` no se ven muy limpios:
+
+```TypeScript
+ItemsService.createItemItemsPost({name: "Plumbus", price: 5})
+```
+
+...eso es porque el generador del cliente usa el **operation ID** interno de OpenAPI para cada *path operation*.
+
+OpenAPI requiere que cada operation ID sea único a través de todas las *path operations*, por lo que FastAPI usa el **nombre de la función**, el **path**, y el **método/operación HTTP** para generar ese operation ID, porque de esa manera puede asegurarse de que los operation IDs sean únicos.
+
+Pero te mostraré cómo mejorar eso a continuación. 🤓
+
+## Operation IDs Personalizados y Mejores Nombres de Métodos
+
+Puedes **modificar** la forma en que estos operation IDs son **generados** para hacerlos más simples y tener **nombres de métodos más simples** en los clientes.
+
+En este caso tendrás que asegurarte de que cada operation ID sea **único** de alguna otra manera.
+
+Por ejemplo, podrías asegurarte de que cada *path operation* tenga un tag, y luego generar el operation ID basado en el **tag** y el nombre de la *path operation* **name** (el nombre de la función).
+
+### Función Personalizada para Generar ID Único
+
+FastAPI usa un **ID único** para cada *path operation*, se usa para el **operation ID** y también para los nombres de cualquier modelo personalizado necesario, para requests o responses.
+
+Puedes personalizar esa función. Toma un `APIRoute` y retorna un string.
+
+Por ejemplo, aquí está usando el primer tag (probablemente tendrás solo un tag) y el nombre de la *path operation* (el nombre de la función).
+
+Puedes entonces pasar esa función personalizada a **FastAPI** como el parámetro `generate_unique_id_function`:
+
+{* ../../docs_src/generate_clients/tutorial003_py39.py hl[6:7,10] *}
+
+### Generar un Cliente TypeScript con Operation IDs Personalizados
+
+Ahora si generas el cliente de nuevo, verás que tiene los nombres de métodos mejorados:
+
+
+
+Como ves, los nombres de métodos ahora tienen el tag y luego el nombre de la función, ahora no incluyen información del path de la URL y la operación HTTP.
+
+### Preprocesa la Especificación OpenAPI para el Generador de Clientes
+
+El código generado aún tiene algo de **información duplicada**.
+
+Ya sabemos que este método está relacionado con los **items** porque esa palabra está en el `ItemsService` (tomado del tag), pero aún tenemos el nombre del tag prefijado en el nombre del método también. 😕
+
+Probablemente aún querremos mantenerlo para OpenAPI en general, ya que eso asegurará que los operation IDs sean **únicos**.
+
+Pero para el cliente generado podríamos **modificar** los operation IDs de OpenAPI justo antes de generar los clientes, solo para hacer esos nombres de métodos más bonitos y **limpios**.
+
+Podríamos descargar el JSON de OpenAPI a un archivo `openapi.json` y luego podríamos **remover ese tag prefijado** con un script como este:
+
+{* ../../docs_src/generate_clients/tutorial004.py *}
+
+//// tab | Node.js
+
+```Javascript
+{!> ../../docs_src/generate_clients/tutorial004.js!}
+```
+
+////
+
+Con eso, los operation IDs serían renombrados de cosas como `items-get_items` a solo `get_items`, de esa manera el generador del cliente puede generar nombres de métodos más simples.
+
+### Generar un Cliente TypeScript con el OpenAPI Preprocesado
+
+Ahora como el resultado final está en un archivo `openapi.json`, modificarías el `package.json` para usar ese archivo local, por ejemplo:
+
+```JSON hl_lines="7"
+{
+ "name": "frontend-app",
+ "version": "1.0.0",
+ "description": "",
+ "main": "index.js",
+ "scripts": {
+ "generate-client": "openapi-ts --input ./openapi.json --output ./src/client --client axios"
+ },
+ "author": "",
+ "license": "",
+ "devDependencies": {
+ "@hey-api/openapi-ts": "^0.27.38",
+ "typescript": "^4.6.2"
+ }
+}
+```
+
+Después de generar el nuevo cliente, ahora tendrías nombres de métodos **limpios**, con todo el **autocompletado**, **errores en línea**, etc:
+
+
+
+## Beneficios
+
+Cuando usas los clientes generados automáticamente obtendrás **autocompletado** para:
+
+* Métodos.
+* Payloads de peticiones en el cuerpo, parámetros de query, etc.
+* Payloads de responses.
+
+También tendrás **errores en línea** para todo.
+
+Y cada vez que actualices el código del backend, y **regeneres** el frontend, tendrás las nuevas *path operations* disponibles como métodos, las antiguas eliminadas, y cualquier otro cambio se reflejará en el código generado. 🤓
+
+Esto también significa que si algo cambió será **reflejado** automáticamente en el código del cliente. Y si haces **build** del cliente, te dará error si tienes algún **desajuste** en los datos utilizados.
+
+Así que, **detectarás muchos errores** muy temprano en el ciclo de desarrollo en lugar de tener que esperar a que los errores se muestren a tus usuarios finales en producción para luego intentar depurar dónde está el problema. ✨
diff --git a/docs/es/docs/advanced/index.md b/docs/es/docs/advanced/index.md
index eb8fe5c1b..0626a1563 100644
--- a/docs/es/docs/advanced/index.md
+++ b/docs/es/docs/advanced/index.md
@@ -1,18 +1,36 @@
-# Guía de Usuario Avanzada
+# Guía avanzada del usuario
-## Características Adicionales
+## Funcionalidades adicionales
-El [Tutorial - Guía de Usuario](../tutorial/index.md){.internal-link target=_blank} principal debe ser suficiente para darte un paseo por todas las características principales de **FastAPI**
+El [Tutorial - Guía del usuario](../tutorial/index.md){.internal-link target=_blank} principal debería ser suficiente para darte un recorrido por todas las funcionalidades principales de **FastAPI**.
-En las secciones siguientes verás otras opciones, configuraciones, y características adicionales.
+En las siguientes secciones verás otras opciones, configuraciones y funcionalidades adicionales.
-!!! tip
- Las próximas secciones **no son necesariamente "avanzadas"**.
+/// tip | Consejo
- Y es posible que para tu caso, la solución se encuentre en una de estas.
+Las siguientes secciones **no son necesariamente "avanzadas"**.
+
+Y es posible que para tu caso de uso, la solución esté en una de ellas.
+
+///
## Lee primero el Tutorial
-Puedes continuar usando la mayoría de las características de **FastAPI** con el conocimiento del [Tutorial - Guía de Usuario](../tutorial/index.md){.internal-link target=_blank} principal.
+Aún podrías usar la mayoría de las funcionalidades en **FastAPI** con el conocimiento del [Tutorial - Guía del usuario](../tutorial/index.md){.internal-link target=_blank} principal.
-En las siguientes secciones se asume que lo has leído y conoces esas ideas principales.
+Y las siguientes secciones asumen que ya lo leíste y que conoces esas ideas principales.
+
+## Cursos externos
+
+Aunque el [Tutorial - Guía del usuario](../tutorial/index.md){.internal-link target=_blank} y esta **Guía avanzada del usuario** están escritos como un tutorial guiado (como un libro) y deberían ser suficientes para que **aprendas FastAPI**, podrías querer complementarlo con cursos adicionales.
+
+O podría ser que simplemente prefieras tomar otros cursos porque se adaptan mejor a tu estilo de aprendizaje.
+
+Algunos proveedores de cursos ✨ [**sponsorean FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨, esto asegura el desarrollo continuo y saludable de FastAPI y su **ecosistema**.
+
+Y muestra su verdadero compromiso con FastAPI y su **comunidad** (tú), ya que no solo quieren brindarte una **buena experiencia de aprendizaje** sino que también quieren asegurarse de que tengas un **buen y saludable framework**, FastAPI. 🙇
+
+Podrías querer probar sus cursos:
+
+* Talk Python Training
+* Desarrollo guiado por pruebas
diff --git a/docs/es/docs/advanced/middleware.md b/docs/es/docs/advanced/middleware.md
new file mode 100644
index 000000000..b8fd86185
--- /dev/null
+++ b/docs/es/docs/advanced/middleware.md
@@ -0,0 +1,96 @@
+# Middleware Avanzado
+
+En el tutorial principal leíste cómo agregar [Middleware Personalizado](../tutorial/middleware.md){.internal-link target=_blank} a tu aplicación.
+
+Y luego también leíste cómo manejar [CORS con el `CORSMiddleware`](../tutorial/cors.md){.internal-link target=_blank}.
+
+En esta sección veremos cómo usar otros middlewares.
+
+## Agregando middlewares ASGI
+
+Como **FastAPI** está basado en Starlette e implementa la especificación ASGI, puedes usar cualquier middleware ASGI.
+
+Un middleware no tiene que estar hecho para FastAPI o Starlette para funcionar, siempre que siga la especificación ASGI.
+
+En general, los middlewares ASGI son clases que esperan recibir una aplicación ASGI como primer argumento.
+
+Entonces, en la documentación de middlewares ASGI de terceros probablemente te indicarán que hagas algo como:
+
+```Python
+from unicorn import UnicornMiddleware
+
+app = SomeASGIApp()
+
+new_app = UnicornMiddleware(app, some_config="rainbow")
+```
+
+Pero FastAPI (en realidad Starlette) proporciona una forma más simple de hacerlo que asegura que los middlewares internos manejen errores del servidor y los controladores de excepciones personalizadas funcionen correctamente.
+
+Para eso, usas `app.add_middleware()` (como en el ejemplo para CORS).
+
+```Python
+from fastapi import FastAPI
+from unicorn import UnicornMiddleware
+
+app = FastAPI()
+
+app.add_middleware(UnicornMiddleware, some_config="rainbow")
+```
+
+`app.add_middleware()` recibe una clase de middleware como primer argumento y cualquier argumento adicional que se le quiera pasar al middleware.
+
+## Middlewares integrados
+
+**FastAPI** incluye varios middlewares para casos de uso común, veremos a continuación cómo usarlos.
+
+/// note | Detalles Técnicos
+
+Para los próximos ejemplos, también podrías usar `from starlette.middleware.something import SomethingMiddleware`.
+
+**FastAPI** proporciona varios middlewares en `fastapi.middleware` solo como una conveniencia para ti, el desarrollador. Pero la mayoría de los middlewares disponibles provienen directamente de Starlette.
+
+///
+
+## `HTTPSRedirectMiddleware`
+
+Impone que todas las requests entrantes deben ser `https` o `wss`.
+
+Cualquier request entrante a `http` o `ws` será redirigida al esquema seguro.
+
+{* ../../docs_src/advanced_middleware/tutorial001.py hl[2,6] *}
+
+## `TrustedHostMiddleware`
+
+Impone que todas las requests entrantes tengan correctamente configurado el header `Host`, para proteger contra ataques de HTTP Host Header.
+
+{* ../../docs_src/advanced_middleware/tutorial002.py hl[2,6:8] *}
+
+Se soportan los siguientes argumentos:
+
+* `allowed_hosts` - Una list de nombres de dominio que deberían ser permitidos como nombres de host. Se soportan dominios comodín como `*.example.com` para hacer coincidir subdominios. Para permitir cualquier nombre de host, usa `allowed_hosts=["*"]` u omite el middleware.
+
+Si una request entrante no se valida correctamente, se enviará un response `400`.
+
+## `GZipMiddleware`
+
+Maneja responses GZip para cualquier request que incluya `"gzip"` en el header `Accept-Encoding`.
+
+El middleware manejará tanto responses estándar como en streaming.
+
+{* ../../docs_src/advanced_middleware/tutorial003.py hl[2,6] *}
+
+Se soportan los siguientes argumentos:
+
+* `minimum_size` - No comprimir con GZip responses que sean más pequeñas que este tamaño mínimo en bytes. Por defecto es `500`.
+* `compresslevel` - Usado durante la compresión GZip. Es un entero que varía de 1 a 9. Por defecto es `9`. Un valor más bajo resulta en una compresión más rápida pero archivos más grandes, mientras que un valor más alto resulta en una compresión más lenta pero archivos más pequeños.
+
+## Otros middlewares
+
+Hay muchos otros middlewares ASGI.
+
+Por ejemplo:
+
+* `ProxyHeadersMiddleware` de Uvicorn
+* MessagePack
+
+Para ver otros middlewares disponibles, revisa la documentación de Middleware de Starlette y la Lista ASGI Awesome.
diff --git a/docs/es/docs/advanced/openapi-callbacks.md b/docs/es/docs/advanced/openapi-callbacks.md
new file mode 100644
index 000000000..60d5cb3cc
--- /dev/null
+++ b/docs/es/docs/advanced/openapi-callbacks.md
@@ -0,0 +1,186 @@
+# OpenAPI Callbacks
+
+Podrías crear una API con una *path operation* que podría desencadenar un request a una *API externa* creada por alguien más (probablemente el mismo desarrollador que estaría *usando* tu API).
+
+El proceso que ocurre cuando tu aplicación API llama a la *API externa* se llama un "callback". Porque el software que escribió el desarrollador externo envía un request a tu API y luego tu API *responde*, enviando un request a una *API externa* (que probablemente fue creada por el mismo desarrollador).
+
+En este caso, podrías querer documentar cómo esa API externa *debería* verse. Qué *path operation* debería tener, qué cuerpo debería esperar, qué response debería devolver, etc.
+
+## Una aplicación con callbacks
+
+Veamos todo esto con un ejemplo.
+
+Imagina que desarrollas una aplicación que permite crear facturas.
+
+Estas facturas tendrán un `id`, `title` (opcional), `customer`, y `total`.
+
+El usuario de tu API (un desarrollador externo) creará una factura en tu API con un request POST.
+
+Luego tu API (imaginemos):
+
+* Enviará la factura a algún cliente del desarrollador externo.
+* Recogerá el dinero.
+* Enviará una notificación de vuelta al usuario de la API (el desarrollador externo).
+ * Esto se hará enviando un request POST (desde *tu API*) a alguna *API externa* proporcionada por ese desarrollador externo (este es el "callback").
+
+## La aplicación normal de **FastAPI**
+
+Primero veamos cómo sería la aplicación API normal antes de agregar el callback.
+
+Tendrá una *path operation* que recibirá un cuerpo `Invoice`, y un parámetro de query `callback_url` que contendrá la URL para el callback.
+
+Esta parte es bastante normal, probablemente ya estés familiarizado con la mayor parte del código:
+
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[9:13,36:53] *}
+
+/// tip | Consejo
+
+El parámetro de query `callback_url` utiliza un tipo Url de Pydantic.
+
+///
+
+Lo único nuevo es el `callbacks=invoices_callback_router.routes` como un argumento para el *decorador de path operation*. Veremos qué es eso a continuación.
+
+## Documentar el callback
+
+El código real del callback dependerá mucho de tu propia aplicación API.
+
+Y probablemente variará mucho de una aplicación a otra.
+
+Podría ser solo una o dos líneas de código, como:
+
+```Python
+callback_url = "https://example.com/api/v1/invoices/events/"
+httpx.post(callback_url, json={"description": "Invoice paid", "paid": True})
+```
+
+Pero posiblemente la parte más importante del callback es asegurarse de que el usuario de tu API (el desarrollador externo) implemente la *API externa* correctamente, de acuerdo con los datos que *tu API* va a enviar en el request body del callback, etc.
+
+Entonces, lo que haremos a continuación es agregar el código para documentar cómo debería verse esa *API externa* para recibir el callback de *tu API*.
+
+Esa documentación aparecerá en la Swagger UI en `/docs` en tu API, y permitirá a los desarrolladores externos saber cómo construir la *API externa*.
+
+Este ejemplo no implementa el callback en sí (eso podría ser solo una línea de código), solo la parte de documentación.
+
+/// tip | Consejo
+
+El callback real es solo un request HTTP.
+
+Cuando implementes el callback tú mismo, podrías usar algo como HTTPX o Requests.
+
+///
+
+## Escribir el código de documentación del callback
+
+Este código no se ejecutará en tu aplicación, solo lo necesitamos para *documentar* cómo debería verse esa *API externa*.
+
+Pero, ya sabes cómo crear fácilmente documentación automática para una API con **FastAPI**.
+
+Así que vamos a usar ese mismo conocimiento para documentar cómo debería verse la *API externa*... creando la(s) *path operation(s)* que la API externa debería implementar (las que tu API va a llamar).
+
+/// tip | Consejo
+
+Cuando escribas el código para documentar un callback, podría ser útil imaginar que eres ese *desarrollador externo*. Y que actualmente estás implementando la *API externa*, no *tu API*.
+
+Adoptar temporalmente este punto de vista (del *desarrollador externo*) puede ayudarte a sentir que es más obvio dónde poner los parámetros, el modelo de Pydantic para el body, para el response, etc. para esa *API externa*.
+
+///
+
+### Crear un `APIRouter` de callback
+
+Primero crea un nuevo `APIRouter` que contendrá uno o más callbacks.
+
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[3,25] *}
+
+### Crear la *path operation* del callback
+
+Para crear la *path operation* del callback utiliza el mismo `APIRouter` que creaste anteriormente.
+
+Debería verse como una *path operation* normal de FastAPI:
+
+* Probablemente debería tener una declaración del body que debería recibir, por ejemplo `body: InvoiceEvent`.
+* Y también podría tener una declaración del response que debería devolver, por ejemplo `response_model=InvoiceEventReceived`.
+
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[16:18,21:22,28:32] *}
+
+Hay 2 diferencias principales respecto a una *path operation* normal:
+
+* No necesita tener ningún código real, porque tu aplicación nunca llamará a este código. Solo se usa para documentar la *API externa*. Así que, la función podría simplemente tener `pass`.
+* El *path* puede contener una expresión OpenAPI 3 (ver más abajo) donde puede usar variables con parámetros y partes del request original enviado a *tu API*.
+
+### La expresión del path del callback
+
+El *path* del callback puede tener una expresión OpenAPI 3 que puede contener partes del request original enviado a *tu API*.
+
+En este caso, es el `str`:
+
+```Python
+"{$callback_url}/invoices/{$request.body.id}"
+```
+
+Entonces, si el usuario de tu API (el desarrollador externo) envía un request a *tu API* a:
+
+```
+https://yourapi.com/invoices/?callback_url=https://www.external.org/events
+```
+
+con un JSON body de:
+
+```JSON
+{
+ "id": "2expen51ve",
+ "customer": "Mr. Richie Rich",
+ "total": "9999"
+}
+```
+
+luego *tu API* procesará la factura, y en algún momento después, enviará un request de callback al `callback_url` (la *API externa*):
+
+```
+https://www.external.org/events/invoices/2expen51ve
+```
+
+con un JSON body que contiene algo como:
+
+```JSON
+{
+ "description": "Payment celebration",
+ "paid": true
+}
+```
+
+y esperaría un response de esa *API externa* con un JSON body como:
+
+```JSON
+{
+ "ok": true
+}
+```
+
+/// tip | Consejo
+
+Observa cómo la URL del callback utilizada contiene la URL recibida como parámetro de query en `callback_url` (`https://www.external.org/events`) y también el `id` de la factura desde dentro del JSON body (`2expen51ve`).
+
+///
+
+### Agregar el router de callback
+
+En este punto tienes las *path operation(s)* del callback necesarias (las que el *desarrollador externo* debería implementar en la *API externa*) en el router de callback que creaste antes.
+
+Ahora usa el parámetro `callbacks` en el *decorador de path operation de tu API* para pasar el atributo `.routes` (que en realidad es solo un `list` de rutas/*path operations*) de ese router de callback:
+
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[35] *}
+
+/// tip | Consejo
+
+Observa que no estás pasando el router en sí (`invoices_callback_router`) a `callback=`, sino el atributo `.routes`, como en `invoices_callback_router.routes`.
+
+///
+
+### Revisa la documentación
+
+Ahora puedes iniciar tu aplicación e ir a http://127.0.0.1:8000/docs.
+
+Verás tu documentación incluyendo una sección de "Callbacks" para tu *path operation* que muestra cómo debería verse la *API externa*:
+
+
diff --git a/docs/es/docs/advanced/openapi-webhooks.md b/docs/es/docs/advanced/openapi-webhooks.md
new file mode 100644
index 000000000..01235b3ab
--- /dev/null
+++ b/docs/es/docs/advanced/openapi-webhooks.md
@@ -0,0 +1,55 @@
+# Webhooks de OpenAPI
+
+Hay casos donde quieres decirle a los **usuarios** de tu API que tu aplicación podría llamar a *su* aplicación (enviando una request) con algunos datos, normalmente para **notificar** de algún tipo de **evento**.
+
+Esto significa que en lugar del proceso normal de tus usuarios enviando requests a tu API, es **tu API** (o tu aplicación) la que podría **enviar requests a su sistema** (a su API, su aplicación).
+
+Esto normalmente se llama un **webhook**.
+
+## Pasos de los webhooks
+
+El proceso normalmente es que **tú defines** en tu código cuál es el mensaje que enviarás, el **body de la request**.
+
+También defines de alguna manera en qué **momentos** tu aplicación enviará esas requests o eventos.
+
+Y **tus usuarios** definen de alguna manera (por ejemplo en un panel web en algún lugar) el **URL** donde tu aplicación debería enviar esas requests.
+
+Toda la **lógica** sobre cómo registrar los URLs para webhooks y el código para realmente enviar esas requests depende de ti. Lo escribes como quieras en **tu propio código**.
+
+## Documentando webhooks con **FastAPI** y OpenAPI
+
+Con **FastAPI**, usando OpenAPI, puedes definir los nombres de estos webhooks, los tipos de operaciones HTTP que tu aplicación puede enviar (por ejemplo, `POST`, `PUT`, etc.) y los **bodies** de las requests que tu aplicación enviaría.
+
+Esto puede hacer mucho más fácil para tus usuarios **implementar sus APIs** para recibir tus requests de **webhook**, incluso podrían ser capaces de autogenerar algo de su propio código de API.
+
+/// info | Información
+
+Los webhooks están disponibles en OpenAPI 3.1.0 y superiores, soportados por FastAPI `0.99.0` y superiores.
+
+///
+
+## Una aplicación con webhooks
+
+Cuando creas una aplicación de **FastAPI**, hay un atributo `webhooks` que puedes usar para definir *webhooks*, de la misma manera que definirías *path operations*, por ejemplo con `@app.webhooks.post()`.
+
+{* ../../docs_src/openapi_webhooks/tutorial001.py hl[9:13,36:53] *}
+
+Los webhooks que defines terminarán en el esquema de **OpenAPI** y en la interfaz automática de **documentación**.
+
+/// info | Información
+
+El objeto `app.webhooks` es en realidad solo un `APIRouter`, el mismo tipo que usarías al estructurar tu aplicación con múltiples archivos.
+
+///
+
+Nota que con los webhooks en realidad no estás declarando un *path* (como `/items/`), el texto que pasas allí es solo un **identificador** del webhook (el nombre del evento), por ejemplo en `@app.webhooks.post("new-subscription")`, el nombre del webhook es `new-subscription`.
+
+Esto es porque se espera que **tus usuarios** definan el actual **URL path** donde quieren recibir la request del webhook de alguna otra manera (por ejemplo, un panel web).
+
+### Revisa la documentación
+
+Ahora puedes iniciar tu app e ir a http://127.0.0.1:8000/docs.
+
+Verás que tu documentación tiene las *path operations* normales y ahora también algunos **webhooks**:
+
+
diff --git a/docs/es/docs/advanced/path-operation-advanced-configuration.md b/docs/es/docs/advanced/path-operation-advanced-configuration.md
index e4edcc52b..2b20819aa 100644
--- a/docs/es/docs/advanced/path-operation-advanced-configuration.md
+++ b/docs/es/docs/advanced/path-operation-advanced-configuration.md
@@ -1,52 +1,204 @@
-# Configuración avanzada de las operaciones de path
+# Configuración Avanzada de Path Operation
-## OpenAPI operationId
+## operationId de OpenAPI
-!!! warning "Advertencia"
- Si no eres una persona "experta" en OpenAPI, probablemente no necesitas leer esto.
+/// warning | Advertencia
-Puedes asignar el `operationId` de OpenAPI para ser usado en tu *operación de path* con el parámetro `operation_id`.
+Si no eres un "experto" en OpenAPI, probablemente no necesites esto.
-En este caso tendrías que asegurarte de que sea único para cada operación.
+///
-```Python hl_lines="6"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial001.py!}
-```
+Puedes establecer el `operationId` de OpenAPI para ser usado en tu *path operation* con el parámetro `operation_id`.
-### Usando el nombre de la *función de la operación de path* en el operationId
+Tienes que asegurarte de que sea único para cada operación.
-Si quieres usar tus nombres de funciones de API como `operationId`s, puedes iterar sobre todos ellos y sobrescribir `operation_id` de cada *operación de path* usando su `APIRoute.name`.
+{* ../../docs_src/path_operation_advanced_configuration/tutorial001.py hl[6] *}
-Deberías hacerlo después de adicionar todas tus *operaciones de path*.
+### Usar el nombre de la *función de path operation* como el operationId
-```Python hl_lines="2 12 13 14 15 16 17 18 19 20 21 24"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial002.py!}
-```
+Si quieres usar los nombres de las funciones de tus APIs como `operationId`s, puedes iterar sobre todas ellas y sobrescribir el `operation_id` de cada *path operation* usando su `APIRoute.name`.
-!!! tip "Consejo"
- Si llamas manualmente a `app.openapi()`, debes actualizar el `operationId`s antes de hacerlo.
+Deberías hacerlo después de agregar todas tus *path operations*.
-!!! warning "Advertencia"
- Si haces esto, debes asegurarte de que cada una de tus *funciones de las operaciones de path* tenga un nombre único.
+{* ../../docs_src/path_operation_advanced_configuration/tutorial002.py hl[2, 12:21, 24] *}
- Incluso si están en diferentes módulos (archivos Python).
+/// tip | Consejo
+
+Si llamas manualmente a `app.openapi()`, deberías actualizar los `operationId`s antes de eso.
+
+///
+
+/// warning | Advertencia
+
+Si haces esto, tienes que asegurarte de que cada una de tus *funciones de path operation* tenga un nombre único.
+
+Incluso si están en diferentes módulos (archivos de Python).
+
+///
## Excluir de OpenAPI
-Para excluir una *operación de path* del esquema OpenAPI generado (y por tanto del la documentación generada automáticamente), usa el parámetro `include_in_schema` y asigna el valor como `False`;
+Para excluir una *path operation* del esquema OpenAPI generado (y por lo tanto, de los sistemas de documentación automática), utiliza el parámetro `include_in_schema` y configúralo en `False`:
-```Python hl_lines="6"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial003.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial003.py hl[6] *}
## Descripción avanzada desde el docstring
-Puedes limitar las líneas usadas desde el docstring de una *operación de path* para OpenAPI.
+Puedes limitar las líneas usadas del docstring de una *función de path operation* para OpenAPI.
-Agregar un `\f` (un carácter de "form feed" escapado) hace que **FastAPI** trunque el output utilizada para OpenAPI en ese punto.
+Añadir un `\f` (un carácter de separación de página escapado) hace que **FastAPI** trunque la salida usada para OpenAPI en este punto.
-No será mostrado en la documentación, pero otras herramientas (como Sphinx) serán capaces de usar el resto.
+No aparecerá en la documentación, pero otras herramientas (como Sphinx) podrán usar el resto.
-```Python hl_lines="19 20 21 22 23 24 25 26 27 28 29"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial004.py!}
+{* ../../docs_src/path_operation_advanced_configuration/tutorial004.py hl[19:29] *}
+
+## Responses Adicionales
+
+Probablemente has visto cómo declarar el `response_model` y el `status_code` para una *path operation*.
+
+Eso define los metadatos sobre el response principal de una *path operation*.
+
+También puedes declarar responses adicionales con sus modelos, códigos de estado, etc.
+
+Hay un capítulo entero en la documentación sobre ello, puedes leerlo en [Responses Adicionales en OpenAPI](additional-responses.md){.internal-link target=_blank}.
+
+## OpenAPI Extra
+
+Cuando declaras una *path operation* en tu aplicación, **FastAPI** genera automáticamente los metadatos relevantes sobre esa *path operation* para incluirlos en el esquema de OpenAPI.
+
+/// note | Nota
+
+En la especificación de OpenAPI se llama el Objeto de Operación.
+
+///
+
+Tiene toda la información sobre la *path operation* y se usa para generar la documentación automática.
+
+Incluye los `tags`, `parameters`, `requestBody`, `responses`, etc.
+
+Este esquema de OpenAPI específico de *path operation* normalmente se genera automáticamente por **FastAPI**, pero también puedes extenderlo.
+
+/// tip | Consejo
+
+Este es un punto de extensión de bajo nivel.
+
+Si solo necesitas declarar responses adicionales, una forma más conveniente de hacerlo es con [Responses Adicionales en OpenAPI](additional-responses.md){.internal-link target=_blank}.
+
+///
+
+Puedes extender el esquema de OpenAPI para una *path operation* usando el parámetro `openapi_extra`.
+
+### Extensiones de OpenAPI
+
+Este `openapi_extra` puede ser útil, por ejemplo, para declarar [Extensiones de OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions):
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial005.py hl[6] *}
+
+Si abres la documentación automática de la API, tu extensión aparecerá en la parte inferior de la *path operation* específica.
+
+
+
+Y si ves el OpenAPI resultante (en `/openapi.json` en tu API), verás tu extensión como parte de la *path operation* específica también:
+
+```JSON hl_lines="22"
+{
+ "openapi": "3.1.0",
+ "info": {
+ "title": "FastAPI",
+ "version": "0.1.0"
+ },
+ "paths": {
+ "/items/": {
+ "get": {
+ "summary": "Read Items",
+ "operationId": "read_items_items__get",
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": {}
+ }
+ }
+ }
+ },
+ "x-aperture-labs-portal": "blue"
+ }
+ }
+ }
+}
```
+
+### Esquema de *path operation* personalizada de OpenAPI
+
+El diccionario en `openapi_extra` se combinará profundamente con el esquema de OpenAPI generado automáticamente para la *path operation*.
+
+Por lo tanto, podrías añadir datos adicionales al esquema generado automáticamente.
+
+Por ejemplo, podrías decidir leer y validar el request con tu propio código, sin usar las funcionalidades automáticas de FastAPI con Pydantic, pero aún podrías querer definir el request en el esquema de OpenAPI.
+
+Podrías hacer eso con `openapi_extra`:
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial006.py hl[19:36, 39:40] *}
+
+En este ejemplo, no declaramos ningún modelo Pydantic. De hecho, el cuerpo del request ni siquiera se parse como JSON, se lee directamente como `bytes`, y la función `magic_data_reader()` sería la encargada de parsearlo de alguna manera.
+
+Sin embargo, podemos declarar el esquema esperado para el cuerpo del request.
+
+### Tipo de contenido personalizado de OpenAPI
+
+Usando este mismo truco, podrías usar un modelo Pydantic para definir el esquema JSON que luego se incluye en la sección personalizada del esquema OpenAPI para la *path operation*.
+
+Y podrías hacer esto incluso si el tipo de datos en el request no es JSON.
+
+Por ejemplo, en esta aplicación no usamos la funcionalidad integrada de FastAPI para extraer el esquema JSON de los modelos Pydantic ni la validación automática para JSON. De hecho, estamos declarando el tipo de contenido del request como YAML, no JSON:
+
+//// tab | Pydantic v2
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[17:22, 24] *}
+
+////
+
+//// tab | Pydantic v1
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py hl[17:22, 24] *}
+
+////
+
+/// info | Información
+
+En la versión 1 de Pydantic el método para obtener el esquema JSON para un modelo se llamaba `Item.schema()`, en la versión 2 de Pydantic, el método se llama `Item.model_json_schema()`.
+
+///
+
+Sin embargo, aunque no estamos usando la funcionalidad integrada por defecto, aún estamos usando un modelo Pydantic para generar manualmente el esquema JSON para los datos que queremos recibir en YAML.
+
+Luego usamos el request directamente, y extraemos el cuerpo como `bytes`. Esto significa que FastAPI ni siquiera intentará parsear la carga útil del request como JSON.
+
+Y luego en nuestro código, parseamos ese contenido YAML directamente, y nuevamente estamos usando el mismo modelo Pydantic para validar el contenido YAML:
+
+//// tab | Pydantic v2
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[26:33] *}
+
+////
+
+//// tab | Pydantic v1
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py hl[26:33] *}
+
+////
+
+/// info | Información
+
+En la versión 1 de Pydantic el método para parsear y validar un objeto era `Item.parse_obj()`, en la versión 2 de Pydantic, el método se llama `Item.model_validate()`.
+
+///
+
+/// tip | Consejo
+
+Aquí reutilizamos el mismo modelo Pydantic.
+
+Pero de la misma manera, podríamos haberlo validado de alguna otra forma.
+
+///
diff --git a/docs/es/docs/advanced/response-change-status-code.md b/docs/es/docs/advanced/response-change-status-code.md
index ecd9fad41..e0889c474 100644
--- a/docs/es/docs/advanced/response-change-status-code.md
+++ b/docs/es/docs/advanced/response-change-status-code.md
@@ -1,33 +1,31 @@
-# Response - Cambiar el Status Code
+# Response - Cambiar Código de Estado
-Probablemente ya has leído con anterioridad que puedes establecer un [Response Status Code](../tutorial/response-status-code.md){.internal-link target=_blank} por defecto.
+Probablemente leíste antes que puedes establecer un [Código de Estado de Response](../tutorial/response-status-code.md){.internal-link target=_blank} por defecto.
-Pero en algunos casos necesitas retornar un status code diferente al predeterminado.
+Pero en algunos casos necesitas devolver un código de estado diferente al predeterminado.
-## Casos de uso
+## Caso de uso
-Por ejemplo, imagina que quieres retornar un HTTP status code de "OK" `200` por defecto.
+Por ejemplo, imagina que quieres devolver un código de estado HTTP de "OK" `200` por defecto.
-Pero si los datos no existen, quieres crearlos y retornar un HTTP status code de "CREATED" `201`.
+Pero si los datos no existieran, quieres crearlos y devolver un código de estado HTTP de "CREATED" `201`.
-Pero aún quieres poder filtrar y convertir los datos que retornas con un `response_model`.
+Pero todavía quieres poder filtrar y convertir los datos que devuelves con un `response_model`.
Para esos casos, puedes usar un parámetro `Response`.
-## Usar un parámetro `Response`
+## Usa un parámetro `Response`
-Puedes declarar un parámetro de tipo `Response` en tu *función de la operación de path* (como puedes hacer para cookies y headers).
+Puedes declarar un parámetro de tipo `Response` en tu *función de path operation* (como puedes hacer para cookies y headers).
-Y luego puedes establecer el `status_code` en ese objeto de respuesta *temporal*.
+Y luego puedes establecer el `status_code` en ese objeto de response *temporal*.
-```Python hl_lines="1 9 12"
-{!../../../docs_src/response_change_status_code/tutorial001.py!}
-```
+{* ../../docs_src/response_change_status_code/tutorial001.py hl[1,9,12] *}
-Y luego puedes retornar cualquier objeto que necesites, como normalmente lo harías (un `dict`, un modelo de base de datos, etc).
+Y luego puedes devolver cualquier objeto que necesites, como lo harías normalmente (un `dict`, un modelo de base de datos, etc.).
-Y si declaraste un `response_model`, aún se usará para filtrar y convertir el objeto que retornaste.
+Y si declaraste un `response_model`, todavía se utilizará para filtrar y convertir el objeto que devolviste.
-**FastAPI** usará esa respuesta *temporal* para extraer el código de estado (también cookies y headers), y los pondrá en la respuesta final que contiene el valor que retornaste, filtrado por cualquier `response_model`.
+**FastAPI** usará ese response *temporal* para extraer el código de estado (también cookies y headers), y los pondrá en el response final que contiene el valor que devolviste, filtrado por cualquier `response_model`.
-También puedes declarar la dependencia del parámetro `Response`, y establecer el código de estado en ellos. Pero ten en cuenta que el último en establecerse será el que gane.
+También puedes declarar el parámetro `Response` en dependencias y establecer el código de estado en ellas. Pero ten en cuenta que el último establecido prevalecerá.
diff --git a/docs/es/docs/advanced/response-cookies.md b/docs/es/docs/advanced/response-cookies.md
new file mode 100644
index 000000000..c4472eaa1
--- /dev/null
+++ b/docs/es/docs/advanced/response-cookies.md
@@ -0,0 +1,51 @@
+# Cookies de Response
+
+## Usar un parámetro `Response`
+
+Puedes declarar un parámetro de tipo `Response` en tu *path operation function*.
+
+Y luego puedes establecer cookies en ese objeto de response *temporal*.
+
+{* ../../docs_src/response_cookies/tutorial002.py hl[1, 8:9] *}
+
+Y entonces puedes devolver cualquier objeto que necesites, como normalmente lo harías (un `dict`, un modelo de base de datos, etc).
+
+Y si declaraste un `response_model`, todavía se utilizará para filtrar y convertir el objeto que devolviste.
+
+**FastAPI** utilizará ese response *temporal* para extraer las cookies (también los headers y el código de estado), y las pondrá en el response final que contiene el valor que devolviste, filtrado por cualquier `response_model`.
+
+También puedes declarar el parámetro `Response` en las dependencias, y establecer cookies (y headers) en ellas.
+
+## Devolver una `Response` directamente
+
+También puedes crear cookies al devolver una `Response` directamente en tu código.
+
+Para hacer eso, puedes crear un response como se describe en [Devolver un Response Directamente](response-directly.md){.internal-link target=_blank}.
+
+Luego establece Cookies en ella, y luego devuélvela:
+
+{* ../../docs_src/response_cookies/tutorial001.py hl[10:12] *}
+
+/// tip | Consejo
+
+Ten en cuenta que si devuelves un response directamente en lugar de usar el parámetro `Response`, FastAPI lo devolverá directamente.
+
+Así que tendrás que asegurarte de que tus datos son del tipo correcto. Por ejemplo, que sea compatible con JSON, si estás devolviendo un `JSONResponse`.
+
+Y también que no estés enviando ningún dato que debería haber sido filtrado por un `response_model`.
+
+///
+
+### Más información
+
+/// note | Detalles Técnicos
+
+También podrías usar `from starlette.responses import Response` o `from starlette.responses import JSONResponse`.
+
+**FastAPI** proporciona los mismos `starlette.responses` como `fastapi.responses` solo como una conveniencia para ti, el desarrollador. Pero la mayoría de los responses disponibles vienen directamente de Starlette.
+
+Y como el `Response` se puede usar frecuentemente para establecer headers y cookies, **FastAPI** también lo proporciona en `fastapi.Response`.
+
+///
+
+Para ver todos los parámetros y opciones disponibles, revisa la documentación en Starlette.
diff --git a/docs/es/docs/advanced/response-directly.md b/docs/es/docs/advanced/response-directly.md
index dee44ac08..8594011d6 100644
--- a/docs/es/docs/advanced/response-directly.md
+++ b/docs/es/docs/advanced/response-directly.md
@@ -1,63 +1,65 @@
-# Devolver una respuesta directamente
+# Devolver una Response Directamente
-Cuando creas una *operación de path* normalmente puedes devolver cualquier dato: un `dict`, una `list`, un modelo Pydantic, un modelo de base de datos, etc.
+Cuando creas una *path operation* en **FastAPI**, normalmente puedes devolver cualquier dato desde ella: un `dict`, una `list`, un modelo de Pydantic, un modelo de base de datos, etc.
-Por defecto, **FastAPI** convertiría automáticamente ese valor devuelto a JSON usando el `jsonable_encoder` explicado en [Codificador Compatible JSON](../tutorial/encoder.md){.internal-link target=_blank}.
+Por defecto, **FastAPI** convertiría automáticamente ese valor de retorno a JSON usando el `jsonable_encoder` explicado en [JSON Compatible Encoder](../tutorial/encoder.md){.internal-link target=_blank}.
-Luego, tras bastidores, pondría esos datos compatibles con JSON (por ejemplo, un `dict`) dentro de una `JSONResponse` que se usaría para enviar la respuesta al cliente.
+Luego, detrás de escena, pondría esos datos compatibles con JSON (por ejemplo, un `dict`) dentro de un `JSONResponse` que se usaría para enviar el response al cliente.
-Pero puedes devolver una `JSONResponse` directamente de tu *operación de path*.
+Pero puedes devolver un `JSONResponse` directamente desde tus *path operations*.
-Esto puede ser útil, por ejemplo, para devolver cookies o headers personalizados.
+Esto podría ser útil, por ejemplo, para devolver headers o cookies personalizados.
## Devolver una `Response`
-De hecho, puedes devolver cualquier `Response` o cualquier subclase de la misma.
+De hecho, puedes devolver cualquier `Response` o cualquier subclase de ella.
-!!! tip "Consejo"
- `JSONResponse` en sí misma es una subclase de `Response`.
+/// tip | Consejo
+
+`JSONResponse` en sí misma es una subclase de `Response`.
+
+///
Y cuando devuelves una `Response`, **FastAPI** la pasará directamente.
-No hará ninguna conversión de datos con modelos Pydantic, no convertirá el contenido a ningún tipo, etc.
+No hará ninguna conversión de datos con los modelos de Pydantic, no convertirá los contenidos a ningún tipo, etc.
-Esto te da mucha flexibilidad. Puedes devolver cualquier tipo de dato, sobrescribir cualquier declaración de datos o validación, etc.
+Esto te da mucha flexibilidad. Puedes devolver cualquier tipo de datos, sobrescribir cualquier declaración o validación de datos, etc.
-## Usando el `jsonable_encoder` en una `Response`
+## Usar el `jsonable_encoder` en una `Response`
-Como **FastAPI** no realiza ningún cambio en la `Response` que devuelves, debes asegurarte de que el contenido está listo.
+Como **FastAPI** no realiza cambios en una `Response` que devuelves, tienes que asegurarte de que sus contenidos estén listos para ello.
-Por ejemplo, no puedes poner un modelo Pydantic en una `JSONResponse` sin primero convertirlo a un `dict` con todos los tipos de datos (como `datetime`, `UUID`, etc) convertidos a tipos compatibles con JSON.
+Por ejemplo, no puedes poner un modelo de Pydantic en un `JSONResponse` sin primero convertirlo a un `dict` con todos los tipos de datos (como `datetime`, `UUID`, etc.) convertidos a tipos compatibles con JSON.
-Para esos casos, puedes usar el `jsonable_encoder` para convertir tus datos antes de pasarlos a la respuesta:
+Para esos casos, puedes usar el `jsonable_encoder` para convertir tus datos antes de pasarlos a un response:
-```Python hl_lines="4 6 20 21"
-{!../../../docs_src/response_directly/tutorial001.py!}
-```
+{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *}
-!!! note "Detalles Técnicos"
- También puedes usar `from starlette.responses import JSONResponse`.
+/// note | Nota
- **FastAPI** provee `starlette.responses` como `fastapi.responses`, simplemente como una conveniencia para ti, el desarrollador. Pero la mayoría de las respuestas disponibles vienen directamente de Starlette.
+También podrías usar `from starlette.responses import JSONResponse`.
-## Devolviendo una `Response` personalizada
+**FastAPI** proporciona los mismos `starlette.responses` como `fastapi.responses` solo como una conveniencia para ti, el desarrollador. Pero la mayoría de los responses disponibles vienen directamente de Starlette.
-El ejemplo anterior muestra las partes que necesitas, pero no es muy útil todavía, dado que podrías simplemente devolver el `item` directamente, y **FastAPI** lo pondría en una `JSONResponse` por ti, convirtiéndolo en un `dict`, etc. Todo esto por defecto.
+///
-Ahora, veamos cómo puedes usarlo para devolver una respuesta personalizada.
+## Devolver una `Response` personalizada
-Digamos que quieres devolver una respuesta XML.
+El ejemplo anterior muestra todas las partes que necesitas, pero aún no es muy útil, ya que podrías haber devuelto el `item` directamente, y **FastAPI** lo colocaría en un `JSONResponse` por ti, convirtiéndolo a un `dict`, etc. Todo eso por defecto.
-Podrías poner tu contenido XML en un string, ponerlo en una `Response` y devolverlo:
+Ahora, veamos cómo podrías usar eso para devolver un response personalizado.
-```Python hl_lines="1 18"
-{!../../../docs_src/response_directly/tutorial002.py!}
-```
+Digamos que quieres devolver un response en XML.
+
+Podrías poner tu contenido XML en un string, poner eso en un `Response`, y devolverlo:
+
+{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
## Notas
-Cuando devuelves una `Response` directamente, los datos no son validados, convertidos (serializados), ni documentados automáticamente.
+Cuando devuelves una `Response` directamente, sus datos no son validados, convertidos (serializados), ni documentados automáticamente.
-Pero todavía es posible documentarlo como es descrito en [Respuestas adicionales en OpenAPI](additional-responses.md){.internal-link target=_blank}.
+Pero aún puedes documentarlo como se describe en [Additional Responses in OpenAPI](additional-responses.md){.internal-link target=_blank}.
-Puedes ver en secciones posteriores como usar/declarar esas `Response`s personalizadas aún teniendo conversión automática de datos, documentación, etc.
+Puedes ver en secciones posteriores cómo usar/declarar estas `Response`s personalizadas mientras todavía tienes conversión automática de datos, documentación, etc.
diff --git a/docs/es/docs/advanced/response-headers.md b/docs/es/docs/advanced/response-headers.md
index aec88a584..49eaa53c1 100644
--- a/docs/es/docs/advanced/response-headers.md
+++ b/docs/es/docs/advanced/response-headers.md
@@ -1,44 +1,41 @@
-# Headers de Respuesta
+# Response Headers
-## Usar un parámetro `Response`
+## Usa un parámetro `Response`
-Puedes declarar un parámetro de tipo `Response` en tu *función de operación de path* (de manera similar como se hace con las cookies).
+Puedes declarar un parámetro de tipo `Response` en tu *función de path operation* (como puedes hacer para cookies).
-Y entonces, podrás configurar las cookies en ese objeto de response *temporal*.
+Y luego puedes establecer headers en ese objeto de response *temporal*.
-```Python hl_lines="1 7-8"
-{!../../../docs_src/response_headers/tutorial002.py!}
-```
+{* ../../docs_src/response_headers/tutorial002.py hl[1, 7:8] *}
-Posteriormente, puedes devolver cualquier objeto que necesites, como normalmente harías (un `dict`, un modelo de base de datos, etc).
+Y luego puedes devolver cualquier objeto que necesites, como harías normalmente (un `dict`, un modelo de base de datos, etc).
-Si declaraste un `response_model`, este se continuará usando para filtrar y convertir el objeto que devolviste.
+Y si declaraste un `response_model`, aún se usará para filtrar y convertir el objeto que devolviste.
-**FastAPI** usará ese response *temporal* para extraer los headers (al igual que las cookies y el status code), además las pondrá en el response final que contendrá el valor retornado y filtrado por algún `response_model`.
+**FastAPI** usará ese response *temporal* para extraer los headers (también cookies y el código de estado), y los pondrá en el response final que contiene el valor que devolviste, filtrado por cualquier `response_model`.
-También puedes declarar el parámetro `Response` en dependencias, así como configurar los headers (y las cookies) en ellas.
+También puedes declarar el parámetro `Response` en dependencias y establecer headers (y cookies) en ellas.
+## Retorna una `Response` directamente
-## Retornar una `Response` directamente
+También puedes agregar headers cuando devuelves un `Response` directamente.
-Adicionalmente, puedes añadir headers cuando se retorne una `Response` directamente.
+Crea un response como se describe en [Retorna un Response Directamente](response-directly.md){.internal-link target=_blank} y pasa los headers como un parámetro adicional:
-Crea un response tal como se describe en [Retornar una respuesta directamente](response-directly.md){.internal-link target=_blank} y pasa los headers como un parámetro adicional:
+{* ../../docs_src/response_headers/tutorial001.py hl[10:12] *}
-```Python hl_lines="10-12"
-{!../../../docs_src/response_headers/tutorial001.py!}
-```
+/// note | Detalles Técnicos
-!!! note "Detalles Técnicos"
- También podrías utilizar `from starlette.responses import Response` o `from starlette.responses import JSONResponse`.
+También podrías usar `from starlette.responses import Response` o `from starlette.responses import JSONResponse`.
- **FastAPI** proporciona las mismas `starlette.responses` en `fastapi.responses` sólo que de una manera más conveniente para ti, el desarrollador. En otras palabras, muchas de las responses disponibles provienen directamente de Starlette.
+**FastAPI** proporciona las mismas `starlette.responses` como `fastapi.responses` solo por conveniencia para ti, el desarrollador. Pero la mayoría de los responses disponibles provienen directamente de Starlette.
+Y como el `Response` se puede usar frecuentemente para establecer headers y cookies, **FastAPI** también lo proporciona en `fastapi.Response`.
- Y como la `Response` puede ser usada frecuentemente para configurar headers y cookies, **FastAPI** también la provee en `fastapi.Response`.
+///
## Headers Personalizados
-Ten en cuenta que se pueden añadir headers propietarios personalizados usando el prefijo 'X-'.
+Ten en cuenta que los headers propietarios personalizados se pueden agregar usando el prefijo 'X-'.
-Si tienes headers personalizados y deseas que un cliente pueda verlos en el navegador, es necesario que los añadas a tus configuraciones de CORS (puedes leer más en [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md){.internal-link target=_blank}), usando el parámetro `expose_headers` documentado en Starlette's CORS docs.
+Pero si tienes headers personalizados que quieres que un cliente en un navegador pueda ver, necesitas agregarlos a tus configuraciones de CORS (leer más en [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md){.internal-link target=_blank}), usando el parámetro `expose_headers` documentado en la documentación CORS de Starlette.
diff --git a/docs/es/docs/advanced/security/http-basic-auth.md b/docs/es/docs/advanced/security/http-basic-auth.md
new file mode 100644
index 000000000..629e6c50a
--- /dev/null
+++ b/docs/es/docs/advanced/security/http-basic-auth.md
@@ -0,0 +1,107 @@
+# HTTP Basic Auth
+
+Para los casos más simples, puedes usar HTTP Basic Auth.
+
+En HTTP Basic Auth, la aplicación espera un header que contiene un nombre de usuario y una contraseña.
+
+Si no lo recibe, devuelve un error HTTP 401 "Unauthorized".
+
+Y devuelve un header `WWW-Authenticate` con un valor de `Basic`, y un parámetro `realm` opcional.
+
+Eso le dice al navegador que muestre el prompt integrado para un nombre de usuario y contraseña.
+
+Luego, cuando escribes ese nombre de usuario y contraseña, el navegador los envía automáticamente en el header.
+
+## Simple HTTP Basic Auth
+
+* Importa `HTTPBasic` y `HTTPBasicCredentials`.
+* Crea un "esquema de `security`" usando `HTTPBasic`.
+* Usa ese `security` con una dependencia en tu *path operation*.
+* Devuelve un objeto de tipo `HTTPBasicCredentials`:
+ * Contiene el `username` y `password` enviados.
+
+{* ../../docs_src/security/tutorial006_an_py39.py hl[4,8,12] *}
+
+Cuando intentas abrir la URL por primera vez (o haces clic en el botón "Execute" en la documentación) el navegador te pedirá tu nombre de usuario y contraseña:
+
+
+
+## Revisa el nombre de usuario
+
+Aquí hay un ejemplo más completo.
+
+Usa una dependencia para comprobar si el nombre de usuario y la contraseña son correctos.
+
+Para esto, usa el módulo estándar de Python `secrets` para verificar el nombre de usuario y la contraseña.
+
+`secrets.compare_digest()` necesita tomar `bytes` o un `str` que solo contenga caracteres ASCII (los carácteres en inglés), esto significa que no funcionaría con caracteres como `á`, como en `Sebastián`.
+
+Para manejar eso, primero convertimos el `username` y `password` a `bytes` codificándolos con UTF-8.
+
+Luego podemos usar `secrets.compare_digest()` para asegurar que `credentials.username` es `"stanleyjobson"`, y que `credentials.password` es `"swordfish"`.
+
+{* ../../docs_src/security/tutorial007_an_py39.py hl[1,12:24] *}
+
+Esto sería similar a:
+
+```Python
+if not (credentials.username == "stanleyjobson") or not (credentials.password == "swordfish"):
+ # Return some error
+ ...
+```
+
+Pero al usar `secrets.compare_digest()` será seguro contra un tipo de ataques llamados "timing attacks".
+
+### Timing Attacks
+
+¿Pero qué es un "timing attack"?
+
+Imaginemos que algunos atacantes están tratando de adivinar el nombre de usuario y la contraseña.
+
+Y envían un request con un nombre de usuario `johndoe` y una contraseña `love123`.
+
+Entonces el código de Python en tu aplicación equivaldría a algo como:
+
+```Python
+if "johndoe" == "stanleyjobson" and "love123" == "swordfish":
+ ...
+```
+
+Pero justo en el momento en que Python compara la primera `j` en `johndoe` con la primera `s` en `stanleyjobson`, devolverá `False`, porque ya sabe que esas dos strings no son iguales, pensando que "no hay necesidad de gastar más computación comparando el resto de las letras". Y tu aplicación dirá "Nombre de usuario o contraseña incorrectos".
+
+Pero luego los atacantes prueban con el nombre de usuario `stanleyjobsox` y contraseña `love123`.
+
+Y el código de tu aplicación hace algo así como:
+
+```Python
+if "stanleyjobsox" == "stanleyjobson" and "love123" == "swordfish":
+ ...
+```
+
+Python tendrá que comparar todo `stanleyjobso` en ambos `stanleyjobsox` y `stanleyjobson` antes de darse cuenta de que ambas strings no son las mismas. Así que tomará algunos microsegundos extra para responder "Nombre de usuario o contraseña incorrectos".
+
+#### El tiempo de respuesta ayuda a los atacantes
+
+En ese punto, al notar que el servidor tardó algunos microsegundos más en enviar el response "Nombre de usuario o contraseña incorrectos", los atacantes sabrán que acertaron en _algo_, algunas de las letras iniciales eran correctas.
+
+Y luego pueden intentar de nuevo sabiendo que probablemente es algo más similar a `stanleyjobsox` que a `johndoe`.
+
+#### Un ataque "profesional"
+
+Por supuesto, los atacantes no intentarían todo esto a mano, escribirían un programa para hacerlo, posiblemente con miles o millones de pruebas por segundo. Y obtendrían solo una letra correcta adicional a la vez.
+
+Pero haciendo eso, en algunos minutos u horas, los atacantes habrían adivinado el nombre de usuario y la contraseña correctos, con la "ayuda" de nuestra aplicación, solo usando el tiempo tomado para responder.
+
+#### Arréglalo con `secrets.compare_digest()`
+
+Pero en nuestro código estamos usando realmente `secrets.compare_digest()`.
+
+En resumen, tomará el mismo tiempo comparar `stanleyjobsox` con `stanleyjobson` que comparar `johndoe` con `stanleyjobson`. Y lo mismo para la contraseña.
+
+De esa manera, usando `secrets.compare_digest()` en el código de tu aplicación, será seguro contra todo este rango de ataques de seguridad.
+
+### Devuelve el error
+
+Después de detectar que las credenciales son incorrectas, regresa un `HTTPException` con un código de estado 401 (el mismo que se devuelve cuando no se proporcionan credenciales) y agrega el header `WWW-Authenticate` para que el navegador muestre el prompt de inicio de sesión nuevamente:
+
+{* ../../docs_src/security/tutorial007_an_py39.py hl[26:30] *}
diff --git a/docs/es/docs/advanced/security/index.md b/docs/es/docs/advanced/security/index.md
index 139e8f9bd..e4ccb5978 100644
--- a/docs/es/docs/advanced/security/index.md
+++ b/docs/es/docs/advanced/security/index.md
@@ -1,16 +1,19 @@
# Seguridad Avanzada
-## Características Adicionales
+## Funcionalidades Adicionales
-Hay algunas características adicionales para manejar la seguridad además de las que se tratan en el [Tutorial - Guía de Usuario: Seguridad](../../tutorial/security/index.md){.internal-link target=_blank}.
+Hay algunas funcionalidades extra para manejar la seguridad aparte de las cubiertas en el [Tutorial - Guía del Usuario: Seguridad](../../tutorial/security/index.md){.internal-link target=_blank}.
-!!! tip
- Las siguientes secciones **no necesariamente son "avanzadas"**.
+/// tip | Consejo
- Y es posible que para tu caso de uso, la solución esté en alguna de ellas.
+Las siguientes secciones **no son necesariamente "avanzadas"**.
-## Leer primero el Tutorial
+Y es posible que para tu caso de uso, la solución esté en una de ellas.
-En las siguientes secciones asumimos que ya has leído el principal [Tutorial - Guía de Usuario: Seguridad](../../tutorial/security/index.md){.internal-link target=_blank}.
+///
-Están basadas en los mismos conceptos, pero permiten algunas funcionalidades adicionales.
+## Lee primero el Tutorial
+
+Las siguientes secciones asumen que ya leíste el [Tutorial - Guía del Usuario: Seguridad](../../tutorial/security/index.md){.internal-link target=_blank}.
+
+Todas están basadas en los mismos conceptos, pero permiten algunas funcionalidades adicionales.
diff --git a/docs/es/docs/advanced/security/oauth2-scopes.md b/docs/es/docs/advanced/security/oauth2-scopes.md
new file mode 100644
index 000000000..17f7b19ca
--- /dev/null
+++ b/docs/es/docs/advanced/security/oauth2-scopes.md
@@ -0,0 +1,274 @@
+# Scopes de OAuth2
+
+Puedes usar scopes de OAuth2 directamente con **FastAPI**, están integrados para funcionar de manera fluida.
+
+Esto te permitiría tener un sistema de permisos más detallado, siguiendo el estándar de OAuth2, integrado en tu aplicación OpenAPI (y la documentación de la API).
+
+OAuth2 con scopes es el mecanismo usado por muchos grandes proveedores de autenticación, como Facebook, Google, GitHub, Microsoft, Twitter, etc. Lo usan para proporcionar permisos específicos a usuarios y aplicaciones.
+
+Cada vez que te "logueas con" Facebook, Google, GitHub, Microsoft, Twitter, esa aplicación está usando OAuth2 con scopes.
+
+En esta sección verás cómo manejar autenticación y autorización con el mismo OAuth2 con scopes en tu aplicación de **FastAPI**.
+
+/// warning | Advertencia
+
+Esta es una sección más o menos avanzada. Si estás comenzando, puedes saltarla.
+
+No necesariamente necesitas scopes de OAuth2, y puedes manejar autenticación y autorización como quieras.
+
+Pero OAuth2 con scopes se puede integrar muy bien en tu API (con OpenAPI) y en la documentación de tu API.
+
+No obstante, tú aún impones esos scopes, o cualquier otro requisito de seguridad/autorización, como necesites, en tu código.
+
+En muchos casos, OAuth2 con scopes puede ser un exceso.
+
+Pero si sabes que lo necesitas, o tienes curiosidad, sigue leyendo.
+
+///
+
+## Scopes de OAuth2 y OpenAPI
+
+La especificación de OAuth2 define "scopes" como una lista de strings separados por espacios.
+
+El contenido de cada uno de estos strings puede tener cualquier formato, pero no debe contener espacios.
+
+Estos scopes representan "permisos".
+
+En OpenAPI (por ejemplo, en la documentación de la API), puedes definir "esquemas de seguridad".
+
+Cuando uno de estos esquemas de seguridad usa OAuth2, también puedes declarar y usar scopes.
+
+Cada "scope" es solo un string (sin espacios).
+
+Normalmente se utilizan para declarar permisos de seguridad específicos, por ejemplo:
+
+* `users:read` o `users:write` son ejemplos comunes.
+* `instagram_basic` es usado por Facebook / Instagram.
+* `https://www.googleapis.com/auth/drive` es usado por Google.
+
+/// info | Información
+
+En OAuth2 un "scope" es solo un string que declara un permiso específico requerido.
+
+No importa si tiene otros caracteres como `:` o si es una URL.
+
+Esos detalles son específicos de la implementación.
+
+Para OAuth2 son solo strings.
+
+///
+
+## Vista global
+
+Primero, echemos un vistazo rápido a las partes que cambian desde los ejemplos en el **Tutorial - User Guide** principal para [OAuth2 con Password (y hashing), Bearer con tokens JWT](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank}. Ahora usando scopes de OAuth2:
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,65,106,108:116,122:125,129:135,140,156] *}
+
+Ahora revisemos esos cambios paso a paso.
+
+## Esquema de seguridad OAuth2
+
+El primer cambio es que ahora estamos declarando el esquema de seguridad OAuth2 con dos scopes disponibles, `me` y `items`.
+
+El parámetro `scopes` recibe un `dict` con cada scope como clave y la descripción como valor:
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[63:66] *}
+
+Como ahora estamos declarando esos scopes, aparecerán en la documentación de la API cuando inicies sesión/autorices.
+
+Y podrás seleccionar cuáles scopes quieres dar de acceso: `me` y `items`.
+
+Este es el mismo mecanismo utilizado cuando das permisos al iniciar sesión con Facebook, Google, GitHub, etc:
+
+
+
+## Token JWT con scopes
+
+Ahora, modifica la *path operation* del token para devolver los scopes solicitados.
+
+Todavía estamos usando el mismo `OAuth2PasswordRequestForm`. Incluye una propiedad `scopes` con una `list` de `str`, con cada scope que recibió en el request.
+
+Y devolvemos los scopes como parte del token JWT.
+
+/// danger | Peligro
+
+Para simplificar, aquí solo estamos añadiendo los scopes recibidos directamente al token.
+
+Pero en tu aplicación, por seguridad, deberías asegurarte de añadir solo los scopes que el usuario realmente puede tener, o los que has predefinido.
+
+///
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[156] *}
+
+## Declarar scopes en *path operations* y dependencias
+
+Ahora declaramos que la *path operation* para `/users/me/items/` requiere el scope `items`.
+
+Para esto, importamos y usamos `Security` de `fastapi`.
+
+Puedes usar `Security` para declarar dependencias (igual que `Depends`), pero `Security` también recibe un parámetro `scopes` con una lista de scopes (strings).
+
+En este caso, pasamos una función de dependencia `get_current_active_user` a `Security` (de la misma manera que haríamos con `Depends`).
+
+Pero también pasamos una `list` de scopes, en este caso con solo un scope: `items` (podría tener más).
+
+Y la función de dependencia `get_current_active_user` también puede declarar sub-dependencias, no solo con `Depends` sino también con `Security`. Declarando su propia función de sub-dependencia (`get_current_user`), y más requisitos de scope.
+
+En este caso, requiere el scope `me` (podría requerir más de un scope).
+
+/// note | Nota
+
+No necesariamente necesitas añadir diferentes scopes en diferentes lugares.
+
+Lo estamos haciendo aquí para demostrar cómo **FastAPI** maneja scopes declarados en diferentes niveles.
+
+///
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[5,140,171] *}
+
+/// info | Información Técnica
+
+`Security` es en realidad una subclase de `Depends`, y tiene solo un parámetro extra que veremos más adelante.
+
+Pero al usar `Security` en lugar de `Depends`, **FastAPI** sabrá que puede declarar scopes de seguridad, usarlos internamente y documentar la API con OpenAPI.
+
+Pero cuando importas `Query`, `Path`, `Depends`, `Security` y otros de `fastapi`, en realidad son funciones que devuelven clases especiales.
+
+///
+
+## Usar `SecurityScopes`
+
+Ahora actualiza la dependencia `get_current_user`.
+
+Esta es la que usan las dependencias anteriores.
+
+Aquí es donde estamos usando el mismo esquema de OAuth2 que creamos antes, declarándolo como una dependencia: `oauth2_scheme`.
+
+Porque esta función de dependencia no tiene ningún requisito de scope en sí, podemos usar `Depends` con `oauth2_scheme`, no tenemos que usar `Security` cuando no necesitamos especificar scopes de seguridad.
+
+También declaramos un parámetro especial de tipo `SecurityScopes`, importado de `fastapi.security`.
+
+Esta clase `SecurityScopes` es similar a `Request` (`Request` se usó para obtener el objeto request directamente).
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[9,106] *}
+
+## Usar los `scopes`
+
+El parámetro `security_scopes` será del tipo `SecurityScopes`.
+
+Tendrá una propiedad `scopes` con una lista que contiene todos los scopes requeridos por sí mismo y por todas las dependencias que lo usan como sub-dependencia. Eso significa, todos los "dependientes"... esto podría sonar confuso, se explica de nuevo más abajo.
+
+El objeto `security_scopes` (de la clase `SecurityScopes`) también proporciona un atributo `scope_str` con un único string, que contiene esos scopes separados por espacios (lo vamos a usar).
+
+Creamos una `HTTPException` que podemos reutilizar (`raise`) más tarde en varios puntos.
+
+En esta excepción, incluimos los scopes requeridos (si los hay) como un string separado por espacios (usando `scope_str`). Ponemos ese string que contiene los scopes en el header `WWW-Authenticate` (esto es parte de la especificación).
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[106,108:116] *}
+
+## Verificar el `username` y la forma de los datos
+
+Verificamos que obtenemos un `username`, y extraemos los scopes.
+
+Y luego validamos esos datos con el modelo de Pydantic (capturando la excepción `ValidationError`), y si obtenemos un error leyendo el token JWT o validando los datos con Pydantic, lanzamos la `HTTPException` que creamos antes.
+
+Para eso, actualizamos el modelo de Pydantic `TokenData` con una nueva propiedad `scopes`.
+
+Al validar los datos con Pydantic podemos asegurarnos de que tenemos, por ejemplo, exactamente una `list` de `str` con los scopes y un `str` con el `username`.
+
+En lugar de, por ejemplo, un `dict`, o algo más, ya que podría romper la aplicación en algún punto posterior, haciéndolo un riesgo de seguridad.
+
+También verificamos que tenemos un usuario con ese username, y si no, lanzamos esa misma excepción que creamos antes.
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[47,117:128] *}
+
+## Verificar los `scopes`
+
+Ahora verificamos que todos los scopes requeridos, por esta dependencia y todos los dependientes (incluyendo *path operations*), estén incluidos en los scopes proporcionados en el token recibido, de lo contrario, lanzamos una `HTTPException`.
+
+Para esto, usamos `security_scopes.scopes`, que contiene una `list` con todos estos scopes como `str`.
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[129:135] *}
+
+## Árbol de dependencias y scopes
+
+Revisemos de nuevo este árbol de dependencias y los scopes.
+
+Como la dependencia `get_current_active_user` tiene como sub-dependencia a `get_current_user`, el scope `"me"` declarado en `get_current_active_user` se incluirá en la lista de scopes requeridos en el `security_scopes.scopes` pasado a `get_current_user`.
+
+La *path operation* en sí también declara un scope, `"items"`, por lo que esto también estará en la lista de `security_scopes.scopes` pasado a `get_current_user`.
+
+Así es como se ve la jerarquía de dependencias y scopes:
+
+* La *path operation* `read_own_items` tiene:
+ * Scopes requeridos `["items"]` con la dependencia:
+ * `get_current_active_user`:
+ * La función de dependencia `get_current_active_user` tiene:
+ * Scopes requeridos `["me"]` con la dependencia:
+ * `get_current_user`:
+ * La función de dependencia `get_current_user` tiene:
+ * No requiere scopes por sí misma.
+ * Una dependencia usando `oauth2_scheme`.
+ * Un parámetro `security_scopes` de tipo `SecurityScopes`:
+ * Este parámetro `security_scopes` tiene una propiedad `scopes` con una `list` que contiene todos estos scopes declarados arriba, por lo que:
+ * `security_scopes.scopes` contendrá `["me", "items"]` para la *path operation* `read_own_items`.
+ * `security_scopes.scopes` contendrá `["me"]` para la *path operation* `read_users_me`, porque está declarado en la dependencia `get_current_active_user`.
+ * `security_scopes.scopes` contendrá `[]` (nada) para la *path operation* `read_system_status`, porque no declaró ningún `Security` con `scopes`, y su dependencia, `get_current_user`, tampoco declara ningún `scopes`.
+
+/// tip | Consejo
+
+Lo importante y "mágico" aquí es que `get_current_user` tendrá una lista diferente de `scopes` para verificar para cada *path operation*.
+
+Todo depende de los `scopes` declarados en cada *path operation* y cada dependencia en el árbol de dependencias para esa *path operation* específica.
+
+///
+
+## Más detalles sobre `SecurityScopes`
+
+Puedes usar `SecurityScopes` en cualquier punto, y en múltiples lugares, no tiene que ser en la dependencia "raíz".
+
+Siempre tendrá los scopes de seguridad declarados en las dependencias `Security` actuales y todos los dependientes para **esa específica** *path operation* y **ese específico** árbol de dependencias.
+
+Debido a que `SecurityScopes` tendrá todos los scopes declarados por dependientes, puedes usarlo para verificar que un token tiene los scopes requeridos en una función de dependencia central, y luego declarar diferentes requisitos de scope en diferentes *path operations*.
+
+Serán verificados independientemente para cada *path operation*.
+
+## Revisa
+
+Si abres la documentación de la API, puedes autenticarte y especificar qué scopes deseas autorizar.
+
+
+
+Si no seleccionas ningún scope, estarás "autenticado", pero cuando intentes acceder a `/users/me/` o `/users/me/items/` obtendrás un error diciendo que no tienes suficientes permisos. Aún podrás acceder a `/status/`.
+
+Y si seleccionas el scope `me` pero no el scope `items`, podrás acceder a `/users/me/` pero no a `/users/me/items/`.
+
+Eso es lo que pasaría a una aplicación de terceros que intentara acceder a una de estas *path operations* con un token proporcionado por un usuario, dependiendo de cuántos permisos el usuario otorgó a la aplicación.
+
+## Acerca de las integraciones de terceros
+
+En este ejemplo estamos usando el flujo de OAuth2 "password".
+
+Esto es apropiado cuando estamos iniciando sesión en nuestra propia aplicación, probablemente con nuestro propio frontend.
+
+Porque podemos confiar en ella para recibir el `username` y `password`, ya que la controlamos.
+
+Pero si estás construyendo una aplicación OAuth2 a la que otros se conectarían (es decir, si estás construyendo un proveedor de autenticación equivalente a Facebook, Google, GitHub, etc.) deberías usar uno de los otros flujos.
+
+El más común es el flujo implícito.
+
+El más seguro es el flujo de código, pero es más complejo de implementar ya que requiere más pasos. Como es más complejo, muchos proveedores terminan sugiriendo el flujo implícito.
+
+/// note | Nota
+
+Es común que cada proveedor de autenticación nombre sus flujos de una manera diferente, para hacerlos parte de su marca.
+
+Pero al final, están implementando el mismo estándar OAuth2.
+
+///
+
+**FastAPI** incluye utilidades para todos estos flujos de autenticación OAuth2 en `fastapi.security.oauth2`.
+
+## `Security` en `dependencies` del decorador
+
+De la misma manera que puedes definir una `list` de `Depends` en el parámetro `dependencies` del decorador (como se explica en [Dependencias en decoradores de path operation](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}), también podrías usar `Security` con `scopes` allí.
diff --git a/docs/es/docs/advanced/settings.md b/docs/es/docs/advanced/settings.md
new file mode 100644
index 000000000..7e591cc01
--- /dev/null
+++ b/docs/es/docs/advanced/settings.md
@@ -0,0 +1,346 @@
+# Configuraciones y Variables de Entorno
+
+En muchos casos, tu aplicación podría necesitar algunas configuraciones o ajustes externos, por ejemplo, claves secretas, credenciales de base de datos, credenciales para servicios de correo electrónico, etc.
+
+La mayoría de estas configuraciones son variables (pueden cambiar), como las URLs de bases de datos. Y muchas podrían ser sensibles, como los secretos.
+
+Por esta razón, es común proporcionarlas en variables de entorno que son leídas por la aplicación.
+
+/// tip | Consejo
+
+Para entender las variables de entorno, puedes leer [Variables de Entorno](../environment-variables.md){.internal-link target=_blank}.
+
+///
+
+## Tipos y validación
+
+Estas variables de entorno solo pueden manejar strings de texto, ya que son externas a Python y tienen que ser compatibles con otros programas y el resto del sistema (e incluso con diferentes sistemas operativos, como Linux, Windows, macOS).
+
+Eso significa que cualquier valor leído en Python desde una variable de entorno será un `str`, y cualquier conversión a un tipo diferente o cualquier validación tiene que hacerse en código.
+
+## Pydantic `Settings`
+
+Afortunadamente, Pydantic proporciona una gran utilidad para manejar estas configuraciones provenientes de variables de entorno con Pydantic: Settings management.
+
+### Instalar `pydantic-settings`
+
+Primero, asegúrate de crear tu [entorno virtual](../virtual-environments.md){.internal-link target=_blank}, actívalo y luego instala el paquete `pydantic-settings`:
+
+
+
+Y luego, abre la documentación para la sub-aplicación, en http://127.0.0.1:8000/subapi/docs.
+
+Verás la documentación automática de la API para la sub-aplicación, incluyendo solo sus propias _path operations_, todas bajo el prefijo correcto del sub-path `/subapi`:
+
+
+
+Si intentas interactuar con cualquiera de las dos interfaces de usuario, funcionarán correctamente, porque el navegador podrá comunicarse con cada aplicación o sub-aplicación específica.
+
+### Detalles Técnicos: `root_path`
+
+Cuando montas una sub-aplicación como se describe arriba, FastAPI se encargará de comunicar el path de montaje para la sub-aplicación usando un mecanismo de la especificación ASGI llamado `root_path`.
+
+De esa manera, la sub-aplicación sabrá usar ese prefijo de path para la interfaz de documentación.
+
+Y la sub-aplicación también podría tener sus propias sub-aplicaciones montadas y todo funcionaría correctamente, porque FastAPI maneja todos estos `root_path`s automáticamente.
+
+Aprenderás más sobre el `root_path` y cómo usarlo explícitamente en la sección sobre [Detrás de un Proxy](behind-a-proxy.md){.internal-link target=_blank}.
diff --git a/docs/es/docs/advanced/templates.md b/docs/es/docs/advanced/templates.md
new file mode 100644
index 000000000..9de866c2b
--- /dev/null
+++ b/docs/es/docs/advanced/templates.md
@@ -0,0 +1,126 @@
+# Plantillas
+
+Puedes usar cualquier motor de plantillas que desees con **FastAPI**.
+
+Una elección común es Jinja2, el mismo que usa Flask y otras herramientas.
+
+Hay utilidades para configurarlo fácilmente que puedes usar directamente en tu aplicación de **FastAPI** (proporcionadas por Starlette).
+
+## Instalar dependencias
+
+Asegúrate de crear un [entorno virtual](../virtual-environments.md){.internal-link target=_blank}, activarlo e instalar `jinja2`:
+
+
+
+Puedes escribir mensajes en el cuadro de entrada y enviarlos:
+
+
+
+Y tu aplicación **FastAPI** con WebSockets responderá de vuelta:
+
+
+
+Puedes enviar (y recibir) muchos mensajes:
+
+
+
+Y todos usarán la misma conexión WebSocket.
+
+## Usando `Depends` y otros
+
+En endpoints de WebSocket puedes importar desde `fastapi` y usar:
+
+* `Depends`
+* `Security`
+* `Cookie`
+* `Header`
+* `Path`
+* `Query`
+
+Funcionan de la misma manera que para otros endpoints de FastAPI/*path operations*:
+
+{* ../../docs_src/websockets/tutorial002_an_py310.py hl[68:69,82] *}
+
+/// info | Información
+
+Como esto es un WebSocket no tiene mucho sentido lanzar un `HTTPException`, en su lugar lanzamos un `WebSocketException`.
+
+Puedes usar un código de cierre de los códigos válidos definidos en la especificación.
+
+///
+
+### Prueba los WebSockets con dependencias
+
+Si tu archivo se llama `main.py`, ejecuta tu aplicación con:
+
+
+
+## Manejar desconexiones y múltiples clientes
+
+Cuando una conexión de WebSocket se cierra, el `await websocket.receive_text()` lanzará una excepción `WebSocketDisconnect`, que puedes capturar y manejar como en este ejemplo.
+
+{* ../../docs_src/websockets/tutorial003_py39.py hl[79:81] *}
+
+Para probarlo:
+
+* Abre la aplicación con varias pestañas del navegador.
+* Escribe mensajes desde ellas.
+* Luego cierra una de las pestañas.
+
+Eso lanzará la excepción `WebSocketDisconnect`, y todos los otros clientes recibirán un mensaje como:
+
+```
+Client #1596980209979 left the chat
+```
+
+/// tip | Consejo
+
+La aplicación anterior es un ejemplo mínimo y simple para demostrar cómo manejar y transmitir mensajes a varias conexiones WebSocket.
+
+Pero ten en cuenta que, como todo se maneja en memoria, en una sola lista, solo funcionará mientras el proceso esté en ejecución, y solo funcionará con un solo proceso.
+
+Si necesitas algo fácil de integrar con FastAPI pero que sea más robusto, soportado por Redis, PostgreSQL u otros, revisa encode/broadcaster.
+
+///
+
+## Más información
+
+Para aprender más sobre las opciones, revisa la documentación de Starlette para:
+
+* La clase `WebSocket`.
+* Manejo de WebSocket basado en clases.
diff --git a/docs/es/docs/advanced/wsgi.md b/docs/es/docs/advanced/wsgi.md
new file mode 100644
index 000000000..7df62fc9a
--- /dev/null
+++ b/docs/es/docs/advanced/wsgi.md
@@ -0,0 +1,35 @@
+# Incluyendo WSGI - Flask, Django, otros
+
+Puedes montar aplicaciones WSGI como viste con [Sub Aplicaciones - Mounts](sub-applications.md){.internal-link target=_blank}, [Detrás de un Proxy](behind-a-proxy.md){.internal-link target=_blank}.
+
+Para eso, puedes usar `WSGIMiddleware` y usarlo para envolver tu aplicación WSGI, por ejemplo, Flask, Django, etc.
+
+## Usando `WSGIMiddleware`
+
+Necesitas importar `WSGIMiddleware`.
+
+Luego envuelve la aplicación WSGI (p. ej., Flask) con el middleware.
+
+Y luego móntala bajo un path.
+
+{* ../../docs_src/wsgi/tutorial001.py hl[2:3,3] *}
+
+## Revisa
+
+Ahora, cada request bajo el path `/v1/` será manejado por la aplicación Flask.
+
+Y el resto será manejado por **FastAPI**.
+
+Si lo ejecutas y vas a http://localhost:8000/v1/ verás el response de Flask:
+
+```txt
+Hello, World from Flask!
+```
+
+Y si vas a http://localhost:8000/v2 verás el response de FastAPI:
+
+```JSON
+{
+ "message": "Hello World"
+}
+```
diff --git a/docs/es/docs/alternatives.md b/docs/es/docs/alternatives.md
new file mode 100644
index 000000000..753b827c0
--- /dev/null
+++ b/docs/es/docs/alternatives.md
@@ -0,0 +1,485 @@
+# Alternativas, Inspiración y Comparaciones
+
+Lo que inspiró a **FastAPI**, cómo se compara con las alternativas y lo que aprendió de ellas.
+
+## Introducción
+
+**FastAPI** no existiría si no fuera por el trabajo previo de otros.
+
+Se han creado muchas herramientas antes que han ayudado a inspirar su creación.
+
+He estado evitando la creación de un nuevo framework durante varios años. Primero intenté resolver todas las funcionalidades cubiertas por **FastAPI** usando muchos frameworks diferentes, plug-ins y herramientas.
+
+Pero en algún punto, no hubo otra opción que crear algo que proporcionara todas estas funcionalidades, tomando las mejores ideas de herramientas previas y combinándolas de la mejor manera posible, usando funcionalidades del lenguaje que ni siquiera estaban disponibles antes (anotaciones de tipos de Python 3.6+).
+
+## Herramientas previas
+
+### Django
+
+Es el framework más popular de Python y es ampliamente confiable. Se utiliza para construir sistemas como Instagram.
+
+Está relativamente acoplado con bases de datos relacionales (como MySQL o PostgreSQL), por lo que tener una base de datos NoSQL (como Couchbase, MongoDB, Cassandra, etc) como motor de almacenamiento principal no es muy fácil.
+
+Fue creado para generar el HTML en el backend, no para crear APIs utilizadas por un frontend moderno (como React, Vue.js y Angular) o por otros sistemas (como dispositivos del IoT) comunicándose con él.
+
+### Django REST Framework
+
+El framework Django REST fue creado para ser un kit de herramientas flexible para construir APIs Web utilizando Django, mejorando sus capacidades API.
+
+Es utilizado por muchas empresas, incluidas Mozilla, Red Hat y Eventbrite.
+
+Fue uno de los primeros ejemplos de **documentación automática de APIs**, y esto fue específicamente una de las primeras ideas que inspiraron "la búsqueda de" **FastAPI**.
+
+/// note | Nota
+
+Django REST Framework fue creado por Tom Christie. El mismo creador de Starlette y Uvicorn, en los cuales **FastAPI** está basado.
+
+///
+
+/// check | Inspiró a **FastAPI** a
+
+Tener una interfaz de usuario web de documentación automática de APIs.
+
+///
+
+### Flask
+
+Flask es un "microframework", no incluye integraciones de bases de datos ni muchas de las cosas que vienen por defecto en Django.
+
+Esta simplicidad y flexibilidad permiten hacer cosas como usar bases de datos NoSQL como el sistema de almacenamiento de datos principal.
+
+Como es muy simple, es relativamente intuitivo de aprender, aunque la documentación se vuelve algo técnica en algunos puntos.
+
+También se utiliza comúnmente para otras aplicaciones que no necesariamente necesitan una base de datos, gestión de usuarios, o cualquiera de las muchas funcionalidades que vienen preconstruidas en Django. Aunque muchas de estas funcionalidades se pueden añadir con plug-ins.
+
+Esta separación de partes, y ser un "microframework" que podría extenderse para cubrir exactamente lo que se necesita, fue una funcionalidad clave que quise mantener.
+
+Dada la simplicidad de Flask, parecía una buena opción para construir APIs. Lo siguiente a encontrar era un "Django REST Framework" para Flask.
+
+/// check | Inspiró a **FastAPI** a
+
+Ser un micro-framework. Haciendo fácil mezclar y combinar las herramientas y partes necesarias.
+
+Tener un sistema de routing simple y fácil de usar.
+
+///
+
+### Requests
+
+**FastAPI** no es en realidad una alternativa a **Requests**. Su ámbito es muy diferente.
+
+De hecho, sería común usar Requests *dentro* de una aplicación FastAPI.
+
+Aun así, FastAPI se inspiró bastante en Requests.
+
+**Requests** es un paquete para *interactuar* con APIs (como cliente), mientras que **FastAPI** es un paquete para *construir* APIs (como servidor).
+
+Están, más o menos, en extremos opuestos, complementándose entre sí.
+
+Requests tiene un diseño muy simple e intuitivo, es muy fácil de usar, con valores predeterminados sensatos. Pero al mismo tiempo, es muy poderoso y personalizable.
+
+Por eso, como se dice en el sitio web oficial:
+
+> Requests es uno de los paquetes Python más descargados de todos los tiempos
+
+La forma en que lo usas es muy sencilla. Por ejemplo, para hacer un `GET` request, escribirías:
+
+```Python
+response = requests.get("http://example.com/some/url")
+```
+
+La operación de path equivalente en FastAPI podría verse como:
+
+```Python hl_lines="1"
+@app.get("/some/url")
+def read_url():
+ return {"message": "Hello World"}
+```
+
+Mira las similitudes entre `requests.get(...)` y `@app.get(...)`.
+
+/// check | Inspiró a **FastAPI** a
+
+* Tener un API simple e intuitivo.
+* Usar nombres de métodos HTTP (operaciones) directamente, de una manera sencilla e intuitiva.
+* Tener valores predeterminados sensatos, pero personalizaciones poderosas.
+
+///
+
+### Swagger / OpenAPI
+
+La principal funcionalidad que quería de Django REST Framework era la documentación automática de la API.
+
+Luego descubrí que había un estándar para documentar APIs, usando JSON (o YAML, una extensión de JSON) llamado Swagger.
+
+Y ya existía una interfaz de usuario web para las APIs Swagger. Por lo tanto, ser capaz de generar documentación Swagger para una API permitiría usar esta interfaz de usuario web automáticamente.
+
+En algún punto, Swagger fue entregado a la Linux Foundation, para ser renombrado OpenAPI.
+
+Es por eso que cuando se habla de la versión 2.0 es común decir "Swagger", y para la versión 3+ "OpenAPI".
+
+/// check | Inspiró a **FastAPI** a
+
+Adoptar y usar un estándar abierto para especificaciones de API, en lugar de usar un esquema personalizado.
+
+Y a integrar herramientas de interfaz de usuario basadas en estándares:
+
+* Swagger UI
+* ReDoc
+
+Estas dos fueron elegidas por ser bastante populares y estables, pero haciendo una búsqueda rápida, podrías encontrar docenas de interfaces de usuario alternativas para OpenAPI (que puedes usar con **FastAPI**).
+
+///
+
+### Frameworks REST para Flask
+
+Existen varios frameworks REST para Flask, pero después de invertir tiempo y trabajo investigándolos, encontré que muchos son descontinuados o abandonados, con varios problemas existentes que los hacían inadecuados.
+
+### Marshmallow
+
+Una de las principales funcionalidades necesitadas por los sistemas API es la "serialización" de datos, que consiste en tomar datos del código (Python) y convertirlos en algo que pueda ser enviado a través de la red. Por ejemplo, convertir un objeto que contiene datos de una base de datos en un objeto JSON. Convertir objetos `datetime` en strings, etc.
+
+Otra gran funcionalidad necesaria por las APIs es la validación de datos, asegurarse de que los datos sean válidos, dados ciertos parámetros. Por ejemplo, que algún campo sea un `int`, y no algún string aleatorio. Esto es especialmente útil para los datos entrantes.
+
+Sin un sistema de validación de datos, tendrías que hacer todas las comprobaciones a mano, en código.
+
+Estas funcionalidades son para lo que fue creado Marshmallow. Es un gran paquete, y lo he usado mucho antes.
+
+Pero fue creado antes de que existieran las anotaciones de tipos en Python. Así que, para definir cada esquema necesitas usar utilidades y clases específicas proporcionadas por Marshmallow.
+
+/// check | Inspiró a **FastAPI** a
+
+Usar código para definir "esquemas" que proporcionen tipos de datos y validación automáticamente.
+
+///
+
+### Webargs
+
+Otra gran funcionalidad requerida por las APIs es el parse de datos de las requests entrantes.
+
+Webargs es una herramienta que fue creada para proporcionar esa funcionalidad sobre varios frameworks, incluido Flask.
+
+Usa Marshmallow por debajo para hacer la validación de datos. Y fue creada por los mismos desarrolladores.
+
+Es una gran herramienta y la he usado mucho también, antes de tener **FastAPI**.
+
+/// info | Información
+
+Webargs fue creada por los mismos desarrolladores de Marshmallow.
+
+///
+
+/// check | Inspiró a **FastAPI** a
+
+Tener validación automática de datos entrantes en una request.
+
+///
+
+### APISpec
+
+Marshmallow y Webargs proporcionan validación, parse y serialización como plug-ins.
+
+Pero la documentación todavía falta. Entonces APISpec fue creado.
+
+Es un plug-in para muchos frameworks (y hay un plug-in para Starlette también).
+
+La manera en que funciona es que escribes la definición del esquema usando el formato YAML dentro del docstring de cada función que maneja una ruta.
+
+Y genera esquemas OpenAPI.
+
+Así es como funciona en Flask, Starlette, Responder, etc.
+
+Pero luego, tenemos otra vez el problema de tener una micro-sintaxis, dentro de un string de Python (un gran YAML).
+
+El editor no puede ayudar mucho con eso. Y si modificamos parámetros o esquemas de Marshmallow y olvidamos también modificar ese docstring YAML, el esquema generado estaría obsoleto.
+
+/// info | Información
+
+APISpec fue creado por los mismos desarrolladores de Marshmallow.
+
+///
+
+/// check | Inspiró a **FastAPI** a
+
+Soportar el estándar abierto para APIs, OpenAPI.
+
+///
+
+### Flask-apispec
+
+Es un plug-in de Flask, que conecta juntos Webargs, Marshmallow y APISpec.
+
+Usa la información de Webargs y Marshmallow para generar automáticamente esquemas OpenAPI, usando APISpec.
+
+Es una gran herramienta, muy subestimada. Debería ser mucho más popular que muchos plug-ins de Flask por ahí. Puede que se deba a que su documentación es demasiado concisa y abstracta.
+
+Esto resolvió tener que escribir YAML (otra sintaxis) dentro de docstrings de Python.
+
+Esta combinación de Flask, Flask-apispec con Marshmallow y Webargs fue mi stack de backend favorito hasta construir **FastAPI**.
+
+Usarlo llevó a la creación de varios generadores de full-stack para Flask. Estos son los principales stacks que yo (y varios equipos externos) hemos estado usando hasta ahora:
+
+* https://github.com/tiangolo/full-stack
+* https://github.com/tiangolo/full-stack-flask-couchbase
+* https://github.com/tiangolo/full-stack-flask-couchdb
+
+Y estos mismos generadores de full-stack fueron la base de los [Generadores de Proyectos **FastAPI**](project-generation.md){.internal-link target=_blank}.
+
+/// info | Información
+
+Flask-apispec fue creado por los mismos desarrolladores de Marshmallow.
+
+///
+
+/// check | Inspiró a **FastAPI** a
+
+Generar el esquema OpenAPI automáticamente, desde el mismo código que define la serialización y validación.
+
+///
+
+### NestJS (y Angular)
+
+Esto ni siquiera es Python, NestJS es un framework de JavaScript (TypeScript) NodeJS inspirado por Angular.
+
+Logra algo algo similar a lo que se puede hacer con Flask-apispec.
+
+Tiene un sistema de inyección de dependencias integrado, inspirado por Angular 2. Requiere pre-registrar los "inyectables" (como todos los otros sistemas de inyección de dependencias que conozco), por lo que añade a la verbosidad y repetición de código.
+
+Como los parámetros se describen con tipos de TypeScript (similar a las anotaciones de tipos en Python), el soporte editorial es bastante bueno.
+
+Pero como los datos de TypeScript no se preservan después de la compilación a JavaScript, no puede depender de los tipos para definir validación, serialización y documentación al mismo tiempo. Debido a esto y algunas decisiones de diseño, para obtener validación, serialización y generación automática del esquema, es necesario agregar decoradores en muchos lugares. Por lo tanto, se vuelve bastante verboso.
+
+No puede manejar muy bien modelos anidados. Entonces, si el cuerpo JSON en la request es un objeto JSON que tiene campos internos que a su vez son objetos JSON anidados, no puede ser documentado y validado apropiadamente.
+
+/// check | Inspiró a **FastAPI** a
+
+Usar tipos de Python para tener un gran soporte del editor.
+
+Tener un poderoso sistema de inyección de dependencias. Encontrar una forma de minimizar la repetición de código.
+
+///
+
+### Sanic
+
+Fue uno de los primeros frameworks de Python extremadamente rápidos basados en `asyncio`. Fue hecho para ser muy similar a Flask.
+
+/// note | Detalles Técnicos
+
+Usó `uvloop` en lugar del loop `asyncio` por defecto de Python. Eso fue lo que lo hizo tan rápido.
+
+Claramente inspiró a Uvicorn y Starlette, que actualmente son más rápidos que Sanic en benchmarks abiertos.
+
+///
+
+/// check | Inspiró a **FastAPI** a
+
+Encontrar una manera de tener un rendimiento impresionante.
+
+Por eso **FastAPI** se basa en Starlette, ya que es el framework más rápido disponible (probado por benchmarks de terceros).
+
+///
+
+### Falcon
+
+Falcon es otro framework de Python de alto rendimiento, está diseñado para ser minimalista y funcionar como la base de otros frameworks como Hug.
+
+Está diseñado para tener funciones que reciben dos parámetros, un "request" y un "response". Luego "lees" partes del request y "escribes" partes en el response. Debido a este diseño, no es posible declarar parámetros de request y cuerpos con las anotaciones de tipos estándar de Python como parámetros de función.
+
+Por lo tanto, la validación de datos, la serialización y la documentación, tienen que hacerse en código, no automáticamente. O tienen que implementarse como un framework sobre Falcon, como Hug. Esta misma distinción ocurre en otros frameworks que se inspiran en el diseño de Falcon, de tener un objeto request y un objeto response como parámetros.
+
+/// check | Inspiró a **FastAPI** a
+
+Buscar maneras de obtener un gran rendimiento.
+
+Junto con Hug (ya que Hug se basa en Falcon), inspiraron a **FastAPI** a declarar un parámetro `response` en las funciones.
+
+Aunque en FastAPI es opcional, y se utiliza principalmente para configurar headers, cookies y códigos de estado alternativos.
+
+///
+
+### Molten
+
+Descubrí Molten en las primeras etapas de construcción de **FastAPI**. Y tiene ideas bastante similares:
+
+* Basado en las anotaciones de tipos de Python.
+* Validación y documentación a partir de estos tipos.
+* Sistema de Inyección de Dependencias.
+
+No utiliza un paquete de validación de datos, serialización y documentación de terceros como Pydantic, tiene el suyo propio. Por lo tanto, estas definiciones de tipos de datos no serían reutilizables tan fácilmente.
+
+Requiere configuraciones un poquito más verbosas. Y dado que se basa en WSGI (en lugar de ASGI), no está diseñado para aprovechar el alto rendimiento proporcionado por herramientas como Uvicorn, Starlette y Sanic.
+
+El sistema de inyección de dependencias requiere pre-registrar las dependencias y las dependencias se resuelven en base a los tipos declarados. Por lo tanto, no es posible declarar más de un "componente" que proporcione cierto tipo.
+
+Las rutas se declaran en un solo lugar, usando funciones declaradas en otros lugares (en lugar de usar decoradores que pueden colocarse justo encima de la función que maneja el endpoint). Esto se acerca más a cómo lo hace Django que a cómo lo hace Flask (y Starlette). Separa en el código cosas que están relativamente acopladas.
+
+/// check | Inspiró a **FastAPI** a
+
+Definir validaciones extra para tipos de datos usando el valor "default" de los atributos del modelo. Esto mejora el soporte del editor y no estaba disponible en Pydantic antes.
+
+Esto en realidad inspiró la actualización de partes de Pydantic, para soportar el mismo estilo de declaración de validación (toda esta funcionalidad ya está disponible en Pydantic).
+
+///
+
+### Hug
+
+Hug fue uno de los primeros frameworks en implementar la declaración de tipos de parámetros API usando las anotaciones de tipos de Python. Esta fue una gran idea que inspiró a otras herramientas a hacer lo mismo.
+
+Usaba tipos personalizados en sus declaraciones en lugar de tipos estándar de Python, pero aún así fue un gran avance.
+
+También fue uno de los primeros frameworks en generar un esquema personalizado declarando toda la API en JSON.
+
+No se basaba en un estándar como OpenAPI y JSON Schema. Por lo que no sería sencillo integrarlo con otras herramientas, como Swagger UI. Pero, nuevamente, fue una idea muy innovadora.
+
+Tiene una funcionalidad interesante e inusual: usando el mismo framework, es posible crear APIs y también CLIs.
+
+Dado que se basa en el estándar previo para frameworks web Python sincrónicos (WSGI), no puede manejar Websockets y otras cosas, aunque aún así tiene un alto rendimiento también.
+
+/// info | Información
+
+Hug fue creado por Timothy Crosley, el mismo creador de `isort`, una gran herramienta para ordenar automáticamente imports en archivos Python.
+
+///
+
+/// check | Ideas que inspiraron a **FastAPI**
+
+Hug inspiró partes de APIStar, y fue una de las herramientas que encontré más prometedoras, junto a APIStar.
+
+Hug ayudó a inspirar a **FastAPI** a usar anotaciones de tipos de Python para declarar parámetros, y a generar un esquema definiendo la API automáticamente.
+
+Hug inspiró a **FastAPI** a declarar un parámetro `response` en funciones para configurar headers y cookies.
+
+///
+
+### APIStar (<= 0.5)
+
+Justo antes de decidir construir **FastAPI** encontré **APIStar** server. Tenía casi todo lo que estaba buscando y tenía un gran diseño.
+
+Era una de las primeras implementaciones de un framework utilizando las anotaciones de tipos de Python para declarar parámetros y requests que jamás vi (antes de NestJS y Molten). Lo encontré más o menos al mismo tiempo que Hug. Pero APIStar usaba el estándar OpenAPI.
+
+Tenía validación de datos automática, serialización de datos y generación del esquema OpenAPI basada en las mismas anotaciones de tipos en varios lugares.
+
+Las definiciones de esquema de cuerpo no usaban las mismas anotaciones de tipos de Python como Pydantic, era un poco más similar a Marshmallow, por lo que el soporte del editor no sería tan bueno, pero aún así, APIStar era la mejor opción disponible.
+
+Tenía los mejores benchmarks de rendimiento en ese momento (solo superado por Starlette).
+
+Al principio, no tenía una interfaz de usuario web de documentación de API automática, pero sabía que podía agregar Swagger UI a él.
+
+Tenía un sistema de inyección de dependencias. Requería pre-registrar componentes, como otras herramientas discutidas anteriormente. Pero aún así, era una gran funcionalidad.
+
+Nunca pude usarlo en un proyecto completo, ya que no tenía integración de seguridad, por lo que no podía reemplazar todas las funcionalidades que tenía con los generadores de full-stack basados en Flask-apispec. Tenía en mi lista de tareas pendientes de proyectos crear un pull request agregando esa funcionalidad.
+
+Pero luego, el enfoque del proyecto cambió.
+
+Ya no era un framework web API, ya que el creador necesitaba enfocarse en Starlette.
+
+Ahora APIStar es un conjunto de herramientas para validar especificaciones OpenAPI, no un framework web.
+
+/// info | Información
+
+APIStar fue creado por Tom Christie. El mismo que creó:
+
+* Django REST Framework
+* Starlette (en la cual **FastAPI** está basado)
+* Uvicorn (usado por Starlette y **FastAPI**)
+
+///
+
+/// check | Inspiró a **FastAPI** a
+
+Existir.
+
+La idea de declarar múltiples cosas (validación de datos, serialización y documentación) con los mismos tipos de Python, que al mismo tiempo proporcionaban un gran soporte del editor, era algo que consideré una idea brillante.
+
+Y después de buscar durante mucho tiempo un framework similar y probar muchas alternativas diferentes, APIStar fue la mejor opción disponible.
+
+Luego APIStar dejó de existir como servidor y Starlette fue creado, y fue una nueva y mejor base para tal sistema. Esa fue la inspiración final para construir **FastAPI**.
+
+Considero a **FastAPI** un "sucesor espiritual" de APIStar, mientras mejora y aumenta las funcionalidades, el sistema de tipos y otras partes, basándose en los aprendizajes de todas estas herramientas previas.
+
+///
+
+## Usado por **FastAPI**
+
+### Pydantic
+
+Pydantic es un paquete para definir validación de datos, serialización y documentación (usando JSON Schema) basándose en las anotaciones de tipos de Python.
+
+Eso lo hace extremadamente intuitivo.
+
+Es comparable a Marshmallow. Aunque es más rápido que Marshmallow en benchmarks. Y como está basado en las mismas anotaciones de tipos de Python, el soporte del editor es estupendo.
+
+/// check | **FastAPI** lo usa para
+
+Manejar toda la validación de datos, serialización de datos y documentación automática de modelos (basada en JSON Schema).
+
+**FastAPI** luego toma esos datos JSON Schema y los coloca en OpenAPI, aparte de todas las otras cosas que hace.
+
+///
+
+### Starlette
+
+Starlette es un framework/toolkit ASGI liviano, ideal para construir servicios asyncio de alto rendimiento.
+
+Es muy simple e intuitivo. Está diseñado para ser fácilmente extensible y tener componentes modulares.
+
+Tiene:
+
+* Un rendimiento seriamente impresionante.
+* Soporte para WebSocket.
+* Tareas en segundo plano dentro del proceso.
+* Eventos de inicio y apagado.
+* Cliente de pruebas basado en HTTPX.
+* CORS, GZip, Archivos estáticos, Responses en streaming.
+* Soporte para sesiones y cookies.
+* Cobertura de tests del 100%.
+* Base de código 100% tipada.
+* Pocas dependencias obligatorias.
+
+Starlette es actualmente el framework de Python más rápido probado. Solo superado por Uvicorn, que no es un framework, sino un servidor.
+
+Starlette proporciona toda la funcionalidad básica de un microframework web.
+
+Pero no proporciona validación de datos automática, serialización o documentación.
+
+Esa es una de las principales cosas que **FastAPI** agrega, todo basado en las anotaciones de tipos de Python (usando Pydantic). Eso, además del sistema de inyección de dependencias, utilidades de seguridad, generación de esquemas OpenAPI, etc.
+
+/// note | Detalles Técnicos
+
+ASGI es un nuevo "estándar" que está siendo desarrollado por miembros del equipo central de Django. Todavía no es un "estándar de Python" (un PEP), aunque están en proceso de hacerlo.
+
+No obstante, ya está siendo usado como un "estándar" por varias herramientas. Esto mejora enormemente la interoperabilidad, ya que podrías cambiar Uvicorn por cualquier otro servidor ASGI (como Daphne o Hypercorn), o podrías añadir herramientas compatibles con ASGI, como `python-socketio`.
+
+///
+
+/// check | **FastAPI** lo usa para
+
+Manejar todas las partes web centrales. Añadiendo funcionalidades encima.
+
+La clase `FastAPI` en sí misma hereda directamente de la clase `Starlette`.
+
+Por lo tanto, cualquier cosa que puedas hacer con Starlette, puedes hacerlo directamente con **FastAPI**, ya que es básicamente Starlette potenciado.
+
+///
+
+### Uvicorn
+
+Uvicorn es un servidor ASGI extremadamente rápido, construido sobre uvloop y httptools.
+
+No es un framework web, sino un servidor. Por ejemplo, no proporciona herramientas para el enrutamiento por paths. Eso es algo que un framework como Starlette (o **FastAPI**) proporcionaría encima.
+
+Es el servidor recomendado para Starlette y **FastAPI**.
+
+/// check | **FastAPI** lo recomienda como
+
+El servidor web principal para ejecutar aplicaciones **FastAPI**.
+
+También puedes usar la opción de línea de comandos `--workers` para tener un servidor multiproceso asíncrono.
+
+Revisa más detalles en la sección [Despliegue](deployment/index.md){.internal-link target=_blank}.
+
+///
+
+## Benchmarks y velocidad
+
+Para entender, comparar, y ver la diferencia entre Uvicorn, Starlette y FastAPI, revisa la sección sobre [Benchmarks](benchmarks.md){.internal-link target=_blank}.
diff --git a/docs/es/docs/async.md b/docs/es/docs/async.md
index 18159775d..e3fd077c4 100644
--- a/docs/es/docs/async.md
+++ b/docs/es/docs/async.md
@@ -1,18 +1,18 @@
# Concurrencia y async / await
-Detalles sobre la sintaxis `async def` para *path operation functions* y un poco de información sobre código asíncrono, concurrencia y paralelismo.
+Detalles sobre la sintaxis `async def` para *path operation functions* y algunos antecedentes sobre el código asíncrono, la concurrencia y el paralelismo.
-## ¿Tienes prisa?
+## ¿Con prisa?
TL;DR:
-Si estás utilizando libraries de terceros que te dicen que las llames con `await`, del tipo:
+Si estás usando paquetes de terceros que te dicen que los llames con `await`, como:
```Python
results = await some_library()
```
-Entonces declara tus *path operation functions* con `async def` de la siguiente manera:
+Entonces, declara tus *path operation functions* con `async def` así:
```Python hl_lines="2"
@app.get('/')
@@ -21,12 +21,15 @@ async def read_results():
return results
```
-!!! note "Nota"
- Solo puedes usar `await` dentro de funciones creadas con `async def`.
+/// note | Nota
+
+Solo puedes usar `await` dentro de funciones creadas con `async def`.
+
+///
---
-Si estás utilizando libraries de terceros que se comunican con algo (una base de datos, una API, el sistema de archivos, etc.) y no tienes soporte para `await` (este es el caso para la mayoría de las libraries de bases de datos), declara tus *path operation functions* de forma habitual, con solo `def`, de la siguiente manera:
+Si estás usando un paquete de terceros que se comunica con algo (una base de datos, una API, el sistema de archivos, etc.) y no tiene soporte para usar `await` (este es actualmente el caso para la mayoría de los paquetes de base de datos), entonces declara tus *path operation functions* como normalmente, usando simplemente `def`, así:
```Python hl_lines="2"
@app.get('/')
@@ -37,7 +40,7 @@ def results():
---
-Si tu aplicación (de alguna manera) no tiene que comunicarse con nada más y en consecuencia esperar a que responda, usa `async def`.
+Si tu aplicación (de alguna manera) no tiene que comunicarse con nada más y esperar a que responda, usa `async def`.
---
@@ -45,17 +48,17 @@ Si simplemente no lo sabes, usa `def` normal.
---
-**Nota**: puedes mezclar `def` y `async def` en tus *path operation functions* tanto como lo necesites y definir cada una utilizando la mejor opción para ti. FastAPI hará lo correcto con ellos.
+**Nota**: Puedes mezclar `def` y `async def` en tus *path operation functions* tanto como necesites y definir cada una utilizando la mejor opción para ti. FastAPI hará lo correcto con ellas.
De todos modos, en cualquiera de los casos anteriores, FastAPI seguirá funcionando de forma asíncrona y será extremadamente rápido.
-Pero siguiendo los pasos anteriores, FastAPI podrá hacer algunas optimizaciones de rendimiento.
+Pero al seguir los pasos anteriores, podrá hacer algunas optimizaciones de rendimiento.
## Detalles Técnicos
-Las versiones modernas de Python tienen soporte para **"código asíncrono"** usando algo llamado **"coroutines"**, usando la sintaxis **`async` y `await`**.
+Las versiones modernas de Python tienen soporte para **"código asíncrono"** utilizando algo llamado **"coroutines"**, con la sintaxis **`async` y `await`**.
-Veamos esa frase por partes en las secciones siguientes:
+Veamos esa frase por partes en las secciones a continuación:
* **Código Asíncrono**
* **`async` y `await`**
@@ -63,197 +66,200 @@ Veamos esa frase por partes en las secciones siguientes:
## Código Asíncrono
-El código asíncrono sólo significa que el lenguaje 💬 tiene una manera de decirle al sistema / programa 🤖 que, en algún momento del código, 🤖 tendrá que esperar a que *algo más* termine en otro sitio. Digamos que ese *algo más* se llama, por ejemplo, "archivo lento" 📝.
+El código asíncrono simplemente significa que el lenguaje 💬 tiene una forma de decirle a la computadora / programa 🤖 que en algún momento del código, tendrá que esperar que *otra cosa* termine en otro lugar. Digamos que esa *otra cosa* se llama "archivo-lento" 📝.
-Durante ese tiempo, el sistema puede hacer otras cosas, mientras "archivo lento" 📝 termina.
+Entonces, durante ese tiempo, la computadora puede ir y hacer algún otro trabajo, mientras "archivo-lento" 📝 termina.
-Entonces el sistema / programa 🤖 volverá cada vez que pueda, sea porque está esperando otra vez, porque 🤖 ha terminado todo el trabajo que tenía en ese momento. Y 🤖 verá si alguna de las tareas por las que estaba esperando ha terminado, haciendo lo que tenía que hacer.
+Luego la computadora / programa 🤖 volverá cada vez que tenga una oportunidad porque está esperando nuevamente, o siempre que 🤖 haya terminado todo el trabajo que tenía en ese punto. Y 🤖 comprobará si alguna de las tareas que estaba esperando ya se han completado, haciendo lo que tenía que hacer.
-Luego, 🤖 cogerá la primera tarea finalizada (digamos, nuestro "archivo lento" 📝) y continuará con lo que tenía que hacer con esa tarea.
+Después, 🤖 toma la primera tarea que termine (digamos, nuestro "archivo-lento" 📝) y continúa con lo que tenía que hacer con ella.
-Esa "espera de otra cosa" normalmente se refiere a operaciones I/O que son relativamente "lentas" (en relación a la velocidad del procesador y memoria RAM), como por ejemplo esperar por:
+Ese "esperar otra cosa" normalmente se refiere a las operaciones de I/O que son relativamente "lentas" (comparadas con la velocidad del procesador y la memoria RAM), como esperar:
-* los datos de cliente que se envían a través de la red
-* los datos enviados por tu programa para ser recibidos por el cliente a través de la red
-* el contenido de un archivo en disco para ser leído por el sistema y entregado al programa
-* los contenidos que tu programa da al sistema para ser escritos en disco
-* una operación relacionada con una API remota
-* una operación de base de datos
-* el retorno de resultados de una consulta de base de datos
+* que los datos del cliente se envíen a través de la red
+* que los datos enviados por tu programa sean recibidos por el cliente a través de la red
+* que el contenido de un archivo en el disco sea leído por el sistema y entregado a tu programa
+* que el contenido que tu programa entregó al sistema sea escrito en el disco
+* una operación de API remota
+* que una operación de base de datos termine
+* que una query de base de datos devuelva los resultados
* etc.
-Como el tiempo de ejecución se consume principalmente al esperar a operaciones de I/O, las llaman operaciones "I/O bound".
+Como el tiempo de ejecución se consume principalmente esperando operaciones de I/O, las llaman operaciones "I/O bound".
-Se llama "asíncrono" porque el sistema / programa no tiene que estar "sincronizado" con la tarea lenta, esperando el momento exacto en que finaliza la tarea, sin hacer nada, para poder recoger el resultado de la tarea y continuar el trabajo.
+Se llama "asíncrono" porque la computadora / programa no tiene que estar "sincronizado" con la tarea lenta, esperando el momento exacto en que la tarea termine, sin hacer nada, para poder tomar el resultado de la tarea y continuar el trabajo.
-En lugar de eso, al ser un sistema "asíncrono", una vez finalizada, la tarea puede esperar un poco en la cola (algunos microsegundos) para que la computadora / programa termine lo que estaba haciendo, y luego vuelva para recoger los resultados y seguir trabajando con ellos.
+En lugar de eso, al ser un sistema "asíncrono", una vez terminado, la tarea puede esperar un poco en la cola (algunos microsegundos) para que la computadora / programa termine lo que salió a hacer, y luego regrese para tomar los resultados y continuar trabajando con ellos.
-Por "síncrono" (contrario a "asíncrono") también se usa habitualmente el término "secuencial", porque el sistema / programa sigue todos los pasos secuencialmente antes de cambiar a una tarea diferente, incluso si esos pasos implican esperas.
+Para el "sincrónico" (contrario al "asíncrono") comúnmente también usan el término "secuencial", porque la computadora / programa sigue todos los pasos en secuencia antes de cambiar a una tarea diferente, incluso si esos pasos implican esperar.
### Concurrencia y Hamburguesas
-El concepto de código **asíncrono** descrito anteriormente a veces también se llama **"concurrencia"**. Es diferente del **"paralelismo"**.
+Esta idea de código **asíncrono** descrita anteriormente a veces también se llama **"concurrencia"**. Es diferente del **"paralelismo"**.
-**Concurrencia** y **paralelismo** ambos se relacionan con "cosas diferentes que suceden más o menos al mismo tiempo".
+**Concurrencia** y **paralelismo** ambos se relacionan con "diferentes cosas sucediendo más o menos al mismo tiempo".
Pero los detalles entre *concurrencia* y *paralelismo* son bastante diferentes.
-Para entender las diferencias, imagina la siguiente historia sobre hamburguesas:
+Para ver la diferencia, imagina la siguiente historia sobre hamburguesas:
### Hamburguesas Concurrentes
-Vas con la persona que te gusta 😍 a pedir comida rápida 🍔, haces cola mientras el cajero 💁 recoge los pedidos de las personas de delante tuyo.
+Vas con tu crush a conseguir comida rápida, te pones en fila mientras el cajero toma los pedidos de las personas frente a ti. 😍
-
+
-Llega tu turno, haces tu pedido de 2 hamburguesas impresionantes para esa persona 😍 y para ti.
+Luego es tu turno, haces tu pedido de 2 hamburguesas muy sofisticadas para tu crush y para ti. 🍔🍔
-
+
-El cajero 💁 le dice algo al chico de la cocina 👨🍳 para que sepa que tiene que preparar tus hamburguesas 🍔 (a pesar de que actualmente está preparando las de los clientes anteriores).
+El cajero dice algo al cocinero en la cocina para que sepan que tienen que preparar tus hamburguesas (aunque actualmente están preparando las de los clientes anteriores).
-
+
-Pagas 💸.
-El cajero 💁 te da el número de tu turno.
+Pagas. 💸
-
+El cajero te da el número de tu turno.
-Mientras esperas, vas con esa persona 😍 y eliges una mesa, se sientan y hablan durante un rato largo (ya que las hamburguesas son muy impresionantes y necesitan un rato para prepararse ✨🍔✨).
+
-Mientras te sientas en la mesa con esa persona 😍, esperando las hamburguesas 🍔, puedes disfrutar ese tiempo admirando lo increíble, inteligente, y bien que se ve ✨😍✨.
+Mientras esperas, vas con tu crush y eliges una mesa, te sientas y hablas con tu crush por un largo rato (ya que tus hamburguesas son muy sofisticadas y toman un tiempo en prepararse).
-
+Mientras estás sentado en la mesa con tu crush, mientras esperas las hamburguesas, puedes pasar ese tiempo admirando lo increíble, lindo e inteligente que es tu crush ✨😍✨.
-Mientras esperas y hablas con esa persona 😍, de vez en cuando, verificas el número del mostrador para ver si ya es tu turno.
+
-Al final, en algún momento, llega tu turno. Vas al mostrador, coges tus hamburguesas 🍔 y vuelves a la mesa.
+Mientras esperas y hablas con tu crush, de vez en cuando revisas el número mostrado en el mostrador para ver si ya es tu turno.
-
+Luego, en algún momento, finalmente es tu turno. Vas al mostrador, obtienes tus hamburguesas y vuelves a la mesa.
-Tú y esa persona 😍 se comen las hamburguesas 🍔 y la pasan genial ✨.
+
-
+Tú y tu crush comen las hamburguesas y pasan un buen rato. ✨
-!!! info
- Las ilustraciones fueron creados por Ketrina Thompson. 🎨
+
+
+/// info | Información
+
+Hermosas ilustraciones de Ketrina Thompson. 🎨
+
+///
---
-Imagina que eres el sistema / programa 🤖 en esa historia.
+Imagina que eres la computadora / programa 🤖 en esa historia.
-Mientras estás en la cola, estás quieto 😴, esperando tu turno, sin hacer nada muy "productivo". Pero la línea va rápida porque el cajero 💁 solo recibe los pedidos (no los prepara), así que está bien.
+Mientras estás en la fila, estás inactivo 😴, esperando tu turno, sin hacer nada muy "productivo". Pero la fila es rápida porque el cajero solo está tomando los pedidos (no preparándolos), así que está bien.
-Luego, cuando llega tu turno, haces un trabajo "productivo" real 🤓, procesas el menú, decides lo que quieres, lo que quiere esa persona 😍, pagas 💸, verificas que das el billete o tarjeta correctos, verificas que te cobren correctamente, que el pedido tiene los artículos correctos, etc.
+Luego, cuando es tu turno, haces un trabajo realmente "productivo", procesas el menú, decides lo que quieres, obtienes la elección de tu crush, pagas, verificas que das el billete o tarjeta correctos, verificas que te cobren correctamente, verificas que el pedido tenga los artículos correctos, etc.
-Pero entonces, aunque aún no tienes tus hamburguesas 🍔, el trabajo hecho con el cajero 💁 está "en pausa" ⏸, porque debes esperar 🕙 a que tus hamburguesas estén listas.
+Pero luego, aunque todavía no tienes tus hamburguesas, tu trabajo con el cajero está "en pausa" ⏸, porque tienes que esperar 🕙 a que tus hamburguesas estén listas.
-Pero como te alejas del mostrador y te sientas en la mesa con un número para tu turno, puedes cambiar tu atención 🔀 a esa persona 😍 y "trabajar" ⏯ 🤓 en eso. Entonces nuevamente estás haciendo algo muy "productivo" 🤓, como coquetear con esa persona 😍.
+Pero como te alejas del mostrador y te sientas en la mesa con un número para tu turno, puedes cambiar 🔀 tu atención a tu crush, y "trabajar" ⏯ 🤓 en eso. Luego, nuevamente estás haciendo algo muy "productivo" como es coquetear con tu crush 😍.
-Después, el 💁 cajero dice "he terminado de hacer las hamburguesas" 🍔 poniendo tu número en la pantalla del mostrador, pero no saltas al momento que el número que se muestra es el tuyo. Sabes que nadie robará tus hamburguesas 🍔 porque tienes el número de tu turno y ellos tienen el suyo.
+Luego el cajero 💁 dice "he terminado de hacer las hamburguesas" al poner tu número en el mostrador, pero no saltas como loco inmediatamente cuando el número mostrado cambia a tu número de turno. Sabes que nadie robará tus hamburguesas porque tienes el número de tu turno, y ellos tienen el suyo.
-Así que esperas a que esa persona 😍 termine la historia (terminas el trabajo actual ⏯ / tarea actual que se está procesando 🤓), sonríes gentilmente y le dices que vas por las hamburguesas ⏸.
+Así que esperas a que tu crush termine la historia (termine el trabajo ⏯ / tarea actual que se está procesando 🤓), sonríes amablemente y dices que vas por las hamburguesas ⏸.
-Luego vas al mostrador 🔀, a la tarea inicial que ya está terminada ⏯, recoges las hamburguesas 🍔, les dices gracias y las llevas a la mesa. Eso termina esa fase / tarea de interacción con el mostrador ⏹. Eso a su vez, crea una nueva tarea, "comer hamburguesas" 🔀 ⏯, pero la anterior de "conseguir hamburguesas" está terminada ⏹.
+Luego vas al mostrador 🔀, a la tarea inicial que ahora está terminada ⏯, recoges las hamburguesas, das las gracias y las llevas a la mesa. Eso termina ese paso / tarea de interacción con el mostrador ⏹. Eso a su vez, crea una nueva tarea, de "comer hamburguesas" 🔀 ⏯, pero la anterior de "obtener hamburguesas" ha terminado ⏹.
### Hamburguesas Paralelas
-Ahora imagina que estas no son "Hamburguesas Concurrentes" sino "Hamburguesas Paralelas".
+Ahora imaginemos que estas no son "Hamburguesas Concurrentes", sino "Hamburguesas Paralelas".
-Vas con la persona que te gusta 😍 por comida rápida paralela 🍔.
+Vas con tu crush a obtener comida rápida paralela.
-Haces la cola mientras varios cajeros (digamos 8) que a la vez son cocineros 👨🍳👨🍳👨🍳👨🍳👨🍳👨🍳👨🍳👨🍳 toman los pedidos de las personas que están delante de ti.
+Te pones en fila mientras varios (digamos 8) cajeros que al mismo tiempo son cocineros toman los pedidos de las personas frente a ti.
-Todos los que están antes de ti están esperando 🕙 que sus hamburguesas 🍔 estén listas antes de dejar el mostrador porque cada uno de los 8 cajeros prepara la hamburguesa de inmediato antes de recibir el siguiente pedido.
+Todos antes que tú están esperando a que sus hamburguesas estén listas antes de dejar el mostrador porque cada uno de los 8 cajeros va y prepara la hamburguesa de inmediato antes de obtener el siguiente pedido.
-
+
-Entonces finalmente es tu turno, haces tu pedido de 2 hamburguesas 🍔 impresionantes para esa persona 😍 y para ti.
+Luego, finalmente es tu turno, haces tu pedido de 2 hamburguesas muy sofisticadas para tu crush y para ti.
Pagas 💸.
-
+
-El cajero va a la cocina 👨🍳.
+El cajero va a la cocina.
-Esperas, de pie frente al mostrador 🕙, para que nadie más recoja tus hamburguesas 🍔, ya que no hay números para los turnos.
+Esperas, de pie frente al mostrador 🕙, para que nadie más tome tus hamburguesas antes que tú, ya que no hay números para los turnos.
-
+
-Como tu y esa persona 😍 están ocupados en impedir que alguien se ponga delante y recoja tus hamburguesas apenas llegan 🕙, tampoco puedes prestarle atención a esa persona 😞.
+Como tú y tu crush están ocupados no dejando que nadie se interponga y tome tus hamburguesas cuando lleguen, no puedes prestar atención a tu crush. 😞
-Este es un trabajo "síncrono", estás "sincronizado" con el cajero / cocinero 👨🍳. Tienes que esperar y estar allí en el momento exacto en que el cajero / cocinero 👨🍳 termina las hamburguesas 🍔 y te las da, o de lo contrario, alguien más podría cogerlas.
+Este es un trabajo "sincrónico", estás "sincronizado" con el cajero/cocinero 👨🍳. Tienes que esperar 🕙 y estar allí en el momento exacto en que el cajero/cocinero 👨🍳 termine las hamburguesas y te las entregue, o de lo contrario, alguien más podría tomarlas.
-
+
-Luego, el cajero / cocinero 👨🍳 finalmente regresa con tus hamburguesas 🍔, después de mucho tiempo esperando 🕙 frente al mostrador.
+Luego tu cajero/cocinero 👨🍳 finalmente regresa con tus hamburguesas, después de mucho tiempo esperando 🕙 allí frente al mostrador.
-
+
-Coges tus hamburguesas 🍔 y vas a la mesa con esa persona 😍.
+Tomas tus hamburguesas y vas a la mesa con tu crush.
-Sólo las comes y listo 🍔 ⏹.
+Simplemente las comes, y has terminado. ⏹
-
+
-No has hablado ni coqueteado mucho, ya que has pasado la mayor parte del tiempo esperando 🕙 frente al mostrador 😞.
+No hubo mucho hablar o coquetear ya que la mayor parte del tiempo se dedicó a esperar 🕙 frente al mostrador. 😞
-!!! info
- Las ilustraciones fueron creados por Ketrina Thompson. 🎨
+/// info | Información
+
+Hermosas ilustraciones de Ketrina Thompson. 🎨
+
+///
---
-En este escenario de las hamburguesas paralelas, tú eres un sistema / programa 🤖 con dos procesadores (tú y la persona que te gusta 😍), ambos esperando 🕙 y dedicando su atención ⏯ a estar "esperando en el mostrador" 🕙 durante mucho tiempo.
+En este escenario de las hamburguesas paralelas, eres una computadora / programa 🤖 con dos procesadores (tú y tu crush), ambos esperando 🕙 y dedicando su atención ⏯ a estar "esperando en el mostrador" 🕙 por mucho tiempo.
-La tienda de comida rápida tiene 8 procesadores (cajeros / cocineros) 👨🍳👨🍳👨🍳👨🍳👨🍳👨🍳👨🍳👨🍳. Mientras que la tienda de hamburguesas concurrentes podría haber tenido solo 2 (un cajero y un cocinero) 💁 👨🍳.
+La tienda de comida rápida tiene 8 procesadores (cajeros/cocineros). Mientras que la tienda de hamburguesas concurrentes podría haber tenido solo 2 (un cajero y un cocinero).
-Pero aún así, la experiencia final no es la mejor 😞.
+Pero aún así, la experiencia final no es la mejor. 😞
---
-Esta sería la historia paralela equivalente de las hamburguesas 🍔.
+Esta sería la historia equivalente de las hamburguesas paralelas. 🍔
-Para un ejemplo más "real" de ésto, imagina un banco.
+Para un ejemplo más "de la vida real" de esto, imagina un banco.
-Hasta hace poco, la mayoría de los bancos tenían varios cajeros 👨💼👨💼👨💼👨💼 y una gran línea 🕙🕙🕙🕙🕙🕙🕙🕙.
+Hasta hace poco, la mayoría de los bancos tenían múltiples cajeros 👨💼👨💼👨💼👨💼 y una gran fila 🕙🕙🕙🕙🕙🕙🕙🕙.
Todos los cajeros haciendo todo el trabajo con un cliente tras otro 👨💼⏯.
-Y tienes que esperar 🕙 en la fila durante mucho tiempo o perderás tu turno.
+Y tienes que esperar 🕙 en la fila por mucho tiempo o pierdes tu turno.
-Probablemente no querrás llevar contigo a la persona que te gusta 😍 a hacer encargos al banco 🏦.
+Probablemente no querrías llevar a tu crush 😍 contigo a hacer trámites en el banco 🏦.
-### Conclusión de las Hamburguesa
+### Conclusión de las Hamburguesas
-En este escenario de "hamburguesas de comida rápida con tu pareja", debido a que hay mucha espera 🕙, tiene mucho más sentido tener un sistema con concurrencia ⏸🔀⏯.
+En este escenario de "hamburguesas de comida rápida con tu crush", como hay mucha espera 🕙, tiene mucho más sentido tener un sistema concurrente ⏸🔀⏯.
-Este es el caso de la mayoría de las aplicaciones web.
+Este es el caso para la mayoría de las aplicaciones web.
-Muchos, muchos usuarios, pero el servidor está esperando 🕙 el envío de las peticiones ya que su conexión no es buena.
+Muchos, muchos usuarios, pero tu servidor está esperando 🕙 su conexión no tan buena para enviar sus requests.
-Y luego esperando 🕙 nuevamente a que las respuestas retornen.
+Y luego esperar 🕙 nuevamente a que los responses retornen.
-Esta "espera" 🕙 se mide en microsegundos, pero aun así, sumando todo, al final es mucha espera.
+Esta "espera" 🕙 se mide en microsegundos, pero aún así, sumándolo todo, es mucha espera al final.
-Es por eso que tiene mucho sentido usar código asíncrono ⏸🔀⏯ para las API web.
+Por eso tiene mucho sentido usar código asíncrono ⏸🔀⏯ para las APIs web.
-La mayoría de los framework populares de Python existentes (incluidos Flask y Django) se crearon antes de que existieran las nuevas funciones asíncronas en Python. Por lo tanto, las formas en que pueden implementarse admiten la ejecución paralela y una forma más antigua de ejecución asíncrona que no es tan potente como la actual.
-
-A pesar de que la especificación principal para Python web asíncrono (ASGI) se desarrolló en Django, para agregar soporte para WebSockets.
-
-Ese tipo de asincronía es lo que hizo popular a NodeJS (aunque NodeJS no es paralelo) y esa es la fortaleza de Go como lenguaje de programación.
+Este tipo de asincronía es lo que hizo popular a NodeJS (aunque NodeJS no es paralelo) y esa es la fortaleza de Go como lenguaje de programación.
Y ese es el mismo nivel de rendimiento que obtienes con **FastAPI**.
-Y como puede tener paralelismo y asincronía al mismo tiempo, obtienes un mayor rendimiento que la mayoría de los frameworks de NodeJS probados y a la par con Go, que es un lenguaje compilado más cercano a C (todo gracias Starlette).
+Y como puedes tener paralelismo y asincronía al mismo tiempo, obtienes un mayor rendimiento que la mayoría de los frameworks de NodeJS probados y a la par con Go, que es un lenguaje compilado más cercano a C (todo gracias a Starlette).
### ¿Es la concurrencia mejor que el paralelismo?
¡No! Esa no es la moraleja de la historia.
-La concurrencia es diferente al paralelismo. Y es mejor en escenarios **específicos** que implican mucha espera. Debido a eso, generalmente es mucho mejor que el paralelismo para el desarrollo de aplicaciones web. Pero no para todo.
+La concurrencia es diferente del paralelismo. Y es mejor en escenarios **específicos** que implican mucha espera. Debido a eso, generalmente es mucho mejor que el paralelismo para el desarrollo de aplicaciones web. Pero no para todo.
-Entonces, para explicar eso, imagina la siguiente historia corta:
+Así que, para equilibrar eso, imagina la siguiente historia corta:
> Tienes que limpiar una casa grande y sucia.
@@ -261,80 +267,80 @@ Entonces, para explicar eso, imagina la siguiente historia corta:
---
-No hay esperas 🕙, solo hay mucho trabajo por hacer, en varios lugares de la casa.
+No hay esperas 🕙 en ninguna parte, solo mucho trabajo por hacer, en múltiples lugares de la casa.
-Podrías tener turnos como en el ejemplo de las hamburguesas, primero la sala de estar, luego la cocina, pero como no estás esperando nada, solo limpiando y limpiando, los turnos no afectarían nada.
+Podrías tener turnos como en el ejemplo de las hamburguesas, primero la sala de estar, luego la cocina, pero como no estás esperando 🕙 nada, solo limpiando y limpiando, los turnos no afectarían nada.
Tomaría la misma cantidad de tiempo terminar con o sin turnos (concurrencia) y habrías hecho la misma cantidad de trabajo.
-Pero en este caso, si pudieras traer a los 8 ex cajeros / cocineros / ahora limpiadores 👨🍳👨🍳👨🍳👨🍳👨🍳👨🍳👨🍳👨🍳, y cada uno de ellos (y tú) podría tomar una zona de la casa para limpiarla, podría hacer todo el trabajo en **paralelo**, con la ayuda adicional y terminar mucho antes.
+Pero en este caso, si pudieras traer a los 8 ex-cajeros/cocineros/ahora-limpiadores, y cada uno de ellos (más tú) pudiera tomar una zona de la casa para limpiarla, podrías hacer todo el trabajo en **paralelo**, con la ayuda extra, y terminar mucho antes.
-En este escenario, cada uno de los limpiadores (incluido tú) sería un procesador, haciendo su parte del trabajo.
+En este escenario, cada uno de los limpiadores (incluyéndote) sería un procesador, haciendo su parte del trabajo.
-Y como la mayor parte del tiempo de ejecución lo coge el trabajo real (en lugar de esperar), y el trabajo en un sistema lo realiza una CPU , a estos problemas se les llama "CPU bound".
+Y como la mayor parte del tiempo de ejecución se dedica al trabajo real (en lugar de esperar), y el trabajo en una computadora lo realiza una CPU, llaman a estos problemas "CPU bound".
---
-Ejemplos típicos de operaciones dependientes de CPU son cosas que requieren un procesamiento matemático complejo.
+Ejemplos comunes de operaciones limitadas por la CPU son cosas que requieren procesamiento matemático complejo.
Por ejemplo:
-* **Audio** o **procesamiento de imágenes**.
-* **Visión por computadora**: una imagen está compuesta de millones de píxeles, cada píxel tiene 3 valores / colores, procesamiento que normalmente requiere calcular algo en esos píxeles, todo al mismo tiempo.
-* **Machine Learning**: normalmente requiere muchas multiplicaciones de "matrices" y "vectores". Imagina en una enorme hoja de cálculo con números y tener que multiplicarlos todos al mismo tiempo.
-* **Deep Learning**: este es un subcampo de Machine Learning, por lo tanto, aplica lo mismo. Es solo que no hay una sola hoja de cálculo de números para multiplicar, sino un gran conjunto de ellas, y en muchos casos, usa un procesador especial para construir y / o usar esos modelos.
+* **Procesamiento de audio** o **imágenes**.
+* **Visión por computadora**: una imagen está compuesta de millones de píxeles, cada píxel tiene 3 valores / colores, procesar eso normalmente requiere calcular algo en esos píxeles, todos al mismo tiempo.
+* **Machine Learning**: normalmente requiere muchas multiplicaciones de "matrices" y "vectores". Piensa en una enorme hoja de cálculo con números y multiplicando todos juntos al mismo tiempo.
+* **Deep Learning**: este es un subcampo de Machine Learning, por lo tanto, se aplica lo mismo. Es solo que no hay una sola hoja de cálculo de números para multiplicar, sino un enorme conjunto de ellas, y en muchos casos, usas un procesador especial para construir y / o usar esos modelos.
### Concurrencia + Paralelismo: Web + Machine Learning
-Con **FastAPI** puedes aprovechar la concurrencia que es muy común para el desarrollo web (atractivo principal de NodeJS).
+Con **FastAPI** puedes aprovechar la concurrencia que es muy común para el desarrollo web (la misma atracción principal de NodeJS).
-Pero también puedes aprovechar los beneficios del paralelismo y el multiprocesamiento (tener múltiples procesos ejecutándose en paralelo) para cargas de trabajo **CPU bound** como las de los sistemas de Machine Learning.
+Pero también puedes explotar los beneficios del paralelismo y la multiprocesamiento (tener múltiples procesos ejecutándose en paralelo) para cargas de trabajo **CPU bound** como las de los sistemas de Machine Learning.
-Eso, más el simple hecho de que Python es el lenguaje principal para **Data Science**, Machine Learning y especialmente Deep Learning, hacen de FastAPI una muy buena combinación para las API y aplicaciones web de Data Science / Machine Learning (entre muchas otras).
+Eso, más el simple hecho de que Python es el lenguaje principal para **Data Science**, Machine Learning y especialmente Deep Learning, hacen de FastAPI una muy buena opción para APIs web de Data Science / Machine Learning y aplicaciones (entre muchas otras).
-Para ver cómo lograr este paralelismo en producción, consulta la sección sobre [Despliegue](deployment/index.md){.internal-link target=_blank}.
+Para ver cómo lograr este paralelismo en producción, consulta la sección sobre [Deployment](deployment/index.md){.internal-link target=_blank}.
## `async` y `await`
-Las versiones modernas de Python tienen una forma muy intuitiva de definir código asíncrono. Esto hace que se vea como un código "secuencial" normal y que haga la "espera" por ti en los momentos correctos.
+Las versiones modernas de Python tienen una forma muy intuitiva de definir código asíncrono. Esto hace que se vea igual que el código "secuencial" normal y hace el "wait" por ti en los momentos adecuados.
-Cuando hay una operación que requerirá esperar antes de dar los resultados y tiene soporte para estas nuevas características de Python, puedes programarlo como:
+Cuando hay una operación que requerirá esperar antes de dar los resultados y tiene soporte para estas nuevas funcionalidades de Python, puedes programarlo así:
```Python
burgers = await get_burgers(2)
```
-La clave aquí es `await`. Eso le dice a Python que tiene que esperar ⏸ a que `get_burgers (2)` termine de hacer lo suyo 🕙 antes de almacenar los resultados en `hamburguesas`. Con eso, Python sabrá que puede ir y hacer otra cosa 🔀 ⏯ mientras tanto (como recibir otra solicitud).
+La clave aquí es el `await`. Dice a Python que tiene que esperar ⏸ a que `get_burgers(2)` termine de hacer su cosa 🕙 antes de almacenar los resultados en `burgers`. Con eso, Python sabrá que puede ir y hacer algo más 🔀 ⏯ mientras tanto (como recibir otro request).
-Para que `await` funcione, tiene que estar dentro de una función que admita esta asincronía. Para hacer eso, simplemente lo declaras con `async def`:
+Para que `await` funcione, tiene que estar dentro de una función que soporte esta asincronía. Para hacer eso, solo declara la función con `async def`:
```Python hl_lines="1"
async def get_burgers(number: int):
- # Do some asynchronous stuff to create the burgers
+ # Hacer algunas cosas asíncronas para crear las hamburguesas
return burgers
```
-...en vez de `def`:
+...en lugar de `def`:
```Python hl_lines="2"
-# This is not asynchronous
+# Esto no es asíncrono
def get_sequential_burgers(number: int):
- # Do some sequential stuff to create the burgers
+ # Hacer algunas cosas secuenciales para crear las hamburguesas
return burgers
```
-Con `async def`, Python sabe que, dentro de esa función, debe tener en cuenta las expresiones `wait` y que puede "pausar" ⏸ la ejecución de esa función e ir a hacer otra cosa 🔀 antes de regresar.
+Con `async def`, Python sabe que, dentro de esa función, tiene que estar atento a las expresiones `await`, y que puede "pausar" ⏸ la ejecución de esa función e ir a hacer algo más 🔀 antes de regresar.
-Cuando desees llamar a una función `async def`, debes "esperarla". Entonces, esto no funcionará:
+Cuando deseas llamar a una función `async def`, tienes que "await" dicha función. Así que, esto no funcionará:
```Python
-# Esto no funcionará, porque get_burgers se definió con: async def
-hamburguesas = get_burgers (2)
+# Esto no funcionará, porque get_burgers fue definido con: async def
+burgers = get_burgers(2)
```
---
-Por lo tanto, si estás utilizando una library que te dice que puedes llamarla con `await`, debes crear las *path operation functions* que la usan con `async def`, como en:
+Así que, si estás usando un paquete que te dice que puedes llamarlo con `await`, necesitas crear las *path operation functions* que lo usen con `async def`, como en:
```Python hl_lines="2-3"
@app.get('/burgers')
@@ -345,15 +351,25 @@ async def read_burgers():
### Más detalles técnicos
-Es posible que hayas notado que `await` solo se puede usar dentro de las funciones definidas con `async def`.
+Podrías haber notado que `await` solo se puede usar dentro de funciones definidas con `async def`.
-Pero al mismo tiempo, las funciones definidas con `async def` deben ser "esperadas". Por lo tanto, las funciones con `async def` solo se pueden invocar dentro de las funciones definidas con `async def` también.
+Pero al mismo tiempo, las funciones definidas con `async def` deben ser "awaited". Por lo tanto, las funciones con `async def` solo se pueden llamar dentro de funciones definidas con `async def` también.
-Entonces, relacionado con la paradoja del huevo y la gallina, ¿cómo se llama a la primera función `async`?
+Entonces, sobre el huevo y la gallina, ¿cómo llamas a la primera función `async`?
-Si estás trabajando con **FastAPI** no tienes que preocuparte por eso, porque esa "primera" función será tu *path operation function*, y FastAPI sabrá cómo hacer lo pertinente.
+Si estás trabajando con **FastAPI** no tienes que preocuparte por eso, porque esa "primera" función será tu *path operation function*, y FastAPI sabrá cómo hacer lo correcto.
-En el caso de que desees usar `async` / `await` sin FastAPI, revisa la documentación oficial de Python.
+Pero si deseas usar `async` / `await` sin FastAPI, también puedes hacerlo.
+
+### Escribe tu propio código async
+
+Starlette (y **FastAPI**) están basados en AnyIO, lo que lo hace compatible tanto con la librería estándar de Python asyncio como con Trio.
+
+En particular, puedes usar directamente AnyIO para tus casos de uso avanzados de concurrencia que requieran patrones más avanzados en tu propio código.
+
+E incluso si no estuvieras usando FastAPI, también podrías escribir tus propias aplicaciones asíncronas con AnyIO para ser altamente compatibles y obtener sus beneficios (p.ej. *concurrencia estructurada*).
+
+Creé otro paquete sobre AnyIO, como una capa delgada, para mejorar un poco las anotaciones de tipos y obtener mejor **autocompletado**, **errores en línea**, etc. También tiene una introducción amigable y tutorial para ayudarte a **entender** y escribir **tu propio código async**: Asyncer. Sería particularmente útil si necesitas **combinar código async con regular** (bloqueante/sincrónico).
### Otras formas de código asíncrono
@@ -361,65 +377,68 @@ Este estilo de usar `async` y `await` es relativamente nuevo en el lenguaje.
Pero hace que trabajar con código asíncrono sea mucho más fácil.
-Esta misma sintaxis (o casi idéntica) también se incluyó recientemente en las versiones modernas de JavaScript (en Browser y NodeJS).
+Esta misma sintaxis (o casi idéntica) también se incluyó recientemente en las versiones modernas de JavaScript (en el Navegador y NodeJS).
-Pero antes de eso, manejar código asíncrono era bastante más complejo y difícil.
+Pero antes de eso, manejar el código asíncrono era mucho más complejo y difícil.
-En versiones anteriores de Python, podrías haber utilizado threads o Gevent. Pero el código es mucho más complejo de entender, depurar y desarrollar.
+En versiones previas de Python, podrías haber usado hilos o Gevent. Pero el código es mucho más complejo de entender, depurar y razonar.
-En versiones anteriores de NodeJS / Browser JavaScript, habrías utilizado "callbacks". Lo que conduce a callback hell.
+En versiones previas de NodeJS / JavaScript en el Navegador, habrías usado "callbacks". Lo que lleva al callback hell.
## Coroutines
-**Coroutine** es un término sofisticado para referirse a la cosa devuelta por una función `async def`. Python sabe que es algo así como una función que puede iniciar y que terminará en algún momento, pero que también podría pausarse ⏸ internamente, siempre que haya un `await` dentro de ella.
+**Coroutines** es simplemente el término muy elegante para la cosa que devuelve una función `async def`. Python sabe que es algo parecido a una función, que puede comenzar y que terminará en algún momento, pero que podría pausar ⏸ internamente también, siempre que haya un `await` dentro de él.
-Pero toda esta funcionalidad de usar código asincrónico con `async` y `await` se resume muchas veces como usar "coroutines". Es comparable a la característica principal de Go, las "Goroutines".
+Pero toda esta funcionalidad de usar código asíncrono con `async` y `await` a menudo se resume como utilizar "coroutines". Es comparable a la funcionalidad clave principal de Go, las "Goroutines".
## Conclusión
Veamos la misma frase de arriba:
-> Las versiones modernas de Python tienen soporte para **"código asíncrono"** usando algo llamado **"coroutines"**, con la sintaxis **`async` y `await`**.
+> Las versiones modernas de Python tienen soporte para **"código asíncrono"** utilizando algo llamado **"coroutines"**, con la sintaxis **`async` y `await`**.
-Eso ya debería tener más sentido ahora. ✨
+Eso debería tener más sentido ahora. ✨
Todo eso es lo que impulsa FastAPI (a través de Starlette) y lo que hace que tenga un rendimiento tan impresionante.
-## Detalles muy técnicos
+## Detalles Muy Técnicos
-!!! warning "Advertencia"
- Probablemente puedas saltarte esto.
+/// warning | Advertencia
- Estos son detalles muy técnicos de cómo **FastAPI** funciona a muy bajo nivel.
+Probablemente puedas saltarte esto.
- Si tienes bastante conocimiento técnico (coroutines, threads, bloqueos, etc.) y tienes curiosidad acerca de cómo FastAPI gestiona `async def` vs `def` normal, continúa.
+Estos son detalles muy técnicos de cómo funciona **FastAPI** en su interior.
-### Path operation functions
+Si tienes bastante conocimiento técnico (coroutines, hilos, bloqueo, etc.) y tienes curiosidad sobre cómo FastAPI maneja `async def` vs `def` normal, adelante.
-Cuando declaras una *path operation function* con `def` normal en lugar de `async def`, se ejecuta en un threadpool externo que luego es "awaited", en lugar de ser llamado directamente (ya que bloquearía el servidor).
+///
-Si vienes de otro framework asíncrono que no funciona de la manera descrita anteriormente y estás acostumbrado a definir *path operation functions* del tipo sólo cálculo con `def` simple para una pequeña ganancia de rendimiento (aproximadamente 100 nanosegundos), ten en cuenta que en **FastAPI** el efecto sería bastante opuesto. En estos casos, es mejor usar `async def` a menos que tus *path operation functions* usen un código que realice el bloqueo I/O.
+### Funciones de *path operation*
-Aún así, en ambas situaciones, es probable que **FastAPI** sea [aún más rápido](index.md#rendimiento){.Internal-link target=_blank} que (o al menos comparable) a tu framework anterior.
+Cuando declaras una *path operation function* con `def` normal en lugar de `async def`, se ejecuta en un threadpool externo que luego es esperado, en lugar de ser llamado directamente (ya que bloquearía el servidor).
+
+Si vienes de otro framework async que no funciona de la manera descrita anteriormente y estás acostumbrado a definir funciones de *path operation* solo de cómputo trivial con `def` normal para una pequeña ganancia de rendimiento (alrededor de 100 nanosegundos), ten en cuenta que en **FastAPI** el efecto sería bastante opuesto. En estos casos, es mejor usar `async def` a menos que tus *path operation functions* usen código que realice I/O de bloqueo.
+
+Aun así, en ambas situaciones, es probable que **FastAPI** [siga siendo más rápida](index.md#performance){.internal-link target=_blank} que (o al menos comparable a) tu framework anterior.
### Dependencias
-Lo mismo se aplica para las dependencias. Si una dependencia es una función estándar `def` en lugar de `async def`, se ejecuta en el threadpool externo.
+Lo mismo aplica para las [dependencias](tutorial/dependencies/index.md){.internal-link target=_blank}. Si una dependencia es una función estándar `def` en lugar de `async def`, se ejecuta en el threadpool externo.
-### Subdependencias
+### Sub-dependencias
-Puedes tener múltiples dependencias y subdependencias que se requieren unas a otras (como parámetros de las definiciones de cada función), algunas de ellas pueden crearse con `async def` y otras con `def` normal. Igual todo seguiría funcionando correctamente, y las creadas con `def` normal se llamarían en un thread externo (del threadpool) en lugar de ser "awaited".
+Puedes tener múltiples dependencias y [sub-dependencias](tutorial/dependencies/sub-dependencies.md){.internal-link target=_blank} requiriéndose mutuamente (como parámetros de las definiciones de funciones), algunas de ellas podrían ser creadas con `async def` y algunas con `def` normal. Aun funcionará, y las que fueron creadas con `def` normal serían llamadas en un hilo externo (del threadpool) en lugar de ser "awaited".
-### Otras funciones de utilidades
+### Otras funciones de utilidad
-Cualquier otra función de utilidad que llames directamente se puede crear con `def` o `async def` normales y FastAPI no afectará la manera en que la llames.
+Cualquier otra función de utilidad que llames directamente puede ser creada con `def` normal o `async def` y FastAPI no afectará la forma en que la llames.
-Esto contrasta con las funciones que FastAPI llama por ti: las *path operation functions* y dependencias.
+Esto contrasta con las funciones que FastAPI llama por ti: *path operation functions* y dependencias.
-Si tu función de utilidad es creada con `def` normal, se llamará directamente (tal cual la escribes en tu código), no en un threadpool, si la función se crea con `async def`, entonces debes usar `await` con esa función cuando la llamas en tu código.
+Si tu función de utilidad es una función normal con `def`, será llamada directamente (como la escribas en tu código), no en un threadpool; si la función es creada con `async def` entonces deberías "await" por esa función cuando la llames en tu código.
---
-Nuevamente, estos son detalles muy técnicos que probablemente sólo son útiles si los viniste a buscar expresamente.
+Nuevamente, estos son detalles muy técnicos que probablemente serían útiles si los buscaste.
-De lo contrario, la guía de la sección anterior debería ser suficiente: ¿Tienes prisa?.
+De lo contrario, deberías estar bien con las pautas de la sección anterior: ¿Con prisa?.
diff --git a/docs/es/docs/benchmarks.md b/docs/es/docs/benchmarks.md
index 3e02d4e9f..49d65b6ba 100644
--- a/docs/es/docs/benchmarks.md
+++ b/docs/es/docs/benchmarks.md
@@ -1,33 +1,34 @@
# Benchmarks
-Los benchmarks independientes de TechEmpower muestran aplicaciones de **FastAPI** que se ejecutan en Uvicorn como uno de los frameworks de Python más rápidos disponibles, solo por debajo de Starlette y Uvicorn (utilizados internamente por FastAPI). (*)
+Los benchmarks independientes de TechEmpower muestran aplicaciones de **FastAPI** ejecutándose bajo Uvicorn como uno de los frameworks de Python más rápidos disponibles, solo por debajo de Starlette y Uvicorn en sí mismos (utilizados internamente por FastAPI).
-Pero al comprobar benchmarks y comparaciones debes tener en cuenta lo siguiente.
+Pero al revisar benchmarks y comparaciones, debes tener en cuenta lo siguiente.
## Benchmarks y velocidad
-Cuando revisas los benchmarks, es común ver varias herramientas de diferentes tipos comparadas como equivalentes.
+Cuando ves los benchmarks, es común ver varias herramientas de diferentes tipos comparadas como equivalentes.
-Específicamente, para ver Uvicorn, Starlette y FastAPI comparadas entre sí (entre muchas otras herramientas).
+Específicamente, ver Uvicorn, Starlette y FastAPI comparados juntos (entre muchas otras herramientas).
-Cuanto más sencillo sea el problema resuelto por la herramienta, mejor rendimiento obtendrá. Y la mayoría de los benchmarks no prueban las funciones adicionales proporcionadas por la herramienta.
+Cuanto más simple sea el problema resuelto por la herramienta, mejor rendimiento tendrá. Y la mayoría de los benchmarks no prueban las funcionalidades adicionales proporcionadas por la herramienta.
-La jerarquía sería:
+La jerarquía es como:
-* **Uvicorn**: como servidor ASGI
+* **Uvicorn**: un servidor ASGI
* **Starlette**: (usa Uvicorn) un microframework web
- * **FastAPI**: (usa Starlette) un microframework API con varias características adicionales para construir APIs, con validación de datos, etc.
+ * **FastAPI**: (usa Starlette) un microframework para APIs con varias funcionalidades adicionales para construir APIs, con validación de datos, etc.
+
* **Uvicorn**:
* Tendrá el mejor rendimiento, ya que no tiene mucho código extra aparte del propio servidor.
- * No escribirías una aplicación directamente en Uvicorn. Eso significaría que tu código tendría que incluir más o menos, al menos, todo el código proporcionado por Starlette (o **FastAPI**). Y si hicieras eso, tu aplicación final tendría la misma sobrecarga que si hubieras usado un framework y minimizado el código de tu aplicación y los errores.
- * Si estás comparando Uvicorn, compáralo con los servidores de aplicaciones Daphne, Hypercorn, uWSGI, etc.
+ * No escribirías una aplicación directamente en Uvicorn. Eso significaría que tu código tendría que incluir, más o menos, al menos, todo el código proporcionado por Starlette (o **FastAPI**). Y si hicieras eso, tu aplicación final tendría la misma carga que si hubieras usado un framework, minimizando el código de tu aplicación y los bugs.
+ * Si estás comparando Uvicorn, compáralo con Daphne, Hypercorn, uWSGI, etc. Servidores de aplicaciones.
* **Starlette**:
- * Tendrá el siguiente mejor desempeño, después de Uvicorn. De hecho, Starlette usa Uvicorn para correr. Por lo tanto, probablemente sólo pueda volverse "más lento" que Uvicorn al tener que ejecutar más código.
- * Pero te proporciona las herramientas para crear aplicaciones web simples, con routing basado en paths, etc.
+ * Tendrá el siguiente mejor rendimiento, después de Uvicorn. De hecho, Starlette usa Uvicorn para ejecutarse. Así que probablemente solo pueda ser "más lento" que Uvicorn por tener que ejecutar más código.
+ * Pero te proporciona las herramientas para construir aplicaciones web sencillas, con enrutamiento basado en paths, etc.
* Si estás comparando Starlette, compáralo con Sanic, Flask, Django, etc. Frameworks web (o microframeworks).
* **FastAPI**:
- * De la misma manera que Starlette usa Uvicorn y no puede ser más rápido que él, **FastAPI** usa Starlette, por lo que no puede ser más rápido que él.
- * * FastAPI ofrece más características además de las de Starlette. Funciones que casi siempre necesitas al crear una API, como validación y serialización de datos. Y al usarlo, obtienes documentación automática de forma gratuita (la documentación automática ni siquiera agrega gastos generales a las aplicaciones en ejecución, se genera al iniciar).
- * Si no usaras FastAPI y usaras Starlette directamente (u otra herramienta, como Sanic, Flask, Responder, etc.), tendrías que implementar toda la validación y serialización de datos tu mismo. Por lo tanto, tu aplicación final seguirá teniendo la misma sobrecarga que si se hubiera creado con FastAPI. Y en muchos casos, esta validación y serialización de datos constituye la mayor cantidad de código escrito en las aplicaciones.
- * Entonces, al usar FastAPI estás ahorrando tiempo de desarrollo, errores, líneas de código y probablemente obtendrías el mismo rendimiento (o mejor) que obtendrías si no lo usaras (ya que tendrías que implementarlo todo en tu código).
- * Si estás comparando FastAPI, compáralo con un framework de aplicaciones web (o conjunto de herramientas) que proporciona validación, serialización y documentación de datos, como Flask-apispec, NestJS, Molten, etc. Frameworks con validación, serialización y documentación automáticas integradas.
+ * De la misma forma en que Starlette usa Uvicorn y no puede ser más rápido que él, **FastAPI** usa Starlette, por lo que no puede ser más rápido que él.
+ * FastAPI ofrece más funcionalidades además de las de Starlette. Funcionalidades que casi siempre necesitas al construir APIs, como la validación y serialización de datos. Y al utilizarlo, obtienes documentación automática gratis (la documentación automática ni siquiera añade carga a las aplicaciones en ejecución, se genera al inicio).
+ * Si no usabas FastAPI y utilizabas Starlette directamente (u otra herramienta, como Sanic, Flask, Responder, etc.) tendrías que implementar toda la validación y serialización de datos por ti mismo. Entonces, tu aplicación final aún tendría la misma carga que si hubiera sido construida usando FastAPI. Y en muchos casos, esta validación y serialización de datos es la mayor cantidad de código escrito en las aplicaciones.
+ * Entonces, al usar FastAPI estás ahorrando tiempo de desarrollo, bugs, líneas de código, y probablemente obtendrías el mismo rendimiento (o mejor) que si no lo usaras (ya que tendrías que implementarlo todo en tu código).
+ * Si estás comparando FastAPI, compáralo con un framework de aplicación web (o conjunto de herramientas) que proporcione validación de datos, serialización y documentación, como Flask-apispec, NestJS, Molten, etc. Frameworks con validación de datos, serialización y documentación automáticas integradas.
diff --git a/docs/es/docs/deployment/cloud.md b/docs/es/docs/deployment/cloud.md
new file mode 100644
index 000000000..fe47d5dcf
--- /dev/null
+++ b/docs/es/docs/deployment/cloud.md
@@ -0,0 +1,18 @@
+# Despliega FastAPI en Proveedores de Nube
+
+Puedes usar prácticamente **cualquier proveedor de nube** para desplegar tu aplicación FastAPI.
+
+En la mayoría de los casos, los principales proveedores de nube tienen guías para desplegar FastAPI con ellos.
+
+## Proveedores de Nube - Sponsors
+
+Algunos proveedores de nube ✨ [**son sponsors de FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨, esto asegura el desarrollo **continuado** y **saludable** de FastAPI y su **ecosistema**.
+
+Y muestra su verdadero compromiso con FastAPI y su **comunidad** (tú), ya que no solo quieren proporcionarte un **buen servicio**, sino también asegurarse de que tengas un **framework bueno y saludable**, FastAPI. 🙇
+
+Podrías querer probar sus servicios y seguir sus guías:
+
+* Platform.sh
+* Porter
+* Coherence
+* Render
diff --git a/docs/es/docs/deployment/concepts.md b/docs/es/docs/deployment/concepts.md
new file mode 100644
index 000000000..bcc7948bc
--- /dev/null
+++ b/docs/es/docs/deployment/concepts.md
@@ -0,0 +1,321 @@
+# Conceptos de Implementación
+
+Cuando implementas una aplicación **FastAPI**, o en realidad, cualquier tipo de API web, hay varios conceptos que probablemente te importen, y al entenderlos, puedes encontrar la **forma más adecuada** de **implementar tu aplicación**.
+
+Algunos de los conceptos importantes son:
+
+* Seguridad - HTTPS
+* Ejecución al iniciar
+* Reinicios
+* Replicación (la cantidad de procesos en ejecución)
+* Memoria
+* Pasos previos antes de iniciar
+
+Veremos cómo afectan estas **implementaciones**.
+
+Al final, el objetivo principal es poder **servir a tus clientes de API** de una manera que sea **segura**, para **evitar interrupciones**, y usar los **recursos de cómputo** (por ejemplo, servidores remotos/máquinas virtuales) de la manera más eficiente posible. 🚀
+
+Te contaré un poquito más sobre estos **conceptos** aquí, y eso, con suerte, te dará la **intuición** que necesitarías para decidir cómo implementar tu API en diferentes entornos, posiblemente incluso en aquellos **futuros** que aún no existen.
+
+Al considerar estos conceptos, podrás **evaluar y diseñar** la mejor manera de implementar **tus propias APIs**.
+
+En los próximos capítulos, te daré más **recetas concretas** para implementar aplicaciones de FastAPI.
+
+Pero por ahora, revisemos estas importantes **ideas conceptuales**. Estos conceptos también se aplican a cualquier otro tipo de API web. 💡
+
+## Seguridad - HTTPS
+
+En el [capítulo anterior sobre HTTPS](https.md){.internal-link target=_blank} aprendimos sobre cómo HTTPS proporciona cifrado para tu API.
+
+También vimos que HTTPS es normalmente proporcionado por un componente **externo** a tu servidor de aplicaciones, un **Proxy de Terminación TLS**.
+
+Y debe haber algo encargado de **renovar los certificados HTTPS**, podría ser el mismo componente o algo diferente.
+
+### Herramientas de Ejemplo para HTTPS
+
+Algunas de las herramientas que podrías usar como Proxy de Terminación TLS son:
+
+* Traefik
+ * Maneja automáticamente las renovaciones de certificados ✨
+* Caddy
+ * Maneja automáticamente las renovaciones de certificados ✨
+* Nginx
+ * Con un componente externo como Certbot para las renovaciones de certificados
+* HAProxy
+ * Con un componente externo como Certbot para las renovaciones de certificados
+* Kubernetes con un Controlador de Ingress como Nginx
+ * Con un componente externo como cert-manager para las renovaciones de certificados
+* Manejado internamente por un proveedor de nube como parte de sus servicios (lee abajo 👇)
+
+Otra opción es que podrías usar un **servicio de nube** que haga más del trabajo, incluyendo configurar HTTPS. Podría tener algunas restricciones o cobrarte más, etc. Pero en ese caso, no tendrías que configurar un Proxy de Terminación TLS tú mismo.
+
+Te mostraré algunos ejemplos concretos en los próximos capítulos.
+
+---
+
+Luego, los siguientes conceptos a considerar son todos acerca del programa que ejecuta tu API real (por ejemplo, Uvicorn).
+
+## Programa y Proceso
+
+Hablaremos mucho sobre el "**proceso**" en ejecución, así que es útil tener claridad sobre lo que significa y cuál es la diferencia con la palabra "**programa**".
+
+### Qué es un Programa
+
+La palabra **programa** se usa comúnmente para describir muchas cosas:
+
+* El **código** que escribes, los **archivos Python**.
+* El **archivo** que puede ser **ejecutado** por el sistema operativo, por ejemplo: `python`, `python.exe` o `uvicorn`.
+* Un programa específico mientras está siendo **ejecutado** en el sistema operativo, usando la CPU y almacenando cosas en la memoria. Esto también se llama **proceso**.
+
+### Qué es un Proceso
+
+La palabra **proceso** se usa normalmente de una manera más específica, refiriéndose solo a lo que está ejecutándose en el sistema operativo (como en el último punto anterior):
+
+* Un programa específico mientras está siendo **ejecutado** en el sistema operativo.
+ * Esto no se refiere al archivo, ni al código, se refiere **específicamente** a lo que está siendo **ejecutado** y gestionado por el sistema operativo.
+* Cualquier programa, cualquier código, **solo puede hacer cosas** cuando está siendo **ejecutado**. Así que, cuando hay un **proceso en ejecución**.
+* El proceso puede ser **terminado** (o "matado") por ti, o por el sistema operativo. En ese punto, deja de ejecutarse/ser ejecutado, y ya no puede **hacer cosas**.
+* Cada aplicación que tienes en ejecución en tu computadora tiene algún proceso detrás, cada programa en ejecución, cada ventana, etc. Y normalmente hay muchos procesos ejecutándose **al mismo tiempo** mientras una computadora está encendida.
+* Puede haber **múltiples procesos** del **mismo programa** ejecutándose al mismo tiempo.
+
+Si revisas el "administrador de tareas" o "monitor del sistema" (o herramientas similares) en tu sistema operativo, podrás ver muchos de esos procesos en ejecución.
+
+Y, por ejemplo, probablemente verás que hay múltiples procesos ejecutando el mismo programa del navegador (Firefox, Chrome, Edge, etc.). Normalmente ejecutan un proceso por pestaña, además de algunos otros procesos extra.
+
+
+
+---
+
+Ahora que conocemos la diferencia entre los términos **proceso** y **programa**, sigamos hablando sobre implementaciones.
+
+## Ejecución al Iniciar
+
+En la mayoría de los casos, cuando creas una API web, quieres que esté **siempre en ejecución**, ininterrumpida, para que tus clientes puedan acceder a ella en cualquier momento. Esto, por supuesto, a menos que tengas una razón específica para que se ejecute solo en ciertas situaciones, pero la mayoría de las veces quieres que esté constantemente en ejecución y **disponible**.
+
+### En un Servidor Remoto
+
+Cuando configuras un servidor remoto (un servidor en la nube, una máquina virtual, etc.) lo más sencillo que puedes hacer es usar `fastapi run` (que utiliza Uvicorn) o algo similar, manualmente, de la misma manera que lo haces al desarrollar localmente.
+
+Y funcionará y será útil **durante el desarrollo**.
+
+Pero si pierdes la conexión con el servidor, el **proceso en ejecución** probablemente morirá.
+
+Y si el servidor se reinicia (por ejemplo, después de actualizaciones o migraciones del proveedor de la nube) probablemente **no lo notarás**. Y debido a eso, ni siquiera sabrás que tienes que reiniciar el proceso manualmente. Así, tu API simplemente quedará muerta. 😱
+
+### Ejecutar Automáticamente al Iniciar
+
+En general, probablemente querrás que el programa del servidor (por ejemplo, Uvicorn) se inicie automáticamente al arrancar el servidor, y sin necesidad de ninguna **intervención humana**, para tener siempre un proceso en ejecución con tu API (por ejemplo, Uvicorn ejecutando tu aplicación FastAPI).
+
+### Programa Separado
+
+Para lograr esto, normalmente tendrás un **programa separado** que se asegurará de que tu aplicación se ejecute al iniciarse. Y en muchos casos, también se asegurará de que otros componentes o aplicaciones se ejecuten, por ejemplo, una base de datos.
+
+### Herramientas de Ejemplo para Ejecutar al Iniciar
+
+Algunos ejemplos de las herramientas que pueden hacer este trabajo son:
+
+* Docker
+* Kubernetes
+* Docker Compose
+* Docker en Modo Swarm
+* Systemd
+* Supervisor
+* Manejado internamente por un proveedor de nube como parte de sus servicios
+* Otros...
+
+Te daré más ejemplos concretos en los próximos capítulos.
+
+## Reinicios
+
+De manera similar a asegurarte de que tu aplicación se ejecute al iniciar, probablemente también quieras asegurarte de que se **reinicie** después de fallos.
+
+### Cometemos Errores
+
+Nosotros, como humanos, cometemos **errores**, todo el tiempo. El software casi *siempre* tiene **bugs** ocultos en diferentes lugares. 🐛
+
+Y nosotros, como desarrolladores, seguimos mejorando el código a medida que encontramos esos bugs y a medida que implementamos nuevas funcionalidades (posiblemente agregando nuevos bugs también 😅).
+
+### Errores Pequeños Manejados Automáticamente
+
+Al construir APIs web con FastAPI, si hay un error en nuestro código, FastAPI normalmente lo contiene a la solicitud única que desencadenó el error. 🛡
+
+El cliente obtendrá un **500 Internal Server Error** para esa solicitud, pero la aplicación continuará funcionando para las siguientes solicitudes en lugar de simplemente colapsar por completo.
+
+### Errores Mayores - Colapsos
+
+Sin embargo, puede haber casos en los que escribamos algún código que **colapse toda la aplicación** haciendo que Uvicorn y Python colapsen. 💥
+
+Y aún así, probablemente no querrías que la aplicación quede muerta porque hubo un error en un lugar, probablemente querrás que **siga ejecutándose** al menos para las *path operations* que no estén rotas.
+
+### Reiniciar Después del Colapso
+
+Pero en esos casos con errores realmente malos que colapsan el **proceso en ejecución**, querrías un componente externo encargado de **reiniciar** el proceso, al menos un par de veces...
+
+/// tip | Consejo
+
+...Aunque si la aplicación completa **colapsa inmediatamente**, probablemente no tenga sentido seguir reiniciándola eternamente. Pero en esos casos, probablemente lo notarás durante el desarrollo, o al menos justo después de la implementación.
+
+Así que enfoquémonos en los casos principales, donde podría colapsar por completo en algunos casos particulares **en el futuro**, y aún así tenga sentido reiniciarla.
+
+///
+
+Probablemente querrías que la cosa encargada de reiniciar tu aplicación sea un **componente externo**, porque para ese punto, la misma aplicación con Uvicorn y Python ya colapsó, así que no hay nada en el mismo código de la misma aplicación que pueda hacer algo al respecto.
+
+### Herramientas de Ejemplo para Reiniciar Automáticamente
+
+En la mayoría de los casos, la misma herramienta que se utiliza para **ejecutar el programa al iniciar** también se utiliza para manejar reinicios automáticos.
+
+Por ejemplo, esto podría ser manejado por:
+
+* Docker
+* Kubernetes
+* Docker Compose
+* Docker en Modo Swarm
+* Systemd
+* Supervisor
+* Manejado internamente por un proveedor de nube como parte de sus servicios
+* Otros...
+
+## Replicación - Procesos y Memoria
+
+Con una aplicación FastAPI, usando un programa servidor como el comando `fastapi` que ejecuta Uvicorn, ejecutarlo una vez en **un proceso** puede servir a múltiples clientes concurrentemente.
+
+Pero en muchos casos, querrás ejecutar varios worker processes al mismo tiempo.
+
+### Múltiples Procesos - Workers
+
+Si tienes más clientes de los que un solo proceso puede manejar (por ejemplo, si la máquina virtual no es muy grande) y tienes **múltiples núcleos** en la CPU del servidor, entonces podrías tener **múltiples procesos** ejecutando la misma aplicación al mismo tiempo, y distribuir todas las requests entre ellos.
+
+Cuando ejecutas **múltiples procesos** del mismo programa de API, comúnmente se les llama **workers**.
+
+### Worker Processes y Puertos
+
+Recuerda de la documentación [Sobre HTTPS](https.md){.internal-link target=_blank} que solo un proceso puede estar escuchando en una combinación de puerto y dirección IP en un servidor.
+
+Esto sigue siendo cierto.
+
+Así que, para poder tener **múltiples procesos** al mismo tiempo, tiene que haber un **solo proceso escuchando en un puerto** que luego transmita la comunicación a cada worker process de alguna forma.
+
+### Memoria por Proceso
+
+Ahora, cuando el programa carga cosas en memoria, por ejemplo, un modelo de machine learning en una variable, o el contenido de un archivo grande en una variable, todo eso **consume un poco de la memoria (RAM)** del servidor.
+
+Y múltiples procesos normalmente **no comparten ninguna memoria**. Esto significa que cada proceso en ejecución tiene sus propias cosas, variables y memoria. Y si estás consumiendo una gran cantidad de memoria en tu código, **cada proceso** consumirá una cantidad equivalente de memoria.
+
+### Memoria del Servidor
+
+Por ejemplo, si tu código carga un modelo de Machine Learning con **1 GB de tamaño**, cuando ejecutas un proceso con tu API, consumirá al menos 1 GB de RAM. Y si inicias **4 procesos** (4 workers), cada uno consumirá 1 GB de RAM. Así que, en total, tu API consumirá **4 GB de RAM**.
+
+Y si tu servidor remoto o máquina virtual solo tiene 3 GB de RAM, intentar cargar más de 4 GB de RAM causará problemas. 🚨
+
+### Múltiples Procesos - Un Ejemplo
+
+En este ejemplo, hay un **Proceso Administrador** que inicia y controla dos **Worker Processes**.
+
+Este Proceso Administrador probablemente sería el que escuche en el **puerto** en la IP. Y transmitirá toda la comunicación a los worker processes.
+
+Esos worker processes serían los que ejecutan tu aplicación, realizarían los cálculos principales para recibir un **request** y devolver un **response**, y cargarían cualquier cosa que pongas en variables en RAM.
+
+fastapi run --workers 4 main.py +INFO Using path main.py +INFO Resolved absolute path /home/user/code/awesomeapp/main.py +INFO Searching for package file structure from directories with __init__.py files +INFO Importing from /home/user/code/awesomeapp + + ╭─ Python module file ─╮ + │ │ + │ 🐍 main.py │ + │ │ + ╰──────────────────────╯ + +INFO Importing module main +INFO Found importable FastAPI app + + ╭─ Importable FastAPI app ─╮ + │ │ + │ from main import app │ + │ │ + ╰──────────────────────────╯ + +INFO Using import string main:app + + ╭─────────── FastAPI CLI - Production mode ───────────╮ + │ │ + │ Serving at: http://0.0.0.0:8000 │ + │ │ + │ API docs: http://0.0.0.0:8000/docs │ + │ │ + │ Running in production mode, for development use: │ + │ │ + │ fastapi dev │ + │ │ + ╰─────────────────────────────────────────────────────╯ + +INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit) +INFO: Started parent process [27365] +INFO: Started server process [27368] +INFO: Waiting for application startup. +INFO: Application startup complete. +INFO: Started server process [27369] +INFO: Waiting for application startup. +INFO: Application startup complete. +INFO: Started server process [27370] +INFO: Waiting for application startup. +INFO: Application startup complete. +INFO: Started server process [27367] +INFO: Waiting for application startup. +INFO: Application startup complete. ++``` + +
+ +**FastAPI** no existiría si no fuera por el trabajo previo de otros. + +Ha habido muchas herramientas creadas antes que han ayudado a inspirar su creación. + +He estado evitando la creación de un nuevo framework durante varios años. Primero traté de resolver todas las funcionalidades cubiertas por **FastAPI** usando varios frameworks, complementos y herramientas diferentes. + +Pero en algún momento, no había otra opción que crear algo que proporcionara todas estas funcionalidades, tomando las mejores ideas de herramientas anteriores y combinándolas de la mejor manera posible, usando funcionalidades del lenguaje que ni siquiera estaban disponibles antes (anotaciones de tipos de Python 3.6+). + ++ +## Investigación + +Al usar todas las alternativas anteriores, tuve la oportunidad de aprender de todas ellas, tomar ideas y combinarlas de la mejor manera que pude encontrar para mí y los equipos de desarrolladores con los que he trabajado. + +Por ejemplo, estaba claro que idealmente debería estar basado en las anotaciones de tipos estándar de Python. + +También, el mejor enfoque era usar estándares ya existentes. + +Entonces, antes de siquiera empezar a programar **FastAPI**, pasé varios meses estudiando las especificaciones de OpenAPI, JSON Schema, OAuth2, etc. Entendiendo su relación, superposición y diferencias. + +## Diseño + +Luego pasé algún tiempo diseñando la "API" de desarrollador que quería tener como usuario (como desarrollador usando FastAPI). + +Probé varias ideas en los editores de Python más populares: PyCharm, VS Code, editores basados en Jedi. + +Según la última Encuesta de Desarrolladores de Python, estos editores cubren alrededor del 80% de los usuarios. + +Esto significa que **FastAPI** fue específicamente probado con los editores usados por el 80% de los desarrolladores de Python. Y como la mayoría de los otros editores tienden a funcionar de manera similar, todos sus beneficios deberían funcionar prácticamente para todos los editores. + +De esa manera, pude encontrar las mejores maneras de reducir la duplicación de código tanto como fuera posible, para tener autocompletado en todas partes, chequeos de tipos y errores, etc. + +Todo de una manera que proporcionara la mejor experiencia de desarrollo para todos los desarrolladores. + +## Requisitos + +Después de probar varias alternativas, decidí que iba a usar **Pydantic** por sus ventajas. + +Luego contribuí a este, para hacerlo totalmente compatible con JSON Schema, para soportar diferentes maneras de definir declaraciones de restricciones, y para mejorar el soporte de los editores (chequeo de tipos, autocompletado) basado en las pruebas en varios editores. + +Durante el desarrollo, también contribuí a **Starlette**, el otro requisito clave. + +## Desarrollo + +Para cuando comencé a crear el propio **FastAPI**, la mayoría de las piezas ya estaban en su lugar, el diseño estaba definido, los requisitos y herramientas estaban listos, y el conocimiento sobre los estándares y especificaciones estaba claro y fresco. + +## Futuro + +A este punto, ya está claro que **FastAPI** con sus ideas está siendo útil para muchas personas. + +Está siendo elegido sobre alternativas anteriores por adaptarse mejor a muchos casos de uso. + +Muchos desarrolladores y equipos ya dependen de **FastAPI** para sus proyectos (incluyéndome a mí y a mi equipo). + +Pero aún así, hay muchas mejoras y funcionalidades por venir. + +**FastAPI** tiene un gran futuro por delante. + +Y [tu ayuda](help-fastapi.md){.internal-link target=_blank} es muy apreciada. diff --git a/docs/es/docs/how-to/conditional-openapi.md b/docs/es/docs/how-to/conditional-openapi.md new file mode 100644 index 000000000..4f806ef6c --- /dev/null +++ b/docs/es/docs/how-to/conditional-openapi.md @@ -0,0 +1,56 @@ +# OpenAPI Condicional + +Si lo necesitaras, podrías usar configuraciones y variables de entorno para configurar OpenAPI condicionalmente según el entorno, e incluso desactivarlo por completo. + +## Sobre seguridad, APIs y documentación + +Ocultar las interfaces de usuario de la documentación en producción *no debería* ser la forma de proteger tu API. + +Eso no añade ninguna seguridad extra a tu API, las *path operations* seguirán estando disponibles donde están. + +Si hay una falla de seguridad en tu código, seguirá existiendo. + +Ocultar la documentación solo hace que sea más difícil entender cómo interactuar con tu API y podría dificultar más depurarla en producción. Podría considerarse simplemente una forma de Seguridad mediante oscuridad. + +Si quieres asegurar tu API, hay varias cosas mejores que puedes hacer, por ejemplo: + +* Asegúrate de tener modelos Pydantic bien definidos para tus request bodies y responses. +* Configura los permisos y roles necesarios usando dependencias. +* Nunca guardes contraseñas en texto plano, solo hashes de contraseñas. +* Implementa y utiliza herramientas criptográficas bien conocidas, como Passlib y JWT tokens, etc. +* Añade controles de permisos más detallados con OAuth2 scopes donde sea necesario. +* ...etc. + +No obstante, podrías tener un caso de uso muy específico donde realmente necesites desactivar la documentación de la API para algún entorno (por ejemplo, para producción) o dependiendo de configuraciones de variables de entorno. + +## OpenAPI condicional desde configuraciones y variables de entorno + +Puedes usar fácilmente las mismas configuraciones de Pydantic para configurar tu OpenAPI generado y las interfaces de usuario de la documentación. + +Por ejemplo: + +{* ../../docs_src/conditional_openapi/tutorial001.py hl[6,11] *} + +Aquí declaramos la configuración `openapi_url` con el mismo valor predeterminado de `"/openapi.json"`. + +Y luego la usamos al crear la app de `FastAPI`. + +Entonces podrías desactivar OpenAPI (incluyendo las UI de documentación) configurando la variable de entorno `OPENAPI_URL` a una string vacía, así: + +
+
+Pero puedes desactivarlo estableciendo `syntaxHighlight` en `False`:
+
+{* ../../docs_src/configure_swagger_ui/tutorial001.py hl[3] *}
+
+...y entonces Swagger UI ya no mostrará el resaltado de sintaxis:
+
+
+
+## Cambiar el tema
+
+De la misma manera, podrías configurar el tema del resaltado de sintaxis con la clave `"syntaxHighlight.theme"` (ten en cuenta que tiene un punto en el medio):
+
+{* ../../docs_src/configure_swagger_ui/tutorial002.py hl[3] *}
+
+Esa configuración cambiaría el tema de color del resaltado de sintaxis:
+
+
+
+## Cambiar los parámetros predeterminados de Swagger UI
+
+FastAPI incluye algunos parámetros de configuración predeterminados apropiados para la mayoría de los casos de uso.
+
+Incluye estas configuraciones predeterminadas:
+
+{* ../../fastapi/openapi/docs.py ln[8:23] hl[17:23] *}
+
+Puedes sobrescribir cualquiera de ellos estableciendo un valor diferente en el argumento `swagger_ui_parameters`.
+
+Por ejemplo, para desactivar `deepLinking` podrías pasar estas configuraciones a `swagger_ui_parameters`:
+
+{* ../../docs_src/configure_swagger_ui/tutorial003.py hl[3] *}
+
+## Otros parámetros de Swagger UI
+
+Para ver todas las demás configuraciones posibles que puedes usar, lee la documentación oficial de los parámetros de Swagger UI.
+
+## Configuraciones solo de JavaScript
+
+Swagger UI también permite otras configuraciones que son objetos **solo de JavaScript** (por ejemplo, funciones de JavaScript).
+
+FastAPI también incluye estas configuraciones `presets` solo de JavaScript:
+
+```JavaScript
+presets: [
+ SwaggerUIBundle.presets.apis,
+ SwaggerUIBundle.SwaggerUIStandalonePreset
+]
+```
+
+Estos son objetos de **JavaScript**, no strings, por lo que no puedes pasarlos directamente desde código de Python.
+
+Si necesitas usar configuraciones solo de JavaScript como esas, puedes usar uno de los métodos anteriores. Sobrescribe toda la *path operation* de Swagger UI y escribe manualmente cualquier JavaScript que necesites.
diff --git a/docs/es/docs/how-to/custom-docs-ui-assets.md b/docs/es/docs/how-to/custom-docs-ui-assets.md
new file mode 100644
index 000000000..0a03ff330
--- /dev/null
+++ b/docs/es/docs/how-to/custom-docs-ui-assets.md
@@ -0,0 +1,185 @@
+# Recursos Estáticos Personalizados para la Docs UI (Self-Hosting)
+
+La documentación de la API utiliza **Swagger UI** y **ReDoc**, y cada uno de estos necesita algunos archivos JavaScript y CSS.
+
+Por defecto, esos archivos se sirven desde un CDN.
+
+Pero es posible personalizarlo, puedes establecer un CDN específico, o servir los archivos tú mismo.
+
+## CDN Personalizado para JavaScript y CSS
+
+Digamos que quieres usar un CDN diferente, por ejemplo, quieres usar `https://unpkg.com/`.
+
+Esto podría ser útil si, por ejemplo, vives en un país que restringe algunas URLs.
+
+### Desactiva la documentación automática
+
+El primer paso es desactivar la documentación automática, ya que por defecto, esos usan el CDN predeterminado.
+
+Para desactivarlos, establece sus URLs en `None` cuando crees tu aplicación de `FastAPI`:
+
+{* ../../docs_src/custom_docs_ui/tutorial001.py hl[8] *}
+
+### Incluye la documentación personalizada
+
+Ahora puedes crear las *path operations* para la documentación personalizada.
+
+Puedes reutilizar las funciones internas de FastAPI para crear las páginas HTML para la documentación, y pasarles los argumentos necesarios:
+
+* `openapi_url`: la URL donde la página HTML para la documentación puede obtener el OpenAPI esquema de tu API. Puedes usar aquí el atributo `app.openapi_url`.
+* `title`: el título de tu API.
+* `oauth2_redirect_url`: puedes usar `app.swagger_ui_oauth2_redirect_url` aquí para usar el valor predeterminado.
+* `swagger_js_url`: la URL donde el HTML para tu documentación de Swagger UI puede obtener el archivo **JavaScript**. Esta es la URL personalizada del CDN.
+* `swagger_css_url`: la URL donde el HTML para tu documentación de Swagger UI puede obtener el archivo **CSS**. Esta es la URL personalizada del CDN.
+
+Y de manera similar para ReDoc...
+
+{* ../../docs_src/custom_docs_ui/tutorial001.py hl[2:6,11:19,22:24,27:33] *}
+
+/// tip | Consejo
+
+La *path operation* para `swagger_ui_redirect` es una herramienta cuando utilizas OAuth2.
+
+Si integras tu API con un proveedor OAuth2, podrás autenticarte y regresar a la documentación de la API con las credenciales adquiridas. E interactuar con ella usando la autenticación real de OAuth2.
+
+Swagger UI lo manejará detrás de escena para ti, pero necesita este auxiliar de "redirección".
+
+///
+
+### Crea una *path operation* para probarlo
+
+Ahora, para poder probar que todo funciona, crea una *path operation*:
+
+{* ../../docs_src/custom_docs_ui/tutorial001.py hl[36:38] *}
+
+### Pruébalo
+
+Ahora, deberías poder ir a tu documentación en http://127.0.0.1:8000/docs, y recargar la página, cargará esos recursos desde el nuevo CDN.
+
+## Self-hosting de JavaScript y CSS para la documentación
+
+El self-hosting de JavaScript y CSS podría ser útil si, por ejemplo, necesitas que tu aplicación siga funcionando incluso offline, sin acceso a Internet, o en una red local.
+
+Aquí verás cómo servir esos archivos tú mismo, en la misma aplicación de FastAPI, y configurar la documentación para usarla.
+
+### Estructura de archivos del proyecto
+
+Supongamos que la estructura de archivos de tu proyecto se ve así:
+
+```
+.
+├── app
+│ ├── __init__.py
+│ ├── main.py
+```
+
+Ahora crea un directorio para almacenar esos archivos estáticos.
+
+Tu nueva estructura de archivos podría verse así:
+
+```
+.
+├── app
+│ ├── __init__.py
+│ ├── main.py
+└── static/
+```
+
+### Descarga los archivos
+
+Descarga los archivos estáticos necesarios para la documentación y ponlos en ese directorio `static/`.
+
+Probablemente puedas hacer clic derecho en cada enlace y seleccionar una opción similar a `Guardar enlace como...`.
+
+**Swagger UI** utiliza los archivos:
+
+* `swagger-ui-bundle.js`
+* `swagger-ui.css`
+
+Y **ReDoc** utiliza el archivo:
+
+* `redoc.standalone.js`
+
+Después de eso, tu estructura de archivos podría verse así:
+
+```
+.
+├── app
+│ ├── __init__.py
+│ ├── main.py
+└── static
+ ├── redoc.standalone.js
+ ├── swagger-ui-bundle.js
+ └── swagger-ui.css
+```
+
+### Sirve los archivos estáticos
+
+* Importa `StaticFiles`.
+* "Monta" una instance de `StaticFiles()` en un path específico.
+
+{* ../../docs_src/custom_docs_ui/tutorial002.py hl[7,11] *}
+
+### Prueba los archivos estáticos
+
+Inicia tu aplicación y ve a http://127.0.0.1:8000/static/redoc.standalone.js.
+
+Deberías ver un archivo JavaScript muy largo de **ReDoc**.
+
+Podría comenzar con algo como:
+
+```JavaScript
+/*! For license information please see redoc.standalone.js.LICENSE.txt */
+!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t(require("null")):
+...
+```
+
+Eso confirma que puedes servir archivos estáticos desde tu aplicación, y que colocaste los archivos estáticos para la documentación en el lugar correcto.
+
+Ahora podemos configurar la aplicación para usar esos archivos estáticos para la documentación.
+
+### Desactiva la documentación automática para archivos estáticos
+
+Igual que cuando usas un CDN personalizado, el primer paso es desactivar la documentación automática, ya que esos usan el CDN por defecto.
+
+Para desactivarlos, establece sus URLs en `None` cuando crees tu aplicación de `FastAPI`:
+
+{* ../../docs_src/custom_docs_ui/tutorial002.py hl[9] *}
+
+### Incluye la documentación personalizada para archivos estáticos
+
+Y de la misma manera que con un CDN personalizado, ahora puedes crear las *path operations* para la documentación personalizada.
+
+Nuevamente, puedes reutilizar las funciones internas de FastAPI para crear las páginas HTML para la documentación, y pasarles los argumentos necesarios:
+
+* `openapi_url`: la URL donde la página HTML para la documentación puede obtener el OpenAPI esquema de tu API. Puedes usar aquí el atributo `app.openapi_url`.
+* `title`: el título de tu API.
+* `oauth2_redirect_url`: puedes usar `app.swagger_ui_oauth2_redirect_url` aquí para usar el valor predeterminado.
+* `swagger_js_url`: la URL donde el HTML para tu documentación de Swagger UI puede obtener el archivo **JavaScript**. **Este es el que tu propia aplicación está sirviendo ahora**.
+* `swagger_css_url`: la URL donde el HTML para tu documentación de Swagger UI puede obtener el archivo **CSS**. **Este es el que tu propia aplicación está sirviendo ahora**.
+
+Y de manera similar para ReDoc...
+
+{* ../../docs_src/custom_docs_ui/tutorial002.py hl[2:6,14:22,25:27,30:36] *}
+
+/// tip | Consejo
+
+La *path operation* para `swagger_ui_redirect` es una herramienta cuando utilizas OAuth2.
+
+Si integras tu API con un proveedor OAuth2, podrás autenticarte y regresar a la documentación de la API con las credenciales adquiridas. Y interactuar con ella usando la autenticación real de OAuth2.
+
+Swagger UI lo manejará detrás de escena para ti, pero necesita este auxiliar de "redirección".
+
+///
+
+### Crea una *path operation* para probar archivos estáticos
+
+Ahora, para poder probar que todo funciona, crea una *path operation*:
+
+{* ../../docs_src/custom_docs_ui/tutorial002.py hl[39:41] *}
+
+### Prueba la UI de Archivos Estáticos
+
+Ahora, deberías poder desconectar tu WiFi, ir a tu documentación en http://127.0.0.1:8000/docs, y recargar la página.
+
+E incluso sin Internet, podrás ver la documentación de tu API e interactuar con ella.
diff --git a/docs/es/docs/how-to/custom-request-and-route.md b/docs/es/docs/how-to/custom-request-and-route.md
new file mode 100644
index 000000000..0b479bf00
--- /dev/null
+++ b/docs/es/docs/how-to/custom-request-and-route.md
@@ -0,0 +1,109 @@
+# Clase personalizada de Request y APIRoute
+
+En algunos casos, puede que quieras sobrescribir la lógica utilizada por las clases `Request` y `APIRoute`.
+
+En particular, esta puede ser una buena alternativa a la lógica en un middleware.
+
+Por ejemplo, si quieres leer o manipular el request body antes de que sea procesado por tu aplicación.
+
+/// danger | Advertencia
+
+Esta es una funcionalidad "avanzada".
+
+Si apenas estás comenzando con **FastAPI**, quizás quieras saltar esta sección.
+
+///
+
+## Casos de uso
+
+Algunos casos de uso incluyen:
+
+* Convertir cuerpos de requests no-JSON a JSON (por ejemplo, `msgpack`).
+* Descomprimir cuerpos de requests comprimidos con gzip.
+* Registrar automáticamente todos los request bodies.
+
+## Manejo de codificaciones personalizadas de request body
+
+Veamos cómo hacer uso de una subclase personalizada de `Request` para descomprimir requests gzip.
+
+Y una subclase de `APIRoute` para usar esa clase de request personalizada.
+
+### Crear una clase personalizada `GzipRequest`
+
+/// tip | Consejo
+
+Este es un ejemplo sencillo para demostrar cómo funciona. Si necesitas soporte para Gzip, puedes usar el [`GzipMiddleware`](../advanced/middleware.md#gzipmiddleware){.internal-link target=_blank} proporcionado.
+
+///
+
+Primero, creamos una clase `GzipRequest`, que sobrescribirá el método `Request.body()` para descomprimir el cuerpo si hay un header apropiado.
+
+Si no hay `gzip` en el header, no intentará descomprimir el cuerpo.
+
+De esa manera, la misma clase de ruta puede manejar requests comprimidos con gzip o no comprimidos.
+
+{* ../../docs_src/custom_request_and_route/tutorial001.py hl[8:15] *}
+
+### Crear una clase personalizada `GzipRoute`
+
+A continuación, creamos una subclase personalizada de `fastapi.routing.APIRoute` que hará uso de `GzipRequest`.
+
+Esta vez, sobrescribirá el método `APIRoute.get_route_handler()`.
+
+Este método devuelve una función. Y esa función es la que recibirá un request y devolverá un response.
+
+Aquí lo usamos para crear un `GzipRequest` a partir del request original.
+
+{* ../../docs_src/custom_request_and_route/tutorial001.py hl[18:26] *}
+
+/// note | Detalles técnicos
+
+Un `Request` tiene un atributo `request.scope`, que es simplemente un `dict` de Python que contiene los metadatos relacionados con el request.
+
+Un `Request` también tiene un `request.receive`, que es una función para "recibir" el cuerpo del request.
+
+El `dict` `scope` y la función `receive` son ambos parte de la especificación ASGI.
+
+Y esas dos cosas, `scope` y `receive`, son lo que se necesita para crear una nueva *Request instance*.
+
+Para aprender más sobre el `Request`, revisa la documentación de Starlette sobre Requests.
+
+///
+
+La única cosa que la función devuelta por `GzipRequest.get_route_handler` hace diferente es convertir el `Request` en un `GzipRequest`.
+
+Haciendo esto, nuestro `GzipRequest` se encargará de descomprimir los datos (si es necesario) antes de pasarlos a nuestras *path operations*.
+
+Después de eso, toda la lógica de procesamiento es la misma.
+
+Pero debido a nuestros cambios en `GzipRequest.body`, el request body se descomprimirá automáticamente cuando sea cargado por **FastAPI** si es necesario.
+
+## Accediendo al request body en un manejador de excepciones
+
+/// tip | Consejo
+
+Para resolver este mismo problema, probablemente sea mucho más fácil usar el `body` en un manejador personalizado para `RequestValidationError` ([Manejo de Errores](../tutorial/handling-errors.md#use-the-requestvalidationerror-body){.internal-link target=_blank}).
+
+Pero este ejemplo sigue siendo válido y muestra cómo interactuar con los componentes internos.
+
+///
+
+También podemos usar este mismo enfoque para acceder al request body en un manejador de excepciones.
+
+Todo lo que necesitamos hacer es manejar el request dentro de un bloque `try`/`except`:
+
+{* ../../docs_src/custom_request_and_route/tutorial002.py hl[13,15] *}
+
+Si ocurre una excepción, la `Request instance` aún estará en el alcance, así que podemos leer y hacer uso del request body cuando manejamos el error:
+
+{* ../../docs_src/custom_request_and_route/tutorial002.py hl[16:18] *}
+
+## Clase personalizada `APIRoute` en un router
+
+También puedes establecer el parámetro `route_class` de un `APIRouter`:
+
+{* ../../docs_src/custom_request_and_route/tutorial003.py hl[26] *}
+
+En este ejemplo, las *path operations* bajo el `router` usarán la clase personalizada `TimedRoute`, y tendrán un header `X-Response-Time` extra en el response con el tiempo que tomó generar el response:
+
+{* ../../docs_src/custom_request_and_route/tutorial003.py hl[13:20] *}
diff --git a/docs/es/docs/how-to/extending-openapi.md b/docs/es/docs/how-to/extending-openapi.md
new file mode 100644
index 000000000..3dbdd666b
--- /dev/null
+++ b/docs/es/docs/how-to/extending-openapi.md
@@ -0,0 +1,80 @@
+# Extender OpenAPI
+
+Hay algunos casos en los que podrías necesitar modificar el esquema de OpenAPI generado.
+
+En esta sección verás cómo hacerlo.
+
+## El proceso normal
+
+El proceso normal (por defecto) es el siguiente.
+
+Una aplicación (instance) de `FastAPI` tiene un método `.openapi()` que se espera que devuelva el esquema de OpenAPI.
+
+Como parte de la creación del objeto de la aplicación, se registra una *path operation* para `/openapi.json` (o para lo que sea que configures tu `openapi_url`).
+
+Simplemente devuelve un response JSON con el resultado del método `.openapi()` de la aplicación.
+
+Por defecto, lo que hace el método `.openapi()` es revisar la propiedad `.openapi_schema` para ver si tiene contenido y devolverlo.
+
+Si no lo tiene, lo genera usando la función de utilidad en `fastapi.openapi.utils.get_openapi`.
+
+Y esa función `get_openapi()` recibe como parámetros:
+
+* `title`: El título de OpenAPI, mostrado en la documentación.
+* `version`: La versión de tu API, por ejemplo `2.5.0`.
+* `openapi_version`: La versión de la especificación OpenAPI utilizada. Por defecto, la más reciente: `3.1.0`.
+* `summary`: Un breve resumen de la API.
+* `description`: La descripción de tu API, esta puede incluir markdown y se mostrará en la documentación.
+* `routes`: Una list de rutas, estas son cada una de las *path operations* registradas. Se toman de `app.routes`.
+
+/// info | Información
+
+El parámetro `summary` está disponible en OpenAPI 3.1.0 y versiones superiores, soportado por FastAPI 0.99.0 y superiores.
+
+///
+
+## Sobrescribir los valores por defecto
+
+Usando la información anterior, puedes usar la misma función de utilidad para generar el esquema de OpenAPI y sobrescribir cada parte que necesites.
+
+Por ejemplo, vamos a añadir la extensión OpenAPI de ReDoc para incluir un logo personalizado.
+
+### **FastAPI** normal
+
+Primero, escribe toda tu aplicación **FastAPI** como normalmente:
+
+{* ../../docs_src/extending_openapi/tutorial001.py hl[1,4,7:9] *}
+
+### Generar el esquema de OpenAPI
+
+Luego, usa la misma función de utilidad para generar el esquema de OpenAPI, dentro de una función `custom_openapi()`:
+
+{* ../../docs_src/extending_openapi/tutorial001.py hl[2,15:21] *}
+
+### Modificar el esquema de OpenAPI
+
+Ahora puedes añadir la extensión de ReDoc, agregando un `x-logo` personalizado al "objeto" `info` en el esquema de OpenAPI:
+
+{* ../../docs_src/extending_openapi/tutorial001.py hl[22:24] *}
+
+### Cachear el esquema de OpenAPI
+
+Puedes usar la propiedad `.openapi_schema` como un "cache", para almacenar tu esquema generado.
+
+De esa forma, tu aplicación no tendrá que generar el esquema cada vez que un usuario abra la documentación de tu API.
+
+Se generará solo una vez, y luego se usará el mismo esquema cacheado para las siguientes requests.
+
+{* ../../docs_src/extending_openapi/tutorial001.py hl[13:14,25:26] *}
+
+### Sobrescribir el método
+
+Ahora puedes reemplazar el método `.openapi()` por tu nueva función.
+
+{* ../../docs_src/extending_openapi/tutorial001.py hl[29] *}
+
+### Revisa
+
+Una vez que vayas a http://127.0.0.1:8000/redoc verás que estás usando tu logo personalizado (en este ejemplo, el logo de **FastAPI**):
+
+
diff --git a/docs/es/docs/how-to/general.md b/docs/es/docs/how-to/general.md
new file mode 100644
index 000000000..e10621ce5
--- /dev/null
+++ b/docs/es/docs/how-to/general.md
@@ -0,0 +1,39 @@
+# General - Cómo Hacer - Recetas
+
+Aquí tienes varias indicaciones hacia otros lugares en la documentación, para preguntas generales o frecuentes.
+
+## Filtrar Datos - Seguridad
+
+Para asegurarte de que no devuelves más datos de los que deberías, lee la documentación para [Tutorial - Modelo de Response - Tipo de Retorno](../tutorial/response-model.md){.internal-link target=_blank}.
+
+## Etiquetas de Documentación - OpenAPI
+
+Para agregar etiquetas a tus *path operations*, y agruparlas en la interfaz de usuario de la documentación, lee la documentación para [Tutorial - Configuraciones de Path Operation - Etiquetas](../tutorial/path-operation-configuration.md#tags){.internal-link target=_blank}.
+
+## Resumen y Descripción de Documentación - OpenAPI
+
+Para agregar un resumen y descripción a tus *path operations*, y mostrarlos en la interfaz de usuario de la documentación, lee la documentación para [Tutorial - Configuraciones de Path Operation - Resumen y Descripción](../tutorial/path-operation-configuration.md#summary-and-description){.internal-link target=_blank}.
+
+## Documentación de Descripción de Response - OpenAPI
+
+Para definir la descripción del response, mostrada en la interfaz de usuario de la documentación, lee la documentación para [Tutorial - Configuraciones de Path Operation - Descripción del Response](../tutorial/path-operation-configuration.md#response-description){.internal-link target=_blank}.
+
+## Documentar la Deprecación de una *Path Operation* - OpenAPI
+
+Para deprecar una *path operation*, y mostrarla en la interfaz de usuario de la documentación, lee la documentación para [Tutorial - Configuraciones de Path Operation - Deprecación](../tutorial/path-operation-configuration.md#deprecate-a-path-operation){.internal-link target=_blank}.
+
+## Convertir cualquier Dato a Compatible con JSON
+
+Para convertir cualquier dato a compatible con JSON, lee la documentación para [Tutorial - Codificador Compatible con JSON](../tutorial/encoder.md){.internal-link target=_blank}.
+
+## Metadatos OpenAPI - Documentación
+
+Para agregar metadatos a tu esquema de OpenAPI, incluyendo una licencia, versión, contacto, etc, lee la documentación para [Tutorial - Metadatos y URLs de Documentación](../tutorial/metadata.md){.internal-link target=_blank}.
+
+## URL Personalizada de OpenAPI
+
+Para personalizar la URL de OpenAPI (o eliminarla), lee la documentación para [Tutorial - Metadatos y URLs de Documentación](../tutorial/metadata.md#openapi-url){.internal-link target=_blank}.
+
+## URLs de Documentación de OpenAPI
+
+Para actualizar las URLs usadas para las interfaces de usuario de documentación generadas automáticamente, lee la documentación para [Tutorial - Metadatos y URLs de Documentación](../tutorial/metadata.md#docs-urls){.internal-link target=_blank}.
diff --git a/docs/es/docs/how-to/graphql.md b/docs/es/docs/how-to/graphql.md
index 1138af76a..52f163809 100644
--- a/docs/es/docs/how-to/graphql.md
+++ b/docs/es/docs/how-to/graphql.md
@@ -1,56 +1,60 @@
# GraphQL
-Como **FastAPI** está basado en el estándar **ASGI**, es muy fácil integrar cualquier library **GraphQL** que sea compatible con ASGI.
+Como **FastAPI** se basa en el estándar **ASGI**, es muy fácil integrar cualquier paquete de **GraphQL** que también sea compatible con ASGI.
-Puedes combinar *operaciones de path* regulares de la library de FastAPI con GraphQL en la misma aplicación.
+Puedes combinar las *path operations* normales de FastAPI con GraphQL en la misma aplicación.
-!!! tip
- **GraphQL** resuelve algunos casos de uso específicos.
+/// tip | Consejo
- Tiene **ventajas** y **desventajas** cuando lo comparas con **APIs web** comunes.
+**GraphQL** resuelve algunos casos de uso muy específicos.
- Asegúrate de evaluar si los **beneficios** para tu caso de uso compensan las **desventajas.** 🤓
+Tiene **ventajas** y **desventajas** en comparación con las **APIs web** comunes.
-## Librerías GraphQL
+Asegúrate de evaluar si los **beneficios** para tu caso de uso compensan los **inconvenientes**. 🤓
-Aquí hay algunas de las libraries de **GraphQL** que tienen soporte con **ASGI** las cuales podrías usar con **FastAPI**:
+///
+
+## Paquetes de GraphQL
+
+Aquí algunos de los paquetes de **GraphQL** que tienen soporte **ASGI**. Podrías usarlos con **FastAPI**:
* Strawberry 🍓
* Con documentación para FastAPI
* Ariadne
* Con documentación para FastAPI
* Tartiflette
- * Con Tartiflette ASGI para proveer integración con ASGI
+ * Con Tartiflette ASGI para proporcionar integración con ASGI
* Graphene
* Con starlette-graphene3
## GraphQL con Strawberry
-Si necesitas o quieres trabajar con **GraphQL**, **Strawberry** es la library **recomendada** por el diseño más cercano a **FastAPI**, el cual es completamente basado en **anotaciones de tipo**.
+Si necesitas o quieres trabajar con **GraphQL**, **Strawberry** es el paquete **recomendado** ya que tiene un diseño muy similar al diseño de **FastAPI**, todo basado en **anotaciones de tipos**.
-Dependiendo de tus casos de uso, podrías preferir usar una library diferente, pero si me preguntas, probablemente te recomendaría **Strawberry**.
+Dependiendo de tu caso de uso, podrías preferir usar un paquete diferente, pero si me preguntas, probablemente te sugeriría probar **Strawberry**.
-Aquí hay una pequeña muestra de cómo podrías integrar Strawberry con FastAPI:
+Aquí tienes una pequeña vista previa de cómo podrías integrar Strawberry con FastAPI:
-```Python hl_lines="3 22 25-26"
-{!../../../docs_src/graphql/tutorial001.py!}
-```
+{* ../../docs_src/graphql/tutorial001.py hl[3,22,25:26] *}
Puedes aprender más sobre Strawberry en la documentación de Strawberry.
-Y también en la documentación sobre Strawberry con FastAPI.
+Y también la documentación sobre Strawberry con FastAPI.
-## Clase obsoleta `GraphQLApp` en Starlette
+## `GraphQLApp` viejo de Starlette
-Versiones anteriores de Starlette incluyen la clase `GraphQLApp` para integrarlo con Graphene.
+Las versiones anteriores de Starlette incluían una clase `GraphQLApp` para integrar con Graphene.
-Esto fue marcado como obsoleto en Starlette, pero si aún tienes código que lo usa, puedes fácilmente **migrar** a starlette-graphene3, la cual cubre el mismo caso de uso y tiene una **interfaz casi idéntica.**
+Fue deprecada de Starlette, pero si tienes código que lo usaba, puedes fácilmente **migrar** a starlette-graphene3, que cubre el mismo caso de uso y tiene una **interfaz casi idéntica**.
-!!! tip
- Si necesitas GraphQL, te recomendaría revisar Strawberry, que es basada en anotaciones de tipo en vez de clases y tipos personalizados.
+/// tip | Consejo
-## Aprende más
+Si necesitas GraphQL, aún te recomendaría revisar Strawberry, ya que se basa en anotaciones de tipos en lugar de clases y tipos personalizados.
-Puedes aprender más acerca de **GraphQL** en la documentación oficial de GraphQL.
+///
-También puedes leer más acerca de cada library descrita anteriormente en sus enlaces.
+## Aprende Más
+
+Puedes aprender más sobre **GraphQL** en la documentación oficial de GraphQL.
+
+También puedes leer más sobre cada uno de esos paquetes descritos arriba en sus enlaces.
diff --git a/docs/es/docs/how-to/index.md b/docs/es/docs/how-to/index.md
new file mode 100644
index 000000000..152499af8
--- /dev/null
+++ b/docs/es/docs/how-to/index.md
@@ -0,0 +1,13 @@
+# How To - Recetas
+
+Aquí verás diferentes recetas o guías de "cómo hacer" para **varios temas**.
+
+La mayoría de estas ideas serían más o menos **independientes**, y en la mayoría de los casos solo deberías estudiarlas si aplican directamente a **tu proyecto**.
+
+Si algo parece interesante y útil para tu proyecto, adelante y revísalo, pero de lo contrario, probablemente puedas simplemente omitirlas.
+
+/// tip | Consejo
+
+Si quieres **aprender FastAPI** de una manera estructurada (recomendado), ve y lee el [Tutorial - User Guide](../tutorial/index.md){.internal-link target=_blank} capítulo por capítulo.
+
+///
diff --git a/docs/es/docs/how-to/separate-openapi-schemas.md b/docs/es/docs/how-to/separate-openapi-schemas.md
new file mode 100644
index 000000000..b77915851
--- /dev/null
+++ b/docs/es/docs/how-to/separate-openapi-schemas.md
@@ -0,0 +1,104 @@
+# Separación de Esquemas OpenAPI para Entrada y Salida o No
+
+Al usar **Pydantic v2**, el OpenAPI generado es un poco más exacto y **correcto** que antes. 😎
+
+De hecho, en algunos casos, incluso tendrá **dos JSON Schemas** en OpenAPI para el mismo modelo Pydantic, para entrada y salida, dependiendo de si tienen **valores por defecto**.
+
+Veamos cómo funciona eso y cómo cambiarlo si necesitas hacerlo.
+
+## Modelos Pydantic para Entrada y Salida
+
+Digamos que tienes un modelo Pydantic con valores por defecto, como este:
+
+{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:7] hl[7] *}
+
+### Modelo para Entrada
+
+Si usas este modelo como entrada, como aquí:
+
+{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:15] hl[14] *}
+
+...entonces el campo `description` **no será requerido**. Porque tiene un valor por defecto de `None`.
+
+### Modelo de Entrada en la Documentación
+
+Puedes confirmar eso en la documentación, el campo `description` no tiene un **asterisco rojo**, no está marcado como requerido:
+
+
+
+
+
+
+
- FastAPI framework, alto desempeño, fácil de aprender, rápido de programar, listo para producción + FastAPI framework, alto rendimiento, fácil de aprender, rápido de programar, listo para producción
--- @@ -29,21 +32,21 @@ **Código Fuente**: https://github.com/fastapi/fastapi --- -FastAPI es un web framework moderno y rápido (de alto rendimiento) para construir APIs con Python basado en las anotaciones de tipos estándar de Python. -Sus características principales son: +FastAPI es un framework web moderno, rápido (de alto rendimiento), para construir APIs con Python basado en las anotaciones de tipos estándar de Python. -* **Rapidez**: Alto rendimiento, a la par con **NodeJS** y **Go** (gracias a Starlette y Pydantic). [Uno de los frameworks de Python más rápidos](#rendimiento). +Las características clave son: -* **Rápido de programar**: Incrementa la velocidad de desarrollo entre 200% y 300%. * -* **Menos errores**: Reduce los errores humanos (de programador) aproximadamente un 40%. * -* **Intuitivo**: Gran soporte en los editores con auto completado en todas partes. Gasta menos tiempo debugging. -* **Fácil**: Está diseñado para ser fácil de usar y aprender. Gastando menos tiempo leyendo documentación. -* **Corto**: Minimiza la duplicación de código. Múltiples funcionalidades con cada declaración de parámetros. Menos errores. -* **Robusto**: Crea código listo para producción con documentación automática interactiva. -* **Basado en estándares**: Basado y totalmente compatible con los estándares abiertos para APIs: OpenAPI (conocido previamente como Swagger) y JSON Schema. +* **Rápido**: Muy alto rendimiento, a la par con **NodeJS** y **Go** (gracias a Starlette y Pydantic). [Uno de los frameworks Python más rápidos disponibles](#performance). +* **Rápido de programar**: Aumenta la velocidad para desarrollar funcionalidades en aproximadamente un 200% a 300%. * +* **Menos bugs**: Reduce en aproximadamente un 40% los errores inducidos por humanos (desarrolladores). * +* **Intuitivo**: Gran soporte para editores. Autocompletado en todas partes. Menos tiempo depurando. +* **Fácil**: Diseñado para ser fácil de usar y aprender. Menos tiempo leyendo documentación. +* **Corto**: Minimiza la duplicación de código. Múltiples funcionalidades desde cada declaración de parámetro. Menos bugs. +* **Robusto**: Obtén código listo para producción. Con documentación interactiva automática. +* **Basado en estándares**: Basado (y completamente compatible) con los estándares abiertos para APIs: OpenAPI (anteriormente conocido como Swagger) y JSON Schema. -* Esta estimación está basada en pruebas con un equipo de desarrollo interno construyendo aplicaciones listas para producción. +* estimación basada en pruebas con un equipo de desarrollo interno, construyendo aplicaciones de producción. ## Sponsors @@ -64,41 +67,47 @@ Sus características principales son: ## Opiniones -"_[...] I'm using **FastAPI** a ton these days. [...] I'm actually planning to use it for all of my team's **ML services at Microsoft**. Some of them are getting integrated into the core **Windows** product and some **Office** products._" +"_[...] Estoy usando **FastAPI** un montón estos días. [...] De hecho, estoy planeando usarlo para todos los servicios de **ML de mi equipo en Microsoft**. Algunos de ellos se están integrando en el núcleo del producto **Windows** y algunos productos de **Office**._"uvicorn main:app --reload...fastapi dev main.py...email_validator - para validación de emails.
+* email-validator - para validación de correos electrónicos.
-Usados por Starlette:
+Usadas por Starlette:
-* httpx - Requerido si quieres usar el `TestClient`.
-* jinja2 - Requerido si quieres usar la configuración por defecto de templates.
-* python-multipart - Requerido si quieres dar soporte a "parsing" de formularios, con `request.form()`.
-* itsdangerous - Requerido para dar soporte a `SessionMiddleware`.
-* pyyaml - Requerido para dar soporte al `SchemaGenerator` de Starlette (probablemente no lo necesites con FastAPI).
-* graphene - Requerido para dar soporte a `GraphQLApp`.
+* httpx - Requerido si deseas usar el `TestClient`.
+* jinja2 - Requerido si deseas usar la configuración de plantilla predeterminada.
+* python-multipart - Requerido si deseas soportar "parsing" de forms, con `request.form()`.
-Usado por FastAPI / Starlette:
+Usadas por FastAPI / Starlette:
-* uvicorn - para el servidor que carga y sirve tu aplicación.
-* orjson - Requerido si quieres usar `ORJSONResponse`.
-* ujson - Requerido si quieres usar `UJSONResponse`.
+* uvicorn - para el servidor que carga y sirve tu aplicación. Esto incluye `uvicorn[standard]`, que incluye algunas dependencias (por ejemplo, `uvloop`) necesarias para servir con alto rendimiento.
+* `fastapi-cli` - para proporcionar el comando `fastapi`.
-Puedes instalarlos con `pip install fastapi[all]`.
+### Sin Dependencias `standard`
+
+Si no deseas incluir las dependencias opcionales `standard`, puedes instalar con `pip install fastapi` en lugar de `pip install "fastapi[standard]"`.
+
+### Dependencias Opcionales Adicionales
+
+Existen algunas dependencias adicionales que podrías querer instalar.
+
+Dependencias opcionales adicionales de Pydantic:
+
+* pydantic-settings - para la gestión de configuraciones.
+* pydantic-extra-types - para tipos extra para ser usados con Pydantic.
+
+Dependencias opcionales adicionales de FastAPI:
+
+* orjson - Requerido si deseas usar `ORJSONResponse`.
+* ujson - Requerido si deseas usar `UJSONResponse`.
## Licencia
-Este proyecto está licenciado bajo los términos de la licencia del MIT.
+Este proyecto tiene licencia bajo los términos de la licencia MIT.
diff --git a/docs/es/docs/learn/index.md b/docs/es/docs/learn/index.md
index b8d26cf34..cc6c7cc3f 100644
--- a/docs/es/docs/learn/index.md
+++ b/docs/es/docs/learn/index.md
@@ -1,5 +1,5 @@
-# Aprender
+# Aprende
Aquí están las secciones introductorias y los tutoriales para aprender **FastAPI**.
-Podrías considerar esto como un **libro**, un **curso**, la forma **oficial** y recomendada de aprender FastAPI. 😎
+Podrías considerar esto un **libro**, un **curso**, la forma **oficial** y recomendada de aprender FastAPI. 😎
diff --git a/docs/es/docs/newsletter.md b/docs/es/docs/newsletter.md
deleted file mode 100644
index f4dcfe155..000000000
--- a/docs/es/docs/newsletter.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# Boletín de Noticias de FastAPI y amigos
-
-
-
-
diff --git a/docs/es/docs/project-generation.md b/docs/es/docs/project-generation.md
new file mode 100644
index 000000000..559995151
--- /dev/null
+++ b/docs/es/docs/project-generation.md
@@ -0,0 +1,28 @@
+# Plantilla Full Stack FastAPI
+
+Las plantillas, aunque normalmente vienen con una configuración específica, están diseñadas para ser flexibles y personalizables. Esto te permite modificarlas y adaptarlas a los requisitos de tu proyecto, haciéndolas un excelente punto de partida. 🏁
+
+Puedes usar esta plantilla para comenzar, ya que incluye gran parte de la configuración inicial, seguridad, base de datos y algunos endpoints de API ya hechos para ti.
+
+Repositorio de GitHub: Plantilla Full Stack FastAPI
+
+## Plantilla Full Stack FastAPI - Tecnología y Funcionalidades
+
+- ⚡ [**FastAPI**](https://fastapi.tiangolo.com) para la API del backend en Python.
+ - 🧰 [SQLModel](https://sqlmodel.tiangolo.com) para las interacciones con bases de datos SQL en Python (ORM).
+ - 🔍 [Pydantic](https://docs.pydantic.dev), utilizado por FastAPI, para la validación de datos y gestión de configuraciones.
+ - 💾 [PostgreSQL](https://www.postgresql.org) como base de datos SQL.
+- 🚀 [React](https://react.dev) para el frontend.
+ - 💃 Usando TypeScript, hooks, [Vite](https://vitejs.dev), y otras partes de una stack moderna de frontend.
+ - 🎨 [Chakra UI](https://chakra-ui.com) para los componentes del frontend.
+ - 🤖 Un cliente de frontend generado automáticamente.
+ - 🧪 [Playwright](https://playwright.dev) para pruebas End-to-End.
+ - 🦇 Soporte para modo oscuro.
+- 🐋 [Docker Compose](https://www.docker.com) para desarrollo y producción.
+- 🔒 Hashing seguro de contraseñas por defecto.
+- 🔑 Autenticación con tokens JWT.
+- 📫 Recuperación de contraseñas basada en email.
+- ✅ Pruebas con [Pytest](https://pytest.org).
+- 📞 [Traefik](https://traefik.io) como proxy inverso / balanceador de carga.
+- 🚢 Instrucciones de despliegue usando Docker Compose, incluyendo cómo configurar un proxy Traefik frontend para manejar certificados HTTPS automáticos.
+- 🏭 CI (integración continua) y CD (despliegue continuo) basados en GitHub Actions.
diff --git a/docs/es/docs/python-types.md b/docs/es/docs/python-types.md
index 89edbb31e..769204f8f 100644
--- a/docs/es/docs/python-types.md
+++ b/docs/es/docs/python-types.md
@@ -1,29 +1,30 @@
-# Introducción a los Tipos de Python
+# Introducción a Tipos en Python
-**Python 3.6+** tiene soporte para "type hints" opcionales.
+Python tiene soporte para "anotaciones de tipos" opcionales (también llamadas "type hints").
-Estos **type hints** son una nueva sintaxis, desde Python 3.6+, que permite declarar el tipo de una variable.
+Estas **"anotaciones de tipos"** o type hints son una sintaxis especial que permite declarar el tipo de una variable.
-Usando las declaraciones de tipos para tus variables, los editores y otras herramientas pueden proveerte un soporte mejor.
+Al declarar tipos para tus variables, los editores y herramientas te pueden proporcionar un mejor soporte.
-Este es solo un **tutorial corto** sobre los Python type hints. Solo cubre lo mínimo necesario para usarlos con **FastAPI**... realmente es muy poco lo que necesitas.
+Este es solo un **tutorial rápido / recordatorio** sobre las anotaciones de tipos en Python. Cubre solo lo mínimo necesario para usarlas con **FastAPI**... que en realidad es muy poco.
-Todo **FastAPI** está basado en estos type hints, lo que le da muchas ventajas y beneficios.
+**FastAPI** se basa completamente en estas anotaciones de tipos, dándole muchas ventajas y beneficios.
-Pero, así nunca uses **FastAPI** te beneficiarás de aprender un poco sobre los type hints.
+Pero incluso si nunca usas **FastAPI**, te beneficiaría aprender un poco sobre ellas.
-!!! note "Nota"
- Si eres un experto en Python y ya lo sabes todo sobre los type hints, salta al siguiente capítulo.
+/// note | Nota
+
+Si eres un experto en Python, y ya sabes todo sobre las anotaciones de tipos, salta al siguiente capítulo.
+
+///
## Motivación
Comencemos con un ejemplo simple:
-```Python
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py *}
-Llamar este programa nos muestra el siguiente output:
+Llamar a este programa genera:
```
John Doe
@@ -31,39 +32,37 @@ John Doe
La función hace lo siguiente:
-* Toma un `first_name` y un `last_name`.
-* Convierte la primera letra de cada uno en una letra mayúscula con `title()`.
-* Las concatena con un espacio en la mitad.
+* Toma un `first_name` y `last_name`.
+* Convierte la primera letra de cada uno a mayúsculas con `title()`.
+* Concatena ambos con un espacio en el medio.
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py hl[2] *}
### Edítalo
Es un programa muy simple.
-Ahora, imagina que lo estás escribiendo desde ceros.
+Pero ahora imagina que lo escribieras desde cero.
-En algún punto habrías comenzado con la definición de la función, tenías los parámetros listos...
+En algún momento habrías empezado la definición de la función, tenías los parámetros listos...
-Pero, luego tienes que llamar "ese método que convierte la primera letra en una mayúscula".
+Pero luego tienes que llamar "ese método que convierte la primera letra a mayúscula".
-Era `upper`? O era `uppercase`? `first_uppercase`? `capitalize`?
+¿Era `upper`? ¿Era `uppercase`? `first_uppercase`? `capitalize`?
-Luego lo intentas con el viejo amigo de los programadores, el auto-completado del editor.
+Entonces, pruebas con el amigo del viejo programador, el autocompletado del editor.
-Escribes el primer parámetro de la función `first_name`, luego un punto (`.`) y luego presionas `Ctrl+Space` para iniciar el auto-completado.
+Escribes el primer parámetro de la función, `first_name`, luego un punto (`.`) y luego presionas `Ctrl+Espacio` para activar el autocompletado.
-Tristemente, no obtienes nada útil:
+Pero, tristemente, no obtienes nada útil:
-
+
-### Añade tipos
+### Añadir tipos
-Vamos a modificar una única línea de la versión previa.
+Modifiquemos una sola línea de la versión anterior.
-Vamos a cambiar exactamente este fragmento, los parámetros de la función, de:
+Cambiaremos exactamente este fragmento, los parámetros de la función, de:
```Python
first_name, last_name
@@ -77,210 +76,501 @@ a:
Eso es todo.
-Esos son los "type hints":
+Esas son las "anotaciones de tipos":
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial002.py!}
-```
+{* ../../docs_src/python_types/tutorial002.py hl[1] *}
-No es lo mismo a declarar valores por defecto, como sería con:
+Eso no es lo mismo que declarar valores predeterminados como sería con:
```Python
first_name="john", last_name="doe"
```
-Es algo diferente.
+Es una cosa diferente.
-Estamos usando los dos puntos (`:`), no un símbolo de igual (`=`).
+Estamos usando dos puntos (`:`), no igualdades (`=`).
-Añadir los type hints normalmente no cambia lo que sucedería si ellos no estuviesen presentes.
+Y agregar anotaciones de tipos normalmente no cambia lo que sucede de lo que ocurriría sin ellas.
-Pero ahora imagina que nuevamente estás creando la función, pero con los type hints.
+Pero ahora, imagina que nuevamente estás en medio de la creación de esa función, pero con anotaciones de tipos.
-En el mismo punto intentas iniciar el auto-completado con `Ctrl+Space` y ves:
+En el mismo punto, intentas activar el autocompletado con `Ctrl+Espacio` y ves:
-
+
-Con esto puedes moverte hacia abajo viendo las opciones hasta que encuentras una que te suene:
+Con eso, puedes desplazarte, viendo las opciones, hasta que encuentres la que "te suene":
-
+
## Más motivación
-Mira esta función que ya tiene type hints:
+Revisa esta función, ya tiene anotaciones de tipos:
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial003.py!}
-```
+{* ../../docs_src/python_types/tutorial003.py hl[1] *}
-Como el editor conoce el tipo de las variables no solo obtienes auto-completado, si no que también obtienes chequeo de errores:
+Porque el editor conoce los tipos de las variables, no solo obtienes autocompletado, también obtienes chequeo de errores:
-
+
-Ahora que sabes que tienes que arreglarlo convierte `age` a un string con `str(age)`:
+Ahora sabes que debes corregirlo, convertir `age` a un string con `str(age)`:
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial004.py!}
-```
+{* ../../docs_src/python_types/tutorial004.py hl[2] *}
-## Declarando tipos
+## Declaración de tipos
-Acabas de ver el lugar principal para declarar los type hints. Como parámetros de las funciones.
+Acabas de ver el lugar principal para declarar anotaciones de tipos. Como parámetros de función.
-Este es también el lugar principal en que los usarías con **FastAPI**.
+Este también es el lugar principal donde los utilizarías con **FastAPI**.
### Tipos simples
-Puedes declarar todos los tipos estándar de Python, no solamente `str`.
+Puedes declarar todos los tipos estándar de Python, no solo `str`.
-Por ejemplo, puedes usar:
+Puedes usar, por ejemplo:
* `int`
* `float`
* `bool`
* `bytes`
+{* ../../docs_src/python_types/tutorial005.py hl[1] *}
+
+### Tipos genéricos con parámetros de tipo
+
+Hay algunas estructuras de datos que pueden contener otros valores, como `dict`, `list`, `set` y `tuple`. Y los valores internos también pueden tener su propio tipo.
+
+Estos tipos que tienen tipos internos se denominan tipos "**genéricos**". Y es posible declararlos, incluso con sus tipos internos.
+
+Para declarar esos tipos y los tipos internos, puedes usar el módulo estándar de Python `typing`. Existe específicamente para soportar estas anotaciones de tipos.
+
+#### Versiones más recientes de Python
+
+La sintaxis que utiliza `typing` es **compatible** con todas las versiones, desde Python 3.6 hasta las versiones más recientes, incluyendo Python 3.9, Python 3.10, etc.
+
+A medida que avanza Python, las **versiones más recientes** vienen con soporte mejorado para estas anotaciones de tipos y en muchos casos ni siquiera necesitarás importar y usar el módulo `typing` para declarar las anotaciones de tipos.
+
+Si puedes elegir una versión más reciente de Python para tu proyecto, podrás aprovechar esa simplicidad adicional.
+
+En toda la documentación hay ejemplos compatibles con cada versión de Python (cuando hay una diferencia).
+
+Por ejemplo, "**Python 3.6+**" significa que es compatible con Python 3.6 o superior (incluyendo 3.7, 3.8, 3.9, 3.10, etc). Y "**Python 3.9+**" significa que es compatible con Python 3.9 o superior (incluyendo 3.10, etc).
+
+Si puedes usar las **últimas versiones de Python**, utiliza los ejemplos para la última versión, esos tendrán la **mejor y más simple sintaxis**, por ejemplo, "**Python 3.10+**".
+
+#### Lista
+
+Por ejemplo, vamos a definir una variable para ser una `list` de `str`.
+
+//// tab | Python 3.9+
+
+Declara la variable, con la misma sintaxis de dos puntos (`:`).
+
+Como tipo, pon `list`.
+
+Como la lista es un tipo que contiene algunos tipos internos, los pones entre corchetes:
+
```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial005.py!}
+{!> ../../docs_src/python_types/tutorial006_py39.py!}
```
-### Tipos con sub-tipos
+////
-Existen algunas estructuras de datos que pueden contener otros valores, como `dict`, `list`, `set` y `tuple`. Los valores internos pueden tener su propio tipo también.
-
-Para declarar esos tipos y sub-tipos puedes usar el módulo estándar de Python `typing`.
-
-Él existe específicamente para dar soporte a este tipo de type hints.
-
-#### Listas
-
-Por ejemplo, vamos a definir una variable para que sea una `list` compuesta de `str`.
+//// tab | Python 3.8+
De `typing`, importa `List` (con una `L` mayúscula):
```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial006.py!}
+{!> ../../docs_src/python_types/tutorial006.py!}
```
-Declara la variable con la misma sintaxis de los dos puntos (`:`).
+Declara la variable, con la misma sintaxis de dos puntos (`:`).
-Pon `List` como el tipo.
+Como tipo, pon el `List` que importaste de `typing`.
-Como la lista es un tipo que permite tener un "sub-tipo" pones el sub-tipo en corchetes `[]`:
+Como la lista es un tipo que contiene algunos tipos internos, los pones entre corchetes:
```Python hl_lines="4"
-{!../../../docs_src/python_types/tutorial006.py!}
+{!> ../../docs_src/python_types/tutorial006.py!}
```
-Esto significa: la variable `items` es una `list` y cada uno de los ítems en esta lista es un `str`.
+////
-Con esta declaración tu editor puede proveerte soporte inclusive mientras está procesando ítems de la lista.
+/// info | Información
-Sin tipos el auto-completado en este tipo de estructura es casi imposible de lograr:
+Esos tipos internos en los corchetes se denominan "parámetros de tipo".
-
+En este caso, `str` es el parámetro de tipo pasado a `List` (o `list` en Python 3.9 y superior).
-Observa que la variable `item` es unos de los elementos en la lista `items`.
+///
-El editor aún sabe que es un `str` y provee soporte para ello.
+Eso significa: "la variable `items` es una `list`, y cada uno de los ítems en esta lista es un `str`".
-#### Tuples y Sets
+/// tip | Consejo
+
+Si usas Python 3.9 o superior, no tienes que importar `List` de `typing`, puedes usar el mismo tipo `list` regular en su lugar.
+
+///
+
+Al hacer eso, tu editor puede proporcionar soporte incluso mientras procesa elementos de la lista:
+
+
+
+Sin tipos, eso es casi imposible de lograr.
+
+Nota que la variable `item` es uno de los elementos en la lista `items`.
+
+Y aún así, el editor sabe que es un `str` y proporciona soporte para eso.
+
+#### Tuple y Set
Harías lo mismo para declarar `tuple`s y `set`s:
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial007.py!}
+//// tab | Python 3.9+
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial007_py39.py!}
```
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial007.py!}
+```
+
+////
+
Esto significa:
* La variable `items_t` es un `tuple` con 3 ítems, un `int`, otro `int`, y un `str`.
-* La variable `items_s` es un `set` y cada uno de sus ítems es de tipo `bytes`.
+* La variable `items_s` es un `set`, y cada uno de sus ítems es del tipo `bytes`.
-#### Diccionarios (Dicts)
+#### Dict
-Para definir un `dict` le pasas 2 sub-tipos separados por comas.
+Para definir un `dict`, pasas 2 parámetros de tipo, separados por comas.
-El primer sub-tipo es para los keys del `dict`.
+El primer parámetro de tipo es para las claves del `dict`.
-El segundo sub-tipo es para los valores del `dict`:
+El segundo parámetro de tipo es para los valores del `dict`:
+
+//// tab | Python 3.9+
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial008.py!}
+{!> ../../docs_src/python_types/tutorial008.py!}
```
+////
+
Esto significa:
* La variable `prices` es un `dict`:
- * Los keys de este `dict` son de tipo `str` (Digamos que son el nombre de cada ítem).
- * Los valores de este `dict` son de tipo `float` (Digamos que son el precio de cada ítem).
+ * Las claves de este `dict` son del tipo `str` (digamos, el nombre de cada ítem).
+ * Los valores de este `dict` son del tipo `float` (digamos, el precio de cada ítem).
+
+#### Union
+
+Puedes declarar que una variable puede ser cualquier de **varios tipos**, por ejemplo, un `int` o un `str`.
+
+En Python 3.6 y posterior (incluyendo Python 3.10) puedes usar el tipo `Union` de `typing` y poner dentro de los corchetes los posibles tipos a aceptar.
+
+En Python 3.10 también hay una **nueva sintaxis** donde puedes poner los posibles tipos separados por una barra vertical (`|`).
+
+//// tab | Python 3.10+
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008b_py310.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial008b.py!}
+```
+
+////
+
+En ambos casos, esto significa que `item` podría ser un `int` o un `str`.
+
+#### Posiblemente `None`
+
+Puedes declarar que un valor podría tener un tipo, como `str`, pero que también podría ser `None`.
+
+En Python 3.6 y posteriores (incluyendo Python 3.10) puedes declararlo importando y usando `Optional` del módulo `typing`.
+
+```Python hl_lines="1 4"
+{!../../docs_src/python_types/tutorial009.py!}
+```
+
+Usar `Optional[str]` en lugar de solo `str` te permitirá al editor ayudarte a detectar errores donde podrías estar asumiendo que un valor siempre es un `str`, cuando en realidad también podría ser `None`.
+
+`Optional[Something]` es realmente un atajo para `Union[Something, None]`, son equivalentes.
+
+Esto también significa que en Python 3.10, puedes usar `Something | None`:
+
+//// tab | Python 3.10+
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial009_py310.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial009.py!}
+```
+
+////
+
+//// tab | Python 3.8+ alternative
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial009b.py!}
+```
+
+////
+
+#### Uso de `Union` u `Optional`
+
+Si estás usando una versión de Python inferior a 3.10, aquí tienes un consejo desde mi punto de vista muy **subjetivo**:
+
+* 🚨 Evita usar `Optional[SomeType]`
+* En su lugar ✨ **usa `Union[SomeType, None]`** ✨.
+
+Ambos son equivalentes y debajo son lo mismo, pero recomendaría `Union` en lugar de `Optional` porque la palabra "**opcional**" parecería implicar que el valor es opcional, y en realidad significa "puede ser `None`", incluso si no es opcional y aún es requerido.
+
+Creo que `Union[SomeType, None]` es más explícito sobre lo que significa.
+
+Se trata solo de las palabras y nombres. Pero esas palabras pueden afectar cómo tú y tus compañeros de equipo piensan sobre el código.
+
+Como ejemplo, tomemos esta función:
+
+{* ../../docs_src/python_types/tutorial009c.py hl[1,4] *}
+
+El parámetro `name` está definido como `Optional[str]`, pero **no es opcional**, no puedes llamar a la función sin el parámetro:
+
+```Python
+say_hi() # ¡Oh, no, esto lanza un error! 😱
+```
+
+El parámetro `name` sigue siendo **requerido** (no *opcional*) porque no tiene un valor predeterminado. Aún así, `name` acepta `None` como valor:
+
+```Python
+say_hi(name=None) # Esto funciona, None es válido 🎉
+```
+
+La buena noticia es que, una vez que estés en Python 3.10, no tendrás que preocuparte por eso, ya que podrás simplemente usar `|` para definir uniones de tipos:
+
+{* ../../docs_src/python_types/tutorial009c_py310.py hl[1,4] *}
+
+Y entonces no tendrás que preocuparte por nombres como `Optional` y `Union`. 😎
+
+#### Tipos genéricos
+
+Estos tipos que toman parámetros de tipo en corchetes se llaman **Tipos Genéricos** o **Genéricos**, por ejemplo:
+
+//// tab | Python 3.10+
+
+Puedes usar los mismos tipos integrados como genéricos (con corchetes y tipos dentro):
+
+* `list`
+* `tuple`
+* `set`
+* `dict`
+
+Y lo mismo que con Python 3.8, desde el módulo `typing`:
+
+* `Union`
+* `Optional` (lo mismo que con Python 3.8)
+* ...y otros.
+
+En Python 3.10, como alternativa a usar los genéricos `Union` y `Optional`, puedes usar la barra vertical (`|`) para declarar uniones de tipos, eso es mucho mejor y más simple.
+
+////
+
+//// tab | Python 3.9+
+
+Puedes usar los mismos tipos integrados como genéricos (con corchetes y tipos dentro):
+
+* `list`
+* `tuple`
+* `set`
+* `dict`
+
+Y lo mismo que con Python 3.8, desde el módulo `typing`:
+
+* `Union`
+* `Optional`
+* ...y otros.
+
+////
+
+//// tab | Python 3.8+
+
+* `List`
+* `Tuple`
+* `Set`
+* `Dict`
+* `Union`
+* `Optional`
+* ...y otros.
+
+////
### Clases como tipos
También puedes declarar una clase como el tipo de una variable.
-Digamos que tienes una clase `Person`con un nombre:
+Digamos que tienes una clase `Person`, con un nombre:
-```Python hl_lines="1-3"
-{!../../../docs_src/python_types/tutorial009.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
-Entonces puedes declarar una variable que sea de tipo `Person`:
+Luego puedes declarar una variable para que sea de tipo `Person`:
-```Python hl_lines="6"
-{!../../../docs_src/python_types/tutorial009.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[6] *}
-Una vez más tendrás todo el soporte del editor:
+Y luego, nuevamente, obtienes todo el soporte del editor:
-
+
-## Modelos de Pydantic
+Nota que esto significa "`one_person` es una **instance** de la clase `Person`".
-Pydantic es una library de Python para llevar a cabo validación de datos.
+No significa "`one_person` es la **clase** llamada `Person`".
-Tú declaras la "forma" de los datos mediante clases con atributos.
+## Modelos Pydantic
-Cada atributo tiene un tipo.
+Pydantic es un paquete de Python para realizar la validación de datos.
-Luego creas un instance de esa clase con algunos valores y Pydantic validará los valores, los convertirá al tipo apropiado (si ese es el caso) y te dará un objeto con todos los datos.
+Declaras la "forma" de los datos como clases con atributos.
-Y obtienes todo el soporte del editor con el objeto resultante.
+Y cada atributo tiene un tipo.
-Tomado de la documentación oficial de Pydantic:
+Entonces creas un instance de esa clase con algunos valores y validará los valores, los convertirá al tipo adecuado (si es el caso) y te dará un objeto con todos los datos.
+
+Y obtienes todo el soporte del editor con ese objeto resultante.
+
+Un ejemplo de la documentación oficial de Pydantic:
+
+//// tab | Python 3.10+
```Python
-{!../../../docs_src/python_types/tutorial010.py!}
+{!> ../../docs_src/python_types/tutorial011_py310.py!}
```
-!!! info "Información"
- Para aprender más sobre Pydantic mira su documentación.
+////
-**FastAPI** está todo basado en Pydantic.
+//// tab | Python 3.9+
-Vas a ver mucho más de esto en práctica en el [Tutorial - User Guide](tutorial/index.md){.internal-link target=_blank}.
+```Python
+{!> ../../docs_src/python_types/tutorial011_py39.py!}
+```
-## Type hints en **FastAPI**
+////
-**FastAPI** aprovecha estos type hints para hacer varias cosas.
+//// tab | Python 3.8+
-Con **FastAPI** declaras los parámetros con type hints y obtienes:
+```Python
+{!> ../../docs_src/python_types/tutorial011.py!}
+```
-* **Soporte en el editor**.
-* **Type checks**.
+////
+
+/// info | Información
+
+Para saber más sobre Pydantic, revisa su documentación.
+
+///
+
+**FastAPI** está completamente basado en Pydantic.
+
+Verás mucho más de todo esto en práctica en el [Tutorial - Guía del Usuario](tutorial/index.md){.internal-link target=_blank}.
+
+/// tip | Consejo
+
+Pydantic tiene un comportamiento especial cuando utilizas `Optional` o `Union[Something, None]` sin un valor por defecto, puedes leer más sobre ello en la documentación de Pydantic sobre Required Optional fields.
+
+///
+
+## Anotaciones de tipos con metadata
+
+Python también tiene una funcionalidad que permite poner **metadata adicional** en estas anotaciones de tipos usando `Annotated`.
+
+//// tab | Python 3.9+
+
+En Python 3.9, `Annotated` es parte de la librería estándar, así que puedes importarlo desde `typing`.
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial013_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+En versiones por debajo de Python 3.9, importas `Annotated` de `typing_extensions`.
+
+Ya estará instalado con **FastAPI**.
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial013.py!}
+```
+
+////
+
+Python en sí no hace nada con este `Annotated`. Y para los editores y otras herramientas, el tipo sigue siendo `str`.
+
+Pero puedes usar este espacio en `Annotated` para proporcionar a **FastAPI** metadata adicional sobre cómo quieres que se comporte tu aplicación.
+
+Lo importante a recordar es que **el primer *parámetro de tipo*** que pasas a `Annotated` es el **tipo real**. El resto es solo metadata para otras herramientas.
+
+Por ahora, solo necesitas saber que `Annotated` existe, y que es Python estándar. 😎
+
+Luego verás lo **poderoso** que puede ser.
+
+/// tip | Consejo
+
+El hecho de que esto sea **Python estándar** significa que seguirás obteniendo la **mejor experiencia de desarrollador posible** en tu editor, con las herramientas que usas para analizar y refactorizar tu código, etc. ✨
+
+Y también que tu código será muy compatible con muchas otras herramientas y paquetes de Python. 🚀
+
+///
+
+## Anotaciones de tipos en **FastAPI**
+
+**FastAPI** aprovecha estas anotaciones de tipos para hacer varias cosas.
+
+Con **FastAPI** declaras parámetros con anotaciones de tipos y obtienes:
+
+* **Soporte del editor**.
+* **Chequeo de tipos**.
...y **FastAPI** usa las mismas declaraciones para:
-* **Definir requerimientos**: desde request path parameters, query parameters, headers, bodies, dependencies, etc.
-* **Convertir datos**: desde el request al tipo requerido.
-* **Validar datos**: viniendo de cada request:
+* **Definir requerimientos**: de parámetros de path de la request, parámetros de query, headers, bodies, dependencias, etc.
+* **Convertir datos**: de la request al tipo requerido.
+* **Validar datos**: provenientes de cada request:
* Generando **errores automáticos** devueltos al cliente cuando los datos son inválidos.
* **Documentar** la API usando OpenAPI:
- * que en su caso es usada por las interfaces de usuario de la documentación automática e interactiva.
+ * Que luego es usada por las interfaces de documentación interactiva automática.
-Puede que todo esto suene abstracto. Pero no te preocupes que todo lo verás en acción en el [Tutorial - User Guide](tutorial/index.md){.internal-link target=_blank}.
+Todo esto puede sonar abstracto. No te preocupes. Verás todo esto en acción en el [Tutorial - Guía del Usuario](tutorial/index.md){.internal-link target=_blank}.
-Lo importante es que usando los tipos de Python estándar en un único lugar (en vez de añadir más clases, decorator, etc.) **FastAPI** hará mucho del trabajo por ti.
+Lo importante es que al usar tipos estándar de Python, en un solo lugar (en lugar de agregar más clases, decoradores, etc.), **FastAPI** hará gran parte del trabajo por ti.
-!!! info "Información"
- Si ya pasaste por todo el tutorial y volviste a la sección de los tipos, una buena referencia es la "cheat sheet" de `mypy`.
+/// info | Información
+
+Si ya revisaste todo el tutorial y volviste para ver más sobre tipos, un buen recurso es la "cheat sheet" de `mypy`.
+
+///
diff --git a/docs/es/docs/tutorial/background-tasks.md b/docs/es/docs/tutorial/background-tasks.md
new file mode 100644
index 000000000..3fe961e41
--- /dev/null
+++ b/docs/es/docs/tutorial/background-tasks.md
@@ -0,0 +1,84 @@
+# Tareas en Segundo Plano
+
+Puedes definir tareas en segundo plano para que se ejecuten *después* de devolver un response.
+
+Esto es útil para operaciones que necesitan ocurrir después de un request, pero para las que el cliente realmente no necesita esperar a que la operación termine antes de recibir el response.
+
+Esto incluye, por ejemplo:
+
+* Notificaciones por email enviadas después de realizar una acción:
+ * Como conectarse a un servidor de email y enviar un email tiende a ser "lento" (varios segundos), puedes devolver el response de inmediato y enviar la notificación por email en segundo plano.
+* Procesamiento de datos:
+ * Por ejemplo, supongamos que recibes un archivo que debe pasar por un proceso lento, puedes devolver un response de "Accepted" (HTTP 202) y procesar el archivo en segundo plano.
+
+## Usando `BackgroundTasks`
+
+Primero, importa `BackgroundTasks` y define un parámetro en tu *path operation function* con una declaración de tipo de `BackgroundTasks`:
+
+{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *}
+
+**FastAPI** creará el objeto de tipo `BackgroundTasks` por ti y lo pasará como ese parámetro.
+
+## Crear una función de tarea
+
+Crea una función para que se ejecute como la tarea en segundo plano.
+
+Es solo una función estándar que puede recibir parámetros.
+
+Puede ser una función `async def` o una función normal `def`, **FastAPI** sabrá cómo manejarla correctamente.
+
+En este caso, la función de tarea escribirá en un archivo (simulando el envío de un email).
+
+Y como la operación de escritura no usa `async` y `await`, definimos la función con un `def` normal:
+
+{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *}
+
+## Agregar la tarea en segundo plano
+
+Dentro de tu *path operation function*, pasa tu función de tarea al objeto de *background tasks* con el método `.add_task()`:
+
+{* ../../docs_src/background_tasks/tutorial001.py hl[14] *}
+
+`.add_task()` recibe como argumentos:
+
+* Una función de tarea para ejecutar en segundo plano (`write_notification`).
+* Cualquier secuencia de argumentos que deba pasarse a la función de tarea en orden (`email`).
+* Cualquier argumento de palabras clave que deba pasarse a la función de tarea (`message="some notification"`).
+
+## Inyección de Dependencias
+
+Usar `BackgroundTasks` también funciona con el sistema de inyección de dependencias, puedes declarar un parámetro de tipo `BackgroundTasks` en varios niveles: en una *path operation function*, en una dependencia (dependable), en una sub-dependencia, etc.
+
+**FastAPI** sabe qué hacer en cada caso y cómo reutilizar el mismo objeto, de modo que todas las tareas en segundo plano se combinan y ejecutan en segundo plano después:
+
+{* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *}
+
+En este ejemplo, los mensajes se escribirán en el archivo `log.txt` *después* de que se envíe el response.
+
+Si hay un query en el request, se escribirá en el log en una tarea en segundo plano.
+
+Y luego otra tarea en segundo plano generada en la *path operation function* escribirá un mensaje usando el parámetro de path `email`.
+
+## Detalles Técnicos
+
+La clase `BackgroundTasks` proviene directamente de `starlette.background`.
+
+Se importa/incluye directamente en FastAPI para que puedas importarla desde `fastapi` y evitar importar accidentalmente la alternativa `BackgroundTask` (sin la `s` al final) de `starlette.background`.
+
+Al usar solo `BackgroundTasks` (y no `BackgroundTask`), es posible usarla como un parámetro de *path operation function* y dejar que **FastAPI** maneje el resto por ti, tal como cuando usas el objeto `Request` directamente.
+
+Todavía es posible usar `BackgroundTask` solo en FastAPI, pero debes crear el objeto en tu código y devolver una `Response` de Starlette incluyéndolo.
+
+Puedes ver más detalles en la documentación oficial de Starlette sobre Background Tasks.
+
+## Advertencia
+
+Si necesitas realizar una computación intensa en segundo plano y no necesariamente necesitas que se ejecute por el mismo proceso (por ejemplo, no necesitas compartir memoria, variables, etc.), podrías beneficiarte del uso de otras herramientas más grandes como Celery.
+
+Tienden a requerir configuraciones más complejas, un gestor de cola de mensajes/trabajos, como RabbitMQ o Redis, pero te permiten ejecutar tareas en segundo plano en múltiples procesos, y especialmente, en múltiples servidores.
+
+Pero si necesitas acceder a variables y objetos de la misma app de **FastAPI**, o necesitas realizar pequeñas tareas en segundo plano (como enviar una notificación por email), simplemente puedes usar `BackgroundTasks`.
+
+## Resumen
+
+Importa y usa `BackgroundTasks` con parámetros en *path operation functions* y dependencias para agregar tareas en segundo plano.
diff --git a/docs/es/docs/tutorial/bigger-applications.md b/docs/es/docs/tutorial/bigger-applications.md
new file mode 100644
index 000000000..c3d8f0686
--- /dev/null
+++ b/docs/es/docs/tutorial/bigger-applications.md
@@ -0,0 +1,554 @@
+# Aplicaciones más grandes - Múltiples archivos
+
+Si estás construyendo una aplicación o una API web, rara vez podrás poner todo en un solo archivo.
+
+**FastAPI** proporciona una herramienta conveniente para estructurar tu aplicación manteniendo toda la flexibilidad.
+
+/// info | Información
+
+Si vienes de Flask, esto sería el equivalente a los Blueprints de Flask.
+
+///
+
+## Un ejemplo de estructura de archivos
+
+Digamos que tienes una estructura de archivos como esta:
+
+```
+.
+├── app
+│ ├── __init__.py
+│ ├── main.py
+│ ├── dependencies.py
+│ └── routers
+│ │ ├── __init__.py
+│ │ ├── items.py
+│ │ └── users.py
+│ └── internal
+│ ├── __init__.py
+│ └── admin.py
+```
+
+/// tip | Consejo
+
+Hay varios archivos `__init__.py`: uno en cada directorio o subdirectorio.
+
+Esto es lo que permite importar código de un archivo a otro.
+
+Por ejemplo, en `app/main.py` podrías tener una línea como:
+
+```
+from app.routers import items
+```
+
+///
+
+* El directorio `app` contiene todo. Y tiene un archivo vacío `app/__init__.py`, por lo que es un "paquete de Python" (una colección de "módulos de Python"): `app`.
+* Contiene un archivo `app/main.py`. Como está dentro de un paquete de Python (un directorio con un archivo `__init__.py`), es un "módulo" de ese paquete: `app.main`.
+* También hay un archivo `app/dependencies.py`, al igual que `app/main.py`, es un "módulo": `app.dependencies`.
+* Hay un subdirectorio `app/routers/` con otro archivo `__init__.py`, por lo que es un "subpaquete de Python": `app.routers`.
+* El archivo `app/routers/items.py` está dentro de un paquete, `app/routers/`, por lo que es un submódulo: `app.routers.items`.
+* Lo mismo con `app/routers/users.py`, es otro submódulo: `app.routers.users`.
+* También hay un subdirectorio `app/internal/` con otro archivo `__init__.py`, por lo que es otro "subpaquete de Python": `app.internal`.
+* Y el archivo `app/internal/admin.py` es otro submódulo: `app.internal.admin`.
+
+
+
+## Incluir el mismo router múltiples veces con diferentes `prefix`
+
+También puedes usar `.include_router()` múltiples veces con el *mismo* router usando diferentes prefijos.
+
+Esto podría ser útil, por ejemplo, para exponer la misma API bajo diferentes prefijos, por ejemplo, `/api/v1` y `/api/latest`.
+
+Este es un uso avanzado que quizás no necesites realmente, pero está allí en caso de que lo necesites.
+
+## Incluir un `APIRouter` en otro
+
+De la misma manera que puedes incluir un `APIRouter` en una aplicación `FastAPI`, puedes incluir un `APIRouter` en otro `APIRouter` usando:
+
+```Python
+router.include_router(other_router)
+```
+
+Asegúrate de hacerlo antes de incluir `router` en la aplicación de `FastAPI`, para que las *path operations* de `other_router` también se incluyan.
diff --git a/docs/es/docs/tutorial/body-fields.md b/docs/es/docs/tutorial/body-fields.md
new file mode 100644
index 000000000..d07d214ec
--- /dev/null
+++ b/docs/es/docs/tutorial/body-fields.md
@@ -0,0 +1,60 @@
+# Body - Campos
+
+De la misma manera que puedes declarar validaciones adicionales y metadatos en los parámetros de las *path operation function* con `Query`, `Path` y `Body`, puedes declarar validaciones y metadatos dentro de los modelos de Pydantic usando `Field` de Pydantic.
+
+## Importar `Field`
+
+Primero, tienes que importarlo:
+
+{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[4] *}
+
+/// warning | Advertencia
+
+Fíjate que `Field` se importa directamente desde `pydantic`, no desde `fastapi` como el resto (`Query`, `Path`, `Body`, etc).
+
+///
+
+## Declarar atributos del modelo
+
+Después puedes utilizar `Field` con los atributos del modelo:
+
+{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[11:14] *}
+
+`Field` funciona de la misma manera que `Query`, `Path` y `Body`, tiene todos los mismos parámetros, etc.
+
+/// note | Detalles técnicos
+
+En realidad, `Query`, `Path` y otros que verás a continuación crean objetos de subclases de una clase común `Param`, que es a su vez una subclase de la clase `FieldInfo` de Pydantic.
+
+Y `Field` de Pydantic también regresa una instance de `FieldInfo`.
+
+`Body` también devuelve objetos de una subclase de `FieldInfo` directamente. Y hay otros que verás más adelante que son subclases de la clase `Body`.
+
+Recuerda que cuando importas `Query`, `Path`, y otros desde `fastapi`, en realidad son funciones que devuelven clases especiales.
+
+///
+
+/// tip | Consejo
+
+Observa cómo cada atributo del modelo con un tipo, un valor por defecto y `Field` tiene la misma estructura que un parámetro de una *path operation function*, con `Field` en lugar de `Path`, `Query` y `Body`.
+
+///
+
+## Agregar información extra
+
+Puedes declarar información extra en `Field`, `Query`, `Body`, etc. Y será incluida en el JSON Schema generado.
+
+Aprenderás más sobre cómo agregar información extra más adelante en la documentación, cuando aprendamos a declarar ejemplos.
+
+/// warning | Advertencia
+
+Las claves extra pasadas a `Field` también estarán presentes en el esquema de OpenAPI resultante para tu aplicación.
+Como estas claves no necesariamente tienen que ser parte de la especificación de OpenAPI, algunas herramientas de OpenAPI, por ejemplo [el validador de OpenAPI](https://validator.swagger.io/), podrían no funcionar con tu esquema generado.
+
+///
+
+## Resumen
+
+Puedes utilizar `Field` de Pydantic para declarar validaciones adicionales y metadatos para los atributos del modelo.
+
+También puedes usar los argumentos de palabra clave extra para pasar metadatos adicionales del JSON Schema.
diff --git a/docs/es/docs/tutorial/body-multiple-params.md b/docs/es/docs/tutorial/body-multiple-params.md
new file mode 100644
index 000000000..df6560b62
--- /dev/null
+++ b/docs/es/docs/tutorial/body-multiple-params.md
@@ -0,0 +1,173 @@
+# Cuerpo - Múltiples Parámetros
+
+Ahora que hemos visto cómo usar `Path` y `Query`, veamos usos más avanzados de las declaraciones del request body.
+
+## Mezclar `Path`, `Query` y parámetros del cuerpo
+
+Primero, por supuesto, puedes mezclar las declaraciones de parámetros de `Path`, `Query` y del request body libremente y **FastAPI** sabrá qué hacer.
+
+Y también puedes declarar parámetros del cuerpo como opcionales, estableciendo el valor predeterminado a `None`:
+
+{* ../../docs_src/body_multiple_params/tutorial001_an_py310.py hl[18:20] *}
+
+## Múltiples parámetros del cuerpo
+
+/// note | Nota
+
+Ten en cuenta que, en este caso, el `item` que se tomaría del cuerpo es opcional. Ya que tiene un valor por defecto de `None`.
+
+///
+
+## Múltiples parámetros del cuerpo
+
+En el ejemplo anterior, las *path operations* esperarían un cuerpo JSON con los atributos de un `Item`, como:
+
+```JSON
+{
+ "name": "Foo",
+ "description": "The pretender",
+ "price": 42.0,
+ "tax": 3.2
+}
+```
+
+Pero también puedes declarar múltiples parámetros del cuerpo, por ejemplo `item` y `user`:
+
+{* ../../docs_src/body_multiple_params/tutorial002_py310.py hl[20] *}
+
+En este caso, **FastAPI** notará que hay más de un parámetro del cuerpo en la función (hay dos parámetros que son modelos de Pydantic).
+
+Entonces, usará los nombres de los parámetros como claves (nombres de campo) en el cuerpo, y esperará un cuerpo como:
+
+```JSON
+{
+ "item": {
+ "name": "Foo",
+ "description": "The pretender",
+ "price": 42.0,
+ "tax": 3.2
+ },
+ "user": {
+ "username": "dave",
+ "full_name": "Dave Grohl"
+ }
+}
+```
+
+/// note | Nota
+
+Ten en cuenta que aunque el `item` se declaró de la misma manera que antes, ahora se espera que esté dentro del cuerpo con una clave `item`.
+
+///
+
+**FastAPI** hará la conversión automática del request, de modo que el parámetro `item` reciba su contenido específico y lo mismo para `user`.
+
+Realizará la validación de los datos compuestos, y los documentará así para el esquema de OpenAPI y la documentación automática.
+
+## Valores singulares en el cuerpo
+
+De la misma manera que hay un `Query` y `Path` para definir datos extra para parámetros de query y path, **FastAPI** proporciona un equivalente `Body`.
+
+Por ejemplo, ampliando el modelo anterior, podrías decidir que deseas tener otra clave `importance` en el mismo cuerpo, además de `item` y `user`.
+
+Si lo declaras tal cual, debido a que es un valor singular, **FastAPI** asumirá que es un parámetro de query.
+
+Pero puedes instruir a **FastAPI** para que lo trate como otra clave del cuerpo usando `Body`:
+
+{* ../../docs_src/body_multiple_params/tutorial003_an_py310.py hl[23] *}
+
+En este caso, **FastAPI** esperará un cuerpo como:
+
+```JSON
+{
+ "item": {
+ "name": "Foo",
+ "description": "The pretender",
+ "price": 42.0,
+ "tax": 3.2
+ },
+ "user": {
+ "username": "dave",
+ "full_name": "Dave Grohl"
+ },
+ "importance": 5
+}
+```
+
+Nuevamente, convertirá los tipos de datos, validará, documentará, etc.
+
+## Múltiples parámetros de cuerpo y query
+
+Por supuesto, también puedes declarar parámetros adicionales de query siempre que lo necesites, además de cualquier parámetro del cuerpo.
+
+Como, por defecto, los valores singulares se interpretan como parámetros de query, no tienes que añadir explícitamente un `Query`, solo puedes hacer:
+
+```Python
+q: Union[str, None] = None
+```
+
+O en Python 3.10 y superior:
+
+```Python
+q: str | None = None
+```
+
+Por ejemplo:
+
+{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[28] *}
+
+/// info | Información
+
+`Body` también tiene todos los mismos parámetros de validación y metadatos extras que `Query`, `Path` y otros que verás luego.
+
+///
+
+## Embeber un solo parámetro de cuerpo
+
+Supongamos que solo tienes un único parámetro de cuerpo `item` de un modelo Pydantic `Item`.
+
+Por defecto, **FastAPI** esperará su cuerpo directamente.
+
+Pero si deseas que espere un JSON con una clave `item` y dentro de ella los contenidos del modelo, como lo hace cuando declaras parámetros de cuerpo extra, puedes usar el parámetro especial `Body` `embed`:
+
+```Python
+item: Item = Body(embed=True)
+```
+
+como en:
+
+{* ../../docs_src/body_multiple_params/tutorial005_an_py310.py hl[17] *}
+
+En este caso, **FastAPI** esperará un cuerpo como:
+
+```JSON hl_lines="2"
+{
+ "item": {
+ "name": "Foo",
+ "description": "The pretender",
+ "price": 42.0,
+ "tax": 3.2
+ }
+}
+```
+
+en lugar de:
+
+```JSON
+{
+ "name": "Foo",
+ "description": "The pretender",
+ "price": 42.0,
+ "tax": 3.2
+}
+```
+
+## Resumen
+
+Puedes añadir múltiples parámetros de cuerpo a tu *path operation function*, aunque un request solo puede tener un único cuerpo.
+
+Pero **FastAPI** lo manejará, te dará los datos correctos en tu función, y validará y documentará el esquema correcto en la *path operation*.
+
+También puedes declarar valores singulares para ser recibidos como parte del cuerpo.
+
+Y puedes instruir a **FastAPI** para embeber el cuerpo en una clave incluso cuando solo hay un único parámetro declarado.
diff --git a/docs/es/docs/tutorial/body-nested-models.md b/docs/es/docs/tutorial/body-nested-models.md
new file mode 100644
index 000000000..5b4cfc14c
--- /dev/null
+++ b/docs/es/docs/tutorial/body-nested-models.md
@@ -0,0 +1,247 @@
+# Cuerpo - Modelos Anidados
+
+Con **FastAPI**, puedes definir, validar, documentar y usar modelos anidados de manera arbitraria (gracias a Pydantic).
+
+## Campos de lista
+
+Puedes definir un atributo como un subtipo. Por ejemplo, una `list` en Python:
+
+{* ../../docs_src/body_nested_models/tutorial001_py310.py hl[12] *}
+
+Esto hará que `tags` sea una lista, aunque no declare el tipo de los elementos de la lista.
+
+## Campos de lista con parámetro de tipo
+
+Pero Python tiene una forma específica de declarar listas con tipos internos, o "parámetros de tipo":
+
+### Importar `List` de typing
+
+En Python 3.9 y superior, puedes usar el `list` estándar para declarar estas anotaciones de tipo como veremos a continuación. 💡
+
+Pero en versiones de Python anteriores a 3.9 (desde 3.6 en adelante), primero necesitas importar `List` del módulo `typing` estándar de Python:
+
+{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *}
+
+### Declarar una `list` con un parámetro de tipo
+
+Para declarar tipos que tienen parámetros de tipo (tipos internos), como `list`, `dict`, `tuple`:
+
+* Si estás en una versión de Python inferior a 3.9, importa su versión equivalente del módulo `typing`
+* Pasa el/los tipo(s) interno(s) como "parámetros de tipo" usando corchetes: `[` y `]`
+
+En Python 3.9 sería:
+
+```Python
+my_list: list[str]
+```
+
+En versiones de Python anteriores a 3.9, sería:
+
+```Python
+from typing import List
+
+my_list: List[str]
+```
+
+Eso es toda la sintaxis estándar de Python para declaraciones de tipo.
+
+Usa esa misma sintaxis estándar para atributos de modelos con tipos internos.
+
+Así, en nuestro ejemplo, podemos hacer que `tags` sea específicamente una "lista de strings":
+
+{* ../../docs_src/body_nested_models/tutorial002_py310.py hl[12] *}
+
+## Tipos de conjunto
+
+Pero luego pensamos en ello, y nos damos cuenta de que los tags no deberían repetirse, probablemente serían strings únicos.
+
+Y Python tiene un tipo de datos especial para conjuntos de elementos únicos, el `set`.
+
+Entonces podemos declarar `tags` como un conjunto de strings:
+
+{* ../../docs_src/body_nested_models/tutorial003_py310.py hl[12] *}
+
+Con esto, incluso si recibes un request con datos duplicados, se convertirá en un conjunto de elementos únicos.
+
+Y siempre que emitas esos datos, incluso si la fuente tenía duplicados, se emitirá como un conjunto de elementos únicos.
+
+Y también se anotará/documentará en consecuencia.
+
+## Modelos Anidados
+
+Cada atributo de un modelo Pydantic tiene un tipo.
+
+Pero ese tipo puede ser en sí mismo otro modelo Pydantic.
+
+Así que, puedes declarar "objetos" JSON anidados profundamente con nombres de atributos específicos, tipos y validaciones.
+
+Todo eso, de manera arbitraria.
+
+### Definir un submodelo
+
+Por ejemplo, podemos definir un modelo `Image`:
+
+{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[7:9] *}
+
+### Usar el submodelo como tipo
+
+Y luego podemos usarlo como el tipo de un atributo:
+
+{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[18] *}
+
+Esto significaría que **FastAPI** esperaría un cuerpo similar a:
+
+```JSON
+{
+ "name": "Foo",
+ "description": "The pretender",
+ "price": 42.0,
+ "tax": 3.2,
+ "tags": ["rock", "metal", "bar"],
+ "image": {
+ "url": "http://example.com/baz.jpg",
+ "name": "The Foo live"
+ }
+}
+```
+
+Nuevamente, haciendo solo esa declaración, con **FastAPI** obtienes:
+
+* Soporte de editor (autocompletado, etc.), incluso para modelos anidados
+* Conversión de datos
+* Validación de datos
+* Documentación automática
+
+## Tipos especiales y validación
+
+Además de tipos singulares normales como `str`, `int`, `float`, etc., puedes usar tipos singulares más complejos que heredan de `str`.
+
+Para ver todas las opciones que tienes, revisa el Overview de Tipos de Pydantic. Verás algunos ejemplos en el siguiente capítulo.
+
+Por ejemplo, como en el modelo `Image` tenemos un campo `url`, podemos declararlo como una instance de `HttpUrl` de Pydantic en lugar de un `str`:
+
+{* ../../docs_src/body_nested_models/tutorial005_py310.py hl[2,8] *}
+
+El string será verificado para ser una URL válida, y documentado en JSON Schema / OpenAPI como tal.
+
+## Atributos con listas de submodelos
+
+También puedes usar modelos Pydantic como subtipos de `list`, `set`, etc.:
+
+{* ../../docs_src/body_nested_models/tutorial006_py310.py hl[18] *}
+
+Esto esperará (convertirá, validará, documentará, etc.) un cuerpo JSON como:
+
+```JSON hl_lines="11"
+{
+ "name": "Foo",
+ "description": "The pretender",
+ "price": 42.0,
+ "tax": 3.2,
+ "tags": [
+ "rock",
+ "metal",
+ "bar"
+ ],
+ "images": [
+ {
+ "url": "http://example.com/baz.jpg",
+ "name": "The Foo live"
+ },
+ {
+ "url": "http://example.com/dave.jpg",
+ "name": "The Baz"
+ }
+ ]
+}
+```
+
+/// info | Información
+
+Nota cómo la clave `images` ahora tiene una lista de objetos de imagen.
+
+///
+
+## Modelos anidados profundamente
+
+Puedes definir modelos anidados tan profundamente como desees:
+
+{* ../../docs_src/body_nested_models/tutorial007_py310.py hl[7,12,18,21,25] *}
+
+/// info | Información
+
+Observa cómo `Offer` tiene una lista de `Item`s, que a su vez tienen una lista opcional de `Image`s
+
+///
+
+## Cuerpos de listas puras
+
+Si el valor superior del cuerpo JSON que esperas es un `array` JSON (una `list` en Python), puedes declarar el tipo en el parámetro de la función, al igual que en los modelos Pydantic:
+
+```Python
+images: List[Image]
+```
+
+o en Python 3.9 y superior:
+
+```Python
+images: list[Image]
+```
+
+como en:
+
+{* ../../docs_src/body_nested_models/tutorial008_py39.py hl[13] *}
+
+## Soporte de editor en todas partes
+
+Y obtienes soporte de editor en todas partes.
+
+Incluso para elementos dentro de listas:
+
+
+
+No podrías obtener este tipo de soporte de editor si estuvieras trabajando directamente con `dict` en lugar de modelos Pydantic.
+
+Pero tampoco tienes que preocuparte por ellos, los `dicts` entrantes se convierten automáticamente y tu salida se convierte automáticamente a JSON también.
+
+## Cuerpos de `dict`s arbitrarios
+
+También puedes declarar un cuerpo como un `dict` con claves de algún tipo y valores de algún otro tipo.
+
+De esta manera, no tienes que saber de antemano cuáles son los nombres válidos de campo/atributo (como sería el caso con modelos Pydantic).
+
+Esto sería útil si deseas recibir claves que aún no conoces.
+
+---
+
+Otro caso útil es cuando deseas tener claves de otro tipo (por ejemplo, `int`).
+
+Eso es lo que vamos a ver aquí.
+
+En este caso, aceptarías cualquier `dict` siempre que tenga claves `int` con valores `float`:
+
+{* ../../docs_src/body_nested_models/tutorial009_py39.py hl[7] *}
+
+/// tip | Consejo
+
+Ten en cuenta que JSON solo admite `str` como claves.
+
+Pero Pydantic tiene conversión automática de datos.
+
+Esto significa que, aunque tus clientes de API solo pueden enviar strings como claves, mientras esos strings contengan enteros puros, Pydantic los convertirá y validará.
+
+Y el `dict` que recibas como `weights` tendrá realmente claves `int` y valores `float`.
+
+///
+
+## Resumen
+
+Con **FastAPI** tienes la máxima flexibilidad proporcionada por los modelos Pydantic, manteniendo tu código simple, corto y elegante.
+
+Pero con todos los beneficios:
+
+* Soporte de editor (¡autocompletado en todas partes!)
+* Conversión de datos (también conocido como parsing/serialización)
+* Validación de datos
+* Documentación del esquema
+* Documentación automática
diff --git a/docs/es/docs/tutorial/body-updates.md b/docs/es/docs/tutorial/body-updates.md
new file mode 100644
index 000000000..26cd3345f
--- /dev/null
+++ b/docs/es/docs/tutorial/body-updates.md
@@ -0,0 +1,116 @@
+# Cuerpo - Actualizaciones
+
+## Actualización reemplazando con `PUT`
+
+Para actualizar un ítem puedes utilizar la operación de HTTP `PUT`.
+
+Puedes usar el `jsonable_encoder` para convertir los datos de entrada en datos que se puedan almacenar como JSON (por ejemplo, con una base de datos NoSQL). Por ejemplo, convirtiendo `datetime` a `str`.
+
+{* ../../docs_src/body_updates/tutorial001_py310.py hl[28:33] *}
+
+`PUT` se usa para recibir datos que deben reemplazar los datos existentes.
+
+### Advertencia sobre el reemplazo
+
+Esto significa que si quieres actualizar el ítem `bar` usando `PUT` con un body que contenga:
+
+```Python
+{
+ "name": "Barz",
+ "price": 3,
+ "description": None,
+}
+```
+
+debido a que no incluye el atributo ya almacenado `"tax": 20.2`, el modelo de entrada tomaría el valor por defecto de `"tax": 10.5`.
+
+Y los datos se guardarían con ese "nuevo" `tax` de `10.5`.
+
+## Actualizaciones parciales con `PATCH`
+
+También puedes usar la operación de HTTP `PATCH` para actualizar *parcialmente* datos.
+
+Esto significa que puedes enviar solo los datos que deseas actualizar, dejando el resto intacto.
+
+/// note | Nota
+
+`PATCH` es menos usado y conocido que `PUT`.
+
+Y muchos equipos utilizan solo `PUT`, incluso para actualizaciones parciales.
+
+Eres **libre** de usarlos como desees, **FastAPI** no impone ninguna restricción.
+
+Pero esta guía te muestra, más o menos, cómo se pretende que se usen.
+
+///
+
+### Uso del parámetro `exclude_unset` de Pydantic
+
+Si quieres recibir actualizaciones parciales, es muy útil usar el parámetro `exclude_unset` en el `.model_dump()` del modelo de Pydantic.
+
+Como `item.model_dump(exclude_unset=True)`.
+
+/// info | Información
+
+En Pydantic v1 el método se llamaba `.dict()`, fue deprecado (pero aún soportado) en Pydantic v2, y renombrado a `.model_dump()`.
+
+Los ejemplos aquí usan `.dict()` para compatibilidad con Pydantic v1, pero deberías usar `.model_dump()` si puedes usar Pydantic v2.
+
+///
+
+Eso generaría un `dict` solo con los datos que se establecieron al crear el modelo `item`, excluyendo los valores por defecto.
+
+Luego puedes usar esto para generar un `dict` solo con los datos que se establecieron (enviados en el request), omitiendo los valores por defecto:
+
+{* ../../docs_src/body_updates/tutorial002_py310.py hl[32] *}
+
+### Uso del parámetro `update` de Pydantic
+
+Ahora, puedes crear una copia del modelo existente usando `.model_copy()`, y pasar el parámetro `update` con un `dict` que contenga los datos a actualizar.
+
+/// info | Información
+
+En Pydantic v1 el método se llamaba `.copy()`, fue deprecado (pero aún soportado) en Pydantic v2, y renombrado a `.model_copy()`.
+
+Los ejemplos aquí usan `.copy()` para compatibilidad con Pydantic v1, pero deberías usar `.model_copy()` si puedes usar Pydantic v2.
+
+///
+
+Como `stored_item_model.model_copy(update=update_data)`:
+
+{* ../../docs_src/body_updates/tutorial002_py310.py hl[33] *}
+
+### Resumen de actualizaciones parciales
+
+En resumen, para aplicar actualizaciones parciales deberías:
+
+* (Opcionalmente) usar `PATCH` en lugar de `PUT`.
+* Recuperar los datos almacenados.
+* Poner esos datos en un modelo de Pydantic.
+* Generar un `dict` sin valores por defecto del modelo de entrada (usando `exclude_unset`).
+ * De esta manera puedes actualizar solo los valores realmente establecidos por el usuario, en lugar de sobrescribir valores ya almacenados con valores por defecto en tu modelo.
+* Crear una copia del modelo almacenado, actualizando sus atributos con las actualizaciones parciales recibidas (usando el parámetro `update`).
+* Convertir el modelo copiado en algo que pueda almacenarse en tu base de datos (por ejemplo, usando el `jsonable_encoder`).
+ * Esto es comparable a usar el método `.model_dump()` del modelo de nuevo, pero asegura (y convierte) los valores a tipos de datos que pueden convertirse a JSON, por ejemplo, `datetime` a `str`.
+* Guardar los datos en tu base de datos.
+* Devolver el modelo actualizado.
+
+{* ../../docs_src/body_updates/tutorial002_py310.py hl[28:35] *}
+
+/// tip | Consejo
+
+Puedes realmente usar esta misma técnica con una operación HTTP `PUT`.
+
+Pero el ejemplo aquí usa `PATCH` porque fue creado para estos casos de uso.
+
+///
+
+/// note | Nota
+
+Observa que el modelo de entrada sigue siendo validado.
+
+Entonces, si deseas recibir actualizaciones parciales que puedan omitir todos los atributos, necesitas tener un modelo con todos los atributos marcados como opcionales (con valores por defecto o `None`).
+
+Para distinguir entre los modelos con todos los valores opcionales para **actualizaciones** y modelos con valores requeridos para **creación**, puedes utilizar las ideas descritas en [Modelos Extra](extra-models.md){.internal-link target=_blank}.
+
+///
diff --git a/docs/es/docs/tutorial/body.md b/docs/es/docs/tutorial/body.md
new file mode 100644
index 000000000..6d0aa7c60
--- /dev/null
+++ b/docs/es/docs/tutorial/body.md
@@ -0,0 +1,164 @@
+# Request Body
+
+Cuando necesitas enviar datos desde un cliente (digamos, un navegador) a tu API, los envías como un **request body**.
+
+Un **request** body es un dato enviado por el cliente a tu API. Un **response** body es el dato que tu API envía al cliente.
+
+Tu API casi siempre tiene que enviar un **response** body. Pero los clientes no necesariamente necesitan enviar **request bodies** todo el tiempo, a veces solo solicitan un path, quizás con algunos parámetros de query, pero no envían un body.
+
+Para declarar un **request** body, usas modelos de Pydantic con todo su poder y beneficios.
+
+/// info | Información
+
+Para enviar datos, deberías usar uno de estos métodos: `POST` (el más común), `PUT`, `DELETE` o `PATCH`.
+
+Enviar un body con un request `GET` tiene un comportamiento indefinido en las especificaciones, no obstante, es soportado por FastAPI, solo para casos de uso muy complejos/extremos.
+
+Como no se recomienda, la documentación interactiva con Swagger UI no mostrará la documentación para el body cuando se usa `GET`, y los proxies intermedios podrían no soportarlo.
+
+///
+
+## Importar `BaseModel` de Pydantic
+
+Primero, necesitas importar `BaseModel` de `pydantic`:
+
+{* ../../docs_src/body/tutorial001_py310.py hl[2] *}
+
+## Crea tu modelo de datos
+
+Luego, declaras tu modelo de datos como una clase que hereda de `BaseModel`.
+
+Usa tipos estándar de Python para todos los atributos:
+
+{* ../../docs_src/body/tutorial001_py310.py hl[5:9] *}
+
+Al igual que al declarar parámetros de query, cuando un atributo del modelo tiene un valor por defecto, no es obligatorio. De lo contrario, es obligatorio. Usa `None` para hacerlo opcional.
+
+Por ejemplo, el modelo anterior declara un “`object`” JSON (o `dict` en Python) como:
+
+```JSON
+{
+ "name": "Foo",
+ "description": "An optional description",
+ "price": 45.2,
+ "tax": 3.5
+}
+```
+
+...dado que `description` y `tax` son opcionales (con un valor por defecto de `None`), este “`object`” JSON también sería válido:
+
+```JSON
+{
+ "name": "Foo",
+ "price": 45.2
+}
+```
+
+## Decláralo como un parámetro
+
+Para añadirlo a tu *path operation*, decláralo de la misma manera que declaraste parámetros de path y query:
+
+{* ../../docs_src/body/tutorial001_py310.py hl[16] *}
+
+...y declara su tipo como el modelo que creaste, `Item`.
+
+## Resultados
+
+Con solo esa declaración de tipo en Python, **FastAPI** hará lo siguiente:
+
+* Leer el body del request como JSON.
+* Convertir los tipos correspondientes (si es necesario).
+* Validar los datos.
+ * Si los datos son inválidos, devolverá un error claro e indicado, señalando exactamente dónde y qué fue lo incorrecto.
+* Proporcionar los datos recibidos en el parámetro `item`.
+ * Como lo declaraste en la función como de tipo `Item`, también tendrás todo el soporte del editor (autocompletado, etc.) para todos los atributos y sus tipos.
+* Generar definiciones de JSON Schema para tu modelo, que también puedes usar en cualquier otro lugar si tiene sentido para tu proyecto.
+* Esquemas que serán parte del esquema de OpenAPI generado y usados por la UIs de documentación automática.
+
+## Documentación automática
+
+Los JSON Schemas de tus modelos serán parte del esquema OpenAPI generado y se mostrarán en la documentación API interactiva:
+
+
+
+Y también se utilizarán en la documentación API dentro de cada *path operation* que los necesite:
+
+
+
+## Soporte del editor
+
+En tu editor, dentro de tu función, obtendrás anotaciones de tipos y autocompletado en todas partes (esto no sucedería si recibieras un `dict` en lugar de un modelo de Pydantic):
+
+
+
+También recibirás chequeos de errores para operaciones de tipo incorrecto:
+
+
+
+No es por casualidad, todo el framework fue construido alrededor de ese diseño.
+
+Y fue rigurosamente probado en la fase de diseño, antes de cualquier implementación, para garantizar que funcionaría con todos los editores.
+
+Incluso se hicieron algunos cambios en Pydantic para admitir esto.
+
+Las capturas de pantalla anteriores se tomaron con Visual Studio Code.
+
+Pero obtendrías el mismo soporte en el editor con PyCharm y la mayoría de los otros editores de Python:
+
+
+
+/// tip | Consejo
+
+Si usas PyCharm como tu editor, puedes usar el Pydantic PyCharm Plugin.
+
+Mejora el soporte del editor para modelos de Pydantic, con:
+
+* autocompletado
+* chequeo de tipos
+* refactorización
+* búsqueda
+* inspecciones
+
+///
+
+## Usa el modelo
+
+Dentro de la función, puedes acceder a todos los atributos del objeto modelo directamente:
+
+{* ../../docs_src/body/tutorial002_py310.py *}
+
+## Request body + parámetros de path
+
+Puedes declarar parámetros de path y request body al mismo tiempo.
+
+**FastAPI** reconocerá que los parámetros de función que coinciden con los parámetros de path deben ser **tomados del path**, y que los parámetros de función que se declaran como modelos de Pydantic deben ser **tomados del request body**.
+
+{* ../../docs_src/body/tutorial003_py310.py hl[15:16] *}
+
+## Request body + path + parámetros de query
+
+También puedes declarar parámetros de **body**, **path** y **query**, todos al mismo tiempo.
+
+**FastAPI** reconocerá cada uno de ellos y tomará los datos del lugar correcto.
+
+{* ../../docs_src/body/tutorial004_py310.py hl[16] *}
+
+Los parámetros de la función se reconocerán de la siguiente manera:
+
+* Si el parámetro también se declara en el **path**, se utilizará como un parámetro de path.
+* Si el parámetro es de un **tipo singular** (como `int`, `float`, `str`, `bool`, etc.), se interpretará como un parámetro de **query**.
+* Si el parámetro se declara como del tipo de un **modelo de Pydantic**, se interpretará como un **request body**.
+
+/// note | Nota
+
+FastAPI sabrá que el valor de `q` no es requerido debido al valor por defecto `= None`.
+
+El `str | None` (Python 3.10+) o `Union` en `Union[str, None]` (Python 3.8+) no es utilizado por FastAPI para determinar que el valor no es requerido, sabrá que no es requerido porque tiene un valor por defecto de `= None`.
+
+Pero agregar las anotaciones de tipos permitirá que tu editor te brinde un mejor soporte y detecte errores.
+
+///
+
+## Sin Pydantic
+
+Si no quieres usar modelos de Pydantic, también puedes usar parámetros **Body**. Consulta la documentación para [Body - Multiples Parametros: Valores singulares en body](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}.
diff --git a/docs/es/docs/tutorial/cookie-param-models.md b/docs/es/docs/tutorial/cookie-param-models.md
new file mode 100644
index 000000000..ebdb59265
--- /dev/null
+++ b/docs/es/docs/tutorial/cookie-param-models.md
@@ -0,0 +1,76 @@
+# Modelos de Cookies
+
+Si tienes un grupo de **cookies** que están relacionadas, puedes crear un **modelo de Pydantic** para declararlas. 🍪
+
+Esto te permitirá **reutilizar el modelo** en **múltiples lugares** y también declarar validaciones y metadatos para todos los parámetros a la vez. 😎
+
+/// note | Nota
+
+Esto es compatible desde la versión `0.115.0` de FastAPI. 🤓
+
+///
+
+/// tip | Consejo
+
+Esta misma técnica se aplica a `Query`, `Cookie`, y `Header`. 😎
+
+///
+
+## Cookies con un Modelo de Pydantic
+
+Declara los parámetros de **cookie** que necesites en un **modelo de Pydantic**, y luego declara el parámetro como `Cookie`:
+
+{* ../../docs_src/cookie_param_models/tutorial001_an_py310.py hl[9:12,16] *}
+
+**FastAPI** **extraerá** los datos para **cada campo** de las **cookies** recibidas en el request y te entregará el modelo de Pydantic que definiste.
+
+## Revisa la Documentación
+
+Puedes ver las cookies definidas en la UI de la documentación en `/docs`:
+
+
+
+
+---
+
+Si usas PyCharm, puedes:
+
+* Abrir el menú "Run".
+* Seleccionar la opción "Debug...".
+* Luego aparece un menú contextual.
+* Selecciona el archivo para depurar (en este caso, `main.py`).
+
+Luego, iniciará el servidor con tu código **FastAPI**, deteniéndose en tus puntos de interrupción, etc.
+
+Así es como podría verse:
+
+
diff --git a/docs/es/docs/tutorial/dependencies/classes-as-dependencies.md b/docs/es/docs/tutorial/dependencies/classes-as-dependencies.md
new file mode 100644
index 000000000..d0868240e
--- /dev/null
+++ b/docs/es/docs/tutorial/dependencies/classes-as-dependencies.md
@@ -0,0 +1,288 @@
+# Clases como dependencias
+
+Antes de profundizar en el sistema de **Inyección de Dependencias**, vamos a mejorar el ejemplo anterior.
+
+## Un `dict` del ejemplo anterior
+
+En el ejemplo anterior, estábamos devolviendo un `dict` de nuestra dependencia ("dependable"):
+
+{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[9] *}
+
+Pero luego obtenemos un `dict` en el parámetro `commons` de la *path operation function*.
+
+Y sabemos que los editores no pueden proporcionar mucho soporte (como autocompletado) para `dict`s, porque no pueden conocer sus claves y tipos de valor.
+
+Podemos hacerlo mejor...
+
+## Qué hace a una dependencia
+
+Hasta ahora has visto dependencias declaradas como funciones.
+
+Pero esa no es la única forma de declarar dependencias (aunque probablemente sea la más común).
+
+El factor clave es que una dependencia debe ser un "callable".
+
+Un "**callable**" en Python es cualquier cosa que Python pueda "llamar" como una función.
+
+Entonces, si tienes un objeto `something` (que podría _no_ ser una función) y puedes "llamarlo" (ejecutarlo) como:
+
+```Python
+something()
+```
+
+o
+
+```Python
+something(some_argument, some_keyword_argument="foo")
+```
+
+entonces es un "callable".
+
+## Clases como dependencias
+
+Puedes notar que para crear una instance de una clase en Python, utilizas esa misma sintaxis.
+
+Por ejemplo:
+
+```Python
+class Cat:
+ def __init__(self, name: str):
+ self.name = name
+
+
+fluffy = Cat(name="Mr Fluffy")
+```
+
+En este caso, `fluffy` es una instance de la clase `Cat`.
+
+Y para crear `fluffy`, estás "llamando" a `Cat`.
+
+Entonces, una clase en Python también es un **callable**.
+
+Entonces, en **FastAPI**, podrías usar una clase de Python como una dependencia.
+
+Lo que **FastAPI** realmente comprueba es que sea un "callable" (función, clase o cualquier otra cosa) y los parámetros definidos.
+
+Si pasas un "callable" como dependencia en **FastAPI**, analizará los parámetros de ese "callable", y los procesará de la misma manera que los parámetros de una *path operation function*. Incluyendo sub-dependencias.
+
+Eso también se aplica a los callables sin parámetros. Igual que sería para *path operation functions* sin parámetros.
+
+Entonces, podemos cambiar la dependencia "dependable" `common_parameters` de arriba a la clase `CommonQueryParams`:
+
+{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[11:15] *}
+
+Presta atención al método `__init__` usado para crear la instance de la clase:
+
+{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[12] *}
+
+...tiene los mismos parámetros que nuestros `common_parameters` anteriores:
+
+{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[8] *}
+
+Esos parámetros son los que **FastAPI** usará para "resolver" la dependencia.
+
+En ambos casos, tendrá:
+
+* Un parámetro de query `q` opcional que es un `str`.
+* Un parámetro de query `skip` que es un `int`, con un valor por defecto de `0`.
+* Un parámetro de query `limit` que es un `int`, con un valor por defecto de `100`.
+
+En ambos casos, los datos serán convertidos, validados, documentados en el esquema de OpenAPI, etc.
+
+## Úsalo
+
+Ahora puedes declarar tu dependencia usando esta clase.
+
+{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[19] *}
+
+**FastAPI** llama a la clase `CommonQueryParams`. Esto crea una "instance" de esa clase y la instance será pasada como el parámetro `commons` a tu función.
+
+## Anotación de tipos vs `Depends`
+
+Nota cómo escribimos `CommonQueryParams` dos veces en el código anterior:
+
+//// tab | Python 3.8+
+
+```Python
+commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
+```
+
+////
+
+//// tab | Python 3.8+ sin `Annotated`
+
+/// tip | Consejo
+
+Prefiere usar la versión `Annotated` si es posible.
+
+///
+
+```Python
+commons: CommonQueryParams = Depends(CommonQueryParams)
+```
+
+////
+
+El último `CommonQueryParams`, en:
+
+```Python
+... Depends(CommonQueryParams)
+```
+
+...es lo que **FastAPI** utilizará realmente para saber cuál es la dependencia.
+
+Es a partir de este que **FastAPI** extraerá los parámetros declarados y es lo que **FastAPI** realmente llamará.
+
+---
+
+En este caso, el primer `CommonQueryParams`, en:
+
+//// tab | Python 3.8+
+
+```Python
+commons: Annotated[CommonQueryParams, ...
+```
+
+////
+
+//// tab | Python 3.8+ sin `Annotated`
+
+/// tip | Consejo
+
+Prefiere usar la versión `Annotated` si es posible.
+
+///
+
+```Python
+commons: CommonQueryParams ...
+```
+
+////
+
+...no tiene ningún significado especial para **FastAPI**. **FastAPI** no lo usará para la conversión de datos, validación, etc. (ya que está usando `Depends(CommonQueryParams)` para eso).
+
+De hecho, podrías escribir simplemente:
+
+//// tab | Python 3.8+
+
+```Python
+commons: Annotated[Any, Depends(CommonQueryParams)]
+```
+
+////
+
+//// tab | Python 3.8+ sin `Annotated`
+
+/// tip | Consejo
+
+Prefiere usar la versión `Annotated` si es posible.
+
+///
+
+```Python
+commons = Depends(CommonQueryParams)
+```
+
+////
+
+...como en:
+
+{* ../../docs_src/dependencies/tutorial003_an_py310.py hl[19] *}
+
+Pero declarar el tipo es recomendable, ya que de esa manera tu editor sabrá lo que se pasará como el parámetro `commons`, y entonces podrá ayudarte con el autocompletado, chequeo de tipos, etc:
+
+
+
+## Atajo
+
+Pero ves que estamos teniendo algo de repetición de código aquí, escribiendo `CommonQueryParams` dos veces:
+
+//// tab | Python 3.8+
+
+```Python
+commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
+```
+
+////
+
+//// tab | Python 3.8+ sin `Annotated`
+
+/// tip | Consejo
+
+Prefiere usar la versión `Annotated` si es posible.
+
+///
+
+```Python
+commons: CommonQueryParams = Depends(CommonQueryParams)
+```
+
+////
+
+**FastAPI** proporciona un atajo para estos casos, en donde la dependencia es *específicamente* una clase que **FastAPI** "llamará" para crear una instance de la clase misma.
+
+Para esos casos específicos, puedes hacer lo siguiente:
+
+En lugar de escribir:
+
+//// tab | Python 3.8+
+
+```Python
+commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
+```
+
+////
+
+//// tab | Python 3.8+ sin `Annotated`
+
+/// tip | Consejo
+
+Prefiere usar la versión `Annotated` si es posible.
+
+///
+
+```Python
+commons: CommonQueryParams = Depends(CommonQueryParams)
+```
+
+////
+
+...escribes:
+
+//// tab | Python 3.8+
+
+```Python
+commons: Annotated[CommonQueryParams, Depends()]
+```
+
+////
+
+//// tab | Python 3.8 sin `Annotated`
+
+/// tip | Consejo
+
+Prefiere usar la versión `Annotated` si es posible.
+
+///
+
+```Python
+commons: CommonQueryParams = Depends()
+```
+
+////
+
+Declaras la dependencia como el tipo del parámetro, y usas `Depends()` sin ningún parámetro, en lugar de tener que escribir la clase completa *otra vez* dentro de `Depends(CommonQueryParams)`.
+
+El mismo ejemplo se vería entonces así:
+
+{* ../../docs_src/dependencies/tutorial004_an_py310.py hl[19] *}
+
+...y **FastAPI** sabrá qué hacer.
+
+/// tip | Consejo
+
+Si eso parece más confuso que útil, ignóralo, no lo *necesitas*.
+
+Es solo un atajo. Porque a **FastAPI** le importa ayudarte a minimizar la repetición de código.
+
+///
diff --git a/docs/es/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md b/docs/es/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
new file mode 100644
index 000000000..fbe17c67a
--- /dev/null
+++ b/docs/es/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
@@ -0,0 +1,69 @@
+# Dependencias en decoradores de *path operation*
+
+En algunos casos realmente no necesitas el valor de retorno de una dependencia dentro de tu *path operation function*.
+
+O la dependencia no devuelve un valor.
+
+Pero aún necesitas que sea ejecutada/resuelta.
+
+Para esos casos, en lugar de declarar un parámetro de *path operation function* con `Depends`, puedes añadir una `list` de `dependencies` al decorador de *path operation*.
+
+## Agregar `dependencies` al decorador de *path operation*
+
+El decorador de *path operation* recibe un argumento opcional `dependencies`.
+
+Debe ser una `list` de `Depends()`:
+
+{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[19] *}
+
+Estas dependencias serán ejecutadas/resueltas de la misma manera que las dependencias normales. Pero su valor (si devuelven alguno) no será pasado a tu *path operation function*.
+
+/// tip | Consejo
+
+Algunos editores revisan los parámetros de función no usados y los muestran como errores.
+
+Usando estas `dependencies` en el decorador de *path operation* puedes asegurarte de que se ejecutan mientras evitas errores en editores/herramientas.
+
+También puede ayudar a evitar confusiones para nuevos desarrolladores que vean un parámetro no usado en tu código y puedan pensar que es innecesario.
+
+///
+
+/// info | Información
+
+En este ejemplo usamos headers personalizados inventados `X-Key` y `X-Token`.
+
+Pero en casos reales, al implementar seguridad, obtendrías más beneficios usando las [Utilidades de Seguridad integradas (el próximo capítulo)](../security/index.md){.internal-link target=_blank}.
+
+///
+
+## Errores de dependencias y valores de retorno
+
+Puedes usar las mismas *funciones* de dependencia que usas normalmente.
+
+### Requisitos de dependencia
+
+Pueden declarar requisitos de request (como headers) u otras sub-dependencias:
+
+{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[8,13] *}
+
+### Lanzar excepciones
+
+Estas dependencias pueden `raise` excepciones, igual que las dependencias normales:
+
+{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[10,15] *}
+
+### Valores de retorno
+
+Y pueden devolver valores o no, los valores no serán usados.
+
+Así que, puedes reutilizar una dependencia normal (que devuelve un valor) que ya uses en otro lugar, y aunque el valor no se use, la dependencia será ejecutada:
+
+{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[11,16] *}
+
+## Dependencias para un grupo de *path operations*
+
+Más adelante, cuando leas sobre cómo estructurar aplicaciones más grandes ([Aplicaciones Más Grandes - Múltiples Archivos](../../tutorial/bigger-applications.md){.internal-link target=_blank}), posiblemente con múltiples archivos, aprenderás cómo declarar un único parámetro `dependencies` para un grupo de *path operations*.
+
+## Dependencias Globales
+
+A continuación veremos cómo añadir dependencias a toda la aplicación `FastAPI`, de modo que se apliquen a cada *path operation*.
diff --git a/docs/es/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/es/docs/tutorial/dependencies/dependencies-with-yield.md
new file mode 100644
index 000000000..94290443a
--- /dev/null
+++ b/docs/es/docs/tutorial/dependencies/dependencies-with-yield.md
@@ -0,0 +1,275 @@
+# Dependencias con yield
+
+FastAPI admite dependencias que realizan algunos pasos adicionales después de finalizar.
+
+Para hacer esto, usa `yield` en lugar de `return` y escribe los pasos adicionales (código) después.
+
+/// tip | Consejo
+
+Asegúrate de usar `yield` una sola vez por dependencia.
+
+///
+
+/// note | Nota técnica
+
+Cualquier función que sea válida para usar con:
+
+* `@contextlib.contextmanager` o
+* `@contextlib.asynccontextmanager`
+
+sería válida para usar como una dependencia en **FastAPI**.
+
+De hecho, FastAPI usa esos dos decoradores internamente.
+
+///
+
+## Una dependencia de base de datos con `yield`
+
+Por ejemplo, podrías usar esto para crear una sesión de base de datos y cerrarla después de finalizar.
+
+Solo el código anterior e incluyendo la declaración `yield` se ejecuta antes de crear un response:
+
+{* ../../docs_src/dependencies/tutorial007.py hl[2:4] *}
+
+El valor generado es lo que se inyecta en *path operations* y otras dependencias:
+
+{* ../../docs_src/dependencies/tutorial007.py hl[4] *}
+
+El código posterior a la declaración `yield` se ejecuta después de crear el response pero antes de enviarla:
+
+{* ../../docs_src/dependencies/tutorial007.py hl[5:6] *}
+
+/// tip | Consejo
+
+Puedes usar funciones `async` o regulares.
+
+**FastAPI** hará lo correcto con cada una, igual que con dependencias normales.
+
+///
+
+## Una dependencia con `yield` y `try`
+
+Si usas un bloque `try` en una dependencia con `yield`, recibirás cualquier excepción que se haya lanzado al usar la dependencia.
+
+Por ejemplo, si algún código en algún punto intermedio, en otra dependencia o en una *path operation*, realiza un "rollback" en una transacción de base de datos o crea cualquier otro error, recibirás la excepción en tu dependencia.
+
+Por lo tanto, puedes buscar esa excepción específica dentro de la dependencia con `except SomeException`.
+
+Del mismo modo, puedes usar `finally` para asegurarte de que los pasos de salida se ejecuten, sin importar si hubo una excepción o no.
+
+{* ../../docs_src/dependencies/tutorial007.py hl[3,5] *}
+
+## Sub-dependencias con `yield`
+
+Puedes tener sub-dependencias y "árboles" de sub-dependencias de cualquier tamaño y forma, y cualquiera o todas ellas pueden usar `yield`.
+
+**FastAPI** se asegurará de que el "código de salida" en cada dependencia con `yield` se ejecute en el orden correcto.
+
+Por ejemplo, `dependency_c` puede tener una dependencia de `dependency_b`, y `dependency_b` de `dependency_a`:
+
+{* ../../docs_src/dependencies/tutorial008_an_py39.py hl[6,14,22] *}
+
+Y todas ellas pueden usar `yield`.
+
+En este caso, `dependency_c`, para ejecutar su código de salida, necesita que el valor de `dependency_b` (aquí llamado `dep_b`) todavía esté disponible.
+
+Y, a su vez, `dependency_b` necesita que el valor de `dependency_a` (aquí llamado `dep_a`) esté disponible para su código de salida.
+
+{* ../../docs_src/dependencies/tutorial008_an_py39.py hl[18:19,26:27] *}
+
+De la misma manera, podrías tener algunas dependencias con `yield` y otras dependencias con `return`, y hacer que algunas de esas dependan de algunas de las otras.
+
+Y podrías tener una sola dependencia que requiera varias otras dependencias con `yield`, etc.
+
+Puedes tener cualquier combinación de dependencias que quieras.
+
+**FastAPI** se asegurará de que todo se ejecute en el orden correcto.
+
+/// note | Nota técnica
+
+Esto funciona gracias a los Context Managers de Python.
+
+**FastAPI** los utiliza internamente para lograr esto.
+
+///
+
+## Dependencias con `yield` y `HTTPException`
+
+Viste que puedes usar dependencias con `yield` y tener bloques `try` que capturen excepciones.
+
+De la misma manera, podrías lanzar una `HTTPException` o similar en el código de salida, después del `yield`.
+
+/// tip | Consejo
+
+Esta es una técnica algo avanzada, y en la mayoría de los casos realmente no lo necesitarás, ya que puedes lanzar excepciones (incluyendo `HTTPException`) desde dentro del resto del código de tu aplicación, por ejemplo, en la *path operation function*.
+
+Pero está ahí para ti si la necesitas. 🤓
+
+///
+
+{* ../../docs_src/dependencies/tutorial008b_an_py39.py hl[18:22,31] *}
+
+Una alternativa que podrías usar para capturar excepciones (y posiblemente también lanzar otra `HTTPException`) es crear un [Manejador de Excepciones Personalizado](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank}.
+
+## Dependencias con `yield` y `except`
+
+Si capturas una excepción usando `except` en una dependencia con `yield` y no la lanzas nuevamente (o lanzas una nueva excepción), FastAPI no podrá notar que hubo una excepción, al igual que sucedería con Python normal:
+
+{* ../../docs_src/dependencies/tutorial008c_an_py39.py hl[15:16] *}
+
+En este caso, el cliente verá un response *HTTP 500 Internal Server Error* como debería, dado que no estamos lanzando una `HTTPException` o similar, pero el servidor **no tendrá ningún registro** ni ninguna otra indicación de cuál fue el error. 😱
+
+### Siempre `raise` en Dependencias con `yield` y `except`
+
+Si capturas una excepción en una dependencia con `yield`, a menos que estés lanzando otra `HTTPException` o similar, deberías volver a lanzar la excepción original.
+
+Puedes volver a lanzar la misma excepción usando `raise`:
+
+{* ../../docs_src/dependencies/tutorial008d_an_py39.py hl[17] *}
+
+Ahora el cliente obtendrá el mismo response *HTTP 500 Internal Server Error*, pero el servidor tendrá nuestro `InternalError` personalizado en los registros. 😎
+
+## Ejecución de dependencias con `yield`
+
+La secuencia de ejecución es más o menos como este diagrama. El tiempo fluye de arriba a abajo. Y cada columna es una de las partes que interactúa o ejecuta código.
+
+```mermaid
+sequenceDiagram
+
+participant client as Client
+participant handler as Exception handler
+participant dep as Dep with yield
+participant operation as Path Operation
+participant tasks as Background tasks
+
+ Note over client,operation: Puede lanzar excepciones, incluyendo HTTPException
+ client ->> dep: Iniciar request
+ Note over dep: Ejecutar código hasta yield
+ opt raise Exception
+ dep -->> handler: Lanzar Exception
+ handler -->> client: Response HTTP de error
+ end
+ dep ->> operation: Ejecutar dependencia, por ejemplo, sesión de BD
+ opt raise
+ operation -->> dep: Lanzar Exception (por ejemplo, HTTPException)
+ opt handle
+ dep -->> dep: Puede capturar excepción, lanzar una nueva HTTPException, lanzar otra excepción
+ end
+ handler -->> client: Response HTTP de error
+ end
+
+ operation ->> client: Devolver response al cliente
+ Note over client,operation: El response ya fue enviado, no se puede cambiar
+ opt Tasks
+ operation -->> tasks: Enviar tareas en background
+ end
+ opt Lanzar otra excepción
+ tasks -->> tasks: Manejar excepciones en el código de la tarea en background
+ end
+```
+
+/// info | Información
+
+Solo **un response** será enviado al cliente. Podría ser uno de los responses de error o será el response de la *path operation*.
+
+Después de que se envíe uno de esos responses, no se podrá enviar ningún otro response.
+
+///
+
+/// tip | Consejo
+
+Este diagrama muestra `HTTPException`, pero también podrías lanzar cualquier otra excepción que captures en una dependencia con `yield` o con un [Manejador de Excepciones Personalizado](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank}.
+
+Si lanzas alguna excepción, será pasada a las dependencias con yield, incluyendo `HTTPException`. En la mayoría de los casos querrás volver a lanzar esa misma excepción o una nueva desde la dependencia con `yield` para asegurarte de que se maneje correctamente.
+
+///
+
+## Dependencias con `yield`, `HTTPException`, `except` y Tareas en Background
+
+/// warning | Advertencia
+
+Probablemente no necesites estos detalles técnicos, puedes omitir esta sección y continuar abajo.
+
+Estos detalles son útiles principalmente si estabas usando una versión de FastAPI anterior a 0.106.0 y usabas recursos de dependencias con `yield` en tareas en background.
+
+///
+
+### Dependencias con `yield` y `except`, Detalles Técnicos
+
+Antes de FastAPI 0.110.0, si usabas una dependencia con `yield`, y luego capturabas una excepción con `except` en esa dependencia, y no volvías a lanzar la excepción, la excepción se lanzaría automáticamente/transmitiría a cualquier manejador de excepciones o al manejador de errores interno del servidor.
+
+Esto se cambió en la versión 0.110.0 para corregir el consumo no gestionado de memoria de excepciones transmitidas sin un manejador (errores internos del servidor), y para que sea consistente con el comportamiento del código regular de Python.
+
+### Tareas en Background y Dependencias con `yield`, Detalles Técnicos
+
+Antes de FastAPI 0.106.0, lanzar excepciones después de `yield` no era posible, el código de salida en dependencias con `yield` se ejecutaba *después* de que el response se enviara, por lo que los [Manejadores de Excepciones](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank} ya se habrían ejecutado.
+
+Esto se diseñó de esta manera principalmente para permitir usar los mismos objetos "extraídos" por dependencias dentro de tareas en background, porque el código de salida se ejecutaría después de que las tareas en background terminaran.
+
+Sin embargo, ya que esto significaría esperar a que el response viaje a través de la red mientras se retiene innecesariamente un recurso en una dependencia con yield (por ejemplo, una conexión a base de datos), esto se cambió en FastAPI 0.106.0.
+
+/// tip | Consejo
+
+Además, una tarea en background es normalmente un conjunto independiente de lógica que debería manejarse por separado, con sus propios recursos (por ejemplo, su propia conexión a base de datos).
+
+De esta manera probablemente tendrás un código más limpio.
+
+///
+
+Si solías depender de este comportamiento, ahora deberías crear los recursos para tareas en background dentro de la propia tarea en background, y usar internamente solo datos que no dependan de los recursos de las dependencias con `yield`.
+
+Por ejemplo, en lugar de usar la misma sesión de base de datos, crearías una nueva sesión de base de datos dentro de la tarea en background, y obtendrías los objetos de la base de datos usando esta nueva sesión. Y luego, en lugar de pasar el objeto de la base de datos como parámetro a la función de tarea en background, pasarías el ID de ese objeto y luego obtendrías el objeto nuevamente dentro de la función de tarea en background.
+
+## Context Managers
+
+### Qué son los "Context Managers"
+
+Los "Context Managers" son aquellos objetos de Python que puedes usar en una declaración `with`.
+
+Por ejemplo, puedes usar `with` para leer un archivo:
+
+```Python
+with open("./somefile.txt") as f:
+ contents = f.read()
+ print(contents)
+```
+
+Internamente, `open("./somefile.txt")` crea un objeto llamado "Context Manager".
+
+Cuando el bloque `with` termina, se asegura de cerrar el archivo, incluso si hubo excepciones.
+
+Cuando creas una dependencia con `yield`, **FastAPI** creará internamente un context manager para ella y lo combinará con algunas otras herramientas relacionadas.
+
+### Usando context managers en dependencias con `yield`
+
+/// warning | Advertencia
+
+Esto es, más o menos, una idea "avanzada".
+
+Si apenas estás comenzando con **FastAPI**, podrías querer omitirlo por ahora.
+
+///
+
+En Python, puedes crear Context Managers creando una clase con dos métodos: `__enter__()` y `__exit__()`.
+
+También puedes usarlos dentro de las dependencias de **FastAPI** con `yield` usando
+`with` o `async with` en la función de dependencia:
+
+{* ../../docs_src/dependencies/tutorial010.py hl[1:9,13] *}
+
+/// tip | Consejo
+
+Otra manera de crear un context manager es con:
+
+* `@contextlib.contextmanager` o
+* `@contextlib.asynccontextmanager`
+
+usándolos para decorar una función con un solo `yield`.
+
+Eso es lo que **FastAPI** usa internamente para dependencias con `yield`.
+
+Pero no tienes que usar los decoradores para las dependencias de FastAPI (y no deberías).
+
+FastAPI lo hará por ti internamente.
+
+///
diff --git a/docs/es/docs/tutorial/dependencies/global-dependencies.md b/docs/es/docs/tutorial/dependencies/global-dependencies.md
new file mode 100644
index 000000000..08dd3d5c5
--- /dev/null
+++ b/docs/es/docs/tutorial/dependencies/global-dependencies.md
@@ -0,0 +1,15 @@
+# Dependencias Globales
+
+Para algunos tipos de aplicaciones, podrías querer agregar dependencias a toda la aplicación.
+
+Similar a como puedes [agregar `dependencies` a los *path operation decorators*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, puedes agregarlos a la aplicación de `FastAPI`.
+
+En ese caso, se aplicarán a todas las *path operations* en la aplicación:
+
+{* ../../docs_src/dependencies/tutorial012_an_py39.py hl[16] *}
+
+Y todas las ideas en la sección sobre [agregar `dependencies` a los *path operation decorators*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank} siguen aplicándose, pero en este caso, a todas las *path operations* en la app.
+
+## Dependencias para grupos de *path operations*
+
+Más adelante, al leer sobre cómo estructurar aplicaciones más grandes ([Aplicaciones Más Grandes - Múltiples Archivos](../../tutorial/bigger-applications.md){.internal-link target=_blank}), posiblemente con múltiples archivos, aprenderás cómo declarar un solo parámetro de `dependencies` para un grupo de *path operations*.
diff --git a/docs/es/docs/tutorial/dependencies/index.md b/docs/es/docs/tutorial/dependencies/index.md
new file mode 100644
index 000000000..2fb060177
--- /dev/null
+++ b/docs/es/docs/tutorial/dependencies/index.md
@@ -0,0 +1,250 @@
+# Dependencias
+
+**FastAPI** tiene un sistema de **Inyección de Dependencias** muy poderoso pero intuitivo.
+
+Está diseñado para ser muy simple de usar, y para hacer que cualquier desarrollador integre otros componentes con **FastAPI** de forma muy sencilla.
+
+## Qué es la "Inyección de Dependencias"
+
+**"Inyección de Dependencias"** significa, en programación, que hay una manera para que tu código (en este caso, tus *path operation functions*) declare las cosas que necesita para funcionar y utilizar: "dependencias".
+
+Y luego, ese sistema (en este caso **FastAPI**) se encargará de hacer lo que sea necesario para proporcionar a tu código esas dependencias necesarias ("inyectar" las dependencias).
+
+Esto es muy útil cuando necesitas:
+
+* Tener lógica compartida (la misma lógica de código una y otra vez).
+* Compartir conexiones a bases de datos.
+* Imponer seguridad, autenticación, requisitos de roles, etc.
+* Y muchas otras cosas...
+
+Todo esto, mientras minimizas la repetición de código.
+
+## Primeros Pasos
+
+Veamos un ejemplo muy simple. Será tan simple que no es muy útil, por ahora.
+
+Pero de esta manera podemos enfocarnos en cómo funciona el sistema de **Inyección de Dependencias**.
+
+### Crear una dependencia, o "dependable"
+
+Primero enfoquémonos en la dependencia.
+
+Es solo una función que puede tomar todos los mismos parámetros que una *path operation function* puede tomar:
+
+{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[8:9] *}
+
+Eso es todo.
+
+**2 líneas**.
+
+Y tiene la misma forma y estructura que todas tus *path operation functions*.
+
+Puedes pensar en ella como una *path operation function* sin el "decorador" (sin el `@app.get("/some-path")`).
+
+Y puede devolver lo que quieras.
+
+En este caso, esta dependencia espera:
+
+* Un parámetro de query opcional `q` que es un `str`.
+* Un parámetro de query opcional `skip` que es un `int`, y por defecto es `0`.
+* Un parámetro de query opcional `limit` que es un `int`, y por defecto es `100`.
+
+Y luego solo devuelve un `dict` que contiene esos valores.
+
+/// info | Información
+
+FastAPI agregó soporte para `Annotated` (y comenzó a recomendarlo) en la versión 0.95.0.
+
+Si tienes una versión anterior, obtendrás errores al intentar usar `Annotated`.
+
+Asegúrate de [Actualizar la versión de FastAPI](../../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank} al menos a la 0.95.1 antes de usar `Annotated`.
+
+///
+
+### Importar `Depends`
+
+{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[3] *}
+
+### Declarar la dependencia, en el "dependant"
+
+De la misma forma en que usas `Body`, `Query`, etc. con los parámetros de tu *path operation function*, usa `Depends` con un nuevo parámetro:
+
+{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[13,18] *}
+
+Aunque usas `Depends` en los parámetros de tu función de la misma manera que usas `Body`, `Query`, etc., `Depends` funciona un poco diferente.
+
+Le das a `Depends` un solo parámetro.
+
+Este parámetro debe ser algo como una función.
+
+**No la llames** directamente (no agregues los paréntesis al final), solo pásala como un parámetro a `Depends()`.
+
+Y esa función toma parámetros de la misma manera que las *path operation functions*.
+
+/// tip | Consejo
+
+Verás qué otras "cosas", además de funciones, pueden usarse como dependencias en el próximo capítulo.
+
+///
+
+Cada vez que llega un nuevo request, **FastAPI** se encargará de:
+
+* Llamar a tu función de dependencia ("dependable") con los parámetros correctos.
+* Obtener el resultado de tu función.
+* Asignar ese resultado al parámetro en tu *path operation function*.
+
+```mermaid
+graph TB
+
+common_parameters(["common_parameters"])
+read_items["/items/"]
+read_users["/users/"]
+
+common_parameters --> read_items
+common_parameters --> read_users
+```
+
+De esta manera escribes código compartido una vez y **FastAPI** se encarga de llamarlo para tus *path operations*.
+
+/// check | Revisa
+
+Nota que no tienes que crear una clase especial y pasarla en algún lugar a **FastAPI** para "registrarla" o algo similar.
+
+Solo la pasas a `Depends` y **FastAPI** sabe cómo hacer el resto.
+
+///
+
+## Compartir dependencias `Annotated`
+
+En los ejemplos anteriores, ves que hay un poquito de **duplicación de código**.
+
+Cuando necesitas usar la dependencia `common_parameters()`, tienes que escribir todo el parámetro con la anotación de tipo y `Depends()`:
+
+```Python
+commons: Annotated[dict, Depends(common_parameters)]
+```
+
+Pero como estamos usando `Annotated`, podemos almacenar ese valor `Annotated` en una variable y usarlo en múltiples lugares:
+
+{* ../../docs_src/dependencies/tutorial001_02_an_py310.py hl[12,16,21] *}
+
+/// tip | Consejo
+
+Esto es solo Python estándar, se llama un "alias de tipo", en realidad no es específico de **FastAPI**.
+
+Pero porque **FastAPI** está basado en los estándares de Python, incluido `Annotated`, puedes usar este truco en tu código. 😎
+
+///
+
+Las dependencias seguirán funcionando como se esperaba, y la **mejor parte** es que la **información de tipo se preservará**, lo que significa que tu editor podrá seguir proporcionándote **autocompletado**, **errores en línea**, etc. Lo mismo para otras herramientas como `mypy`.
+
+Esto será especialmente útil cuando lo uses en una **gran base de código** donde uses **las mismas dependencias** una y otra vez en **muchas *path operations***.
+
+## Usar `async` o no usar `async`
+
+Como las dependencias también serán llamadas por **FastAPI** (lo mismo que tus *path operation functions*), las mismas reglas aplican al definir tus funciones.
+
+Puedes usar `async def` o `def` normal.
+
+Y puedes declarar dependencias con `async def` dentro de *path operation functions* normales `def`, o dependencias `def` dentro de *path operation functions* `async def`, etc.
+
+No importa. **FastAPI** sabrá qué hacer.
+
+/// note | Nota
+
+Si no lo sabes, revisa la sección [Async: *"¿Con prisa?"*](../../async.md#in-a-hurry){.internal-link target=_blank} sobre `async` y `await` en la documentación.
+
+///
+
+## Integración con OpenAPI
+
+Todas las declaraciones de request, validaciones y requisitos de tus dependencias (y sub-dependencias) se integrarán en el mismo esquema de OpenAPI.
+
+Así, la documentación interactiva tendrá toda la información de estas dependencias también:
+
+
+
+## Uso simple
+
+Si lo ves, las *path operation functions* se declaran para ser usadas siempre que un *path* y una *operación* coincidan, y luego **FastAPI** se encarga de llamar la función con los parámetros correctos, extrayendo los datos del request.
+
+En realidad, todos (o la mayoría) de los frameworks web funcionan de esta misma manera.
+
+Nunca llamas directamente a esas funciones. Son llamadas por tu framework (en este caso, **FastAPI**).
+
+Con el sistema de Inyección de Dependencias, también puedes decirle a **FastAPI** que tu *path operation function* también "depende" de algo más que debe ejecutarse antes que tu *path operation function*, y **FastAPI** se encargará de ejecutarlo e "inyectar" los resultados.
+
+Otros términos comunes para esta misma idea de "inyección de dependencias" son:
+
+* recursos
+* proveedores
+* servicios
+* inyectables
+* componentes
+
+## Plug-ins de **FastAPI**
+
+Las integraciones y "plug-ins" pueden construirse usando el sistema de **Inyección de Dependencias**. Pero, de hecho, en realidad **no hay necesidad de crear "plug-ins"**, ya que al usar dependencias es posible declarar una cantidad infinita de integraciones e interacciones que se vuelven disponibles para tus *path operation functions*.
+
+Y las dependencias se pueden crear de una manera muy simple e intuitiva que te permite simplemente importar los paquetes de Python que necesitas, e integrarlos con tus funciones de API en un par de líneas de código, *literalmente*.
+
+Verás ejemplos de esto en los próximos capítulos, sobre bases de datos relacionales y NoSQL, seguridad, etc.
+
+## Compatibilidad de **FastAPI**
+
+La simplicidad del sistema de inyección de dependencias hace que **FastAPI** sea compatible con:
+
+* todas las bases de datos relacionales
+* bases de datos NoSQL
+* paquetes externos
+* APIs externas
+* sistemas de autenticación y autorización
+* sistemas de monitoreo de uso de la API
+* sistemas de inyección de datos de response
+* etc.
+
+## Simple y Poderoso
+
+Aunque el sistema de inyección de dependencias jerárquico es muy simple de definir y usar, sigue siendo muy poderoso.
+
+Puedes definir dependencias que a su vez pueden definir dependencias ellas mismas.
+
+Al final, se construye un árbol jerárquico de dependencias, y el sistema de **Inyección de Dependencias** se encarga de resolver todas estas dependencias por ti (y sus sub-dependencias) y proporcionar (inyectar) los resultados en cada paso.
+
+Por ejemplo, digamos que tienes 4 endpoints de API (*path operations*):
+
+* `/items/public/`
+* `/items/private/`
+* `/users/{user_id}/activate`
+* `/items/pro/`
+
+entonces podrías agregar diferentes requisitos de permiso para cada uno de ellos solo con dependencias y sub-dependencias:
+
+```mermaid
+graph TB
+
+current_user(["current_user"])
+active_user(["active_user"])
+admin_user(["admin_user"])
+paying_user(["paying_user"])
+
+public["/items/public/"]
+private["/items/private/"]
+activate_user["/users/{user_id}/activate"]
+pro_items["/items/pro/"]
+
+current_user --> active_user
+active_user --> admin_user
+active_user --> paying_user
+
+current_user --> public
+active_user --> private
+admin_user --> activate_user
+paying_user --> pro_items
+```
+
+## Integrado con **OpenAPI**
+
+Todas estas dependencias, al declarar sus requisitos, también añaden parámetros, validaciones, etc. a tus *path operations*.
+
+**FastAPI** se encargará de agregar todo al esquema de OpenAPI, para que se muestre en los sistemas de documentación interactiva.
diff --git a/docs/es/docs/tutorial/dependencies/sub-dependencies.md b/docs/es/docs/tutorial/dependencies/sub-dependencies.md
new file mode 100644
index 000000000..bba532207
--- /dev/null
+++ b/docs/es/docs/tutorial/dependencies/sub-dependencies.md
@@ -0,0 +1,105 @@
+# Sub-dependencias
+
+Puedes crear dependencias que tengan **sub-dependencias**.
+
+Pueden ser tan **profundas** como necesites.
+
+**FastAPI** se encargará de resolverlas.
+
+## Primera dependencia "dependable"
+
+Podrías crear una primera dependencia ("dependable") así:
+
+{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[8:9] *}
+
+Declara un parámetro de query opcional `q` como un `str`, y luego simplemente lo devuelve.
+
+Esto es bastante simple (no muy útil), pero nos ayudará a centrarnos en cómo funcionan las sub-dependencias.
+
+## Segunda dependencia, "dependable" y "dependant"
+
+Luego puedes crear otra función de dependencia (un "dependable") que al mismo tiempo declare una dependencia propia (por lo que también es un "dependant"):
+
+{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[13] *}
+
+Centrémonos en los parámetros declarados:
+
+* Aunque esta función es una dependencia ("dependable") en sí misma, también declara otra dependencia (depende de algo más).
+ * Depende del `query_extractor`, y asigna el valor que devuelve al parámetro `q`.
+* También declara una `last_query` cookie opcional, como un `str`.
+ * Si el usuario no proporcionó ningún query `q`, usamos el último query utilizado, que guardamos previamente en una cookie.
+
+## Usa la dependencia
+
+Entonces podemos usar la dependencia con:
+
+{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[23] *}
+
+/// info | Información
+
+Fíjate que solo estamos declarando una dependencia en la *path operation function*, `query_or_cookie_extractor`.
+
+Pero **FastAPI** sabrá que tiene que resolver `query_extractor` primero, para pasar los resultados de eso a `query_or_cookie_extractor` al llamarlo.
+
+///
+
+```mermaid
+graph TB
+
+query_extractor(["query_extractor"])
+query_or_cookie_extractor(["query_or_cookie_extractor"])
+
+read_query["/items/"]
+
+query_extractor --> query_or_cookie_extractor --> read_query
+```
+
+## Usando la misma dependencia múltiples veces
+
+Si una de tus dependencias se declara varias veces para la misma *path operation*, por ejemplo, múltiples dependencias tienen una sub-dependencia común, **FastAPI** sabrá llamar a esa sub-dependencia solo una vez por request.
+
+Y guardará el valor devuelto en un "cache" y lo pasará a todos los "dependants" que lo necesiten en ese request específico, en lugar de llamar a la dependencia varias veces para el mismo request.
+
+En un escenario avanzado donde sabes que necesitas que la dependencia se llame en cada paso (posiblemente varias veces) en el mismo request en lugar de usar el valor "cache", puedes establecer el parámetro `use_cache=False` al usar `Depends`:
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1"
+async def needy_dependency(fresh_value: Annotated[str, Depends(get_value, use_cache=False)]):
+ return {"fresh_value": fresh_value}
+```
+
+////
+
+//// tab | Python 3.8+ sin Anotaciones
+
+/// tip | Consejo
+
+Prefiere usar la versión `Annotated` si es posible.
+
+///
+
+```Python hl_lines="1"
+async def needy_dependency(fresh_value: str = Depends(get_value, use_cache=False)):
+ return {"fresh_value": fresh_value}
+```
+
+////
+
+## Resumen
+
+Aparte de todas las palabras rimbombantes usadas aquí, el sistema de **Inyección de Dependencias** es bastante simple.
+
+Solo son funciones que se ven igual que las *path operation functions*.
+
+Pero aun así, es muy potente y te permite declarar "grafos" de dependencia anidados arbitrariamente profundos (árboles).
+
+/// tip | Consejo
+
+Todo esto podría no parecer tan útil con estos ejemplos simples.
+
+Pero verás lo útil que es en los capítulos sobre **seguridad**.
+
+Y también verás la cantidad de código que te ahorrará.
+
+///
diff --git a/docs/es/docs/tutorial/encoder.md b/docs/es/docs/tutorial/encoder.md
new file mode 100644
index 000000000..9b8919d4b
--- /dev/null
+++ b/docs/es/docs/tutorial/encoder.md
@@ -0,0 +1,35 @@
+# JSON Compatible Encoder
+
+Hay algunos casos en los que podrías necesitar convertir un tipo de dato (como un modelo de Pydantic) a algo compatible con JSON (como un `dict`, `list`, etc).
+
+Por ejemplo, si necesitas almacenarlo en una base de datos.
+
+Para eso, **FastAPI** proporciona una función `jsonable_encoder()`.
+
+## Usando el `jsonable_encoder`
+
+Imaginemos que tienes una base de datos `fake_db` que solo recibe datos compatibles con JSON.
+
+Por ejemplo, no recibe objetos `datetime`, ya que no son compatibles con JSON.
+
+Entonces, un objeto `datetime` tendría que ser convertido a un `str` que contenga los datos en formato ISO.
+
+De la misma manera, esta base de datos no recibiría un modelo de Pydantic (un objeto con atributos), solo un `dict`.
+
+Puedes usar `jsonable_encoder` para eso.
+
+Recibe un objeto, como un modelo de Pydantic, y devuelve una versión compatible con JSON:
+
+{* ../../docs_src/encoder/tutorial001_py310.py hl[4,21] *}
+
+En este ejemplo, convertiría el modelo de Pydantic a un `dict`, y el `datetime` a un `str`.
+
+El resultado de llamarlo es algo que puede ser codificado con la función estándar de Python `json.dumps()`.
+
+No devuelve un gran `str` que contenga los datos en formato JSON (como una cadena de texto). Devuelve una estructura de datos estándar de Python (por ejemplo, un `dict`) con valores y sub-valores que son todos compatibles con JSON.
+
+/// note | Nota
+
+`jsonable_encoder` es utilizado internamente por **FastAPI** para convertir datos. Pero es útil en muchos otros escenarios.
+
+///
diff --git a/docs/es/docs/tutorial/extra-data-types.md b/docs/es/docs/tutorial/extra-data-types.md
new file mode 100644
index 000000000..28775780f
--- /dev/null
+++ b/docs/es/docs/tutorial/extra-data-types.md
@@ -0,0 +1,62 @@
+# Tipos de Datos Extra
+
+Hasta ahora, has estado usando tipos de datos comunes, como:
+
+* `int`
+* `float`
+* `str`
+* `bool`
+
+Pero también puedes usar tipos de datos más complejos.
+
+Y seguirás teniendo las mismas funcionalidades como hasta ahora:
+
+* Gran soporte de editor.
+* Conversión de datos de requests entrantes.
+* Conversión de datos para datos de response.
+* Validación de datos.
+* Anotación y documentación automática.
+
+## Otros tipos de datos
+
+Aquí hay algunos de los tipos de datos adicionales que puedes usar:
+
+* `UUID`:
+ * Un "Identificador Universalmente Único" estándar, común como un ID en muchas bases de datos y sistemas.
+ * En requests y responses se representará como un `str`.
+* `datetime.datetime`:
+ * Un `datetime.datetime` de Python.
+ * En requests y responses se representará como un `str` en formato ISO 8601, como: `2008-09-15T15:53:00+05:00`.
+* `datetime.date`:
+ * `datetime.date` de Python.
+ * En requests y responses se representará como un `str` en formato ISO 8601, como: `2008-09-15`.
+* `datetime.time`:
+ * Un `datetime.time` de Python.
+ * En requests y responses se representará como un `str` en formato ISO 8601, como: `14:23:55.003`.
+* `datetime.timedelta`:
+ * Un `datetime.timedelta` de Python.
+ * En requests y responses se representará como un `float` de segundos totales.
+ * Pydantic también permite representarlo como una "codificación de diferencia horaria ISO 8601", consulta la documentación para más información.
+* `frozenset`:
+ * En requests y responses, tratado igual que un `set`:
+ * En requests, se leerá una list, eliminando duplicados y convirtiéndola en un `set`.
+ * En responses, el `set` se convertirá en una `list`.
+ * El esquema generado especificará que los valores del `set` son únicos (usando `uniqueItems` de JSON Schema).
+* `bytes`:
+ * `bytes` estándar de Python.
+ * En requests y responses se tratará como `str`.
+ * El esquema generado especificará que es un `str` con "binary" como "format".
+* `Decimal`:
+ * `Decimal` estándar de Python.
+ * En requests y responses, manejado igual que un `float`.
+* Puedes revisar todos los tipos de datos válidos de Pydantic aquí: Tipos de datos de Pydantic.
+
+## Ejemplo
+
+Aquí tienes un ejemplo de una *path operation* con parámetros usando algunos de los tipos anteriores.
+
+{* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[1,3,12:16] *}
+
+Nota que los parámetros dentro de la función tienen su tipo de dato natural, y puedes, por ejemplo, realizar manipulaciones de fechas normales, como:
+
+{* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[18:19] *}
diff --git a/docs/es/docs/tutorial/extra-models.md b/docs/es/docs/tutorial/extra-models.md
new file mode 100644
index 000000000..0380b9690
--- /dev/null
+++ b/docs/es/docs/tutorial/extra-models.md
@@ -0,0 +1,222 @@
+# Modelos Extra
+
+Continuando con el ejemplo anterior, será común tener más de un modelo relacionado.
+
+Esto es especialmente el caso para los modelos de usuario, porque:
+
+* El **modelo de entrada** necesita poder tener una contraseña.
+* El **modelo de salida** no debería tener una contraseña.
+* El **modelo de base de datos** probablemente necesitaría tener una contraseña hasheada.
+
+/// danger | Peligro
+
+Nunca almacenes contraseñas de usuarios en texto plano. Siempre almacena un "hash seguro" que puedas verificar luego.
+
+Si no lo sabes, aprenderás qué es un "hash de contraseña" en los [capítulos de seguridad](security/simple-oauth2.md#password-hashing){.internal-link target=_blank}.
+
+///
+
+## Múltiples modelos
+
+Aquí tienes una idea general de cómo podrían ser los modelos con sus campos de contraseña y los lugares donde se utilizan:
+
+{* ../../docs_src/extra_models/tutorial001_py310.py hl[7,9,14,20,22,27:28,31:33,38:39] *}
+
+/// info | Información
+
+En Pydantic v1 el método se llamaba `.dict()`, fue deprecado (pero aún soportado) en Pydantic v2, y renombrado a `.model_dump()`.
+
+Los ejemplos aquí usan `.dict()` para compatibilidad con Pydantic v1, pero deberías usar `.model_dump()` en su lugar si puedes usar Pydantic v2.
+
+///
+
+### Acerca de `**user_in.dict()`
+
+#### `.dict()` de Pydantic
+
+`user_in` es un modelo Pydantic de la clase `UserIn`.
+
+Los modelos Pydantic tienen un método `.dict()` que devuelve un `dict` con los datos del modelo.
+
+Así que, si creamos un objeto Pydantic `user_in` como:
+
+```Python
+user_in = UserIn(username="john", password="secret", email="john.doe@example.com")
+```
+
+y luego llamamos a:
+
+```Python
+user_dict = user_in.dict()
+```
+
+ahora tenemos un `dict` con los datos en la variable `user_dict` (es un `dict` en lugar de un objeto modelo Pydantic).
+
+Y si llamamos a:
+
+```Python
+print(user_dict)
+```
+
+obtendremos un `dict` de Python con:
+
+```Python
+{
+ 'username': 'john',
+ 'password': 'secret',
+ 'email': 'john.doe@example.com',
+ 'full_name': None,
+}
+```
+
+#### Desempaquetando un `dict`
+
+Si tomamos un `dict` como `user_dict` y lo pasamos a una función (o clase) con `**user_dict`, Python lo "desempaquetará". Pasará las claves y valores del `user_dict` directamente como argumentos clave-valor.
+
+Así que, continuando con el `user_dict` anterior, escribir:
+
+```Python
+UserInDB(**user_dict)
+```
+
+sería equivalente a algo como:
+
+```Python
+UserInDB(
+ username="john",
+ password="secret",
+ email="john.doe@example.com",
+ full_name=None,
+)
+```
+
+O más exactamente, usando `user_dict` directamente, con cualquier contenido que pueda tener en el futuro:
+
+```Python
+UserInDB(
+ username = user_dict["username"],
+ password = user_dict["password"],
+ email = user_dict["email"],
+ full_name = user_dict["full_name"],
+)
+```
+
+#### Un modelo Pydantic a partir del contenido de otro
+
+Como en el ejemplo anterior obtuvimos `user_dict` de `user_in.dict()`, este código:
+
+```Python
+user_dict = user_in.dict()
+UserInDB(**user_dict)
+```
+
+sería equivalente a:
+
+```Python
+UserInDB(**user_in.dict())
+```
+
+...porque `user_in.dict()` es un `dict`, y luego hacemos que Python lo "desempaquete" al pasarlo a `UserInDB` con el prefijo `**`.
+
+Así, obtenemos un modelo Pydantic a partir de los datos en otro modelo Pydantic.
+
+#### Desempaquetando un `dict` y palabras clave adicionales
+
+Y luego agregando el argumento de palabra clave adicional `hashed_password=hashed_password`, como en:
+
+```Python
+UserInDB(**user_in.dict(), hashed_password=hashed_password)
+```
+
+...termina siendo como:
+
+```Python
+UserInDB(
+ username = user_dict["username"],
+ password = user_dict["password"],
+ email = user_dict["email"],
+ full_name = user_dict["full_name"],
+ hashed_password = hashed_password,
+)
+```
+
+/// warning | Advertencia
+
+Las funciones adicionales de soporte `fake_password_hasher` y `fake_save_user` son solo para demostrar un posible flujo de datos, pero por supuesto no proporcionan ninguna seguridad real.
+
+///
+
+## Reducir duplicación
+
+Reducir la duplicación de código es una de las ideas centrales en **FastAPI**.
+
+Ya que la duplicación de código incrementa las posibilidades de bugs, problemas de seguridad, problemas de desincronización de código (cuando actualizas en un lugar pero no en los otros), etc.
+
+Y estos modelos están compartiendo muchos de los datos y duplicando nombres y tipos de atributos.
+
+Podríamos hacerlo mejor.
+
+Podemos declarar un modelo `UserBase` que sirva como base para nuestros otros modelos. Y luego podemos hacer subclases de ese modelo que heredan sus atributos (declaraciones de tipo, validación, etc).
+
+Toda la conversión de datos, validación, documentación, etc. seguirá funcionando normalmente.
+
+De esa manera, podemos declarar solo las diferencias entre los modelos (con `password` en texto plano, con `hashed_password` y sin contraseña):
+
+{* ../../docs_src/extra_models/tutorial002_py310.py hl[7,13:14,17:18,21:22] *}
+
+## `Union` o `anyOf`
+
+Puedes declarar un response que sea la `Union` de dos o más tipos, eso significa que el response sería cualquiera de ellos.
+
+Se definirá en OpenAPI con `anyOf`.
+
+Para hacerlo, usa el type hint estándar de Python `typing.Union`:
+
+/// note | Nota
+
+Al definir una `Union`, incluye el tipo más específico primero, seguido por el tipo menos específico. En el ejemplo a continuación, el más específico `PlaneItem` viene antes de `CarItem` en `Union[PlaneItem, CarItem]`.
+
+///
+
+{* ../../docs_src/extra_models/tutorial003_py310.py hl[1,14:15,18:20,33] *}
+
+
+### `Union` en Python 3.10
+
+En este ejemplo pasamos `Union[PlaneItem, CarItem]` como el valor del argumento `response_model`.
+
+Porque lo estamos pasando como un **valor a un argumento** en lugar de ponerlo en una **anotación de tipo**, tenemos que usar `Union` incluso en Python 3.10.
+
+Si estuviera en una anotación de tipo podríamos haber usado la barra vertical, como:
+
+```Python
+some_variable: PlaneItem | CarItem
+```
+
+Pero si ponemos eso en la asignación `response_model=PlaneItem | CarItem` obtendríamos un error, porque Python intentaría realizar una **operación inválida** entre `PlaneItem` y `CarItem` en lugar de interpretar eso como una anotación de tipo.
+
+## Lista de modelos
+
+De la misma manera, puedes declarar responses de listas de objetos.
+
+Para eso, usa el `typing.List` estándar de Python (o simplemente `list` en Python 3.9 y posteriores):
+
+{* ../../docs_src/extra_models/tutorial004_py39.py hl[18] *}
+
+
+## Response con `dict` arbitrario
+
+También puedes declarar un response usando un `dict` arbitrario plano, declarando solo el tipo de las claves y valores, sin usar un modelo Pydantic.
+
+Esto es útil si no conoces los nombres de los campos/atributos válidos (que serían necesarios para un modelo Pydantic) de antemano.
+
+En este caso, puedes usar `typing.Dict` (o solo `dict` en Python 3.9 y posteriores):
+
+{* ../../docs_src/extra_models/tutorial005_py39.py hl[6] *}
+
+
+## Recapitulación
+
+Usa múltiples modelos Pydantic y hereda libremente para cada caso.
+
+No necesitas tener un solo modelo de datos por entidad si esa entidad debe poder tener diferentes "estados". Como el caso con la "entidad" usuario con un estado que incluye `password`, `password_hash` y sin contraseña.
diff --git a/docs/es/docs/tutorial/first-steps.md b/docs/es/docs/tutorial/first-steps.md
index c37ce00fb..5d869c22f 100644
--- a/docs/es/docs/tutorial/first-steps.md
+++ b/docs/es/docs/tutorial/first-steps.md
@@ -1,49 +1,74 @@
-# Primeros pasos
+# Primeros Pasos
-Un archivo muy simple de FastAPI podría verse así:
+El archivo FastAPI más simple podría verse así:
-```Python
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py *}
-Copia eso a un archivo `main.py`.
+Copia eso en un archivo `main.py`.
-Corre el servidor en vivo:
+Ejecuta el servidor en vivo:
get
+* usando una get operation
-!!! info "Información sobre `@decorator`"
- Esa sintaxis `@algo` se llama un "decorador" en Python.
+/// info | Información sobre `@decorator`
- Lo pones encima de una función. Es como un lindo sombrero decorado (creo que de ahí salió el concepto).
+Esa sintaxis `@algo` en Python se llama un "decorador".
- Un "decorador" toma la función que tiene debajo y hace algo con ella.
+Lo pones encima de una función. Como un bonito sombrero decorativo (supongo que de ahí viene el término).
- En nuestro caso, este decorador le dice a **FastAPI** que la función que está debajo corresponde al **path** `/` con una **operación** `get`.
+Un "decorador" toma la función de abajo y hace algo con ella.
- Es el "**decorador de operaciones de path**".
+En nuestro caso, este decorador le dice a **FastAPI** que la función de abajo corresponde al **path** `/` con una **operation** `get`.
+
+Es el "**path operation decorator**".
+
+///
También puedes usar las otras operaciones:
@@ -267,67 +265,67 @@ También puedes usar las otras operaciones:
* `@app.put()`
* `@app.delete()`
-y las más exóticas:
+Y los más exóticos:
* `@app.options()`
* `@app.head()`
* `@app.patch()`
* `@app.trace()`
-!!! tip "Consejo"
- Tienes la libertad de usar cada operación (método de HTTP) como quieras.
+/// tip
- **FastAPI** no impone ningún significado específico.
+Eres libre de usar cada operación (método HTTP) como quieras.
- La información que está presentada aquí es una guía, no un requerimiento.
+**FastAPI** no fuerza ningún significado específico.
- Por ejemplo, cuando usas GraphQL normalmente realizas todas las acciones usando únicamente operaciones `POST`.
+La información aquí se presenta como una guía, no un requisito.
-### Paso 4: define la **función de la operación de path**
+Por ejemplo, cuando usas GraphQL normalmente realizas todas las acciones usando solo operaciones `POST`.
-Esta es nuestra "**función de la operación de path**":
+///
+
+### Paso 4: define la **path operation function**
+
+Esta es nuestra "**path operation function**":
* **path**: es `/`.
-* **operación**: es `get`.
-* **función**: es la función debajo del "decorador" (debajo de `@app.get("/")`).
+* **operation**: es `get`.
+* **function**: es la función debajo del "decorador" (debajo de `@app.get("/")`).
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[7] *}
-Esto es una función de Python.
+Esta es una función de Python.
-Esta función será llamada por **FastAPI** cada vez que reciba un request en la URL "`/`" usando una operación `GET`.
+Será llamada por **FastAPI** cuando reciba un request en la URL "`/`" usando una operación `GET`.
-En este caso es una función `async`.
+En este caso, es una función `async`.
---
-También podrías definirla como una función estándar en lugar de `async def`:
+También podrías definirla como una función normal en lugar de `async def`:
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial003.py!}
-```
+{* ../../docs_src/first_steps/tutorial003.py hl[7] *}
-!!! note "Nota"
- Si no sabes la diferencia, revisa el [Async: *"¿Tienes prisa?"*](../async.md#tienes-prisa){.internal-link target=_blank}.
+/// note | Nota
-### Paso 5: devuelve el contenido
+Si no sabes la diferencia, revisa la sección [Async: *"¿Tienes prisa?"*](../async.md#in-a-hurry){.internal-link target=_blank}.
-```Python hl_lines="8"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+///
-Puedes devolver `dict`, `list`, valores singulares como un `str`, `int`, etc.
+### Paso 5: retorna el contenido
-También puedes devolver modelos de Pydantic (ya verás más sobre esto más adelante).
+{* ../../docs_src/first_steps/tutorial001.py hl[8] *}
-Hay muchos objetos y modelos que pueden ser convertidos automáticamente a JSON (incluyendo ORMs, etc.). Intenta usar tus favoritos, es muy probable que ya tengan soporte.
+Puedes retornar un `dict`, `list`, valores singulares como `str`, `int`, etc.
-## Repaso
+También puedes retornar modelos de Pydantic (verás más sobre eso más adelante).
+
+Hay muchos otros objetos y modelos que serán automáticamente convertidos a JSON (incluyendo ORMs, etc). Intenta usar tus favoritos, es altamente probable que ya sean compatibles.
+
+## Recapitulación
* Importa `FastAPI`.
-* Crea un instance de `app`.
-* Escribe un **decorador de operación de path** (como `@app.get("/")`).
-* Escribe una **función de la operación de path** (como `def root(): ...` arriba).
-* Corre el servidor de desarrollo (como `uvicorn main:app --reload`).
+* Crea una instancia `app`.
+* Escribe un **path operation decorator** usando decoradores como `@app.get("/")`.
+* Define una **path operation function**; por ejemplo, `def root(): ...`.
+* Ejecuta el servidor de desarrollo usando el comando `fastapi dev`.
diff --git a/docs/es/docs/tutorial/handling-errors.md b/docs/es/docs/tutorial/handling-errors.md
new file mode 100644
index 000000000..2e4464989
--- /dev/null
+++ b/docs/es/docs/tutorial/handling-errors.md
@@ -0,0 +1,255 @@
+# Manejo de Errores
+
+Existen muchas situaciones en las que necesitas notificar un error a un cliente que está usando tu API.
+
+Este cliente podría ser un navegador con un frontend, un código de otra persona, un dispositivo IoT, etc.
+
+Podrías necesitar decirle al cliente que:
+
+* El cliente no tiene suficientes privilegios para esa operación.
+* El cliente no tiene acceso a ese recurso.
+* El ítem al que el cliente intentaba acceder no existe.
+* etc.
+
+En estos casos, normalmente devolverías un **código de estado HTTP** en el rango de **400** (de 400 a 499).
+
+Esto es similar a los códigos de estado HTTP 200 (de 200 a 299). Esos códigos de estado "200" significan que de alguna manera hubo un "éxito" en el request.
+
+Los códigos de estado en el rango de 400 significan que hubo un error por parte del cliente.
+
+¿Recuerdas todos esos errores de **"404 Not Found"** (y chistes)?
+
+## Usa `HTTPException`
+
+Para devolver responses HTTP con errores al cliente, usa `HTTPException`.
+
+### Importa `HTTPException`
+
+{* ../../docs_src/handling_errors/tutorial001.py hl[1] *}
+
+### Lanza un `HTTPException` en tu código
+
+`HTTPException` es una excepción de Python normal con datos adicionales relevantes para APIs.
+
+Debido a que es una excepción de Python, no la `return`, sino que la `raise`.
+
+Esto también significa que si estás dentro de una función de utilidad que estás llamando dentro de tu *path operation function*, y lanzas el `HTTPException` desde dentro de esa función de utilidad, no se ejecutará el resto del código en la *path operation function*, terminará ese request de inmediato y enviará el error HTTP del `HTTPException` al cliente.
+
+El beneficio de lanzar una excepción en lugar de `return`ar un valor será más evidente en la sección sobre Dependencias y Seguridad.
+
+En este ejemplo, cuando el cliente solicita un ítem por un ID que no existe, lanza una excepción con un código de estado de `404`:
+
+{* ../../docs_src/handling_errors/tutorial001.py hl[11] *}
+
+### El response resultante
+
+Si el cliente solicita `http://example.com/items/foo` (un `item_id` `"foo"`), ese cliente recibirá un código de estado HTTP de 200, y un response JSON de:
+
+```JSON
+{
+ "item": "The Foo Wrestlers"
+}
+```
+
+Pero si el cliente solicita `http://example.com/items/bar` (un `item_id` inexistente `"bar"`), ese cliente recibirá un código de estado HTTP de 404 (el error "no encontrado"), y un response JSON de:
+
+```JSON
+{
+ "detail": "Item not found"
+}
+```
+
+/// tip | Consejo
+
+Cuando lanzas un `HTTPException`, puedes pasar cualquier valor que pueda convertirse a JSON como el parámetro `detail`, no solo `str`.
+
+Podrías pasar un `dict`, un `list`, etc.
+
+Son manejados automáticamente por **FastAPI** y convertidos a JSON.
+
+///
+
+## Agrega headers personalizados
+
+Existen algunas situaciones en las que es útil poder agregar headers personalizados al error HTTP. Por ejemplo, para algunos tipos de seguridad.
+
+Probablemente no necesitarás usarlos directamente en tu código.
+
+Pero en caso de que los necesites para un escenario avanzado, puedes agregar headers personalizados:
+
+{* ../../docs_src/handling_errors/tutorial002.py hl[14] *}
+
+## Instalar manejadores de excepciones personalizados
+
+Puedes agregar manejadores de excepciones personalizados con las mismas utilidades de excepciones de Starlette.
+
+Supongamos que tienes una excepción personalizada `UnicornException` que tú (o un paquete que usas) podría lanzar.
+
+Y quieres manejar esta excepción globalmente con FastAPI.
+
+Podrías agregar un manejador de excepciones personalizado con `@app.exception_handler()`:
+
+{* ../../docs_src/handling_errors/tutorial003.py hl[5:7,13:18,24] *}
+
+Aquí, si solicitas `/unicorns/yolo`, la *path operation* lanzará un `UnicornException`.
+
+Pero será manejado por el `unicorn_exception_handler`.
+
+Así que recibirás un error limpio, con un código de estado HTTP de `418` y un contenido JSON de:
+
+```JSON
+{"message": "Oops! yolo did something. There goes a rainbow..."}
+```
+
+/// note | Nota Técnica
+
+También podrías usar `from starlette.requests import Request` y `from starlette.responses import JSONResponse`.
+
+**FastAPI** ofrece las mismas `starlette.responses` como `fastapi.responses` solo como una conveniencia para ti, el desarrollador. Pero la mayoría de los responses disponibles vienen directamente de Starlette. Lo mismo con `Request`.
+
+///
+
+## Sobrescribir los manejadores de excepciones predeterminados
+
+**FastAPI** tiene algunos manejadores de excepciones predeterminados.
+
+Estos manejadores se encargan de devolver los responses JSON predeterminadas cuando lanzas un `HTTPException` y cuando el request tiene datos inválidos.
+
+Puedes sobrescribir estos manejadores de excepciones con los tuyos propios.
+
+### Sobrescribir excepciones de validación de request
+
+Cuando un request contiene datos inválidos, **FastAPI** lanza internamente un `RequestValidationError`.
+
+Y también incluye un manejador de excepciones predeterminado para ello.
+
+Para sobrescribirlo, importa el `RequestValidationError` y úsalo con `@app.exception_handler(RequestValidationError)` para decorar el manejador de excepciones.
+
+El manejador de excepciones recibirá un `Request` y la excepción.
+
+{* ../../docs_src/handling_errors/tutorial004.py hl[2,14:16] *}
+
+Ahora, si vas a `/items/foo`, en lugar de obtener el error JSON por defecto con:
+
+```JSON
+{
+ "detail": [
+ {
+ "loc": [
+ "path",
+ "item_id"
+ ],
+ "msg": "value is not a valid integer",
+ "type": "type_error.integer"
+ }
+ ]
+}
+```
+
+obtendrás una versión en texto, con:
+
+```
+1 validation error
+path -> item_id
+ value is not a valid integer (type=type_error.integer)
+```
+
+#### `RequestValidationError` vs `ValidationError`
+
+/// warning | Advertencia
+
+Estos son detalles técnicos que podrías omitir si no es importante para ti en este momento.
+
+///
+
+`RequestValidationError` es una subclase de `ValidationError` de Pydantic.
+
+**FastAPI** la usa para que, si usas un modelo Pydantic en `response_model`, y tus datos tienen un error, lo verás en tu log.
+
+Pero el cliente/usuario no lo verá. En su lugar, el cliente recibirá un "Error Interno del Servidor" con un código de estado HTTP `500`.
+
+Debería ser así porque si tienes un `ValidationError` de Pydantic en tu *response* o en cualquier lugar de tu código (no en el *request* del cliente), en realidad es un bug en tu código.
+
+Y mientras lo arreglas, tus clientes/usuarios no deberían tener acceso a información interna sobre el error, ya que eso podría exponer una vulnerabilidad de seguridad.
+
+### Sobrescribir el manejador de errores de `HTTPException`
+
+De la misma manera, puedes sobrescribir el manejador de `HTTPException`.
+
+Por ejemplo, podrías querer devolver un response de texto plano en lugar de JSON para estos errores:
+
+{* ../../docs_src/handling_errors/tutorial004.py hl[3:4,9:11,22] *}
+
+/// note | Nota Técnica
+
+También podrías usar `from starlette.responses import PlainTextResponse`.
+
+**FastAPI** ofrece las mismas `starlette.responses` como `fastapi.responses` solo como una conveniencia para ti, el desarrollador. Pero la mayoría de los responses disponibles vienen directamente de Starlette.
+
+///
+
+### Usar el body de `RequestValidationError`
+
+El `RequestValidationError` contiene el `body` que recibió con datos inválidos.
+
+Podrías usarlo mientras desarrollas tu aplicación para registrar el body y depurarlo, devolverlo al usuario, etc.
+
+{* ../../docs_src/handling_errors/tutorial005.py hl[14] *}
+
+Ahora intenta enviar un ítem inválido como:
+
+```JSON
+{
+ "title": "towel",
+ "size": "XL"
+}
+```
+
+Recibirás un response que te dirá que los datos son inválidos conteniendo el body recibido:
+
+```JSON hl_lines="12-15"
+{
+ "detail": [
+ {
+ "loc": [
+ "body",
+ "size"
+ ],
+ "msg": "value is not a valid integer",
+ "type": "type_error.integer"
+ }
+ ],
+ "body": {
+ "title": "towel",
+ "size": "XL"
+ }
+}
+```
+
+#### `HTTPException` de FastAPI vs `HTTPException` de Starlette
+
+**FastAPI** tiene su propio `HTTPException`.
+
+Y la clase de error `HTTPException` de **FastAPI** hereda de la clase de error `HTTPException` de Starlette.
+
+La única diferencia es que el `HTTPException` de **FastAPI** acepta cualquier dato JSON-able para el campo `detail`, mientras que el `HTTPException` de Starlette solo acepta strings para ello.
+
+Así que puedes seguir lanzando un `HTTPException` de **FastAPI** como de costumbre en tu código.
+
+Pero cuando registras un manejador de excepciones, deberías registrarlo para el `HTTPException` de Starlette.
+
+De esta manera, si alguna parte del código interno de Starlette, o una extensión o complemento de Starlette, lanza un `HTTPException` de Starlette, tu manejador podrá capturarlo y manejarlo.
+
+En este ejemplo, para poder tener ambos `HTTPException` en el mismo código, las excepciones de Starlette son renombradas a `StarletteHTTPException`:
+
+```Python
+from starlette.exceptions import HTTPException as StarletteHTTPException
+```
+
+### Reutilizar los manejadores de excepciones de **FastAPI**
+
+Si quieres usar la excepción junto con los mismos manejadores de excepciones predeterminados de **FastAPI**, puedes importar y reutilizar los manejadores de excepciones predeterminados de `fastapi.exception_handlers`:
+
+{* ../../docs_src/handling_errors/tutorial006.py hl[2:5,15,21] *}
+
+En este ejemplo solo estás `print`eando el error con un mensaje muy expresivo, pero te haces una idea. Puedes usar la excepción y luego simplemente reutilizar los manejadores de excepciones predeterminados.
diff --git a/docs/es/docs/tutorial/header-param-models.md b/docs/es/docs/tutorial/header-param-models.md
new file mode 100644
index 000000000..3676231e6
--- /dev/null
+++ b/docs/es/docs/tutorial/header-param-models.md
@@ -0,0 +1,56 @@
+# Modelos de Parámetros de Header
+
+Si tienes un grupo de **parámetros de header** relacionados, puedes crear un **modelo Pydantic** para declararlos.
+
+Esto te permitirá **reutilizar el modelo** en **múltiples lugares** y también declarar validaciones y metadatos para todos los parámetros al mismo tiempo. 😎
+
+/// note | Nota
+
+Esto es compatible desde la versión `0.115.0` de FastAPI. 🤓
+
+///
+
+## Parámetros de Header con un Modelo Pydantic
+
+Declara los **parámetros de header** que necesitas en un **modelo Pydantic**, y luego declara el parámetro como `Header`:
+
+{* ../../docs_src/header_param_models/tutorial001_an_py310.py hl[9:14,18] *}
+
+**FastAPI** **extraerá** los datos para **cada campo** de los **headers** en el request y te dará el modelo Pydantic que definiste.
+
+## Revisa la Documentación
+
+Puedes ver los headers requeridos en la interfaz de documentación en `/docs`:
+
+
+contact fields| Parámetro | Tipo | Descripción |
|---|---|---|
name | str | El nombre identificativo de la persona/organización de contacto. |
url | str | La URL que apunta a la información de contacto. DEBE tener el formato de una URL. |
email | str | La dirección de correo electrónico de la persona/organización de contacto. DEBE tener el formato de una dirección de correo. |
license_info fields| Parámetro | Tipo | Descripción |
|---|---|---|
name | str | REQUERIDO (si se establece un license_info). El nombre de la licencia utilizada para la API. |
identifier | str | Una expresión de licencia SPDX para la API. El campo identifier es mutuamente excluyente del campo url. Disponible desde OpenAPI 3.1.0, FastAPI 0.99.0. |
url | str | Una URL a la licencia utilizada para la API. DEBE tener el formato de una URL. |
+
+## Identificador de licencia
+
+Desde OpenAPI 3.1.0 y FastAPI 0.99.0, también puedes establecer la `license_info` con un `identifier` en lugar de una `url`.
+
+Por ejemplo:
+
+{* ../../docs_src/metadata/tutorial001_1.py hl[31] *}
+
+## Metadata para etiquetas
+
+También puedes agregar metadata adicional para las diferentes etiquetas usadas para agrupar tus path operations con el parámetro `openapi_tags`.
+
+Este toma una list que contiene un diccionario para cada etiqueta.
+
+Cada diccionario puede contener:
+
+* `name` (**requerido**): un `str` con el mismo nombre de etiqueta que usas en el parámetro `tags` en tus *path operations* y `APIRouter`s.
+* `description`: un `str` con una breve descripción de la etiqueta. Puede tener Markdown y se mostrará en la interfaz de documentación.
+* `externalDocs`: un `dict` que describe documentación externa con:
+ * `description`: un `str` con una breve descripción para la documentación externa.
+ * `url` (**requerido**): un `str` con la URL para la documentación externa.
+
+### Crear metadata para etiquetas
+
+Probemos eso en un ejemplo con etiquetas para `users` y `items`.
+
+Crea metadata para tus etiquetas y pásala al parámetro `openapi_tags`:
+
+{* ../../docs_src/metadata/tutorial004.py hl[3:16,18] *}
+
+Nota que puedes utilizar Markdown dentro de las descripciones, por ejemplo "login" se mostrará en negrita (**login**) y "fancy" se mostrará en cursiva (_fancy_).
+
+/// tip | Consejo
+
+No tienes que agregar metadata para todas las etiquetas que uses.
+
+///
+
+### Usar tus etiquetas
+
+Usa el parámetro `tags` con tus *path operations* (y `APIRouter`s) para asignarlas a diferentes etiquetas:
+
+{* ../../docs_src/metadata/tutorial004.py hl[21,26] *}
+
+/// info | Información
+
+Lee más sobre etiquetas en [Configuración de Path Operation](path-operation-configuration.md#tags){.internal-link target=_blank}.
+
+///
+
+### Revisa la documentación
+
+Ahora, si revisas la documentación, mostrará toda la metadata adicional:
+
+
+
+### Orden de las etiquetas
+
+El orden de cada diccionario de metadata de etiqueta también define el orden mostrado en la interfaz de documentación.
+
+Por ejemplo, aunque `users` iría después de `items` en orden alfabético, se muestra antes porque agregamos su metadata como el primer diccionario en la list.
+
+## URL de OpenAPI
+
+Por defecto, el esquema OpenAPI se sirve en `/openapi.json`.
+
+Pero puedes configurarlo con el parámetro `openapi_url`.
+
+Por ejemplo, para configurarlo para que se sirva en `/api/v1/openapi.json`:
+
+{* ../../docs_src/metadata/tutorial002.py hl[3] *}
+
+Si quieres deshabilitar el esquema OpenAPI completamente, puedes establecer `openapi_url=None`, eso también deshabilitará las interfaces de usuario de documentación que lo usan.
+
+## URLs de Docs
+
+Puedes configurar las dos interfaces de usuario de documentación incluidas:
+
+* **Swagger UI**: servida en `/docs`.
+ * Puedes establecer su URL con el parámetro `docs_url`.
+ * Puedes deshabilitarla estableciendo `docs_url=None`.
+* **ReDoc**: servida en `/redoc`.
+ * Puedes establecer su URL con el parámetro `redoc_url`.
+ * Puedes deshabilitarla estableciendo `redoc_url=None`.
+
+Por ejemplo, para configurar Swagger UI para que se sirva en `/documentation` y deshabilitar ReDoc:
+
+{* ../../docs_src/metadata/tutorial003.py hl[3] *}
diff --git a/docs/es/docs/tutorial/middleware.md b/docs/es/docs/tutorial/middleware.md
new file mode 100644
index 000000000..296374525
--- /dev/null
+++ b/docs/es/docs/tutorial/middleware.md
@@ -0,0 +1,72 @@
+# Middleware
+
+Puedes añadir middleware a las aplicaciones de **FastAPI**.
+
+Un "middleware" es una función que trabaja con cada **request** antes de que sea procesada por cualquier *path operation* específica. Y también con cada **response** antes de devolverla.
+
+* Toma cada **request** que llega a tu aplicación.
+* Puede entonces hacer algo a esa **request** o ejecutar cualquier código necesario.
+* Luego pasa la **request** para que sea procesada por el resto de la aplicación (por alguna *path operation*).
+* Después toma la **response** generada por la aplicación (por alguna *path operation*).
+* Puede hacer algo a esa **response** o ejecutar cualquier código necesario.
+* Luego devuelve la **response**.
+
+/// note | Detalles Técnicos
+
+Si tienes dependencias con `yield`, el código de salida se ejecutará *después* del middleware.
+
+Si hubiera alguna tarea en segundo plano (documentada más adelante), se ejecutará *después* de todo el middleware.
+
+///
+
+## Crear un middleware
+
+Para crear un middleware usas el decorador `@app.middleware("http")` encima de una función.
+
+La función middleware recibe:
+
+* La `request`.
+* Una función `call_next` que recibirá la `request` como parámetro.
+ * Esta función pasará la `request` a la correspondiente *path operation*.
+ * Luego devuelve la `response` generada por la correspondiente *path operation*.
+* Puedes entonces modificar aún más la `response` antes de devolverla.
+
+{* ../../docs_src/middleware/tutorial001.py hl[8:9,11,14] *}
+
+/// tip | Consejo
+
+Ten en cuenta que los custom proprietary headers se pueden añadir usando el prefijo 'X-'.
+
+Pero si tienes custom headers que deseas que un cliente en un navegador pueda ver, necesitas añadirlos a tus configuraciones de CORS ([CORS (Cross-Origin Resource Sharing)](cors.md){.internal-link target=_blank}) usando el parámetro `expose_headers` documentado en la documentación de CORS de Starlette.
+
+///
+
+/// note | Detalles Técnicos
+
+También podrías usar `from starlette.requests import Request`.
+
+**FastAPI** lo proporciona como una conveniencia para ti, el desarrollador. Pero viene directamente de Starlette.
+
+///
+
+### Antes y después de la `response`
+
+Puedes añadir código que se ejecute con la `request`, antes de que cualquier *path operation* la reciba.
+
+Y también después de que se genere la `response`, antes de devolverla.
+
+Por ejemplo, podrías añadir un custom header `X-Process-Time` que contenga el tiempo en segundos que tomó procesar la request y generar una response:
+
+{* ../../docs_src/middleware/tutorial001.py hl[10,12:13] *}
+
+/// tip | Consejo
+
+Aquí usamos `time.perf_counter()` en lugar de `time.time()` porque puede ser más preciso para estos casos de uso. 🤓
+
+///
+
+## Otros middlewares
+
+Más adelante puedes leer sobre otros middlewares en la [Guía del Usuario Avanzado: Middleware Avanzado](../advanced/middleware.md){.internal-link target=_blank}.
+
+Leerás sobre cómo manejar CORS con un middleware en la siguiente sección.
diff --git a/docs/es/docs/tutorial/path-operation-configuration.md b/docs/es/docs/tutorial/path-operation-configuration.md
new file mode 100644
index 000000000..909cd69b9
--- /dev/null
+++ b/docs/es/docs/tutorial/path-operation-configuration.md
@@ -0,0 +1,107 @@
+# Configuración de Path Operation
+
+Hay varios parámetros que puedes pasar a tu *path operation decorator* para configurarlo.
+
+/// warning | Advertencia
+
+Ten en cuenta que estos parámetros se pasan directamente al *path operation decorator*, no a tu *path operation function*.
+
+///
+
+## Código de Estado del Response
+
+Puedes definir el `status_code` (HTTP) que se utilizará en el response de tu *path operation*.
+
+Puedes pasar directamente el código `int`, como `404`.
+
+Pero si no recuerdas para qué es cada código numérico, puedes usar las constantes atajo en `status`:
+
+{* ../../docs_src/path_operation_configuration/tutorial001_py310.py hl[1,15] *}
+
+Ese código de estado se usará en el response y se añadirá al esquema de OpenAPI.
+
+/// note | Detalles Técnicos
+
+También podrías usar `from starlette import status`.
+
+**FastAPI** ofrece el mismo `starlette.status` como `fastapi.status` solo por conveniencia para ti, el desarrollador. Pero viene directamente de Starlette.
+
+///
+
+## Tags
+
+Puedes añadir tags a tu *path operation*, pasando el parámetro `tags` con un `list` de `str` (comúnmente solo una `str`):
+
+{* ../../docs_src/path_operation_configuration/tutorial002_py310.py hl[15,20,25] *}
+
+Serán añadidas al esquema de OpenAPI y usadas por las interfaces de documentación automática:
+
+
+
+### Tags con Enums
+
+Si tienes una gran aplicación, podrías terminar acumulando **varias tags**, y querrías asegurarte de que siempre uses la **misma tag** para *path operations* relacionadas.
+
+En estos casos, podría tener sentido almacenar las tags en un `Enum`.
+
+**FastAPI** soporta eso de la misma manera que con strings normales:
+
+{* ../../docs_src/path_operation_configuration/tutorial002b.py hl[1,8:10,13,18] *}
+
+## Resumen y Descripción
+
+Puedes añadir un `summary` y `description`:
+
+{* ../../docs_src/path_operation_configuration/tutorial003_py310.py hl[18:19] *}
+
+## Descripción desde docstring
+
+Como las descripciones tienden a ser largas y cubrir múltiples líneas, puedes declarar la descripción de la *path operation* en la docstring de la función y **FastAPI** la leerá desde allí.
+
+Puedes escribir Markdown en el docstring, se interpretará y mostrará correctamente (teniendo en cuenta la indentación del docstring).
+
+{* ../../docs_src/path_operation_configuration/tutorial004_py310.py hl[17:25] *}
+
+Será usado en la documentación interactiva:
+
+
+
+## Descripción del Response
+
+Puedes especificar la descripción del response con el parámetro `response_description`:
+
+{* ../../docs_src/path_operation_configuration/tutorial005_py310.py hl[19] *}
+
+/// info | Información
+
+Ten en cuenta que `response_description` se refiere específicamente al response, mientras que `description` se refiere a la *path operation* en general.
+
+///
+
+/// check | Revisa
+
+OpenAPI especifica que cada *path operation* requiere una descripción de response.
+
+Entonces, si no proporcionas una, **FastAPI** generará automáticamente una de "Response exitoso".
+
+///
+
+
+
+## Deprecar una *path operation*
+
+Si necesitas marcar una *path operation* como deprecated, pero sin eliminarla, pasa el parámetro `deprecated`:
+
+{* ../../docs_src/path_operation_configuration/tutorial006.py hl[16] *}
+
+Se marcará claramente como deprecado en la documentación interactiva:
+
+
+
+Revisa cómo lucen las *path operations* deprecadas y no deprecadas:
+
+
+
+## Resumen
+
+Puedes configurar y añadir metadatos a tus *path operations* fácilmente pasando parámetros a los *path operation decorators*.
diff --git a/docs/es/docs/tutorial/path-params-numeric-validations.md b/docs/es/docs/tutorial/path-params-numeric-validations.md
new file mode 100644
index 000000000..44d73b5ed
--- /dev/null
+++ b/docs/es/docs/tutorial/path-params-numeric-validations.md
@@ -0,0 +1,164 @@
+# Parámetros de Path y Validaciones Numéricas
+
+De la misma manera que puedes declarar más validaciones y metadatos para los parámetros de query con `Query`, puedes declarar el mismo tipo de validaciones y metadatos para los parámetros de path con `Path`.
+
+## Importar Path
+
+Primero, importa `Path` de `fastapi`, e importa `Annotated`:
+
+{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[1,3] *}
+
+/// info | Información
+
+FastAPI agregó soporte para `Annotated` (y comenzó a recomendar su uso) en la versión 0.95.0.
+
+Si tienes una versión anterior, obtendrás errores al intentar usar `Annotated`.
+
+Asegúrate de [Actualizar la versión de FastAPI](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank} a al menos la 0.95.1 antes de usar `Annotated`.
+
+///
+
+## Declarar metadatos
+
+Puedes declarar todos los mismos parámetros que para `Query`.
+
+Por ejemplo, para declarar un valor de metadato `title` para el parámetro de path `item_id` puedes escribir:
+
+{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[10] *}
+
+/// note | Nota
+
+Un parámetro de path siempre es requerido ya que tiene que formar parte del path. Incluso si lo declaras con `None` o le asignas un valor por defecto, no afectará en nada, siempre será requerido.
+
+///
+
+## Ordena los parámetros como necesites
+
+/// tip | Consejo
+
+Esto probablemente no es tan importante o necesario si usas `Annotated`.
+
+///
+
+Supongamos que quieres declarar el parámetro de query `q` como un `str` requerido.
+
+Y no necesitas declarar nada más para ese parámetro, así que realmente no necesitas usar `Query`.
+
+Pero aún necesitas usar `Path` para el parámetro de path `item_id`. Y no quieres usar `Annotated` por alguna razón.
+
+Python se quejará si pones un valor con un "default" antes de un valor que no tenga un "default".
+
+Pero puedes reordenarlos y poner el valor sin un default (el parámetro de query `q`) primero.
+
+No importa para **FastAPI**. Detectará los parámetros por sus nombres, tipos y declaraciones por defecto (`Query`, `Path`, etc.), no le importa el orden.
+
+Así que puedes declarar tu función como:
+
+//// tab | Python 3.8 non-Annotated
+
+/// tip | Consejo
+
+Prefiere usar la versión `Annotated` si es posible.
+
+///
+
+{* ../../docs_src/path_params_numeric_validations/tutorial002.py hl[7] *}
+
+////
+
+Pero ten en cuenta que si usas `Annotated`, no tendrás este problema, no importará ya que no estás usando los valores por defecto de los parámetros de la función para `Query()` o `Path()`.
+
+{* ../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py *}
+
+## Ordena los parámetros como necesites, trucos
+
+/// tip | Consejo
+
+Esto probablemente no es tan importante o necesario si usas `Annotated`.
+
+///
+
+Aquí hay un **pequeño truco** que puede ser útil, pero no lo necesitarás a menudo.
+
+Si quieres:
+
+* declarar el parámetro de query `q` sin un `Query` ni ningún valor por defecto
+* declarar el parámetro de path `item_id` usando `Path`
+* tenerlos en un orden diferente
+* no usar `Annotated`
+
+...Python tiene una sintaxis especial para eso.
+
+Pasa `*`, como el primer parámetro de la función.
+
+Python no hará nada con ese `*`, pero sabrá que todos los parámetros siguientes deben ser llamados como argumentos de palabras clave (parejas key-value), también conocidos como kwargs. Incluso si no tienen un valor por defecto.
+
+{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *}
+
+### Mejor con `Annotated`
+
+Ten en cuenta que si usas `Annotated`, como no estás usando valores por defecto de los parámetros de la función, no tendrás este problema y probablemente no necesitarás usar `*`.
+
+{* ../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py hl[10] *}
+
+## Validaciones numéricas: mayor o igual
+
+Con `Query` y `Path` (y otros que verás más adelante) puedes declarar restricciones numéricas.
+
+Aquí, con `ge=1`, `item_id` necesitará ser un número entero "`g`reater than or `e`qual" a `1`.
+
+{* ../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py hl[10] *}
+
+## Validaciones numéricas: mayor que y menor o igual
+
+Lo mismo aplica para:
+
+* `gt`: `g`reater `t`han
+* `le`: `l`ess than or `e`qual
+
+{* ../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py hl[10] *}
+
+## Validaciones numéricas: flotantes, mayor y menor
+
+Las validaciones numéricas también funcionan para valores `float`.
+
+Aquí es donde se convierte en importante poder declarar gt y no solo ge. Ya que con esto puedes requerir, por ejemplo, que un valor sea mayor que `0`, incluso si es menor que `1`.
+
+Así, `0.5` sería un valor válido. Pero `0.0` o `0` no lo serían.
+
+Y lo mismo para lt.
+
+{* ../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py hl[13] *}
+
+## Resumen
+
+Con `Query`, `Path` (y otros que aún no has visto) puedes declarar metadatos y validaciones de string de las mismas maneras que con [Parámetros de Query y Validaciones de String](query-params-str-validations.md){.internal-link target=_blank}.
+
+Y también puedes declarar validaciones numéricas:
+
+* `gt`: `g`reater `t`han
+* `ge`: `g`reater than or `e`qual
+* `lt`: `l`ess `t`han
+* `le`: `l`ess than or `e`qual
+
+/// info | Información
+
+`Query`, `Path` y otras clases que verás más adelante son subclases de una clase común `Param`.
+
+Todas ellas comparten los mismos parámetros para validación adicional y metadatos que has visto.
+
+///
+
+/// note | Nota técnica
+
+Cuando importas `Query`, `Path` y otros de `fastapi`, en realidad son funciones.
+
+Que cuando se llaman, retornan instances de clases con el mismo nombre.
+
+Así que importas `Query`, que es una función. Y cuando la llamas, retorna una instance de una clase también llamada `Query`.
+
+Estas funciones están allí (en lugar de usar simplemente las clases directamente) para que tu editor no marque errores sobre sus tipos.
+
+De esa forma puedes usar tu editor y herramientas de programación normales sin tener que agregar configuraciones personalizadas para omitir esos errores.
+
+///
diff --git a/docs/es/docs/tutorial/path-params.md b/docs/es/docs/tutorial/path-params.md
index 7faa92f51..12a1b647b 100644
--- a/docs/es/docs/tutorial/path-params.md
+++ b/docs/es/docs/tutorial/path-params.md
@@ -1,14 +1,12 @@
-# Parámetros de path
+# Parámetros de Path
-Puedes declarar los "parámetros" o "variables" con la misma sintaxis que usan los format strings de Python:
+Puedes declarar "parámetros" o "variables" de path con la misma sintaxis que se usa en los format strings de Python:
-```Python hl_lines="6-7"
-{!../../../docs_src/path_params/tutorial001.py!}
-```
+{* ../../docs_src/path_params/tutorial001.py hl[6:7] *}
-El valor del parámetro de path `item_id` será pasado a tu función como el argumento `item_id`.
+El valor del parámetro de path `item_id` se pasará a tu función como el argumento `item_id`.
-Entonces, si corres este ejemplo y vas a http://127.0.0.1:8000/items/foo, verás una respuesta de:
+Así que, si ejecutas este ejemplo y vas a http://127.0.0.1:8000/items/foo, verás un response de:
```JSON
{"item_id":"foo"}
@@ -16,175 +14,190 @@ Entonces, si corres este ejemplo y vas a Conversión de datos
+Esto te dará soporte del editor dentro de tu función, con chequeo de errores, autocompletado, etc.
-Si corres este ejemplo y abres tu navegador en http://127.0.0.1:8000/items/3 verás una respuesta de:
+///
+
+## Conversión de datos
+
+Si ejecutas este ejemplo y abres tu navegador en http://127.0.0.1:8000/items/3, verás un response de:
```JSON
{"item_id":3}
```
-!!! check "Revisa"
- Observa que el valor que recibió (y devolvió) tu función es `3`, como un Python `int`, y no un string `"3"`.
+/// check | Revisa
- Entonces, con esa declaración de tipos **FastAPI** te da "parsing" automático del request.
+Nota que el valor que tu función recibió (y devolvió) es `3`, como un `int` de Python, no un string `"3"`.
+
+Entonces, con esa declaración de tipo, **FastAPI** te ofrece "parsing" automático de requests.
+
+///
## Validación de datos
-Pero si abres tu navegador en http://127.0.0.1:8000/items/foo verás este lindo error de HTTP:
+Pero si vas al navegador en http://127.0.0.1:8000/items/foo, verás un bonito error HTTP de:
```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"
+ }
+ ]
}
```
-debido a que el parámetro de path `item_id` tenía el valor `"foo"`, que no es un `int`.
+porque el parámetro de path `item_id` tenía un valor de `"foo"`, que no es un `int`.
-El mismo error aparecería si pasaras un `float` en vez de un `int` como en: http://127.0.0.1:8000/items/4.2
+El mismo error aparecería si proporcionaras un `float` en lugar de un `int`, como en: http://127.0.0.1:8000/items/4.2
-!!! check "Revisa"
- Así, con la misma declaración de tipo de Python, **FastAPI** te da validación de datos.
+/// check | Revisa
- Observa que el error también muestra claramente el punto exacto en el que no pasó la validación.
+Entonces, con la misma declaración de tipo de Python, **FastAPI** te ofrece validación de datos.
- Esto es increíblemente útil cuando estás desarrollando y debugging código que interactúa con tu API.
+Nota que el error también indica claramente el punto exacto donde la validación falló.
+
+Esto es increíblemente útil mientras desarrollas y depuras código que interactúa con tu API.
+
+///
## Documentación
-Cuando abras tu navegador en http://127.0.0.1:8000/docs verás la documentación automática e interactiva del API como:
+Y cuando abras tu navegador en http://127.0.0.1:8000/docs, verás una documentación de API automática e interactiva como:
-!!! check "Revisa"
- Nuevamente, con la misma declaración de tipo de Python, **FastAPI** te da documentación automática e interactiva (integrándose con Swagger UI)
+/// check | Revisa
- Observa que el parámetro de path está declarado como un integer.
+Nuevamente, solo con esa misma declaración de tipo de Python, **FastAPI** te ofrece documentación automática e interactiva (integrando Swagger UI).
+
+Nota que el parámetro de path está declarado como un entero.
+
+///
## Beneficios basados en estándares, documentación alternativa
-Debido a que el schema generado es del estándar OpenAPI hay muchas herramientas compatibles.
+Y porque el esquema generado es del estándar OpenAPI, hay muchas herramientas compatibles.
-Es por esto que **FastAPI** mismo provee una documentación alternativa de la API (usando ReDoc), a la que puedes acceder en http://127.0.0.1:8000/redoc:
+Debido a esto, el propio **FastAPI** proporciona una documentación de API alternativa (usando ReDoc), a la cual puedes acceder en http://127.0.0.1:8000/redoc:
-De la misma manera hay muchas herramientas compatibles. Incluyendo herramientas de generación de código para muchos lenguajes.
+De la misma manera, hay muchas herramientas compatibles. Incluyendo herramientas de generación de código para muchos lenguajes.
## Pydantic
-Toda la validación de datos es realizada tras bastidores por Pydantic, así que obtienes todos sus beneficios. Así sabes que estás en buenas manos.
+Toda la validación de datos se realiza internamente con Pydantic, así que obtienes todos los beneficios de esta. Y sabes que estás en buenas manos.
-Puedes usar las mismas declaraciones de tipos con `str`, `float`, `bool` y otros tipos de datos más complejos.
+Puedes usar las mismas declaraciones de tipo con `str`, `float`, `bool` y muchos otros tipos de datos complejos.
-Exploraremos varios de estos tipos en los próximos capítulos del tutorial.
+Varios de estos se exploran en los siguientes capítulos del tutorial.
## El orden importa
-Cuando creas *operaciones de path* puedes encontrarte con situaciones en las que tengas un path fijo.
+Al crear *path operations*, puedes encontrarte en situaciones donde tienes un path fijo.
-Digamos algo como `/users/me` que sea para obtener datos del usuario actual.
+Como `/users/me`, imaginemos que es para obtener datos sobre el usuario actual.
-... y luego puedes tener el path `/users/{user_id}` para obtener los datos sobre un usuario específico asociados a un ID de usuario.
+Y luego también puedes tener un path `/users/{user_id}` para obtener datos sobre un usuario específico por algún ID de usuario.
-Porque las *operaciones de path* son evaluadas en orden, tienes que asegurarte de que el path para `/users/me` sea declarado antes que el path para `/users/{user_id}`:
+Debido a que las *path operations* se evalúan en orden, necesitas asegurarte de que el path para `/users/me` se declara antes que el de `/users/{user_id}`:
-```Python hl_lines="6 11"
-{!../../../docs_src/path_params/tutorial003.py!}
-```
+{* ../../docs_src/path_params/tutorial003.py hl[6,11] *}
-De otra manera el path para `/users/{user_id}` coincidiría también con `/users/me` "pensando" que está recibiendo el parámetro `user_id` con el valor `"me"`.
+De lo contrario, el path para `/users/{user_id}` también coincidiría para `/users/me`, "pensando" que está recibiendo un parámetro `user_id` con un valor de `"me"`.
+
+De manera similar, no puedes redefinir una path operation:
+
+{* ../../docs_src/path_params/tutorial003b.py hl[6,11] *}
+
+La primera siempre será utilizada ya que el path coincide primero.
## Valores predefinidos
-Si tienes una *operación de path* que recibe un *parámetro de path* pero quieres que los valores posibles del *parámetro de path* sean predefinidos puedes usar un `Enum` estándar de Python.
+Si tienes una *path operation* que recibe un *path parameter*, pero quieres que los valores posibles válidos del *path parameter* estén predefinidos, puedes usar un `Enum` estándar de Python.
-### Crea una clase `Enum`
+### Crear una clase `Enum`
-Importa `Enum` y crea una sub-clase que herede desde `str` y desde `Enum`.
+Importa `Enum` y crea una subclase que herede de `str` y de `Enum`.
-Al heredar desde `str` la documentación de la API podrá saber que los valores deben ser de tipo `string` y podrá mostrarlos correctamente.
+Al heredar de `str`, la documentación de la API podrá saber que los valores deben ser de tipo `string` y podrá representarlos correctamente.
-Luego crea atributos de clase con valores fijos, que serán los valores disponibles válidos:
+Luego crea atributos de clase con valores fijos, que serán los valores válidos disponibles:
-```Python hl_lines="1 6-9"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[1,6:9] *}
-!!! info "Información"
- Las Enumerations (o enums) están disponibles en Python desde la versión 3.4.
+/// info | Información
-!!! tip "Consejo"
- Si lo estás dudando, "AlexNet", "ResNet", y "LeNet" son solo nombres de modelos de Machine Learning.
+Las enumeraciones (o enums) están disponibles en Python desde la versión 3.4.
-### Declara un *parámetro de path*
+///
-Luego, crea un *parámetro de path* con anotaciones de tipos usando la clase enum que creaste (`ModelName`):
+/// tip | Consejo
-```Python hl_lines="16"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+Si te estás preguntando, "AlexNet", "ResNet" y "LeNet" son solo nombres de modelos de Machine Learning.
+
+///
+
+### Declarar un *path parameter*
+
+Luego crea un *path parameter* con una anotación de tipo usando la clase enum que creaste (`ModelName`):
+
+{* ../../docs_src/path_params/tutorial005.py hl[16] *}
### Revisa la documentación
-Debido a que los valores disponibles para el *parámetro de path* están predefinidos, la documentación interactiva los puede mostrar bien:
+Como los valores disponibles para el *path parameter* están predefinidos, la documentación interactiva puede mostrarlos de manera ordenada:
-### Trabajando con los *enumerations* de Python
+### Trabajando con *enumeraciones* de Python
-El valor del *parámetro de path* será un *enumeration member*.
+El valor del *path parameter* será un *miembro* de enumeración.
-#### Compara *enumeration members*
+#### Comparar *miembros* de enumeraciones
-Puedes compararlo con el *enumeration member* en el enum (`ModelName`) que creaste:
+Puedes compararlo con el *miembro* de enumeración en tu enum creada `ModelName`:
-```Python hl_lines="17"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[17] *}
-#### Obtén el *enumeration value*
+#### Obtener el valor de *enumeración*
-Puedes obtener el valor exacto (un `str` en este caso) usando `model_name.value`, o en general, `your_enum_member.value`:
+Puedes obtener el valor actual (un `str` en este caso) usando `model_name.value`, o en general, `your_enum_member.value`:
-```Python hl_lines="20"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[20] *}
-!!! tip "Consejo"
- También podrías obtener el valor `"lenet"` con `ModelName.lenet.value`.
+/// tip | Consejo
-#### Devuelve *enumeration members*
+También podrías acceder al valor `"lenet"` con `ModelName.lenet.value`.
-Puedes devolver *enum members* desde tu *operación de path* inclusive en un body de JSON anidado (por ejemplo, un `dict`).
+///
-Ellos serán convertidos a sus valores correspondientes (strings en este caso) antes de devolverlos al cliente:
+#### Devolver *miembros* de enumeración
-```Python hl_lines="18 21 23"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+Puedes devolver *miembros de enum* desde tu *path operation*, incluso anidados en un cuerpo JSON (por ejemplo, un `dict`).
-En tu cliente obtendrás una respuesta en JSON como:
+Serán convertidos a sus valores correspondientes (cadenas en este caso) antes de devolverlos al cliente:
+
+{* ../../docs_src/path_params/tutorial005.py hl[18,21,23] *}
+
+En tu cliente recibirás un response JSON como:
```JSON
{
@@ -193,52 +206,53 @@ En tu cliente obtendrás una respuesta en JSON como:
}
```
-## Parámetros de path parameters que contienen paths
+## Parámetros de path conteniendo paths
-Digamos que tienes una *operación de path* con un path `/files/{file_path}`.
+Imaginemos que tienes una *path operation* con un path `/files/{file_path}`.
-Pero necesitas que el mismo `file_path` contenga un path como `home/johndoe/myfile.txt`.
+Pero necesitas que `file_path` en sí mismo contenga un *path*, como `home/johndoe/myfile.txt`.
Entonces, la URL para ese archivo sería algo como: `/files/home/johndoe/myfile.txt`.
### Soporte de OpenAPI
-OpenAPI no soporta una manera de declarar un *parámetro de path* que contenga un path, dado que esto podría llevar a escenarios que son difíciles de probar y definir.
+OpenAPI no soporta una manera de declarar un *path parameter* para que contenga un *path* dentro, ya que eso podría llevar a escenarios que son difíciles de probar y definir.
-Sin embargo, lo puedes hacer en **FastAPI** usando una de las herramientas internas de Starlette.
+Sin embargo, todavía puedes hacerlo en **FastAPI**, usando una de las herramientas internas de Starlette.
-La documentación seguirá funcionando, aunque no añadirá ninguna información diciendo que el parámetro debería contener un path.
+Y la documentación seguiría funcionando, aunque no agregue ninguna documentación indicando que el parámetro debe contener un path.
-### Convertidor de path
+### Convertidor de Path
-Usando una opción directamente desde Starlette puedes declarar un *parámetro de path* que contenga un path usando una URL como:
+Usando una opción directamente de Starlette puedes declarar un *path parameter* conteniendo un *path* usando una URL como:
```
/files/{file_path:path}
```
-En este caso el nombre del parámetro es `file_path` y la última parte, `:path`, le dice que el parámetro debería coincidir con cualquier path.
+En este caso, el nombre del parámetro es `file_path`, y la última parte, `:path`, indica que el parámetro debería coincidir con cualquier *path*.
-Entonces lo puedes usar con:
+Así que, puedes usarlo con:
-```Python hl_lines="6"
-{!../../../docs_src/path_params/tutorial004.py!}
-```
+{* ../../docs_src/path_params/tutorial004.py hl[6] *}
-!!! tip "Consejo"
- Podrías necesitar que el parámetro contenga `/home/johndoe/myfile.txt` con un slash inicial (`/`).
+/// tip | Consejo
- En este caso la URL sería `/files//home/johndoe/myfile.txt` con un slash doble (`//`) entre `files` y `home`.
+Podrías necesitar que el parámetro contenga `/home/johndoe/myfile.txt`, con una barra inclinada (`/`) inicial.
-## Repaso
+En ese caso, la URL sería: `/files//home/johndoe/myfile.txt`, con una doble barra inclinada (`//`) entre `files` y `home`.
-Con **FastAPI**, usando declaraciones de tipo de Python intuitivas y estándares, obtienes:
+///
-* Soporte en el editor: chequeo de errores, auto-completado, etc.
-* "Parsing" de datos
+## Resumen
+
+Con **FastAPI**, al usar declaraciones de tipo estándar de Python, cortas e intuitivas, obtienes:
+
+* Soporte del editor: chequeo de errores, autocompletado, etc.
+* "parsing" de datos
* Validación de datos
-* Anotación de la API y documentación automática
+* Anotación de API y documentación automática
-Solo tienes que declararlos una vez.
+Y solo tienes que declararlos una vez.
-Esa es probablemente la principal ventaja visible de **FastAPI** sobre otros frameworks alternativos (aparte del rendimiento puro).
+Probablemente esa sea la principal ventaja visible de **FastAPI** en comparación con otros frameworks alternativos (aparte del rendimiento bruto).
diff --git a/docs/es/docs/tutorial/query-param-models.md b/docs/es/docs/tutorial/query-param-models.md
new file mode 100644
index 000000000..8338fc358
--- /dev/null
+++ b/docs/es/docs/tutorial/query-param-models.md
@@ -0,0 +1,68 @@
+# Modelos de Parámetros Query
+
+Si tienes un grupo de **parámetros query** que están relacionados, puedes crear un **modelo de Pydantic** para declararlos.
+
+Esto te permitiría **reutilizar el modelo** en **múltiples lugares** y también declarar validaciones y metadatos para todos los parámetros de una vez. 😎
+
+/// note | Nota
+
+Esto es compatible desde la versión `0.115.0` de FastAPI. 🤓
+
+///
+
+## Parámetros Query con un Modelo Pydantic
+
+Declara los **parámetros query** que necesitas en un **modelo de Pydantic**, y luego declara el parámetro como `Query`:
+
+{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *}
+
+**FastAPI** **extraerá** los datos para **cada campo** de los **parámetros query** en el request y te proporcionará el modelo de Pydantic que definiste.
+
+## Revisa la Documentación
+
+Puedes ver los parámetros query en la UI de documentación en `/docs`:
+
+
+
+
+### Lista de parámetros de Query / múltiples valores con valores por defecto
+
+Y también puedes definir un valor por defecto `list` de valores si no se proporcionan ninguno:
+
+{* ../../docs_src/query_params_str_validations/tutorial012_an_py39.py hl[9] *}
+
+Si vas a:
+
+```
+http://localhost:8000/items/
+```
+
+el valor por defecto de `q` será: `["foo", "bar"]` y tu response será:
+
+```JSON
+{
+ "q": [
+ "foo",
+ "bar"
+ ]
+}
+```
+
+#### Usando solo `list`
+
+También puedes usar `list` directamente en lugar de `List[str]` (o `list[str]` en Python 3.9+):
+
+{* ../../docs_src/query_params_str_validations/tutorial013_an_py39.py hl[9] *}
+
+/// note | Nota
+
+Ten en cuenta que en este caso, FastAPI no comprobará el contenido de la lista.
+
+Por ejemplo, `List[int]` comprobaría (y documentaría) que el contenido de la lista son enteros. Pero `list` sola no lo haría.
+
+///
+
+## Declarar más metadatos
+
+Puedes agregar más información sobre el parámetro.
+
+Esa información se incluirá en el OpenAPI generado y será utilizada por las interfaces de usuario de documentación y herramientas externas.
+
+/// note | Nota
+
+Ten en cuenta que diferentes herramientas podrían tener diferentes niveles de soporte de OpenAPI.
+
+Algunas de ellas podrían no mostrar toda la información extra declarada todavía, aunque en la mayoría de los casos, la funcionalidad faltante ya está planificada para desarrollo.
+
+///
+
+Puedes agregar un `title`:
+
+{* ../../docs_src/query_params_str_validations/tutorial007_an_py310.py hl[10] *}
+
+Y una `description`:
+
+{* ../../docs_src/query_params_str_validations/tutorial008_an_py310.py hl[14] *}
+
+## Alias para parámetros
+
+Imagina que quieres que el parámetro sea `item-query`.
+
+Como en:
+
+```
+http://127.0.0.1:8000/items/?item-query=foobaritems
+```
+
+Pero `item-query` no es un nombre de variable válido en Python.
+
+Lo más cercano sería `item_query`.
+
+Pero aún necesitas que sea exactamente `item-query`...
+
+Entonces puedes declarar un `alias`, y ese alias será usado para encontrar el valor del parámetro:
+
+{* ../../docs_src/query_params_str_validations/tutorial009_an_py310.py hl[9] *}
+
+## Declarar parámetros obsoletos
+
+Ahora digamos que ya no te gusta este parámetro.
+
+Tienes que dejarlo allí por un tiempo porque hay clientes usándolo, pero quieres que la documentación lo muestre claramente como deprecated.
+
+Luego pasa el parámetro `deprecated=True` a `Query`:
+
+{* ../../docs_src/query_params_str_validations/tutorial010_an_py310.py hl[19] *}
+
+La documentación lo mostrará así:
+
+
+
+## Excluir parámetros de OpenAPI
+
+Para excluir un parámetro de query del esquema de OpenAPI generado (y por lo tanto, de los sistemas de documentación automática), establece el parámetro `include_in_schema` de `Query` a `False`:
+
+{* ../../docs_src/query_params_str_validations/tutorial014_an_py310.py hl[10] *}
+
+## Recapitulación
+
+Puedes declarar validaciones y metadatos adicionales para tus parámetros.
+
+Validaciones genéricas y metadatos:
+
+* `alias`
+* `title`
+* `description`
+* `deprecated`
+
+Validaciones específicas para strings:
+
+* `min_length`
+* `max_length`
+* `pattern`
+
+En estos ejemplos viste cómo declarar validaciones para valores de tipo `str`.
+
+Mira los siguientes capítulos para aprender cómo declarar validaciones para otros tipos, como números.
diff --git a/docs/es/docs/tutorial/query-params.md b/docs/es/docs/tutorial/query-params.md
index 76dc331a9..09c66a545 100644
--- a/docs/es/docs/tutorial/query-params.md
+++ b/docs/es/docs/tutorial/query-params.md
@@ -1,12 +1,10 @@
-# Parámetros de query
+# Parámetros de Query
-Cuando declaras otros parámetros de la función que no hacen parte de los parámetros de path estos se interpretan automáticamente como parámetros de "query".
+Cuando declaras otros parámetros de función que no son parte de los parámetros de path, son automáticamente interpretados como parámetros de "query".
-```Python hl_lines="9"
-{!../../../docs_src/query_params/tutorial001.py!}
-```
+{* ../../docs_src/query_params/tutorial001.py hl[9] *}
-El query es el conjunto de pares de key-value que van después del `?` en la URL, separados por caracteres `&`.
+La query es el conjunto de pares clave-valor que van después del `?` en una URL, separados por caracteres `&`.
Por ejemplo, en la URL:
@@ -19,36 +17,36 @@ http://127.0.0.1:8000/items/?skip=0&limit=10
* `skip`: con un valor de `0`
* `limit`: con un valor de `10`
-Dado que son parte de la URL son strings "naturalmente".
+Como son parte de la URL, son "naturalmente" strings.
-Pero cuando los declaras con tipos de Python (en el ejemplo arriba, como `int`) son convertidos a ese tipo y son validados con él.
+Pero cuando los declaras con tipos de Python (en el ejemplo anterior, como `int`), son convertidos a ese tipo y validados respecto a él.
-Todo el proceso que aplicaba a los parámetros de path también aplica a los parámetros de query:
+Todo el mismo proceso que se aplica para los parámetros de path también se aplica para los parámetros de query:
* Soporte del editor (obviamente)
-* "Parsing" de datos
+* "Parsing" de datos
* Validación de datos
* Documentación automática
-## Configuraciones por defecto
+## Valores por defecto
-Como los parámetros de query no están fijos en una parte del path pueden ser opcionales y pueden tener valores por defecto.
+Como los parámetros de query no son una parte fija de un path, pueden ser opcionales y pueden tener valores por defecto.
-El ejemplo arriba tiene `skip=0` y `limit=10` como los valores por defecto.
+En el ejemplo anterior, tienen valores por defecto de `skip=0` y `limit=10`.
-Entonces, si vas a la URL:
+Entonces, ir a la URL:
```
http://127.0.0.1:8000/items/
```
-Sería lo mismo que ir a:
+sería lo mismo que ir a:
```
http://127.0.0.1:8000/items/?skip=0&limit=10
```
-Pero, si por ejemplo vas a:
+Pero si vas a, por ejemplo:
```
http://127.0.0.1:8000/items/?skip=20
@@ -56,34 +54,26 @@ http://127.0.0.1:8000/items/?skip=20
Los valores de los parámetros en tu función serán:
-* `skip=20`: porque lo definiste en la URL
-* `limit=10`: porque era el valor por defecto
+* `skip=20`: porque lo configuraste en la URL
+* `limit=10`: porque ese era el valor por defecto
## Parámetros opcionales
-Del mismo modo puedes declarar parámetros de query opcionales definiendo el valor por defecto como `None`:
+De la misma manera, puedes declarar parámetros de query opcionales, estableciendo su valor por defecto en `None`:
-```Python hl_lines="9"
-{!../../../docs_src/query_params/tutorial002.py!}
-```
+{* ../../docs_src/query_params/tutorial002_py310.py hl[7] *}
-En este caso el parámetro de la función `q` será opcional y será `None` por defecto.
+/// check | Revisa
-!!! check "Revisa"
- También puedes notar que **FastAPI** es lo suficientemente inteligente para darse cuenta de que el parámetro de path `item_id` es un parámetro de path y que `q` no lo es, y por lo tanto es un parámetro de query.
+Además, nota que **FastAPI** es lo suficientemente inteligente para notar que el parámetro de path `item_id` es un parámetro de path y `q` no lo es, por lo tanto, es un parámetro de query.
-!!! note "Nota"
- FastAPI sabrá que `q` es opcional por el `= None`.
+///
- El `Union` en `Union[str, None]` no es usado por FastAPI (FastAPI solo usará la parte `str`), pero el `Union[str, None]` le permitirá a tu editor ayudarte a encontrar errores en tu código.
+## Conversión de tipos en parámetros de query
-## Conversión de tipos de parámetros de query
+También puedes declarar tipos `bool`, y serán convertidos:
-También puedes declarar tipos `bool` y serán convertidos:
-
-```Python hl_lines="9"
-{!../../../docs_src/query_params/tutorial003.py!}
-```
+{* ../../docs_src/query_params/tutorial003_py310.py hl[7] *}
En este caso, si vas a:
@@ -115,58 +105,56 @@ o
http://127.0.0.1:8000/items/foo?short=yes
```
-o cualquier otra variación (mayúsculas, primera letra en mayúscula, etc.) tu función verá el parámetro `short` con un valor `bool` de `True`. Si no, lo verá como `False`.
+o cualquier otra variación (mayúsculas, primera letra en mayúscula, etc.), tu función verá el parámetro `short` con un valor `bool` de `True`. De lo contrario, será `False`.
-## Múltiples parámetros de path y query
+## Múltiples parámetros de path y de query
-Puedes declarar múltiples parámetros de path y parámetros de query al mismo tiempo. **FastAPI** sabe cuál es cuál.
+Puedes declarar múltiples parámetros de path y de query al mismo tiempo, **FastAPI** sabe cuál es cuál.
-No los tienes que declarar en un orden específico.
+Y no tienes que declararlos en un orden específico.
Serán detectados por nombre:
-```Python hl_lines="8 10"
-{!../../../docs_src/query_params/tutorial004.py!}
-```
+{* ../../docs_src/query_params/tutorial004_py310.py hl[6,8] *}
## Parámetros de query requeridos
-Cuando declaras un valor por defecto para los parámetros que no son de path (por ahora solo hemos visto parámetros de query), entonces no es requerido.
+Cuando declaras un valor por defecto para parámetros que no son de path (por ahora, solo hemos visto parámetros de query), entonces no es requerido.
-Si no quieres añadir un valor específico sino solo hacerlo opcional, pon el valor por defecto como `None`.
+Si no quieres agregar un valor específico pero solo hacer que sea opcional, establece el valor por defecto como `None`.
-Pero cuando quieres hacer que un parámetro de query sea requerido, puedes simplemente no declararle un valor por defecto:
+Pero cuando quieres hacer un parámetro de query requerido, simplemente no declares ningún valor por defecto:
-```Python hl_lines="6-7"
-{!../../../docs_src/query_params/tutorial005.py!}
-```
+{* ../../docs_src/query_params/tutorial005.py hl[6:7] *}
-Aquí el parámetro de query `needy` es un parámetro de query requerido, del tipo `str`.
+Aquí el parámetro de query `needy` es un parámetro de query requerido de tipo `str`.
-Si abres tu navegador en una URL como:
+Si abres en tu navegador una URL como:
```
http://127.0.0.1:8000/items/foo-item
```
-...sin añadir el parámetro `needy` requerido, verás un error como:
+...sin agregar el parámetro requerido `needy`, verás un error como:
```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"
+ }
+ ]
}
```
-Dado que `needy` es un parámetro requerido necesitarías declararlo en la URL:
+Como `needy` es un parámetro requerido, necesitarías establecerlo en la URL:
```
http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
@@ -181,17 +169,18 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
}
```
-Por supuesto que también puedes definir algunos parámetros como requeridos, con un valor por defecto y otros completamente opcionales:
+Y por supuesto, puedes definir algunos parámetros como requeridos, algunos con un valor por defecto, y algunos enteramente opcionales:
-```Python hl_lines="10"
-{!../../../docs_src/query_params/tutorial006.py!}
-```
+{* ../../docs_src/query_params/tutorial006_py310.py hl[8] *}
-En este caso hay 3 parámetros de query:
+En este caso, hay 3 parámetros de query:
* `needy`, un `str` requerido.
* `skip`, un `int` con un valor por defecto de `0`.
* `limit`, un `int` opcional.
-!!! tip "Consejo"
- También podrías usar los `Enum`s de la misma manera que con los [Parámetros de path](path-params.md#valores-predefinidos){.internal-link target=_blank}.
+/// tip | Consejo
+
+También podrías usar `Enum`s de la misma manera que con [Parámetros de Path](path-params.md#predefined-values){.internal-link target=_blank}.
+
+///
diff --git a/docs/es/docs/tutorial/request-files.md b/docs/es/docs/tutorial/request-files.md
new file mode 100644
index 000000000..330523c7e
--- /dev/null
+++ b/docs/es/docs/tutorial/request-files.md
@@ -0,0 +1,176 @@
+# Archivos de Request
+
+Puedes definir archivos que serán subidos por el cliente utilizando `File`.
+
+/// info | Información
+
+Para recibir archivos subidos, primero instala `python-multipart`.
+
+Asegúrate de crear un [entorno virtual](../virtual-environments.md){.internal-link target=_blank}, activarlo y luego instalarlo, por ejemplo:
+
+```console
+$ pip install python-multipart
+```
+
+Esto es porque los archivos subidos se envían como "form data".
+
+///
+
+## Importar `File`
+
+Importa `File` y `UploadFile` desde `fastapi`:
+
+{* ../../docs_src/request_files/tutorial001_an_py39.py hl[3] *}
+
+## Definir Parámetros `File`
+
+Crea parámetros de archivo de la misma manera que lo harías para `Body` o `Form`:
+
+{* ../../docs_src/request_files/tutorial001_an_py39.py hl[9] *}
+
+/// info | Información
+
+`File` es una clase que hereda directamente de `Form`.
+
+Pero recuerda que cuando importas `Query`, `Path`, `File` y otros desde `fastapi`, esos son en realidad funciones que devuelven clases especiales.
+
+///
+
+/// tip | Consejo
+
+Para declarar cuerpos de File, necesitas usar `File`, porque de otra manera los parámetros serían interpretados como parámetros query o parámetros de cuerpo (JSON).
+
+///
+
+Los archivos se subirán como "form data".
+
+Si declaras el tipo de tu parámetro de *path operation function* como `bytes`, **FastAPI** leerá el archivo por ti y recibirás el contenido como `bytes`.
+
+Ten en cuenta que esto significa que todo el contenido se almacenará en memoria. Esto funcionará bien para archivos pequeños.
+
+Pero hay varios casos en los que podrías beneficiarte de usar `UploadFile`.
+
+## Parámetros de Archivo con `UploadFile`
+
+Define un parámetro de archivo con un tipo de `UploadFile`:
+
+{* ../../docs_src/request_files/tutorial001_an_py39.py hl[14] *}
+
+Usar `UploadFile` tiene varias ventajas sobre `bytes`:
+
+* No tienes que usar `File()` en el valor por defecto del parámetro.
+* Usa un archivo "spooled":
+ * Un archivo almacenado en memoria hasta un límite de tamaño máximo, y después de superar este límite, se almacenará en el disco.
+* Esto significa que funcionará bien para archivos grandes como imágenes, videos, binarios grandes, etc. sin consumir toda la memoria.
+* Puedes obtener metadatos del archivo subido.
+* Tiene una interfaz `async` parecida a un archivo.
+* Expone un objeto Python real `SpooledTemporaryFile` que puedes pasar directamente a otros paquetes que esperan un objeto parecido a un archivo.
+
+### `UploadFile`
+
+`UploadFile` tiene los siguientes atributos:
+
+* `filename`: Un `str` con el nombre original del archivo que fue subido (por ejemplo, `myimage.jpg`).
+* `content_type`: Un `str` con el tipo de contenido (MIME type / media type) (por ejemplo, `image/jpeg`).
+* `file`: Un `SpooledTemporaryFile` (un objeto parecido a un archivo). Este es el objeto de archivo Python real que puedes pasar directamente a otras funciones o paquetes que esperan un objeto "parecido a un archivo".
+
+`UploadFile` tiene los siguientes métodos `async`. Todos ellos llaman a los métodos correspondientes del archivo por debajo (usando el `SpooledTemporaryFile` interno).
+
+* `write(data)`: Escribe `data` (`str` o `bytes`) en el archivo.
+* `read(size)`: Lee `size` (`int`) bytes/caracteres del archivo.
+* `seek(offset)`: Va a la posición de bytes `offset` (`int`) en el archivo.
+ * Por ejemplo, `await myfile.seek(0)` iría al inicio del archivo.
+ * Esto es especialmente útil si ejecutas `await myfile.read()` una vez y luego necesitas leer el contenido nuevamente.
+* `close()`: Cierra el archivo.
+
+Como todos estos métodos son métodos `async`, necesitas "await" para ellos.
+
+Por ejemplo, dentro de una *path operation function* `async` puedes obtener los contenidos con:
+
+```Python
+contents = await myfile.read()
+```
+
+Si estás dentro de una *path operation function* normal `def`, puedes acceder al `UploadFile.file` directamente, por ejemplo:
+
+```Python
+contents = myfile.file.read()
+```
+
+/// note | Detalles Técnicos de `async`
+
+Cuando usas los métodos `async`, **FastAPI** ejecuta los métodos del archivo en un threadpool y los espera.
+
+///
+
+/// note | Detalles Técnicos de Starlette
+
+El `UploadFile` de **FastAPI** hereda directamente del `UploadFile` de **Starlette**, pero añade algunas partes necesarias para hacerlo compatible con **Pydantic** y las otras partes de FastAPI.
+
+///
+
+## Qué es "Form Data"
+
+La manera en que los forms de HTML (``) envían los datos al servidor normalmente utiliza una codificación "especial" para esos datos, es diferente de JSON.
+
+**FastAPI** se asegurará de leer esos datos del lugar correcto en lugar de JSON.
+
+/// note | Detalles Técnicos
+
+Los datos de los forms normalmente se codifican usando el "media type" `application/x-www-form-urlencoded` cuando no incluyen archivos.
+
+Pero cuando el formulario incluye archivos, se codifica como `multipart/form-data`. Si usas `File`, **FastAPI** sabrá que tiene que obtener los archivos de la parte correcta del cuerpo.
+
+Si deseas leer más sobre estas codificaciones y campos de formularios, dirígete a la MDN web docs para POST.
+
+///
+
+/// warning | Advertencia
+
+Puedes declarar múltiples parámetros `File` y `Form` en una *path operation*, pero no puedes declarar campos `Body` que esperas recibir como JSON, ya que el request tendrá el cuerpo codificado usando `multipart/form-data` en lugar de `application/json`.
+
+Esto no es una limitación de **FastAPI**, es parte del protocolo HTTP.
+
+///
+
+## Subida de Archivos Opcional
+
+Puedes hacer un archivo opcional utilizando anotaciones de tipos estándar y estableciendo un valor por defecto de `None`:
+
+{* ../../docs_src/request_files/tutorial001_02_an_py310.py hl[9,17] *}
+
+## `UploadFile` con Metadatos Adicionales
+
+También puedes usar `File()` con `UploadFile`, por ejemplo, para establecer metadatos adicionales:
+
+{* ../../docs_src/request_files/tutorial001_03_an_py39.py hl[9,15] *}
+
+## Subidas de Múltiples Archivos
+
+Es posible subir varios archivos al mismo tiempo.
+
+Estarían asociados al mismo "campo de formulario" enviado usando "form data".
+
+Para usar eso, declara una lista de `bytes` o `UploadFile`:
+
+{* ../../docs_src/request_files/tutorial002_an_py39.py hl[10,15] *}
+
+Recibirás, como se declaró, una `list` de `bytes` o `UploadFile`s.
+
+/// note | Detalles Técnicos
+
+También podrías usar `from starlette.responses import HTMLResponse`.
+
+**FastAPI** proporciona las mismas `starlette.responses` como `fastapi.responses` solo como una conveniencia para ti, el desarrollador. Pero la mayoría de los responses disponibles vienen directamente de Starlette.
+
+///
+
+### Subidas de Múltiples Archivos con Metadatos Adicionales
+
+Y de la misma manera que antes, puedes usar `File()` para establecer parámetros adicionales, incluso para `UploadFile`:
+
+{* ../../docs_src/request_files/tutorial003_an_py39.py hl[11,18:20] *}
+
+## Recapitulación
+
+Usa `File`, `bytes` y `UploadFile` para declarar archivos que se subirán en el request, enviados como form data.
diff --git a/docs/es/docs/tutorial/request-form-models.md b/docs/es/docs/tutorial/request-form-models.md
new file mode 100644
index 000000000..9d5d7495a
--- /dev/null
+++ b/docs/es/docs/tutorial/request-form-models.md
@@ -0,0 +1,78 @@
+# Modelos de Formulario
+
+Puedes usar **modelos de Pydantic** para declarar **campos de formulario** en FastAPI.
+
+/// info | Información
+
+Para usar formularios, primero instala `python-multipart`.
+
+Asegúrate de crear un [entorno virtual](../virtual-environments.md){.internal-link target=_blank}, activarlo, y luego instalarlo, por ejemplo:
+
+```console
+$ pip install python-multipart
+```
+
+///
+
+/// note | Nota
+
+Esto es compatible desde la versión `0.113.0` de FastAPI. 🤓
+
+///
+
+## Modelos de Pydantic para Formularios
+
+Solo necesitas declarar un **modelo de Pydantic** con los campos que quieres recibir como **campos de formulario**, y luego declarar el parámetro como `Form`:
+
+{* ../../docs_src/request_form_models/tutorial001_an_py39.py hl[9:11,15] *}
+
+**FastAPI** **extraerá** los datos de **cada campo** de los **form data** en el request y te dará el modelo de Pydantic que definiste.
+
+## Revisa la Documentación
+
+Puedes verificarlo en la interfaz de documentación en `/docs`:
+
+
+POST.
+
+///
+
+/// warning | Advertencia
+
+Puedes declarar múltiples parámetros `Form` en una *path operation*, pero no puedes también declarar campos `Body` que esperas recibir como JSON, ya que el request tendrá el body codificado usando `application/x-www-form-urlencoded` en lugar de `application/json`.
+
+Esto no es una limitación de **FastAPI**, es parte del protocolo HTTP.
+
+///
+
+## Recapitulación
+
+Usa `Form` para declarar parámetros de entrada de datos de formulario.
diff --git a/docs/es/docs/tutorial/response-model.md b/docs/es/docs/tutorial/response-model.md
new file mode 100644
index 000000000..09682f51b
--- /dev/null
+++ b/docs/es/docs/tutorial/response-model.md
@@ -0,0 +1,357 @@
+# Modelo de Response - Tipo de Retorno
+
+Puedes declarar el tipo utilizado para el response anotando el **tipo de retorno** de la *path operation function*.
+
+Puedes utilizar **anotaciones de tipos** de la misma manera que lo harías para datos de entrada en **parámetros** de función, puedes utilizar modelos de Pydantic, listas, diccionarios, valores escalares como enteros, booleanos, etc.
+
+{* ../../docs_src/response_model/tutorial001_01_py310.py hl[16,21] *}
+
+FastAPI usará este tipo de retorno para:
+
+* **Validar** los datos devueltos.
+ * Si los datos son inválidos (por ejemplo, falta un campo), significa que el código de *tu* aplicación está defectuoso, no devolviendo lo que debería, y retornará un error del servidor en lugar de devolver datos incorrectos. De esta manera, tú y tus clientes pueden estar seguros de que recibirán los datos y la forma de los datos esperada.
+* Agregar un **JSON Schema** para el response, en la *path operation* de OpenAPI.
+ * Esto será utilizado por la **documentación automática**.
+ * También será utilizado por herramientas de generación automática de código de cliente.
+
+Pero lo más importante:
+
+* **Limitará y filtrará** los datos de salida a lo que se define en el tipo de retorno.
+ * Esto es particularmente importante para la **seguridad**, veremos más sobre eso a continuación.
+
+## Parámetro `response_model`
+
+Hay algunos casos en los que necesitas o quieres devolver algunos datos que no son exactamente lo que declara el tipo.
+
+Por ejemplo, podrías querer **devolver un diccionario** u objeto de base de datos, pero **declararlo como un modelo de Pydantic**. De esta manera el modelo de Pydantic haría toda la documentación de datos, validación, etc. para el objeto que devolviste (por ejemplo, un diccionario u objeto de base de datos).
+
+Si añadiste la anotación del tipo de retorno, las herramientas y editores se quejarían con un error (correcto) diciéndote que tu función está devolviendo un tipo (por ejemplo, un dict) que es diferente de lo que declaraste (por ejemplo, un modelo de Pydantic).
+
+En esos casos, puedes usar el parámetro del decorador de path operation `response_model` en lugar del tipo de retorno.
+
+Puedes usar el parámetro `response_model` en cualquiera de las *path operations*:
+
+* `@app.get()`
+* `@app.post()`
+* `@app.put()`
+* `@app.delete()`
+* etc.
+
+{* ../../docs_src/response_model/tutorial001_py310.py hl[17,22,24:27] *}
+
+/// note | Nota
+
+Observa que `response_model` es un parámetro del método "decorador" (`get`, `post`, etc). No de tu *path operation function*, como todos los parámetros y el cuerpo.
+
+///
+
+`response_model` recibe el mismo tipo que declararías para un campo de modelo Pydantic, por lo que puede ser un modelo de Pydantic, pero también puede ser, por ejemplo, un `list` de modelos de Pydantic, como `List[Item]`.
+
+FastAPI usará este `response_model` para hacer toda la documentación de datos, validación, etc. y también para **convertir y filtrar los datos de salida** a su declaración de tipo.
+
+/// tip | Consejo
+
+Si tienes chequeos estrictos de tipos en tu editor, mypy, etc., puedes declarar el tipo de retorno de la función como `Any`.
+
+De esa manera le dices al editor que intencionalmente estás devolviendo cualquier cosa. Pero FastAPI todavía hará la documentación de datos, validación, filtrado, etc. con `response_model`.
+
+///
+
+### Prioridad del `response_model`
+
+Si declaras tanto un tipo de retorno como un `response_model`, el `response_model` tomará prioridad y será utilizado por FastAPI.
+
+De esta manera puedes añadir anotaciones de tipos correctas a tus funciones incluso cuando estás devolviendo un tipo diferente al modelo de response, para ser utilizado por el editor y herramientas como mypy. Y aún así puedes hacer que FastAPI realice la validación de datos, documentación, etc. usando el `response_model`.
+
+También puedes usar `response_model=None` para desactivar la creación de un modelo de response para esa *path operation*, podrías necesitar hacerlo si estás añadiendo anotaciones de tipos para cosas que no son campos válidos de Pydantic, verás un ejemplo de eso en una de las secciones a continuación.
+
+## Devolver los mismos datos de entrada
+
+Aquí estamos declarando un modelo `UserIn`, contendrá una contraseña en texto plano:
+
+{* ../../docs_src/response_model/tutorial002_py310.py hl[7,9] *}
+
+/// info | Información
+
+Para usar `EmailStr`, primero instala `email-validator`.
+
+Asegúrate de crear un [entorno virtual](../virtual-environments.md){.internal-link target=_blank}, activarlo, y luego instalarlo, por ejemplo:
+
+```console
+$ pip install email-validator
+```
+
+o con:
+
+```console
+$ pip install "pydantic[email]"
+```
+
+///
+
+Y estamos usando este modelo para declarar nuestra entrada y el mismo modelo para declarar nuestra salida:
+
+{* ../../docs_src/response_model/tutorial002_py310.py hl[16] *}
+
+Ahora, cada vez que un navegador esté creando un usuario con una contraseña, la API devolverá la misma contraseña en el response.
+
+En este caso, podría no ser un problema, porque es el mismo usuario que envía la contraseña.
+
+Pero si usamos el mismo modelo para otra *path operation*, podríamos estar enviando las contraseñas de nuestros usuarios a cada cliente.
+
+/// danger | Peligro
+
+Nunca almacenes la contraseña en texto plano de un usuario ni la envíes en un response como esta, a menos que conozcas todas las advertencias y sepas lo que estás haciendo.
+
+///
+
+## Añadir un modelo de salida
+
+Podemos en cambio crear un modelo de entrada con la contraseña en texto plano y un modelo de salida sin ella:
+
+{* ../../docs_src/response_model/tutorial003_py310.py hl[9,11,16] *}
+
+Aquí, aunque nuestra *path operation function* está devolviendo el mismo usuario de entrada que contiene la contraseña:
+
+{* ../../docs_src/response_model/tutorial003_py310.py hl[24] *}
+
+...hemos declarado el `response_model` para ser nuestro modelo `UserOut`, que no incluye la contraseña:
+
+{* ../../docs_src/response_model/tutorial003_py310.py hl[22] *}
+
+Entonces, **FastAPI** se encargará de filtrar todos los datos que no estén declarados en el modelo de salida (usando Pydantic).
+
+### `response_model` o Tipo de Retorno
+
+En este caso, como los dos modelos son diferentes, si anotáramos el tipo de retorno de la función como `UserOut`, el editor y las herramientas se quejarían de que estamos devolviendo un tipo inválido, ya que son clases diferentes.
+
+Por eso en este ejemplo tenemos que declararlo en el parámetro `response_model`.
+
+...pero sigue leyendo abajo para ver cómo superar eso.
+
+## Tipo de Retorno y Filtrado de Datos
+
+Continuemos con el ejemplo anterior. Queríamos **anotar la función con un tipo**, pero queríamos poder devolver desde la función algo que en realidad incluya **más datos**.
+
+Queremos que FastAPI continúe **filtrando** los datos usando el modelo de response. Para que, incluso cuando la función devuelva más datos, el response solo incluya los campos declarados en el modelo de response.
+
+En el ejemplo anterior, debido a que las clases eran diferentes, tuvimos que usar el parámetro `response_model`. Pero eso también significa que no obtenemos el soporte del editor y las herramientas verificando el tipo de retorno de la función.
+
+Pero en la mayoría de los casos en los que necesitamos hacer algo como esto, queremos que el modelo solo **filtre/elimine** algunos de los datos como en este ejemplo.
+
+Y en esos casos, podemos usar clases y herencia para aprovechar las **anotaciones de tipos** de funciones para obtener mejor soporte en el editor y herramientas, y aún así obtener el **filtrado de datos** de FastAPI.
+
+{* ../../docs_src/response_model/tutorial003_01_py310.py hl[7:10,13:14,18] *}
+
+Con esto, obtenemos soporte de las herramientas, de los editores y mypy ya que este código es correcto en términos de tipos, pero también obtenemos el filtrado de datos de FastAPI.
+
+¿Cómo funciona esto? Vamos a echarle un vistazo. 🤓
+
+### Anotaciones de Tipos y Herramientas
+
+Primero vamos a ver cómo los editores, mypy y otras herramientas verían esto.
+
+`BaseUser` tiene los campos base. Luego `UserIn` hereda de `BaseUser` y añade el campo `password`, por lo que incluirá todos los campos de ambos modelos.
+
+Anotamos el tipo de retorno de la función como `BaseUser`, pero en realidad estamos devolviendo una instancia de `UserIn`.
+
+El editor, mypy y otras herramientas no se quejarán de esto porque, en términos de tipificación, `UserIn` es una subclase de `BaseUser`, lo que significa que es un tipo *válido* cuando se espera algo que es un `BaseUser`.
+
+### Filtrado de Datos en FastAPI
+
+Ahora, para FastAPI, verá el tipo de retorno y se asegurará de que lo que devuelves incluya **solo** los campos que están declarados en el tipo.
+
+FastAPI realiza varias cosas internamente con Pydantic para asegurarse de que esas mismas reglas de herencia de clases no se utilicen para el filtrado de datos devueltos, de lo contrario, podrías terminar devolviendo muchos más datos de los que esperabas.
+
+De esta manera, puedes obtener lo mejor de ambos mundos: anotaciones de tipos con **soporte de herramientas** y **filtrado de datos**.
+
+## Verlo en la documentación
+
+Cuando veas la documentación automática, puedes verificar que el modelo de entrada y el modelo de salida tendrán cada uno su propio JSON Schema:
+
+
+
+Y ambos modelos se utilizarán para la documentación interactiva de la API:
+
+
+
+## Otras Anotaciones de Tipos de Retorno
+
+Podría haber casos en los que devuelvas algo que no es un campo válido de Pydantic y lo anotes en la función, solo para obtener el soporte proporcionado por las herramientas (el editor, mypy, etc).
+
+### Devolver un Response Directamente
+
+El caso más común sería [devolver un Response directamente como se explica más adelante en la documentación avanzada](../advanced/response-directly.md){.internal-link target=_blank}.
+
+{* ../../docs_src/response_model/tutorial003_02.py hl[8,10:11] *}
+
+Este caso simple es manejado automáticamente por FastAPI porque la anotación del tipo de retorno es la clase (o una subclase de) `Response`.
+
+Y las herramientas también estarán felices porque tanto `RedirectResponse` como `JSONResponse` son subclases de `Response`, por lo que la anotación del tipo es correcta.
+
+### Anotar una Subclase de Response
+
+También puedes usar una subclase de `Response` en la anotación del tipo:
+
+{* ../../docs_src/response_model/tutorial003_03.py hl[8:9] *}
+
+Esto también funcionará porque `RedirectResponse` es una subclase de `Response`, y FastAPI manejará automáticamente este caso simple.
+
+### Anotaciones de Tipos de Retorno Inválidas
+
+Pero cuando devuelves algún otro objeto arbitrario que no es un tipo válido de Pydantic (por ejemplo, un objeto de base de datos) y lo anotas así en la función, FastAPI intentará crear un modelo de response de Pydantic a partir de esa anotación de tipo, y fallará.
+
+Lo mismo sucedería si tuvieras algo como un union entre diferentes tipos donde uno o más de ellos no son tipos válidos de Pydantic, por ejemplo esto fallaría 💥:
+
+{* ../../docs_src/response_model/tutorial003_04_py310.py hl[8] *}
+
+...esto falla porque la anotación de tipo no es un tipo de Pydantic y no es solo una sola clase `Response` o subclase, es una unión (cualquiera de los dos) entre una `Response` y un `dict`.
+
+### Desactivar el Modelo de Response
+
+Continuando con el ejemplo anterior, puede que no quieras tener la validación de datos por defecto, documentación, filtrado, etc. que realiza FastAPI.
+
+Pero puedes querer mantener la anotación del tipo de retorno en la función para obtener el soporte de herramientas como editores y verificadores de tipos (por ejemplo, mypy).
+
+En este caso, puedes desactivar la generación del modelo de response configurando `response_model=None`:
+
+{* ../../docs_src/response_model/tutorial003_05_py310.py hl[7] *}
+
+Esto hará que FastAPI omita la generación del modelo de response y de esa manera puedes tener cualquier anotación de tipo de retorno que necesites sin que afecte a tu aplicación FastAPI. 🤓
+
+## Parámetros de codificación del Modelo de Response
+
+Tu modelo de response podría tener valores por defecto, como:
+
+{* ../../docs_src/response_model/tutorial004_py310.py hl[9,11:12] *}
+
+* `description: Union[str, None] = None` (o `str | None = None` en Python 3.10) tiene un valor por defecto de `None`.
+* `tax: float = 10.5` tiene un valor por defecto de `10.5`.
+* `tags: List[str] = []` tiene un valor por defecto de una lista vacía: `[]`.
+
+pero podrías querer omitirlos del resultado si no fueron en realidad almacenados.
+
+Por ejemplo, si tienes modelos con muchos atributos opcionales en una base de datos NoSQL, pero no quieres enviar responses JSON muy largos llenos de valores por defecto.
+
+### Usa el parámetro `response_model_exclude_unset`
+
+Puedes configurar el parámetro del decorador de path operation `response_model_exclude_unset=True`:
+
+{* ../../docs_src/response_model/tutorial004_py310.py hl[22] *}
+
+y esos valores por defecto no serán incluidos en el response, solo los valores realmente establecidos.
+
+Entonces, si envías un request a esa *path operation* para el ítem con ID `foo`, el response (no incluyendo valores por defecto) será:
+
+```JSON
+{
+ "name": "Foo",
+ "price": 50.2
+}
+```
+
+/// info | Información
+
+En Pydantic v1 el método se llamaba `.dict()`, fue deprecado (pero aún soportado) en Pydantic v2, y renombrado a `.model_dump()`.
+
+Los ejemplos aquí usan `.dict()` para compatibilidad con Pydantic v1, pero deberías usar `.model_dump()` en su lugar si puedes usar Pydantic v2.
+
+///
+
+/// info | Información
+
+FastAPI usa el método `.dict()` del modelo de Pydantic con su parámetro `exclude_unset` para lograr esto.
+
+///
+
+/// info | Información
+
+También puedes usar:
+
+* `response_model_exclude_defaults=True`
+* `response_model_exclude_none=True`
+
+como se describe en la documentación de Pydantic para `exclude_defaults` y `exclude_none`.
+
+///
+
+#### Datos con valores para campos con valores por defecto
+
+Pero si tus datos tienen valores para los campos del modelo con valores por defecto, como el artículo con ID `bar`:
+
+```Python hl_lines="3 5"
+{
+ "name": "Bar",
+ "description": "The bartenders",
+ "price": 62,
+ "tax": 20.2
+}
+```
+
+serán incluidos en el response.
+
+#### Datos con los mismos valores que los valores por defecto
+
+Si los datos tienen los mismos valores que los valores por defecto, como el artículo con ID `baz`:
+
+```Python hl_lines="3 5-6"
+{
+ "name": "Baz",
+ "description": None,
+ "price": 50.2,
+ "tax": 10.5,
+ "tags": []
+}
+```
+
+FastAPI es lo suficientemente inteligente (de hecho, Pydantic es lo suficientemente inteligente) para darse cuenta de que, a pesar de que `description`, `tax` y `tags` tienen los mismos valores que los valores por defecto, fueron establecidos explícitamente (en lugar de tomados de los valores por defecto).
+
+Por lo tanto, se incluirán en el response JSON.
+
+/// tip | Consejo
+
+Ten en cuenta que los valores por defecto pueden ser cualquier cosa, no solo `None`.
+
+Pueden ser una lista (`[]`), un `float` de `10.5`, etc.
+
+///
+
+### `response_model_include` y `response_model_exclude`
+
+También puedes usar los parámetros del decorador de path operation `response_model_include` y `response_model_exclude`.
+
+Aceptan un `set` de `str` con el nombre de los atributos a incluir (omitiendo el resto) o excluir (incluyendo el resto).
+
+Esto se puede usar como un atajo rápido si solo tienes un modelo de Pydantic y quieres eliminar algunos datos de la salida.
+
+/// tip | Consejo
+
+Pero todavía se recomienda usar las ideas anteriores, usando múltiples clases, en lugar de estos parámetros.
+
+Esto se debe a que el JSON Schema generado en el OpenAPI de tu aplicación (y la documentación) aún será el del modelo completo, incluso si usas `response_model_include` o `response_model_exclude` para omitir algunos atributos.
+
+Esto también se aplica a `response_model_by_alias` que funciona de manera similar.
+
+///
+
+{* ../../docs_src/response_model/tutorial005_py310.py hl[29,35] *}
+
+/// tip | Consejo
+
+La sintaxis `{"name", "description"}` crea un `set` con esos dos valores.
+
+Es equivalente a `set(["name", "description"])`.
+
+///
+
+#### Usar `list`s en lugar de `set`s
+
+Si olvidas usar un `set` y usas un `list` o `tuple` en su lugar, FastAPI todavía lo convertirá a un `set` y funcionará correctamente:
+
+{* ../../docs_src/response_model/tutorial006_py310.py hl[29,35] *}
+
+## Resumen
+
+Usa el parámetro `response_model` del *decorador de path operation* para definir modelos de response y especialmente para asegurarte de que los datos privados sean filtrados.
+
+Usa `response_model_exclude_unset` para devolver solo los valores establecidos explícitamente.
diff --git a/docs/es/docs/tutorial/response-status-code.md b/docs/es/docs/tutorial/response-status-code.md
new file mode 100644
index 000000000..92df1f4cc
--- /dev/null
+++ b/docs/es/docs/tutorial/response-status-code.md
@@ -0,0 +1,101 @@
+# Código de Estado del Response
+
+De la misma manera que puedes especificar un modelo de response, también puedes declarar el código de estado HTTP usado para el response con el parámetro `status_code` en cualquiera de las *path operations*:
+
+* `@app.get()`
+* `@app.post()`
+* `@app.put()`
+* `@app.delete()`
+* etc.
+
+{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
+
+/// note | Nota
+
+Observa que `status_code` es un parámetro del método "decorador" (`get`, `post`, etc). No de tu *path operation function*, como todos los parámetros y body.
+
+///
+
+El parámetro `status_code` recibe un número con el código de estado HTTP.
+
+/// info | Información
+
+`status_code` también puede recibir un `IntEnum`, como por ejemplo el `http.HTTPStatus` de Python.
+
+///
+
+Esto hará:
+
+* Devolver ese código de estado en el response.
+* Documentarlo como tal en el esquema de OpenAPI (y por lo tanto, en las interfaces de usuario):
+
+
+
+/// note | Nota
+
+Algunos códigos de response (ver la siguiente sección) indican que el response no tiene un body.
+
+FastAPI sabe esto, y producirá documentación OpenAPI que establece que no hay un response body.
+
+///
+
+## Acerca de los códigos de estado HTTP
+
+/// note | Nota
+
+Si ya sabes qué son los códigos de estado HTTP, salta a la siguiente sección.
+
+///
+
+En HTTP, envías un código de estado numérico de 3 dígitos como parte del response.
+
+Estos códigos de estado tienen un nombre asociado para reconocerlos, pero la parte importante es el número.
+
+En breve:
+
+* `100` y superiores son para "Información". Rara vez los usas directamente. Los responses con estos códigos de estado no pueden tener un body.
+* **`200`** y superiores son para responses "Exitosos". Estos son los que usarías más.
+ * `200` es el código de estado por defecto, lo que significa que todo estaba "OK".
+ * Otro ejemplo sería `201`, "Created". Comúnmente se usa después de crear un nuevo registro en la base de datos.
+ * Un caso especial es `204`, "No Content". Este response se usa cuando no hay contenido para devolver al cliente, por lo tanto, el response no debe tener un body.
+* **`300`** y superiores son para "Redirección". Los responses con estos códigos de estado pueden o no tener un body, excepto `304`, "Not Modified", que no debe tener uno.
+* **`400`** y superiores son para responses de "Error del Cliente". Este es el segundo tipo que probablemente más usarías.
+ * Un ejemplo es `404`, para un response "Not Found".
+ * Para errores genéricos del cliente, puedes usar simplemente `400`.
+* `500` y superiores son para errores del servidor. Casi nunca los usas directamente. Cuando algo sale mal en alguna parte de tu código de aplicación, o del servidor, automáticamente devolverá uno de estos códigos de estado.
+
+/// tip | Consejo
+
+Para saber más sobre cada código de estado y qué código es para qué, revisa la documentación de MDN sobre códigos de estado HTTP.
+
+///
+
+## Atajo para recordar los nombres
+
+Veamos de nuevo el ejemplo anterior:
+
+{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
+
+`201` es el código de estado para "Created".
+
+Pero no tienes que memorizar lo que significa cada uno de estos códigos.
+
+Puedes usar las variables de conveniencia de `fastapi.status`.
+
+{* ../../docs_src/response_status_code/tutorial002.py hl[1,6] *}
+
+Son solo una conveniencia, mantienen el mismo número, pero de esa manera puedes usar el autocompletado del editor para encontrarlos:
+
+
+
+/// note | Nota Técnica
+
+También podrías usar `from starlette import status`.
+
+**FastAPI** proporciona el mismo `starlette.status` como `fastapi.status` solo como una conveniencia para ti, el desarrollador. Pero proviene directamente de Starlette.
+
+///
+
+## Cambiando el valor por defecto
+
+Más adelante, en la [Guía de Usuario Avanzada](../advanced/response-change-status-code.md){.internal-link target=_blank}, verás cómo devolver un código de estado diferente al valor por defecto que estás declarando aquí.
diff --git a/docs/es/docs/tutorial/schema-extra-example.md b/docs/es/docs/tutorial/schema-extra-example.md
new file mode 100644
index 000000000..645060d71
--- /dev/null
+++ b/docs/es/docs/tutorial/schema-extra-example.md
@@ -0,0 +1,224 @@
+# Declarar Ejemplos de Request
+
+Puedes declarar ejemplos de los datos que tu aplicación puede recibir.
+
+Aquí tienes varias formas de hacerlo.
+
+## Datos extra de JSON Schema en modelos de Pydantic
+
+Puedes declarar `examples` para un modelo de Pydantic que se añadirá al JSON Schema generado.
+
+//// tab | Pydantic v2
+
+{* ../../docs_src/schema_extra_example/tutorial001_py310.py hl[13:24] *}
+
+////
+
+//// tab | Pydantic v1
+
+{* ../../docs_src/schema_extra_example/tutorial001_pv1_py310.py hl[13:23] *}
+
+////
+
+Esa información extra se añadirá tal cual al **JSON Schema** generado para ese modelo, y se usará en la documentación de la API.
+
+//// tab | Pydantic v2
+
+En Pydantic versión 2, usarías el atributo `model_config`, que toma un `dict` como se describe en la documentación de Pydantic: Configuración.
+
+Puedes establecer `"json_schema_extra"` con un `dict` que contenga cualquier dato adicional que desees que aparezca en el JSON Schema generado, incluyendo `examples`.
+
+////
+
+//// tab | Pydantic v1
+
+En Pydantic versión 1, usarías una clase interna `Config` y `schema_extra`, como se describe en la documentación de Pydantic: Personalización de Esquema.
+
+Puedes establecer `schema_extra` con un `dict` que contenga cualquier dato adicional que desees que aparezca en el JSON Schema generado, incluyendo `examples`.
+
+////
+
+/// tip | Consejo
+
+Podrías usar la misma técnica para extender el JSON Schema y añadir tu propia información extra personalizada.
+
+Por ejemplo, podrías usarlo para añadir metadatos para una interfaz de usuario frontend, etc.
+
+///
+
+/// info | Información
+
+OpenAPI 3.1.0 (usado desde FastAPI 0.99.0) añadió soporte para `examples`, que es parte del estándar de **JSON Schema**.
+
+Antes de eso, solo soportaba la palabra clave `example` con un solo ejemplo. Eso aún es soportado por OpenAPI 3.1.0, pero está obsoleto y no es parte del estándar de JSON Schema. Así que se recomienda migrar de `example` a `examples`. 🤓
+
+Puedes leer más al final de esta página.
+
+///
+
+## Argumentos adicionales en `Field`
+
+Cuando usas `Field()` con modelos de Pydantic, también puedes declarar `examples` adicionales:
+
+{* ../../docs_src/schema_extra_example/tutorial002_py310.py hl[2,8:11] *}
+
+## `examples` en JSON Schema - OpenAPI
+
+Cuando usas cualquiera de:
+
+* `Path()`
+* `Query()`
+* `Header()`
+* `Cookie()`
+* `Body()`
+* `Form()`
+* `File()`
+
+también puedes declarar un grupo de `examples` con información adicional que se añadirá a sus **JSON Schemas** dentro de **OpenAPI**.
+
+### `Body` con `examples`
+
+Aquí pasamos `examples` que contiene un ejemplo de los datos esperados en `Body()`:
+
+{* ../../docs_src/schema_extra_example/tutorial003_an_py310.py hl[22:29] *}
+
+### Ejemplo en la interfaz de documentación
+
+Con cualquiera de los métodos anteriores se vería así en los `/docs`:
+
+
+
+### `Body` con múltiples `examples`
+
+Por supuesto, también puedes pasar múltiples `examples`:
+
+{* ../../docs_src/schema_extra_example/tutorial004_an_py310.py hl[23:38] *}
+
+Cuando haces esto, los ejemplos serán parte del **JSON Schema** interno para esos datos de body.
+
+Sin embargo, al momento de escribir esto, Swagger UI, la herramienta encargada de mostrar la interfaz de documentación, no soporta mostrar múltiples ejemplos para los datos en **JSON Schema**. Pero lee más abajo para una solución alternativa.
+
+### `examples` específicos de OpenAPI
+
+Desde antes de que **JSON Schema** soportara `examples`, OpenAPI tenía soporte para un campo diferente también llamado `examples`.
+
+Estos `examples` específicos de **OpenAPI** van en otra sección en la especificación de OpenAPI. Van en los **detalles para cada *path operation***, no dentro de cada JSON Schema.
+
+Y Swagger UI ha soportado este campo particular de `examples` por un tiempo. Así que, puedes usarlo para **mostrar** diferentes **ejemplos en la interfaz de documentación**.
+
+La forma de este campo específico de OpenAPI `examples` es un `dict` con **múltiples ejemplos** (en lugar de una `list`), cada uno con información adicional que también se añadirá a **OpenAPI**.
+
+Esto no va dentro de cada JSON Schema contenido en OpenAPI, esto va afuera, directamente en la *path operation*.
+
+### Usando el Parámetro `openapi_examples`
+
+Puedes declarar los `examples` específicos de OpenAPI en FastAPI con el parámetro `openapi_examples` para:
+
+* `Path()`
+* `Query()`
+* `Header()`
+* `Cookie()`
+* `Body()`
+* `Form()`
+* `File()`
+
+Las claves del `dict` identifican cada ejemplo, y cada valor es otro `dict`.
+
+Cada `dict` específico del ejemplo en los `examples` puede contener:
+
+* `summary`: Descripción corta del ejemplo.
+* `description`: Una descripción larga que puede contener texto Markdown.
+* `value`: Este es el ejemplo real mostrado, e.g. un `dict`.
+* `externalValue`: alternativa a `value`, una URL que apunta al ejemplo. Aunque esto puede no ser soportado por tantas herramientas como `value`.
+
+Puedes usarlo así:
+
+{* ../../docs_src/schema_extra_example/tutorial005_an_py310.py hl[23:49] *}
+
+### Ejemplos de OpenAPI en la Interfaz de Documentación
+
+Con `openapi_examples` añadido a `Body()`, los `/docs` se verían así:
+
+
+
+## Detalles Técnicos
+
+/// tip | Consejo
+
+Si ya estás usando la versión **0.99.0 o superior** de **FastAPI**, probablemente puedes **omitir** estos detalles.
+
+Son más relevantes para versiones más antiguas, antes de que OpenAPI 3.1.0 estuviera disponible.
+
+Puedes considerar esto una breve lección de **historia** de OpenAPI y JSON Schema. 🤓
+
+///
+
+/// warning | Advertencia
+
+Estos son detalles muy técnicos sobre los estándares **JSON Schema** y **OpenAPI**.
+
+Si las ideas anteriores ya funcionan para ti, eso podría ser suficiente, y probablemente no necesites estos detalles, siéntete libre de omitirlos.
+
+///
+
+Antes de OpenAPI 3.1.0, OpenAPI usaba una versión más antigua y modificada de **JSON Schema**.
+
+JSON Schema no tenía `examples`, así que OpenAPI añadió su propio campo `example` a su versión modificada.
+
+OpenAPI también añadió los campos `example` y `examples` a otras partes de la especificación:
+
+* `Parameter Object` (en la especificación) que era usado por FastAPI:
+ * `Path()`
+ * `Query()`
+ * `Header()`
+ * `Cookie()`
+* `Request Body Object`, en el campo `content`, sobre el `Media Type Object` (en la especificación) que era usado por FastAPI:
+ * `Body()`
+ * `File()`
+ * `Form()`
+
+/// info | Información
+
+Este viejo parámetro `examples` específico de OpenAPI ahora es `openapi_examples` desde FastAPI `0.103.0`.
+
+///
+
+### Campo `examples` de JSON Schema
+
+Pero luego JSON Schema añadió un campo `examples` a una nueva versión de la especificación.
+
+Y entonces el nuevo OpenAPI 3.1.0 se basó en la última versión (JSON Schema 2020-12) que incluía este nuevo campo `examples`.
+
+Y ahora este nuevo campo `examples` tiene precedencia sobre el viejo campo único (y personalizado) `example`, que ahora está obsoleto.
+
+Este nuevo campo `examples` en JSON Schema es **solo una `list`** de ejemplos, no un dict con metadatos adicionales como en los otros lugares en OpenAPI (descritos arriba).
+
+/// info | Información
+
+Incluso después de que OpenAPI 3.1.0 fue lanzado con esta nueva integración más sencilla con JSON Schema, por un tiempo, Swagger UI, la herramienta que proporciona la documentación automática, no soportaba OpenAPI 3.1.0 (lo hace desde la versión 5.0.0 🎉).
+
+Debido a eso, las versiones de FastAPI anteriores a 0.99.0 todavía usaban versiones de OpenAPI menores a 3.1.0.
+
+///
+
+### `examples` de Pydantic y FastAPI
+
+Cuando añades `examples` dentro de un modelo de Pydantic, usando `schema_extra` o `Field(examples=["algo"])`, ese ejemplo se añade al **JSON Schema** para ese modelo de Pydantic.
+
+Y ese **JSON Schema** del modelo de Pydantic se incluye en el **OpenAPI** de tu API, y luego se usa en la interfaz de documentación.
+
+En las versiones de FastAPI antes de 0.99.0 (0.99.0 y superior usan el nuevo OpenAPI 3.1.0) cuando usabas `example` o `examples` con cualquiera de las otras utilidades (`Query()`, `Body()`, etc.) esos ejemplos no se añadían al JSON Schema que describe esos datos (ni siquiera a la propia versión de JSON Schema de OpenAPI), se añadían directamente a la declaración de la *path operation* en OpenAPI (fuera de las partes de OpenAPI que usan JSON Schema).
+
+Pero ahora que FastAPI 0.99.0 y superiores usa OpenAPI 3.1.0, que usa JSON Schema 2020-12, y Swagger UI 5.0.0 y superiores, todo es más consistente y los ejemplos se incluyen en JSON Schema.
+
+### Swagger UI y `examples` específicos de OpenAPI
+
+Ahora, como Swagger UI no soportaba múltiples ejemplos de JSON Schema (a fecha de 2023-08-26), los usuarios no tenían una forma de mostrar múltiples ejemplos en los documentos.
+
+Para resolver eso, FastAPI `0.103.0` **añadió soporte** para declarar el mismo viejo campo **específico de OpenAPI** `examples` con el nuevo parámetro `openapi_examples`. 🤓
+
+### Resumen
+
+Solía decir que no me gustaba mucho la historia... y mírame ahora dando lecciones de "historia tecnológica". 😅
+
+En resumen, **actualiza a FastAPI 0.99.0 o superior**, y las cosas son mucho **más simples, consistentes e intuitivas**, y no necesitas conocer todos estos detalles históricos. 😎
diff --git a/docs/es/docs/tutorial/security/first-steps.md b/docs/es/docs/tutorial/security/first-steps.md
new file mode 100644
index 000000000..5dbbab02a
--- /dev/null
+++ b/docs/es/docs/tutorial/security/first-steps.md
@@ -0,0 +1,203 @@
+# Seguridad - Primeros pasos
+
+Imaginemos que tienes tu API de **backend** en algún dominio.
+
+Y tienes un **frontend** en otro dominio o en un path diferente del mismo dominio (o en una aplicación móvil).
+
+Y quieres tener una forma para que el frontend se autentique con el backend, usando un **username** y **password**.
+
+Podemos usar **OAuth2** para construir eso con **FastAPI**.
+
+Pero vamos a ahorrarte el tiempo de leer la larga especificación completa solo para encontrar esos pequeños fragmentos de información que necesitas.
+
+Usemos las herramientas proporcionadas por **FastAPI** para manejar la seguridad.
+
+## Cómo se ve
+
+Primero solo usemos el código y veamos cómo funciona, y luego volveremos para entender qué está sucediendo.
+
+## Crea `main.py`
+
+Copia el ejemplo en un archivo `main.py`:
+
+{* ../../docs_src/security/tutorial001_an_py39.py *}
+
+## Ejecútalo
+
+/// info | Información
+
+El paquete `python-multipart` se instala automáticamente con **FastAPI** cuando ejecutas el comando `pip install "fastapi[standard]"`.
+
+Sin embargo, si usas el comando `pip install fastapi`, el paquete `python-multipart` no se incluye por defecto.
+
+Para instalarlo manualmente, asegúrate de crear un [entorno virtual](../../virtual-environments.md){.internal-link target=_blank}, activarlo, y luego instalarlo con:
+
+```console
+$ pip install python-multipart
+```
+
+Esto se debe a que **OAuth2** utiliza "form data" para enviar el `username` y `password`.
+
+///
+
+Ejecuta el ejemplo con:
+
+
+
+/// check | ¡Botón de autorización!
+
+Ya tienes un nuevo y brillante botón de "Authorize".
+
+Y tu *path operation* tiene un pequeño candado en la esquina superior derecha que puedes pulsar.
+
+///
+
+Y si lo haces, tendrás un pequeño formulario de autorización para escribir un `username` y `password` (y otros campos opcionales):
+
+
+
+/// note | Nota
+
+No importa lo que escribas en el formulario, aún no funcionará. Pero llegaremos allí.
+
+///
+
+Esto por supuesto no es el frontend para los usuarios finales, pero es una gran herramienta automática para documentar interactivamente toda tu API.
+
+Puede ser utilizada por el equipo de frontend (que también puedes ser tú mismo).
+
+Puede ser utilizada por aplicaciones y sistemas de terceros.
+
+Y también puede ser utilizada por ti mismo, para depurar, revisar y probar la misma aplicación.
+
+## El flujo `password`
+
+Ahora retrocedamos un poco y entendamos qué es todo eso.
+
+El "flujo" `password` es una de las formas ("flujos") definidas en OAuth2, para manejar la seguridad y la autenticación.
+
+OAuth2 fue diseñado para que el backend o la API pudieran ser independientes del servidor que autentica al usuario.
+
+Pero en este caso, la misma aplicación de **FastAPI** manejará la API y la autenticación.
+
+Así que, revisémoslo desde ese punto de vista simplificado:
+
+* El usuario escribe el `username` y `password` en el frontend, y presiona `Enter`.
+* El frontend (ejecutándose en el navegador del usuario) envía ese `username` y `password` a una URL específica en nuestra API (declarada con `tokenUrl="token"`).
+* La API verifica ese `username` y `password`, y responde con un "token" (no hemos implementado nada de esto aún).
+ * Un "token" es solo un string con algún contenido que podemos usar luego para verificar a este usuario.
+ * Normalmente, un token se establece para que expire después de algún tiempo.
+ * Así que, el usuario tendrá que volver a iniciar sesión más adelante.
+ * Y si el token es robado, el riesgo es menor. No es como una llave permanente que funcionará para siempre (en la mayoría de los casos).
+* El frontend almacena temporalmente ese token en algún lugar.
+* El usuario hace clic en el frontend para ir a otra sección de la aplicación web frontend.
+* El frontend necesita obtener más datos de la API.
+ * Pero necesita autenticación para ese endpoint específico.
+ * Así que, para autenticarse con nuestra API, envía un `header` `Authorization` con un valor de `Bearer ` más el token.
+ * Si el token contiene `foobar`, el contenido del `header` `Authorization` sería: `Bearer foobar`.
+
+## `OAuth2PasswordBearer` de **FastAPI**
+
+**FastAPI** proporciona varias herramientas, en diferentes niveles de abstracción, para implementar estas funcionalidades de seguridad.
+
+En este ejemplo vamos a usar **OAuth2**, con el flujo **Password**, usando un token **Bearer**. Hacemos eso utilizando la clase `OAuth2PasswordBearer`.
+
+/// info | Información
+
+Un token "bearer" no es la única opción.
+
+Pero es la mejor para nuestro caso de uso.
+
+Y podría ser la mejor para la mayoría de los casos de uso, a menos que seas un experto en OAuth2 y sepas exactamente por qué hay otra opción que se adapta mejor a tus necesidades.
+
+En ese caso, **FastAPI** también te proporciona las herramientas para construirlo.
+
+///
+
+Cuando creamos una instance de la clase `OAuth2PasswordBearer` pasamos el parámetro `tokenUrl`. Este parámetro contiene la URL que el cliente (el frontend corriendo en el navegador del usuario) usará para enviar el `username` y `password` a fin de obtener un token.
+
+{* ../../docs_src/security/tutorial001_an_py39.py hl[8] *}
+
+/// tip | Consejo
+
+Aquí `tokenUrl="token"` se refiere a una URL relativa `token` que aún no hemos creado. Como es una URL relativa, es equivalente a `./token`.
+
+Porque estamos usando una URL relativa, si tu API estuviera ubicada en `https://example.com/`, entonces se referiría a `https://example.com/token`. Pero si tu API estuviera ubicada en `https://example.com/api/v1/`, entonces se referiría a `https://example.com/api/v1/token`.
+
+Usar una URL relativa es importante para asegurarse de que tu aplicación siga funcionando incluso en un caso de uso avanzado como [Detrás de un Proxy](../../advanced/behind-a-proxy.md){.internal-link target=_blank}.
+
+///
+
+Este parámetro no crea ese endpoint / *path operation*, pero declara que la URL `/token` será la que el cliente deberá usar para obtener el token. Esa información se usa en OpenAPI, y luego en los sistemas de documentación interactiva del API.
+
+Pronto también crearemos la verdadera *path operation*.
+
+/// info | Información
+
+Si eres un "Pythonista" muy estricto, tal vez no te guste el estilo del nombre del parámetro `tokenUrl` en lugar de `token_url`.
+
+Eso es porque está usando el mismo nombre que en la especificación de OpenAPI. Para que si necesitas investigar más sobre cualquiera de estos esquemas de seguridad, puedas simplemente copiarlo y pegarlo para encontrar más información al respecto.
+
+///
+
+La variable `oauth2_scheme` es una instance de `OAuth2PasswordBearer`, pero también es un "callable".
+
+Podría ser llamada como:
+
+```Python
+oauth2_scheme(some, parameters)
+```
+
+Así que, puede usarse con `Depends`.
+
+### Úsalo
+
+Ahora puedes pasar ese `oauth2_scheme` en una dependencia con `Depends`.
+
+{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *}
+
+Esta dependencia proporcionará un `str` que se asigna al parámetro `token` de la *path operation function*.
+
+**FastAPI** sabrá que puede usar esta dependencia para definir un "security scheme" en el esquema OpenAPI (y en los docs automáticos del API).
+
+/// info | Detalles técnicos
+
+**FastAPI** sabrá que puede usar la clase `OAuth2PasswordBearer` (declarada en una dependencia) para definir el esquema de seguridad en OpenAPI porque hereda de `fastapi.security.oauth2.OAuth2`, que a su vez hereda de `fastapi.security.base.SecurityBase`.
+
+Todas las utilidades de seguridad que se integran con OpenAPI (y los docs automáticos del API) heredan de `SecurityBase`, así es como **FastAPI** puede saber cómo integrarlas en OpenAPI.
+
+///
+
+## Lo que hace
+
+Irá y buscará en el request ese header `Authorization`, verificará si el valor es `Bearer ` más algún token, y devolverá el token como un `str`.
+
+Si no ve un header `Authorization`, o el valor no tiene un token `Bearer `, responderá directamente con un error de código de estado 401 (`UNAUTHORIZED`).
+
+Ni siquiera tienes que verificar si el token existe para devolver un error. Puedes estar seguro de que si tu función se ejecuta, tendrá un `str` en ese token.
+
+Puedes probarlo ya en los docs interactivos:
+
+
+
+Todavía no estamos verificando la validez del token, pero ya es un comienzo.
+
+## Resumen
+
+Así que, en solo 3 o 4 líneas adicionales, ya tienes alguna forma primitiva de seguridad.
diff --git a/docs/es/docs/tutorial/security/get-current-user.md b/docs/es/docs/tutorial/security/get-current-user.md
new file mode 100644
index 000000000..249a70c18
--- /dev/null
+++ b/docs/es/docs/tutorial/security/get-current-user.md
@@ -0,0 +1,103 @@
+# Obtener Usuario Actual
+
+En el capítulo anterior, el sistema de seguridad (que se basa en el sistema de inyección de dependencias) le estaba dando a la *path operation function* un `token` como un `str`:
+
+{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *}
+
+Pero eso aún no es tan útil. Vamos a hacer que nos dé el usuario actual.
+
+## Crear un modelo de usuario
+
+Primero, vamos a crear un modelo de usuario con Pydantic.
+
+De la misma manera que usamos Pydantic para declarar cuerpos, podemos usarlo en cualquier otra parte:
+
+{* ../../docs_src/security/tutorial002_an_py310.py hl[5,12:6] *}
+
+## Crear una dependencia `get_current_user`
+
+Vamos a crear una dependencia `get_current_user`.
+
+¿Recuerdas que las dependencias pueden tener sub-dependencias?
+
+`get_current_user` tendrá una dependencia con el mismo `oauth2_scheme` que creamos antes.
+
+De la misma manera que estábamos haciendo antes en la *path operation* directamente, nuestra nueva dependencia `get_current_user` recibirá un `token` como un `str` de la sub-dependencia `oauth2_scheme`:
+
+{* ../../docs_src/security/tutorial002_an_py310.py hl[25] *}
+
+## Obtener el usuario
+
+`get_current_user` usará una función de utilidad (falsa) que creamos, que toma un token como un `str` y devuelve nuestro modelo de Pydantic `User`:
+
+{* ../../docs_src/security/tutorial002_an_py310.py hl[19:22,26:27] *}
+
+## Inyectar al usuario actual
+
+Entonces ahora podemos usar el mismo `Depends` con nuestro `get_current_user` en la *path operation*:
+
+{* ../../docs_src/security/tutorial002_an_py310.py hl[31] *}
+
+Ten en cuenta que declaramos el tipo de `current_user` como el modelo de Pydantic `User`.
+
+Esto nos ayudará dentro de la función con todo el autocompletado y chequeo de tipos.
+
+/// tip | Consejo
+
+Tal vez recuerdes que los cuerpos de request también se declaran con modelos de Pydantic.
+
+Aquí **FastAPI** no se confundirá porque estás usando `Depends`.
+
+///
+
+/// check | Revisa
+
+El modo en que este sistema de dependencias está diseñado nos permite tener diferentes dependencias (diferentes "dependables") que todas devuelven un modelo `User`.
+
+No estamos restringidos a tener solo una dependencia que pueda devolver ese tipo de datos.
+
+///
+
+## Otros modelos
+
+Ahora puedes obtener el usuario actual directamente en las *path operation functions* y manejar los mecanismos de seguridad a nivel de **Dependency Injection**, usando `Depends`.
+
+Y puedes usar cualquier modelo o datos para los requisitos de seguridad (en este caso, un modelo de Pydantic `User`).
+
+Pero no estás limitado a usar algún modelo de datos, clase o tipo específico.
+
+¿Quieres tener un `id` y `email` y no tener un `username` en tu modelo? Claro. Puedes usar estas mismas herramientas.
+
+¿Quieres solo tener un `str`? ¿O solo un `dict`? ¿O un instance de clase modelo de base de datos directamente? Todo funciona de la misma manera.
+
+¿En realidad no tienes usuarios que inicien sesión en tu aplicación sino robots, bots u otros sistemas, que solo tienen un token de acceso? Una vez más, todo funciona igual.
+
+Usa cualquier tipo de modelo, cualquier tipo de clase, cualquier tipo de base de datos que necesites para tu aplicación. **FastAPI** te cubre con el sistema de inyección de dependencias.
+
+## Tamaño del código
+
+Este ejemplo podría parecer extenso. Ten en cuenta que estamos mezclando seguridad, modelos de datos, funciones de utilidad y *path operations* en el mismo archivo.
+
+Pero aquí está el punto clave.
+
+El tema de seguridad e inyección de dependencias se escribe una vez.
+
+Y puedes hacerlo tan complejo como desees. Y aún así, tenerlo escrito solo una vez, en un solo lugar. Con toda la flexibilidad.
+
+Pero puedes tener miles de endpoints (*path operations*) usando el mismo sistema de seguridad.
+
+Y todos ellos (o cualquier porción de ellos que quieras) pueden aprovechar la reutilización de estas dependencias o cualquier otra dependencia que crees.
+
+Y todas estas miles de *path operations* pueden ser tan pequeñas como 3 líneas:
+
+{* ../../docs_src/security/tutorial002_an_py310.py hl[30:32] *}
+
+## Resumen
+
+Ahora puedes obtener el usuario actual directamente en tu *path operation function*.
+
+Ya estamos a mitad de camino.
+
+Solo necesitamos agregar una *path operation* para que el usuario/cliente envíe realmente el `username` y `password`.
+
+Eso es lo que viene a continuación.
diff --git a/docs/es/docs/tutorial/security/index.md b/docs/es/docs/tutorial/security/index.md
new file mode 100644
index 000000000..12e39fdaa
--- /dev/null
+++ b/docs/es/docs/tutorial/security/index.md
@@ -0,0 +1,105 @@
+# Seguridad
+
+Hay muchas formas de manejar la seguridad, autenticación y autorización.
+
+Y normalmente es un tema complejo y "difícil".
+
+En muchos frameworks y sistemas, solo manejar la seguridad y autenticación requiere una gran cantidad de esfuerzo y código (en muchos casos puede ser el 50% o más de todo el código escrito).
+
+**FastAPI** proporciona varias herramientas para ayudarte a manejar la **Seguridad** de manera fácil, rápida y estándar, sin tener que estudiar y aprender todas las especificaciones de seguridad.
+
+Pero primero, vamos a revisar algunos pequeños conceptos.
+
+## ¿Con prisa?
+
+Si no te importan ninguno de estos términos y solo necesitas agregar seguridad con autenticación basada en nombre de usuario y contraseña *ahora mismo*, salta a los siguientes capítulos.
+
+## OAuth2
+
+OAuth2 es una especificación que define varias maneras de manejar la autenticación y autorización.
+
+Es una especificación bastante extensa y cubre varios casos de uso complejos.
+
+Incluye formas de autenticarse usando un "tercero".
+
+Eso es lo que todos los sistemas con "iniciar sesión con Facebook, Google, Twitter, GitHub" utilizan internamente.
+
+### OAuth 1
+
+Hubo un OAuth 1, que es muy diferente de OAuth2, y más complejo, ya que incluía especificaciones directas sobre cómo encriptar la comunicación.
+
+No es muy popular o usado hoy en día.
+
+OAuth2 no especifica cómo encriptar la comunicación, espera que tengas tu aplicación servida con HTTPS.
+
+/// tip | Consejo
+
+En la sección sobre **deployment** verás cómo configurar HTTPS de forma gratuita, usando Traefik y Let's Encrypt.
+
+///
+
+## OpenID Connect
+
+OpenID Connect es otra especificación, basada en **OAuth2**.
+
+Solo extiende OAuth2 especificando algunas cosas que son relativamente ambiguas en OAuth2, para intentar hacerla más interoperable.
+
+Por ejemplo, el login de Google usa OpenID Connect (que internamente usa OAuth2).
+
+Pero el login de Facebook no soporta OpenID Connect. Tiene su propia versión de OAuth2.
+
+### OpenID (no "OpenID Connect")
+
+Hubo también una especificación "OpenID". Que intentaba resolver lo mismo que **OpenID Connect**, pero no estaba basada en OAuth2.
+
+Entonces, era un sistema completo adicional.
+
+No es muy popular o usado hoy en día.
+
+## OpenAPI
+
+OpenAPI (anteriormente conocido como Swagger) es la especificación abierta para construir APIs (ahora parte de la Linux Foundation).
+
+**FastAPI** se basa en **OpenAPI**.
+
+Eso es lo que hace posible tener múltiples interfaces de documentación interactiva automática, generación de código, etc.
+
+OpenAPI tiene una forma de definir múltiples "esquemas" de seguridad.
+
+Al usarlos, puedes aprovechar todas estas herramientas basadas en estándares, incluidos estos sistemas de documentación interactiva.
+
+OpenAPI define los siguientes esquemas de seguridad:
+
+* `apiKey`: una clave específica de la aplicación que puede provenir de:
+ * Un parámetro de query.
+ * Un header.
+ * Una cookie.
+* `http`: sistemas de autenticación HTTP estándar, incluyendo:
+ * `bearer`: un header `Authorization` con un valor de `Bearer ` más un token. Esto se hereda de OAuth2.
+ * Autenticación básica HTTP.
+ * Digest HTTP, etc.
+* `oauth2`: todas las formas de OAuth2 para manejar la seguridad (llamadas "flujos").
+ * Varios de estos flujos son apropiados para construir un proveedor de autenticación OAuth 2.0 (como Google, Facebook, Twitter, GitHub, etc.):
+ * `implicit`
+ * `clientCredentials`
+ * `authorizationCode`
+ * Pero hay un "flujo" específico que puede usarse perfectamente para manejar la autenticación directamente en la misma aplicación:
+ * `password`: algunos de los próximos capítulos cubrirán ejemplos de esto.
+* `openIdConnect`: tiene una forma de definir cómo descubrir automáticamente los datos de autenticación OAuth2.
+ * Este descubrimiento automático es lo que se define en la especificación de OpenID Connect.
+
+/// tip | Consejo
+
+Integrar otros proveedores de autenticación/autorización como Google, Facebook, Twitter, GitHub, etc. también es posible y relativamente fácil.
+
+El problema más complejo es construir un proveedor de autenticación/autorización como esos, pero **FastAPI** te da las herramientas para hacerlo fácilmente, mientras hace el trabajo pesado por ti.
+
+///
+
+## Utilidades de **FastAPI**
+
+FastAPI proporciona varias herramientas para cada uno de estos esquemas de seguridad en el módulo `fastapi.security` que simplifican el uso de estos mecanismos de seguridad.
+
+En los siguientes capítulos verás cómo agregar seguridad a tu API usando esas herramientas proporcionadas por **FastAPI**.
+
+Y también verás cómo se integra automáticamente en el sistema de documentación interactiva.
diff --git a/docs/es/docs/tutorial/security/oauth2-jwt.md b/docs/es/docs/tutorial/security/oauth2-jwt.md
new file mode 100644
index 000000000..4ab9c8ca2
--- /dev/null
+++ b/docs/es/docs/tutorial/security/oauth2-jwt.md
@@ -0,0 +1,273 @@
+# OAuth2 con Password (y hashing), Bearer con tokens JWT
+
+Ahora que tenemos todo el flujo de seguridad, hagamos que la aplicación sea realmente segura, usando tokens JWT y hashing de contraseñas seguras.
+
+Este código es algo que puedes usar realmente en tu aplicación, guardar los hashes de las contraseñas en tu base de datos, etc.
+
+Vamos a empezar desde donde lo dejamos en el capítulo anterior e incrementarlo.
+
+## Acerca de JWT
+
+JWT significa "JSON Web Tokens".
+
+Es un estándar para codificar un objeto JSON en un string largo y denso sin espacios. Se ve así:
+
+```
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+```
+
+No está encriptado, por lo que cualquiera podría recuperar la información de los contenidos.
+
+Pero está firmado. Así que, cuando recibes un token que has emitido, puedes verificar que realmente lo emitiste.
+
+De esta manera, puedes crear un token con una expiración de, digamos, 1 semana. Y luego, cuando el usuario regresa al día siguiente con el token, sabes que el usuario todavía está registrado en tu sistema.
+
+Después de una semana, el token estará expirado y el usuario no estará autorizado y tendrá que iniciar sesión nuevamente para obtener un nuevo token. Y si el usuario (o un tercero) intenta modificar el token para cambiar la expiración, podrás descubrirlo, porque las firmas no coincidirían.
+
+Si quieres jugar con tokens JWT y ver cómo funcionan, revisa https://jwt.io.
+
+## Instalar `PyJWT`
+
+Necesitamos instalar `PyJWT` para generar y verificar los tokens JWT en Python.
+
+Asegúrate de crear un [entorno virtual](../../virtual-environments.md){.internal-link target=_blank}, activarlo y luego instalar `pyjwt`:
+
+
+
+Autoriza la aplicación de la misma manera que antes.
+
+Usando las credenciales:
+
+Usuario: `johndoe`
+Contraseña: `secret`
+
+/// check | Revisa
+
+Observa que en ninguna parte del código está la contraseña en texto claro "`secret`", solo tenemos la versión con hash.
+
+///
+
+
+
+Llama al endpoint `/users/me/`, obtendrás el response como:
+
+```JSON
+{
+ "username": "johndoe",
+ "email": "johndoe@example.com",
+ "full_name": "John Doe",
+ "disabled": false
+}
+```
+
+
+
+Si abres las herramientas de desarrollador, podrías ver cómo los datos enviados solo incluyen el token, la contraseña solo se envía en la primera petición para autenticar al usuario y obtener ese token de acceso, pero no después:
+
+
+
+/// note | Nota
+
+Observa el header `Authorization`, con un valor que comienza con `Bearer `.
+
+///
+
+## Uso avanzado con `scopes`
+
+OAuth2 tiene la noción de "scopes".
+
+Puedes usarlos para agregar un conjunto específico de permisos a un token JWT.
+
+Luego, puedes darle este token directamente a un usuario o a un tercero, para interactuar con tu API con un conjunto de restricciones.
+
+Puedes aprender cómo usarlos y cómo están integrados en **FastAPI** más adelante en la **Guía de Usuario Avanzada**.
+
+## Resumen
+
+Con lo que has visto hasta ahora, puedes configurar una aplicación **FastAPI** segura usando estándares como OAuth2 y JWT.
+
+En casi cualquier framework el manejo de la seguridad se convierte en un tema bastante complejo rápidamente.
+
+Muchos paquetes que lo simplifican tienen que hacer muchos compromisos con el modelo de datos, la base de datos y las funcionalidades disponibles. Y algunos de estos paquetes que simplifican las cosas demasiado en realidad tienen fallos de seguridad en el fondo.
+
+---
+
+**FastAPI** no hace ningún compromiso con ninguna base de datos, modelo de datos o herramienta.
+
+Te da toda la flexibilidad para elegir aquellas que se ajusten mejor a tu proyecto.
+
+Y puedes usar directamente muchos paquetes bien mantenidos y ampliamente usados como `passlib` y `PyJWT`, porque **FastAPI** no requiere mecanismos complejos para integrar paquetes externos.
+
+Pero te proporciona las herramientas para simplificar el proceso tanto como sea posible sin comprometer la flexibilidad, la robustez o la seguridad.
+
+Y puedes usar e implementar protocolos seguros y estándar, como OAuth2 de una manera relativamente simple.
+
+Puedes aprender más en la **Guía de Usuario Avanzada** sobre cómo usar "scopes" de OAuth2, para un sistema de permisos más detallado, siguiendo estos mismos estándares. OAuth2 con scopes es el mecanismo utilizado por muchos grandes proveedores de autenticación, como Facebook, Google, GitHub, Microsoft, Twitter, etc. para autorizar aplicaciones de terceros para interactuar con sus APIs en nombre de sus usuarios.
diff --git a/docs/es/docs/tutorial/security/simple-oauth2.md b/docs/es/docs/tutorial/security/simple-oauth2.md
new file mode 100644
index 000000000..67449332f
--- /dev/null
+++ b/docs/es/docs/tutorial/security/simple-oauth2.md
@@ -0,0 +1,289 @@
+# Simple OAuth2 con Password y Bearer
+
+Ahora vamos a construir a partir del capítulo anterior y agregar las partes faltantes para tener un flujo de seguridad completo.
+
+## Obtener el `username` y `password`
+
+Vamos a usar las utilidades de seguridad de **FastAPI** para obtener el `username` y `password`.
+
+OAuth2 especifica que cuando se utiliza el "password flow" (que estamos usando), el cliente/usuario debe enviar campos `username` y `password` como form data.
+
+Y la especificación dice que los campos deben llamarse así. Por lo que `user-name` o `email` no funcionarían.
+
+Pero no te preocupes, puedes mostrarlo como quieras a tus usuarios finales en el frontend.
+
+Y tus modelos de base de datos pueden usar cualquier otro nombre que desees.
+
+Pero para la *path operation* de inicio de sesión, necesitamos usar estos nombres para ser compatibles con la especificación (y poder, por ejemplo, utilizar el sistema de documentación integrada de la API).
+
+La especificación también establece que el `username` y `password` deben enviarse como form data (por lo que no hay JSON aquí).
+
+### `scope`
+
+La especificación también indica que el cliente puede enviar otro campo del formulario llamado "`scope`".
+
+El nombre del campo del formulario es `scope` (en singular), pero en realidad es un string largo con "scopes" separados por espacios.
+
+Cada "scope" es simplemente un string (sin espacios).
+
+Normalmente se utilizan para declarar permisos de seguridad específicos, por ejemplo:
+
+* `users:read` o `users:write` son ejemplos comunes.
+* `instagram_basic` es usado por Facebook / Instagram.
+* `https://www.googleapis.com/auth/drive` es usado por Google.
+
+/// info | Información
+
+En OAuth2 un "scope" es solo un string que declara un permiso específico requerido.
+
+No importa si tiene otros caracteres como `:` o si es una URL.
+
+Esos detalles son específicos de la implementación.
+
+Para OAuth2 son solo strings.
+
+///
+
+## Código para obtener el `username` y `password`
+
+Ahora vamos a usar las utilidades proporcionadas por **FastAPI** para manejar esto.
+
+### `OAuth2PasswordRequestForm`
+
+Primero, importa `OAuth2PasswordRequestForm`, y úsalo como una dependencia con `Depends` en la *path operation* para `/token`:
+
+{* ../../docs_src/security/tutorial003_an_py310.py hl[4,78] *}
+
+`OAuth2PasswordRequestForm` es una dependencia de clase que declara un body de formulario con:
+
+* El `username`.
+* El `password`.
+* Un campo opcional `scope` como un string grande, compuesto por strings separados por espacios.
+* Un `grant_type` opcional.
+
+/// tip | Consejo
+
+La especificación de OAuth2 en realidad *requiere* un campo `grant_type` con un valor fijo de `password`, pero `OAuth2PasswordRequestForm` no lo obliga.
+
+Si necesitas imponerlo, utiliza `OAuth2PasswordRequestFormStrict` en lugar de `OAuth2PasswordRequestForm`.
+
+///
+
+* Un `client_id` opcional (no lo necesitamos para nuestro ejemplo).
+* Un `client_secret` opcional (no lo necesitamos para nuestro ejemplo).
+
+/// info | Información
+
+`OAuth2PasswordRequestForm` no es una clase especial para **FastAPI** como lo es `OAuth2PasswordBearer`.
+
+`OAuth2PasswordBearer` hace que **FastAPI** sepa que es un esquema de seguridad. Así que se añade de esa manera a OpenAPI.
+
+Pero `OAuth2PasswordRequestForm` es solo una dependencia de clase que podrías haber escrito tú mismo, o podrías haber declarado parámetros de `Form` directamente.
+
+Pero como es un caso de uso común, se proporciona directamente por **FastAPI**, solo para facilitarlo.
+
+///
+
+### Usa el form data
+
+/// tip | Consejo
+
+La instance de la clase de dependencia `OAuth2PasswordRequestForm` no tendrá un atributo `scope` con el string largo separado por espacios, en su lugar, tendrá un atributo `scopes` con la lista real de strings para cada scope enviado.
+
+No estamos usando `scopes` en este ejemplo, pero la funcionalidad está ahí si la necesitas.
+
+///
+
+Ahora, obtén los datos del usuario desde la base de datos (falsa), usando el `username` del campo del form.
+
+Si no existe tal usuario, devolvemos un error diciendo "Incorrect username or password".
+
+Para el error, usamos la excepción `HTTPException`:
+
+{* ../../docs_src/security/tutorial003_an_py310.py hl[3,79:81] *}
+
+### Revisa el password
+
+En este punto tenemos los datos del usuario de nuestra base de datos, pero no hemos revisado el password.
+
+Primero pongamos esos datos en el modelo `UserInDB` de Pydantic.
+
+Nunca deberías guardar passwords en texto plano, así que, usaremos el sistema de hash de passwords (falso).
+
+Si los passwords no coinciden, devolvemos el mismo error.
+
+#### Hashing de passwords
+
+"Hacer hash" significa: convertir algún contenido (un password en este caso) en una secuencia de bytes (solo un string) que parece un galimatías.
+
+Siempre que pases exactamente el mismo contenido (exactamente el mismo password) obtienes exactamente el mismo galimatías.
+
+Pero no puedes convertir del galimatías al password.
+
+##### Por qué usar hashing de passwords
+
+Si tu base de datos es robada, el ladrón no tendrá los passwords en texto plano de tus usuarios, solo los hashes.
+
+Entonces, el ladrón no podrá intentar usar esos mismos passwords en otro sistema (como muchos usuarios usan el mismo password en todas partes, esto sería peligroso).
+
+{* ../../docs_src/security/tutorial003_an_py310.py hl[82:85] *}
+
+#### Sobre `**user_dict`
+
+`UserInDB(**user_dict)` significa:
+
+*Pasa las claves y valores de `user_dict` directamente como argumentos clave-valor, equivalente a:*
+
+```Python
+UserInDB(
+ username = user_dict["username"],
+ email = user_dict["email"],
+ full_name = user_dict["full_name"],
+ disabled = user_dict["disabled"],
+ hashed_password = user_dict["hashed_password"],
+)
+```
+
+/// info | Información
+
+Para una explicación más completa de `**user_dict` revisa en [la documentación para **Extra Models**](../extra-models.md#about-user_indict){.internal-link target=_blank}.
+
+///
+
+## Devolver el token
+
+El response del endpoint `token` debe ser un objeto JSON.
+
+Debe tener un `token_type`. En nuestro caso, como estamos usando tokens "Bearer", el tipo de token debe ser "`bearer`".
+
+Y debe tener un `access_token`, con un string que contenga nuestro token de acceso.
+
+Para este ejemplo simple, vamos a ser completamente inseguros y devolver el mismo `username` como el token.
+
+/// tip | Consejo
+
+En el próximo capítulo, verás una implementación segura real, con hashing de passwords y tokens JWT.
+
+Pero por ahora, enfoquémonos en los detalles específicos que necesitamos.
+
+///
+
+{* ../../docs_src/security/tutorial003_an_py310.py hl[87] *}
+
+/// tip | Consejo
+
+De acuerdo con la especificación, deberías devolver un JSON con un `access_token` y un `token_type`, igual que en este ejemplo.
+
+Esto es algo que tienes que hacer tú mismo en tu código, y asegurarte de usar esas claves JSON.
+
+Es casi lo único que tienes que recordar hacer correctamente tú mismo, para ser compatible con las especificaciones.
+
+Para el resto, **FastAPI** lo maneja por ti.
+
+///
+
+## Actualizar las dependencias
+
+Ahora vamos a actualizar nuestras dependencias.
+
+Queremos obtener el `current_user` *solo* si este usuario está activo.
+
+Entonces, creamos una dependencia adicional `get_current_active_user` que a su vez utiliza `get_current_user` como dependencia.
+
+Ambas dependencias solo devolverán un error HTTP si el usuario no existe, o si está inactivo.
+
+Así que, en nuestro endpoint, solo obtendremos un usuario si el usuario existe, fue autenticado correctamente, y está activo:
+
+{* ../../docs_src/security/tutorial003_an_py310.py hl[58:66,69:74,94] *}
+
+/// info | Información
+
+El header adicional `WWW-Authenticate` con el valor `Bearer` que estamos devolviendo aquí también es parte de la especificación.
+
+Cualquier código de estado HTTP (error) 401 "UNAUTHORIZED" se supone que también debe devolver un header `WWW-Authenticate`.
+
+En el caso de tokens bearer (nuestro caso), el valor de ese header debe ser `Bearer`.
+
+De hecho, puedes omitir ese header extra y aún funcionaría.
+
+Pero se proporciona aquí para cumplir con las especificaciones.
+
+Además, podría haber herramientas que lo esperen y lo usen (ahora o en el futuro) y eso podría ser útil para ti o tus usuarios, ahora o en el futuro.
+
+Ese es el beneficio de los estándares...
+
+///
+
+## Verlo en acción
+
+Abre la documentación interactiva: http://127.0.0.1:8000/docs.
+
+### Autenticar
+
+Haz clic en el botón "Authorize".
+
+Usa las credenciales:
+
+Usuario: `johndoe`
+
+Contraseña: `secret`
+
+
+
+Después de autenticarte en el sistema, lo verás así:
+
+
+
+### Obtener tus propios datos de usuario
+
+Ahora usa la operación `GET` con la path `/users/me`.
+
+Obtendrás los datos de tu usuario, como:
+
+```JSON
+{
+ "username": "johndoe",
+ "email": "johndoe@example.com",
+ "full_name": "John Doe",
+ "disabled": false,
+ "hashed_password": "fakehashedsecret"
+}
+```
+
+
+
+Si haces clic en el icono de candado y cierras sesión, y luego intentas la misma operación nuevamente, obtendrás un error HTTP 401 de:
+
+```JSON
+{
+ "detail": "Not authenticated"
+}
+```
+
+### Usuario inactivo
+
+Ahora prueba con un usuario inactivo, autentícate con:
+
+Usuario: `alice`
+
+Contraseña: `secret2`
+
+Y trata de usar la operación `GET` con la path `/users/me`.
+
+Obtendrás un error de "Usuario inactivo", como:
+
+```JSON
+{
+ "detail": "Inactive user"
+}
+```
+
+## Recapitulación
+
+Ahora tienes las herramientas para implementar un sistema de seguridad completo basado en `username` y `password` para tu API.
+
+Usando estas herramientas, puedes hacer que el sistema de seguridad sea compatible con cualquier base de datos y con cualquier modelo de usuario o de datos.
+
+El único detalle que falta es que en realidad no es "seguro" aún.
+
+En el próximo capítulo verás cómo usar un paquete de hashing de passwords seguro y tokens JWT.
diff --git a/docs/es/docs/tutorial/sql-databases.md b/docs/es/docs/tutorial/sql-databases.md
new file mode 100644
index 000000000..68cc78603
--- /dev/null
+++ b/docs/es/docs/tutorial/sql-databases.md
@@ -0,0 +1,360 @@
+# Bases de Datos SQL (Relacionales)
+
+**FastAPI** no requiere que uses una base de datos SQL (relacional). Pero puedes utilizar **cualquier base de datos** que desees.
+
+Aquí veremos un ejemplo usando SQLModel.
+
+**SQLModel** está construido sobre SQLAlchemy y Pydantic. Fue creado por el mismo autor de **FastAPI** para ser la combinación perfecta para aplicaciones de FastAPI que necesiten usar **bases de datos SQL**.
+
+/// tip | Consejo
+
+Puedes usar cualquier otro paquete de bases de datos SQL o NoSQL que quieras (en algunos casos llamadas "ORMs"), FastAPI no te obliga a usar nada. 😎
+
+///
+
+Como SQLModel se basa en SQLAlchemy, puedes usar fácilmente **cualquier base de datos soportada** por SQLAlchemy (lo que las hace también soportadas por SQLModel), como:
+
+* PostgreSQL
+* MySQL
+* SQLite
+* Oracle
+* Microsoft SQL Server, etc.
+
+En este ejemplo, usaremos **SQLite**, porque utiliza un solo archivo y Python tiene soporte integrado. Así que puedes copiar este ejemplo y ejecutarlo tal cual.
+
+Más adelante, para tu aplicación en producción, es posible que desees usar un servidor de base de datos como **PostgreSQL**.
+
+/// tip | Consejo
+
+Hay un generador de proyectos oficial con **FastAPI** y **PostgreSQL** que incluye un frontend y más herramientas: https://github.com/fastapi/full-stack-fastapi-template
+
+///
+
+Este es un tutorial muy simple y corto, si deseas aprender sobre bases de datos en general, sobre SQL o más funcionalidades avanzadas, ve a la documentación de SQLModel.
+
+## Instalar `SQLModel`
+
+Primero, asegúrate de crear tu [entorno virtual](../virtual-environments.md){.internal-link target=_blank}, actívalo, y luego instala `sqlmodel`:
+
+
+
+
-
-
+
+
-
-
+
+
@@ -90,7 +90,7 @@ FastAPI یک وب فریمورک مدرن و سریع (با کارایی با
email_validator - برای اعتبارسنجی آدرسهای ایمیل.
+* email-validator - برای اعتبارسنجی آدرسهای ایمیل.
استفاده شده توسط Starlette:
diff --git a/docs/fa/docs/learn/index.md b/docs/fa/docs/learn/index.md
new file mode 100644
index 000000000..06aa7f00e
--- /dev/null
+++ b/docs/fa/docs/learn/index.md
@@ -0,0 +1,5 @@
+# یادگیری
+
+اینجا بخشهای مقدماتی و آموزشهایی هستن که برای یادگیری **FastAPI** بهت کمک میکنن.
+
+میتونی اینو یه **کتاب**، یه **دوره آموزشی**، یا راه **رسمی** و پیشنهادی برای یادگیری FastAPI در نظر بگیری. 😎
diff --git a/docs/fa/docs/tutorial/middleware.md b/docs/fa/docs/tutorial/middleware.md
index c5752a4b5..75b1c4c5c 100644
--- a/docs/fa/docs/tutorial/middleware.md
+++ b/docs/fa/docs/tutorial/middleware.md
@@ -11,10 +11,13 @@
* می تواند کاری با **پاسخ** انجام دهید یا هر کد مورد نیازتان را اجرا کند.
* سپس **پاسخ** را برمی گرداند.
-!!! توجه "جزئیات فنی"
- در صورت وجود وابستگی هایی با `yield`، کد خروجی **پس از** اجرای میانافزار اجرا خواهد شد.
+/// توجه | جزئیات فنی
- در صورت وجود هر گونه وظایف پس زمینه (که در ادامه توضیح داده میشوند)، تمام میانافزارها *پس از آن* اجرا خواهند شد.
+در صورت وجود وابستگی هایی با `yield`، کد خروجی **پس از** اجرای میانافزار اجرا خواهد شد.
+
+در صورت وجود هر گونه وظایف پس زمینه (که در ادامه توضیح داده میشوند)، تمام میانافزارها *پس از آن* اجرا خواهند شد.
+
+///
## ساخت یک میان افزار
@@ -27,18 +30,21 @@
* سپس `پاسخ` تولید شده توسط *path operation* مربوطه را برمیگرداند.
* شما میتوانید سپس `پاسخ` را تغییر داده و پس از آن را برگردانید.
-```Python hl_lines="8-9 11 14"
-{!../../../docs_src/middleware/tutorial001.py!}
-```
+{* ../../docs_src/middleware/tutorial001.py hl[8:9,11,14] *}
-!!! نکته به خاطر داشته باشید که هدرهای اختصاصی سفارشی را می توان با استفاده از پیشوند "X-" اضافه کرد.
+/// نکته | به خاطر داشته باشید که هدرهای اختصاصی سفارشی را می توان با استفاده از پیشوند "X-" اضافه کرد.
- اما اگر هدرهای سفارشی دارید که میخواهید مرورگر کاربر بتواند آنها را ببیند، باید آنها را با استفاده از پارامتر `expose_headers` که در مستندات CORS از Starlette توضیح داده شده است، به پیکربندی CORS خود اضافه کنید.
+اما اگر هدرهای سفارشی دارید که میخواهید مرورگر کاربر بتواند آنها را ببیند، باید آنها را با استفاده از پارامتر `expose_headers` که در مستندات CORS از Starlette توضیح داده شده است، به پیکربندی CORS خود اضافه کنید.
-!!! توجه "جزئیات فنی"
- شما همچنین میتوانید از `from starlette.requests import Request` استفاده کنید.
+///
- **FastAPI** این را به عنوان یک سهولت برای شما به عنوان برنامهنویس فراهم میکند. اما این مستقیما از Starlette به دست میآید.
+/// توجه | جزئیات فنی
+
+شما همچنین میتوانید از `from starlette.requests import Request` استفاده کنید.
+
+**FastAPI** این را به عنوان یک سهولت برای شما به عنوان برنامهنویس فراهم میکند. اما این مستقیما از Starlette به دست میآید.
+
+///
### قبل و بعد از `پاسخ`
@@ -48,9 +54,7 @@
به عنوان مثال، میتوانید یک هدر سفارشی به نام `X-Process-Time` که شامل زمان پردازش درخواست و تولید پاسخ به صورت ثانیه است، اضافه کنید.
-```Python hl_lines="10 12-13"
-{!../../../docs_src/middleware/tutorial001.py!}
-```
+{* ../../docs_src/middleware/tutorial001.py hl[10,12:13] *}
## سایر میان افزار
diff --git a/docs/fa/docs/tutorial/security/index.md b/docs/fa/docs/tutorial/security/index.md
index 4e68ba961..c0827a8b3 100644
--- a/docs/fa/docs/tutorial/security/index.md
+++ b/docs/fa/docs/tutorial/security/index.md
@@ -33,8 +33,11 @@
پروتکل استاندارد OAuth2 روش رمزگذاری ارتباط را مشخص نمی کند، بلکه انتظار دارد که برنامه شما با HTTPS سرویس دهی شود.
-!!! نکته
- در بخش در مورد **استقرار** ، شما یاد خواهید گرفت که چگونه با استفاده از Traefik و Let's Encrypt رایگان HTTPS را راه اندازی کنید.
+/// نکته
+
+در بخش در مورد **استقرار** ، شما یاد خواهید گرفت که چگونه با استفاده از Traefik و Let's Encrypt رایگان HTTPS را راه اندازی کنید.
+
+///
## استاندارد OpenID Connect
@@ -86,10 +89,13 @@
* شیوه `openIdConnect`: یک روش برای تعریف نحوه کشف دادههای احراز هویت OAuth2 به صورت خودکار.
* کشف خودکار این موضوع را که در مشخصه OpenID Connect تعریف شده است، مشخص میکند.
-!!! نکته
- ادغام سایر ارائهدهندگان احراز هویت/اجازهدهی مانند گوگل، فیسبوک، توییتر، گیتهاب و غیره نیز امکانپذیر و نسبتاً آسان است.
+/// نکته
- مشکل پیچیدهترین مسئله، ساخت یک ارائهدهنده احراز هویت/اجازهدهی مانند آنها است، اما **FastAPI** ابزارهای لازم برای انجام این کار را با سهولت به شما میدهد و همه کارهای سنگین را برای شما انجام میدهد.
+ادغام سایر ارائهدهندگان احراز هویت/اجازهدهی مانند گوگل، فیسبوک، توییتر، گیتهاب و غیره نیز امکانپذیر و نسبتاً آسان است.
+
+مشکل پیچیدهترین مسئله، ساخت یک ارائهدهنده احراز هویت/اجازهدهی مانند آنها است، اما **FastAPI** ابزارهای لازم برای انجام این کار را با سهولت به شما میدهد و همه کارهای سنگین را برای شما انجام میدهد.
+
+///
## ابزارهای **FastAPI**
diff --git a/docs/fr/docs/advanced/additional-responses.md b/docs/fr/docs/advanced/additional-responses.md
index 685a054ad..38527aad3 100644
--- a/docs/fr/docs/advanced/additional-responses.md
+++ b/docs/fr/docs/advanced/additional-responses.md
@@ -1,9 +1,12 @@
# Réponses supplémentaires dans OpenAPI
-!!! warning "Attention"
- Ceci concerne un sujet plutôt avancé.
+/// warning | Attention
- Si vous débutez avec **FastAPI**, vous n'en aurez peut-être pas besoin.
+Ceci concerne un sujet plutôt avancé.
+
+Si vous débutez avec **FastAPI**, vous n'en aurez peut-être pas besoin.
+
+///
Vous pouvez déclarer des réponses supplémentaires, avec des codes HTTP, des types de médias, des descriptions, etc.
@@ -23,24 +26,28 @@ Chacun de ces `dict` de réponse peut avoir une clé `model`, contenant un modè
Par exemple, pour déclarer une autre réponse avec un code HTTP `404` et un modèle Pydantic `Message`, vous pouvez écrire :
-```Python hl_lines="18 22"
-{!../../../docs_src/additional_responses/tutorial001.py!}
-```
+{* ../../docs_src/additional_responses/tutorial001.py hl[18,22] *}
-!!! note "Remarque"
- Gardez à l'esprit que vous devez renvoyer directement `JSONResponse`.
+/// note | Remarque
-!!! info
- La clé `model` ne fait pas partie d'OpenAPI.
+Gardez à l'esprit que vous devez renvoyer directement `JSONResponse`.
- **FastAPI** prendra le modèle Pydantic à partir de là, générera le `JSON Schema` et le placera au bon endroit.
+///
- Le bon endroit est :
+/// info
- * Dans la clé `content`, qui a pour valeur un autre objet JSON (`dict`) qui contient :
- * Une clé avec le type de support, par ex. `application/json`, qui contient comme valeur un autre objet JSON, qui contient :
- * Une clé `schema`, qui a pour valeur le schéma JSON du modèle, voici le bon endroit.
- * **FastAPI** ajoute ici une référence aux schémas JSON globaux à un autre endroit de votre OpenAPI au lieu de l'inclure directement. De cette façon, d'autres applications et clients peuvent utiliser ces schémas JSON directement, fournir de meilleurs outils de génération de code, etc.
+La clé `model` ne fait pas partie d'OpenAPI.
+
+**FastAPI** prendra le modèle Pydantic à partir de là, générera le `JSON Schema` et le placera au bon endroit.
+
+Le bon endroit est :
+
+* Dans la clé `content`, qui a pour valeur un autre objet JSON (`dict`) qui contient :
+ * Une clé avec le type de support, par ex. `application/json`, qui contient comme valeur un autre objet JSON, qui contient :
+ * Une clé `schema`, qui a pour valeur le schéma JSON du modèle, voici le bon endroit.
+ * **FastAPI** ajoute ici une référence aux schémas JSON globaux à un autre endroit de votre OpenAPI au lieu de l'inclure directement. De cette façon, d'autres applications et clients peuvent utiliser ces schémas JSON directement, fournir de meilleurs outils de génération de code, etc.
+
+///
Les réponses générées au format OpenAPI pour cette *opération de chemin* seront :
@@ -168,17 +175,21 @@ Vous pouvez utiliser ce même paramètre `responses` pour ajouter différents ty
Par exemple, vous pouvez ajouter un type de média supplémentaire `image/png`, en déclarant que votre *opération de chemin* peut renvoyer un objet JSON (avec le type de média `application/json`) ou une image PNG :
-```Python hl_lines="19-24 28"
-{!../../../docs_src/additional_responses/tutorial002.py!}
-```
+{* ../../docs_src/additional_responses/tutorial002.py hl[19:24,28] *}
-!!! note "Remarque"
- Notez que vous devez retourner l'image en utilisant directement un `FileResponse`.
+/// note | Remarque
-!!! info
- À moins que vous ne spécifiiez explicitement un type de média différent dans votre paramètre `responses`, FastAPI supposera que la réponse a le même type de média que la classe de réponse principale (par défaut `application/json`).
+Notez que vous devez retourner l'image en utilisant directement un `FileResponse`.
- Mais si vous avez spécifié une classe de réponse personnalisée avec `None` comme type de média, FastAPI utilisera `application/json` pour toute réponse supplémentaire associée à un modèle.
+///
+
+/// info
+
+À moins que vous ne spécifiiez explicitement un type de média différent dans votre paramètre `responses`, FastAPI supposera que la réponse a le même type de média que la classe de réponse principale (par défaut `application/json`).
+
+Mais si vous avez spécifié une classe de réponse personnalisée avec `None` comme type de média, FastAPI utilisera `application/json` pour toute réponse supplémentaire associée à un modèle.
+
+///
## Combinaison d'informations
@@ -192,9 +203,7 @@ Par exemple, vous pouvez déclarer une réponse avec un code HTTP `404` qui util
Et une réponse avec un code HTTP `200` qui utilise votre `response_model`, mais inclut un `example` personnalisé :
-```Python hl_lines="20-31"
-{!../../../docs_src/additional_responses/tutorial003.py!}
-```
+{* ../../docs_src/additional_responses/tutorial003.py hl[20:31] *}
Tout sera combiné et inclus dans votre OpenAPI, et affiché dans la documentation de l'API :
@@ -228,9 +237,7 @@ Vous pouvez utiliser cette technique pour réutiliser certaines réponses préd
Par exemple:
-```Python hl_lines="13-17 26"
-{!../../../docs_src/additional_responses/tutorial004.py!}
-```
+{* ../../docs_src/additional_responses/tutorial004.py hl[13:17,26] *}
## Plus d'informations sur les réponses OpenAPI
diff --git a/docs/fr/docs/advanced/additional-status-codes.md b/docs/fr/docs/advanced/additional-status-codes.md
index 51f0db737..dde6b9a63 100644
--- a/docs/fr/docs/advanced/additional-status-codes.md
+++ b/docs/fr/docs/advanced/additional-status-codes.md
@@ -14,21 +14,25 @@ Mais vous voulez aussi qu'il accepte de nouveaux éléments. Et lorsque les él
Pour y parvenir, importez `JSONResponse` et renvoyez-y directement votre contenu, en définissant le `status_code` que vous souhaitez :
-```Python hl_lines="4 25"
-{!../../../docs_src/additional_status_codes/tutorial001.py!}
-```
+{* ../../docs_src/additional_status_codes/tutorial001.py hl[4,25] *}
-!!! warning "Attention"
- Lorsque vous renvoyez une `Response` directement, comme dans l'exemple ci-dessus, elle sera renvoyée directement.
+/// warning | Attention
- Elle ne sera pas sérialisée avec un modèle.
+Lorsque vous renvoyez une `Response` directement, comme dans l'exemple ci-dessus, elle sera renvoyée directement.
- Assurez-vous qu'il contient les données souhaitées et que les valeurs soient dans un format JSON valides (si vous utilisez une `JSONResponse`).
+Elle ne sera pas sérialisée avec un modèle.
-!!! note "Détails techniques"
- Vous pouvez également utiliser `from starlette.responses import JSONResponse`.
+Assurez-vous qu'il contient les données souhaitées et que les valeurs soient dans un format JSON valides (si vous utilisez une `JSONResponse`).
- Pour plus de commodités, **FastAPI** fournit les objets `starlette.responses` sous forme d'un alias accessible par `fastapi.responses`. Mais la plupart des réponses disponibles proviennent directement de Starlette. Il en est de même avec l'objet `statut`.
+///
+
+/// note | Détails techniques
+
+Vous pouvez également utiliser `from starlette.responses import JSONResponse`.
+
+Pour plus de commodités, **FastAPI** fournit les objets `starlette.responses` sous forme d'un alias accessible par `fastapi.responses`. Mais la plupart des réponses disponibles proviennent directement de Starlette. Il en est de même avec l'objet `statut`.
+
+///
## Documents OpenAPI et API
diff --git a/docs/fr/docs/advanced/index.md b/docs/fr/docs/advanced/index.md
index 4599bcb6f..d9d8ad8e6 100644
--- a/docs/fr/docs/advanced/index.md
+++ b/docs/fr/docs/advanced/index.md
@@ -6,10 +6,13 @@ Le [Tutoriel - Guide de l'utilisateur](../tutorial/index.md){.internal-link targ
Dans les sections suivantes, vous verrez des options, configurations et fonctionnalités supplémentaires.
-!!! note "Remarque"
- Les sections de ce chapitre ne sont **pas nécessairement "avancées"**.
+/// note | Remarque
- Et il est possible que pour votre cas d'utilisation, la solution se trouve dans l'un d'entre eux.
+Les sections de ce chapitre ne sont **pas nécessairement "avancées"**.
+
+Et il est possible que pour votre cas d'utilisation, la solution se trouve dans l'un d'entre eux.
+
+///
## Lisez d'abord le didacticiel
diff --git a/docs/fr/docs/advanced/path-operation-advanced-configuration.md b/docs/fr/docs/advanced/path-operation-advanced-configuration.md
index 77f551aea..7daf0fc65 100644
--- a/docs/fr/docs/advanced/path-operation-advanced-configuration.md
+++ b/docs/fr/docs/advanced/path-operation-advanced-configuration.md
@@ -2,16 +2,17 @@
## ID d'opération OpenAPI
-!!! warning "Attention"
- Si vous n'êtes pas un "expert" en OpenAPI, vous n'en avez probablement pas besoin.
+/// warning | Attention
+
+Si vous n'êtes pas un "expert" en OpenAPI, vous n'en avez probablement pas besoin.
+
+///
Dans OpenAPI, les chemins sont des ressources, tels que /users/ ou /items/, exposées par votre API, et les opérations sont les méthodes HTTP utilisées pour manipuler ces chemins, telles que GET, POST ou DELETE. Les operationId sont des chaînes uniques facultatives utilisées pour identifier une opération d'un chemin. Vous pouvez définir l'OpenAPI `operationId` à utiliser dans votre *opération de chemin* avec le paramètre `operation_id`.
Vous devez vous assurer qu'il est unique pour chaque opération.
-```Python hl_lines="6"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial001.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial001.py hl[6] *}
### Utilisation du nom *path operation function* comme operationId
@@ -19,25 +20,27 @@ Si vous souhaitez utiliser les noms de fonction de vos API comme `operationId`,
Vous devriez le faire après avoir ajouté toutes vos *paramètres de chemin*.
-```Python hl_lines="2 12-21 24"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial002.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial002.py hl[2,12:21,24] *}
-!!! tip "Astuce"
- Si vous appelez manuellement `app.openapi()`, vous devez mettre à jour les `operationId` avant.
+/// tip | Astuce
-!!! warning "Attention"
- Pour faire cela, vous devez vous assurer que chacun de vos *chemin* ait un nom unique.
+Si vous appelez manuellement `app.openapi()`, vous devez mettre à jour les `operationId` avant.
- Même s'ils se trouvent dans des modules différents (fichiers Python).
+///
+
+/// warning | Attention
+
+Pour faire cela, vous devez vous assurer que chacun de vos *chemin* ait un nom unique.
+
+Même s'ils se trouvent dans des modules différents (fichiers Python).
+
+///
## Exclusion d'OpenAPI
Pour exclure un *chemin* du schéma OpenAPI généré (et donc des systèmes de documentation automatiques), utilisez le paramètre `include_in_schema` et assignez-lui la valeur `False` :
-```Python hl_lines="6"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial003.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial003.py hl[6] *}
## Description avancée de docstring
@@ -47,9 +50,7 @@ L'ajout d'un `\f` (un caractère d'échappement "form feed") va permettre à **F
Il n'apparaîtra pas dans la documentation, mais d'autres outils (tel que Sphinx) pourront utiliser le reste.
-```Python hl_lines="19-29"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial004.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial004.py hl[19:29] *}
## Réponses supplémentaires
@@ -65,8 +66,11 @@ Il y a un chapitre entier ici dans la documentation à ce sujet, vous pouvez le
Lorsque vous déclarez un *chemin* dans votre application, **FastAPI** génère automatiquement les métadonnées concernant ce *chemin* à inclure dans le schéma OpenAPI.
-!!! note "Détails techniques"
- La spécification OpenAPI appelle ces métadonnées des Objets d'opération.
+/// note | Détails techniques
+
+La spécification OpenAPI appelle ces métadonnées des Objets d'opération.
+
+///
Il contient toutes les informations sur le *chemin* et est utilisé pour générer automatiquement la documentation.
@@ -74,8 +78,11 @@ Il inclut les `tags`, `parameters`, `requestBody`, `responses`, etc.
Ce schéma OpenAPI spécifique aux *operations* est normalement généré automatiquement par **FastAPI**, mais vous pouvez également l'étendre.
-!!! tip "Astuce"
- Si vous avez seulement besoin de déclarer des réponses supplémentaires, un moyen plus pratique de le faire est d'utiliser les [réponses supplémentaires dans OpenAPI](additional-responses.md){.internal-link target=_blank}.
+/// tip | Astuce
+
+Si vous avez seulement besoin de déclarer des réponses supplémentaires, un moyen plus pratique de le faire est d'utiliser les [réponses supplémentaires dans OpenAPI](additional-responses.md){.internal-link target=_blank}.
+
+///
Vous pouvez étendre le schéma OpenAPI pour une *opération de chemin* en utilisant le paramètre `openapi_extra`.
@@ -83,9 +90,7 @@ Vous pouvez étendre le schéma OpenAPI pour une *opération de chemin* en utili
Cet `openapi_extra` peut être utile, par exemple, pour déclarer [OpenAPI Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions) :
-```Python hl_lines="6"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial005.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial005.py hl[6] *}
Si vous ouvrez la documentation automatique de l'API, votre extension apparaîtra au bas du *chemin* spécifique.
@@ -132,9 +137,7 @@ Par exemple, vous pouvez décider de lire et de valider la requête avec votre p
Vous pouvez le faire avec `openapi_extra` :
-```Python hl_lines="20-37 39-40"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial006.py !}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial006.py hl[20:37,39:40] *}
Dans cet exemple, nous n'avons déclaré aucun modèle Pydantic. En fait, le corps de la requête n'est même pas parsé en tant que JSON, il est lu directement en tant que `bytes`, et la fonction `magic_data_reader()` serait chargé de l'analyser d'une manière ou d'une autre.
@@ -148,9 +151,7 @@ Et vous pouvez le faire même si le type de données dans la requête n'est pas
Dans cet exemple, nous n'utilisons pas les fonctionnalités de FastAPI pour extraire le schéma JSON des modèles Pydantic ni la validation automatique pour JSON. En fait, nous déclarons le type de contenu de la requête en tant que YAML, et non JSON :
-```Python hl_lines="17-22 24"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial007.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[17:22,24] *}
Néanmoins, bien que nous n'utilisions pas la fonctionnalité par défaut, nous utilisons toujours un modèle Pydantic pour générer manuellement le schéma JSON pour les données que nous souhaitons recevoir en YAML.
@@ -158,11 +159,12 @@ Ensuite, nous utilisons directement la requête et extrayons son contenu en tant
Et nous analysons directement ce contenu YAML, puis nous utilisons à nouveau le même modèle Pydantic pour valider le contenu YAML :
-```Python hl_lines="26-33"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial007.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[26:33] *}
-!!! tip "Astuce"
- Ici, nous réutilisons le même modèle Pydantic.
+/// tip | Astuce
- Mais nous aurions pu tout aussi bien pu le valider d'une autre manière.
+Ici, nous réutilisons le même modèle Pydantic.
+
+Mais nous aurions pu tout aussi bien pu le valider d'une autre manière.
+
+///
diff --git a/docs/fr/docs/advanced/response-directly.md b/docs/fr/docs/advanced/response-directly.md
index ed29446d4..4ff883c77 100644
--- a/docs/fr/docs/advanced/response-directly.md
+++ b/docs/fr/docs/advanced/response-directly.md
@@ -14,8 +14,11 @@ Cela peut être utile, par exemple, pour retourner des en-têtes personnalisés
En fait, vous pouvez retourner n'importe quelle `Response` ou n'importe quelle sous-classe de celle-ci.
-!!! note "Remarque"
- `JSONResponse` est elle-même une sous-classe de `Response`.
+/// note | Remarque
+
+`JSONResponse` est elle-même une sous-classe de `Response`.
+
+///
Et quand vous retournez une `Response`, **FastAPI** la transmet directement.
@@ -31,14 +34,15 @@ Par exemple, vous ne pouvez pas mettre un modèle Pydantic dans une `JSONRespons
Pour ces cas, vous pouvez spécifier un appel à `jsonable_encoder` pour convertir vos données avant de les passer à une réponse :
-```Python hl_lines="6-7 21-22"
-{!../../../docs_src/response_directly/tutorial001.py!}
-```
+{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *}
-!!! note "Détails techniques"
- Vous pouvez aussi utiliser `from starlette.responses import JSONResponse`.
+/// note | Détails techniques
- **FastAPI** fournit le même objet `starlette.responses` que `fastapi.responses` juste par commodité pour le développeur. Mais la plupart des réponses disponibles proviennent directement de Starlette.
+Vous pouvez aussi utiliser `from starlette.responses import JSONResponse`.
+
+**FastAPI** fournit le même objet `starlette.responses` que `fastapi.responses` juste par commodité pour le développeur. Mais la plupart des réponses disponibles proviennent directement de Starlette.
+
+///
## Renvoyer une `Response` personnalisée
@@ -50,9 +54,7 @@ Disons que vous voulez retourner une réponse Flask
Flask est un "micro-framework", il ne comprend pas d'intégrations de bases de données ni beaucoup de choses qui sont fournies par défaut dans Django.
@@ -59,11 +65,14 @@ qui est nécessaire, était une caractéristique clé que je voulais conserver.
Compte tenu de la simplicité de Flask, il semblait bien adapté à la création d'API. La prochaine chose à trouver était un "Django REST Framework" pour Flask.
-!!! check "A inspiré **FastAPI** à"
+/// check | A inspiré **FastAPI** à
+
Être un micro-framework. Il est donc facile de combiner les outils et les pièces nécessaires.
Proposer un système de routage simple et facile à utiliser.
+///
+
### Requests
**FastAPI** n'est pas réellement une alternative à **Requests**. Leur cadre est très différent.
@@ -98,9 +107,13 @@ def read_url():
Notez les similitudes entre `requests.get(...)` et `@app.get(...)`.
-!!! check "A inspiré **FastAPI** à"
-_ Avoir une API simple et intuitive.
-_ Utiliser les noms de méthodes HTTP (opérations) directement, de manière simple et intuitive. \* Avoir des valeurs par défaut raisonnables, mais des personnalisations puissantes.
+/// check | A inspiré **FastAPI** à
+
+Avoir une API simple et intuitive.
+
+Utiliser les noms de méthodes HTTP (opérations) directement, de manière simple et intuitive. \* Avoir des valeurs par défaut raisonnables, mais des personnalisations puissantes.
+
+///
### Swagger / OpenAPI
@@ -115,15 +128,18 @@ Swagger pour une API permettrait d'utiliser cette interface utilisateur web auto
C'est pourquoi, lorsqu'on parle de la version 2.0, il est courant de dire "Swagger", et pour la version 3+ "OpenAPI".
-!!! check "A inspiré **FastAPI** à"
+/// check | A inspiré **FastAPI** à
+
Adopter et utiliser une norme ouverte pour les spécifications des API, au lieu d'un schéma personnalisé.
- Intégrer des outils d'interface utilisateur basés sur des normes :
+Intégrer des outils d'interface utilisateur basés sur des normes :
- * Swagger UI
- * ReDoc
+* Swagger UI
+* ReDoc
- Ces deux-là ont été choisis parce qu'ils sont populaires et stables, mais en faisant une recherche rapide, vous pourriez trouver des dizaines d'alternatives supplémentaires pour OpenAPI (que vous pouvez utiliser avec **FastAPI**).
+Ces deux-là ont été choisis parce qu'ils sont populaires et stables, mais en faisant une recherche rapide, vous pourriez trouver des dizaines d'alternatives supplémentaires pour OpenAPI (que vous pouvez utiliser avec **FastAPI**).
+
+///
### Frameworks REST pour Flask
@@ -150,9 +166,12 @@ Ces fonctionnalités sont ce pourquoi Marshmallow a été construit. C'est une e
Mais elle a été créée avant que les type hints n'existent en Python. Ainsi, pour définir chaque schéma, vous devez utiliser des utilitaires et des classes spécifiques fournies par Marshmallow.
-!!! check "A inspiré **FastAPI** à"
+/// check | A inspiré **FastAPI** à
+
Utilisez du code pour définir des "schémas" qui fournissent automatiquement les types de données et la validation.
+///
+
### Webargs
Une autre grande fonctionnalité requise par les API est le APISpec
Marshmallow et Webargs fournissent la validation, l'analyse et la sérialisation en tant que plug-ins.
@@ -188,12 +213,18 @@ Mais alors, nous avons à nouveau le problème d'avoir une micro-syntaxe, dans u
L'éditeur ne peut guère aider en la matière. Et si nous modifions les paramètres ou les schémas Marshmallow et que nous oublions de modifier également cette docstring YAML, le schéma généré deviendrait obsolète.
-!!! info
+/// info
+
APISpec a été créé par les développeurs de Marshmallow.
-!!! check "A inspiré **FastAPI** à"
+///
+
+/// check | A inspiré **FastAPI** à
+
Supporter la norme ouverte pour les API, OpenAPI.
+///
+
### Flask-apispec
C'est un plug-in pour Flask, qui relie Webargs, Marshmallow et APISpec.
@@ -215,12 +246,18 @@ j'ai (ainsi que plusieurs équipes externes) utilisées jusqu'à présent :
Ces mêmes générateurs full-stack ont servi de base aux [Générateurs de projets pour **FastAPI**](project-generation.md){.internal-link target=\_blank}.
-!!! info
+/// info
+
Flask-apispec a été créé par les développeurs de Marshmallow.
-!!! check "A inspiré **FastAPI** à"
+///
+
+/// check | A inspiré **FastAPI** à
+
Générer le schéma OpenAPI automatiquement, à partir du même code qui définit la sérialisation et la validation.
+///
+
### NestJS (et Angular)
Ce n'est même pas du Python, NestJS est un framework JavaScript (TypeScript) NodeJS inspiré d'Angular.
@@ -236,24 +273,33 @@ Mais comme les données TypeScript ne sont pas préservées après la compilatio
Il ne peut pas très bien gérer les modèles imbriqués. Ainsi, si le corps JSON de la requête est un objet JSON comportant des champs internes qui sont à leur tour des objets JSON imbriqués, il ne peut pas être correctement documenté et validé.
-!!! check "A inspiré **FastAPI** à"
+/// check | A inspiré **FastAPI** à
+
Utiliser les types Python pour bénéficier d'un excellent support de l'éditeur.
- Disposer d'un puissant système d'injection de dépendances. Trouver un moyen de minimiser la répétition du code.
+Disposer d'un puissant système d'injection de dépendances. Trouver un moyen de minimiser la répétition du code.
+
+///
### Sanic
C'était l'un des premiers frameworks Python extrêmement rapides basés sur `asyncio`. Il a été conçu pour être très similaire à Flask.
-!!! note "Détails techniques"
+/// note | Détails techniques
+
Il utilisait `uvloop` au lieu du système par défaut de Python `asyncio`. C'est ce qui l'a rendu si rapide.
- Il a clairement inspiré Uvicorn et Starlette, qui sont actuellement plus rapides que Sanic dans les benchmarks.
+Il a clairement inspiré Uvicorn et Starlette, qui sont actuellement plus rapides que Sanic dans les benchmarks.
+
+///
+
+/// check | A inspiré **FastAPI** à
-!!! check "A inspiré **FastAPI** à"
Trouvez un moyen d'avoir une performance folle.
- C'est pourquoi **FastAPI** est basé sur Starlette, car il s'agit du framework le plus rapide disponible (testé par des benchmarks tiers).
+C'est pourquoi **FastAPI** est basé sur Starlette, car il s'agit du framework le plus rapide disponible (testé par des benchmarks tiers).
+
+///
### Falcon
@@ -267,12 +313,15 @@ pas possible de déclarer des paramètres de requête et des corps avec des indi
Ainsi, la validation, la sérialisation et la documentation des données doivent être effectuées dans le code, et non pas automatiquement. Ou bien elles doivent être implémentées comme un framework au-dessus de Falcon, comme Hug. Cette même distinction se retrouve dans d'autres frameworks qui s'inspirent de la conception de Falcon, qui consiste à avoir un objet de requête et un objet de réponse comme paramètres.
-!!! check "A inspiré **FastAPI** à"
+/// check | A inspiré **FastAPI** à
+
Trouver des moyens d'obtenir de bonnes performances.
- Avec Hug (puisque Hug est basé sur Falcon), **FastAPI** a inspiré la déclaration d'un paramètre `response` dans les fonctions.
+Avec Hug (puisque Hug est basé sur Falcon), **FastAPI** a inspiré la déclaration d'un paramètre `response` dans les fonctions.
- Bien que dans FastAPI, il est facultatif, et est utilisé principalement pour définir les en-têtes, les cookies, et les codes de statut alternatifs.
+Bien que dans FastAPI, il est facultatif, et est utilisé principalement pour définir les en-têtes, les cookies, et les codes de statut alternatifs.
+
+///
### Molten
@@ -294,12 +343,15 @@ d'utiliser des décorateurs qui peuvent être placés juste au-dessus de la fonc
méthode est plus proche de celle de Django que de celle de Flask (et Starlette). Il sépare dans le code des choses
qui sont relativement fortement couplées.
-!!! check "A inspiré **FastAPI** à"
+/// check | A inspiré **FastAPI** à
+
Définir des validations supplémentaires pour les types de données utilisant la valeur "par défaut" des attributs du modèle. Ceci améliore le support de l'éditeur, et n'était pas disponible dans Pydantic auparavant.
- Cela a en fait inspiré la mise à jour de certaines parties de Pydantic, afin de supporter le même style de déclaration de validation (toute cette fonctionnalité est maintenant déjà disponible dans Pydantic).
+Cela a en fait inspiré la mise à jour de certaines parties de Pydantic, afin de supporter le même style de déclaration de validation (toute cette fonctionnalité est maintenant déjà disponible dans Pydantic).
-### Hug
+///
+
+### Hug
Hug a été l'un des premiers frameworks à implémenter la déclaration des types de paramètres d'API en utilisant les type hints Python. C'était une excellente idée qui a inspiré d'autres outils à faire de même.
@@ -314,16 +366,22 @@ API et des CLI.
Comme il est basé sur l'ancienne norme pour les frameworks web Python synchrones (WSGI), il ne peut pas gérer les Websockets et autres, bien qu'il soit également très performant.
-!!! info
+/// info
+
Hug a été créé par Timothy Crosley, le créateur de `isort`, un excellent outil pour trier automatiquement les imports dans les fichiers Python.
-!!! check "A inspiré **FastAPI** à"
+///
+
+/// check | A inspiré **FastAPI** à
+
Hug a inspiré certaines parties d'APIStar, et était l'un des outils que je trouvais les plus prometteurs, à côté d'APIStar.
- Hug a contribué à inspirer **FastAPI** pour utiliser les type hints Python
- pour déclarer les paramètres, et pour générer automatiquement un schéma définissant l'API.
+Hug a contribué à inspirer **FastAPI** pour utiliser les type hints Python
+pour déclarer les paramètres, et pour générer automatiquement un schéma définissant l'API.
- Hug a inspiré **FastAPI** pour déclarer un paramètre `response` dans les fonctions pour définir les en-têtes et les cookies.
+Hug a inspiré **FastAPI** pour déclarer un paramètre `response` dans les fonctions pour définir les en-têtes et les cookies.
+
+///
### APIStar (<= 0.5)
@@ -351,23 +409,29 @@ Il ne s'agissait plus d'un framework web API, le créateur devant se concentrer
Maintenant, APIStar est un ensemble d'outils pour valider les spécifications OpenAPI, et non un framework web.
-!!! info
+/// info
+
APIStar a été créé par Tom Christie. Le même gars qui a créé :
- * Django REST Framework
- * Starlette (sur lequel **FastAPI** est basé)
- * Uvicorn (utilisé par Starlette et **FastAPI**)
+* Django REST Framework
+* Starlette (sur lequel **FastAPI** est basé)
+* Uvicorn (utilisé par Starlette et **FastAPI**)
+
+///
+
+/// check | A inspiré **FastAPI** à
-!!! check "A inspiré **FastAPI** à"
Exister.
- L'idée de déclarer plusieurs choses (validation des données, sérialisation et documentation) avec les mêmes types Python, tout en offrant un excellent support pour les éditeurs, était pour moi une idée brillante.
+L'idée de déclarer plusieurs choses (validation des données, sérialisation et documentation) avec les mêmes types Python, tout en offrant un excellent support pour les éditeurs, était pour moi une idée brillante.
- Et après avoir longtemps cherché un framework similaire et testé de nombreuses alternatives, APIStar était la meilleure option disponible.
+Et après avoir longtemps cherché un framework similaire et testé de nombreuses alternatives, APIStar était la meilleure option disponible.
- Puis APIStar a cessé d'exister en tant que serveur et Starlette a été créé, et a constitué une meilleure base pour un tel système. Ce fut l'inspiration finale pour construire **FastAPI**.
+Puis APIStar a cessé d'exister en tant que serveur et Starlette a été créé, et a constitué une meilleure base pour un tel système. Ce fut l'inspiration finale pour construire **FastAPI**.
- Je considère **FastAPI** comme un "successeur spirituel" d'APIStar, tout en améliorant et en augmentant les fonctionnalités, le système de typage et d'autres parties, sur la base des enseignements tirés de tous ces outils précédents.
+Je considère **FastAPI** comme un "successeur spirituel" d'APIStar, tout en améliorant et en augmentant les fonctionnalités, le système de typage et d'autres parties, sur la base des enseignements tirés de tous ces outils précédents.
+
+///
## Utilisés par **FastAPI**
@@ -380,10 +444,13 @@ Cela le rend extrêmement intuitif.
Il est comparable à Marshmallow. Bien qu'il soit plus rapide que Marshmallow dans les benchmarks. Et comme il est
basé sur les mêmes type hints Python, le support de l'éditeur est grand.
-!!! check "**FastAPI** l'utilise pour"
+/// check | **FastAPI** l'utilise pour
+
Gérer toute la validation des données, leur sérialisation et la documentation automatique du modèle (basée sur le schéma JSON).
- **FastAPI** prend ensuite ces données JSON Schema et les place dans OpenAPI, en plus de toutes les autres choses qu'il fait.
+**FastAPI** prend ensuite ces données JSON Schema et les place dans OpenAPI, en plus de toutes les autres choses qu'il fait.
+
+///
### Starlette
@@ -413,17 +480,23 @@ Mais il ne fournit pas de validation automatique des données, de sérialisation
C'est l'une des principales choses que **FastAPI** ajoute par-dessus, le tout basé sur les type hints Python (en utilisant Pydantic). Cela, plus le système d'injection de dépendances, les utilitaires de sécurité, la génération de schémas OpenAPI, etc.
-!!! note "Détails techniques"
+/// note | Détails techniques
+
ASGI est une nouvelle "norme" développée par les membres de l'équipe principale de Django. Il ne s'agit pas encore d'une "norme Python" (un PEP), bien qu'ils soient en train de le faire.
- Néanmoins, il est déjà utilisé comme "standard" par plusieurs outils. Cela améliore grandement l'interopérabilité, puisque vous pouvez remplacer Uvicorn par n'importe quel autre serveur ASGI (comme Daphne ou Hypercorn), ou vous pouvez ajouter des outils compatibles ASGI, comme `python-socketio`.
+Néanmoins, il est déjà utilisé comme "standard" par plusieurs outils. Cela améliore grandement l'interopérabilité, puisque vous pouvez remplacer Uvicorn par n'importe quel autre serveur ASGI (comme Daphne ou Hypercorn), ou vous pouvez ajouter des outils compatibles ASGI, comme `python-socketio`.
+
+///
+
+/// check | **FastAPI** l'utilise pour
-!!! check "**FastAPI** l'utilise pour"
Gérer toutes les parties web de base. Ajouter des fonctionnalités par-dessus.
- La classe `FastAPI` elle-même hérite directement de la classe `Starlette`.
+La classe `FastAPI` elle-même hérite directement de la classe `Starlette`.
- Ainsi, tout ce que vous pouvez faire avec Starlette, vous pouvez le faire directement avec **FastAPI**, car il s'agit en fait de Starlette sous stéroïdes.
+Ainsi, tout ce que vous pouvez faire avec Starlette, vous pouvez le faire directement avec **FastAPI**, car il s'agit en fait de Starlette sous stéroïdes.
+
+///
### Uvicorn
@@ -434,12 +507,15 @@ quelque chose qu'un framework comme Starlette (ou **FastAPI**) fournirait par-de
C'est le serveur recommandé pour Starlette et **FastAPI**.
-!!! check "**FastAPI** le recommande comme"
+/// check | **FastAPI** le recommande comme
+
Le serveur web principal pour exécuter les applications **FastAPI**.
- Vous pouvez le combiner avec Gunicorn, pour avoir un serveur multi-processus asynchrone.
+Vous pouvez le combiner avec Gunicorn, pour avoir un serveur multi-processus asynchrone.
- Pour plus de détails, consultez la section [Déploiement](deployment/index.md){.internal-link target=_blank}.
+Pour plus de détails, consultez la section [Déploiement](deployment/index.md){.internal-link target=_blank}.
+
+///
## Benchmarks et vitesse
diff --git a/docs/fr/docs/async.md b/docs/fr/docs/async.md
index eabd9686a..0ff5fa5d1 100644
--- a/docs/fr/docs/async.md
+++ b/docs/fr/docs/async.md
@@ -20,8 +20,11 @@ async def read_results():
return results
```
-!!! note
- Vous pouvez uniquement utiliser `await` dans les fonctions créées avec `async def`.
+/// note
+
+Vous pouvez uniquement utiliser `await` dans les fonctions créées avec `async def`.
+
+///
---
@@ -135,8 +138,11 @@ Vous et votre crush 😍 mangez les burgers 🍔 et passez un bon moment ✨.
-!!! info
- Illustrations proposées par Ketrina Thompson. 🎨
+/// info
+
+Illustrations proposées par Ketrina Thompson. 🎨
+
+///
---
@@ -198,8 +204,11 @@ Vous les mangez, et vous avez terminé 🍔 ⏹.
Durant tout ce processus, il n'y a presque pas eu de discussions ou de flirts car la plupart de votre temps à été passé à attendre 🕙 devant le comptoir 😞.
-!!! info
- Illustrations proposées par Ketrina Thompson. 🎨
+/// info
+
+Illustrations proposées par Ketrina Thompson. 🎨
+
+///
---
@@ -384,12 +393,15 @@ Tout ceci est donc ce qui donne sa force à **FastAPI** (à travers Starlette) e
## Détails très techniques
-!!! warning "Attention !"
- Vous pouvez probablement ignorer cela.
+/// warning | Attention !
- Ce sont des détails très poussés sur comment **FastAPI** fonctionne en arrière-plan.
+Vous pouvez probablement ignorer cela.
- Si vous avez de bonnes connaissances techniques (coroutines, threads, code bloquant, etc.) et êtes curieux de comment **FastAPI** gère `async def` versus le `def` classique, cette partie est faite pour vous.
+Ce sont des détails très poussés sur comment **FastAPI** fonctionne en arrière-plan.
+
+Si vous avez de bonnes connaissances techniques (coroutines, threads, code bloquant, etc.) et êtes curieux de comment **FastAPI** gère `async def` versus le `def` classique, cette partie est faite pour vous.
+
+///
### Fonctions de chemin
diff --git a/docs/fr/docs/contributing.md b/docs/fr/docs/contributing.md
deleted file mode 100644
index ed4d32f5a..000000000
--- a/docs/fr/docs/contributing.md
+++ /dev/null
@@ -1,501 +0,0 @@
-# Développement - Contribuer
-
-Tout d'abord, vous voudrez peut-être voir les moyens de base pour [aider FastAPI et obtenir de l'aide](help-fastapi.md){.internal-link target=_blank}.
-
-## Développement
-
-Si vous avez déjà cloné le dépôt et que vous savez que vous devez vous plonger dans le code, voici quelques directives pour mettre en place votre environnement.
-
-### Environnement virtuel avec `venv`
-
-Vous pouvez créer un environnement virtuel dans un répertoire en utilisant le module `venv` de Python :
-
-
-{% endfor %}
-{% endif %}
-
-{% if sponsors.silver %}
-
-### Silver Sponsors
-
-{% for sponsor in sponsors.silver -%}
-
-{% endfor %}
-{% endif %}
-
-{% if sponsors.bronze %}
-
-### Bronze Sponsors
-
-{% for sponsor in sponsors.bronze -%}
-
-{% endfor %}
-{% endif %}
-
-{% endif %}
-### Individual Sponsors
-
-{% if github_sponsors %}
-{% for group in github_sponsors.sponsors %}
-
-
-
+
@@ -93,7 +93,7 @@ Les principales fonctionnalités sont :
"_Honnêtement, ce que vous avez construit a l'air super solide et élégant. A bien des égards, c'est comme ça que je voulais que **Hug** soit - c'est vraiment inspirant de voir quelqu'un construire ça._"
-
+
---
@@ -449,7 +449,7 @@ Pour en savoir plus, consultez la section
email_validator - pour la validation des adresses email.
+* email-validator - pour la validation des adresses email.
Utilisées par Starlette :
diff --git a/docs/fr/docs/python-types.md b/docs/fr/docs/python-types.md
index 4232633e3..99ca90827 100644
--- a/docs/fr/docs/python-types.md
+++ b/docs/fr/docs/python-types.md
@@ -13,16 +13,17 @@ Seulement le minimum nécessaire pour les utiliser avec **FastAPI** sera couvert
Mais même si vous n'utilisez pas ou n'utiliserez jamais **FastAPI**, vous pourriez bénéficier d'apprendre quelques choses sur ces dernières.
-!!! note
- Si vous êtes un expert Python, et que vous savez déjà **tout** sur les annotations de type, passez au chapitre suivant.
+/// note
+
+Si vous êtes un expert Python, et que vous savez déjà **tout** sur les annotations de type, passez au chapitre suivant.
+
+///
## Motivations
Prenons un exemple simple :
-```Python
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{*../../docs_src/python_types/tutorial001.py*}
Exécuter ce programe affiche :
@@ -36,9 +37,7 @@ La fonction :
* Convertit la première lettre de chaque paramètre en majuscules grâce à `title()`.
* Concatène les résultats avec un espace entre les deux.
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{*../../docs_src/python_types/tutorial001.py hl[2] *}
### Limitations
@@ -81,9 +80,7 @@ C'est tout.
Ce sont des annotations de types :
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial002.py!}
-```
+{*../../docs_src/python_types/tutorial002.py hl[1] *}
À ne pas confondre avec la déclaration de valeurs par défaut comme ici :
@@ -111,9 +108,7 @@ Vous pouvez donc dérouler les options jusqu'à trouver la méthode à laquelle
Cette fonction possède déjà des annotations de type :
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial003.py!}
-```
+{*../../docs_src/python_types/tutorial003.py hl[1] *}
Comme l'éditeur connaît le type des variables, vous n'avez pas seulement l'auto-complétion, mais aussi de la détection d'erreurs :
@@ -121,9 +116,7 @@ Comme l'éditeur connaît le type des variables, vous n'avez pas seulement l'aut
Maintenant que vous avez connaissance du problème, convertissez `age` en chaîne de caractères grâce à `str(age)` :
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial004.py!}
-```
+{*../../docs_src/python_types/tutorial004.py hl[2] *}
## Déclarer des types
@@ -142,9 +135,7 @@ Comme par exemple :
* `bool`
* `bytes`
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial005.py!}
-```
+{*../../docs_src/python_types/tutorial005.py hl[1] *}
### Types génériques avec des paramètres de types
@@ -160,9 +151,7 @@ Par exemple, définissons une variable comme `list` de `str`.
Importez `List` (avec un `L` majuscule) depuis `typing`.
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial006.py!}
-```
+{*../../docs_src/python_types/tutorial006.py hl[1] *}
Déclarez la variable, en utilisant la syntaxe des deux-points (`:`).
@@ -170,14 +159,15 @@ Et comme type, mettez `List`.
Les listes étant un type contenant des types internes, mettez ces derniers entre crochets (`[`, `]`) :
-```Python hl_lines="4"
-{!../../../docs_src/python_types/tutorial006.py!}
-```
+{*../../docs_src/python_types/tutorial006.py hl[4] *}
-!!! tip "Astuce"
- Ces types internes entre crochets sont appelés des "paramètres de type".
+/// tip | Astuce
- Ici, `str` est un paramètre de type passé à `List`.
+Ces types internes entre crochets sont appelés des "paramètres de type".
+
+Ici, `str` est un paramètre de type passé à `List`.
+
+///
Ce qui signifie : "la variable `items` est une `list`, et chacun de ses éléments a pour type `str`.
@@ -195,9 +185,7 @@ Et pourtant, l'éditeur sait qu'elle est de type `str` et pourra donc vous aider
C'est le même fonctionnement pour déclarer un `tuple` ou un `set` :
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial007.py!}
-```
+{*../../docs_src/python_types/tutorial007.py hl[1,4] *}
Dans cet exemple :
@@ -210,9 +198,7 @@ Pour définir un `dict`, il faut lui passer 2 paramètres, séparés par une vir
Le premier paramètre de type est pour les clés et le second pour les valeurs du dictionnaire (`dict`).
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial008.py!}
-```
+{*../../docs_src/python_types/tutorial008.py hl[1,4] *}
Dans cet exemple :
@@ -224,9 +210,7 @@ Dans cet exemple :
Vous pouvez aussi utiliser `Optional` pour déclarer qu'une variable a un type, comme `str` mais qu'il est "optionnel" signifiant qu'il pourrait aussi être `None`.
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial009.py!}
-```
+{*../../docs_src/python_types/tutorial009.py hl[1,4] *}
Utiliser `Optional[str]` plutôt que `str` permettra à l'éditeur de vous aider à détecter les erreurs où vous supposeriez qu'une valeur est toujours de type `str`, alors qu'elle pourrait aussi être `None`.
@@ -249,15 +233,12 @@ Vous pouvez aussi déclarer une classe comme type d'une variable.
Disons que vous avez une classe `Person`, avec une variable `name` :
-```Python hl_lines="1-3"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{*../../docs_src/python_types/tutorial010.py hl[1:3] *}
+
Vous pouvez ensuite déclarer une variable de type `Person` :
-```Python hl_lines="6"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{*../../docs_src/python_types/tutorial010.py hl[6] *}
Et vous aurez accès, encore une fois, au support complet offert par l'éditeur :
@@ -277,12 +258,13 @@ Ainsi, votre éditeur vous offrira un support adapté pour l'objet résultant.
Extrait de la documentation officielle de **Pydantic** :
-```Python
-{!../../../docs_src/python_types/tutorial011.py!}
-```
+{*../../docs_src/python_types/tutorial011.py*}
-!!! info
- Pour en savoir plus à propos de Pydantic, allez jeter un coup d'oeil à sa documentation.
+/// info
+
+Pour en savoir plus à propos de Pydantic, allez jeter un coup d'oeil à sa documentation.
+
+///
**FastAPI** est basé entièrement sur **Pydantic**.
@@ -310,5 +292,8 @@ Tout cela peut paraître bien abstrait, mais ne vous inquiétez pas, vous verrez
Ce qu'il faut retenir c'est qu'en utilisant les types standard de Python, à un seul endroit (plutôt que d'ajouter plus de classes, de décorateurs, etc.), **FastAPI** fera une grande partie du travail pour vous.
-!!! info
- Si vous avez déjà lu le tutoriel et êtes revenus ici pour voir plus sur les types, une bonne ressource est la "cheat sheet" de `mypy`.
+/// info
+
+Si vous avez déjà lu le tutoriel et êtes revenus ici pour voir plus sur les types, une bonne ressource est la "cheat sheet" de `mypy`.
+
+///
diff --git a/docs/fr/docs/tutorial/background-tasks.md b/docs/fr/docs/tutorial/background-tasks.md
index f7cf1a6cc..2065ca58e 100644
--- a/docs/fr/docs/tutorial/background-tasks.md
+++ b/docs/fr/docs/tutorial/background-tasks.md
@@ -16,9 +16,7 @@ Cela comprend, par exemple :
Pour commencer, importez `BackgroundTasks` et définissez un paramètre dans votre *fonction de chemin* avec `BackgroundTasks` comme type déclaré.
-```Python hl_lines="1 13"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *}
**FastAPI** créera l'objet de type `BackgroundTasks` pour vous et le passera comme paramètre.
@@ -32,18 +30,14 @@ Dans cet exemple, la fonction de tâche écrira dans un fichier (afin de simuler
L'opération d'écriture n'utilisant ni `async` ni `await`, on définit la fonction avec un `def` normal.
-```Python hl_lines="6-9"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *}
## Ajouter une tâche d'arrière-plan
Dans votre *fonction de chemin*, passez votre fonction de tâche à l'objet de type `BackgroundTasks` (`background_tasks` ici) grâce à la méthode `.add_task()` :
-```Python hl_lines="14"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[14] *}
`.add_task()` reçoit comme arguments :
@@ -57,9 +51,7 @@ Utiliser `BackgroundTasks` fonctionne aussi avec le système d'injection de dép
**FastAPI** sait quoi faire dans chaque cas et comment réutiliser le même objet, afin que tous les paramètres de type `BackgroundTasks` soient fusionnés et que les tâches soient exécutées en arrière-plan :
-```Python hl_lines="13 15 22 25"
-{!../../../docs_src/background_tasks/tutorial002.py!}
-```
+{* ../../docs_src/background_tasks/tutorial002.py hl[13,15,22,25] *}
Dans cet exemple, les messages seront écrits dans le fichier `log.txt` après que la réponse soit envoyée.
@@ -85,8 +77,6 @@ Si vous avez besoin de réaliser des traitements lourds en tâche d'arrière-pla
Ces outils nécessitent généralement des configurations plus complexes ainsi qu'un gestionnaire de queue de message, comme RabbitMQ ou Redis, mais ils permettent d'exécuter des tâches d'arrière-plan dans différents process, et potentiellement, sur plusieurs serveurs.
-Pour voir un exemple, allez voir les [Générateurs de projets](../project-generation.md){.internal-link target=_blank}, ils incluent tous Celery déjà configuré.
-
Mais si vous avez besoin d'accéder aux variables et objets de la même application **FastAPI**, ou si vous avez besoin d'effectuer de petites tâches d'arrière-plan (comme envoyer des notifications par email), vous pouvez simplement vous contenter d'utiliser `BackgroundTasks`.
## Résumé
diff --git a/docs/fr/docs/tutorial/body-multiple-params.md b/docs/fr/docs/tutorial/body-multiple-params.md
new file mode 100644
index 000000000..0541acc74
--- /dev/null
+++ b/docs/fr/docs/tutorial/body-multiple-params.md
@@ -0,0 +1,171 @@
+# Body - Paramètres multiples
+
+Maintenant que nous avons vu comment manipuler `Path` et `Query`, voyons comment faire pour le corps d'une requête, communément désigné par le terme anglais "body".
+
+## Mélanger les paramètres `Path`, `Query` et body
+
+Tout d'abord, sachez que vous pouvez mélanger les déclarations des paramètres `Path`, `Query` et body, **FastAPI** saura quoi faire.
+
+Vous pouvez également déclarer des paramètres body comme étant optionnels, en leur assignant une valeur par défaut à `None` :
+
+{* ../../docs_src/body_multiple_params/tutorial001_an_py310.py hl[18:20] *}
+
+/// note
+
+Notez que, dans ce cas, le paramètre `item` provenant du `Body` est optionnel (sa valeur par défaut est `None`).
+
+///
+
+## Paramètres multiples du body
+
+Dans l'exemple précédent, les opérations de routage attendaient un body JSON avec les attributs d'un `Item`, par exemple :
+
+```JSON
+{
+ "name": "Foo",
+ "description": "The pretender",
+ "price": 42.0,
+ "tax": 3.2
+}
+```
+
+Mais vous pouvez également déclarer plusieurs paramètres provenant de body, par exemple `item` et `user` simultanément :
+
+{* ../../docs_src/body_multiple_params/tutorial002_py310.py hl[20] *}
+
+Dans ce cas, **FastAPI** détectera qu'il y a plus d'un paramètre dans le body (chacun correspondant à un modèle Pydantic).
+
+Il utilisera alors les noms des paramètres comme clés, et s'attendra à recevoir quelque chose de semblable à :
+
+```JSON
+{
+ "item": {
+ "name": "Foo",
+ "description": "The pretender",
+ "price": 42.0,
+ "tax": 3.2
+ },
+ "user": {
+ "username": "dave",
+ "full_name": "Dave Grohl"
+ }
+}
+```
+
+/// note
+
+"Notez que, bien que nous ayons déclaré le paramètre `item` de la même manière que précédemment, il est maintenant associé à la clé `item` dans le corps de la requête."`.
+
+///
+
+**FastAPI** effectue la conversion de la requête de façon transparente, de sorte que les objets `item` et `user` se trouvent correctement définis.
+
+Il effectue également la validation des données (même imbriquées les unes dans les autres), et permet de les documenter correctement (schéma OpenAPI et documentation auto-générée).
+
+## Valeurs scalaires dans le body
+
+De la même façon qu'il existe `Query` et `Path` pour définir des données supplémentaires pour les paramètres query et path, **FastAPI** fournit un équivalent `Body`.
+
+Par exemple, en étendant le modèle précédent, vous pouvez vouloir ajouter un paramètre `importance` dans le même body, en plus des paramètres `item` et `user`.
+
+Si vous le déclarez tel quel, comme c'est une valeur [scalaire](https://docs.github.com/fr/graphql/reference/scalars), **FastAPI** supposera qu'il s'agit d'un paramètre de requête (`Query`).
+
+Mais vous pouvez indiquer à **FastAPI** de la traiter comme une variable de body en utilisant `Body` :
+
+{* ../../docs_src/body_multiple_params/tutorial003_an_py310.py hl[23] *}
+
+Dans ce cas, **FastAPI** s'attendra à un body semblable à :
+
+```JSON
+{
+ "item": {
+ "name": "Foo",
+ "description": "The pretender",
+ "price": 42.0,
+ "tax": 3.2
+ },
+ "user": {
+ "username": "dave",
+ "full_name": "Dave Grohl"
+ },
+ "importance": 5
+}
+```
+
+Encore une fois, cela convertira les types de données, les validera, permettra de générer la documentation, etc...
+
+## Paramètres multiples body et query
+
+Bien entendu, vous pouvez déclarer autant de paramètres que vous le souhaitez, en plus des paramètres body déjà déclarés.
+
+Par défaut, les valeurs [scalaires](https://docs.github.com/fr/graphql/reference/scalars) sont interprétées comme des paramètres query, donc inutile d'ajouter explicitement `Query`. Vous pouvez juste écrire :
+
+```Python
+q: Union[str, None] = None
+```
+
+Ou bien, en Python 3.10 et supérieur :
+
+```Python
+q: str | None = None
+```
+
+Par exemple :
+
+{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[27] *}
+
+/// info
+
+`Body` possède les mêmes paramètres de validation additionnels et de gestion des métadonnées que `Query` et `Path`, ainsi que d'autres que nous verrons plus tard.
+
+///
+
+## Inclure un paramètre imbriqué dans le body
+
+Disons que vous avez seulement un paramètre `item` dans le body, correspondant à un modèle Pydantic `Item`.
+
+Par défaut, **FastAPI** attendra sa déclaration directement dans le body.
+
+Cependant, si vous souhaitez qu'il interprête correctement un JSON avec une clé `item` associée au contenu du modèle, comme cela serait le cas si vous déclariez des paramètres body additionnels, vous pouvez utiliser le paramètre spécial `embed` de `Body` :
+
+```Python
+item: Item = Body(embed=True)
+```
+
+Voici un exemple complet :
+
+{* ../../docs_src/body_multiple_params/tutorial005_an_py310.py hl[17] *}
+
+Dans ce cas **FastAPI** attendra un body semblable à :
+
+```JSON hl_lines="2"
+{
+ "item": {
+ "name": "Foo",
+ "description": "The pretender",
+ "price": 42.0,
+ "tax": 3.2
+ }
+}
+```
+
+au lieu de :
+
+```JSON
+{
+ "name": "Foo",
+ "description": "The pretender",
+ "price": 42.0,
+ "tax": 3.2
+}
+```
+
+## Pour résumer
+
+Vous pouvez ajouter plusieurs paramètres body dans votre fonction de routage, même si une requête ne peut avoir qu'un seul body.
+
+Cependant, **FastAPI** se chargera de faire opérer sa magie, afin de toujours fournir à votre fonction des données correctes, les validera et documentera le schéma associé.
+
+Vous pouvez également déclarer des valeurs [scalaires](https://docs.github.com/fr/graphql/reference/scalars) à recevoir dans le body.
+
+Et vous pouvez indiquer à **FastAPI** d'inclure le body dans une autre variable, même lorsqu'un seul paramètre est déclaré.
diff --git a/docs/fr/docs/tutorial/body.md b/docs/fr/docs/tutorial/body.md
index ae952405c..760b6d80a 100644
--- a/docs/fr/docs/tutorial/body.md
+++ b/docs/fr/docs/tutorial/body.md
@@ -8,20 +8,21 @@ Votre API aura presque toujours à envoyer un corps de **réponse**. Mais un cli
Pour déclarer un corps de **requête**, on utilise les modèles de Pydantic en profitant de tous leurs avantages et fonctionnalités.
-!!! info
- Pour envoyer de la donnée, vous devriez utiliser : `POST` (le plus populaire), `PUT`, `DELETE` ou `PATCH`.
+/// info
- Envoyer un corps dans une requête `GET` a un comportement non défini dans les spécifications, cela est néanmoins supporté par **FastAPI**, seulement pour des cas d'utilisation très complexes/extrêmes.
+Pour envoyer de la donnée, vous devriez utiliser : `POST` (le plus populaire), `PUT`, `DELETE` ou `PATCH`.
- Ceci étant découragé, la documentation interactive générée par Swagger UI ne montrera pas de documentation pour le corps d'une requête `GET`, et les proxys intermédiaires risquent de ne pas le supporter.
+Envoyer un corps dans une requête `GET` a un comportement non défini dans les spécifications, cela est néanmoins supporté par **FastAPI**, seulement pour des cas d'utilisation très complexes/extrêmes.
+
+Ceci étant découragé, la documentation interactive générée par Swagger UI ne montrera pas de documentation pour le corps d'une requête `GET`, et les proxys intermédiaires risquent de ne pas le supporter.
+
+///
## Importez le `BaseModel` de Pydantic
Commencez par importer la classe `BaseModel` du module `pydantic` :
-```Python hl_lines="4"
-{!../../../docs_src/body/tutorial001.py!}
-```
+{* ../../docs_src/body/tutorial001.py hl[4] *}
## Créez votre modèle de données
@@ -29,9 +30,7 @@ Déclarez ensuite votre modèle de données en tant que classe qui hérite de `B
Utilisez les types Python standard pour tous les attributs :
-```Python hl_lines="7-11"
-{!../../../docs_src/body/tutorial001.py!}
-```
+{* ../../docs_src/body/tutorial001.py hl[7:11] *}
Tout comme pour la déclaration de paramètres de requête, quand un attribut de modèle a une valeur par défaut, il n'est pas nécessaire. Sinon, cet attribut doit être renseigné dans le corps de la requête. Pour rendre ce champ optionnel simplement, utilisez `None` comme valeur par défaut.
@@ -59,9 +58,7 @@ Par exemple, le modèle ci-dessus déclare un "objet" JSON (ou `dict` Python) te
Pour l'ajouter à votre *opération de chemin*, déclarez-le comme vous déclareriez des paramètres de chemin ou de requête :
-```Python hl_lines="18"
-{!../../../docs_src/body/tutorial001.py!}
-```
+{* ../../docs_src/body/tutorial001.py hl[18] *}
...et déclarez que son type est le modèle que vous avez créé : `Item`.
@@ -110,24 +107,25 @@ Mais vous auriez le même support de l'éditeur avec
-!!! tip "Astuce"
- Si vous utilisez PyCharm comme éditeur, vous pouvez utiliser le Plugin Pydantic PyCharm Plugin.
+/// tip | Astuce
- Ce qui améliore le support pour les modèles Pydantic avec :
+Si vous utilisez PyCharm comme éditeur, vous pouvez utiliser le Plugin Pydantic PyCharm Plugin.
- * de l'auto-complétion
- * des vérifications de type
- * du "refactoring" (ou remaniement de code)
- * de la recherche
- * de l'inspection
+Ce qui améliore le support pour les modèles Pydantic avec :
+
+* de l'auto-complétion
+* des vérifications de type
+* du "refactoring" (ou remaniement de code)
+* de la recherche
+* de l'inspection
+
+///
## Utilisez le modèle
Dans la fonction, vous pouvez accéder à tous les attributs de l'objet du modèle directement :
-```Python hl_lines="21"
-{!../../../docs_src/body/tutorial002.py!}
-```
+{* ../../docs_src/body/tutorial002.py hl[21] *}
## Corps de la requête + paramètres de chemin
@@ -135,9 +133,7 @@ Vous pouvez déclarer des paramètres de chemin et un corps de requête pour la
**FastAPI** est capable de reconnaître que les paramètres de la fonction qui correspondent aux paramètres de chemin doivent être **récupérés depuis le chemin**, et que les paramètres de fonctions déclarés comme modèles Pydantic devraient être **récupérés depuis le corps de la requête**.
-```Python hl_lines="17-18"
-{!../../../docs_src/body/tutorial003.py!}
-```
+{* ../../docs_src/body/tutorial003.py hl[17:18] *}
## Corps de la requête + paramètres de chemin et de requête
@@ -145,9 +141,7 @@ Vous pouvez aussi déclarer un **corps**, et des paramètres de **chemin** et de
**FastAPI** saura reconnaître chacun d'entre eux et récupérer la bonne donnée au bon endroit.
-```Python hl_lines="18"
-{!../../../docs_src/body/tutorial004.py!}
-```
+{* ../../docs_src/body/tutorial004.py hl[18] *}
Les paramètres de la fonction seront reconnus comme tel :
@@ -155,10 +149,13 @@ Les paramètres de la fonction seront reconnus comme tel :
* Si le paramètre est d'un **type singulier** (comme `int`, `float`, `str`, `bool`, etc.), il sera interprété comme un paramètre de **requête**.
* Si le paramètre est déclaré comme ayant pour type un **modèle Pydantic**, il sera interprété comme faisant partie du **corps** de la requête.
-!!! note
- **FastAPI** saura que la valeur de `q` n'est pas requise grâce à la valeur par défaut `=None`.
+/// note
- Le type `Optional` dans `Optional[str]` n'est pas utilisé par **FastAPI**, mais sera utile à votre éditeur pour améliorer le support offert par ce dernier et détecter plus facilement des erreurs de type.
+**FastAPI** saura que la valeur de `q` n'est pas requise grâce à la valeur par défaut `=None`.
+
+Le type `Optional` dans `Optional[str]` n'est pas utilisé par **FastAPI**, mais sera utile à votre éditeur pour améliorer le support offert par ce dernier et détecter plus facilement des erreurs de type.
+
+///
## Sans Pydantic
diff --git a/docs/fr/docs/tutorial/debugging.md b/docs/fr/docs/tutorial/debugging.md
index e58872d30..ab00fbdeb 100644
--- a/docs/fr/docs/tutorial/debugging.md
+++ b/docs/fr/docs/tutorial/debugging.md
@@ -6,9 +6,7 @@ Vous pouvez connecter le débogueur da
Dans votre application FastAPI, importez et exécutez directement `uvicorn` :
-```Python hl_lines="1 15"
-{!../../../docs_src/debugging/tutorial001.py!}
-```
+{* ../../docs_src/debugging/tutorial001.py hl[1,15] *}
### À propos de `__name__ == "__main__"`
@@ -74,9 +72,12 @@ Ainsi, la ligne :
ne sera pas exécutée.
-!!! info
+/// info
+
Pour plus d'informations, consultez la documentation officielle de Python.
+///
+
## Exécutez votre code avec votre débogueur
Parce que vous exécutez le serveur Uvicorn directement depuis votre code, vous pouvez appeler votre programme Python (votre application FastAPI) directement depuis le débogueur.
diff --git a/docs/fr/docs/tutorial/first-steps.md b/docs/fr/docs/tutorial/first-steps.md
index e98283f1e..758145362 100644
--- a/docs/fr/docs/tutorial/first-steps.md
+++ b/docs/fr/docs/tutorial/first-steps.md
@@ -2,9 +2,7 @@
Le fichier **FastAPI** le plus simple possible pourrait ressembler à cela :
-```Python
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py *}
Copiez ce code dans un fichier nommé `main.py`.
@@ -24,12 +22,15 @@ $ uvicorn main:app --reload
-!!! note
- La commande `uvicorn main:app` fait référence à :
+/// note
- * `main` : le fichier `main.py` (le module Python).
- * `app` : l'objet créé dans `main.py` via la ligne `app = FastAPI()`.
- * `--reload` : l'option disant à uvicorn de redémarrer le serveur à chaque changement du code. À ne pas utiliser en production !
+La commande `uvicorn main:app` fait référence à :
+
+* `main` : le fichier `main.py` (le module Python).
+* `app` : l'objet créé dans `main.py` via la ligne `app = FastAPI()`.
+* `--reload` : l'option disant à uvicorn de redémarrer le serveur à chaque changement du code. À ne pas utiliser en production !
+
+///
Vous devriez voir dans la console, une ligne semblable à la suivante :
@@ -131,22 +132,21 @@ Vous pourriez aussi l'utiliser pour générer du code automatiquement, pour les
### Étape 1 : import `FastAPI`
-```Python hl_lines="1"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[1] *}
`FastAPI` est une classe Python qui fournit toutes les fonctionnalités nécessaires au lancement de votre API.
-!!! note "Détails techniques"
- `FastAPI` est une classe héritant directement de `Starlette`.
+/// note | Détails techniques
- Vous pouvez donc aussi utiliser toutes les fonctionnalités de Starlette depuis `FastAPI`.
+`FastAPI` est une classe héritant directement de `Starlette`.
+
+Vous pouvez donc aussi utiliser toutes les fonctionnalités de Starlette depuis `FastAPI`.
+
+///
### Étape 2 : créer une "instance" `FastAPI`
-```Python hl_lines="3"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[3] *}
Ici la variable `app` sera une "instance" de la classe `FastAPI`.
@@ -166,9 +166,7 @@ $ uvicorn main:app --reload
Si vous créez votre app avec :
-```Python hl_lines="3"
-{!../../../docs_src/first_steps/tutorial002.py!}
-```
+{* ../../docs_src/first_steps/tutorial002.py hl[3] *}
Et la mettez dans un fichier `main.py`, alors vous appelleriez `uvicorn` avec :
@@ -200,9 +198,11 @@ https://example.com/items/foo
/items/foo
```
-!!! info
- Un chemin, ou "path" est aussi souvent appelé route ou "endpoint".
+/// info
+Un chemin, ou "path" est aussi souvent appelé route ou "endpoint".
+
+///
#### Opération
@@ -242,25 +242,26 @@ Nous allons donc aussi appeler ces dernières des "**opérations**".
#### Définir un *décorateur d'opération de chemin*
-```Python hl_lines="6"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[6] *}
Le `@app.get("/")` dit à **FastAPI** que la fonction en dessous est chargée de gérer les requêtes qui vont sur :
* le chemin `/`
* en utilisant une opération get
-!!! info "`@décorateur` Info"
- Cette syntaxe `@something` en Python est appelée un "décorateur".
+/// info | `@décorateur` Info
- Vous la mettez au dessus d'une fonction. Comme un joli chapeau décoratif (j'imagine que ce terme vient de là 🤷🏻♂).
+Cette syntaxe `@something` en Python est appelée un "décorateur".
- Un "décorateur" prend la fonction en dessous et en fait quelque chose.
+Vous la mettez au dessus d'une fonction. Comme un joli chapeau décoratif (j'imagine que ce terme vient de là 🤷🏻♂).
- Dans notre cas, ce décorateur dit à **FastAPI** que la fonction en dessous correspond au **chemin** `/` avec l'**opération** `get`.
+Un "décorateur" prend la fonction en dessous et en fait quelque chose.
- C'est le "**décorateur d'opération de chemin**".
+Dans notre cas, ce décorateur dit à **FastAPI** que la fonction en dessous correspond au **chemin** `/` avec l'**opération** `get`.
+
+C'est le "**décorateur d'opération de chemin**".
+
+///
Vous pouvez aussi utiliser les autres opérations :
@@ -275,14 +276,17 @@ Tout comme celles les plus exotiques :
* `@app.patch()`
* `@app.trace()`
-!!! tip "Astuce"
- Vous êtes libres d'utiliser chaque opération (méthode HTTP) comme vous le désirez.
+/// tip | Astuce
- **FastAPI** n'impose pas de sens spécifique à chacune d'elle.
+Vous êtes libres d'utiliser chaque opération (méthode HTTP) comme vous le désirez.
- Les informations qui sont présentées ici forment une directive générale, pas des obligations.
+**FastAPI** n'impose pas de sens spécifique à chacune d'elle.
- Par exemple, quand l'on utilise **GraphQL**, toutes les actions sont effectuées en utilisant uniquement des opérations `POST`.
+Les informations qui sont présentées ici forment une directive générale, pas des obligations.
+
+Par exemple, quand l'on utilise **GraphQL**, toutes les actions sont effectuées en utilisant uniquement des opérations `POST`.
+
+///
### Étape 4 : définir la **fonction de chemin**.
@@ -292,9 +296,7 @@ Voici notre "**fonction de chemin**" (ou fonction d'opération de chemin) :
* **opération** : `get`.
* **fonction** : la fonction sous le "décorateur" (sous `@app.get("/")`).
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[7] *}
C'est une fonction Python.
@@ -306,18 +308,17 @@ Ici, c'est une fonction asynchrone (définie avec `async def`).
Vous pourriez aussi la définir comme une fonction classique plutôt qu'avec `async def` :
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial003.py!}
-```
+{* ../../docs_src/first_steps/tutorial003.py hl[7] *}
-!!! note
- Si vous ne connaissez pas la différence, allez voir la section [Concurrence : *"Vous êtes pressés ?"*](../async.md#vous-etes-presses){.internal-link target=_blank}.
+/// note
+
+Si vous ne connaissez pas la différence, allez voir la section [Concurrence : *"Vous êtes pressés ?"*](../async.md#vous-etes-presses){.internal-link target=_blank}.
+
+///
### Étape 5 : retourner le contenu
-```Python hl_lines="8"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[8] *}
Vous pouvez retourner un dictionnaire (`dict`), une liste (`list`), des valeurs seules comme des chaines de caractères (`str`) et des entiers (`int`), etc.
diff --git a/docs/fr/docs/tutorial/index.md b/docs/fr/docs/tutorial/index.md
index 4dc202b33..83cc5f9e8 100644
--- a/docs/fr/docs/tutorial/index.md
+++ b/docs/fr/docs/tutorial/index.md
@@ -52,22 +52,25 @@ $ pip install fastapi[all]
... qui comprend également `uvicorn`, que vous pouvez utiliser comme serveur pour exécuter votre code.
-!!! note
- Vous pouvez également l'installer pièce par pièce.
+/// note
- C'est ce que vous feriez probablement une fois que vous voudrez déployer votre application en production :
+Vous pouvez également l'installer pièce par pièce.
- ```
- pip install fastapi
- ```
+C'est ce que vous feriez probablement une fois que vous voudrez déployer votre application en production :
- Installez également `uvicorn` pour qu'il fonctionne comme serveur :
+```
+pip install fastapi
+```
- ```
- pip install uvicorn
- ```
+Installez également `uvicorn` pour qu'il fonctionne comme serveur :
- Et la même chose pour chacune des dépendances facultatives que vous voulez utiliser.
+```
+pip install uvicorn
+```
+
+Et la même chose pour chacune des dépendances facultatives que vous voulez utiliser.
+
+///
## Guide utilisateur avancé
diff --git a/docs/fr/docs/tutorial/path-params-numeric-validations.md b/docs/fr/docs/tutorial/path-params-numeric-validations.md
new file mode 100644
index 000000000..3f3280e64
--- /dev/null
+++ b/docs/fr/docs/tutorial/path-params-numeric-validations.md
@@ -0,0 +1,163 @@
+# Paramètres de chemin et validations numériques
+
+De la même façon que vous pouvez déclarer plus de validations et de métadonnées pour les paramètres de requête avec `Query`, vous pouvez déclarer le même type de validations et de métadonnées pour les paramètres de chemin avec `Path`.
+
+## Importer Path
+
+Tout d'abord, importez `Path` de `fastapi`, et importez `Annotated` :
+
+{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[1,3] *}
+
+/// info
+
+FastAPI a ajouté le support pour `Annotated` (et a commencé à le recommander) dans la version 0.95.0.
+
+Si vous avez une version plus ancienne, vous obtiendrez des erreurs en essayant d'utiliser `Annotated`.
+
+Assurez-vous de [Mettre à jour la version de FastAPI](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank} à la version 0.95.1 à minima avant d'utiliser `Annotated`.
+
+///
+
+## Déclarer des métadonnées
+
+Vous pouvez déclarer les mêmes paramètres que pour `Query`.
+
+Par exemple, pour déclarer une valeur de métadonnée `title` pour le paramètre de chemin `item_id`, vous pouvez écrire :
+
+{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[10] *}
+
+/// note
+
+Un paramètre de chemin est toujours requis car il doit faire partie du chemin. Même si vous l'avez déclaré avec `None` ou défini une valeur par défaut, cela ne changerait rien, il serait toujours requis.
+
+///
+
+## Ordonnez les paramètres comme vous le souhaitez
+
+/// tip
+
+Ce n'est probablement pas aussi important ou nécessaire si vous utilisez `Annotated`.
+
+///
+
+Disons que vous voulez déclarer le paramètre de requête `q` comme un `str` requis.
+
+Et vous n'avez pas besoin de déclarer autre chose pour ce paramètre, donc vous n'avez pas vraiment besoin d'utiliser `Query`.
+
+Mais vous avez toujours besoin d'utiliser `Path` pour le paramètre de chemin `item_id`. Et vous ne voulez pas utiliser `Annotated` pour une raison quelconque.
+
+Python se plaindra si vous mettez une valeur avec une "défaut" avant une valeur qui n'a pas de "défaut".
+
+Mais vous pouvez les réorganiser, et avoir la valeur sans défaut (le paramètre de requête `q`) en premier.
+
+Cela n'a pas d'importance pour **FastAPI**. Il détectera les paramètres par leurs noms, types et déclarations par défaut (`Query`, `Path`, etc), il ne se soucie pas de l'ordre.
+
+Ainsi, vous pouvez déclarer votre fonction comme suit :
+
+{* ../../docs_src/path_params_numeric_validations/tutorial002.py hl[7] *}
+
+Mais gardez à l'esprit que si vous utilisez `Annotated`, vous n'aurez pas ce problème, cela n'aura pas d'importance car vous n'utilisez pas les valeurs par défaut des paramètres de fonction pour `Query()` ou `Path()`.
+
+{* ../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py hl[10] *}
+
+## Ordonnez les paramètres comme vous le souhaitez (astuces)
+
+/// tip
+
+Ce n'est probablement pas aussi important ou nécessaire si vous utilisez `Annotated`.
+
+///
+
+Voici une **petite astuce** qui peut être pratique, mais vous n'en aurez pas souvent besoin.
+
+Si vous voulez :
+
+* déclarer le paramètre de requête `q` sans `Query` ni valeur par défaut
+* déclarer le paramètre de chemin `item_id` en utilisant `Path`
+* les avoir dans un ordre différent
+* ne pas utiliser `Annotated`
+
+...Python a une petite syntaxe spéciale pour cela.
+
+Passez `*`, comme premier paramètre de la fonction.
+
+Python ne fera rien avec ce `*`, mais il saura que tous les paramètres suivants doivent être appelés comme arguments "mots-clés" (paires clé-valeur), également connus sous le nom de kwargs. Même s'ils n'ont pas de valeur par défaut.
+
+{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *}
+
+# Avec `Annotated`
+
+Gardez à l'esprit que si vous utilisez `Annotated`, comme vous n'utilisez pas les valeurs par défaut des paramètres de fonction, vous n'aurez pas ce problème, et vous n'aurez probablement pas besoin d'utiliser `*`.
+
+{* ../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py hl[10] *}
+
+## Validations numériques : supérieur ou égal
+
+Avec `Query` et `Path` (et d'autres que vous verrez plus tard) vous pouvez déclarer des contraintes numériques.
+
+Ici, avec `ge=1`, `item_id` devra être un nombre entier "`g`reater than or `e`qual" à `1`.
+
+{* ../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py hl[10] *}
+
+## Validations numériques : supérieur ou égal et inférieur ou égal
+
+La même chose s'applique pour :
+
+* `gt` : `g`reater `t`han
+* `le` : `l`ess than or `e`qual
+
+{* ../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py hl[10] *}
+
+## Validations numériques : supérieur et inférieur ou égal
+
+La même chose s'applique pour :
+
+* `gt` : `g`reater `t`han
+* `le` : `l`ess than or `e`qual
+
+{* ../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py hl[10] *}
+
+## Validations numériques : flottants, supérieur et inférieur
+
+Les validations numériques fonctionnent également pour les valeurs `float`.
+
+C'est ici qu'il devient important de pouvoir déclarer gt et pas seulement ge. Avec cela, vous pouvez exiger, par exemple, qu'une valeur doit être supérieure à `0`, même si elle est inférieure à `1`.
+
+Ainsi, `0.5` serait une valeur valide. Mais `0.0` ou `0` ne le serait pas.
+
+Et la même chose pour lt.
+
+{* ../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py hl[13] *}
+
+## Pour résumer
+
+Avec `Query`, `Path` (et d'autres que vous verrez plus tard) vous pouvez déclarer des métadonnées et des validations de chaînes de la même manière qu'avec les [Paramètres de requête et validations de chaînes](query-params-str-validations.md){.internal-link target=_blank}.
+
+Et vous pouvez également déclarer des validations numériques :
+
+* `gt` : `g`reater `t`han
+* `ge` : `g`reater than or `e`qual
+* `lt` : `l`ess `t`han
+* `le` : `l`ess than or `e`qual
+
+/// info
+
+`Query`, `Path`, et d'autres classes que vous verrez plus tard sont des sous-classes d'une classe commune `Param`.
+
+Tous partagent les mêmes paramètres pour des validations supplémentaires et des métadonnées que vous avez vu précédemment.
+
+///
+
+/// note | Détails techniques
+
+Lorsque vous importez `Query`, `Path` et d'autres de `fastapi`, ce sont en fait des fonctions.
+
+Ces dernières, lorsqu'elles sont appelées, renvoient des instances de classes du même nom.
+
+Ainsi, vous importez `Query`, qui est une fonction. Et lorsque vous l'appelez, elle renvoie une instance d'une classe également nommée `Query`.
+
+Ces fonctions sont là (au lieu d'utiliser simplement les classes directement) pour que votre éditeur ne marque pas d'erreurs sur leurs types.
+
+De cette façon, vous pouvez utiliser votre éditeur et vos outils de codage habituels sans avoir à ajouter des configurations personnalisées pour ignorer ces erreurs.
+
+///
diff --git a/docs/fr/docs/tutorial/path-params.md b/docs/fr/docs/tutorial/path-params.md
index 523e2c8c2..71c96b18e 100644
--- a/docs/fr/docs/tutorial/path-params.md
+++ b/docs/fr/docs/tutorial/path-params.md
@@ -4,9 +4,7 @@ Vous pouvez déclarer des "paramètres" ou "variables" de chemin avec la même s
formatage de chaîne Python :
-```Python hl_lines="6-7"
-{!../../../docs_src/path_params/tutorial001.py!}
-```
+{* ../../docs_src/path_params/tutorial001.py hl[6:7] *}
La valeur du paramètre `item_id` sera transmise à la fonction dans l'argument `item_id`.
@@ -22,15 +20,16 @@ vous verrez comme réponse :
Vous pouvez déclarer le type d'un paramètre de chemin dans la fonction, en utilisant les annotations de type Python :
-```Python hl_lines="7"
-{!../../../docs_src/path_params/tutorial002.py!}
-```
+{* ../../docs_src/path_params/tutorial002.py hl[7] *}
Ici, `item_id` est déclaré comme `int`.
-!!! check "vérifier"
- Ceci vous permettra d'obtenir des fonctionnalités de l'éditeur dans votre fonction, telles
- que des vérifications d'erreur, de l'auto-complétion, etc.
+/// check | vérifier
+
+Ceci vous permettra d'obtenir des fonctionnalités de l'éditeur dans votre fonction, telles
+que des vérifications d'erreur, de l'auto-complétion, etc.
+
+///
## Conversion de données
@@ -40,12 +39,15 @@ Si vous exécutez cet exemple et allez sur "parsing" automatique.
+Comme vous l'avez remarqué, la valeur reçue par la fonction (et renvoyée ensuite) est `3`,
+en tant qu'entier (`int`) Python, pas la chaîne de caractères (`string`) `"3"`.
+
+Grâce aux déclarations de types, **FastAPI** fournit du
+"parsing" automatique.
+
+///
## Validation de données
@@ -72,12 +74,15 @@ La même erreur se produira si vous passez un nombre flottant (`float`) et non u
http://127.0.0.1:8000/items/4.2.
-!!! check "vérifier"
- Donc, avec ces mêmes déclarations de type Python, **FastAPI** vous fournit de la validation de données.
+/// check | vérifier
- Notez que l'erreur mentionne le point exact où la validation n'a pas réussi.
+Donc, avec ces mêmes déclarations de type Python, **FastAPI** vous fournit de la validation de données.
- Ce qui est incroyablement utile au moment de développer et débugger du code qui interagit avec votre API.
+Notez que l'erreur mentionne le point exact où la validation n'a pas réussi.
+
+Ce qui est incroyablement utile au moment de développer et débugger du code qui interagit avec votre API.
+
+///
## Documentation
@@ -86,10 +91,13 @@ documentation générée automatiquement et interactive :
-!!! info
- À nouveau, en utilisant uniquement les déclarations de type Python, **FastAPI** vous fournit automatiquement une documentation interactive (via Swagger UI).
+/// info
- On voit bien dans la documentation que `item_id` est déclaré comme entier.
+À nouveau, en utilisant uniquement les déclarations de type Python, **FastAPI** vous fournit automatiquement une documentation interactive (via Swagger UI).
+
+On voit bien dans la documentation que `item_id` est déclaré comme entier.
+
+///
## Les avantages d'avoir une documentation basée sur une norme, et la documentation alternative.
@@ -119,9 +127,7 @@ Et vous avez un second chemin : `/users/{user_id}` pour récupérer de la donné
Les *fonctions de chemin* étant évaluées dans l'ordre, il faut s'assurer que la fonction correspondant à `/users/me` est déclarée avant celle de `/users/{user_id}` :
-```Python hl_lines="6 11"
-{!../../../docs_src/path_params/tutorial003.py!}
-```
+{* ../../docs_src/path_params/tutorial003.py hl[6,11] *}
Sinon, le chemin `/users/{user_id}` correspondrait aussi à `/users/me`, la fonction "croyant" qu'elle a reçu un paramètre `user_id` avec pour valeur `"me"`.
@@ -137,23 +143,25 @@ En héritant de `str` la documentation sera capable de savoir que les valeurs do
Créez ensuite des attributs de classe avec des valeurs fixes, qui seront les valeurs autorisées pour cette énumération.
-```Python hl_lines="1 6-9"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[1,6:9] *}
-!!! info
- Les énumérations (ou enums) sont disponibles en Python depuis la version 3.4.
+/// info
-!!! tip "Astuce"
- Pour ceux qui se demandent, "AlexNet", "ResNet", et "LeNet" sont juste des noms de modèles de Machine Learning.
+Les énumérations (ou enums) sont disponibles en Python depuis la version 3.4.
+
+///
+
+/// tip | Astuce
+
+Pour ceux qui se demandent, "AlexNet", "ResNet", et "LeNet" sont juste des noms de modèles de Machine Learning.
+
+///
### Déclarer un paramètre de chemin
Créez ensuite un *paramètre de chemin* avec une annotation de type désignant l'énumération créée précédemment (`ModelName`) :
-```Python hl_lines="16"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[16] *}
### Documentation
@@ -169,20 +177,19 @@ La valeur du *paramètre de chemin* sera un des "membres" de l'énumération.
Vous pouvez comparer ce paramètre avec les membres de votre énumération `ModelName` :
-```Python hl_lines="17"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[17] *}
#### Récupérer la *valeur de l'énumération*
Vous pouvez obtenir la valeur réel d'un membre (une chaîne de caractères ici), avec `model_name.value`, ou en général, `votre_membre_d'enum.value` :
-```Python hl_lines="20"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[20] *}
-!!! tip "Astuce"
- Vous pouvez aussi accéder la valeur `"lenet"` avec `ModelName.lenet.value`.
+/// tip | Astuce
+
+Vous pouvez aussi accéder la valeur `"lenet"` avec `ModelName.lenet.value`.
+
+///
#### Retourner des *membres d'énumération*
@@ -190,9 +197,7 @@ Vous pouvez retourner des *membres d'énumération* dans vos *fonctions de chemi
Ils seront convertis vers leurs valeurs correspondantes (chaînes de caractères ici) avant d'être transmis au client :
-```Python hl_lines="18 21 23"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[18,21,23] *}
Le client recevra une réponse JSON comme celle-ci :
@@ -231,14 +236,15 @@ Dans ce cas, le nom du paramètre est `file_path`, et la dernière partie, `:pat
Vous pouvez donc l'utilisez comme tel :
-```Python hl_lines="6"
-{!../../../docs_src/path_params/tutorial004.py!}
-```
+{* ../../docs_src/path_params/tutorial004.py hl[6] *}
-!!! tip "Astuce"
- Vous pourriez avoir besoin que le paramètre contienne `/home/johndoe/myfile.txt`, avec un slash au début (`/`).
+/// tip | Astuce
- Dans ce cas, l'URL serait : `/files//home/johndoe/myfile.txt`, avec un double slash (`//`) entre `files` et `home`.
+Vous pourriez avoir besoin que le paramètre contienne `/home/johndoe/myfile.txt`, avec un slash au début (`/`).
+
+Dans ce cas, l'URL serait : `/files//home/johndoe/myfile.txt`, avec un double slash (`//`) entre `files` et `home`.
+
+///
## Récapitulatif
diff --git a/docs/fr/docs/tutorial/query-params-str-validations.md b/docs/fr/docs/tutorial/query-params-str-validations.md
index f5248fe8b..c54c0c717 100644
--- a/docs/fr/docs/tutorial/query-params-str-validations.md
+++ b/docs/fr/docs/tutorial/query-params-str-validations.md
@@ -4,16 +4,17 @@
Commençons avec cette application pour exemple :
-```Python hl_lines="9"
-{!../../../docs_src/query_params_str_validations/tutorial001.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial001.py hl[9] *}
Le paramètre de requête `q` a pour type `Union[str, None]` (ou `str | None` en Python 3.10), signifiant qu'il est de type `str` mais pourrait aussi être égal à `None`, et bien sûr, la valeur par défaut est `None`, donc **FastAPI** saura qu'il n'est pas requis.
-!!! note
- **FastAPI** saura que la valeur de `q` n'est pas requise grâce à la valeur par défaut `= None`.
+/// note
- Le `Union` dans `Union[str, None]` permettra à votre éditeur de vous offrir un meilleur support et de détecter les erreurs.
+**FastAPI** saura que la valeur de `q` n'est pas requise grâce à la valeur par défaut `= None`.
+
+Le `Union` dans `Union[str, None]` permettra à votre éditeur de vous offrir un meilleur support et de détecter les erreurs.
+
+///
## Validation additionnelle
@@ -23,17 +24,13 @@ Nous allons imposer que bien que `q` soit un paramètre optionnel, dès qu'il es
Pour cela, importez d'abord `Query` depuis `fastapi` :
-```Python hl_lines="3"
-{!../../../docs_src/query_params_str_validations/tutorial002.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial002.py hl[3] *}
## Utiliser `Query` comme valeur par défaut
Construisez ensuite la valeur par défaut de votre paramètre avec `Query`, en choisissant 50 comme `max_length` :
-```Python hl_lines="9"
-{!../../../docs_src/query_params_str_validations/tutorial002.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial002.py hl[9] *}
Comme nous devons remplacer la valeur par défaut `None` dans la fonction par `Query()`, nous pouvons maintenant définir la valeur par défaut avec le paramètre `Query(default=None)`, il sert le même objectif qui est de définir cette valeur par défaut.
@@ -51,22 +48,25 @@ q: Union[str, None] = None
Mais déclare explicitement `q` comme étant un paramètre de requête.
-!!! info
- Gardez à l'esprit que la partie la plus importante pour rendre un paramètre optionnel est :
+/// info
- ```Python
- = None
- ```
+Gardez à l'esprit que la partie la plus importante pour rendre un paramètre optionnel est :
- ou :
+```Python
+= None
+```
- ```Python
- = Query(None)
- ```
+ou :
- et utilisera ce `None` pour détecter que ce paramètre de requête **n'est pas requis**.
+```Python
+= Query(None)
+```
- Le `Union[str, None]` est uniquement là pour permettre à votre éditeur un meilleur support.
+et utilisera ce `None` pour détecter que ce paramètre de requête **n'est pas requis**.
+
+Le `Union[str, None]` est uniquement là pour permettre à votre éditeur un meilleur support.
+
+///
Ensuite, nous pouvons passer d'autres paramètres à `Query`. Dans cet exemple, le paramètre `max_length` qui s'applique aux chaînes de caractères :
@@ -80,17 +80,13 @@ Cela va valider les données, montrer une erreur claire si ces dernières ne son
Vous pouvez aussi rajouter un second paramètre `min_length` :
-```Python hl_lines="9"
-{!../../../docs_src/query_params_str_validations/tutorial003.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial003.py hl[9] *}
## Ajouter des validations par expressions régulières
On peut définir une expression régulière à laquelle le paramètre doit correspondre :
-```Python hl_lines="10"
-{!../../../docs_src/query_params_str_validations/tutorial004.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial004.py hl[10] *}
Cette expression régulière vérifie que la valeur passée comme paramètre :
@@ -108,12 +104,13 @@ De la même façon que vous pouvez passer `None` comme premier argument pour l'u
Disons que vous déclarez le paramètre `q` comme ayant une longueur minimale de `3`, et une valeur par défaut étant `"fixedquery"` :
-```Python hl_lines="7"
-{!../../../docs_src/query_params_str_validations/tutorial005.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial005.py hl[7] *}
-!!! note "Rappel"
- Avoir une valeur par défaut rend le paramètre optionnel.
+/// note | Rappel
+
+Avoir une valeur par défaut rend le paramètre optionnel.
+
+///
## Rendre ce paramètre requis
@@ -137,12 +134,13 @@ q: Union[str, None] = Query(default=None, min_length=3)
Donc pour déclarer une valeur comme requise tout en utilisant `Query`, il faut utiliser `...` comme premier argument :
-```Python hl_lines="7"
-{!../../../docs_src/query_params_str_validations/tutorial006.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial006.py hl[7] *}
-!!! info
- Si vous n'avez jamais vu ce `...` auparavant : c'est une des constantes natives de Python appelée "Ellipsis".
+/// info
+
+Si vous n'avez jamais vu ce `...` auparavant : c'est une des constantes natives de Python appelée "Ellipsis".
+
+///
Cela indiquera à **FastAPI** que la présence de ce paramètre est obligatoire.
@@ -152,9 +150,7 @@ Quand on définit un paramètre de requête explicitement avec `Query` on peut a
Par exemple, pour déclarer un paramètre de requête `q` qui peut apparaître plusieurs fois dans une URL, on écrit :
-```Python hl_lines="9"
-{!../../../docs_src/query_params_str_validations/tutorial011.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial011.py hl[9] *}
Ce qui fait qu'avec une URL comme :
@@ -175,8 +171,11 @@ Donc la réponse de cette URL serait :
}
```
-!!! tip "Astuce"
- Pour déclarer un paramètre de requête de type `list`, comme dans l'exemple ci-dessus, il faut explicitement utiliser `Query`, sinon cela sera interprété comme faisant partie du corps de la requête.
+/// tip | Astuce
+
+Pour déclarer un paramètre de requête de type `list`, comme dans l'exemple ci-dessus, il faut explicitement utiliser `Query`, sinon cela sera interprété comme faisant partie du corps de la requête.
+
+///
La documentation sera donc mise à jour automatiquement pour autoriser plusieurs valeurs :
@@ -186,9 +185,7 @@ La documentation sera donc mise à jour automatiquement pour autoriser plusieurs
Et l'on peut aussi définir une liste de valeurs par défaut si aucune n'est fournie :
-```Python hl_lines="9"
-{!../../../docs_src/query_params_str_validations/tutorial012.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial012.py hl[9] *}
Si vous allez à :
@@ -213,14 +210,15 @@ et la réponse sera :
Il est aussi possible d'utiliser directement `list` plutôt que `List[str]` :
-```Python hl_lines="7"
-{!../../../docs_src/query_params_str_validations/tutorial013.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial013.py hl[7] *}
-!!! note
- Dans ce cas-là, **FastAPI** ne vérifiera pas le contenu de la liste.
+/// note
- Par exemple, `List[int]` vérifiera (et documentera) que la liste est bien entièrement composée d'entiers. Alors qu'un simple `list` ne ferait pas cette vérification.
+Dans ce cas-là, **FastAPI** ne vérifiera pas le contenu de la liste.
+
+Par exemple, `List[int]` vérifiera (et documentera) que la liste est bien entièrement composée d'entiers. Alors qu'un simple `list` ne ferait pas cette vérification.
+
+///
## Déclarer des métadonnées supplémentaires
@@ -228,22 +226,21 @@ On peut aussi ajouter plus d'informations sur le paramètre.
Ces informations seront incluses dans le schéma `OpenAPI` généré et utilisées par la documentation interactive ou les outils externes utilisés.
-!!! note
- Gardez en tête que les outils externes utilisés ne supportent pas forcément tous parfaitement OpenAPI.
+/// note
- Il se peut donc que certains d'entre eux n'utilisent pas toutes les métadonnées que vous avez déclarées pour le moment, bien que dans la plupart des cas, les fonctionnalités manquantes ont prévu d'être implémentées.
+Gardez en tête que les outils externes utilisés ne supportent pas forcément tous parfaitement OpenAPI.
+
+Il se peut donc que certains d'entre eux n'utilisent pas toutes les métadonnées que vous avez déclarées pour le moment, bien que dans la plupart des cas, les fonctionnalités manquantes ont prévu d'être implémentées.
+
+///
Vous pouvez ajouter un `title` :
-```Python hl_lines="10"
-{!../../../docs_src/query_params_str_validations/tutorial007.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial007.py hl[10] *}
Et une `description` :
-```Python hl_lines="13"
-{!../../../docs_src/query_params_str_validations/tutorial008.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial008.py hl[13] *}
## Alias de paramètres
@@ -263,9 +260,7 @@ Mais vous avez vraiment envie que ce soit exactement `item-query`...
Pour cela vous pouvez déclarer un `alias`, et cet alias est ce qui sera utilisé pour trouver la valeur du paramètre :
-```Python hl_lines="9"
-{!../../../docs_src/query_params_str_validations/tutorial009.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial009.py hl[9] *}
## Déprécier des paramètres
@@ -275,9 +270,7 @@ Il faut qu'il continue à exister pendant un certain temps car vos clients l'uti
On utilise alors l'argument `deprecated=True` de `Query` :
-```Python hl_lines="18"
-{!../../../docs_src/query_params_str_validations/tutorial010.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial010.py hl[18] *}
La documentation le présentera comme il suit :
diff --git a/docs/fr/docs/tutorial/query-params.md b/docs/fr/docs/tutorial/query-params.md
index 962135f63..b87c26c78 100644
--- a/docs/fr/docs/tutorial/query-params.md
+++ b/docs/fr/docs/tutorial/query-params.md
@@ -2,9 +2,7 @@
Quand vous déclarez des paramètres dans votre fonction de chemin qui ne font pas partie des paramètres indiqués dans le chemin associé, ces paramètres sont automatiquement considérés comme des paramètres de "requête".
-```Python hl_lines="9"
-{!../../../docs_src/query_params/tutorial001.py!}
-```
+{* ../../docs_src/query_params/tutorial001.py hl[9] *}
La partie appelée requête (ou **query**) dans une URL est l'ensemble des paires clés-valeurs placées après le `?` , séparées par des `&`.
@@ -63,28 +61,29 @@ Les valeurs des paramètres de votre fonction seront :
De la même façon, vous pouvez définir des paramètres de requête comme optionnels, en leur donnant comme valeur par défaut `None` :
-```Python hl_lines="9"
-{!../../../docs_src/query_params/tutorial002.py!}
-```
+{* ../../docs_src/query_params/tutorial002.py hl[9] *}
Ici, le paramètre `q` sera optionnel, et aura `None` comme valeur par défaut.
-!!! check "Remarque"
- On peut voir que **FastAPI** est capable de détecter que le paramètre de chemin `item_id` est un paramètre de chemin et que `q` n'en est pas un, c'est donc un paramètre de requête.
+/// check | Remarque
-!!! note
- **FastAPI** saura que `q` est optionnel grâce au `=None`.
+On peut voir que **FastAPI** est capable de détecter que le paramètre de chemin `item_id` est un paramètre de chemin et que `q` n'en est pas un, c'est donc un paramètre de requête.
- Le `Optional` dans `Optional[str]` n'est pas utilisé par **FastAPI** (**FastAPI** n'en utilisera que la partie `str`), mais il servira tout de même à votre éditeur de texte pour détecter des erreurs dans votre code.
+///
+/// note
+
+**FastAPI** saura que `q` est optionnel grâce au `=None`.
+
+Le `Optional` dans `Optional[str]` n'est pas utilisé par **FastAPI** (**FastAPI** n'en utilisera que la partie `str`), mais il servira tout de même à votre éditeur de texte pour détecter des erreurs dans votre code.
+
+///
## Conversion des types des paramètres de requête
Vous pouvez aussi déclarer des paramètres de requête comme booléens (`bool`), **FastAPI** les convertira :
-```Python hl_lines="9"
-{!../../../docs_src/query_params/tutorial003.py!}
-```
+{* ../../docs_src/query_params/tutorial003.py hl[9] *}
Avec ce code, en allant sur :
@@ -126,9 +125,7 @@ Et vous n'avez pas besoin de les déclarer dans un ordre spécifique.
Ils seront détectés par leurs noms :
-```Python hl_lines="8 10"
-{!../../../docs_src/query_params/tutorial004.py!}
-```
+{* ../../docs_src/query_params/tutorial004.py hl[8,10] *}
## Paramètres de requête requis
@@ -138,9 +135,7 @@ Si vous ne voulez pas leur donner de valeur par défaut mais juste les rendre op
Mais si vous voulez rendre un paramètre de requête obligatoire, vous pouvez juste ne pas y affecter de valeur par défaut :
-```Python hl_lines="6-7"
-{!../../../docs_src/query_params/tutorial005.py!}
-```
+{* ../../docs_src/query_params/tutorial005.py hl[6:7] *}
Ici le paramètre `needy` est un paramètre requis (ou obligatoire) de type `str`.
@@ -184,9 +179,7 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
Et bien sur, vous pouvez définir certains paramètres comme requis, certains avec des valeurs par défaut et certains entièrement optionnels :
-```Python hl_lines="10"
-{!../../../docs_src/query_params/tutorial006.py!}
-```
+{* ../../docs_src/query_params/tutorial006.py hl[10] *}
Ici, on a donc 3 paramètres de requête :
@@ -194,5 +187,8 @@ Ici, on a donc 3 paramètres de requête :
* `skip`, un `int` avec comme valeur par défaut `0`.
* `limit`, un `int` optionnel.
-!!! tip "Astuce"
- Vous pouvez utiliser les `Enum`s de la même façon qu'avec les [Paramètres de chemin](path-params.md#valeurs-predefinies){.internal-link target=_blank}.
+/// tip | Astuce
+
+Vous pouvez utiliser les `Enum`s de la même façon qu'avec les [Paramètres de chemin](path-params.md#valeurs-predefinies){.internal-link target=_blank}.
+
+///
diff --git a/docs/he/docs/index.md b/docs/he/docs/index.md
index 3af166ab0..bd166f205 100644
--- a/docs/he/docs/index.md
+++ b/docs/he/docs/index.md
@@ -12,10 +12,10 @@
-
+
-
-
+
+
@@ -94,7 +94,7 @@ FastAPI היא תשתית רשת מודרנית ומהירה (ביצועים ג
"_Honestly, what you've built looks super solid and polished. In many ways, it's what I wanted **Hug** to be - it's really inspiring to see someone build that._"
-
+
---
@@ -446,7 +446,7 @@ item: Item
בשימוש Pydantic:
--
email_validator - לאימות כתובות אימייל.
+- email-validator - לאימות כתובות אימייל.
בשימוש Starlette:
diff --git a/docs/hu/docs/index.md b/docs/hu/docs/index.md
index b7231ad56..45ff49c3b 100644
--- a/docs/hu/docs/index.md
+++ b/docs/hu/docs/index.md
@@ -6,7 +6,7 @@
-
+
@@ -87,7 +87,7 @@ Kulcs funkciók:
"_Honestly, what you've built looks super solid and polished. In many ways, it's what I wanted **Hug** to be - it's really inspiring to see someone build that._"
-
+
---
@@ -376,7 +376,7 @@ Visszatérve az előző kód példához. A **FastAPI**:
* Validálja hogy van egy `item_id` mező a `GET` és `PUT` kérésekben.
* Validálja hogy az `item_id` `int` típusú a `GET` és `PUT` kérésekben.
* Ha nem akkor látni fogunk egy tiszta hibát ezzel kapcsolatban.
-* ellenőrzi hogyha van egy opcionális query paraméter `q` névvel (azaz `http://127.0.0.1:8000/items/foo?q=somequery`) `GET` kérések esetén.
+* ellenőrzi hogyha van egy opcionális query paraméter `q` névvel (azaz `http://127.0.0.1:8000/items/foo?q=somequery`) `GET` kérések esetén.
* Mivel a `q` paraméter `= None`-al van deklarálva, ezért opcionális.
* `None` nélkül ez a mező kötelező lenne (mint például a body `PUT` kérések esetén).
* a `/items/{item_id}` címre érkező `PUT` kérések esetén, a JSON-t a következőképpen olvassa be:
@@ -443,7 +443,7 @@ Ezeknek a további megértéséhez:
email_validator - e-mail validációkra.
+* email-validator - e-mail validációkra.
* pydantic-settings - Beállítások követésére.
* pydantic-extra-types - Extra típusok Pydantic-hoz.
diff --git a/docs/id/docs/index.md b/docs/id/docs/index.md
new file mode 100644
index 000000000..5fb0c4c9c
--- /dev/null
+++ b/docs/id/docs/index.md
@@ -0,0 +1,495 @@
+# FastAPI
+
+
+
+
+ FastAPI, framework performa tinggi, mudah dipelajari, cepat untuk coding, siap untuk pengembangan +
+ + +--- + +**Dokumentasi**: https://fastapi.tiangolo.com + +**Kode Sumber**: https://github.com/fastapi/fastapi + +--- + +FastAPI adalah *framework* *web* moderen, cepat (performa-tinggi) untuk membangun API dengan Python berdasarkan tipe petunjuk Python. + +Fitur utama FastAPI: + +* **Cepat**: Performa sangat tinggi, setara **NodeJS** dan **Go** (berkat Starlette dan Pydantic). [Salah satu *framework* Python tercepat yang ada](#performa). +* **Cepat untuk coding**: Meningkatkan kecepatan pengembangan fitur dari 200% sampai 300%. * +* **Sedikit bug**: Mengurangi hingga 40% kesalahan dari manusia (pemrogram). * +* **Intuitif**: Dukungan editor hebat. Penyelesaian di mana pun. Lebih sedikit *debugging*. +* **Mudah**: Dibuat mudah digunakan dan dipelajari. Sedikit waktu membaca dokumentasi. +* **Ringkas**: Mengurasi duplikasi kode. Beragam fitur dari setiap deklarasi parameter. Lebih sedikit *bug*. +* **Handal**: Dapatkan kode siap-digunakan. Dengan dokumentasi otomatis interaktif. +* **Standar-resmi**: Berdasarkan (kompatibel dengan ) standar umum untuk API: OpenAPI (sebelumnya disebut Swagger) dan JSON Schema. + +* estimasi berdasarkan pengujian tim internal pengembangan applikasi siap pakai. + +## Sponsor + + + +{% if sponsors %} +{% for sponsor in sponsors.gold -%} +async def...fastapi dev main.py...email-validator - untuk validasi email.
+
+Digunakan oleh Starlette:
+
+* httpx - Dibutuhkan jika anda menggunakan `TestClient`.
+* jinja2 - Dibutuhkan jika anda menggunakan konfigurasi template bawaan.
+* python-multipart - Dibutuhkan jika anda menggunakan form dukungan "parsing", dengan `request.form()`.
+
+Digunakan oleh FastAPI / Starlette:
+
+* uvicorn - untuk server yang memuat dan melayani aplikasi anda. Termasuk `uvicorn[standard]`, yang memasukan sejumlah dependensi (misal `uvloop`) untuk needed melayani dengan performa tinggi.
+* `fastapi-cli` - untuk menyediakan perintah `fastapi`.
+
+### Tanpda dependensi `standard`
+
+Jika anda tidak ingin menambahkan dependensi opsional `standard`, anda dapat menggunakan `pip install fastapi` daripada `pip install "fastapi[standard]"`.
+
+### Dependensi Opsional Tambahan
+
+Ada beberapa dependensi opsional yang bisa anda install.
+
+Dependensi opsional tambahan Pydantic:
+
+* pydantic-settings - untuk manajemen setting.
+* pydantic-extra-types - untuk tipe tambahan yang digunakan dengan Pydantic.
+
+Dependensi tambahan opsional FastAPI:
+
+* orjson - Diperlukan jika anda akan menggunakan`ORJSONResponse`.
+* ujson - Diperlukan jika anda akan menggunakan `UJSONResponse`.
+
+## Lisensi
+
+Project terlisensi dengan lisensi MIT.
diff --git a/docs/id/docs/tutorial/first-steps.md b/docs/id/docs/tutorial/first-steps.md
new file mode 100644
index 000000000..9b461507d
--- /dev/null
+++ b/docs/id/docs/tutorial/first-steps.md
@@ -0,0 +1,332 @@
+# Langkah Pertama
+
+File FastAPI yang paling sederhana bisa seperti berikut:
+
+{* ../../docs_src/first_steps/tutorial001.py *}
+
+Salin file tersebut ke `main.py`.
+
+Jalankan di server:
+
+get
+
+/// info | `@decorator` Info
+
+Sintaksis `@sesuatu` di Python disebut "dekorator".
+
+Dekorator ditempatkan di atas fungsi. Seperti sebuah topi cantik (Saya pikir istilah ini berasal dari situ).
+
+"dekorator" memanggil dan bekerja dengan fungsi yang ada di bawahnya
+
+Pada kondisi ini, dekorator ini memberi tahu **FastAPI** bahwa fungsi di bawah nya berhubungan dengan **path** `/` dengan **operasi** `get`.
+
+Sehingga disebut **dekorator operasi path**.
+
+///
+
+Operasi lainnya yang bisa digunakan:
+
+* `@app.post()`
+* `@app.put()`
+* `@app.delete()`
+
+Dan operasi unik lainnya:
+
+* `@app.options()`
+* `@app.head()`
+* `@app.patch()`
+* `@app.trace()`
+
+/// tip | Tips
+
+Jika anda bisa menggunakan operasi apa saja (metode HTTP).
+
+**FastAPI** tidak mengharuskan anda menggunakan operasi tertentu.
+
+Informasi di sini hanyalah sebagai panduan, bukan keharusan.
+
+Sebagai contoh, ketika menggunakan GraphQL, semua operasi umumnya hanya menggunakan `POST`.
+
+///
+
+### Langkah 4: mendefinisikan **fungsi operasi path**
+
+Ini "**fungsi operasi path**" kita:
+
+* **path**: adalah `/`.
+* **operasi**: adalah `get`.
+* **fungsi**: adalah fungsi yang ada di bawah dekorator (di bawah `@app.get("/")`).
+
+{* ../../docs_src/first_steps/tutorial001.py hl[7] *}
+
+Ini adalah fungsi Python.
+
+Fungsi ini dipanggil **FastAPI** setiap kali menerima request ke URL "`/`" dengan operasi `GET`.
+
+Di kondisi ini, ini adalah sebuah fungsi `async`.
+
+---
+
+Anda bisa mendefinisikan fungsi ini sebagai fungsi normal daripada `async def`:
+
+{* ../../docs_src/first_steps/tutorial003.py hl[7] *}
+
+/// note | Catatan
+
+Jika anda tidak tahu perbedaannya, kunjungi [Async: *"Panduan cepat"*](../async.md#in-a-hurry){.internal-link target=_blank}.
+
+///
+
+### Langkah 5: hasilkan konten
+
+{* ../../docs_src/first_steps/tutorial001.py hl[8] *}
+
+Anda bisa menghasilkan `dict`, `list`, nilai singular seperti `str`, `int`, dll.
+
+Anda juga bisa menghasilkan model Pydantic (anda akan belajar mengenai ini nanti).
+
+Ada banyak objek dan model yang secara otomatis dikonversi ke JSON (termasuk ORM, dll). Anda bisa menggunakan yang anda suka, kemungkinan sudah didukung.
+
+## Ringkasan
+
+* Impor `FastAPI`.
+* Buat sebuah instance `app`.
+* Tulis **dekorator operasi path** menggunakan dekorator seperti `@app.get("/")`.
+* Definisikan **fungsi operasi path**; sebagai contoh, `def root(): ...`.
+* Jalankan server development dengan perintah `fastapi dev`.
diff --git a/docs/id/docs/tutorial/index.md b/docs/id/docs/tutorial/index.md
index 6b6de24f0..c01ec9a89 100644
--- a/docs/id/docs/tutorial/index.md
+++ b/docs/id/docs/tutorial/index.md
@@ -52,22 +52,25 @@ $ pip install "fastapi[all]"
...yang juga termasuk `uvicorn`, yang dapat kamu gunakan sebagai server yang menjalankan kodemu.
-!!! note "Catatan"
- Kamu juga dapat meng-installnya bagian demi bagian.
+/// note | Catatan
- Hal ini mungkin yang akan kamu lakukan ketika kamu hendak menyebarkan (men-deploy) aplikasimu ke tahap produksi:
+Kamu juga dapat meng-installnya bagian demi bagian.
- ```
- pip install fastapi
- ```
+Hal ini mungkin yang akan kamu lakukan ketika kamu hendak menyebarkan (men-deploy) aplikasimu ke tahap produksi:
- Juga install `uvicorn` untuk menjalankan server"
+```
+pip install fastapi
+```
- ```
- pip install "uvicorn[standard]"
- ```
+Juga install `uvicorn` untuk menjalankan server"
- Dan demikian juga untuk pilihan dependensi yang hendak kamu gunakan.
+```
+pip install "uvicorn[standard]"
+```
+
+Dan demikian juga untuk pilihan dependensi yang hendak kamu gunakan.
+
+///
## Pedoman Pengguna Lanjutan
diff --git a/docs/id/docs/tutorial/path-params.md b/docs/id/docs/tutorial/path-params.md
new file mode 100644
index 000000000..7c24de4d3
--- /dev/null
+++ b/docs/id/docs/tutorial/path-params.md
@@ -0,0 +1,258 @@
+# Parameter Path
+
+"parameter" atau "variabel" path didefinisikan dengan sintaksis Python format string:
+
+{* ../../docs_src/path_params/tutorial001.py hl[6:7] *}
+
+Nilai parameter path `item_id` akan dikirim ke fungsi sebagai argument `item_id`:
+
+Jika anda menjalankan contoh berikut dan kunjungi http://127.0.0.1:8000/items/foo, anda akan melihat respon:
+
+```JSON
+{"item_id":"foo"}
+```
+
+## Parameter path dengan tipe data
+
+Tipe data parameter path bisa didefinisikan di dalam fungsi, menggunakan anotasi tipe data standar Python:
+
+{* ../../docs_src/path_params/tutorial002.py hl[7] *}
+
+Dalam hal ini `item_id` didefinisikan sebagai `int`.
+
+/// check | Periksa
+
+Penyunting kode anda bisa membantu periksa di dalam fungsi seperti pemeriksaan kesalahan, kelengkapan kode, dll.
+
+///
+
+## Konversi data
+
+Jika contoh berikut dijalankan dan diakses browser melalui http://127.0.0.1:8000/items/3, anda akan melihat respon:
+
+```JSON
+{"item_id":3}
+```
+
+/// check | Periksa
+
+Perhatikan nilai fungsi yang diterima (dan dihasilkan) adalah `3`, sebagai `int` di Python, dan bukan string `"3"`.
+
+Sehingga dengan deklarasi tipe data **FastAPI** memberikan request otomatis "parsing".
+
+///
+
+## Validasi Data
+
+Tetapi jika di browser anda akses http://127.0.0.1:8000/items/foo, anda akan melihat pesan kesalahan HTTP:
+
+```JSON
+{
+ "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"
+ }
+ ]
+}
+```
+
+Karena parameter path `item_id` bernilai `"foo"` yang bukan tipe data `int`.
+
+Kesalahan yang sama akan muncul jika menggunakan `float` daripada `int`, seperti di: http://127.0.0.1:8000/items/4.2
+
+/// check | Periksa
+
+Dengan deklarasi tipe data Python, **FastAPI** melakukan validasi data.
+
+Perhatikan kesalahan tersebut juga menjelaskan validasi apa yang tidak sesuai.
+
+Validasi ini sangat membantu ketika mengembangkan dan men-*debug* kode yang berhubungan dengan API anda.
+
+///
+
+## Dokumentasi
+
+Ketika anda membuka browser di http://127.0.0.1:8000/docs, anda melihat dokumentasi API interaktif otomatis berikut:
+
+
+
+/// check | Periksa
+
+Dengan deklarasi tipe data Python yang sama, **FastAPI** membuat dokumentasi interaktif otomatis (terintegrasi Swagger UI).
+
+Perhatikan parameter path dideklarasikan sebagai integer.
+
+///
+
+## Keuntungan basis-standar, dokumentasi alternatif
+
+Karena skema yang dibuat berasal dari standar OpenAPI, maka banyak alat lain yang kompatibel.
+
+Sehingga **FastAPI** menyediakan dokumentasi alternatif (menggunakan ReDoc), yang bisa diakses di http://127.0.0.1:8000/redoc:
+
+
+
+Cara yang sama untuk menggunakan tools kompatibel lainnya. Termasuk alat membuat kode otomatis untuk banyak bahasa.
+
+## Pydantic
+
+Semua validasi data dikerjakan di belakang layar oleh Pydantic, sehingga anda mendapatkan banyak kemudahan. Anda juga tahu proses ini akan ditangani dengan baik.
+
+Anda bisa mendeklarasikan tipe data dengan `str`, `float`, `bool` dan banyak tipe data kompleks lainnya.
+
+Beberapa tipe di atas akan dibahas pada bab berikutnya tutorial ini.
+
+## Urutan berpengaruh
+
+Ketika membuat *operasi path*, anda bisa menghadapi kondisi dimana *path* nya sudah tetap.
+
+Seperti `/users/me`, untuk mendapatkan data user yang sedang aktif.
+
+Kemudian anda bisa memiliki path `/users/{user_id}` untuk mendapatkan data user tertentu melalui user ID.
+
+karena *operasi path* dievaluasi melalui urutan, anda harus memastikan path untuk `/users/me` dideklarasikan sebelum `/user/{user_id}`:
+
+{* ../../docs_src/path_params/tutorial003.py hl[6,11] *}
+
+Sebaliknya, path `/users/{user_id}` juga akan sesuai dengan `/users/me`, "menganggap" menerima parameter `user_id` dengan nilai `"me"`.
+
+Serupa, anda juga tidak bisa mendefinisikan operasi path:
+
+{* ../../docs_src/path_params/tutorial003b.py hl[6,11] *}
+
+Path pertama akan selalu digunakan karena path sesuai dengan yang pertama.
+
+## Nilai terdefinisi
+
+Jika ada *operasi path* yang menerima *parameter path*, tetapi anda ingin nilai valid *parameter path* sudah terdefinisi, anda bisa menggunakan standar Python `Enum`.
+
+### Membuat class `Enum`
+
+Import `Enum` dan buat *sub-class* warisan dari `str` dan `Enum`.
+
+Dengan warisan dari `str` dokumen API mengetahui nilai nya harus berjenis `string` supaya bisa digunakan dengan benar.
+
+Kemudian buat atribut *class* dengan nilai tetap *string* yang benar:
+
+{* ../../docs_src/path_params/tutorial005.py hl[1,6:9] *}
+
+/// info
+
+Enumerasi (atau enum) tersedia di Python sejak versi 3.4.
+
+///
+
+/// tip | Tips
+
+"AlxexNet", "ResNet", dan "LeNet" adalah nama model *Machine Learning*.
+
+///
+
+### Mendeklarasikan *parameter path*
+
+Kemudian buat *parameter path* dengan tipe anotasi menggunakan *class* enum dari (`ModelName`)
+
+{* ../../docs_src/path_params/tutorial005.py hl[16] *}
+
+### Periksa dokumentasi
+
+Karena nilai yang tersedia untuk *parameter path* telah terdefinisi, dokumen interatik bisa memunculkan:
+
+
+
+### Bekerja dengan *enumarasi* Python
+
+Nilai *parameter path* akan menjadi *anggota enumerasi*.
+
+#### Membandingkan *anggota enumerasi*
+
+Anda bisa membandingkan parameter *path* dengan *anggota enumerasi* di enum `ModelName` yang anda buat:
+
+{* ../../docs_src/path_params/tutorial005.py hl[17] *}
+
+#### Mendapatkan *nilai enumerasi*
+
+Anda bisa mendapatkan nilai (`str` dalam kasus ini) menggunakan `model_name.value`, atau secara umum `anggota_enum_anda.value`:
+
+{* ../../docs_src/path_params/tutorial005.py hl[20] *}
+
+/// tip | Tips
+
+Anda bisa mengakses nilai `"lenet"` dnegan `ModelName.lenet.value`.
+
+///
+
+#### Menghasilkan *anggota enumerasi*
+
+Anda bisa menghasilkan *anggota enumerasi* dari *operasi path* bahkan di body JSON bersarang (contoh `dict`).
+
+They will be converted to their corresponding values (strings in this case) before returning them to the client:
+
+{* ../../docs_src/path_params/tutorial005.py hl[18,21,23] *}
+
+Klien akan mendapatkan respon JSON seperti berikut:
+
+```JSON
+{
+ "model_name": "alexnet",
+ "message": "Deep Learning FTW!"
+}
+```
+
+## Parameter path berisi path
+
+Misalkan terdapat *operasi path* dengan path `/files/{file_path}`.
+
+Tetapi anda memerlukan `file_path` itu berisi *path*, seperti like `home/johndoe/myfile.txt`.
+
+Sehingga URL untuk file tersebut akan seperti: `/files/home/johndoe/myfile.txt`.
+
+### Dukungan OpenAPI
+
+OpenAPI tidak bisa mendeklarasikan *parameter path* berisi *path* di dalamnya, karena menyebabkan kondisi yang sulit di*test* dan didefinisikan.
+
+Tetapi, di **FastAPI** anda tetap bisa melakukannya dengan menggunakan *tools* internal dari Starlette.
+
+Dan dokumentasi tetap berfungsi walaupun tidak menambahkan keterangan bahwa parameter harus berisi *path*.
+
+### Konverter path
+
+Melalui Starlette anda bisa mendeklarasikan *parameter path* berisi *path* dengan URL seperti:
+
+```
+/files/{file_path:path}
+```
+
+Dikondisi ini nama parameter adalah `file_path` dan bagian terakhir `:path` menginformasikan parameter harus sesuai dengan setiap *path*.
+
+Sehingga anda bisa menggunakan:
+
+{* ../../docs_src/path_params/tutorial004.py hl[6] *}
+
+/// tip | Tips
+
+Anda mungkin perlu parameter berisi `/home/johndoe/myfile.txt` di awali garis belakang (`/`).
+
+Di kondisi ini, URL nya menjadi: `/files//home/johndoe/myfile.txt`, dengan dua garis belakang (`//`) di antara `files` dan `home`.
+
+///
+
+## Ringkasan
+
+Di **FastAPI** dengan menggunakan deklarasi tipe Python standar, pendek, intuitif, anda mendapatkan:
+
+* Dukungan editor: pemeriksaan kesalahan, autocompletion, dll.
+* "Parsing" data.
+* Validasi data.
+* Annotasi API dan dokumentasi otomatis.
+
+Semua itu anda hanya perlu mendeklarasikan sekali saja.
+
+Ini adalah salah satu keunggulan **FastAPI** dibandingkan dengan *framework* lainnya (selain dari performa Python *native*c)
diff --git a/docs/id/docs/tutorial/static-files.md b/docs/id/docs/tutorial/static-files.md
new file mode 100644
index 000000000..b55f31394
--- /dev/null
+++ b/docs/id/docs/tutorial/static-files.md
@@ -0,0 +1,40 @@
+# Berkas Statis
+
+Anda dapat menyajikan berkas statis secara otomatis dari sebuah direktori menggunakan `StaticFiles`.
+
+## Penggunaan `StaticFiles`
+
+* Mengimpor `StaticFiles`.
+* "Mount" representatif `StaticFiles()` di jalur spesifik.
+
+{* ../../docs_src/static_files/tutorial001.py hl[2,6] *}
+
+/// note | Detail Teknis
+
+Anda dapat pula menggunakan `from starlette.staticfiles import StaticFiles`.
+
+**FastAPI** menyediakan `starlette.staticfiles` sama seperti `fastapi.staticfiles` sebagai kemudahan pada Anda, yaitu para pengembang. Tetapi ini asli berasal langsung dari Starlette.
+
+///
+
+### Apa itu "Mounting"
+
+"Mounting" dimaksud menambah aplikasi "independen" secara lengkap di jalur spesifik, kemudian menangani seluruh sub-jalur.
+
+Hal ini berbeda dari menggunakan `APIRouter` karena aplikasi yang dimount benar-benar independen. OpenAPI dan dokumentasi dari aplikasi utama Anda tak akan menyertakan apa pun dari aplikasi yang dimount, dst.
+
+Anda dapat mempelajari mengenai ini dalam [Panduan Pengguna Lanjutan](../advanced/index.md){.internal-link target=_blank}.
+
+## Detail
+
+Terhadap `"/static"` pertama mengacu pada sub-jalur yang akan menjadi tempat "sub-aplikasi" ini akan "dimount". Maka, jalur apa pun yang dimulai dengan `"/static"` akan ditangani oleh sub-jalur tersebut.
+
+Terhadap `directory="static"` mengacu pada nama direktori yang berisi berkas statis Anda.
+
+Terhadap `name="static"` ialah nama yang dapat digunakan secara internal oleh **FastAPI**.
+
+Seluruh parameter ini dapat berbeda dari sekadar "`static`", sesuaikan parameter dengan keperluan dan detail spesifik akan aplikasi Anda.
+
+## Info lanjutan
+
+Sebagai detail dan opsi tambahan lihat dokumentasi Starlette perihal Berkas Statis.
diff --git a/docs/it/docs/index.md b/docs/it/docs/index.md
index 38f611734..dc8f5b846 100644
--- a/docs/it/docs/index.md
+++ b/docs/it/docs/index.md
@@ -1,22 +1,22 @@
-
-{!../../../docs/missing-translation.md!}
-
-
FastAPI framework, alte prestazioni, facile da imparare, rapido da implementare, pronto per il rilascio in produzione
+ @@ -88,7 +88,7 @@ Le sue caratteristiche principali sono: "_Honestly, what you've built looks super solid and polished. In many ways, it's what I wanted **Hug** to be - it's really inspiring to see someone build that._" - + --- @@ -438,7 +438,7 @@ Per approfondire, consulta la sezioneemail_validator - per la validazione di email.
+* email-validator - per la validazione di email.
Usate da Starlette:
diff --git a/docs/ja/docs/advanced/additional-status-codes.md b/docs/ja/docs/advanced/additional-status-codes.md
index d1f8e6451..33457f591 100644
--- a/docs/ja/docs/advanced/additional-status-codes.md
+++ b/docs/ja/docs/advanced/additional-status-codes.md
@@ -14,21 +14,25 @@
これを達成するには、 `JSONResponse` をインポートし、 `status_code` を設定して直接内容を返します。
-```Python hl_lines="4 25"
-{!../../../docs_src/additional_status_codes/tutorial001.py!}
-```
+{* ../../docs_src/additional_status_codes/tutorial001.py hl[4,25] *}
-!!! warning "注意"
- 上記の例のように `Response` を明示的に返す場合、それは直接返されます。
+/// warning | 注意
- モデルなどはシリアライズされません。
+上記の例のように `Response` を明示的に返す場合、それは直接返されます。
- 必要なデータが含まれていることや、値が有効なJSONであること (`JSONResponse` を使う場合) を確認してください。
+モデルなどはシリアライズされません。
-!!! note "技術詳細"
- `from starlette.responses import JSONResponse` を利用することもできます。
+必要なデータが含まれていることや、値が有効なJSONであること (`JSONResponse` を使う場合) を確認してください。
- **FastAPI** は `fastapi.responses` と同じ `starlette.responses` を、開発者の利便性のために提供しています。しかし有効なレスポンスはほとんどStarletteから来ています。 `status` についても同じです。
+///
+
+/// note | 技術詳細
+
+`from starlette.responses import JSONResponse` を利用することもできます。
+
+**FastAPI** は `fastapi.responses` と同じ `starlette.responses` を、開発者の利便性のために提供しています。しかし有効なレスポンスはほとんどStarletteから来ています。 `status` についても同じです。
+
+///
## OpenAPIとAPIドキュメント
diff --git a/docs/ja/docs/advanced/custom-response.md b/docs/ja/docs/advanced/custom-response.md
index d8b47629a..1b2cd914d 100644
--- a/docs/ja/docs/advanced/custom-response.md
+++ b/docs/ja/docs/advanced/custom-response.md
@@ -12,8 +12,11 @@
そしてもし、`Response` が、`JSONResponse` や `UJSONResponse` の場合のようにJSONメディアタイプ (`application/json`) ならば、データは *path operationデコレータ* に宣言したPydantic `response_model` により自動的に変換 (もしくはフィルタ) されます。
-!!! note "備考"
- メディアタイプを指定せずにレスポンスクラスを利用すると、FastAPIは何もコンテンツがないことを期待します。そのため、生成されるOpenAPIドキュメントにレスポンスフォーマットが記載されません。
+/// note | 備考
+
+メディアタイプを指定せずにレスポンスクラスを利用すると、FastAPIは何もコンテンツがないことを期待します。そのため、生成されるOpenAPIドキュメントにレスポンスフォーマットが記載されません。
+
+///
## `ORJSONResponse` を使う
@@ -21,19 +24,23 @@
使いたい `Response` クラス (サブクラス) をインポートし、 *path operationデコレータ* に宣言します。
-```Python hl_lines="2 7"
-{!../../../docs_src/custom_response/tutorial001b.py!}
-```
+{* ../../docs_src/custom_response/tutorial001b.py hl[2,7] *}
-!!! info "情報"
- パラメータ `response_class` は、レスポンスの「メディアタイプ」を定義するために利用することもできます。
+/// info | 情報
- この場合、HTTPヘッダー `Content-Type` には `application/json` がセットされます。
+パラメータ `response_class` は、レスポンスの「メディアタイプ」を定義するために利用することもできます。
- そして、OpenAPIにはそのようにドキュメントされます。
+この場合、HTTPヘッダー `Content-Type` には `application/json` がセットされます。
-!!! tip "豆知識"
- `ORJSONResponse` は、現在はFastAPIのみで利用可能で、Starletteでは利用できません。
+そして、OpenAPIにはそのようにドキュメントされます。
+
+///
+
+/// tip | 豆知識
+
+`ORJSONResponse` は、現在はFastAPIのみで利用可能で、Starletteでは利用できません。
+
+///
## HTMLレスポンス
@@ -42,16 +49,17 @@
* `HTMLResponse` をインポートする。
* *path operation* のパラメータ `content_type` に `HTMLResponse` を渡す。
-```Python hl_lines="2 7"
-{!../../../docs_src/custom_response/tutorial002.py!}
-```
+{* ../../docs_src/custom_response/tutorial002.py hl[2,7] *}
-!!! info "情報"
- パラメータ `response_class` は、レスポンスの「メディアタイプ」を定義するために利用されます。
+/// info | 情報
- この場合、HTTPヘッダー `Content-Type` には `text/html` がセットされます。
+パラメータ `response_class` は、レスポンスの「メディアタイプ」を定義するために利用されます。
- そして、OpenAPIにはそのようにドキュメント化されます。
+この場合、HTTPヘッダー `Content-Type` には `text/html` がセットされます。
+
+そして、OpenAPIにはそのようにドキュメント化されます。
+
+///
### `Response` を返す
@@ -59,15 +67,19 @@
上記と同じ例において、 `HTMLResponse` を返すと、このようになります:
-```Python hl_lines="2 7 19"
-{!../../../docs_src/custom_response/tutorial003.py!}
-```
+{* ../../docs_src/custom_response/tutorial003.py hl[2,7,19] *}
-!!! warning "注意"
- *path operation関数* から直接返される `Response` は、OpenAPIにドキュメントされず (例えば、 `Content-Type` がドキュメントされない) 、自動的な対話的ドキュメントからも閲覧できません。
+/// warning | 注意
-!!! info "情報"
- もちろん、実際の `Content-Type` ヘッダーやステータスコードなどは、返された `Response` オブジェクトに由来しています。
+*path operation関数* から直接返される `Response` は、OpenAPIにドキュメントされず (例えば、 `Content-Type` がドキュメントされない) 、自動的な対話的ドキュメントからも閲覧できません。
+
+///
+
+/// info | 情報
+
+もちろん、実際の `Content-Type` ヘッダーやステータスコードなどは、返された `Response` オブジェクトに由来しています。
+
+///
### OpenAPIドキュメントと `Response` のオーバーライド
@@ -79,9 +91,7 @@
例えば、このようになります:
-```Python hl_lines="7 21 23"
-{!../../../docs_src/custom_response/tutorial004.py!}
-```
+{* ../../docs_src/custom_response/tutorial004.py hl[7,21,23] *}
この例では、関数 `generate_html_response()` は、`str` のHTMLを返すのではなく `Response` を生成して返しています。
@@ -97,10 +107,13 @@
`Response` を使って他の何かを返せますし、カスタムのサブクラスも作れることを覚えておいてください。
-!!! note "技術詳細"
- `from starlette.responses import HTMLResponse` も利用できます。
+/// note | 技術詳細
- **FastAPI** は開発者の利便性のために `fastapi.responses` として `starlette.responses` と同じものを提供しています。しかし、利用可能なレスポンスのほとんどはStarletteから直接提供されます。
+`from starlette.responses import HTMLResponse` も利用できます。
+
+**FastAPI** は開発者の利便性のために `fastapi.responses` として `starlette.responses` と同じものを提供しています。しかし、利用可能なレスポンスのほとんどはStarletteから直接提供されます。
+
+///
### `Response`
@@ -117,9 +130,7 @@
FastAPI (実際にはStarlette) は自動的にContent-Lengthヘッダーを含みます。また、media_typeに基づいたContent-Typeヘッダーを含み、テキストタイプのためにcharsetを追加します。
-```Python hl_lines="1 18"
-{!../../../docs_src/response_directly/tutorial002.py!}
-```
+{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
### `HTMLResponse`
@@ -129,9 +140,7 @@ FastAPI (実際にはStarlette) は自動的にContent-Lengthヘッダーを含
テキストやバイトを受け取り、プレーンテキストのレスポンスを返します。
-```Python hl_lines="2 7 9"
-{!../../../docs_src/custom_response/tutorial005.py!}
-```
+{* ../../docs_src/custom_response/tutorial005.py hl[2,7,9] *}
### `JSONResponse`
@@ -147,31 +156,31 @@ FastAPI (実際にはStarlette) は自動的にContent-Lengthヘッダーを含
`ujson`を使った、代替のJSONレスポンスです。
-!!! warning "注意"
- `ujson` は、いくつかのエッジケースの取り扱いについて、Pythonにビルトインされた実装よりも作りこまれていません。
+/// warning | 注意
-```Python hl_lines="2 7"
-{!../../../docs_src/custom_response/tutorial001.py!}
-```
+`ujson` は、いくつかのエッジケースの取り扱いについて、Pythonにビルトインされた実装よりも作りこまれていません。
-!!! tip "豆知識"
- `ORJSONResponse` のほうが高速な代替かもしれません。
+///
+
+{* ../../docs_src/custom_response/tutorial001.py hl[2,7] *}
+
+/// tip | 豆知識
+
+`ORJSONResponse` のほうが高速な代替かもしれません。
+
+///
### `RedirectResponse`
HTTPリダイレクトを返します。デフォルトでは307ステータスコード (Temporary Redirect) となります。
-```Python hl_lines="2 9"
-{!../../../docs_src/custom_response/tutorial006.py!}
-```
+{* ../../docs_src/custom_response/tutorial006.py hl[2,9] *}
### `StreamingResponse`
非同期なジェネレータか通常のジェネレータ・イテレータを受け取り、レスポンスボディをストリームします。
-```Python hl_lines="2 14"
-{!../../../docs_src/custom_response/tutorial007.py!}
-```
+{* ../../docs_src/custom_response/tutorial007.py hl[2,14] *}
#### `StreamingResponse` をファイルライクなオブジェクトとともに使う
@@ -179,12 +188,13 @@ HTTPリダイレクトを返します。デフォルトでは307ステータス
これにはクラウドストレージとの連携や映像処理など、多くのライブラリが含まれています。
-```Python hl_lines="2 10-12 14"
-{!../../../docs_src/custom_response/tutorial008.py!}
-```
+{* ../../docs_src/custom_response/tutorial008.py hl[2,10:12,14] *}
-!!! tip "豆知識"
- ここでは `async` や `await` をサポートしていない標準の `open()` を使っているので、通常の `def` でpath operationを宣言していることに注意してください。
+/// tip | 豆知識
+
+ここでは `async` や `await` をサポートしていない標準の `open()` を使っているので、通常の `def` でpath operationを宣言していることに注意してください。
+
+///
### `FileResponse`
@@ -199,9 +209,7 @@ HTTPリダイレクトを返します。デフォルトでは307ステータス
ファイルレスポンスには、適切な `Content-Length` 、 `Last-Modified` 、 `ETag` ヘッダーが含まれます。
-```Python hl_lines="2 10"
-{!../../../docs_src/custom_response/tutorial009.py!}
-```
+{* ../../docs_src/custom_response/tutorial009.py hl[2,10] *}
## デフォルトレスポンスクラス
@@ -211,12 +219,13 @@ HTTPリダイレクトを返します。デフォルトでは307ステータス
以下の例では、 **FastAPI** は、全ての *path operation* で `JSONResponse` の代わりに `ORJSONResponse` をデフォルトとして利用します。
-```Python hl_lines="2 4"
-{!../../../docs_src/custom_response/tutorial010.py!}
-```
+{* ../../docs_src/custom_response/tutorial010.py hl[2,4] *}
-!!! tip "豆知識"
- 前に見たように、 *path operation* の中で `response_class` をオーバーライドできます。
+/// tip | 豆知識
+
+前に見たように、 *path operation* の中で `response_class` をオーバーライドできます。
+
+///
## その他のドキュメント
diff --git a/docs/ja/docs/advanced/index.md b/docs/ja/docs/advanced/index.md
index 2d60e7489..22eaf6eb8 100644
--- a/docs/ja/docs/advanced/index.md
+++ b/docs/ja/docs/advanced/index.md
@@ -6,10 +6,13 @@
以降のセクションでは、チュートリアルでは説明しきれなかったオプションや設定、および機能について説明します。
-!!! tip "豆知識"
- 以降のセクションは、 **必ずしも"応用編"ではありません**。
+/// tip | 豆知識
- ユースケースによっては、その中から解決策を見つけられるかもしれません。
+以降のセクションは、 **必ずしも"応用編"ではありません**。
+
+ユースケースによっては、その中から解決策を見つけられるかもしれません。
+
+///
## 先にチュートリアルを読む
diff --git a/docs/ja/docs/advanced/path-operation-advanced-configuration.md b/docs/ja/docs/advanced/path-operation-advanced-configuration.md
index 35b381cae..05188d5b2 100644
--- a/docs/ja/docs/advanced/path-operation-advanced-configuration.md
+++ b/docs/ja/docs/advanced/path-operation-advanced-configuration.md
@@ -2,16 +2,17 @@
## OpenAPI operationId
-!!! warning "注意"
- あなたがOpenAPIの「エキスパート」でなければ、これは必要ないかもしれません。
+/// warning | 注意
+
+あなたがOpenAPIの「エキスパート」でなければ、これは必要ないかもしれません。
+
+///
*path operation* で `operation_id` パラメータを利用することで、OpenAPIの `operationId` を設定できます。
`operation_id` は各オペレーションで一意にする必要があります。
-```Python hl_lines="6"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial001.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial001.py hl[6] *}
### *path operation関数* の名前をoperationIdとして使用する
@@ -19,25 +20,27 @@ APIの関数名を `operationId` として利用したい場合、すべてのAP
そうする場合は、すべての *path operation* を追加した後に行う必要があります。
-```Python hl_lines="2 12-21 24"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial002.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial002.py hl[2,12:21,24] *}
-!!! tip "豆知識"
- `app.openapi()` を手動でコールする場合、その前に`operationId`を更新する必要があります。
+/// tip | 豆知識
-!!! warning "注意"
- この方法をとる場合、各 *path operation関数* が一意な名前である必要があります。
+`app.openapi()` を手動でコールする場合、その前に`operationId`を更新する必要があります。
- それらが異なるモジュール (Pythonファイル) にあるとしてもです。
+///
+
+/// warning | 注意
+
+この方法をとる場合、各 *path operation関数* が一意な名前である必要があります。
+
+それらが異なるモジュール (Pythonファイル) にあるとしてもです。
+
+///
## OpenAPIから除外する
生成されるOpenAPIスキーマ (つまり、自動ドキュメント生成の仕組み) から *path operation* を除外するには、 `include_in_schema` パラメータを `False` にします。
-```Python hl_lines="6"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial003.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial003.py hl[6] *}
## docstringによる説明の高度な設定
@@ -47,6 +50,4 @@ APIの関数名を `operationId` として利用したい場合、すべてのAP
ドキュメントには表示されませんが、他のツール (例えばSphinx) では残りの部分を利用できるでしょう。
-```Python hl_lines="19-29"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial004.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial004.py hl[19:29] *}
diff --git a/docs/ja/docs/advanced/response-directly.md b/docs/ja/docs/advanced/response-directly.md
index 10ec88548..42412d507 100644
--- a/docs/ja/docs/advanced/response-directly.md
+++ b/docs/ja/docs/advanced/response-directly.md
@@ -14,8 +14,11 @@
実際は、`Response` やそのサブクラスを返すことができます。
-!!! tip "豆知識"
- `JSONResponse` それ自体は、 `Response` のサブクラスです。
+/// tip | 豆知識
+
+`JSONResponse` それ自体は、 `Response` のサブクラスです。
+
+///
`Response` を返した場合は、**FastAPI** は直接それを返します。
@@ -31,14 +34,15 @@
このようなケースでは、レスポンスにデータを含める前に `jsonable_encoder` を使ってデータを変換できます。
-```Python hl_lines="6-7 21-22"
-{!../../../docs_src/response_directly/tutorial001.py!}
-```
+{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *}
-!!! note "技術詳細"
- また、`from starlette.responses import JSONResponse` も利用できます。
+/// note | 技術詳細
- **FastAPI** は開発者の利便性のために `fastapi.responses` という `starlette.responses` と同じものを提供しています。しかし、利用可能なレスポンスのほとんどはStarletteから直接提供されます。
+また、`from starlette.responses import JSONResponse` も利用できます。
+
+**FastAPI** は開発者の利便性のために `fastapi.responses` という `starlette.responses` と同じものを提供しています。しかし、利用可能なレスポンスのほとんどはStarletteから直接提供されます。
+
+///
## カスタム `Response` を返す
@@ -50,9 +54,7 @@
XMLを文字列にし、`Response` に含め、それを返します。
-```Python hl_lines="1 18"
-{!../../../docs_src/response_directly/tutorial002.py!}
-```
+{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
## 備考
diff --git a/docs/ja/docs/advanced/websockets.md b/docs/ja/docs/advanced/websockets.md
index 65e4112a6..43009eba8 100644
--- a/docs/ja/docs/advanced/websockets.md
+++ b/docs/ja/docs/advanced/websockets.md
@@ -38,30 +38,27 @@ $ pip install websockets
しかし、これはWebSocketのサーバーサイドに焦点を当て、実用的な例を示す最も簡単な方法です。
-```Python hl_lines="2 6-38 41-43"
-{!../../../docs_src/websockets/tutorial001.py!}
-```
+{* ../../docs_src/websockets/tutorial001.py hl[2,6:38,41:43] *}
## `websocket` を作成する
**FastAPI** アプリケーションで、`websocket` を作成します。
-```Python hl_lines="1 46-47"
-{!../../../docs_src/websockets/tutorial001.py!}
-```
+{* ../../docs_src/websockets/tutorial001.py hl[1,46:47] *}
-!!! note "技術詳細"
- `from starlette.websockets import WebSocket` を使用しても構いません.
+/// note | 技術詳細
- **FastAPI** は開発者の利便性のために、同じ `WebSocket` を提供します。しかし、こちらはStarletteから直接提供されるものです。
+`from starlette.websockets import WebSocket` を使用しても構いません.
+
+**FastAPI** は開発者の利便性のために、同じ `WebSocket` を提供します。しかし、こちらはStarletteから直接提供されるものです。
+
+///
## メッセージの送受信
WebSocketルートでは、 `await` を使ってメッセージの送受信ができます。
-```Python hl_lines="48-52"
-{!../../../docs_src/websockets/tutorial001.py!}
-```
+{* ../../docs_src/websockets/tutorial001.py hl[48:52] *}
バイナリやテキストデータ、JSONデータを送受信できます。
@@ -112,16 +109,17 @@ WebSocketエンドポイントでは、`fastapi` から以下をインポート
これらは、他のFastAPI エンドポイント/*path operation* の場合と同じように機能します。
-```Python hl_lines="58-65 68-83"
-{!../../../docs_src/websockets/tutorial002.py!}
-```
+{* ../../docs_src/websockets/tutorial002.py hl[58:65,68:83] *}
-!!! info "情報"
- WebSocket で `HTTPException` を発生させることはあまり意味がありません。したがって、WebSocketの接続を直接閉じる方がよいでしょう。
+/// info | 情報
- クロージングコードは、仕様で定義された有効なコードの中から使用することができます。
+WebSocket で `HTTPException` を発生させることはあまり意味がありません。したがって、WebSocketの接続を直接閉じる方がよいでしょう。
- 将来的には、どこからでも `raise` できる `WebSocketException` が用意され、専用の例外ハンドラを追加できるようになる予定です。これは、Starlette の PR #527 に依存するものです。
+クロージングコードは、仕様で定義された有効なコードの中から使用することができます。
+
+将来的には、どこからでも `raise` できる `WebSocketException` が用意され、専用の例外ハンドラを追加できるようになる予定です。これは、Starlette の PR #527 に依存するものです。
+
+///
### 依存関係を用いてWebSocketsを試してみる
@@ -144,8 +142,11 @@ $ uvicorn main:app --reload
* パスで使用される「Item ID」
* クエリパラメータとして使用される「Token」
-!!! tip "豆知識"
- クエリ `token` は依存パッケージによって処理されることに注意してください。
+/// tip | 豆知識
+
+クエリ `token` は依存パッケージによって処理されることに注意してください。
+
+///
これにより、WebSocketに接続してメッセージを送受信できます。
@@ -155,9 +156,7 @@ $ uvicorn main:app --reload
WebSocket接続が閉じられると、 `await websocket.receive_text()` は例外 `WebSocketDisconnect` を発生させ、この例のようにキャッチして処理することができます。
-```Python hl_lines="81-83"
-{!../../../docs_src/websockets/tutorial003.py!}
-```
+{* ../../docs_src/websockets/tutorial003.py hl[81:83] *}
試してみるには、
@@ -171,12 +170,15 @@ WebSocket接続が閉じられると、 `await websocket.receive_text()` は例
Client #1596980209979 left the chat
```
-!!! tip "豆知識"
- 上記のアプリは、複数の WebSocket 接続に対してメッセージを処理し、ブロードキャストする方法を示すための最小限のシンプルな例です。
+/// tip | 豆知識
- しかし、すべての接続がメモリ内の単一のリストで処理されるため、プロセスの実行中にのみ機能し、単一のプロセスでのみ機能することに注意してください。
+上記のアプリは、複数の WebSocket 接続に対してメッセージを処理し、ブロードキャストする方法を示すための最小限のシンプルな例です。
- もしFastAPIと簡単に統合できて、RedisやPostgreSQLなどでサポートされている、より堅牢なものが必要なら、encode/broadcaster を確認してください。
+しかし、すべての接続がメモリ内の単一のリストで処理されるため、プロセスの実行中にのみ機能し、単一のプロセスでのみ機能することに注意してください。
+
+もしFastAPIと簡単に統合できて、RedisやPostgreSQLなどでサポートされている、より堅牢なものが必要なら、encode/broadcaster を確認してください。
+
+///
## その他のドキュメント
diff --git a/docs/ja/docs/alternatives.md b/docs/ja/docs/alternatives.md
index ce4b36408..8129a7002 100644
--- a/docs/ja/docs/alternatives.md
+++ b/docs/ja/docs/alternatives.md
@@ -30,11 +30,17 @@ Mozilla、Red Hat、Eventbrite など多くの企業で利用されています
これは**自動的なAPIドキュメント生成**の最初の例であり、これは**FastAPI**に向けた「調査」を触発した最初のアイデアの一つでした。
-!!! note "備考"
- Django REST Framework は Tom Christie によって作成されました。StarletteとUvicornの生みの親であり、**FastAPI**のベースとなっています。
+/// note | 備考
-!!! check "**FastAPI**へ与えたインスピレーション"
- 自動でAPIドキュメントを生成するWebユーザーインターフェースを持っている点。
+Django REST Framework は Tom Christie によって作成されました。StarletteとUvicornの生みの親であり、**FastAPI**のベースとなっています。
+
+///
+
+/// check | **FastAPI**へ与えたインスピレーション
+
+自動でAPIドキュメントを生成するWebユーザーインターフェースを持っている点。
+
+///
### Flask
@@ -50,11 +56,13 @@ Flask は「マイクロフレームワーク」であり、データベース
Flaskのシンプルさを考えると、APIを構築するのに適しているように思えました。次に見つけるべきは、Flask 用の「Django REST Framework」でした。
-!!! check "**FastAPI**へ与えたインスピレーション"
- マイクロフレームワークであること。ツールやパーツを目的に合うように簡単に組み合わせられる点。
+/// check | **FastAPI**へ与えたインスピレーション
- シンプルで簡単なルーティングの仕組みを持っている点。
+マイクロフレームワークであること。ツールやパーツを目的に合うように簡単に組み合わせられる点。
+シンプルで簡単なルーティングの仕組みを持っている点。
+
+///
### Requests
@@ -90,11 +98,13 @@ def read_url():
`requests.get(...)` と`@app.get(...)` には類似点が見受けられます。
-!!! check "**FastAPI**へ与えたインスピレーション"
- * シンプルで直感的なAPIを持っている点。
- * HTTPメソッド名を直接利用し、単純で直感的である。
- * 適切なデフォルト値を持ちつつ、強力なカスタマイズ性を持っている。
+/// check | **FastAPI**へ与えたインスピレーション
+* シンプルで直感的なAPIを持っている点。
+* HTTPメソッド名を直接利用し、単純で直感的である。
+* 適切なデフォルト値を持ちつつ、強力なカスタマイズ性を持っている。
+
+///
### Swagger / OpenAPI
@@ -108,15 +118,18 @@ def read_url():
そのため、バージョン2.0では「Swagger」、バージョン3以上では「OpenAPI」と表記するのが一般的です。
-!!! check "**FastAPI**へ与えたインスピレーション"
- 独自のスキーマの代わりに、API仕様のオープンな標準を採用しました。
+/// check | **FastAPI**へ与えたインスピレーション
- そして、標準に基づくユーザーインターフェースツールを統合しています。
+独自のスキーマの代わりに、API仕様のオープンな標準を採用しました。
- * Swagger UI
- * ReDoc
+そして、標準に基づくユーザーインターフェースツールを統合しています。
- この二つは人気で安定したものとして選択されましたが、少し検索してみると、 (**FastAPI**と同時に使用できる) OpenAPIのための多くの代替となるツールを見つけることができます。
+* Swagger UI
+* ReDoc
+
+この二つは人気で安定したものとして選択されましたが、少し検索してみると、 (**FastAPI**と同時に使用できる) OpenAPIのための多くの代替となるツールを見つけることができます。
+
+///
### Flask REST フレームワーク
@@ -134,8 +147,11 @@ APIが必要とするもう一つの大きな機能はデータのバリデー
しかし、それはPythonの型ヒントが存在する前に作られたものです。そのため、すべてのスキーマを定義するためには、Marshmallowが提供する特定のユーティリティやクラスを使用する必要があります。
-!!! check "**FastAPI**へ与えたインスピレーション"
- コードで「スキーマ」を定義し、データの型やバリデーションを自動で提供する点。
+/// check | **FastAPI**へ与えたインスピレーション
+
+コードで「スキーマ」を定義し、データの型やバリデーションを自動で提供する点。
+
+///
### Webargs
@@ -147,11 +163,17 @@ WebargsはFlaskをはじめとするいくつかのフレームワークの上
素晴らしいツールで、私も**FastAPI**を持つ前はよく使っていました。
-!!! info "情報"
- Webargsは、Marshmallowと同じ開発者により作られました。
+/// info | 情報
-!!! check "**FastAPI**へ与えたインスピレーション"
- 受信したデータに対する自動的なバリデーションを持っている点。
+Webargsは、Marshmallowと同じ開発者により作られました。
+
+///
+
+/// check | **FastAPI**へ与えたインスピレーション
+
+受信したデータに対する自動的なバリデーションを持っている点。
+
+///
### APISpec
@@ -171,11 +193,17 @@ Flask, Starlette, Responderなどにおいてはそのように動作します
エディタでは、この問題を解決することはできません。また、パラメータやMarshmallowスキーマを変更したときに、YAMLのdocstringを変更するのを忘れてしまうと、生成されたスキーマが古くなってしまいます。
-!!! info "情報"
- APISpecは、Marshmallowと同じ開発者により作成されました。
+/// info | 情報
-!!! check "**FastAPI**へ与えたインスピレーション"
- OpenAPIという、APIについてのオープンな標準をサポートしている点。
+APISpecは、Marshmallowと同じ開発者により作成されました。
+
+///
+
+/// check | **FastAPI**へ与えたインスピレーション
+
+OpenAPIという、APIについてのオープンな標準をサポートしている点。
+
+///
### Flask-apispec
@@ -197,11 +225,17 @@ Flask、Flask-apispec、Marshmallow、Webargsの組み合わせは、**FastAPI**
そして、これらのフルスタックジェネレーターは、[**FastAPI** Project Generators](project-generation.md){.internal-link target=_blank}の元となっていました。
-!!! info "情報"
- Flask-apispecはMarshmallowと同じ開発者により作成されました。
+/// info | 情報
-!!! check "**FastAPI**へ与えたインスピレーション"
- シリアライゼーションとバリデーションを定義したコードから、OpenAPIスキーマを自動的に生成する点。
+Flask-apispecはMarshmallowと同じ開発者により作成されました。
+
+///
+
+/// check | **FastAPI**へ与えたインスピレーション
+
+シリアライゼーションとバリデーションを定義したコードから、OpenAPIスキーマを自動的に生成する点。
+
+///
### NestJS (とAngular)
@@ -217,24 +251,33 @@ Angular 2にインスピレーションを受けた、統合された依存性
入れ子になったモデルをうまく扱えません。そのため、リクエストのJSONボディが内部フィールドを持つJSONオブジェクトで、それが順番にネストされたJSONオブジェクトになっている場合、適切にドキュメント化やバリデーションをすることができません。
-!!! check "**FastAPI**へ与えたインスピレーション"
- 素晴らしいエディターの補助を得るために、Pythonの型ヒントを利用している点。
+/// check | **FastAPI**へ与えたインスピレーション
- 強力な依存性注入の仕組みを持ち、コードの繰り返しを最小化する方法を見つけた点。
+素晴らしいエディターの補助を得るために、Pythonの型ヒントを利用している点。
+
+強力な依存性注入の仕組みを持ち、コードの繰り返しを最小化する方法を見つけた点。
+
+///
### Sanic
`asyncio`に基づいた、Pythonのフレームワークの中でも非常に高速なものの一つです。Flaskと非常に似た作りになっています。
-!!! note "技術詳細"
- Pythonの`asyncio`ループの代わりに、`uvloop`が利用されています。それにより、非常に高速です。
+/// note | 技術詳細
- `Uvicorn`と`Starlette`に明らかなインスピレーションを与えており、それらは現在オープンなベンチマークにおいてSanicより高速です。
+Pythonの`asyncio`ループの代わりに、`uvloop`が利用されています。それにより、非常に高速です。
-!!! check "**FastAPI**へ与えたインスピレーション"
- 物凄い性能を出す方法を見つけた点。
+`Uvicorn`と`Starlette`に明らかなインスピレーションを与えており、それらは現在オープンなベンチマークにおいてSanicより高速です。
- **FastAPI**が、(サードパーティのベンチマークによりテストされた) 最も高速なフレームワークであるStarletteに基づいている理由です。
+///
+
+/// check | **FastAPI**へ与えたインスピレーション
+
+物凄い性能を出す方法を見つけた点。
+
+**FastAPI**が、(サードパーティのベンチマークによりテストされた) 最も高速なフレームワークであるStarletteに基づいている理由です。
+
+///
### Falcon
@@ -246,12 +289,15 @@ Pythonのウェブフレームワーク標準規格 (WSGI) を使用していま
そのため、データのバリデーション、シリアライゼーション、ドキュメント化は、自動的にできずコードの中で行わなければなりません。あるいは、HugのようにFalconの上にフレームワークとして実装されなければなりません。このような分断は、パラメータとして1つのリクエストオブジェクトと1つのレスポンスオブジェクトを持つというFalconのデザインにインスピレーションを受けた他のフレームワークでも起こります。
-!!! check "**FastAPI**へ与えたインスピレーション"
- 素晴らしい性能を得るための方法を見つけた点。
+/// check | **FastAPI**へ与えたインスピレーション
- Hug (HugはFalconをベースにしています) と一緒に、**FastAPI**が`response`引数を関数に持つことにインスピレーションを与えました。
+素晴らしい性能を得るための方法を見つけた点。
- **FastAPI**では任意ですが、ヘッダーやCookieやステータスコードを設定するために利用されています。
+Hug (HugはFalconをベースにしています) と一緒に、**FastAPI**が`response`引数を関数に持つことにインスピレーションを与えました。
+
+**FastAPI**では任意ですが、ヘッダーやCookieやステータスコードを設定するために利用されています。
+
+///
### Molten
@@ -269,10 +315,13 @@ Pydanticのようなデータのバリデーション、シリアライゼーシ
ルーティングは一つの場所で宣言され、他の場所で宣言された関数を使用します (エンドポイントを扱う関数のすぐ上に配置できるデコレータを使用するのではなく) 。これはFlask (やStarlette) よりも、Djangoに近いです。これは、比較的緊密に結合されているものをコードの中で分離しています。
-!!! check "**FastAPI**へ与えたインスピレーション"
- モデルの属性の「デフォルト」値を使用したデータ型の追加バリデーションを定義します。これはエディタの補助を改善するもので、以前はPydanticでは利用できませんでした。
+/// check | **FastAPI**へ与えたインスピレーション
- 同様の方法でのバリデーションの宣言をサポートするよう、Pydanticを部分的にアップデートするインスピーレションを与えました。(現在はこれらの機能は全てPydanticで可能となっています。)
+モデルの属性の「デフォルト」値を使用したデータ型の追加バリデーションを定義します。これはエディタの補助を改善するもので、以前はPydanticでは利用できませんでした。
+
+同様の方法でのバリデーションの宣言をサポートするよう、Pydanticを部分的にアップデートするインスピーレションを与えました。(現在はこれらの機能は全てPydanticで可能となっています。)
+
+///
### Hug
@@ -288,15 +337,21 @@ OpenAPIやJSON Schemaのような標準に基づいたものではありませ
以前のPythonの同期型Webフレームワーク標準 (WSGI) をベースにしているため、Websocketなどは扱えませんが、それでも高性能です。
-!!! info "情報"
- HugはTimothy Crosleyにより作成されました。彼は`isort`など、Pythonのファイル内のインポートの並び替えを自動的におこうなう素晴らしいツールの開発者です。
+/// info | 情報
-!!! check "**FastAPI**へ与えたインスピレーション"
- HugはAPIStarに部分的なインスピレーションを与えており、私が発見した中ではAPIStarと同様に最も期待の持てるツールの一つでした。
+HugはTimothy Crosleyにより作成されました。彼は`isort`など、Pythonのファイル内のインポートの並び替えを自動的におこうなう素晴らしいツールの開発者です。
- Hugは、**FastAPI**がPythonの型ヒントを用いてパラメータを宣言し自動的にAPIを定義するスキーマを生成することを触発しました。
+///
- Hugは、**FastAPI**がヘッダーやクッキーを設定するために関数に `response`引数を宣言することにインスピレーションを与えました。
+/// check | **FastAPI**へ与えたインスピレーション
+
+HugはAPIStarに部分的なインスピレーションを与えており、私が発見した中ではAPIStarと同様に最も期待の持てるツールの一つでした。
+
+Hugは、**FastAPI**がPythonの型ヒントを用いてパラメータを宣言し自動的にAPIを定義するスキーマを生成することを触発しました。
+
+Hugは、**FastAPI**がヘッダーやクッキーを設定するために関数に `response`引数を宣言することにインスピレーションを与えました。
+
+///
### APIStar (<= 0.5)
@@ -322,23 +377,29 @@ OpenAPIやJSON Schemaのような標準に基づいたものではありませ
今ではAPIStarはOpenAPI仕様を検証するためのツールセットであり、ウェブフレームワークではありません。
-!!! info "情報"
- APIStarはTom Christieにより開発されました。以下の開発者でもあります:
+/// info | 情報
- * Django REST Framework
- * Starlette (**FastAPI**のベースになっています)
- * Uvicorn (Starletteや**FastAPI**で利用されています)
+APIStarはTom Christieにより開発されました。以下の開発者でもあります:
-!!! check "**FastAPI**へ与えたインスピレーション"
- 存在そのもの。
+* Django REST Framework
+* Starlette (**FastAPI**のベースになっています)
+* Uvicorn (Starletteや**FastAPI**で利用されています)
- 複数の機能 (データのバリデーション、シリアライゼーション、ドキュメント化) を同じPython型で宣言し、同時に優れたエディタの補助を提供するというアイデアは、私にとって素晴らしいアイデアでした。
+///
- そして、長い間同じようなフレームワークを探し、多くの異なる代替ツールをテストした結果、APIStarが最良の選択肢となりました。
+/// check | **FastAPI**へ与えたインスピレーション
- その後、APIStarはサーバーとして存在しなくなり、Starletteが作られ、そのようなシステムのための新しくより良い基盤となりました。これが**FastAPI**を構築するための最終的なインスピレーションでした。
+存在そのもの。
- 私は、これまでのツールから学んだことをもとに、機能や型システムなどの部分を改善・拡充しながら、**FastAPI**をAPIStarの「精神的な後継者」と考えています。
+複数の機能 (データのバリデーション、シリアライゼーション、ドキュメント化) を同じPython型で宣言し、同時に優れたエディタの補助を提供するというアイデアは、私にとって素晴らしいアイデアでした。
+
+そして、長い間同じようなフレームワークを探し、多くの異なる代替ツールをテストした結果、APIStarが最良の選択肢となりました。
+
+その後、APIStarはサーバーとして存在しなくなり、Starletteが作られ、そのようなシステムのための新しくより良い基盤となりました。これが**FastAPI**を構築するための最終的なインスピレーションでした。
+
+私は、これまでのツールから学んだことをもとに、機能や型システムなどの部分を改善・拡充しながら、**FastAPI**をAPIStarの「精神的な後継者」と考えています。
+
+///
## **FastAPI**が利用しているもの
@@ -350,10 +411,13 @@ Pydanticは、Pythonの型ヒントを元にデータのバリデーション、
Marshmallowに匹敵しますが、ベンチマークではMarshmallowよりも高速です。また、Pythonの型ヒントを元にしているので、エディタの補助が素晴らしいです。
-!!! check "**FastAPI**での使用用途"
- データのバリデーション、データのシリアライゼーション、自動的なモデルの (JSON Schemaに基づいた) ドキュメント化の全てを扱えます。
+/// check | **FastAPI**での使用用途
- **FastAPI**はJSON SchemaのデータをOpenAPIに利用します。
+データのバリデーション、データのシリアライゼーション、自動的なモデルの (JSON Schemaに基づいた) ドキュメント化の全てを扱えます。
+
+**FastAPI**はJSON SchemaのデータをOpenAPIに利用します。
+
+///
### Starlette
@@ -383,17 +447,23 @@ Starletteは基本的なWebマイクロフレームワークの機能をすべ
これは **FastAPI** が追加する主な機能の一つで、すべての機能は Pythonの型ヒントに基づいています (Pydanticを使用しています) 。これに加えて、依存性注入の仕組み、セキュリティユーティリティ、OpenAPIスキーマ生成などがあります。
-!!! note "技術詳細"
- ASGIはDjangoのコアチームメンバーにより開発された新しい「標準」です。まだ「Pythonの標準 (PEP) 」ではありませんが、現在そうなるように進めています。
+/// note | 技術詳細
- しかしながら、いくつかのツールにおいてすでに「標準」として利用されています。このことは互換性を大きく改善するもので、Uvicornから他のASGIサーバー (DaphneやHypercorn) に乗り換えることができたり、あなたが`python-socketio`のようなASGI互換のツールを追加することもできます。
+ASGIはDjangoのコアチームメンバーにより開発された新しい「標準」です。まだ「Pythonの標準 (PEP) 」ではありませんが、現在そうなるように進めています。
-!!! check "**FastAPI**での使用用途"
- webに関するコアな部分を全て扱います。その上に機能を追加します。
+しかしながら、いくつかのツールにおいてすでに「標準」として利用されています。このことは互換性を大きく改善するもので、Uvicornから他のASGIサーバー (DaphneやHypercorn) に乗り換えることができたり、あなたが`python-socketio`のようなASGI互換のツールを追加することもできます。
- `FastAPI`クラスそのものは、`Starlette`クラスを直接継承しています。
+///
- 基本的にはStarletteの強化版であるため、Starletteで可能なことは**FastAPI**で直接可能です。
+/// check | **FastAPI**での使用用途
+
+webに関するコアな部分を全て扱います。その上に機能を追加します。
+
+`FastAPI`クラスそのものは、`Starlette`クラスを直接継承しています。
+
+基本的にはStarletteの強化版であるため、Starletteで可能なことは**FastAPI**で直接可能です。
+
+///
### Uvicorn
@@ -403,12 +473,15 @@ Uvicornは非常に高速なASGIサーバーで、uvloopとhttptoolsにより構
Starletteや**FastAPI**のサーバーとして推奨されています。
-!!! check "**FastAPI**が推奨する理由"
- **FastAPI**アプリケーションを実行するメインのウェブサーバーである点。
+/// check | **FastAPI**が推奨する理由
- Gunicornと組み合わせることで、非同期でマルチプロセスなサーバーを持つことがきます。
+**FastAPI**アプリケーションを実行するメインのウェブサーバーである点。
- 詳細は[デプロイ](deployment/index.md){.internal-link target=_blank}の項目で確認してください。
+Gunicornと組み合わせることで、非同期でマルチプロセスなサーバーを持つことがきます。
+
+詳細は[デプロイ](deployment/index.md){.internal-link target=_blank}の項目で確認してください。
+
+///
## ベンチマーク と スピード
diff --git a/docs/ja/docs/async.md b/docs/ja/docs/async.md
index 5e38d1cec..d1da1f82d 100644
--- a/docs/ja/docs/async.md
+++ b/docs/ja/docs/async.md
@@ -21,8 +21,11 @@ async def read_results():
return results
```
-!!! note "備考"
- `async def` を使用して作成された関数の内部でしか `await` は使用できません。
+/// note | 備考
+
+`async def` を使用して作成された関数の内部でしか `await` は使用できません。
+
+///
---
@@ -355,12 +358,15 @@ async def read_burgers():
## 非常に発展的な技術的詳細
-!!! warning "注意"
- 恐らくスキップしても良いでしょう。
+/// warning | 注意
- この部分は**FastAPI**の仕組みに関する非常に技術的な詳細です。
+恐らくスキップしても良いでしょう。
- かなりの技術知識 (コルーチン、スレッド、ブロッキングなど) があり、FastAPIが `async def` と通常の `def` をどのように処理するか知りたい場合は、先に進んでください。
+この部分は**FastAPI**の仕組みに関する非常に技術的な詳細です。
+
+かなりの技術知識 (コルーチン、スレッド、ブロッキングなど) があり、FastAPIが `async def` と通常の `def` をどのように処理するか知りたい場合は、先に進んでください。
+
+///
### Path operation 関数
diff --git a/docs/ja/docs/contributing.md b/docs/ja/docs/contributing.md
deleted file mode 100644
index be8e9280e..000000000
--- a/docs/ja/docs/contributing.md
+++ /dev/null
@@ -1,470 +0,0 @@
-# 開発 - 貢献
-
-まず、[FastAPIを応援 - ヘルプの入手](help-fastapi.md){.internal-link target=_blank}の基本的な方法を見て、ヘルプを得た方がいいかもしれません。
-
-## 開発
-
-すでにリポジトリをクローンし、コードを詳しく調べる必要があるとわかっている場合に、環境構築のためのガイドラインをいくつか紹介します。
-
-### `venv`を使用した仮想環境
-
-Pythonの`venv`モジュールを使用して、ディレクトリに仮想環境を作成します:
-
-email_validator - E メールの検証
+- email-validator - E メールの検証
Starlette によって使用されるもの:
diff --git a/docs/ja/docs/learn/index.md b/docs/ja/docs/learn/index.md
new file mode 100644
index 000000000..2f24c670a
--- /dev/null
+++ b/docs/ja/docs/learn/index.md
@@ -0,0 +1,5 @@
+# 学習
+
+ここでは、**FastAPI** を学習するための入門セクションとチュートリアルを紹介します。
+
+これは、FastAPIを学習するにあたっての**書籍**や**コース**であり、**公式**かつ推奨される方法とみなすことができます 😎
diff --git a/docs/ja/docs/python-types.md b/docs/ja/docs/python-types.md
index f8e02fdc3..a847ce5d5 100644
--- a/docs/ja/docs/python-types.md
+++ b/docs/ja/docs/python-types.md
@@ -12,16 +12,18 @@
しかしたとえまったく **FastAPI** を使用しない場合でも、それらについて少し学ぶことで利点を得ることができるでしょう。
-!!! note "備考"
- もしあなたがPythonの専門家で、すでに型ヒントについてすべて知っているのであれば、次の章まで読み飛ばしてください。
+/// note | 備考
+
+もしあなたがPythonの専門家で、すでに型ヒントについてすべて知っているのであれば、次の章まで読み飛ばしてください。
+
+///
## 動機
簡単な例から始めてみましょう:
-```Python
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py *}
+
このプログラムを実行すると以下が出力されます:
@@ -35,9 +37,8 @@ John Doe
* `title()`を用いて、それぞれの最初の文字を大文字に変換します。
* 真ん中にスペースを入れて連結します。
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py hl[2] *}
+
### 編集
@@ -79,9 +80,8 @@ John Doe
それが「型ヒント」です:
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial002.py!}
-```
+{* ../../docs_src/python_types/tutorial002.py hl[1] *}
+
これは、以下のようにデフォルト値を宣言するのと同じではありません:
@@ -109,9 +109,8 @@ John Doe
この関数を見てください。すでに型ヒントを持っています:
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial003.py!}
-```
+{* ../../docs_src/python_types/tutorial003.py hl[1] *}
+
エディタは変数の型を知っているので、補完だけでなく、エラーチェックをすることもできます。
@@ -119,9 +118,8 @@ John Doe
これで`age`を`str(age)`で文字列に変換して修正する必要があることがわかります:
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial004.py!}
-```
+{* ../../docs_src/python_types/tutorial004.py hl[2] *}
+
## 型の宣言
@@ -140,9 +138,8 @@ John Doe
* `bool`
* `bytes`
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial005.py!}
-```
+{* ../../docs_src/python_types/tutorial005.py hl[1] *}
+
### 型パラメータを持つジェネリック型
@@ -158,9 +155,8 @@ John Doe
`typing`から`List`をインポートします(大文字の`L`を含む):
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial006.py!}
-```
+{* ../../docs_src/python_types/tutorial006.py hl[1] *}
+
同じようにコロン(`:`)の構文で変数を宣言します。
@@ -168,14 +164,16 @@ John Doe
リストはいくつかの内部の型を含む型なので、それらを角括弧で囲んでいます。
-```Python hl_lines="4"
-{!../../../docs_src/python_types/tutorial006.py!}
-```
+{* ../../docs_src/python_types/tutorial006.py hl[4] *}
-!!! tip "豆知識"
- 角括弧内の内部の型は「型パラメータ」と呼ばれています。
- この場合、`str`は`List`に渡される型パラメータです。
+/// tip | 豆知識
+
+角括弧内の内部の型は「型パラメータ」と呼ばれています。
+
+この場合、`str`は`List`に渡される型パラメータです。
+
+///
つまり: 変数`items`は`list`であり、このリストの各項目は`str`です。
@@ -193,9 +191,8 @@ John Doe
`tuple`と`set`の宣言も同様です:
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial007.py!}
-```
+{* ../../docs_src/python_types/tutorial007.py hl[1,4] *}
+
つまり:
@@ -211,9 +208,8 @@ John Doe
2番目の型パラメータは`dict`の値です。
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial008.py!}
-```
+{* ../../docs_src/python_types/tutorial008.py hl[1,4] *}
+
つまり:
@@ -226,7 +222,7 @@ John Doe
また、`Optional`を使用して、変数が`str`のような型を持つことを宣言することもできますが、それは「オプション」であり、`None`にすることもできます。
```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial009.py!}
+{!../../docs_src/python_types/tutorial009.py!}
```
ただの`str`の代わりに`Optional[str]`を使用することで、エディタは値が常に`str`であると仮定している場合に実際には`None`である可能性があるエラーを検出するのに役立ちます。
@@ -250,15 +246,13 @@ John Doe
例えば、`Person`クラスという名前のクラスがあるとしましょう:
-```Python hl_lines="1 2 3"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[1,2,3] *}
+
変数の型を`Person`として宣言することができます:
-```Python hl_lines="6"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[6] *}
+
そして、再び、すべてのエディタのサポートを得ることができます:
@@ -278,12 +272,14 @@ John Doe
Pydanticの公式ドキュメントから引用:
-```Python
-{!../../../docs_src/python_types/tutorial011.py!}
-```
+{* ../../docs_src/python_types/tutorial011.py *}
-!!! info "情報"
- Pydanticについてより学びたい方はドキュメントを参照してください.
+
+/// info | 情報
+
+Pydanticについてより学びたい方はドキュメントを参照してください.
+
+///
**FastAPI** はすべてPydanticをベースにしています。
@@ -311,5 +307,8 @@ Pydanticの公式ドキュメントから引用:
重要なのは、Pythonの標準的な型を使うことで、(クラスやデコレータなどを追加するのではなく)1つの場所で **FastAPI** が多くの作業を代わりにやってくれているということです。
-!!! info "情報"
- すでにすべてのチュートリアルを終えて、型についての詳細を見るためにこのページに戻ってきた場合は、`mypy`のチートシートを参照してください
+/// info | 情報
+
+すでにすべてのチュートリアルを終えて、型についての詳細を見るためにこのページに戻ってきた場合は、`mypy`のチートシートを参照してください
+
+///
diff --git a/docs/ja/docs/tutorial/background-tasks.md b/docs/ja/docs/tutorial/background-tasks.md
index 6094c370f..650a079fb 100644
--- a/docs/ja/docs/tutorial/background-tasks.md
+++ b/docs/ja/docs/tutorial/background-tasks.md
@@ -15,9 +15,7 @@
まず初めに、`BackgroundTasks` をインポートし、` BackgroundTasks` の型宣言と共に、*path operation 関数* のパラメーターを定義します:
-```Python hl_lines="1 13"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *}
**FastAPI** は、`BackgroundTasks` 型のオブジェクトを作成し、そのパラメーターに渡します。
@@ -33,17 +31,13 @@
また、書き込み操作では `async` と `await` を使用しないため、通常の `def` で関数を定義します。
-```Python hl_lines="6-9"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *}
## バックグラウンドタスクの追加
*path operations 関数* 内で、`.add_task()` メソッドを使用してタスク関数を *background tasks* オブジェクトに渡します。
-```Python hl_lines="14"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[14] *}
`.add_task()` は以下の引数を受け取ります:
@@ -57,9 +51,7 @@
**FastAPI** は、それぞれの場合の処理方法と同じオブジェクトの再利用方法を知っているため、すべてのバックグラウンドタスクがマージされ、バックグラウンドで後で実行されます。
-```Python hl_lines="13 15 22 25"
-{!../../../docs_src/background_tasks/tutorial002.py!}
-```
+{* ../../docs_src/background_tasks/tutorial002.py hl[13,15,22,25] *}
この例では、レスポンスが送信された *後* にメッセージが `log.txt` ファイルに書き込まれます。
@@ -85,8 +77,6 @@
これらは、より複雑な構成、RabbitMQ や Redis などのメッセージ/ジョブキューマネージャーを必要とする傾向がありますが、複数のプロセス、特に複数のサーバーでバックグラウンドタスクを実行できます。
-例を確認するには、[Project Generators](../project-generation.md){.internal-link target=_blank} を参照してください。これらにはすべて、Celery が構築済みです。
-
ただし、同じ **FastAPI** アプリから変数とオブジェクトにアクセスする必要がある場合、または小さなバックグラウンドタスク (電子メール通知の送信など) を実行する必要がある場合は、単に `BackgroundTasks` を使用できます。
## まとめ
diff --git a/docs/ja/docs/tutorial/body-fields.md b/docs/ja/docs/tutorial/body-fields.md
index 8f01e8216..ce5630351 100644
--- a/docs/ja/docs/tutorial/body-fields.md
+++ b/docs/ja/docs/tutorial/body-fields.md
@@ -6,40 +6,45 @@
まず、以下のようにインポートします:
-```Python hl_lines="4"
-{!../../../docs_src/body_fields/tutorial001.py!}
-```
+{* ../../docs_src/body_fields/tutorial001.py hl[4] *}
-!!! warning "注意"
- `Field`は他の全てのもの(`Query`、`Path`、`Body`など)とは違い、`fastapi`からではなく、`pydantic`から直接インポートされていることに注意してください。
+/// warning | 注意
+
+`Field`は他の全てのもの(`Query`、`Path`、`Body`など)とは違い、`fastapi`からではなく、`pydantic`から直接インポートされていることに注意してください。
+
+///
## モデルの属性の宣言
以下のように`Field`をモデルの属性として使用することができます:
-```Python hl_lines="11 12 13 14"
-{!../../../docs_src/body_fields/tutorial001.py!}
-```
+{* ../../docs_src/body_fields/tutorial001.py hl[11,12,13,14] *}
`Field`は`Query`や`Path`、`Body`と同じように動作し、全く同様のパラメータなどを持ちます。
-!!! note "技術詳細"
- 実際には次に見る`Query`や`Path`などは、共通の`Param`クラスのサブクラスのオブジェクトを作成しますが、それ自体はPydanticの`FieldInfo`クラスのサブクラスです。
+/// note | 技術詳細
- また、Pydanticの`Field`は`FieldInfo`のインスタンスも返します。
+実際には次に見る`Query`や`Path`などは、共通の`Param`クラスのサブクラスのオブジェクトを作成しますが、それ自体はPydanticの`FieldInfo`クラスのサブクラスです。
- `Body`は`FieldInfo`のサブクラスのオブジェクトを直接返すこともできます。そして、他にも`Body`クラスのサブクラスであるものがあります。
+また、Pydanticの`Field`は`FieldInfo`のインスタンスも返します。
- `fastapi`から`Query`や`Path`などをインポートする場合、これらは実際には特殊なクラスを返す関数であることに注意してください。
+`Body`は`FieldInfo`のサブクラスのオブジェクトを直接返すこともできます。そして、他にも`Body`クラスのサブクラスであるものがあります。
-!!! tip "豆知識"
- 型、デフォルト値、`Field`を持つ各モデルの属性が、`Path`や`Query`、`Body`の代わりに`Field`を持つ、*path operation 関数の*パラメータと同じ構造になっていることに注目してください。
+`fastapi`から`Query`や`Path`などをインポートする場合、これらは実際には特殊なクラスを返す関数であることに注意してください。
+
+///
+
+/// tip | 豆知識
+
+型、デフォルト値、`Field`を持つ各モデルの属性が、`Path`や`Query`、`Body`の代わりに`Field`を持つ、*path operation 関数の*パラメータと同じ構造になっていることに注目してください。
+
+///
## 追加情報の追加
追加情報は`Field`や`Query`、`Body`などで宣言することができます。そしてそれは生成されたJSONスキーマに含まれます。
-後に例を用いて宣言を学ぶ際に、追加情報を句悪方法を学べます。
+後に例を用いて宣言を学ぶ際に、追加情報を追加する方法を学べます。
## まとめ
diff --git a/docs/ja/docs/tutorial/body-multiple-params.md b/docs/ja/docs/tutorial/body-multiple-params.md
index 2ba10c583..cbfdda4b2 100644
--- a/docs/ja/docs/tutorial/body-multiple-params.md
+++ b/docs/ja/docs/tutorial/body-multiple-params.md
@@ -8,12 +8,13 @@
また、デフォルトの`None`を設定することで、ボディパラメータをオプションとして宣言することもできます:
-```Python hl_lines="19 20 21"
-{!../../../docs_src/body_multiple_params/tutorial001.py!}
-```
+{* ../../docs_src/body_multiple_params/tutorial001.py hl[19,20,21] *}
-!!! note "備考"
- この場合、ボディから取得する`item`はオプションであることに注意してください。デフォルト値は`None`です。
+/// note | 備考
+
+この場合、ボディから取得する`item`はオプションであることに注意してください。デフォルト値は`None`です。
+
+///
## 複数のボディパラメータ
@@ -30,9 +31,7 @@
しかし、`item`と`user`のように複数のボディパラメータを宣言することもできます:
-```Python hl_lines="22"
-{!../../../docs_src/body_multiple_params/tutorial002.py!}
-```
+{* ../../docs_src/body_multiple_params/tutorial002.py hl[22] *}
この場合、**FastAPI**は関数内に複数のボディパラメータ(Pydanticモデルである2つのパラメータ)があることに気付きます。
@@ -53,8 +52,11 @@
}
```
-!!! note "備考"
- 以前と同じように`item`が宣言されていたにもかかわらず、`item`はキー`item`を持つボディの内部にあることが期待されていることに注意してください。
+/// note | 備考
+
+以前と同じように`item`が宣言されていたにもかかわらず、`item`はキー`item`を持つボディの内部にあることが期待されていることに注意してください。
+
+///
**FastAPI** はリクエストから自動で変換を行い、パラメータ`item`が特定の内容を受け取り、`user`も同じように特定の内容を受け取ります。
@@ -71,9 +73,7 @@
しかし、`Body`を使用して、**FastAPI** に別のボディキーとして扱うように指示することができます:
-```Python hl_lines="23"
-{!../../../docs_src/body_multiple_params/tutorial003.py!}
-```
+{* ../../docs_src/body_multiple_params/tutorial003.py hl[23] *}
この場合、**FastAPI** は以下のようなボディを期待します:
@@ -108,13 +108,13 @@ q: str = None
以下において:
-```Python hl_lines="27"
-{!../../../docs_src/body_multiple_params/tutorial004.py!}
-```
+{* ../../docs_src/body_multiple_params/tutorial004.py hl[27] *}
-!!! info "情報"
- `Body`もまた、後述する `Query` や `Path` などと同様に、すべての検証パラメータとメタデータパラメータを持っています。
+/// info | 情報
+`Body`もまた、後述する `Query` や `Path` などと同様に、すべての検証パラメータとメタデータパラメータを持っています。
+
+///
## 単一のボディパラメータの埋め込み
@@ -130,9 +130,7 @@ item: Item = Body(..., embed=True)
以下において:
-```Python hl_lines="17"
-{!../../../docs_src/body_multiple_params/tutorial005.py!}
-```
+{* ../../docs_src/body_multiple_params/tutorial005.py hl[17] *}
この場合、**FastAPI** は以下のようなボディを期待します:
diff --git a/docs/ja/docs/tutorial/body-nested-models.md b/docs/ja/docs/tutorial/body-nested-models.md
index 092e25798..a1680d10f 100644
--- a/docs/ja/docs/tutorial/body-nested-models.md
+++ b/docs/ja/docs/tutorial/body-nested-models.md
@@ -6,9 +6,7 @@
属性をサブタイプとして定義することができます。例えば、Pythonの`list`は以下のように定義できます:
-```Python hl_lines="12"
-{!../../../docs_src/body_nested_models/tutorial001.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial001.py hl[12] *}
これにより、各項目の型は宣言されていませんが、`tags`はある項目のリストになります。
@@ -20,9 +18,7 @@
まず、Pythonの標準の`typing`モジュールから`List`をインポートします:
-```Python hl_lines="1"
-{!../../../docs_src/body_nested_models/tutorial002.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *}
### タイプパラメータを持つ`List`の宣言
@@ -43,9 +39,7 @@ my_list: List[str]
そのため、以下の例では`tags`を具体的な「文字列のリスト」にすることができます:
-```Python hl_lines="14"
-{!../../../docs_src/body_nested_models/tutorial002.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial002.py hl[14] *}
## セット型
@@ -55,9 +49,7 @@ my_list: List[str]
そのため、以下のように、`Set`をインポートして`str`の`set`として`tags`を宣言することができます:
-```Python hl_lines="1 14"
-{!../../../docs_src/body_nested_models/tutorial003.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial003.py hl[1,14] *}
これを使えば、データが重複しているリクエストを受けた場合でも、ユニークな項目のセットに変換されます。
@@ -79,17 +71,13 @@ Pydanticモデルの各属性には型があります。
例えば、`Image`モデルを定義することができます:
-```Python hl_lines="9 10 11"
-{!../../../docs_src/body_nested_models/tutorial004.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial004.py hl[9,10,11] *}
### サブモデルを型として使用
そして、それを属性の型として使用することができます:
-```Python hl_lines="20"
-{!../../../docs_src/body_nested_models/tutorial004.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial004.py hl[20] *}
これは **FastAPI** が以下のようなボディを期待することを意味します:
@@ -122,9 +110,7 @@ Pydanticモデルの各属性には型があります。
例えば、`Image`モデルのように`url`フィールドがある場合、`str`の代わりにPydanticの`HttpUrl`を指定することができます:
-```Python hl_lines="4 10"
-{!../../../docs_src/body_nested_models/tutorial005.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial005.py hl[4,10] *}
文字列は有効なURLであることが確認され、そのようにJSONスキーマ・OpenAPIで文書化されます。
@@ -132,9 +118,7 @@ Pydanticモデルの各属性には型があります。
Pydanticモデルを`list`や`set`などのサブタイプとして使用することもできます:
-```Python hl_lines="20"
-{!../../../docs_src/body_nested_models/tutorial006.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial006.py hl[20] *}
これは、次のようなJSONボディを期待します(変換、検証、ドキュメントなど):
@@ -162,19 +146,23 @@ Pydanticモデルを`list`や`set`などのサブタイプとして使用する
}
```
-!!! info "情報"
- `images`キーが画像オブジェクトのリストを持つようになったことに注目してください。
+/// info | 情報
+
+`images`キーが画像オブジェクトのリストを持つようになったことに注目してください。
+
+///
## 深くネストされたモデル
深くネストされた任意のモデルを定義することができます:
-```Python hl_lines="9 14 20 23 27"
-{!../../../docs_src/body_nested_models/tutorial007.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial007.py hl[9,14,20,23,27] *}
-!!! info "情報"
- `Offer`は`Item`のリストであり、オプションの`Image`のリストを持っていることに注目してください。
+/// info | 情報
+
+`Offer`は`Item`のリストであり、オプションの`Image`のリストを持っていることに注目してください。
+
+///
## 純粋なリストのボディ
@@ -186,9 +174,7 @@ images: List[Image]
以下のように:
-```Python hl_lines="15"
-{!../../../docs_src/body_nested_models/tutorial008.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial008.py hl[15] *}
## あらゆる場所でのエディタサポート
@@ -218,18 +204,19 @@ Pydanticモデルではなく、`dict`を直接使用している場合はこの
この場合、`int`のキーと`float`の値を持つものであれば、どんな`dict`でも受け入れることができます:
-```Python hl_lines="15"
-{!../../../docs_src/body_nested_models/tutorial009.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial009.py hl[15] *}
-!!! tip "豆知識"
- JSONはキーとして`str`しかサポートしていないことに注意してください。
+/// tip | 豆知識
- しかしPydanticには自動データ変換機能があります。
+JSONはキーとして`str`しかサポートしていないことに注意してください。
- これは、APIクライアントがキーとして文字列しか送信できなくても、それらの文字列に純粋な整数が含まれている限り、Pydanticが変換して検証することを意味します。
+しかしPydanticには自動データ変換機能があります。
- そして、`weights`として受け取る`dict`は、実際には`int`のキーと`float`の値を持つことになります。
+これは、APIクライアントがキーとして文字列しか送信できなくても、それらの文字列に純粋な整数が含まれている限り、Pydanticが変換して検証することを意味します。
+
+そして、`weights`として受け取る`dict`は、実際には`int`のキーと`float`の値を持つことになります。
+
+///
## まとめ
diff --git a/docs/ja/docs/tutorial/body-updates.md b/docs/ja/docs/tutorial/body-updates.md
index 95d328ec5..ffbe52e1d 100644
--- a/docs/ja/docs/tutorial/body-updates.md
+++ b/docs/ja/docs/tutorial/body-updates.md
@@ -6,9 +6,7 @@
`jsonable_encoder`を用いて、入力データをJSON形式で保存できるデータに変換することができます(例:NoSQLデータベース)。例えば、`datetime`を`str`に変換します。
-```Python hl_lines="30 31 32 33 34 35"
-{!../../../docs_src/body_updates/tutorial001.py!}
-```
+{* ../../docs_src/body_updates/tutorial001.py hl[30,31,32,33,34,35] *}
既存のデータを置き換えるべきデータを受け取るために`PUT`は使用されます。
@@ -34,14 +32,17 @@
つまり、更新したいデータだけを送信して、残りはそのままにしておくことができます。
-!!! note "備考"
- `PATCH`は`PUT`よりもあまり使われておらず、知られていません。
+/// note | 備考
- また、多くのチームは部分的な更新であっても`PUT`だけを使用しています。
+`PATCH`は`PUT`よりもあまり使われておらず、知られていません。
- **FastAPI** はどんな制限も課けていないので、それらを使うのは **自由** です。
+また、多くのチームは部分的な更新であっても`PUT`だけを使用しています。
- しかし、このガイドでは、それらがどのように使用されることを意図しているかを多かれ少なかれ、示しています。
+**FastAPI** はどんな制限も課けていないので、それらを使うのは **自由** です。
+
+しかし、このガイドでは、それらがどのように使用されることを意図しているかを多かれ少なかれ、示しています。
+
+///
### Pydanticの`exclude_unset`パラメータの使用
@@ -53,9 +54,7 @@
これを使うことで、デフォルト値を省略して、設定された(リクエストで送られた)データのみを含む`dict`を生成することができます:
-```Python hl_lines="34"
-{!../../../docs_src/body_updates/tutorial002.py!}
-```
+{* ../../docs_src/body_updates/tutorial002.py hl[34] *}
### Pydanticの`update`パラメータ
@@ -63,9 +62,7 @@
`stored_item_model.copy(update=update_data)`のように:
-```Python hl_lines="35"
-{!../../../docs_src/body_updates/tutorial002.py!}
-```
+{* ../../docs_src/body_updates/tutorial002.py hl[35] *}
### 部分的更新のまとめ
@@ -82,18 +79,22 @@
* データをDBに保存します。
* 更新されたモデルを返します。
-```Python hl_lines="30 31 32 33 34 35 36 37"
-{!../../../docs_src/body_updates/tutorial002.py!}
-```
+{* ../../docs_src/body_updates/tutorial002.py hl[30,31,32,33,34,35,36,37] *}
-!!! tip "豆知識"
- 実際には、HTTPの`PUT`操作でも同じテクニックを使用することができます。
+/// tip | 豆知識
- しかし、これらのユースケースのために作成されたので、ここでの例では`PATCH`を使用しています。
+実際には、HTTPの`PUT`操作でも同じテクニックを使用することができます。
-!!! note "備考"
- 入力モデルがまだ検証されていることに注目してください。
+しかし、これらのユースケースのために作成されたので、ここでの例では`PATCH`を使用しています。
- そのため、すべての属性を省略できる部分的な変更を受け取りたい場合は、すべての属性をオプションとしてマークしたモデルを用意する必要があります(デフォルト値または`None`を使用して)。
+///
- **更新** のためのオプション値がすべて設定されているモデルと、**作成** のための必須値が設定されているモデルを区別するには、[追加モデル](extra-models.md){.internal-link target=_blank}で説明されている考え方を利用することができます。
+/// note | 備考
+
+入力モデルがまだ検証されていることに注目してください。
+
+そのため、すべての属性を省略できる部分的な変更を受け取りたい場合は、すべての属性をオプションとしてマークしたモデルを用意する必要があります(デフォルト値または`None`を使用して)。
+
+**更新** のためのオプション値がすべて設定されているモデルと、**作成** のための必須値が設定されているモデルを区別するには、[追加モデル](extra-models.md){.internal-link target=_blank}で説明されている考え方を利用することができます。
+
+///
diff --git a/docs/ja/docs/tutorial/body.md b/docs/ja/docs/tutorial/body.md
index ccce9484d..8376959d5 100644
--- a/docs/ja/docs/tutorial/body.md
+++ b/docs/ja/docs/tutorial/body.md
@@ -8,20 +8,21 @@ APIはほとんどの場合 **レスポンス** ボディを送らなければ
**リクエスト** ボディを宣言するために Pydantic モデルを使用します。そして、その全てのパワーとメリットを利用します。
-!!! info "情報"
- データを送るには、`POST` (もっともよく使われる)、`PUT`、`DELETE` または `PATCH` を使うべきです。
+/// info | 情報
- GET リクエストでボディを送信することは、仕様では未定義の動作ですが、FastAPI でサポートされており、非常に複雑な(極端な)ユースケースにのみ対応しています。
+データを送るには、`POST` (もっともよく使われる)、`PUT`、`DELETE` または `PATCH` を使うべきです。
- 非推奨なので、Swagger UIを使った対話型のドキュメントにはGETのボディ情報は表示されません。さらに、中継するプロキシが対応していない可能性があります。
+GET リクエストでボディを送信することは、仕様では未定義の動作ですが、FastAPI でサポートされており、非常に複雑な(極端な)ユースケースにのみ対応しています。
+
+非推奨なので、Swagger UIを使った対話型のドキュメントにはGETのボディ情報は表示されません。さらに、中継するプロキシが対応していない可能性があります。
+
+///
## Pydanticの `BaseModel` をインポート
ます初めに、 `pydantic` から `BaseModel` をインポートする必要があります:
-```Python hl_lines="2"
-{!../../../docs_src/body/tutorial001.py!}
-```
+{* ../../docs_src/body/tutorial001.py hl[2] *}
## データモデルの作成
@@ -29,9 +30,7 @@ APIはほとんどの場合 **レスポンス** ボディを送らなければ
すべての属性にpython標準の型を使用します:
-```Python hl_lines="5-9"
-{!../../../docs_src/body/tutorial001.py!}
-```
+{* ../../docs_src/body/tutorial001.py hl[5:9] *}
クエリパラメータの宣言と同様に、モデル属性がデフォルト値をもつとき、必須な属性ではなくなります。それ以外は必須になります。オプショナルな属性にしたい場合は `None` を使用してください。
@@ -59,9 +58,7 @@ APIはほとんどの場合 **レスポンス** ボディを送らなければ
*パスオペレーション* に加えるために、パスパラメータやクエリパラメータと同じ様に宣言します:
-```Python hl_lines="16"
-{!../../../docs_src/body/tutorial001.py!}
-```
+{* ../../docs_src/body/tutorial001.py hl[16] *}
...そして、作成したモデル `Item` で型を宣言します。
@@ -110,24 +107,25 @@ APIはほとんどの場合 **レスポンス** ボディを送らなければ
-!!! tip "豆知識"
- PyCharmエディタを使用している場合は、Pydantic PyCharm Pluginが使用可能です。
+/// tip | 豆知識
- 以下のエディターサポートが強化されます:
+PyCharmエディタを使用している場合は、Pydantic PyCharm Pluginが使用可能です。
- * 自動補完
- * 型チェック
- * リファクタリング
- * 検索
- * インスペクション
+以下のエディターサポートが強化されます:
+
+* 自動補完
+* 型チェック
+* リファクタリング
+* 検索
+* インスペクション
+
+///
## モデルの使用
関数内部で、モデルの全ての属性に直接アクセスできます:
-```Python hl_lines="19"
-{!../../../docs_src/body/tutorial002.py!}
-```
+{* ../../docs_src/body/tutorial002.py hl[19] *}
## リクエストボディ + パスパラメータ
@@ -135,9 +133,7 @@ APIはほとんどの場合 **レスポンス** ボディを送らなければ
**FastAPI** はパスパラメータである関数パラメータは**パスから受け取り**、Pydanticモデルによって宣言された関数パラメータは**リクエストボディから受け取る**ということを認識します。
-```Python hl_lines="15-16"
-{!../../../docs_src/body/tutorial003.py!}
-```
+{* ../../docs_src/body/tutorial003.py hl[15:16] *}
## リクエストボディ + パスパラメータ + クエリパラメータ
@@ -145,9 +141,7 @@ APIはほとんどの場合 **レスポンス** ボディを送らなければ
**FastAPI** はそれぞれを認識し、適切な場所からデータを取得します。
-```Python hl_lines="16"
-{!../../../docs_src/body/tutorial004.py!}
-```
+{* ../../docs_src/body/tutorial004.py hl[16] *}
関数パラメータは以下の様に認識されます:
@@ -155,10 +149,13 @@ APIはほとんどの場合 **レスポンス** ボディを送らなければ
* パラメータが**単数型** (`int`、`float`、`str`、`bool` など)の場合は**クエリ**パラメータとして解釈されます。
* パラメータが **Pydantic モデル**型で宣言された場合、リクエスト**ボディ**として解釈されます。
-!!! note "備考"
- FastAPIは、`= None`があるおかげで、`q`がオプショナルだとわかります。
+/// note | 備考
- `Optional[str]` の`Optional` はFastAPIでは使用されていません(FastAPIは`str`の部分のみ使用します)。しかし、`Optional[str]` はエディタがコードのエラーを見つけるのを助けてくれます。
+FastAPIは、`= None`があるおかげで、`q`がオプショナルだとわかります。
+
+`Optional[str]` の`Optional` はFastAPIでは使用されていません(FastAPIは`str`の部分のみ使用します)。しかし、`Optional[str]` はエディタがコードのエラーを見つけるのを助けてくれます。
+
+///
## Pydanticを使わない方法
diff --git a/docs/ja/docs/tutorial/cookie-param-models.md b/docs/ja/docs/tutorial/cookie-param-models.md
new file mode 100644
index 000000000..8285f44ef
--- /dev/null
+++ b/docs/ja/docs/tutorial/cookie-param-models.md
@@ -0,0 +1,77 @@
+# クッキーパラメータモデル
+
+もし関連する**複数のクッキー**から成るグループがあるなら、それらを宣言するために、**Pydanticモデル**を作成できます。🍪
+
+こうすることで、**複数の場所**で**そのPydanticモデルを再利用**でき、バリデーションやメタデータを、すべてのクッキーパラメータに対して一度に宣言できます。😎
+
+/// note | 備考
+
+この機能は、FastAPIのバージョン `0.115.0` からサポートされています。🤓
+
+///
+
+/// tip | 豆知識
+
+これと同じテクニックは `Query` 、 `Cookie` 、 `Header` にも適用できます。 😎
+
+///
+
+## クッキーにPydanticモデルを使用する
+
+必要な複数の**クッキー**パラメータを**Pydanticモデル**で宣言し、さらに、それを `Cookie` として宣言しましょう:
+
+{* ../../docs_src/cookie_param_models/tutorial001_an_py310.py hl[9:12,16] *}
+
+**FastAPI**は、リクエストの**クッキー**から**それぞれのフィールド**のデータを**抽出**し、定義された**Pydanticモデル**を提供します。
+
+## ドキュメントの確認
+
+対話的APIドキュメントUI `/docs` で、定義されているクッキーを確認できます:
+
+
+kwargsとしても知られています。たとえデフォルト値がなくても。
-```Python hl_lines="8"
-{!../../../docs_src/path_params_numeric_validations/tutorial003.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[8] *}
## 数値の検証: 以上
`Query`と`Path`(、そして後述する他のもの)を用いて、文字列の制約を宣言することができますが、数値の制約も同様に宣言できます。
-ここで、`ge=1`の場合、`item_id`は`1`「より大きい`g`か、同じ`e`」整数でなれけばなりません。
+ここで、`ge=1`の場合、`item_id`は`1`「より大きい`g`か、同じ`e`」整数でなれけばなりません。
-```Python hl_lines="8"
-{!../../../docs_src/path_params_numeric_validations/tutorial004.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial004.py hl[8] *}
## 数値の検証: より大きいと小なりイコール
@@ -76,9 +69,7 @@ Pythonはその`*`で何かをすることはありませんが、それ以降
* `gt`: より大きい(`g`reater `t`han)
* `le`: 小なりイコール(`l`ess than or `e`qual)
-```Python hl_lines="9"
-{!../../../docs_src/path_params_numeric_validations/tutorial005.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial005.py hl[9] *}
## 数値の検証: 浮動小数点、 大なり小なり
@@ -90,9 +81,7 @@ Pythonはその`*`で何かをすることはありませんが、それ以降
これはltも同じです。
-```Python hl_lines="11"
-{!../../../docs_src/path_params_numeric_validations/tutorial006.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial006.py hl[11] *}
## まとめ
@@ -105,18 +94,24 @@ Pythonはその`*`で何かをすることはありませんが、それ以降
* `lt`: より小さい(`l`ess `t`han)
* `le`: 以下(`l`ess than or `e`qual)
-!!! info "情報"
- `Query`、`Path`などは後に共通の`Param`クラスのサブクラスを見ることになります。(使う必要はありません)
+/// info | 情報
- そして、それらすべては、これまで見てきた追加のバリデーションとメタデータと同じパラメータを共有しています。
+`Query`、`Path`などは後に共通の`Param`クラスのサブクラスを見ることになります。(使う必要はありません)
-!!! note "技術詳細"
- `fastapi`から`Query`、`Path`などをインポートすると、これらは実際には関数です。
+そして、それらすべては、これまで見てきた追加のバリデーションとメタデータと同じパラメータを共有しています。
- 呼び出されると、同じ名前のクラスのインスタンスを返します。
+///
- そのため、関数である`Query`をインポートし、それを呼び出すと、`Query`という名前のクラスのインスタンスが返されます。
+/// note | 技術詳細
- これらの関数は(クラスを直接使うのではなく)エディタが型についてエラーとしないようにするために存在します。
+`fastapi`から`Query`、`Path`などをインポートすると、これらは実際には関数です。
- この方法によって、これらのエラーを無視するための設定を追加することなく、通常のエディタやコーディングツールを使用することができます。
+呼び出されると、同じ名前のクラスのインスタンスを返します。
+
+そのため、関数である`Query`をインポートし、それを呼び出すと、`Query`という名前のクラスのインスタンスが返されます。
+
+これらの関数は(クラスを直接使うのではなく)エディタが型についてエラーとしないようにするために存在します。
+
+この方法によって、これらのエラーを無視するための設定を追加することなく、通常のエディタやコーディングツールを使用することができます。
+
+///
diff --git a/docs/ja/docs/tutorial/path-params.md b/docs/ja/docs/tutorial/path-params.md
index b395dc41d..1893ec12f 100644
--- a/docs/ja/docs/tutorial/path-params.md
+++ b/docs/ja/docs/tutorial/path-params.md
@@ -2,9 +2,7 @@
Pythonのformat文字列と同様のシンタックスで「パスパラメータ」や「パス変数」を宣言できます:
-```Python hl_lines="6 7"
-{!../../../docs_src/path_params/tutorial001.py!}
-```
+{* ../../docs_src/path_params/tutorial001.py hl[6,7] *}
パスパラメータ `item_id` の値は、引数 `item_id` として関数に渡されます。
@@ -18,14 +16,15 @@ Pythonのformat文字列と同様のシンタックスで「パスパラメー
標準のPythonの型アノテーションを使用して、関数内のパスパラメータの型を宣言できます:
-```Python hl_lines="7"
-{!../../../docs_src/path_params/tutorial002.py!}
-```
+{* ../../docs_src/path_params/tutorial002.py hl[7] *}
ここでは、 `item_id` は `int` として宣言されています。
-!!! check "確認"
- これにより、関数内でのエディターサポート (エラーチェックや補完など) が提供されます。
+/// check | 確認
+
+これにより、関数内でのエディターサポート (エラーチェックや補完など) が提供されます。
+
+///
## データ変換
@@ -35,10 +34,13 @@ Pythonのformat文字列と同様のシンタックスで「パスパラメー
{"item_id":3}
```
-!!! check "確認"
- 関数が受け取った(および返した)値は、文字列の `"3"` ではなく、Pythonの `int` としての `3` であることに注意してください。
+/// check | 確認
- したがって、型宣言を使用すると、**FastAPI**は自動リクエスト "解析" を行います。
+関数が受け取った(および返した)値は、文字列の `"3"` ではなく、Pythonの `int` としての `3` であることに注意してください。
+
+したがって、型宣言を使用すると、**FastAPI**は自動リクエスト "解析" を行います。
+
+///
## データバリデーション
@@ -63,12 +65,15 @@ Pythonのformat文字列と同様のシンタックスで「パスパラメー
http://127.0.0.1:8000/items/4.2 で見られるように、intのかわりに `float` が与えられた場合にも同様なエラーが表示されます。
-!!! check "確認"
- したがって、Pythonの型宣言を使用することで、**FastAPI**はデータのバリデーションを行います。
+/// check | 確認
- 表示されたエラーには問題のある箇所が明確に指摘されていることに注意してください。
+したがって、Pythonの型宣言を使用することで、**FastAPI**はデータのバリデーションを行います。
- これは、APIに関連するコードの開発およびデバッグに非常に役立ちます。
+表示されたエラーには問題のある箇所が明確に指摘されていることに注意してください。
+
+これは、APIに関連するコードの開発およびデバッグに非常に役立ちます。
+
+///
## ドキュメント
@@ -76,10 +81,13 @@ Pythonのformat文字列と同様のシンタックスで「パスパラメー
-!!! check "確認"
- 繰り返しになりますが、Python型宣言を使用するだけで、**FastAPI**は対話的なAPIドキュメントを自動的に生成します(Swagger UIを統合)。
+/// check | 確認
- パスパラメータが整数として宣言されていることに注意してください。
+繰り返しになりますが、Python型宣言を使用するだけで、**FastAPI**は対話的なAPIドキュメントを自動的に生成します(Swagger UIを統合)。
+
+パスパラメータが整数として宣言されていることに注意してください。
+
+///
## 標準であることのメリット、ドキュメンテーションの代替物
@@ -109,9 +117,7 @@ Pythonのformat文字列と同様のシンタックスで「パスパラメー
*path operations* は順に評価されるので、 `/users/me` が `/users/{user_id}` よりも先に宣言されているか確認する必要があります:
-```Python hl_lines="6 11"
-{!../../../docs_src/path_params/tutorial003.py!}
-```
+{* ../../docs_src/path_params/tutorial003.py hl[6,11] *}
それ以外の場合、 `/users/{users_id}` は `/users/me` としてもマッチします。値が「"me"」であるパラメータ `user_id` を受け取ると「考え」ます。
@@ -127,23 +133,25 @@ Pythonのformat文字列と同様のシンタックスで「パスパラメー
そして、固定値のクラス属性を作ります。すると、その値が使用可能な値となります:
-```Python hl_lines="1 6 7 8 9"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[1,6,7,8,9] *}
-!!! info "情報"
- Enumerations (もしくは、enums)はPython 3.4以降で利用できます。
+/// info | 情報
-!!! tip "豆知識"
- "AlexNet"、"ResNet"そして"LeNet"は機械学習モデルの名前です。
+Enumerations (もしくは、enums)はPython 3.4以降で利用できます。
+
+///
+
+/// tip | 豆知識
+
+"AlexNet"、"ResNet"そして"LeNet"は機械学習モデルの名前です。
+
+///
### *パスパラメータ*の宣言
次に、作成したenumクラスである`ModelName`を使用した型アノテーションをもつ*パスパラメータ*を作成します:
-```Python hl_lines="16"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[16] *}
### ドキュメントの確認
@@ -159,20 +167,19 @@ Pythonのformat文字列と同様のシンタックスで「パスパラメー
これは、作成した列挙型 `ModelName` の*列挙型メンバ*と比較できます:
-```Python hl_lines="17"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[17] *}
#### *列挙値*の取得
`model_name.value` 、もしくは一般に、 `your_enum_member.value` を使用して実際の値 (この場合は `str`) を取得できます。
-```Python hl_lines="20"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[20] *}
-!!! tip "豆知識"
- `ModelName.lenet.value` でも `"lenet"` 値にアクセスできます。
+/// tip | 豆知識
+
+`ModelName.lenet.value` でも `"lenet"` 値にアクセスできます。
+
+///
#### *列挙型メンバ*の返却
@@ -180,9 +187,7 @@ Pythonのformat文字列と同様のシンタックスで「パスパラメー
それらはクライアントに返される前に適切な値 (この場合は文字列) に変換されます。
-```Python hl_lines="18 21 23"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[18,21,23] *}
クライアントは以下の様なJSONレスポンスを得ます:
@@ -221,14 +226,15 @@ Starletteのオプションを直接使用することで、以下のURLの様
したがって、以下の様に使用できます:
-```Python hl_lines="6"
-{!../../../docs_src/path_params/tutorial004.py!}
-```
+{* ../../docs_src/path_params/tutorial004.py hl[6] *}
-!!! tip "豆知識"
- 最初のスラッシュ (`/`)が付いている `/home/johndoe/myfile.txt` をパラメータが含んでいる必要があります。
+/// tip | 豆知識
- この場合、URLは `files` と `home` の間にダブルスラッシュ (`//`) のある、 `/files//home/johndoe/myfile.txt` になります。
+最初のスラッシュ (`/`)が付いている `/home/johndoe/myfile.txt` をパラメータが含んでいる必要があります。
+
+この場合、URLは `files` と `home` の間にダブルスラッシュ (`//`) のある、 `/files//home/johndoe/myfile.txt` になります。
+
+///
## まとめ
diff --git a/docs/ja/docs/tutorial/query-param-models.md b/docs/ja/docs/tutorial/query-param-models.md
new file mode 100644
index 000000000..053d0740b
--- /dev/null
+++ b/docs/ja/docs/tutorial/query-param-models.md
@@ -0,0 +1,68 @@
+# クエリパラメータモデル
+
+もし関連する**複数のクエリパラメータ**から成るグループがあるなら、それらを宣言するために、**Pydanticモデル**を作成できます。
+
+こうすることで、**複数の場所**で**そのPydanticモデルを再利用**でき、バリデーションやメタデータを、すべてのクエリパラメータに対して一度に宣言できます。😎
+
+/// note | 備考
+
+この機能は、FastAPIのバージョン `0.115.0` からサポートされています。🤓
+
+///
+
+## クエリパラメータにPydanticモデルを使用する
+
+必要な**複数のクエリパラメータ**を**Pydanticモデル**で宣言し、さらに、それを `Query` として宣言しましょう:
+
+{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *}
+
+**FastAPI**は、リクエストの**クエリパラメータ**からそれぞれの**フィールド**のデータを**抽出**し、定義された**Pydanticモデル**を提供します。
+
+## ドキュメントの確認
+
+対話的APIドキュメント `/docs` でクエリパラメータを確認できます:
+
+
+POSTのウェブドキュメントを参照してください。
+しかし、フォームがファイルを含む場合は、`multipart/form-data`としてエンコードされます。ファイルの扱いについては次の章で説明します。
-!!! warning "注意"
- *path operation*で複数の`Form`パラメータを宣言することができますが、JSONとして受け取ることを期待している`Body`フィールドを宣言することはできません。なぜなら、リクエストは`application/json`の代わりに`application/x-www-form-urlencoded`を使ってボディをエンコードするからです。
+これらのエンコーディングやフォームフィールドの詳細については、MDNのPOSTのウェブドキュメントを参照してください。
- これは **FastAPI**の制限ではなく、HTTPプロトコルの一部です。
+///
+
+/// warning | 注意
+
+*path operation*で複数の`Form`パラメータを宣言することができますが、JSONとして受け取ることを期待している`Body`フィールドを宣言することはできません。なぜなら、リクエストは`application/json`の代わりに`application/x-www-form-urlencoded`を使ってボディをエンコードするからです。
+
+これは **FastAPI**の制限ではなく、HTTPプロトコルの一部です。
+
+///
## まとめ
diff --git a/docs/ja/docs/tutorial/response-model.md b/docs/ja/docs/tutorial/response-model.md
index b8b6978d4..b8464a4c7 100644
--- a/docs/ja/docs/tutorial/response-model.md
+++ b/docs/ja/docs/tutorial/response-model.md
@@ -8,12 +8,13 @@
* `@app.delete()`
* など。
-```Python hl_lines="17"
-{!../../../docs_src/response_model/tutorial001.py!}
-```
+{* ../../docs_src/response_model/tutorial001.py hl[17] *}
-!!! note "備考"
- `response_model`は「デコレータ」メソッド(`get`、`post`など)のパラメータであることに注意してください。すべてのパラメータやボディのように、*path operation関数* のパラメータではありません。
+/// note | 備考
+
+`response_model`は「デコレータ」メソッド(`get`、`post`など)のパラメータであることに注意してください。すべてのパラメータやボディのように、*path operation関数* のパラメータではありません。
+
+///
Pydanticモデルの属性に対して宣言するのと同じ型を受け取るので、Pydanticモデルになることもできますが、例えば、`List[Item]`のようなPydanticモデルの`list`になることもできます。
@@ -28,22 +29,21 @@ FastAPIは`response_model`を使って以下のことをします:
* 出力データをモデルのデータに限定します。これがどのように重要なのか以下で見ていきましょう。
-!!! note "技術詳細"
- レスポンスモデルは、関数の戻り値のアノテーションではなく、このパラメータで宣言されています。なぜなら、パス関数は実際にはそのレスポンスモデルを返すのではなく、`dict`やデータベースオブジェクト、あるいは他のモデルを返し、`response_model`を使用してフィールドの制限やシリアライズを行うからです。
+/// note | 技術詳細
+
+レスポンスモデルは、関数の戻り値のアノテーションではなく、このパラメータで宣言されています。なぜなら、パス関数は実際にはそのレスポンスモデルを返すのではなく、`dict`やデータベースオブジェクト、あるいは他のモデルを返し、`response_model`を使用してフィールドの制限やシリアライズを行うからです。
+
+///
## 同じ入力データの返却
ここでは`UserIn`モデルを宣言しています。それには平文のパスワードが含まれています:
-```Python hl_lines="9 11"
-{!../../../docs_src/response_model/tutorial002.py!}
-```
+{* ../../docs_src/response_model/tutorial002.py hl[9,11] *}
そして、このモデルを使用して入力を宣言し、同じモデルを使って出力を宣言しています:
-```Python hl_lines="17 18"
-{!../../../docs_src/response_model/tutorial002.py!}
-```
+{* ../../docs_src/response_model/tutorial002.py hl[17,18] *}
これで、ブラウザがパスワードを使ってユーザーを作成する際に、APIがレスポンスで同じパスワードを返すようになりました。
@@ -51,28 +51,25 @@ FastAPIは`response_model`を使って以下のことをします:
しかし、同じモデルを別の*path operation*に使用すると、すべてのクライアントにユーザーのパスワードを送信してしまうことになります。
-!!! danger "危険"
- ユーザーの平文のパスワードを保存したり、レスポンスで送信したりすることは絶対にしないでください。
+/// danger | 危険
+
+ユーザーの平文のパスワードを保存したり、レスポンスで送信したりすることは絶対にしないでください。
+
+///
## 出力モデルの追加
代わりに、平文のパスワードを持つ入力モデルと、パスワードを持たない出力モデルを作成することができます:
-```Python hl_lines="9 11 16"
-{!../../../docs_src/response_model/tutorial003.py!}
-```
+{* ../../docs_src/response_model/tutorial003.py hl[9,11,16] *}
ここでは、*path operation関数*がパスワードを含む同じ入力ユーザーを返しているにもかかわらず:
-```Python hl_lines="24"
-{!../../../docs_src/response_model/tutorial003.py!}
-```
+{* ../../docs_src/response_model/tutorial003.py hl[24] *}
...`response_model`を`UserOut`と宣言したことで、パスワードが含まれていません:
-```Python hl_lines="22"
-{!../../../docs_src/response_model/tutorial003.py!}
-```
+{* ../../docs_src/response_model/tutorial003.py hl[22] *}
そのため、**FastAPI** は出力モデルで宣言されていない全てのデータをフィルタリングしてくれます(Pydanticを使用)。
@@ -90,9 +87,7 @@ FastAPIは`response_model`を使って以下のことをします:
レスポンスモデルにはデフォルト値を設定することができます:
-```Python hl_lines="11 13 14"
-{!../../../docs_src/response_model/tutorial004.py!}
-```
+{* ../../docs_src/response_model/tutorial004.py hl[11,13,14] *}
* `description: str = None`は`None`がデフォルト値です。
* `tax: float = 10.5`は`10.5`がデフォルト値です。
@@ -106,9 +101,7 @@ FastAPIは`response_model`を使って以下のことをします:
*path operation デコレータ*に`response_model_exclude_unset=True`パラメータを設定することができます:
-```Python hl_lines="24"
-{!../../../docs_src/response_model/tutorial004.py!}
-```
+{* ../../docs_src/response_model/tutorial004.py hl[24] *}
そして、これらのデフォルト値はレスポンスに含まれず、実際に設定された値のみが含まれます。
@@ -121,16 +114,22 @@ FastAPIは`response_model`を使って以下のことをします:
}
```
-!!! info "情報"
- FastAPIはこれをするために、Pydanticモデルの`.dict()`をその`exclude_unset`パラメータで使用しています。
+/// info | 情報
-!!! info "情報"
- 以下も使用することができます:
+FastAPIはこれをするために、Pydanticモデルの`.dict()`をその`exclude_unset`パラメータで使用しています。
- * `response_model_exclude_defaults=True`
- * `response_model_exclude_none=True`
+///
- `exclude_defaults`と`exclude_none`については、Pydanticのドキュメントで説明されている通りです。
+/// info | 情報
+
+以下も使用することができます:
+
+* `response_model_exclude_defaults=True`
+* `response_model_exclude_none=True`
+
+`exclude_defaults`と`exclude_none`については、Pydanticのドキュメントで説明されている通りです。
+
+///
#### デフォルト値を持つフィールドの値を持つデータ
@@ -165,9 +164,12 @@ FastAPIは十分に賢いので(実際には、Pydanticが十分に賢い)`d
そのため、それらはJSONレスポンスに含まれることになります。
-!!! tip "豆知識"
- デフォルト値は`None`だけでなく、なんでも良いことに注意してください。
- 例えば、リスト(`[]`)や`10.5`の`float`などです。
+/// tip | 豆知識
+
+デフォルト値は`None`だけでなく、なんでも良いことに注意してください。
+例えば、リスト(`[]`)や`10.5`の`float`などです。
+
+///
### `response_model_include`と`response_model_exclude`
@@ -177,29 +179,31 @@ FastAPIは十分に賢いので(実際には、Pydanticが十分に賢い)`d
これは、Pydanticモデルが1つしかなく、出力からいくつかのデータを削除したい場合のクイックショートカットとして使用することができます。
-!!! tip "豆知識"
- それでも、これらのパラメータではなく、複数のクラスを使用して、上記のようなアイデアを使うことをおすすめします。
+/// tip | 豆知識
- これは`response_model_include`や`response_mode_exclude`を使用していくつかの属性を省略しても、アプリケーションのOpenAPI(とドキュメント)で生成されたJSON Schemaが完全なモデルになるからです。
+それでも、これらのパラメータではなく、複数のクラスを使用して、上記のようなアイデアを使うことをおすすめします。
- 同様に動作する`response_model_by_alias`にも当てはまります。
+これは`response_model_include`や`response_mode_exclude`を使用していくつかの属性を省略しても、アプリケーションのOpenAPI(とドキュメント)で生成されたJSON Schemaが完全なモデルになるからです。
-```Python hl_lines="31 37"
-{!../../../docs_src/response_model/tutorial005.py!}
-```
+同様に動作する`response_model_by_alias`にも当てはまります。
-!!! tip "豆知識"
- `{"name", "description"}`の構文はこれら2つの値をもつ`set`を作成します。
+///
- これは`set(["name", "description"])`と同等です。
+{* ../../docs_src/response_model/tutorial005.py hl[31,37] *}
+
+/// tip | 豆知識
+
+`{"name", "description"}`の構文はこれら2つの値をもつ`set`を作成します。
+
+これは`set(["name", "description"])`と同等です。
+
+///
#### `set`の代わりに`list`を使用する
もし`set`を使用することを忘れて、代わりに`list`や`tuple`を使用しても、FastAPIはそれを`set`に変換して正しく動作します:
-```Python hl_lines="31 37"
-{!../../../docs_src/response_model/tutorial006.py!}
-```
+{* ../../docs_src/response_model/tutorial006.py hl[31,37] *}
## まとめ
diff --git a/docs/ja/docs/tutorial/response-status-code.md b/docs/ja/docs/tutorial/response-status-code.md
index ead2addda..6d197d543 100644
--- a/docs/ja/docs/tutorial/response-status-code.md
+++ b/docs/ja/docs/tutorial/response-status-code.md
@@ -8,17 +8,21 @@
* `@app.delete()`
* など。
-```Python hl_lines="6"
-{!../../../docs_src/response_status_code/tutorial001.py!}
-```
+{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
-!!! note "備考"
- `status_code`は「デコレータ」メソッド(`get`、`post`など)のパラメータであることに注意してください。すべてのパラメータやボディのように、*path operation関数*のものではありません。
+/// note | 備考
+
+`status_code`は「デコレータ」メソッド(`get`、`post`など)のパラメータであることに注意してください。すべてのパラメータやボディのように、*path operation関数*のものではありません。
+
+///
`status_code`パラメータはHTTPステータスコードを含む数値を受け取ります。
-!!! info "情報"
- `status_code`は代わりに、Pythonの`http.HTTPStatus`のように、`IntEnum`を受け取ることもできます。
+/// info | 情報
+
+`status_code`は代わりに、Pythonの`http.HTTPStatus`のように、`IntEnum`を受け取ることもできます。
+
+///
これは:
@@ -27,15 +31,21 @@
-!!! note "備考"
- いくつかのレスポンスコード(次のセクションを参照)は、レスポンスにボディがないことを示しています。
+/// note | 備考
- FastAPIはこれを知っていて、レスポンスボディがないというOpenAPIドキュメントを生成します。
+いくつかのレスポンスコード(次のセクションを参照)は、レスポンスにボディがないことを示しています。
+
+FastAPIはこれを知っていて、レスポンスボディがないというOpenAPIドキュメントを生成します。
+
+///
## HTTPステータスコードについて
-!!! note "備考"
- すでにHTTPステータスコードが何であるかを知っている場合は、次のセクションにスキップしてください。
+/// note | 備考
+
+すでにHTTPステータスコードが何であるかを知っている場合は、次のセクションにスキップしてください。
+
+///
HTTPでは、レスポンスの一部として3桁の数字のステータスコードを送信します。
@@ -54,16 +64,17 @@ HTTPでは、レスポンスの一部として3桁の数字のステータス
* クライアントからの一般的なエラーについては、`400`を使用することができます。
* `500`以上はサーバーエラーのためのものです。これらを直接使うことはほとんどありません。アプリケーションコードやサーバーのどこかで何か問題が発生した場合、これらのステータスコードのいずれかが自動的に返されます。
-!!! tip "豆知識"
- それぞれのステータスコードとどのコードが何のためのコードなのかについて詳細はMDN HTTP レスポンスステータスコードについてのドキュメントを参照してください。
+/// tip | 豆知識
+
+それぞれのステータスコードとどのコードが何のためのコードなのかについて詳細はMDN HTTP レスポンスステータスコードについてのドキュメントを参照してください。
+
+///
## 名前を覚えるための近道
先ほどの例をもう一度見てみましょう:
-```Python hl_lines="6"
-{!../../../docs_src/response_status_code/tutorial001.py!}
-```
+{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
`201`は「作成完了」のためのステータスコードです。
@@ -71,18 +82,19 @@ HTTPでは、レスポンスの一部として3桁の数字のステータス
`fastapi.status`の便利な変数を利用することができます。
-```Python hl_lines="1 6"
-{!../../../docs_src/response_status_code/tutorial002.py!}
-```
+{* ../../docs_src/response_status_code/tutorial002.py hl[1,6] *}
それらは便利です。それらは同じ番号を保持しており、その方法ではエディタの自動補完を使用してそれらを見つけることができます。
-!!! note "技術詳細"
- また、`from starlette import status`を使うこともできます。
+/// note | 技術詳細
- **FastAPI** は、`開発者の利便性を考慮して、fastapi.status`と同じ`starlette.status`を提供しています。しかし、これはStarletteから直接提供されています。
+また、`from starlette import status`を使うこともできます。
+
+**FastAPI** は、`開発者の利便性を考慮して、fastapi.status`と同じ`starlette.status`を提供しています。しかし、これはStarletteから直接提供されています。
+
+///
## デフォルトの変更
diff --git a/docs/ja/docs/tutorial/schema-extra-example.md b/docs/ja/docs/tutorial/schema-extra-example.md
index d96163b82..1834e67b2 100644
--- a/docs/ja/docs/tutorial/schema-extra-example.md
+++ b/docs/ja/docs/tutorial/schema-extra-example.md
@@ -10,9 +10,7 @@ JSON Schemaの追加情報を宣言する方法はいくつかあります。
Pydanticのドキュメント: スキーマのカスタマイズで説明されているように、`Config`と`schema_extra`を使ってPydanticモデルの例を宣言することができます:
-```Python hl_lines="15 16 17 18 19 20 21 22 23"
-{!../../../docs_src/schema_extra_example/tutorial001.py!}
-```
+{* ../../docs_src/schema_extra_example/tutorial001.py hl[15,16,17,18,19,20,21,22,23] *}
その追加情報はそのまま出力され、JSON Schemaに追加されます。
@@ -20,12 +18,13 @@ JSON Schemaの追加情報を宣言する方法はいくつかあります。
後述する`Field`、`Path`、`Query`、`Body`などでは、任意の引数を関数に渡すことでJSON Schemaの追加情報を宣言することもできます:
-```Python hl_lines="4 10 11 12 13"
-{!../../../docs_src/schema_extra_example/tutorial002.py!}
-```
+{* ../../docs_src/schema_extra_example/tutorial002.py hl[4,10,11,12,13] *}
-!!! warning "注意"
- これらの追加引数が渡されても、文書化のためのバリデーションは追加されず、注釈だけが追加されることを覚えておいてください。
+/// warning | 注意
+
+これらの追加引数が渡されても、文書化のためのバリデーションは追加されず、注釈だけが追加されることを覚えておいてください。
+
+///
## `Body`の追加引数
@@ -33,9 +32,7 @@ JSON Schemaの追加情報を宣言する方法はいくつかあります。
例えば、`Body`にボディリクエストの`example`を渡すことができます:
-```Python hl_lines="21 22 23 24 25 26"
-{!../../../docs_src/schema_extra_example/tutorial003.py!}
-```
+{* ../../docs_src/schema_extra_example/tutorial003.py hl[21,22,23,24,25,26] *}
## ドキュメントのUIの例
diff --git a/docs/ja/docs/tutorial/security/first-steps.md b/docs/ja/docs/tutorial/security/first-steps.md
index dc3267e62..0ce0f929b 100644
--- a/docs/ja/docs/tutorial/security/first-steps.md
+++ b/docs/ja/docs/tutorial/security/first-steps.md
@@ -20,18 +20,19 @@
`main.py`に、下記の例をコピーします:
-```Python
-{!../../../docs_src/security/tutorial001.py!}
-```
+{* ../../docs_src/security/tutorial001.py *}
## 実行
-!!! info "情報"
- まず`python-multipart`をインストールします。
+/// info | 情報
- 例えば、`pip install python-multipart`。
+まず`python-multipart`をインストールします。
- これは、**OAuth2**が `ユーザー名` や `パスワード` を送信するために、「フォームデータ」を使うからです。
+例えば、`pip install python-multipart`。
+
+これは、**OAuth2**が `ユーザー名` や `パスワード` を送信するために、「フォームデータ」を使うからです。
+
+///
例を実行します:
@@ -53,17 +54,23 @@ $ uvicorn main:app --reload
-!!! check "Authorizeボタン!"
- すでにピカピカの新しい「Authorize」ボタンがあります。
+/// check | Authorizeボタン!
- そして、あなたの*path operation*には、右上にクリックできる小さな鍵アイコンがあります。
+すでにピカピカの新しい「Authorize」ボタンがあります。
+
+そして、あなたの*path operation*には、右上にクリックできる小さな鍵アイコンがあります。
+
+///
それをクリックすると、`ユーザー名`と`パスワード` (およびその他のオプションフィールド) を入力する小さな認証フォームが表示されます:
-!!! note "備考"
- フォームに何を入力しても、まだうまくいきません。ですが、これから動くようになります。
+/// note | 備考
+
+フォームに何を入力しても、まだうまくいきません。ですが、これから動くようになります。
+
+///
もちろんエンドユーザーのためのフロントエンドではありません。しかし、すべてのAPIをインタラクティブにドキュメント化するための素晴らしい自動ツールです。
@@ -105,36 +112,43 @@ OAuth2は、バックエンドやAPIがユーザーを認証するサーバー
この例では、**Bearer**トークンを使用して**OAuth2**を**パスワード**フローで使用します。これには`OAuth2PasswordBearer`クラスを使用します。
-!!! info "情報"
- 「bearer」トークンが、唯一の選択肢ではありません。
+/// info | 情報
- しかし、私たちのユースケースには最適です。
+「bearer」トークンが、唯一の選択肢ではありません。
- あなたがOAuth2の専門家で、あなたのニーズに適した別のオプションがある理由を正確に知っている場合を除き、ほとんどのユースケースに最適かもしれません。
+しかし、私たちのユースケースには最適です。
- その場合、**FastAPI**はそれを構築するためのツールも提供します。
+あなたがOAuth2の専門家で、あなたのニーズに適した別のオプションがある理由を正確に知っている場合を除き、ほとんどのユースケースに最適かもしれません。
+
+その場合、**FastAPI**はそれを構築するためのツールも提供します。
+
+///
`OAuth2PasswordBearer` クラスのインスタンスを作成する時に、パラメーター`tokenUrl`を渡します。このパラメーターには、クライアント (ユーザーのブラウザで動作するフロントエンド) がトークンを取得するために`ユーザー名`と`パスワード`を送信するURLを指定します。
-```Python hl_lines="6"
-{!../../../docs_src/security/tutorial001.py!}
-```
+{* ../../docs_src/security/tutorial001.py hl[6] *}
-!!! tip "豆知識"
- ここで、`tokenUrl="token"`は、まだ作成していない相対URL`token`を指します。相対URLなので、`./token`と同じです。
+/// tip | 豆知識
- 相対URLを使っているので、APIが`https://example.com/`にある場合、`https://example.com/token`を参照します。しかし、APIが`https://example.com/api/v1/`にある場合は`https://example.com/api/v1/token`を参照することになります。
+ここで、`tokenUrl="token"`は、まだ作成していない相対URL`token`を指します。相対URLなので、`./token`と同じです。
- 相対 URL を使うことは、[プロキシと接続](../../advanced/behind-a-proxy.md){.internal-link target=_blank}のような高度なユースケースでもアプリケーションを動作させ続けるために重要です。
+相対URLを使っているので、APIが`https://example.com/`にある場合、`https://example.com/token`を参照します。しかし、APIが`https://example.com/api/v1/`にある場合は`https://example.com/api/v1/token`を参照することになります。
+
+相対 URL を使うことは、[プロキシと接続](../../advanced/behind-a-proxy.md){.internal-link target=_blank}のような高度なユースケースでもアプリケーションを動作させ続けるために重要です。
+
+///
このパラメーターはエンドポイント/ *path operation*を作成しません。しかし、URL`/token`はクライアントがトークンを取得するために使用するものであると宣言します。この情報は OpenAPI やインタラクティブな API ドキュメントシステムで使われます。
実際のpath operationもすぐに作ります。
-!!! info "情報"
- 非常に厳格な「Pythonista」であれば、パラメーター名のスタイルが`token_url`ではなく`tokenUrl`であることを気に入らないかもしれません。
+/// info | 情報
- それはOpenAPI仕様と同じ名前を使用しているからです。そのため、これらのセキュリティスキームについてもっと調べる必要がある場合は、それをコピーして貼り付ければ、それについての詳細な情報を見つけることができます。
+非常に厳格な「Pythonista」であれば、パラメーター名のスタイルが`token_url`ではなく`tokenUrl`であることを気に入らないかもしれません。
+
+それはOpenAPI仕様と同じ名前を使用しているからです。そのため、これらのセキュリティスキームについてもっと調べる必要がある場合は、それをコピーして貼り付ければ、それについての詳細な情報を見つけることができます。
+
+///
変数`oauth2_scheme`は`OAuth2PasswordBearer`のインスタンスですが、「呼び出し可能」です。
@@ -150,18 +164,19 @@ oauth2_scheme(some, parameters)
これで`oauth2_scheme`を`Depends`で依存関係に渡すことができます。
-```Python hl_lines="10"
-{!../../../docs_src/security/tutorial001.py!}
-```
+{* ../../docs_src/security/tutorial001.py hl[10] *}
この依存関係は、*path operation function*のパラメーター`token`に代入される`str`を提供します。
**FastAPI**は、この依存関係を使用してOpenAPIスキーマ (および自動APIドキュメント) で「セキュリティスキーム」を定義できることを知っています。
-!!! info "技術詳細"
- **FastAPI**は、`OAuth2PasswordBearer` クラス (依存関係で宣言されている) を使用してOpenAPIのセキュリティスキームを定義できることを知っています。これは`fastapi.security.oauth2.OAuth2`、`fastapi.security.base.SecurityBase`を継承しているからです。
+/// info | 技術詳細
- OpenAPIと統合するセキュリティユーティリティ (および自動APIドキュメント) はすべて`SecurityBase`を継承しています。それにより、**FastAPI**はそれらをOpenAPIに統合する方法を知ることができます。
+**FastAPI**は、`OAuth2PasswordBearer` クラス (依存関係で宣言されている) を使用してOpenAPIのセキュリティスキームを定義できることを知っています。これは`fastapi.security.oauth2.OAuth2`、`fastapi.security.base.SecurityBase`を継承しているからです。
+
+OpenAPIと統合するセキュリティユーティリティ (および自動APIドキュメント) はすべて`SecurityBase`を継承しています。それにより、**FastAPI**はそれらをOpenAPIに統合する方法を知ることができます。
+
+///
## どのように動作するか
diff --git a/docs/ja/docs/tutorial/security/get-current-user.md b/docs/ja/docs/tutorial/security/get-current-user.md
index 7f8dcaad2..9fc46c07c 100644
--- a/docs/ja/docs/tutorial/security/get-current-user.md
+++ b/docs/ja/docs/tutorial/security/get-current-user.md
@@ -2,9 +2,7 @@
一つ前の章では、(依存性注入システムに基づいた)セキュリティシステムは、 *path operation関数* に `str` として `token` を与えていました:
-```Python hl_lines="10"
-{!../../../docs_src/security/tutorial001.py!}
-```
+{* ../../docs_src/security/tutorial001.py hl[10] *}
しかし、それはまだそんなに有用ではありません。
@@ -16,9 +14,7 @@
ボディを宣言するのにPydanticを使用するのと同じやり方で、Pydanticを別のどんなところでも使うことができます:
-```Python hl_lines="5 12-16"
-{!../../../docs_src/security/tutorial002.py!}
-```
+{* ../../docs_src/security/tutorial002.py hl[5,12:16] *}
## 依存関係 `get_current_user` を作成
@@ -30,41 +26,39 @@
以前直接 *path operation* の中でしていたのと同じように、新しい依存関係である `get_current_user` は `str` として `token` を受け取るようになります:
-```Python hl_lines="25"
-{!../../../docs_src/security/tutorial002.py!}
-```
+{* ../../docs_src/security/tutorial002.py hl[25] *}
## ユーザーの取得
`get_current_user` は作成した(偽物の)ユーティリティ関数を使って、 `str` としてトークンを受け取り、先ほどのPydanticの `User` モデルを返却します:
-```Python hl_lines="19-22 26-27"
-{!../../../docs_src/security/tutorial002.py!}
-```
+{* ../../docs_src/security/tutorial002.py hl[19:22,26:27] *}
## 現在のユーザーの注入
ですので、 `get_current_user` に対して同様に *path operation* の中で `Depends` を利用できます。
-```Python hl_lines="31"
-{!../../../docs_src/security/tutorial002.py!}
-```
+{* ../../docs_src/security/tutorial002.py hl[31] *}
Pydanticモデルの `User` として、 `current_user` の型を宣言することに注意してください。
その関数の中ですべての入力補完や型チェックを行う際に役に立ちます。
-!!! tip "豆知識"
- リクエストボディはPydanticモデルでも宣言できることを覚えているかもしれません。
+/// tip | 豆知識
- ここでは `Depends` を使っているおかげで、 **FastAPI** が混乱することはありません。
+リクエストボディはPydanticモデルでも宣言できることを覚えているかもしれません。
+ここでは `Depends` を使っているおかげで、 **FastAPI** が混乱することはありません。
-!!! check "確認"
- 依存関係システムがこのように設計されているおかげで、 `User` モデルを返却する別の依存関係(別の"dependables")を持つことができます。
+///
- 同じデータ型を返却する依存関係は一つだけしか持てない、という制約が入ることはないのです。
+/// check | 確認
+依存関係システムがこのように設計されているおかげで、 `User` モデルを返却する別の依存関係(別の"dependables")を持つことができます。
+
+同じデータ型を返却する依存関係は一つだけしか持てない、という制約が入ることはないのです。
+
+///
## 別のモデル
@@ -99,9 +93,7 @@ Pydanticモデルの `User` として、 `current_user` の型を宣言するこ
さらに、こうした何千もの *path operations* は、たった3行で表現できるのです:
-```Python hl_lines="30-32"
-{!../../../docs_src/security/tutorial002.py!}
-```
+{* ../../docs_src/security/tutorial002.py hl[30:32] *}
## まとめ
diff --git a/docs/ja/docs/tutorial/security/index.md b/docs/ja/docs/tutorial/security/index.md
index 390f21047..37b8bb958 100644
--- a/docs/ja/docs/tutorial/security/index.md
+++ b/docs/ja/docs/tutorial/security/index.md
@@ -32,9 +32,11 @@ OAuth 1というものもありましたが、これはOAuth2とは全く異な
OAuth2は、通信を暗号化する方法を指定せず、アプリケーションがHTTPSで提供されることを想定しています。
-!!! tip "豆知識"
- **デプロイ**のセクションでは、TraefikとLet's Encryptを使用して、無料でHTTPSを設定する方法が紹介されています。
+/// tip | 豆知識
+**デプロイ**のセクションでは、TraefikとLet's Encryptを使用して、無料でHTTPSを設定する方法が紹介されています。
+
+///
## OpenID Connect
@@ -87,10 +89,13 @@ OpenAPIでは、以下のセキュリティスキームを定義しています:
* この自動検出メカニズムは、OpenID Connectの仕様で定義されているものです。
-!!! tip "豆知識"
- Google、Facebook、Twitter、GitHubなど、他の認証/認可プロバイダを統合することも可能で、比較的簡単です。
+/// tip | 豆知識
- 最も複雑な問題は、それらのような認証/認可プロバイダを構築することですが、**FastAPI**は、あなたのために重い仕事をこなしながら、それを簡単に行うためのツールを提供します。
+Google、Facebook、Twitter、GitHubなど、他の認証/認可プロバイダを統合することも可能で、比較的簡単です。
+
+最も複雑な問題は、それらのような認証/認可プロバイダを構築することですが、**FastAPI**は、あなたのために重い仕事をこなしながら、それを簡単に行うためのツールを提供します。
+
+///
## **FastAPI** ユーティリティ
diff --git a/docs/ja/docs/tutorial/security/oauth2-jwt.md b/docs/ja/docs/tutorial/security/oauth2-jwt.md
index d5b179aa0..4859819cc 100644
--- a/docs/ja/docs/tutorial/security/oauth2-jwt.md
+++ b/docs/ja/docs/tutorial/security/oauth2-jwt.md
@@ -44,10 +44,13 @@ $ pip install python-jose[cryptography]
ここでは、推奨されているものを使用します:pyca/cryptography。
-!!! tip "豆知識"
- このチュートリアルでは以前、PyJWTを使用していました。
+/// tip | 豆知識
- しかし、Python-joseは、PyJWTのすべての機能に加えて、後に他のツールと統合して構築する際におそらく必要となる可能性のあるいくつかの追加機能を提供しています。そのため、代わりにPython-joseを使用するように更新されました。
+このチュートリアルでは以前、PyJWTを使用していました。
+
+しかし、Python-joseは、PyJWTのすべての機能に加えて、後に他のツールと統合して構築する際におそらく必要となる可能性のあるいくつかの追加機能を提供しています。そのため、代わりにPython-joseを使用するように更新されました。
+
+///
## パスワードのハッシュ化
@@ -83,13 +86,15 @@ $ pip install passlib[bcrypt]
-!!! tip "豆知識"
- `passlib`を使用すると、**Django**や**Flask**のセキュリティプラグインなどで作成されたパスワードを読み取れるように設定できます。
+/// tip | 豆知識
- 例えば、Djangoアプリケーションからデータベース内の同じデータをFastAPIアプリケーションと共有できるだけではなく、同じデータベースを使用してDjangoアプリケーションを徐々に移行することもできます。
+`passlib`を使用すると、**Django**や**Flask**のセキュリティプラグインなどで作成されたパスワードを読み取れるように設定できます。
- また、ユーザーはDjangoアプリまたは**FastAPI**アプリからも、同時にログインできるようになります。
+例えば、Djangoアプリケーションからデータベース内の同じデータをFastAPIアプリケーションと共有できるだけではなく、同じデータベースを使用してDjangoアプリケーションを徐々に移行することもできます。
+また、ユーザーはDjangoアプリまたは**FastAPI**アプリからも、同時にログインできるようになります。
+
+///
## パスワードのハッシュ化と検証
@@ -97,12 +102,15 @@ $ pip install passlib[bcrypt]
PassLib の「context」を作成します。これは、パスワードのハッシュ化と検証に使用されるものです。
-!!! tip "豆知識"
- PassLibのcontextには、検証だけが許された非推奨の古いハッシュアルゴリズムを含む、様々なハッシュアルゴリズムを使用した検証機能もあります。
+/// tip | 豆知識
- 例えば、この機能を使用して、別のシステム(Djangoなど)によって生成されたパスワードを読み取って検証し、Bcryptなどの別のアルゴリズムを使用して新しいパスワードをハッシュするといったことができます。
+PassLibのcontextには、検証だけが許された非推奨の古いハッシュアルゴリズムを含む、様々なハッシュアルゴリズムを使用した検証機能もあります。
- そして、同時にそれらはすべてに互換性があります。
+例えば、この機能を使用して、別のシステム(Djangoなど)によって生成されたパスワードを読み取って検証し、Bcryptなどの別のアルゴリズムを使用して新しいパスワードをハッシュするといったことができます。
+
+そして、同時にそれらはすべてに互換性があります。
+
+///
ユーザーから送られてきたパスワードをハッシュ化するユーティリティー関数を作成します。
@@ -110,12 +118,13 @@ PassLib の「context」を作成します。これは、パスワードのハ
さらに、ユーザーを認証して返す関数も作成します。
-```Python hl_lines="7 48 55-56 59-60 69-75"
-{!../../../docs_src/security/tutorial004.py!}
-```
+{* ../../docs_src/security/tutorial004.py hl[7,48,55:56,59:60,69:75] *}
-!!! note "備考"
- 新しい(偽の)データベース`fake_users_db`を確認すると、ハッシュ化されたパスワードが次のようになっていることがわかります:`"$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW"`
+/// note | 備考
+
+新しい(偽の)データベース`fake_users_db`を確認すると、ハッシュ化されたパスワードが次のようになっていることがわかります:`"$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW"`
+
+///
## JWTトークンの取り扱い
@@ -145,9 +154,7 @@ JWTトークンの署名に使用するアルゴリズム`"HS256"`を指定し
新しいアクセストークンを生成するユーティリティ関数を作成します。
-```Python hl_lines="6 12-14 28-30 78-86"
-{!../../../docs_src/security/tutorial004.py!}
-```
+{* ../../docs_src/security/tutorial004.py hl[6,12:14,28:30,78:86] *}
## 依存関係の更新
@@ -157,9 +164,7 @@ JWTトークンの署名に使用するアルゴリズム`"HS256"`を指定し
トークンが無効な場合は、すぐにHTTPエラーを返します。
-```Python hl_lines="89-106"
-{!../../../docs_src/security/tutorial004.py!}
-```
+{* ../../docs_src/security/tutorial004.py hl[89:106] *}
## `/token` パスオペレーションの更新
@@ -167,9 +172,7 @@ JWTトークンの署名に使用するアルゴリズム`"HS256"`を指定し
JWTアクセストークンを作成し、それを返します。
-```Python hl_lines="115-130"
-{!../../../docs_src/security/tutorial004.py!}
-```
+{* ../../docs_src/security/tutorial004.py hl[115:130] *}
### JWTの"subject" `sub` についての技術的な詳細
@@ -208,8 +211,11 @@ IDの衝突を回避するために、ユーザーのJWTトークンを作成す
Username: `johndoe`
Password: `secret`
-!!! check "確認"
- コードのどこにも平文のパスワード"`secret`"はなく、ハッシュ化されたものしかないことを確認してください。
+/// check | 確認
+
+コードのどこにも平文のパスワード"`secret`"はなく、ハッシュ化されたものしかないことを確認してください。
+
+///
@@ -230,8 +236,11 @@ Password: `secret`
-!!! note "備考"
- ヘッダーの`Authorization`には、`Bearer`で始まる値があります。
+/// note | 備考
+
+ヘッダーの`Authorization`には、`Bearer`で始まる値があります。
+
+///
## `scopes` を使った高度なユースケース
diff --git a/docs/ja/docs/tutorial/static-files.md b/docs/ja/docs/tutorial/static-files.md
index 1d9c434c3..f63f3f3b1 100644
--- a/docs/ja/docs/tutorial/static-files.md
+++ b/docs/ja/docs/tutorial/static-files.md
@@ -7,14 +7,15 @@
* `StaticFiles` をインポート。
* `StaticFiles()` インスタンスを生成し、特定のパスに「マウント」。
-```Python hl_lines="2 6"
-{!../../../docs_src/static_files/tutorial001.py!}
-```
+{* ../../docs_src/static_files/tutorial001.py hl[2,6] *}
-!!! note "技術詳細"
- `from starlette.staticfiles import StaticFiles` も使用できます。
+/// note | 技術詳細
- **FastAPI**は、開発者の利便性のために、`starlette.staticfiles` と同じ `fastapi.staticfiles` を提供します。しかし、実際にはStarletteから直接渡されています。
+`from starlette.staticfiles import StaticFiles` も使用できます。
+
+**FastAPI**は、開発者の利便性のために、`starlette.staticfiles` と同じ `fastapi.staticfiles` を提供します。しかし、実際にはStarletteから直接渡されています。
+
+///
### 「マウント」とは
diff --git a/docs/ja/docs/tutorial/testing.md b/docs/ja/docs/tutorial/testing.md
index 037e9628f..fe6c8c6b4 100644
--- a/docs/ja/docs/tutorial/testing.md
+++ b/docs/ja/docs/tutorial/testing.md
@@ -18,24 +18,31 @@
チェックしたい Python の標準的な式と共に、シンプルに `assert` 文を記述します。
-```Python hl_lines="2 12 15-18"
-{!../../../docs_src/app_testing/tutorial001.py!}
-```
+{* ../../docs_src/app_testing/tutorial001.py hl[2,12,15:18] *}
-!!! tip "豆知識"
- テスト関数は `async def` ではなく、通常の `def` であることに注意してください。
+/// tip | 豆知識
- また、クライアントへの呼び出しも通常の呼び出しであり、`await` を使用しません。
+テスト関数は `async def` ではなく、通常の `def` であることに注意してください。
- これにより、煩雑にならずに、`pytest` を直接使用できます。
+また、クライアントへの呼び出しも通常の呼び出しであり、`await` を使用しません。
-!!! note "技術詳細"
- `from starlette.testclient import TestClient` も使用できます。
+これにより、煩雑にならずに、`pytest` を直接使用できます。
- **FastAPI** は開発者の利便性のために `fastapi.testclient` と同じ `starlette.testclient` を提供します。しかし、実際にはStarletteから直接渡されています。
+///
-!!! tip "豆知識"
- FastAPIアプリケーションへのリクエストの送信とは別に、テストで `async` 関数 (非同期データベース関数など) を呼び出したい場合は、高度なチュートリアルの[Async Tests](../advanced/async-tests.md){.internal-link target=_blank} を参照してください。
+/// note | 技術詳細
+
+`from starlette.testclient import TestClient` も使用できます。
+
+**FastAPI** は開発者の利便性のために `fastapi.testclient` と同じ `starlette.testclient` を提供します。しかし、実際にはStarletteから直接渡されています。
+
+///
+
+/// tip | 豆知識
+
+FastAPIアプリケーションへのリクエストの送信とは別に、テストで `async` 関数 (非同期データベース関数など) を呼び出したい場合は、高度なチュートリアルの[Async Tests](../advanced/async-tests.md){.internal-link target=_blank} を参照してください。
+
+///
## テストの分離
@@ -47,17 +54,13 @@
**FastAPI** アプリに `main.py` ファイルがあるとします:
-```Python
-{!../../../docs_src/app_testing/main.py!}
-```
+{* ../../docs_src/app_testing/main.py *}
### テストファイル
次に、テストを含む `test_main.py` ファイルを作成し、`main` モジュール (`main.py`) から `app` をインポートします:
-```Python
-{!../../../docs_src/app_testing/test_main.py!}
-```
+{* ../../docs_src/app_testing/test_main.py *}
## テスト: 例の拡張
@@ -74,25 +77,13 @@
これらの *path operation* には `X-Token` ヘッダーが必要です。
-=== "Python 3.10+"
-
- ```Python
- {!> ../../../docs_src/app_testing/app_b_py310/main.py!}
- ```
-
-=== "Python 3.6+"
-
- ```Python
- {!> ../../../docs_src/app_testing/app_b/main.py!}
- ```
+{* ../../docs_src/app_testing/app_b_py310/main.py *}
### 拡張版テストファイル
次に、先程のものに拡張版のテストを加えた、`test_main_b.py` を作成します。
-```Python
-{!> ../../../docs_src/app_testing/app_b/test_main.py!}
-```
+{* ../../docs_src/app_testing/app_b/test_main.py *}
リクエストに情報を渡せるクライアントが必要で、その方法がわからない場合はいつでも、`httpx` での実現方法を検索 (Google) できます。
@@ -108,10 +99,13 @@
(`httpx` または `TestClient` を使用して) バックエンドにデータを渡す方法の詳細は、HTTPXのドキュメントを確認してください。
-!!! info "情報"
- `TestClient` は、Pydanticモデルではなく、JSONに変換できるデータを受け取ることに注意してください。
+/// info | 情報
- テストにPydanticモデルがあり、テスト中にそのデータをアプリケーションに送信したい場合は、[JSON互換エンコーダ](encoder.md){.internal-link target=_blank} で説明されている `jsonable_encoder` が利用できます。
+`TestClient` は、Pydanticモデルではなく、JSONに変換できるデータを受け取ることに注意してください。
+
+テストにPydanticモデルがあり、テスト中にそのデータをアプリケーションに送信したい場合は、[JSON互換エンコーダ](encoder.md){.internal-link target=_blank} で説明されている `jsonable_encoder` が利用できます。
+
+///
## 実行
diff --git a/docs/ja/docs/virtual-environments.md b/docs/ja/docs/virtual-environments.md
new file mode 100644
index 000000000..791cf64a8
--- /dev/null
+++ b/docs/ja/docs/virtual-environments.md
@@ -0,0 +1,831 @@
+# 仮想環境
+
+Pythonプロジェクトの作業では、**仮想環境**(または類似の仕組み)を使用し、プロジェクトごとにインストールするパッケージを分離するべきでしょう。
+
+/// info | 情報
+
+もし、仮想環境の概要や作成方法、使用方法について既にご存知なら、このセクションをスキップすることができます。🤓
+
+///
+
+/// tip | 豆知識
+
+**仮想環境**は、**環境変数**とは異なります。
+
+**環境変数**は、プログラムが使用できるシステム内の変数です。
+
+**仮想環境**は、ファイルをまとめたディレクトリのことです。
+
+///
+
+/// info | 情報
+このページでは、**仮想環境**の使用方法と、そのはたらきについて説明します。
+
+もし**すべてを管理するツール**(Pythonのインストールも含む)を導入する準備ができているなら、uv をお試しください。
+
+///
+
+## プロジェクトの作成
+
+まず、プロジェクト用のディレクトリを作成します。
+
+私は通常 home/user ディレクトリの中に `code` というディレクトリを用意していて、プロジェクトごとに1つのディレクトリをその中に作成しています。
+
+
+
+## 사용 가능한 응답들
+
+다음은 사용할 수 있는 몇가지 응답들 입니다.
+
+`Response`를 사용하여 다른 어떤 것도 반환 할수 있으며, 직접 하위 클래스를 만들 수도 있습니다.
+
+/// note | 기술 세부사항
+
+`from starlette.responses import HTMLResponse`를 사용할 수도 있습니다.
+
+**FastAPI**는 개발자인 여러분의 편의를 위해 `starlette.responses`를 `fastapi.responses`로 제공 하지만, 대부분의 사용 가능한 응답은 Starlette에서 직접 가져옵니다.
+
+///
+
+### `Response`
+
+기본 `Response` 클래스는 다른 모든 응답 클래스의 부모 클래스 입니다.
+
+이 클래스를 직접 반환할 수 있습니다.
+
+다음 매개변수를 받을 수 있습니다:
+
+* `content` - `str` 또는 `bytes`.
+* `status_code` - HTTP 상태코드를 나타내는 `int`.
+* `headers` - 문자열로 이루어진 `dict`.
+* `media_type` - 미디어 타입을 나타내는 `str` 예: `"text/html"`.
+
+FastAPI (실제로는 Starlette)가 자동으로 `Content-Length` 헤더를 포함시킵니다. 또한 `media_type`에 기반하여 `Content-Type` 헤더를 포함하며, 텍스트 타입의 경우 문자 집합을 추가 합니다.
+
+{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
+
+### `HTMLResponse`
+
+텍스트 또는 바이트를 받아 HTML 응답을 반환합니다. 위에서 설명한 내용과 같습니다.
+
+### `PlainTextResponse`
+
+텍스트 또는 바이트를 받아 일반 텍스트 응답을 반환합니다.
+
+{* ../../docs_src/custom_response/tutorial005.py hl[2,7,9] *}
+
+### `JSONResponse`
+
+데이터를 받아 `application/json`으로 인코딩된 응답을 반환합니다.
+
+이는 위에서 설명했듯이 **FastAPI**에서 기본적으로 사용되는 응답 형식입니다.
+
+### `ORJSONResponse`
+
+ `orjson`을 사용하여 빠른 JSON 응답을 제공하는 대안입니다. 위에서 설명한 내용과 같습니다.
+
+/// info | 정보
+
+이를 사용하려면 `orjson`을 설치해야합니다. 예: `pip install orjson`.
+
+///
+
+### `UJSONResponse`
+
+`ujson`을 사용한 또 다른 JSON 응답 형식입니다.
+
+/// info | 정보
+
+이 응답을 사용하려면 `ujson`을 설치해야합니다. 예: 'pip install ujson`.
+
+///
+
+/// warning | 경고
+
+`ujson` 은 일부 예외 경우를 처리하는 데 있어 Python 내장 구현보다 덜 엄격합니다.
+
+///
+
+{* ../../docs_src/custom_response/tutorial001.py hl[2,7] *}
+
+/// tip | 팁
+
+`ORJSONResponse`가 더 빠른 대안일 가능성이 있습니다.
+
+///
+
+### `RedirectResponse`
+
+HTTP 리디렉션 응답을 반환합니다. 기본적으로 상태 코드는 307(임시 리디렉션)으로 설정됩니다.
+
+`RedirectResponse`를 직접 반환할 수 있습니다.
+
+{* ../../docs_src/custom_response/tutorial006.py hl[2,9] *}
+
+---
+
+또는 `response_class` 매개변수에서 사용할 수도 있습니다:
+
+
+{* ../../docs_src/custom_response/tutorial006b.py hl[2,7,9] *}
+
+이 경우, *경로 작업* 함수에서 URL을 직접 반환할 수 있습니다.
+
+이 경우, 사용되는 `status_code`는 `RedirectResponse`의 기본값인 `307` 입니다.
+
+---
+
+`status_code` 매개변수를 `response_class` 매개변수와 함께 사용할 수도 있습니다:
+
+{* ../../docs_src/custom_response/tutorial006c.py hl[2,7,9] *}
+
+### `StreamingResponse`
+
+비동기 제너레이터 또는 일반 제너레이터/이터레이터를 받아 응답 본문을 스트리밍 합니다.
+
+{* ../../docs_src/custom_response/tutorial007.py hl[2,14] *}
+
+#### 파일과 같은 객체를 사용한 `StreamingResponse`
+
+파일과 같은 객체(예: `open()`으로 반환된 객체)가 있는 경우, 해당 파일과 같은 객체를 반복(iterate)하는 제너레이터 함수를 만들 수 있습니다.
+
+이 방식으로, 파일 전체를 메모리에 먼저 읽어들일 필요 없이, 제너레이터 함수를 `StreamingResponse`에 전달하여 반환할 수 있습니다.
+
+이 방식은 클라우드 스토리지, 비디오 처리 등의 다양한 라이브러리와 함께 사용할 수 있습니다.
+
+{* ../../docs_src/custom_response/tutorial008.py hl[2,10:12,14] *}
+
+1. 이것이 제너레이터 함수입니다. `yield` 문을 포함하고 있으므로 "제너레이터 함수"입니다.
+2. `with` 블록을 사용함으로써, 제너레이터 함수가 완료된 후 파일과 같은 객체가 닫히도록 합니다. 즉, 응답 전송이 끝난 후 닫힙니다.
+3. 이 `yield from`은 함수가 `file_like`라는 객체를 반복(iterate)하도록 합니다. 반복된 각 부분은 이 제너레이터 함수(`iterfile`)에서 생성된 것처럼 `yield` 됩니다.
+
+ 이렇게 하면 "생성(generating)" 작업을 내부적으로 다른 무언가에 위임하는 제너레이터 함수가 됩니다.
+
+ 이 방식을 사용하면 `with` 블록 안에서 파일을 열 수 있어, 작업이 완료된 후 파일과 같은 객체가 닫히는 것을 보장할 수 있습니다.
+
+/// tip | 팁
+
+여기서 표준 `open()`을 사용하고 있기 때문에 `async`와 `await`를 지원하지 않습니다. 따라서 경로 작업은 일반 `def`로 선언합니다.
+
+///
+
+### `FileResponse`
+
+파일을 비동기로 스트리밍하여 응답합니다.
+
+다른 응답 유형과는 다른 인수를 사용하여 객체를 생성합니다:
+
+* `path` - 스트리밍할 파일의 경로.
+* `headers` - 딕셔너리 형식의 사용자 정의 헤더.
+* `media_type` - 미디어 타입을 나타내는 문자열. 설정되지 않은 경우 파일 이름이나 경로를 사용하여 추론합니다.
+* `filename` - 설정된 경우 응답의 `Content-Disposition`에 포함됩니다.
+
+파일 응답에는 적절한 `Content-Length`, `Last-Modified`, 및 `ETag` 헤더가 포함됩니다.
+
+{* ../../docs_src/custom_response/tutorial009.py hl[2,10] *}
+
+또한 `response_class` 매개변수를 사용할 수도 있습니다:
+
+{* ../../docs_src/custom_response/tutorial009b.py hl[2,8,10] *}
+
+이 경우, 경로 작업 함수에서 파일 경로를 직접 반환할 수 있습니다.
+
+## 사용자 정의 응답 클래스
+
+`Response`를 상속받아 사용자 정의 응답 클래스를 생성하고 사용할 수 있습니다.
+
+예를 들어, 포함된 `ORJSONResponse` 클래스에서 사용되지 않는 설정으로 orjson을 사용하고 싶다고 가정해봅시다.
+
+만약 들여쓰기 및 포맷된 JSON을 반환하고 싶다면, `orjson.OPT_INDENT_2` 옵션을 사용할 수 있습니다.
+
+`CustomORJSONResponse`를 생성할 수 있습니다. 여기서 핵심은 `Response.render(content)` 메서드를 생성하여 내용을 `bytes`로 반환하는 것입니다:
+
+{* ../../docs_src/custom_response/tutorial009c.py hl[9:14,17] *}
+
+이제 다음 대신:
+
+```json
+{"message": "Hello World"}
+```
+
+이 응답은 이렇게 반환됩니다:
+
+```json
+{
+ "message": "Hello World"
+}
+```
+
+물론 JSON 포맷팅보다 더 유용하게 활용할 방법을 찾을 수 있을 것입니다. 😉
+
+## 기본 응답 클래스
+
+**FastAPI** 클래스 객체 또는 `APIRouter`를 생성할 때 기본적으로 사용할 응답 클래스를 지정할 수 있습니다.
+
+이를 정의하는 매개변수는 `default_response_class`입니다.
+
+아래 예제에서 **FastAPI**는 모든 경로 작업에서 기본적으로 `JSONResponse` 대신 `ORJSONResponse`를 사용합니다.
+
+{* ../../docs_src/custom_response/tutorial010.py hl[2,4] *}
+
+/// tip | 팁
+
+여전히 이전처럼 *경로 작업*에서 `response_class`를 재정의할 수 있습니다.
+
+///
+
+## 추가 문서화
+
+OpenAPI에서 `responses`를 사용하여 미디어 타입 및 기타 세부 정보를 선언할 수도 있습니다: [OpenAPI에서 추가 응답](additional-responses.md){.internal-link target=_blank}.
diff --git a/docs/ko/docs/advanced/events.md b/docs/ko/docs/advanced/events.md
index d3227497b..5f8fe0f1e 100644
--- a/docs/ko/docs/advanced/events.md
+++ b/docs/ko/docs/advanced/events.md
@@ -1,45 +1,165 @@
-# 이벤트: startup과 shutdown
+# Lifespan 이벤트
-필요에 따라 응용 프로그램이 시작되기 전이나 종료될 때 실행되는 이벤트 핸들러(함수)를 정의할 수 있습니다.
+애플리케이션 **시작 전**에 실행되어야 하는 로직(코드)을 정의할 수 있습니다. 이는 이 코드가 **한 번**만 실행되며, **애플리케이션이 요청을 받기 시작하기 전**에 실행된다는 의미입니다.
-이 함수들은 `async def` 또는 평범하게 `def`으로 선언할 수 있습니다.
+마찬가지로, 애플리케이션이 **종료될 때** 실행되어야 하는 로직(코드)을 정의할 수 있습니다. 이 경우, 이 코드는 **한 번**만 실행되며, **여러 요청을 처리한 후**에 실행됩니다.
-!!! warning "경고"
- 이벤트 핸들러는 주 응용 프로그램에서만 작동합니다. [하위 응용 프로그램 - 마운트](./sub-applications.md){.internal-link target=_blank}에서는 작동하지 않습니다.
+이 코드가 애플리케이션이 **요청을 받기 시작하기 전에** 실행되고, 요청 처리가 끝난 후 **종료 직전에** 실행되기 때문에 전체 애플리케이션의 **수명(Lifespan)**을 다룹니다. (잠시 후 "수명"이라는 단어가 중요해집니다 😉)
-## `startup` 이벤트
+이 방법은 전체 애플리케이션에서 사용해야 하는 **자원**을 설정하거나 요청 간에 **공유되는** 자원을 설정하고, 또는 그 후에 **정리**하는 데 매우 유용할 수 있습니다. 예를 들어, 데이터베이스 연결 풀 또는 공유되는 머신러닝 모델을 로드하는 경우입니다.
-응용 프로그램을 시작하기 전에 실행하려는 함수를 "startup" 이벤트로 선언합니다:
-```Python hl_lines="8"
-{!../../../docs_src/events/tutorial001.py!}
+## 사용 사례
+
+먼저 **사용 사례**를 예로 들어보고, 이를 어떻게 해결할 수 있는지 살펴보겠습니다.
+
+우리가 요청을 처리하기 위해 사용하고 싶은 **머신러닝 모델**이 있다고 상상해 봅시다. 🤖
+
+이 모델들은 요청 간에 공유되므로, 요청마다 모델이 하나씩 있는 것이 아니라, 여러 요청에서 동일한 모델을 사용합니다.
+
+모델을 로드하는 데 **상당한 시간이 걸린다고 상상해 봅시다**, 왜냐하면 모델이 **디스크에서 많은 데이터를 읽어야** 하기 때문입니다. 따라서 모든 요청에 대해 모델을 매번 로드하고 싶지 않습니다.
+
+모듈/파일의 최상위에서 모델을 로드할 수도 있지만, 그러면 **모델을 로드하는데** 시간이 걸리기 때문에, 단순한 자동화된 테스트를 실행할 때도 모델이 로드될 때까지 기다려야 해서 **테스트 속도가 느려집니다**.
+
+이 문제를 해결하려고 하는 것입니다. 요청을 처리하기 전에 모델을 로드하되, 애플리케이션이 요청을 받기 시작하기 직전에만 로드하고, 코드가 로드되는 동안은 로드하지 않도록 하겠습니다.
+
+## Lifespan
+
+`FastAPI` 애플리케이션의 `lifespan` 매개변수와 "컨텍스트 매니저"를 사용하여 *시작*과 *종료* 로직을 정의할 수 있습니다. (컨텍스트 매니저가 무엇인지 잠시 후에 설명드리겠습니다.)
+
+예제를 통해 시작하고, 그 후에 자세히 살펴보겠습니다.
+
+우리는 `yield`를 사용하여 비동기 함수 `lifespan()`을 다음과 같이 생성합니다:
+
+{* ../../docs_src/events/tutorial003.py hl[16,19] *}
+
+여기서 우리는 모델을 로드하는 비싼 *시작* 작업을 시뮬레이션하고 있습니다. `yield` 앞에서 (가짜) 모델 함수를 머신러닝 모델이 담긴 딕셔너리에 넣습니다. 이 코드는 **애플리케이션이 요청을 받기 시작하기 전**, *시작* 동안에 실행됩니다.
+
+그리고 `yield` 직후에는 모델을 언로드합니다. 이 코드는 **애플리케이션이 요청 처리 완료 후**, *종료* 직전에 실행됩니다. 예를 들어, 메모리나 GPU와 같은 자원을 해제하는 작업을 할 수 있습니다.
+
+/// tip | 팁
+
+`shutdown`은 애플리케이션을 **종료**할 때 발생합니다.
+
+새로운 버전을 시작해야 하거나, 그냥 실행을 멈추고 싶을 수도 있습니다. 🤷
+
+///
+
+### Lifespan 함수
+
+먼저 주목할 점은, `yield`를 사용하여 비동기 함수(async function)를 정의하고 있다는 것입니다. 이는 `yield`를 사용한 의존성과 매우 유사합니다.
+
+{* ../../docs_src/events/tutorial003.py hl[14:19] *}
+
+함수의 첫 번째 부분, 즉 `yield` 이전의 코드는 애플리케이션이 시작되기 **전에** 실행됩니다.
+
+그리고 `yield` 이후의 부분은 애플리케이션이 완료된 후 **나중에** 실행됩니다.
+
+### 비동기 컨텍스트 매니저
+
+함수를 확인해보면, `@asynccontextmanager`로 장식되어 있습니다.
+
+이것은 함수를 "**비동기 컨텍스트 매니저**"라고 불리는 것으로 변환시킵니다.
+
+{* ../../docs_src/events/tutorial003.py hl[1,13] *}
+
+파이썬에서 **컨텍스트 매니저**는 `with` 문에서 사용할 수 있는 것입니다. 예를 들어, `open()`은 컨텍스트 매니저로 사용할 수 있습니다:
+
+```Python
+with open("file.txt") as file:
+ file.read()
+```
+최근 버전의 파이썬에서는 **비동기 컨텍스트 매니저**도 있습니다. 이를 `async with`와 함께 사용합니다:
+
+```Python
+async with lifespan(app):
+ await do_stuff()
```
-이 경우 `startup` 이벤트 핸들러 함수는 단순히 몇 가지 값으로 구성된 `dict` 형식의 "데이터베이스"를 초기화합니다.
+컨텍스트 매니저나 위와 같은 비동기 컨텍스트 매니저를 만들면, `with` 블록에 들어가기 전에 `yield` 이전의 코드가 실행되고, `with` 블록을 벗어난 후에는 `yield` 이후의 코드가 실행됩니다.
-하나 이상의 이벤트 핸들러 함수를 추가할 수도 있습니다.
+위의 코드 예제에서는 직접 사용하지 않고, FastAPI에 전달하여 사용하도록 합니다.
-그리고 응용 프로그램은 모든 `startup` 이벤트 핸들러가 완료될 때까지 요청을 받지 않습니다.
+`FastAPI` 애플리케이션의 `lifespan` 매개변수는 **비동기 컨텍스트 매니저**를 받기 때문에, 새로운 `lifespan` 비동기 컨텍스트 매니저를 FastAPI에 전달할 수 있습니다.
-## `shutdown` 이벤트
+{* ../../docs_src/events/tutorial003.py hl[22] *}
-응용 프로그램이 종료될 때 실행하려는 함수를 추가하려면 `"shutdown"` 이벤트로 선언합니다:
+## 대체 이벤트 (사용 중단)
-```Python hl_lines="6"
-{!../../../docs_src/events/tutorial002.py!}
-```
+/// warning | 경고
-이 예제에서 `shutdown` 이벤트 핸들러 함수는 `"Application shutdown"`이라는 텍스트가 적힌 `log.txt` 파일을 추가할 것입니다.
+*시작*과 *종료*를 처리하는 권장 방법은 위에서 설명한 대로 `FastAPI` 애플리케이션의 `lifespan` 매개변수를 사용하는 것입니다. `lifespan` 매개변수를 제공하면 `startup`과 `shutdown` 이벤트 핸들러는 더 이상 호출되지 않습니다. `lifespan`을 사용할지, 모든 이벤트를 사용할지 선택해야 하며 둘 다 사용할 수는 없습니다.
-!!! info "정보"
- `open()` 함수에서 `mode="a"`는 "추가"를 의미합니다. 따라서 이미 존재하는 파일의 내용을 덮어쓰지 않고 새로운 줄을 추가합니다.
+이 부분은 건너뛰셔도 좋습니다.
-!!! tip "팁"
- 이 예제에서는 파일과 상호작용 하기 위해 파이썬 표준 함수인 `open()`을 사용하고 있습니다.
+///
- 따라서 디스크에 데이터를 쓰기 위해 "대기"가 필요한 I/O (입력/출력) 작업을 수행합니다.
+*시작*과 *종료* 동안 실행될 이 로직을 정의하는 대체 방법이 있습니다.
- 그러나 `open()`은 `async`와 `await`을 사용하지 않기 때문에 이벤트 핸들러 함수는 `async def`가 아닌 표준 `def`로 선언하고 있습니다.
+애플리케이션이 시작되기 전에 또는 종료될 때 실행해야 하는 이벤트 핸들러(함수)를 정의할 수 있습니다.
-!!! info "정보"
- 이벤트 핸들러에 관한 내용은 Starlette 이벤트 문서에서 추가로 확인할 수 있습니다.
+이 함수들은 `async def` 또는 일반 `def`로 선언할 수 있습니다.
+
+### `startup` 이벤트
+
+애플리케이션이 시작되기 전에 실행되어야 하는 함수를 추가하려면, `"startup"` 이벤트로 선언합니다:
+
+{* ../../docs_src/events/tutorial001.py hl[8] *}
+
+이 경우, `startup` 이벤트 핸들러 함수는 "database"라는 항목(단지 `dict`)을 일부 값으로 초기화합니다.
+
+여러 개의 이벤트 핸들러 함수를 추가할 수 있습니다.
+
+애플리케이션은 모든 `startup` 이벤트 핸들러가 완료될 때까지 요청을 받기 시작하지 않습니다.
+
+### `shutdown` 이벤트
+
+애플리케이션이 종료될 때 실행되어야 하는 함수를 추가하려면, `"shutdown"` 이벤트로 선언합니다:
+
+{* ../../docs_src/events/tutorial002.py hl[6] *}
+
+여기서, `shutdown` 이벤트 핸들러 함수는 `"Application shutdown"`이라는 텍스트를 `log.txt` 파일에 기록합니다.
+
+/// info | 정보
+
+`open()` 함수에서 `mode="a"`는 "추가"를 의미하므로, 파일에 있는 기존 내용은 덮어쓰지 않고 새로운 줄이 추가됩니다.
+
+///
+
+/// tip | 팁
+
+이 경우, 우리는 표준 파이썬 `open()` 함수를 사용하여 파일과 상호작용하고 있습니다.
+
+따라서 I/O(입출력) 작업이 포함되어 있어 디스크에 기록되는 것을 "기다리는" 과정이 필요합니다.
+
+하지만 `open()`은 `async`와 `await`를 사용하지 않습니다.
+
+그래서 우리는 이벤트 핸들러 함수를 `async def` 대신 일반 `def`로 선언합니다.
+
+///
+
+### `startup`과 `shutdown`을 함께 사용
+
+*시작*과 *종료* 로직이 연결될 가능성이 높습니다. 예를 들어, 무언가를 시작한 후 끝내거나, 자원을 획득한 후 해제하는 등의 작업을 할 수 있습니다.
+
+이러한 작업을 별도의 함수로 처리하면 서로 로직이나 변수를 공유하지 않기 때문에 더 어려워집니다. 값들을 전역 변수에 저장하거나 비슷한 트릭을 사용해야 할 수 있습니다.
+
+그렇기 때문에 위에서 설명한 대로 `lifespan`을 사용하는 것이 권장됩니다.
+
+## 기술적 세부사항
+
+호기심 많은 분들을 위한 기술적인 세부사항입니다. 🤓
+
+ASGI 기술 사양에 따르면, 이는 Lifespan Protocol의 일부이며, `startup`과 `shutdown`이라는 이벤트를 정의합니다.
+
+/// info | 정보
+
+Starlette의 `lifespan` 핸들러에 대해 더 읽고 싶다면 Starlette의 Lifespan 문서에서 확인할 수 있습니다.
+
+이 문서에는 코드의 다른 영역에서 사용할 수 있는 lifespan 상태를 처리하는 방법도 포함되어 있습니다.
+
+///
+
+## 서브 애플리케이션
+
+🚨 이 lifespan 이벤트(`startup`과 `shutdown`)는 메인 애플리케이션에 대해서만 실행되며, [서브 애플리케이션 - Mounts](sub-applications.md){.internal-link target=_blank}에는 실행되지 않음을 유의하세요.
diff --git a/docs/ko/docs/advanced/index.md b/docs/ko/docs/advanced/index.md
index 5fd1711a1..31704727c 100644
--- a/docs/ko/docs/advanced/index.md
+++ b/docs/ko/docs/advanced/index.md
@@ -6,10 +6,13 @@
이어지는 장에서는 여러분이 다른 옵션, 구성 및 추가 기능을 보실 수 있습니다.
-!!! tip "팁"
- 다음 장들이 **반드시 "심화"**인 것은 아닙니다.
+/// tip | 팁
- 그리고 여러분의 사용 사례에 대한 해결책이 그중 하나에 있을 수 있습니다.
+다음 장들이 **반드시 "심화"**인 것은 아닙니다.
+
+그리고 여러분의 사용 사례에 대한 해결책이 그중 하나에 있을 수 있습니다.
+
+///
## 자습서를 먼저 읽으십시오
diff --git a/docs/ko/docs/advanced/middlewares.md b/docs/ko/docs/advanced/middlewares.md
new file mode 100644
index 000000000..c00aedeaf
--- /dev/null
+++ b/docs/ko/docs/advanced/middlewares.md
@@ -0,0 +1,96 @@
+# 고급 미들웨어
+
+메인 튜토리얼에서 [Custom Middleware](../tutorial/middleware.md){.internal-link target=_blank}를 응용프로그램에 추가하는 방법을 읽으셨습니다.
+
+그리고 [CORS with the `CORSMiddleware`](){.internal-link target=_blank}하는 방법도 보셨습니다.
+
+이 섹션에서는 다른 미들웨어들을 사용하는 방법을 알아보겠습니다.
+
+## ASGI 미들웨어 추가하기
+
+**FastAPI**는 Starlette을 기반으로 하고 있으며, ASGI 사양을 구현하므로 ASGI 미들웨어를 사용할 수 있습니다.
+
+미들웨어가 FastAPI나 Starlette용으로 만들어지지 않아도 ASGI 사양을 준수하는 한 동작할 수 있습니다.
+
+일반적으로 ASGI 미들웨어는 첫 번째 인수로 ASGI 앱을 받는 클래스들입니다.
+
+따라서 타사 ASGI 미들웨어 문서에서 일반적으로 다음과 같이 사용하도록 안내할 것입니다.
+
+```Python
+from unicorn import UnicornMiddleware
+
+app = SomeASGIApp()
+
+new_app = UnicornMiddleware(app, some_config="rainbow")
+```
+
+하지만 내부 미들웨어가 서버 오류를 처리하고 사용자 정의 예외 처리기가 제대로 작동하도록 하는 더 간단한 방법을 제공하는 FastAPI(실제로는 Starlette)가 있습니다.
+
+이를 위해 `app.add_middleware()`를 사용합니다(CORS의 예에서와 같이).
+
+```Python
+from fastapi import FastAPI
+from unicorn import UnicornMiddleware
+
+app = FastAPI()
+
+app.add_middleware(UnicornMiddleware, some_config="rainbow")
+```
+
+`app.add_middleware()`는 첫 번째 인수로 미들웨어 클래스와 미들웨어에 전달할 추가 인수를 받습니다.
+
+## 통합 미들웨어
+
+**FastAPI**에는 일반적인 사용 사례를 위한 여러 미들웨어가 포함되어 있으며, 사용 방법은 다음에서 살펴보겠습니다.
+
+/// note | 기술 세부 사항
+
+다음 예제에서는 `from starlette.middleware.something import SomethingMiddleware`를 사용할 수도 있습니다.
+
+**FastAPI**는 개발자의 편의를 위해 `fastapi.middleware`에 여러 미들웨어를 제공합니다. 그러나 사용 가능한 대부분의 미들웨어는 Starlette에서 직접 제공합니다.
+
+///
+
+## `HTTPSRedirectMiddleware`
+
+들어오는 모든 요청이 `https` 또는 `wss`여야 합니다.
+
+`http` 또는 `ws`로 들어오는 모든 요청은 대신 보안 체계로 리디렉션됩니다.
+
+{* ../../docs_src/advanced_middleware/tutorial001.py hl[2,6] *}
+
+## `TrustedHostMiddleware`
+
+HTTP 호스트 헤더 공격을 방지하기 위해 모든 수신 요청에 올바르게 설정된 `Host` 헤더를 갖도록 강제합니다.
+
+{* ../../docs_src/advanced_middleware/tutorial002.py hl[2,6:8] *}
+
+다음 인수가 지원됩니다:
+
+* `allowed_hosts` - 호스트 이름으로 허용해야 하는 도메인 이름 목록입니다. 일치하는 하위 도메인에 대해 `*.example.com`과 같은 와일드카드 도메인이 지원됩니다. 모든 호스트 이름을 허용하려면 `allowed_hosts=[“*”]`를 사용하거나 미들웨어를 생략하세요.
+
+수신 요청의 유효성이 올바르게 확인되지 않으면 `400`이라는 응답이 전송됩니다.
+
+## `GZipMiddleware`
+
+`Accept-Encoding` 헤더에 `“gzip”`이 포함된 모든 요청에 대해 GZip 응답을 처리합니다.
+
+미들웨어는 표준 응답과 스트리밍 응답을 모두 처리합니다.
+
+{* ../../docs_src/advanced_middleware/tutorial003.py hl[2,6] *}
+
+지원되는 인수는 다음과 같습니다:
+
+* `minimum_size` - 이 최소 크기(바이트)보다 작은 응답은 GZip하지 않습니다. 기본값은 `500`입니다.
+* `compresslevel` - GZip 압축 중에 사용됩니다. 1에서 9 사이의 정수입니다. 기본값은 `9`입니다. 값이 낮을수록 압축 속도는 빨라지지만 파일 크기는 커지고, 값이 높을수록 압축 속도는 느려지지만 파일 크기는 작아집니다.
+
+## 기타 미들웨어
+
+다른 많은 ASGI 미들웨어가 있습니다.
+
+예를 들어:
+
+유비콘의 `ProxyHeadersMiddleware`>
+MessagePack
+
+사용 가능한 다른 미들웨어를 확인하려면 스타렛의 미들웨어 문서 및 ASGI Awesome List를 참조하세요.
diff --git a/docs/ko/docs/advanced/response-change-status-code.md b/docs/ko/docs/advanced/response-change-status-code.md
new file mode 100644
index 000000000..1ba9aa3cc
--- /dev/null
+++ b/docs/ko/docs/advanced/response-change-status-code.md
@@ -0,0 +1,31 @@
+# 응답 - 상태 코드 변경
+
+기본 [응답 상태 코드 설정](../tutorial/response-status-code.md){.internal-link target=_blank}이 가능하다는 걸 이미 알고 계실 겁니다.
+
+하지만 경우에 따라 기본 설정과 다른 상태 코드를 반환해야 할 때가 있습니다.
+
+## 사용 예
+
+예를 들어 기본적으로 HTTP 상태 코드 "OK" `200`을 반환하고 싶다고 가정해 봅시다.
+
+하지만 데이터가 존재하지 않으면 이를 새로 생성하고, HTTP 상태 코드 "CREATED" `201`을 반환하고자 할 때가 있을 수 있습니다.
+
+이때도 여전히 `response_model`을 사용하여 반환하는 데이터를 필터링하고 변환하고 싶을 수 있습니다.
+
+이런 경우에는 `Response` 파라미터를 사용할 수 있습니다.
+
+## `Response` 파라미터 사용하기
+
+*경로 작동 함수*에 `Response` 타입의 파라미터를 선언할 수 있습니다. (쿠키와 헤더에 대해 선언하는 것과 유사하게)
+
+그리고 이 *임시* 응답 객체에서 `status_code`를 설정할 수 있습니다.
+
+{* ../../docs_src/response_change_status_code/tutorial001.py hl[1,9,12] *}
+
+그리고 평소처럼 원하는 객체(`dict`, 데이터베이스 모델 등)를 반환할 수 있습니다.
+
+`response_model`을 선언했다면 반환된 객체는 여전히 필터링되고 변환됩니다.
+
+**FastAPI**는 이 *임시* 응답 객체에서 상태 코드(쿠키와 헤더 포함)를 추출하여, `response_model`로 필터링된 반환 값을 최종 응답에 넣습니다.
+
+또한, 의존성에서도 `Response` 파라미터를 선언하고 그 안에서 상태 코드를 설정할 수 있습니다. 단, 마지막으로 설정된 상태 코드가 우선 적용된다는 점을 유의하세요.
diff --git a/docs/ko/docs/advanced/response-cookies.md b/docs/ko/docs/advanced/response-cookies.md
new file mode 100644
index 000000000..327f20afe
--- /dev/null
+++ b/docs/ko/docs/advanced/response-cookies.md
@@ -0,0 +1,49 @@
+# 응답 쿠키
+
+## `Response` 매개변수 사용하기
+
+*경로 작동 함수*에서 `Response` 타입의 매개변수를 선언할 수 있습니다.
+
+그런 다음 해당 *임시* 응답 객체에서 쿠키를 설정할 수 있습니다.
+
+{* ../../docs_src/response_cookies/tutorial002.py hl[1,8:9] *}
+
+그런 다음 필요한 객체(`dict`, 데이터베이스 모델 등)를 반환할 수 있습니다.
+
+그리고 `response_model`을 선언했다면 반환한 객체를 거르고 변환하는 데 여전히 사용됩니다.
+
+**FastAPI**는 그 *임시* 응답에서 쿠키(또한 헤더 및 상태 코드)를 추출하고, 반환된 값이 포함된 최종 응답에 이를 넣습니다. 이 값은 `response_model`로 걸러지게 됩니다.
+
+또한 의존관계에서 `Response` 매개변수를 선언하고, 해당 의존성에서 쿠키(및 헤더)를 설정할 수도 있습니다.
+
+## `Response`를 직접 반환하기
+
+코드에서 `Response`를 직접 반환할 때도 쿠키를 생성할 수 있습니다.
+
+이를 위해 [Response를 직접 반환하기](response-directly.md){.internal-link target=_blank}에서 설명한 대로 응답을 생성할 수 있습니다.
+
+그런 다음 쿠키를 설정하고 반환하면 됩니다:
+{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
+/// tip
+
+`Response` 매개변수를 사용하지 않고 응답을 직접 반환하는 경우, FastAPI는 이를 직접 반환한다는 점에 유의하세요.
+
+따라서 데이터가 올바른 유형인지 확인해야 합니다. 예: `JSONResponse`를 반환하는 경우, JSON과 호환되는지 확인하세요.
+
+또한 `response_model`로 걸러져야 할 데이터가 전달되지 않도록 확인하세요.
+
+///
+
+### 추가 정보
+
+/// note | 기술적 세부사항
+
+`from starlette.responses import Response` 또는 `from starlette.responses import JSONResponse`를 사용할 수도 있습니다.
+
+**FastAPI**는 개발자의 편의를 위해 `fastapi.responses`로 동일한 `starlette.responses`를 제공합니다. 그러나 대부분의 응답은 Starlette에서 직접 제공됩니다.
+
+또한 `Response`는 헤더와 쿠키를 설정하는 데 자주 사용되므로, **FastAPI**는 이를 `fastapi.Response`로도 제공합니다.
+
+///
+
+사용 가능한 모든 매개변수와 옵션은 Starlette 문서에서 확인할 수 있습니다.
diff --git a/docs/ko/docs/advanced/response-directly.md b/docs/ko/docs/advanced/response-directly.md
new file mode 100644
index 000000000..08d63c43c
--- /dev/null
+++ b/docs/ko/docs/advanced/response-directly.md
@@ -0,0 +1,63 @@
+# 응답을 직접 반환하기
+
+**FastAPI**에서 *경로 작업(path operation)*을 생성할 때, 일반적으로 `dict`, `list`, Pydantic 모델, 데이터베이스 모델 등의 데이터를 반환할 수 있습니다.
+
+기본적으로 **FastAPI**는 [JSON 호환 가능 인코더](../tutorial/encoder.md){.internal-link target=_blank}에 설명된 `jsonable_encoder`를 사용해 해당 반환 값을 자동으로 `JSON`으로 변환합니다.
+
+그런 다음, JSON 호환 데이터(예: `dict`)를 `JSONResponse`에 넣어 사용자의 응답을 전송하는 방식으로 처리됩니다.
+
+그러나 *경로 작업*에서 `JSONResponse`를 직접 반환할 수도 있습니다.
+
+예를 들어, 사용자 정의 헤더나 쿠키를 반환해야 하는 경우에 유용할 수 있습니다.
+
+## `Response` 반환하기
+
+사실, `Response` 또는 그 하위 클래스를 반환할 수 있습니다.
+
+/// tip
+
+`JSONResponse` 자체도 `Response`의 하위 클래스입니다.
+
+///
+
+그리고 `Response`를 반환하면 **FastAPI**가 이를 그대로 전달합니다.
+
+Pydantic 모델로 데이터 변환을 수행하지 않으며, 내용을 다른 형식으로 변환하지 않습니다.
+
+이로 인해 많은 유연성을 얻을 수 있습니다. 어떤 데이터 유형이든 반환할 수 있고, 데이터 선언이나 유효성 검사를 재정의할 수 있습니다.
+
+## `Response`에서 `jsonable_encoder` 사용하기
+
+**FastAPI**는 반환하는 `Response`에 아무런 변환을 하지 않으므로, 그 내용이 준비되어 있어야 합니다.
+
+예를 들어, Pydantic 모델을 `dict`로 변환해 `JSONResponse`에 넣지 않으면 JSON 호환 유형으로 변환된 데이터 유형(예: `datetime`, `UUID` 등)이 사용되지 않습니다.
+
+이러한 경우, 데이터를 응답에 전달하기 전에 `jsonable_encoder`를 사용하여 변환할 수 있습니다:
+
+{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *}
+
+/// note | 기술적 세부 사항
+
+`from starlette.responses import JSONResponse`를 사용할 수도 있습니다.
+
+**FastAPI**는 개발자의 편의를 위해 `starlette.responses`를 `fastapi.responses`로 제공합니다. 그러나 대부분의 가능한 응답은 Starlette에서 직접 제공합니다.
+
+///
+
+## 사용자 정의 `Response` 반환하기
+위 예제는 필요한 모든 부분을 보여주지만, 아직 유용하지는 않습니다. 사실 데이터를 직접 반환하면 **FastAPI**가 이를 `JSONResponse`에 넣고 `dict`로 변환하는 등 모든 작업을 자동으로 처리합니다.
+
+이제, 사용자 정의 응답을 반환하는 방법을 알아보겠습니다.
+
+예를 들어 XML 응답을 반환하고 싶다고 가정해보겠습니다.
+
+XML 내용을 문자열에 넣고, 이를 `Response`에 넣어 반환할 수 있습니다:
+
+{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
+
+## 참고 사항
+`Response`를 직접 반환할 때, 그 데이터는 자동으로 유효성 검사되거나, 변환(직렬화)되거나, 문서화되지 않습니다.
+
+그러나 [OpenAPI에서 추가 응답](additional-responses.md){.internal-link target=_blank}에서 설명된 대로 문서화할 수 있습니다.
+
+이후 단락에서 자동 데이터 변환, 문서화 등을 사용하면서 사용자 정의 `Response`를 선언하는 방법을 확인할 수 있습니다.
diff --git a/docs/ko/docs/advanced/response-headers.md b/docs/ko/docs/advanced/response-headers.md
new file mode 100644
index 000000000..e8abe0be2
--- /dev/null
+++ b/docs/ko/docs/advanced/response-headers.md
@@ -0,0 +1,41 @@
+# 응답 헤더
+
+## `Response` 매개변수 사용하기
+
+여러분은 *경로 작동 함수*에서 `Response` 타입의 매개변수를 선언할 수 있습니다 (쿠키와 같이 사용할 수 있습니다).
+
+그런 다음, 여러분은 해당 *임시* 응답 객체에서 헤더를 설정할 수 있습니다.
+
+{* ../../docs_src/response_headers/tutorial002.py hl[1,7:8] *}
+
+그 후, 일반적으로 사용하듯이 필요한 객체(`dict`, 데이터베이스 모델 등)를 반환할 수 있습니다.
+
+`response_model`을 선언한 경우, 반환한 객체를 필터링하고 변환하는 데 여전히 사용됩니다.
+
+**FastAPI**는 해당 *임시* 응답에서 헤더(쿠키와 상태 코드도 포함)를 추출하여, 여러분이 반환한 값을 포함하는 최종 응답에 `response_model`로 필터링된 값을 넣습니다.
+
+또한, 종속성에서 `Response` 매개변수를 선언하고 그 안에서 헤더(및 쿠키)를 설정할 수 있습니다.
+
+## `Response` 직접 반환하기
+
+`Response`를 직접 반환할 때에도 헤더를 추가할 수 있습니다.
+
+[응답을 직접 반환하기](response-directly.md){.internal-link target=_blank}에서 설명한 대로 응답을 생성하고, 헤더를 추가 매개변수로 전달하세요.
+
+{* ../../docs_src/response_headers/tutorial001.py hl[10:12] *}
+
+/// note | 기술적 세부사항
+
+`from starlette.responses import Response`나 `from starlette.responses import JSONResponse`를 사용할 수도 있습니다.
+
+**FastAPI**는 `starlette.responses`를 `fastapi.responses`로 개발자의 편의를 위해 직접 제공하지만, 대부분의 응답은 Starlette에서 직접 제공됩니다.
+
+그리고 `Response`는 헤더와 쿠키를 설정하는 데 자주 사용될 수 있으므로, **FastAPI**는 `fastapi.Response`로도 이를 제공합니다.
+
+///
+
+## 커스텀 헤더
+
+‘X-’ 접두어를 사용하여 커스텀 사설 헤더를 추가할 수 있습니다.
+
+하지만, 여러분이 브라우저에서 클라이언트가 볼 수 있기를 원하는 커스텀 헤더가 있는 경우, CORS 설정에 이를 추가해야 합니다([CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md){.internal-link target=_blank}에서 자세히 알아보세요). `expose_headers` 매개변수를 사용하여 Starlette의 CORS 설명서에 문서화된 대로 설정할 수 있습니다.
diff --git a/docs/ko/docs/advanced/sub-applications.md b/docs/ko/docs/advanced/sub-applications.md
new file mode 100644
index 000000000..c5835de15
--- /dev/null
+++ b/docs/ko/docs/advanced/sub-applications.md
@@ -0,0 +1,67 @@
+# 하위 응용프로그램 - 마운트
+
+만약 각각의 독립적인 OpenAPI와 문서 UI를 갖는 두 개의 독립적인 FastAPI 응용프로그램이 필요하다면, 메인 어플리케이션에 하나 (또는 그 이상의) 하위-응용프로그램(들)을 “마운트"해서 사용할 수 있습니다.
+
+## **FastAPI** 응용프로그램 마운트
+
+“마운트"이란 완전히 “독립적인" 응용프로그램을 특정 경로에 추가하여 해당 하위 응용프로그램에서 선언된 *경로 동작*을 통해 해당 경로 아래에 있는 모든 작업들을 처리할 수 있도록 하는 것을 의미합니다.
+
+### 최상단 응용프로그램
+
+먼저, 메인, 최상단의 **FastAPI** 응용프로그램과 이것의 *경로 동작*을 생성합니다:
+
+{* ../../docs_src/sub_applications/tutorial001.py hl[3, 6:8] *}
+
+### 하위 응용프로그램
+
+다음으로, 하위 응용프로그램과 이것의 *경로 동작*을 생성합니다:
+
+이 하위 응용프로그램은 또 다른 표준 FastAPI 응용프로그램입니다. 다만 이것은 “마운트”될 것입니다:
+
+{* ../../docs_src/sub_applications/tutorial001.py hl[11, 14:16] *}
+
+### 하위 응용프로그램 마운트
+
+최상단 응용프로그램, `app`에 하위 응용프로그램, `subapi`를 마운트합니다.
+
+이 예시에서, 하위 응용프로그램션은 `/subapi` 경로에 마운트 될 것입니다:
+
+{* ../../docs_src/sub_applications/tutorial001.py hl[11, 19] *}
+
+### 자동으로 생성된 API 문서 확인
+
+이제, `uvicorn`으로 메인 응용프로그램을 실행하십시오. 당신의 파일이 `main.py`라면, 이렇게 실행합니다:
+
+
+
+다음으로, http://127.0.0.1:8000/subapi/docs에서 하위 응용프로그램의 문서를 여십시오.
+
+하위 경로 접두사 `/subapi` 아래에 선언된 *경로 동작* 을 포함하는, 하위 응용프로그램에 대한 자동 API 문서를 확인할 수 있습니다:
+
+
+
+두 사용자 인터페이스 중 어느 하나를 사용해야하는 경우, 브라우저는 특정 응용프로그램 또는 하위 응용프로그램과 각각 통신할 수 있기 때문에 올바르게 동작할 것입니다.
+
+### 기술적 세부사항: `root_path`
+
+위에 설명된 것과 같이 하위 응용프로그램을 마운트하는 경우, FastAPI는 `root_path`라고 하는 ASGI 명세의 매커니즘을 사용하여 하위 응용프로그램에 대한 마운트 경로 통신을 처리합니다.
+
+이를 통해, 하위 응용프로그램은 문서 UI를 위해 경로 접두사를 사용해야 한다는 사실을 인지합니다.
+
+하위 응용프로그램에도 역시 다른 하위 응용프로그램을 마운트하는 것이 가능하며 FastAPI가 모든 `root_path` 들을 자동적으로 처리하기 때문에 모든 것은 올바르게 동작할 것입니다.
+
+`root_path`와 이것을 사용하는 방법에 대해서는 [프록시의 뒷단](./behind-a-proxy.md){.internal-link target=_blank} 섹션에서 배울 수 있습니다.
diff --git a/docs/ko/docs/advanced/templates.md b/docs/ko/docs/advanced/templates.md
new file mode 100644
index 000000000..4cb4cbe0d
--- /dev/null
+++ b/docs/ko/docs/advanced/templates.md
@@ -0,0 +1,127 @@
+# 템플릿
+
+**FastAPI**와 함께 원하는 어떤 템플릿 엔진도 사용할 수 있습니다.
+
+일반적인 선택은 Jinja2로, Flask와 다른 도구에서도 사용됩니다.
+
+설정을 쉽게 할 수 있는 유틸리티가 있으며, 이를 **FastAPI** 애플리케이션에서 직접 사용할 수 있습니다(Starlette 제공).
+
+## 의존성 설치
+
+가상 환경을 생성하고(virtual environment{.internal-link target=_blank}), 활성화한 후 jinja2를 설치해야 합니다:
+
+
+
+
+입력창에 메시지를 입력하고 전송할 수 있습니다:
+
+
+
+**FastAPI** WebSocket 응용 프로그램이 응답을 돌려줄 것입니다:
+
+
+
+여러 메시지를 전송(그리고 수신)할 수 있습니다:
+
+
+
+모든 메시지는 동일한 WebSocket 연결을 사용합니다.
+
+## `Depends` 및 기타 사용하기
+
+WebSocket 엔드포인트에서 `fastapi`에서 다음을 가져와 사용할 수 있습니다:
+
+* `Depends`
+* `Security`
+* `Cookie`
+* `Header`
+* `Path`
+* `Query`
+
+이들은 다른 FastAPI 엔드포인트/*경로 작동*과 동일하게 동작합니다:
+
+{* ../../docs_src/websockets/tutorial002_an_py310.py hl[68:69,82] *}
+
+/// info | 정보
+
+WebSocket에서는 `HTTPException`을 발생시키는 것이 적합하지 않습니다. 대신 `WebSocketException`을 발생시킵니다.
+
+명세서에 정의된 유효한 코드를 사용하여 종료 코드를 설정할 수 있습니다.
+
+///
+
+### 종속성을 가진 WebSockets 테스트
+
+파일 이름이 `main.py`라고 가정하고 응용 프로그램을 실행합니다:
+
+
+
+## 연결 해제 및 다중 클라이언트 처리
+
+WebSocket 연결이 닫히면, `await websocket.receive_text()`가 `WebSocketDisconnect` 예외를 발생시킵니다. 이를 잡아 처리할 수 있습니다:
+
+{* ../../docs_src/websockets/tutorial003_py39.py hl[79:81] *}
+
+테스트해보기:
+
+* 여러 브라우저 탭에서 앱을 엽니다.
+* 각 탭에서 메시지를 작성합니다.
+* 한 탭을 닫아보세요.
+
+`WebSocketDisconnect` 예외가 발생하며, 다른 모든 클라이언트가 다음과 같은 메시지를 수신합니다:
+
+```
+Client #1596980209979 left the chat
+```
+
+/// tip | 팁
+
+위 응용 프로그램은 여러 WebSocket 연결에 메시지를 브로드캐스트하는 방법을 보여주는 간단한 예제입니다.
+
+그러나 모든 것을 메모리의 단일 리스트로 처리하므로, 프로세스가 실행 중인 동안만 동작하며 단일 프로세스에서만 작동합니다.
+
+FastAPI와 쉽게 통합할 수 있으면서 더 견고하고 Redis, PostgreSQL 등을 지원하는 도구를 찾고 있다면, encode/broadcaster를 확인하세요.
+
+///
+
+## 추가 정보
+
+다음 옵션에 대한 자세한 내용을 보려면 Starlette의 문서를 확인하세요:
+
+* `WebSocket` 클래스.
+* 클래스 기반 WebSocket 처리.
diff --git a/docs/ko/docs/advanced/wsgi.md b/docs/ko/docs/advanced/wsgi.md
new file mode 100644
index 000000000..3e9de3e6c
--- /dev/null
+++ b/docs/ko/docs/advanced/wsgi.md
@@ -0,0 +1,35 @@
+# WSGI 포함하기 - Flask, Django 그 외
+
+[서브 응용 프로그램 - 마운트](sub-applications.md){.internal-link target=_blank}, [프록시 뒤편에서](behind-a-proxy.md){.internal-link target=_blank}에서 보았듯이 WSGI 응용 프로그램들을 다음과 같이 마운트 할 수 있습니다.
+
+`WSGIMiddleware`를 사용하여 WSGI 응용 프로그램(예: Flask, Django 등)을 감쌀 수 있습니다.
+
+## `WSGIMiddleware` 사용하기
+
+`WSGIMiddleware`를 불러와야 합니다.
+
+그런 다음, WSGI(예: Flask) 응용 프로그램을 미들웨어로 포장합니다.
+
+그 후, 해당 경로에 마운트합니다.
+
+{* ../../docs_src/wsgi/tutorial001.py hl[2:3,23] *}
+
+## 확인하기
+
+이제 `/v1/` 경로에 있는 모든 요청은 Flask 응용 프로그램에서 처리됩니다.
+
+그리고 나머지는 **FastAPI**에 의해 처리됩니다.
+
+실행하면 http://localhost:8000/v1/으로 이동해서 Flask의 응답을 볼 수 있습니다:
+
+```txt
+Hello, World from Flask!
+```
+
+그리고 다음으로 이동하면 http://localhost:8000/v2 Flask의 응답을 볼 수 있습니다:
+
+```JSON
+{
+ "message": "Hello World"
+}
+```
diff --git a/docs/ko/docs/async.md b/docs/ko/docs/async.md
index 65ee124ec..fa0d20488 100644
--- a/docs/ko/docs/async.md
+++ b/docs/ko/docs/async.md
@@ -21,8 +21,11 @@ async def read_results():
return results
```
-!!! note "참고"
- `async def`로 생성된 함수 내부에서만 `await`를 사용할 수 있습니다.
+/// note | 참고
+
+`async def`로 생성된 함수 내부에서만 `await`를 사용할 수 있습니다.
+
+///
---
@@ -366,12 +369,15 @@ FastAPI를 사용하지 않더라도, 높은 호환성 및 가장 빠른 Python 프레임워크 중 하나로 실행되며, Starlette와 Uvicorn 자체(내부적으로 FastAPI가 사용하는 도구)보다 조금 아래에 위치합니다.
+
+그러나 벤치마크와 비교를 확인할 때 다음 사항을 염두에 두어야 합니다.
+
+## 벤치마크와 속도
+
+벤치마크를 확인할 때, 일반적으로 여러 가지 유형의 도구가 동등한 것으로 비교되는 것을 볼 수 있습니다.
+
+특히, Uvicorn, Starlette, FastAPI가 함께 비교되는 경우가 많습니다(다른 여러 도구와 함께).
+
+도구가 해결하는 문제가 단순할수록 성능이 더 좋아집니다. 그리고 대부분의 벤치마크는 도구가 제공하는 추가 기능을 테스트하지 않습니다.
+
+계층 구조는 다음과 같습니다:
+
+* **Uvicorn**: ASGI 서버
+ * **Starlette**: (Uvicorn 사용) 웹 마이크로 프레임워크
+ * **FastAPI**: (Starlette 사용) API 구축을 위한 데이터 검증 등 여러 추가 기능이 포함된 API 마이크로 프레임워크
+
+* **Uvicorn**:
+ * 서버 자체 외에는 많은 추가 코드가 없기 때문에 최고의 성능을 발휘합니다.
+ * 직접 Uvicorn으로 응용 프로그램을 작성하지는 않을 것입니다. 즉, 사용자의 코드에는 적어도 Starlette(또는 **FastAPI**)에서 제공하는 모든 코드가 포함되어야 합니다. 그렇게 하면 최종 응용 프로그램은 프레임워크를 사용하고 앱 코드와 버그를 최소화하는 것과 동일한 오버헤드를 갖게 됩니다.
+ * Uvicorn을 비교할 때는 Daphne, Hypercorn, uWSGI 등의 응용 프로그램 서버와 비교하세요.
+* **Starlette**:
+ * Uvicorn 다음으로 좋은 성능을 발휘합니다. 사실 Starlette는 Uvicorn을 사용하여 실행됩니다. 따라서 더 많은 코드를 실행해야 하기 때문에 Uvicorn보다 "느려질" 수밖에 없습니다.
+ * 하지만 경로 기반 라우팅 등 간단한 웹 응용 프로그램을 구축할 수 있는 도구를 제공합니다.
+ * Starlette를 비교할 때는 Sanic, Flask, Django 등의 웹 프레임워크(또는 마이크로 프레임워크)와 비교하세요.
+* **FastAPI**:
+ * Starlette가 Uvicorn을 사용하므로 Uvicorn보다 빨라질 수 없는 것과 마찬가지로, **FastAPI**는 Starlette를 사용하므로 더 빠를 수 없습니다.
+ * FastAPI는 Starlette에 추가적으로 더 많은 기능을 제공합니다. API를 구축할 때 거의 항상 필요한 데이터 검증 및 직렬화와 같은 기능들이 포함되어 있습니다. 그리고 이를 사용하면 문서 자동화 기능도 제공됩니다(문서 자동화는 응용 프로그램 실행 시 오버헤드를 추가하지 않고 시작 시 생성됩니다).
+ * FastAPI를 사용하지 않고 직접 Starlette(또는 Sanic, Flask, Responder 등)를 사용했다면 데이터 검증 및 직렬화를 직접 구현해야 합니다. 따라서 최종 응용 프로그램은 FastAPI를 사용한 것과 동일한 오버헤드를 가지게 될 것입니다. 많은 경우 데이터 검증 및 직렬화가 응용 프로그램에서 작성된 코드 중 가장 많은 부분을 차지합니다.
+ * 따라서 FastAPI를 사용함으로써 개발 시간, 버그, 코드 라인을 줄일 수 있으며, FastAPI를 사용하지 않았을 때와 동일하거나 더 나은 성능을 얻을 수 있습니다(코드에서 모두 구현해야 하기 때문에).
+ * FastAPI를 비교할 때는 Flask-apispec, NestJS, Molten 등 데이터 검증, 직렬화 및 문서화가 통합된 자동 데이터 검증, 직렬화 및 문서화를 제공하는 웹 응용 프로그램 프레임워크(또는 도구 집합)와 비교하세요.
diff --git a/docs/ko/docs/deployment/docker.md b/docs/ko/docs/deployment/docker.md
index 0e8f85cae..e8b2746c5 100644
--- a/docs/ko/docs/deployment/docker.md
+++ b/docs/ko/docs/deployment/docker.md
@@ -4,8 +4,11 @@ FastAPI 어플리케이션을 배포할 때 일반적인 접근 방법은 **리
리눅스 컨테이너를 사용하는 데에는 **보안**, **반복 가능성**, **단순함** 등의 장점이 있습니다.
-!!! tip "팁"
- 시간에 쫓기고 있고 이미 이런것들을 알고 있다면 [`Dockerfile`👇](#build-a-docker-image-for-fastapi)로 점프할 수 있습니다.
+/// tip | 팁
+
+시간에 쫓기고 있고 이미 이런것들을 알고 있다면 [`Dockerfile`👇](#build-a-docker-image-for-fastapi)로 점프할 수 있습니다.
+
+///
+
+그러나 `syntaxHighlight`를 `False`로 설정하여 구문 강조 기능을 비활성화할 수 있습니다:
+
+{* ../../docs_src/configure_swagger_ui/tutorial001.py hl[3] *}
+
+...그럼 Swagger UI에서 더 이상 구문 강조 기능이 표시되지 않습니다:
+
+
+
+## 테마 변경
+
+동일한 방식으로 `"syntaxHighlight.theme"` 키를 사용하여 구문 강조 테마를 설정할 수 있습니다 (중간에 점이 포함된 것을 참고하십시오).
+
+{* ../../docs_src/configure_swagger_ui/tutorial002.py hl[3] *}
+
+이 설정은 구문 강조 색상 테마를 변경합니다:
+
+
+
+## 기본 Swagger UI 매개변수 변경
+
+FastAPI는 대부분의 사용 사례에 적합한 몇 가지 기본 구성 매개변수를 포함하고 있습니다.
+
+기본 구성에는 다음이 포함됩니다:
+
+{* ../../fastapi/openapi/docs.py ln[8:23] hl[17:23] *}
+
+`swagger_ui_parameters` 인수에 다른 값을 설정하여 이러한 기본값 중 일부를 재정의할 수 있습니다.
+
+예를 들어, `deepLinking`을 비활성화하려면 `swagger_ui_parameters`에 다음 설정을 전달할 수 있습니다:
+
+{* ../../docs_src/configure_swagger_ui/tutorial003.py hl[3] *}
+
+## 기타 Swagger UI 매개변수
+
+사용할 수 있는 다른 모든 구성 옵션을 확인하려면, Swagger UI 매개변수에 대한 공식 문서를 참조하십시오.
+
+## JavaScript 전용 설정
+
+Swagger UI는 **JavaScript 전용** 객체(예: JavaScript 함수)로 다른 구성을 허용하기도 합니다.
+
+FastAPI는 이러한 JavaScript 전용 `presets` 설정을 포함하고 있습니다:
+
+```JavaScript
+presets: [
+ SwaggerUIBundle.presets.apis,
+ SwaggerUIBundle.SwaggerUIStandalonePreset
+]
+```
+
+이들은 문자열이 아닌 **JavaScript** 객체이므로 Python 코드에서 직접 전달할 수 없습니다.
+
+이와 같은 JavaScript 전용 구성을 사용해야 하는 경우, 위의 방법 중 하나를 사용하여 모든 Swagger UI 경로 작업을 재정의하고 필요한 JavaScript를 수동으로 작성할 수 있습니다.
diff --git a/docs/ko/docs/index.md b/docs/ko/docs/index.md
index 620fcc881..0df2000fa 100644
--- a/docs/ko/docs/index.md
+++ b/docs/ko/docs/index.md
@@ -11,15 +11,18 @@
FastAPI 프레임워크, 고성능, 간편한 학습, 빠른 코드 작성, 준비된 프로덕션
---
@@ -441,7 +444,7 @@ item: Item
Pydantic이 사용하는:
-* email_validator - 이메일 유효성 검사.
+* email-validator - 이메일 유효성 검사.
Starlette이 사용하는:
diff --git a/docs/ko/docs/openapi-webhooks.md b/docs/ko/docs/openapi-webhooks.md
new file mode 100644
index 000000000..96339aa96
--- /dev/null
+++ b/docs/ko/docs/openapi-webhooks.md
@@ -0,0 +1,55 @@
+# OpenAPI 웹훅(Webhooks)
+
+API **사용자**에게 특정 **이벤트**가 발생할 때 *그들*의 앱(시스템)에 요청을 보내 **알림**을 전달할 수 있다는 것을 알리고 싶은 경우가 있습니다.
+
+즉, 일반적으로 사용자가 API에 요청을 보내는 것과는 반대로, **API**(또는 앱)가 **사용자의 시스템**(그들의 API나 앱)으로 **요청을 보내는** 상황을 의미합니다.
+
+이를 흔히 **웹훅(Webhook)**이라고 부릅니다.
+
+## 웹훅 스텝
+
+**코드에서** 웹훅으로 보낼 메시지, 즉 요청의 **바디(body)**를 정의하는 것이 일반적인 프로세스입니다.
+
+앱에서 해당 요청이나 이벤트를 전송할 **시점**을 정의합니다.
+
+**사용자**는 앱이 해당 요청을 보낼 **URL**을 정의합니다. (예: 웹 대시보드에서 설정)
+
+웹훅의 URL을 등록하는 방법과 이러한 요청을 실제로 전송하는 코드에 대한 모든 로직은 여러분에게 달려 있습니다. 원하는대로 **고유의 코드**를 작성하면 됩니다.
+
+## **FastAPI**와 OpenAPI로 웹훅 문서화하기
+
+**FastAPI**를 사용하여 OpenAPI와 함께 웹훅의 이름, 앱이 보낼 수 있는 HTTP 작업 유형(예: `POST`, `PUT` 등), 그리고 보낼 요청의 **바디**를 정의할 수 있습니다.
+
+이를 통해 사용자가 **웹훅** 요청을 수신할 **API 구현**을 훨씬 쉽게 할 수 있으며, 경우에 따라 사용자 API 코드의 일부를 자동 생성할 수도 있습니다.
+
+/// info
+
+웹훅은 OpenAPI 3.1.0 이상에서 지원되며, FastAPI `0.99.0` 이상 버전에서 사용할 수 있습니다.
+
+///
+
+## 웹훅이 포함된 앱 만들기
+
+**FastAPI** 애플리케이션을 만들 때, `webhooks` 속성을 사용하여 *웹훅*을 정의할 수 있습니다. 이는 `@app.webhooks.post()`와 같은 방식으로 *경로(path) 작업*을 정의하는 것과 비슷합니다.
+
+{* ../../docs_src/openapi_webhooks/tutorial001.py hl[9:13,36:53] *}
+
+이렇게 정의한 웹훅은 **OpenAPI** 스키마와 자동 **문서화 UI**에 표시됩니다.
+
+/// info
+
+`app.webhooks` 객체는 사실 `APIRouter`일 뿐이며, 여러 파일로 앱을 구성할 때 사용하는 것과 동일한 타입입니다.
+
+///
+
+웹훅에서는 실제 **경로(path)** (예: `/items/`)를 선언하지 않는 점에 유의해야 합니다. 여기서 전달하는 텍스트는 **식별자**로, 웹훅의 이름(이벤트 이름)입니다. 예를 들어, `@app.webhooks.post("new-subscription")`에서 웹훅 이름은 `new-subscription`입니다.
+
+이는 실제 **URL 경로**는 **사용자**가 다른 방법(예: 웹 대시보드)을 통해 지정하도록 기대되기 때문입니다.
+
+### 문서 확인하기
+
+이제 앱을 시작하고 http://127.0.0.1:8000/docs로 이동해 봅시다.
+
+문서에서 기존 *경로 작업*뿐만 아니라 **웹훅**도 표시된 것을 확인할 수 있습니다:
+
+
diff --git a/docs/ko/docs/project-generation.md b/docs/ko/docs/project-generation.md
new file mode 100644
index 000000000..dd11fca70
--- /dev/null
+++ b/docs/ko/docs/project-generation.md
@@ -0,0 +1,28 @@
+# Full Stack FastAPI 템플릿
+
+템플릿은 일반적으로 특정 설정과 함께 제공되지만, 유연하고 커스터마이징이 가능하게 디자인 되었습니다. 이 특성들은 여러분이 프로젝트의 요구사항에 맞춰 수정, 적용을 할 수 있게 해주고, 템플릿이 완벽한 시작점이 되게 해줍니다. 🏁
+
+많은 초기 설정, 보안, 데이터베이스 및 일부 API 엔드포인트가 이미 준비되어 있으므로, 여러분은 이 템플릿을 (프로젝트를) 시작하는 데 사용할 수 있습니다.
+
+GitHub 저장소: Full Stack FastAPI 템플릿
+
+## Full Stack FastAPI 템플릿 - 기술 스택과 기능들
+
+- ⚡ [**FastAPI**](https://fastapi.tiangolo.com): Python 백엔드 API.
+ - 🧰 [SQLModel](https://sqlmodel.tiangolo.com): Python SQL 데이터 상호작용을 위한 (ORM).
+ - 🔍 [Pydantic](https://docs.pydantic.dev): FastAPI에 의해 사용되는, 데이터 검증과 설정관리.
+ - 💾 [PostgreSQL](https://www.postgresql.org): SQL 데이터베이스.
+- 🚀 [React](https://react.dev): 프론트엔드.
+ - 💃 TypeScript, hooks, [Vite](https://vitejs.dev) 및 기타 현대적인 프론트엔드 스택을 사용.
+ - 🎨 [Chakra UI](https://chakra-ui.com): 프론트엔드 컴포넌트.
+ - 🤖 자동으로 생성된 프론트엔드 클라이언트.
+ - 🧪 E2E 테스트를 위한 [Playwright](https://playwright.dev).
+ - 🦇 다크 모드 지원.
+- 🐋 [Docker Compose](https://www.docker.com): 개발 환경과 프로덕션(운영).
+- 🔒 기본으로 지원되는 안전한 비밀번호 해싱.
+- 🔑 JWT 토큰 인증.
+- 📫 이메일 기반 비밀번호 복구.
+- ✅ [Pytest]를 이용한 테스트(https://pytest.org).
+- 📞 [Traefik](https://traefik.io): 리버스 프록시 / 로드 밸런서.
+- 🚢 Docker Compose를 이용한 배포 지침: 자동 HTTPS 인증서를 처리하기 위한 프론트엔드 Traefik 프록시 설정 방법을 포함.
+- 🏭 GitHub Actions를 기반으로 CI (지속적인 통합) 및 CD (지속적인 배포).
diff --git a/docs/ko/docs/python-types.md b/docs/ko/docs/python-types.md
index 267ce6c7e..18d4b341e 100644
--- a/docs/ko/docs/python-types.md
+++ b/docs/ko/docs/python-types.md
@@ -12,16 +12,18 @@
비록 **FastAPI**를 쓰지 않는다고 하더라도, 조금이라도 알아두면 도움이 될 것입니다.
-!!! note "참고"
- 파이썬에 능숙하셔서 타입 힌트에 대해 모두 아신다면, 다음 챕터로 건너뛰세요.
+/// note | 참고
+
+파이썬에 능숙하셔서 타입 힌트에 대해 모두 아신다면, 다음 챕터로 건너뛰세요.
+
+///
## 동기 부여
간단한 예제부터 시작해봅시다:
-```Python
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py *}
+
이 프로그램을 실행한 결과값:
@@ -35,9 +37,8 @@ John Doe
* `title()`로 각 첫 문자를 대문자로 변환시킵니다.
* 두 단어를 중간에 공백을 두고 연결합니다.
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py hl[2] *}
+
### 코드 수정
@@ -79,9 +80,8 @@ John Doe
이게 "타입 힌트"입니다:
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial002.py!}
-```
+{* ../../docs_src/python_types/tutorial002.py hl[1] *}
+
타입힌트는 다음과 같이 기본 값을 선언하는 것과는 다릅니다:
@@ -109,9 +109,8 @@ John Doe
아래 함수를 보면, 이미 타입 힌트가 적용되어 있는 걸 볼 수 있습니다:
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial003.py!}
-```
+{* ../../docs_src/python_types/tutorial003.py hl[1] *}
+
편집기가 변수의 타입을 알고 있기 때문에, 자동완성 뿐 아니라 에러도 확인할 수 있습니다:
@@ -119,9 +118,8 @@ John Doe
이제 고쳐야하는 걸 알기 때문에, `age`를 `str(age)`과 같이 문자열로 바꾸게 됩니다:
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial004.py!}
-```
+{* ../../docs_src/python_types/tutorial004.py hl[2] *}
+
## 타입 선언
@@ -140,9 +138,8 @@ John Doe
* `bool`
* `bytes`
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial005.py!}
-```
+{* ../../docs_src/python_types/tutorial005.py hl[1] *}
+
### 타입 매개변수를 활용한 Generic(제네릭) 타입
@@ -158,9 +155,8 @@ John Doe
`typing`에서 `List`(대문자 `L`)를 import 합니다.
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial006.py!}
-```
+{* ../../docs_src/python_types/tutorial006.py hl[1] *}
+
콜론(`:`) 문법을 이용하여 변수를 선언합니다.
@@ -168,14 +164,16 @@ John Doe
이때 배열은 내부 타입을 포함하는 타입이기 때문에 대괄호 안에 넣어줍니다.
-```Python hl_lines="4"
-{!../../../docs_src/python_types/tutorial006.py!}
-```
+{* ../../docs_src/python_types/tutorial006.py hl[4] *}
-!!! tip "팁"
- 대괄호 안의 내부 타입은 "타입 매개변수(type paramters)"라고 합니다.
- 이번 예제에서는 `str`이 `List`에 들어간 타입 매개변수 입니다.
+/// tip | 팁
+
+대괄호 안의 내부 타입은 "타입 매개변수(type paramters)"라고 합니다.
+
+이번 예제에서는 `str`이 `List`에 들어간 타입 매개변수 입니다.
+
+///
이는 "`items`은 `list`인데, 배열에 들어있는 아이템 각각은 `str`이다"라는 뜻입니다.
@@ -193,9 +191,8 @@ John Doe
`tuple`과 `set`도 동일하게 선언할 수 있습니다.
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial007.py!}
-```
+{* ../../docs_src/python_types/tutorial007.py hl[1,4] *}
+
이 뜻은 아래와 같습니다:
@@ -210,9 +207,8 @@ John Doe
두 번째 매개변수는 `dict`의 값(value)입니다.
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial008.py!}
-```
+{* ../../docs_src/python_types/tutorial008.py hl[1,4] *}
+
이 뜻은 아래와 같습니다:
@@ -225,7 +221,7 @@ John Doe
`str`과 같이 타입을 선언할 때 `Optional`을 쓸 수도 있는데, "선택적(Optional)"이기때문에 `None`도 될 수 있습니다:
```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial009.py!}
+{!../../docs_src/python_types/tutorial009.py!}
```
`Optional[str]`을 `str` 대신 쓰게 되면, 특정 값이 실제로는 `None`이 될 수도 있는데 항상 `str`이라고 가정하는 상황에서 에디터가 에러를 찾게 도와줄 수 있습니다.
@@ -249,15 +245,13 @@ John Doe
이름(name)을 가진 `Person` 클래스가 있다고 해봅시다.
-```Python hl_lines="1-3"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
+
그렇게 하면 변수를 `Person`이라고 선언할 수 있게 됩니다.
-```Python hl_lines="6"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[6] *}
+
그리고 역시나 모든 에디터 도움을 받게 되겠죠.
@@ -277,13 +271,14 @@ John Doe
Pydantic 공식 문서 예시:
-```Python
-{!../../../docs_src/python_types/tutorial011.py!}
-```
+{* ../../docs_src/python_types/tutorial011.py *}
-!!! info "정보"
- Pydantic<에 대해 더 배우고 싶다면 공식 문서를 참고하세요.
+/// info | 정보
+
+Pydantic<에 대해 더 배우고 싶다면 공식 문서를 참고하세요.
+
+///
**FastAPI**는 모두 Pydantic을 기반으로 되어 있습니다.
@@ -311,5 +306,8 @@ Pydantic 공식 문서 예시:
가장 중요한 건, 표준 파이썬 타입을 한 곳에서(클래스를 더하거나, 데코레이터 사용하는 대신) 사용함으로써 **FastAPI**가 당신을 위해 많은 일을 해준다는 사실이죠.
-!!! info "정보"
- 만약 모든 자습서를 다 보았음에도 타입에 대해서 더 보고자 방문한 경우에는 `mypy`에서 제공하는 "cheat sheet"이 좋은 자료가 될 겁니다.
+/// info | 정보
+
+만약 모든 자습서를 다 보았음에도 타입에 대해서 더 보고자 방문한 경우에는 `mypy`에서 제공하는 "cheat sheet"이 좋은 자료가 될 겁니다.
+
+///
diff --git a/docs/ko/docs/resources/index.md b/docs/ko/docs/resources/index.md
new file mode 100644
index 000000000..e804dd4d5
--- /dev/null
+++ b/docs/ko/docs/resources/index.md
@@ -0,0 +1,3 @@
+# 리소스
+
+추가 리소스, 외부 링크, 기사 등. ✈️
diff --git a/docs/ko/docs/security/index.md b/docs/ko/docs/security/index.md
new file mode 100644
index 000000000..5a6c733f0
--- /dev/null
+++ b/docs/ko/docs/security/index.md
@@ -0,0 +1,19 @@
+# 고급 보안
+
+## 추가 기능
+
+[자습서 - 사용자 가이드: 보안](../../tutorial/security/index.md){.internal-link target=_blank} 문서에서 다룬 내용 외에도 보안 처리를 위한 몇 가지 추가 기능이 있습니다.
+
+/// tip
+
+다음 섹션은 **반드시 "고급"** 기능은 아닙니다.
+
+그리고 여러분의 사용 사례에 따라, 적합한 해결책이 그 중 하나에 있을 가능성이 있습니다.
+
+///
+
+## 먼저 자습서 읽기
+
+다음 섹션은 이미 [자습서 - 사용자 가이드: 보안](../../tutorial/security/index.md){.internal-link target=_blank} 문서를 읽었다고 가정합니다.
+
+이 섹션들은 모두 동일한 개념을 바탕으로 하며, 추가 기능을 제공합니다.
diff --git a/docs/ko/docs/tutorial/background-tasks.md b/docs/ko/docs/tutorial/background-tasks.md
index ee83d6570..a2c4abbd9 100644
--- a/docs/ko/docs/tutorial/background-tasks.md
+++ b/docs/ko/docs/tutorial/background-tasks.md
@@ -15,9 +15,7 @@ FastAPI에서는 응답을 반환한 후에 실행할 백그라운드 작업을
먼저 아래와 같이 `BackgroundTasks`를 임포트하고, `BackgroundTasks`를 _경로 작동 함수_ 에서 매개변수로 가져오고 정의합니다.
-```Python hl_lines="1 13"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *}
**FastAPI** 는 `BackgroundTasks` 개체를 생성하고, 매개 변수로 전달합니다.
@@ -33,17 +31,13 @@ FastAPI에서는 응답을 반환한 후에 실행할 백그라운드 작업을
그리고 이 작업은 `async`와 `await`를 사용하지 않으므로 일반 `def` 함수로 선언합니다.
-```Python hl_lines="6-9"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *}
## 백그라운드 작업 추가
_경로 작동 함수_ 내에서 작업 함수를 `.add_task()` 함수 통해 _백그라운드 작업_ 개체에 전달합니다.
-```Python hl_lines="14"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[14] *}
`.add_task()` 함수는 다음과 같은 인자를 받습니다 :
@@ -57,17 +51,7 @@ _경로 작동 함수_ 내에서 작업 함수를 `.add_task()` 함수 통해 _
**FastAPI**는 각 경우에 수행할 작업과 동일한 개체를 내부적으로 재사용하기에, 모든 백그라운드 작업이 함께 병합되고 나중에 백그라운드에서 실행됩니다.
-=== "Python 3.6 and above"
-
- ```Python hl_lines="13 15 22 25"
- {!> ../../../docs_src/background_tasks/tutorial002.py!}
- ```
-
-=== "Python 3.10 and above"
-
- ```Python hl_lines="11 13 20 23"
- {!> ../../../docs_src/background_tasks/tutorial002_py310.py!}
- ```
+{* ../../docs_src/background_tasks/tutorial002.py hl[13,15,22,25] *}
이 예제에서는 응답이 반환된 후에 `log.txt` 파일에 메시지가 기록됩니다.
@@ -93,8 +77,6 @@ FastAPI에서 `BackgroundTask`를 단독으로 사용하는 것은 여전히 가
RabbitMQ 또는 Redis와 같은 메시지/작업 큐 시스템 보다 복잡한 구성이 필요한 경향이 있지만, 여러 작업 프로세스를 특히 여러 서버의 백그라운드에서 실행할 수 있습니다.
-예제를 보시려면 [프로젝트 생성기](../project-generation.md){.internal-link target=\_blank} 를 참고하세요. 해당 예제에는 이미 구성된 `Celery`가 포함되어 있습니다.
-
그러나 동일한 FastAPI 앱에서 변수 및 개체에 접근해야햐는 작은 백그라운드 수행이 필요한 경우 (예 : 알림 이메일 보내기) 간단하게 `BackgroundTasks`를 사용해보세요.
## 요약
diff --git a/docs/ko/docs/tutorial/body-fields.md b/docs/ko/docs/tutorial/body-fields.md
index c91d6130b..4708e7099 100644
--- a/docs/ko/docs/tutorial/body-fields.md
+++ b/docs/ko/docs/tutorial/body-fields.md
@@ -6,98 +6,39 @@
먼저 이를 임포트해야 합니다:
-=== "Python 3.10+"
+{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[4] *}
- ```Python hl_lines="4"
- {!> ../../../docs_src/body_fields/tutorial001_an_py310.py!}
- ```
+/// warning | 경고
-=== "Python 3.9+"
+`Field`는 다른 것들처럼 (`Query`, `Path`, `Body` 등) `fastapi`에서가 아닌 `pydantic`에서 바로 임포트 되는 점에 주의하세요.
- ```Python hl_lines="4"
- {!> ../../../docs_src/body_fields/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="4"
- {!> ../../../docs_src/body_fields/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ Annotated가 없는 경우"
-
- !!! tip "팁"
- 가능하다면 `Annotated`가 달린 버전을 권장합니다.
-
- ```Python hl_lines="2"
- {!> ../../../docs_src/body_fields/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ Annotated가 없는 경우"
-
- !!! tip "팁"
- 가능하다면 `Annotated`가 달린 버전을 권장합니다.
-
- ```Python hl_lines="4"
- {!> ../../../docs_src/body_fields/tutorial001.py!}
- ```
-
-!!! warning "경고"
- `Field`는 다른 것들처럼 (`Query`, `Path`, `Body` 등) `fastapi`에서가 아닌 `pydantic`에서 바로 임포트 되는 점에 주의하세요.
+///
## 모델 어트리뷰트 선언
그 다음 모델 어트리뷰트와 함께 `Field`를 사용할 수 있습니다:
-=== "Python 3.10+"
-
- ```Python hl_lines="11-14"
- {!> ../../../docs_src/body_fields/tutorial001_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="11-14"
- {!> ../../../docs_src/body_fields/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="12-15"
- {!> ../../../docs_src/body_fields/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ Annotated가 없는 경우"
-
- !!! tip "팁"
- 가능하다면 `Annotated`가 달린 버전을 권장합니다.
-
- ```Python hl_lines="9-12"
- {!> ../../../docs_src/body_fields/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ Annotated가 없는 경우"
-
- !!! tip "팁"
- 가능하다면 `Annotated`가 달린 버전을 권장합니다.
-
- ```Python hl_lines="11-14"
- {!> ../../../docs_src/body_fields/tutorial001.py!}
- ```
+{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[11:14] *}
`Field`는 `Query`, `Path`와 `Body`와 같은 방식으로 동작하며, 모두 같은 매개변수들 등을 가집니다.
-!!! note "기술적 세부사항"
- 실제로 `Query`, `Path`등, 여러분이 앞으로 볼 다른 것들은 공통 클래스인 `Param` 클래스의 서브클래스 객체를 만드는데, 그 자체로 Pydantic의 `FieldInfo` 클래스의 서브클래스입니다.
+/// note | 기술적 세부사항
- 그리고 Pydantic의 `Field` 또한 `FieldInfo`의 인스턴스를 반환합니다.
+실제로 `Query`, `Path`등, 여러분이 앞으로 볼 다른 것들은 공통 클래스인 `Param` 클래스의 서브클래스 객체를 만드는데, 그 자체로 Pydantic의 `FieldInfo` 클래스의 서브클래스입니다.
- `Body` 또한 `FieldInfo`의 서브클래스 객체를 직접적으로 반환합니다. 그리고 `Body` 클래스의 서브클래스인 것들도 여러분이 나중에 보게될 것입니다.
+그리고 Pydantic의 `Field` 또한 `FieldInfo`의 인스턴스를 반환합니다.
- `Query`, `Path`와 그 외 것들을 `fastapi`에서 임포트할 때, 이는 실제로 특별한 클래스를 반환하는 함수인 것을 기억해 주세요.
+`Body` 또한 `FieldInfo`의 서브클래스 객체를 직접적으로 반환합니다. 그리고 `Body` 클래스의 서브클래스인 것들도 여러분이 나중에 보게될 것입니다.
-!!! tip "팁"
- 주목할 점은 타입, 기본 값 및 `Field`로 이루어진 각 모델 어트리뷰트가 `Path`, `Query`와 `Body`대신 `Field`를 사용하는 *경로 작동 함수*의 매개변수와 같은 구조를 가진다는 점 입니다.
+ `Query`, `Path`와 그 외 것들을 `fastapi`에서 임포트할 때, 이는 실제로 특별한 클래스를 반환하는 함수인 것을 기억해 주세요.
+
+///
+
+/// tip | 팁
+
+주목할 점은 타입, 기본 값 및 `Field`로 이루어진 각 모델 어트리뷰트가 `Path`, `Query`와 `Body`대신 `Field`를 사용하는 *경로 작동 함수*의 매개변수와 같은 구조를 가진다는 점 입니다.
+
+///
## 별도 정보 추가
@@ -105,9 +46,12 @@
여러분이 예제를 선언할 때 나중에 이 공식 문서에서 별도 정보를 추가하는 방법을 배울 것입니다.
-!!! warning "경고"
- 별도 키가 전달된 `Field` 또한 여러분의 어플리케이션의 OpenAPI 스키마에 나타날 것입니다.
- 이런 키가 OpenAPI 명세서, [the OpenAPI validator](https://validator.swagger.io/)같은 몇몇 OpenAPI 도구들에 포함되지 못할 수 있으며, 여러분이 생성한 스키마와 호환되지 않을 수 있습니다.
+/// warning | 경고
+
+별도 키가 전달된 `Field` 또한 여러분의 어플리케이션의 OpenAPI 스키마에 나타날 것입니다.
+이런 키가 OpenAPI 명세서, [the OpenAPI validator](https://validator.swagger.io/)같은 몇몇 OpenAPI 도구들에 포함되지 못할 수 있으며, 여러분이 생성한 스키마와 호환되지 않을 수 있습니다.
+
+///
## 요약
diff --git a/docs/ko/docs/tutorial/body-multiple-params.md b/docs/ko/docs/tutorial/body-multiple-params.md
index 2cf5df7f3..edf892dfa 100644
--- a/docs/ko/docs/tutorial/body-multiple-params.md
+++ b/docs/ko/docs/tutorial/body-multiple-params.md
@@ -10,12 +10,13 @@
또한, 기본 값을 `None`으로 설정해 본문 매개변수를 선택사항으로 선언할 수 있습니다.
-```Python hl_lines="19-21"
-{!../../../docs_src/body_multiple_params/tutorial001.py!}
-```
+{* ../../docs_src/body_multiple_params/tutorial001.py hl[19:21] *}
-!!! note "참고"
- 이 경우에는 본문으로 부터 가져온 ` item`은 기본값이 `None`이기 때문에, 선택사항이라는 점을 유의해야 합니다.
+/// note | 참고
+
+이 경우에는 본문으로 부터 가져온 ` item`은 기본값이 `None`이기 때문에, 선택사항이라는 점을 유의해야 합니다.
+
+///
## 다중 본문 매개변수
@@ -32,9 +33,7 @@
하지만, 다중 본문 매개변수 역시 선언할 수 있습니다. 예. `item`과 `user`:
-```Python hl_lines="22"
-{!../../../docs_src/body_multiple_params/tutorial002.py!}
-```
+{* ../../docs_src/body_multiple_params/tutorial002.py hl[22] *}
이 경우에, **FastAPI**는 이 함수 안에 한 개 이상의 본문 매개변수(Pydantic 모델인 두 매개변수)가 있다고 알 것입니다.
@@ -55,8 +54,11 @@
}
```
-!!! note "참고"
- 이전과 같이 `item`이 선언 되었더라도, 본문 내의 `item` 키가 있을 것이라고 예측합니다.
+/// note | 참고
+
+이전과 같이 `item`이 선언 되었더라도, 본문 내의 `item` 키가 있을 것이라고 예측합니다.
+
+///
FastAPI는 요청을 자동으로 변환해, 매개변수의 `item`과 `user`를 특별한 내용으로 받도록 할 것입니다.
@@ -73,9 +75,7 @@ FastAPI는 요청을 자동으로 변환해, 매개변수의 `item`과 `user`를
하지만, **FastAPI**의 `Body`를 사용해 다른 본문 키로 처리하도록 제어할 수 있습니다:
-```Python hl_lines="23"
-{!../../../docs_src/body_multiple_params/tutorial003.py!}
-```
+{* ../../docs_src/body_multiple_params/tutorial003.py hl[23] *}
이 경우에는 **FastAPI**는 본문을 이와 같이 예측할 것입니다:
@@ -104,9 +104,7 @@ FastAPI는 요청을 자동으로 변환해, 매개변수의 `item`과 `user`를
기본적으로 단일 값은 쿼리 매개변수로 해석되므로, 명시적으로 `Query`를 추가할 필요가 없고, 아래처럼 할 수 있습니다:
-```Python hl_lines="27"
-{!../../../docs_src/body_multiple_params/tutorial004.py!}
-```
+{* ../../docs_src/body_multiple_params/tutorial004.py hl[27] *}
이렇게:
@@ -114,8 +112,11 @@ FastAPI는 요청을 자동으로 변환해, 매개변수의 `item`과 `user`를
q: Optional[str] = None
```
-!!! info "정보"
- `Body` 또한 `Query`, `Path` 그리고 이후에 볼 다른 것들처럼 동일한 추가 검증과 메타데이터 매개변수를 갖고 있습니다.
+/// info | 정보
+
+`Body` 또한 `Query`, `Path` 그리고 이후에 볼 다른 것들처럼 동일한 추가 검증과 메타데이터 매개변수를 갖고 있습니다.
+
+///
## 단일 본문 매개변수 삽입하기
@@ -125,9 +126,7 @@ Pydantic 모델 `Item`의 `item`을 본문 매개변수로 오직 한개만 갖
하지만, 만약 모델 내용에 `item `키를 가진 JSON으로 예측하길 원한다면, 추가적인 본문 매개변수를 선언한 것처럼 `Body`의 특별한 매개변수인 `embed`를 사용할 수 있습니다:
-```Python hl_lines="17"
-{!../../../docs_src/body_multiple_params/tutorial005.py!}
-```
+{* ../../docs_src/body_multiple_params/tutorial005.py hl[17] *}
아래 처럼:
diff --git a/docs/ko/docs/tutorial/body-nested-models.md b/docs/ko/docs/tutorial/body-nested-models.md
index 10af0a062..ebd7b3ba6 100644
--- a/docs/ko/docs/tutorial/body-nested-models.md
+++ b/docs/ko/docs/tutorial/body-nested-models.md
@@ -5,9 +5,7 @@
어트리뷰트를 서브타입으로 정의할 수 있습니다. 예를 들어 파이썬 `list`는:
-```Python hl_lines="14"
-{!../../../docs_src/body_nested_models/tutorial001.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial001.py hl[14] *}
이는 `tags`를 항목 리스트로 만듭니다. 각 항목의 타입을 선언하지 않더라도요.
@@ -19,9 +17,7 @@
먼저, 파이썬 표준 `typing` 모듈에서 `List`를 임포트합니다:
-```Python hl_lines="1"
-{!../../../docs_src/body_nested_models/tutorial002.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *}
### 타입 매개변수로 `List` 선언
@@ -42,9 +38,7 @@ my_list: List[str]
마찬가지로 예제에서 `tags`를 구체적으로 "문자열의 리스트"로 만들 수 있습니다:
-```Python hl_lines="14"
-{!../../../docs_src/body_nested_models/tutorial002.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial002.py hl[14] *}
## 집합 타입
@@ -54,9 +48,7 @@ my_list: List[str]
그렇다면 `Set`을 임포트 하고 `tags`를 `str`의 `set`으로 선언할 수 있습니다:
-```Python hl_lines="1 14"
-{!../../../docs_src/body_nested_models/tutorial003.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial003.py hl[1,14] *}
덕분에 중복 데이터가 있는 요청을 수신하더라도 고유한 항목들의 집합으로 변환됩니다.
@@ -78,17 +70,13 @@ Pydantic 모델의 각 어트리뷰트는 타입을 갖습니다.
예를 들어, `Image` 모델을 선언할 수 있습니다:
-```Python hl_lines="9-11"
-{!../../../docs_src/body_nested_models/tutorial004.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial004.py hl[9:11] *}
### 서브모듈을 타입으로 사용
그리고 어트리뷰트의 타입으로 사용할 수 있습니다:
-```Python hl_lines="20"
-{!../../../docs_src/body_nested_models/tutorial004.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial004.py hl[20] *}
이는 **FastAPI**가 다음과 유사한 본문을 기대한다는 것을 의미합니다:
@@ -121,9 +109,7 @@ Pydantic 모델의 각 어트리뷰트는 타입을 갖습니다.
예를 들어 `Image` 모델 안에 `url` 필드를 `str` 대신 Pydantic의 `HttpUrl`로 선언할 수 있습니다:
-```Python hl_lines="4 10"
-{!../../../docs_src/body_nested_models/tutorial005.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial005.py hl[4,10] *}
이 문자열이 유효한 URL인지 검사하고 JSON 스키마/OpenAPI로 문서화 됩니다.
@@ -131,9 +117,7 @@ Pydantic 모델의 각 어트리뷰트는 타입을 갖습니다.
`list`, `set` 등의 서브타입으로 Pydantic 모델을 사용할 수도 있습니다:
-```Python hl_lines="20"
-{!../../../docs_src/body_nested_models/tutorial006.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial006.py hl[20] *}
아래와 같은 JSON 본문으로 예상(변환, 검증, 문서화 등을)합니다:
@@ -161,19 +145,23 @@ Pydantic 모델의 각 어트리뷰트는 타입을 갖습니다.
}
```
-!!! info "정보"
- `images` 키가 어떻게 이미지 객체 리스트를 갖는지 주목하세요.
+/// info | 정보
+
+`images` 키가 어떻게 이미지 객체 리스트를 갖는지 주목하세요.
+
+///
## 깊게 중첩된 모델
단독으로 깊게 중첩된 모델을 정의할 수 있습니다:
-```Python hl_lines="9 14 20 23 27"
-{!../../../docs_src/body_nested_models/tutorial007.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial007.py hl[9,14,20,23,27] *}
-!!! info "정보"
- `Offer`가 선택사항 `Image` 리스트를 차례로 갖는 `Item` 리스트를 어떻게 가지고 있는지 주목하세요
+/// info | 정보
+
+`Offer`가 선택사항 `Image` 리스트를 차례로 갖는 `Item` 리스트를 어떻게 가지고 있는지 주목하세요
+
+///
## 순수 리스트의 본문
@@ -185,9 +173,7 @@ images: List[Image]
이를 아래처럼:
-```Python hl_lines="15"
-{!../../../docs_src/body_nested_models/tutorial008.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial008.py hl[15] *}
## 어디서나 편집기 지원
@@ -217,18 +203,19 @@ Pydantic 모델 대신에 `dict`를 직접 사용하여 작업할 경우, 이러
이 경우, `float` 값을 가진 `int` 키가 있는 모든 `dict`를 받아들입니다:
-```Python hl_lines="15"
-{!../../../docs_src/body_nested_models/tutorial009.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial009.py hl[15] *}
-!!! tip "팁"
- JSON은 오직 `str`형 키만 지원한다는 것을 염두에 두세요.
+/// tip | 팁
- 하지만 Pydantic은 자동 데이터 변환이 있습니다.
+JSON은 오직 `str`형 키만 지원한다는 것을 염두에 두세요.
- 즉, API 클라이언트가 문자열을 키로 보내더라도 해당 문자열이 순수한 정수를 포함하는한 Pydantic은 이를 변환하고 검증합니다.
+하지만 Pydantic은 자동 데이터 변환이 있습니다.
- 그러므로 `weights`로 받은 `dict`는 실제로 `int` 키와 `float` 값을 가집니다.
+즉, API 클라이언트가 문자열을 키로 보내더라도 해당 문자열이 순수한 정수를 포함하는한 Pydantic은 이를 변환하고 검증합니다.
+
+그러므로 `weights`로 받은 `dict`는 실제로 `int` 키와 `float` 값을 가집니다.
+
+///
## 요약
diff --git a/docs/ko/docs/tutorial/body.md b/docs/ko/docs/tutorial/body.md
index 0ab8b7162..b3914fa4b 100644
--- a/docs/ko/docs/tutorial/body.md
+++ b/docs/ko/docs/tutorial/body.md
@@ -8,28 +8,21 @@
**요청** 본문을 선언하기 위해서 모든 강력함과 이점을 갖춘 Pydantic 모델을 사용합니다.
-!!! info "정보"
- 데이터를 보내기 위해, (좀 더 보편적인) `POST`, `PUT`, `DELETE` 혹은 `PATCH` 중에 하나를 사용하는 것이 좋습니다.
+/// info | 정보
- `GET` 요청에 본문을 담아 보내는 것은 명세서에 정의되지 않은 행동입니다. 그럼에도 불구하고, 이 방식은 아주 복잡한/극한의 사용 상황에서만 FastAPI에 의해 지원됩니다.
+데이터를 보내기 위해, (좀 더 보편적인) `POST`, `PUT`, `DELETE` 혹은 `PATCH` 중에 하나를 사용하는 것이 좋습니다.
- `GET` 요청에 본문을 담는 것은 권장되지 않기에, Swagger UI같은 대화형 문서에서는 `GET` 사용시 담기는 본문에 대한 문서를 표시하지 않으며, 중간에 있는 프록시는 이를 지원하지 않을 수도 있습니다.
+`GET` 요청에 본문을 담아 보내는 것은 명세서에 정의되지 않은 행동입니다. 그럼에도 불구하고, 이 방식은 아주 복잡한/극한의 사용 상황에서만 FastAPI에 의해 지원됩니다.
+
+`GET` 요청에 본문을 담는 것은 권장되지 않기에, Swagger UI같은 대화형 문서에서는 `GET` 사용시 담기는 본문에 대한 문서를 표시하지 않으며, 중간에 있는 프록시는 이를 지원하지 않을 수도 있습니다.
+
+///
## Pydantic의 `BaseModel` 임포트
먼저 `pydantic`에서 `BaseModel`를 임포트해야 합니다:
-=== "Python 3.10+"
-
- ```Python hl_lines="2"
- {!> ../../../docs_src/body/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="4"
- {!> ../../../docs_src/body/tutorial001.py!}
- ```
+{* ../../docs_src/body/tutorial001_py310.py hl[2] *}
## 여러분의 데이터 모델 만들기
@@ -37,17 +30,7 @@
모든 어트리뷰트에 대해 표준 파이썬 타입을 사용합니다:
-=== "Python 3.10+"
-
- ```Python hl_lines="5-9"
- {!> ../../../docs_src/body/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="7-11"
- {!> ../../../docs_src/body/tutorial001.py!}
- ```
+{* ../../docs_src/body/tutorial001_py310.py hl[5:9] *}
쿼리 매개변수를 선언할 때와 같이, 모델 어트리뷰트가 기본 값을 가지고 있어도 이는 필수가 아닙니다. 그외에는 필수입니다. 그저 `None`을 사용하여 선택적으로 만들 수 있습니다.
@@ -75,17 +58,7 @@
여러분의 *경로 작동*에 추가하기 위해, 경로 매개변수 그리고 쿼리 매개변수에서 선언했던 것과 같은 방식으로 선언하면 됩니다.
-=== "Python 3.10+"
-
- ```Python hl_lines="16"
- {!> ../../../docs_src/body/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body/tutorial001.py!}
- ```
+{* ../../docs_src/body/tutorial001_py310.py hl[16] *}
...그리고 만들어낸 모델인 `Item`으로 타입을 선언합니다.
@@ -134,32 +107,25 @@
-!!! tip "팁"
- 만약 PyCharm를 편집기로 사용한다면, Pydantic PyCharm Plugin을 사용할 수 있습니다.
+/// tip | 팁
- 다음 사항을 포함해 Pydantic 모델에 대한 편집기 지원을 향상시킵니다:
+만약 PyCharm를 편집기로 사용한다면, Pydantic PyCharm Plugin을 사용할 수 있습니다.
- * 자동 완성
- * 타입 확인
- * 리팩토링
- * 검색
- * 점검
+다음 사항을 포함해 Pydantic 모델에 대한 편집기 지원을 향상시킵니다:
+
+* 자동 완성
+* 타입 확인
+* 리팩토링
+* 검색
+* 점검
+
+///
## 모델 사용하기
함수 안에서 모델 객체의 모든 어트리뷰트에 직접 접근 가능합니다:
-=== "Python 3.10+"
-
- ```Python hl_lines="19"
- {!> ../../../docs_src/body/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="21"
- {!> ../../../docs_src/body/tutorial002.py!}
- ```
+{* ../../docs_src/body/tutorial002_py310.py hl[19] *}
## 요청 본문 + 경로 매개변수
@@ -167,17 +133,7 @@
**FastAPI**는 경로 매개변수와 일치하는 함수 매개변수가 **경로에서 가져와야 한다**는 것을 인지하며, Pydantic 모델로 선언된 그 함수 매개변수는 **요청 본문에서 가져와야 한다**는 것을 인지할 것입니다.
-=== "Python 3.10+"
-
- ```Python hl_lines="15-16"
- {!> ../../../docs_src/body/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="17-18"
- {!> ../../../docs_src/body/tutorial003.py!}
- ```
+{* ../../docs_src/body/tutorial003_py310.py hl[15:16] *}
## 요청 본문 + 경로 + 쿼리 매개변수
@@ -185,17 +141,7 @@
**FastAPI**는 각각을 인지하고 데이터를 옳바른 위치에 가져올 것입니다.
-=== "Python 3.10+"
-
- ```Python hl_lines="16"
- {!> ../../../docs_src/body/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body/tutorial004.py!}
- ```
+{* ../../docs_src/body/tutorial004_py310.py hl[16] *}
함수 매개변수는 다음을 따라서 인지하게 됩니다:
@@ -203,10 +149,13 @@
* 만약 매개변수가 (`int`, `float`, `str`, `bool` 등과 같은) **유일한 타입**으로 되어있으면, **쿼리** 매개변수로 해석될 것입니다.
* 만약 매개변수가 **Pydantic 모델** 타입으로 선언되어 있으면, 요청 **본문**으로 해석될 것입니다.
-!!! note "참고"
- FastAPI는 `q`의 값이 필요없음을 알게 될 것입니다. 기본 값이 `= None`이기 때문입니다.
+/// note | 참고
- `Union[str, None]`에 있는 `Union`은 FastAPI에 의해 사용된 것이 아니지만, 편집기로 하여금 더 나은 지원과 에러 탐지를 지원할 것입니다.
+FastAPI는 `q`의 값이 필요없음을 알게 될 것입니다. 기본 값이 `= None`이기 때문입니다.
+
+`Union[str, None]`에 있는 `Union`은 FastAPI에 의해 사용된 것이 아니지만, 편집기로 하여금 더 나은 지원과 에러 탐지를 지원할 것입니다.
+
+///
## Pydantic없이
diff --git a/docs/ko/docs/tutorial/cookie-param-models.md b/docs/ko/docs/tutorial/cookie-param-models.md
new file mode 100644
index 000000000..e7eef0b1d
--- /dev/null
+++ b/docs/ko/docs/tutorial/cookie-param-models.md
@@ -0,0 +1,76 @@
+# 쿠키 매개변수 모델
+
+관련있는 **쿠키**들의 그룹이 있는 경우, **Pydantic 모델**을 생성하여 선언할 수 있습니다. 🍪
+
+이를 통해 **여러 위치**에서 **모델을 재사용** 할 수 있고 모든 매개변수에 대한 유효성 검사 및 메타데이터를 한 번에 선언할 수도 있습니다. 😍
+
+/// note | 참고
+
+이 기능은 FastAPI 버전 `0.115.0` 이후부터 지원됩니다. 🤓
+
+///
+
+/// tip | 팁
+
+동일한 기술이 `Query`, `Cookie`, 그리고 `Header`에 적용됩니다. 😎
+
+///
+
+## Pydantic 모델을 사용한 쿠키
+
+**Pydantic 모델**에 필요한 **쿠키** 매개변수를 선언한 다음, 해당 매개변수를 `Cookie`로 선언합니다:
+
+{* ../../docs_src/cookie_param_models/tutorial001_an_py310.py hl[9:12,16] *}
+
+**FastAPI**는 요청에서 받은 **쿠키**에서 **각 필드**에 대한 데이터를 **추출**하고 정의한 Pydantic 모델을 줍니다.
+
+## 문서 확인하기
+
+문서 UI `/docs`에서 정의한 쿠키를 볼 수 있습니다:
+
+
+get 작동 사용
-!!! info "`@decorator` 정보"
- 이 `@something` 문법은 파이썬에서 "데코레이터"라 부릅니다.
+/// info | `@decorator` 정보
- 마치 예쁜 장식용(Decorative) 모자처럼(개인적으로 이 용어가 여기서 유래한 것 같습니다) 함수 맨 위에 놓습니다.
+이 `@something` 문법은 파이썬에서 "데코레이터"라 부릅니다.
- "데코레이터"는 아래 있는 함수를 받아 그것으로 무언가를 합니다.
+마치 예쁜 장식용(Decorative) 모자처럼(개인적으로 이 용어가 여기서 유래한 것 같습니다) 함수 맨 위에 놓습니다.
- 우리의 경우, 이 데코레이터는 **FastAPI**에게 아래 함수가 **경로** `/`의 `get` **작동**에 해당한다고 알려줍니다.
+"데코레이터"는 아래 있는 함수를 받아 그것으로 무언가를 합니다.
- 이것이 "**경로 작동 데코레이터**"입니다.
+우리의 경우, 이 데코레이터는 **FastAPI**에게 아래 함수가 **경로** `/`의 `get` **작동**에 해당한다고 알려줍니다.
+
+이것이 "**경로 작동 데코레이터**"입니다.
+
+///
다른 작동도 사용할 수 있습니다:
@@ -274,14 +276,17 @@ API를 설계할 때 일반적으로 특정 행동을 수행하기 위해 특정
* `@app.patch()`
* `@app.trace()`
-!!! tip "팁"
- 각 작동(HTTP 메소드)을 원하는 대로 사용해도 됩니다.
+/// tip | 팁
- **FastAPI**는 특정 의미를 강제하지 않습니다.
+각 작동(HTTP 메소드)을 원하는 대로 사용해도 됩니다.
- 여기서 정보는 지침서일뿐 강제사항이 아닙니다.
+**FastAPI**는 특정 의미를 강제하지 않습니다.
- 예를 들어 GraphQL을 사용하는 경우, 일반적으로 `POST` 작동만 사용하여 모든 행동을 수행합니다.
+여기서 정보는 지침서일뿐 강제사항이 아닙니다.
+
+예를 들어 GraphQL을 사용하는 경우, 일반적으로 `POST` 작동만 사용하여 모든 행동을 수행합니다.
+
+///
### 4 단계: **경로 작동 함수** 정의
@@ -291,9 +296,7 @@ API를 설계할 때 일반적으로 특정 행동을 수행하기 위해 특정
* **작동**: 은 `get`입니다.
* **함수**: 는 "데코레이터" 아래에 있는 함수입니다 (`@app.get("/")` 아래).
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[7] *}
이것은 파이썬 함수입니다.
@@ -305,18 +308,17 @@ URL "`/`"에 대한 `GET` 작동을 사용하는 요청을 받을 때마다 **Fa
`async def`을 이용하는 대신 일반 함수로 정의할 수 있습니다:
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial003.py!}
-```
+{* ../../docs_src/first_steps/tutorial003.py hl[7] *}
-!!! note "참고"
- 차이점을 모르겠다면 [Async: *"바쁘신 경우"*](../async.md#_1){.internal-link target=_blank}을 확인하세요.
+/// note | 참고
+
+차이점을 모르겠다면 [Async: *"바쁘신 경우"*](../async.md#_1){.internal-link target=_blank}을 확인하세요.
+
+///
### 5 단계: 콘텐츠 반환
-```Python hl_lines="8"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[8] *}
`dict`, `list`, 단일값을 가진 `str`, `int` 등을 반환할 수 있습니다.
diff --git a/docs/ko/docs/tutorial/header-param-models.md b/docs/ko/docs/tutorial/header-param-models.md
new file mode 100644
index 000000000..bab7291e3
--- /dev/null
+++ b/docs/ko/docs/tutorial/header-param-models.md
@@ -0,0 +1,56 @@
+# 헤더 매개변수 모델
+
+관련 있는 **헤더 매개변수** 그룹이 있는 경우, **Pydantic 모델**을 생성하여 선언할 수 있습니다.
+
+이를 통해 **여러 위치**에서 **모델을 재사용** 할 수 있고 모든 매개변수에 대한 유효성 검사 및 메타데이터를 한 번에 선언할 수도 있습니다. 😎
+
+/// note | 참고
+
+이 기능은 FastAPI 버전 `0.115.0` 이후부터 지원됩니다. 🤓
+
+///
+
+## Pydantic 모델을 사용한 헤더 매개변수
+
+**Pydantic 모델**에 필요한 **헤더 매개변수**를 선언한 다음, 해당 매개변수를 `Header`로 선언합니다:
+
+{* ../../docs_src/header_param_models/tutorial001_an_py310.py hl[9:14,18] *}
+
+**FastAPI**는 요청에서 받은 **헤더**에서 **각 필드**에 대한 데이터를 **추출**하고 정의한 Pydantic 모델을 줍니다.
+
+## 문서 확인하기
+
+문서 UI `/docs`에서 필요한 헤더를 볼 수 있습니다:
+
+
+contact 필드| 매개변수 | 타입 | 설명 |
|---|---|---|
name | str | 연락처 인물/조직의 식별명입니다. |
url | str | 연락처 정보가 담긴 URL입니다. URL 형식이어야 합니다. |
email | str | 연락처 인물/조직의 이메일 주소입니다. 이메일 주소 형식이어야 합니다. |
license_info 필드| 매개변수 | 타입 | 설명 |
|---|---|---|
name | str | 필수 (license_info가 설정된 경우). API에 사용된 라이선스 이름입니다. |
identifier | str | API에 대한 SPDX 라이선스 표현입니다. identifier 필드는 url 필드와 상호 배타적입니다. OpenAPI 3.1.0, FastAPI 0.99.0부터 사용 가능 |
url | str | API에 사용된 라이선스의 URL입니다. URL 형식이어야 합니다. |
+
+## 라이선스 식별자
+
+OpenAPI 3.1.0 및 FastAPI 0.99.0부터 `license_info`에 `identifier`를 URL 대신 설정할 수 있습니다.
+
+예:
+
+{* ../../docs_src/metadata/tutorial001_1.py hl[31] *}
+
+## 태그에 대한 메타데이터
+
+`openapi_tags` 매개변수를 사용하여 경로 작동을 그룹화하는 데 사용되는 태그에 추가 메타데이터를 추가할 수 있습니다.
+
+리스트는 각 태그에 대해 하나의 딕셔너리를 포함해야 합니다.
+
+각 딕셔너리에는 다음이 포함될 수 있습니다:
+
+* `name` (**필수**): `tags` 매개변수에서 *경로 작동*과 `APIRouter`에 사용된 태그 이름과 동일한 `str`입니다.
+* `description`: 태그에 대한 간단한 설명을 담은 `str`입니다. 마크다운을 사용할 수 있으며 문서 UI에 표시됩니다.
+* `externalDocs`: 외부 문서를 설명하는 `dict`이며:
+ * `description`: 외부 문서에 대한 간단한 설명을 담은 `str`입니다.
+ * `url` (**필수**): 외부 문서의 URL을 담은 `str`입니다.
+
+### 태그에 대한 메타데이터 생성
+
+`users` 및 `items`에 대한 태그 예시와 함께 메타데이터를 생성하고 이를 `openapi_tags` 매개변수로 전달해 보겠습니다:
+
+{* ../../docs_src/metadata/tutorial004.py hl[3:16,18] *}
+
+설명 안에 마크다운을 사용할 수 있습니다. 예를 들어 "login"은 굵게(**login**) 표시되고, "fancy"는 기울임꼴(_fancy_)로 표시됩니다.
+
+/// tip
+
+사용 중인 모든 태그에 메타데이터를 추가할 필요는 없습니다.
+
+///
+
+### 태그 사용
+
+`tags` 매개변수를 *경로 작동* 및 `APIRouter`와 함께 사용하여 태그에 할당할 수 있습니다:
+
+{* ../../docs_src/metadata/tutorial004.py hl[21,26] *}
+
+/// info
+
+태그에 대한 자세한 내용은 [경로 작동 구성](path-operation-configuration.md#tags){.internal-link target=_blank}에서 읽어보세요.
+
+///
+
+### 문서 확인
+
+이제 문서를 확인하면 모든 추가 메타데이터가 표시됩니다:
+
+
+
+### 태그 순서
+
+각 태그 메타데이터 딕셔너리의 순서는 문서 UI에 표시되는 순서를 정의합니다.
+
+예를 들어, 알파벳 순서상 `users`는 `items` 뒤에 오지만, 우리는 `users` 메타데이터를 리스트의 첫 번째 딕셔너리로 추가했기 때문에 먼저 표시됩니다.
+
+## OpenAPI URL
+
+OpenAPI 구조는 기본적으로 `/openapi.json`에서 제공됩니다.
+
+`openapi_url` 매개변수를 통해 이를 설정할 수 있습니다.
+
+예를 들어, 이를 `/api/v1/openapi.json`에 제공하도록 설정하려면:
+
+{* ../../docs_src/metadata/tutorial002.py hl[3] *}
+
+OpenAPI 구조를 완전히 비활성화하려면 `openapi_url=None`으로 설정할 수 있으며, 이를 사용하여 문서화 사용자 인터페이스도 비활성화됩니다.
+
+## 문서화 URL
+
+포함된 두 가지 문서화 사용자 인터페이스를 설정할 수 있습니다:
+
+* **Swagger UI**: `/docs`에서 제공됩니다.
+ * `docs_url` 매개변수로 URL을 설정할 수 있습니다.
+ * `docs_url=None`으로 설정하여 비활성화할 수 있습니다.
+* **ReDoc**: `/redoc`에서 제공됩니다.
+ * `redoc_url` 매개변수로 URL을 설정할 수 있습니다.
+ * `redoc_url=None`으로 설정하여 비활성화할 수 있습니다.
+
+예를 들어, Swagger UI를 `/documentation`에서 제공하고 ReDoc을 비활성화하려면:
+
+{* ../../docs_src/metadata/tutorial003.py hl[3] *}
diff --git a/docs/ko/docs/tutorial/middleware.md b/docs/ko/docs/tutorial/middleware.md
index f35b446a6..3cd752a0e 100644
--- a/docs/ko/docs/tutorial/middleware.md
+++ b/docs/ko/docs/tutorial/middleware.md
@@ -11,10 +11,13 @@
* **응답** 또는 다른 필요한 코드를 실행시키는 동작을 할 수 있습니다.
* **응답**를 반환합니다.
-!!! note "기술 세부사항"
- 만약 `yield`를 사용한 의존성을 가지고 있다면, 미들웨어가 실행되고 난 후에 exit이 실행됩니다.
+/// note | 기술 세부사항
- 만약 (나중에 문서에서 다룰) 백그라운드 작업이 있다면, 모든 미들웨어가 실행되고 *난 후에* 실행됩니다.
+만약 `yield`를 사용한 의존성을 가지고 있다면, 미들웨어가 실행되고 난 후에 exit이 실행됩니다.
+
+만약 (나중에 문서에서 다룰) 백그라운드 작업이 있다면, 모든 미들웨어가 실행되고 *난 후에* 실행됩니다.
+
+///
## 미들웨어 만들기
@@ -28,19 +31,23 @@
* 그런 다음, *경로 작업*에 의해 생성된 `response` 를 반환합니다.
* `response`를 반환하기 전에 추가로 `response`를 수정할 수 있습니다.
-```Python hl_lines="8-9 11 14"
-{!../../../docs_src/middleware/tutorial001.py!}
-```
+{* ../../docs_src/middleware/tutorial001.py hl[8:9,11,14] *}
-!!! tip "팁"
- 사용자 정의 헤더는 'X-' 접두사를 사용하여 추가할 수 있습니다.
+/// tip | 팁
- 그러나 만약 클라이언트의 브라우저에서 볼 수 있는 사용자 정의 헤더를 가지고 있다면, 그것들을 CORS 설정([CORS (Cross-Origin Resource Sharing)](cors.md){.internal-link target=_blank})에 Starlette CORS 문서에 명시된 `expose_headers` 매개변수를 이용하여 헤더들을 추가하여야합니다.
+사용자 정의 헤더는 'X-' 접두사를 사용하여 추가할 수 있습니다.
-!!! note "기술적 세부사항"
- `from starlette.requests import request`를 사용할 수도 있습니다.
+그러나 만약 클라이언트의 브라우저에서 볼 수 있는 사용자 정의 헤더를 가지고 있다면, 그것들을 CORS 설정([CORS (Cross-Origin Resource Sharing)](cors.md){.internal-link target=_blank})에 Starlette CORS 문서에 명시된 `expose_headers` 매개변수를 이용하여 헤더들을 추가하여야합니다.
- **FastAPI**는 개발자에게 편의를 위해 이를 제공합니다. 그러나 Starlette에서 직접 파생되었습니다.
+///
+
+/// note | 기술적 세부사항
+
+`from starlette.requests import request`를 사용할 수도 있습니다.
+
+**FastAPI**는 개발자에게 편의를 위해 이를 제공합니다. 그러나 Starlette에서 직접 파생되었습니다.
+
+///
### `response`의 전과 후
@@ -50,9 +57,7 @@
예를 들어, 요청을 수행하고 응답을 생성하는데 까지 걸린 시간 값을 가지고 있는 `X-Process-Time` 같은 사용자 정의 헤더를 추가할 수 있습니다.
-```Python hl_lines="10 12-13"
-{!../../../docs_src/middleware/tutorial001.py!}
-```
+{* ../../docs_src/middleware/tutorial001.py hl[10,12:13] *}
## 다른 미들웨어
diff --git a/docs/ko/docs/tutorial/path-operation-configuration.md b/docs/ko/docs/tutorial/path-operation-configuration.md
index 411c43493..81914182a 100644
--- a/docs/ko/docs/tutorial/path-operation-configuration.md
+++ b/docs/ko/docs/tutorial/path-operation-configuration.md
@@ -2,8 +2,11 @@
*경로 작동 데코레이터*를 설정하기 위해서 전달할수 있는 몇 가지 매개변수가 있습니다.
-!!! warning "경고"
- 아래 매개변수들은 *경로 작동 함수*가 아닌 *경로 작동 데코레이터*에 직접 전달된다는 사실을 기억하십시오.
+/// warning | 경고
+
+아래 매개변수들은 *경로 작동 함수*가 아닌 *경로 작동 데코레이터*에 직접 전달된다는 사실을 기억하십시오.
+
+///
## 응답 상태 코드
@@ -13,24 +16,23 @@
하지만 각 코드의 의미를 모른다면, `status`에 있는 단축 상수들을 사용할수 있습니다:
-```Python hl_lines="3 17"
-{!../../../docs_src/path_operation_configuration/tutorial001.py!}
-```
+{* ../../docs_src/path_operation_configuration/tutorial001.py hl[3,17] *}
각 상태 코드들은 응답에 사용되며, OpenAPI 스키마에 추가됩니다.
-!!! note "기술적 세부사항"
- 다음과 같이 임포트하셔도 좋습니다. `from starlette import status`.
+/// note | 기술적 세부사항
- **FastAPI**는 개발자 여러분의 편의를 위해서 `starlette.status`와 동일한 `fastapi.status`를 제공합니다. 하지만 Starlette에서 직접 온 것입니다.
+다음과 같이 임포트하셔도 좋습니다. `from starlette import status`.
+
+**FastAPI**는 개발자 여러분의 편의를 위해서 `starlette.status`와 동일한 `fastapi.status`를 제공합니다. 하지만 Starlette에서 직접 온 것입니다.
+
+///
## 태그
(보통 단일 `str`인) `str`로 구성된 `list`와 함께 매개변수 `tags`를 전달하여, `경로 작동`에 태그를 추가할 수 있습니다:
-```Python hl_lines="17 22 27"
-{!../../../docs_src/path_operation_configuration/tutorial002.py!}
-```
+{* ../../docs_src/path_operation_configuration/tutorial002.py hl[17,22,27] *}
전달된 태그들은 OpenAPI의 스키마에 추가되며, 자동 문서 인터페이스에서 사용됩니다:
@@ -40,9 +42,7 @@
`summary`와 `description`을 추가할 수 있습니다:
-```Python hl_lines="20-21"
-{!../../../docs_src/path_operation_configuration/tutorial003.py!}
-```
+{* ../../docs_src/path_operation_configuration/tutorial003.py hl[20:21] *}
## 독스트링으로 만든 기술
@@ -50,9 +50,7 @@
마크다운 문법으로 독스트링을 작성할 수 있습니다, 작성된 마크다운 형식의 독스트링은 (마크다운의 들여쓰기를 고려하여) 올바르게 화면에 출력됩니다.
-```Python hl_lines="19-27"
-{!../../../docs_src/path_operation_configuration/tutorial004.py!}
-```
+{* ../../docs_src/path_operation_configuration/tutorial004.py hl[19:27] *}
이는 대화형 문서에서 사용됩니다:
@@ -62,17 +60,21 @@
`response_description` 매개변수로 응답에 관한 설명을 명시할 수 있습니다:
-```Python hl_lines="21"
-{!../../../docs_src/path_operation_configuration/tutorial005.py!}
-```
+{* ../../docs_src/path_operation_configuration/tutorial005.py hl[21] *}
-!!! info "정보"
- `response_description`은 구체적으로 응답을 지칭하며, `description`은 일반적인 *경로 작동*을 지칭합니다.
+/// info | 정보
-!!! check "확인"
- OpenAPI는 각 *경로 작동*이 응답에 관한 설명을 요구할 것을 명시합니다.
+`response_description`은 구체적으로 응답을 지칭하며, `description`은 일반적인 *경로 작동*을 지칭합니다.
- 따라서, 응답에 관한 설명이 없을경우, **FastAPI**가 자동으로 "성공 응답" 중 하나를 생성합니다.
+///
+
+/// check | 확인
+
+OpenAPI는 각 *경로 작동*이 응답에 관한 설명을 요구할 것을 명시합니다.
+
+따라서, 응답에 관한 설명이 없을경우, **FastAPI**가 자동으로 "성공 응답" 중 하나를 생성합니다.
+
+///
@@ -80,9 +82,7 @@
단일 *경로 작동*을 없애지 않고 지원중단을 해야한다면, `deprecated` 매개변수를 전달하면 됩니다.
-```Python hl_lines="16"
-{!../../../docs_src/path_operation_configuration/tutorial006.py!}
-```
+{* ../../docs_src/path_operation_configuration/tutorial006.py hl[16] *}
대화형 문서에 지원중단이라고 표시됩니다.
diff --git a/docs/ko/docs/tutorial/path-params-numeric-validations.md b/docs/ko/docs/tutorial/path-params-numeric-validations.md
index cadf543fc..f21c9290e 100644
--- a/docs/ko/docs/tutorial/path-params-numeric-validations.md
+++ b/docs/ko/docs/tutorial/path-params-numeric-validations.md
@@ -6,9 +6,7 @@
먼저 `fastapi`에서 `Path`를 임포트합니다:
-```Python hl_lines="3"
-{!../../../docs_src/path_params_numeric_validations/tutorial001.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial001.py hl[3] *}
## 메타데이터 선언
@@ -16,16 +14,17 @@
예를 들어, `title` 메타데이터 값을 경로 매개변수 `item_id`에 선언하려면 다음과 같이 입력할 수 있습니다:
-```Python hl_lines="10"
-{!../../../docs_src/path_params_numeric_validations/tutorial001.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial001.py hl[10] *}
-!!! note "참고"
- 경로 매개변수는 경로의 일부여야 하므로 언제나 필수적입니다.
+/// note | 참고
- 즉, `...`로 선언해서 필수임을 나타내는게 좋습니다.
+경로 매개변수는 경로의 일부여야 하므로 언제나 필수적입니다.
- 그럼에도 `None`으로 선언하거나 기본값을 지정할지라도 아무 영향을 끼치지 않으며 언제나 필수입니다.
+즉, `...`로 선언해서 필수임을 나타내는게 좋습니다.
+
+그럼에도 `None`으로 선언하거나 기본값을 지정할지라도 아무 영향을 끼치지 않으며 언제나 필수입니다.
+
+///
## 필요한 경우 매개변수 정렬하기
@@ -43,9 +42,7 @@
따라서 함수를 다음과 같이 선언 할 수 있습니다:
-```Python hl_lines="7"
-{!../../../docs_src/path_params_numeric_validations/tutorial002.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial002.py hl[7] *}
## 필요한 경우 매개변수 정렬하기, 트릭
@@ -55,9 +52,7 @@
파이썬은 `*`으로 아무런 행동도 하지 않지만, 따르는 매개변수들은 kwargs로도 알려진 키워드 인자(키-값 쌍)여야 함을 인지합니다. 기본값을 가지고 있지 않더라도 그렇습니다.
-```Python hl_lines="7"
-{!../../../docs_src/path_params_numeric_validations/tutorial003.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *}
## 숫자 검증: 크거나 같음
@@ -65,9 +60,7 @@
여기서 `ge=1`인 경우, `item_id`는 `1`보다 "크거나(`g`reater) 같은(`e`qual)" 정수형 숫자여야 합니다.
-```Python hl_lines="8"
-{!../../../docs_src/path_params_numeric_validations/tutorial004.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial004.py hl[8] *}
## 숫자 검증: 크거나 같음 및 작거나 같음
@@ -76,9 +69,7 @@
* `gt`: 크거나(`g`reater `t`han)
* `le`: 작거나 같은(`l`ess than or `e`qual)
-```Python hl_lines="9"
-{!../../../docs_src/path_params_numeric_validations/tutorial005.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial005.py hl[9] *}
## 숫자 검증: 부동소수, 크거나 및 작거나
@@ -90,9 +81,7 @@
lt 역시 마찬가지입니다.
-```Python hl_lines="11"
-{!../../../docs_src/path_params_numeric_validations/tutorial006.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial006.py hl[11] *}
## 요약
@@ -105,18 +94,24 @@
* `lt`: 작거나(`l`ess `t`han)
* `le`: 작거나 같은(`l`ess than or `e`qual)
-!!! info "정보"
- `Query`, `Path`, 그리고 나중에게 보게될 것들은 (여러분이 사용할 필요가 없는) 공통 `Param` 클래스의 서브 클래스입니다.
+/// info | 정보
- 그리고 이들 모두는 여태까지 본 추가 검증과 메타데이터의 동일한 모든 매개변수를 공유합니다.
+`Query`, `Path`, 그리고 나중에게 보게될 것들은 (여러분이 사용할 필요가 없는) 공통 `Param` 클래스의 서브 클래스입니다.
-!!! note "기술 세부사항"
- `fastapi`에서 `Query`, `Path` 등을 임포트 할 때, 이것들은 실제로 함수입니다.
+그리고 이들 모두는 여태까지 본 추가 검증과 메타데이터의 동일한 모든 매개변수를 공유합니다.
- 호출되면 동일한 이름의 클래스의 인스턴스를 반환합니다.
+///
- 즉, 함수인 `Query`를 임포트한 겁니다. 그리고 호출하면 `Query`라는 이름을 가진 클래스의 인스턴스를 반환합니다.
+/// note | 기술 세부사항
- 편집기에서 타입에 대한 오류를 표시하지 않도록 하기 위해 (클래스를 직접 사용하는 대신) 이러한 함수들이 있습니다.
+`fastapi`에서 `Query`, `Path` 등을 임포트 할 때, 이것들은 실제로 함수입니다.
- 이렇게 하면 오류를 무시하기 위한 사용자 설정을 추가하지 않고도 일반 편집기와 코딩 도구를 사용할 수 있습니다.
+호출되면 동일한 이름의 클래스의 인스턴스를 반환합니다.
+
+즉, 함수인 `Query`를 임포트한 겁니다. 그리고 호출하면 `Query`라는 이름을 가진 클래스의 인스턴스를 반환합니다.
+
+편집기에서 타입에 대한 오류를 표시하지 않도록 하기 위해 (클래스를 직접 사용하는 대신) 이러한 함수들이 있습니다.
+
+이렇게 하면 오류를 무시하기 위한 사용자 설정을 추가하지 않고도 일반 편집기와 코딩 도구를 사용할 수 있습니다.
+
+///
diff --git a/docs/ko/docs/tutorial/path-params.md b/docs/ko/docs/tutorial/path-params.md
index a75c3cc8c..b72787e0b 100644
--- a/docs/ko/docs/tutorial/path-params.md
+++ b/docs/ko/docs/tutorial/path-params.md
@@ -2,9 +2,7 @@
파이썬의 포맷 문자열 리터럴에서 사용되는 문법을 이용하여 경로 "매개변수" 또는 "변수"를 선언할 수 있습니다:
-```Python hl_lines="6-7"
-{!../../../docs_src/path_params/tutorial001.py!}
-```
+{* ../../docs_src/path_params/tutorial001.py hl[6:7] *}
경로 매개변수 `item_id`의 값은 함수의 `item_id` 인자로 전달됩니다.
@@ -18,14 +16,15 @@
파이썬 표준 타입 어노테이션을 사용하여 함수에 있는 경로 매개변수의 타입을 선언할 수 있습니다:
-```Python hl_lines="7"
-{!../../../docs_src/path_params/tutorial002.py!}
-```
+{* ../../docs_src/path_params/tutorial002.py hl[7] *}
위의 예시에서, `item_id`는 `int`로 선언되었습니다.
-!!! check "확인"
- 이 기능은 함수 내에서 오류 검사, 자동완성 등의 편집기 기능을 활용할 수 있게 해줍니다.
+/// check | 확인
+
+이 기능은 함수 내에서 오류 검사, 자동완성 등의 편집기 기능을 활용할 수 있게 해줍니다.
+
+///
## 데이터 변환
@@ -35,10 +34,13 @@
{"item_id":3}
```
-!!! check "확인"
- 함수가 받은(반환도 하는) 값은 문자열 `"3"`이 아니라 파이썬 `int` 형인 `3`입니다.
+/// check | 확인
- 즉, 타입 선언을 하면 **FastAPI**는 자동으로 요청을 "파싱"합니다.
+함수가 받은(반환도 하는) 값은 문자열 `"3"`이 아니라 파이썬 `int` 형인 `3`입니다.
+
+즉, 타입 선언을 하면 **FastAPI**는 자동으로 요청을 "파싱"합니다.
+
+///
## 데이터 검증
@@ -63,12 +65,15 @@
`int`가 아닌 `float`을 전달하는 경우에도 동일한 오류가 나타납니다: http://127.0.0.1:8000/items/4.2
-!!! check "확인"
- 즉, 파이썬 타입 선언을 하면 **FastAPI**는 데이터 검증을 합니다.
+/// check | 확인
- 오류에는 정확히 어느 지점에서 검증을 통과하지 못했는지 명시됩니다.
+즉, 파이썬 타입 선언을 하면 **FastAPI**는 데이터 검증을 합니다.
- 이는 API와 상호 작용하는 코드를 개발하고 디버깅하는 데 매우 유용합니다.
+오류에는 정확히 어느 지점에서 검증을 통과하지 못했는지 명시됩니다.
+
+이는 API와 상호 작용하는 코드를 개발하고 디버깅하는 데 매우 유용합니다.
+
+///
## 문서화
@@ -76,10 +81,13 @@
-!!! check "확인"
- 그저 파이썬 타입 선언을 하기만 하면 **FastAPI**는 자동 대화형 API 문서(Swagger UI)를 제공합니다.
+/// check | 확인
- 경로 매개변수가 정수형으로 명시된 것을 확인할 수 있습니다.
+그저 파이썬 타입 선언을 하기만 하면 **FastAPI**는 자동 대화형 API 문서(Swagger UI)를 제공합니다.
+
+경로 매개변수가 정수형으로 명시된 것을 확인할 수 있습니다.
+
+///
## 표준 기반의 이점, 대체 문서
@@ -109,9 +117,7 @@
*경로 작동*은 순차적으로 실행되기 때문에 `/users/{user_id}` 이전에 `/users/me`를 먼저 선언해야 합니다:
-```Python hl_lines="6 11"
-{!../../../docs_src/path_params/tutorial003.py!}
-```
+{* ../../docs_src/path_params/tutorial003.py hl[6,11] *}
그렇지 않으면 `/users/{user_id}`는 `/users/me` 요청 또한 매개변수 `user_id`의 값이 `"me"`인 것으로 "생각하게" 됩니다.
@@ -127,23 +133,25 @@
가능한 값들에 해당하는 고정된 값의 클래스 어트리뷰트들을 만듭니다:
-```Python hl_lines="1 6-9"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[1,6:9] *}
-!!! info "정보"
- 열거형(또는 enums)은 파이썬 버전 3.4 이후로 사용 가능합니다.
+/// info | 정보
-!!! tip "팁"
- 혹시 궁금하다면, "AlexNet", "ResNet", 그리고 "LeNet"은 그저 기계 학습 모델들의 이름입니다.
+열거형(또는 enums)은 파이썬 버전 3.4 이후로 사용 가능합니다.
+
+///
+
+/// tip | 팁
+
+혹시 궁금하다면, "AlexNet", "ResNet", 그리고 "LeNet"은 그저 기계 학습 모델들의 이름입니다.
+
+///
### *경로 매개변수* 선언
생성한 열거형 클래스(`ModelName`)를 사용하는 타입 어노테이션으로 *경로 매개변수*를 만듭니다:
-```Python hl_lines="16"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[16] *}
### 문서 확인
@@ -159,20 +167,19 @@
열거형 `ModelName`의 *열거형 멤버*를 비교할 수 있습니다:
-```Python hl_lines="17"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[17] *}
#### *열거형 값* 가져오기
`model_name.value` 또는 일반적으로 `your_enum_member.value`를 이용하여 실제 값(위 예시의 경우 `str`)을 가져올 수 있습니다:
-```Python hl_lines="20"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[20] *}
-!!! tip "팁"
- `ModelName.lenet.value`로도 값 `"lenet"`에 접근할 수 있습니다.
+/// tip | 팁
+
+`ModelName.lenet.value`로도 값 `"lenet"`에 접근할 수 있습니다.
+
+///
#### *열거형 멤버* 반환
@@ -180,9 +187,7 @@
클라이언트에 반환하기 전에 해당 값(이 경우 문자열)으로 변환됩니다:
-```Python hl_lines="18 21 23"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[18,21,23] *}
클라이언트는 아래의 JSON 응답을 얻습니다:
@@ -221,14 +226,15 @@ Starlette의 옵션을 직접 이용하여 다음과 같은 URL을 사용함으
따라서 다음과 같이 사용할 수 있습니다:
-```Python hl_lines="6"
-{!../../../docs_src/path_params/tutorial004.py!}
-```
+{* ../../docs_src/path_params/tutorial004.py hl[6] *}
-!!! tip "팁"
- 매개변수가 가져야 하는 값이 `/home/johndoe/myfile.txt`와 같이 슬래시로 시작(`/`)해야 할 수 있습니다.
+/// tip | 팁
- 이 경우 URL은: `/files//home/johndoe/myfile.txt`이며 `files`과 `home` 사이에 이중 슬래시(`//`)가 생깁니다.
+매개변수가 가져야 하는 값이 `/home/johndoe/myfile.txt`와 같이 슬래시로 시작(`/`)해야 할 수 있습니다.
+
+이 경우 URL은: `/files//home/johndoe/myfile.txt`이며 `files`과 `home` 사이에 이중 슬래시(`//`)가 생깁니다.
+
+///
## 요약
diff --git a/docs/ko/docs/tutorial/query-param-models.md b/docs/ko/docs/tutorial/query-param-models.md
new file mode 100644
index 000000000..2ca65a331
--- /dev/null
+++ b/docs/ko/docs/tutorial/query-param-models.md
@@ -0,0 +1,68 @@
+# 쿼리 매개변수 모델
+
+연관된 쿼리 **매개변수** 그룹이 있다면 **Pydantic 모델** 을 사용해 선언할 수 있습니다.
+
+이렇게 하면 **여러 곳**에서 **모델을 재사용**할 수 있을 뿐만 아니라, 매개변수에 대한 검증 및 메타데이터도 한 번에 선언할 수 있습니다. 😎
+
+/// note | 참고
+
+이 기능은 FastAPI 버전 `0.115.0`부터 제공됩니다. 🤓
+
+///
+
+## 쿼리 매개변수와 Pydantic 모델
+
+필요한 **쿼리 매개변수**를 **Pydantic 모델** 안에 선언한 다음, 모델을 `Query`로 선언합니다.
+
+{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *}
+
+**FastAPI**는 요청의 **쿼리 매개변수**에서 **각 필드**의 데이터를 **추출**해 정의한 Pydantic 모델로 제공합니다.
+
+## 문서 확인하기
+
+`/docs` 경로의 API 문서에서 매개변수를 확인할 수 있습니다.
+
+
+POST에 관한MDN웹 문서 를 참고하기 바랍니다,.
+하지만 파일이 포함된 경우, `multipart/form-data`로 인코딩됩니다. `File`을 사용하였다면, **FastAPI**는 본문의 적합한 부분에서 파일을 가져와야 한다는 것을 인지합니다.
-!!! warning "경고"
- 다수의 `File` 과 `Form` 매개변수를 한 *경로 작동*에 선언하는 것이 가능하지만, 요청의 본문이 `application/json` 가 아닌 `multipart/form-data` 로 인코딩 되기 때문에 JSON으로 받아야하는 `Body` 필드를 함께 선언할 수는 없습니다.
+인코딩과 폼 필드에 대해 더 알고싶다면, POST에 관한MDN웹 문서 를 참고하기 바랍니다,.
- 이는 **FastAPI**의 한계가 아니라, HTTP 프로토콜에 의한 것입니다.
+///
+
+/// warning | 경고
+
+다수의 `File` 과 `Form` 매개변수를 한 *경로 작동*에 선언하는 것이 가능하지만, 요청의 본문이 `application/json` 가 아닌 `multipart/form-data` 로 인코딩 되기 때문에 JSON으로 받아야하는 `Body` 필드를 함께 선언할 수는 없습니다.
+
+이는 **FastAPI**의 한계가 아니라, HTTP 프로토콜에 의한 것입니다.
+
+///
## 다중 파일 업로드
@@ -121,23 +136,27 @@ HTML의 폼들(``)이 서버에 데이터를 전송하는 방식은
이 기능을 사용하기 위해 , `bytes` 의 `List` 또는 `UploadFile` 를 선언하기 바랍니다:
-```Python hl_lines="10 15"
-{!../../../docs_src/request_files/tutorial002.py!}
-```
+{* ../../docs_src/request_files/tutorial002.py hl[10,15] *}
선언한대로, `bytes` 의 `list` 또는 `UploadFile` 들을 전송받을 것입니다.
-!!! note "참고"
- 2019년 4월 14일부터 Swagger UI가 하나의 폼 필드로 다수의 파일을 업로드하는 것을 지원하지 않습니다. 더 많은 정보를 원하면, #4276과 #3641을 참고하세요.
+/// note | 참고
- 그럼에도, **FastAPI**는 표준 Open API를 사용해 이미 호환이 가능합니다.
+2019년 4월 14일부터 Swagger UI가 하나의 폼 필드로 다수의 파일을 업로드하는 것을 지원하지 않습니다. 더 많은 정보를 원하면, #4276과 #3641을 참고하세요.
- 따라서 Swagger UI 또는 기타 그 외의 OpenAPI를 지원하는 툴이 다중 파일 업로드를 지원하는 경우, 이들은 **FastAPI**와 호환됩니다.
+그럼에도, **FastAPI**는 표준 Open API를 사용해 이미 호환이 가능합니다.
-!!! note "기술적 세부사항"
- `from starlette.responses import HTMLResponse` 역시 사용할 수 있습니다.
+따라서 Swagger UI 또는 기타 그 외의 OpenAPI를 지원하는 툴이 다중 파일 업로드를 지원하는 경우, 이들은 **FastAPI**와 호환됩니다.
- **FastAPI**는 개발자의 편의를 위해 `fastapi.responses` 와 동일한 `starlette.responses` 도 제공합니다. 하지만 대부분의 응답들은 Starlette로부터 직접 제공됩니다.
+///
+
+/// note | 기술적 세부사항
+
+`from starlette.responses import HTMLResponse` 역시 사용할 수 있습니다.
+
+**FastAPI**는 개발자의 편의를 위해 `fastapi.responses` 와 동일한 `starlette.responses` 도 제공합니다. 하지만 대부분의 응답들은 Starlette로부터 직접 제공됩니다.
+
+///
## 요약
diff --git a/docs/ko/docs/tutorial/request-form-models.md b/docs/ko/docs/tutorial/request-form-models.md
new file mode 100644
index 000000000..3316a93d5
--- /dev/null
+++ b/docs/ko/docs/tutorial/request-form-models.md
@@ -0,0 +1,78 @@
+# 폼 모델
+
+FastAPI에서 **Pydantic 모델**을 이용하여 **폼 필드**를 선언할 수 있습니다.
+
+/// info | 정보
+
+폼(Form)을 사용하려면, 먼저 `python-multipart`를 설치하세요.
+
+[가상 환경](../virtual-environments.md){.internal-link target=_blank}을 생성하고 활성화한 다음, 아래와 같이 설치할 수 있습니다:
+
+```console
+$ pip install python-multipart
+```
+
+///
+
+/// note | 참고
+
+이 기능은 FastAPI 버전 `0.113.0` 이후부터 지원됩니다. 🤓
+
+///
+
+## Pydantic 모델을 사용한 폼
+
+**폼 필드**로 받고 싶은 필드를 **Pydantic 모델**로 선언한 다음, 매개변수를 `Form`으로 선언하면 됩니다:
+
+{* ../../docs_src/request_form_models/tutorial001_an_py39.py hl[9:11,15] *}
+
+**FastAPI**는 요청에서 받은 **폼 데이터**에서 **각 필드**에 대한 데이터를 **추출**하고 정의한 Pydantic 모델을 줍니다.
+
+## 문서 확인하기
+
+문서 UI `/docs`에서 확인할 수 있습니다:
+
+
+POST에 대한 MDN 웹 문서를 참조하세요.
+
+///
+
+/// warning | 경고
+
+*경로 작업*에서 여러 `Form` 매개변수를 선언할 수 있지만, JSON으로 수신할 것으로 예상되는 `Body` 필드와 함께 선언할 수 없습니다. 요청 본문은 `application/json` 대신에 `application/x-www-form-urlencoded`를 사용하여 인코딩되기 때문입니다.
+
+이는 **FastAPI**의 제한 사항이 아니며 HTTP 프로토콜의 일부입니다.
+
+///
+
+## 요약
+
+폼 데이터 입력 매개변수를 선언하려면 `Form`을 사용하세요.
diff --git a/docs/ko/docs/tutorial/response-model.md b/docs/ko/docs/tutorial/response-model.md
index feff88a42..a71d649f9 100644
--- a/docs/ko/docs/tutorial/response-model.md
+++ b/docs/ko/docs/tutorial/response-model.md
@@ -8,12 +8,13 @@
* `@app.delete()`
* 기타.
-```Python hl_lines="17"
-{!../../../docs_src/response_model/tutorial001.py!}
-```
+{* ../../docs_src/response_model/tutorial001.py hl[17] *}
-!!! note "참고"
- `response_model`은 "데코레이터" 메소드(`get`, `post`, 등)의 매개변수입니다. 모든 매개변수들과 본문(body)처럼 *경로 작동 함수*가 아닙니다.
+/// note | 참고
+
+`response_model`은 "데코레이터" 메소드(`get`, `post`, 등)의 매개변수입니다. 모든 매개변수들과 본문(body)처럼 *경로 작동 함수*가 아닙니다.
+
+///
Pydantic 모델 어트리뷰트를 선언한 것과 동일한 타입을 수신하므로 Pydantic 모델이 될 수 있지만, `List[Item]`과 같이 Pydantic 모델들의 `list`일 수도 있습니다.
@@ -28,22 +29,21 @@ FastAPI는 이 `response_model`를 사용하여:
* 해당 모델의 출력 데이터 제한. 이것이 얼마나 중요한지 아래에서 볼 것입니다.
-!!! note "기술 세부사항"
- 응답 모델은 함수의 타입 어노테이션 대신 이 매개변수로 선언하는데, 경로 함수가 실제 응답 모델을 반환하지 않고 `dict`, 데이터베이스 객체나 기타 다른 모델을 `response_model`을 사용하여 필드 제한과 직렬화를 수행하고 반환할 수 있기 때문입니다
+/// note | 기술 세부사항
+
+응답 모델은 함수의 타입 어노테이션 대신 이 매개변수로 선언하는데, 경로 함수가 실제 응답 모델을 반환하지 않고 `dict`, 데이터베이스 객체나 기타 다른 모델을 `response_model`을 사용하여 필드 제한과 직렬화를 수행하고 반환할 수 있기 때문입니다
+
+///
## 동일한 입력 데이터 반환
여기서 우리는 평문 비밀번호를 포함하는 `UserIn` 모델을 선언합니다:
-```Python hl_lines="9 11"
-{!../../../docs_src/response_model/tutorial002.py!}
-```
+{* ../../docs_src/response_model/tutorial002.py hl[9,11] *}
그리고 이 모델을 사용하여 입력을 선언하고 같은 모델로 출력을 선언합니다:
-```Python hl_lines="17-18"
-{!../../../docs_src/response_model/tutorial002.py!}
-```
+{* ../../docs_src/response_model/tutorial002.py hl[17:18] *}
이제 브라우저가 비밀번호로 사용자를 만들 때마다 API는 응답으로 동일한 비밀번호를 반환합니다.
@@ -51,28 +51,25 @@ FastAPI는 이 `response_model`를 사용하여:
그러나 동일한 모델을 다른 *경로 작동*에서 사용할 경우, 모든 클라이언트에게 사용자의 비밀번호를 발신할 수 있습니다.
-!!! danger "위험"
- 절대로 사용자의 평문 비밀번호를 저장하거나 응답으로 발신하지 마십시오.
+/// danger | 위험
+
+절대로 사용자의 평문 비밀번호를 저장하거나 응답으로 발신하지 마십시오.
+
+///
## 출력 모델 추가
대신 평문 비밀번호로 입력 모델을 만들고 해당 비밀번호 없이 출력 모델을 만들 수 있습니다:
-```Python hl_lines="9 11 16"
-{!../../../docs_src/response_model/tutorial003.py!}
-```
+{* ../../docs_src/response_model/tutorial003.py hl[9,11,16] *}
여기서 *경로 작동 함수*가 비밀번호를 포함하는 동일한 입력 사용자를 반환할지라도:
-```Python hl_lines="24"
-{!../../../docs_src/response_model/tutorial003.py!}
-```
+{* ../../docs_src/response_model/tutorial003.py hl[24] *}
...`response_model`을 `UserOut` 모델로 선언했기 때문에 비밀번호를 포함하지 않습니다:
-```Python hl_lines="22"
-{!../../../docs_src/response_model/tutorial003.py!}
-```
+{* ../../docs_src/response_model/tutorial003.py hl[22] *}
따라서 **FastAPI**는 출력 모델에서 선언하지 않은 모든 데이터를 (Pydantic을 사용하여) 필터링합니다.
@@ -90,9 +87,7 @@ FastAPI는 이 `response_model`를 사용하여:
응답 모델은 아래와 같이 기본값을 가질 수 있습니다:
-```Python hl_lines="11 13-14"
-{!../../../docs_src/response_model/tutorial004.py!}
-```
+{* ../../docs_src/response_model/tutorial004.py hl[11,13:14] *}
* `description: Optional[str] = None`은 기본값으로 `None`을 갖습니다.
* `tax: float = 10.5`는 기본값으로 `10.5`를 갖습니다.
@@ -106,9 +101,7 @@ FastAPI는 이 `response_model`를 사용하여:
*경로 작동 데코레이터* 매개변수를 `response_model_exclude_unset=True`로 설정 할 수 있습니다:
-```Python hl_lines="24"
-{!../../../docs_src/response_model/tutorial004.py!}
-```
+{* ../../docs_src/response_model/tutorial004.py hl[24] *}
이러한 기본값은 응답에 포함되지 않고 실제로 설정된 값만 포함됩니다.
@@ -121,16 +114,22 @@ FastAPI는 이 `response_model`를 사용하여:
}
```
-!!! info "정보"
- FastAPI는 이를 위해 Pydantic 모델의 `.dict()`의 `exclude_unset` 매개변수를 사용합니다.
+/// info | 정보
-!!! info "정보"
- 아래 또한 사용할 수 있습니다:
+FastAPI는 이를 위해 Pydantic 모델의 `.dict()`의 `exclude_unset` 매개변수를 사용합니다.
- * `response_model_exclude_defaults=True`
- * `response_model_exclude_none=True`
+///
- Pydantic 문서에서 `exclude_defaults` 및 `exclude_none`에 대해 설명한 대로 사용할 수 있습니다.
+/// info | 정보
+
+아래 또한 사용할 수 있습니다:
+
+* `response_model_exclude_defaults=True`
+* `response_model_exclude_none=True`
+
+Pydantic 문서에서 `exclude_defaults` 및 `exclude_none`에 대해 설명한 대로 사용할 수 있습니다.
+
+///
#### 기본값이 있는 필드를 갖는 값의 데이터
@@ -166,10 +165,13 @@ ID가 `baz`인 항목(items)처럼 기본값과 동일한 값을 갖는다면:
따라서 JSON 스키마에 포함됩니다.
-!!! tip "팁"
- `None` 뿐만 아니라 다른 어떤 것도 기본값이 될 수 있습니다.
+/// tip | 팁
- 리스트(`[]`), `float`인 `10.5` 등이 될 수 있습니다.
+`None` 뿐만 아니라 다른 어떤 것도 기본값이 될 수 있습니다.
+
+리스트(`[]`), `float`인 `10.5` 등이 될 수 있습니다.
+
+///
### `response_model_include` 및 `response_model_exclude`
@@ -179,29 +181,31 @@ ID가 `baz`인 항목(items)처럼 기본값과 동일한 값을 갖는다면:
Pydantic 모델이 하나만 있고 출력에서 일부 데이터를 제거하려는 경우 빠른 지름길로 사용할 수 있습니다.
-!!! tip "팁"
- 하지만 이러한 매개변수 대신 여러 클래스를 사용하여 위 아이디어를 사용하는 것을 추천합니다.
+/// tip | 팁
- 이는 일부 어트리뷰트를 생략하기 위해 `response_model_include` 또는 `response_model_exclude`를 사용하더라도 앱의 OpenAPI(및 문서)가 생성한 JSON 스키마가 여전히 전체 모델에 대한 스키마이기 때문입니다.
+하지만 이러한 매개변수 대신 여러 클래스를 사용하여 위 아이디어를 사용하는 것을 추천합니다.
- 비슷하게 작동하는 `response_model_by_alias` 역시 마찬가지로 적용됩니다.
+이는 일부 어트리뷰트를 생략하기 위해 `response_model_include` 또는 `response_model_exclude`를 사용하더라도 앱의 OpenAPI(및 문서)가 생성한 JSON 스키마가 여전히 전체 모델에 대한 스키마이기 때문입니다.
-```Python hl_lines="31 37"
-{!../../../docs_src/response_model/tutorial005.py!}
-```
+비슷하게 작동하는 `response_model_by_alias` 역시 마찬가지로 적용됩니다.
-!!! tip "팁"
- 문법 `{"name", "description"}`은 두 값을 갖는 `set`을 만듭니다.
+///
- 이는 `set(["name", "description"])`과 동일합니다.
+{* ../../docs_src/response_model/tutorial005.py hl[31,37] *}
+
+/// tip | 팁
+
+문법 `{"name", "description"}`은 두 값을 갖는 `set`을 만듭니다.
+
+이는 `set(["name", "description"])`과 동일합니다.
+
+///
#### `set` 대신 `list` 사용하기
`list` 또는 `tuple` 대신 `set`을 사용하는 법을 잊었더라도, FastAPI는 `set`으로 변환하고 정상적으로 작동합니다:
-```Python hl_lines="31 37"
-{!../../../docs_src/response_model/tutorial006.py!}
-```
+{* ../../docs_src/response_model/tutorial006.py hl[31,37] *}
## 요약
diff --git a/docs/ko/docs/tutorial/response-status-code.md b/docs/ko/docs/tutorial/response-status-code.md
index e6eed5120..bcaf7843b 100644
--- a/docs/ko/docs/tutorial/response-status-code.md
+++ b/docs/ko/docs/tutorial/response-status-code.md
@@ -8,17 +8,21 @@
* `@app.delete()`
* 기타
-```Python hl_lines="6"
-{!../../../docs_src/response_status_code/tutorial001.py!}
-```
+{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
-!!! note "참고"
- `status_code` 는 "데코레이터" 메소드(`get`, `post` 등)의 매개변수입니다. 모든 매개변수들과 본문처럼 *경로 작동 함수*가 아닙니다.
+/// note | 참고
+
+`status_code` 는 "데코레이터" 메소드(`get`, `post` 등)의 매개변수입니다. 모든 매개변수들과 본문처럼 *경로 작동 함수*가 아닙니다.
+
+///
`status_code` 매개변수는 HTTP 상태 코드를 숫자로 입력받습니다.
-!!! info "정보"
- `status_code` 는 파이썬의 `http.HTTPStatus` 와 같은 `IntEnum` 을 입력받을 수도 있습니다.
+/// info | 정보
+
+`status_code` 는 파이썬의 `http.HTTPStatus` 와 같은 `IntEnum` 을 입력받을 수도 있습니다.
+
+///
`status_code` 매개변수는:
@@ -27,15 +31,21 @@
-!!! note "참고"
- 어떤 응답 코드들은 해당 응답에 본문이 없다는 것을 의미하기도 합니다 (다음 항목 참고).
+/// note | 참고
- 이에 따라 FastAPI는 응답 본문이 없음을 명시하는 OpenAPI를 생성합니다.
+어떤 응답 코드들은 해당 응답에 본문이 없다는 것을 의미하기도 합니다 (다음 항목 참고).
+
+이에 따라 FastAPI는 응답 본문이 없음을 명시하는 OpenAPI를 생성합니다.
+
+///
## HTTP 상태 코드에 대하여
-!!! note "참고"
- 만약 HTTP 상태 코드에 대하여 이미 알고있다면, 다음 항목으로 넘어가십시오.
+/// note | 참고
+
+만약 HTTP 상태 코드에 대하여 이미 알고있다면, 다음 항목으로 넘어가십시오.
+
+///
HTTP는 세자리의 숫자 상태 코드를 응답의 일부로 전송합니다.
@@ -54,16 +64,17 @@ HTTP는 세자리의 숫자 상태 코드를 응답의 일부로 전송합니다
* 일반적인 클라이언트 오류의 경우 `400` 을 사용할 수 있습니다.
* `5xx` 상태 코드는 서버 오류에 사용됩니다. 이것들을 직접 사용할 일은 거의 없습니다. 응용 프로그램 코드나 서버의 일부에서 문제가 발생하면 자동으로 이들 상태 코드 중 하나를 반환합니다.
-!!! tip "팁"
- 각각의 상태 코드와 이들이 의미하는 내용에 대해 더 알고싶다면 MDN HTTP 상태 코드에 관한 문서 를 확인하십시오.
+/// tip | 팁
+
+각각의 상태 코드와 이들이 의미하는 내용에 대해 더 알고싶다면 MDN HTTP 상태 코드에 관한 문서 를 확인하십시오.
+
+///
## 이름을 기억하는 쉬운 방법
상기 예시 참고:
-```Python hl_lines="6"
-{!../../../docs_src/response_status_code/tutorial001.py!}
-```
+{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
`201` 은 "생성됨"를 의미하는 상태 코드입니다.
@@ -71,18 +82,19 @@ HTTP는 세자리의 숫자 상태 코드를 응답의 일부로 전송합니다
`fastapi.status` 의 편의 변수를 사용할 수 있습니다.
-```Python hl_lines="1 6"
-{!../../../docs_src/response_status_code/tutorial002.py!}
-```
+{* ../../docs_src/response_status_code/tutorial002.py hl[1,6] *}
이것은 단순히 작업을 편리하게 하기 위한 것으로, HTTP 상태 코드와 동일한 번호를 갖고있지만, 이를 사용하면 편집기의 자동완성 기능을 사용할 수 있습니다:
-!!! note "기술적 세부사항"
- `from starlette import status` 역시 사용할 수 있습니다.
+/// note | 기술적 세부사항
- **FastAPI**는 개발자인 여러분의 편의를 위해 `fastapi.status` 와 동일한 `starlette.status` 도 제공합니다. 하지만 이것은 Starlette로부터 직접 제공됩니다.
+`from starlette import status` 역시 사용할 수 있습니다.
+
+**FastAPI**는 개발자인 여러분의 편의를 위해 `fastapi.status` 와 동일한 `starlette.status` 도 제공합니다. 하지만 이것은 Starlette로부터 직접 제공됩니다.
+
+///
## 기본값 변경
diff --git a/docs/ko/docs/tutorial/schema-extra-example.md b/docs/ko/docs/tutorial/schema-extra-example.md
index 4e319e075..77e94db72 100644
--- a/docs/ko/docs/tutorial/schema-extra-example.md
+++ b/docs/ko/docs/tutorial/schema-extra-example.md
@@ -8,71 +8,59 @@
생성된 JSON 스키마에 추가될 Pydantic 모델을 위한 `examples`을 선언할 수 있습니다.
-=== "Python 3.10+ Pydantic v2"
+//// tab | Pydantic v2
- ```Python hl_lines="13-24"
- {!> ../../../docs_src/schema_extra_example/tutorial001_py310.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial001_py310.py hl[13:24] *}
-=== "Python 3.10+ Pydantic v1"
+////
- ```Python hl_lines="13-23"
- {!> ../../../docs_src/schema_extra_example/tutorial001_py310_pv1.py!}
- ```
+//// tab | Pydantic v1
-=== "Python 3.8+ Pydantic v2"
+{* ../../docs_src/schema_extra_example/tutorial001_pv1_py310.py hl[13:23] *}
- ```Python hl_lines="15-26"
- {!> ../../../docs_src/schema_extra_example/tutorial001.py!}
- ```
-
-=== "Python 3.8+ Pydantic v1"
-
- ```Python hl_lines="15-25"
- {!> ../../../docs_src/schema_extra_example/tutorial001_pv1.py!}
- ```
+////
추가 정보는 있는 그대로 해당 모델의 **JSON 스키마** 결과에 추가되고, API 문서에서 사용합니다.
-=== "Pydantic v2"
+//// tab | Pydantic v2
- Pydantic 버전 2에서 Pydantic 공식 문서: Model Config에 나와 있는 것처럼 `dict`를 받는 `model_config` 어트리뷰트를 사용할 것입니다.
+Pydantic 버전 2에서 Pydantic 공식 문서: Model Config에 나와 있는 것처럼 `dict`를 받는 `model_config` 어트리뷰트를 사용할 것입니다.
- `"json_schema_extra"`를 생성된 JSON 스키마에서 보여주고 싶은 별도의 데이터와 `examples`를 포함하는 `dict`으로 설정할 수 있습니다.
+`"json_schema_extra"`를 생성된 JSON 스키마에서 보여주고 싶은 별도의 데이터와 `examples`를 포함하는 `dict`으로 설정할 수 있습니다.
-=== "Pydantic v1"
+////
- Pydantic v1에서 Pydantic 공식 문서: Schema customization에서 설명하는 것처럼, 내부 클래스인 `Config`와 `schema_extra`를 사용할 것입니다.
+//// tab | Pydantic v1
- `schema_extra`를 생성된 JSON 스키마에서 보여주고 싶은 별도의 데이터와 `examples`를 포함하는 `dict`으로 설정할 수 있습니다.
+Pydantic v1에서 Pydantic 공식 문서: Schema customization에서 설명하는 것처럼, 내부 클래스인 `Config`와 `schema_extra`를 사용할 것입니다.
-!!! tip "팁"
- JSON 스키마를 확장하고 여러분의 별도의 자체 데이터를 추가하기 위해 같은 기술을 사용할 수 있습니다.
+`schema_extra`를 생성된 JSON 스키마에서 보여주고 싶은 별도의 데이터와 `examples`를 포함하는 `dict`으로 설정할 수 있습니다.
- 예를 들면, 프론트엔드 사용자 인터페이스에 메타데이터를 추가하는 등에 사용할 수 있습니다.
+////
-!!! info "정보"
- (FastAPI 0.99.0부터 쓰이기 시작한) OpenAPI 3.1.0은 **JSON 스키마** 표준의 일부인 `examples`에 대한 지원을 추가했습니다.
+/// tip | 팁
- 그 전에는, 하나의 예제만 가능한 `example` 키워드만 지원했습니다. 이는 아직 OpenAPI 3.1.0에서 지원하지만, 지원이 종료될 것이며 JSON 스키마 표준에 포함되지 않습니다. 그렇기에 `example`을 `examples`으로 이전하는 것을 추천합니다. 🤓
+JSON 스키마를 확장하고 여러분의 별도의 자체 데이터를 추가하기 위해 같은 기술을 사용할 수 있습니다.
- 이 문서 끝에 더 많은 읽을거리가 있습니다.
+예를 들면, 프론트엔드 사용자 인터페이스에 메타데이터를 추가하는 등에 사용할 수 있습니다.
+
+///
+
+/// info | 정보
+
+(FastAPI 0.99.0부터 쓰이기 시작한) OpenAPI 3.1.0은 **JSON 스키마** 표준의 일부인 `examples`에 대한 지원을 추가했습니다.
+
+그 전에는, 하나의 예제만 가능한 `example` 키워드만 지원했습니다. 이는 아직 OpenAPI 3.1.0에서 지원하지만, 지원이 종료될 것이며 JSON 스키마 표준에 포함되지 않습니다. 그렇기에 `example`을 `examples`으로 이전하는 것을 추천합니다. 🤓
+
+이 문서 끝에 더 많은 읽을거리가 있습니다.
+
+///
## `Field` 추가 인자
Pydantic 모델과 같이 `Field()`를 사용할 때 추가적인 `examples`를 선언할 수 있습니다:
-=== "Python 3.10+"
-
- ```Python hl_lines="2 8-11"
- {!> ../../../docs_src/schema_extra_example/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="4 10-13"
- {!> ../../../docs_src/schema_extra_example/tutorial002.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial002_py310.py hl[2,8:11] *}
## JSON Schema에서의 `examples` - OpenAPI
@@ -92,41 +80,7 @@ Pydantic 모델과 같이 `Field()`를 사용할 때 추가적인 `examples`를
여기, `Body()`에 예상되는 예제 데이터 하나를 포함한 `examples`를 넘겼습니다:
-=== "Python 3.10+"
-
- ```Python hl_lines="22-29"
- {!> ../../../docs_src/schema_extra_example/tutorial003_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="22-29"
- {!> ../../../docs_src/schema_extra_example/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="23-30"
- {!> ../../../docs_src/schema_extra_example/tutorial003_an.py!}
- ```
-
-=== "Python 3.10+ Annotated가 없는 경우"
-
- !!! tip "팁"
- 가능하다면 `Annotated`가 달린 버전을 권장합니다.
-
- ```Python hl_lines="18-25"
- {!> ../../../docs_src/schema_extra_example/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+ Annotated가 없는 경우"
-
- !!! tip "팁"
- 가능하다면 `Annotated`가 달린 버전을 권장합니다.
-
- ```Python hl_lines="20-27"
- {!> ../../../docs_src/schema_extra_example/tutorial003.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial003_an_py310.py hl[22:29] *}
### 문서 UI 예시
@@ -138,41 +92,7 @@ Pydantic 모델과 같이 `Field()`를 사용할 때 추가적인 `examples`를
물론 여러 `examples`를 넘길 수 있습니다:
-=== "Python 3.10+"
-
- ```Python hl_lines="23-38"
- {!> ../../../docs_src/schema_extra_example/tutorial004_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="23-38"
- {!> ../../../docs_src/schema_extra_example/tutorial004_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="24-39"
- {!> ../../../docs_src/schema_extra_example/tutorial004_an.py!}
- ```
-
-=== "Python 3.10+ Annotated가 없는 경우"
-
- !!! tip "팁"
- 가능하다면 `Annotated`가 달린 버전을 권장합니다.
-
- ```Python hl_lines="19-34"
- {!> ../../../docs_src/schema_extra_example/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+ Annotated가 없는 경우"
-
- !!! tip "팁"
- 가능하다면 `Annotated`가 달린 버전을 권장합니다.
-
- ```Python hl_lines="21-36"
- {!> ../../../docs_src/schema_extra_example/tutorial004.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial004_an_py310.py hl[23:38] *}
이와 같이 하면 이 예제는 그 본문 데이터를 위한 내부 **JSON 스키마**의 일부가 될 것입니다.
@@ -213,41 +133,7 @@ Pydantic 모델과 같이 `Field()`를 사용할 때 추가적인 `examples`를
이를 다음과 같이 사용할 수 있습니다:
-=== "Python 3.10+"
-
- ```Python hl_lines="23-49"
- {!> ../../../docs_src/schema_extra_example/tutorial005_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="23-49"
- {!> ../../../docs_src/schema_extra_example/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="24-50"
- {!> ../../../docs_src/schema_extra_example/tutorial005_an.py!}
- ```
-
-=== "Python 3.10+ Annotated가 없는 경우"
-
- !!! tip "팁"
- 가능하다면 `Annotated`가 달린 버전을 권장합니다.
-
- ```Python hl_lines="19-45"
- {!> ../../../docs_src/schema_extra_example/tutorial005_py310.py!}
- ```
-
-=== "Python 3.8+ Annotated가 없는 경우"
-
- !!! tip "팁"
- 가능하다면 `Annotated`가 달린 버전을 권장합니다.
-
- ```Python hl_lines="21-47"
- {!> ../../../docs_src/schema_extra_example/tutorial005.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial005_an_py310.py hl[23:49] *}
### 문서 UI에서의 OpenAPI 예시
@@ -257,17 +143,23 @@ Pydantic 모델과 같이 `Field()`를 사용할 때 추가적인 `examples`를
## 기술적 세부 사항
-!!! tip "팁"
- 이미 **FastAPI**의 **0.99.0 혹은 그 이상** 버전을 사용하고 있다면, 이 세부 사항을 **스킵**해도 상관 없을 것입니다.
+/// tip | 팁
- 세부 사항은 OpenAPI 3.1.0이 사용가능하기 전, 예전 버전과 더 관련있습니다.
+이미 **FastAPI**의 **0.99.0 혹은 그 이상** 버전을 사용하고 있다면, 이 세부 사항을 **스킵**해도 상관 없을 것입니다.
- 간략한 OpenAPI와 JSON 스키마 **역사 강의**로 생각할 수 있습니다. 🤓
+세부 사항은 OpenAPI 3.1.0이 사용가능하기 전, 예전 버전과 더 관련있습니다.
-!!! warning "경고"
- 표준 **JSON 스키마**와 **OpenAPI**에 대한 아주 기술적인 세부사항입니다.
+간략한 OpenAPI와 JSON 스키마 **역사 강의**로 생각할 수 있습니다. 🤓
- 만약 위의 생각이 작동한다면, 그것으로 충분하며 이 세부 사항은 필요없을 것이니, 마음 편하게 스킵하셔도 됩니다.
+///
+
+/// warning | 경고
+
+표준 **JSON 스키마**와 **OpenAPI**에 대한 아주 기술적인 세부사항입니다.
+
+만약 위의 생각이 작동한다면, 그것으로 충분하며 이 세부 사항은 필요없을 것이니, 마음 편하게 스킵하셔도 됩니다.
+
+///
OpenAPI 3.1.0 전에 OpenAPI는 오래된 **JSON 스키마**의 수정된 버전을 사용했습니다.
@@ -285,8 +177,11 @@ OpenAPI는 또한 `example`과 `examples` 필드를 명세서의 다른 부분
* `File()`
* `Form()`
-!!! info "정보"
- 이 예전 OpenAPI-특화 `examples` 매개변수는 이제 FastAPI `0.103.0`부터 `openapi_examples`입니다.
+/// info | 정보
+
+이 예전 OpenAPI-특화 `examples` 매개변수는 이제 FastAPI `0.103.0`부터 `openapi_examples`입니다.
+
+///
### JSON 스키마의 `examples` 필드
@@ -298,10 +193,13 @@ OpenAPI는 또한 `example`과 `examples` 필드를 명세서의 다른 부분
JSON 스키마의 새로운 `examples` 필드는 예제 속 **단순한 `list`**이며, (위에서 상술한 것처럼) OpenAPI의 다른 곳에 존재하는 dict으로 된 추가적인 메타데이터가 아닙니다.
-!!! info "정보"
- 더 쉽고 새로운 JSON 스키마와의 통합과 함께 OpenAPI 3.1.0가 배포되었지만, 잠시동안 자동 문서 생성을 제공하는 도구인 Swagger UI는 OpenAPI 3.1.0을 지원하지 않았습니다 (5.0.0 버전부터 지원합니다 🎉).
+/// info | 정보
- 이로인해, FastAPI 0.99.0 이전 버전은 아직 OpenAPI 3.1.0 보다 낮은 버전을 사용했습니다.
+더 쉽고 새로운 JSON 스키마와의 통합과 함께 OpenAPI 3.1.0가 배포되었지만, 잠시동안 자동 문서 생성을 제공하는 도구인 Swagger UI는 OpenAPI 3.1.0을 지원하지 않았습니다 (5.0.0 버전부터 지원합니다 🎉).
+
+이로인해, FastAPI 0.99.0 이전 버전은 아직 OpenAPI 3.1.0 보다 낮은 버전을 사용했습니다.
+
+///
### Pydantic과 FastAPI `examples`
diff --git a/docs/ko/docs/tutorial/security/get-current-user.md b/docs/ko/docs/tutorial/security/get-current-user.md
index f4b6f9471..98ef3885e 100644
--- a/docs/ko/docs/tutorial/security/get-current-user.md
+++ b/docs/ko/docs/tutorial/security/get-current-user.md
@@ -2,9 +2,7 @@
이전 장에서 (의존성 주입 시스템을 기반으로 한)보안 시스템은 *경로 작동 함수*에서 `str`로 `token`을 제공했습니다:
-```Python hl_lines="10"
-{!../../../docs_src/security/tutorial001.py!}
-```
+{* ../../docs_src/security/tutorial001.py hl[10] *}
그러나 아직도 유용하지 않습니다.
@@ -16,17 +14,7 @@
Pydantic을 사용하여 본문을 선언하는 것과 같은 방식으로 다른 곳에서 사용할 수 있습니다.
-=== "파이썬 3.7 이상"
-
- ```Python hl_lines="5 12-16"
- {!> ../../../docs_src/security/tutorial002.py!}
- ```
-
-=== "파이썬 3.10 이상"
-
- ```Python hl_lines="3 10-14"
- {!> ../../../docs_src/security/tutorial002_py310.py!}
- ```
+{* ../../docs_src/security/tutorial002.py hl[5,12:16] *}
## `get_current_user` 의존성 생성하기
@@ -38,63 +26,39 @@ Pydantic을 사용하여 본문을 선언하는 것과 같은 방식으로 다
이전에 *경로 작동*에서 직접 수행했던 것과 동일하게 새 종속성 `get_current_user`는 하위 종속성 `oauth2_scheme`에서 `str`로 `token`을 수신합니다.
-=== "파이썬 3.7 이상"
-
- ```Python hl_lines="25"
- {!> ../../../docs_src/security/tutorial002.py!}
- ```
-
-=== "파이썬 3.10 이상"
-
- ```Python hl_lines="23"
- {!> ../../../docs_src/security/tutorial002_py310.py!}
- ```
+{* ../../docs_src/security/tutorial002.py hl[25] *}
## 유저 가져오기
`get_current_user`는 토큰을 `str`로 취하고 Pydantic `User` 모델을 반환하는 우리가 만든 (가짜) 유틸리티 함수를 사용합니다.
-=== "파이썬 3.7 이상"
-
- ```Python hl_lines="19-22 26-27"
- {!> ../../../docs_src/security/tutorial002.py!}
- ```
-
-=== "파이썬 3.10 이상"
-
- ```Python hl_lines="17-20 24-25"
- {!> ../../../docs_src/security/tutorial002_py310.py!}
- ```
+{* ../../docs_src/security/tutorial002.py hl[19:22,26:27] *}
## 현재 유저 주입하기
이제 *경로 작동*에서 `get_current_user`와 동일한 `Depends`를 사용할 수 있습니다.
-=== "파이썬 3.7 이상"
-
- ```Python hl_lines="31"
- {!> ../../../docs_src/security/tutorial002.py!}
- ```
-
-=== "파이썬 3.10 이상"
-
- ```Python hl_lines="29"
- {!> ../../../docs_src/security/tutorial002_py310.py!}
- ```
+{* ../../docs_src/security/tutorial002.py hl[31] *}
Pydantic 모델인 `User`로 `current_user`의 타입을 선언하는 것을 알아야 합니다.
이것은 모든 완료 및 타입 검사를 통해 함수 내부에서 우리를 도울 것입니다.
-!!! tip "팁"
- 요청 본문도 Pydantic 모델로 선언된다는 것을 기억할 것입니다.
+/// tip | 팁
- 여기서 **FastAPI**는 `Depends`를 사용하고 있기 때문에 혼동되지 않습니다.
+요청 본문도 Pydantic 모델로 선언된다는 것을 기억할 것입니다.
-!!! check "확인"
- 이 의존성 시스템이 설계된 방식은 모두 `User` 모델을 반환하는 다양한 의존성(다른 "의존적인")을 가질 수 있도록 합니다.
+여기서 **FastAPI**는 `Depends`를 사용하고 있기 때문에 혼동되지 않습니다.
- 해당 타입의 데이터를 반환할 수 있는 의존성이 하나만 있는 것으로 제한되지 않습니다.
+///
+
+/// check | 확인
+
+이 의존성 시스템이 설계된 방식은 모두 `User` 모델을 반환하는 다양한 의존성(다른 "의존적인")을 가질 수 있도록 합니다.
+
+해당 타입의 데이터를 반환할 수 있는 의존성이 하나만 있는 것으로 제한되지 않습니다.
+
+///
## 다른 모델
@@ -128,17 +92,7 @@ Pydantic 모델인 `User`로 `current_user`의 타입을 선언하는 것을 알
그리고 이 수천 개의 *경로 작동*은 모두 3줄 정도로 줄일 수 있습니다.
-=== "파이썬 3.7 이상"
-
- ```Python hl_lines="30-32"
- {!> ../../../docs_src/security/tutorial002.py!}
- ```
-
-=== "파이썬 3.10 이상"
-
- ```Python hl_lines="28-30"
- {!> ../../../docs_src/security/tutorial002_py310.py!}
- ```
+{* ../../docs_src/security/tutorial002.py hl[30:32] *}
## 요약
diff --git a/docs/ko/docs/tutorial/security/oauth2-jwt.md b/docs/ko/docs/tutorial/security/oauth2-jwt.md
new file mode 100644
index 000000000..d8bac8346
--- /dev/null
+++ b/docs/ko/docs/tutorial/security/oauth2-jwt.md
@@ -0,0 +1,273 @@
+# 패스워드 해싱을 이용한 OAuth2, JWT 토큰을 사용하는 Bearer 인증
+
+모든 보안 흐름을 구성했으므로, 이제 JWT 토큰과 패스워드 해싱을 사용해 애플리케이션을 안전하게 만들 것입니다.
+
+이 코드는 실제로 애플리케이션에서 패스워드를 해싱하여 DB에 저장하는 등의 작업에 활용할 수 있습니다.
+
+이전 장에 이어서 시작해 봅시다.
+
+## JWT
+
+JWT 는 "JSON Web Tokens" 을 의미합니다.
+
+JSON 객체를 공백이 없는 긴 문자열로 인코딩하는 표준이며, 다음과 같은 형태입니다:
+
+```
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+```
+
+JWT는 암호화되지 않아 누구든지 토큰에서 정보를 복원할 수 있습니다.
+
+하지만 JWT는 서명되어 있습니다. 그래서 자신이 발급한 토큰을 받았을 때, 실제로 자신이 발급한게 맞는지 검증할 수 있습니다.
+
+만료 기간이 일주일인 토큰을 발행했다고 가정해 봅시다. 다음 날 사용자가 토큰을 가져왔을 때, 그 사용자가 시스템에 여전히 로그인되어 있다는 것을 알 수 있습니다.
+
+일주일 뒤에는 토큰이 만료될 것이고, 사용자는 인가되지 않아 새 토큰을 받기 위해 다시 로그인해야 할 것입니다. 만약 사용자(또는 제3자)가 토큰을 수정하거나 만료일을 변경하면, 서명이 일치하지 않기 때문에 알아챌 수 있을 것입니다.
+
+만약 JWT 토큰을 다뤄보고, 작동 방식도 알아보고 싶다면 https://jwt.io 을 확인하십시오.
+
+## `PyJWT` 설치
+
+파이썬으로 JWT 토큰을 생성하고 검증하려면 `PyJWT` 를 설치해야 합니다.
+
+[가상환경](../../virtual-environments.md){.internal-link target=_blank} 을 만들고 활성화한 다음 `pyjwt` 를 설치하십시오:
+
+
+
+이전과 같은 방법으로 애플리케이션에 인증하십시오.
+
+다음 인증 정보를 사용하십시오:
+
+Username: `johndoe`
+Password: `secret`
+
+/// check
+
+코드 어디에도 평문 패스워드 "`secret`" 이 없다는 점에 유의하십시오. 해시된 버전만 있습니다.
+
+///
+
+
+
+`/users/me/` 를 호출하면 다음과 같은 응답을 얻을 수 있습니다:
+
+```JSON
+{
+ "username": "johndoe",
+ "email": "johndoe@example.com",
+ "full_name": "John Doe",
+ "disabled": false
+}
+```
+
+
+
+개발자 도구를 열어보면 전송된 데이터에 토큰만 포함된 것을 확인할 수 있습니다. 패스워드는 사용자를 인증하고 액세스 토큰을 받기 위한 첫 번째 요청에만 전송되며, 이후에는 전송되지 않습니다:
+
+
+
+/// note
+
+`Bearer `로 시작하는 `Authorization` 헤더에 주목하십시오.
+
+///
+
+## `scopes` 의 고급 사용법
+
+OAuth2는 "스코프(scopes)" 라는 개념을 갖고 있습니다.
+
+이를 사용하여 JWT 토큰에 특정 권한 집합을 추가할 수 있습니다.
+
+그 후 이 토큰을 사용자에게 직접 제공하거나 제3자에게 제공하여, 특정 제한사항 하에있는 API와 통신하도록 할 수 있습니다.
+
+**FastAPI** 에서의 사용 방법과 통합 방식은 **심화 사용자 안내서** 에서 자세히 배울 수 있습니다.
+
+## 요약
+
+지금까지 살펴본 내용을 바탕으로, OAuth2와 JWT 같은 표준을 사용하여 안전한 **FastAPI** 애플리케이션을 만들 수 있습니다.
+
+거의 모든 프레임워크에서 보안 처리는 상당히 복잡한 주제입니다.
+
+이를 단순화하는 많은 패키지는 데이터 모델, 데이터베이스, 사용 가능한 기능들에 대해 여러 제약이 있습니다. 그리고 지나치게 단순화하는 일부 패키지들은 심각한 보안 결함을 가질 수도 있습니다.
+
+---
+
+**FastAPI** 는 어떤 데이터베이스, 데이터 모델, 도구도 강요하지 않습니다.
+
+프로젝트에 가장 적합한 것을 선택할 수 있는 유연성을 제공합니다.
+
+그리고 `passlib` 와 `PyJWT` 처럼 잘 관리되고 널리 사용되는 패키지들을 바로 사용할 수 있습니다. **FastAPI** 는 외부 패키지 통합을 위해 복잡한 메커니즘이 필요하지 않기 때문입니다.
+
+그러나 유연성, 견고성, 보안성을 해치지 않으면서 과정을 단순화할 수 있는 도구들을 제공합니다.
+
+그리고 OAuth2와 같은 표준 프로토콜을 비교적 간단한 방법으로 구현하고 사용할 수 있습니다.
+
+더 세분화된 권한 체계를 위해 OAuth2의 "스코프"를 사용하는 방법은 **심화 사용자 안내서**에서 더 자세히 배울 수 있습니다. OAuth2의 스코프는 제3자 애플리케이션이 사용자를 대신해 그들의 API와 상호작용하도록 권한을 부여하기 위해, Facebook, Google, GitHub, Microsoft, Twitter 등의 많은 대형 인증 제공업체들이 사용하는 메커니즘입니다.
diff --git a/docs/ko/docs/tutorial/security/simple-oauth2.md b/docs/ko/docs/tutorial/security/simple-oauth2.md
index 1e33f5766..f10c4f588 100644
--- a/docs/ko/docs/tutorial/security/simple-oauth2.md
+++ b/docs/ko/docs/tutorial/security/simple-oauth2.md
@@ -32,14 +32,17 @@ OAuth2는 (우리가 사용하고 있는) "패스워드 플로우"을 사용할
* `instagram_basic`은 페이스북/인스타그램에서 사용합니다.
* `https://www.googleapis.com/auth/drive`는 Google에서 사용합니다.
-!!! 정보
- OAuth2에서 "범위"는 필요한 특정 권한을 선언하는 문자열입니다.
+/// info | 정보
- `:`과 같은 다른 문자가 있는지 또는 URL인지는 중요하지 않습니다.
+OAuth2에서 "범위"는 필요한 특정 권한을 선언하는 문자열입니다.
- 이러한 세부 사항은 구현에 따라 다릅니다.
+`:`과 같은 다른 문자가 있는지 또는 URL인지는 중요하지 않습니다.
- OAuth2의 경우 문자열일 뿐입니다.
+이러한 세부 사항은 구현에 따라 다릅니다.
+
+OAuth2의 경우 문자열일 뿐입니다.
+
+///
## `username`과 `password`를 가져오는 코드
@@ -49,17 +52,7 @@ OAuth2는 (우리가 사용하고 있는) "패스워드 플로우"을 사용할
먼저 `OAuth2PasswordRequestForm`을 가져와 `/token`에 대한 *경로 작동*에서 `Depends`의 의존성으로 사용합니다.
-=== "파이썬 3.7 이상"
-
- ```Python hl_lines="4 76"
- {!> ../../../docs_src/security/tutorial003.py!}
- ```
-
-=== "파이썬 3.10 이상"
-
- ```Python hl_lines="2 74"
- {!> ../../../docs_src/security/tutorial003_py310.py!}
- ```
+{* ../../docs_src/security/tutorial003.py hl[4,76] *}
`OAuth2PasswordRequestForm`은 다음을 사용하여 폼 본문을 선언하는 클래스 의존성입니다:
@@ -68,29 +61,38 @@ OAuth2는 (우리가 사용하고 있는) "패스워드 플로우"을 사용할
* `scope`는 선택적인 필드로 공백으로 구분된 문자열로 구성된 큰 문자열입니다.
* `grant_type`(선택적으로 사용).
-!!! 팁
- OAuth2 사양은 실제로 `password`라는 고정 값이 있는 `grant_type` 필드를 *요구*하지만 `OAuth2PasswordRequestForm`은 이를 강요하지 않습니다.
+/// tip | 팁
- 사용해야 한다면 `OAuth2PasswordRequestForm` 대신 `OAuth2PasswordRequestFormStrict`를 사용하면 됩니다.
+OAuth2 사양은 실제로 `password`라는 고정 값이 있는 `grant_type` 필드를 *요구*하지만 `OAuth2PasswordRequestForm`은 이를 강요하지 않습니다.
+
+사용해야 한다면 `OAuth2PasswordRequestForm` 대신 `OAuth2PasswordRequestFormStrict`를 사용하면 됩니다.
+
+///
* `client_id`(선택적으로 사용) (예제에서는 필요하지 않습니다).
* `client_secret`(선택적으로 사용) (예제에서는 필요하지 않습니다).
-!!! 정보
- `OAuth2PasswordRequestForm`은 `OAuth2PasswordBearer`와 같이 **FastAPI**에 대한 특수 클래스가 아닙니다.
+/// info | 정보
- `OAuth2PasswordBearer`는 **FastAPI**가 보안 체계임을 알도록 합니다. 그래서 OpenAPI에 그렇게 추가됩니다.
+`OAuth2PasswordRequestForm`은 `OAuth2PasswordBearer`와 같이 **FastAPI**에 대한 특수 클래스가 아닙니다.
- 그러나 `OAuth2PasswordRequestForm`은 직접 작성하거나 `Form` 매개변수를 직접 선언할 수 있는 클래스 의존성일 뿐입니다.
+`OAuth2PasswordBearer`는 **FastAPI**가 보안 체계임을 알도록 합니다. 그래서 OpenAPI에 그렇게 추가됩니다.
- 그러나 일반적인 사용 사례이므로 더 쉽게 하기 위해 **FastAPI**에서 직접 제공합니다.
+그러나 `OAuth2PasswordRequestForm`은 직접 작성하거나 `Form` 매개변수를 직접 선언할 수 있는 클래스 의존성일 뿐입니다.
+
+그러나 일반적인 사용 사례이므로 더 쉽게 하기 위해 **FastAPI**에서 직접 제공합니다.
+
+///
### 폼 데이터 사용하기
-!!! 팁
- 종속성 클래스 `OAuth2PasswordRequestForm`의 인스턴스에는 공백으로 구분된 긴 문자열이 있는 `scope` 속성이 없고 대신 전송된 각 범위에 대한 실제 문자열 목록이 있는 `scopes` 속성이 있습니다.
+/// tip | 팁
- 이 예제에서는 `scopes`를 사용하지 않지만 필요한 경우, 기능이 있습니다.
+종속성 클래스 `OAuth2PasswordRequestForm`의 인스턴스에는 공백으로 구분된 긴 문자열이 있는 `scope` 속성이 없고 대신 전송된 각 범위에 대한 실제 문자열 목록이 있는 `scopes` 속성이 있습니다.
+
+이 예제에서는 `scopes`를 사용하지 않지만 필요한 경우, 기능이 있습니다.
+
+///
이제 폼 필드의 `username`을 사용하여 (가짜) 데이터베이스에서 유저 데이터를 가져옵니다.
@@ -98,17 +100,7 @@ OAuth2는 (우리가 사용하고 있는) "패스워드 플로우"을 사용할
오류의 경우 `HTTPException` 예외를 사용합니다:
-=== "파이썬 3.7 이상"
-
- ```Python hl_lines="3 77-79"
- {!> ../../../docs_src/security/tutorial003.py!}
- ```
-
-=== "파이썬 3.10 이상"
-
- ```Python hl_lines="1 75-77"
- {!> ../../../docs_src/security/tutorial003_py310.py!}
- ```
+{* ../../docs_src/security/tutorial003.py hl[3,77:79] *}
### 패스워드 확인하기
@@ -134,17 +126,13 @@ OAuth2는 (우리가 사용하고 있는) "패스워드 플로우"을 사용할
따라서 해커는 다른 시스템에서 동일한 암호를 사용하려고 시도할 수 없습니다(많은 사용자가 모든 곳에서 동일한 암호를 사용하므로 이는 위험할 수 있습니다).
-=== "P파이썬 3.7 이상"
+//// tab | 파이썬 3.7 이상
- ```Python hl_lines="80-83"
- {!> ../../../docs_src/security/tutorial003.py!}
- ```
+{* ../../docs_src/security/tutorial003.py hl[80:83] *}
-=== "파이썬 3.10 이상"
+////
- ```Python hl_lines="78-81"
- {!> ../../../docs_src/security/tutorial003_py310.py!}
- ```
+{* ../../docs_src/security/tutorial003_py310.py hl[78:81] *}
#### `**user_dict`에 대해
@@ -162,8 +150,11 @@ UserInDB(
)
```
-!!! 정보
- `**user_dict`에 대한 자세한 설명은 [**추가 모델** 문서](../extra-models.md#about-user_indict){.internal-link target=_blank}를 다시 읽어봅시다.
+/// info | 정보
+
+`**user_dict`에 대한 자세한 설명은 [**추가 모델** 문서](../extra-models.md#about-user_indict){.internal-link target=_blank}를 다시 읽어봅시다.
+
+///
## 토큰 반환하기
@@ -175,31 +166,27 @@ UserInDB(
이 간단한 예제에서는 완전히 안전하지 않고, 동일한 `username`을 토큰으로 반환합니다.
-!!! 팁
- 다음 장에서는 패스워드 해싱 및 JWT 토큰을 사용하여 실제 보안 구현을 볼 수 있습니다.
+/// tip | 팁
- 하지만 지금은 필요한 세부 정보에 집중하겠습니다.
+다음 장에서는 패스워드 해싱 및 JWT 토큰을 사용하여 실제 보안 구현을 볼 수 있습니다.
-=== "파이썬 3.7 이상"
+하지만 지금은 필요한 세부 정보에 집중하겠습니다.
- ```Python hl_lines="85"
- {!> ../../../docs_src/security/tutorial003.py!}
- ```
+///
-=== "파이썬 3.10 이상"
+{* ../../docs_src/security/tutorial003.py hl[85] *}
- ```Python hl_lines="83"
- {!> ../../../docs_src/security/tutorial003_py310.py!}
- ```
+/// tip | 팁
-!!! 팁
- 사양에 따라 이 예제와 동일하게 `access_token` 및 `token_type`이 포함된 JSON을 반환해야 합니다.
+사양에 따라 이 예제와 동일하게 `access_token` 및 `token_type`이 포함된 JSON을 반환해야 합니다.
- 이는 코드에서 직접 수행해야 하며 해당 JSON 키를 사용해야 합니다.
+이는 코드에서 직접 수행해야 하며 해당 JSON 키를 사용해야 합니다.
- 사양을 준수하기 위해 스스로 올바르게 수행하기 위해 거의 유일하게 기억해야 하는 것입니다.
+사양을 준수하기 위해 스스로 올바르게 수행하기 위해 거의 유일하게 기억해야 하는 것입니다.
- 나머지는 **FastAPI**가 처리합니다.
+나머지는 **FastAPI**가 처리합니다.
+
+///
## 의존성 업데이트하기
@@ -213,32 +200,25 @@ UserInDB(
따라서 엔드포인트에서는 사용자가 존재하고 올바르게 인증되었으며 활성 상태인 경우에만 사용자를 얻습니다:
-=== "파이썬 3.7 이상"
+{* ../../docs_src/security/tutorial003.py hl[58:66,69:72,90] *}
- ```Python hl_lines="58-66 69-72 90"
- {!> ../../../docs_src/security/tutorial003.py!}
- ```
+/// info | 정보
-=== "파이썬 3.10 이상"
+여기서 반환하는 값이 `Bearer`인 추가 헤더 `WWW-Authenticate`도 사양의 일부입니다.
- ```Python hl_lines="55-64 67-70 88"
- {!> ../../../docs_src/security/tutorial003_py310.py!}
- ```
+모든 HTTP(오류) 상태 코드 401 "UNAUTHORIZED"는 `WWW-Authenticate` 헤더도 반환해야 합니다.
-!!! 정보
- 여기서 반환하는 값이 `Bearer`인 추가 헤더 `WWW-Authenticate`도 사양의 일부입니다.
+베어러 토큰의 경우(지금의 경우) 해당 헤더의 값은 `Bearer`여야 합니다.
- 모든 HTTP(오류) 상태 코드 401 "UNAUTHORIZED"는 `WWW-Authenticate` 헤더도 반환해야 합니다.
+실제로 추가 헤더를 건너뛸 수 있으며 여전히 작동합니다.
- 베어러 토큰의 경우(지금의 경우) 해당 헤더의 값은 `Bearer`여야 합니다.
+그러나 여기에서는 사양을 준수하도록 제공됩니다.
- 실제로 추가 헤더를 건너뛸 수 있으며 여전히 작동합니다.
+또한 이를 예상하고 (현재 또는 미래에) 사용하는 도구가 있을 수 있으며, 현재 또는 미래에 자신 혹은 자신의 유저들에게 유용할 것입니다.
- 그러나 여기에서는 사양을 준수하도록 제공됩니다.
+그것이 표준의 이점입니다 ...
- 또한 이를 예상하고 (현재 또는 미래에) 사용하는 도구가 있을 수 있으며, 현재 또는 미래에 자신 혹은 자신의 유저들에게 유용할 것입니다.
-
- 그것이 표준의 이점입니다 ...
+///
## 확인하기
diff --git a/docs/ko/docs/tutorial/sql-databases.md b/docs/ko/docs/tutorial/sql-databases.md
new file mode 100644
index 000000000..58c7017d6
--- /dev/null
+++ b/docs/ko/docs/tutorial/sql-databases.md
@@ -0,0 +1,360 @@
+# SQL (관계형) 데이터베이스
+
+**FastAPI**에서 SQL(관계형) 데이터베이스 사용은 필수가 아닙니다. 여러분이 원하는 **어떤 데이터베이스든** 사용할 수 있습니다.
+
+여기서는 SQLModel을 사용하는 예제를 살펴보겠습니다.
+
+**SQLModel**은 SQLAlchemy와 Pydantic을 기반으로 구축되었습니다.SQLModel은 **SQL 데이터베이스**를 사용하는 FastAPI 애플리케이션에 완벽히 어울리도록 **FastAPI**의 제작자가 설계한 도구입니다.
+
+/// tip | 팁
+
+다른 SQL 또는 NoSQL 데이터베이스 라이브러리를 사용할 수도 있습니다 (일부는 "ORM"이라고도 불립니다), FastAPI는 특정 라이브러리의 사용을 강요하지 않습니다. 😎
+
+///
+
+SQLModel은 SQLAlchemy를 기반으로 하므로, SQLAlchemy에서 **지원하는 모든 데이터베이스**를 손쉽게 사용할 수 있습니다(SQLModel에서도 동일하게 지원됩니다). 예를 들면:
+
+* PostgreSQL
+* MySQL
+* SQLite
+* Oracle
+* Microsoft SQL Server 등.
+
+이 예제에서는 **SQLite**를 사용합니다. SQLite는 단일 파일을 사용하고 파이썬에서 기본적으로 지원하기 때문입니다. 따라서 이 예제를 그대로 복사하여 실행할 수 있습니다.
+
+나중에 실제 프로덕션 애플리케이션에서는 **PostgreSQL**과 같은 데이터베이스 서버를 사용하는 것이 좋습니다.
+
+/// tip | 팁
+
+**FastAPI**와 **PostgreSQL**를 포함하여 프론트엔드와 다양한 도구를 제공하는 공식 프로젝트 생성기가 있습니다: https://github.com/fastapi/full-stack-fastapi-template
+
+///
+
+이 튜토리얼은 매우 간단하고 짧습니다. 데이터베이스 기본 개념, SQL, 또는 더 복잡한 기능에 대해 배우고 싶다면, SQLModel 문서를 참고하세요.
+
+## `SQLModel` 설치하기
+
+먼저, [가상 환경](../virtual-environments.md){.internal-link target=_blank}을 생성하고 활성화한 다음, `sqlmodel`을 설치하세요:
+
+
+
++ FastAPI framework, zeer goede prestaties, eenvoudig te leren, snel te programmeren, klaar voor productie +
+ + +--- + +**Documentatie**: https://fastapi.tiangolo.com + +**Broncode**: https://github.com/tiangolo/fastapi + +--- + +FastAPI is een modern, snel (zeer goede prestaties), web framework voor het bouwen van API's in Python, gebruikmakend van standaard Python type-hints. + +De belangrijkste kenmerken zijn: + +* **Snel**: Zeer goede prestaties, vergelijkbaar met **NodeJS** en **Go** (dankzij Starlette en Pydantic). [Een van de snelste beschikbare Python frameworks](#prestaties). +* **Snel te programmeren**: Verhoog de snelheid om functionaliteit te ontwikkelen met ongeveer 200% tot 300%. * +* **Minder bugs**: Verminder ongeveer 40% van de door mensen (ontwikkelaars) veroorzaakte fouten. * +* **Intuïtief**: Buitengewoon goede ondersteuning voor editors. Overal automische code aanvulling. Minder tijd kwijt aan debuggen. +* **Eenvoudig**: Ontworpen om gemakkelijk te gebruiken en te leren. Minder tijd nodig om documentatie te lezen. +* **Kort**: Minimaliseer codeduplicatie. Elke parameterdeclaratie ondersteunt meerdere functionaliteiten. Minder bugs. +* **Robust**: Code gereed voor productie. Met automatische interactieve documentatie. +* **Standards-based**: Gebaseerd op (en volledig verenigbaar met) open standaarden voor API's: OpenAPI (voorheen bekend als Swagger) en JSON Schema. + +* schatting op basis van testen met een intern ontwikkelteam en bouwen van productieapplicaties. + +## Sponsors + + + +{% if sponsors %} +{% for sponsor in sponsors.gold -%} +async def...fastapi dev main.py...email_validator - voor email validatie.
+
+Gebruikt door Starlette:
+
+* httpx - Vereist indien je de `TestClient` wil gebruiken.
+* jinja2 - Vereist als je de standaard templateconfiguratie wil gebruiken.
+* python-multipart - Vereist indien je "parsen" van formulieren wil ondersteunen met `requests.form()`.
+
+Gebruikt door FastAPI / Starlette:
+
+* uvicorn - voor de server die jouw applicatie laadt en bedient.
+* `fastapi-cli` - om het `fastapi` commando te voorzien.
+
+### Zonder `standard` Afhankelijkheden
+
+Indien je de optionele `standard` afhankelijkheden niet wenst te installeren, kan je installeren met `pip install fastapi` in plaats van `pip install "fastapi[standard]"`.
+
+### Bijkomende Optionele Afhankelijkheden
+
+Er zijn nog een aantal bijkomende afhankelijkheden die je eventueel kan installeren.
+
+Bijkomende optionele afhankelijkheden voor Pydantic:
+
+* pydantic-settings - voor het beheren van settings.
+* pydantic-extra-types - voor extra data types die gebruikt kunnen worden met Pydantic.
+
+Bijkomende optionele afhankelijkheden voor FastAPI:
+
+* orjson - Vereist indien je `ORJSONResponse` wil gebruiken.
+* ujson - Vereist indien je `UJSONResponse` wil gebruiken.
+
+## Licentie
+
+Dit project is gelicenseerd onder de voorwaarden van de MIT licentie.
diff --git a/docs/nl/docs/python-types.md b/docs/nl/docs/python-types.md
new file mode 100644
index 000000000..fb8b1e5fd
--- /dev/null
+++ b/docs/nl/docs/python-types.md
@@ -0,0 +1,587 @@
+# Introductie tot Python Types
+
+Python biedt ondersteuning voor optionele "type hints" (ook wel "type annotaties" genoemd).
+
+Deze **"type hints"** of annotaties zijn een speciale syntax waarmee het type van een variabele kan worden gedeclareerd.
+
+Door types voor je variabelen te declareren, kunnen editors en hulpmiddelen je beter ondersteunen.
+
+Dit is slechts een **korte tutorial/opfrisser** over Python type hints. Het behandelt enkel het minimum dat nodig is om ze te gebruiken met **FastAPI**... en dat is relatief weinig.
+
+**FastAPI** is helemaal gebaseerd op deze type hints, ze geven veel voordelen.
+
+Maar zelfs als je **FastAPI** nooit gebruikt, heb je er baat bij om er iets over te leren.
+
+/// note
+
+Als je een Python expert bent en alles al weet over type hints, sla dan dit hoofdstuk over.
+
+///
+
+## Motivatie
+
+Laten we beginnen met een eenvoudig voorbeeld:
+
+{* ../../docs_src/python_types/tutorial001.py *}
+
+
+Het aanroepen van dit programma leidt tot het volgende resultaat:
+
+```
+John Doe
+```
+
+De functie voert het volgende uit:
+
+* Neem een `first_name` en een `last_name`
+* Converteer de eerste letter van elk naar een hoofdletter met `title()`.
+``
+* Voeg samen met een spatie in het midden.
+
+{* ../../docs_src/python_types/tutorial001.py hl[2] *}
+
+
+### Bewerk het
+
+Dit is een heel eenvoudig programma.
+
+Maar stel je nu voor dat je het vanaf nul zou moeten maken.
+
+Op een gegeven moment zou je aan de definitie van de functie zijn begonnen, je had de parameters klaar...
+
+Maar dan moet je “die methode die de eerste letter naar hoofdletters converteert” aanroepen.
+
+Was het `upper`? Was het `uppercase`? `first_uppercase`? `capitalize`?
+
+Dan roep je de hulp in van je oude programmeursvriend, (automatische) code aanvulling in je editor.
+
+Je typt de eerste parameter van de functie, `first_name`, dan een punt (`.`) en drukt dan op `Ctrl+Spatie` om de aanvulling te activeren.
+
+Maar helaas krijg je niets bruikbaars:
+
+
+
+### Types toevoegen
+
+Laten we een enkele regel uit de vorige versie aanpassen.
+
+We zullen precies dit fragment, de parameters van de functie, wijzigen van:
+
+```Python
+ first_name, last_name
+```
+
+naar:
+
+```Python
+ first_name: str, last_name: str
+```
+
+Dat is alles.
+
+Dat zijn de "type hints":
+
+{* ../../docs_src/python_types/tutorial002.py hl[1] *}
+
+
+Dit is niet hetzelfde als het declareren van standaardwaarden zoals bij:
+
+```Python
+ first_name="john", last_name="doe"
+```
+
+Het is iets anders.
+
+We gebruiken dubbele punten (`:`), geen gelijkheidstekens (`=`).
+
+Het toevoegen van type hints verandert normaal gesproken niet wat er gebeurt in je programma t.o.v. wat er zonder type hints zou gebeuren.
+
+Maar stel je voor dat je weer bezig bent met het maken van een functie, maar deze keer met type hints.
+
+Op hetzelfde moment probeer je de automatische aanvulling te activeren met `Ctrl+Spatie` en je ziet:
+
+
+
+Nu kun je de opties bekijken en er doorheen scrollen totdat je de optie vindt die “een belletje doet rinkelen”:
+
+
+
+### Meer motivatie
+
+Bekijk deze functie, deze heeft al type hints:
+
+{* ../../docs_src/python_types/tutorial003.py hl[1] *}
+
+
+Omdat de editor de types van de variabelen kent, krijgt u niet alleen aanvulling, maar ook controles op fouten:
+
+
+
+Nu weet je hoe je het moet oplossen, converteer `age` naar een string met `str(age)`:
+
+{* ../../docs_src/python_types/tutorial004.py hl[2] *}
+
+
+## Types declareren
+
+Je hebt net de belangrijkste plek om type hints te declareren gezien. Namelijk als functieparameters.
+
+Dit is ook de belangrijkste plek waar je ze gebruikt met **FastAPI**.
+
+### Eenvoudige types
+
+Je kunt alle standaard Python types declareren, niet alleen `str`.
+
+Je kunt bijvoorbeeld het volgende gebruiken:
+
+* `int`
+* `float`
+* `bool`
+* `bytes`
+
+{* ../../docs_src/python_types/tutorial005.py hl[1] *}
+
+
+### Generieke types met typeparameters
+
+Er zijn enkele datastructuren die andere waarden kunnen bevatten, zoals `dict`, `list`, `set` en `tuple` en waar ook de interne waarden hun eigen type kunnen hebben.
+
+Deze types die interne types hebben worden “**generieke**” types genoemd. Het is mogelijk om ze te declareren, zelfs met hun interne types.
+
+Om deze types en de interne types te declareren, kun je de standaard Python module `typing` gebruiken. Deze module is speciaal gemaakt om deze type hints te ondersteunen.
+
+#### Nieuwere versies van Python
+
+De syntax met `typing` is **verenigbaar** met alle versies, van Python 3.6 tot aan de nieuwste, inclusief Python 3.9, Python 3.10, enz.
+
+Naarmate Python zich ontwikkelt, worden **nieuwere versies**, met verbeterde ondersteuning voor deze type annotaties, beschikbaar. In veel gevallen hoef je niet eens de `typing` module te importeren en te gebruiken om de type annotaties te declareren.
+
+Als je een recentere versie van Python kunt kiezen voor je project, kun je profiteren van die extra eenvoud.
+
+In alle documentatie staan voorbeelden die compatibel zijn met elke versie van Python (als er een verschil is).
+
+Bijvoorbeeld “**Python 3.6+**” betekent dat het compatibel is met Python 3.6 of hoger (inclusief 3.7, 3.8, 3.9, 3.10, etc). En “**Python 3.9+**” betekent dat het compatibel is met Python 3.9 of hoger (inclusief 3.10, etc).
+
+Als je de **laatste versies van Python** kunt gebruiken, gebruik dan de voorbeelden voor de laatste versie, die hebben de **beste en eenvoudigste syntax**, bijvoorbeeld “**Python 3.10+**”.
+
+#### List
+
+Laten we bijvoorbeeld een variabele definiëren als een `list` van `str`.
+
+//// tab | Python 3.9+
+
+Declareer de variabele met dezelfde dubbele punt (`:`) syntax.
+
+Als type, vul `list` in.
+
+Doordat de list een type is dat enkele interne types bevat, zet je ze tussen vierkante haakjes:
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial006_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+Van `typing`, importeer `List` (met een hoofdletter `L`):
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial006.py!}
+```
+
+Declareer de variabele met dezelfde dubbele punt (`:`) syntax.
+
+Zet als type de `List` die je hebt geïmporteerd uit `typing`.
+
+Doordat de list een type is dat enkele interne types bevat, zet je ze tussen vierkante haakjes:
+
+```Python hl_lines="4"
+{!> ../../docs_src/python_types/tutorial006.py!}
+```
+
+////
+
+/// info
+
+De interne types tussen vierkante haakjes worden “typeparameters” genoemd.
+
+In dit geval is `str` de typeparameter die wordt doorgegeven aan `List` (of `list` in Python 3.9 en hoger).
+
+///
+
+Dat betekent: “de variabele `items` is een `list`, en elk van de items in deze list is een `str`”.
+
+/// tip
+
+Als je Python 3.9 of hoger gebruikt, hoef je `List` niet te importeren uit `typing`, je kunt in plaats daarvan hetzelfde reguliere `list` type gebruiken.
+
+///
+
+Door dat te doen, kan je editor ondersteuning bieden, zelfs tijdens het verwerken van items uit de list:
+
+
+
+Zonder types is dat bijna onmogelijk om te bereiken.
+
+Merk op dat de variabele `item` een van de elementen is in de lijst `items`.
+
+Toch weet de editor dat het een `str` is, en biedt daar vervolgens ondersteuning voor aan.
+
+#### Tuple en Set
+
+Je kunt hetzelfde doen om `tuple`s en `set`s te declareren:
+
+//// tab | Python 3.9+
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial007_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial007.py!}
+```
+
+////
+
+Dit betekent:
+
+* De variabele `items_t` is een `tuple` met 3 items, een `int`, nog een `int`, en een `str`.
+* De variabele `items_s` is een `set`, en elk van de items is van het type `bytes`.
+
+#### Dict
+
+Om een `dict` te definiëren, geef je 2 typeparameters door, gescheiden door komma's.
+
+De eerste typeparameter is voor de sleutels (keys) van de `dict`.
+
+De tweede typeparameter is voor de waarden (values) van het `dict`:
+
+//// tab | Python 3.9+
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial008.py!}
+```
+
+////
+
+Dit betekent:
+
+* De variabele `prices` is een `dict`:
+ * De sleutels van dit `dict` zijn van het type `str` (bijvoorbeeld de naam van elk item).
+ * De waarden van dit `dict` zijn van het type `float` (bijvoorbeeld de prijs van elk item).
+
+#### Union
+
+Je kunt een variable declareren die van **verschillende types** kan zijn, bijvoorbeeld een `int` of een `str`.
+
+In Python 3.6 en hoger (inclusief Python 3.10) kun je het `Union`-type van `typing` gebruiken en de mogelijke types die je wilt accepteren, tussen de vierkante haakjes zetten.
+
+In Python 3.10 is er ook een **nieuwe syntax** waarin je de mogelijke types kunt scheiden door een verticale balk (`|`).
+
+//// tab | Python 3.10+
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008b_py310.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial008b.py!}
+```
+
+////
+
+In beide gevallen betekent dit dat `item` een `int` of een `str` kan zijn.
+
+#### Mogelijk `None`
+
+Je kunt declareren dat een waarde een type kan hebben, zoals `str`, maar dat het ook `None` kan zijn.
+
+In Python 3.6 en hoger (inclusief Python 3.10) kun je het declareren door `Optional` te importeren en te gebruiken vanuit de `typing`-module.
+
+```Python hl_lines="1 4"
+{!../../docs_src/python_types/tutorial009.py!}
+```
+
+Door `Optional[str]` te gebruiken in plaats van alleen `str`, kan de editor je helpen fouten te detecteren waarbij je ervan uit zou kunnen gaan dat een waarde altijd een `str` is, terwijl het in werkelijkheid ook `None` zou kunnen zijn.
+
+`Optional[EenType]` is eigenlijk een snelkoppeling voor `Union[EenType, None]`, ze zijn equivalent.
+
+Dit betekent ook dat je in Python 3.10 `EenType | None` kunt gebruiken:
+
+//// tab | Python 3.10+
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial009_py310.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial009.py!}
+```
+
+////
+
+//// tab | Python 3.8+ alternative
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial009b.py!}
+```
+
+////
+
+#### Gebruik van `Union` of `Optional`
+
+Als je een Python versie lager dan 3.10 gebruikt, is dit een tip vanuit mijn **subjectieve** standpunt:
+
+* 🚨 Vermijd het gebruik van `Optional[EenType]`.
+* Gebruik in plaats daarvan **`Union[EenType, None]`** ✨.
+
+Beide zijn gelijkwaardig en onderliggend zijn ze hetzelfde, maar ik zou `Union` aanraden in plaats van `Optional` omdat het woord “**optional**” lijkt te impliceren dat de waarde optioneel is, en het eigenlijk betekent “het kan `None` zijn”, zelfs als het niet optioneel is en nog steeds vereist is.
+
+Ik denk dat `Union[SomeType, None]` explicieter is over wat het betekent.
+
+Het gaat alleen om de woorden en naamgeving. Maar die naamgeving kan invloed hebben op hoe jij en je teamgenoten over de code denken.
+
+Laten we als voorbeeld deze functie nemen:
+
+{* ../../docs_src/python_types/tutorial009c.py hl[1,4] *}
+
+
+De parameter `name` is gedefinieerd als `Optional[str]`, maar is **niet optioneel**, je kunt de functie niet aanroepen zonder de parameter:
+
+```Python
+say_hi() # Oh, nee, dit geeft een foutmelding! 😱
+```
+
+De `name` parameter is **nog steeds vereist** (niet *optioneel*) omdat het geen standaardwaarde heeft. Toch accepteert `name` `None` als waarde:
+
+```Python
+say_hi(name=None) # Dit werkt, None is geldig 🎉
+```
+
+Het goede nieuws is dat als je eenmaal Python 3.10 gebruikt, je je daar geen zorgen meer over hoeft te maken, omdat je dan gewoon `|` kunt gebruiken om unions van types te definiëren:
+
+{* ../../docs_src/python_types/tutorial009c_py310.py hl[1,4] *}
+
+
+Dan hoef je je geen zorgen te maken over namen als `Optional` en `Union`. 😎
+
+#### Generieke typen
+
+De types die typeparameters in vierkante haakjes gebruiken, worden **Generieke types** of **Generics** genoemd, bijvoorbeeld:
+
+//// tab | Python 3.10+
+
+Je kunt dezelfde ingebouwde types gebruiken als generics (met vierkante haakjes en types erin):
+
+* `list`
+* `tuple`
+* `set`
+* `dict`
+
+Hetzelfde als bij Python 3.8, uit de `typing`-module:
+
+* `Union`
+* `Optional` (hetzelfde als bij Python 3.8)
+* ...en anderen.
+
+In Python 3.10 kun je , als alternatief voor de generieke `Union` en `Optional`, de verticale lijn (`|`) gebruiken om unions van typen te voorzien, dat is veel beter en eenvoudiger.
+
+////
+
+//// tab | Python 3.9+
+
+Je kunt dezelfde ingebouwde types gebruiken als generieke types (met vierkante haakjes en types erin):
+
+* `list`
+* `tuple`
+* `set`
+* `dict`
+
+En hetzelfde als met Python 3.8, vanuit de `typing`-module:
+
+* `Union`
+* `Optional`
+* ...en anderen.
+
+////
+
+//// tab | Python 3.8+
+
+* `List`
+* `Tuple`
+* `Set`
+* `Dict`
+* `Union`
+* `Optional`
+* ...en anderen.
+
+////
+
+### Klassen als types
+
+Je kunt een klasse ook declareren als het type van een variabele.
+
+Stel dat je een klasse `Person` hebt, met een naam:
+
+{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
+
+
+Vervolgens kun je een variabele van het type `Persoon` declareren:
+
+{* ../../docs_src/python_types/tutorial010.py hl[6] *}
+
+
+Dan krijg je ook nog eens volledige editorondersteuning:
+
+
+
+Merk op dat dit betekent dat "`one_person` een **instantie** is van de klasse `Person`".
+
+Dit betekent niet dat `one_person` de **klasse** is met de naam `Person`.
+
+## Pydantic modellen
+
+Pydantic is een Python-pakket voor het uitvoeren van datavalidatie.
+
+Je declareert de "vorm" van de data als klassen met attributen.
+
+Elk attribuut heeft een type.
+
+Vervolgens maak je een instantie van die klasse met een aantal waarden en het valideert de waarden, converteert ze naar het juiste type (als dat het geval is) en geeft je een object met alle data terug.
+
+Daarnaast krijg je volledige editorondersteuning met dat resulterende object.
+
+Een voorbeeld uit de officiële Pydantic-documentatie:
+
+//// tab | Python 3.10+
+
+```Python
+{!> ../../docs_src/python_types/tutorial011_py310.py!}
+```
+
+////
+
+//// tab | Python 3.9+
+
+```Python
+{!> ../../docs_src/python_types/tutorial011_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python
+{!> ../../docs_src/python_types/tutorial011.py!}
+```
+
+////
+
+/// info
+
+Om meer te leren over Pydantic, bekijk de documentatie.
+
+///
+
+**FastAPI** is volledig gebaseerd op Pydantic.
+
+Je zult veel meer van dit alles in de praktijk zien in de [Tutorial - Gebruikershandleiding](tutorial/index.md){.internal-link target=_blank}.
+
+/// tip
+
+Pydantic heeft een speciaal gedrag wanneer je `Optional` of `Union[EenType, None]` gebruikt zonder een standaardwaarde, je kunt er meer over lezen in de Pydantic-documentatie over Verplichte optionele velden.
+
+///
+
+## Type Hints met Metadata Annotaties
+
+Python heeft ook een functie waarmee je **extra metadata** in deze type hints kunt toevoegen met behulp van `Annotated`.
+
+//// tab | Python 3.9+
+
+In Python 3.9 is `Annotated` onderdeel van de standaardpakket, dus je kunt het importeren vanuit `typing`.
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial013_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+In versies lager dan Python 3.9 importeer je `Annotated` vanuit `typing_extensions`.
+
+Het wordt al geïnstalleerd met **FastAPI**.
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial013.py!}
+```
+
+////
+
+Python zelf doet niets met deze `Annotated` en voor editors en andere hulpmiddelen is het type nog steeds een `str`.
+
+Maar je kunt deze ruimte in `Annotated` gebruiken om **FastAPI** te voorzien van extra metadata over hoe je wilt dat je applicatie zich gedraagt.
+
+Het belangrijkste om te onthouden is dat **de eerste *typeparameter*** die je doorgeeft aan `Annotated` het **werkelijke type** is. De rest is gewoon metadata voor andere hulpmiddelen.
+
+Voor nu hoef je alleen te weten dat `Annotated` bestaat en dat het standaard Python is. 😎
+
+Later zul je zien hoe **krachtig** het kan zijn.
+
+/// tip
+
+Het feit dat dit **standaard Python** is, betekent dat je nog steeds de **best mogelijke ontwikkelaarservaring** krijgt in je editor, met de hulpmiddelen die je gebruikt om je code te analyseren en te refactoren, enz. ✨
+
+Daarnaast betekent het ook dat je code zeer verenigbaar zal zijn met veel andere Python-hulpmiddelen en -pakketten. 🚀
+
+///
+
+## Type hints in **FastAPI**
+
+**FastAPI** maakt gebruik van type hints om verschillende dingen te doen.
+
+Met **FastAPI** declareer je parameters met type hints en krijg je:
+
+* **Editor ondersteuning**.
+* **Type checks**.
+
+...en **FastAPI** gebruikt dezelfde declaraties om:
+
+* **Vereisten te definïeren **: van request pad parameters, query parameters, headers, bodies, dependencies, enz.
+* **Data te converteren**: van de request naar het vereiste type.
+* **Data te valideren**: afkomstig van elke request:
+ * **Automatische foutmeldingen** te genereren die naar de client worden geretourneerd wanneer de data ongeldig is.
+* De API met OpenAPI te **documenteren**:
+ * die vervolgens wordt gebruikt door de automatische interactieve documentatie gebruikersinterfaces.
+
+Dit klinkt misschien allemaal abstract. Maak je geen zorgen. Je ziet dit allemaal in actie in de [Tutorial - Gebruikershandleiding](tutorial/index.md){.internal-link target=_blank}.
+
+Het belangrijkste is dat door standaard Python types te gebruiken, op één plek (in plaats van meer klassen, decorators, enz. toe te voegen), **FastAPI** een groot deel van het werk voor je doet.
+
+/// info
+
+Als je de hele tutorial al hebt doorgenomen en terug bent gekomen om meer te weten te komen over types, is een goede bron het "cheat sheet" van `mypy`.
+
+///
diff --git a/docs/nl/mkdocs.yml b/docs/nl/mkdocs.yml
new file mode 100644
index 000000000..de18856f4
--- /dev/null
+++ b/docs/nl/mkdocs.yml
@@ -0,0 +1 @@
+INHERIT: ../en/mkdocs.yml
diff --git a/docs/pl/docs/fastapi-people.md b/docs/pl/docs/fastapi-people.md
deleted file mode 100644
index 6c431b401..000000000
--- a/docs/pl/docs/fastapi-people.md
+++ /dev/null
@@ -1,178 +0,0 @@
-# Ludzie FastAPI
-
-FastAPI posiada wspaniałą społeczność, która jest otwarta dla ludzi z każdego środowiska.
-
-## Twórca - Opienik
-
-Cześć! 👋
-
-To ja:
-
-{% if people %}
-email_validator - dla walidacji adresów email.
+* email-validator - dla walidacji adresów email.
Używane przez Starlette:
diff --git a/docs/pl/docs/tutorial/first-steps.md b/docs/pl/docs/tutorial/first-steps.md
index ce71f8b83..8fa4c75ad 100644
--- a/docs/pl/docs/tutorial/first-steps.md
+++ b/docs/pl/docs/tutorial/first-steps.md
@@ -2,9 +2,7 @@
Najprostszy plik FastAPI może wyglądać tak:
-```Python
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py *}
Skopiuj to do pliku `main.py`.
@@ -24,12 +22,15 @@ $ uvicorn main:app --reload
-!!! note
- Polecenie `uvicorn main:app` odnosi się do:
+/// note
- * `main`: plik `main.py` ("moduł" Python).
- * `app`: obiekt utworzony w pliku `main.py` w lini `app = FastAPI()`.
- * `--reload`: sprawia, że serwer uruchamia się ponownie po zmianie kodu. Używany tylko w trakcie tworzenia oprogramowania.
+Polecenie `uvicorn main:app` odnosi się do:
+
+* `main`: plik `main.py` ("moduł" Python).
+* `app`: obiekt utworzony w pliku `main.py` w lini `app = FastAPI()`.
+* `--reload`: sprawia, że serwer uruchamia się ponownie po zmianie kodu. Używany tylko w trakcie tworzenia oprogramowania.
+
+///
Na wyjściu znajduje się linia z czymś w rodzaju:
@@ -130,23 +131,21 @@ Możesz go również użyć do automatycznego generowania kodu dla klientów, kt
### Krok 1: zaimportuj `FastAPI`
-```Python hl_lines="1"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[1] *}
`FastAPI` jest klasą, która zapewnia wszystkie funkcjonalności Twojego API.
-!!! note "Szczegóły techniczne"
- `FastAPI` jest klasą, która dziedziczy bezpośrednio z `Starlette`.
+/// note | Szczegóły techniczne
- Oznacza to, że możesz korzystać ze wszystkich funkcjonalności Starlette również w `FastAPI`.
+`FastAPI` jest klasą, która dziedziczy bezpośrednio z `Starlette`.
+Oznacza to, że możesz korzystać ze wszystkich funkcjonalności Starlette również w `FastAPI`.
+
+///
### Krok 2: utwórz instancję `FastAPI`
-```Python hl_lines="3"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{*../../docs_src/first_steps/tutorial001.py hl[3] *}
Zmienna `app` będzie tutaj "instancją" klasy `FastAPI`.
@@ -166,9 +165,7 @@ $ uvicorn main:app --reload
Jeśli stworzysz swoją aplikację, np.:
-```Python hl_lines="3"
-{!../../../docs_src/first_steps/tutorial002.py!}
-```
+{* ../../docs_src/first_steps/tutorial002.py hl[3] *}
I umieścisz to w pliku `main.py`, to będziesz mógł tak wywołać `uvicorn`:
@@ -200,8 +197,11 @@ https://example.com/items/foo
/items/foo
```
-!!! info
- "Ścieżka" jest zazwyczaj nazywana "path", "endpoint" lub "route'.
+/// info
+
+"Ścieżka" jest zazwyczaj nazywana "path", "endpoint" lub "route'.
+
+///
Podczas budowania API, "ścieżka" jest głównym sposobem na oddzielenie "odpowiedzialności" i „zasobów”.
@@ -242,25 +242,26 @@ Będziemy je również nazywali "**operacjami**".
#### Zdefiniuj *dekorator operacji na ścieżce*
-```Python hl_lines="6"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[6] *}
`@app.get("/")` mówi **FastAPI** że funkcja poniżej odpowiada za obsługę żądań, które trafiają do:
* ścieżki `/`
* używając operacji get
-!!! info "`@decorator` Info"
- Składnia `@something` jest w Pythonie nazywana "dekoratorem".
+/// info | `@decorator` Info
- Umieszczasz to na szczycie funkcji. Jak ładną ozdobną czapkę (chyba stąd wzięła się nazwa).
+Składnia `@something` jest w Pythonie nazywana "dekoratorem".
- "Dekorator" przyjmuje funkcję znajdującą się poniżej jego i coś z nią robi.
+Umieszczasz to na szczycie funkcji. Jak ładną ozdobną czapkę (chyba stąd wzięła się nazwa).
- W naszym przypadku dekorator mówi **FastAPI**, że poniższa funkcja odpowiada **ścieżce** `/` z **operacją** `get`.
+"Dekorator" przyjmuje funkcję znajdującą się poniżej jego i coś z nią robi.
- Jest to "**dekorator operacji na ścieżce**".
+W naszym przypadku dekorator mówi **FastAPI**, że poniższa funkcja odpowiada **ścieżce** `/` z **operacją** `get`.
+
+Jest to "**dekorator operacji na ścieżce**".
+
+///
Możesz również użyć innej operacji:
@@ -275,14 +276,17 @@ Oraz tych bardziej egzotycznych:
* `@app.patch()`
* `@app.trace()`
-!!! tip
- Możesz dowolnie używać każdej operacji (metody HTTP).
+/// tip
- **FastAPI** nie narzuca żadnego konkretnego znaczenia.
+Możesz dowolnie używać każdej operacji (metody HTTP).
- Informacje tutaj są przedstawione jako wskazówka, a nie wymóg.
+**FastAPI** nie narzuca żadnego konkretnego znaczenia.
- Na przykład, używając GraphQL, normalnie wykonujesz wszystkie akcje używając tylko operacji `POST`.
+Informacje tutaj są przedstawione jako wskazówka, a nie wymóg.
+
+Na przykład, używając GraphQL, normalnie wykonujesz wszystkie akcje używając tylko operacji `POST`.
+
+///
### Krok 4: zdefiniuj **funkcję obsługującą ścieżkę**
@@ -292,9 +296,7 @@ To jest nasza "**funkcja obsługująca ścieżkę**":
* **operacja**: to `get`.
* **funkcja**: to funkcja poniżej "dekoratora" (poniżej `@app.get("/")`).
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[7] *}
Jest to funkcja Python.
@@ -306,18 +308,17 @@ W tym przypadku jest to funkcja "asynchroniczna".
Możesz również zdefiniować to jako normalną funkcję zamiast `async def`:
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial003.py!}
-```
+{* ../../docs_src/first_steps/tutorial003.py hl[7] *}
-!!! note
- Jeśli nie znasz różnicy, sprawdź [Async: *"In a hurry?"*](../async.md#in-a-hurry){.internal-link target=_blank}.
+/// note
+
+Jeśli nie znasz różnicy, sprawdź [Async: *"In a hurry?"*](../async.md#in-a-hurry){.internal-link target=_blank}.
+
+///
### Krok 5: zwróć zawartość
-```Python hl_lines="8"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[8] *}
Możesz zwrócić `dict`, `list`, pojedynczą wartość jako `str`, `int`, itp.
diff --git a/docs/pl/docs/tutorial/index.md b/docs/pl/docs/tutorial/index.md
index f8c5c6022..66f7c6d62 100644
--- a/docs/pl/docs/tutorial/index.md
+++ b/docs/pl/docs/tutorial/index.md
@@ -52,22 +52,25 @@ $ pip install "fastapi[all]"
...wliczając w to `uvicorn`, który będzie służył jako serwer wykonujacy Twój kod.
-!!! note
- Możesz również wykonać instalację "krok po kroku".
+/// note
- Prawdopodobnie zechcesz to zrobić, kiedy będziesz wdrażać swoją aplikację w środowisku produkcyjnym:
+Możesz również wykonać instalację "krok po kroku".
- ```
- pip install fastapi
- ```
+Prawdopodobnie zechcesz to zrobić, kiedy będziesz wdrażać swoją aplikację w środowisku produkcyjnym:
- Zainstaluj też `uvicorn`, który będzie służył jako serwer:
+```
+pip install fastapi
+```
- ```
- pip install "uvicorn[standard]"
- ```
+Zainstaluj też `uvicorn`, który będzie służył jako serwer:
- Tak samo możesz zainstalować wszystkie dodatkowe biblioteki, których chcesz użyć.
+```
+pip install "uvicorn[standard]"
+```
+
+Tak samo możesz zainstalować wszystkie dodatkowe biblioteki, których chcesz użyć.
+
+///
## Zaawansowany poradnik
diff --git a/docs/pt/docs/advanced/additional-responses.md b/docs/pt/docs/advanced/additional-responses.md
index 7c7d22611..1060d18af 100644
--- a/docs/pt/docs/advanced/additional-responses.md
+++ b/docs/pt/docs/advanced/additional-responses.md
@@ -1,9 +1,12 @@
# Retornos Adicionais no OpenAPI
-!!! warning "Aviso"
- Este é um tema bem avançado.
+/// warning | Aviso
- Se você está começando com o **FastAPI**, provavelmente você não precisa disso.
+Este é um tema bem avançado.
+
+Se você está começando com o **FastAPI**, provavelmente você não precisa disso.
+
+///
Você pode declarar retornos adicionais, com códigos de status adicionais, media types, descrições, etc.
@@ -23,24 +26,28 @@ O **FastAPI** pegará este modelo, gerará o esquema JSON dele e incluirá no lo
Por exemplo, para declarar um outro retorno com o status code `404` e um modelo do Pydantic chamado `Message`, você pode escrever:
-```Python hl_lines="18 22"
-{!../../../docs_src/additional_responses/tutorial001.py!}
-```
+{* ../../docs_src/additional_responses/tutorial001.py hl[18,22] *}
-!!! note "Nota"
- Lembre-se que você deve retornar o `JSONResponse` diretamente.
+/// note | Nota
-!!! info "Informação"
- A chave `model` não é parte do OpenAPI.
+Lembre-se que você deve retornar o `JSONResponse` diretamente.
- O **FastAPI** pegará o modelo do Pydantic, gerará o `JSON Schema`, e adicionará no local correto.
+///
- O local correto é:
+/// info | Informação
- * Na chave `content`, que tem como valor um outro objeto JSON (`dict`) que contém:
- * Uma chave com o media type, como por exemplo `application/json`, que contém como valor um outro objeto JSON, contendo::
- * Uma chave `schema`, que contém como valor o JSON Schema do modelo, sendo este o local correto.
- * O **FastAPI** adiciona aqui a referência dos esquemas JSON globais que estão localizados em outro lugar, ao invés de incluí-lo diretamente. Deste modo, outras aplicações e clientes podem utilizar estes esquemas JSON diretamente, fornecer melhores ferramentas de geração de código, etc.
+A chave `model` não é parte do OpenAPI.
+
+O **FastAPI** pegará o modelo do Pydantic, gerará o `JSON Schema`, e adicionará no local correto.
+
+O local correto é:
+
+* Na chave `content`, que tem como valor um outro objeto JSON (`dict`) que contém:
+ * Uma chave com o media type, como por exemplo `application/json`, que contém como valor um outro objeto JSON, contendo::
+ * Uma chave `schema`, que contém como valor o JSON Schema do modelo, sendo este o local correto.
+ * O **FastAPI** adiciona aqui a referência dos esquemas JSON globais que estão localizados em outro lugar, ao invés de incluí-lo diretamente. Deste modo, outras aplicações e clientes podem utilizar estes esquemas JSON diretamente, fornecer melhores ferramentas de geração de código, etc.
+
+///
O retorno gerado no OpenAI para esta *operação de caminho* será:
@@ -168,17 +175,21 @@ Você pode utilizar o mesmo parâmetro `responses` para adicionar diferentes med
Por exemplo, você pode adicionar um media type adicional de `image/png`, declarando que a sua *operação de caminho* pode retornar um objeto JSON (com o media type `application/json`) ou uma imagem PNG:
-```Python hl_lines="19-24 28"
-{!../../../docs_src/additional_responses/tutorial002.py!}
-```
+{* ../../docs_src/additional_responses/tutorial002.py hl[19:24,28] *}
-!!! note "Nota"
- Note que você deve retornar a imagem utilizando um `FileResponse` diretamente.
+/// note | Nota
-!!! info "Informação"
- A menos que você especifique um media type diferente explicitamente em seu parâmetro `responses`, o FastAPI assumirá que o retorno possui o mesmo media type contido na classe principal de retorno (padrão `application/json`).
+Note que você deve retornar a imagem utilizando um `FileResponse` diretamente.
- Porém se você especificou uma classe de retorno com o valor `None` como media type, o FastAPI utilizará `application/json` para qualquer retorno adicional que possui um modelo associado.
+///
+
+/// info | Informação
+
+A menos que você especifique um media type diferente explicitamente em seu parâmetro `responses`, o FastAPI assumirá que o retorno possui o mesmo media type contido na classe principal de retorno (padrão `application/json`).
+
+Porém se você especificou uma classe de retorno com o valor `None` como media type, o FastAPI utilizará `application/json` para qualquer retorno adicional que possui um modelo associado.
+
+///
## Combinando informações
@@ -192,9 +203,7 @@ Por exemplo, você pode declarar um retorno com o código de status `404` que ut
E um retorno com o código de status `200` que utiliza o seu `response_model`, porém inclui um `example` customizado:
-```Python hl_lines="20-31"
-{!../../../docs_src/additional_responses/tutorial003.py!}
-```
+{* ../../docs_src/additional_responses/tutorial003.py hl[20:31] *}
Isso será combinado e incluído em seu OpenAPI, e disponibilizado na documentação da sua API:
@@ -228,9 +237,7 @@ Você pode utilizar essa técnica para reutilizar alguns retornos predefinidos n
Por exemplo:
-```Python hl_lines="13-17 26"
-{!../../../docs_src/additional_responses/tutorial004.py!}
-```
+{* ../../docs_src/additional_responses/tutorial004.py hl[13:17,26] *}
## Mais informações sobre retornos OpenAPI
diff --git a/docs/pt/docs/advanced/additional-status-codes.md b/docs/pt/docs/advanced/additional-status-codes.md
index a7699b324..06d619151 100644
--- a/docs/pt/docs/advanced/additional-status-codes.md
+++ b/docs/pt/docs/advanced/additional-status-codes.md
@@ -14,53 +14,25 @@ Mas você também deseja aceitar novos itens. E quando os itens não existiam, e
Para conseguir isso, importe `JSONResponse` e retorne o seu conteúdo diretamente, definindo o `status_code` que você deseja:
-=== "Python 3.10+"
+{* ../../docs_src/additional_status_codes/tutorial001_an_py310.py hl[4,25] *}
- ```Python hl_lines="4 25"
- {!> ../../../docs_src/additional_status_codes/tutorial001_an_py310.py!}
- ```
+/// warning | Aviso
-=== "Python 3.9+"
+Quando você retorna um `Response` diretamente, como no exemplo acima, ele será retornado diretamente.
- ```Python hl_lines="4 25"
- {!> ../../../docs_src/additional_status_codes/tutorial001_an_py39.py!}
- ```
+Ele não será serializado com um modelo, etc.
-=== "Python 3.8+"
+Garanta que ele tenha toda informação que você deseja, e que os valores sejam um JSON válido (caso você esteja usando `JSONResponse`).
- ```Python hl_lines="4 26"
- {!> ../../../docs_src/additional_status_codes/tutorial001_an.py!}
- ```
+///
-=== "Python 3.10+ non-Annotated"
+/// note | Detalhes técnicos
- !!! tip "Dica"
- Faça uso da versão `Annotated` quando possível.
+Você também pode utilizar `from starlette.responses import JSONResponse`.
- ```Python hl_lines="2 23"
- {!> ../../../docs_src/additional_status_codes/tutorial001_py310.py!}
- ```
+O **FastAPI** disponibiliza o `starlette.responses` como `fastapi.responses` apenas por conveniência para você, o programador. Porém a maioria dos retornos disponíveis vem diretamente do Starlette. O mesmo com `status`.
-=== "Python 3.8+ non-Annotated"
-
- !!! tip "Dica"
- Faça uso da versão `Annotated` quando possível.
-
- ```Python hl_lines="4 25"
- {!> ../../../docs_src/additional_status_codes/tutorial001.py!}
- ```
-
-!!! warning "Aviso"
- Quando você retorna um `Response` diretamente, como no exemplo acima, ele será retornado diretamente.
-
- Ele não será serializado com um modelo, etc.
-
- Garanta que ele tenha toda informação que você deseja, e que os valores sejam um JSON válido (caso você esteja usando `JSONResponse`).
-
-!!! note "Detalhes técnicos"
- Você também pode utilizar `from starlette.responses import JSONResponse`.
-
- O **FastAPI** disponibiliza o `starlette.responses` como `fastapi.responses` apenas por conveniência para você, o programador. Porém a maioria dos retornos disponíveis vem diretamente do Starlette. O mesmo com `status`.
+///
## OpenAPI e documentação da API
diff --git a/docs/pt/docs/advanced/advanced-dependencies.md b/docs/pt/docs/advanced/advanced-dependencies.md
index 58887f9c8..f57abba61 100644
--- a/docs/pt/docs/advanced/advanced-dependencies.md
+++ b/docs/pt/docs/advanced/advanced-dependencies.md
@@ -18,26 +18,7 @@ Não propriamente a classe (que já é um chamável), mas a instância desta cla
Para fazer isso, nós declaramos o método `__call__`:
-=== "Python 3.9+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/dependencies/tutorial011_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/dependencies/tutorial011_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip "Dica"
- Prefira utilizar a versão `Annotated` se possível.
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/dependencies/tutorial011.py!}
- ```
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[12] *}
Neste caso, o `__call__` é o que o **FastAPI** utilizará para verificar parâmetros adicionais e sub dependências, e isso é o que será chamado para passar o valor ao parâmetro na sua *função de operação de rota* posteriormente.
@@ -45,26 +26,7 @@ Neste caso, o `__call__` é o que o **FastAPI** utilizará para verificar parâm
E agora, nós podemos utilizar o `__init__` para declarar os parâmetros da instância que podemos utilizar para "parametrizar" a dependência:
-=== "Python 3.9+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/dependencies/tutorial011_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/dependencies/tutorial011_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip "Dica"
- Prefira utilizar a versão `Annotated` se possível.
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/dependencies/tutorial011.py!}
- ```
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[9] *}
Neste caso, o **FastAPI** nunca tocará ou se importará com o `__init__`, nós vamos utilizar diretamente em nosso código.
@@ -72,26 +34,7 @@ Neste caso, o **FastAPI** nunca tocará ou se importará com o `__init__`, nós
Nós poderíamos criar uma instância desta classe com:
-=== "Python 3.9+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/dependencies/tutorial011_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="17"
- {!> ../../../docs_src/dependencies/tutorial011_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip "Dica"
- Prefira utilizar a versão `Annotated` se possível.
-
- ```Python hl_lines="16"
- {!> ../../../docs_src/dependencies/tutorial011.py!}
- ```
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[18] *}
E deste modo nós podemos "parametrizar" a nossa dependência, que agora possui `"bar"` dentro dele, como o atributo `checker.fixed_content`.
@@ -107,32 +50,16 @@ checker(q="somequery")
...e passar o que quer que isso retorne como valor da dependência em nossa *função de operação de rota* como o parâmetro `fixed_content_included`:
-=== "Python 3.9+"
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[22] *}
- ```Python hl_lines="22"
- {!> ../../../docs_src/dependencies/tutorial011_an_py39.py!}
- ```
+/// tip | Dica
-=== "Python 3.8+"
+Tudo isso parece não ser natural. E pode não estar muito claro ou aparentar ser útil ainda.
- ```Python hl_lines="21"
- {!> ../../../docs_src/dependencies/tutorial011_an.py!}
- ```
+Estes exemplos são intencionalmente simples, porém mostram como tudo funciona.
-=== "Python 3.8+ non-Annotated"
+Nos capítulos sobre segurança, existem funções utilitárias que são implementadas desta maneira.
- !!! tip "Dica"
- Prefira utilizar a versão `Annotated` se possível.
+Se você entendeu tudo isso, você já sabe como essas funções utilitárias para segurança funcionam por debaixo dos panos.
- ```Python hl_lines="20"
- {!> ../../../docs_src/dependencies/tutorial011.py!}
- ```
-
-!!! tip "Dica"
- Tudo isso parece não ser natural. E pode não estar muito claro ou aparentar ser útil ainda.
-
- Estes exemplos são intencionalmente simples, porém mostram como tudo funciona.
-
- Nos capítulos sobre segurança, existem funções utilitárias que são implementadas desta maneira.
-
- Se você entendeu tudo isso, você já sabe como essas funções utilitárias para segurança funcionam por debaixo dos panos.
+///
diff --git a/docs/pt/docs/advanced/async-tests.md b/docs/pt/docs/advanced/async-tests.md
index 4ccc0c452..a2b79426c 100644
--- a/docs/pt/docs/advanced/async-tests.md
+++ b/docs/pt/docs/advanced/async-tests.md
@@ -32,15 +32,11 @@ Para um exemplos simples, vamos considerar uma estrutura de arquivos semelhante
O arquivo `main.py` teria:
-```Python
-{!../../../docs_src/async_tests/main.py!}
-```
+{* ../../docs_src/async_tests/main.py *}
O arquivo `test_main.py` teria os testes para para o arquivo `main.py`, ele poderia ficar assim:
-```Python
-{!../../../docs_src/async_tests/test_main.py!}
-```
+{* ../../docs_src/async_tests/test_main.py *}
## Executá-lo
@@ -60,18 +56,17 @@ $ pytest
O marcador `@pytest.mark.anyio` informa ao pytest que esta função de teste deve ser invocada de maneira assíncrona:
-```Python hl_lines="7"
-{!../../../docs_src/async_tests/test_main.py!}
-```
+{* ../../docs_src/async_tests/test_main.py hl[7] *}
-!!! tip "Dica"
- Note que a função de teste é `async def` agora, no lugar de apenas `def` como quando estávamos utilizando o `TestClient` anteriormente.
+/// tip | Dica
+
+Note que a função de teste é `async def` agora, no lugar de apenas `def` como quando estávamos utilizando o `TestClient` anteriormente.
+
+///
Então podemos criar um `AsyncClient` com a aplicação, e enviar requisições assíncronas para ela utilizando `await`.
-```Python hl_lines="9-10"
-{!../../../docs_src/async_tests/test_main.py!}
-```
+{* ../../docs_src/async_tests/test_main.py hl[9:12] *}
Isso é equivalente a:
@@ -81,15 +76,24 @@ response = client.get('/')
...que nós utilizamos para fazer as nossas requisições utilizando o `TestClient`.
-!!! tip "Dica"
- Note que nós estamos utilizando async/await com o novo `AsyncClient` - a requisição é assíncrona.
+/// tip | Dica
-!!! warning "Aviso"
- Se a sua aplicação depende dos eventos de vida útil (*lifespan*), o `AsyncClient` não acionará estes eventos. Para garantir que eles são acionados, utilize o `LifespanManager` do florimondmanca/asgi-lifespan.
+Note que nós estamos utilizando async/await com o novo `AsyncClient` - a requisição é assíncrona.
+
+///
+
+/// warning | Aviso
+
+Se a sua aplicação depende dos eventos de vida útil (*lifespan*), o `AsyncClient` não acionará estes eventos. Para garantir que eles são acionados, utilize o `LifespanManager` do florimondmanca/asgi-lifespan.
+
+///
## Outras Chamadas de Funções Assíncronas
Como a função de teste agora é assíncrona, você pode chamar (e `esperar`) outras funções `async` além de enviar requisições para a sua aplicação FastAPI em seus testes, exatamente como você as chamaria em qualquer outro lugar do seu código.
-!!! tip "Dica"
- Se você se deparar com um `RuntimeError: Task attached to a different loop` ao integrar funções assíncronas em seus testes (e.g. ao utilizar o MotorClient do MongoDB) Lembre-se de instanciar objetos que precisam de um loop de eventos (*event loop*) apenas em funções assíncronas, e.g. um *"callback"* `'@app.on_event("startup")`.
+/// tip | Dica
+
+Se você se deparar com um `RuntimeError: Task attached to a different loop` ao integrar funções assíncronas em seus testes (e.g. ao utilizar o MotorClient do MongoDB) Lembre-se de instanciar objetos que precisam de um loop de eventos (*event loop*) apenas em funções assíncronas, e.g. um *"callback"* `'@app.on_event("startup")`.
+
+///
diff --git a/docs/pt/docs/advanced/behind-a-proxy.md b/docs/pt/docs/advanced/behind-a-proxy.md
new file mode 100644
index 000000000..6837c9542
--- /dev/null
+++ b/docs/pt/docs/advanced/behind-a-proxy.md
@@ -0,0 +1,361 @@
+# Atrás de um Proxy
+
+Em algumas situações, você pode precisar usar um servidor **proxy** como Traefik ou Nginx com uma configuração que adiciona um prefixo de caminho extra que não é visto pela sua aplicação.
+
+Nesses casos, você pode usar `root_path` para configurar sua aplicação.
+
+O `root_path` é um mecanismo fornecido pela especificação ASGI (que o FastAPI utiliza, através do Starlette).
+
+O `root_path` é usado para lidar com esses casos específicos.
+
+E também é usado internamente ao montar sub-aplicações.
+
+## Proxy com um prefixo de caminho removido
+
+Ter um proxy com um prefixo de caminho removido, nesse caso, significa que você poderia declarar um caminho em `/app` no seu código, mas então, você adiciona uma camada no topo (o proxy) que colocaria sua aplicação **FastAPI** sob um caminho como `/api/v1`.
+
+Nesse caso, o caminho original `/app` seria servido em `/api/v1/app`.
+
+Embora todo o seu código esteja escrito assumindo que existe apenas `/app`.
+
+{* ../../docs_src/behind_a_proxy/tutorial001.py hl[6] *}
+
+E o proxy estaria **"removendo"** o **prefixo do caminho** dinamicamente antes de transmitir a solicitação para o servidor da aplicação (provavelmente Uvicorn via CLI do FastAPI), mantendo sua aplicação convencida de que está sendo servida em `/app`, para que você não precise atualizar todo o seu código para incluir o prefixo `/api/v1`.
+
+Até aqui, tudo funcionaria normalmente.
+
+Mas então, quando você abre a interface de documentação integrada (o frontend), ele esperaria obter o OpenAPI schema em `/openapi.json`, em vez de `/api/v1/openapi.json`.
+
+Então, o frontend (que roda no navegador) tentaria acessar `/openapi.json` e não conseguiria obter o OpenAPI schema.
+
+Como temos um proxy com um prefixo de caminho de `/api/v1` para nossa aplicação, o frontend precisa buscar o OpenAPI schema em `/api/v1/openapi.json`.
+
+```mermaid
+graph LR
+
+browser("Browser")
+proxy["Proxy on http://0.0.0.0:9999/api/v1/app"]
+server["Server on http://127.0.0.1:8000/app"]
+
+browser --> proxy
+proxy --> server
+```
+
+/// tip | Dica
+
+O IP `0.0.0.0` é comumente usado para significar que o programa escuta em todos os IPs disponíveis naquela máquina/servidor.
+
+///
+
+A interface de documentação também precisaria do OpenAPI schema para declarar que API `server` está localizado em `/api/v1` (atrás do proxy). Por exemplo:
+
+```JSON hl_lines="4-8"
+{
+ "openapi": "3.1.0",
+ // Mais coisas aqui
+ "servers": [
+ {
+ "url": "/api/v1"
+ }
+ ],
+ "paths": {
+ // Mais coisas aqui
+ }
+}
+```
+
+Neste exemplo, o "Proxy" poderia ser algo como **Traefik**. E o servidor seria algo como CLI do FastAPI com **Uvicorn**, executando sua aplicação FastAPI.
+
+### Fornecendo o `root_path`
+
+Para conseguir isso, você pode usar a opção de linha de comando `--root-path` assim:
+
+
+
+Mas se acessarmos a interface de documentação no URL "oficial" usando o proxy com a porta `9999`, em `/api/v1/docs`, ela funciona corretamente! 🎉
+
+Você pode verificar em http://127.0.0.1:9999/api/v1/docs:
+
+
+
+Exatamente como queríamos. ✔️
+
+Isso porque o FastAPI usa esse `root_path` para criar o `server` padrão no OpenAPI com o URL fornecido pelo `root_path`.
+
+## Servidores adicionais
+
+/// warning | Aviso
+
+Este é um caso de uso mais avançado. Sinta-se à vontade para pular.
+
+///
+
+Por padrão, o **FastAPI** criará um `server` no OpenAPI schema com o URL para o `root_path`.
+
+Mas você também pode fornecer outros `servers` alternativos, por exemplo, se quiser que a *mesma* interface de documentação interaja com ambientes de staging e produção.
+
+Se você passar uma lista personalizada de `servers` e houver um `root_path` (porque sua API está atrás de um proxy), o **FastAPI** inserirá um "server" com esse `root_path` no início da lista.
+
+Por exemplo:
+
+{* ../../docs_src/behind_a_proxy/tutorial003.py hl[4:7] *}
+
+Gerará um OpenAPI schema como:
+
+```JSON hl_lines="5-7"
+{
+ "openapi": "3.1.0",
+ // Mais coisas aqui
+ "servers": [
+ {
+ "url": "/api/v1"
+ },
+ {
+ "url": "https://stag.example.com",
+ "description": "Staging environment"
+ },
+ {
+ "url": "https://prod.example.com",
+ "description": "Production environment"
+ }
+ ],
+ "paths": {
+ // Mais coisas aqui
+ }
+}
+```
+
+/// tip | Dica
+
+Perceba o servidor gerado automaticamente com um valor `url` de `/api/v1`, retirado do `root_path`.
+
+///
+
+Na interface de documentação em http://127.0.0.1:9999/api/v1/docs parecerá:
+
+
+
+/// tip | Dica
+
+A interface de documentação interagirá com o servidor que você selecionar.
+
+///
+
+### Desabilitar servidor automático de `root_path`
+
+Se você não quiser que o **FastAPI** inclua um servidor automático usando o `root_path`, você pode usar o parâmetro `root_path_in_servers=False`:
+
+{* ../../docs_src/behind_a_proxy/tutorial004.py hl[9] *}
+
+e então ele não será incluído no OpenAPI schema.
+
+## Montando uma sub-aplicação
+
+Se você precisar montar uma sub-aplicação (como descrito em [Sub Aplicações - Montagens](sub-applications.md){.internal-link target=_blank}) enquanto também usa um proxy com `root_path`, você pode fazer isso normalmente, como esperaria.
+
+O FastAPI usará internamente o `root_path` de forma inteligente, então tudo funcionará. ✨
diff --git a/docs/pt/docs/advanced/benchmarks.md b/docs/pt/docs/advanced/benchmarks.md
deleted file mode 100644
index 72ef1e444..000000000
--- a/docs/pt/docs/advanced/benchmarks.md
+++ /dev/null
@@ -1,34 +0,0 @@
-# Benchmarks
-
-Benchmarks independentes da TechEmpower mostram que aplicações **FastAPI** rodando com o Uvicorn como um dos frameworks Python mais rápidos disponíveis, ficando atrás apenas do Starlette e Uvicorn (utilizado internamente pelo FastAPI).
-
-Porém, ao verificar benchmarks e comparações você deve prestar atenção ao seguinte:
-
-## Benchmarks e velocidade
-
-Quando você verifica os benchmarks, é comum ver diversas ferramentas de diferentes tipos comparados como se fossem equivalentes.
-
-Especificamente, para ver o Uvicorn, Starlette e FastAPI comparados entre si (entre diversas outras ferramentas).
-
-Quanto mais simples o problema resolvido pela ferramenta, melhor será a performance. E a maioria das análises não testa funcionalidades adicionais que são oferecidas pela ferramenta.
-
-A hierarquia é:
-
-* **Uvicorn**: um servidor ASGI
- * **Starlette**: (utiliza Uvicorn) um microframework web
- * **FastAPI**: (utiliza Starlette) um microframework para APIs com diversas funcionalidades adicionais para a construção de APIs, com validação de dados, etc.
-
-* **Uvicorn**:
- * Terá a melhor performance, pois não possui muito código além do próprio servidor.
- * Você não escreveria uma aplicação utilizando o Uvicorn diretamente. Isso significaria que o seu código teria que incluir pelo menos todo o código fornecido pelo Starlette (ou o **FastAPI**). E caso você fizesse isso, a sua aplicação final teria a mesma sobrecarga que teria se utilizasse um framework, minimizando o código e os bugs.
- * Se você está comparando o Uvicorn, compare com os servidores de aplicação Daphne, Hypercorn, uWSGI, etc.
-* **Starlette**:
- * Terá o melhor desempenho, depois do Uvicorn. Na verdade, o Starlette utiliza o Uvicorn para rodar. Portanto, ele pode ficar mais "devagar" que o Uvicorn apenas por ter que executar mais código.
- * Mas ele fornece as ferramentas para construir aplicações web simples, com roteamento baseado em caminhos, etc.
- * Se você está comparando o Starlette, compare-o com o Sanic, Flask, Django, etc. Frameworks web (ou microframeworks).
-* **FastAPI**:
- * Da mesma forma que o Starlette utiliza o Uvicorn e não consegue ser mais rápido que ele, o **FastAPI** utiliza o Starlette, portanto, ele não consegue ser mais rápido que ele.
- * O FastAPI provê mais funcionalidades em cima do Starlette. Funcionalidades que você quase sempre precisará quando estiver construindo APIs, como validação de dados e serialização. E ao utilizá-lo, você obtém documentação automática sem custo nenhum (a documentação automática sequer adiciona sobrecarga nas aplicações rodando, pois ela é gerada na inicialização).
- * Caso você não utilize o FastAPI e faz uso do Starlette diretamente (ou outra ferramenta, como o Sanic, Flask, Responder, etc) você mesmo teria que implementar toda a validação de dados e serialização. Então, a sua aplicação final ainda teria a mesma sobrecarga caso estivesse usando o FastAPI. E em muitos casos, validação de dados e serialização é a maior parte do código escrito em aplicações.
- * Então, ao utilizar o FastAPI, você está economizando tempo de programação, evitando bugs, linhas de código, e provavelmente terá a mesma performance (ou até melhor) do que teria caso você não o utilizasse (já que você teria que implementar tudo no seu código).
- * Se você está comparando o FastAPI, compare-o com frameworks de aplicações web (ou conjunto de ferramentas) que oferecem validação de dados, serialização e documentação, como por exemplo o Flask-apispec, NestJS, Molten, etc. Frameworks que possuem validação integrada de dados, serialização e documentação.
diff --git a/docs/pt/docs/advanced/custom-response.md b/docs/pt/docs/advanced/custom-response.md
new file mode 100644
index 000000000..a0bcc2b97
--- /dev/null
+++ b/docs/pt/docs/advanced/custom-response.md
@@ -0,0 +1,314 @@
+# Resposta Personalizada - HTML, Stream, File e outras
+
+Por padrão, o **FastAPI** irá retornar respostas utilizando `JSONResponse`.
+
+Mas você pode sobrescrever esse comportamento utilizando `Response` diretamente, como visto em [Retornando uma Resposta Diretamente](response-directly.md){.internal-link target=_blank}.
+
+Mas se você retornar uma `Response` diretamente (ou qualquer subclasse, como `JSONResponse`), os dados não serão convertidos automaticamente (mesmo que você declare um `response_model`), e a documentação não será gerada automaticamente (por exemplo, incluindo o "media type", no cabeçalho HTTP `Content-Type` como parte do esquema OpenAPI gerado).
+
+Mas você também pode declarar a `Response` que você deseja utilizar (e.g. qualquer subclasse de `Response`), em um *decorador de operação de rota* utilizando o parâmetro `response_class`.
+
+Os conteúdos que você retorna em sua *função de operador de rota* serão colocados dentro dessa `Response`.
+
+E se a `Response` tiver um media type JSON (`application/json`), como é o caso com `JSONResponse` e `UJSONResponse`, os dados que você retornar serão automaticamente convertidos (e filtrados) com qualquer `response_model` do Pydantic que for declarado em sua *função de operador de rota*.
+
+/// note | Nota
+
+Se você utilizar uma classe de Resposta sem media type, o FastAPI esperará que sua resposta não tenha conteúdo, então ele não irá documentar o formato da resposta na documentação OpenAPI gerada.
+
+///
+
+## Utilizando `ORJSONResponse`
+
+Por exemplo, se você precisa bastante de performance, você pode instalar e utilizar o `orjson` e definir a resposta para ser uma `ORJSONResponse`.
+
+Importe a classe, ou subclasse, de `Response` que você deseja utilizar e declare ela no *decorador de operação de rota*.
+
+Para respostas grandes, retornar uma `Response` diretamente é muito mais rápido que retornar um dicionário.
+
+Isso ocorre por que, por padrão, o FastAPI irá verificar cada item dentro do dicionário e garantir que ele seja serializável para JSON, utilizando o mesmo[Codificador Compatível com JSON](../tutorial/encoder.md){.internal-link target=_blank} explicado no tutorial. Isso permite que você retorne **objetos abstratos**, como modelos do banco de dados, por exemplo.
+
+Mas se você tem certeza que o conteúdo que você está retornando é **serializável com JSON**, você pode passá-lo diretamente para a classe de resposta e evitar o trabalho extra que o FastAPI teria ao passar o conteúdo pelo `jsonable_encoder` antes de passar para a classe de resposta.
+
+{* ../../docs_src/custom_response/tutorial001b.py hl[2,7] *}
+
+/// info | Informação
+
+O parâmetro `response_class` também será usado para definir o "media type" da resposta.
+
+Neste caso, o cabeçalho HTTP `Content-Type` irá ser definido como `application/json`.
+
+E será documentado como tal no OpenAPI.
+
+///
+
+/// tip | Dica
+
+A `ORJSONResponse` está disponível apenas no FastAPI, e não no Starlette.
+
+///
+
+## Resposta HTML
+
+Para retornar uma resposta com HTML diretamente do **FastAPI**, utilize `HTMLResponse`.
+
+* Importe `HTMLResponse`
+* Passe `HTMLResponse` como o parâmetro de `response_class` do seu *decorador de operação de rota*.
+
+{* ../../docs_src/custom_response/tutorial002.py hl[2,7] *}
+
+/// info | Informação
+
+O parâmetro `response_class` também será usado para definir o "media type" da resposta.
+
+Neste caso, o cabeçalho HTTP `Content-Type` será definido como `text/html`.
+
+E será documentado como tal no OpenAPI.
+
+///
+
+### Retornando uma `Response`
+
+Como visto em [Retornando uma Resposta Diretamente](response-directly.md){.internal-link target=_blank}, você também pode sobrescrever a resposta diretamente na sua *operação de rota*, ao retornar ela.
+
+O mesmo exemplo de antes, retornando uma `HTMLResponse`, poderia parecer com:
+
+{* ../../docs_src/custom_response/tutorial003.py hl[2,7,19] *}
+
+/// warning | Aviso
+
+Uma `Response` retornada diretamente em sua *função de operação de rota* não será documentada no OpenAPI (por exemplo, o `Content-Type` não será documentado) e não será visível na documentação interativa automática.
+
+///
+
+/// info | Informação
+
+Obviamente, o cabeçalho `Content-Type`, o código de status, etc, virão do objeto `Response` que você retornou.
+
+///
+
+### Documentar no OpenAPI e sobrescrever `Response`
+
+Se você deseja sobrescrever a resposta dentro de uma função, mas ao mesmo tempo documentar o "media type" no OpenAPI, você pode utilizar o parâmetro `response_class` E retornar um objeto `Response`.
+
+A `response_class` será usada apenas para documentar o OpenAPI da *operação de rota*, mas sua `Response` será usada como foi definida.
+
+##### Retornando uma `HTMLResponse` diretamente
+
+Por exemplo, poderia ser algo como:
+
+{* ../../docs_src/custom_response/tutorial004.py hl[7,21,23] *}
+
+Neste exemplo, a função `generate_html_response()` já cria e retorna uma `Response` em vez de retornar o HTML em uma `str`.
+
+Ao retornar o resultado chamando `generate_html_response()`, você já está retornando uma `Response` que irá sobrescrever o comportamento padrão do **FastAPI**.
+
+Mas se você passasse uma `HTMLResponse` em `response_class` também, o **FastAPI** saberia como documentar isso no OpenAPI e na documentação interativa como um HTML com `text/html`:
+
+
+
+## Respostas disponíveis
+
+Aqui estão algumas dos tipos de resposta disponíveis.
+
+Lembre-se que você pode utilizar `Response` para retornar qualquer outra coisa, ou até mesmo criar uma subclasse personalizada.
+
+/// note | Detalhes Técnicos
+
+Você também pode utilizar `from starlette.responses import HTMLResponse`.
+
+O **FastAPI** provê a mesma `starlette.responses` como `fastapi.responses` apenas como uma facilidade para você, desenvolvedor. Mas a maioria das respostas disponíveis vêm diretamente do Starlette.
+
+///
+
+### `Response`
+
+A classe principal de respostas, todas as outras respostas herdam dela.
+
+Você pode retorná-la diretamente.
+
+Ela aceita os seguintes parâmetros:
+
+* `content` - Uma sequência de caracteres (`str`) ou `bytes`.
+* `status_code` - Um código de status HTTP do tipo `int`.
+* `headers` - Um dicionário `dict` de strings.
+* `media_type` - Uma `str` informando o media type. E.g. `"text/html"`.
+
+O FastAPI (Starlette, na verdade) irá incluir o cabeçalho Content-Length automaticamente. Ele também irá incluir o cabeçalho Content-Type, baseado no `media_type` e acrescentando uma codificação para tipos textuais.
+
+{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
+
+### `HTMLResponse`
+
+Usa algum texto ou sequência de bytes e retorna uma resposta HTML. Como você leu acima.
+
+### `PlainTextResponse`
+
+Usa algum texto ou sequência de bytes para retornar uma resposta de texto não formatado.
+
+{* ../../docs_src/custom_response/tutorial005.py hl[2,7,9] *}
+
+### `JSONResponse`
+
+Pega alguns dados e retorna uma resposta com codificação `application/json`.
+
+É a resposta padrão utilizada no **FastAPI**, como você leu acima.
+
+### `ORJSONResponse`
+
+Uma alternativa mais rápida de resposta JSON utilizando o `orjson`, como você leu acima.
+
+/// info | Informação
+
+Essa resposta requer a instalação do pacote `orjson`, com o comando `pip install orjson`, por exemplo.
+
+///
+
+### `UJSONResponse`
+
+Uma alternativa de resposta JSON utilizando a biblioteca `ujson`.
+
+/// info | Informação
+
+Essa resposta requer a instalação do pacote `ujson`, com o comando `pip install ujson`, por exemplo.
+
+///
+
+/// warning | Aviso
+
+`ujson` é menos cauteloso que a implementação nativa do Python na forma que os casos especiais são tratados
+
+///
+
+{* ../../docs_src/custom_response/tutorial001.py hl[2,7] *}
+
+/// tip | Dica
+
+É possível que `ORJSONResponse` seja uma alternativa mais rápida.
+
+///
+
+### `RedirectResponse`
+
+Retorna um redirecionamento HTTP. Utiliza o código de status 307 (Redirecionamento Temporário) por padrão.
+
+Você pode retornar uma `RedirectResponse` diretamente:
+
+{* ../../docs_src/custom_response/tutorial006.py hl[2,9] *}
+
+---
+
+Ou você pode utilizá-la no parâmetro `response_class`:
+
+{* ../../docs_src/custom_response/tutorial006b.py hl[2,7,9] *}
+
+Se você fizer isso, então você pode retornar a URL diretamente da sua *função de operação de rota*
+
+Neste caso, o `status_code` utilizada será o padrão de `RedirectResponse`, que é `307`.
+
+---
+
+Você também pode utilizar o parâmetro `status_code` combinado com o parâmetro `response_class`:
+
+{* ../../docs_src/custom_response/tutorial006c.py hl[2,7,9] *}
+
+### `StreamingResponse`
+
+Recebe uma gerador assíncrono ou um gerador/iterador comum e retorna o corpo da requisição continuamente (stream).
+
+{* ../../docs_src/custom_response/tutorial007.py hl[2,14] *}
+
+#### Utilizando `StreamingResponse` com objetos semelhantes a arquivos
+
+Se você tiver um objeto semelhante a um arquivo (e.g. o objeto retornado por `open()`), você pode criar uma função geradora para iterar sobre esse objeto.
+
+Dessa forma, você não precisa ler todo o arquivo na memória primeiro, e você pode passar essa função geradora para `StreamingResponse` e retorná-la.
+
+Isso inclui muitas bibliotecas que interagem com armazenamento em nuvem, processamento de vídeos, entre outras.
+
+```{ .python .annotate hl_lines="2 10-12 14" }
+{!../../docs_src/custom_response/tutorial008.py!}
+```
+
+1. Essa é a função geradora. É definida como "função geradora" porque contém declarações `yield` nela.
+2. Ao utilizar o bloco `with`, nós garantimos que o objeto semelhante a um arquivo é fechado após a função geradora ser finalizada. Isto é, após a resposta terminar de ser enivada.
+3. Essa declaração `yield from` informa a função para iterar sobre essa coisa nomeada de `file_like`. E então, para cada parte iterada, fornece essa parte como se viesse dessa função geradora (`iterfile`).
+
+ Então, é uma função geradora que transfere o trabalho de "geração" para alguma outra coisa interna.
+
+ Fazendo dessa forma, podemos colocá-la em um bloco `with`, e assim garantir que o objeto semelhante a um arquivo é fechado quando a função termina.
+
+/// tip | Dica
+
+Perceba que aqui estamos utilizando o `open()` da biblioteca padrão que não suporta `async` e `await`, e declaramos a operação de rota com o `def` básico.
+
+///
+
+### `FileResponse`
+
+Envia um arquivo de forma assíncrona e contínua (stream).
+*
+Recebe um conjunto de argumentos do construtor diferente dos outros tipos de resposta:
+
+* `path` - O caminho do arquivo que será transmitido
+* `headers` - quaisquer cabeçalhos que serão incluídos, como um dicionário.
+* `media_type` - Uma string com o media type. Se não for definida, o media type é inferido a partir do nome ou caminho do arquivo.
+* `filename` - Se for definido, é incluído no cabeçalho `Content-Disposition`.
+
+Respostas de Arquivos incluem o tamanho do arquivo, data da última modificação e ETags apropriados, nos cabeçalhos `Content-Length`, `Last-Modified` e `ETag`, respectivamente.
+
+{* ../../docs_src/custom_response/tutorial009.py hl[2,10] *}
+
+Você também pode usar o parâmetro `response_class`:
+
+{* ../../docs_src/custom_response/tutorial009b.py hl[2,8,10] *}
+
+Nesse caso, você pode retornar o caminho do arquivo diretamente da sua *função de operação de rota*.
+
+## Classe de resposta personalizada
+
+Você pode criar sua própria classe de resposta, herdando de `Response` e usando essa nova classe.
+
+Por exemplo, vamos supor que você queira utilizar o `orjson`, mas com algumas configurações personalizadas que não estão incluídas na classe `ORJSONResponse`.
+
+Vamos supor também que você queira retornar um JSON indentado e formatado, então você quer utilizar a opção `orjson.OPT_INDENT_2` do orjson.
+
+Você poderia criar uma classe `CustomORJSONResponse`. A principal coisa a ser feita é sobrecarregar o método render da classe Response, `Response.render(content)`, que retorna o conteúdo em bytes, para retornar o conteúdo que você deseja:
+
+{* ../../docs_src/custom_response/tutorial009c.py hl[9:14,17] *}
+
+Agora em vez de retornar:
+
+```json
+{"message": "Hello World"}
+```
+
+...essa resposta retornará:
+
+```json
+{
+ "message": "Hello World"
+}
+```
+
+Obviamente, você provavelmente vai encontrar maneiras muito melhores de se aproveitar disso do que a formatação de JSON. 😉
+
+## Classe de resposta padrão
+
+Quando você criar uma instância da classe **FastAPI** ou um `APIRouter` você pode especificar qual classe de resposta utilizar por padrão.
+
+O padrão que define isso é o `default_response_class`.
+
+No exemplo abaixo, o **FastAPI** irá utilizar `ORJSONResponse` por padrão, em todas as *operações de rota*, em vez de `JSONResponse`.
+
+{* ../../docs_src/custom_response/tutorial010.py hl[2,4] *}
+
+/// tip | Dica
+
+Você ainda pode substituir `response_class` em *operações de rota* como antes.
+
+///
+
+## Documentação adicional
+
+Você também pode declarar o media type e muitos outros detalhes no OpenAPI utilizando `responses`: [Retornos Adicionais no OpenAPI](additional-responses.md){.internal-link target=_blank}.
diff --git a/docs/pt/docs/advanced/dataclasses.md b/docs/pt/docs/advanced/dataclasses.md
new file mode 100644
index 000000000..600c8c268
--- /dev/null
+++ b/docs/pt/docs/advanced/dataclasses.md
@@ -0,0 +1,97 @@
+# Usando Dataclasses
+
+FastAPI é construído em cima do **Pydantic**, e eu tenho mostrado como usar modelos Pydantic para declarar requisições e respostas.
+
+Mas o FastAPI também suporta o uso de `dataclasses` da mesma forma:
+
+{* ../../docs_src/dataclasses/tutorial001.py hl[1,7:12,19:20] *}
+
+Isso ainda é suportado graças ao **Pydantic**, pois ele tem suporte interno para `dataclasses`.
+
+Então, mesmo com o código acima que não usa Pydantic explicitamente, o FastAPI está usando Pydantic para converter essas dataclasses padrão para a versão do Pydantic.
+
+E claro, ele suporta o mesmo:
+
+* validação de dados
+* serialização de dados
+* documentação de dados, etc.
+
+Isso funciona da mesma forma que com os modelos Pydantic. E na verdade é alcançado da mesma maneira por baixo dos panos, usando Pydantic.
+
+/// info | Informação
+
+Lembre-se de que dataclasses não podem fazer tudo o que os modelos Pydantic podem fazer.
+
+Então, você ainda pode precisar usar modelos Pydantic.
+
+Mas se você tem um monte de dataclasses por aí, este é um truque legal para usá-las para alimentar uma API web usando FastAPI. 🤓
+
+///
+
+## Dataclasses em `response_model`
+
+Você também pode usar `dataclasses` no parâmetro `response_model`:
+
+{* ../../docs_src/dataclasses/tutorial002.py hl[1,7:13,19] *}
+
+A dataclass será automaticamente convertida para uma dataclass Pydantic.
+
+Dessa forma, seu esquema aparecerá na interface de documentação da API:
+
+
+
+## Dataclasses em Estruturas de Dados Aninhadas
+
+Você também pode combinar `dataclasses` com outras anotações de tipo para criar estruturas de dados aninhadas.
+
+Em alguns casos, você ainda pode ter que usar a versão do Pydantic das `dataclasses`. Por exemplo, se você tiver erros com a documentação da API gerada automaticamente.
+
+Nesse caso, você pode simplesmente trocar as `dataclasses` padrão por `pydantic.dataclasses`, que é um substituto direto:
+
+```{ .python .annotate hl_lines="1 5 8-11 14-17 23-25 28" }
+{!../../docs_src/dataclasses/tutorial003.py!}
+```
+
+1. Ainda importamos `field` das `dataclasses` padrão.
+
+2. `pydantic.dataclasses` é um substituto direto para `dataclasses`.
+
+3. A dataclass `Author` inclui uma lista de dataclasses `Item`.
+
+4. A dataclass `Author` é usada como o parâmetro `response_model`.
+
+5. Você pode usar outras anotações de tipo padrão com dataclasses como o corpo da requisição.
+
+ Neste caso, é uma lista de dataclasses `Item`.
+
+6. Aqui estamos retornando um dicionário que contém `items`, que é uma lista de dataclasses.
+
+ O FastAPI ainda é capaz de serializar os dados para JSON.
+
+7. Aqui o `response_model` está usando uma anotação de tipo de uma lista de dataclasses `Author`.
+
+ Novamente, você pode combinar `dataclasses` com anotações de tipo padrão.
+
+8. Note que esta *função de operação de rota* usa `def` regular em vez de `async def`.
+
+ Como sempre, no FastAPI você pode combinar `def` e `async def` conforme necessário.
+
+ Se você precisar de uma atualização sobre quando usar qual, confira a seção _"Com pressa?"_ na documentação sobre [`async` e `await`](../async.md#in-a-hurry){.internal-link target=_blank}.
+
+9. Esta *função de operação de rota* não está retornando dataclasses (embora pudesse), mas uma lista de dicionários com dados internos.
+
+ O FastAPI usará o parâmetro `response_model` (que inclui dataclasses) para converter a resposta.
+
+Você pode combinar `dataclasses` com outras anotações de tipo em muitas combinações diferentes para formar estruturas de dados complexas.
+
+Confira as dicas de anotação no código acima para ver mais detalhes específicos.
+
+## Saiba Mais
+
+Você também pode combinar `dataclasses` com outros modelos Pydantic, herdar deles, incluí-los em seus próprios modelos, etc.
+
+Para saber mais, confira a documentação do Pydantic sobre dataclasses.
+
+## Versão
+
+Isso está disponível desde a versão `0.67.0` do FastAPI. 🔖
diff --git a/docs/pt/docs/advanced/events.md b/docs/pt/docs/advanced/events.md
index 12aa93f29..504b6db57 100644
--- a/docs/pt/docs/advanced/events.md
+++ b/docs/pt/docs/advanced/events.md
@@ -31,26 +31,25 @@ Vamos iniciar com um exemplo e ver isso detalhadamente.
Nós criamos uma função assíncrona chamada `lifespan()` com `yield` como este:
-```Python hl_lines="16 19"
-{!../../../docs_src/events/tutorial003.py!}
-```
+{* ../../docs_src/events/tutorial003.py hl[16,19] *}
Aqui nós estamos simulando a *inicialização* custosa do carregamento do modelo colocando a (falsa) função de modelo no dicionário com modelos de _machine learning_ antes do `yield`. Este código será executado **antes** da aplicação **começar a receber requisições**, durante a *inicialização*.
E então, logo após o `yield`, descarregaremos o modelo. Esse código será executado **após** a aplicação **terminar de lidar com as requisições**, pouco antes do *encerramento*. Isso poderia, por exemplo, liberar recursos como memória ou GPU.
-!!! tip "Dica"
- O `shutdown` aconteceria quando você estivesse **encerrando** a aplicação.
+/// tip | Dica
- Talvez você precise inicializar uma nova versão, ou apenas cansou de executá-la. 🤷
+O `shutdown` aconteceria quando você estivesse **encerrando** a aplicação.
+
+Talvez você precise inicializar uma nova versão, ou apenas cansou de executá-la. 🤷
+
+///
### Função _lifespan_
A primeira coisa a notar, é que estamos definindo uma função assíncrona com `yield`. Isso é muito semelhante à Dependências com `yield`.
-```Python hl_lines="14-19"
-{!../../../docs_src/events/tutorial003.py!}
-```
+{* ../../docs_src/events/tutorial003.py hl[14:19] *}
A primeira parte da função, antes do `yield`, será executada **antes** da aplicação inicializar.
@@ -62,9 +61,7 @@ Se você verificar, a função está decorada com um `@asynccontextmanager`.
Que converte a função em algo chamado de "**Gerenciador de Contexto Assíncrono**".
-```Python hl_lines="1 13"
-{!../../../docs_src/events/tutorial003.py!}
-```
+{* ../../docs_src/events/tutorial003.py hl[1,13] *}
Um **gerenciador de contexto** em Python é algo que você pode usar em uma declaração `with`, por exemplo, `open()` pode ser usado como um gerenciador de contexto:
@@ -86,16 +83,17 @@ No nosso exemplo de código acima, nós não usamos ele diretamente, mas nós pa
O parâmetro `lifespan` da aplicação `FastAPI` usa um **Gerenciador de Contexto Assíncrono**, então nós podemos passar nosso novo gerenciador de contexto assíncrono do `lifespan` para ele.
-```Python hl_lines="22"
-{!../../../docs_src/events/tutorial003.py!}
-```
+{* ../../docs_src/events/tutorial003.py hl[22] *}
## Eventos alternativos (deprecados)
-!!! warning "Aviso"
- A maneira recomendada para lidar com a *inicialização* e o *encerramento* é usando o parâmetro `lifespan` da aplicação `FastAPI` como descrito acima.
+/// warning | Aviso
- Você provavelmente pode pular essa parte.
+A maneira recomendada para lidar com a *inicialização* e o *encerramento* é usando o parâmetro `lifespan` da aplicação `FastAPI` como descrito acima.
+
+Você provavelmente pode pular essa parte.
+
+///
Existe uma forma alternativa para definir a execução dessa lógica durante *inicialização* e durante *encerramento*.
@@ -107,9 +105,7 @@ Essas funções podem ser declaradas com `async def` ou `def` normal.
Para adicionar uma função que deve rodar antes da aplicação iniciar, declare-a com o evento `"startup"`:
-```Python hl_lines="8"
-{!../../../docs_src/events/tutorial001.py!}
-```
+{* ../../docs_src/events/tutorial001.py hl[8] *}
Nesse caso, a função de manipulação de evento `startup` irá inicializar os itens do "banco de dados" (só um `dict`) com alguns valores.
@@ -121,23 +117,27 @@ E sua aplicação não irá começar a receber requisições até que todos os m
Para adicionar uma função que deve ser executada quando a aplicação estiver encerrando, declare ela com o evento `"shutdown"`:
-```Python hl_lines="6"
-{!../../../docs_src/events/tutorial002.py!}
-```
+{* ../../docs_src/events/tutorial002.py hl[6] *}
Aqui, a função de manipulação de evento `shutdown` irá escrever uma linha de texto `"Application shutdown"` no arquivo `log.txt`.
-!!! info "Informação"
- Na função `open()`, o `mode="a"` significa "acrescentar", então, a linha irá ser adicionada depois de qualquer coisa que esteja naquele arquivo, sem sobrescrever o conteúdo anterior.
+/// info | Informação
-!!! tip "Dica"
- Perceba que nesse caso nós estamos usando a função padrão do Python `open()` que interage com um arquivo.
+Na função `open()`, o `mode="a"` significa "acrescentar", então, a linha irá ser adicionada depois de qualquer coisa que esteja naquele arquivo, sem sobrescrever o conteúdo anterior.
- Então, isso envolve I/O (input/output), que exige "esperar" que coisas sejam escritas em disco.
+///
- Mas `open()` não usa `async` e `await`.
+/// tip | Dica
- Então, nós declaramos uma função de manipulação de evento com o padrão `def` ao invés de `async def`.
+Perceba que nesse caso nós estamos usando a função padrão do Python `open()` que interage com um arquivo.
+
+Então, isso envolve I/O (input/output), que exige "esperar" que coisas sejam escritas em disco.
+
+Mas `open()` não usa `async` e `await`.
+
+Então, nós declaramos uma função de manipulação de evento com o padrão `def` ao invés de `async def`.
+
+///
### `startup` e `shutdown` juntos
@@ -153,10 +153,13 @@ Só um detalhe técnico para nerds curiosos. 🤓
Por baixo, na especificação técnica ASGI, essa é a parte do Protocolo Lifespan, e define eventos chamados `startup` e `shutdown`.
-!!! info "Informação"
- Você pode ler mais sobre o manipulador `lifespan` do Starlette na Documentação do Lifespan Starlette.
+/// info | Informação
- Incluindo como manipular estado do lifespan que pode ser usado em outras áreas do seu código.
+Você pode ler mais sobre o manipulador `lifespan` do Starlette na Documentação do Lifespan Starlette.
+
+Incluindo como manipular estado do lifespan que pode ser usado em outras áreas do seu código.
+
+///
## Sub Aplicações
diff --git a/docs/pt/docs/advanced/generate-clients.md b/docs/pt/docs/advanced/generate-clients.md
new file mode 100644
index 000000000..dc6b29511
--- /dev/null
+++ b/docs/pt/docs/advanced/generate-clients.md
@@ -0,0 +1,261 @@
+# Generate Clients
+
+Como o **FastAPI** é baseado na especificação **OpenAPI**, você obtém compatibilidade automática com muitas ferramentas, incluindo a documentação automática da API (fornecida pelo Swagger UI).
+
+Uma vantagem particular que nem sempre é óbvia é que você pode **gerar clientes** (às vezes chamados de **SDKs**) para a sua API, para muitas **linguagens de programação** diferentes.
+
+## Geradores de Clientes OpenAPI
+
+Existem muitas ferramentas para gerar clientes a partir do **OpenAPI**.
+
+Uma ferramenta comum é o OpenAPI Generator.
+
+Se voce está construindo um **frontend**, uma alternativa muito interessante é o openapi-ts.
+
+## Geradores de Clientes e SDKs - Patrocinadores
+
+Existem também alguns geradores de clientes e SDKs baseados na OpenAPI (FastAPI) **patrocinados por empresas**, em alguns casos eles podem oferecer **recursos adicionais** além de SDKs/clientes gerados de alta qualidade.
+
+Alguns deles também ✨ [**patrocinam o FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨, isso garante o **desenvolvimento** contínuo e saudável do FastAPI e seu **ecossistema**.
+
+E isso mostra o verdadeiro compromisso deles com o FastAPI e sua **comunidade** (você), pois eles não apenas querem fornecer um **bom serviço**, mas também querem garantir que você tenha um **framework bom e saudável**, o FastAPI. 🙇
+
+Por exemplo, você pode querer experimentar:
+
+* Speakeasy
+* Stainless
+* liblab
+
+Existem também várias outras empresas que oferecem serviços semelhantes que você pode pesquisar e encontrar online. 🤓
+
+## Gerar um Cliente Frontend TypeScript
+
+Vamos começar com um aplicativo **FastAPI** simples:
+
+{* ../../docs_src/generate_clients/tutorial001_py39.py hl[7:9,12:13,16:17,21] *}
+
+Note que as *operações de rota* definem os modelos que usam para o corpo da requisição e o corpo da resposta, usando os modelos `Item` e `ResponseMessage`.
+
+### Documentação da API
+
+Se você acessar a documentação da API, verá que ela tem os **schemas** para os dados a serem enviados nas requisições e recebidos nas respostas:
+
+
+
+Você pode ver esses schemas porque eles foram declarados com os modelos no app.
+
+Essas informações estão disponíveis no **OpenAPI schema** do app e são mostradas na documentação da API (pelo Swagger UI).
+
+E essas mesmas informações dos modelos que estão incluídas no OpenAPI são o que pode ser usado para **gerar o código do cliente**.
+
+### Gerar um Cliente TypeScript
+
+Agora que temos o app com os modelos, podemos gerar o código do cliente para o frontend.
+
+#### Instalar o `openapi-ts`
+
+Você pode instalar o `openapi-ts` no seu código frontend com:
+
+
+
+Você também obterá preenchimento automático para o corpo a ser enviado:
+
+
+
+/// tip | Dica
+
+Observe o preenchimento automático para `name` e `price`, que foi definido no aplicativo FastAPI, no modelo `Item`.
+
+///
+
+Você terá erros em linha para os dados que você envia:
+
+
+
+O objeto de resposta também terá preenchimento automático:
+
+
+
+## App FastAPI com Tags
+
+Em muitos casos seu app FastAPI será maior, e você provavelmente usará tags para separar diferentes grupos de *operações de rota*.
+
+Por exemplo, você poderia ter uma seção para **items** e outra seção para **users**, e elas poderiam ser separadas por tags:
+
+{* ../../docs_src/generate_clients/tutorial002_py39.py hl[21,26,34] *}
+
+### Gerar um Cliente TypeScript com Tags
+
+Se você gerar um cliente para um app FastAPI usando tags, normalmente também separará o código do cliente com base nas tags.
+
+Dessa forma, você poderá ter as coisas ordenadas e agrupadas corretamente para o código do cliente:
+
+
+
+Nesse caso você tem:
+
+* `ItemsService`
+* `UsersService`
+
+### Nomes dos Métodos do Cliente
+
+Agora os nomes dos métodos gerados como `createItemItemsPost` não parecem muito "limpos":
+
+```TypeScript
+ItemsService.createItemItemsPost({name: "Plumbus", price: 5})
+```
+
+...isto ocorre porque o gerador de clientes usa o **operation ID** interno do OpenAPI para cada *operação de rota*.
+
+O OpenAPI exige que cada operation ID seja único em todas as *operações de rota*, então o FastAPI usa o **nome da função**, o **caminho** e o **método/operacao HTTP** para gerar esse operation ID, porque dessa forma ele pode garantir que os operation IDs sejam únicos.
+
+Mas eu vou te mostrar como melhorar isso a seguir. 🤓
+
+### IDs de Operação Personalizados e Melhores Nomes de Método
+
+Você pode **modificar** a maneira como esses IDs de operação são **gerados** para torná-los mais simples e ter **nomes de método mais simples** nos clientes.
+
+Neste caso, você terá que garantir que cada ID de operação seja **único** de alguma outra maneira.
+
+Por exemplo, você poderia garantir que cada *operação de rota* tenha uma tag, e então gerar o ID da operação com base na **tag** e no **nome** da *operação de rota* (o nome da função).
+
+### Função Personalizada para Gerar IDs de Operação Únicos
+
+O FastAPI usa um **ID único** para cada *operação de rota*, ele é usado para o **ID da operação** e também para os nomes de quaisquer modelos personalizados necessários, para requisições ou respostas.
+
+Você pode personalizar essa função. Ela recebe uma `APIRoute` e gera uma string.
+
+Por exemplo, aqui está usando a primeira tag (você provavelmente terá apenas uma tag) e o nome da *operação de rota* (o nome da função).
+
+Você pode então passar essa função personalizada para o **FastAPI** como o parâmetro `generate_unique_id_function`:
+
+{* ../../docs_src/generate_clients/tutorial003_py39.py hl[6:7,10] *}
+
+### Gerar um Cliente TypeScript com IDs de Operação Personalizados
+
+Agora, se você gerar o cliente novamente, verá que ele tem os nomes dos métodos melhorados:
+
+
+
+Como você pode ver, os nomes dos métodos agora têm a tag e, em seguida, o nome da função. Agora eles não incluem informações do caminho da URL e da operação HTTP.
+
+### Pré-processar a Especificação OpenAPI para o Gerador de Clientes
+
+O código gerado ainda tem algumas **informações duplicadas**.
+
+Nós já sabemos que esse método está relacionado aos **items** porque essa palavra está no `ItemsService` (retirada da tag), mas ainda temos o nome da tag prefixado no nome do método também. 😕
+
+Provavelmente ainda queremos mantê-lo para o OpenAPI em geral, pois isso garantirá que os IDs de operação sejam **únicos**.
+
+Mas para o cliente gerado, poderíamos **modificar** os IDs de operação do OpenAPI logo antes de gerar os clientes, apenas para tornar esses nomes de método mais **simples**.
+
+Poderíamos baixar o JSON do OpenAPI para um arquivo `openapi.json` e então poderíamos **remover essa tag prefixada** com um script como este:
+
+{* ../../docs_src/generate_clients/tutorial004.py *}
+
+//// tab | Node.js
+
+```Javascript
+{!> ../../docs_src/generate_clients/tutorial004.js!}
+```
+
+////
+
+Com isso, os IDs de operação seriam renomeados de coisas como `items-get_items` para apenas `get_items`, dessa forma o gerador de clientes pode gerar nomes de métodos mais simples.
+
+### Gerar um Cliente TypeScript com o OpenAPI Pré-processado
+
+Agora, como o resultado final está em um arquivo `openapi.json`, você modificaria o `package.json` para usar esse arquivo local, por exemplo:
+
+```JSON hl_lines="7"
+{
+ "name": "frontend-app",
+ "version": "1.0.0",
+ "description": "",
+ "main": "index.js",
+ "scripts": {
+ "generate-client": "openapi-ts --input ./openapi.json --output ./src/client --client axios"
+ },
+ "author": "",
+ "license": "",
+ "devDependencies": {
+ "@hey-api/openapi-ts": "^0.27.38",
+ "typescript": "^4.6.2"
+ }
+}
+```
+
+Depois de gerar o novo cliente, você teria agora **nomes de métodos "limpos"**, com todo o **preenchimento automático**, **erros em linha**, etc:
+
+
+
+## Benefícios
+
+Ao usar os clientes gerados automaticamente, você teria **preenchimento automático** para:
+
+* Métodos.
+* Corpo de requisições, parâmetros da query, etc.
+* Corpo de respostas.
+
+Você também teria **erros em linha** para tudo.
+
+E sempre que você atualizar o código do backend, e **regenerar** o frontend, ele teria quaisquer novas *operações de rota* disponíveis como métodos, as antigas removidas, e qualquer outra alteração seria refletida no código gerado. 🤓
+
+Isso também significa que se algo mudar, será **refletido** no código do cliente automaticamente. E se você **construir** o cliente, ele dará erro se houver alguma **incompatibilidade** nos dados usados.
+
+Então, você **detectaria vários erros** muito cedo no ciclo de desenvolvimento, em vez de ter que esperar que os erros apareçam para seus usuários finais em produção e então tentar depurar onde está o problema. ✨
diff --git a/docs/pt/docs/advanced/index.md b/docs/pt/docs/advanced/index.md
index 413d8815f..22ba2bf4a 100644
--- a/docs/pt/docs/advanced/index.md
+++ b/docs/pt/docs/advanced/index.md
@@ -6,10 +6,13 @@ O [Tutorial - Guia de Usuário](../tutorial/index.md){.internal-link target=_bla
Na próxima seção você verá outras opções, configurações, e recursos adicionais.
-!!! tip "Dica"
- As próximas seções **não são necessáriamente "avançadas"**
+/// tip | Dica
- E é possível que para seu caso de uso, a solução esteja em uma delas.
+As próximas seções **não são necessáriamente "avançadas"**
+
+E é possível que para seu caso de uso, a solução esteja em uma delas.
+
+///
## Leia o Tutorial primeiro
diff --git a/docs/pt/docs/advanced/middleware.md b/docs/pt/docs/advanced/middleware.md
new file mode 100644
index 000000000..8167f7d27
--- /dev/null
+++ b/docs/pt/docs/advanced/middleware.md
@@ -0,0 +1,96 @@
+# Middleware Avançado
+
+No tutorial principal você leu como adicionar [Middleware Personalizado](../tutorial/middleware.md){.internal-link target=_blank} à sua aplicação.
+
+E então você também leu como lidar com [CORS com o `CORSMiddleware`](../tutorial/cors.md){.internal-link target=_blank}.
+
+Nesta seção, veremos como usar outros middlewares.
+
+## Adicionando middlewares ASGI
+
+Como o **FastAPI** é baseado no Starlette e implementa a especificação ASGI, você pode usar qualquer middleware ASGI.
+
+O middleware não precisa ser feito para o FastAPI ou Starlette para funcionar, desde que siga a especificação ASGI.
+
+No geral, os middlewares ASGI são classes que esperam receber um aplicativo ASGI como o primeiro argumento.
+
+Então, na documentação de middlewares ASGI de terceiros, eles provavelmente dirão para você fazer algo como:
+
+```Python
+from unicorn import UnicornMiddleware
+
+app = SomeASGIApp()
+
+new_app = UnicornMiddleware(app, some_config="rainbow")
+```
+
+Mas, o FastAPI (na verdade, o Starlette) fornece uma maneira mais simples de fazer isso que garante que os middlewares internos lidem com erros do servidor e que os manipuladores de exceções personalizados funcionem corretamente.
+
+Para isso, você usa `app.add_middleware()` (como no exemplo para CORS).
+
+```Python
+from fastapi import FastAPI
+from unicorn import UnicornMiddleware
+
+app = FastAPI()
+
+app.add_middleware(UnicornMiddleware, some_config="rainbow")
+```
+
+`app.add_middleware()` recebe uma classe de middleware como o primeiro argumento e quaisquer argumentos adicionais a serem passados para o middleware.
+
+## Middlewares Integrados
+
+**FastAPI** inclui vários middlewares para casos de uso comuns, veremos a seguir como usá-los.
+
+/// note | Detalhes Técnicos
+
+Para o próximo exemplo, você também poderia usar `from starlette.middleware.something import SomethingMiddleware`.
+
+**FastAPI** fornece vários middlewares em `fastapi.middleware` apenas como uma conveniência para você, o desenvolvedor. Mas a maioria dos middlewares disponíveis vem diretamente do Starlette.
+
+///
+
+## `HTTPSRedirectMiddleware`
+
+Garante que todas as requisições devem ser `https` ou `wss`.
+
+Qualquer requisição para `http` ou `ws` será redirecionada para o esquema seguro.
+
+{* ../../docs_src/advanced_middleware/tutorial001.py hl[2,6] *}
+
+## `TrustedHostMiddleware`
+
+Garante que todas as requisições recebidas tenham um cabeçalho `Host` corretamente configurado, a fim de proteger contra ataques de cabeçalho de host HTTP.
+
+{* ../../docs_src/advanced_middleware/tutorial002.py hl[2,6:8] *}
+
+Os seguintes argumentos são suportados:
+
+* `allowed_hosts` - Uma lista de nomes de domínio que são permitidos como nomes de host. Domínios com coringa, como `*.example.com`, são suportados para corresponder a subdomínios. Para permitir qualquer nome de host, use `allowed_hosts=["*"]` ou omita o middleware.
+
+Se uma requisição recebida não for validada corretamente, uma resposta `400` será enviada.
+
+## `GZipMiddleware`
+
+Gerencia respostas GZip para qualquer requisição que inclua `"gzip"` no cabeçalho `Accept-Encoding`.
+
+O middleware lidará com respostas padrão e de streaming.
+
+{* ../../docs_src/advanced_middleware/tutorial003.py hl[2,6] *}
+
+Os seguintes argumentos são suportados:
+
+* `minimum_size` - Não comprima respostas menores que este tamanho mínimo em bytes. O padrão é `500`.
+* `compresslevel` - Usado durante a compressão GZip. É um inteiro variando de 1 a 9. O padrão é `9`. Um valor menor resulta em uma compressão mais rápida, mas em arquivos maiores, enquanto um valor maior resulta em uma compressão mais lenta, mas em arquivos menores.
+
+## Outros middlewares
+
+Há muitos outros middlewares ASGI.
+
+Por exemplo:
+
+* Uvicorn's `ProxyHeadersMiddleware`
+* MessagePack
+
+Para checar outros middlewares disponíveis, confira Documentação de Middlewares do Starlette e a Lista Incrível do ASGI.
diff --git a/docs/pt/docs/advanced/openapi-callbacks.md b/docs/pt/docs/advanced/openapi-callbacks.md
new file mode 100644
index 000000000..b0659d3d6
--- /dev/null
+++ b/docs/pt/docs/advanced/openapi-callbacks.md
@@ -0,0 +1,186 @@
+# Callbacks na OpenAPI
+
+Você poderia criar uma API com uma *operação de rota* que poderia acionar uma solicitação a uma *API externa* criada por outra pessoa (provavelmente o mesmo desenvolvedor que estaria *usando* sua API).
+
+O processo que acontece quando seu aplicativo de API chama a *API externa* é chamado de "callback". Porque o software que o desenvolvedor externo escreveu envia uma solicitação para sua API e então sua API *chama de volta*, enviando uma solicitação para uma *API externa* (que provavelmente foi criada pelo mesmo desenvolvedor).
+
+Nesse caso, você poderia querer documentar como essa API externa *deveria* ser. Que *operação de rota* ela deveria ter, que corpo ela deveria esperar, que resposta ela deveria retornar, etc.
+
+## Um aplicativo com callbacks
+
+Vamos ver tudo isso com um exemplo.
+
+Imagine que você tem um aplicativo que permite criar faturas.
+
+Essas faturas terão um `id`, `title` (opcional), `customer` e `total`.
+
+O usuário da sua API (um desenvolvedor externo) criará uma fatura em sua API com uma solicitação POST.
+
+Então sua API irá (vamos imaginar):
+
+* Enviar uma solicitação de pagamento para o desenvolvedor externo.
+* Coletar o dinheiro.
+* Enviar a notificação de volta para o usuário da API (o desenvolvedor externo).
+* Isso será feito enviando uma solicitação POST (de *sua API*) para alguma *API externa* fornecida por esse desenvolvedor externo (este é o "callback").
+
+## O aplicativo **FastAPI** normal
+
+Vamos primeiro ver como o aplicativo da API normal se pareceria antes de adicionar o callback.
+
+Ele terá uma *operação de rota* que receberá um corpo `Invoice`, e um parâmetro de consulta `callback_url` que conterá a URL para o callback.
+
+Essa parte é bastante normal, a maior parte do código provavelmente já é familiar para você:
+
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[9:13,36:53] *}
+
+/// tip | Dica
+
+O parâmetro de consulta `callback_url` usa um tipo Pydantic Url.
+
+///
+
+A única coisa nova é o argumento `callbacks=invoices_callback_router.routes` no decorador da *operação de rota*. Veremos o que é isso a seguir.
+
+## Documentando o callback
+
+O código real do callback dependerá muito do seu próprio aplicativo de API.
+
+E provavelmente variará muito de um aplicativo para o outro.
+
+Poderia ser apenas uma ou duas linhas de código, como:
+
+```Python
+callback_url = "https://example.com/api/v1/invoices/events/"
+httpx.post(callback_url, json={"description": "Invoice paid", "paid": True})
+```
+
+Mas possivelmente a parte mais importante do callback é garantir que o usuário da sua API (o desenvolvedor externo) implemente a *API externa* corretamente, de acordo com os dados que *sua API* vai enviar no corpo da solicitação do callback, etc.
+
+Então, o que faremos a seguir é adicionar o código para documentar como essa *API externa* deve ser para receber o callback de *sua API*.
+
+A documentação aparecerá na interface do Swagger em `/docs` em sua API, e permitirá que os desenvolvedores externos saibam como construir a *API externa*.
+
+Esse exemplo não implementa o callback em si (que poderia ser apenas uma linha de código), apenas a parte da documentação.
+
+/// tip | Dica
+
+O callback real é apenas uma solicitação HTTP.
+
+Quando implementando o callback por você mesmo, você pode usar algo como HTTPX ou Requisições.
+
+///
+
+## Escrevendo o código de documentação do callback
+
+Esse código não será executado em seu aplicativo, nós só precisamos dele para *documentar* como essa *API externa* deveria ser.
+
+Mas, você já sabe como criar facilmente documentação automática para uma API com o **FastAPI**.
+
+Então vamos usar esse mesmo conhecimento para documentar como a *API externa* deveria ser... criando as *operações de rota* que a *API externa* deveria implementar (as que sua API irá chamar).
+
+/// tip | Dica
+
+Quando escrever o código para documentar um callback, pode ser útil imaginar que você é aquele *desenvolvedor externo*. E que você está atualmente implementando a *API externa*, não *sua API*.
+
+Adotar temporariamente esse ponto de vista (do *desenvolvedor externo*) pode ajudar a sentir que é mais óbvio onde colocar os parâmetros, o modelo Pydantic para o corpo, para a resposta, etc. para essa *API externa*.
+
+///
+
+### Criar um `APIRouter` para o callback
+
+Primeiramente crie um novo `APIRouter` que conterá um ou mais callbacks.
+
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[3,25] *}
+
+### Crie a *operação de rota* do callback
+
+Para criar a *operação de rota* do callback, use o mesmo `APIRouter` que você criou acima.
+
+Ele deve parecer exatamente como uma *operação de rota* normal do FastAPI:
+
+* Ele provavelmente deveria ter uma declaração do corpo que deveria receber, por exemplo. `body: InvoiceEvent`.
+* E também deveria ter uma declaração de um código de status de resposta, por exemplo. `response_model=InvoiceEventReceived`.
+
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[16:18,21:22,28:32] *}
+
+Há 2 diferenças principais de uma *operação de rota* normal:
+
+* Ela não necessita ter nenhum código real, porque seu aplicativo nunca chamará esse código. Ele é usado apenas para documentar a *API externa*. Então, a função poderia ter apenas `pass`.
+* A *rota* pode conter uma expressão OpenAPI 3 (veja mais abaixo) onde pode usar variáveis com parâmetros e partes da solicitação original enviada para *sua API*.
+
+### A expressão do caminho do callback
+
+A *rota* do callback pode ter uma expressão OpenAPI 3 que pode conter partes da solicitação original enviada para *sua API*.
+
+Nesse caso, é a `str`:
+
+```Python
+"{$callback_url}/invoices/{$request.body.id}"
+```
+
+Então, se o usuário da sua API (o desenvolvedor externo) enviar uma solicitação para *sua API* para:
+
+```
+https://yourapi.com/invoices/?callback_url=https://www.external.org/events
+```
+
+com um corpo JSON de:
+
+```JSON
+{
+ "id": "2expen51ve",
+ "customer": "Mr. Richie Rich",
+ "total": "9999"
+}
+```
+
+então *sua API* processará a fatura e, em algum momento posterior, enviará uma solicitação de callback para o `callback_url` (a *API externa*):
+
+```
+https://www.external.org/events/invoices/2expen51ve
+```
+
+com um corpo JSON contendo algo como:
+
+```JSON
+{
+ "description": "Payment celebration",
+ "paid": true
+}
+```
+
+e esperaria uma resposta daquela *API externa* com um corpo JSON como:
+
+```JSON
+{
+ "ok": true
+}
+```
+
+/// tip | Dica
+
+Perceba como a URL de callback usada contém a URL recebida como um parâmetro de consulta em `callback_url` (`https://www.external.org/events`) e também o `id` da fatura de dentro do corpo JSON (`2expen51ve`).
+
+///
+
+### Adicionar o roteador de callback
+
+Nesse ponto você tem a(s) *operação de rota de callback* necessária(s) (a(s) que o *desenvolvedor externo* deveria implementar na *API externa*) no roteador de callback que você criou acima.
+
+Agora use o parâmetro `callbacks` no decorador da *operação de rota de sua API* para passar o atributo `.routes` (que é na verdade apenas uma `list` de rotas/*operações de rota*) do roteador de callback que você criou acima:
+
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[35] *}
+
+/// tip | Dica
+
+Perceba que você não está passando o roteador em si (`invoices_callback_router`) para `callback=`, mas o atributo `.routes`, como em `invoices_callback_router.routes`.
+
+///
+
+### Verifique a documentação
+
+Agora você pode iniciar seu aplicativo e ir para http://127.0.0.1:8000/docs.
+
+Você verá sua documentação incluindo uma seção "Callbacks" para sua *operação de rota* que mostra como a *API externa* deveria ser:
+
+
diff --git a/docs/pt/docs/advanced/openapi-webhooks.md b/docs/pt/docs/advanced/openapi-webhooks.md
index 932fe0d9a..f35922234 100644
--- a/docs/pt/docs/advanced/openapi-webhooks.md
+++ b/docs/pt/docs/advanced/openapi-webhooks.md
@@ -22,21 +22,25 @@ Com o **FastAPI**, utilizando o OpenAPI, você pode definir os nomes destes webh
Isto pode facilitar bastante para os seus usuários **implementarem as APIs deles** para receber as requisições dos seus **webhooks**, eles podem inclusive ser capazes de gerar parte do código da API deles.
-!!! info "Informação"
- Webhooks estão disponíveis a partir do OpenAPI 3.1.0, e possui suporte do FastAPI a partir da versão `0.99.0`.
+/// info | Informação
+
+Webhooks estão disponíveis a partir do OpenAPI 3.1.0, e possui suporte do FastAPI a partir da versão `0.99.0`.
+
+///
## Uma aplicação com webhooks
Quando você cria uma aplicação com o **FastAPI**, existe um atributo chamado `webhooks`, que você utilizar para defini-los da mesma maneira que você definiria as suas **operações de rotas**, utilizando por exemplo `@app.webhooks.post()`.
-```Python hl_lines="9-13 36-53"
-{!../../../docs_src/openapi_webhooks/tutorial001.py!}
-```
+{* ../../docs_src/openapi_webhooks/tutorial001.py hl[9:13,36:53] *}
Os webhooks que você define aparecerão no esquema do **OpenAPI** e na **página de documentação** gerada automaticamente.
-!!! info "Informação"
- O objeto `app.webhooks` é na verdade apenas um `APIRouter`, o mesmo tipo que você utilizaria ao estruturar a sua aplicação com diversos arquivos.
+/// info | Informação
+
+O objeto `app.webhooks` é na verdade apenas um `APIRouter`, o mesmo tipo que você utilizaria ao estruturar a sua aplicação com diversos arquivos.
+
+///
Note que utilizando webhooks você não está de fato declarando uma **rota** (como `/items/`), o texto que informa é apenas um **identificador** do webhook (o nome do evento), por exemplo em `@app.webhooks.post("new-subscription")`, o nome do webhook é `new-subscription`.
diff --git a/docs/pt/docs/advanced/path-operation-advanced-configuration.md b/docs/pt/docs/advanced/path-operation-advanced-configuration.md
new file mode 100644
index 000000000..411d0f9a7
--- /dev/null
+++ b/docs/pt/docs/advanced/path-operation-advanced-configuration.md
@@ -0,0 +1,204 @@
+# Configuração Avançada da Operação de Rota
+
+## operationId do OpenAPI
+
+/// warning | Aviso
+
+Se você não é um "especialista" no OpenAPI, você provavelmente não precisa disso.
+
+///
+
+Você pode definir o `operationId` do OpenAPI que será utilizado na sua *operação de rota* com o parâmetro `operation_id`.
+
+Você precisa ter certeza que ele é único para cada operação.
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial001.py hl[6] *}
+
+### Utilizando o nome da *função de operação de rota* como o operationId
+
+Se você quiser utilizar o nome das funções da sua API como `operationId`s, você pode iterar sobre todos esses nomes e sobrescrever o `operationId` em cada *operação de rota* utilizando o `APIRoute.name` dela.
+
+Você deve fazer isso depois de adicionar todas as suas *operações de rota*.
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial002.py hl[2,12:21,24] *}
+
+/// tip | Dica
+
+Se você chamar `app.openapi()` manualmente, os `operationId`s devem ser atualizados antes dessa chamada.
+
+///
+
+/// warning | Aviso
+
+Se você fizer isso, você tem que ter certeza de que cada uma das suas *funções de operação de rota* tem um nome único.
+
+Mesmo que elas estejam em módulos (arquivos Python) diferentes.
+
+///
+
+## Excluir do OpenAPI
+
+Para excluir uma *operação de rota* do esquema OpenAPI gerado (e por consequência, dos sistemas de documentação automáticos), utilize o parâmetro `include_in_schema` e defina ele como `False`:
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial003.py hl[6] *}
+
+## Descrição avançada a partir de docstring
+
+Você pode limitar as linhas utilizadas a partir de uma docstring de uma *função de operação de rota* para o OpenAPI.
+
+Adicionar um `\f` (um caractere de escape para alimentação de formulário) faz com que o **FastAPI** restrinja a saída utilizada pelo OpenAPI até esse ponto.
+
+Ele não será mostrado na documentação, mas outras ferramentas (como o Sphinx) serão capazes de utilizar o resto do texto.
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial004.py hl[19:29] *}
+
+## Respostas Adicionais
+
+Você provavelmente já viu como declarar o `response_model` e `status_code` para uma *operação de rota*.
+
+Isso define os metadados sobre a resposta principal da *operação de rota*.
+
+Você também pode declarar respostas adicionais, com seus modelos, códigos de status, etc.
+
+Existe um capítulo inteiro da nossa documentação sobre isso, você pode ler em [Retornos Adicionais no OpenAPI](additional-responses.md){.internal-link target=_blank}.
+
+## Extras do OpenAPI
+
+Quando você declara uma *operação de rota* na sua aplicação, o **FastAPI** irá gerar os metadados relevantes da *operação de rota* automaticamente para serem incluídos no esquema do OpenAPI.
+
+/// note | Nota
+
+Na especificação do OpenAPI, isso é chamado de um Objeto de Operação.
+
+///
+
+Ele possui toda a informação sobre a *operação de rota* e é usado para gerar a documentação automaticamente.
+
+Ele inclui os atributos `tags`, `parameters`, `requestBody`, `responses`, etc.
+
+Esse esquema específico para uma *operação de rota* normalmente é gerado automaticamente pelo **FastAPI**, mas você também pode estender ele.
+
+/// tip | Dica
+
+Esse é um ponto de extensão de baixo nível.
+
+Caso você só precise declarar respostas adicionais, uma forma conveniente de fazer isso é com [Retornos Adicionais no OpenAPI](additional-responses.md){.internal-link target=_blank}.
+
+///
+
+Você pode estender o esquema do OpenAPI para uma *operação de rota* utilizando o parâmetro `openapi_extra`.
+
+### Extensões do OpenAPI
+
+Esse parâmetro `openapi_extra` pode ser útil, por exemplo, para declarar [Extensões do OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions):
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial005.py hl[6] *}
+
+Se você abrir os documentos criados automaticamente para a API, sua extensão aparecerá no final da *operação de rota* específica.
+
+
+
+E se você olhar o esquema OpenAPI resultante (na rota `/openapi.json` da sua API), você verá que a sua extensão também faz parte da *operação de rota* específica:
+
+```JSON hl_lines="22"
+{
+ "openapi": "3.1.0",
+ "info": {
+ "title": "FastAPI",
+ "version": "0.1.0"
+ },
+ "paths": {
+ "/items/": {
+ "get": {
+ "summary": "Read Items",
+ "operationId": "read_items_items__get",
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": {}
+ }
+ }
+ }
+ },
+ "x-aperture-labs-portal": "blue"
+ }
+ }
+ }
+}
+```
+
+### Esquema de *operação de rota* do OpenAPI personalizado
+
+O dicionário em `openapi_extra` vai ter todos os seus níveis mesclados dentro do esquema OpenAPI gerado automaticamente para a *operação de rota*.
+
+Então, você pode adicionar dados extras para o esquema gerado automaticamente.
+
+Por exemplo, você poderia optar por ler e validar a requisição com seu próprio código, sem utilizar funcionalidades automatizadas do FastAPI com o Pydantic, mas você ainda pode quere definir a requisição no esquema OpenAPI.
+
+Você pode fazer isso com `openapi_extra`:
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial006.py hl[19:36,39:40] *}
+
+Nesse exemplo, nós não declaramos nenhum modelo do Pydantic. Na verdade, o corpo da requisição não está nem mesmo analisado como JSON, ele é lido diretamente como `bytes` e a função `magic_data_reader()` seria a responsável por analisar ele de alguma forma.
+
+De toda forma, nós podemos declarar o esquema esperado para o corpo da requisição.
+
+### Tipo de conteúdo do OpenAPI personalizado
+
+Utilizando esse mesmo truque, você pode utilizar um modelo Pydantic para definir o esquema JSON que é então incluído na seção do esquema personalizado do OpenAPI na *operação de rota*.
+
+E você pode fazer isso até mesmo quando os dados da requisição não seguem o formato JSON.
+
+Por exemplo, nesta aplicação nós não usamos a funcionalidade integrada ao FastAPI de extrair o esquema JSON dos modelos Pydantic nem a validação automática do JSON. Na verdade, estamos declarando o tipo do conteúdo da requisição como YAML, em vez de JSON:
+
+//// tab | Pydantic v2
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[17:22,24] *}
+
+////
+
+//// tab | Pydantic v1
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py hl[17:22,24] *}
+
+////
+
+/// info | Informação
+
+Na versão 1 do Pydantic, o método para obter o esquema JSON de um modelo é `Item.schema()`, na versão 2 do Pydantic, o método é `Item.model_json_schema()`
+
+///
+
+Entretanto, mesmo que não utilizemos a funcionalidade integrada por padrão, ainda estamos usando um modelo Pydantic para gerar um esquema JSON manualmente para os dados que queremos receber no formato YAML.
+
+Então utilizamos a requisição diretamente, e extraímos o corpo como `bytes`. Isso significa que o FastAPI não vai sequer tentar analisar o corpo da requisição como JSON.
+
+E então no nosso código, nós analisamos o conteúdo YAML diretamente, e estamos utilizando o mesmo modelo Pydantic para validar o conteúdo YAML:
+
+//// tab | Pydantic v2
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[26:33] *}
+
+////
+
+//// tab | Pydantic v1
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py hl[26:33] *}
+
+////
+
+/// info | Informação
+
+Na versão 1 do Pydantic, o método para analisar e validar um objeto era `Item.parse_obj()`, na versão 2 do Pydantic, o método é chamado de `Item.model_validate()`.
+
+///
+
+///tip | Dica
+
+Aqui reutilizamos o mesmo modelo do Pydantic.
+
+Mas da mesma forma, nós poderíamos ter validado de alguma outra forma.
+
+///
diff --git a/docs/pt/docs/advanced/response-change-status-code.md b/docs/pt/docs/advanced/response-change-status-code.md
index 99695c831..358c12d54 100644
--- a/docs/pt/docs/advanced/response-change-status-code.md
+++ b/docs/pt/docs/advanced/response-change-status-code.md
@@ -20,9 +20,7 @@ Você pode declarar um parâmetro do tipo `Response` em sua *função de operaç
E então você pode definir o `status_code` neste objeto de retorno temporal.
-```Python hl_lines="1 9 12"
-{!../../../docs_src/response_change_status_code/tutorial001.py!}
-```
+{* ../../docs_src/response_change_status_code/tutorial001.py hl[1,9,12] *}
E então você pode retornar qualquer objeto que você precise, como você faria normalmente (um `dict`, um modelo de banco de dados, etc.).
diff --git a/docs/pt/docs/advanced/response-cookies.md b/docs/pt/docs/advanced/response-cookies.md
new file mode 100644
index 000000000..eed69f222
--- /dev/null
+++ b/docs/pt/docs/advanced/response-cookies.md
@@ -0,0 +1,51 @@
+# Cookies de Resposta
+
+## Usando um parâmetro `Response`
+
+Você pode declarar um parâmetro do tipo `Response` na sua *função de operação de rota*.
+
+E então você pode definir cookies nesse objeto de resposta *temporário*.
+
+{* ../../docs_src/response_cookies/tutorial002.py hl[1,8:9] *}
+
+Em seguida, você pode retornar qualquer objeto que precise, como normalmente faria (um `dict`, um modelo de banco de dados, etc).
+
+E se você declarou um `response_model`, ele ainda será usado para filtrar e converter o objeto que você retornou.
+
+**FastAPI** usará essa resposta *temporária* para extrair os cookies (também os cabeçalhos e código de status) e os colocará na resposta final que contém o valor que você retornou, filtrado por qualquer `response_model`.
+
+Você também pode declarar o parâmetro `Response` em dependências e definir cookies (e cabeçalhos) nelas.
+
+## Retornando uma `Response` diretamente
+
+Você também pode criar cookies ao retornar uma `Response` diretamente no seu código.
+
+Para fazer isso, você pode criar uma resposta como descrito em [Retornando uma Resposta Diretamente](response-directly.md){.internal-link target=_blank}.
+
+Então, defina os cookies nela e a retorne:
+
+{* ../../docs_src/response_cookies/tutorial001.py hl[10:12] *}
+
+/// tip | Dica
+
+Lembre-se de que se você retornar uma resposta diretamente em vez de usar o parâmetro `Response`, FastAPI a retornará diretamente.
+
+Portanto, você terá que garantir que seus dados sejam do tipo correto. E.g. será compatível com JSON se você estiver retornando um `JSONResponse`.
+
+E também que você não esteja enviando nenhum dado que deveria ter sido filtrado por um `response_model`.
+
+///
+
+### Mais informações
+
+/// note | Detalhes Técnicos
+
+Você também poderia usar `from starlette.responses import Response` ou `from starlette.responses import JSONResponse`.
+
+**FastAPI** fornece as mesmas `starlette.responses` em `fastapi.responses` apenas como uma conveniência para você, o desenvolvedor. Mas a maioria das respostas disponíveis vem diretamente do Starlette.
+
+E como o `Response` pode ser usado frequentemente para definir cabeçalhos e cookies, o **FastAPI** também o fornece em `fastapi.Response`.
+
+///
+
+Para ver todos os parâmetros e opções disponíveis, verifique a documentação no Starlette.
diff --git a/docs/pt/docs/advanced/response-directly.md b/docs/pt/docs/advanced/response-directly.md
new file mode 100644
index 000000000..ea717be00
--- /dev/null
+++ b/docs/pt/docs/advanced/response-directly.md
@@ -0,0 +1,66 @@
+# Retornando uma Resposta Diretamente
+
+Quando você cria uma *operação de rota* no **FastAPI** você pode retornar qualquer dado nela: um dicionário (`dict`), uma lista (`list`), um modelo do Pydantic ou do seu banco de dados, etc.
+
+Por padrão, o **FastAPI** irá converter automaticamente o valor do retorno para JSON utilizando o `jsonable_encoder` explicado em [JSON Compatible Encoder](../tutorial/encoder.md){.internal-link target=_blank}.
+
+Então, por baixo dos panos, ele incluiria esses dados compatíveis com JSON (e.g. um `dict`) dentro de uma `JSONResponse` que é utilizada para enviar uma resposta para o cliente.
+
+Mas você pode retornar a `JSONResponse` diretamente nas suas *operações de rota*.
+
+Pode ser útil para retornar cabeçalhos e cookies personalizados, por exemplo.
+
+## Retornando uma `Response`
+
+Na verdade, você pode retornar qualquer `Response` ou subclasse dela.
+
+/// tip | Dica
+
+A própria `JSONResponse` é uma subclasse de `Response`.
+
+///
+
+E quando você retorna uma `Response`, o **FastAPI** vai repassá-la diretamente.
+
+Ele não vai fazer conversões de dados com modelos do Pydantic, não irá converter a tipagem de nenhum conteúdo, etc.
+
+Isso te dá bastante flexibilidade. Você pode retornar qualquer tipo de dado, sobrescrever qualquer declaração e validação nos dados, etc.
+
+## Utilizando o `jsonable_encoder` em uma `Response`
+
+Como o **FastAPI** não realiza nenhuma mudança na `Response` que você retorna, você precisa garantir que o conteúdo dela está pronto para uso.
+
+Por exemplo, você não pode colocar um modelo do Pydantic em uma `JSONResponse` sem antes convertê-lo em um `dict` com todos os tipos de dados (como `datetime`, `UUID`, etc) convertidos para tipos compatíveis com JSON.
+
+Para esses casos, você pode usar o `jsonable_encoder` para converter seus dados antes de repassá-los para a resposta:
+
+{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *}
+
+/// note | Detalhes Técnicos
+
+Você também pode utilizar `from starlette.responses import JSONResponse`.
+
+**FastAPI** utiliza a mesma `starlette.responses` como `fastapi.responses` apenas como uma conveniência para você, desenvolvedor. Mas maior parte das respostas disponíveis vem diretamente do Starlette.
+
+///
+
+## Retornando uma `Response`
+
+O exemplo acima mostra todas as partes que você precisa, mas ainda não é muito útil, já que você poderia ter retornado o `item` diretamente, e o **FastAPI** colocaria em uma `JSONResponse` para você, convertendo em um `dict`, etc. Tudo isso por padrão.
+
+Agora, vamos ver como você pode usar isso para retornar uma resposta personalizada.
+
+Vamos dizer quer retornar uma resposta XML.
+
+Você pode colocar o seu conteúdo XML em uma string, colocar em uma `Response`, e retorná-lo:
+
+{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
+
+## Notas
+
+Quando você retorna uma `Response` diretamente os dados não são validados, convertidos (serializados) ou documentados automaticamente.
+
+Mas você ainda pode documentar como descrito em [Retornos Adicionais no OpenAPI
+](additional-responses.md){.internal-link target=_blank}.
+
+Você pode ver nas próximas seções como usar/declarar essas `Responses` customizadas enquanto mantém a conversão e documentação automática dos dados.
diff --git a/docs/pt/docs/advanced/response-headers.md b/docs/pt/docs/advanced/response-headers.md
new file mode 100644
index 000000000..a8034a7a4
--- /dev/null
+++ b/docs/pt/docs/advanced/response-headers.md
@@ -0,0 +1,41 @@
+# Cabeçalhos de resposta
+
+## Usando um parâmetro `Response`
+
+Você pode declarar um parâmetro do tipo `Response` na sua *função de operação de rota* (assim como você pode fazer para cookies).
+
+Então você pode definir os cabeçalhos nesse objeto de resposta *temporário*.
+
+{* ../../docs_src/response_headers/tutorial002.py hl[1,7:8] *}
+
+Em seguida você pode retornar qualquer objeto que precisar, da maneira que faria normalmente (um `dict`, um modelo de banco de dados, etc.).
+
+Se você declarou um `response_model`, ele ainda será utilizado para filtrar e converter o objeto que você retornou.
+
+**FastAPI** usará essa resposta *temporária* para extrair os cabeçalhos (cookies e código de status também) e os colocará na resposta final que contém o valor que você retornou, filtrado por qualquer `response_model`.
+
+Você também pode declarar o parâmetro `Response` em dependências e definir cabeçalhos (e cookies) nelas.
+
+## Retornar uma `Response` diretamente
+
+Você também pode adicionar cabeçalhos quando retornar uma `Response` diretamente.
+
+Crie uma resposta conforme descrito em [Retornar uma resposta diretamente](response-directly.md){.internal-link target=_blank} e passe os cabeçalhos como um parâmetro adicional:
+
+{* ../../docs_src/response_headers/tutorial001.py hl[10:12] *}
+
+/// note | Detalhes técnicos
+
+Você também pode usar `from starlette.responses import Response` ou `from starlette.responses import JSONResponse`.
+
+**FastAPI** fornece as mesmas `starlette.responses` como `fastapi.responses` apenas como uma conveniência para você, desenvolvedor. Mas a maioria das respostas disponíveis vem diretamente do Starlette.
+
+E como a `Response` pode ser usada frequentemente para definir cabeçalhos e cookies, **FastAPI** também a fornece em `fastapi.Response`.
+
+///
+
+## Cabeçalhos personalizados
+
+Tenha em mente que cabeçalhos personalizados proprietários podem ser adicionados usando o prefixo 'X-'.
+
+Porém, se voce tiver cabeçalhos personalizados que deseja que um cliente no navegador possa ver, você precisa adicioná-los às suas configurações de CORS (saiba mais em [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md){.internal-link target=_blank}), usando o parâmetro `expose_headers` descrito na documentação de CORS do Starlette.
diff --git a/docs/pt/docs/advanced/security/http-basic-auth.md b/docs/pt/docs/advanced/security/http-basic-auth.md
new file mode 100644
index 000000000..331513927
--- /dev/null
+++ b/docs/pt/docs/advanced/security/http-basic-auth.md
@@ -0,0 +1,108 @@
+# HTTP Basic Auth
+
+Para os casos mais simples, você pode utilizar o HTTP Basic Auth.
+
+No HTTP Basic Auth, a aplicação espera um cabeçalho que contém um usuário e uma senha.
+
+Caso ela não receba, ela retorna um erro HTTP 401 "Unauthorized" (*Não Autorizado*).
+
+E retorna um cabeçalho `WWW-Authenticate` com o valor `Basic`, e um parâmetro opcional `realm`.
+
+Isso sinaliza ao navegador para mostrar o prompt integrado para um usuário e senha.
+
+Então, quando você digitar o usuário e senha, o navegador os envia automaticamente no cabeçalho.
+
+## HTTP Basic Auth Simples
+
+* Importe `HTTPBasic` e `HTTPBasicCredentials`.
+* Crie um "esquema `security`" utilizando `HTTPBasic`.
+* Utilize o `security` com uma dependência em sua *operação de rota*.
+* Isso retorna um objeto do tipo `HTTPBasicCredentials`:
+ * Isto contém o `username` e o `password` enviado.
+
+{* ../../docs_src/security/tutorial006_an_py39.py hl[4,8,12] *}
+
+Quando você tentar abrir a URL pela primeira vez (ou clicar no botão "Executar" nos documentos) o navegador vai pedir pelo seu usuário e senha:
+
+
+
+## Verifique o usuário
+
+Aqui está um exemplo mais completo.
+
+Utilize uma dependência para verificar se o usuário e a senha estão corretos.
+
+Para isso, utilize o módulo padrão do Python `secrets` para verificar o usuário e senha.
+
+O `secrets.compare_digest()` necessita receber `bytes` ou `str` que possuem apenas caracteres ASCII (os em inglês). Isso significa que não funcionaria com caracteres como o `á`, como em `Sebastián`.
+
+Para lidar com isso, primeiramente nós convertemos o `username` e o `password` para `bytes`, codificando-os com UTF-8.
+
+Então nós podemos utilizar o `secrets.compare_digest()` para garantir que o `credentials.username` é `"stanleyjobson"`, e que o `credentials.password` é `"swordfish"`.
+
+{* ../../docs_src/security/tutorial007_an_py39.py hl[1,12:24] *}
+
+Isso seria parecido com:
+
+```Python
+if not (credentials.username == "stanleyjobson") or not (credentials.password == "swordfish"):
+ # Return some error
+ ...
+```
+
+Porém, ao utilizar o `secrets.compare_digest()`, isso estará seguro contra um tipo de ataque chamado "timing attacks" (ataques de temporização).
+
+### Ataques de Temporização
+
+Mas o que é um "timing attack" (ataque de temporização)?
+
+Vamos imaginar que alguns invasores estão tentando adivinhar o usuário e a senha.
+
+E eles enviam uma requisição com um usuário `johndoe` e uma senha `love123`.
+
+Então o código Python em sua aplicação seria equivalente a algo como:
+
+```Python
+if "johndoe" == "stanleyjobson" and "love123" == "swordfish":
+ ...
+```
+
+Mas no exato momento que o Python compara o primeiro `j` em `johndoe` contra o primeiro `s` em `stanleyjobson`, ele retornará `False`, porque ele já sabe que aquelas duas strings não são a mesma, pensando que "não existe a necessidade de desperdiçar mais poder computacional comparando o resto das letras". E a sua aplicação dirá "Usuário ou senha incorretos".
+
+Então os invasores vão tentar com o usuário `stanleyjobsox` e a senha `love123`.
+
+E a sua aplicação faz algo como:
+
+```Python
+if "stanleyjobsox" == "stanleyjobson" and "love123" == "swordfish":
+ ...
+```
+
+O Python terá que comparar todo o `stanleyjobso` tanto em `stanleyjobsox` como em `stanleyjobson` antes de perceber que as strings não são a mesma. Então isso levará alguns microssegundos a mais para retornar "Usuário ou senha incorretos".
+
+#### O tempo para responder ajuda os invasores
+
+Neste ponto, ao perceber que o servidor demorou alguns microssegundos a mais para enviar o retorno "Usuário ou senha incorretos", os invasores irão saber que eles acertaram _alguma coisa_, algumas das letras iniciais estavam certas.
+
+E eles podem tentar de novo sabendo que provavelmente é algo mais parecido com `stanleyjobsox` do que com `johndoe`.
+
+#### Um ataque "profissional"
+
+Claro, os invasores não tentariam tudo isso de forma manual, eles escreveriam um programa para fazer isso, possivelmente com milhares ou milhões de testes por segundo. E obteriam apenas uma letra a mais por vez.
+
+Mas fazendo isso, em alguns minutos ou horas os invasores teriam adivinhado o usuário e senha corretos, com a "ajuda" da nossa aplicação, apenas usando o tempo levado para responder.
+
+#### Corrija com o `secrets.compare_digest()`
+
+Mas em nosso código já estamos utilizando o `secrets.compare_digest()`.
+
+Resumindo, levará o mesmo tempo para comparar `stanleyjobsox` com `stanleyjobson` do que comparar `johndoe` com `stanleyjobson`. E o mesmo para a senha.
+
+Deste modo, ao utilizar `secrets.compare_digest()` no código de sua aplicação, ela estará a salvo contra toda essa gama de ataques de segurança.
+
+
+### Retorne o erro
+
+Após detectar que as credenciais estão incorretas, retorne um `HTTPException` com o status 401 (o mesmo retornado quando nenhuma credencial foi informada) e adicione o cabeçalho `WWW-Authenticate` para fazer com que o navegador mostre o prompt de login novamente:
+
+{* ../../docs_src/security/tutorial007_an_py39.py hl[26:30] *}
diff --git a/docs/pt/docs/advanced/security/index.md b/docs/pt/docs/advanced/security/index.md
new file mode 100644
index 000000000..6c7becb67
--- /dev/null
+++ b/docs/pt/docs/advanced/security/index.md
@@ -0,0 +1,19 @@
+# Segurança Avançada
+
+## Funcionalidades Adicionais
+
+Existem algumas funcionalidades adicionais para lidar com segurança além das cobertas em [Tutorial - Guia de Usuário: Segurança](../../tutorial/security/index.md){.internal-link target=_blank}.
+
+/// tip | Dica
+
+As próximas seções **não são necessariamente "avançadas"**.
+
+E é possível que para o seu caso de uso, a solução está em uma delas.
+
+///
+
+## Leia o Tutorial primeiro
+
+As próximas seções pressupõem que você já leu o principal [Tutorial - Guia de Usuário: Segurança](../../tutorial/security/index.md){.internal-link target=_blank}.
+
+Todas elas são baseadas nos mesmos conceitos, mas permitem algumas funcionalidades extras.
diff --git a/docs/pt/docs/advanced/security/oauth2-scopes.md b/docs/pt/docs/advanced/security/oauth2-scopes.md
new file mode 100644
index 000000000..1d53f42d8
--- /dev/null
+++ b/docs/pt/docs/advanced/security/oauth2-scopes.md
@@ -0,0 +1,274 @@
+# Escopos OAuth2
+
+Você pode utilizar escopos do OAuth2 diretamente com o **FastAPI**, eles são integrados para funcionar perfeitamente.
+
+Isso permitiria que você tivesse um sistema de permissionamento mais refinado, seguindo o padrão do OAuth2 integrado na sua aplicação OpenAPI (e as documentações da API).
+
+OAuth2 com escopos é o mecanismo utilizado por muitos provedores de autenticação, como o Facebook, Google, GitHub, Microsoft, Twitter, etc. Eles utilizam isso para prover permissões específicas para os usuários e aplicações.
+
+Toda vez que você "se autentica com" Facebook, Google, GitHub, Microsoft, Twitter, aquela aplicação está utilizando o OAuth2 com escopos.
+
+Nesta seção, você verá como gerenciar a autenticação e autorização com os mesmos escopos do OAuth2 em sua aplicação **FastAPI**.
+
+/// warning | Aviso
+
+Isso é uma seção mais ou menos avançada. Se você está apenas começando, você pode pular.
+
+Você não necessariamente precisa de escopos do OAuth2, e você pode lidar com autenticação e autorização da maneira que você achar melhor.
+
+Mas o OAuth2 com escopos pode ser integrado de maneira fácil em sua API (com OpenAPI) e a sua documentação de API.
+
+No entando, você ainda aplica estes escopos, ou qualquer outro requisito de segurança/autorização, conforme necessário, em seu código.
+
+Em muitos casos, OAuth2 com escopos pode ser um exagero.
+
+Mas se você sabe que precisa, ou está curioso, continue lendo.
+
+///
+
+## Escopos OAuth2 e OpenAPI
+
+A especificação OAuth2 define "escopos" como uma lista de strings separadas por espaços.
+
+O conteúdo de cada uma dessas strings pode ter qualquer formato, mas não devem possuir espaços.
+
+Estes escopos representam "permissões".
+
+No OpenAPI (e.g. os documentos da API), você pode definir "esquemas de segurança".
+
+Quando um desses esquemas de segurança utiliza OAuth2, você pode também declarar e utilizar escopos.
+
+Cada "escopo" é apenas uma string (sem espaços).
+
+Eles são normalmente utilizados para declarar permissões de segurança específicas, como por exemplo:
+
+* `users:read` or `users:write` são exemplos comuns.
+* `instagram_basic` é utilizado pelo Facebook / Instagram.
+* `https://www.googleapis.com/auth/drive` é utilizado pelo Google.
+
+/// info | Informação
+
+No OAuth2, um "escopo" é apenas uma string que declara uma permissão específica necessária.
+
+Não importa se ela contém outros caracteres como `:` ou se ela é uma URL.
+
+Estes detalhes são específicos da implementação.
+
+Para o OAuth2, eles são apenas strings.
+
+///
+
+## Visão global
+
+Primeiro, vamos olhar rapidamente as partes que mudam dos exemplos do **Tutorial - Guia de Usuário** para [OAuth2 com Senha (e hash), Bearer com tokens JWT](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank}. Agora utilizando escopos OAuth2:
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,65,106,108:116,122:125,129:135,140,156] *}
+
+Agora vamos revisar essas mudanças passo a passo.
+
+## Esquema de segurança OAuth2
+
+A primeira mudança é que agora nós estamos declarando o esquema de segurança OAuth2 com dois escopos disponíveis, `me` e `items`.
+
+O parâmetro `scopes` recebe um `dict` contendo cada escopo como chave e a descrição como valor:
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[63:66] *}
+
+Pelo motivo de estarmos declarando estes escopos, eles aparecerão nos documentos da API quando você se autenticar/autorizar.
+
+E você poderá selecionar quais escopos você deseja dar acesso: `me` e `items`.
+
+Este é o mesmo mecanismo utilizado quando você adiciona permissões enquanto se autentica com o Facebook, Google, GitHub, etc:
+
+
+
+## Token JWT com escopos
+
+Agora, modifique o *caminho de rota* para retornar os escopos solicitados.
+
+Nós ainda estamos utilizando o mesmo `OAuth2PasswordRequestForm`. Ele inclui a propriedade `scopes` com uma `list` de `str`, com cada escopo que ele recebeu na requisição.
+
+E nós retornamos os escopos como parte do token JWT.
+
+/// danger | Cuidado
+
+Para manter as coisas simples, aqui nós estamos apenas adicionando os escopos recebidos diretamente ao token.
+
+Porém em sua aplicação, por segurança, você deve garantir que você apenas adiciona os escopos que o usuário possui permissão de fato, ou aqueles que você predefiniu.
+
+///
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[156] *}
+
+## Declare escopos em *operações de rota* e dependências
+
+Agora nós declaramos que a *operação de rota* para `/users/me/items/` exige o escopo `items`.
+
+Para isso, nós importamos e utilizamos `Security` de `fastapi`.
+
+Você pode utilizar `Security` para declarar dependências (assim como `Depends`), porém o `Security` também recebe o parâmetros `scopes` com uma lista de escopos (strings).
+
+Neste caso, nós passamos a função `get_current_active_user` como dependência para `Security` (da mesma forma que nós faríamos com `Depends`).
+
+Mas nós também passamos uma `list` de escopos, neste caso com apenas um escopo: `items` (poderia ter mais).
+
+E a função de dependência `get_current_active_user` também pode declarar subdependências, não apenas com `Depends`, mas também com `Security`. Ao declarar sua própria função de subdependência (`get_current_user`), e mais requisitos de escopo.
+
+Neste caso, ele requer o escopo `me` (poderia requerer mais de um escopo).
+
+/// note | Nota
+
+Você não necessariamente precisa adicionar diferentes escopos em diferentes lugares.
+
+Nós estamos fazendo isso aqui para demonstrar como o **FastAPI** lida com escopos declarados em diferentes níveis.
+
+///
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[5,140,171] *}
+
+/// info | Informações Técnicas
+
+`Security` é na verdade uma subclasse de `Depends`, e ele possui apenas um parâmetro extra que veremos depois.
+
+Porém ao utilizar `Security` no lugar de `Depends`, o **FastAPI** saberá que ele pode declarar escopos de segurança, utilizá-los internamente, e documentar a API com o OpenAPI.
+
+Mas quando você importa `Query`, `Path`, `Depends`, `Security` entre outros de `fastapi`, eles são na verdade funções que retornam classes especiais.
+
+///
+
+## Utilize `SecurityScopes`
+
+Agora atualize a dependência `get_current_user`.
+
+Este é o usado pelas dependências acima.
+
+Aqui é onde estamos utilizando o mesmo esquema OAuth2 que nós declaramos antes, declarando-o como uma dependência: `oauth2_scheme`.
+
+Porque esta função de dependência não possui nenhum requerimento de escopo, nós podemos utilizar `Depends` com o `oauth2_scheme`. Nós não precisamos utilizar `Security` quando nós não precisamos especificar escopos de segurança.
+
+Nós também declaramos um parâmetro especial do tipo `SecurityScopes`, importado de `fastapi.security`.
+
+A classe `SecurityScopes` é semelhante à classe `Request` (`Request` foi utilizada para obter o objeto da requisição diretamente).
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[9,106] *}
+
+## Utilize os `scopes`
+
+O parâmetro `security_scopes` será do tipo `SecurityScopes`.
+
+Ele terá a propriedade `scopes` com uma lista contendo todos os escopos requeridos por ele e todas as dependências que utilizam ele como uma subdependência. Isso significa, todos os "dependentes"... pode soar meio confuso, e isso será explicado novamente mais adiante.
+
+O objeto `security_scopes` (da classe `SecurityScopes`) também oferece um atributo `scope_str` com uma única string, contendo os escopos separados por espaços (nós vamos utilizar isso).
+
+Nós criamos uma `HTTPException` que nós podemos reutilizar (`raise`) mais tarde em diversos lugares.
+
+Nesta exceção, nós incluímos os escopos necessários (se houver algum) como uma string separada por espaços (utilizando `scope_str`). Nós colocamos esta string contendo os escopos no cabeçalho `WWW-Authenticate` (isso é parte da especificação).
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[106,108:116] *}
+
+## Verifique o `username` e o formato dos dados
+
+Nós verificamos que nós obtemos um `username`, e extraímos os escopos.
+
+E depois nós validamos esse dado com o modelo Pydantic (capturando a exceção `ValidationError`), e se nós obtemos um erro ao ler o token JWT ou validando os dados com o Pydantic, nós levantamos a exceção `HTTPException` que criamos anteriormente.
+
+Para isso, nós atualizamos o modelo Pydantic `TokenData` com a nova propriedade `scopes`.
+
+Ao validar os dados com o Pydantic nós podemos garantir que temos, por exemplo, exatamente uma `list` de `str` com os escopos e uma `str` com o `username`.
+
+No lugar de, por exemplo, um `dict`, ou alguma outra coisa, que poderia quebrar a aplicação em algum lugar mais tarde, tornando isso um risco de segurança.
+
+Nós também verificamos que nós temos um usuário com o "*username*", e caso contrário, nós levantamos a mesma exceção que criamos anteriormente.
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[47,117:128] *}
+
+## Verifique os `scopes`
+
+Nós verificamos agora que todos os escopos necessários, por essa dependência e todos os dependentes (incluindo as *operações de rota*) estão incluídas nos escopos fornecidos pelo token recebido, caso contrário, levantamos uma `HTTPException`.
+
+Para isso, nós utilizamos `security_scopes.scopes`, que contém uma `list` com todos esses escopos como uma `str`.
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[129:135] *}
+
+## Árvore de dependência e escopos
+
+Vamos rever novamente essa árvore de dependência e os escopos.
+
+Como a dependência `get_current_active_user` possui uma subdependência em `get_current_user`, o escopo `"me"` declarado em `get_current_active_user` será incluído na lista de escopos necessários em `security_scopes.scopes` passado para `get_current_user`.
+
+A própria *operação de rota* também declara o escopo, `"items"`, então ele também estará na lista de `security_scopes.scopes` passado para o `get_current_user`.
+
+Aqui está como a hierarquia de dependências e escopos parecem:
+
+* A *operação de rota* `read_own_items` possui:
+ * Escopos necessários `["items"]` com a dependência:
+ * `get_current_active_user`:
+ * A função de dependência `get_current_active_user` possui:
+ * Escopos necessários `["me"]` com a dependência:
+ * `get_current_user`:
+ * A função de dependência `get_current_user` possui:
+ * Nenhum escopo necessário.
+ * Uma dependência utilizando `oauth2_scheme`.
+ * Um parâmetro `security_scopes` do tipo `SecurityScopes`:
+ * Este parâmetro `security_scopes` possui uma propriedade `scopes` com uma `list` contendo todos estes escopos declarados acima, então:
+ * `security_scopes.scopes` terá `["me", "items"]` para a *operação de rota* `read_own_items`.
+ * `security_scopes.scopes` terá `["me"]` para a *operação de rota* `read_users_me`, porque ela declarou na dependência `get_current_active_user`.
+ * `security_scopes.scopes` terá `[]` (nada) para a *operação de rota* `read_system_status`, porque ele não declarou nenhum `Security` com `scopes`, e sua dependência, `get_current_user`, não declara nenhum `scopes` também.
+
+/// tip | Dica
+
+A coisa importante e "mágica" aqui é que `get_current_user` terá diferentes listas de `scopes` para validar para cada *operação de rota*.
+
+Tudo depende dos `scopes` declarados em cada *operação de rota* e cada dependência da árvore de dependências para aquela *operação de rota* específica.
+
+///
+
+## Mais detalhes sobre `SecurityScopes`
+
+Você pode utilizar `SecurityScopes` em qualquer lugar, e em diversos lugares. Ele não precisa estar na dependência "raiz".
+
+Ele sempre terá os escopos de segurança declarados nas dependências atuais de `Security` e todos os dependentes para **aquela** *operação de rota* **específica** e **aquela** árvore de dependência **específica**.
+
+Porque o `SecurityScopes` terá todos os escopos declarados por dependentes, você pode utilizá-lo para verificar se o token possui os escopos necessários em uma função de dependência central, e depois declarar diferentes requisitos de escopo em diferentes *operações de rota*.
+
+Todos eles serão validados independentemente para cada *operação de rota*.
+
+## Verifique
+
+Se você abrir os documentos da API, você pode antenticar e especificar quais escopos você quer autorizar.
+
+
+
+Se você não selecionar nenhum escopo, você terá "autenticado", mas quando você tentar acessar `/users/me/` ou `/users/me/items/`, você vai obter um erro dizendo que você não possui as permissões necessárias. Você ainda poderá acessar `/status/`.
+
+E se você selecionar o escopo `me`, mas não o escopo `items`, você poderá acessar `/users/me/`, mas não `/users/me/items/`.
+
+Isso é o que aconteceria se uma aplicação terceira que tentou acessar uma dessas *operações de rota* com um token fornecido por um usuário, dependendo de quantas permissões o usuário forneceu para a aplicação.
+
+## Sobre integrações de terceiros
+
+Neste exemplos nós estamos utilizando o fluxo de senha do OAuth2.
+
+Isso é apropriado quando nós estamos autenticando em nossa própria aplicação, provavelmente com o nosso próprio "*frontend*".
+
+Porque nós podemos confiar nele para receber o `username` e o `password`, pois nós controlamos isso.
+
+Mas se nós estamos construindo uma aplicação OAuth2 que outros poderiam conectar (i.e., se você está construindo um provedor de autenticação equivalente ao Facebook, Google, GitHub, etc.) você deveria utilizar um dos outros fluxos.
+
+O mais comum é o fluxo implícito.
+
+O mais seguro é o fluxo de código, mas ele é mais complexo para implementar, pois ele necessita mais passos. Como ele é mais complexo, muitos provedores terminam sugerindo o fluxo implícito.
+
+/// note | Nota
+
+É comum que cada provedor de autenticação nomeie os seus fluxos de forma diferente, para torná-lo parte de sua marca.
+
+Mas no final, eles estão implementando o mesmo padrão OAuth2.
+
+///
+
+O **FastAPI** inclui utilitários para todos esses fluxos de autenticação OAuth2 em `fastapi.security.oauth2`.
+
+## `Security` em docoradores de `dependências`
+
+Da mesma forma que você pode definir uma `list` de `Depends` no parâmetro de `dependencias` do decorador (como explicado em [Dependências em decoradores de operações de rota](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}), você também pode utilizar `Security` com escopos lá.
diff --git a/docs/pt/docs/advanced/settings.md b/docs/pt/docs/advanced/settings.md
index f6962831f..cdc6400ad 100644
--- a/docs/pt/docs/advanced/settings.md
+++ b/docs/pt/docs/advanced/settings.md
@@ -8,44 +8,51 @@ Por isso é comum prover essas configurações como variáveis de ambiente que s
## Variáveis de Ambiente
-!!! dica
- Se você já sabe o que são variáveis de ambiente e como utilizá-las, sinta-se livre para avançar para o próximo tópico.
+/// tip | Dica
+
+Se você já sabe o que são variáveis de ambiente e como utilizá-las, sinta-se livre para avançar para o próximo tópico.
+
+///
Uma variável de ambiente (abreviada em inglês para "env var") é uma variável definida fora do código Python, no sistema operacional, e pode ser lida pelo seu código Python (ou por outros programas).
Você pode criar e utilizar variáveis de ambiente no terminal, sem precisar utilizar Python:
-=== "Linux, macOS, Windows Bash"
+//// tab | Linux, macOS, Windows Bash
-
+
+E então, abra a documentação para a sub-aplicação, em http://127.0.0.1:8000/subapi/docs.
+
+Você verá a documentação automática da API para a sub-aplicação, incluindo apenas suas próprias _operações de rota_, todas sob o prefixo de sub-caminho correto `/subapi`:
+
+
+
+Se você tentar interagir com qualquer uma das duas interfaces de usuário, elas funcionarão corretamente, porque o navegador será capaz de se comunicar com cada aplicação ou sub-aplicação específica.
+
+### Detalhes Técnicos: `root_path`
+
+Quando você monta uma sub-aplicação como descrito acima, o FastAPI se encarrega de comunicar o caminho de montagem para a sub-aplicação usando um mecanismo da especificação ASGI chamado `root_path`.
+
+Dessa forma, a sub-aplicação saberá usar esse prefixo de caminho para a interface de documentação.
+
+E a sub-aplicação também poderia ter suas próprias sub-aplicações montadas e tudo funcionaria corretamente, porque o FastAPI lida com todos esses `root_path`s automaticamente.
+
+Você aprenderá mais sobre o `root_path` e como usá-lo explicitamente na seção sobre [Atrás de um Proxy](behind-a-proxy.md){.internal-link target=_blank}.
diff --git a/docs/pt/docs/advanced/templates.md b/docs/pt/docs/advanced/templates.md
index 3bada5e43..4d22bfbbf 100644
--- a/docs/pt/docs/advanced/templates.md
+++ b/docs/pt/docs/advanced/templates.md
@@ -25,31 +25,36 @@ $ pip install jinja2
* Declare um parâmetro `Request` no *path operation* que retornará um template.
* Use o `template` que você criou para renderizar e retornar uma `TemplateResponse`, passe o nome do template, o request object, e um "context" dict com pares chave-valor a serem usados dentro do template do Jinja2.
-```Python hl_lines="4 11 15-18"
-{!../../../docs_src/templates/tutorial001.py!}
-```
+{* ../../docs_src/templates/tutorial001.py hl[4,11,15:18] *}
-!!! note
- Antes do FastAPI 0.108.0, Starlette 0.29.0, `name` era o primeiro parâmetro.
+/// note
- Além disso, em versões anteriores, o objeto `request` era passado como parte dos pares chave-valor no "context" dict para o Jinja2.
+Antes do FastAPI 0.108.0, Starlette 0.29.0, `name` era o primeiro parâmetro.
+Além disso, em versões anteriores, o objeto `request` era passado como parte dos pares chave-valor no "context" dict para o Jinja2.
-!!! tip "Dica"
- Ao declarar `response_class=HTMLResponse`, a documentação entenderá que a resposta será HTML.
+///
+/// tip | Dica
-!!! note "Detalhes Técnicos"
- Você também poderia usar `from starlette.templating import Jinja2Templates`.
+Ao declarar `response_class=HTMLResponse`, a documentação entenderá que a resposta será HTML.
- **FastAPI** fornece o mesmo `starlette.templating` como `fastapi.templating` apenas como uma conveniência para você, o desenvolvedor. Mas a maioria das respostas disponíveis vêm diretamente do Starlette. O mesmo acontece com `Request` e `StaticFiles`.
+///
+
+/// note | Detalhes Técnicos
+
+Você também poderia usar `from starlette.templating import Jinja2Templates`.
+
+**FastAPI** fornece o mesmo `starlette.templating` como `fastapi.templating` apenas como uma conveniência para você, o desenvolvedor. Mas a maioria das respostas disponíveis vêm diretamente do Starlette. O mesmo acontece com `Request` e `StaticFiles`.
+
+///
## Escrevendo Templates
Então você pode escrever um template em `templates/item.html`, por exemplo:
```jinja hl_lines="7"
-{!../../../docs_src/templates/templates/item.html!}
+{!../../docs_src/templates/templates/item.html!}
```
### Interpolação de Valores no Template
@@ -103,13 +108,13 @@ Por exemplo, com um ID de `42`, isso renderizará:
Você também pode usar `url_for()` dentro do template e usá-lo, por examplo, com o `StaticFiles` que você montou com o `name="static"`.
```jinja hl_lines="4"
-{!../../../docs_src/templates/templates/item.html!}
+{!../../docs_src/templates/templates/item.html!}
```
Neste exemplo, ele seria vinculado a um arquivo CSS em `static/styles.css` com:
```CSS hl_lines="4"
-{!../../../docs_src/templates/static/styles.css!}
+{!../../docs_src/templates/static/styles.css!}
```
E como você está usando `StaticFiles`, este arquivo CSS será automaticamente servido pela sua aplicação FastAPI na URL `/static/styles.css`.
diff --git a/docs/pt/docs/advanced/testing-dependencies.md b/docs/pt/docs/advanced/testing-dependencies.md
new file mode 100644
index 000000000..3ede4741d
--- /dev/null
+++ b/docs/pt/docs/advanced/testing-dependencies.md
@@ -0,0 +1,53 @@
+# Testando Dependências com Sobreposição (Overrides)
+
+## Sobrepondo dependências durante os testes
+
+Existem alguns cenários onde você deseje sobrepor uma dependência durante os testes.
+
+Você não quer que a dependência original execute (e nenhuma das subdependências que você possa ter).
+
+Em vez disso, você deseja fornecer uma dependência diferente que será usada somente durante os testes (possivelmente apenas para alguns testes específicos) e fornecerá um valor que pode ser usado onde o valor da dependência original foi usado.
+
+### Casos de uso: serviço externo
+
+Um exemplo pode ser que você possua um provedor de autenticação externo que você precisa chamar.
+
+Você envia ao serviço um *token* e ele retorna um usuário autenticado.
+
+Este provedor pode cobrar por requisição, e chamá-lo pode levar mais tempo do que se você tivesse um usuário fixo para os testes.
+
+Você provavelmente quer testar o provedor externo uma vez, mas não necessariamente chamá-lo em todos os testes que executarem.
+
+Neste caso, você pode sobrepor (*override*) a dependência que chama o provedor, e utilizar uma dependência customizada que retorna um *mock* do usuário, apenas para os seus testes.
+
+### Utilize o atributo `app.dependency_overrides`
+
+Para estes casos, a sua aplicação **FastAPI** possui o atributo `app.dependency_overrides`. Ele é um simples `dict`.
+
+Para sobrepor a dependência para os testes, você coloca como chave a dependência original (a função), e como valor, a sua sobreposição da dependência (outra função).
+
+E então o **FastAPI** chamará a sobreposição no lugar da dependência original.
+
+{* ../../docs_src/dependency_testing/tutorial001_an_py310.py hl[26:27,30] *}
+
+/// tip | Dica
+
+Você pode definir uma sobreposição de dependência para uma dependência que é utilizada em qualquer lugar da sua aplicação **FastAPI**.
+
+A dependência original pode estar sendo utilizada em uma *função de operação de rota*, um *docorador de operação de rota* (quando você não utiliza o valor retornado), uma chamada ao `.include_router()`, etc.
+
+O FastAPI ainda poderá sobrescrevê-lo.
+
+///
+
+E então você pode redefinir as suas sobreposições (removê-las) definindo o `app.dependency_overrides` como um `dict` vazio:
+
+```Python
+app.dependency_overrides = {}
+```
+
+/// tip | Dica
+
+Se você quer sobrepor uma dependência apenas para alguns testes, você pode definir a sobreposição no início do testes (dentro da função de teste) e reiniciá-la ao final (no final da função de teste).
+
+///
diff --git a/docs/pt/docs/advanced/testing-events.md b/docs/pt/docs/advanced/testing-events.md
new file mode 100644
index 000000000..6113c9913
--- /dev/null
+++ b/docs/pt/docs/advanced/testing-events.md
@@ -0,0 +1,5 @@
+# Testando Eventos: inicialização - encerramento
+
+Quando você precisa que os seus manipuladores de eventos (`startup` e `shutdown`) sejam executados em seus testes, você pode utilizar o `TestClient` usando a instrução `with`:
+
+{* ../../docs_src/app_testing/tutorial003.py hl[9:12,20:24] *}
diff --git a/docs/pt/docs/advanced/testing-websockets.md b/docs/pt/docs/advanced/testing-websockets.md
new file mode 100644
index 000000000..942771bc9
--- /dev/null
+++ b/docs/pt/docs/advanced/testing-websockets.md
@@ -0,0 +1,13 @@
+# Testando WebSockets
+
+Você pode usar o mesmo `TestClient` para testar WebSockets.
+
+Para isso, você utiliza o `TestClient` dentro de uma instrução `with`, conectando com o WebSocket:
+
+{* ../../docs_src/app_testing/tutorial002.py hl[27:31] *}
+
+/// note | Nota
+
+Para mais detalhes, confira a documentação do Starlette para testar WebSockets.
+
+///
diff --git a/docs/pt/docs/advanced/using-request-directly.md b/docs/pt/docs/advanced/using-request-directly.md
new file mode 100644
index 000000000..f31e2ed15
--- /dev/null
+++ b/docs/pt/docs/advanced/using-request-directly.md
@@ -0,0 +1,56 @@
+# Utilizando o Request diretamente
+
+Até agora você declarou as partes da requisição que você precisa utilizando os seus tipos.
+
+Obtendo dados de:
+
+* Os parâmetros das rotas.
+* Cabeçalhos (*Headers*).
+* Cookies.
+* etc.
+
+E ao fazer isso, o **FastAPI** está validando as informações, convertendo-as e gerando documentação para a sua API automaticamente.
+
+Porém há situações em que você possa precisar acessar o objeto `Request` diretamente.
+
+## Detalhes sobre o objeto `Request`
+
+Como o **FastAPI** é na verdade o **Starlette** por baixo, com camadas de diversas funcionalidades por cima, você pode utilizar o objeto `Request` do Starlette diretamente quando precisar.
+
+Isso significaria também que se você obtiver informações do objeto `Request` diretamente (ler o corpo da requisição por exemplo), as informações não serão validadas, convertidas ou documentadas (com o OpenAPI, para a interface de usuário automática da API) pelo FastAPI.
+
+Embora qualquer outro parâmetro declarado normalmente (o corpo da requisição com um modelo Pydantic, por exemplo) ainda seria validado, convertido, anotado, etc.
+
+Mas há situações específicas onde é útil utilizar o objeto `Request`.
+
+## Utilize o objeto `Request` diretamente
+
+Vamos imaginar que você deseja obter o endereço de IP/host do cliente dentro da sua *função de operação de rota*.
+
+Para isso você precisa acessar a requisição diretamente.
+
+{* ../../docs_src/using_request_directly/tutorial001.py hl[1,7:8] *}
+
+Ao declarar o parâmetro com o tipo sendo um `Request` em sua *função de operação de rota*, o **FastAPI** saberá como passar o `Request` neste parâmetro.
+
+/// tip | Dica
+
+Note que neste caso, nós estamos declarando o parâmetro da rota ao lado do parâmetro da requisição.
+
+Assim, o parâmetro da rota será extraído, validado, convertido para o tipo especificado e anotado com OpenAPI.
+
+Do mesmo jeito, você pode declarar qualquer outro parâmetro normalmente, e além disso, obter o `Request` também.
+
+///
+
+## Documentação do `Request`
+
+Você pode ler mais sobre os detalhes do objeto `Request` no site da documentação oficial do Starlette..
+
+/// note | Detalhes Técnicos
+
+Você também pode utilizar `from starlette.requests import Request`.
+
+O **FastAPI** fornece isso diretamente apenas como uma conveniência para você, o desenvolvedor. Mas ele vem diretamente do Starlette.
+
+///
diff --git a/docs/pt/docs/advanced/websockets.md b/docs/pt/docs/advanced/websockets.md
new file mode 100644
index 000000000..82e443886
--- /dev/null
+++ b/docs/pt/docs/advanced/websockets.md
@@ -0,0 +1,186 @@
+# WebSockets
+
+Você pode usar WebSockets com **FastAPI**.
+
+## Instalando `WebSockets`
+
+Garanta que você criou um [ambiente virtual](../virtual-environments.md){.internal-link target=_blank}, o ativou e instalou o `websockets`:
+
+
+
+Você pode digitar mensagens na caixa de entrada e enviá-las:
+
+
+
+E sua aplicação **FastAPI** com WebSockets responderá de volta:
+
+
+
+Você pode enviar (e receber) muitas mensagens:
+
+
+
+E todas elas usarão a mesma conexão WebSocket.
+
+## Usando `Depends` e outros
+
+Nos endpoints WebSocket você pode importar do `fastapi` e usar:
+
+* `Depends`
+* `Security`
+* `Cookie`
+* `Header`
+* `Path`
+* `Query`
+
+Eles funcionam da mesma forma que para outros endpoints FastAPI/*operações de rota*:
+
+{*../../docs_src/websockets/tutorial002_an_py310.py hl[68:69,82]*}
+
+/// info | Informação
+
+Como isso é um WebSocket, não faz muito sentido levantar uma `HTTPException`, em vez disso levantamos uma `WebSocketException`.
+
+Você pode usar um código de fechamento dos códigos válidos definidos na especificação.
+
+///
+
+### Tente os WebSockets com dependências
+
+Se seu arquivo for nomeado `main.py`, execute sua aplicação com:
+
+
+
+## Lidando com desconexões e múltiplos clientes
+
+Quando uma conexão WebSocket é fechada, o `await websocket.receive_text()` levantará uma exceção `WebSocketDisconnect`, que você pode então capturar e lidar como neste exemplo.
+
+{*../../docs_src/websockets/tutorial003_py39.py hl[79:81]*}
+
+Para testar:
+
+* Abrar o aplicativo com várias abas do navegador.
+* Escreva mensagens a partir delas.
+* Então feche uma das abas.
+
+Isso levantará a exceção `WebSocketDisconnect`, e todos os outros clientes receberão uma mensagem como:
+
+```
+Client #1596980209979 left the chat
+```
+
+/// tip | Dica
+
+O app acima é um exemplo mínimo e simples para demonstrar como lidar e transmitir mensagens para várias conexões WebSocket.
+
+Mas tenha em mente que, como tudo é manipulado na memória, em uma única lista, ele só funcionará enquanto o processo estiver em execução e só funcionará com um único processo.
+
+Se você precisa de algo fácil de integrar com o FastAPI, mas que seja mais robusto, suportado por Redis, PostgreSQL ou outros, verifique o encode/broadcaster.
+
+///
+
+## Mais informações
+
+Para aprender mais sobre as opções, verifique a documentação do Starlette para:
+
+* A classe `WebSocket`.
+* Manipulação de WebSockets baseada em classes.
diff --git a/docs/pt/docs/advanced/wsgi.md b/docs/pt/docs/advanced/wsgi.md
index 2c7ac1ffe..a36261e5e 100644
--- a/docs/pt/docs/advanced/wsgi.md
+++ b/docs/pt/docs/advanced/wsgi.md
@@ -12,9 +12,7 @@ Em seguinda, encapsular a aplicação WSGI (e.g. Flask) com o middleware.
E então **"montar"** em um caminho de rota.
-```Python hl_lines="2-3 23"
-{!../../../docs_src/wsgi/tutorial001.py!}
-```
+{* ../../docs_src/wsgi/tutorial001.py hl[2:3,23] *}
## Conferindo
diff --git a/docs/pt/docs/alternatives.md b/docs/pt/docs/alternatives.md
index ba721536f..29c9693bb 100644
--- a/docs/pt/docs/alternatives.md
+++ b/docs/pt/docs/alternatives.md
@@ -1,6 +1,6 @@
# Alternativas, Inspiração e Comparações
-O que inspirou **FastAPI**, como ele se compara a outras alternativas e o que FastAPI aprendeu delas.
+O que inspirou o **FastAPI**, como ele se compara às alternativas e o que FastAPI aprendeu delas.
## Introdução
@@ -30,11 +30,17 @@ Ele é utilizado por muitas companhias incluindo Mozilla, Red Hat e Eventbrite.
Ele foi um dos primeiros exemplos de **documentação automática de API**, e essa foi especificamente uma das primeiras idéias que inspirou "a busca por" **FastAPI**.
-!!! note "Nota"
- Django REST Framework foi criado por Tom Christie. O mesmo criador de Starlette e Uvicorn, nos quais **FastAPI** é baseado.
+/// note | Nota
-!!! check "**FastAPI** inspirado para"
- Ter uma documentação automática da API em interface web.
+Django REST Framework foi criado por Tom Christie. O mesmo criador de Starlette e Uvicorn, nos quais **FastAPI** é baseado.
+
+///
+
+/// check | **FastAPI** inspirado para
+
+Ter uma documentação automática da API em interface web.
+
+///
### Flask
@@ -50,10 +56,13 @@ Esse desacoplamento de partes, e sendo um "microframework" que pode ser extendid
Dada a simplicidade do Flask, parecia uma ótima opção para construção de APIs. A próxima coisa a procurar era um "Django REST Framework" para Flask.
-!!! check "**FastAPI** inspirado para"
- Ser um microframework. Fazer ele fácil para misturar e combinar com ferramentas e partes necessárias.
+/// check | **FastAPI** inspirado para
- Ser simples e com sistema de roteamento fácil de usar.
+Ser um microframework. Fazer ele fácil para misturar e combinar com ferramentas e partes necessárias.
+
+Ser simples e com sistema de roteamento fácil de usar.
+
+///
### Requests
@@ -89,10 +98,13 @@ def read_url():
Veja as similaridades em `requests.get(...)` e `@app.get(...)`.
-!!! check "**FastAPI** inspirado para"
- * Ter uma API simples e intuitiva.
- * Utilizar nomes de métodos HTTP (operações) diretamente, de um jeito direto e intuitivo.
- * Ter padrões sensíveis, mas customizações poderosas.
+/// check | **FastAPI** inspirado para
+
+* Ter uma API simples e intuitiva.
+* Utilizar nomes de métodos HTTP (operações) diretamente, de um jeito direto e intuitivo.
+* Ter padrões sensíveis, mas customizações poderosas.
+
+///
### Swagger / OpenAPI
@@ -106,15 +118,18 @@ Em algum ponto, Swagger foi dado para a Fundação Linux, e foi renomeado OpenAP
Isso acontece porquê quando alguém fala sobre a versão 2.0 é comum dizer "Swagger", e para a versão 3+, "OpenAPI".
-!!! check "**FastAPI** inspirado para"
- Adotar e usar um padrão aberto para especificações API, ao invés de algum esquema customizado.
+/// check | **FastAPI** inspirado para
- E integrar ferramentas de interface para usuários baseado nos padrões:
+Adotar e usar um padrão aberto para especificações API, ao invés de algum esquema customizado.
- * Swagger UI
- * ReDoc
+E integrar ferramentas de interface para usuários baseado nos padrões:
- Esses dois foram escolhidos por serem bem populares e estáveis, mas fazendo uma pesquisa rápida, você pode encontrar dúzias de interfaces alternativas adicionais para OpenAPI (assim você poderá utilizar com **FastAPI**).
+* Swagger UI
+* ReDoc
+
+Esses dois foram escolhidos por serem bem populares e estáveis, mas fazendo uma pesquisa rápida, você pode encontrar dúzias de interfaces alternativas adicionais para OpenAPI (assim você poderá utilizar com **FastAPI**).
+
+///
### Flask REST frameworks
@@ -132,8 +147,11 @@ Esses recursos são o que Marshmallow foi construído para fornecer. Ele é uma
Mas ele foi criado antes da existência do _type hints_ do Python. Então, para definir todo o _schema_ você precisa utilizar específicas ferramentas e classes fornecidas pelo Marshmallow.
-!!! check "**FastAPI** inspirado para"
- Usar código para definir "schemas" que forneçam, automaticamente, tipos de dados e validação.
+/// check | **FastAPI** inspirado para
+
+Usar código para definir "schemas" que forneçam, automaticamente, tipos de dados e validação.
+
+///
### Webargs
@@ -145,11 +163,17 @@ Ele utiliza Marshmallow por baixo para validação de dados. E ele foi criado pe
Ele é uma grande ferramenta e eu também a utilizei muito, antes de ter o **FastAPI**.
-!!! info
- Webargs foi criado pelos mesmos desenvolvedores do Marshmallow.
+/// info
-!!! check "**FastAPI** inspirado para"
- Ter validação automática de dados vindos de requisições.
+Webargs foi criado pelos mesmos desenvolvedores do Marshmallow.
+
+///
+
+/// check | **FastAPI** inspirado para
+
+Ter validação automática de dados vindos de requisições.
+
+///
### APISpec
@@ -169,11 +193,17 @@ Mas então, nós temos novamente o problema de ter uma micro-sintaxe, dentro de
O editor não poderá ajudar muito com isso. E se nós modificarmos os parâmetros dos _schemas_ do Marshmallow e esquecer de modificar também aquela _docstring_ YAML, o _schema_ gerado pode ficar obsoleto.
-!!! info
- APISpec foi criado pelos mesmos desenvolvedores do Marshmallow.
+/// info
-!!! check "**FastAPI** inspirado para"
- Dar suporte a padrões abertos para APIs, OpenAPI.
+APISpec foi criado pelos mesmos desenvolvedores do Marshmallow.
+
+///
+
+/// check | **FastAPI** inspirado para
+
+Dar suporte a padrões abertos para APIs, OpenAPI.
+
+///
### Flask-apispec
@@ -185,7 +215,7 @@ Ele utiliza a informação do Webargs e Marshmallow para gerar automaticamente _
Isso resolveu o problema de ter que escrever YAML (outra sintaxe) dentro das _docstrings_ Python.
-Essa combinação de Flask, Flask-apispec com Marshmallow e Webargs foi meu _backend stack_ favorito até construir **FastAPI**.
+Essa combinação de Flask, Flask-apispec com Marshmallow e Webargs foi meu _backend stack_ favorito até construir o **FastAPI**.
Usando essa combinação levou a criação de vários geradores Flask _full-stack_. Há muitas _stacks_ que eu (e vários times externos) estou utilizando até agora:
@@ -195,11 +225,17 @@ Usando essa combinação levou a criação de vários geradores Flask _full-stac
E esses mesmos geradores _full-stack_ foram a base dos [Geradores de Projetos **FastAPI**](project-generation.md){.internal-link target=_blank}.
-!!! info
- Flask-apispec foi criado pelos mesmos desenvolvedores do Marshmallow.
+/// info
-!!! check "**FastAPI** inspirado para"
- Gerar _schema_ OpenAPI automaticamente, a partir do mesmo código que define serialização e validação.
+Flask-apispec foi criado pelos mesmos desenvolvedores do Marshmallow.
+
+///
+
+/// check | **FastAPI** inspirado para
+
+Gerar _schema_ OpenAPI automaticamente, a partir do mesmo código que define serialização e validação.
+
+///
### NestJS (and Angular)
@@ -207,7 +243,7 @@ NestJS, que não é nem Python, é um framework NodeJS JavaScript (TypeScript) i
Ele alcança de uma forma similar ao que pode ser feito com o Flask-apispec.
-Ele tem um sistema de injeção de dependência integrado, inspirado pelo Angular dois. É necessário fazer o pré-registro dos "injetáveis" (como todos os sistemas de injeção de dependência que conheço), então, adicionando verbosidade e repetição de código.
+Ele tem um sistema de injeção de dependência integrado, inspirado pelo Angular 2. É necessário fazer o pré-registro dos "injetáveis" (como todos os sistemas de injeção de dependência que conheço), então, adicionando verbosidade e repetição de código.
Como os parâmetros são descritos com tipos TypeScript (similar aos _type hints_ do Python), o suporte ao editor é muito bom.
@@ -215,24 +251,33 @@ Mas como os dados TypeScript não são preservados após a compilação para o J
Ele também não controla modelos aninhados muito bem. Então, se o corpo JSON na requisição for um objeto JSON que contém campos internos que contém objetos JSON aninhados, ele não consegue ser validado e documentado apropriadamente.
-!!! check "**FastAPI** inspirado para"
- Usar tipos Python para ter um ótimo suporte do editor.
+/// check | **FastAPI** inspirado para
- Ter um sistema de injeção de dependência poderoso. Achar um jeito de minimizar repetição de código.
+Usar tipos Python para ter um ótimo suporte do editor.
+
+Ter um sistema de injeção de dependência poderoso. Achar um jeito de minimizar repetição de código.
+
+///
### Sanic
Ele foi um dos primeiros frameworks Python extremamente rápido baseado em `asyncio`. Ele foi feito para ser muito similar ao Flask.
-!!! note "Detalhes técnicos"
- Ele utiliza `uvloop` ao invés do '_loop_' `asyncio` padrão do Python. É isso que deixa ele tão rápido.
+/// note | Detalhes técnicos
- Ele claramente inspirou Uvicorn e Starlette, que são atualmente mais rápidos que o Sanic em testes de performance abertos.
+Ele utiliza `uvloop` ao invés do '_loop_' `asyncio` padrão do Python. É isso que deixa ele tão rápido.
-!!! check "**FastAPI** inspirado para"
- Achar um jeito de ter uma performance insana.
+Ele claramente inspirou Uvicorn e Starlette, que são atualmente mais rápidos que o Sanic em testes de performance abertos.
- É por isso que o **FastAPI** é baseado em Starlette, para que ele seja o framework mais rápido disponível (performance testada por terceiros).
+///
+
+/// check | **FastAPI** inspirado para
+
+Achar um jeito de ter uma performance insana.
+
+É por isso que o **FastAPI** é baseado em Starlette, para que ele seja o framework mais rápido disponível (performance testada por terceiros).
+
+///
### Falcon
@@ -244,12 +289,15 @@ Ele é projetado para ter funções que recebem dois parâmetros, uma "requisiç
Então, validação de dados, serialização e documentação tem que ser feitos no código, não automaticamente. Ou eles terão que ser implementados como um framework acima do Falcon, como o Hug. Essa mesma distinção acontece em outros frameworks que são inspirados pelo design do Falcon, tendo um objeto de requisição e um objeto de resposta como parâmetros.
-!!! check "**FastAPI** inspirado para"
- Achar jeitos de conseguir melhor performance.
+/// check | **FastAPI** inspirado para
- Juntamente com Hug (como Hug é baseado no Falcon) inspirou **FastAPI** para declarar um parâmetro de `resposta`nas funções.
+Achar jeitos de conseguir melhor performance.
- Embora no FastAPI seja opcional, é utilizado principalmente para configurar cabeçalhos, cookies e códigos de status alternativos.
+Juntamente com Hug (como Hug é baseado no Falcon) inspirou **FastAPI** para declarar um parâmetro de `resposta` nas funções.
+
+Embora no FastAPI seja opcional, é utilizado principalmente para configurar cabeçalhos, cookies e códigos de status alternativos.
+
+///
### Molten
@@ -267,12 +315,15 @@ O sistema de injeção de dependência exige pré-registro das dependências e a
Rotas são declaradas em um único lugar, usando funções declaradas em outros lugares (ao invés de usar decoradores que possam ser colocados diretamente acima da função que controla o _endpoint_). Isso é mais perto de como o Django faz isso do que como Flask (e Starlette) faz. Ele separa no código coisas que são relativamente amarradas.
-!!! check "**FastAPI** inspirado para"
- Definir validações extras para tipos de dados usando valores "padrão" de atributos dos modelos. Isso melhora o suporte do editor, e não estava disponível no Pydantic antes.
+/// check | **FastAPI** inspirado para
- Isso na verdade inspirou a atualização de partes do Pydantic, para dar suporte ao mesmo estilo de declaração da validação (toda essa funcionalidade já está disponível no Pydantic).
+Definir validações extras para tipos de dados usando valores "padrão" de atributos dos modelos. Isso melhora o suporte do editor, e não estava disponível no Pydantic antes.
-### Hug
+Isso na verdade inspirou a atualização de partes do Pydantic, para dar suporte ao mesmo estilo de declaração da validação (toda essa funcionalidade já está disponível no Pydantic).
+
+///
+
+### Hug
Hug foi um dos primeiros frameworks a implementar a declaração de tipos de parâmetros usando Python _type hints_. Isso foi uma ótima idéia que inspirou outras ferramentas a fazer o mesmo.
@@ -286,15 +337,21 @@ Hug tinha um incomum, interessante recurso: usando o mesmo framework, é possív
Como é baseado nos padrões anteriores de frameworks web síncronos (WSGI), ele não pode controlar _Websockets_ e outras coisas, embora ele ainda tenha uma alta performance também.
-!!! info
- Hug foi criado por Timothy Crosley, o mesmo criador do `isort`, uma grande ferramenta para ordenação automática de _imports_ em arquivos Python.
+/// info
-!!! check "Idéias inspiradas para o **FastAPI**"
- Hug inspirou partes do APIStar, e foi uma das ferramentas que eu achei mais promissora, ao lado do APIStar.
+Hug foi criado por Timothy Crosley, o mesmo criador do `isort`, uma grande ferramenta para ordenação automática de _imports_ em arquivos Python.
- Hug ajudou a inspirar o **FastAPI** a usar _type hints_ do Python para declarar parâmetros, e para gerar um _schema_ definindo a API automaticamente.
+///
- Hug inspirou **FastAPI** a declarar um parâmetro de `resposta` em funções para definir cabeçalhos e cookies.
+/// check | Idéias inspiradas para o **FastAPI**
+
+Hug inspirou partes do APIStar, e foi uma das ferramentas que eu achei mais promissora, ao lado do APIStar.
+
+Hug ajudou a inspirar o **FastAPI** a usar _type hints_ do Python para declarar parâmetros, e para gerar um _schema_ definindo a API automaticamente.
+
+Hug inspirou **FastAPI** a declarar um parâmetro de `resposta` em funções para definir cabeçalhos e cookies.
+
+///
### APIStar (<= 0.5)
@@ -320,23 +377,29 @@ Ele não era mais um framework web API, como o criador precisava focar no Starle
Agora APIStar é um conjunto de ferramentas para validar especificações OpenAPI, não um framework web.
-!!! info
- APIStar foi criado por Tom Christie. O mesmo cara que criou:
+/// info
- * Django REST Framework
- * Starlette (no qual **FastAPI** é baseado)
- * Uvicorn (usado por Starlette e **FastAPI**)
+APIStar foi criado por Tom Christie. O mesmo cara que criou:
-!!! check "**FastAPI** inspirado para"
- Existir.
+* Django REST Framework
+* Starlette (no qual **FastAPI** é baseado)
+* Uvicorn (usado por Starlette e **FastAPI**)
- A idéia de declarar múltiplas coisas (validação de dados, serialização e documentação) com os mesmos tipos Python, que ao mesmo tempo fornecesse grande suporte ao editor, era algo que eu considerava uma brilhante idéia.
+///
- E após procurar por um logo tempo por um framework similar e testar muitas alternativas diferentes, APIStar foi a melhor opção disponível.
+/// check | **FastAPI** inspirado para
- Então APIStar parou de existir como um servidor e Starlette foi criado, e foi uma nova melhor fundação para tal sistema. Essa foi a inspiração final para construir **FastAPI**.
+Existir.
- Eu considero **FastAPI** um "sucessor espiritual" para o APIStar, evoluindo e melhorando os recursos, sistema de tipagem e outras partes, baseado na aprendizagem de todas essas ferramentas acima.
+A idéia de declarar múltiplas coisas (validação de dados, serialização e documentação) com os mesmos tipos Python, que ao mesmo tempo fornecesse grande suporte ao editor, era algo que eu considerava uma brilhante idéia.
+
+E após procurar por um logo tempo por um framework similar e testar muitas alternativas diferentes, APIStar foi a melhor opção disponível.
+
+Então APIStar parou de existir como um servidor e Starlette foi criado, e foi uma nova melhor fundação para tal sistema. Essa foi a inspiração final para construir **FastAPI**.
+
+Eu considero **FastAPI** um "sucessor espiritual" para o APIStar, evoluindo e melhorando os recursos, sistema de tipagem e outras partes, baseado na aprendizagem de todas essas ferramentas acima.
+
+///
## Usados por **FastAPI**
@@ -348,10 +411,13 @@ Isso faz dele extremamente intuitivo.
Ele é comparável ao Marshmallow. Embora ele seja mais rápido que Marshmallow em testes de performance. E ele é baseado nos mesmos Python _type hints_, o suporte ao editor é ótimo.
-!!! check "**FastAPI** usa isso para"
- Controlar toda a validação de dados, serialização de dados e modelo de documentação automática (baseado no JSON Schema).
+/// check | **FastAPI** usa isso para
- **FastAPI** então pega dados do JSON Schema e coloca eles no OpenAPI, à parte de todas as outras coisas que ele faz.
+Controlar toda a validação de dados, serialização de dados e modelo de documentação automática (baseado no JSON Schema).
+
+**FastAPI** então pega dados do JSON Schema e coloca eles no OpenAPI, à parte de todas as outras coisas que ele faz.
+
+///
### Starlette
@@ -366,7 +432,7 @@ Ele tem:
* Suporte a GraphQL.
* Tarefas de processamento interno por trás dos panos.
* Eventos de inicialização e encerramento.
-* Cliente de testes construído com requests.
+* Cliente de testes construído com HTTPX.
* Respostas CORS, GZip, Arquivos Estáticos, Streaming.
* Suporte para Sessão e Cookie.
* 100% coberto por testes.
@@ -381,17 +447,23 @@ Mas ele não fornece validação de dados automática, serialização e document
Essa é uma das principais coisas que **FastAPI** adiciona no topo, tudo baseado em Python _type hints_ (usando Pydantic). Isso, mais o sistema de injeção de dependência, utilidades de segurança, geração de _schema_ OpenAPI, etc.
-!!! note "Detalhes Técnicos"
- ASGI é um novo "padrão" sendo desenvolvido pelos membros do time central do Django. Ele ainda não está como "Padrão Python" (PEP), embora eles estejam em processo de fazer isso.
+/// note | Detalhes Técnicos
- No entanto, ele já está sendo utilizado como "padrão" por diversas ferramentas. Isso melhora enormemente a interoperabilidade, como você poderia trocar Uvicorn por qualquer outro servidor ASGI (como Daphne ou Hypercorn), ou você poderia adicionar ferramentas compatíveis com ASGI, como `python-socketio`.
+ASGI é um novo "padrão" sendo desenvolvido pelos membros do time central do Django. Ele ainda não está como "Padrão Python" (PEP), embora eles estejam em processo de fazer isso.
-!!! check "**FastAPI** usa isso para"
- Controlar todas as partes web centrais. Adiciona recursos no topo.
+No entanto, ele já está sendo utilizado como "padrão" por diversas ferramentas. Isso melhora enormemente a interoperabilidade, como você poderia trocar Uvicorn por qualquer outro servidor ASGI (como Daphne ou Hypercorn), ou você poderia adicionar ferramentas compatíveis com ASGI, como `python-socketio`.
- A classe `FastAPI` em si herda `Starlette`.
+///
- Então, qualquer coisa que você faz com Starlette, você pode fazer diretamente com **FastAPI**, pois ele é basicamente um Starlette com esteróides.
+/// check | **FastAPI** usa isso para
+
+Controlar todas as partes web centrais. Adiciona recursos no topo.
+
+A classe `FastAPI` em si herda `Starlette`.
+
+Então, qualquer coisa que você faz com Starlette, você pode fazer diretamente com **FastAPI**, pois ele é basicamente um Starlette com esteróides.
+
+///
### Uvicorn
@@ -401,12 +473,15 @@ Ele não é um framework web, mas sim um servidor. Por exemplo, ele não fornece
Ele é o servidor recomendado para Starlette e **FastAPI**.
-!!! check "**FastAPI** recomenda isso para"
- O principal servidor web para rodar aplicações **FastAPI**.
+/// check | **FastAPI** recomenda isso para
- Você pode combinar ele com o Gunicorn, para ter um servidor multi-processos assíncrono.
+O principal servidor web para rodar aplicações **FastAPI**.
- Verifique mais detalhes na seção [Deployment](deployment/index.md){.internal-link target=_blank}.
+Você pode combinar ele com o Gunicorn, para ter um servidor multi-processos assíncrono.
+
+Verifique mais detalhes na seção [Deployment](deployment/index.md){.internal-link target=_blank}.
+
+///
## Performance e velocidade
diff --git a/docs/pt/docs/async.md b/docs/pt/docs/async.md
index 1ec8f07c6..0d6bdbf0e 100644
--- a/docs/pt/docs/async.md
+++ b/docs/pt/docs/async.md
@@ -21,8 +21,11 @@ async def read_results():
return results
```
-!!! note
- Você só pode usar `await` dentro de funções criadas com `async def`.
+/// note
+
+Você só pode usar `await` dentro de funções criadas com `async def`.
+
+///
---
@@ -356,12 +359,15 @@ Tudo isso é o que deixa o FastAPI poderoso (através do Starlette) e que o faz
## Detalhes muito técnicos
-!!! warning
- Você pode provavelmente pular isso.
+/// warning
- Esses são detalhes muito técnicos de como **FastAPI** funciona por baixo do capô.
+Você pode provavelmente pular isso.
- Se você tem algum conhecimento técnico (corrotinas, threads, blocking etc) e está curioso sobre como o FastAPI controla o `async def` vs normal `def`, vá em frente.
+Esses são detalhes muito técnicos de como **FastAPI** funciona por baixo do capô.
+
+Se você tem algum conhecimento técnico (corrotinas, threads, blocking etc) e está curioso sobre como o FastAPI controla o `async def` vs normal `def`, vá em frente.
+
+///
### Funções de operação de rota
diff --git a/docs/pt/docs/contributing.md b/docs/pt/docs/contributing.md
deleted file mode 100644
index 7d8d1fd5e..000000000
--- a/docs/pt/docs/contributing.md
+++ /dev/null
@@ -1,479 +0,0 @@
-# Desenvolvimento - Contribuindo
-
-Primeiramente, você deveria ver os meios básicos para [ajudar FastAPI e pedir ajuda](help-fastapi.md){.internal-link target=_blank}.
-
-## Desenvolvendo
-
-Se você já clonou o repositório e precisa mergulhar no código, aqui estão algumas orientações para configurar seu ambiente.
-
-### Ambiente virtual com `venv`
-
-Você pode criar um ambiente virtual em um diretório utilizando o módulo `venv` do Python:
-
-
+
+---
+
+Agora que sabemos a diferença entre os termos **processo** e **programa**, vamos continuar falando sobre implantações.
+
+## Executando na inicialização
+
+Na maioria dos casos, quando você cria uma API web, você quer que ela esteja **sempre em execução**, ininterrupta, para que seus clientes possam sempre acessá-la. Isso é claro, a menos que você tenha um motivo específico para querer que ela seja executada somente em certas situações, mas na maioria das vezes você quer que ela esteja constantemente em execução e **disponível**.
+
+### Em um servidor remoto
+
+Ao configurar um servidor remoto (um servidor em nuvem, uma máquina virtual, etc.), a coisa mais simples que você pode fazer é usar `fastapi run` (que usa Uvicorn) ou algo semelhante, manualmente, da mesma forma que você faz ao desenvolver localmente.
+
+E funcionará e será útil **durante o desenvolvimento**.
+
+Mas se sua conexão com o servidor for perdida, o **processo em execução** provavelmente morrerá.
+
+E se o servidor for reiniciado (por exemplo, após atualizações ou migrações do provedor de nuvem), você provavelmente **não notará**. E por causa disso, você nem saberá que precisa reiniciar o processo manualmente. Então, sua API simplesmente permanecerá inativa. 😱
+
+### Executar automaticamente na inicialização
+
+Em geral, você provavelmente desejará que o programa do servidor (por exemplo, Uvicorn) seja iniciado automaticamente na inicialização do servidor e, sem precisar de nenhuma **intervenção humana**, tenha um processo sempre em execução com sua API (por exemplo, Uvicorn executando seu aplicativo FastAPI).
+
+### Programa separado
+
+Para conseguir isso, você normalmente terá um **programa separado** que garantiria que seu aplicativo fosse executado na inicialização. E em muitos casos, ele também garantiria que outros componentes ou aplicativos também fossem executados, por exemplo, um banco de dados.
+
+### Ferramentas de exemplo para executar na inicialização
+
+Alguns exemplos de ferramentas que podem fazer esse trabalho são:
+
+* Docker
+* Kubernetes
+* Docker Compose
+* Docker em Modo Swarm
+* Systemd
+* Supervisor
+* Gerenciado internamente por um provedor de nuvem como parte de seus serviços
+* Outros...
+
+Darei exemplos mais concretos nos próximos capítulos.
+
+## Reinicializações
+
+Semelhante a garantir que seu aplicativo seja executado na inicialização, você provavelmente também deseja garantir que ele seja **reiniciado** após falhas.
+
+### Nós cometemos erros
+
+Nós, como humanos, cometemos **erros** o tempo todo. O software quase *sempre* tem **bugs** escondidos em lugares diferentes. 🐛
+
+E nós, como desenvolvedores, continuamos aprimorando o código à medida que encontramos esses bugs e implementamos novos recursos (possivelmente adicionando novos bugs também 😅).
+
+### Pequenos erros são tratados automaticamente
+
+Ao criar APIs da web com FastAPI, se houver um erro em nosso código, o FastAPI normalmente o conterá na única solicitação que acionou o erro. 🛡
+
+O cliente receberá um **Erro Interno do Servidor 500** para essa solicitação, mas o aplicativo continuará funcionando para as próximas solicitações em vez de travar completamente.
+
+### Erros maiores - Travamentos
+
+No entanto, pode haver casos em que escrevemos algum código que **trava todo o aplicativo**, fazendo com que o Uvicorn e o Python travem. 💥
+
+E ainda assim, você provavelmente não gostaria que o aplicativo permanecesse inativo porque houve um erro em um lugar, você provavelmente quer que ele **continue em execução** pelo menos para as *operações de caminho* que não estão quebradas.
+
+### Reiniciar após falha
+
+Mas nos casos com erros realmente graves que travam o **processo** em execução, você vai querer um componente externo que seja responsável por **reiniciar** o processo, pelo menos algumas vezes...
+
+/// tip | Dica
+
+...Embora se o aplicativo inteiro estiver **travando imediatamente**, provavelmente não faça sentido reiniciá-lo para sempre. Mas nesses casos, você provavelmente notará isso durante o desenvolvimento, ou pelo menos logo após a implantação.
+
+Então, vamos nos concentrar nos casos principais, onde ele pode travar completamente em alguns casos específicos **no futuro**, e ainda faz sentido reiniciá-lo.
+
+///
+
+Você provavelmente gostaria de ter a coisa responsável por reiniciar seu aplicativo como um **componente externo**, porque a essa altura, o mesmo aplicativo com Uvicorn e Python já havia travado, então não há nada no mesmo código do mesmo aplicativo que possa fazer algo a respeito.
+
+### Ferramentas de exemplo para reiniciar automaticamente
+
+Na maioria dos casos, a mesma ferramenta usada para **executar o programa na inicialização** também é usada para lidar com **reinicializações** automáticas.
+
+Por exemplo, isso poderia ser resolvido por:
+
+* Docker
+* Kubernetes
+* Docker Compose
+* Docker no Modo Swarm
+* Systemd
+* Supervisor
+* Gerenciado internamente por um provedor de nuvem como parte de seus serviços
+* Outros...
+
+## Replicação - Processos e Memória
+
+Com um aplicativo FastAPI, usando um programa de servidor como o comando `fastapi` que executa o Uvicorn, executá-lo uma vez em **um processo** pode atender a vários clientes simultaneamente.
+
+Mas em muitos casos, você desejará executar vários processos de trabalho ao mesmo tempo.
+
+### Processos Múltiplos - Trabalhadores
+
+Se você tiver mais clientes do que um único processo pode manipular (por exemplo, se a máquina virtual não for muito grande) e tiver **vários núcleos** na CPU do servidor, você poderá ter **vários processos** em execução com o mesmo aplicativo ao mesmo tempo e distribuir todas as solicitações entre eles.
+
+Quando você executa **vários processos** do mesmo programa de API, eles são comumente chamados de **trabalhadores**.
+
+### Processos do Trabalhador e Portas
+
+Lembra da documentação [Sobre HTTPS](https.md){.internal-link target=_blank} que diz que apenas um processo pode escutar em uma combinação de porta e endereço IP em um servidor?
+
+Isso ainda é verdade.
+
+Então, para poder ter **vários processos** ao mesmo tempo, tem que haver um **único processo escutando em uma porta** que então transmite a comunicação para cada processo de trabalho de alguma forma.
+
+### Memória por Processo
+
+Agora, quando o programa carrega coisas na memória, por exemplo, um modelo de aprendizado de máquina em uma variável, ou o conteúdo de um arquivo grande em uma variável, tudo isso **consome um pouco da memória (RAM)** do servidor.
+
+E vários processos normalmente **não compartilham nenhuma memória**. Isso significa que cada processo em execução tem suas próprias coisas, variáveis e memória. E se você estiver consumindo uma grande quantidade de memória em seu código, **cada processo** consumirá uma quantidade equivalente de memória.
+
+### Memória do servidor
+
+Por exemplo, se seu código carrega um modelo de Machine Learning com **1 GB de tamanho**, quando você executa um processo com sua API, ele consumirá pelo menos 1 GB de RAM. E se você iniciar **4 processos** (4 trabalhadores), cada um consumirá 1 GB de RAM. Então, no total, sua API consumirá **4 GB de RAM**.
+
+E se o seu servidor remoto ou máquina virtual tiver apenas 3 GB de RAM, tentar carregar mais de 4 GB de RAM causará problemas. 🚨
+
+### Processos Múltiplos - Um Exemplo
+
+Neste exemplo, há um **Processo Gerenciador** que inicia e controla dois **Processos de Trabalhadores**.
+
+Este Processo de Gerenciador provavelmente seria o que escutaria na **porta** no IP. E ele transmitiria toda a comunicação para os processos de trabalho.
+
+Esses processos de trabalho seriam aqueles que executariam seu aplicativo, eles executariam os cálculos principais para receber uma **solicitação** e retornar uma **resposta**, e carregariam qualquer coisa que você colocasse em variáveis na RAM.
+
+
+
+Mas você pode desabilitá-lo definindo `syntaxHighlight` como `False`:
+
+{* ../../docs_src/configure_swagger_ui/tutorial001.py hl[3] *}
+
+...e então o Swagger UI não mostrará mais o destaque de sintaxe:
+
+
+
+## Alterar o tema
+
+Da mesma forma que você pode definir o tema de destaque de sintaxe com a chave `"syntaxHighlight.theme"` (observe que há um ponto no meio):
+
+{* ../../docs_src/configure_swagger_ui/tutorial002.py hl[3] *}
+
+Essa configuração alteraria o tema de cores de destaque de sintaxe:
+
+
+
+## Alterar parâmetros de UI padrão do Swagger
+
+O FastAPI inclui alguns parâmetros de configuração padrão apropriados para a maioria dos casos de uso.
+
+Inclui estas configurações padrão:
+
+{* ../../fastapi/openapi/docs.py ln[7:23] *}
+
+Você pode substituir qualquer um deles definindo um valor diferente no argumento `swagger_ui_parameters`.
+
+Por exemplo, para desabilitar `deepLinking` você pode passar essas configurações para `swagger_ui_parameters`:
+
+{* ../../docs_src/configure_swagger_ui/tutorial003.py hl[3] *}
+
+## Outros parâmetros da UI do Swagger
+
+Para ver todas as outras configurações possíveis que você pode usar, leia a documentação oficial dos parâmetros da UI do Swagger.
+
+## Configurações somente JavaScript
+
+A interface do usuário do Swagger também permite que outras configurações sejam objetos **somente JavaScript** (por exemplo, funções JavaScript).
+
+O FastAPI também inclui estas configurações de `predefinições` somente para JavaScript:
+
+```JavaScript
+presets: [
+ SwaggerUIBundle.presets.apis,
+ SwaggerUIBundle.SwaggerUIStandalonePreset
+]
+```
+
+Esses são objetos **JavaScript**, não strings, então você não pode passá-los diretamente do código Python.
+
+Se você precisar usar configurações somente JavaScript como essas, você pode usar um dos métodos acima. Sobrescreva todas as *operações de rotas* do Swagger UI e escreva manualmente qualquer JavaScript que você precisar.
diff --git a/docs/pt/docs/how-to/custom-docs-ui-assets.md b/docs/pt/docs/how-to/custom-docs-ui-assets.md
new file mode 100644
index 000000000..b7de6c8bd
--- /dev/null
+++ b/docs/pt/docs/how-to/custom-docs-ui-assets.md
@@ -0,0 +1,185 @@
+# Recursos Estáticos Personalizados para a UI de Documentação (Hospedagem Própria)
+
+A documentação da API usa **Swagger UI** e **ReDoc**, e cada um deles precisa de alguns arquivos JavaScript e CSS.
+
+Por padrão, esses arquivos são fornecidos por um CDN.
+
+Mas é possível personalizá-los, você pode definir um CDN específico ou providenciar os arquivos você mesmo.
+
+## CDN Personalizado para JavaScript e CSS
+
+Vamos supor que você deseja usar um CDN diferente, por exemplo, você deseja usar `https://unpkg.com/`.
+
+Isso pode ser útil se, por exemplo, você mora em um país que restringe algumas URLs.
+
+### Desativar a documentação automática
+
+O primeiro passo é desativar a documentação automática, pois por padrão, ela usa o CDN padrão.
+
+Para desativá-los, defina suas URLs como `None` ao criar seu aplicativo `FastAPI`:
+
+{* ../../docs_src/custom_docs_ui/tutorial001.py hl[8] *}
+
+### Incluir a documentação personalizada
+
+Agora você pode criar as *operações de rota* para a documentação personalizada.
+
+Você pode reutilizar as funções internas do FastAPI para criar as páginas HTML para a documentação e passar os argumentos necessários:
+
+* `openapi_url`: a URL onde a página HTML para a documentação pode obter o esquema OpenAPI para a sua API. Você pode usar aqui o atributo `app.openapi_url`.
+* `title`: o título da sua API.
+* `oauth2_redirect_url`: você pode usar `app.swagger_ui_oauth2_redirect_url` aqui para usar o padrão.
+* `swagger_js_url`: a URL onde a página HTML para a sua documentação do Swagger UI pode obter o arquivo **JavaScript**. Este é o URL do CDN personalizado.
+* `swagger_css_url`: a URL onde a página HTML para a sua documentação do Swagger UI pode obter o arquivo **CSS**. Este é o URL do CDN personalizado.
+
+E de forma semelhante para o ReDoc...
+
+{* ../../docs_src/custom_docs_ui/tutorial001.py hl[2:6,11:19,22:24,27:33] *}
+
+/// tip | Dica
+
+A *operação de rota* para `swagger_ui_redirect` é um auxiliar para quando você usa OAuth2.
+
+Se você integrar sua API com um provedor OAuth2, você poderá autenticar e voltar para a documentação da API com as credenciais adquiridas. E interagir com ela usando a autenticação OAuth2 real.
+
+Swagger UI lidará com isso nos bastidores para você, mas ele precisa desse auxiliar de "redirecionamento".
+
+///
+
+### Criar uma *operação de rota* para testar
+
+Agora, para poder testar se tudo funciona, crie uma *operação de rota*:
+
+{* ../../docs_src/custom_docs_ui/tutorial001.py hl[36:38] *}
+
+### Teste
+
+Agora, você deve ser capaz de ir para a documentação em http://127.0.0.1:8000/docs, e recarregar a página, ela carregará esses recursos do novo CDN.
+
+## Hospedagem Própria de JavaScript e CSS para a documentação
+
+Hospedar o JavaScript e o CSS pode ser útil se, por exemplo, você precisa que seu aplicativo continue funcionando mesmo offline, sem acesso aberto à Internet, ou em uma rede local.
+
+Aqui você verá como providenciar esses arquivos você mesmo, no mesmo aplicativo FastAPI, e configurar a documentação para usá-los.
+
+### Estrutura de Arquivos do Projeto
+
+Vamos supor que a estrutura de arquivos do seu projeto se pareça com isso:
+
+```
+.
+├── app
+│ ├── __init__.py
+│ ├── main.py
+```
+
+Agora crie um diretório para armazenar esses arquivos estáticos.
+
+Sua nova estrutura de arquivos poderia se parecer com isso:
+
+```
+.
+├── app
+│ ├── __init__.py
+│ ├── main.py
+└── static/
+```
+
+### Baixe os arquivos
+
+Baixe os arquivos estáticos necessários para a documentação e coloque-os no diretório `static/`.
+
+Você provavelmente pode clicar com o botão direito em cada link e selecionar uma opção semelhante a `Salvar link como...`.
+
+**Swagger UI** usa os arquivos:
+
+* `swagger-ui-bundle.js`
+* `swagger-ui.css`
+
+E o **ReDoc** usa os arquivos:
+
+* `redoc.standalone.js`
+
+Depois disso, sua estrutura de arquivos deve se parecer com:
+
+```
+.
+├── app
+│ ├── __init__.py
+│ ├── main.py
+└── static
+ ├── redoc.standalone.js
+ ├── swagger-ui-bundle.js
+ └── swagger-ui.css
+```
+
+### Prover os arquivos estáticos
+
+* Importe `StaticFiles`.
+* "Monte" a instância `StaticFiles()` em um caminho específico.
+
+{* ../../docs_src/custom_docs_ui/tutorial002.py hl[7,11] *}
+
+### Teste os arquivos estáticos
+
+Inicialize seu aplicativo e vá para http://127.0.0.1:8000/static/redoc.standalone.js.
+
+Você deverá ver um arquivo JavaScript muito longo para o **ReDoc**.
+
+Esse arquivo pode começar com algo como:
+
+```JavaScript
+/*! For license information please see redoc.standalone.js.LICENSE.txt */
+!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t(require("null")):
+...
+```
+
+Isso confirma que você está conseguindo fornecer arquivos estáticos do seu aplicativo e que você colocou os arquivos estáticos para a documentação no local correto.
+
+Agora, podemos configurar o aplicativo para usar esses arquivos estáticos para a documentação.
+
+### Desativar a documentação automática para arquivos estáticos
+
+Da mesma forma que ao usar um CDN personalizado, o primeiro passo é desativar a documentação automática, pois ela usa o CDN padrão.
+
+Para desativá-los, defina suas URLs como `None` ao criar seu aplicativo `FastAPI`:
+
+{* ../../docs_src/custom_docs_ui/tutorial002.py hl[9] *}
+
+### Incluir a documentação personalizada para arquivos estáticos
+
+E da mesma forma que com um CDN personalizado, agora você pode criar as *operações de rota* para a documentação personalizada.
+
+Novamente, você pode reutilizar as funções internas do FastAPI para criar as páginas HTML para a documentação e passar os argumentos necessários:
+
+* `openapi_url`: a URL onde a página HTML para a documentação pode obter o esquema OpenAPI para a sua API. Você pode usar aqui o atributo `app.openapi_url`.
+* `title`: o título da sua API.
+* `oauth2_redirect_url`: Você pode usar `app.swagger_ui_oauth2_redirect_url` aqui para usar o padrão.
+* `swagger_js_url`: a URL onde a página HTML para a sua documentação do Swagger UI pode obter o arquivo **JavaScript**. Este é o URL do CDN personalizado. **Este é o URL que seu aplicativo está fornecendo**.
+* `swagger_css_url`: a URL onde a página HTML para a sua documentação do Swagger UI pode obter o arquivo **CSS**. **Esse é o que seu aplicativo está fornecendo**.
+
+E de forma semelhante para o ReDoc...
+
+{* ../../docs_src/custom_docs_ui/tutorial002.py hl[2:6,14:22,25:27,30:36] *}
+
+/// tip | Dica
+
+A *operação de rota* para `swagger_ui_redirect` é um auxiliar para quando você usa OAuth2.
+
+Se você integrar sua API com um provedor OAuth2, você poderá autenticar e voltar para a documentação da API com as credenciais adquiridas. E, então, interagir com ela usando a autenticação OAuth2 real.
+
+Swagger UI lidará com isso nos bastidores para você, mas ele precisa desse auxiliar de "redirect".
+
+///
+
+### Criar uma *operação de rota* para testar arquivos estáticos
+
+Agora, para poder testar se tudo funciona, crie uma *operação de rota*:
+
+{* ../../docs_src/custom_docs_ui/tutorial002.py hl[39:41] *}
+
+### Teste a UI de Arquivos Estáticos
+
+Agora, você deve ser capaz de desconectar o WiFi, ir para a documentação em http://127.0.0.1:8000/docs, e recarregar a página.
+
+E mesmo sem Internet, você será capaz de ver a documentação da sua API e interagir com ela.
diff --git a/docs/pt/docs/how-to/custom-request-and-route.md b/docs/pt/docs/how-to/custom-request-and-route.md
new file mode 100644
index 000000000..8f432f6fe
--- /dev/null
+++ b/docs/pt/docs/how-to/custom-request-and-route.md
@@ -0,0 +1,109 @@
+# Requisições Personalizadas e Classes da APIRoute
+
+Em algum casos, você pode querer sobreescrever a lógica usada pelas classes `Request`e `APIRoute`.
+
+Em particular, isso pode ser uma boa alternativa para uma lógica em um middleware
+
+Por exemplo, se você quiser ler ou manipular o corpo da requisição antes que ele seja processado pela sua aplicação.
+
+/// danger | Perigo
+
+Isso é um recurso "avançado".
+
+Se você for um iniciante em **FastAPI** você deve considerar pular essa seção.
+
+///
+
+## Casos de Uso
+
+Alguns casos de uso incluem:
+
+* Converter requisições não-JSON para JSON (por exemplo, `msgpack`).
+* Descomprimir corpos de requisição comprimidos com gzip.
+* Registrar automaticamente todos os corpos de requisição.
+
+## Manipulando codificações de corpo de requisição personalizadas
+
+Vamos ver como usar uma subclasse personalizada de `Request` para descomprimir requisições gzip.
+
+E uma subclasse de `APIRoute` para usar essa classe de requisição personalizada.
+
+### Criar uma classe `GzipRequest` personalizada
+
+/// tip | Dica
+
+Isso é um exemplo de brincadeira para demonstrar como funciona, se você precisar de suporte para Gzip, você pode usar o [`GzipMiddleware`](../advanced/middleware.md#gzipmiddleware){.internal-link target=_blank} fornecido.
+
+///
+
+Primeiro, criamos uma classe `GzipRequest`, que irá sobrescrever o método `Request.body()` para descomprimir o corpo na presença de um cabeçalho apropriado.
+
+Se não houver `gzip` no cabeçalho, ele não tentará descomprimir o corpo.
+
+Dessa forma, a mesma classe de rota pode lidar com requisições comprimidas ou não comprimidas.
+
+{* ../../docs_src/custom_request_and_route/tutorial001.py hl[8:15] *}
+
+### Criar uma classe `GzipRoute` personalizada
+
+Em seguida, criamos uma subclasse personalizada de `fastapi.routing.APIRoute` que fará uso do `GzipRequest`.
+
+Dessa vez, ele irá sobrescrever o método `APIRoute.get_route_handler()`.
+
+Esse método retorna uma função. E essa função é o que irá receber uma requisição e retornar uma resposta.
+
+Aqui nós usamos para criar um `GzipRequest` a partir da requisição original.
+
+{* ../../docs_src/custom_request_and_route/tutorial001.py hl[18:26] *}
+
+/// note | Detalhes Técnicos
+
+Um `Request` também tem um `request.receive`, que é uma função para "receber" o corpo da requisição.
+
+Um `Request` também tem um `request.receive`, que é uma função para "receber" o corpo da requisição.
+
+O dicionário `scope` e a função `receive` são ambos parte da especificação ASGI.
+
+E essas duas coisas, `scope` e `receive`, são o que é necessário para criar uma nova instância de `Request`.
+
+Para aprender mais sobre o `Request` confira a documentação do Starlette sobre Requests.
+
+///
+
+A única coisa que a função retornada por `GzipRequest.get_route_handler` faz de diferente é converter o `Request` para um `GzipRequest`.
+
+Fazendo isso, nosso `GzipRequest` irá cuidar de descomprimir os dados (se necessário) antes de passá-los para nossas *operações de rota*.
+
+Depois disso, toda a lógica de processamento é a mesma.
+
+Mas por causa das nossas mudanças em `GzipRequest.body`, o corpo da requisição será automaticamente descomprimido quando for carregado pelo **FastAPI** quando necessário.
+
+## Acessando o corpo da requisição em um manipulador de exceção
+
+/// tip | Dica
+
+Para resolver esse mesmo problema, é provavelmente muito mais fácil usar o `body` em um manipulador personalizado para `RequestValidationError` ([Tratando Erros](../tutorial/handling-errors.md#use-the-requestvalidationerror-body){.internal-link target=_blank}).
+
+Mas esse exemplo ainda é valido e mostra como interagir com os componentes internos.
+
+///
+
+Também podemos usar essa mesma abordagem para acessar o corpo da requisição em um manipulador de exceção.
+
+Tudo que precisamos fazer é manipular a requisição dentro de um bloco `try`/`except`:
+
+{* ../../docs_src/custom_request_and_route/tutorial002.py hl[13,15] *}
+
+Se uma exceção ocorrer, a instância `Request` ainda estará em escopo, então podemos ler e fazer uso do corpo da requisição ao lidar com o erro:
+
+{* ../../docs_src/custom_request_and_route/tutorial002.py hl[16:18] *}
+
+## Classe `APIRoute` personalizada em um router
+
+você também pode definir o parametro `route_class` de uma `APIRouter`;
+
+{* ../../docs_src/custom_request_and_route/tutorial003.py hl[26] *}
+
+Nesse exemplo, as *operações de rota* sob o `router` irão usar a classe `TimedRoute` personalizada, e terão um cabeçalho extra `X-Response-Time` na resposta com o tempo que levou para gerar a resposta:
+
+{* ../../docs_src/custom_request_and_route/tutorial003.py hl[13:20] *}
diff --git a/docs/pt/docs/how-to/extending-openapi.md b/docs/pt/docs/how-to/extending-openapi.md
new file mode 100644
index 000000000..b4785edc1
--- /dev/null
+++ b/docs/pt/docs/how-to/extending-openapi.md
@@ -0,0 +1,80 @@
+# Extendendo o OpenAPI
+
+Existem alguns casos em que pode ser necessário modificar o esquema OpenAPI gerado.
+
+Nesta seção, você verá como fazer isso.
+
+## O processo normal
+
+O processo normal (padrão) é o seguinte:
+
+Uma aplicação (instância) do `FastAPI` possui um método `.openapi()` que deve retornar o esquema OpenAPI.
+
+Como parte da criação do objeto de aplicação, uma *operação de rota* para `/openapi.json` (ou para o que você definir como `openapi_url`) é registrada.
+
+Ela apenas retorna uma resposta JSON com o resultado do método `.openapi()` da aplicação.
+
+Por padrão, o que o método `.openapi()` faz é verificar se a propriedade `.openapi_schema` tem conteúdo e retorná-lo.
+
+Se não tiver, ele gera o conteúdo usando a função utilitária em `fastapi.openapi.utils.get_openapi`.
+
+E essa função `get_openapi()` recebe como parâmetros:
+
+* `title`: O título do OpenAPI, exibido na documentação.
+* `version`: A versão da sua API, por exemplo, `2.5.0`.
+* `openapi_version`: A versão da especificação OpenAPI utilizada. Por padrão, a mais recente: `3.1.0`.
+* `summary`: Um resumo curto da API.
+* `description`: A descrição da sua API, que pode incluir markdown e será exibida na documentação.
+* `routes`: Uma lista de rotas, que são cada uma das *operações de rota* registradas. Elas são obtidas de `app.routes`.
+
+/// info | Informação
+
+O parâmetro `summary` está disponível no OpenAPI 3.1.0 e superior, suportado pelo FastAPI 0.99.0 e superior.
+
+///
+
+## Sobrescrevendo os padrões
+
+Com as informações acima, você pode usar a mesma função utilitária para gerar o esquema OpenAPI e sobrescrever cada parte que precisar.
+
+Por exemplo, vamos adicionar Extensão OpenAPI do ReDoc para incluir um logo personalizado.
+
+### **FastAPI** Normal
+
+Primeiro, escreva toda a sua aplicação **FastAPI** normalmente:
+
+{* ../../docs_src/extending_openapi/tutorial001.py hl[1,4,7:9] *}
+
+### Gerar o esquema OpenAPI
+
+Em seguida, use a mesma função utilitária para gerar o esquema OpenAPI, dentro de uma função `custom_openapi()`:
+
+{* ../../docs_src/extending_openapi/tutorial001.py hl[2,15:21] *}
+
+### Modificar o esquema OpenAPI
+
+Agora, você pode adicionar a extensão do ReDoc, incluindo um `x-logo` personalizado ao "objeto" `info` no esquema OpenAPI:
+
+{* ../../docs_src/extending_openapi/tutorial001.py hl[22:24] *}
+
+### Armazenar em cache o esquema OpenAPI
+
+Você pode usar a propriedade `.openapi_schema` como um "cache" para armazenar o esquema gerado.
+
+Dessa forma, sua aplicação não precisará gerar o esquema toda vez que um usuário abrir a documentação da sua API.
+
+Ele será gerado apenas uma vez, e o mesmo esquema armazenado em cache será utilizado nas próximas requisições.
+
+{* ../../docs_src/extending_openapi/tutorial001.py hl[13:14,25:26] *}
+
+### Sobrescrever o método
+
+Agora, você pode substituir o método `.openapi()` pela sua nova função.
+
+{* ../../docs_src/extending_openapi/tutorial001.py hl[29] *}
+
+### Verificar
+
+Uma vez que você acessar http://127.0.0.1:8000/redoc, verá que está usando seu logo personalizado (neste exemplo, o logo do **FastAPI**):
+
+
diff --git a/docs/pt/docs/how-to/graphql.md b/docs/pt/docs/how-to/graphql.md
new file mode 100644
index 000000000..ef0bad7f6
--- /dev/null
+++ b/docs/pt/docs/how-to/graphql.md
@@ -0,0 +1,60 @@
+# GraphQL
+
+Como o **FastAPI** é baseado no padrão **ASGI**, é muito fácil integrar qualquer biblioteca **GraphQL** também compatível com ASGI.
+
+Você pode combinar *operações de rota* normais do FastAPI com GraphQL na mesma aplicação.
+
+/// tip | Dica
+
+**GraphQL** resolve alguns casos de uso muito específicos.
+
+Ele tem **vantagens** e **desvantagens** quando comparado a **web APIs** comuns.
+
+Certifique-se de avaliar se os **benefícios** para o seu caso de uso compensam as **desvantagens**. 🤓
+
+///
+
+## Bibliotecas GraphQL
+
+Aqui estão algumas das bibliotecas **GraphQL** que têm suporte **ASGI**. Você pode usá-las com **FastAPI**:
+
+* Strawberry 🍓
+ * Com docs para FastAPI
+* Ariadne
+ * Com docs para FastAPI
+* Tartiflette
+ * Com Tartiflette ASGI para fornecer integração ASGI
+* Graphene
+ * Com starlette-graphene3
+
+## GraphQL com Strawberry
+
+Se você precisar ou quiser trabalhar com **GraphQL**, **Strawberry** é a biblioteca **recomendada** pois tem o design mais próximo ao design do **FastAPI**, ela é toda baseada em **type annotations**.
+
+Dependendo do seu caso de uso, você pode preferir usar uma biblioteca diferente, mas se você me perguntasse, eu provavelmente sugeriria que você experimentasse o **Strawberry**.
+
+Aqui está uma pequena prévia de como você poderia integrar Strawberry com FastAPI:
+
+{* ../../docs_src/graphql/tutorial001.py hl[3,22,25:26] *}
+
+Você pode aprender mais sobre Strawberry na documentação do Strawberry.
+
+E também na documentação sobre Strawberry com FastAPI.
+
+## Antigo `GraphQLApp` do Starlette
+
+Versões anteriores do Starlette incluiam uma classe `GraphQLApp` para integrar com Graphene.
+
+Ela foi descontinuada do Starlette, mas se você tem código que a utilizava, você pode facilmente **migrar** para starlette-graphene3, que cobre o mesmo caso de uso e tem uma **interface quase idêntica**.
+
+/// tip | Dica
+
+Se você precisa de GraphQL, eu ainda recomendaria que você desse uma olhada no Strawberry, pois ele é baseado em type annotations em vez de classes e tipos personalizados.
+
+///
+
+## Saiba Mais
+
+Você pode aprender mais sobre **GraphQL** na documentação oficial do GraphQL.
+
+Você também pode ler mais sobre cada uma das bibliotecas descritas acima em seus links.
diff --git a/docs/pt/docs/how-to/index.md b/docs/pt/docs/how-to/index.md
index 664e89144..6747b01c7 100644
--- a/docs/pt/docs/how-to/index.md
+++ b/docs/pt/docs/how-to/index.md
@@ -6,6 +6,8 @@ A maioria dessas ideias será mais ou menos **independente**, e na maioria dos c
Se algo parecer interessante e útil para o seu projeto, vá em frente e dê uma olhada. Caso contrário, você pode simplesmente ignorá-lo.
-!!! tip
+/// tip
- Se você deseja **aprender FastAPI** de forma estruturada (recomendado), leia capítulo por capítulo [Tutorial - Guia de Usuário](../tutorial/index.md){.internal-link target=_blank} em vez disso.
+Se você deseja **aprender FastAPI** de forma estruturada (recomendado), leia capítulo por capítulo [Tutorial - Guia de Usuário](../tutorial/index.md){.internal-link target=_blank} em vez disso.
+
+///
diff --git a/docs/pt/docs/how-to/separate-openapi-schemas.md b/docs/pt/docs/how-to/separate-openapi-schemas.md
new file mode 100644
index 000000000..291b0e163
--- /dev/null
+++ b/docs/pt/docs/how-to/separate-openapi-schemas.md
@@ -0,0 +1,104 @@
+# Esquemas OpenAPI Separados para Entrada e Saída ou Não
+
+Ao usar **Pydantic v2**, o OpenAPI gerado é um pouco mais exato e **correto** do que antes. 😎
+
+Inclusive, em alguns casos, ele terá até **dois JSON Schemas** no OpenAPI para o mesmo modelo Pydantic, para entrada e saída, dependendo se eles possuem **valores padrão**.
+
+Vamos ver como isso funciona e como alterar se for necessário.
+
+## Modelos Pydantic para Entrada e Saída
+
+Digamos que você tenha um modelo Pydantic com valores padrão, como este:
+
+{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:7] hl[7] *}
+
+### Modelo para Entrada
+
+Se você usar esse modelo como entrada, como aqui:
+
+{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:15] hl[14] *}
+
+... então o campo `description` não será obrigatório. Porque ele tem um valor padrão de `None`.
+
+### Modelo de Entrada na Documentação
+
+Você pode confirmar que na documentação, o campo `description` não tem um **asterisco vermelho**, não é marcado como obrigatório:
+
+
+
+
+
+
+uvicorn main:app --reload...fastapi dev main.py...email_validator - para validação de email.
-Usados por Starlette:
+### Dependências `standard`
-* httpx - Necessário se você quiser utilizar o `TestClient`.
-* jinja2 - Necessário se você quiser utilizar a configuração padrão de templates.
-* python-multipart - Necessário se você quiser suporte com "parsing" de formulário, com `request.form()`.
-* itsdangerous - Necessário para suporte a `SessionMiddleware`.
-* pyyaml - Necessário para suporte a `SchemaGenerator` da Starlette (você provavelmente não precisará disso com o FastAPI).
-* graphene - Necessário para suporte a `GraphQLApp`.
+Quando você instala o FastAPI com `pip install "fastapi[standard]"`, ele vêm com o grupo `standard` (padrão) de dependências opcionais:
-Usados por FastAPI / Starlette:
+Utilizado pelo Pydantic:
-* uvicorn - para o servidor que carrega e serve sua aplicação.
-* orjson - Necessário se você quer utilizar `ORJSONResponse`.
-* ujson - Necessário se você quer utilizar `UJSONResponse`.
+* email-validator - para validação de email.
-Você pode instalar todas essas dependências com `pip install fastapi[all]`.
+Utilizado pelo Starlette:
+
+* httpx - Obrigatório caso você queira utilizar o `TestClient`.
+* jinja2 - Obrigatório se você quer utilizar a configuração padrão de templates.
+* python-multipart - Obrigatório se você deseja suporte a "parsing" de formulário, com `request.form()`.
+
+Utilizado pelo FastAPI / Starlette:
+
+* uvicorn - para o servidor que carrega e serve a sua aplicação. Isto inclui `uvicorn[standard]`, que inclui algumas dependências (e.g. `uvloop`) necessárias para servir em alta performance.
+* `fastapi-cli` - que disponibiliza o comando `fastapi`.
+
+### Sem as dependências `standard`
+
+Se você não deseja incluir as dependências opcionais `standard`, você pode instalar utilizando `pip install fastapi` ao invés de `pip install "fastapi[standard]"`.
+
+### Dpendências opcionais adicionais
+
+Existem algumas dependências adicionais que você pode querer instalar.
+
+Dependências opcionais adicionais do Pydantic:
+
+* pydantic-settings - para gerenciamento de configurações.
+* pydantic-extra-types - tipos extras para serem utilizados com o Pydantic.
+
+Dependências opcionais adicionais do FastAPI:
+
+* orjson - Obrigatório se você deseja utilizar o `ORJSONResponse`.
+* ujson - Obrigatório se você deseja utilizar o `UJSONResponse`.
## Licença
diff --git a/docs/pt/docs/python-types.md b/docs/pt/docs/python-types.md
index 52b2dad8e..90a361f40 100644
--- a/docs/pt/docs/python-types.md
+++ b/docs/pt/docs/python-types.md
@@ -1,28 +1,28 @@
# Introdução aos tipos Python
-**Python 3.6 +** tem suporte para "type hints" opcionais.
+O Python possui suporte para "dicas de tipo" ou "type hints" (também chamado de "anotações de tipo" ou "type annotations")
-Esses **"type hints"** são uma nova sintaxe (desde Python 3.6+) que permite declarar o tipo de uma variável.
+Esses **"type hints"** são uma sintaxe especial que permite declarar o tipo de uma variável.
Ao declarar tipos para suas variáveis, editores e ferramentas podem oferecer um melhor suporte.
-Este é apenas um **tutorial rápido / atualização** sobre type hints Python. Ele cobre apenas o mínimo necessário para usá-los com o **FastAPI** ... que é realmente muito pouco.
+Este é apenas um **tutorial rápido / atualização** sobre type hints do Python. Ele cobre apenas o mínimo necessário para usá-los com o **FastAPI**... que é realmente muito pouco.
O **FastAPI** é baseado nesses type hints, eles oferecem muitas vantagens e benefícios.
Mas mesmo que você nunca use o **FastAPI**, você se beneficiaria de aprender um pouco sobre eles.
-!!! note "Nota"
- Se você é um especialista em Python e já sabe tudo sobre type hints, pule para o próximo capítulo.
+/// note | Nota
+Se você é um especialista em Python e já sabe tudo sobre type hints, pule para o próximo capítulo.
+
+///
## Motivação
Vamos começar com um exemplo simples:
-```Python
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py *}
A chamada deste programa gera:
@@ -33,12 +33,10 @@ John Doe
A função faz o seguinte:
* Pega um `first_name` e `last_name`.
-* Converte a primeira letra de cada uma em maiúsculas com `title ()`.
-* Concatena com um espaço no meio.
+* Converte a primeira letra de cada uma em maiúsculas com `title()`.
+* Concatena com um espaço no meio.
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py hl[2] *}
### Edite-o
@@ -46,7 +44,7 @@ A função faz o seguinte:
Mas agora imagine que você estava escrevendo do zero.
-Em algum momento você teria iniciado a definição da função, já tinha os parâmetros prontos ...
+Em algum momento você teria iniciado a definição da função, já tinha os parâmetros prontos...
Mas então você deve chamar "esse método que converte a primeira letra em maiúscula".
@@ -80,9 +78,7 @@ para:
Esses são os "type hints":
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial002.py!}
-```
+{* ../../docs_src/python_types/tutorial002.py hl[1] *}
Isso não é o mesmo que declarar valores padrão como seria com:
@@ -94,37 +90,33 @@ Isso não é o mesmo que declarar valores padrão como seria com:
Estamos usando dois pontos (`:`), não é igual a (`=`).
-E adicionar type hints normalmente não muda o que acontece do que aconteceria sem elas.
+E adicionar type hints normalmente não muda o que acontece do que aconteceria sem eles.
Mas agora, imagine que você está novamente no meio da criação dessa função, mas com type hints.
-No mesmo ponto, você tenta acionar o preenchimento automático com o `Ctrl Space` e vê:
+No mesmo ponto, você tenta acionar o preenchimento automático com o `Ctrl+Space` e vê:
-Com isso, você pode rolar, vendo as opções, até encontrar o que "toca uma campainha":
+Com isso, você pode rolar, vendo as opções, até encontrar o que "soa familiar":
## Mais motivação
-Marque esta função, ela já possui type hints:
+Verifique esta função, ela já possui type hints:
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial003.py!}
-```
+{* ../../docs_src/python_types/tutorial003.py hl[1] *}
-Como o editor conhece os tipos de variáveis, você não apenas obtém a conclusão, mas também as verificações de erro:
+Como o editor conhece os tipos de variáveis, você não obtém apenas o preenchimento automático, mas também as verificações de erro:
-Agora você sabe que precisa corrigí-lo, converta `age` em uma string com `str (age)`:
+Agora você sabe que precisa corrigí-lo, converta `age` em uma string com `str(age)`:
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial004.py!}
-```
+{* ../../docs_src/python_types/tutorial004.py hl[2] *}
-## Tipos de declaração
+## Declarando Tipos
Você acabou de ver o local principal para declarar type hints. Como parâmetros de função.
@@ -141,44 +133,83 @@ Você pode usar, por exemplo:
* `bool`
* `bytes`
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial005.py!}
-```
+{* ../../docs_src/python_types/tutorial005.py hl[1] *}
### Tipos genéricos com parâmetros de tipo
Existem algumas estruturas de dados que podem conter outros valores, como `dict`, `list`, `set` e `tuple`. E os valores internos também podem ter seu próprio tipo.
-Para declarar esses tipos e os tipos internos, você pode usar o módulo Python padrão `typing`.
+Estes tipos que possuem tipos internos são chamados de tipos "**genéricos**". E é possível declará-los mesmo com os seus tipos internos.
-Ele existe especificamente para suportar esses type hints.
+Para declarar esses tipos e os tipos internos, você pode usar o módulo Python padrão `typing`. Ele existe especificamente para suportar esses type hints.
-#### `List`
+#### Versões mais recentes do Python
-Por exemplo, vamos definir uma variável para ser uma `lista` de `str`.
+A sintaxe utilizando `typing` é **compatível** com todas as versões, desde o Python 3.6 até as últimas, incluindo o Python 3.9, 3.10, etc.
-Em `typing`, importe `List` (com um `L` maiúsculo):
+Conforme o Python evolui, **novas versões** chegam com suporte melhorado para esses type annotations, e em muitos casos, você não precisará nem importar e utilizar o módulo `typing` para declarar os type annotations.
+
+Se você pode escolher uma versão mais recente do Python para o seu projeto, você poderá aproveitar isso ao seu favor.
+
+Em todos os documentos existem exemplos compatíveis com cada versão do Python (quando existem diferenças).
+
+Por exemplo, "**Python 3.6+**" significa que é compatível com o Python 3.6 ou superior (incluindo o 3.7, 3.8, 3.9, 3.10, etc). E "**Python 3.9+**" significa que é compatível com o Python 3.9 ou mais recente (incluindo o 3.10, etc).
+
+Se você pode utilizar a **versão mais recente do Python**, utilize os exemplos para as últimas versões. Eles terão as **melhores e mais simples sintaxes**, como por exemplo, "**Python 3.10+**".
+
+#### List
+
+Por exemplo, vamos definir uma variável para ser uma `list` de `str`.
+
+//// tab | Python 3.9+
+
+Declare uma variável com a mesma sintaxe com dois pontos (`:`)
+
+Como tipo, coloque `list`.
+
+Como a lista é o tipo que contém algum tipo interno, você coloca o tipo dentro de colchetes:
```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial006.py!}
+{!> ../../docs_src/python_types/tutorial006_py39.py!}
```
-Declare a variável com a mesma sintaxe de dois pontos (`:`).
+////
-Como o tipo, coloque a `List`.
+//// tab | Python 3.8+
-Como a lista é um tipo que contém alguns tipos internos, você os coloca entre colchetes:
+De `typing`, importe `List` (com o `L` maiúsculo):
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial006.py!}
+```
+
+Declare uma variável com a mesma sintaxe com dois pontos (`:`)
+
+Como tipo, coloque o `List` que você importou de `typing`.
+
+Como a lista é o tipo que contém algum tipo interno, você coloca o tipo dentro de colchetes:
```Python hl_lines="4"
-{!../../../docs_src/python_types/tutorial006.py!}
+{!> ../../docs_src/python_types/tutorial006.py!}
```
-!!! tip "Dica"
- Esses tipos internos entre colchetes são chamados de "parâmetros de tipo".
+////
- Nesse caso, `str` é o parâmetro de tipo passado para `List`.
+/// info | Informação
-Isso significa que: "a variável `items` é uma `list`, e cada um dos itens desta lista é uma `str`".
+Estes tipos internos dentro dos colchetes são chamados "parâmetros de tipo" (type parameters).
+
+Neste caso, `str` é o parâmetro de tipo passado para `List` (ou `list` no Python 3.9 ou superior).
+
+///
+
+Isso significa: "a variável `items` é uma `list`, e cada um dos itens desta lista é uma `str`".
+
+/// tip | Dica
+
+Se você usa o Python 3.9 ou superior, você não precisa importar `List` de `typing`. Você pode utilizar o mesmo tipo `list` no lugar.
+
+///
Ao fazer isso, seu editor pode fornecer suporte mesmo durante o processamento de itens da lista:
@@ -190,20 +221,32 @@ Observe que a variável `item` é um dos elementos da lista `items`.
E, ainda assim, o editor sabe que é um `str` e fornece suporte para isso.
-#### `Tuple` e `Set`
+#### Tuple e Set
Você faria o mesmo para declarar `tuple`s e `set`s:
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial007.py!}
+//// tab | Python 3.9+
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial007_py39.py!}
```
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial007.py!}
+```
+
+////
+
Isso significa que:
* A variável `items_t` é uma `tuple` com 3 itens, um `int`, outro `int` e uma `str`.
* A variável `items_s` é um `set`, e cada um de seus itens é do tipo `bytes`.
-#### `Dict`
+#### Dict
Para definir um `dict`, você passa 2 parâmetros de tipo, separados por vírgulas.
@@ -211,38 +254,181 @@ O primeiro parâmetro de tipo é para as chaves do `dict`.
O segundo parâmetro de tipo é para os valores do `dict`:
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial008.py!}
+//// tab | Python 3.9+
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008_py39.py!}
```
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial008.py!}
+```
+
+////
+
Isso significa que:
* A variável `prices` é um dict`:
* As chaves deste `dict` são do tipo `str` (digamos, o nome de cada item).
* Os valores deste `dict` são do tipo `float` (digamos, o preço de cada item).
-#### `Opcional`
+#### Union
-Você também pode usar o `Opcional` para declarar que uma variável tem um tipo, como `str`, mas que é "opcional", o que significa que também pode ser `None`:
+Você pode declarar que uma variável pode ser de qualquer um dentre **diversos tipos**. Por exemplo, um `int` ou um `str`.
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial009.py!}
+No Python 3.6 e superior (incluindo o Python 3.10), você pode utilizar o tipo `Union` de `typing`, e colocar dentro dos colchetes os possíveis tipos aceitáveis.
+
+No Python 3.10 também existe uma **nova sintaxe** onde você pode colocar os possívels tipos separados por uma barra vertical (`|`).
+
+//// tab | Python 3.10+
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008b_py310.py!}
```
-O uso de `Opcional [str]` em vez de apenas `str` permitirá que o editor o ajude a detectar erros, onde você pode estar assumindo que um valor é sempre um `str`, quando na verdade também pode ser `None`.
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial008b.py!}
+```
+
+////
+
+Em ambos os casos, isso significa que `item` poderia ser um `int` ou um `str`.
+
+
+#### Possívelmente `None`
+
+Você pode declarar que um valor pode ter um tipo, como `str`, mas que ele também pode ser `None`.
+
+No Python 3.6 e superior (incluindo o Python 3.10) você pode declará-lo importando e utilizando `Optional` do módulo `typing`.
+
+```Python hl_lines="1 4"
+{!../../docs_src/python_types/tutorial009.py!}
+```
+
+O uso de `Optional[str]` em vez de apenas `str` permitirá que o editor o ajude a detectar erros, onde você pode estar assumindo que um valor é sempre um `str`, quando na verdade também pode ser `None`.
+
+`Optional[Something]` é na verdade um atalho para `Union[Something, None]`, eles são equivalentes.
+
+Isso também significa que no Python 3.10, você pode utilizar `Something | None`:
+
+//// tab | Python 3.10+
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial009_py310.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial009.py!}
+```
+
+////
+
+//// tab | Python 3.8+ alternative
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial009b.py!}
+```
+
+////
+
+#### Utilizando `Union` ou `Optional`
+
+Se você está utilizando uma versão do Python abaixo da 3.10, aqui vai uma dica do meu ponto de vista bem **subjetivo**:
+
+* 🚨 Evite utilizar `Optional[SomeType]`
+* No lugar, ✨ **use `Union[SomeType, None]`** ✨.
+
+Ambos são equivalentes, e no final das contas, eles são o mesmo. Mas eu recomendaria o `Union` ao invés de `Optional` porque a palavra **Optional** parece implicar que o valor é opcional, quando na verdade significa "isso pode ser `None`", mesmo que ele não seja opcional e ainda seja obrigatório.
+
+Eu penso que `Union[SomeType, None]` é mais explícito sobre o que ele significa.
+
+Isso é apenas sobre palavras e nomes. Mas estas palavras podem afetar como os seus colegas de trabalho pensam sobre o código.
+
+Por exemplo, vamos pegar esta função:
+
+{* ../../docs_src/python_types/tutorial009c.py hl[1,4] *}
+
+O paâmetro `name` é definido como `Optional[str]`, mas ele **não é opcional**, você não pode chamar a função sem o parâmetro:
+
+```Python
+say_hi() # Oh, no, this throws an error! 😱
+```
+
+O parâmetro `name` **ainda é obrigatório** (não *opicional*) porque ele não possui um valor padrão. Mesmo assim, `name` aceita `None` como valor:
+
+```Python
+say_hi(name=None) # This works, None is valid 🎉
+```
+
+A boa notícia é, quando você estiver no Python 3.10 você não precisará se preocupar mais com isso, pois você poderá simplesmente utilizar o `|` para definir uniões de tipos:
+
+{* ../../docs_src/python_types/tutorial009c_py310.py hl[1,4] *}
+
+E então você não precisará mais se preocupar com nomes como `Optional` e `Union`. 😎
#### Tipos genéricos
-Esses tipos que usam parâmetros de tipo entre colchetes, como:
+Esses tipos que usam parâmetros de tipo entre colchetes são chamados **tipos genéricos** ou **genéricos**. Por exemplo:
+
+//// tab | Python 3.10+
+
+Você pode utilizar os mesmos tipos internos como genéricos (com colchetes e tipos dentro):
+
+* `list`
+* `tuple`
+* `set`
+* `dict`
+
+E o mesmo como no Python 3.8, do módulo `typing`:
+
+* `Union`
+* `Optional` (o mesmo que com o 3.8)
+* ...entro outros.
+
+No Python 3.10, como uma alternativa para a utilização dos genéricos `Union` e `Optional`, você pode usar a barra vertical (`|`) para declarar uniões de tipos. Isso é muito melhor e mais simples.
+
+////
+
+//// tab | Python 3.9+
+
+Você pode utilizar os mesmos tipos internos como genéricos (com colchetes e tipos dentro):
+
+* `list`
+* `tuple`
+* `set`
+* `dict`
+
+E o mesmo como no Python 3.8, do módulo `typing`:
+
+* `Union`
+* `Optional`
+* ...entro outros.
+
+////
+
+//// tab | Python 3.8+
* `List`
* `Tuple`
* `Set`
* `Dict`
-* `Opcional`
-* ...e outros.
+* `Union`
+* `Optional`
+* ...entro outros.
-são chamados **tipos genéricos** ou **genéricos**.
+////
### Classes como tipos
@@ -250,23 +436,23 @@ Você também pode declarar uma classe como o tipo de uma variável.
Digamos que você tenha uma classe `Person`, com um nome:
-```Python hl_lines="1 2 3"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
Então você pode declarar que uma variável é do tipo `Person`:
-```Python hl_lines="6"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[6] *}
E então, novamente, você recebe todo o suporte do editor:
+Perceba que isso significa que "`one_person` é uma **instância** da classe `Person`".
+
+Isso não significa que "`one_person` é a **classe** chamada `Person`".
+
## Modelos Pydantic
- Pydantic é uma biblioteca Python para executar a validação de dados.
+O Pydantic é uma biblioteca Python para executar a validação de dados.
Você declara a "forma" dos dados como classes com atributos.
@@ -278,18 +464,93 @@ E você recebe todo o suporte do editor com esse objeto resultante.
Retirado dos documentos oficiais dos Pydantic:
+//// tab | Python 3.10+
+
```Python
-{!../../../docs_src/python_types/tutorial011.py!}
+{!> ../../docs_src/python_types/tutorial011_py310.py!}
```
-!!! info "Informação"
- Para saber mais sobre o Pydantic, verifique seus documentos .
+////
-**FastAPI** é todo baseado em Pydantic.
+//// tab | Python 3.9+
+
+```Python
+{!> ../../docs_src/python_types/tutorial011_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python
+{!> ../../docs_src/python_types/tutorial011.py!}
+```
+
+////
+
+/// info | Informação
+
+Para saber mais sobre o Pydantic, verifique a sua documentação.
+
+///
+
+O **FastAPI** é todo baseado em Pydantic.
Você verá muito mais disso na prática no [Tutorial - Guia do usuário](tutorial/index.md){.internal-link target=_blank}.
-## Type hints em **FastAPI**
+/// tip | Dica
+
+O Pydantic tem um comportamento especial quando você usa `Optional` ou `Union[Something, None]` sem um valor padrão. Você pode ler mais sobre isso na documentação do Pydantic sobre campos Opcionais Obrigatórios.
+
+///
+
+
+## Type Hints com Metadados de Anotações
+
+O Python possui uma funcionalidade que nos permite incluir **metadados adicionais** nos type hints utilizando `Annotated`.
+
+//// tab | Python 3.9+
+
+No Python 3.9, `Annotated` é parte da biblioteca padrão, então você pode importá-lo de `typing`.
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial013_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+Em versões abaixo do Python 3.9, você importa `Annotated` de `typing_extensions`.
+
+Ele já estará instalado com o **FastAPI**.
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial013.py!}
+```
+
+////
+
+O Python em si não faz nada com este `Annotated`. E para editores e outras ferramentas, o tipo ainda é `str`.
+
+Mas você pode utilizar este espaço dentro do `Annotated` para fornecer ao **FastAPI** metadata adicional sobre como você deseja que a sua aplicação se comporte.
+
+O importante aqui de se lembrar é que **o primeiro *type parameter*** que você informar ao `Annotated` é o **tipo de fato**. O resto é apenas metadado para outras ferramentas.
+
+Por hora, você precisa apenas saber que o `Annotated` existe, e que ele é Python padrão. 😎
+
+Mais tarde você verá o quão **poderoso** ele pode ser.
+
+/// tip | Dica
+
+O fato de que isso é **Python padrão** significa que você ainda obtém a **melhor experiência de desenvolvedor possível** no seu editor, com as ferramentas que você utiliza para analisar e refatorar o seu código, etc. ✨
+
+E também que o seu código será muito compatível com diversas outras ferramentas e bibliotecas Python. 🚀
+
+///
+
+
+## Type hints no **FastAPI**
O **FastAPI** aproveita esses type hints para fazer várias coisas.
@@ -298,18 +559,21 @@ Com o **FastAPI**, você declara parâmetros com type hints e obtém:
* **Suporte ao editor**.
* **Verificações de tipo**.
-... e **FastAPI** usa as mesmas declarações para:
+... e o **FastAPI** usa as mesmas declarações para:
-* **Definir requisitos**: dos parâmetros do caminho da solicitação, parâmetros da consulta, cabeçalhos, corpos, dependências, etc.
+* **Definir requisitos**: dos parâmetros de rota, parâmetros da consulta, cabeçalhos, corpos, dependências, etc.
* **Converter dados**: da solicitação para o tipo necessário.
* **Validar dados**: provenientes de cada solicitação:
- * A geração de **erros automáticos** retornou ao cliente quando os dados são inválidos.
-* **Documente** a API usando OpenAPI:
+ * Gerando **erros automáticos** retornados ao cliente quando os dados são inválidos.
+* **Documentar** a API usando OpenAPI:
* que é usado pelas interfaces de usuário da documentação interativa automática.
Tudo isso pode parecer abstrato. Não se preocupe. Você verá tudo isso em ação no [Tutorial - Guia do usuário](tutorial/index.md){.internal-link target=_blank}.
O importante é que, usando tipos padrão de Python, em um único local (em vez de adicionar mais classes, decoradores, etc.), o **FastAPI** fará muito trabalho para você.
-!!! info "Informação"
- Se você já passou por todo o tutorial e voltou para ver mais sobre os tipos, um bom recurso é a "cheat sheet" do `mypy` .
+/// info | Informação
+
+Se você já passou por todo o tutorial e voltou para ver mais sobre os tipos, um bom recurso é a "cheat sheet" do `mypy` .
+
+///
diff --git a/docs/pt/docs/reference/apirouter.md b/docs/pt/docs/reference/apirouter.md
deleted file mode 100644
index 7568601c9..000000000
--- a/docs/pt/docs/reference/apirouter.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# Classe `APIRouter`
-
-Aqui está a informação de referência para a classe `APIRouter`, com todos os seus parâmetros, atributos e métodos.
-
-Você pode importar a classe `APIRouter` diretamente do `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/pt/docs/reference/background.md b/docs/pt/docs/reference/background.md
deleted file mode 100644
index bfc15aa76..000000000
--- a/docs/pt/docs/reference/background.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# Tarefas em Segundo Plano - `BackgroundTasks`
-
-Você pode declarar um parâmetro em uma *função de operação de rota* ou em uma função de dependência com o tipo `BackgroundTasks`, e então utilizá-lo para agendar a execução de tarefas em segundo plano após o envio da resposta.
-
-Você pode importá-lo diretamente do `fastapi`:
-
-```python
-from fastapi import BackgroundTasks
-```
-
-::: fastapi.BackgroundTasks
diff --git a/docs/pt/docs/reference/exceptions.md b/docs/pt/docs/reference/exceptions.md
deleted file mode 100644
index d6b5d2613..000000000
--- a/docs/pt/docs/reference/exceptions.md
+++ /dev/null
@@ -1,20 +0,0 @@
-# Exceções - `HTTPException` e `WebSocketException`
-
-Essas são as exceções que você pode lançar para mostrar erros ao cliente.
-
-Quando você lança uma exceção, como aconteceria com o Python normal, o restante da execução é abortado. Dessa forma, você pode lançar essas exceções de qualquer lugar do código para abortar uma solicitação e mostrar o erro ao cliente.
-
-Você pode usar:
-
-* `HTTPException`
-* `WebSocketException`
-
-Essas exceções podem ser importadas diretamente do `fastapi`:
-
-```python
-from fastapi import HTTPException, WebSocketException
-```
-
-::: fastapi.HTTPException
-
-::: fastapi.WebSocketException
diff --git a/docs/pt/docs/reference/index.md b/docs/pt/docs/reference/index.md
deleted file mode 100644
index 533a6a996..000000000
--- a/docs/pt/docs/reference/index.md
+++ /dev/null
@@ -1,6 +0,0 @@
-# Referência - API de Código
-
-Aqui está a referência ou API de código, as classes, funções, parâmetros, atributos e todas as partes do FastAPI que você pode usar em suas aplicações.
-
-Se você quer **aprender FastAPI**, é muito melhor ler o
-[FastAPI Tutorial](https://fastapi.tiangolo.com/tutorial/).
diff --git a/docs/pt/docs/tutorial/background-tasks.md b/docs/pt/docs/tutorial/background-tasks.md
index 625fa2b11..0f3796371 100644
--- a/docs/pt/docs/tutorial/background-tasks.md
+++ b/docs/pt/docs/tutorial/background-tasks.md
@@ -15,9 +15,7 @@ Isso inclui, por exemplo:
Primeiro, importe `BackgroundTasks` e defina um parâmetro em sua _função de operação de caminho_ com uma declaração de tipo de `BackgroundTasks`:
-```Python hl_lines="1 13"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *}
O **FastAPI** criará o objeto do tipo `BackgroundTasks` para você e o passará como esse parâmetro.
@@ -33,17 +31,13 @@ Nesse caso, a função de tarefa gravará em um arquivo (simulando o envio de um
E como a operação de gravação não usa `async` e `await`, definimos a função com `def` normal:
-```Python hl_lines="6-9"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *}
## Adicionar a tarefa em segundo plano
Dentro de sua _função de operação de caminho_, passe sua função de tarefa para o objeto _tarefas em segundo plano_ com o método `.add_task()`:
-```Python hl_lines="14"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[14] *}
`.add_task()` recebe como argumentos:
@@ -57,9 +51,7 @@ Usar `BackgroundTasks` também funciona com o sistema de injeção de dependênc
O **FastAPI** sabe o que fazer em cada caso e como reutilizar o mesmo objeto, de forma que todas as tarefas em segundo plano sejam mescladas e executadas em segundo plano posteriormente:
-```Python hl_lines="13 15 22 25"
-{!../../../docs_src/background_tasks/tutorial002.py!}
-```
+{* ../../docs_src/background_tasks/tutorial002.py hl[13,15,22,25] *}
Neste exemplo, as mensagens serão gravadas no arquivo `log.txt` _após_ o envio da resposta.
@@ -85,8 +77,6 @@ Se você precisa realizar cálculos pesados em segundo plano e não necess
Eles tendem a exigir configurações mais complexas, um gerenciador de fila de mensagens/tarefas, como RabbitMQ ou Redis, mas permitem que você execute tarefas em segundo plano em vários processos e, especialmente, em vários servidores.
-Para ver um exemplo, verifique os [Geradores de projeto](../project-generation.md){.internal-link target=\_blank}, todos incluem celery já configurado.
-
Mas se você precisa acessar variáveis e objetos do mesmo aplicativo **FastAPI**, ou precisa realizar pequenas tarefas em segundo plano (como enviar uma notificação por e-mail), você pode simplesmente usar `BackgroundTasks`.
## Recapitulando
diff --git a/docs/pt/docs/tutorial/bigger-applications.md b/docs/pt/docs/tutorial/bigger-applications.md
new file mode 100644
index 000000000..b621f3c72
--- /dev/null
+++ b/docs/pt/docs/tutorial/bigger-applications.md
@@ -0,0 +1,556 @@
+# Aplicações Maiores - Múltiplos Arquivos
+
+Se você está construindo uma aplicação ou uma API web, é raro que você possa colocar tudo em um único arquivo.
+
+**FastAPI** oferece uma ferramenta conveniente para estruturar sua aplicação, mantendo toda a flexibilidade.
+
+/// info | Informação
+
+Se você vem do Flask, isso seria o equivalente aos Blueprints do Flask.
+
+///
+
+## Um exemplo de estrutura de arquivos
+
+Digamos que você tenha uma estrutura de arquivos como esta:
+
+```
+.
+├── app
+│ ├── __init__.py
+│ ├── main.py
+│ ├── dependencies.py
+│ └── routers
+│ │ ├── __init__.py
+│ │ ├── items.py
+│ │ └── users.py
+│ └── internal
+│ ├── __init__.py
+│ └── admin.py
+```
+
+/// tip | Dica
+
+Existem vários arquivos `__init__.py` presentes em cada diretório ou subdiretório.
+
+Isso permite a importação de código de um arquivo para outro.
+
+Por exemplo, no arquivo `app/main.py`, você poderia ter uma linha como:
+
+```
+from app.routers import items
+```
+
+///
+
+* O diretório `app` contém todo o código da aplicação. Ele possui um arquivo `app/__init__.py` vazio, o que o torna um "pacote Python" (uma coleção de "módulos Python"): `app`.
+* Dentro dele, o arquivo `app/main.py` está localizado em um pacote Python (diretório com `__init__.py`). Portanto, ele é um "módulo" desse pacote: `app.main`.
+* Existem também um arquivo `app/dependencies.py`, assim como o `app/main.py`, ele é um "módulo": `app.dependencies`.
+* Há um subdiretório `app/routers/` com outro arquivo `__init__.py`, então ele é um "subpacote Python": `app.routers`.
+* O arquivo `app/routers/items.py` está dentro de um pacote, `app/routers/`, portanto, é um "submódulo": `app.routers.items`.
+* O mesmo com `app/routers/users.py`, ele é outro submódulo: `app.routers.users`.
+* Há também um subdiretório `app/internal/` com outro arquivo `__init__.py`, então ele é outro "subpacote Python":`app.internal`.
+* E o arquivo `app/internal/admin.py` é outro submódulo: `app.internal.admin`.
+
+
+
+## Incluir o mesmo roteador várias vezes com `prefixos` diferentes
+
+Você também pode usar `.include_router()` várias vezes com o *mesmo* roteador usando prefixos diferentes.
+
+Isso pode ser útil, por exemplo, para expor a mesma API sob prefixos diferentes, por exemplo, `/api/v1` e `/api/latest`.
+
+Esse é um uso avançado que você pode não precisar, mas está lá caso precise.
+
+## Incluir um `APIRouter` em outro
+
+Da mesma forma que você pode incluir um `APIRouter` em um aplicativo `FastAPI`, você pode incluir um `APIRouter` em outro `APIRouter` usando:
+
+```Python
+router.include_router(other_router)
+```
+
+Certifique-se de fazer isso antes de incluir `router` no aplicativo `FastAPI`, para que as *operações de rota* de `other_router` também sejam incluídas.
diff --git a/docs/pt/docs/tutorial/body-fields.md b/docs/pt/docs/tutorial/body-fields.md
index 8f3313ae9..e7dfb07f2 100644
--- a/docs/pt/docs/tutorial/body-fields.md
+++ b/docs/pt/docs/tutorial/body-fields.md
@@ -6,34 +6,39 @@ Da mesma forma que você pode declarar validações adicionais e metadados nos p
Primeiro, você tem que importá-lo:
-```Python hl_lines="4"
-{!../../../docs_src/body_fields/tutorial001.py!}
-```
+{* ../../docs_src/body_fields/tutorial001.py hl[4] *}
-!!! warning "Aviso"
- Note que `Field` é importado diretamente do `pydantic`, não do `fastapi` como todo o resto (`Query`, `Path`, `Body`, etc).
+/// warning | Aviso
+
+Note que `Field` é importado diretamente do `pydantic`, não do `fastapi` como todo o resto (`Query`, `Path`, `Body`, etc).
+
+///
## Declare atributos do modelo
Você pode então utilizar `Field` com atributos do modelo:
-```Python hl_lines="11-14"
-{!../../../docs_src/body_fields/tutorial001.py!}
-```
+{* ../../docs_src/body_fields/tutorial001.py hl[11:14] *}
`Field` funciona da mesma forma que `Query`, `Path` e `Body`, ele possui todos os mesmos parâmetros, etc.
-!!! note "Detalhes técnicos"
- Na realidade, `Query`, `Path` e outros que você verá em seguida, criam objetos de subclasses de uma classe `Param` comum, que é ela mesma uma subclasse da classe `FieldInfo` do Pydantic.
+/// note | Detalhes técnicos
- E `Field` do Pydantic retorna uma instância de `FieldInfo` também.
+Na realidade, `Query`, `Path` e outros que você verá em seguida, criam objetos de subclasses de uma classe `Param` comum, que é ela mesma uma subclasse da classe `FieldInfo` do Pydantic.
- `Body` também retorna objetos de uma subclasse de `FieldInfo` diretamente. E tem outras que você verá mais tarde que são subclasses da classe `Body`.
+E `Field` do Pydantic retorna uma instância de `FieldInfo` também.
- Lembre-se que quando você importa `Query`, `Path`, e outros de `fastapi`, esse são na realidade funções que retornam classes especiais.
+`Body` também retorna objetos de uma subclasse de `FieldInfo` diretamente. E tem outras que você verá mais tarde que são subclasses da classe `Body`.
-!!! tip "Dica"
- Note como cada atributo do modelo com um tipo, valor padrão e `Field` possuem a mesma estrutura que parâmetros de *funções de operações de rota*, com `Field` ao invés de `Path`, `Query` e `Body`.
+Lembre-se que quando você importa `Query`, `Path`, e outros de `fastapi`, esse são na realidade funções que retornam classes especiais.
+
+///
+
+/// tip | Dica
+
+Note como cada atributo do modelo com um tipo, valor padrão e `Field` possuem a mesma estrutura que parâmetros de *funções de operações de rota*, com `Field` ao invés de `Path`, `Query` e `Body`.
+
+///
## Adicione informações extras
diff --git a/docs/pt/docs/tutorial/body-multiple-params.md b/docs/pt/docs/tutorial/body-multiple-params.md
index 7d0435a6b..eda9b4dff 100644
--- a/docs/pt/docs/tutorial/body-multiple-params.md
+++ b/docs/pt/docs/tutorial/body-multiple-params.md
@@ -8,20 +8,13 @@ Primeiro, é claro, você pode misturar `Path`, `Query` e declarações de parâ
E você também pode declarar parâmetros de corpo como opcionais, definindo o valor padrão com `None`:
-=== "Python 3.10+"
+{* ../../docs_src/body_multiple_params/tutorial001_py310.py hl[17:19] *}
- ```Python hl_lines="17-19"
- {!> ../../../docs_src/body_multiple_params/tutorial001_py310.py!}
- ```
+/// note | Nota
-=== "Python 3.8+"
+Repare que, neste caso, o `item` que seria capturado a partir do corpo é opcional. Visto que ele possui `None` como valor padrão.
- ```Python hl_lines="19-21"
- {!> ../../../docs_src/body_multiple_params/tutorial001.py!}
- ```
-
-!!! note "Nota"
- Repare que, neste caso, o `item` que seria capturado a partir do corpo é opcional. Visto que ele possui `None` como valor padrão.
+///
## Múltiplos parâmetros de corpo
@@ -38,17 +31,7 @@ No exemplo anterior, as *operações de rota* esperariam um JSON no corpo conten
Mas você pode também declarar múltiplos parâmetros de corpo, por exemplo, `item` e `user`:
-=== "Python 3.10+"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_multiple_params/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/body_multiple_params/tutorial002.py!}
- ```
+{* ../../docs_src/body_multiple_params/tutorial002_py310.py hl[20] *}
Neste caso, o **FastAPI** perceberá que existe mais de um parâmetro de corpo na função (dois parâmetros que são modelos Pydantic).
@@ -69,9 +52,11 @@ Então, ele usará o nome dos parâmetros como chaves (nome dos campos) no corpo
}
```
-!!! note "Nota"
- Repare que mesmo que o `item` esteja declarado da mesma maneira que antes, agora é esperado que ele esteja dentro do corpo com uma chave `item`.
+/// note | Nota
+Repare que mesmo que o `item` esteja declarado da mesma maneira que antes, agora é esperado que ele esteja dentro do corpo com uma chave `item`.
+
+///
O **FastAPI** fará a conversão automática a partir da requisição, assim esse parâmetro `item` receberá seu respectivo conteúdo e o mesmo ocorrerá com `user`.
@@ -87,17 +72,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.8+"
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/body_multiple_params/tutorial003.py!}
- ```
-
-=== "Python 3.10+"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_multiple_params/tutorial003_py310.py!}
- ```
+{* ../../docs_src/body_multiple_params/tutorial003.py hl[22] *}
Neste caso, o **FastAPI** esperará um corpo como:
@@ -137,20 +112,13 @@ q: str | None = None
Por exemplo:
-=== "Python 3.10+"
+{* ../../docs_src/body_multiple_params/tutorial004_py310.py hl[26] *}
- ```Python hl_lines="26"
- {!> ../../../docs_src/body_multiple_params/tutorial004_py310.py!}
- ```
+/// info | Informação
-=== "Python 3.8+"
+`Body` também possui todas as validações adicionais e metadados de parâmetros como em `Query`,`Path` e outras que você verá depois.
- ```Python hl_lines="27"
- {!> ../../../docs_src/body_multiple_params/tutorial004.py!}
- ```
-
-!!! info "Informação"
- `Body` também possui todas as validações adicionais e metadados de parâmetros como em `Query`,`Path` e outras que você verá depois.
+///
## Declare um único parâmetro de corpo indicando sua chave
@@ -166,17 +134,7 @@ item: Item = Body(embed=True)
como em:
-=== "Python 3.10+"
-
- ```Python hl_lines="15"
- {!> ../../../docs_src/body_multiple_params/tutorial005_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="17"
- {!> ../../../docs_src/body_multiple_params/tutorial005.py!}
- ```
+{* ../../docs_src/body_multiple_params/tutorial005_py310.py hl[15] *}
Neste caso o **FastAPI** esperará um corpo como:
diff --git a/docs/pt/docs/tutorial/body-nested-models.md b/docs/pt/docs/tutorial/body-nested-models.md
index c9d0b8bb6..2954ae3db 100644
--- a/docs/pt/docs/tutorial/body-nested-models.md
+++ b/docs/pt/docs/tutorial/body-nested-models.md
@@ -6,9 +6,7 @@ Com o **FastAPI**, você pode definir, validar, documentar e usar modelos profun
Você pode definir um atributo como um subtipo. Por exemplo, uma `list` do Python:
-```Python hl_lines="14"
-{!../../../docs_src/body_nested_models/tutorial001.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial001.py hl[14] *}
Isso fará com que tags seja uma lista de itens mesmo sem declarar o tipo dos elementos desta lista.
@@ -20,9 +18,7 @@ Mas o Python tem uma maneira específica de declarar listas com tipos internos o
Primeiramente, importe `List` do módulo `typing` que já vem por padrão no Python:
-```Python hl_lines="1"
-{!../../../docs_src/body_nested_models/tutorial002.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *}
### Declare a `List` com um parâmetro de tipo
@@ -44,9 +40,7 @@ Use a mesma sintaxe padrão para atributos de modelo com tipos internos.
Portanto, em nosso exemplo, podemos fazer com que `tags` sejam especificamente uma "lista de strings":
-```Python hl_lines="14"
-{!../../../docs_src/body_nested_models/tutorial002.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial002.py hl[14] *}
## Tipo "set"
@@ -58,9 +52,7 @@ E que o Python tem um tipo de dados especial para conjuntos de itens únicos, o
Então podemos importar `Set` e declarar `tags` como um `set` de `str`s:
-```Python hl_lines="1 14"
-{!../../../docs_src/body_nested_models/tutorial003.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial003.py hl[1,14] *}
Com isso, mesmo que você receba uma requisição contendo dados duplicados, ela será convertida em um conjunto de itens exclusivos.
@@ -82,17 +74,13 @@ Tudo isso, aninhado arbitrariamente.
Por exemplo, nós podemos definir um modelo `Image`:
-```Python hl_lines="9-11"
-{!../../../docs_src/body_nested_models/tutorial004.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial004.py hl[9:11] *}
### Use o sub-modelo como um tipo
E então podemos usa-lo como o tipo de um atributo:
-```Python hl_lines="20"
-{!../../../docs_src/body_nested_models/tutorial004.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial004.py hl[20] *}
Isso significa que o **FastAPI** vai esperar um corpo similar à:
@@ -125,9 +113,7 @@ Para ver todas as opções possíveis, cheque a documentação para osHTTP `PUT`.
+
+Você pode usar `jsonable_encoder` para converter os dados de entrada em dados que podem ser armazenados como JSON (por exemplo, com um banco de dados NoSQL). Por exemplo, convertendo `datetime` em `str`.
+
+{* ../../docs_src/body_updates/tutorial001_py310.py hl[28:33] *}
+
+`PUT` é usado para receber dados que devem substituir os dados existentes.
+
+### Aviso sobre a substituição
+
+Isso significa que, se você quiser atualizar o item `bar` usando `PUT` com um corpo contendo:
+
+```Python
+{
+ "name": "Barz",
+ "price": 3,
+ "description": None,
+}
+```
+
+Como ele não inclui o atributo já armazenado `"tax": 20.2`, o modelo de entrada assumiria o valor padrão de `"tax": 10.5`.
+
+E os dados seriam salvos com esse "novo" `tax` de `10.5`.
+
+## Atualizações parciais com `PATCH`
+
+Você também pode usar a operação HTTP `PATCH` para *atualizar* parcialmente os dados.
+
+Isso significa que você pode enviar apenas os dados que deseja atualizar, deixando o restante intacto.
+
+/// note | Nota
+
+`PATCH` é menos comumente usado e conhecido do que `PUT`.
+
+E muitas equipes usam apenas `PUT`, mesmo para atualizações parciais.
+
+Você é **livre** para usá-los como preferir, **FastAPI** não impõe restrições.
+
+Mas este guia te dá uma ideia de como eles são destinados a serem usados.
+
+///
+
+### Usando o parâmetro `exclude_unset` do Pydantic
+
+Se você quiser receber atualizações parciais, é muito útil usar o parâmetro `exclude_unset` no método `.model_dump()` do modelo do Pydantic.
+
+Como `item.model_dump(exclude_unset=True)`.
+
+/// info | Informação
+
+No Pydantic v1, o método que era chamado `.dict()` e foi depreciado (mas ainda suportado) no Pydantic v2. Agora, deve-se usar o método `.model_dump()`.
+
+Os exemplos aqui usam `.dict()` para compatibilidade com o Pydantic v1, mas você deve usar `.model_dump()` a partir do Pydantic v2.
+
+///
+
+Isso gera um `dict` com apenas os dados definidos ao criar o modelo `item`, excluindo os valores padrão.
+
+Então, você pode usar isso para gerar um `dict` com apenas os dados definidos (enviados na solicitação), omitindo valores padrão:
+
+{* ../../docs_src/body_updates/tutorial002_py310.py hl[32] *}
+
+### Usando o parâmetro `update` do Pydantic
+
+Agora, você pode criar uma cópia do modelo existente usando `.model_copy()`, e passar o parâmetro `update` com um `dict` contendo os dados para atualizar.
+
+/// info | Informação
+
+No Pydantic v1, o método era chamado `.copy()`, ele foi depreciado (mas ainda suportado) no Pydantic v2, e renomeado para `.model_copy()`.
+
+Os exemplos aqui usam `.copy()` para compatibilidade com o Pydantic v1, mas você deve usar `.model_copy()` com o Pydantic v2.
+
+///
+
+Como `stored_item_model.model_copy(update=update_data)`:
+
+{* ../../docs_src/body_updates/tutorial002_py310.py hl[33] *}
+
+### Recapitulando as atualizações parciais
+
+Resumindo, para aplicar atualizações parciais você pode:
+
+* (Opcionalmente) usar `PATCH` em vez de `PUT`.
+* Recuperar os dados armazenados.
+* Colocar esses dados em um modelo do Pydantic.
+* Gerar um `dict` sem valores padrão a partir do modelo de entrada (usando `exclude_unset`).
+ * Dessa forma, você pode atualizar apenas os valores definidos pelo usuário, em vez de substituir os valores já armazenados com valores padrão em seu modelo.
+* Criar uma cópia do modelo armazenado, atualizando seus atributos com as atualizações parciais recebidas (usando o parâmetro `update`).
+* Converter o modelo copiado em algo que possa ser armazenado no seu banco de dados (por exemplo, usando o `jsonable_encoder`).
+ * Isso é comparável ao uso do método `.model_dump()`, mas garante (e converte) os valores para tipos de dados que possam ser convertidos em JSON, por exemplo, `datetime` para `str`.
+* Salvar os dados no seu banco de dados.
+* Retornar o modelo atualizado.
+
+{* ../../docs_src/body_updates/tutorial002_py310.py hl[28:35] *}
+
+/// tip | Dica
+
+Você pode realmente usar essa mesma técnica com uma operação HTTP `PUT`.
+
+Mas o exemplo aqui usa `PATCH` porque foi criado para esses casos de uso.
+
+///
+
+/// note | Nota
+
+Observe que o modelo de entrada ainda é validado.
+
+Portanto, se você quiser receber atualizações parciais que possam omitir todos os atributos, precisará ter um modelo com todos os atributos marcados como opcionais (com valores padrão ou `None`).
+
+Para distinguir os modelos com todos os valores opcionais para **atualizações** e modelos com valores obrigatórios para **criação**, você pode usar as ideias descritas em [Modelos Adicionais](extra-models.md){.internal-link target=_blank}.
+
+///
diff --git a/docs/pt/docs/tutorial/body.md b/docs/pt/docs/tutorial/body.md
index 713bea2d1..2508d7981 100644
--- a/docs/pt/docs/tutorial/body.md
+++ b/docs/pt/docs/tutorial/body.md
@@ -8,20 +8,21 @@ Sua API quase sempre irá enviar um corpo na **resposta**. Mas os clientes não
Para declarar um corpo da **requisição**, você utiliza os modelos do Pydantic com todos os seus poderes e benefícios.
-!!! info "Informação"
- Para enviar dados, você deve usar utilizar um dos métodos: `POST` (Mais comum), `PUT`, `DELETE` ou `PATCH`.
+/// info | Informação
- Enviar um corpo em uma requisição `GET` não tem um comportamento definido nas especificações, porém é suportado pelo FastAPI, apenas para casos de uso bem complexos/extremos.
+Para enviar dados, você deve usar utilizar um dos métodos: `POST` (Mais comum), `PUT`, `DELETE` ou `PATCH`.
- Como é desencorajado, a documentação interativa com Swagger UI não irá mostrar a documentação para o corpo da requisição para um `GET`, e proxies que intermediarem podem não suportar o corpo da requisição.
+Enviar um corpo em uma requisição `GET` não tem um comportamento definido nas especificações, porém é suportado pelo FastAPI, apenas para casos de uso bem complexos/extremos.
+
+Como é desencorajado, a documentação interativa com Swagger UI não irá mostrar a documentação para o corpo da requisição para um `GET`, e proxies que intermediarem podem não suportar o corpo da requisição.
+
+///
## Importe o `BaseModel` do Pydantic
Primeiro, você precisa importar `BaseModel` do `pydantic`:
-```Python hl_lines="4"
-{!../../../docs_src/body/tutorial001.py!}
-```
+{* ../../docs_src/body/tutorial001.py hl[4] *}
## Crie seu modelo de dados
@@ -29,9 +30,7 @@ Então você declara seu modelo de dados como uma classe que herda `BaseModel`.
Utilize os tipos Python padrão para todos os atributos:
-```Python hl_lines="7-11"
-{!../../../docs_src/body/tutorial001.py!}
-```
+{* ../../docs_src/body/tutorial001.py hl[7:11] *}
Assim como quando declaramos parâmetros de consulta, quando um atributo do modelo possui um valor padrão, ele se torna opcional. Caso contrário, se torna obrigatório. Use `None` para torná-lo opcional.
@@ -59,9 +58,7 @@ Por exemplo, o modelo acima declara um JSON "`object`" (ou `dict` no Python) com
Para adicionar o corpo na *função de operação de rota*, declare-o da mesma maneira que você declarou parâmetros de rota e consulta:
-```Python hl_lines="18"
-{!../../../docs_src/body/tutorial001.py!}
-```
+{* ../../docs_src/body/tutorial001.py hl[18] *}
...E declare o tipo como o modelo que você criou, `Item`.
@@ -110,24 +107,25 @@ Mas você terá o mesmo suporte do editor no
-!!! tip "Dica"
- Se você utiliza o PyCharm como editor, você pode utilizar o Plugin do Pydantic para o PyCharm .
+/// tip | Dica
- Melhora o suporte do editor para seus modelos Pydantic com::
+Se você utiliza o PyCharm como editor, você pode utilizar o Plugin do Pydantic para o PyCharm .
- * completação automática
- * verificação de tipos
- * refatoração
- * buscas
- * inspeções
+Melhora o suporte do editor para seus modelos Pydantic com::
+
+* completação automática
+* verificação de tipos
+* refatoração
+* buscas
+* inspeções
+
+///
## Use o modelo
Dentro da função, você pode acessar todos os atributos do objeto do modelo diretamente:
-```Python hl_lines="21"
-{!../../../docs_src/body/tutorial002.py!}
-```
+{* ../../docs_src/body/tutorial002.py hl[21] *}
## Corpo da requisição + parâmetros de rota
@@ -135,9 +133,7 @@ Você pode declarar parâmetros de rota e corpo da requisição ao mesmo tempo.
O **FastAPI** irá reconhecer que os parâmetros da função que combinam com parâmetros de rota devem ser **retirados da rota**, e parâmetros da função que são declarados como modelos Pydantic sejam **retirados do corpo da requisição**.
-```Python hl_lines="17-18"
-{!../../../docs_src/body/tutorial003.py!}
-```
+{* ../../docs_src/body/tutorial003.py hl[17:18] *}
## Corpo da requisição + parâmetros de rota + parâmetros de consulta
@@ -145,9 +141,7 @@ Você também pode declarar parâmetros de **corpo**, **rota** e **consulta**, a
O **FastAPI** irá reconhecer cada um deles e retirar a informação do local correto.
-```Python hl_lines="18"
-{!../../../docs_src/body/tutorial004.py!}
-```
+{* ../../docs_src/body/tutorial004.py hl[18] *}
Os parâmetros da função serão reconhecidos conforme abaixo:
@@ -155,10 +149,13 @@ Os parâmetros da função serão reconhecidos conforme abaixo:
* Se o parâmetro é de um **tipo único** (como `int`, `float`, `str`, `bool`, etc) será interpretado como um parâmetro de **consulta**.
* Se o parâmetro é declarado como um **modelo Pydantic**, será interpretado como o **corpo** da requisição.
-!!! note "Observação"
- O FastAPI saberá que o valor de `q` não é obrigatório por causa do valor padrão `= None`.
+/// note | Observação
- O `Union` em `Union[str, None]` não é utilizado pelo FastAPI, mas permite ao seu editor de texto lhe dar um suporte melhor e detectar erros.
+O FastAPI saberá que o valor de `q` não é obrigatório por causa do valor padrão `= None`.
+
+O `Union` em `Union[str, None]` não é utilizado pelo FastAPI, mas permite ao seu editor de texto lhe dar um suporte melhor e detectar erros.
+
+///
## Sem o Pydantic
diff --git a/docs/pt/docs/tutorial/cookie-param-models.md b/docs/pt/docs/tutorial/cookie-param-models.md
new file mode 100644
index 000000000..3d46ba44c
--- /dev/null
+++ b/docs/pt/docs/tutorial/cookie-param-models.md
@@ -0,0 +1,78 @@
+# Modelos de Parâmetros de Cookie
+
+Se você possui um grupo de **cookies** que estão relacionados, você pode criar um **modelo Pydantic** para declará-los. 🍪
+
+Isso lhe permitiria **reutilizar o modelo** em **diversos lugares** e também declarar validações e metadata para todos os parâmetros de uma vez. 😎
+
+/// note | Nota
+
+Isso é suportado desde a versão `0.115.0` do FastAPI. 🤓
+
+///
+
+/// tip | Dica
+
+Essa mesma técnica se aplica para `Query`, `Cookie`, e `Header`. 😎
+
+///
+
+## Cookies com Modelos Pydantic
+
+Declare o parâmetro de **cookie** que você precisa em um **modelo Pydantic**, e depois declare o parâmetro como um `Cookie`:
+
+{* ../../docs_src/cookie_param_models/tutorial001_an_py310.py hl[9:12,16] *}
+
+O **FastAPI** irá **extrair** os dados para **cada campo** dos **cookies** recebidos na requisição e lhe fornecer o modelo Pydantic que você definiu.
+
+## Verifique os Documentos
+
+Você pode ver os cookies definidos na IU dos documentos em `/docs`:
+
+
+
+
+---
+
+Se você usar o Pycharm, você pode:
+
+* Abrir o menu "Executar".
+* Selecionar a opção "Depurar...".
+* Então um menu de contexto aparece.
+* Selecionar o arquivo para depurar (neste caso, `main.py`).
+
+Em seguida, ele iniciará o servidor com seu código **FastAPI**, parará em seus pontos de interrupção, etc.
+
+Veja como pode parecer:
+
+
diff --git a/docs/pt/docs/tutorial/dependencies/classes-as-dependencies.md b/docs/pt/docs/tutorial/dependencies/classes-as-dependencies.md
index 028bf3d20..ef67aa979 100644
--- a/docs/pt/docs/tutorial/dependencies/classes-as-dependencies.md
+++ b/docs/pt/docs/tutorial/dependencies/classes-as-dependencies.md
@@ -6,41 +6,7 @@ Antes de nos aprofundarmos no sistema de **Injeção de Dependência**, vamos me
No exemplo anterior, nós retornávamos um `dict` da nossa dependência ("injetável"):
-=== "Python 3.10+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/dependencies/tutorial001_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/dependencies/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/dependencies/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível.
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/dependencies/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível.
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/dependencies/tutorial001.py!}
- ```
+{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[9] *}
Mas assim obtemos um `dict` como valor do parâmetro `commons` na *função de operação de rota*.
@@ -103,123 +69,15 @@ Isso também se aplica a objetos chamáveis que não recebem nenhum parâmetro.
Então, podemos mudar o "injetável" na dependência `common_parameters` acima para a classe `CommonQueryParams`:
-=== "Python 3.10+"
-
- ```Python hl_lines="11-15"
- {!> ../../../docs_src/dependencies/tutorial002_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="11-15"
- {!> ../../../docs_src/dependencies/tutorial002_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="12-16"
- {!> ../../../docs_src/dependencies/tutorial002_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível.
-
-
- ```Python hl_lines="9-13"
- {!> ../../../docs_src/dependencies/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível.
-
-
- ```Python hl_lines="11-15"
- {!> ../../../docs_src/dependencies/tutorial002.py!}
- ```
+{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[11:15] *}
Observe o método `__init__` usado para criar uma instância da classe:
-=== "Python 3.10+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/dependencies/tutorial002_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/dependencies/tutorial002_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="13"
- {!> ../../../docs_src/dependencies/tutorial002_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível.
-
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/dependencies/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível.
-
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/dependencies/tutorial002.py!}
- ```
+{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[12] *}
...ele possui os mesmos parâmetros que nosso `common_parameters` anterior:
-=== "Python 3.10+"
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/dependencies/tutorial001_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/dependencies/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/dependencies/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível.
-
-
- ```Python hl_lines="6"
- {!> ../../../docs_src/dependencies/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível.
-
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/dependencies/tutorial001.py!}
- ```
+{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[8] *}
Esses parâmetros são utilizados pelo **FastAPI** para "definir" a dependência.
@@ -235,43 +93,7 @@ Os dados serão convertidos, validados, documentados no esquema da OpenAPI e etc
Agora você pode declarar sua dependência utilizando essa classe.
-=== "Python 3.10+"
-
- ```Python hl_lines="19"
- {!> ../../../docs_src/dependencies/tutorial002_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="19"
- {!> ../../../docs_src/dependencies/tutorial002_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/dependencies/tutorial002_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível.
-
-
- ```Python hl_lines="17"
- {!> ../../../docs_src/dependencies/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível.
-
-
- ```Python hl_lines="19"
- {!> ../../../docs_src/dependencies/tutorial002.py!}
- ```
+{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[19] *}
O **FastAPI** chama a classe `CommonQueryParams`. Isso cria uma "instância" dessa classe e é a instância que será passada para o parâmetro `commons` na sua função.
@@ -279,21 +101,27 @@ O **FastAPI** chama a classe `CommonQueryParams`. Isso cria uma "instância" des
Perceba como escrevemos `CommonQueryParams` duas vezes no código abaixo:
-=== "Python 3.8+"
+//// tab | Python 3.8+
- ```Python
- commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
- ```
+```Python
+commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
+```
-=== "Python 3.8+ non-Annotated"
+////
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível.
+//// tab | Python 3.8+ non-Annotated
+/// tip | Dica
- ```Python
- commons: CommonQueryParams = Depends(CommonQueryParams)
- ```
+Utilize a versão com `Annotated` se possível.
+
+///
+
+```Python
+commons: CommonQueryParams = Depends(CommonQueryParams)
+```
+
+////
O último `CommonQueryParams`, em:
@@ -309,81 +137,57 @@ O último `CommonQueryParams`, em:
Nesse caso, o primeiro `CommonQueryParams`, em:
-=== "Python 3.8+"
+//// tab | Python 3.8+
- ```Python
- commons: Annotated[CommonQueryParams, ...
- ```
+```Python
+commons: Annotated[CommonQueryParams, ...
+```
-=== "Python 3.8+ non-Annotated"
+////
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível.
+//// tab | Python 3.8+ non-Annotated
+/// tip | Dica
- ```Python
- commons: CommonQueryParams ...
- ```
+Utilize a versão com `Annotated` se possível.
+
+///
+
+```Python
+commons: CommonQueryParams ...
+```
+
+////
...não tem nenhum signficado especial para o **FastAPI**. O FastAPI não irá utilizá-lo para conversão dos dados, validação, etc (já que ele utiliza `Depends(CommonQueryParams)` para isso).
Na verdade você poderia escrever apenas:
-=== "Python 3.8+"
+//// tab | Python 3.8+
- ```Python
- commons: Annotated[Any, Depends(CommonQueryParams)]
- ```
+```Python
+commons: Annotated[Any, Depends(CommonQueryParams)]
+```
-=== "Python 3.8+ non-Annotated"
+////
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível.
+//// tab | Python 3.8+ non-Annotated
+/// tip | Dica
- ```Python
- commons = Depends(CommonQueryParams)
- ```
+Utilize a versão com `Annotated` se possível.
+
+///
+
+```Python
+commons = Depends(CommonQueryParams)
+```
+
+////
...como em:
-=== "Python 3.10+"
-
- ```Python hl_lines="19"
- {!> ../../../docs_src/dependencies/tutorial003_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="19"
- {!> ../../../docs_src/dependencies/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/dependencies/tutorial003_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível.
-
-
- ```Python hl_lines="17"
- {!> ../../../docs_src/dependencies/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível.
-
-
- ```Python hl_lines="19"
- {!> ../../../docs_src/dependencies/tutorial003.py!}
- ```
+{* ../../docs_src/dependencies/tutorial003_an_py310.py hl[19] *}
Mas declarar o tipo é encorajado por que é a forma que o seu editor de texto sabe o que será passado como valor do parâmetro `commons`.
@@ -393,20 +197,27 @@ Mas declarar o tipo é encorajado por que é a forma que o seu editor de texto s
Mas você pode ver que temos uma repetição do código neste exemplo, escrevendo `CommonQueryParams` duas vezes:
-=== "Python 3.8+"
+//// tab | Python 3.8+
- ```Python
- commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
- ```
+```Python
+commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
+```
-=== "Python 3.8+ non-Annotated"
+////
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível.
+//// tab | Python 3.8+ non-Annotated
- ```Python
- commons: CommonQueryParams = Depends(CommonQueryParams)
- ```
+/// tip | Dica
+
+Utilize a versão com `Annotated` se possível.
+
+///
+
+```Python
+commons: CommonQueryParams = Depends(CommonQueryParams)
+```
+
+////
O **FastAPI** nos fornece um atalho para esses casos, onde a dependência é *especificamente* uma classe que o **FastAPI** irá "chamar" para criar uma instância da própria classe.
@@ -414,84 +225,64 @@ Para esses casos específicos, você pode fazer o seguinte:
Em vez de escrever:
-=== "Python 3.8+"
+//// tab | Python 3.8+
- ```Python
- commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
- ```
+```Python
+commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
+```
-=== "Python 3.8+ non-Annotated"
+////
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível.
+//// tab | Python 3.8+ non-Annotated
- ```Python
- commons: CommonQueryParams = Depends(CommonQueryParams)
- ```
+/// tip | Dica
+
+Utilize a versão com `Annotated` se possível.
+
+///
+
+```Python
+commons: CommonQueryParams = Depends(CommonQueryParams)
+```
+
+////
...escreva:
-=== "Python 3.8+"
+//// tab | Python 3.8+
- ```Python
- commons: Annotated[CommonQueryParams, Depends()]
- ```
+```Python
+commons: Annotated[CommonQueryParams, Depends()]
+```
-=== "Python 3.8 non-Annotated"
+////
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível.
+//// tab | Python 3.8 non-Annotated
+/// tip | Dica
- ```Python
- commons: CommonQueryParams = Depends()
- ```
+Utilize a versão com `Annotated` se possível.
+
+///
+
+```Python
+commons: CommonQueryParams = Depends()
+```
+
+////
Você declara a dependência como o tipo do parâmetro, e utiliza `Depends()` sem nenhum parâmetro, em vez de ter que escrever a classe *novamente* dentro de `Depends(CommonQueryParams)`.
O mesmo exemplo ficaria então dessa forma:
-=== "Python 3.10+"
-
- ```Python hl_lines="19"
- {!> ../../../docs_src/dependencies/tutorial004_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="19"
- {!> ../../../docs_src/dependencies/tutorial004_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/dependencies/tutorial004_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível.
-
-
- ```Python hl_lines="17"
- {!> ../../../docs_src/dependencies/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível.
-
-
- ```Python hl_lines="19"
- {!> ../../../docs_src/dependencies/tutorial004.py!}
- ```
+{* ../../docs_src/dependencies/tutorial004_an_py310.py hl[19] *}
...e o **FastAPI** saberá o que fazer.
-!!! tip "Dica"
- Se isso parece mais confuso do que útil, não utilize, você não *precisa* disso.
+/// tip | Dica
- É apenas um atalho. Por que o **FastAPI** se preocupa em ajudar a minimizar a repetição de código.
+Se isso parece mais confuso do que útil, não utilize, você não *precisa* disso.
+
+É apenas um atalho. Por que o **FastAPI** se preocupa em ajudar a minimizar a repetição de código.
+
+///
diff --git a/docs/pt/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md b/docs/pt/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
index 4a297268c..d7d31bb45 100644
--- a/docs/pt/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
+++ b/docs/pt/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
@@ -14,39 +14,27 @@ O *decorador da operação de rota* recebe um argumento opcional `dependencies`.
Ele deve ser uma lista de `Depends()`:
-=== "Python 3.9+"
+{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[19] *}
- ```Python hl_lines="19"
- {!> ../../../docs_src/dependencies/tutorial006_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/dependencies/tutorial006_an.py!}
- ```
-
-=== "Python 3.8 non-Annotated"
-
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível
-
- ```Python hl_lines="17"
- {!> ../../../docs_src/dependencies/tutorial006.py!}
- ```
Essas dependências serão executadas/resolvidas da mesma forma que dependências comuns. Mas o valor delas (se existir algum) não será passado para a sua *função de operação de rota*.
-!!! tip "Dica"
- Alguns editores de texto checam parâmetros de funções não utilizados, e os mostram como erros.
+/// tip | Dica
- Utilizando `dependencies` no *decorador da operação de rota* você pode garantir que elas serão executadas enquanto evita errors de editores/ferramentas.
+Alguns editores de texto checam parâmetros de funções não utilizados, e os mostram como erros.
- Isso também pode ser útil para evitar confundir novos desenvolvedores que ao ver um parâmetro não usado no seu código podem pensar que ele é desnecessário.
+Utilizando `dependencies` no *decorador da operação de rota* você pode garantir que elas serão executadas enquanto evita errors de editores/ferramentas.
-!!! info "Informação"
- Neste exemplo utilizamos cabeçalhos personalizados inventados `X-Keys` e `X-Token`.
+Isso também pode ser útil para evitar confundir novos desenvolvedores que ao ver um parâmetro não usado no seu código podem pensar que ele é desnecessário.
- Mas em situações reais, como implementações de segurança, você pode obter mais vantagens em usar as [Ferramentas de segurança integradas (o próximo capítulo)](../security/index.md){.internal-link target=_blank}.
+///
+
+/// info | Informação
+
+Neste exemplo utilizamos cabeçalhos personalizados inventados `X-Keys` e `X-Token`.
+
+Mas em situações reais, como implementações de segurança, você pode obter mais vantagens em usar as [Ferramentas de segurança integradas (o próximo capítulo)](../security/index.md){.internal-link target=_blank}.
+
+///
## Erros das dependências e valores de retorno
@@ -56,51 +44,13 @@ Você pode utilizar as mesmas *funções* de dependências que você usaria norm
Dependências podem declarar requisitos de requisições (como cabeçalhos) ou outras subdependências:
-=== "Python 3.9+"
-
- ```Python hl_lines="8 13"
- {!> ../../../docs_src/dependencies/tutorial006_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="7 12"
- {!> ../../../docs_src/dependencies/tutorial006_an.py!}
- ```
-
-=== "Python 3.8 non-Annotated"
-
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível
-
- ```Python hl_lines="6 11"
- {!> ../../../docs_src/dependencies/tutorial006.py!}
- ```
+{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[8,13] *}
### Levantando exceções
Essas dependências podem levantar exceções, da mesma forma que dependências comuns:
-=== "Python 3.9+"
-
- ```Python hl_lines="10 15"
- {!> ../../../docs_src/dependencies/tutorial006_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9 14"
- {!> ../../../docs_src/dependencies/tutorial006_an.py!}
- ```
-
-=== "Python 3.8 non-Annotated"
-
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível
-
- ```Python hl_lines="8 13"
- {!> ../../../docs_src/dependencies/tutorial006.py!}
- ```
+{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[10,15] *}
### Valores de retorno
@@ -108,26 +58,7 @@ E elas também podem ou não retornar valores, eles não serão utilizados.
Então, você pode reutilizar uma dependência comum (que retorna um valor) que já seja utilizada em outro lugar, e mesmo que o valor não seja utilizado, a dependência será executada:
-=== "Python 3.9+"
-
- ```Python hl_lines="11 16"
- {!> ../../../docs_src/dependencies/tutorial006_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="10 15"
- {!> ../../../docs_src/dependencies/tutorial006_an.py!}
- ```
-
-=== "Python 3.8 non-Annotated"
-
- !!! tip "Dica"
- Utilize a versão com `Annotated` se possível
-
- ```Python hl_lines="9 14"
- {!> ../../../docs_src/dependencies/tutorial006.py!}
- ```
+{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[11,16] *}
## Dependências para um grupo de *operações de rota*
diff --git a/docs/pt/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/pt/docs/tutorial/dependencies/dependencies-with-yield.md
index 8b4175fc5..eaf711197 100644
--- a/docs/pt/docs/tutorial/dependencies/dependencies-with-yield.md
+++ b/docs/pt/docs/tutorial/dependencies/dependencies-with-yield.md
@@ -4,18 +4,24 @@ O FastAPI possui suporte para dependências que realizam .
+
+Mas se você tiver cabeçalhos personalizados desejando que um cliente em um navegador esteja apto a ver, você precisa adicioná-los às suas configurações CORS ([CORS (Cross-Origin Resource Sharing)](cors.md){.internal-link target=_blank}) usando o parâmetro `expose_headers` documentado em Documentos CORS da Starlette.
+
+///
+
+/// note | Detalhes técnicos
+
+Você também pode usar `from starlette.requests import Request`.
+
+**FastAPI** fornece isso como uma conveniência para você, o desenvolvedor. Mas vem diretamente da Starlette.
+
+///
+
+### Antes e depois da `response`
+
+Você pode adicionar código para ser executado com a `request`, antes que qualquer *operação de rota* o receba.
+
+E também depois que a `response` é gerada, antes de retorná-la.
+
+Por exemplo, você pode adicionar um cabeçalho personalizado `X-Process-Time` contendo o tempo em segundos que levou para processar a solicitação e gerar uma resposta:
+
+{* ../../docs_src/middleware/tutorial001.py hl[10,12:13] *}
+
+## Outros middlewares
+
+Mais tarde, você pode ler mais sobre outros middlewares no [Guia do usuário avançado: Middleware avançado](../advanced/middleware.md){.internal-link target=_blank}.
+
+Você lerá sobre como manipular CORS com um middleware na próxima seção.
diff --git a/docs/pt/docs/tutorial/path-operation-configuration.md b/docs/pt/docs/tutorial/path-operation-configuration.md
index 13a87240f..f183c9d23 100644
--- a/docs/pt/docs/tutorial/path-operation-configuration.md
+++ b/docs/pt/docs/tutorial/path-operation-configuration.md
@@ -2,8 +2,11 @@
Existem vários parâmetros que você pode passar para o seu *decorador de operação de rota* para configurá-lo.
-!!! warning "Aviso"
- Observe que esses parâmetros são passados diretamente para o *decorador de operação de rota*, não para a sua *função de operação de rota*.
+/// warning | Aviso
+
+Observe que esses parâmetros são passados diretamente para o *decorador de operação de rota*, não para a sua *função de operação de rota*.
+
+///
## Código de Status da Resposta
@@ -13,52 +16,23 @@ 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.8 and above"
-
- ```Python hl_lines="3 17"
- {!> ../../../docs_src/path_operation_configuration/tutorial001.py!}
- ```
-
-=== "Python 3.9 and above"
-
- ```Python hl_lines="3 17"
- {!> ../../../docs_src/path_operation_configuration/tutorial001_py39.py!}
- ```
-
-=== "Python 3.10 and above"
-
- ```Python hl_lines="1 15"
- {!> ../../../docs_src/path_operation_configuration/tutorial001_py310.py!}
- ```
+{* ../../docs_src/path_operation_configuration/tutorial001.py hl[3,17] *}
Esse código de status será usado na resposta e será adicionado ao esquema OpenAPI.
-!!! note "Detalhes Técnicos"
- Você também poderia usar `from starlette import status`.
+/// note | Detalhes Técnicos
- **FastAPI** fornece o mesmo `starlette.status` como `fastapi.status` apenas como uma conveniência para você, o desenvolvedor. Mas vem diretamente do Starlette.
+Você também poderia usar `from starlette import status`.
+
+**FastAPI** fornece o mesmo `starlette.status` como `fastapi.status` apenas como uma conveniência para você, o desenvolvedor. Mas vem diretamente do Starlette.
+
+///
## Tags
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.8 and above"
-
- ```Python hl_lines="17 22 27"
- {!> ../../../docs_src/path_operation_configuration/tutorial002.py!}
- ```
-
-=== "Python 3.9 and above"
-
- ```Python hl_lines="17 22 27"
- {!> ../../../docs_src/path_operation_configuration/tutorial002_py39.py!}
- ```
-
-=== "Python 3.10 and above"
-
- ```Python hl_lines="15 20 25"
- {!> ../../../docs_src/path_operation_configuration/tutorial002_py310.py!}
- ```
+{* ../../docs_src/path_operation_configuration/tutorial002.py hl[17,22,27] *}
Eles serão adicionados ao esquema OpenAPI e usados pelas interfaces de documentação automática:
@@ -72,31 +46,13 @@ Nestes casos, pode fazer sentido armazenar as tags em um `Enum`.
**FastAPI** suporta isso da mesma maneira que com strings simples:
-```Python hl_lines="1 8-10 13 18"
-{!../../../docs_src/path_operation_configuration/tutorial002b.py!}
-```
+{* ../../docs_src/path_operation_configuration/tutorial002b.py hl[1,8:10,13,18] *}
## Resumo e descrição
Você pode adicionar um `summary` e uma `description`:
-=== "Python 3.8 and above"
-
- ```Python hl_lines="20-21"
- {!> ../../../docs_src/path_operation_configuration/tutorial003.py!}
- ```
-
-=== "Python 3.9 and above"
-
- ```Python hl_lines="20-21"
- {!> ../../../docs_src/path_operation_configuration/tutorial003_py39.py!}
- ```
-
-=== "Python 3.10 and above"
-
- ```Python hl_lines="18-19"
- {!> ../../../docs_src/path_operation_configuration/tutorial003_py310.py!}
- ```
+{* ../../docs_src/path_operation_configuration/tutorial003.py hl[20:21] *}
## Descrição do docstring
@@ -104,23 +60,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.8 and above"
-
- ```Python hl_lines="19-27"
- {!> ../../../docs_src/path_operation_configuration/tutorial004.py!}
- ```
-
-=== "Python 3.9 and above"
-
- ```Python hl_lines="19-27"
- {!> ../../../docs_src/path_operation_configuration/tutorial004_py39.py!}
- ```
-
-=== "Python 3.10 and above"
-
- ```Python hl_lines="17-25"
- {!> ../../../docs_src/path_operation_configuration/tutorial004_py310.py!}
- ```
+{* ../../docs_src/path_operation_configuration/tutorial004.py hl[19:27] *}
Ela será usada nas documentações interativas:
@@ -131,31 +71,21 @@ Ela será usada nas documentações interativas:
Você pode especificar a descrição da resposta com o parâmetro `response_description`:
-=== "Python 3.8 and above"
+{* ../../docs_src/path_operation_configuration/tutorial005.py hl[21] *}
- ```Python hl_lines="21"
- {!> ../../../docs_src/path_operation_configuration/tutorial005.py!}
- ```
+/// info | Informação
-=== "Python 3.9 and above"
+Note que `response_description` se refere especificamente à resposta, a `description` se refere à *operação de rota* em geral.
- ```Python hl_lines="21"
- {!> ../../../docs_src/path_operation_configuration/tutorial005_py39.py!}
- ```
+///
-=== "Python 3.10 and above"
+/// check
- ```Python hl_lines="19"
- {!> ../../../docs_src/path_operation_configuration/tutorial005_py310.py!}
- ```
+OpenAPI especifica que cada *operação de rota* requer uma descrição de resposta.
-!!! info "Informação"
- Note que `response_description` se refere especificamente à resposta, a `description` se refere à *operação de rota* em geral.
+Então, se você não fornecer uma, o **FastAPI** irá gerar automaticamente uma de "Resposta bem-sucedida".
-!!! check
- OpenAPI especifica que cada *operação de rota* requer uma descrição de resposta.
-
- Então, se você não fornecer uma, o **FastAPI** irá gerar automaticamente uma de "Resposta bem-sucedida".
+///
@@ -163,9 +93,7 @@ Você pode especificar a descrição da resposta com o parâmetro `response_desc
Se você precisar marcar uma *operação de rota* como descontinuada, mas sem removê-la, passe o parâmetro `deprecated`:
-```Python hl_lines="16"
-{!../../../docs_src/path_operation_configuration/tutorial006.py!}
-```
+{* ../../docs_src/path_operation_configuration/tutorial006.py hl[16] *}
Ela será claramente marcada como descontinuada nas documentações interativas:
diff --git a/docs/pt/docs/tutorial/path-params-numeric-validations.md b/docs/pt/docs/tutorial/path-params-numeric-validations.md
index eb0d31dc3..3aea1188d 100644
--- a/docs/pt/docs/tutorial/path-params-numeric-validations.md
+++ b/docs/pt/docs/tutorial/path-params-numeric-validations.md
@@ -6,17 +6,7 @@ Do mesmo modo que você pode declarar mais validações e metadados para parâme
Primeiro, importe `Path` de `fastapi`:
-=== "Python 3.10+"
-
- ```Python hl_lines="1"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="3"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001.py!}
- ```
+{* ../../docs_src/path_params_numeric_validations/tutorial001_py310.py hl[1] *}
## Declare metadados
@@ -24,24 +14,17 @@ Você pode declarar todos os parâmetros da mesma maneira que na `Query`.
Por exemplo para declarar um valor de metadado `title` para o parâmetro de rota `item_id` você pode digitar:
-=== "Python 3.10+"
+{* ../../docs_src/path_params_numeric_validations/tutorial001_py310.py hl[8] *}
- ```Python hl_lines="8"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_py310.py!}
- ```
+/// note | Nota
-=== "Python 3.8+"
+Um parâmetro de rota é sempre obrigatório, como se fizesse parte da rota.
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001.py!}
- ```
+Então, você deve declará-lo com `...` para marcá-lo como obrigatório.
-!!! note "Nota"
- Um parâmetro de rota é sempre obrigatório, como se fizesse parte da rota.
+Mesmo que você declare-o como `None` ou defina um valor padrão, isso não teria efeito algum, o parâmetro ainda seria obrigatório.
- Então, você deve declará-lo com `...` para marcá-lo como obrigatório.
-
- Mesmo que você declare-o como `None` ou defina um valor padrão, isso não teria efeito algum, o parâmetro ainda seria obrigatório.
+///
## Ordene os parâmetros de acordo com sua necessidade
@@ -59,9 +42,7 @@ Isso não faz diferença para o **FastAPI**. Ele vai detectar os parâmetros pel
Então, você pode declarar sua função assim:
-```Python hl_lines="7"
-{!../../../docs_src/path_params_numeric_validations/tutorial002.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial002.py hl[7] *}
## Ordene os parâmetros de a acordo com sua necessidade, truques
@@ -71,9 +52,7 @@ Passe `*`, como o primeiro parâmetro da função.
O Python não vai fazer nada com esse `*`, mas ele vai saber que a partir dali os parâmetros seguintes deverão ser chamados argumentos nomeados (pares chave-valor), também conhecidos como kwargs. Mesmo que eles não possuam um valor padrão.
-```Python hl_lines="7"
-{!../../../docs_src/path_params_numeric_validations/tutorial003.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *}
## Validações numéricas: maior que ou igual
@@ -81,9 +60,7 @@ Com `Query` e `Path` (e outras que você verá mais tarde) você pode declarar r
Aqui, com `ge=1`, `item_id` precisará ser um número inteiro maior que ("`g`reater than") ou igual ("`e`qual") a 1.
-```Python hl_lines="8"
-{!../../../docs_src/path_params_numeric_validations/tutorial004.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial004.py hl[8] *}
## Validações numéricas: maior que e menor que ou igual
@@ -92,9 +69,7 @@ O mesmo se aplica para:
* `gt`: maior que (`g`reater `t`han)
* `le`: menor que ou igual (`l`ess than or `e`qual)
-```Python hl_lines="9"
-{!../../../docs_src/path_params_numeric_validations/tutorial005.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial005.py hl[9] *}
## Validações numéricas: valores do tipo float, maior que e menor que
@@ -106,9 +81,7 @@ Assim, `0.5` seria um valor válido. Mas `0.0` ou `0` não seria.
E o mesmo para lt.
-```Python hl_lines="11"
-{!../../../docs_src/path_params_numeric_validations/tutorial006.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial006.py hl[11] *}
## Recapitulando
@@ -121,18 +94,24 @@ E você também pode declarar validações numéricas:
* `lt`: menor que (`l`ess `t`han)
* `le`: menor que ou igual (`l`ess than or `e`qual)
-!!! info "Informação"
- `Query`, `Path` e outras classes que você verá a frente são subclasses de uma classe comum `Param`.
+/// info | Informação
- Todas elas compartilham os mesmos parâmetros para validação adicional e metadados que você viu.
+`Query`, `Path` e outras classes que você verá a frente são subclasses de uma classe comum `Param`.
-!!! note "Detalhes Técnicos"
- Quando você importa `Query`, `Path` e outras de `fastapi`, elas são na verdade funções.
+Todas elas compartilham os mesmos parâmetros para validação adicional e metadados que você viu.
- Que quando chamadas, retornam instâncias de classes de mesmo nome.
+///
- Então, você importa `Query`, que é uma função. E quando você a chama, ela retorna uma instância de uma classe também chamada `Query`.
+/// note | Detalhes Técnicos
- Estas funções são assim (ao invés de apenas usar as classes diretamente) para que seu editor não acuse erros sobre seus tipos.
+Quando você importa `Query`, `Path` e outras de `fastapi`, elas são na verdade funções.
- Dessa maneira você pode user seu editor e ferramentas de desenvolvimento sem precisar adicionar configurações customizadas para ignorar estes erros.
+Que quando chamadas, retornam instâncias de classes de mesmo nome.
+
+Então, você importa `Query`, que é uma função. E quando você a chama, ela retorna uma instância de uma classe também chamada `Query`.
+
+Estas funções são assim (ao invés de apenas usar as classes diretamente) para que seu editor não acuse erros sobre seus tipos.
+
+Dessa maneira você pode user seu editor e ferramentas de desenvolvimento sem precisar adicionar configurações customizadas para ignorar estes erros.
+
+///
diff --git a/docs/pt/docs/tutorial/path-params.md b/docs/pt/docs/tutorial/path-params.md
index 27aa9dfcf..ecf77d676 100644
--- a/docs/pt/docs/tutorial/path-params.md
+++ b/docs/pt/docs/tutorial/path-params.md
@@ -2,9 +2,7 @@
Você pode declarar os "parâmetros" ou "variáveis" com a mesma sintaxe utilizada pelo formato de strings do Python:
-```Python hl_lines="6-7"
-{!../../../docs_src/path_params/tutorial001.py!}
-```
+{* ../../docs_src/path_params/tutorial001.py hl[6:7] *}
O valor do parâmetro que foi passado à `item_id` será passado para a sua função como o argumento `item_id`.
@@ -18,13 +16,16 @@ Então, se você rodar este exemplo e for até dados
@@ -35,7 +36,12 @@ Se você rodar esse exemplo e abrir o seu navegador em "parsing" automático no request .
@@ -63,7 +69,12 @@ devido ao parâmetro da rota `item_id` ter um valor `"foo"`, que não é um `int
O mesmo erro apareceria se você tivesse fornecido um `float` ao invés de um `int`, como em: http://127.0.0.1:8000/items/4.2
-!!! check "Verifique"
+/// check | Verifique
+
+
+
+///
+
Então, com a mesma declaração de tipo do Python, o **FastAPI** dá pra você validação de dados.
Observe que o erro também mostra claramente o ponto exato onde a validação não passou.
@@ -76,7 +87,12 @@ Quando você abrir o seu navegador em
-!!! check "Verifique"
+/// check | Verifique
+
+
+
+///
+
Novamente, apenas com a mesma declaração de tipo do Python, o **FastAPI** te dá de forma automática e interativa a documentação (integrada com o Swagger UI).
Veja que o parâmetro de rota está declarado como sendo um inteiro (int).
@@ -109,9 +125,7 @@ E então você pode ter também uma rota `/users/{user_id}` para pegar dados sob
Porque as operações de rota são avaliadas em ordem, você precisa ter certeza que a rota para `/users/me` está sendo declarado antes da rota `/users/{user_id}`:
-```Python hl_lines="6 11"
-{!../../../docs_src/path_params/tutorial003.py!}
-```
+{* ../../docs_src/path_params/tutorial003.py hl[6,11] *}
Caso contrário, a rota para `/users/{user_id}` coincidiria também para `/users/me`, "pensando" que estaria recebendo o parâmetro `user_id` com o valor de `"me"`.
@@ -127,23 +141,27 @@ Por herdar de `str` a documentação da API vai ser capaz de saber que os valore
Assim, crie atributos de classe com valores fixos, que serão os valores válidos disponíveis.
-```Python hl_lines="1 6-9"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[1,6:9] *}
-!!! info "informação"
- Enumerations (ou enums) estão disponíveis no Python desde a versão 3.4.
+/// info | informação
+
+Enumerations (ou enums) estão disponíveis no Python desde a versão 3.4.
+
+///
+
+/// tip | Dica
+
+
+
+///
-!!! tip "Dica"
Se você está se perguntando, "AlexNet", "ResNet", e "LeNet" são apenas nomes de modelos de Machine Learning (aprendizado de máquina).
### Declare um *parâmetro de rota*
Logo, crie um *parâmetro de rota* com anotações de tipo usando a classe enum que você criou (`ModelName`):
-```Python hl_lines="16"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[16] *}
### Revise a documentação
@@ -159,19 +177,20 @@ O valor do *parâmetro da rota* será um *membro de enumeration*.
Você pode comparar eles com o *membro de enumeration* no enum `ModelName` que você criou:
-```Python hl_lines="17"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[17] *}
#### Obtenha o *valor de enumerate*
Você pode ter o valor exato de enumerate (um `str` nesse caso) usando `model_name.value`, ou em geral, `your_enum_member.value`:
-```Python hl_lines="20"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[20] *}
+
+/// tip | Dica
+
+
+
+///
-!!! tip "Dica"
Você também poderia acessar o valor `"lenet"` com `ModelName.lenet.value`
#### Retorne *membros de enumeration*
@@ -180,9 +199,7 @@ Você pode retornar *membros de enum* da sua *rota de operação*, em um corpo J
Eles serão convertidos para o seus valores correspondentes (strings nesse caso) antes de serem retornados ao cliente:
-```Python hl_lines="18 21 23"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[18,21,23] *}
No seu cliente você vai obter uma resposta JSON como:
@@ -221,11 +238,14 @@ Nesse caso, o nome do parâmetro é `file_path`, e a última parte, `:path`, diz
Então, você poderia usar ele com:
-```Python hl_lines="6"
-{!../../../docs_src/path_params/tutorial004.py!}
-```
+{* ../../docs_src/path_params/tutorial004.py hl[6] *}
+
+/// tip | Dica
+
+
+
+///
-!!! tip "Dica"
Você poderia precisar que o parâmetro contivesse `/home/johndoe/myfile.txt`, com uma barra no inicio (`/`).
Neste caso, a URL deveria ser: `/files//home/johndoe/myfile.txt`, com barra dupla (`//`) entre `files` e `home`.
diff --git a/docs/pt/docs/tutorial/query-param-models.md b/docs/pt/docs/tutorial/query-param-models.md
new file mode 100644
index 000000000..01a6e462f
--- /dev/null
+++ b/docs/pt/docs/tutorial/query-param-models.md
@@ -0,0 +1,69 @@
+# Modelos de Parâmetros de Consulta
+
+Se você possui um grupo de **parâmetros de consultas** que são relacionados, você pode criar um **modelo Pydantic** para declará-los.
+
+Isso permitiria que você **reutilizasse o modelo** em **diversos lugares**, e também declarasse validações e metadados de todos os parâmetros de uma única vez. 😎
+
+/// note | Nota
+
+Isso é suportado desde o FastAPI versão `0.115.0`. 🤓
+
+///
+
+## Parâmetros de Consulta com um Modelo Pydantic
+
+Declare os **parâmetros de consulta** que você precisa em um **modelo Pydantic**, e então declare o parâmetro como `Query`:
+
+{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *}
+
+O **FastAPI** **extrairá** os dados para **cada campo** dos **parâmetros de consulta** presentes na requisição, e fornecerá o modelo Pydantic que você definiu.
+
+
+## Verifique os Documentos
+
+Você pode ver os parâmetros de consulta nos documentos de IU em `/docs`:
+
+
+POST.
+
+///
+
+/// warning | Aviso
+
+Você pode declarar múltiplos parâmetros `File` e `Form` em uma *operação de rota*, mas você não pode declarar campos `Body` que você espera receber como JSON, pois a requisição terá o corpo codificado usando `multipart/form-data` ao invés de `application/json`.
+
+Isso não é uma limitação do **FastAPI**, é parte do protocolo HTTP.
+
+///
+
+## Upload de Arquivo Opcional
+
+Você pode tornar um arquivo opcional usando anotações de tipo padrão e definindo um valor padrão de `None`:
+
+{* ../../docs_src/request_files/tutorial001_02_an_py310.py hl[9,17] *}
+
+## `UploadFile` com Metadados Adicionais
+
+Você também pode usar `File()` com `UploadFile`, por exemplo, para definir metadados adicionais:
+
+{* ../../docs_src/request_files/tutorial001_03_an_py39.py hl[9,15] *}
+
+## Uploads de Múltiplos Arquivos
+
+É possível realizar o upload de vários arquivos ao mesmo tempo.
+
+Eles serão associados ao mesmo "campo de formulário" enviado usando "dados de formulário".
+
+Para usar isso, declare uma lista de `bytes` ou `UploadFile`:
+
+{* ../../docs_src/request_files/tutorial002_an_py39.py hl[10,15] *}
+
+Você receberá, tal como declarado, uma `list` de `bytes` ou `UploadFile`.
+
+/// note | Detalhes Técnicos
+
+Você pode também pode usar `from starlette.responses import HTMLResponse`.
+
+**FastAPI** providencia o mesmo `starlette.responses` que `fastapi.responses` apenas como uma conveniência para você, o desenvolvedor. Mas a maioria das respostas disponíveis vem diretamente do Starlette.
+
+///
+
+### Uploads de Múltiplos Arquivos com Metadados Adicionais
+
+Da mesma forma de antes, você pode usar `File()` para definir parâmetros adicionais, mesmo para `UploadFile`:
+
+{* ../../docs_src/request_files/tutorial003_an_py39.py hl[11,18:20] *}
+
+## Recapitulando
+
+Utilize `File`, `bytes` e `UploadFile` para declarar arquivos a serem enviados na requisição, enviados como dados de formulário.
diff --git a/docs/pt/docs/tutorial/request-form-models.md b/docs/pt/docs/tutorial/request-form-models.md
new file mode 100644
index 000000000..ea0e63d38
--- /dev/null
+++ b/docs/pt/docs/tutorial/request-form-models.md
@@ -0,0 +1,78 @@
+# Modelos de Formulários
+
+Você pode utilizar **Modelos Pydantic** para declarar **campos de formulários** no FastAPI.
+
+/// info | Informação
+
+Para utilizar formulários, instale primeiramente o `python-multipart`.
+
+Certifique-se de criar um [ambiente virtual](../virtual-environments.md){.internal-link target=_blank}, ativá-lo, e então instalar. Por exemplo:
+
+```console
+$ pip install python-multipart
+```
+
+///
+
+/// note | Nota
+
+Isto é suportado desde a versão `0.113.0` do FastAPI. 🤓
+
+///
+
+## Modelos Pydantic para Formulários
+
+Você precisa apenas declarar um **modelo Pydantic** com os campos que deseja receber como **campos de formulários**, e então declarar o parâmetro como um `Form`:
+
+{* ../../docs_src/request_form_models/tutorial001_an_py39.py hl[9:11,15] *}
+
+O **FastAPI** irá **extrair** as informações para **cada campo** dos **dados do formulário** na requisição e dar para você o modelo Pydantic que você definiu.
+
+## Confira os Documentos
+
+Você pode verificar na UI de documentação em `/docs`:
+
+
+POST.
+ Mas quando o formulário inclui arquivos, ele é codificado como `multipart/form-data`. Você lerá sobre como lidar com arquivos no próximo capítulo.
-!!! warning "Aviso"
- Você pode declarar vários parâmetros `Form` em uma *operação de caminho*, mas não pode declarar campos `Body` que espera receber como JSON, pois a solicitação terá o corpo codificado usando `application/x-www- form-urlencoded` em vez de `application/json`.
+Se você quiser ler mais sobre essas codificações e campos de formulário, vá para o MDN web docs para POST.
- Esta não é uma limitação do **FastAPI**, é parte do protocolo HTTP.
+///
+
+/// warning | Aviso
+
+Você pode declarar vários parâmetros `Form` em uma *operação de caminho*, mas não pode declarar campos `Body` que espera receber como JSON, pois a solicitação terá o corpo codificado usando `application/x-www- form-urlencoded` em vez de `application/json`.
+
+Esta não é uma limitação do **FastAPI**, é parte do protocolo HTTP.
+
+///
## Recapitulando
diff --git a/docs/pt/docs/tutorial/request_files.md b/docs/pt/docs/tutorial/request_files.md
new file mode 100644
index 000000000..15c1ad825
--- /dev/null
+++ b/docs/pt/docs/tutorial/request_files.md
@@ -0,0 +1,172 @@
+# Arquivos de Requisição
+
+Você pode definir arquivos para serem enviados para o cliente utilizando `File`.
+
+/// info
+
+Para receber arquivos compartilhados, primeiro instale `python-multipart`.
+
+E.g. `pip install python-multipart`.
+
+Isso se deve por que arquivos enviados são enviados como "dados de formulário".
+
+///
+
+## Importe `File`
+
+Importe `File` e `UploadFile` do `fastapi`:
+
+{* ../../docs_src/request_files/tutorial001_an_py39.py hl[3] *}
+
+## Defina os parâmetros de `File`
+
+Cria os parâmetros do arquivo da mesma forma que você faria para `Body` ou `Form`:
+
+{* ../../docs_src/request_files/tutorial001_an_py39.py hl[9] *}
+
+/// info | Informação
+
+`File` é uma classe que herda diretamente de `Form`.
+
+Mas lembre-se que quando você importa `Query`,`Path`, `File`, entre outros, do `fastapi`, essas são na verdade funções que retornam classes especiais.
+
+///
+
+/// tip | Dica
+
+Para declarar o corpo de arquivos, você precisa utilizar `File`, do contrário os parâmetros seriam interpretados como parâmetros de consulta ou corpo (JSON) da requisição.
+
+///
+
+Os arquivos serão enviados como "form data".
+
+Se você declarar o tipo do seu parâmetro na sua *função de operação de rota* como `bytes`, o **FastAPI** irá ler o arquivo para você e você receberá o conteúdo como `bytes`.
+
+Lembre-se que isso significa que o conteúdo inteiro será armazenado em memória. Isso funciona bem para arquivos pequenos.
+
+Mas existem vários casos em que você pode se beneficiar ao usar `UploadFile`.
+
+## Parâmetros de arquivo com `UploadFile`
+
+Defina um parâmetro de arquivo com o tipo `UploadFile`
+
+{* ../../docs_src/request_files/tutorial001_an_py39.py hl[14] *}
+
+Utilizando `UploadFile` tem várias vantagens sobre `bytes`:
+
+* Você não precisa utilizar `File()` como o valor padrão do parâmetro.
+* A classe utiliza um arquivo em "spool":
+ * Um arquivo guardado em memória até um tamanho máximo, depois desse limite ele é guardado em disco.
+* Isso significa que a classe funciona bem com arquivos grandes como imagens, vídeos, binários extensos, etc. Sem consumir toda a memória.
+* Você pode obter metadados do arquivo enviado.
+* Ela possui uma interface semelhante a arquivos `async`.
+* Ela expõe um objeto python `SpooledTemporaryFile` que você pode repassar para bibliotecas que esperam um objeto com comportamento de arquivo.
+
+### `UploadFile`
+
+`UploadFile` tem os seguintes atributos:
+
+* `filename`: Uma string (`str`) com o nome original do arquivo enviado (e.g. `myimage.jpg`).
+* `content-type`: Uma `str` com o tipo do conteúdo (tipo MIME / media) (e.g. `image/jpeg`).
+* `file`: Um objeto do tipo `SpooledTemporaryFile` (um objeto file-like). O arquivo propriamente dito que você pode passar diretamente para outras funções ou bibliotecas que esperam um objeto "file-like".
+
+`UploadFile` tem os seguintes métodos `async`. Todos eles chamam os métodos de arquivos por baixo dos panos (usando o objeto `SpooledTemporaryFile` interno).
+
+* `write(data)`: escreve dados (`data`) em `str` ou `bytes` no arquivo.
+* `read(size)`: Lê um número de bytes/caracteres de acordo com a quantidade `size` (`int`).
+* `seek(offset)`: Navega para o byte na posição `offset` (`int`) do arquivo.
+ * E.g., `await myfile.seek(0)` navegaria para o ínicio do arquivo.
+ * Isso é especialmente útil se você executar `await myfile.read()` uma vez e depois precisar ler os conteúdos do arquivo de novo.
+* `close()`: Fecha o arquivo.
+
+Como todos esses métodos são assíncronos (`async`) você precisa esperar ("await") por eles.
+
+Por exemplo, dentro de uma *função de operação de rota* assíncrona você pode obter os conteúdos com:
+
+```Python
+contents = await myfile.read()
+```
+
+Se você estiver dentro de uma *função de operação de rota* definida normalmente com `def`, você pode acessar `UploadFile.file` diretamente, por exemplo:
+
+```Python
+contents = myfile.file.read()
+```
+
+/// note | Detalhes técnicos do `async`
+
+Quando você utiliza métodos assíncronos, o **FastAPI** executa os métodos do arquivo em uma threadpool e espera por eles.
+
+///
+
+/// note | Detalhes técnicos do Starlette
+
+O `UploadFile` do **FastAPI** herda diretamente do `UploadFile` do **Starlette**, mas adiciona algumas funcionalidades necessárias para ser compatível com o **Pydantic**
+
+///
+
+## O que é "Form Data"
+
+A forma como formulários HTML(``) enviam dados para o servidor normalmente utilizam uma codificação "especial" para esses dados, que é diferente do JSON.
+
+O **FastAPI** garante que os dados serão lidos da forma correta, em vez do JSON.
+
+/// note | Detalhes Técnicos
+
+Dados vindos de formulários geralmente tem a codificação com o "media type" `application/x-www-form-urlencoded` quando estes não incluem arquivos.
+
+Mas quando os dados incluem arquivos, eles são codificados como `multipart/form-data`. Se você utilizar `File`, **FastAPI** saberá que deve receber os arquivos da parte correta do corpo da requisição.
+
+Se você quer ler mais sobre essas codificações e campos de formulário, veja a documentação online da MDN sobre POST .
+
+///
+
+/// warning | Aviso
+
+Você pode declarar múltiplos parâmetros `File` e `Form` em uma *operação de rota*, mas você não pode declarar campos `Body`que seriam recebidos como JSON junto desses parâmetros, por que a codificação do corpo da requisição será `multipart/form-data` em vez de `application/json`.
+
+Isso não é uma limitação do **FastAPI**, é uma parte do protocolo HTTP.
+
+///
+
+## Arquivo de upload opcional
+
+Você pode definir um arquivo como opcional utilizando as anotações de tipo padrão e definindo o valor padrão como `None`:
+
+{* ../../docs_src/request_files/tutorial001_02_an_py310.py hl[9,17] *}
+
+## `UploadFile` com Metadados Adicionais
+
+Você também pode utilizar `File()` com `UploadFile`, por exemplo, para definir metadados adicionais:
+
+{* ../../docs_src/request_files/tutorial001_03_an_py39.py hl[9,15] *}
+
+## Envio de Múltiplos Arquivos
+
+É possível enviar múltiplos arquivos ao mesmo tmepo.
+
+Ele ficam associados ao mesmo "campo do formulário" enviado com "form data".
+
+Para usar isso, declare uma lista de `bytes` ou `UploadFile`:
+
+{* ../../docs_src/request_files/tutorial002_an_py39.py hl[10,15] *}
+
+Você irá receber, como delcarado uma lista (`list`) de `bytes` ou `UploadFile`s,
+
+/// note | Detalhes Técnicos
+
+Você também poderia utilizar `from starlette.responses import HTMLResponse`.
+
+O **FastAPI** fornece as mesmas `starlette.responses` como `fastapi.responses` apenas como um facilitador para você, desenvolvedor. Mas a maior parte das respostas vem diretamente do Starlette.
+
+///
+
+### Enviando Múltiplos Arquivos com Metadados Adicionais
+
+E da mesma forma que antes, você pode utilizar `File()` para definir parâmetros adicionais, até mesmo para `UploadFile`:
+
+{* ../../docs_src/request_files/tutorial003_an_py39.py hl[11,18:20] *}
+
+## Recapitulando
+
+Use `File`, `bytes` e `UploadFile` para declarar arquivos que serão enviados na requisição, enviados como dados do formulário.
diff --git a/docs/pt/docs/tutorial/response-model.md b/docs/pt/docs/tutorial/response-model.md
new file mode 100644
index 000000000..6726a20a7
--- /dev/null
+++ b/docs/pt/docs/tutorial/response-model.md
@@ -0,0 +1,357 @@
+# Modelo de resposta - Tipo de retorno
+
+Você pode declarar o tipo usado para a resposta anotando o **tipo de retorno** *da função de operação de rota*.
+
+Você pode usar **anotações de tipo** da mesma forma que usaria para dados de entrada em **parâmetros** de função, você pode usar modelos Pydantic, listas, dicionários, valores escalares como inteiros, booleanos, etc.
+
+{* ../../docs_src/response_model/tutorial001_01_py310.py hl[16,21] *}
+
+O FastAPI usará este tipo de retorno para:
+
+* **Validar** os dados retornados.
+ * Se os dados forem inválidos (por exemplo, se estiver faltando um campo), significa que o código do *seu* aplicativo está quebrado, não retornando o que deveria, e retornará um erro de servidor em vez de retornar dados incorretos. Dessa forma, você e seus clientes podem ter certeza de que receberão os dados e o formato de dados esperados.
+* Adicionar um **Esquema JSON** para a resposta, na *operação de rota* do OpenAPI.
+ * Isso será usado pela **documentação automática**.
+ * Também será usado por ferramentas de geração automática de código do cliente.
+
+Mas o mais importante:
+
+* Ele **limitará e filtrará** os dados de saída para o que está definido no tipo de retorno.
+ * Isso é particularmente importante para a **segurança**, veremos mais sobre isso abaixo.
+
+## Parâmetro `response_model`
+
+Existem alguns casos em que você precisa ou deseja retornar alguns dados que não são exatamente o que o tipo declara.
+
+Por exemplo, você pode querer **retornar um dicionário** ou um objeto de banco de dados, mas **declará-lo como um modelo Pydantic**. Dessa forma, o modelo Pydantic faria toda a documentação de dados, validação, etc. para o objeto que você retornou (por exemplo, um dicionário ou objeto de banco de dados).
+
+Se você adicionasse a anotação do tipo de retorno, ferramentas e editores reclamariam com um erro (correto) informando que sua função está retornando um tipo (por exemplo, um dict) diferente do que você declarou (por exemplo, um modelo Pydantic).
+
+Nesses casos, você pode usar o parâmetro `response_model` do *decorador de operação de rota* em vez do tipo de retorno.
+
+Você pode usar o parâmetro `response_model` em qualquer uma das *operações de rota*:
+
+* `@app.get()`
+* `@app.post()`
+* `@app.put()`
+* `@app.delete()`
+* etc.
+
+{* ../../docs_src/response_model/tutorial001_py310.py hl[17,22,24:27] *}
+
+/// note | Nota
+
+Observe que `response_model` é um parâmetro do método "decorator" (`get`, `post`, etc). Não da sua *função de operação de rota*, como todos os parâmetros e corpo.
+
+///
+
+`response_model` recebe o mesmo tipo que você declararia para um campo de modelo Pydantic, então, pode ser um modelo Pydantic, mas também pode ser, por exemplo, uma `lista` de modelos Pydantic, como `List[Item]`.
+
+O FastAPI usará este `response_model` para fazer toda a documentação de dados, validação, etc. e também para **converter e filtrar os dados de saída** para sua declaração de tipo.
+
+/// tip | Dica
+
+Se você tiver verificações de tipo rigorosas em seu editor, mypy, etc, você pode declarar o tipo de retorno da função como `Any`.
+
+Dessa forma, você diz ao editor que está retornando qualquer coisa intencionalmente. Mas o FastAPI ainda fará a documentação de dados, validação, filtragem, etc. com o `response_model`.
+
+///
+
+### Prioridade `response_model`
+
+Se você declarar tanto um tipo de retorno quanto um `response_model`, o `response_model` terá prioridade e será usado pelo FastAPI.
+
+Dessa forma, você pode adicionar anotações de tipo corretas às suas funções, mesmo quando estiver retornando um tipo diferente do modelo de resposta, para ser usado pelo editor e ferramentas como mypy. E ainda assim você pode fazer com que o FastAPI faça a validação de dados, documentação, etc. usando o `response_model`.
+
+Você também pode usar `response_model=None` para desabilitar a criação de um modelo de resposta para essa *operação de rota*, você pode precisar fazer isso se estiver adicionando anotações de tipo para coisas que não são campos Pydantic válidos, você verá um exemplo disso em uma das seções abaixo.
+
+## Retorna os mesmos dados de entrada
+
+Aqui estamos declarando um modelo `UserIn`, ele conterá uma senha em texto simples:
+
+{* ../../docs_src/response_model/tutorial002_py310.py hl[7,9] *}
+
+/// info | Informação
+
+Para usar `EmailStr`, primeiro instale `email-validator`.
+
+Certifique-se de criar um [ambiente virtual](../virtual-environments.md){.internal-link target=_blank}, ative-o e instale-o, por exemplo:
+
+```console
+$ pip install email-validator
+```
+
+ou com:
+
+```console
+$ pip install "pydantic[email]"
+```
+
+///
+
+E estamos usando este modelo para declarar nossa entrada e o mesmo modelo para declarar nossa saída:
+
+{* ../../docs_src/response_model/tutorial002_py310.py hl[16] *}
+
+Agora, sempre que um navegador estiver criando um usuário com uma senha, a API retornará a mesma senha na resposta.
+
+Neste caso, pode não ser um problema, porque é o mesmo usuário enviando a senha.
+
+Mas se usarmos o mesmo modelo para outra *operação de rota*, poderíamos estar enviando as senhas dos nossos usuários para todos os clientes.
+
+/// danger | Perigo
+
+Nunca armazene a senha simples de um usuário ou envie-a em uma resposta como esta, a menos que você saiba todas as ressalvas e saiba o que está fazendo.
+
+///
+
+## Adicionar um modelo de saída
+
+Podemos, em vez disso, criar um modelo de entrada com a senha em texto simples e um modelo de saída sem ela:
+
+{* ../../docs_src/response_model/tutorial003_py310.py hl[9,11,16] *}
+
+Aqui, embora nossa *função de operação de rota* esteja retornando o mesmo usuário de entrada que contém a senha:
+
+{* ../../docs_src/response_model/tutorial003_py310.py hl[24] *}
+
+...declaramos o `response_model` como nosso modelo `UserOut`, que não inclui a senha:
+
+{* ../../docs_src/response_model/tutorial003_py310.py hl[22] *}
+
+Então, **FastAPI** cuidará de filtrar todos os dados que não são declarados no modelo de saída (usando Pydantic).
+
+### `response_model` ou Tipo de Retorno
+
+Neste caso, como os dois modelos são diferentes, se anotássemos o tipo de retorno da função como `UserOut`, o editor e as ferramentas reclamariam que estamos retornando um tipo inválido, pois são classes diferentes.
+
+É por isso que neste exemplo temos que declará-lo no parâmetro `response_model`.
+
+...mas continue lendo abaixo para ver como superar isso.
+
+## Tipo de Retorno e Filtragem de Dados
+
+Vamos continuar do exemplo anterior. Queríamos **anotar a função com um tipo**, mas queríamos poder retornar da função algo que realmente incluísse **mais dados**.
+
+Queremos que o FastAPI continue **filtrando** os dados usando o modelo de resposta. Para que, embora a função retorne mais dados, a resposta inclua apenas os campos declarados no modelo de resposta.
+
+No exemplo anterior, como as classes eram diferentes, tivemos que usar o parâmetro `response_model`. Mas isso também significa que não temos suporte do editor e das ferramentas verificando o tipo de retorno da função.
+
+Mas na maioria dos casos em que precisamos fazer algo assim, queremos que o modelo apenas **filtre/remova** alguns dados como neste exemplo.
+
+E nesses casos, podemos usar classes e herança para aproveitar as **anotações de tipo** de função para obter melhor suporte no editor e nas ferramentas, e ainda obter a **filtragem de dados** FastAPI.
+
+{* ../../docs_src/response_model/tutorial003_01_py310.py hl[7:10,13:14,18] *}
+
+Com isso, temos suporte de ferramentas, de editores e mypy, pois este código está correto em termos de tipos, mas também obtemos a filtragem de dados do FastAPI.
+
+Como isso funciona? Vamos verificar. 🤓
+
+### Anotações de tipo e ferramentas
+
+Primeiro, vamos ver como editores, mypy e outras ferramentas veriam isso.
+
+`BaseUser` tem os campos base. Então `UserIn` herda de `BaseUser` e adiciona o campo `password`, então, ele incluirá todos os campos de ambos os modelos.
+
+Anotamos o tipo de retorno da função como `BaseUser`, mas na verdade estamos retornando uma instância `UserIn`.
+
+O editor, mypy e outras ferramentas não reclamarão disso porque, em termos de digitação, `UserIn` é uma subclasse de `BaseUser`, o que significa que é um tipo *válido* quando o que é esperado é qualquer coisa que seja um `BaseUser`.
+
+### Filtragem de dados FastAPI
+
+Agora, para FastAPI, ele verá o tipo de retorno e garantirá que o que você retornar inclua **apenas** os campos que são declarados no tipo.
+
+O FastAPI faz várias coisas internamente com o Pydantic para garantir que essas mesmas regras de herança de classe não sejam usadas para a filtragem de dados retornados, caso contrário, você pode acabar retornando muito mais dados do que o esperado.
+
+Dessa forma, você pode obter o melhor dos dois mundos: anotações de tipo com **suporte a ferramentas** e **filtragem de dados**.
+
+## Veja na documentação
+
+Quando você vê a documentação automática, pode verificar se o modelo de entrada e o modelo de saída terão seus próprios esquemas JSON:
+
+
+
+E ambos os modelos serão usados para a documentação interativa da API:
+
+
+
+## Outras anotações de tipo de retorno
+
+Pode haver casos em que você retorna algo que não é um campo Pydantic válido e anota na função, apenas para obter o suporte fornecido pelas ferramentas (o editor, mypy, etc).
+
+### Retornar uma resposta diretamente
+
+O caso mais comum seria [retornar uma resposta diretamente, conforme explicado posteriormente na documentação avançada](../advanced/response-directly.md){.internal-link target=_blank}.
+
+{* ../../docs_src/response_model/tutorial003_02.py hl[8,10:11] *}
+
+Este caso simples é tratado automaticamente pelo FastAPI porque a anotação do tipo de retorno é a classe (ou uma subclasse de) `Response`.
+
+E as ferramentas também ficarão felizes porque `RedirectResponse` e `JSONResponse` são subclasses de `Response`, então a anotação de tipo está correta.
+
+### Anotar uma subclasse de resposta
+
+Você também pode usar uma subclasse de `Response` na anotação de tipo:
+
+{* ../../docs_src/response_model/tutorial003_03.py hl[8:9] *}
+
+Isso também funcionará porque `RedirectResponse` é uma subclasse de `Response`, e o FastAPI tratará automaticamente este caso simples.
+
+### Anotações de Tipo de Retorno Inválido
+
+Mas quando você retorna algum outro objeto arbitrário que não é um tipo Pydantic válido (por exemplo, um objeto de banco de dados) e você o anota dessa forma na função, o FastAPI tentará criar um modelo de resposta Pydantic a partir dessa anotação de tipo e falhará.
+
+O mesmo aconteceria se você tivesse algo como uma união entre tipos diferentes onde um ou mais deles não são tipos Pydantic válidos, por exemplo, isso falharia 💥:
+
+{* ../../docs_src/response_model/tutorial003_04_py310.py hl[8] *}
+
+... isso falha porque a anotação de tipo não é um tipo Pydantic e não é apenas uma única classe ou subclasse `Response`, é uma união (qualquer uma das duas) entre um `Response` e um `dict`.
+
+### Desabilitar modelo de resposta
+
+Continuando com o exemplo acima, você pode não querer ter a validação de dados padrão, documentação, filtragem, etc. que é realizada pelo FastAPI.
+
+Mas você pode querer manter a anotação do tipo de retorno na função para obter o suporte de ferramentas como editores e verificadores de tipo (por exemplo, mypy).
+
+Neste caso, você pode desabilitar a geração do modelo de resposta definindo `response_model=None`:
+
+{* ../../docs_src/response_model/tutorial003_05_py310.py hl[7] *}
+
+Isso fará com que o FastAPI pule a geração do modelo de resposta e, dessa forma, você pode ter quaisquer anotações de tipo de retorno que precisar sem afetar seu aplicativo FastAPI. 🤓
+
+## Parâmetros de codificação do modelo de resposta
+
+Seu modelo de resposta pode ter valores padrão, como:
+
+{* ../../docs_src/response_model/tutorial004_py310.py hl[9,11:12] *}
+
+* `description: Union[str, None] = None` (ou `str | None = None` no Python 3.10) tem um padrão de `None`.
+* `tax: float = 10.5` tem um padrão de `10.5`.
+* `tags: List[str] = []` tem um padrão de uma lista vazia: `[]`.
+
+mas você pode querer omiti-los do resultado se eles não foram realmente armazenados.
+
+Por exemplo, se você tem modelos com muitos atributos opcionais em um banco de dados NoSQL, mas não quer enviar respostas JSON muito longas cheias de valores padrão.
+
+### Usar o parâmetro `response_model_exclude_unset`
+
+Você pode definir o parâmetro `response_model_exclude_unset=True` do *decorador de operação de rota* :
+
+{* ../../docs_src/response_model/tutorial004_py310.py hl[22] *}
+
+e esses valores padrão não serão incluídos na resposta, apenas os valores realmente definidos.
+
+Então, se você enviar uma solicitação para essa *operação de rota* para o item com ID `foo`, a resposta (sem incluir valores padrão) será:
+
+```JSON
+{
+"name": "Foo",
+"price": 50.2
+}
+```
+
+/// info | Informação
+
+No Pydantic v1, o método era chamado `.dict()`, ele foi descontinuado (mas ainda suportado) no Pydantic v2 e renomeado para `.model_dump()`.
+
+Os exemplos aqui usam `.dict()` para compatibilidade com Pydantic v1, mas você deve usar `.model_dump()` em vez disso se puder usar Pydantic v2.
+
+///
+
+/// info | Informação
+
+O FastAPI usa `.dict()` do modelo Pydantic com seu parâmetro `exclude_unset` para chegar a isso.
+
+///
+
+/// info | Informação
+
+Você também pode usar:
+
+* `response_model_exclude_defaults=True`
+* `response_model_exclude_none=True`
+
+conforme descrito na documentação do Pydantic para `exclude_defaults` e `exclude_none`.
+
+///
+
+#### Dados com valores para campos com padrões
+
+Mas se seus dados tiverem valores para os campos do modelo com valores padrões, como o item com ID `bar`:
+
+```Python hl_lines="3 5"
+{
+"name": "Bar",
+"description": "The bartenders",
+"price": 62,
+"tax": 20.2
+}
+```
+
+eles serão incluídos na resposta.
+
+#### Dados com os mesmos valores que os padrões
+
+Se os dados tiverem os mesmos valores que os padrões, como o item com ID `baz`:
+
+```Python hl_lines="3 5-6"
+{
+"name": "Baz",
+"description": None,
+"price": 50.2,
+"tax": 10.5,
+"tags": []
+}
+```
+
+O FastAPI é inteligente o suficiente (na verdade, o Pydantic é inteligente o suficiente) para perceber que, embora `description`, `tax` e `tags` tenham os mesmos valores que os padrões, eles foram definidos explicitamente (em vez de retirados dos padrões).
+
+Portanto, eles serão incluídos na resposta JSON.
+
+/// tip | Dica
+
+Observe que os valores padrão podem ser qualquer coisa, não apenas `None`.
+
+Eles podem ser uma lista (`[]`), um `float` de `10.5`, etc.
+
+///
+
+### `response_model_include` e `response_model_exclude`
+
+Você também pode usar os parâmetros `response_model_include` e `response_model_exclude` do *decorador de operação de rota*.
+
+Eles pegam um `set` de `str` com o nome dos atributos para incluir (omitindo o resto) ou para excluir (incluindo o resto).
+
+Isso pode ser usado como um atalho rápido se você tiver apenas um modelo Pydantic e quiser remover alguns dados da saída.
+
+/// tip | Dica
+
+Mas ainda é recomendado usar as ideias acima, usando várias classes, em vez desses parâmetros.
+
+Isso ocorre porque o Schema JSON gerado no OpenAPI do seu aplicativo (e a documentação) ainda será o único para o modelo completo, mesmo que você use `response_model_include` ou `response_model_exclude` para omitir alguns atributos.
+
+Isso também se aplica ao `response_model_by_alias` que funciona de forma semelhante.
+
+///
+
+{* ../../docs_src/response_model/tutorial005_py310.py hl[29,35] *}
+
+/// tip | Dica
+
+A sintaxe `{"nome", "descrição"}` cria um `conjunto` com esses dois valores.
+
+É equivalente a `set(["nome", "descrição"])`.
+
+///
+
+#### Usando `list`s em vez de `set`s
+
+Se você esquecer de usar um `set` e usar uma `lista` ou `tupla` em vez disso, o FastAPI ainda o converterá em um `set` e funcionará corretamente:
+
+{* ../../docs_src/response_model/tutorial006_py310.py hl[29,35] *}
+
+## Recapitulação
+
+Use o parâmetro `response_model` do *decorador de operação de rota* para definir modelos de resposta e, especialmente, para garantir que dados privados sejam filtrados.
+
+Use `response_model_exclude_unset` para retornar apenas os valores definidos explicitamente.
diff --git a/docs/pt/docs/tutorial/response-status-code.md b/docs/pt/docs/tutorial/response-status-code.md
index 2df17d4ea..48957f67a 100644
--- a/docs/pt/docs/tutorial/response-status-code.md
+++ b/docs/pt/docs/tutorial/response-status-code.md
@@ -8,17 +8,21 @@ Da mesma forma que você pode especificar um modelo de resposta, você também p
* `@app.delete()`
* etc.
-```Python hl_lines="6"
-{!../../../docs_src/response_status_code/tutorial001.py!}
-```
+{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
-!!! note "Nota"
- Observe que `status_code` é um parâmetro do método "decorador" (get, post, etc). Não da sua função de *operação de caminho*, como todos os parâmetros e corpo.
+/// note | Nota
+
+Observe que `status_code` é um parâmetro do método "decorador" (get, post, etc). Não da sua função de *operação de caminho*, como todos os parâmetros e corpo.
+
+///
O parâmetro `status_code` recebe um número com o código de status HTTP.
-!!! info "Informação"
- `status_code` também pode receber um `IntEnum`, como o do Python `http.HTTPStatus`.
+/// info | Informação
+
+`status_code` também pode receber um `IntEnum`, como o do Python `http.HTTPStatus`.
+
+///
Dessa forma:
@@ -27,15 +31,21 @@ Dessa forma:
-!!! note "Nota"
- Alguns códigos de resposta (consulte a próxima seção) indicam que a resposta não possui um corpo.
+/// note | Nota
- O FastAPI sabe disso e produzirá documentos OpenAPI informando que não há corpo de resposta.
+Alguns códigos de resposta (consulte a próxima seção) indicam que a resposta não possui um corpo.
+
+O FastAPI sabe disso e produzirá documentos OpenAPI informando que não há corpo de resposta.
+
+///
## Sobre os códigos de status HTTP
-!!! note "Nota"
- Se você já sabe o que são códigos de status HTTP, pule para a próxima seção.
+/// note | Nota
+
+Se você já sabe o que são códigos de status HTTP, pule para a próxima seção.
+
+///
Em HTTP, você envia um código de status numérico de 3 dígitos como parte da resposta.
@@ -55,16 +65,17 @@ Resumidamente:
* Para erros genéricos do cliente, você pode usar apenas `400`.
* `500` e acima são para erros do servidor. Você quase nunca os usa diretamente. Quando algo der errado em alguma parte do código do seu aplicativo ou servidor, ele retornará automaticamente um desses códigos de status.
-!!! tip "Dica"
- Para saber mais sobre cada código de status e qual código serve para quê, verifique o MDN documentação sobre códigos de status HTTP.
+/// tip | Dica
+
+Para saber mais sobre cada código de status e qual código serve para quê, verifique o MDN documentação sobre códigos de status HTTP.
+
+///
## Atalho para lembrar os nomes
Vamos ver o exemplo anterior novamente:
-```Python hl_lines="6"
-{!../../../docs_src/response_status_code/tutorial001.py!}
-```
+{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
`201` é o código de status para "Criado".
@@ -72,19 +83,19 @@ Mas você não precisa memorizar o que cada um desses códigos significa.
Você pode usar as variáveis de conveniência de `fastapi.status`.
-```Python hl_lines="1 6"
-{!../../../docs_src/response_status_code/tutorial002.py!}
-```
+{* ../../docs_src/response_status_code/tutorial002.py hl[1,6] *}
Eles são apenas uma conveniência, eles possuem o mesmo número, mas dessa forma você pode usar o autocomplete do editor para encontrá-los:
-!!! note "Detalhes técnicos"
- Você também pode usar `from starlette import status`.
+/// note | Detalhes técnicos
- **FastAPI** fornece o mesmo `starlette.status` como `fastapi.status` apenas como uma conveniência para você, o desenvolvedor. Mas vem diretamente da Starlette.
+Você também pode usar `from starlette import status`.
+**FastAPI** fornece o mesmo `starlette.status` como `fastapi.status` apenas como uma conveniência para você, o desenvolvedor. Mas vem diretamente da Starlette.
+
+///
## Alterando o padrão
diff --git a/docs/pt/docs/tutorial/schema-extra-example.md b/docs/pt/docs/tutorial/schema-extra-example.md
index d04dc1a26..5d3498d7d 100644
--- a/docs/pt/docs/tutorial/schema-extra-example.md
+++ b/docs/pt/docs/tutorial/schema-extra-example.md
@@ -8,16 +8,17 @@ Aqui estão várias formas de se fazer isso.
Você pode declarar um `example` para um modelo Pydantic usando `Config` e `schema_extra`, conforme descrito em Documentação do Pydantic: Schema customization:
-```Python hl_lines="15-23"
-{!../../../docs_src/schema_extra_example/tutorial001.py!}
-```
+{* ../../docs_src/schema_extra_example/tutorial001.py hl[15:23] *}
Essas informações extras serão adicionadas como se encontram no **JSON Schema** de resposta desse modelo e serão usadas na documentação da API.
-!!! tip "Dica"
- Você pode usar a mesma técnica para estender o JSON Schema e adicionar suas próprias informações extras de forma personalizada.
+/// tip | Dica
- Por exemplo, você pode usar isso para adicionar metadados para uma interface de usuário de front-end, etc.
+Você pode usar a mesma técnica para estender o JSON Schema e adicionar suas próprias informações extras de forma personalizada.
+
+Por exemplo, você pode usar isso para adicionar metadados para uma interface de usuário de front-end, etc.
+
+///
## `Field` de argumentos adicionais
@@ -25,12 +26,13 @@ Ao usar `Field ()` com modelos Pydantic, você também pode declarar informaçõ
Você pode usar isso para adicionar um `example` para cada campo:
-```Python hl_lines="4 10-13"
-{!../../../docs_src/schema_extra_example/tutorial002.py!}
-```
+{* ../../docs_src/schema_extra_example/tutorial002.py hl[4,10:13] *}
-!!! warning "Atenção"
- Lembre-se de que esses argumentos extras passados não adicionarão nenhuma validação, apenas informações extras, para fins de documentação.
+/// warning | Atenção
+
+Lembre-se de que esses argumentos extras passados não adicionarão nenhuma validação, apenas informações extras, para fins de documentação.
+
+///
## `example` e `examples` no OpenAPI
@@ -50,9 +52,7 @@ você também pode declarar um dado `example` ou um grupo de `examples` com info
Aqui nós passamos um `example` dos dados esperados por `Body()`:
-```Python hl_lines="21-26"
-{!../../../docs_src/schema_extra_example/tutorial003.py!}
-```
+{* ../../docs_src/schema_extra_example/tutorial003.py hl[21:26] *}
### Exemplo na UI da documentação
@@ -73,9 +73,7 @@ Cada `dict` de exemplo específico em `examples` pode conter:
* `value`: O próprio exemplo mostrado, ex: um `dict`.
* `externalValue`: alternativa ao `value`, uma URL apontando para o exemplo. Embora isso possa não ser suportado por tantas ferramentas quanto `value`.
-```Python hl_lines="22-48"
-{!../../../docs_src/schema_extra_example/tutorial004.py!}
-```
+{* ../../docs_src/schema_extra_example/tutorial004.py hl[22:48] *}
### Exemplos na UI da documentação
@@ -85,10 +83,13 @@ Com `examples` adicionado a `Body()`, os `/docs` vão ficar assim:
## Detalhes técnicos
-!!! warning "Atenção"
- Esses são detalhes muito técnicos sobre os padrões **JSON Schema** e **OpenAPI**.
+/// warning | Atenção
- Se as ideias explicadas acima já funcionam para você, isso pode ser o suficiente, e você provavelmente não precisa desses detalhes, fique à vontade para pular.
+Esses são detalhes muito técnicos sobre os padrões **JSON Schema** e **OpenAPI**.
+
+Se as ideias explicadas acima já funcionam para você, isso pode ser o suficiente, e você provavelmente não precisa desses detalhes, fique à vontade para pular.
+
+///
Quando você adiciona um exemplo dentro de um modelo Pydantic, usando `schema_extra` ou` Field(example="something") `esse exemplo é adicionado ao **JSON Schema** para esse modelo Pydantic.
diff --git a/docs/pt/docs/tutorial/security/first-steps.md b/docs/pt/docs/tutorial/security/first-steps.md
index 4331a0bc3..f4dea8e14 100644
--- a/docs/pt/docs/tutorial/security/first-steps.md
+++ b/docs/pt/docs/tutorial/security/first-steps.md
@@ -19,13 +19,16 @@ Vamos primeiro usar o código e ver como funciona, e depois voltaremos para ente
## Crie um `main.py`
Copie o exemplo em um arquivo `main.py`:
-```Python
-{!../../../docs_src/security/tutorial001.py!}
-```
+{* ../../docs_src/security/tutorial001.py *}
## Execute-o
-!!! info "informação"
+/// info | informação
+
+
+
+///
+
Primeiro, instale `python-multipart`.
Ex: `pip install python-multipart`.
@@ -52,7 +55,12 @@ Você verá algo deste tipo:
-!!! check "Botão de Autorizar!"
+/// check | Botão de Autorizar!
+
+
+
+///
+
Você já tem um novo "botão de autorizar!".
E seu *path operation* tem um pequeno cadeado no canto superior direito que você pode clicar.
@@ -61,7 +69,12 @@ E se você clicar, você terá um pequeno formulário de autorização para digi
-!!! note "Nota"
+/// note | Nota
+
+
+
+///
+
Não importa o que você digita no formulário, não vai funcionar ainda. Mas nós vamos chegar lá.
Claro que este não é o frontend para os usuários finais, mas é uma ótima ferramenta automática para documentar interativamente toda sua API.
@@ -104,7 +117,12 @@ Então, vamos rever de um ponto de vista simplificado:
Neste exemplo, nós vamos usar o **OAuth2** com o fluxo de **Senha**, usando um token **Bearer**. Fazemos isso usando a classe `OAuth2PasswordBearer`.
-!!! info "informação"
+/// info | informação
+
+
+
+///
+
Um token "bearer" não é a única opção.
Mas é a melhor no nosso caso.
@@ -115,11 +133,14 @@ Neste exemplo, nós vamos usar o **OAuth2** com o fluxo de **Senha**, usando um
Quando nós criamos uma instância da classe `OAuth2PasswordBearer`, nós passamos pelo parâmetro `tokenUrl` Esse parâmetro contém a URL que o client (o frontend rodando no browser do usuário) vai usar para mandar o `username` e `senha` para obter um token.
-```Python hl_lines="6"
-{!../../../docs_src/security/tutorial001.py!}
-```
+{* ../../docs_src/security/tutorial001.py hl[6] *}
+
+/// tip | Dica
+
+
+
+///
-!!! tip "Dica"
Esse `tokenUrl="token"` se refere a uma URL relativa que nós não criamos ainda. Como é uma URL relativa, é equivalente a `./token`.
Porque estamos usando uma URL relativa, se sua API estava localizada em `https://example.com/`, então irá referir-se à `https://example.com/token`. Mas se sua API estava localizada em `https://example.com/api/v1/`, então irá referir-se à `https://example.com/api/v1/token`.
@@ -130,7 +151,12 @@ Esse parâmetro não cria um endpoint / *path operation*, mas declara que a URL
Em breve também criaremos o atual path operation.
-!!! info "informação"
+/// info | informação
+
+
+
+///
+
Se você é um "Pythonista" muito rigoroso, você pode não gostar do estilo do nome do parâmetro `tokenUrl` em vez de `token_url`.
Isso ocorre porque está utilizando o mesmo nome que está nas especificações do OpenAPI. Então, se você precisa investigar mais sobre qualquer um desses esquemas de segurança, você pode simplesmente copiar e colar para encontrar mais informações sobre isso.
@@ -149,15 +175,18 @@ Então, pode ser usado com `Depends`.
Agora você pode passar aquele `oauth2_scheme` em uma dependência com `Depends`.
-```Python hl_lines="10"
-{!../../../docs_src/security/tutorial001.py!}
-```
+{* ../../docs_src/security/tutorial001.py hl[10] *}
Esse dependência vai fornecer uma `str` que é atribuído ao parâmetro `token da *função do path operation*
A **FastAPI** saberá que pode usar essa dependência para definir um "esquema de segurança" no esquema da OpenAPI (e na documentação da API automática).
-!!! info "Detalhes técnicos"
+/// info | Detalhes técnicos
+
+
+
+///
+
**FastAPI** saberá que pode usar a classe `OAuth2PasswordBearer` (declarada na dependência) para definir o esquema de segurança na OpenAPI porque herda de `fastapi.security.oauth2.OAuth2`, que por sua vez herda de `fastapi.security.base.Securitybase`.
Todos os utilitários de segurança que se integram com OpenAPI (e na documentação da API automática) herdam de `SecurityBase`, é assim que **FastAPI** pode saber como integrá-los no OpenAPI.
diff --git a/docs/pt/docs/tutorial/security/get-current-user.md b/docs/pt/docs/tutorial/security/get-current-user.md
new file mode 100644
index 000000000..1a2badb83
--- /dev/null
+++ b/docs/pt/docs/tutorial/security/get-current-user.md
@@ -0,0 +1,105 @@
+# Obter Usuário Atual
+
+No capítulo anterior, o sistema de segurança (que é baseado no sistema de injeção de dependências) estava fornecendo à *função de operação de rota* um `token` como uma `str`:
+
+{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *}
+
+Mas isso ainda não é tão útil.
+
+Vamos fazer com que ele nos forneça o usuário atual.
+
+## Criar um modelo de usuário
+
+Primeiro, vamos criar um modelo de usuário com Pydantic.
+
+Da mesma forma que usamos o Pydantic para declarar corpos, podemos usá-lo em qualquer outro lugar:
+
+{* ../../docs_src/security/tutorial002_an_py310.py hl[5,12:6] *}
+
+## Criar uma dependência `get_current_user`
+
+Vamos criar uma dependência chamada `get_current_user`.
+
+Lembra que as dependências podem ter subdependências?
+
+`get_current_user` terá uma dependência com o mesmo `oauth2_scheme` que criamos antes.
+
+Da mesma forma que estávamos fazendo antes diretamente na *operação de rota*, a nossa nova dependência `get_current_user` receberá um `token` como uma `str` da subdependência `oauth2_scheme`:
+
+{* ../../docs_src/security/tutorial002_an_py310.py hl[25] *}
+
+## Obter o usuário
+
+`get_current_user` usará uma função utilitária (falsa) que criamos, que recebe um token como uma `str` e retorna nosso modelo Pydantic `User`:
+
+{* ../../docs_src/security/tutorial002_an_py310.py hl[19:22,26:27] *}
+
+## Injetar o usuário atual
+
+Então agora nós podemos usar o mesmo `Depends` com nosso `get_current_user` na *operação de rota*:
+
+{* ../../docs_src/security/tutorial002_an_py310.py hl[31] *}
+
+Observe que nós declaramos o tipo de `current_user` como o modelo Pydantic `User`.
+
+Isso nos ajudará dentro da função com todo o preenchimento automático e verificações de tipo.
+
+/// tip | Dica
+
+Você pode se lembrar que corpos de requisição também são declarados com modelos Pydantic.
+
+Aqui, o **FastAPI** não ficará confuso porque você está usando `Depends`.
+
+///
+
+/// check | Verifique
+
+A forma como esse sistema de dependências foi projetado nos permite ter diferentes dependências (diferentes "dependables") que retornam um modelo `User`.
+
+Não estamos restritos a ter apenas uma dependência que possa retornar esse tipo de dado.
+
+///
+
+## Outros modelos
+
+Agora você pode obter o usuário atual diretamente nas *funções de operação de rota* e lidar com os mecanismos de segurança no nível da **Injeção de Dependências**, usando `Depends`.
+
+E você pode usar qualquer modelo ou dado para os requisitos de segurança (neste caso, um modelo Pydantic `User`).
+
+Mas você não está restrito a usar um modelo de dados, classe ou tipo específico.
+
+Você quer ter apenas um `id` e `email`, sem incluir nenhum `username` no modelo? Claro. Você pode usar essas mesmas ferramentas.
+
+Você quer ter apenas uma `str`? Ou apenas um `dict`? Ou uma instância de modelo de classe de banco de dados diretamente? Tudo funciona da mesma forma.
+
+Na verdade, você não tem usuários que fazem login no seu aplicativo, mas sim robôs, bots ou outros sistemas, que possuem apenas um token de acesso? Novamente, tudo funciona da mesma forma.
+
+Apenas use qualquer tipo de modelo, qualquer tipo de classe, qualquer tipo de banco de dados que você precise para a sua aplicação. O **FastAPI** cobre tudo com o sistema de injeção de dependências.
+
+## Tamanho do código
+
+Este exemplo pode parecer verboso. Lembre-se de que estamos misturando segurança, modelos de dados, funções utilitárias e *operações de rota* no mesmo arquivo.
+
+Mas aqui está o ponto principal.
+
+O código relacionado à segurança e à injeção de dependências é escrito apenas uma vez.
+
+E você pode torná-lo tão complexo quanto quiser. E ainda assim, tê-lo escrito apenas uma vez, em um único lugar. Com toda a flexibilidade.
+
+Mas você pode ter milhares de endpoints (*operações de rota*) usando o mesmo sistema de segurança.
+
+E todos eles (ou qualquer parte deles que você desejar) podem aproveitar o reuso dessas dependências ou de quaisquer outras dependências que você criar.
+
+E todos esses milhares de *operações de rota* podem ter apenas 3 linhas:
+
+{* ../../docs_src/security/tutorial002_an_py310.py hl[30:32] *}
+
+## Recapitulação
+
+Agora você pode obter o usuário atual diretamente na sua *função de operação de rota*.
+
+Já estamos na metade do caminho.
+
+Só precisamos adicionar uma *operação de rota* para que o usuário/cliente realmente envie o `username` e `password`.
+
+Isso vem a seguir.
diff --git a/docs/pt/docs/tutorial/security/index.md b/docs/pt/docs/tutorial/security/index.md
index f94a8ab62..b4440ec04 100644
--- a/docs/pt/docs/tutorial/security/index.md
+++ b/docs/pt/docs/tutorial/security/index.md
@@ -32,9 +32,11 @@ Não é muito popular ou usado nos dias atuais.
OAuth2 não especifica como criptografar a comunicação, ele espera que você tenha sua aplicação em um servidor HTTPS.
-!!! tip "Dica"
- Na seção sobre **deployment** você irá ver como configurar HTTPS de modo gratuito, usando Traefik e Let’s Encrypt.
+/// tip | Dica
+Na seção sobre **deployment** você irá ver como configurar HTTPS de modo gratuito, usando Traefik e Let’s Encrypt.
+
+///
## OpenID Connect
@@ -87,10 +89,13 @@ OpenAPI define os seguintes esquemas de segurança:
* Essa descoberta automática é o que é definido na especificação OpenID Connect.
-!!! tip "Dica"
- Integração com outros provedores de autenticação/autorização como Google, Facebook, Twitter, GitHub, etc. é bem possível e relativamente fácil.
+/// tip | Dica
- O problema mais complexo é criar um provedor de autenticação/autorização como eles, mas o FastAPI dá a você ferramentas para fazer isso facilmente, enquanto faz o trabalho pesado para você.
+Integração com outros provedores de autenticação/autorização como Google, Facebook, Twitter, GitHub, etc. é bem possível e relativamente fácil.
+
+O problema mais complexo é criar um provedor de autenticação/autorização como eles, mas o FastAPI dá a você ferramentas para fazer isso facilmente, enquanto faz o trabalho pesado para você.
+
+///
## **FastAPI** utilitários
diff --git a/docs/pt/docs/tutorial/security/oauth2-jwt.md b/docs/pt/docs/tutorial/security/oauth2-jwt.md
new file mode 100644
index 000000000..4b99c4c59
--- /dev/null
+++ b/docs/pt/docs/tutorial/security/oauth2-jwt.md
@@ -0,0 +1,274 @@
+# OAuth2 com Senha (e hashing), Bearer com tokens JWT
+
+Agora que temos todo o fluxo de segurança, vamos tornar a aplicação realmente segura, usando tokens JWT e hashing de senhas seguras.
+
+Este código é algo que você pode realmente usar na sua aplicação, salvar os hashes das senhas no seu banco de dados, etc.
+
+Vamos começar de onde paramos no capítulo anterior e incrementá-lo.
+
+## Sobre o JWT
+
+JWT significa "JSON Web Tokens".
+
+É um padrão para codificar um objeto JSON em uma string longa e densa sem espaços. Ele se parece com isso:
+
+```
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+```
+
+Ele não é criptografado, então qualquer pessoa pode recuperar as informações do seu conteúdo.
+
+Mas ele é assinado. Assim, quando você recebe um token que você emitiu, você pode verificar que foi realmente você quem o emitiu.
+
+Dessa forma, você pode criar um token com um prazo de expiração, digamos, de 1 semana. E então, quando o usuário voltar no dia seguinte com o token, você sabe que ele ainda está logado no seu sistema.
+
+Depois de uma semana, o token expirará e o usuário não estará autorizado, precisando fazer login novamente para obter um novo token. E se o usuário (ou uma terceira parte) tentar modificar o token para alterar a expiração, você seria capaz de descobrir isso, pois as assinaturas não iriam corresponder.
+
+Se você quiser brincar com tokens JWT e ver como eles funcionam, visite https://jwt.io.
+
+## Instalar `PyJWT`
+
+Nós precisamos instalar o `PyJWT` para criar e verificar os tokens JWT em Python.
+
+Certifique-se de criar um [ambiente virtual](../../virtual-environments.md){.internal-link target=_blank}, ativá-lo e então instalar o `pyjwt`:
+
+
+
+Autorize a aplicação da mesma maneira que antes.
+
+Usando as credenciais:
+
+Username: `johndoe`
+Password: `secret`
+
+/// check | Verifique
+
+Observe que em nenhuma parte do código está a senha em texto puro "`secret`", nós temos apenas o hash.
+
+///
+
+
+
+Chame o endpoint `/users/me/`, você receberá o retorno como:
+
+```JSON
+{
+ "username": "johndoe",
+ "email": "johndoe@example.com",
+ "full_name": "John Doe",
+ "disabled": false
+}
+```
+
+
+
+Se você abrir as ferramentas de desenvolvedor, poderá ver que os dados enviados incluem apenas o token. A senha é enviada apenas na primeira requisição para autenticar o usuário e obter o token de acesso, mas não é enviada nas próximas requisições:
+
+
+
+/// note | Nota
+
+Perceba que o cabeçalho `Authorization`, com o valor que começa com `Bearer `.
+
+///
+
+## Uso avançado com `scopes`
+
+O OAuth2 tem a noção de "scopes" (escopos).
+
+Você pode usá-los para adicionar um conjunto específico de permissões a um token JWT.
+
+Então, você pode dar este token diretamente a um usuário ou a uma terceira parte para interagir com sua API com um conjunto de restrições.
+
+Você pode aprender como usá-los e como eles são integrados ao **FastAPI** mais adiante no **Guia Avançado do Usuário**.
+
+
+## Recapitulação
+
+Com o que você viu até agora, você pode configurar uma aplicação **FastAPI** segura usando padrões como OAuth2 e JWT.
+
+Em quase qualquer framework, lidar com a segurança se torna rapidamente um assunto bastante complexo.
+
+Muitos pacotes que simplificam bastante isso precisam fazer muitas concessões com o modelo de dados, o banco de dados e os recursos disponíveis. E alguns desses pacotes que simplificam demais na verdade têm falhas de segurança subjacentes.
+
+---
+
+O **FastAPI** não faz nenhuma concessão com nenhum banco de dados, modelo de dados ou ferramenta.
+
+Ele oferece toda a flexibilidade para você escolher as opções que melhor se ajustam ao seu projeto.
+
+E você pode usar diretamente muitos pacotes bem mantidos e amplamente utilizados, como `passlib` e `PyJWT`, porque o **FastAPI** não exige mecanismos complexos para integrar pacotes externos.
+
+Mas ele fornece as ferramentas para simplificar o processo o máximo possível, sem comprometer a flexibilidade, robustez ou segurança.
+
+E você pode usar e implementar protocolos padrão seguros, como o OAuth2, de uma maneira relativamente simples.
+
+Você pode aprender mais no **Guia Avançado do Usuário** sobre como usar os "scopes" do OAuth2 para um sistema de permissões mais refinado, seguindo esses mesmos padrões. O OAuth2 com scopes é o mecanismo usado por muitos provedores grandes de autenticação, como o Facebook, Google, GitHub, Microsoft, Twitter, etc. para autorizar aplicativos de terceiros a interagir com suas APIs em nome de seus usuários.
diff --git a/docs/pt/docs/tutorial/security/simple-oauth2.md b/docs/pt/docs/tutorial/security/simple-oauth2.md
new file mode 100644
index 000000000..1cf05785e
--- /dev/null
+++ b/docs/pt/docs/tutorial/security/simple-oauth2.md
@@ -0,0 +1,289 @@
+# Simples OAuth2 com senha e Bearer
+
+Agora vamos construir a partir do capítulo anterior e adicionar as partes que faltam para ter um fluxo de segurança completo.
+
+## Pegue o `username` (nome de usuário) e `password` (senha)
+
+É utilizado o utils de segurança da **FastAPI** para obter o `username` e a `password`.
+
+OAuth2 especifica que ao usar o "password flow" (fluxo de senha), que estamos usando, o cliente/usuário deve enviar os campos `username` e `password` como dados do formulário.
+
+E a especificação diz que os campos devem ser nomeados assim. Portanto, `user-name` ou `email` não funcionariam.
+
+Mas não se preocupe, você pode mostrá-lo como quiser aos usuários finais no frontend.
+
+E seus modelos de banco de dados podem usar qualquer outro nome que você desejar.
+
+Mas para a *operação de rota* de login, precisamos usar esses nomes para serem compatíveis com a especificação (e poder, por exemplo, usar o sistema integrado de documentação da API).
+
+A especificação também afirma que o `username` e a `password` devem ser enviados como dados de formulário (portanto, não há JSON aqui).
+
+### `scope`
+
+A especificação também diz que o cliente pode enviar outro campo de formulário "`scope`" (Escopo).
+
+O nome do campo do formulário é `scope` (no singular), mas na verdade é uma longa string com "escopos" separados por espaços.
+
+Cada “scope” é apenas uma string (sem espaços).
+
+Normalmente são usados para declarar permissões de segurança específicas, por exemplo:
+
+* `users:read` ou `users:write` são exemplos comuns.
+* `instagram_basic` é usado pelo Facebook e Instagram.
+* `https://www.googleapis.com/auth/drive` é usado pelo Google.
+
+/// info | Informação
+
+No OAuth2, um "scope" é apenas uma string que declara uma permissão específica necessária.
+
+Não importa se tem outros caracteres como `:` ou se é uma URL.
+
+Esses detalhes são específicos da implementação.
+
+Para OAuth2 são apenas strings.
+
+///
+
+## Código para conseguir o `username` e a `password`
+
+Agora vamos usar os utilitários fornecidos pelo **FastAPI** para lidar com isso.
+
+### `OAuth2PasswordRequestForm`
+
+Primeiro, importe `OAuth2PasswordRequestForm` e use-o como uma dependência com `Depends` na *operação de rota* para `/token`:
+
+{* ../../docs_src/security/tutorial003_an_py310.py hl[4,78] *}
+
+`OAuth2PasswordRequestForm` é uma dependência de classe que declara um corpo de formulário com:
+
+* O `username`.
+* A `password`.
+* Um campo `scope` opcional como uma string grande, composta de strings separadas por espaços.
+* Um `grant_type` (tipo de concessão) opcional.
+
+/// tip | Dica
+
+A especificação OAuth2 na verdade *requer* um campo `grant_type` com um valor fixo de `password`, mas `OAuth2PasswordRequestForm` não o impõe.
+
+Se você precisar aplicá-lo, use `OAuth2PasswordRequestFormStrict` em vez de `OAuth2PasswordRequestForm`.
+
+///
+
+* Um `client_id` opcional (não precisamos dele em nosso exemplo).
+* Um `client_secret` opcional (não precisamos dele em nosso exemplo).
+
+/// info | Informação
+
+O `OAuth2PasswordRequestForm` não é uma classe especial para **FastAPI** como é `OAuth2PasswordBearer`.
+
+`OAuth2PasswordBearer` faz com que **FastAPI** saiba que é um esquema de segurança. Portanto, é adicionado dessa forma ao OpenAPI.
+
+Mas `OAuth2PasswordRequestForm` é apenas uma dependência de classe que você mesmo poderia ter escrito ou poderia ter declarado os parâmetros do `Form` (formulário) diretamente.
+
+Mas como é um caso de uso comum, ele é fornecido diretamente pelo **FastAPI**, apenas para facilitar.
+
+///
+
+### Use os dados do formulário
+
+/// tip | Dica
+
+A instância da classe de dependência `OAuth2PasswordRequestForm` não terá um atributo `scope` com a string longa separada por espaços, em vez disso, terá um atributo `scopes` com a lista real de strings para cada escopo enviado.
+
+Não estamos usando `scopes` neste exemplo, mas a funcionalidade está disponível se você precisar.
+
+///
+
+Agora, obtenha os dados do usuário do banco de dados (falso), usando o `username` do campo do formulário.
+
+Se não existir tal usuário, retornaremos um erro dizendo "Incorrect username or password" (Nome de usuário ou senha incorretos).
+
+Para o erro, usamos a exceção `HTTPException`:
+
+{* ../../docs_src/security/tutorial003_an_py310.py hl[3,79:81] *}
+
+### Confira a password (senha)
+
+Neste ponto temos os dados do usuário do nosso banco de dados, mas não verificamos a senha.
+
+Vamos colocar esses dados primeiro no modelo `UserInDB` do Pydantic.
+
+Você nunca deve salvar senhas em texto simples, portanto, usaremos o sistema de hashing de senhas (falsas).
+
+Se as senhas não corresponderem, retornaremos o mesmo erro.
+
+#### Hashing de senha
+
+"Hashing" significa: converter algum conteúdo (uma senha neste caso) em uma sequência de bytes (apenas uma string) que parece algo sem sentido.
+
+Sempre que você passa exatamente o mesmo conteúdo (exatamente a mesma senha), você obtém exatamente a mesma sequência aleatória de caracteres.
+
+Mas você não pode converter a sequência aleatória de caracteres de volta para a senha.
+
+##### Porque usar hashing de senha
+
+Se o seu banco de dados for roubado, o ladrão não terá as senhas em texto simples dos seus usuários, apenas os hashes.
+
+Assim, o ladrão não poderá tentar usar essas mesmas senhas em outro sistema (como muitos usuários usam a mesma senha em todos os lugares, isso seria perigoso).
+
+{* ../../docs_src/security/tutorial003_an_py310.py hl[82:85] *}
+
+#### Sobre `**user_dict`
+
+`UserInDB(**user_dict)` significa:
+
+*Passe as keys (chaves) e values (valores) de `user_dict` diretamente como argumentos de valor-chave, equivalente a:*
+
+```Python
+UserInDB(
+ username = user_dict["username"],
+ email = user_dict["email"],
+ full_name = user_dict["full_name"],
+ disabled = user_dict["disabled"],
+ hashed_password = user_dict["hashed_password"],
+)
+```
+
+/// info | Informação
+
+Para uma explicação mais completa de `**user_dict`, verifique [a documentação para **Extra Models**](../extra-models.md#about-user_indict){.internal-link target=_blank}.
+
+///
+
+## Retorne o token
+
+A resposta do endpoint `token` deve ser um objeto JSON.
+
+Deve ter um `token_type`. No nosso caso, como estamos usando tokens "Bearer", o tipo de token deve ser "`bearer`".
+
+E deve ter um `access_token`, com uma string contendo nosso token de acesso.
+
+Para este exemplo simples, seremos completamente inseguros e retornaremos o mesmo `username` do token.
+
+/// tip | Dica
+
+No próximo capítulo, você verá uma implementação realmente segura, com hash de senha e tokens JWT.
+
+Mas, por enquanto, vamos nos concentrar nos detalhes específicos de que precisamos.
+
+///
+
+{* ../../docs_src/security/tutorial003_an_py310.py hl[87] *}
+
+/// tip | Dica
+
+Pela especificação, você deve retornar um JSON com um `access_token` e um `token_type`, o mesmo que neste exemplo.
+
+Isso é algo que você mesmo deve fazer em seu código e certifique-se de usar essas chaves JSON.
+
+É quase a única coisa que você deve se lembrar de fazer corretamente, para estar em conformidade com as especificações.
+
+De resto, **FastAPI** cuida disso para você.
+
+///
+
+## Atualize as dependências
+
+Agora vamos atualizar nossas dependências.
+
+Queremos obter o `user_user` *somente* se este usuário estiver ativo.
+
+Portanto, criamos uma dependência adicional `get_current_active_user` que por sua vez usa `get_current_user` como dependência.
+
+Ambas as dependências retornarão apenas um erro HTTP se o usuário não existir ou se estiver inativo.
+
+Portanto, em nosso endpoint, só obteremos um usuário se o usuário existir, tiver sido autenticado corretamente e estiver ativo:
+
+{* ../../docs_src/security/tutorial003_an_py310.py hl[58:66,69:74,94] *}
+
+/// info | Informação
+
+O cabeçalho adicional `WWW-Authenticate` com valor `Bearer` que estamos retornando aqui também faz parte da especificação.
+
+Qualquer código de status HTTP (erro) 401 "UNAUTHORIZED" também deve retornar um cabeçalho `WWW-Authenticate`.
+
+No caso de tokens ao portador (nosso caso), o valor desse cabeçalho deve ser `Bearer`.
+
+Na verdade, você pode pular esse cabeçalho extra e ainda funcionaria.
+
+Mas é fornecido aqui para estar em conformidade com as especificações.
+
+Além disso, pode haver ferramentas que esperam e usam isso (agora ou no futuro) e que podem ser úteis para você ou seus usuários, agora ou no futuro.
+
+Esse é o benefício dos padrões...
+
+///
+
+## Veja em ação
+
+Abra o docs interativo: http://127.0.0.1:8000/docs.
+
+### Autenticação
+
+Clique no botão "Authorize".
+
+Use as credenciais:
+
+User: `johndoe`
+
+Password: `secret`
+
+
+
+Após autenticar no sistema, você verá assim:
+
+
+
+### Obtenha seus próprios dados de usuário
+
+Agora use a operação `GET` com o caminho `/users/me`.
+
+Você obterá os dados do seu usuário, como:
+
+```JSON
+{
+ "username": "johndoe",
+ "email": "johndoe@example.com",
+ "full_name": "John Doe",
+ "disabled": false,
+ "hashed_password": "fakehashedsecret"
+}
+```
+
+
+
+Se você clicar no ícone de cadeado, sair e tentar a mesma operação novamente, receberá um erro HTTP 401 de:
+
+```JSON
+{
+ "detail": "Not authenticated"
+}
+```
+
+### Usuário inativo
+
+Agora tente com um usuário inativo, autentique-se com:
+
+User: `alice`
+
+Password: `secret2`
+
+E tente usar a operação `GET` com o caminho `/users/me`.
+
+Você receberá um erro "Usuário inativo", como:
+
+```JSON
+{
+ "detail": "Inactive user"
+}
+```
+
+## Recaptulando
+
+Agora você tem as ferramentas para implementar um sistema de segurança completo baseado em `username` e `password` para sua API.
+
+Usando essas ferramentas, você pode tornar o sistema de segurança compatível com qualquer banco de dados e com qualquer usuário ou modelo de dados.
+
+O único detalhe que falta é que ainda não é realmente "seguro".
+
+No próximo capítulo você verá como usar uma biblioteca de hashing de senha segura e tokens JWT.
diff --git a/docs/pt/docs/tutorial/sql-databases.md b/docs/pt/docs/tutorial/sql-databases.md
new file mode 100644
index 000000000..3d76a532c
--- /dev/null
+++ b/docs/pt/docs/tutorial/sql-databases.md
@@ -0,0 +1,359 @@
+# Bancos de Dados SQL (Relacionais)
+
+**FastAPI** não exige que você use um banco de dados SQL (relacional). Mas você pode usar **qualquer banco de dados** que quiser.
+
+Aqui veremos um exemplo usando SQLModel.
+
+**SQLModel** é construído sobre SQLAlchemy e Pydantic. Ele foi criado pelo mesmo autor do **FastAPI** para ser o par perfeito para aplicações **FastAPI** que precisam usar **bancos de dados SQL**.
+
+/// tip | Dica
+
+Você pode usar qualquer outra biblioteca de banco de dados SQL ou NoSQL que quiser (em alguns casos chamadas de "ORMs"), o FastAPI não obriga você a usar nada. 😎
+
+///
+
+Como o SQLModel é baseado no SQLAlchemy, você pode facilmente usar **qualquer banco de dados suportado** pelo SQLAlchemy (o que também os torna suportados pelo SQLModel), como:
+
+* PostgreSQL
+* MySQL
+* SQLite
+* Oracle
+* Microsoft SQL Server, etc.
+
+Neste exemplo, usaremos **SQLite**, porque ele usa um único arquivo e o Python tem suporte integrado. Assim, você pode copiar este exemplo e executá-lo como está.
+
+Mais tarde, para sua aplicação em produção, você pode querer usar um servidor de banco de dados como o **PostgreSQL**.
+
+/// tip | Dica
+
+Existe um gerador de projetos oficial com **FastAPI** e **PostgreSQL** incluindo um frontend e mais ferramentas: https://github.com/fastapi/full-stack-fastapi-template
+
+///
+
+Este é um tutorial muito simples e curto, se você quiser aprender sobre bancos de dados em geral, sobre SQL ou recursos mais avançados, acesse a documentação do SQLModel.
+
+## Instalar o `SQLModel`
+
+Primeiro, certifique-se de criar seu [ambiente virtual](../virtual-environments.md){.internal-link target=_blank}, ativá-lo e, em seguida, instalar o `sqlmodel`:
+
+
+
+
+
+Вы можете набирать сообщения в поле ввода и отправлять их:
+
+
+
+И ваше **FastAPI** приложение с веб-сокетами ответит:
+
+
+
+Вы можете отправлять и получать множество сообщений:
+
+
+
+И все они будут использовать одно и то же веб-сокет соединение.
+
+## Использование `Depends` и не только
+
+Вы можете импортировать из `fastapi` и использовать в эндпоинте вебсокета:
+
+* `Depends`
+* `Security`
+* `Cookie`
+* `Header`
+* `Path`
+* `Query`
+
+Они работают так же, как и в других FastAPI эндпоинтах/*операциях пути*:
+
+{* ../../docs_src/websockets/tutorial002_an_py310.py hl[68:69,82] *}
+
+/// info | Примечание
+
+В веб-сокете вызывать `HTTPException` не имеет смысла. Вместо этого нужно использовать `WebSocketException`.
+
+Закрывающий статус код можно использовать из valid codes defined in the specification.
+
+///
+
+### Веб-сокеты с зависимостями: проверка в действии
+
+Если ваш файл называется `main.py`, то запустите приложение командой:
+
+
+
+## Обработка отключений и работа с несколькими клиентами
+
+Если веб-сокет соединение закрыто, то `await websocket.receive_text()` вызовет исключение `WebSocketDisconnect`, которое можно поймать и обработать как в этом примере:
+
+{* ../../docs_src/websockets/tutorial003_py39.py hl[79:81] *}
+
+Чтобы воспроизвести пример:
+
+* Откройте приложение в нескольких вкладках браузера.
+* Отправьте из них сообщения.
+* Затем закройте одну из вкладок.
+
+Это вызовет исключение `WebSocketDisconnect`, и все остальные клиенты получат следующее сообщение:
+
+```
+Client #1596980209979 left the chat
+```
+
+/// tip | Примечание
+
+Приложение выше - это всего лишь простой минимальный пример, демонстрирующий обработку и передачу сообщений нескольким веб-сокет соединениям.
+
+Но имейте в виду, что это будет работать только в одном процессе и только пока он активен, так как всё обрабатывается в простом списке в оперативной памяти.
+
+Если нужно что-то легко интегрируемое с FastAPI, но более надежное и с поддержкой Redis, PostgreSQL или другого, то можно воспользоваться encode/broadcaster.
+
+///
+
+## Дополнительная информация
+
+Для более глубокого изучения темы воспользуйтесь документацией Starlette:
+
+* The `WebSocket` class.
+* Class-based WebSocket handling.
diff --git a/docs/ru/docs/alternatives.md b/docs/ru/docs/alternatives.md
index 24a45fa55..3c5147e79 100644
--- a/docs/ru/docs/alternatives.md
+++ b/docs/ru/docs/alternatives.md
@@ -33,12 +33,18 @@ DRF использовался многими компаниями, включа
Это был один из первых примеров **автоматического документирования API** и это была одна из первых идей, вдохновивших на создание **FastAPI**.
-!!! note "Заметка"
- Django REST Framework был создан Tom Christie.
- Он же создал Starlette и Uvicorn, на которых основан **FastAPI**.
+/// note | Заметка
-!!! check "Идея для **FastAPI**"
- Должно быть автоматическое создание документации API с пользовательским веб-интерфейсом.
+Django REST Framework был создан Tom Christie.
+Он же создал Starlette и Uvicorn, на которых основан **FastAPI**.
+
+///
+
+/// check | Идея для **FastAPI**
+
+Должно быть автоматическое создание документации API с пользовательским веб-интерфейсом.
+
+///
### Flask
@@ -56,11 +62,13 @@ Flask часто используется и для приложений, кот
Простота Flask, показалась мне подходящей для создания API.
Но ещё нужно было найти "Django REST Framework" для Flask.
-!!! check "Идеи для **FastAPI**"
- Это будет микрофреймворк. К нему легко будет добавить необходимые инструменты и части.
+/// check | Идеи для **FastAPI**
- Должна быть простая и лёгкая в использовании система маршрутизации запросов.
+Это будет микрофреймворк. К нему легко будет добавить необходимые инструменты и части.
+Должна быть простая и лёгкая в использовании система маршрутизации запросов.
+
+///
### Requests
@@ -100,11 +108,13 @@ def read_url():
Глядите, как похоже `requests.get(...)` и `@app.get(...)`.
-!!! check "Идеи для **FastAPI**"
- * Должен быть простой и понятный API.
- * Нужно использовать названия HTTP-методов (операций) для упрощения понимания происходящего.
- * Должны быть разумные настройки по умолчанию и широкие возможности их кастомизации.
+/// check | Идеи для **FastAPI**
+* Должен быть простой и понятный API.
+* Нужно использовать названия HTTP-методов (операций) для упрощения понимания происходящего.
+* Должны быть разумные настройки по умолчанию и широкие возможности их кастомизации.
+
+///
### Swagger / OpenAPI
@@ -119,16 +129,19 @@ def read_url():
Вот почему, когда говорят о версии 2.0, обычно говорят "Swagger", а для версии 3+ "OpenAPI".
-!!! check "Идеи для **FastAPI**"
- Использовать открытые стандарты для спецификаций API вместо самодельных схем.
+/// check | Идеи для **FastAPI**
- Совместимость с основанными на стандартах пользовательскими интерфейсами:
+Использовать открытые стандарты для спецификаций API вместо самодельных схем.
- * Swagger UI
- * ReDoc
+Совместимость с основанными на стандартах пользовательскими интерфейсами:
- Они были выбраны за популярность и стабильность.
- Но сделав беглый поиск, Вы можете найти десятки альтернативных пользовательских интерфейсов для OpenAPI, которые Вы можете использовать с **FastAPI**.
+* Swagger UI
+* ReDoc
+
+Они были выбраны за популярность и стабильность.
+Но сделав беглый поиск, Вы можете найти десятки альтернативных пользовательских интерфейсов для OpenAPI, которые Вы можете использовать с **FastAPI**.
+
+///
### REST фреймворки для Flask
@@ -152,8 +165,11 @@ def read_url():
Итак, чтобы определить каждую схему,
Вам нужно использовать определенные утилиты и классы, предоставляемые Marshmallow.
-!!! check "Идея для **FastAPI**"
- Использовать код программы для автоматического создания "схем", определяющих типы данных и их проверку.
+/// check | Идея для **FastAPI**
+
+Использовать код программы для автоматического создания "схем", определяющих типы данных и их проверку.
+
+///
### Webargs
@@ -165,11 +181,17 @@ Webargs - это инструмент, который был создан для
Это превосходный инструмент и я тоже часто пользовался им до **FastAPI**.
-!!! info "Информация"
- Webargs бы создан разработчиками Marshmallow.
+/// info | Информация
-!!! check "Идея для **FastAPI**"
- Должна быть автоматическая проверка входных данных.
+Webargs бы создан разработчиками Marshmallow.
+
+///
+
+/// check | Идея для **FastAPI**
+
+Должна быть автоматическая проверка входных данных.
+
+///
### APISpec
@@ -190,11 +212,17 @@ Marshmallow и Webargs осуществляют проверку, анализ
Редактор кода не особо может помочь в такой парадигме.
А изменив какие-то параметры или схемы для Marshmallow можно забыть отредактировать докстринг с YAML и сгенерированная схема становится недействительной.
-!!! info "Информация"
- APISpec тоже был создан авторами Marshmallow.
+/// info | Информация
-!!! check "Идея для **FastAPI**"
- Необходима поддержка открытого стандарта для API - OpenAPI.
+APISpec тоже был создан авторами Marshmallow.
+
+///
+
+/// check | Идея для **FastAPI**
+
+Необходима поддержка открытого стандарта для API - OpenAPI.
+
+///
### Flask-apispec
@@ -218,11 +246,17 @@ Marshmallow и Webargs осуществляют проверку, анализ
Эти генераторы проектов также стали основой для [Генераторов проектов с **FastAPI**](project-generation.md){.internal-link target=_blank}.
-!!! info "Информация"
- Как ни странно, но Flask-apispec тоже создан авторами Marshmallow.
+/// info | Информация
-!!! check "Идея для **FastAPI**"
- Схема OpenAPI должна создаваться автоматически и использовать тот же код, который осуществляет сериализацию и проверку данных.
+Как ни странно, но Flask-apispec тоже создан авторами Marshmallow.
+
+///
+
+/// check | Идея для **FastAPI**
+
+Схема OpenAPI должна создаваться автоматически и использовать тот же код, который осуществляет сериализацию и проверку данных.
+
+///
### NestJS (и Angular)
@@ -242,25 +276,34 @@ Marshmallow и Webargs осуществляют проверку, анализ
Кроме того, он не очень хорошо справляется с вложенными моделями.
Если в запросе имеется объект JSON, внутренние поля которого, в свою очередь, являются вложенными объектами JSON, это не может быть должным образом задокументировано и проверено.
-!!! check "Идеи для **FastAPI** "
- Нужно использовать подсказки типов, чтоб воспользоваться поддержкой редактора кода.
+/// check | Идеи для **FastAPI**
- Нужна мощная система внедрения зависимостей. Необходим способ для уменьшения повторов кода.
+Нужно использовать подсказки типов, чтоб воспользоваться поддержкой редактора кода.
+
+Нужна мощная система внедрения зависимостей. Необходим способ для уменьшения повторов кода.
+
+///
### Sanic
Sanic был одним из первых чрезвычайно быстрых Python-фреймворков основанных на `asyncio`.
Он был сделан очень похожим на Flask.
-!!! note "Технические детали"
- В нём использован `uvloop` вместо стандартного цикла событий `asyncio`, что и сделало его таким быстрым.
+/// note | Технические детали
- Он явно вдохновил создателей Uvicorn и Starlette, которые в настоящее время быстрее Sanic в открытых бенчмарках.
+В нём использован `uvloop` вместо стандартного цикла событий `asyncio`, что и сделало его таким быстрым.
-!!! check "Идеи для **FastAPI**"
- Должна быть сумасшедшая производительность.
+Он явно вдохновил создателей Uvicorn и Starlette, которые в настоящее время быстрее Sanic в открытых бенчмарках.
- Для этого **FastAPI** основан на Starlette, самом быстром из доступных фреймворков (по замерам незаинтересованных лиц).
+///
+
+/// check | Идеи для **FastAPI**
+
+Должна быть сумасшедшая производительность.
+
+Для этого **FastAPI** основан на Starlette, самом быстром из доступных фреймворков (по замерам незаинтересованных лиц).
+
+///
### Falcon
@@ -275,12 +318,15 @@ Falcon - ещё один высокопроизводительный Python-ф
Либо эти функции должны быть встроены во фреймворк, сконструированный поверх Falcon, как в Hug.
Такая же особенность присутствует и в других фреймворках, вдохновлённых идеей Falcon, использовать только один объект запроса и один объект ответа.
-!!! check "Идея для **FastAPI**"
- Найдите способы добиться отличной производительности.
+/// check | Идея для **FastAPI**
- Объявлять параметры `ответа сервера` в функциях, как в Hug.
+Найдите способы добиться отличной производительности.
- Хотя в FastAPI это необязательно и используется в основном для установки заголовков, куки и альтернативных кодов состояния.
+Объявлять параметры `ответа сервера` в функциях, как в Hug.
+
+Хотя в FastAPI это необязательно и используется в основном для установки заголовков, куки и альтернативных кодов состояния.
+
+///
### Molten
@@ -302,13 +348,16 @@ Molten мне попался на начальной стадии написан
Это больше похоже на Django, чем на Flask и Starlette.
Он разделяет в коде вещи, которые довольно тесно связаны.
-!!! check "Идея для **FastAPI**"
- Определить дополнительные проверки типов данных, используя значения атрибутов модели "по умолчанию".
- Это улучшает помощь редактора и раньше это не было доступно в Pydantic.
+/// check | Идея для **FastAPI**
- Фактически это подтолкнуло на обновление Pydantic для поддержки одинакового стиля проверок (теперь этот функционал уже доступен в Pydantic).
+Определить дополнительные проверки типов данных, используя значения атрибутов модели "по умолчанию".
+Это улучшает помощь редактора и раньше это не было доступно в Pydantic.
-### Hug
+Фактически это подтолкнуло на обновление Pydantic для поддержки одинакового стиля проверок (теперь этот функционал уже доступен в Pydantic).
+
+///
+
+### Hug
Hug был одним из первых фреймворков, реализовавших объявление параметров API с использованием подсказок типов Python.
Эта отличная идея была использована и другими инструментами.
@@ -325,15 +374,21 @@ Hug был одним из первых фреймворков, реализов
Поскольку он основан на WSGI, старом стандарте для синхронных веб-фреймворков, он не может работать с веб-сокетами и другими модными штуками, но всё равно обладает высокой производительностью.
-!!! info "Информация"
- Hug создан Timothy Crosley, автором `isort`, отличного инструмента для автоматической сортировки импортов в Python-файлах.
+/// info | Информация
-!!! check "Идеи для **FastAPI**"
- Hug повлиял на создание некоторых частей APIStar и был одним из инструментов, которые я счел наиболее многообещающими, наряду с APIStar.
+Hug создан Timothy Crosley, автором `isort`, отличного инструмента для автоматической сортировки импортов в Python-файлах.
- Hug натолкнул на мысли использовать в **FastAPI** подсказки типов Python для автоматического создания схемы, определяющей API и его параметры.
+///
- Hug вдохновил **FastAPI** объявить параметр `ответа` в функциях для установки заголовков и куки.
+/// check | Идеи для **FastAPI**
+
+Hug повлиял на создание некоторых частей APIStar и был одним из инструментов, которые я счел наиболее многообещающими, наряду с APIStar.
+
+Hug натолкнул на мысли использовать в **FastAPI** подсказки типов Python для автоматического создания схемы, определяющей API и его параметры.
+
+Hug вдохновил **FastAPI** объявить параметр `ответа` в функциях для установки заголовков и куки.
+
+///
### APIStar (<= 0.5)
@@ -363,24 +418,30 @@ Hug был одним из первых фреймворков, реализов
Ныне APIStar - это набор инструментов для проверки спецификаций OpenAPI.
-!!! info "Информация"
- APIStar был создан Tom Christie. Тот самый парень, который создал:
+/// info | Информация
- * Django REST Framework
- * Starlette (на котором основан **FastAPI**)
- * Uvicorn (используемый в Starlette и **FastAPI**)
+APIStar был создан Tom Christie. Тот самый парень, который создал:
-!!! check "Идеи для **FastAPI**"
- Воплощение.
+* Django REST Framework
+* Starlette (на котором основан **FastAPI**)
+* Uvicorn (используемый в Starlette и **FastAPI**)
- Мне казалось блестящей идеей объявлять множество функций (проверка данных, сериализация, документация) с помощью одних и тех же типов Python, которые при этом обеспечивают ещё и помощь редактора кода.
+///
- После долгих поисков среди похожих друг на друга фреймворков и сравнения их различий, APIStar стал самым лучшим выбором.
+/// check | Идеи для **FastAPI**
- Но APIStar перестал быть фреймворком для создания веб-сервера, зато появился Starlette, новая и лучшая основа для построения подобных систем.
- Это была последняя капля, сподвигнувшая на создание **FastAPI**.
+Воплощение.
- Я считаю **FastAPI** "духовным преемником" APIStar, улучившим его возможности благодаря урокам, извлечённым из всех упомянутых выше инструментов.
+Мне казалось блестящей идеей объявлять множество функций (проверка данных, сериализация, документация) с помощью одних и тех же типов Python, которые при этом обеспечивают ещё и помощь редактора кода.
+
+После долгих поисков среди похожих друг на друга фреймворков и сравнения их различий, APIStar стал самым лучшим выбором.
+
+Но APIStar перестал быть фреймворком для создания веб-сервера, зато появился Starlette, новая и лучшая основа для построения подобных систем.
+Это была последняя капля, сподвигнувшая на создание **FastAPI**.
+
+Я считаю **FastAPI** "духовным преемником" APIStar, улучившим его возможности благодаря урокам, извлечённым из всех упомянутых выше инструментов.
+
+///
## Что используется в **FastAPI**
@@ -391,10 +452,13 @@ Pydantic - это библиотека для валидации данных,
Его можно сравнить с Marshmallow, хотя в бенчмарках Pydantic быстрее, чем Marshmallow.
И он основан на тех же подсказках типов, которые отлично поддерживаются редакторами кода.
-!!! check "**FastAPI** использует Pydantic"
- Для проверки данных, сериализации данных и автоматической документации моделей (на основе JSON Schema).
+/// check | **FastAPI** использует Pydantic
- Затем **FastAPI** берёт эти схемы JSON и помещает их в схему OpenAPI, не касаясь других вещей, которые он делает.
+Для проверки данных, сериализации данных и автоматической документации моделей (на основе JSON Schema).
+
+Затем **FastAPI** берёт эти схемы JSON и помещает их в схему OpenAPI, не касаясь других вещей, которые он делает.
+
+///
### Starlette
@@ -424,19 +488,25 @@ Starlette обеспечивает весь функционал микрофр
**FastAPI** добавляет эти функции используя подсказки типов Python и Pydantic.
Ещё **FastAPI** добавляет систему внедрения зависимостей, утилиты безопасности, генерацию схемы OpenAPI и т.д.
-!!! note "Технические детали"
- ASGI - это новый "стандарт" разработанный участниками команды Django.
- Он пока что не является "стандартом в Python" (то есть принятым PEP), но процесс принятия запущен.
+/// note | Технические детали
- Тем не менее он уже используется в качестве "стандарта" несколькими инструментами.
- Это значительно улучшает совместимость, поскольку Вы можете переключиться с Uvicorn на любой другой ASGI-сервер (например, Daphne или Hypercorn) или Вы можете добавить ASGI-совместимые инструменты, такие как `python-socketio`.
+ASGI - это новый "стандарт" разработанный участниками команды Django.
+Он пока что не является "стандартом в Python" (то есть принятым PEP), но процесс принятия запущен.
-!!! check "**FastAPI** использует Starlette"
- В качестве ядра веб-сервиса для обработки запросов, добавив некоторые функции сверху.
+Тем не менее он уже используется в качестве "стандарта" несколькими инструментами.
+Это значительно улучшает совместимость, поскольку Вы можете переключиться с Uvicorn на любой другой ASGI-сервер (например, Daphne или Hypercorn) или Вы можете добавить ASGI-совместимые инструменты, такие как `python-socketio`.
- Класс `FastAPI` наследуется напрямую от класса `Starlette`.
+///
- Таким образом, всё что Вы могли делать со Starlette, Вы можете делать с **FastAPI**, по сути это прокачанный Starlette.
+/// check | **FastAPI** использует Starlette
+
+В качестве ядра веб-сервиса для обработки запросов, добавив некоторые функции сверху.
+
+Класс `FastAPI` наследуется напрямую от класса `Starlette`.
+
+Таким образом, всё что Вы могли делать со Starlette, Вы можете делать с **FastAPI**, по сути это прокачанный Starlette.
+
+///
### Uvicorn
@@ -448,12 +518,15 @@ Uvicorn является сервером, а не фреймворком.
Он рекомендуется в качестве сервера для Starlette и **FastAPI**.
-!!! check "**FastAPI** рекомендует его"
- Как основной сервер для запуска приложения **FastAPI**.
+/// check | **FastAPI** рекомендует его
- Вы можете объединить его с Gunicorn, чтобы иметь асинхронный многопроцессный сервер.
+Как основной сервер для запуска приложения **FastAPI**.
- Узнать больше деталей можно в разделе [Развёртывание](deployment/index.md){.internal-link target=_blank}.
+Вы можете объединить его с Gunicorn, чтобы иметь асинхронный многопроцессный сервер.
+
+Узнать больше деталей можно в разделе [Развёртывание](deployment/index.md){.internal-link target=_blank}.
+
+///
## Тестовые замеры и скорость
diff --git a/docs/ru/docs/async.md b/docs/ru/docs/async.md
index 20dbb108b..6c5d982df 100644
--- a/docs/ru/docs/async.md
+++ b/docs/ru/docs/async.md
@@ -21,8 +21,11 @@ async def read_results():
return results
```
-!!! note
- `await` можно использовать только внутри функций, объявленных с использованием `async def`.
+/// note
+
+`await` можно использовать только внутри функций, объявленных с использованием `async def`.
+
+///
---
@@ -444,14 +447,17 @@ Starlette (и **FastAPI**) основаны на
-
-```console
-$ python -m venv env
-```
-
-
-
-Эта команда создаст директорию `./env/` с бинарными (двоичными) файлами Python, а затем Вы сможете скачивать и устанавливать необходимые библиотеки в изолированное виртуальное окружение.
-
-### Активация виртуального окружения
-
-Активируйте виртуально окружение командой:
-
-=== "Linux, macOS"
-
-
-
+
-
-
+
+
@@ -93,7 +93,7 @@ FastAPI — это современный, быстрый (высокопрои
"_Честно говоря, то, что вы создали, выглядит очень солидно и отполировано. Во многих смыслах я хотел, чтобы **Hug** был именно таким — это действительно вдохновляет, когда кто-то создаёт такое._"
-
+
---
@@ -443,7 +443,7 @@ item: Item
Используется Pydantic:
-*
email_validator - для проверки электронной почты.
+* email-validator - для проверки электронной почты.
Используется Starlette:
diff --git a/docs/ru/docs/python-types.md b/docs/ru/docs/python-types.md
index 3c8492c67..b1d4715fd 100644
--- a/docs/ru/docs/python-types.md
+++ b/docs/ru/docs/python-types.md
@@ -12,16 +12,18 @@ Python имеет поддержку необязательных аннотац
Но даже если вы никогда не используете **FastAPI**, вам будет полезно немного узнать о них.
-!!! note
- Если вы являетесь экспертом в Python и уже знаете всё об аннотациях типов, переходите к следующему разделу.
+/// note
+
+Если вы являетесь экспертом в Python и уже знаете всё об аннотациях типов, переходите к следующему разделу.
+
+///
## Мотивация
Давайте начнем с простого примера:
-```Python
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py *}
+
Вызов этой программы выводит:
@@ -35,9 +37,8 @@ John Doe
* Преобразует первую букву содержимого каждой переменной в верхний регистр с `title()`.
* Соединяет их через пробел.
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py hl[2] *}
+
### Отредактируем пример
@@ -79,9 +80,8 @@ John Doe
Это аннотации типов:
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial002.py!}
-```
+{* ../../docs_src/python_types/tutorial002.py hl[1] *}
+
Это не то же самое, что объявление значений по умолчанию, например:
@@ -109,9 +109,8 @@ John Doe
Проверьте эту функцию, она уже имеет аннотации типов:
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial003.py!}
-```
+{* ../../docs_src/python_types/tutorial003.py hl[1] *}
+
Поскольку редактор знает типы переменных, вы получаете не только дополнение, но и проверки ошибок:
@@ -119,9 +118,8 @@ John Doe
Теперь вы знаете, что вам нужно исправить, преобразовав `age` в строку с `str(age)`:
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial004.py!}
-```
+{* ../../docs_src/python_types/tutorial004.py hl[2] *}
+
## Объявление типов
@@ -140,9 +138,8 @@ John Doe
* `bool`
* `bytes`
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial005.py!}
-```
+{* ../../docs_src/python_types/tutorial005.py hl[1] *}
+
### Generic-типы с параметрами типов
@@ -158,9 +155,8 @@ John Doe
Импортируйте `List` из `typing` (с заглавной `L`):
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial006.py!}
-```
+{* ../../docs_src/python_types/tutorial006.py hl[1] *}
+
Объявите переменную с тем же синтаксисом двоеточия (`:`).
@@ -168,14 +164,16 @@ John Doe
Поскольку список является типом, содержащим некоторые внутренние типы, вы помещаете их в квадратные скобки:
-```Python hl_lines="4"
-{!../../../docs_src/python_types/tutorial006.py!}
-```
+{* ../../docs_src/python_types/tutorial006.py hl[4] *}
-!!! tip
- Эти внутренние типы в квадратных скобках называются «параметрами типов».
- В этом случае `str` является параметром типа, передаваемым в `List`.
+/// tip
+
+Эти внутренние типы в квадратных скобках называются «параметрами типов».
+
+В этом случае `str` является параметром типа, передаваемым в `List`.
+
+///
Это означает: "переменная `items` является `list`, и каждый из элементов этого списка является `str`".
@@ -193,9 +191,8 @@ John Doe
Вы бы сделали то же самое, чтобы объявить `tuple` и `set`:
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial007.py!}
-```
+{* ../../docs_src/python_types/tutorial007.py hl[1,4] *}
+
Это означает:
@@ -210,9 +207,8 @@ John Doe
Второй параметр типа предназначен для значений `dict`:
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial008.py!}
-```
+{* ../../docs_src/python_types/tutorial008.py hl[1,4] *}
+
Это означает:
@@ -225,7 +221,7 @@ John Doe
Вы также можете использовать `Optional`, чтобы объявить, что переменная имеет тип, например, `str`, но это является «необязательным», что означает, что она также может быть `None`:
```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial009.py!}
+{!../../docs_src/python_types/tutorial009.py!}
```
Использование `Optional[str]` вместо просто `str` позволит редактору помочь вам в обнаружении ошибок, в которых вы могли бы предположить, что значение всегда является `str`, хотя на самом деле это может быть и `None`.
@@ -249,15 +245,13 @@ John Doe
Допустим, у вас есть класс `Person` с полем `name`:
-```Python hl_lines="1-3"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
+
Тогда вы можете объявить переменную типа `Person`:
-```Python hl_lines="6"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[6] *}
+
И снова вы получаете полную поддержку редактора:
@@ -277,12 +271,14 @@ John Doe
Взято из официальной документации Pydantic:
-```Python
-{!../../../docs_src/python_types/tutorial011.py!}
-```
+{* ../../docs_src/python_types/tutorial011.py *}
-!!! info
- Чтобы узнать больше о Pydantic, читайте его документацию.
+
+/// info
+
+Чтобы узнать больше о Pydantic, читайте его документацию.
+
+///
**FastAPI** целиком основан на Pydantic.
@@ -310,5 +306,8 @@ John Doe
Важно то, что при использовании стандартных типов Python в одном месте (вместо добавления дополнительных классов, декораторов и т.д.) **FastAPI** сделает за вас большую часть работы.
-!!! info
- Если вы уже прошли всё руководство и вернулись, чтобы узнать больше о типах, хорошим ресурсом является «шпаргалка» от `mypy`.
+/// info
+
+Если вы уже прошли всё руководство и вернулись, чтобы узнать больше о типах, хорошим ресурсом является «шпаргалка» от `mypy`.
+
+///
diff --git a/docs/ru/docs/tutorial/background-tasks.md b/docs/ru/docs/tutorial/background-tasks.md
index 73ba860bc..bf2e9dec3 100644
--- a/docs/ru/docs/tutorial/background-tasks.md
+++ b/docs/ru/docs/tutorial/background-tasks.md
@@ -15,9 +15,7 @@
Сначала импортируйте `BackgroundTasks`, потом добавьте в функцию параметр с типом `BackgroundTasks`:
-```Python hl_lines="1 13"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *}
**FastAPI** создаст объект класса `BackgroundTasks` для вас и запишет его в параметр.
@@ -33,17 +31,13 @@
Так как операция записи не использует `async` и `await`, мы определим ее как обычную `def`:
-```Python hl_lines="6-9"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *}
## Добавление фоновой задачи
Внутри функции вызовите метод `.add_task()` у объекта *background tasks* и передайте ему функцию, которую хотите выполнить в фоне:
-```Python hl_lines="14"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[14] *}
`.add_task()` принимает следующие аргументы:
@@ -57,17 +51,7 @@
**FastAPI** знает, что нужно сделать в каждом случае и как переиспользовать тот же объект `BackgroundTasks`, так чтобы все фоновые задачи собрались и запустились вместе в фоне:
-=== "Python 3.10+"
-
- ```Python hl_lines="11 13 20 23"
- {!> ../../../docs_src/background_tasks/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="13 15 22 25"
- {!> ../../../docs_src/background_tasks/tutorial002.py!}
- ```
+{* ../../docs_src/background_tasks/tutorial002_py310.py hl[11,13,20,23] *}
В этом примере сообщения будут записаны в `log.txt` *после* того, как ответ сервера был отправлен.
@@ -93,8 +77,6 @@
Их тяжелее настраивать, также им нужен брокер сообщений наподобие RabbitMQ или Redis, но зато они позволяют вам запускать фоновые задачи в нескольких процессах и даже на нескольких серверах.
-Для примера, посмотрите [Project Generators](../project-generation.md){.internal-link target=_blank}, там есть проект с уже настроенным Celery.
-
Но если вам нужен доступ к общим переменным и объектам вашего **FastAPI** приложения или вам нужно выполнять простые фоновые задачи (наподобие отправки письма из примера) вы можете просто использовать `BackgroundTasks`.
## Резюме
diff --git a/docs/ru/docs/tutorial/bigger-applications.md b/docs/ru/docs/tutorial/bigger-applications.md
new file mode 100644
index 000000000..8b9080d39
--- /dev/null
+++ b/docs/ru/docs/tutorial/bigger-applications.md
@@ -0,0 +1,556 @@
+# Большие приложения, в которых много файлов
+
+При построении приложения или веб-API нам редко удается поместить всё в один файл.
+
+**FastAPI** предоставляет удобный инструментарий, который позволяет нам структурировать приложение, сохраняя при этом всю необходимую гибкость.
+
+/// info | Примечание
+
+Если вы раньше использовали Flask, то это аналог шаблонов Flask (Flask's Blueprints).
+
+///
+
+## Пример структуры приложения
+
+Давайте предположим, что наше приложение имеет следующую структуру:
+
+```
+.
+├── app
+│ ├── __init__.py
+│ ├── main.py
+│ ├── dependencies.py
+│ └── routers
+│ │ ├── __init__.py
+│ │ ├── items.py
+│ │ └── users.py
+│ └── internal
+│ ├── __init__.py
+│ └── admin.py
+```
+
+/// tip | Подсказка
+
+Обратите внимание, что в каждом каталоге и подкаталоге имеется файл `__init__.py`
+
+Это как раз то, что позволяет импортировать код из одного файла в другой.
+
+Например, в файле `app/main.py` может быть следующая строка:
+
+```
+from app.routers import items
+```
+
+///
+
+* Всё помещается в каталоге `app`. В нём также находится пустой файл `app/__init__.py`. Таким образом, `app` является "Python-пакетом" (коллекцией модулей Python).
+* Он содержит файл `app/main.py`. Данный файл является частью пакета (т.е. находится внутри каталога, содержащего файл `__init__.py`), и, соответственно, он является модулем пакета: `app.main`.
+* Он также содержит файл `app/dependencies.py`, который также, как и `app/main.py`, является модулем: `app.dependencies`.
+* Здесь также находится подкаталог `app/routers/`, содержащий `__init__.py`. Он является суб-пакетом: `app.routers`.
+* Файл `app/routers/items.py` находится внутри пакета `app/routers/`. Таким образом, он является суб-модулем: `app.routers.items`.
+* Точно также `app/routers/users.py` является ещё одним суб-модулем: `app.routers.users`.
+* Подкаталог `app/internal/`, содержащий файл `__init__.py`, является ещё одним суб-пакетом: `app.internal`.
+* А файл `app/internal/admin.py` является ещё одним суб-модулем: `app.internal.admin`.
+
+
+
+Та же самая файловая структура приложения, но с комментариями:
+
+```
+.
+├── app # "app" пакет
+│ ├── __init__.py # этот файл превращает "app" в "Python-пакет"
+│ ├── main.py # модуль "main", напр.: import app.main
+│ ├── dependencies.py # модуль "dependencies", напр.: import app.dependencies
+│ └── routers # суб-пакет "routers"
+│ │ ├── __init__.py # превращает "routers" в суб-пакет
+│ │ ├── items.py # суб-модуль "items", напр.: import app.routers.items
+│ │ └── users.py # суб-модуль "users", напр.: import app.routers.users
+│ └── internal # суб-пакет "internal"
+│ ├── __init__.py # превращает "internal" в суб-пакет
+│ └── admin.py # суб-модуль "admin", напр.: import app.internal.admin
+```
+
+## `APIRouter`
+
+Давайте предположим, что для работы с пользователями используется отдельный файл (суб-модуль) `/app/routers/users.py`.
+
+Для лучшей организации приложения, вы хотите отделить операции пути, связанные с пользователями, от остального кода.
+
+Но так, чтобы эти операции по-прежнему оставались частью **FastAPI** приложения/веб-API (частью одного пакета)
+
+С помощью `APIRouter` вы можете создать *операции пути* (*эндпоинты*) для данного модуля.
+
+
+### Импорт `APIRouter`
+
+Точно также, как и в случае с классом `FastAPI`, вам нужно импортировать и создать объект класса `APIRouter`.
+
+```Python hl_lines="1 3" title="app/routers/users.py"
+{!../../docs_src/bigger_applications/app/routers/users.py!}
+```
+
+### Создание *эндпоинтов* с помощью `APIRouter`
+
+В дальнейшем используйте `APIRouter` для объявления *эндпоинтов*, точно также, как вы используете класс `FastAPI`:
+
+```Python hl_lines="6 11 16" title="app/routers/users.py"
+{!../../docs_src/bigger_applications/app/routers/users.py!}
+```
+
+Вы можете думать об `APIRouter` как об "уменьшенной версии" класса FastAPI`.
+
+`APIRouter` поддерживает все те же самые опции.
+
+`APIRouter` поддерживает все те же самые параметры, такие как `parameters`, `responses`, `dependencies`, `tags`, и т. д.
+
+/// tip | Подсказка
+
+В данном примере, в качестве названия переменной используется `router`, но вы можете использовать любое другое имя.
+
+///
+
+Мы собираемся подключить данный `APIRouter` к нашему основному приложению на `FastAPI`, но сначала давайте проверим зависимости и создадим ещё один модуль с `APIRouter`.
+
+## Зависимости
+
+Нам понадобятся некоторые зависимости, которые мы будем использовать в разных местах нашего приложения.
+
+Мы поместим их в отдельный модуль `dependencies` (`app/dependencies.py`).
+
+Теперь мы воспользуемся простой зависимостью, чтобы прочитать кастомизированный `X-Token` из заголовка:
+
+//// tab | Python 3.9+
+
+```Python hl_lines="3 6-8" title="app/dependencies.py"
+{!> ../../docs_src/bigger_applications/app_an_py39/dependencies.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1 5-7" title="app/dependencies.py"
+{!> ../../docs_src/bigger_applications/app_an/dependencies.py!}
+```
+
+////
+
+//// tab | Python 3.8+ non-Annotated
+
+/// tip | Подсказка
+
+Мы рекомендуем использовать версию `Annotated`, когда это возможно.
+
+///
+
+```Python hl_lines="1 4-6" title="app/dependencies.py"
+{!> ../../docs_src/bigger_applications/app/dependencies.py!}
+```
+
+////
+
+/// tip | Подсказка
+
+Для простоты мы воспользовались неким воображаемым заголовоком.
+
+В реальных случаях для получения наилучших результатов используйте интегрированные утилиты обеспечения безопасности [Security utilities](security/index.md){.internal-link target=_blank}.
+
+///
+
+## Ещё один модуль с `APIRouter`
+
+Давайте также предположим, что у вас есть *эндпоинты*, отвечающие за обработку "items", и они находятся в модуле `app/routers/items.py`.
+
+У вас определены следующие *операции пути* (*эндпоинты*):
+
+* `/items/`
+* `/items/{item_id}`
+
+Тут всё точно также, как и в ситуации с `app/routers/users.py`.
+
+Но теперь мы хотим поступить немного умнее и слегка упростить код.
+
+Мы знаем, что все *эндпоинты* данного модуля имеют некоторые общие свойства:
+
+* Префикс пути: `/items`.
+* Теги: (один единственный тег: `items`).
+* Дополнительные ответы (responses)
+* Зависимости: использование созданной нами зависимости `X-token`
+
+Таким образом, вместо того чтобы добавлять все эти свойства в функцию каждого отдельного *эндпоинта*,
+мы добавим их в `APIRouter`.
+
+```Python hl_lines="5-10 16 21" title="app/routers/items.py"
+{!../../docs_src/bigger_applications/app/routers/items.py!}
+```
+
+Так как каждый *эндпоинт* начинается с символа `/`:
+
+```Python hl_lines="1"
+@router.get("/{item_id}")
+async def read_item(item_id: str):
+ ...
+```
+
+...то префикс не должен заканчиваться символом `/`.
+
+В нашем случае префиксом является `/items`.
+
+Мы также можем добавить в наш маршрутизатор (router) список `тегов` (`tags`) и дополнительных `ответов` (`responses`), которые являются общими для каждого *эндпоинта*.
+
+И ещё мы можем добавить в наш маршрутизатор список `зависимостей`, которые должны вызываться при каждом обращении к *эндпоинтам*.
+
+/// tip | Подсказка
+
+Обратите внимание, что также, как и в случае с зависимостями в декораторах *эндпоинтов* ([dependencies in *path operation decorators*](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}), никакого значения в *функцию эндпоинта* передано не будет.
+
+///
+
+В результате мы получим следующие эндпоинты:
+
+* `/items/`
+* `/items/{item_id}`
+
+...как мы и планировали.
+
+* Они будут помечены тегами из заданного списка, в нашем случае это `"items"`.
+ * Эти теги особенно полезны для системы автоматической интерактивной документации (с использованием OpenAPI).
+* Каждый из них будет включать предопределенные ответы `responses`.
+* Каждый *эндпоинт* будет иметь список зависимостей (`dependencies`), исполняемых перед вызовом *эндпоинта*.
+ * Если вы определили зависимости в самой операции пути, **то она также будет выполнена**.
+ * Сначала выполняются зависимости маршрутизатора, затем вызываются зависимости, определенные в декораторе *эндпоинта* ([`dependencies` in the decorator](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}), и, наконец, обычные параметрические зависимости.
+ * Вы также можете добавить зависимости безопасности с областями видимости (`scopes`) [`Security` dependencies with `scopes`](../advanced/security/oauth2-scopes.md){.internal-link target=_blank}.
+
+/// tip | Подсказка
+
+Например, с помощью зависимостей в `APIRouter` мы можем потребовать аутентификации для доступа ко всей группе *эндпоинтов*, не указывая зависимости для каждой отдельной функции *эндпоинта*.
+
+///
+
+/// check | Заметка
+
+Параметры `prefix`, `tags`, `responses` и `dependencies` относятся к функционалу **FastAPI**, помогающему избежать дублирования кода.
+
+///
+
+### Импорт зависимостей
+
+Наш код находится в модуле `app.routers.items` (файл `app/routers/items.py`).
+
+И нам нужно вызвать функцию зависимости из модуля `app.dependencies` (файл `app/dependencies.py`).
+
+Мы используем операцию относительного импорта `..` для импорта зависимости:
+
+```Python hl_lines="3" title="app/routers/items.py"
+{!../../docs_src/bigger_applications/app/routers/items.py!}
+```
+
+#### Как работает относительный импорт?
+
+/// tip | Подсказка
+
+Если вы прекрасно знаете, как работает импорт в Python, то переходите к следующему разделу.
+
+///
+
+Одна точка `.`, как в данном примере:
+
+```Python
+from .dependencies import get_token_header
+```
+означает:
+
+* Начните с пакета, в котором находится данный модуль (файл `app/routers/items.py` расположен в каталоге `app/routers/`)...
+* ... найдите модуль `dependencies` (файл `app/routers/dependencies.py`)...
+* ... и импортируйте из него функцию `get_token_header`.
+
+К сожалению, такого файла не существует, и наши зависимости находятся в файле `app/dependencies.py`.
+
+Вспомните, как выглядит файловая структура нашего приложения:
+
+
+
+---
+
+Две точки `..`, как в данном примере:
+
+```Python
+from ..dependencies import get_token_header
+```
+
+означают:
+
+* Начните с пакета, в котором находится данный модуль (файл `app/routers/items.py` находится в каталоге `app/routers/`)...
+* ... перейдите в родительский пакет (каталог `app/`)...
+* ... найдите в нём модуль `dependencies` (файл `app/dependencies.py`)...
+* ... и импортируйте из него функцию `get_token_header`.
+
+Это работает верно! 🎉
+
+---
+
+Аналогично, если бы мы использовали три точки `...`, как здесь:
+
+```Python
+from ...dependencies import get_token_header
+```
+
+то это бы означало:
+
+* Начните с пакета, в котором находится данный модуль (файл `app/routers/items.py` находится в каталоге `app/routers/`)...
+* ... перейдите в родительский пакет (каталог `app/`)...
+* ... затем перейдите в родительский пакет текущего пакета (такого пакета не существует, `app` находится на самом верхнем уровне 😱)...
+* ... найдите в нём модуль `dependencies` (файл `app/dependencies.py`)...
+* ... и импортируйте из него функцию `get_token_header`.
+
+Это будет относиться к некоторому пакету, находящемуся на один уровень выше чем `app/` и содержащему свой собственный файл `__init__.py`. Но ничего такого у нас нет. Поэтому это приведет к ошибке в нашем примере. 🚨
+
+Теперь вы знаете, как работает импорт в Python, и сможете использовать относительное импортирование в своих собственных приложениях любого уровня сложности. 🤓
+
+### Добавление пользовательских тегов (`tags`), ответов (`responses`) и зависимостей (`dependencies`)
+
+Мы не будем добавлять префикс `/items` и список тегов `tags=["items"]` для каждого *эндпоинта*, т.к. мы уже их добавили с помощью `APIRouter`.
+
+Но помимо этого мы можем добавить новые теги для каждого отдельного *эндпоинта*, а также некоторые дополнительные ответы (`responses`), характерные для данного *эндпоинта*:
+
+```Python hl_lines="30-31" title="app/routers/items.py"
+{!../../docs_src/bigger_applications/app/routers/items.py!}
+```
+
+/// tip | Подсказка
+
+Последний *эндпоинт* будет иметь следующую комбинацию тегов: `["items", "custom"]`.
+
+А также в его документации будут содержаться оба ответа: один для `404` и другой для `403`.
+
+///
+
+## Модуль main в `FastAPI`
+
+Теперь давайте посмотрим на модуль `app/main.py`.
+
+Именно сюда вы импортируете и именно здесь вы используете класс `FastAPI`.
+
+Это основной файл вашего приложения, который объединяет всё в одно целое.
+
+И теперь, когда большая часть логики приложения разделена на отдельные модули, основной файл `app/main.py` будет достаточно простым.
+
+### Импорт `FastAPI`
+
+Вы импортируете и создаете класс `FastAPI` как обычно.
+
+Мы даже можем объявить глобальные зависимости [global dependencies](dependencies/global-dependencies.md){.internal-link target=_blank}, которые будут объединены с зависимостями для каждого отдельного маршрутизатора:
+
+```Python hl_lines="1 3 7" title="app/main.py"
+{!../../docs_src/bigger_applications/app/main.py!}
+```
+
+### Импорт `APIRouter`
+
+Теперь мы импортируем другие суб-модули, содержащие `APIRouter`:
+
+```Python hl_lines="4-5" title="app/main.py"
+{!../../docs_src/bigger_applications/app/main.py!}
+```
+
+Так как файлы `app/routers/users.py` и `app/routers/items.py` являются суб-модулями одного и того же Python-пакета `app`, то мы сможем их импортировать, воспользовавшись операцией относительного импорта `.`.
+
+### Как работает импорт?
+
+Данная строка кода:
+
+```Python
+from .routers import items, users
+```
+
+означает:
+
+* Начните с пакета, в котором содержится данный модуль (файл `app/main.py` содержится в каталоге `app/`)...
+* ... найдите суб-пакет `routers` (каталог `app/routers/`)...
+* ... и из него импортируйте суб-модули `items` (файл `app/routers/items.py`) и `users` (файл `app/routers/users.py`)...
+
+В модуле `items` содержится переменная `router` (`items.router`), та самая, которую мы создали в файле `app/routers/items.py`, она является объектом класса `APIRouter`.
+
+И затем мы сделаем то же самое для модуля `users`.
+
+Мы также могли бы импортировать и другим методом:
+
+```Python
+from app.routers import items, users
+```
+
+/// info | Примечание
+
+Первая версия является примером относительного импорта:
+
+```Python
+from .routers import items, users
+```
+
+Вторая версия является примером абсолютного импорта:
+
+```Python
+from app.routers import items, users
+```
+
+Узнать больше о пакетах и модулях в Python вы можете из официальной документации Python о модулях
+
+///
+
+### Избегайте конфликтов имен
+
+Вместо того чтобы импортировать только переменную `router`, мы импортируем непосредственно суб-модуль `items`.
+
+Мы делаем это потому, что у нас есть ещё одна переменная `router` в суб-модуле `users`.
+
+Если бы мы импортировали их одну за другой, как показано в примере:
+
+```Python
+from .routers.items import router
+from .routers.users import router
+```
+
+то переменная `router` из `users` переписал бы переменную `router` из `items`, и у нас не было бы возможности использовать их одновременно.
+
+Поэтому, для того чтобы использовать обе эти переменные в одном файле, мы импортировали соответствующие суб-модули:
+
+```Python hl_lines="5" title="app/main.py"
+{!../../docs_src/bigger_applications/app/main.py!}
+```
+
+### Подключение маршрутизаторов (`APIRouter`) для `users` и для `items`
+
+Давайте подключим маршрутизаторы (`router`) из суб-модулей `users` и `items`:
+
+```Python hl_lines="10-11" title="app/main.py"
+{!../../docs_src/bigger_applications/app/main.py!}
+```
+
+/// info | Примечание
+
+`users.router` содержит `APIRouter` из файла `app/routers/users.py`.
+
+А `items.router` содержит `APIRouter` из файла `app/routers/items.py`.
+
+///
+
+С помощью `app.include_router()` мы можем добавить каждый из маршрутизаторов (`APIRouter`) в основное приложение `FastAPI`.
+
+Он подключит все маршруты заданного маршрутизатора к нашему приложению.
+
+/// note | Технические детали
+
+Фактически, внутри он создаст все *операции пути* для каждой операции пути объявленной в `APIRouter`.
+
+И под капотом всё будет работать так, как будто бы мы имеем дело с одним файлом приложения.
+
+///
+
+/// check | Заметка
+
+При подключении маршрутизаторов не стоит беспокоиться о производительности.
+
+Операция подключения займёт микросекунды и понадобится только при запуске приложения.
+
+Таким образом, это не повлияет на производительность. ⚡
+
+///
+
+### Подключение `APIRouter` с пользовательскими префиксом (`prefix`), тегами (`tags`), ответами (`responses`), и зависимостями (`dependencies`)
+
+Теперь давайте представим, что ваша организация передала вам файл `app/internal/admin.py`.
+
+Он содержит `APIRouter` с некоторыми *эндпоитами* администрирования, которые ваша организация использует для нескольких проектов.
+
+В данном примере это сделать очень просто. Но давайте предположим, что поскольку файл используется для нескольких проектов,
+то мы не можем модифицировать его, добавляя префиксы (`prefix`), зависимости (`dependencies`), теги (`tags`), и т.д. непосредственно в `APIRouter`:
+
+```Python hl_lines="3" title="app/internal/admin.py"
+{!../../docs_src/bigger_applications/app/internal/admin.py!}
+```
+
+Но, несмотря на это, мы хотим использовать кастомный префикс (`prefix`) для подключенного маршрутизатора (`APIRouter`), в результате чего, каждая *операция пути* будет начинаться с `/admin`. Также мы хотим защитить наш маршрутизатор с помощью зависимостей, созданных для нашего проекта. И ещё мы хотим включить теги (`tags`) и ответы (`responses`).
+
+Мы можем применить все вышеперечисленные настройки, не изменяя начальный `APIRouter`. Нам всего лишь нужно передать нужные параметры в `app.include_router()`.
+
+```Python hl_lines="14-17" title="app/main.py"
+{!../../docs_src/bigger_applications/app/main.py!}
+```
+
+Таким образом, оригинальный `APIRouter` не будет модифицирован, и мы сможем использовать файл `app/internal/admin.py` сразу в нескольких проектах организации.
+
+В результате, в нашем приложении каждый *эндпоинт* модуля `admin` будет иметь:
+
+* Префикс `/admin`.
+* Тег `admin`.
+* Зависимость `get_token_header`.
+* Ответ `418`. 🍵
+
+Это будет иметь место исключительно для `APIRouter` в нашем приложении, и не затронет любой другой код, использующий его.
+
+Например, другие проекты, могут использовать тот же самый `APIRouter` с другими методами аутентификации.
+
+### Подключение отдельного *эндпоинта*
+
+Мы также можем добавить *эндпоинт* непосредственно в основное приложение `FastAPI`.
+
+Здесь мы это делаем ... просто, чтобы показать, что это возможно 🤷:
+
+```Python hl_lines="21-23" title="app/main.py"
+{!../../docs_src/bigger_applications/app/main.py!}
+```
+
+и это будет работать корректно вместе с другими *эндпоинтами*, добавленными с помощью `app.include_router()`.
+
+/// info | Сложные технические детали
+
+**Примечание**: это сложная техническая деталь, которую, скорее всего, **вы можете пропустить**.
+
+---
+
+Маршрутизаторы (`APIRouter`) не "монтируются" по-отдельности и не изолируются от остального приложения.
+
+Это происходит потому, что нужно включить их *эндпоинты* в OpenAPI схему и в интерфейс пользователя.
+
+В силу того, что мы не можем их изолировать и "примонтировать" независимо от остальных, *эндпоинты* клонируются (пересоздаются) и не подключаются напрямую.
+
+///
+
+## Проверка автоматической документации API
+
+Теперь запустите приложение:
+
+
+
+## Подключение существующего маршрута через новый префикс (`prefix`)
+
+Вы можете использовать `.include_router()` несколько раз с одним и тем же маршрутом, применив различные префиксы.
+
+Это может быть полезным, если нужно предоставить доступ к одному и тому же API через различные префиксы, например, `/api/v1` и `/api/latest`.
+
+Это продвинутый способ, который вам может и не пригодится. Мы приводим его на случай, если вдруг вам это понадобится.
+
+## Включение одного маршрутизатора (`APIRouter`) в другой
+
+Точно так же, как вы включаете `APIRouter` в приложение `FastAPI`, вы можете включить `APIRouter` в другой `APIRouter`:
+
+```Python
+router.include_router(other_router)
+```
+
+Удостоверьтесь, что вы сделали это до того, как подключить маршрутизатор (`router`) к вашему `FastAPI` приложению, и *эндпоинты* маршрутизатора `other_router` были также подключены.
diff --git a/docs/ru/docs/tutorial/body-fields.md b/docs/ru/docs/tutorial/body-fields.md
index 02a598004..5ed5f59fc 100644
--- a/docs/ru/docs/tutorial/body-fields.md
+++ b/docs/ru/docs/tutorial/body-fields.md
@@ -6,50 +6,39 @@
Сначала вы должны импортировать его:
-=== "Python 3.10+"
+{* ../../docs_src/body_fields/tutorial001_py310.py hl[2] *}
- ```Python hl_lines="2"
- {!> ../../../docs_src/body_fields/tutorial001_py310.py!}
- ```
+/// warning | Внимание
-=== "Python 3.8+"
+Обратите внимание, что функция `Field` импортируется непосредственно из `pydantic`, а не из `fastapi`, как все остальные функции (`Query`, `Path`, `Body` и т.д.).
- ```Python hl_lines="4"
- {!> ../../../docs_src/body_fields/tutorial001.py!}
- ```
-
-!!! warning "Внимание"
- Обратите внимание, что функция `Field` импортируется непосредственно из `pydantic`, а не из `fastapi`, как все остальные функции (`Query`, `Path`, `Body` и т.д.).
+///
## Объявление атрибутов модели
Вы можете использовать функцию `Field` с атрибутами модели:
-=== "Python 3.10+"
-
- ```Python hl_lines="9-12"
- {!> ../../../docs_src/body_fields/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="11-14"
- {!> ../../../docs_src/body_fields/tutorial001.py!}
- ```
+{* ../../docs_src/body_fields/tutorial001_py310.py hl[9:12] *}
Функция `Field` работает так же, как `Query`, `Path` и `Body`, у неё такие же параметры и т.д.
-!!! note "Технические детали"
- На самом деле, `Query`, `Path` и другие функции, которые вы увидите в дальнейшем, создают объекты подклассов общего класса `Param`, который сам по себе является подклассом `FieldInfo` из Pydantic.
+/// note | Технические детали
- И `Field` (из Pydantic), и `Body`, оба возвращают объекты подкласса `FieldInfo`.
+На самом деле, `Query`, `Path` и другие функции, которые вы увидите в дальнейшем, создают объекты подклассов общего класса `Param`, который сам по себе является подклассом `FieldInfo` из Pydantic.
- У класса `Body` есть и другие подклассы, с которыми вы ознакомитесь позже.
+И `Field` (из Pydantic), и `Body`, оба возвращают объекты подкласса `FieldInfo`.
- Помните, что когда вы импортируете `Query`, `Path` и другое из `fastapi`, это фактически функции, которые возвращают специальные классы.
+У класса `Body` есть и другие подклассы, с которыми вы ознакомитесь позже.
-!!! tip "Подсказка"
- Обратите внимание, что каждый атрибут модели с типом, значением по умолчанию и `Field` имеет ту же структуру, что и параметр *функции обработки пути* с `Field` вместо `Path`, `Query` и `Body`.
+Помните, что когда вы импортируете `Query`, `Path` и другое из `fastapi`, это фактически функции, которые возвращают специальные классы.
+
+///
+
+/// tip | Подсказка
+
+Обратите внимание, что каждый атрибут модели с типом, значением по умолчанию и `Field` имеет ту же структуру, что и параметр *функции обработки пути* с `Field` вместо `Path`, `Query` и `Body`.
+
+///
## Добавление дополнительной информации
@@ -58,9 +47,12 @@
Вы узнаете больше о добавлении дополнительной информации позже в документации, когда будете изучать, как задавать примеры принимаемых данных.
-!!! warning "Внимание"
- Дополнительные ключи, переданные в функцию `Field`, также будут присутствовать в сгенерированной OpenAPI схеме вашего приложения.
- Поскольку эти ключи не являются обязательной частью спецификации OpenAPI, некоторые инструменты OpenAPI, например, [валидатор OpenAPI](https://validator.swagger.io/), могут не работать с вашей сгенерированной схемой.
+/// warning | Внимание
+
+Дополнительные ключи, переданные в функцию `Field`, также будут присутствовать в сгенерированной OpenAPI схеме вашего приложения.
+Поскольку эти ключи не являются обязательной частью спецификации OpenAPI, некоторые инструменты OpenAPI, например, [валидатор OpenAPI](https://validator.swagger.io/), могут не работать с вашей сгенерированной схемой.
+
+///
## Резюме
diff --git a/docs/ru/docs/tutorial/body-multiple-params.md b/docs/ru/docs/tutorial/body-multiple-params.md
index ffba1d0f4..9300aa1bd 100644
--- a/docs/ru/docs/tutorial/body-multiple-params.md
+++ b/docs/ru/docs/tutorial/body-multiple-params.md
@@ -8,44 +8,13 @@
Вы также можете объявить параметры тела запроса как необязательные, установив значение по умолчанию, равное `None`:
-=== "Python 3.10+"
+{* ../../docs_src/body_multiple_params/tutorial001_an_py310.py hl[18:20] *}
- ```Python hl_lines="18-20"
- {!> ../../../docs_src/body_multiple_params/tutorial001_an_py310.py!}
- ```
+/// note | Заметка
-=== "Python 3.9+"
+Заметьте, что в данном случае параметр `item`, который будет взят из тела запроса, необязателен. Так как было установлено значение `None` по умолчанию.
- ```Python hl_lines="18-20"
- {!> ../../../docs_src/body_multiple_params/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="19-21"
- {!> ../../../docs_src/body_multiple_params/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip "Заметка"
- Рекомендуется использовать `Annotated` версию, если это возможно.
-
- ```Python hl_lines="17-19"
- {!> ../../../docs_src/body_multiple_params/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip "Заметка"
- Рекомендуется использовать версию с `Annotated`, если это возможно.
-
- ```Python hl_lines="19-21"
- {!> ../../../docs_src/body_multiple_params/tutorial001.py!}
- ```
-
-!!! note "Заметка"
- Заметьте, что в данном случае параметр `item`, который будет взят из тела запроса, необязателен. Так как было установлено значение `None` по умолчанию.
+///
## Несколько параметров тела запроса
@@ -62,17 +31,7 @@
Но вы также можете объявить множество параметров тела запроса, например `item` и `user`:
-=== "Python 3.10+"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_multiple_params/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/body_multiple_params/tutorial002.py!}
- ```
+{* ../../docs_src/body_multiple_params/tutorial002_py310.py hl[20] *}
В этом случае **FastAPI** заметит, что в функции есть более одного параметра тела (два параметра, которые являются моделями Pydantic).
@@ -93,9 +52,11 @@
}
```
-!!! note "Внимание"
- Обратите внимание, что хотя параметр `item` был объявлен таким же способом, как и раньше, теперь предпологается, что он находится внутри тела с ключом `item`.
+/// note | Внимание
+Обратите внимание, что хотя параметр `item` был объявлен таким же способом, как и раньше, теперь предпологается, что он находится внутри тела с ключом `item`.
+
+///
**FastAPI** сделает автоматические преобразование из запроса, так что параметр `item` получит своё конкретное содержимое, и то же самое происходит с пользователем `user`.
@@ -111,41 +72,7 @@
Но вы можете указать **FastAPI** обрабатывать его, как ещё один ключ тела запроса, используя `Body`:
-=== "Python 3.10+"
-
- ```Python hl_lines="23"
- {!> ../../../docs_src/body_multiple_params/tutorial003_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="23"
- {!> ../../../docs_src/body_multiple_params/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="24"
- {!> ../../../docs_src/body_multiple_params/tutorial003_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip "Заметка"
- Рекомендуется использовать `Annotated` версию, если это возможно.
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_multiple_params/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip "Заметка"
- Рекомендуется использовать `Annotated` версию, если это возможно.
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/body_multiple_params/tutorial003.py!}
- ```
+{* ../../docs_src/body_multiple_params/tutorial003_an_py310.py hl[23] *}
В этом случае, **FastAPI** будет ожидать тело запроса в формате:
@@ -185,44 +112,13 @@ q: str | None = None
Например:
-=== "Python 3.10+"
+{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[27] *}
- ```Python hl_lines="27"
- {!> ../../../docs_src/body_multiple_params/tutorial004_an_py310.py!}
- ```
+/// info | Информация
-=== "Python 3.9+"
+`Body` также имеет все те же дополнительные параметры валидации и метаданных, как у `Query`,`Path` и других, которые вы увидите позже.
- ```Python hl_lines="27"
- {!> ../../../docs_src/body_multiple_params/tutorial004_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="28"
- {!> ../../../docs_src/body_multiple_params/tutorial004_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip "Заметка"
- Рекомендуется использовать `Annotated` версию, если это возможно.
-
- ```Python hl_lines="25"
- {!> ../../../docs_src/body_multiple_params/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip "Заметка"
- Рекомендуется использовать `Annotated` версию, если это возможно.
-
- ```Python hl_lines="27"
- {!> ../../../docs_src/body_multiple_params/tutorial004.py!}
- ```
-
-!!! info "Информация"
- `Body` также имеет все те же дополнительные параметры валидации и метаданных, как у `Query`,`Path` и других, которые вы увидите позже.
+///
## Добавление одного body-параметра
@@ -238,41 +134,7 @@ item: Item = Body(embed=True)
так же, как в этом примере:
-=== "Python 3.10+"
-
- ```Python hl_lines="17"
- {!> ../../../docs_src/body_multiple_params/tutorial005_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="17"
- {!> ../../../docs_src/body_multiple_params/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body_multiple_params/tutorial005_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip "Заметка"
- Рекомендуется использовать `Annotated` версию, если это возможно.
-
- ```Python hl_lines="15"
- {!> ../../../docs_src/body_multiple_params/tutorial005_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip "Заметка"
- Рекомендуется использовать `Annotated` версию, если это возможно.
-
- ```Python hl_lines="17"
- {!> ../../../docs_src/body_multiple_params/tutorial005.py!}
- ```
+{* ../../docs_src/body_multiple_params/tutorial005_an_py310.py hl[17] *}
В этом случае **FastAPI** будет ожидать тело запроса в формате:
diff --git a/docs/ru/docs/tutorial/body-nested-models.md b/docs/ru/docs/tutorial/body-nested-models.md
index 51a32ba56..430092892 100644
--- a/docs/ru/docs/tutorial/body-nested-models.md
+++ b/docs/ru/docs/tutorial/body-nested-models.md
@@ -6,17 +6,7 @@
Вы можете определять атрибут как подтип. Например, тип `list` в Python:
-=== "Python 3.10+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/body_nested_models/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="14"
- {!> ../../../docs_src/body_nested_models/tutorial001.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial001_py310.py hl[12] *}
Это приведёт к тому, что обьект `tags` преобразуется в список, несмотря на то что тип его элементов не объявлен.
@@ -30,9 +20,7 @@
Но в версиях Python до 3.9 (начиная с 3.6) сначала вам необходимо импортировать `List` из стандартного модуля `typing` в Python:
-```Python hl_lines="1"
-{!> ../../../docs_src/body_nested_models/tutorial002.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *}
### Объявление `list` с указанием типов для вложенных элементов
@@ -61,23 +49,7 @@ my_list: List[str]
Таким образом, в нашем примере мы можем явно указать тип данных для поля `tags` как "список строк":
-=== "Python 3.10+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/body_nested_models/tutorial002_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="14"
- {!> ../../../docs_src/body_nested_models/tutorial002_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="14"
- {!> ../../../docs_src/body_nested_models/tutorial002.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial002_py310.py hl[12] *}
## Типы множеств
@@ -87,23 +59,7 @@ my_list: List[str]
Тогда мы можем обьявить поле `tags` как множество строк:
-=== "Python 3.10+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/body_nested_models/tutorial003_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="14"
- {!> ../../../docs_src/body_nested_models/tutorial003_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="1 14"
- {!> ../../../docs_src/body_nested_models/tutorial003.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial003_py310.py hl[12] *}
С помощью этого, даже если вы получите запрос с повторяющимися данными, они будут преобразованы в множество уникальных элементов.
@@ -125,45 +81,13 @@ my_list: List[str]
Например, мы можем определить модель `Image`:
-=== "Python 3.10+"
-
- ```Python hl_lines="7-9"
- {!> ../../../docs_src/body_nested_models/tutorial004_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="9-11"
- {!> ../../../docs_src/body_nested_models/tutorial004_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9-11"
- {!> ../../../docs_src/body_nested_models/tutorial004.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[7:9] *}
### Использование вложенной модели в качестве типа
Также мы можем использовать эту модель как тип атрибута:
-=== "Python 3.10+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body_nested_models/tutorial004_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_nested_models/tutorial004_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_nested_models/tutorial004.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[18] *}
Это означает, что **FastAPI** будет ожидать тело запроса, аналогичное этому:
@@ -196,23 +120,7 @@ my_list: List[str]
Например, так как в модели `Image` у нас есть поле `url`, то мы можем объявить его как тип `HttpUrl` из модуля Pydantic вместо типа `str`:
-=== "Python 3.10+"
-
- ```Python hl_lines="2 8"
- {!> ../../../docs_src/body_nested_models/tutorial005_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="4 10"
- {!> ../../../docs_src/body_nested_models/tutorial005_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="4 10"
- {!> ../../../docs_src/body_nested_models/tutorial005.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial005_py310.py hl[2,8] *}
Строка будет проверена на соответствие допустимому URL-адресу и задокументирована в JSON схему / OpenAPI.
@@ -220,23 +128,7 @@ my_list: List[str]
Вы также можете использовать модели Pydantic в качестве типов вложенных в `list`, `set` и т.д:
-=== "Python 3.10+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body_nested_models/tutorial006_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_nested_models/tutorial006_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_nested_models/tutorial006.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial006_py310.py hl[18] *}
Такая реализация будет ожидать (конвертировать, валидировать, документировать и т.д) JSON-содержимое в следующем формате:
@@ -264,33 +156,23 @@ my_list: List[str]
}
```
-!!! info "Информация"
- Заметьте, что теперь у ключа `images` есть список объектов изображений.
+/// info | Информация
+
+Заметьте, что теперь у ключа `images` есть список объектов изображений.
+
+///
## Глубоко вложенные модели
Вы можете определять модели с произвольным уровнем вложенности:
-=== "Python 3.10+"
+{* ../../docs_src/body_nested_models/tutorial007_py310.py hl[7,12,18,21,25] *}
- ```Python hl_lines="7 12 18 21 25"
- {!> ../../../docs_src/body_nested_models/tutorial007_py310.py!}
- ```
+/// info | Информация
-=== "Python 3.9+"
+Заметьте, что у объекта `Offer` есть список объектов `Item`, которые, в свою очередь, могут содержать необязательный список объектов `Image`
- ```Python hl_lines="9 14 20 23 27"
- {!> ../../../docs_src/body_nested_models/tutorial007_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9 14 20 23 27"
- {!> ../../../docs_src/body_nested_models/tutorial007.py!}
- ```
-
-!!! info "Информация"
- Заметьте, что у объекта `Offer` есть список объектов `Item`, которые, в свою очередь, могут содержать необязательный список объектов `Image`
+///
## Тела с чистыми списками элементов
@@ -308,17 +190,7 @@ images: list[Image]
например так:
-=== "Python 3.9+"
-
- ```Python hl_lines="13"
- {!> ../../../docs_src/body_nested_models/tutorial008_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="15"
- {!> ../../../docs_src/body_nested_models/tutorial008.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial008_py39.py hl[13] *}
## Универсальная поддержка редактора
@@ -348,26 +220,19 @@ images: list[Image]
В этом случае вы принимаете `dict`, пока у него есть ключи типа `int` со значениями типа `float`:
-=== "Python 3.9+"
+{* ../../docs_src/body_nested_models/tutorial009_py39.py hl[7] *}
- ```Python hl_lines="7"
- {!> ../../../docs_src/body_nested_models/tutorial009_py39.py!}
- ```
+/// tip | Совет
-=== "Python 3.8+"
+Имейте в виду, что JSON поддерживает только ключи типа `str`.
- ```Python hl_lines="9"
- {!> ../../../docs_src/body_nested_models/tutorial009.py!}
- ```
+Но Pydantic обеспечивает автоматическое преобразование данных.
-!!! tip "Совет"
- Имейте в виду, что JSON поддерживает только ключи типа `str`.
+Это значит, что даже если пользователи вашего API могут отправлять только строки в качестве ключей, при условии, что эти строки содержат целые числа, Pydantic автоматический преобразует и валидирует эти данные.
- Но Pydantic обеспечивает автоматическое преобразование данных.
+А `dict`, с именем `weights`, который вы получите в качестве ответа Pydantic, действительно будет иметь ключи типа `int` и значения типа `float`.
- Это значит, что даже если пользователи вашего API могут отправлять только строки в качестве ключей, при условии, что эти строки содержат целые числа, Pydantic автоматический преобразует и валидирует эти данные.
-
- А `dict`, с именем `weights`, который вы получите в качестве ответа Pydantic, действительно будет иметь ключи типа `int` и значения типа `float`.
+///
## Резюме
diff --git a/docs/ru/docs/tutorial/body-updates.md b/docs/ru/docs/tutorial/body-updates.md
index 4998ab31a..99f475a41 100644
--- a/docs/ru/docs/tutorial/body-updates.md
+++ b/docs/ru/docs/tutorial/body-updates.md
@@ -6,23 +6,7 @@
Вы можете использовать функцию `jsonable_encoder` для преобразования входных данных в JSON, так как нередки случаи, когда работать можно только с простыми типами данных (например, для хранения в NoSQL-базе данных).
-=== "Python 3.10+"
-
- ```Python hl_lines="28-33"
- {!> ../../../docs_src/body_updates/tutorial001_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="30-35"
- {!> ../../../docs_src/body_updates/tutorial001_py39.py!}
- ```
-
-=== "Python 3.6+"
-
- ```Python hl_lines="30-35"
- {!> ../../../docs_src/body_updates/tutorial001.py!}
- ```
+{* ../../docs_src/body_updates/tutorial001_py310.py hl[28:33] *}
`PUT` используется для получения данных, которые должны полностью заменить существующие данные.
@@ -48,14 +32,17 @@
Это означает, что можно передавать только те данные, которые необходимо обновить, оставляя остальные нетронутыми.
-!!! note "Технические детали"
- `PATCH` менее распространен и известен, чем `PUT`.
+/// note | Технические детали
- А многие команды используют только `PUT`, даже для частичного обновления.
+`PATCH` менее распространен и известен, чем `PUT`.
- Вы можете **свободно** использовать их как угодно, **FastAPI** не накладывает никаких ограничений.
+А многие команды используют только `PUT`, даже для частичного обновления.
- Но в данном руководстве более или менее понятно, как они должны использоваться.
+Вы можете **свободно** использовать их как угодно, **FastAPI** не накладывает никаких ограничений.
+
+Но в данном руководстве более или менее понятно, как они должны использоваться.
+
+///
### Использование параметра `exclude_unset` в Pydantic
@@ -65,23 +52,7 @@
В результате будет сгенерирован словарь, содержащий только те данные, которые были заданы при создании модели `item`, без учета значений по умолчанию. Затем вы можете использовать это для создания словаря только с теми данными, которые были установлены (отправлены в запросе), опуская значения по умолчанию:
-=== "Python 3.10+"
-
- ```Python hl_lines="32"
- {!> ../../../docs_src/body_updates/tutorial002_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="34"
- {!> ../../../docs_src/body_updates/tutorial002_py39.py!}
- ```
-
-=== "Python 3.6+"
-
- ```Python hl_lines="34"
- {!> ../../../docs_src/body_updates/tutorial002.py!}
- ```
+{* ../../docs_src/body_updates/tutorial002_py310.py hl[32] *}
### Использование параметра `update` в Pydantic
@@ -89,23 +60,7 @@
Например, `stored_item_model.copy(update=update_data)`:
-=== "Python 3.10+"
-
- ```Python hl_lines="33"
- {!> ../../../docs_src/body_updates/tutorial002_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="35"
- {!> ../../../docs_src/body_updates/tutorial002_py39.py!}
- ```
-
-=== "Python 3.6+"
-
- ```Python hl_lines="35"
- {!> ../../../docs_src/body_updates/tutorial002.py!}
- ```
+{* ../../docs_src/body_updates/tutorial002_py310.py hl[33] *}
### Кратко о частичном обновлении
@@ -122,32 +77,22 @@
* Сохранить данные в своей БД.
* Вернуть обновленную модель.
-=== "Python 3.10+"
+{* ../../docs_src/body_updates/tutorial002_py310.py hl[28:35] *}
- ```Python hl_lines="28-35"
- {!> ../../../docs_src/body_updates/tutorial002_py310.py!}
- ```
+/// tip | Подсказка
-=== "Python 3.9+"
+Эту же технику можно использовать и для операции HTTP `PUT`.
- ```Python hl_lines="30-37"
- {!> ../../../docs_src/body_updates/tutorial002_py39.py!}
- ```
+Но в приведенном примере используется `PATCH`, поскольку он был создан именно для таких случаев использования.
-=== "Python 3.6+"
+///
- ```Python hl_lines="30-37"
- {!> ../../../docs_src/body_updates/tutorial002.py!}
- ```
+/// note | Технические детали
-!!! tip "Подсказка"
- Эту же технику можно использовать и для операции HTTP `PUT`.
+Обратите внимание, что входная модель по-прежнему валидируется.
- Но в приведенном примере используется `PATCH`, поскольку он был создан именно для таких случаев использования.
+Таким образом, если вы хотите получать частичные обновления, в которых могут быть опущены все атрибуты, вам необходимо иметь модель, в которой все атрибуты помечены как необязательные (со значениями по умолчанию или `None`).
-!!! note "Технические детали"
- Обратите внимание, что входная модель по-прежнему валидируется.
+Чтобы отличить модели со всеми необязательными значениями для **обновления** от моделей с обязательными значениями для **создания**, можно воспользоваться идеями, описанными в [Дополнительные модели](extra-models.md){.internal-link target=_blank}.
- Таким образом, если вы хотите получать частичные обновления, в которых могут быть опущены все атрибуты, вам необходимо иметь модель, в которой все атрибуты помечены как необязательные (со значениями по умолчанию или `None`).
-
- Чтобы отличить модели со всеми необязательными значениями для **обновления** от моделей с обязательными значениями для **создания**, можно воспользоваться идеями, описанными в [Дополнительные модели](extra-models.md){.internal-link target=_blank}.
+///
diff --git a/docs/ru/docs/tutorial/body.md b/docs/ru/docs/tutorial/body.md
index 5d0e033fd..2c9110226 100644
--- a/docs/ru/docs/tutorial/body.md
+++ b/docs/ru/docs/tutorial/body.md
@@ -8,20 +8,21 @@
Чтобы объявить тело **запроса**, необходимо использовать модели Pydantic, со всей их мощью и преимуществами.
-!!! info "Информация"
- Чтобы отправить данные, необходимо использовать один из методов: `POST` (обычно), `PUT`, `DELETE` или `PATCH`.
+/// info | Информация
- Отправка тела с запросом `GET` имеет неопределенное поведение в спецификациях, тем не менее, оно поддерживается FastAPI только для очень сложных/экстремальных случаев использования.
+Чтобы отправить данные, необходимо использовать один из методов: `POST` (обычно), `PUT`, `DELETE` или `PATCH`.
- Поскольку это не рекомендуется, интерактивная документация со Swagger UI не будет отображать информацию для тела при использовании метода GET, а промежуточные прокси-серверы могут не поддерживать такой вариант запроса.
+Отправка тела с запросом `GET` имеет неопределенное поведение в спецификациях, тем не менее, оно поддерживается FastAPI только для очень сложных/экстремальных случаев использования.
+
+Поскольку это не рекомендуется, интерактивная документация со Swagger UI не будет отображать информацию для тела при использовании метода GET, а промежуточные прокси-серверы могут не поддерживать такой вариант запроса.
+
+///
## Импортирование `BaseModel` из Pydantic
Первое, что вам необходимо сделать, это импортировать `BaseModel` из пакета `pydantic`:
-```Python hl_lines="4"
-{!../../../docs_src/body/tutorial001.py!}
-```
+{* ../../docs_src/body/tutorial001.py hl[4] *}
## Создание вашей собственной модели
@@ -29,9 +30,7 @@
Используйте аннотации типов Python для всех атрибутов:
-```Python hl_lines="7-11"
-{!../../../docs_src/body/tutorial001.py!}
-```
+{* ../../docs_src/body/tutorial001.py hl[7:11] *}
Также как и при описании параметров запроса, когда атрибут модели имеет значение по умолчанию, он является необязательным. Иначе он обязателен. Используйте `None`, чтобы сделать его необязательным без использования конкретных значений по умолчанию.
@@ -59,9 +58,7 @@
Чтобы добавить параметр к вашему *обработчику*, объявите его также, как вы объявляли параметры пути или параметры запроса:
-```Python hl_lines="18"
-{!../../../docs_src/body/tutorial001.py!}
-```
+{* ../../docs_src/body/tutorial001.py hl[18] *}
...и укажите созданную модель в качестве типа параметра, `Item`.
@@ -110,24 +107,25 @@
-!!! tip "Подсказка"
- Если вы используете PyCharm в качестве редактора, то вам стоит попробовать плагин Pydantic PyCharm Plugin.
+/// tip | Подсказка
- Он улучшает поддержку редактором моделей Pydantic в части:
+Если вы используете PyCharm в качестве редактора, то вам стоит попробовать плагин Pydantic PyCharm Plugin.
- * автодополнения,
- * проверки типов,
- * рефакторинга,
- * поиска,
- * инспектирования.
+Он улучшает поддержку редактором моделей Pydantic в части:
+
+* автодополнения,
+* проверки типов,
+* рефакторинга,
+* поиска,
+* инспектирования.
+
+///
## Использование модели
Внутри функции вам доступны все атрибуты объекта модели напрямую:
-```Python hl_lines="21"
-{!../../../docs_src/body/tutorial002.py!}
-```
+{* ../../docs_src/body/tutorial002.py hl[21] *}
## Тело запроса + параметры пути
@@ -135,9 +133,7 @@
**FastAPI** распознает, какие параметры функции соответствуют параметрам пути и должны быть **получены из пути**, а какие параметры функции, объявленные как модели Pydantic, должны быть **получены из тела запроса**.
-```Python hl_lines="17-18"
-{!../../../docs_src/body/tutorial003.py!}
-```
+{* ../../docs_src/body/tutorial003.py hl[17:18] *}
## Тело запроса + параметры пути + параметры запроса
@@ -145,9 +141,7 @@
**FastAPI** распознает каждый из них и возьмет данные из правильного источника.
-```Python hl_lines="18"
-{!../../../docs_src/body/tutorial004.py!}
-```
+{* ../../docs_src/body/tutorial004.py hl[18] *}
Параметры функции распознаются следующим образом:
@@ -155,10 +149,13 @@
* Если аннотация типа параметра содержит **примитивный тип** (`int`, `float`, `str`, `bool` и т.п.), он будет интерпретирован как параметр **запроса**.
* Если аннотация типа параметра представляет собой **модель Pydantic**, он будет интерпретирован как параметр **тела запроса**.
-!!! note "Заметка"
- FastAPI понимает, что значение параметра `q` не является обязательным, потому что имеет значение по умолчанию `= None`.
+/// note | Заметка
- Аннотация `Optional` в `Optional[str]` не используется FastAPI, но помогает вашему редактору лучше понимать ваш код и обнаруживать ошибки.
+FastAPI понимает, что значение параметра `q` не является обязательным, потому что имеет значение по умолчанию `= None`.
+
+Аннотация `Optional` в `Optional[str]` не используется FastAPI, но помогает вашему редактору лучше понимать ваш код и обнаруживать ошибки.
+
+///
## Без Pydantic
diff --git a/docs/ru/docs/tutorial/cookie-param-models.md b/docs/ru/docs/tutorial/cookie-param-models.md
new file mode 100644
index 000000000..3a57443bb
--- /dev/null
+++ b/docs/ru/docs/tutorial/cookie-param-models.md
@@ -0,0 +1,76 @@
+# Модели параметров cookie
+
+Если у вас есть группа **cookies**, которые связаны между собой, вы можете создать **Pydantic-модель** для их объявления. 🍪
+
+Это позволит вам **переиспользовать модель** в **разных местах**, а также объявить проверки и метаданные сразу для всех параметров. 😎
+
+/// note | Заметка
+
+Этот функционал доступен с версии `0.115.0`. 🤓
+
+///
+
+/// tip | Совет
+
+Такой же подход применяется для `Query`, `Cookie`, и `Header`. 😎
+
+///
+
+## Pydantic-модель для cookies
+
+Объявите параметры **cookie**, которые вам нужны, в **Pydantic-модели**, а затем объявите параметр как `Cookie`:
+
+{* ../../docs_src/cookie_param_models/tutorial001_an_py310.py hl[9:12,16] *}
+
+**FastAPI** **извлечёт** данные для **каждого поля** из **cookies**, полученных в запросе, и выдаст вам объявленную Pydantic-модель.
+
+## Проверка сгенерированной документации
+
+Вы можете посмотреть объявленные cookies в графическом интерфейсе Документации по пути `/docs`:
+
+
+get операцию
-!!! info "`@decorator` Дополнительная информация"
- Синтаксис `@something` в Python называется "декоратор".
+/// info | `@decorator` Дополнительная информация
- Вы помещаете его над функцией. Как красивую декоративную шляпу (думаю, что оттуда и происходит этот термин).
+Синтаксис `@something` в Python называется "декоратор".
- "Декоратор" принимает функцию ниже и выполняет с ней какое-то действие.
+Вы помещаете его над функцией. Как красивую декоративную шляпу (думаю, что оттуда и происходит этот термин).
- В нашем случае, этот декоратор сообщает **FastAPI**, что функция ниже соответствует **пути** `/` и **операции** `get`.
+"Декоратор" принимает функцию ниже и выполняет с ней какое-то действие.
- Это и есть "**декоратор операции пути**".
+В нашем случае, этот декоратор сообщает **FastAPI**, что функция ниже соответствует **пути** `/` и **операции** `get`.
+
+Это и есть "**декоратор операции пути**".
+
+///
Можно также использовать операции:
@@ -274,14 +276,17 @@ https://example.com/items/foo
* `@app.patch()`
* `@app.trace()`
-!!! tip "Подсказка"
- Вы можете использовать каждую операцию (HTTP-метод) по своему усмотрению.
+/// tip | Подсказка
- **FastAPI** не навязывает определенного значения для каждого метода.
+Вы можете использовать каждую операцию (HTTP-метод) по своему усмотрению.
- Информация здесь представлена как рекомендация, а не требование.
+**FastAPI** не навязывает определенного значения для каждого метода.
- Например, при использовании GraphQL обычно все действия выполняются только с помощью POST операций.
+Информация здесь представлена как рекомендация, а не требование.
+
+Например, при использовании GraphQL обычно все действия выполняются только с помощью POST операций.
+
+///
### Шаг 4: определите **функцию операции пути**
@@ -291,9 +296,7 @@ https://example.com/items/foo
* **операция**: `get`.
* **функция**: функция ниже "декоратора" (ниже `@app.get("/")`).
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[7] *}
Это обычная Python функция.
@@ -305,18 +308,17 @@ https://example.com/items/foo
Вы также можете определить ее как обычную функцию вместо `async def`:
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial003.py!}
-```
+{* ../../docs_src/first_steps/tutorial003.py hl[7] *}
-!!! note "Технические детали"
- Если не знаете в чём разница, посмотрите [Конкурентность: *"Нет времени?"*](../async.md#_1){.internal-link target=_blank}.
+/// note | Технические детали
+
+Если не знаете в чём разница, посмотрите [Конкурентность: *"Нет времени?"*](../async.md#_1){.internal-link target=_blank}.
+
+///
### Шаг 5: верните результат
-```Python hl_lines="8"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[8] *}
Вы можете вернуть `dict`, `list`, отдельные значения `str`, `int` и т.д.
diff --git a/docs/ru/docs/tutorial/handling-errors.md b/docs/ru/docs/tutorial/handling-errors.md
index 40b6f9bc4..c596abe1f 100644
--- a/docs/ru/docs/tutorial/handling-errors.md
+++ b/docs/ru/docs/tutorial/handling-errors.md
@@ -25,9 +25,7 @@
### Импортируйте `HTTPException`
-```Python hl_lines="1"
-{!../../../docs_src/handling_errors/tutorial001.py!}
-```
+{* ../../docs_src/handling_errors/tutorial001.py hl[1] *}
### Вызовите `HTTPException` в своем коде
@@ -41,9 +39,7 @@
В данном примере, когда клиент запрашивает элемент по несуществующему ID, возникает исключение со статус-кодом `404`:
-```Python hl_lines="11"
-{!../../../docs_src/handling_errors/tutorial001.py!}
-```
+{* ../../docs_src/handling_errors/tutorial001.py hl[11] *}
### Возвращаемый ответ
@@ -63,12 +59,15 @@
}
```
-!!! tip "Подсказка"
- При вызове `HTTPException` в качестве параметра `detail` можно передавать любое значение, которое может быть преобразовано в JSON, а не только `str`.
+/// tip | Подсказка
- Вы можете передать `dict`, `list` и т.д.
+При вызове `HTTPException` в качестве параметра `detail` можно передавать любое значение, которое может быть преобразовано в JSON, а не только `str`.
- Они автоматически обрабатываются **FastAPI** и преобразуются в JSON.
+Вы можете передать `dict`, `list` и т.д.
+
+Они автоматически обрабатываются **FastAPI** и преобразуются в JSON.
+
+///
## Добавление пользовательских заголовков
@@ -78,9 +77,7 @@
Но в случае, если это необходимо для продвинутого сценария, можно добавить пользовательские заголовки:
-```Python hl_lines="14"
-{!../../../docs_src/handling_errors/tutorial002.py!}
-```
+{* ../../docs_src/handling_errors/tutorial002.py hl[14] *}
## Установка пользовательских обработчиков исключений
@@ -92,9 +89,7 @@
Можно добавить собственный обработчик исключений с помощью `@app.exception_handler()`:
-```Python hl_lines="5-7 13-18 24"
-{!../../../docs_src/handling_errors/tutorial003.py!}
-```
+{* ../../docs_src/handling_errors/tutorial003.py hl[5:7,13:18,24] *}
Здесь, если запросить `/unicorns/yolo`, то *операция пути* вызовет `UnicornException`.
@@ -106,10 +101,13 @@
{"message": "Oops! yolo did something. There goes a rainbow..."}
```
-!!! note "Технические детали"
- Также можно использовать `from starlette.requests import Request` и `from starlette.responses import JSONResponse`.
+/// note | Технические детали
- **FastAPI** предоставляет тот же `starlette.responses`, что и `fastapi.responses`, просто для удобства разработчика. Однако большинство доступных ответов поступает непосредственно из Starlette. То же самое касается и `Request`.
+Также можно использовать `from starlette.requests import Request` и `from starlette.responses import JSONResponse`.
+
+**FastAPI** предоставляет тот же `starlette.responses`, что и `fastapi.responses`, просто для удобства разработчика. Однако большинство доступных ответов поступает непосредственно из Starlette. То же самое касается и `Request`.
+
+///
## Переопределение стандартных обработчиков исключений
@@ -129,9 +127,7 @@
Обработчик исключения получит объект `Request` и исключение.
-```Python hl_lines="2 14-16"
-{!../../../docs_src/handling_errors/tutorial004.py!}
-```
+{* ../../docs_src/handling_errors/tutorial004.py hl[2,14:16] *}
Теперь, если перейти к `/items/foo`, то вместо стандартной JSON-ошибки с:
@@ -160,8 +156,11 @@ path -> item_id
#### `RequestValidationError` или `ValidationError`
-!!! warning "Внимание"
- Это технические детали, которые можно пропустить, если они не важны для вас сейчас.
+/// warning | Внимание
+
+Это технические детали, которые можно пропустить, если они не важны для вас сейчас.
+
+///
`RequestValidationError` является подклассом Pydantic `ValidationError`.
@@ -179,14 +178,15 @@ path -> item_id
Например, для этих ошибок можно вернуть обычный текстовый ответ вместо JSON:
-```Python hl_lines="3-4 9-11 22"
-{!../../../docs_src/handling_errors/tutorial004.py!}
-```
+{* ../../docs_src/handling_errors/tutorial004.py hl[3:4,9:11,22] *}
-!!! note "Технические детали"
- Можно также использовать `from starlette.responses import PlainTextResponse`.
+/// note | Технические детали
- **FastAPI** предоставляет тот же `starlette.responses`, что и `fastapi.responses`, просто для удобства разработчика. Однако большинство доступных ответов поступает непосредственно из Starlette.
+Можно также использовать `from starlette.responses import PlainTextResponse`.
+
+**FastAPI** предоставляет тот же `starlette.responses`, что и `fastapi.responses`, просто для удобства разработчика. Однако большинство доступных ответов поступает непосредственно из Starlette.
+
+///
### Используйте тело `RequestValidationError`
@@ -194,9 +194,7 @@ path -> item_id
Вы можете использовать его при разработке приложения для регистрации тела и его отладки, возврата пользователю и т.д.
-```Python hl_lines="14"
-{!../../../docs_src/handling_errors/tutorial005.py!}
-```
+{* ../../docs_src/handling_errors/tutorial005.py hl[14] *}
Теперь попробуйте отправить недействительный элемент, например:
@@ -254,8 +252,6 @@ from starlette.exceptions import HTTPException as StarletteHTTPException
Если вы хотите использовать исключение вместе с теми же обработчиками исключений по умолчанию из **FastAPI**, вы можете импортировать и повторно использовать обработчики исключений по умолчанию из `fastapi.exception_handlers`:
-```Python hl_lines="2-5 15 21"
-{!../../../docs_src/handling_errors/tutorial006.py!}
-```
+{* ../../docs_src/handling_errors/tutorial006.py hl[2:5,15,21] *}
В этом примере вы просто `выводите в терминал` ошибку с очень выразительным сообщением, но идея вам понятна. Вы можете использовать исключение, а затем просто повторно использовать стандартные обработчики исключений.
diff --git a/docs/ru/docs/tutorial/header-param-models.md b/docs/ru/docs/tutorial/header-param-models.md
new file mode 100644
index 000000000..4f54e3e15
--- /dev/null
+++ b/docs/ru/docs/tutorial/header-param-models.md
@@ -0,0 +1,72 @@
+# Модели Header-параметров
+
+Если у вас есть группа связанных **header-параметров**, то вы можете объединить их в одну **Pydantic-модель**.
+
+Это позволит вам **переиспользовать модель** в **разных местах**, а также задать валидацию и метаданные сразу для всех параметров. 😎
+
+/// note | Заметка
+
+Этот функционал доступен в FastAPI начиная с версии `0.115.0`. 🤓
+
+///
+
+## Header-параметры в виде Pydantic-модели
+
+Объявите нужные **header-параметры** в **Pydantic-модели** и затем аннотируйте параметр как `Header`:
+
+{* ../../docs_src/header_param_models/tutorial001_an_py310.py hl[9:14,18] *}
+
+**FastAPI** **извлечёт** данные для **каждого поля** из **заголовков** запроса и выдаст заданную вами Pydantic-модель.
+
+## Проверьте документацию
+
+Вы можете посмотреть нужные header-параметры в графическом интерфейсе сгенерированной документации по пути `/docs`:
+
+
+
@@ -162,9 +92,7 @@
Если вам необходимо пометить *операцию пути* как устаревшую, при этом не удаляя её, передайте параметр `deprecated`:
-```Python hl_lines="16"
-{!../../../docs_src/path_operation_configuration/tutorial006.py!}
-```
+{* ../../docs_src/path_operation_configuration/tutorial006.py hl[16] *}
Он будет четко помечен как устаревший в интерактивной документации:
diff --git a/docs/ru/docs/tutorial/path-params-numeric-validations.md b/docs/ru/docs/tutorial/path-params-numeric-validations.md
index 0baf51fa9..dca267f78 100644
--- a/docs/ru/docs/tutorial/path-params-numeric-validations.md
+++ b/docs/ru/docs/tutorial/path-params-numeric-validations.md
@@ -6,48 +6,17 @@
Сначала импортируйте `Path` из `fastapi`, а также импортируйте `Annotated`:
-=== "Python 3.10+"
+{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[1,3] *}
- ```Python hl_lines="1 3"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py!}
- ```
+/// info | Информация
-=== "Python 3.9+"
+Поддержка `Annotated` была добавлена в FastAPI начиная с версии 0.95.0 (и с этой версии рекомендуется использовать этот подход).
- ```Python hl_lines="1 3"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py39.py!}
- ```
+Если вы используете более старую версию, вы столкнётесь с ошибками при попытке использовать `Annotated`.
-=== "Python 3.8+"
+Убедитесь, что вы [обновили версию FastAPI](../deployment/versions.md#fastapi_2){.internal-link target=_blank} как минимум до 0.95.1 перед тем, как использовать `Annotated`.
- ```Python hl_lines="3-4"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ без Annotated"
-
- !!! tip "Подсказка"
- Рекомендуется использовать версию с `Annotated` если возможно.
-
- ```Python hl_lines="1"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ без Annotated"
-
- !!! tip "Подсказка"
- Рекомендуется использовать версию с `Annotated` если возможно.
-
- ```Python hl_lines="3"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001.py!}
- ```
-
-!!! info "Информация"
- Поддержка `Annotated` была добавлена в FastAPI начиная с версии 0.95.0 (и с этой версии рекомендуется использовать этот подход).
-
- Если вы используете более старую версию, вы столкнётесь с ошибками при попытке использовать `Annotated`.
-
- Убедитесь, что вы [обновили версию FastAPI](../deployment/versions.md#fastapi_2){.internal-link target=_blank} как минимум до 0.95.1 перед тем, как использовать `Annotated`.
+///
## Определите метаданные
@@ -55,53 +24,25 @@
Например, чтобы указать значение метаданных `title` для path-параметра `item_id`, вы можете написать:
-=== "Python 3.10+"
+{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[10] *}
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py!}
- ```
+/// note | Примечание
-=== "Python 3.9+"
+Path-параметр всегда является обязательным, поскольку он составляет часть пути.
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py39.py!}
- ```
+Поэтому следует объявить его с помощью `...`, чтобы обозначить, что этот параметр обязательный.
-=== "Python 3.8+"
+Тем не менее, даже если вы объявите его как `None` или установите для него значение по умолчанию, это ни на что не повлияет и параметр останется обязательным.
- ```Python hl_lines="11"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ без Annotated"
-
- !!! tip "Подсказка"
- Рекомендуется использовать версию с `Annotated` если возможно.
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ без Annotated"
-
- !!! tip "Подсказка"
- Рекомендуется использовать версию с `Annotated` если возможно.
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001.py!}
- ```
-
-!!! note "Примечание"
- Path-параметр всегда является обязательным, поскольку он составляет часть пути.
-
- Поэтому следует объявить его с помощью `...`, чтобы обозначить, что этот параметр обязательный.
-
- Тем не менее, даже если вы объявите его как `None` или установите для него значение по умолчанию, это ни на что не повлияет и параметр останется обязательным.
+///
## Задайте нужный вам порядок параметров
-!!! tip "Подсказка"
- Это не имеет большого значения, если вы используете `Annotated`.
+/// tip | Подсказка
+
+Это не имеет большого значения, если вы используете `Annotated`.
+
+///
Допустим, вы хотите объявить query-параметр `q` как обязательный параметр типа `str`.
@@ -117,33 +58,31 @@
Поэтому вы можете определить функцию так:
-=== "Python 3.8 без Annotated"
+//// tab | Python 3.8 без Annotated
- !!! tip "Подсказка"
- Рекомендуется использовать версию с `Annotated` если возможно.
+/// tip | Подсказка
- ```Python hl_lines="7"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial002.py!}
- ```
+Рекомендуется использовать версию с `Annotated` если возможно.
+
+///
+
+```Python hl_lines="7"
+{!> ../../docs_src/path_params_numeric_validations/tutorial002.py!}
+```
+
+////
Но имейте в виду, что если вы используете `Annotated`, вы не столкнётесь с этой проблемой, так как вы не используете `Query()` или `Path()` в качестве значения по умолчанию для параметра функции.
-=== "Python 3.9+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial002_an.py!}
- ```
+{* ../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py hl[10] *}
## Задайте нужный вам порядок параметров, полезные приёмы
-!!! tip "Подсказка"
- Это не имеет большого значения, если вы используете `Annotated`.
+/// tip | Подсказка
+
+Это не имеет большого значения, если вы используете `Annotated`.
+
+///
Здесь описан **небольшой приём**, который может оказаться удобным, хотя часто он вам не понадобится.
@@ -160,25 +99,13 @@
Python не будет ничего делать с `*`, но он будет знать, что все следующие параметры являются именованными аргументами (парами ключ-значение), также известными как kwargs, даже если у них нет значений по умолчанию.
-```Python hl_lines="7"
-{!../../../docs_src/path_params_numeric_validations/tutorial003.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *}
### Лучше с `Annotated`
Имейте в виду, что если вы используете `Annotated`, то, поскольку вы не используете значений по умолчанию для параметров функции, то у вас не возникнет подобной проблемы и вам не придётся использовать `*`.
-=== "Python 3.9+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial003_an.py!}
- ```
+{* ../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py hl[10] *}
## Валидация числовых данных: больше или равно
@@ -186,26 +113,7 @@ Python не будет ничего делать с `*`, но он будет з
В этом примере при указании `ge=1`, параметр `item_id` должен быть больше или равен `1` ("`g`reater than or `e`qual").
-=== "Python 3.9+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial004_an.py!}
- ```
-
-=== "Python 3.8+ без Annotated"
-
- !!! tip "Подсказка"
- Рекомендуется использовать версию с `Annotated` если возможно.
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial004.py!}
- ```
+{* ../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py hl[10] *}
## Валидация числовых данных: больше и меньше или равно
@@ -214,26 +122,7 @@ Python не будет ничего делать с `*`, но он будет з
* `gt`: больше (`g`reater `t`han)
* `le`: меньше или равно (`l`ess than or `e`qual)
-=== "Python 3.9+"
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial005_an.py!}
- ```
-
-=== "Python 3.8+ без Annotated"
-
- !!! tip "Подсказка"
- Рекомендуется использовать версию с `Annotated` если возможно.
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial005.py!}
- ```
+{* ../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py hl[10] *}
## Валидация числовых данных: числа с плавающей точкой, больше и меньше
@@ -245,26 +134,7 @@ Python не будет ничего делать с `*`, но он будет з
То же самое справедливо и для lt.
-=== "Python 3.9+"
-
- ```Python hl_lines="13"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial006_an.py!}
- ```
-
-=== "Python 3.8+ без Annotated"
-
- !!! tip "Подсказка"
- Рекомендуется использовать версию с `Annotated` если возможно.
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial006.py!}
- ```
+{* ../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py hl[13] *}
## Резюме
@@ -277,16 +147,22 @@ Python не будет ничего делать с `*`, но он будет з
* `lt`: меньше (`l`ess `t`han)
* `le`: меньше или равно (`l`ess than or `e`qual)
-!!! info "Информация"
- `Query`, `Path` и другие классы, которые мы разберём позже, являются наследниками общего класса `Param`.
+/// info | Информация
- Все они используют те же параметры для дополнительной валидации и метаданных, которые вы видели ранее.
+`Query`, `Path` и другие классы, которые мы разберём позже, являются наследниками общего класса `Param`.
-!!! note "Технические детали"
- `Query`, `Path` и другие "классы", которые вы импортируете из `fastapi`, на самом деле являются функциями, которые при вызове возвращают экземпляры одноимённых классов.
+Все они используют те же параметры для дополнительной валидации и метаданных, которые вы видели ранее.
- Объект `Query`, который вы импортируете, является функцией. И при вызове она возвращает экземпляр одноимённого класса `Query`.
+///
- Использование функций (вместо использования классов напрямую) нужно для того, чтобы ваш редактор не подсвечивал ошибки, связанные с их типами.
+/// note | Технические детали
- Таким образом вы можете использовать привычный вам редактор и инструменты разработки, не добавляя дополнительных конфигураций для игнорирования подобных ошибок.
+`Query`, `Path` и другие "классы", которые вы импортируете из `fastapi`, на самом деле являются функциями, которые при вызове возвращают экземпляры одноимённых классов.
+
+Объект `Query`, который вы импортируете, является функцией. И при вызове она возвращает экземпляр одноимённого класса `Query`.
+
+Использование функций (вместо использования классов напрямую) нужно для того, чтобы ваш редактор не подсвечивал ошибки, связанные с их типами.
+
+Таким образом вы можете использовать привычный вам редактор и инструменты разработки, не добавляя дополнительных конфигураций для игнорирования подобных ошибок.
+
+///
diff --git a/docs/ru/docs/tutorial/path-params.md b/docs/ru/docs/tutorial/path-params.md
index 1241e0919..5c2d82a65 100644
--- a/docs/ru/docs/tutorial/path-params.md
+++ b/docs/ru/docs/tutorial/path-params.md
@@ -2,9 +2,7 @@
Вы можете определить "параметры" или "переменные" пути, используя синтаксис форматированных строк Python:
-```Python hl_lines="6-7"
-{!../../../docs_src/path_params/tutorial001.py!}
-```
+{* ../../docs_src/path_params/tutorial001.py hl[6:7] *}
Значение параметра пути `item_id` будет передано в функцию в качестве аргумента `item_id`.
@@ -18,14 +16,15 @@
Вы можете объявить тип параметра пути в функции, используя стандартные аннотации типов Python.
-```Python hl_lines="7"
-{!../../../docs_src/path_params/tutorial002.py!}
-```
+{* ../../docs_src/path_params/tutorial002.py hl[7] *}
Здесь, `item_id` объявлен типом `int`.
-!!! check "Заметка"
- Это обеспечит поддержку редактора внутри функции (проверка ошибок, автодополнение и т.п.).
+/// check | Заметка
+
+Это обеспечит поддержку редактора внутри функции (проверка ошибок, автодополнение и т.п.).
+
+///
## Преобразование данных
@@ -35,10 +34,13 @@
{"item_id":3}
```
-!!! check "Заметка"
- Обратите внимание на значение `3`, которое получила (и вернула) функция. Это целочисленный Python `int`, а не строка `"3"`.
+/// check | Заметка
- Используя определения типов, **FastAPI** выполняет автоматический "парсинг" запросов.
+Обратите внимание на значение `3`, которое получила (и вернула) функция. Это целочисленный Python `int`, а не строка `"3"`.
+
+Используя определения типов, **FastAPI** выполняет автоматический "парсинг" запросов.
+
+///
## Проверка данных
@@ -63,12 +65,15 @@
Та же ошибка возникнет, если вместо `int` передать `float` , например: http://127.0.0.1:8000/items/4.2
-!!! check "Заметка"
- **FastAPI** обеспечивает проверку типов, используя всё те же определения типов.
+/// check | Заметка
- Обратите внимание, что в тексте ошибки явно указано место не прошедшее проверку.
+**FastAPI** обеспечивает проверку типов, используя всё те же определения типов.
- Это очень полезно при разработке и отладке кода, который взаимодействует с API.
+Обратите внимание, что в тексте ошибки явно указано место не прошедшее проверку.
+
+Это очень полезно при разработке и отладке кода, который взаимодействует с API.
+
+///
## Документация
@@ -76,10 +81,13 @@
-!!! check "Заметка"
- Ещё раз, просто используя определения типов, **FastAPI** обеспечивает автоматическую интерактивную документацию (с интеграцией Swagger UI).
+/// check | Заметка
- Обратите внимание, что параметр пути объявлен целочисленным.
+Ещё раз, просто используя определения типов, **FastAPI** обеспечивает автоматическую интерактивную документацию (с интеграцией Swagger UI).
+
+Обратите внимание, что параметр пути объявлен целочисленным.
+
+///
## Преимущества стандартизации, альтернативная документация
@@ -110,17 +118,13 @@
Поскольку *операции пути* выполняются в порядке их объявления, необходимо, чтобы путь для `/users/me` был объявлен раньше, чем путь для `/users/{user_id}`:
-```Python hl_lines="6 11"
-{!../../../docs_src/path_params/tutorial003.py!}
-```
+{* ../../docs_src/path_params/tutorial003.py hl[6,11] *}
Иначе путь для `/users/{user_id}` также будет соответствовать `/users/me`, "подразумевая", что он получает параметр `user_id` со значением `"me"`.
Аналогично, вы не можете переопределить операцию с путем:
-```Python hl_lines="6 11"
-{!../../../docs_src/path_params/tutorial003b.py!}
-```
+{* ../../docs_src/path_params/tutorial003b.py hl[6,11] *}
Первый будет выполняться всегда, так как путь совпадает первым.
@@ -136,23 +140,25 @@
Затем создайте атрибуты класса с фиксированными допустимыми значениями:
-```Python hl_lines="1 6-9"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[1,6:9] *}
-!!! info "Дополнительная информация"
- Перечисления (enum) доступны в Python начиная с версии 3.4.
+/// info | Дополнительная информация
-!!! tip "Подсказка"
- Если интересно, то "AlexNet", "ResNet" и "LeNet" - это названия моделей машинного обучения.
+Перечисления (enum) доступны в Python начиная с версии 3.4.
+
+///
+
+/// tip | Подсказка
+
+Если интересно, то "AlexNet", "ResNet" и "LeNet" - это названия моделей машинного обучения.
+
+///
### Определение *параметра пути*
Определите *параметр пути*, используя в аннотации типа класс перечисления (`ModelName`), созданный ранее:
-```Python hl_lines="16"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[16] *}
### Проверьте документацию
@@ -168,20 +174,19 @@
Вы можете сравнить это значение с *элементом перечисления* класса `ModelName`:
-```Python hl_lines="17"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[17] *}
#### Получение *значения перечисления*
Можно получить фактическое значение (в данном случае - `str`) с помощью `model_name.value` или в общем случае `your_enum_member.value`:
-```Python hl_lines="20"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[20] *}
-!!! tip "Подсказка"
- Значение `"lenet"` также можно получить с помощью `ModelName.lenet.value`.
+/// tip | Подсказка
+
+Значение `"lenet"` также можно получить с помощью `ModelName.lenet.value`.
+
+///
#### Возврат *элементов перечисления*
@@ -189,9 +194,7 @@
Они будут преобразованы в соответствующие значения (в данном случае - строки) перед их возвратом клиенту:
-```Python hl_lines="18 21 23"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[18,21,23] *}
Вы отправите клиенту такой JSON-ответ:
```JSON
@@ -229,14 +232,15 @@ OpenAPI не поддерживает способов объявления *п
Можете использовать так:
-```Python hl_lines="6"
-{!../../../docs_src/path_params/tutorial004.py!}
-```
+{* ../../docs_src/path_params/tutorial004.py hl[6] *}
-!!! tip "Подсказка"
- Возможно, вам понадобится, чтобы параметр содержал `/home/johndoe/myfile.txt` с ведущим слэшем (`/`).
+/// tip | Подсказка
- В этом случае URL будет таким: `/files//home/johndoe/myfile.txt`, с двойным слэшем (`//`) между `files` и `home`.
+Возможно, вам понадобится, чтобы параметр содержал `/home/johndoe/myfile.txt` с ведущим слэшем (`/`).
+
+В этом случае URL будет таким: `/files//home/johndoe/myfile.txt`, с двойным слэшем (`//`) между `files` и `home`.
+
+///
## Резюме
Используя **FastAPI** вместе со стандартными объявлениями типов Python (короткими и интуитивно понятными), вы получаете:
diff --git a/docs/ru/docs/tutorial/query-param-models.md b/docs/ru/docs/tutorial/query-param-models.md
new file mode 100644
index 000000000..4d76d09e8
--- /dev/null
+++ b/docs/ru/docs/tutorial/query-param-models.md
@@ -0,0 +1,68 @@
+# Модели Query-Параметров
+
+Если у вас есть группа связанных **query-параметров**, то вы можете объединить их в одну **Pydantic-модель**.
+
+Это позволит вам **переиспользовать модель** в **разных местах**, устанавливать валидаторы и метаданные, в том числе для сразу всех параметров, в одном месте. 😎
+
+/// note | Заметка
+
+Этот функционал доступен с версии `0.115.0`. 🤓
+
+///
+
+## Pydantic-Модель для Query-Параметров
+
+Объявите нужные **query-параметры** в **Pydantic-модели**, а после аннотируйте параметр как `Query`:
+
+{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *}
+
+**FastAPI извлечёт** данные соответствующие **каждому полю модели** из **query-параметров** запроса и выдаст вам объявленную Pydantic-модель заполненную ими.
+
+## Проверьте Сгенерированную Документацию
+
+Вы можете посмотреть query-параметры в графическом интерфейсе сгенерированной документации по пути `/docs`:
+
+
+POST.
+Но когда форма включает файлы, она кодируется как multipart/form-data. Если вы используете `File`, **FastAPI** будет знать, что ему нужно получить файлы из нужной части тела.
-!!! warning "Внимание"
- В операции *функции операции пути* можно объявить несколько параметров `File` и `Form`, но нельзя также объявлять поля `Body`, которые предполагается получить в виде JSON, поскольку тело запроса будет закодировано с помощью `multipart/form-data`, а не `application/json`.
+Если вы хотите узнать больше об этих кодировках и полях форм, перейдите по ссылке MDN web docs for POST.
- Это не является ограничением **FastAPI**, это часть протокола HTTP.
+///
+
+/// warning | Внимание
+
+В операции *функции операции пути* можно объявить несколько параметров `File` и `Form`, но нельзя также объявлять поля `Body`, которые предполагается получить в виде JSON, поскольку тело запроса будет закодировано с помощью `multipart/form-data`, а не `application/json`.
+
+Это не является ограничением **FastAPI**, это часть протокола HTTP.
+
+///
## Необязательная загрузка файлов
Вы можете сделать загрузку файла необязательной, используя стандартные аннотации типов и установив значение по умолчанию `None`:
-=== "Python 3.10+"
-
- ```Python hl_lines="9 17"
- {!> ../../../docs_src/request_files/tutorial001_02_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="9 17"
- {!> ../../../docs_src/request_files/tutorial001_02_an_py39.py!}
- ```
-
-=== "Python 3.6+"
-
- ```Python hl_lines="10 18"
- {!> ../../../docs_src/request_files/tutorial001_02_an.py!}
- ```
-
-=== "Python 3.10+ без Annotated"
-
- !!! tip "Подсказка"
- Предпочтительнее использовать версию с аннотацией, если это возможно.
-
- ```Python hl_lines="7 15"
- {!> ../../../docs_src/request_files/tutorial001_02_py310.py!}
- ```
-
-=== "Python 3.6+ без Annotated"
-
- !!! tip "Подсказка"
- Предпочтительнее использовать версию с аннотацией, если это возможно.
-
- ```Python hl_lines="9 17"
- {!> ../../../docs_src/request_files/tutorial001_02.py!}
- ```
+{* ../../docs_src/request_files/tutorial001_02_an_py310.py hl[9,17] *}
## `UploadFile` с дополнительными метаданными
Вы также можете использовать `File()` вместе с `UploadFile`, например, для установки дополнительных метаданных:
-=== "Python 3.9+"
-
- ```Python hl_lines="9 15"
- {!> ../../../docs_src/request_files/tutorial001_03_an_py39.py!}
- ```
-
-=== "Python 3.6+"
-
- ```Python hl_lines="8 14"
- {!> ../../../docs_src/request_files/tutorial001_03_an.py!}
- ```
-
-=== "Python 3.6+ без Annotated"
-
- !!! tip "Подсказка"
- Предпочтительнее использовать версию с аннотацией, если это возможно.
-
- ```Python hl_lines="7 13"
- {!> ../../../docs_src/request_files/tutorial001_03.py!}
- ```
+{* ../../docs_src/request_files/tutorial001_03_an_py39.py hl[9,15] *}
## Загрузка нескольких файлов
@@ -238,76 +149,23 @@ contents = myfile.file.read()
Для этого необходимо объявить список `bytes` или `UploadFile`:
-=== "Python 3.9+"
-
- ```Python hl_lines="10 15"
- {!> ../../../docs_src/request_files/tutorial002_an_py39.py!}
- ```
-
-=== "Python 3.6+"
-
- ```Python hl_lines="11 16"
- {!> ../../../docs_src/request_files/tutorial002_an.py!}
- ```
-
-=== "Python 3.9+ без Annotated"
-
- !!! tip "Подсказка"
- Предпочтительнее использовать версию с аннотацией, если это возможно.
-
- ```Python hl_lines="8 13"
- {!> ../../../docs_src/request_files/tutorial002_py39.py!}
- ```
-
-=== "Python 3.6+ без Annotated"
-
- !!! tip "Подсказка"
- Предпочтительнее использовать версию с аннотацией, если это возможно.
-
- ```Python hl_lines="10 15"
- {!> ../../../docs_src/request_files/tutorial002.py!}
- ```
+{* ../../docs_src/request_files/tutorial002_an_py39.py hl[10,15] *}
Вы получите, как и было объявлено, список `list` из `bytes` или `UploadFile`.
-!!! note "Technical Details"
- Можно также использовать `from starlette.responses import HTMLResponse`.
+/// note | Technical Details
- **FastAPI** предоставляет тот же `starlette.responses`, что и `fastapi.responses`, просто для удобства разработчика. Однако большинство доступных ответов поступает непосредственно из Starlette.
+Можно также использовать `from starlette.responses import HTMLResponse`.
+
+**FastAPI** предоставляет тот же `starlette.responses`, что и `fastapi.responses`, просто для удобства разработчика. Однако большинство доступных ответов поступает непосредственно из Starlette.
+
+///
### Загрузка нескольких файлов с дополнительными метаданными
Так же, как и раньше, вы можете использовать `File()` для задания дополнительных параметров, даже для `UploadFile`:
-=== "Python 3.9+"
-
- ```Python hl_lines="11 18-20"
- {!> ../../../docs_src/request_files/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.6+"
-
- ```Python hl_lines="12 19-21"
- {!> ../../../docs_src/request_files/tutorial003_an.py!}
- ```
-
-=== "Python 3.9+ без Annotated"
-
- !!! tip "Подсказка"
- Предпочтительнее использовать версию с аннотацией, если это возможно.
-
- ```Python hl_lines="9 16"
- {!> ../../../docs_src/request_files/tutorial003_py39.py!}
- ```
-
-=== "Python 3.6+ без Annotated"
-
- !!! tip "Подсказка"
- Предпочтительнее использовать версию с аннотацией, если это возможно.
-
- ```Python hl_lines="11 18"
- {!> ../../../docs_src/request_files/tutorial003.py!}
- ```
+{* ../../docs_src/request_files/tutorial003_an_py39.py hl[11,18:20] *}
## Резюме
diff --git a/docs/ru/docs/tutorial/request-form-models.md b/docs/ru/docs/tutorial/request-form-models.md
new file mode 100644
index 000000000..1034ed27f
--- /dev/null
+++ b/docs/ru/docs/tutorial/request-form-models.md
@@ -0,0 +1,78 @@
+# Модели форм
+
+Вы можете использовать **Pydantic-модели** для объявления **полей форм** в FastAPI.
+
+/// info | Дополнительная информация
+
+Чтобы использовать формы, сначала установите `python-multipart`.
+
+Убедитесь, что вы создали и активировали [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, а затем установите пакет, например:
+
+```console
+$ pip install python-multipart
+```
+
+///
+
+/// note | Заметка
+
+Этот функционал доступен с версии `0.113.0`. 🤓
+
+///
+
+## Pydantic-модель для формы
+
+Вам просто нужно объявить **Pydantic-модель** с полями, которые вы хотите получить как **поля формы**, а затем объявить параметр как `Form`:
+
+{* ../../docs_src/request_form_models/tutorial001_an_py39.py hl[9:11,15] *}
+
+**FastAPI** **извлечёт** данные для **каждого поля** из **данных формы** в запросе и выдаст вам объявленную Pydantic-модель.
+
+## Проверка сгенерированной документации
+
+Вы можете посмотреть поля формы в графическом интерфейсе Документации по пути `/docs`:
+
+
+
-!!! note "Примечание"
- Некоторые коды статуса ответа (см. следующий раздел) указывают на то, что ответ не имеет тела.
+/// note | Примечание
- FastAPI знает об этом и создаст документацию OpenAPI, в которой будет указано, что тело ответа отсутствует.
+Некоторые коды статуса ответа (см. следующий раздел) указывают на то, что ответ не имеет тела.
+
+FastAPI знает об этом и создаст документацию OpenAPI, в которой будет указано, что тело ответа отсутствует.
+
+///
## Об HTTP кодах статуса ответа
-!!! note "Примечание"
- Если вы уже знаете, что представляют собой HTTP коды статуса ответа, можете перейти к следующему разделу.
+/// note | Примечание
+
+Если вы уже знаете, что представляют собой HTTP коды статуса ответа, можете перейти к следующему разделу.
+
+///
В протоколе HTTP числовой код состояния из 3 цифр отправляется как часть ответа.
@@ -54,16 +64,17 @@
* Для общих ошибок со стороны клиента можно просто использовать код `400`.
* `5XX` – статус-коды, сообщающие о серверной ошибке. Они почти никогда не используются разработчиками напрямую. Когда что-то идет не так в какой-то части кода вашего приложения или на сервере, он автоматически вернёт один из 5XX кодов.
-!!! tip "Подсказка"
- Чтобы узнать больше о HTTP кодах статуса и о том, для чего каждый из них предназначен, ознакомьтесь с документацией MDN об HTTP кодах статуса ответа.
+/// tip | Подсказка
+
+Чтобы узнать больше о HTTP кодах статуса и о том, для чего каждый из них предназначен, ознакомьтесь с документацией MDN об HTTP кодах статуса ответа.
+
+///
## Краткие обозначения для запоминания названий кодов
Рассмотрим предыдущий пример еще раз:
-```Python hl_lines="6"
-{!../../../docs_src/response_status_code/tutorial001.py!}
-```
+{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
`201` – это код статуса "Создано".
@@ -71,18 +82,19 @@
Для удобства вы можете использовать переменные из `fastapi.status`.
-```Python hl_lines="1 6"
-{!../../../docs_src/response_status_code/tutorial002.py!}
-```
+{* ../../docs_src/response_status_code/tutorial002.py hl[1,6] *}
Они содержат те же числовые значения, но позволяют использовать подсказки редактора для выбора кода статуса:
-!!! note "Технические детали"
- Вы также можете использовать `from starlette import status` вместо `from fastapi import status`.
+/// note | Технические детали
- **FastAPI** позволяет использовать как `starlette.status`, так и `fastapi.status` исключительно для удобства разработчиков. Но поставляется fastapi.status непосредственно из Starlette.
+Вы также можете использовать `from starlette import status` вместо `from fastapi import status`.
+
+**FastAPI** позволяет использовать как `starlette.status`, так и `fastapi.status` исключительно для удобства разработчиков. Но поставляется fastapi.status непосредственно из Starlette.
+
+///
## Изменение кода статуса по умолчанию
diff --git a/docs/ru/docs/tutorial/schema-extra-example.md b/docs/ru/docs/tutorial/schema-extra-example.md
index e1011805a..f17b24349 100644
--- a/docs/ru/docs/tutorial/schema-extra-example.md
+++ b/docs/ru/docs/tutorial/schema-extra-example.md
@@ -8,24 +8,17 @@
Вы можете объявить ключ `example` для модели Pydantic, используя класс `Config` и переменную `schema_extra`, как описано в Pydantic документации: Настройка схемы:
-=== "Python 3.10+"
-
- ```Python hl_lines="13-21"
- {!> ../../../docs_src/schema_extra_example/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="15-23"
- {!> ../../../docs_src/schema_extra_example/tutorial001.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial001_py310.py hl[13:21] *}
Эта дополнительная информация будет включена в **JSON Schema** выходных данных для этой модели, и она будет использоваться в документации к API.
-!!! tip Подсказка
- Вы можете использовать тот же метод для расширения JSON-схемы и добавления своей собственной дополнительной информации.
+/// tip | Подсказка
- Например, вы можете использовать это для добавления дополнительной информации для пользовательского интерфейса в вашем веб-приложении и т.д.
+Вы можете использовать тот же метод для расширения JSON-схемы и добавления своей собственной дополнительной информации.
+
+Например, вы можете использовать это для добавления дополнительной информации для пользовательского интерфейса в вашем веб-приложении и т.д.
+
+///
## Дополнительные аргументы поля `Field`
@@ -33,20 +26,13 @@
Вы можете использовать это, чтобы добавить аргумент `example` для каждого поля:
-=== "Python 3.10+"
+{* ../../docs_src/schema_extra_example/tutorial002_py310.py hl[2,8:11] *}
- ```Python hl_lines="2 8-11"
- {!> ../../../docs_src/schema_extra_example/tutorial002_py310.py!}
- ```
+/// warning | Внимание
-=== "Python 3.8+"
+Имейте в виду, что эти дополнительные переданные аргументы не добавляют никакой валидации, только дополнительную информацию для документации.
- ```Python hl_lines="4 10-13"
- {!> ../../../docs_src/schema_extra_example/tutorial002.py!}
- ```
-
-!!! warning Внимание
- Имейте в виду, что эти дополнительные переданные аргументы не добавляют никакой валидации, только дополнительную информацию для документации.
+///
## Использование `example` и `examples` в OpenAPI
@@ -66,41 +52,7 @@
Здесь мы передаём аргумент `example`, как пример данных ожидаемых в параметре `Body()`:
-=== "Python 3.10+"
-
- ```Python hl_lines="22-27"
- {!> ../../../docs_src/schema_extra_example/tutorial003_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="22-27"
- {!> ../../../docs_src/schema_extra_example/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="23-28"
- {!> ../../../docs_src/schema_extra_example/tutorial003_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip Заметка
- Рекомендуется использовать версию с `Annotated`, если это возможно.
-
- ```Python hl_lines="18-23"
- {!> ../../../docs_src/schema_extra_example/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip Заметка
- Рекомендуется использовать версию с `Annotated`, если это возможно.
-
- ```Python hl_lines="20-25"
- {!> ../../../docs_src/schema_extra_example/tutorial003.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial003_an_py310.py hl[22:27] *}
### Аргумент "example" в UI документации
@@ -121,41 +73,7 @@
* `value`: Это конкретный пример, который отображается, например, в виде типа `dict`.
* `externalValue`: альтернатива параметру `value`, URL-адрес, указывающий на пример. Хотя это может не поддерживаться таким же количеством инструментов разработки и тестирования API, как параметр `value`.
-=== "Python 3.10+"
-
- ```Python hl_lines="23-49"
- {!> ../../../docs_src/schema_extra_example/tutorial004_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="23-49"
- {!> ../../../docs_src/schema_extra_example/tutorial004_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="24-50"
- {!> ../../../docs_src/schema_extra_example/tutorial004_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip Заметка
- Рекомендуется использовать версию с `Annotated`, если это возможно.
-
- ```Python hl_lines="19-45"
- {!> ../../../docs_src/schema_extra_example/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip Заметка
- Рекомендуется использовать версию с `Annotated`, если это возможно.
-
- ```Python hl_lines="21-47"
- {!> ../../../docs_src/schema_extra_example/tutorial004.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial004_an_py310.py hl[23:49] *}
### Аргумент "examples" в UI документации
@@ -165,10 +83,13 @@
## Технические Детали
-!!! warning Внимание
- Эти технические детали относятся к стандартам **JSON Schema** и **OpenAPI**.
+/// warning | Внимание
- Если предложенные выше идеи уже работают для вас, возможно этого будет достаточно и эти детали вам не потребуются, можете спокойно их пропустить.
+Эти технические детали относятся к стандартам **JSON Schema** и **OpenAPI**.
+
+Если предложенные выше идеи уже работают для вас, возможно этого будет достаточно и эти детали вам не потребуются, можете спокойно их пропустить.
+
+///
Когда вы добавляете пример внутрь модели Pydantic, используя `schema_extra` или `Field(example="something")`, этот пример добавляется в **JSON Schema** для данной модели Pydantic.
diff --git a/docs/ru/docs/tutorial/security/first-steps.md b/docs/ru/docs/tutorial/security/first-steps.md
index fdeccc01a..375c2d7f6 100644
--- a/docs/ru/docs/tutorial/security/first-steps.md
+++ b/docs/ru/docs/tutorial/security/first-steps.md
@@ -20,36 +20,19 @@
Скопируйте пример в файл `main.py`:
-=== "Python 3.9+"
-
- ```Python
- {!> ../../../docs_src/security/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python
- {!> ../../../docs_src/security/tutorial001_an.py!}
- ```
-
-=== "Python 3.8+ без Annotated"
-
- !!! tip "Подсказка"
- Предпочтительнее использовать версию с аннотацией, если это возможно.
-
- ```Python
- {!> ../../../docs_src/security/tutorial001.py!}
- ```
-
+{* ../../docs_src/security/tutorial001_an_py39.py *}
## Запуск
-!!! info "Дополнительная информация"
- Вначале, установите библиотеку `python-multipart`.
+/// info | Дополнительная информация
- А именно: `pip install python-multipart`.
+Вначале, установите библиотеку `python-multipart`.
- Это связано с тем, что **OAuth2** использует "данные формы" для передачи `имени пользователя` и `пароля`.
+А именно: `pip install python-multipart`.
+
+Это связано с тем, что **OAuth2** использует "данные формы" для передачи `имени пользователя` и `пароля`.
+
+///
Запустите ваш сервер:
@@ -71,17 +54,23 @@ $ uvicorn main:app --reload
-!!! check "Кнопка авторизации!"
- У вас уже появилась новая кнопка "Authorize".
+/// check | Кнопка авторизации!
- А у *операции пути* теперь появился маленький замочек в правом верхнем углу, на который можно нажать.
+У вас уже появилась новая кнопка "Authorize".
+
+А у *операции пути* теперь появился маленький замочек в правом верхнем углу, на который можно нажать.
+
+///
При нажатии на нее появляется небольшая форма авторизации, в которую нужно ввести `имя пользователя` и `пароль` (и другие необязательные поля):
-!!! note "Технические детали"
- Неважно, что вы введете в форму, она пока не будет работать. Но мы к этому еще придем.
+/// note | Технические детали
+
+Неважно, что вы введете в форму, она пока не будет работать. Но мы к этому еще придем.
+
+///
Конечно, это не фронтенд для конечных пользователей, но это отличный автоматический инструмент для интерактивного документирования всех ваших API.
@@ -123,51 +112,41 @@ OAuth2 был разработан для того, чтобы бэкэнд ил
В данном примере мы будем использовать **OAuth2**, с аутентификацией по паролю, используя токен **Bearer**. Для этого мы используем класс `OAuth2PasswordBearer`.
-!!! info "Дополнительная информация"
- Токен "bearer" - не единственный вариант, но для нашего случая он является наилучшим.
+/// info | Дополнительная информация
- И это может быть лучшим вариантом для большинства случаев использования, если только вы не являетесь экспертом в области OAuth2 и точно знаете, почему вам лучше подходит какой-то другой вариант.
+Токен "bearer" - не единственный вариант, но для нашего случая он является наилучшим.
- В этом случае **FastAPI** также предоставляет инструменты для его реализации.
+И это может быть лучшим вариантом для большинства случаев использования, если только вы не являетесь экспертом в области OAuth2 и точно знаете, почему вам лучше подходит какой-то другой вариант.
+
+В этом случае **FastAPI** также предоставляет инструменты для его реализации.
+
+///
При создании экземпляра класса `OAuth2PasswordBearer` мы передаем в него параметр `tokenUrl`. Этот параметр содержит URL, который клиент (фронтенд, работающий в браузере пользователя) будет использовать для отправки `имени пользователя` и `пароля` с целью получения токена.
-=== "Python 3.9+"
+{* ../../docs_src/security/tutorial001_an_py39.py hl[8] *}
- ```Python hl_lines="8"
- {!> ../../../docs_src/security/tutorial001_an_py39.py!}
- ```
+/// tip | Подсказка
-=== "Python 3.8+"
+Здесь `tokenUrl="token"` ссылается на относительный URL `token`, который мы еще не создали. Поскольку это относительный URL, он эквивалентен `./token`.
- ```Python hl_lines="7"
- {!> ../../../docs_src/security/tutorial001_an.py!}
- ```
+Поскольку мы используем относительный URL, если ваш API расположен по адресу `https://example.com/`, то он будет ссылаться на `https://example.com/token`. Если же ваш API расположен по адресу `https://example.com/api/v1/`, то он будет ссылаться на `https://example.com/api/v1/token`.
-=== "Python 3.8+ без Annotated"
+Использование относительного URL важно для того, чтобы ваше приложение продолжало работать даже в таких сложных случаях, как оно находится [за прокси-сервером](../../advanced/behind-a-proxy.md){.internal-link target=_blank}.
- !!! tip "Подсказка"
- Предпочтительнее использовать версию с аннотацией, если это возможно.
-
- ```Python hl_lines="6"
- {!> ../../../docs_src/security/tutorial001.py!}
- ```
-
-!!! tip "Подсказка"
- Здесь `tokenUrl="token"` ссылается на относительный URL `token`, который мы еще не создали. Поскольку это относительный URL, он эквивалентен `./token`.
-
- Поскольку мы используем относительный URL, если ваш API расположен по адресу `https://example.com/`, то он будет ссылаться на `https://example.com/token`. Если же ваш API расположен по адресу `https://example.com/api/v1/`, то он будет ссылаться на `https://example.com/api/v1/token`.
-
- Использование относительного URL важно для того, чтобы ваше приложение продолжало работать даже в таких сложных случаях, как оно находится [за прокси-сервером](../../advanced/behind-a-proxy.md){.internal-link target=_blank}.
+///
Этот параметр не создает конечную точку / *операцию пути*, а объявляет, что URL `/token` будет таким, который клиент должен использовать для получения токена. Эта информация используется в OpenAPI, а затем в интерактивных системах документации API.
Вскоре мы создадим и саму операцию пути.
-!!! info "Дополнительная информация"
- Если вы очень строгий "питонист", то вам может не понравиться стиль названия параметра `tokenUrl` вместо `token_url`.
+/// info | Дополнительная информация
- Это связано с тем, что тут используется то же имя, что и в спецификации OpenAPI. Таким образом, если вам необходимо более подробно изучить какую-либо из этих схем безопасности, вы можете просто использовать копирование/вставку, чтобы найти дополнительную информацию о ней.
+Если вы очень строгий "питонист", то вам может не понравиться стиль названия параметра `tokenUrl` вместо `token_url`.
+
+Это связано с тем, что тут используется то же имя, что и в спецификации OpenAPI. Таким образом, если вам необходимо более подробно изучить какую-либо из этих схем безопасности, вы можете просто использовать копирование/вставку, чтобы найти дополнительную информацию о ней.
+
+///
Переменная `oauth2_scheme` является экземпляром `OAuth2PasswordBearer`, но она также является "вызываемой".
@@ -183,35 +162,19 @@ oauth2_scheme(some, parameters)
Теперь вы можете передать ваш `oauth2_scheme` в зависимость с помощью `Depends`.
-=== "Python 3.9+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/security/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="11"
- {!> ../../../docs_src/security/tutorial001_an.py!}
- ```
-
-=== "Python 3.8+ без Annotated"
-
- !!! tip "Подсказка"
- Предпочтительнее использовать версию с аннотацией, если это возможно.
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/security/tutorial001.py!}
- ```
+{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *}
Эта зависимость будет предоставлять `строку`, которая присваивается параметру `token` в *функции операции пути*.
**FastAPI** будет знать, что он может использовать эту зависимость для определения "схемы безопасности" в схеме OpenAPI (и автоматической документации по API).
-!!! info "Технические детали"
- **FastAPI** будет знать, что он может использовать класс `OAuth2PasswordBearer` (объявленный в зависимости) для определения схемы безопасности в OpenAPI, поскольку он наследуется от `fastapi.security.oauth2.OAuth2`, который, в свою очередь, наследуется от `fastapi.security.base.SecurityBase`.
+/// info | Технические детали
- Все утилиты безопасности, интегрируемые в OpenAPI (и автоматическая документация по API), наследуются от `SecurityBase`, поэтому **FastAPI** может знать, как интегрировать их в OpenAPI.
+**FastAPI** будет знать, что он может использовать класс `OAuth2PasswordBearer` (объявленный в зависимости) для определения схемы безопасности в OpenAPI, поскольку он наследуется от `fastapi.security.oauth2.OAuth2`, который, в свою очередь, наследуется от `fastapi.security.base.SecurityBase`.
+
+Все утилиты безопасности, интегрируемые в OpenAPI (и автоматическая документация по API), наследуются от `SecurityBase`, поэтому **FastAPI** может знать, как интегрировать их в OpenAPI.
+
+///
## Что он делает
@@ -219,7 +182,7 @@ oauth2_scheme(some, parameters)
Если он не видит заголовка `Authorization` или значение не имеет токена `Bearer`, то в ответ будет выдана ошибка с кодом состояния 401 (`UNAUTHORIZED`).
-Для возврата ошибки даже не нужно проверять, существует ли токен. Вы можете быть уверены, что если ваша функция будет выполнилась, то в этом токене есть `строка`.
+Для возврата ошибки даже не нужно проверять, существует ли токен. Вы можете быть уверены, что если ваша функция была выполнена, то в этом токене есть `строка`.
Проверить это можно уже сейчас в интерактивной документации:
diff --git a/docs/ru/docs/tutorial/security/get-current-user.md b/docs/ru/docs/tutorial/security/get-current-user.md
new file mode 100644
index 000000000..05eb290d7
--- /dev/null
+++ b/docs/ru/docs/tutorial/security/get-current-user.md
@@ -0,0 +1,99 @@
+# Данные текущего пользователя
+
+В предыдущей главе система безопасности (основанная на системе внедрения зависимостей) передавала *функции, обрабатывающей эндпоинт,* `токен` в виде `строки`:
+
+{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *}
+
+Это пока что не слишком нам полезно. Давайте изменим код так, чтобы он возвращал нам данные пользователя, отправившего запрос.
+
+## Создание модели пользователя
+
+Сначала создадим Pydantic-модель пользователя.
+
+Точно так же, как мы использовали Pydantic для объявления тел запросов, мы можем использовать его где угодно:
+
+{* ../../docs_src/security/tutorial002_an_py310.py hl[5,12:6] *}
+
+## Создание зависимости `get_current_user`
+
+Давайте создадим зависимость `get_current_user`.
+
+Помните, что у зависимостей могут быть подзависимости?
+
+`get_current_user` как раз будет иметь подзависимость `oauth2_scheme`, которую мы создали ранее.
+
+Аналогично тому, как мы делали это ранее в *обработчике эндпоинта* наша новая зависимость `get_current_user` будет получать `token` в виде `строки` от подзависимости `oauth2_scheme`:
+
+{* ../../docs_src/security/tutorial002_an_py310.py hl[25] *}
+
+## Получение данных пользователя
+
+`get_current_user` будет использовать созданную нами (ненастоящую) служебную функцию, которая принимает токен в виде `строки` и возвращает нашу Pydantic-модель `User`:
+
+{* ../../docs_src/security/tutorial002_an_py310.py hl[19:22,26:27] *}
+
+## Внедрение зависимости текущего пользователя
+
+Теперь мы можем использовать тот же `Depends` с нашей зависимостью `get_current_user` в *функции обрабатывающей эндпоинт*:
+
+{* ../../docs_src/security/tutorial002_an_py310.py hl[31] *}
+
+Обратите внимание, что мы объявляем тип переменной `current_user` как Pydantic-модель `User`.
+
+Это поможет выполнить внутри функции все проверки автозаполнения и типа.
+
+/// tip | Подсказка
+Возможно, вы помните, что тело запроса также объявляется с помощью Pydantic-моделей.
+
+В этом месте у **FastAPI** не возникнет проблем, потому что вы используете `Depends`.
+///
+
+/// check | Заметка
+То, как устроена эта система зависимостей, позволяет нам иметь различные зависимости, которые возвращают модель `User`.
+
+Мы не ограничены наличием только одной зависимости, которая может возвращать данные такого типа.
+///
+
+## Другие модели
+
+Теперь вы можете получать информацию о текущем пользователе непосредственно в *функции обрабатывающей эндпоинт* и работать с механизмами безопасности на уровне **Внедрения Зависимостей**, используя `Depends`.
+
+Причем для обеспечения требований безопасности можно использовать любую модель или данные (в данном случае - Pydantic-модель `User`).
+
+Но вы не ограничены использованием какой-то конкретной моделью данных, классом или типом.
+
+Вы хотите использовать в модели `id` и `email`, а `username` вам не нужен? Ну разумеется. Воспользуйтесь тем же инструментарием.
+
+Вам нужны только `строки`? Или только `словари`? Или непосредственно экземпляр модели класса базы данных? Все это работает точно также.
+
+У вас нет пользователей, которые входят в ваше приложение, а только роботы, боты или другие системы, у которых есть только токен доступа? Опять же, все работает одинаково.
+
+Просто используйте любую модель, любой класс, любую базу данных, которые нужны для вашего приложения. Система внедрения зависимостей **FastAPI** поможет вам в этом.
+
+## Размер кода
+
+Этот пример может показаться многословным. Следует иметь в виду, что в одном файле мы смешиваем безопасность, модели данных, служебные функции и *эндпоинты*.
+
+Но вот ключевой момент:
+
+Все, что касается безопасности и внедрения зависимостей, пишется один раз.
+
+И вы можете сделать его настолько сложным, насколько захотите. И все это будет написано только один раз, в одном месте, со всей своей гибкостью.
+
+И у вас могут быть тысячи конечных точек (*эндпоинтов*), использующих одну и ту же систему безопасности.
+
+И все они (или любая их часть по вашему желанию) могут воспользоваться преимуществами повторного использования этих зависимостей или любых других зависимостей, которые вы создадите.
+
+И все эти тысячи *эндпоинтов* могут составлять всего 3 строки:
+
+{* ../../docs_src/security/tutorial002_an_py310.py hl[30:32] *}
+
+## Резюме
+
+Теперь вы можете получать данные о текущем пользователе непосредственно в своей *функции обработчике эндпоинта*.
+
+Мы уже на полпути к этому.
+
+Осталось лишь добавить *эндпоинт* для отправки пользователем/клиентом своих `имени пользователя` и `пароля`.
+
+Это будет рассмотрено в следующем разделе.
diff --git a/docs/ru/docs/tutorial/security/index.md b/docs/ru/docs/tutorial/security/index.md
index d5fe4e76f..e4969c4cf 100644
--- a/docs/ru/docs/tutorial/security/index.md
+++ b/docs/ru/docs/tutorial/security/index.md
@@ -32,9 +32,11 @@ OAuth2 включает в себя способы аутентификации
OAuth2 не указывает, как шифровать сообщение, он ожидает, что ваше приложение будет обслуживаться по протоколу HTTPS.
-!!! tip "Подсказка"
- В разделе **Развертывание** вы увидите [как настроить протокол HTTPS бесплатно, используя Traefik и Let's Encrypt.](https://fastapi.tiangolo.com/ru/deployment/https/)
+/// tip | Подсказка
+В разделе **Развертывание** вы увидите [как настроить протокол HTTPS бесплатно, используя Traefik и Let's Encrypt.](https://fastapi.tiangolo.com/ru/deployment/https/)
+
+///
## OpenID Connect
@@ -87,10 +89,13 @@ OpenAPI может использовать следующие схемы авт
* Это автоматическое обнаружение определено в спецификации OpenID Connect.
-!!! tip "Подсказка"
- Интеграция сторонних сервисов для аутентификации/авторизации таких как Google, Facebook, Twitter, GitHub и т.д. осуществляется достаточно легко.
+/// tip | Подсказка
- Самой сложной проблемой является создание такого провайдера аутентификации/авторизации, но **FastAPI** предоставляет вам инструменты, позволяющие легко это сделать, выполняя при этом всю тяжелую работу за вас.
+Интеграция сторонних сервисов для аутентификации/авторизации таких как Google, Facebook, Twitter, GitHub и т.д. осуществляется достаточно легко.
+
+Самой сложной проблемой является создание такого провайдера аутентификации/авторизации, но **FastAPI** предоставляет вам инструменты, позволяющие легко это сделать, выполняя при этом всю тяжелую работу за вас.
+
+///
## Преимущества **FastAPI**
diff --git a/docs/ru/docs/tutorial/security/oauth2-jwt.md b/docs/ru/docs/tutorial/security/oauth2-jwt.md
new file mode 100644
index 000000000..1195fad21
--- /dev/null
+++ b/docs/ru/docs/tutorial/security/oauth2-jwt.md
@@ -0,0 +1,261 @@
+# OAuth2 с паролем (и хешированием), Bearer с JWT-токенами
+
+Теперь, когда у нас определен процесс обеспечения безопасности, давайте сделаем приложение действительно безопасным, используя токены JWT и безопасное хеширование паролей.
+
+Этот код можно реально использовать в своем приложении, сохранять хэши паролей в базе данных и т.д.
+
+Мы продолжим разбираться, начиная с того места, на котором остановились в предыдущей главе.
+
+## Про JWT
+
+JWT означает "JSON Web Tokens".
+
+Это стандарт для кодирования JSON-объекта в виде длинной строки без пробелов. Выглядит это следующим образом:
+
+```
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+```
+
+Он не зашифрован, поэтому любой человек может восстановить информацию из его содержимого.
+
+Но он подписан. Следовательно, когда вы получаете токен, который вы эмитировали (выдавали), вы можете убедиться, что это именно вы его эмитировали.
+
+Таким образом, можно создать токен со сроком действия, скажем, 1 неделя. А когда пользователь вернется на следующий день с тем же токеном, вы будете знать, что он все еще авторизирован в вашей системе.
+
+Через неделю срок действия токена истечет, пользователь не будет авторизован и ему придется заново входить в систему, чтобы получить новый токен. А если пользователь (или третье лицо) попытается модифицировать токен, чтобы изменить срок действия, вы сможете это обнаружить, поскольку подписи не будут совпадать.
+
+Если вы хотите поиграть с JWT-токенами и посмотреть, как они работают, посмотрите https://jwt.io.
+
+## Установка `PyJWT`
+
+Нам необходимо установить `pyjwt` для генерации и проверки JWT-токенов на языке Python.
+
+Убедитесь, что вы создали [виртуальное окружение](../../virtual-environments.md){.internal-link target=_blank}, активируйте его, а затем установите `pyjwt`:
+
+
+
+Пройдите авторизацию так же, как делали раньше.
+
+Используя учетные данные пользователя:
+
+Username: `johndoe`
+Password: `secret`
+
+/// check | Заметка
+Обратите внимание, что нигде в коде не используется открытый текст пароля "`secret`", мы используем только его хэшированную версию.
+///
+
+
+
+Вызвав эндпоинт `/users/me/`, вы получите ответ в виде:
+
+```JSON
+{
+ "username": "johndoe",
+ "email": "johndoe@example.com",
+ "full_name": "John Doe",
+ "disabled": false
+}
+```
+
+
+
+Если открыть инструменты разработчика, то можно увидеть, что передаваемые данные включают только токен, пароль передается только в первом запросе для аутентификации пользователя и получения токена доступа, но не в последующих:
+
+
+
+/// note | Техническая информация
+Обратите внимание на заголовок `Authorization`, значение которого начинается с `Bearer`.
+///
+
+## Продвинутое использование `scopes`
+
+В OAuth2 существует понятие "диапазоны" ("`scopes`").
+
+С их помощью можно добавить определенный набор разрешений к JWT-токену.
+
+Затем вы можете передать этот токен непосредственно пользователю или третьей стороне для взаимодействия с вашим API с определенным набором ограничений.
+
+О том, как их использовать и как они интегрированы в **FastAPI**, читайте далее в **Руководстве пользователя**.
+
+## Резюме
+
+С учетом того, что вы видели до сих пор, вы можете создать безопасное приложение **FastAPI**, используя такие стандарты, как OAuth2 и JWT.
+
+Практически в любом фреймворке работа с безопасностью довольно быстро превращается в сложную тему.
+
+Многие пакеты, сильно упрощающие эту задачу, вынуждены идти на многочисленные компромиссы с моделью данных, с базой данных и с доступным функционалом. Некоторые из этих пакетов, которые пытаются уж слишком все упростить, имеют даже "дыры" в системе безопасности.
+
+---
+
+**FastAPI** не делает уступок ни одной базе данных, модели данных или инструментарию.
+
+Он предоставляет вам полную свободу действий, позволяя выбирать то, что лучше всего подходит для вашего проекта.
+
+Вы можете напрямую использовать многие хорошо поддерживаемые и широко распространенные пакеты, такие как `passlib` и `PyJWT`, поскольку **FastAPI** не требует сложных механизмов для интеграции внешних пакетов.
+
+Напротив, он предоставляет инструменты, позволяющие максимально упростить этот процесс без ущерба для гибкости, надежности и безопасности.
+
+При этом вы можете использовать и реализовывать безопасные стандартные протоколы, такие как OAuth2, относительно простым способом.
+
+В **Руководстве пользователя** вы можете узнать больше о том, как использовать "диапазоны" ("`scopes`") OAuth2 для создания более точно настроенной системы разрешений в соответствии с теми же стандартами. OAuth2 с диапазонами - это механизм, используемый многими крупными провайдерами сервиса аутентификации, такими как Facebook, Google, GitHub, Microsoft, Twitter и др., для авторизации сторонних приложений на взаимодействие с их API от имени их пользователей.
diff --git a/docs/ru/docs/tutorial/security/simple-oauth2.md b/docs/ru/docs/tutorial/security/simple-oauth2.md
new file mode 100644
index 000000000..9732265cc
--- /dev/null
+++ b/docs/ru/docs/tutorial/security/simple-oauth2.md
@@ -0,0 +1,272 @@
+# Простая авторизация по протоколу OAuth2 с токеном типа Bearer
+
+Теперь, отталкиваясь от предыдущей главы, добавим недостающие части, чтобы получить безопасную систему.
+
+## Получение `имени пользователя` и `пароля`
+
+Для получения `имени пользователя` и `пароля` мы будем использовать утилиты безопасности **FastAPI**.
+
+Протокол OAuth2 определяет, что при использовании "аутентификации по паролю" (которую мы и используем) клиент/пользователь должен передавать поля `username` и `password` в полях формы.
+
+В спецификации сказано, что поля должны быть названы именно так. Поэтому `user-name` или `email` работать не будут.
+
+Но не волнуйтесь, вы можете показать его конечным пользователям во фронтенде в том виде, в котором хотите.
+
+А ваши модели баз данных могут использовать любые другие имена.
+
+Но при авторизации согласно спецификации, требуется использовать именно эти имена, что даст нам возможность воспользоваться встроенной системой документации API.
+
+В спецификации также указано, что `username` и `password` должны передаваться в виде данных формы (так что никакого JSON здесь нет).
+
+### Oбласть видимости (scope)
+
+В спецификации также говорится, что клиент может передать еще одно поле формы "`scope`".
+
+Имя поля формы - `scope` (в единственном числе), но на самом деле это длинная строка, состоящая из отдельных областей видимости (scopes), разделенных пробелами.
+
+Каждая "область видимости" (scope) - это просто строка (без пробелов).
+
+Обычно они используются для указания уровней доступа, например:
+
+* `users:read` или `users:write` являются распространенными примерами.
+* `instagram_basic` используется Facebook / Instagram.
+* `https://www.googleapis.com/auth/drive` используется компанией Google.
+
+/// info | Дополнительнаяя информация
+В OAuth2 "scope" - это просто строка, которая уточняет уровень доступа.
+
+Не имеет значения, содержит ли он другие символы, например `:`, или является ли он URL.
+
+Эти детали зависят от конкретной реализации.
+
+Для OAuth2 это просто строки.
+///
+
+## Код получения `имени пользователя` и `пароля`
+
+Для решения задачи давайте воспользуемся утилитами, предоставляемыми **FastAPI**.
+
+### `OAuth2PasswordRequestForm`
+
+Сначала импортируйте `OAuth2PasswordRequestForm` и затем используйте ее как зависимость с `Depends` в *эндпоинте* `/token`:
+
+
+{* ../../docs_src/security/tutorial003_an_py310.py hl[4,78] *}
+
+`OAuth2PasswordRequestForm` - это класс для использования в качестве зависимости для *функции обрабатывающей эндпоинт*, который определяет тело формы со следующими полями:
+
+* `username`.
+* `password`.
+* Необязательное поле `scope` в виде большой строки, состоящей из строк, разделенных пробелами.
+* Необязательное поле `grant_type`.
+
+/// tip | Подсказка
+По спецификации OAuth2 поле `grant_type` является обязательным и содержит фиксированное значение `password`, но `OAuth2PasswordRequestForm` не обеспечивает этого.
+
+Если вам необходимо использовать `grant_type`, воспользуйтесь `OAuth2PasswordRequestFormStrict` вместо `OAuth2PasswordRequestForm`.
+///
+
+* Необязательное поле `client_id` (в нашем примере он не нужен).
+* Необязательное поле `client_secret` (в нашем примере он не нужен).
+
+/// info | Дополнительная информация
+Форма `OAuth2PasswordRequestForm` не является специальным классом для **FastAPI**, как `OAuth2PasswordBearer`.
+
+`OAuth2PasswordBearer` указывает **FastAPI**, что это схема безопасности. Следовательно, она будет добавлена в OpenAPI.
+
+Но `OAuth2PasswordRequestForm` - это всего лишь класс зависимости, который вы могли бы написать самостоятельно или вы могли бы объявить параметры `Form` напрямую.
+
+Но, поскольку это распространённый вариант использования, он предоставляется **FastAPI** напрямую, просто чтобы облегчить задачу.
+///
+
+### Использование данных формы
+
+/// tip | Подсказка
+В экземпляре зависимого класса `OAuth2PasswordRequestForm` атрибут `scope`, состоящий из одной длинной строки, разделенной пробелами, заменен на атрибут `scopes`, состоящий из списка отдельных строк, каждая из которых соответствует определенному уровню доступа.
+
+В данном примере мы не используем `scopes`, но если вам это необходимо, то такая функциональность имеется.
+///
+
+Теперь получим данные о пользователе из (ненастоящей) базы данных, используя `username` из поля формы.
+
+Если такого пользователя нет, то мы возвращаем ошибку "неверное имя пользователя или пароль".
+
+Для ошибки мы используем исключение `HTTPException`:
+
+{* ../../docs_src/security/tutorial003_an_py310.py hl[3,79:81] *}
+
+### Проверка пароля
+
+На данный момент у нас есть данные о пользователе из нашей базы данных, но мы еще не проверили пароль.
+
+Давайте сначала поместим эти данные в модель Pydantic `UserInDB`.
+
+Ни в коем случае нельзя сохранять пароли в открытом виде, поэтому мы будем использовать (пока что ненастоящую) систему хеширования паролей.
+
+Если пароли не совпадают, мы возвращаем ту же ошибку.
+
+#### Хеширование паролей
+
+"Хеширование" означает: преобразование некоторого содержимого (в данном случае пароля) в последовательность байтов (просто строку), которая выглядит как тарабарщина.
+
+Каждый раз, когда вы передаете точно такое же содержимое (точно такой же пароль), вы получаете точно такую же тарабарщину.
+
+Но преобразовать тарабарщину обратно в пароль невозможно.
+
+##### Зачем использовать хеширование паролей
+
+Если ваша база данных будет украдена, то у вора не будет паролей пользователей в открытом виде, только хэши.
+
+Таким образом, вор не сможет использовать эти же пароли в другой системе (поскольку многие пользователи используют одни и те же пароли повсеместно, это было бы опасно).
+
+{* ../../docs_src/security/tutorial003_an_py310.py hl[82:85] *}
+
+#### Про `**user_dict`
+
+`UserInDB(**user_dict)` означает:
+
+*Передавать ключи и значения `user_dict` непосредственно в качестве аргументов ключ-значение, что эквивалентно:*
+
+```Python
+UserInDB(
+ username = user_dict["username"],
+ email = user_dict["email"],
+ full_name = user_dict["full_name"],
+ disabled = user_dict["disabled"],
+ hashed_password = user_dict["hashed_password"],
+)
+```
+
+/// info | Дополнительная информация
+Более полное объяснение `**user_dict` можно найти в [документации к **Дополнительным моделям**](../extra-models.md#about-user_indict){.internal-link target=_blank}.
+///
+
+## Возврат токена
+
+Ответ эндпоинта `token` должен представлять собой объект в формате JSON.
+
+Он должен иметь `token_type`. В нашем случае, поскольку мы используем токены типа "Bearer", тип токена должен быть "`bearer`".
+
+И в нем должна быть строка `access_token`, содержащая наш токен доступа.
+
+В этом простом примере мы нарушим все правила безопасности, и будем считать, что имя пользователя (username) полностью соответствует токену (token)
+
+/// tip | Подсказка
+В следующей главе мы рассмотрим реальную защищенную реализацию с хешированием паролей и токенами JWT.
+
+Но пока давайте остановимся на необходимых нам деталях.
+///
+
+{* ../../docs_src/security/tutorial003_an_py310.py hl[87] *}
+
+/// tip | Подсказка
+Согласно спецификации, вы должны возвращать JSON с `access_token` и `token_type`, как в данном примере.
+
+Это то, что вы должны сделать сами в своем коде и убедиться, что вы используете эти JSON-ключи.
+
+Это практически единственное, что нужно не забывать делать самостоятельно, чтобы следовать требованиям спецификации.
+
+Все остальное за вас сделает **FastAPI**.
+///
+
+## Обновление зависимостей
+
+Теперь мы обновим наши зависимости.
+
+Мы хотим получить значение `current_user` *только* если этот пользователь активен.
+
+Поэтому мы создаем дополнительную зависимость `get_current_active_user`, которая, в свою очередь, использует в качестве зависимости `get_current_user`.
+
+Обе эти зависимости просто вернут HTTP-ошибку, если пользователь не существует или неактивен.
+
+Таким образом, в нашем эндпоинте мы получим пользователя только в том случае, если он существует, правильно аутентифицирован и активен:
+
+{* ../../docs_src/security/tutorial003_an_py310.py hl[58:66,69:74,94] *}
+
+/// info | Дополнительная информация
+Дополнительный заголовок `WWW-Authenticate` со значением `Bearer`, который мы здесь возвращаем, также является частью спецификации.
+
+Ответ сервера с HTTP-кодом 401 "UNAUTHORIZED" должен также возвращать заголовок `WWW-Authenticate`.
+
+В случае с bearer-токенами (наш случай) значение этого заголовка должно быть `Bearer`.
+
+На самом деле этот дополнительный заголовок можно пропустить и все будет работать.
+
+Но он приведён здесь для соответствия спецификации.
+
+Кроме того, могут существовать инструменты, которые ожидают его и могут использовать, и это может быть полезно для вас или ваших пользователей сейчас или в будущем.
+
+В этом и заключается преимущество стандартов...
+///
+
+## Посмотим как это работает
+
+Откроем интерактивную документацию: http://127.0.0.1:8000/docs.
+
+### Аутентификация
+
+Нажмите кнопку "Авторизация".
+
+Используйте учётные данные:
+
+Пользователь: `johndoe`
+
+Пароль: `secret`
+
+
+
+После авторизации в системе вы увидите следующее:
+
+
+
+### Получение собственных пользовательских данных
+
+Теперь, используя операцию `GET` с путем `/users/me`, вы получите данные пользователя, например:
+
+```JSON
+{
+ "username": "johndoe",
+ "email": "johndoe@example.com",
+ "full_name": "John Doe",
+ "disabled": false,
+ "hashed_password": "fakehashedsecret"
+}
+```
+
+
+
+Если щелкнуть на значке замка и выйти из системы, а затем попытаться выполнить ту же операцию ещё раз, то будет выдана ошибка HTTP 401:
+
+```JSON
+{
+ "detail": "Not authenticated"
+}
+```
+
+### Неактивный пользователь
+
+Теперь попробуйте пройти аутентификацию с неактивным пользователем:
+
+Пользователь: `alice`
+
+Пароль: `secret2`
+
+И попробуйте использовать операцию `GET` с путем `/users/me`.
+
+Вы получите ошибку "Inactive user", как тут:
+
+```JSON
+{
+ "detail": "Inactive user"
+}
+```
+
+## Резюме
+
+Теперь у вас есть инструменты для реализации полноценной системы безопасности на основе `имени пользователя` и `пароля` для вашего API.
+
+Используя эти средства, можно сделать систему безопасности совместимой с любой базой данных, с любым пользователем или моделью данных.
+
+ Единственным недостатком нашей системы является то, что она всё ещё не защищена.
+
+В следующей главе вы увидите, как использовать библиотеку безопасного хеширования паролей и токены JWT.
diff --git a/docs/ru/docs/tutorial/sql-databases.md b/docs/ru/docs/tutorial/sql-databases.md
new file mode 100644
index 000000000..b127e44d5
--- /dev/null
+++ b/docs/ru/docs/tutorial/sql-databases.md
@@ -0,0 +1,358 @@
+# SQL (реляционные) базы данных
+
+**FastAPI** не требует использования реляционной базы данных. Вы можете воспользоваться любой базой данных, которой хотите.
+
+В этом разделе мы продемонстрируем, как работать с SQLModel.
+
+Библиотека **SQLModel** построена на основе SQLAlchemy и Pydantic. Она была разработана автором **FastAPI** специально для приложений на основе FastAPI, которые используют **реляционные базы данных**.
+
+/// tip | Подсказка
+
+Вы можете воспользоваться любой библиотекой для работы с реляционными (SQL) или нереляционными (NoSQL) базами данных. (Их ещё называют **ORM** библиотеками). FastAPI не принуждает вас к использованию чего-либо конкретного. 😎
+
+///
+
+В основе SQLModel лежит SQLAlchemy, поэтому вы спокойно можете использовать любую базу данных, поддерживаемую SQLAlchemy (и, соответственно, поддерживаемую SQLModel), например:
+
+* PostgreSQL
+* MySQL
+* SQLite
+* Oracle
+* Microsoft SQL Server, и т.д.
+
+В данном примере мы будем использовать базу данных **SQLite**, т.к. она состоит из единственного файла и поддерживается встроенными библиотеками Python. Таким образом, вы сможете скопировать данный пример и запустить его как он есть.
+
+В дальнейшем, для продакшн-версии вашего приложения, возможно, вам стоит использовать серверную базу данных, например, **PostgreSQL**.
+
+/// tip | Подсказка
+
+Существует официальный генератор проектов на **FastAPI** и **PostgreSQL**, который также включает frontend и дополнительные инструменты https://github.com/fastapi/full-stack-fastapi-template
+
+///
+
+Это очень простое и короткое руководство, поэтому, если вы хотите узнать о базах данных в целом, об SQL, разобраться с более продвинутым функционалом, то воспользуйтесь документацией SQLModel.
+
+## Установка `SQLModel`
+
+Создайте виртуальное окружение [virtual environment](../virtual-environments.md){.internal-link target=_blank}, активируйте его и установите `sqlmodel`:
+
+
+
+
-
+
@@ -449,7 +449,7 @@ Daha fazla bilgi için, bu bölüme bir göz at
email_validator - email doğrulaması için.
+* email-validator - email doğrulaması için.
* pydantic-settings - ayar yönetimi için.
* pydantic-extra-types - Pydantic ile birlikte kullanılabilecek ek tipler için.
diff --git a/docs/tr/docs/newsletter.md b/docs/tr/docs/newsletter.md
deleted file mode 100644
index 22ca1b1e2..000000000
--- a/docs/tr/docs/newsletter.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# FastAPI ve Arkadaşları Bülteni
-
-
-
-
diff --git a/docs/tr/docs/python-types.md b/docs/tr/docs/python-types.md
index ac3111136..b44aa3b9d 100644
--- a/docs/tr/docs/python-types.md
+++ b/docs/tr/docs/python-types.md
@@ -12,16 +12,18 @@ Bu pythonda tip belirteçleri için **hızlı bir başlangıç / bilgi tazeleme
**FastAPI** kullanmayacak olsanız bile tür belirteçleri hakkında bilgi edinmenizde fayda var.
-!!! note "Not"
- Python uzmanıysanız ve tip belirteçleri ilgili her şeyi zaten biliyorsanız, sonraki bölüme geçin.
+/// note | Not
+
+Python uzmanıysanız ve tip belirteçleri ilgili her şeyi zaten biliyorsanız, sonraki bölüme geçin.
+
+///
## Motivasyon
Basit bir örnek ile başlayalım:
-```Python
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py *}
+
Programın çıktısı:
@@ -35,9 +37,8 @@ Fonksiyon sırayla şunları yapar:
* `title()` ile değişkenlerin ilk karakterlerini büyütür.
* Değişkenleri aralarında bir boşlukla beraber Birleştirir.
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py hl[2] *}
+
### Düzenle
@@ -79,9 +80,8 @@ Bu kadar.
İşte bunlar "tip belirteçleri":
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial002.py!}
-```
+{* ../../docs_src/python_types/tutorial002.py hl[1] *}
+
Bu, aşağıdaki gibi varsayılan değerleri bildirmekle aynı şey değildir:
@@ -109,9 +109,8 @@ Aradığınızı bulana kadar seçenekleri kaydırabilirsiniz:
Bu fonksiyon, zaten tür belirteçlerine sahip:
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial003.py!}
-```
+{* ../../docs_src/python_types/tutorial003.py hl[1] *}
+
Editör değişkenlerin tiplerini bildiğinden, yalnızca otomatik tamamlama değil, hata kontrolleri de sağlar:
@@ -119,9 +118,8 @@ Editör değişkenlerin tiplerini bildiğinden, yalnızca otomatik tamamlama de
Artık `age` değişkenini `str(age)` olarak kullanmanız gerektiğini biliyorsunuz:
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial004.py!}
-```
+{* ../../docs_src/python_types/tutorial004.py hl[2] *}
+
## Tip bildirme
@@ -140,9 +138,8 @@ Yalnızca `str` değil, tüm standart Python tiplerinin bildirebilirsiniz.
* `bool`
* `bytes`
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial005.py!}
-```
+{* ../../docs_src/python_types/tutorial005.py hl[1] *}
+
### Tip parametreleri ile Generic tipler
@@ -158,9 +155,8 @@ Bu tür tip belirteçlerini desteklemek için özel olarak mevcuttur.
From `typing`, import `List` (büyük harf olan `L` ile):
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial006.py!}
-```
+{* ../../docs_src/python_types/tutorial006.py hl[1] *}
+
Değişkenin tipini yine iki nokta üstüste (`:`) ile belirleyin.
@@ -168,14 +164,16 @@ tip olarak `List` kullanın.
Liste, bazı dahili tipleri içeren bir tür olduğundan, bunları köşeli parantez içine alırsınız:
-```Python hl_lines="4"
-{!../../../docs_src/python_types/tutorial006.py!}
-```
+{* ../../docs_src/python_types/tutorial006.py hl[4] *}
-!!! tip "Ipucu"
- Köşeli parantez içindeki bu dahili tiplere "tip parametreleri" denir.
- Bu durumda `str`, `List`e iletilen tür parametresidir.
+/// tip | Ipucu
+
+Köşeli parantez içindeki bu dahili tiplere "tip parametreleri" denir.
+
+Bu durumda `str`, `List`e iletilen tür parametresidir.
+
+///
Bunun anlamı şudur: "`items` değişkeni bir `list`tir ve bu listedeki öğelerin her biri bir `str`dir".
@@ -193,9 +191,8 @@ Ve yine, editör bunun bir `str` olduğunu biliyor ve bunun için destek s
`Tuple` ve `set`lerin tiplerini bildirmek için de aynısını yapıyoruz:
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial007.py!}
-```
+{* ../../docs_src/python_types/tutorial007.py hl[1,4] *}
+
Bu şu anlama geliyor:
@@ -210,9 +207,8 @@ Bir `dict` tanımlamak için virgülle ayrılmış iki parametre verebilirsiniz.
İkinci parametre ise `dict` değerinin `value` değeri içindir:
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial008.py!}
-```
+{* ../../docs_src/python_types/tutorial008.py hl[1,4] *}
+
Bu şu anlama gelir:
@@ -225,7 +221,7 @@ Bu şu anlama gelir:
`Optional` bir değişkenin `str`gibi bir tipi olabileceğini ama isteğe bağlı olarak tipinin `None` olabileceğini belirtir:
```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial009.py!}
+{!../../docs_src/python_types/tutorial009.py!}
```
`str` yerine `Optional[str]` kullanmak editorün bu değerin her zaman `str` tipinde değil bazen `None` tipinde de olabileceğini belirtir ve hataları tespit etmemizde yardımcı olur.
@@ -249,15 +245,13 @@ Bir değişkenin tipini bir sınıf ile bildirebilirsiniz.
Diyelim ki `name` değerine sahip `Person` sınıfınız var:
-```Python hl_lines="1-3"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
+
Sonra bir değişkeni 'Person' tipinde tanımlayabilirsiniz:
-```Python hl_lines="6"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[6] *}
+
Ve yine bütün editör desteğini alırsınız:
@@ -277,12 +271,14 @@ Ve ortaya çıkan nesne üzerindeki bütün editör desteğini alırsınız.
Resmi Pydantic dokümanlarından alınmıştır:
-```Python
-{!../../../docs_src/python_types/tutorial011.py!}
-```
+{* ../../docs_src/python_types/tutorial011.py *}
-!!! info
- Daha fazla şey öğrenmek için Pydantic'i takip edin.
+
+/// info
+
+Daha fazla şey öğrenmek için Pydantic'i takip edin.
+
+///
**FastAPI** tamamen Pydantic'e dayanmaktadır.
@@ -310,5 +306,8 @@ Bütün bunlar kulağa soyut gelebilir. Merak etme. Tüm bunları çalışırken
Önemli olan, standart Python türlerini tek bir yerde kullanarak (daha fazla sınıf, dekoratör vb. eklemek yerine), **FastAPI**'nin bizim için işi yapmasını sağlamak.
-!!! info
- Tüm öğreticiyi zaten okuduysanız ve türler hakkında daha fazla bilgi için geri döndüyseniz, iyi bir kaynak: the "cheat sheet" from `mypy`.
+/// info
+
+Tüm öğreticiyi zaten okuduysanız ve türler hakkında daha fazla bilgi için geri döndüyseniz, iyi bir kaynak: the "cheat sheet" from `mypy`.
+
+///
diff --git a/docs/tr/docs/tutorial/cookie-params.md b/docs/tr/docs/tutorial/cookie-params.md
index 4a66f26eb..f07508c2f 100644
--- a/docs/tr/docs/tutorial/cookie-params.md
+++ b/docs/tr/docs/tutorial/cookie-params.md
@@ -6,41 +6,7 @@
Öncelikle, `Cookie`'yi projenize dahil edin:
-=== "Python 3.10+"
-
- ```Python hl_lines="3"
- {!> ../../../docs_src/cookie_params/tutorial001_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="3"
- {!> ../../../docs_src/cookie_params/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="3"
- {!> ../../../docs_src/cookie_params/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip "İpucu"
- Mümkün mertebe 'Annotated' sınıfını kullanmaya çalışın.
-
- ```Python hl_lines="1"
- {!> ../../../docs_src/cookie_params/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip "İpucu"
- Mümkün mertebe 'Annotated' sınıfını kullanmaya çalışın.
-
- ```Python hl_lines="3"
- {!> ../../../docs_src/cookie_params/tutorial001.py!}
- ```
+{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[3] *}
## `Cookie` Parametrelerini Tanımlayın
@@ -48,49 +14,21 @@
İlk değer varsayılan değerdir; tüm ekstra doğrulama veya belirteç parametrelerini kullanabilirsiniz:
-=== "Python 3.10+"
+{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[9] *}
- ```Python hl_lines="9"
- {!> ../../../docs_src/cookie_params/tutorial001_an_py310.py!}
- ```
+/// note | Teknik Detaylar
-=== "Python 3.9+"
+`Cookie` sınıfı `Path` ve `Query` sınıflarının kardeşidir. Diğerleri gibi `Param` sınıfını miras alan bir sınıftır.
- ```Python hl_lines="9"
- {!> ../../../docs_src/cookie_params/tutorial001_an_py39.py!}
- ```
+Ancak `fastapi`'dan projenize dahil ettiğiniz `Query`, `Path`, `Cookie` ve diğerleri aslında özel sınıflar döndüren birer fonksiyondur.
-=== "Python 3.8+"
+///
- ```Python hl_lines="10"
- {!> ../../../docs_src/cookie_params/tutorial001_an.py!}
- ```
+/// info | Bilgi
-=== "Python 3.10+ non-Annotated"
+Çerez tanımlamak için `Cookie` sınıfını kullanmanız gerekmektedir, aksi taktirde parametreler sorgu parametreleri olarak yorumlanır.
- !!! tip "İpucu"
- Mümkün mertebe 'Annotated' sınıfını kullanmaya çalışın.
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/cookie_params/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip "İpucu"
- Mümkün mertebe 'Annotated' sınıfını kullanmaya çalışın.
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/cookie_params/tutorial001.py!}
- ```
-
-!!! note "Teknik Detaylar"
- `Cookie` sınıfı `Path` ve `Query` sınıflarının kardeşidir. Diğerleri gibi `Param` sınıfını miras alan bir sınıftır.
-
- Ancak `fastapi`'dan projenize dahil ettiğiniz `Query`, `Path`, `Cookie` ve diğerleri aslında özel sınıflar döndüren birer fonksiyondur.
-
-!!! info "Bilgi"
- Çerez tanımlamak için `Cookie` sınıfını kullanmanız gerekmektedir, aksi taktirde parametreler sorgu parametreleri olarak yorumlanır.
+///
## Özet
diff --git a/docs/tr/docs/tutorial/first-steps.md b/docs/tr/docs/tutorial/first-steps.md
index e66f73034..2d2949b50 100644
--- a/docs/tr/docs/tutorial/first-steps.md
+++ b/docs/tr/docs/tutorial/first-steps.md
@@ -2,9 +2,7 @@
En sade FastAPI dosyası şu şekilde görünür:
-```Python
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py *}
Yukarıdaki içeriği bir `main.py` dosyasına kopyalayalım.
@@ -24,12 +22,15 @@ $ uvicorn main:app --reload
-!!! note "Not"
- `uvicorn main:app` komutunu şu şekilde açıklayabiliriz:
+/// note | Not
- * `main`: dosya olan `main.py` (yani Python "modülü").
- * `app`: ise `main.py` dosyasının içerisinde `app = FastAPI()` satırında oluşturduğumuz `FastAPI` nesnesi.
- * `--reload`: kod değişikliklerinin ardından sunucuyu otomatik olarak yeniden başlatır. Bu parameteyi sadece geliştirme aşamasında kullanmalıyız.
+`uvicorn main:app` komutunu şu şekilde açıklayabiliriz:
+
+* `main`: dosya olan `main.py` (yani Python "modülü").
+* `app`: ise `main.py` dosyasının içerisinde `app = FastAPI()` satırında oluşturduğumuz `FastAPI` nesnesi.
+* `--reload`: kod değişikliklerinin ardından sunucuyu otomatik olarak yeniden başlatır. Bu parameteyi sadece geliştirme aşamasında kullanmalıyız.
+
+///
Çıktı olarak şöyle bir satır ile karşılaşacaksınız:
@@ -130,22 +131,21 @@ Ayrıca, API'ınızla iletişim kuracak önyüz, mobil veya IoT uygulamaları gi
### Adım 1: `FastAPI`yı Projemize Dahil Edelim
-```Python hl_lines="1"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[1] *}
`FastAPI`, API'niz için tüm işlevselliği sağlayan bir Python sınıfıdır.
-!!! note "Teknik Detaylar"
- `FastAPI` doğrudan `Starlette`'i miras alan bir sınıftır.
+/// note | Teknik Detaylar
- Starlette'in tüm işlevselliğini `FastAPI` ile de kullanabilirsiniz.
+`FastAPI` doğrudan `Starlette`'i miras alan bir sınıftır.
+
+Starlette'in tüm işlevselliğini `FastAPI` ile de kullanabilirsiniz.
+
+///
### Adım 2: Bir `FastAPI` "Örneği" Oluşturalım
-```Python hl_lines="3"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[3] *}
Burada `app` değişkeni `FastAPI` sınıfının bir örneği olacaktır.
@@ -165,9 +165,7 @@ $ uvicorn main:app --reload
Uygulamanızı aşağıdaki gibi oluşturursanız:
-```Python hl_lines="3"
-{!../../../docs_src/first_steps/tutorial002.py!}
-```
+{* ../../docs_src/first_steps/tutorial002.py hl[3] *}
Ve bunu `main.py` dosyasına yerleştirirseniz eğer `uvicorn` komutunu şu şekilde çalıştırabilirsiniz:
@@ -199,8 +197,11 @@ https://example.com/items/foo
/items/foo
```
-!!! info "Bilgi"
- "Yol" genellikle "endpoint" veya "route" olarak adlandırılır.
+/// info | Bilgi
+
+"Yol" genellikle "endpoint" veya "route" olarak adlandırılır.
+
+///
Bir API oluştururken, "yol", "kaynaklar" ile "endişeleri" ayırmanın ana yöntemidir.
@@ -241,25 +242,26 @@ Biz de onları "**operasyonlar**" olarak adlandıracağız.
#### Bir *Yol Operasyonu Dekoratörü* Tanımlayalım
-```Python hl_lines="6"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[6] *}
`@app.get("/")` dekoratörü, **FastAPI**'a hemen altındaki fonksiyonun aşağıdaki durumlardan sorumlu olduğunu söyler:
* get operasyonu ile
* `/` yoluna gelen istekler
-!!! info "`@decorator` Bilgisi"
- Python'da `@something` sözdizimi "dekoratör" olarak adlandırılır.
+/// info | `@decorator` Bilgisi
- Dekoratörler, dekoratif bir şapka gibi (sanırım terim buradan geliyor) fonksiyonların üzerlerine yerleştirilirler.
+Python'da `@something` sözdizimi "dekoratör" olarak adlandırılır.
- Bir "dekoratör" hemen altında bulunan fonksiyonu alır ve o fonksiyon ile bazı işlemler gerçekleştirir.
+Dekoratörler, dekoratif bir şapka gibi (sanırım terim buradan geliyor) fonksiyonların üzerlerine yerleştirilirler.
- Bizim durumumuzda, kullandığımız dekoratör, **FastAPI**'a altındaki fonksiyonun `/` yoluna gelen `get` metodlu isteklerden sorumlu olduğunu söyler.
+Bir "dekoratör" hemen altında bulunan fonksiyonu alır ve o fonksiyon ile bazı işlemler gerçekleştirir.
- Bu bir **yol operasyonu dekoratörüdür**.
+Bizim durumumuzda, kullandığımız dekoratör, **FastAPI**'a altındaki fonksiyonun `/` yoluna gelen `get` metodlu isteklerden sorumlu olduğunu söyler.
+
+Bu bir **yol operasyonu dekoratörüdür**.
+
+///
Ayrıca diğer operasyonları da kullanabilirsiniz:
@@ -274,14 +276,17 @@ Daha az kullanılanları da kullanabilirsiniz:
* `@app.patch()`
* `@app.trace()`
-!!! tip "İpucu"
- Her işlemi (HTTP metod) istediğiniz gibi kullanmakta özgürsünüz.
+/// tip | İpucu
- **FastAPI** herhangi bir özel amacı veya anlamı olması konusunda ısrarcı olmaz.
+Her işlemi (HTTP metod) istediğiniz gibi kullanmakta özgürsünüz.
- Buradaki bilgiler bir gereklilik değil, bir kılavuz olarak sunulmaktadır.
+**FastAPI** herhangi bir özel amacı veya anlamı olması konusunda ısrarcı olmaz.
- Mesela GraphQL kullanırkan genelde tüm işlemleri yalnızca `POST` operasyonunu kullanarak gerçekleştirirsiniz.
+Buradaki bilgiler bir gereklilik değil, bir kılavuz olarak sunulmaktadır.
+
+Mesela GraphQL kullanırkan genelde tüm işlemleri yalnızca `POST` operasyonunu kullanarak gerçekleştirirsiniz.
+
+///
### Adım 4: **Yol Operasyonu Fonksiyonunu** Tanımlayın
@@ -291,9 +296,7 @@ Aşağıdaki, bizim **yol operasyonu fonksiyonumuzdur**:
* **operasyon**: `get`
* **fonksiyon**: "dekoratör"ün (`@app.get("/")`'in) altındaki fonksiyondur.
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[7] *}
Bu bir Python fonksiyonudur.
@@ -305,18 +308,17 @@ Bu durumda bu fonksiyon bir `async` fonksiyondur.
Bu fonksiyonu `async def` yerine normal bir fonksiyon olarak da tanımlayabilirsiniz.
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial003.py!}
-```
+{* ../../docs_src/first_steps/tutorial003.py hl[7] *}
-!!! note "Not"
- Eğer farkı bilmiyorsanız, [Async: *"Aceleniz mi var?"*](../async.md#in-a-hurry){.internal-link target=_blank} sayfasını kontrol edebilirsiniz.
+/// note | Not
+
+Eğer farkı bilmiyorsanız, [Async: *"Aceleniz mi var?"*](../async.md#in-a-hurry){.internal-link target=_blank} sayfasını kontrol edebilirsiniz.
+
+///
### Adım 5: İçeriği Geri Döndürün
-```Python hl_lines="8"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[8] *}
Bir `dict`, `list` veya `str`, `int` gibi tekil değerler döndürebilirsiniz.
diff --git a/docs/tr/docs/tutorial/path-params.md b/docs/tr/docs/tutorial/path-params.md
index c19023645..e1707a5d9 100644
--- a/docs/tr/docs/tutorial/path-params.md
+++ b/docs/tr/docs/tutorial/path-params.md
@@ -2,9 +2,7 @@
Yol "parametrelerini" veya "değişkenlerini" Python string biçimlemede kullanılan sözdizimi ile tanımlayabilirsiniz.
-```Python hl_lines="6-7"
-{!../../../docs_src/path_params/tutorial001.py!}
-```
+{* ../../docs_src/path_params/tutorial001.py hl[6:7] *}
Yol parametresi olan `item_id`'nin değeri, fonksiyonunuza `item_id` argümanı olarak aktarılacaktır.
@@ -18,14 +16,15 @@ Eğer bu örneği çalıştırıp Dönüşümü
POST sayfasını ziyaret edebilirsiniz.
+Ancak form içerisinde dosyalar yer aldığında `multipart/form-data` olarak kodlanır. Bir sonraki bölümde dosyaların işlenmesi hakkında bilgi edineceksiniz.
-!!! warning "Uyarı"
- *Yol operasyonları* içerisinde birden fazla `Form` parametresi tanımlayabilirsiniz ancak bunlarla birlikte JSON verisi kabul eden `Body` alanları tanımlayamazsınız çünkü bu durumda istek gövdesi `application/json` yerine `application/x-www-form-urlencoded` ile kodlanmış olur.
+Form kodlama türleri ve form alanları hakkında daha fazla bilgi edinmek istiyorsanız MDN web docs for POST sayfasını ziyaret edebilirsiniz.
- Bu **FastAPI**'ın getirdiği bir kısıtlama değildir, HTTP protokolünün bir parçasıdır.
+///
+
+/// warning | Uyarı
+
+*Yol operasyonları* içerisinde birden fazla `Form` parametresi tanımlayabilirsiniz ancak bunlarla birlikte JSON verisi kabul eden `Body` alanları tanımlayamazsınız çünkü bu durumda istek gövdesi `application/json` yerine `application/x-www-form-urlencoded` ile kodlanmış olur.
+
+Bu **FastAPI**'ın getirdiği bir kısıtlama değildir, HTTP protokolünün bir parçasıdır.
+
+///
## Özet
diff --git a/docs/tr/docs/tutorial/static-files.md b/docs/tr/docs/tutorial/static-files.md
index 00c833686..db30f13bc 100644
--- a/docs/tr/docs/tutorial/static-files.md
+++ b/docs/tr/docs/tutorial/static-files.md
@@ -7,14 +7,15 @@
* `StaticFiles` sınıfını projenize dahil edin.
* Bir `StaticFiles()` örneğini belirli bir yola bağlayın.
-```Python hl_lines="2 6"
-{!../../../docs_src/static_files/tutorial001.py!}
-```
+{* ../../docs_src/static_files/tutorial001.py hl[2,6] *}
-!!! note "Teknik Detaylar"
- Projenize dahil etmek için `from starlette.staticfiles import StaticFiles` kullanabilirsiniz.
+/// note | Teknik Detaylar
- **FastAPI**, geliştiricilere kolaylık sağlamak amacıyla `starlette.staticfiles`'ı `fastapi.staticfiles` olarak sağlar. Ancak `StaticFiles` sınıfı aslında doğrudan Starlette'den gelir.
+Projenize dahil etmek için `from starlette.staticfiles import StaticFiles` kullanabilirsiniz.
+
+**FastAPI**, geliştiricilere kolaylık sağlamak amacıyla `starlette.staticfiles`'ı `fastapi.staticfiles` olarak sağlar. Ancak `StaticFiles` sınıfı aslında doğrudan Starlette'den gelir.
+
+///
### Bağlama (Mounting) Nedir?
diff --git a/docs/uk/docs/alternatives.md b/docs/uk/docs/alternatives.md
index 16cc0d875..1acbe237a 100644
--- a/docs/uk/docs/alternatives.md
+++ b/docs/uk/docs/alternatives.md
@@ -30,12 +30,17 @@
Це був один із перших прикладів **автоматичної документації API**, і саме це була одна з перших ідей, яка надихнула на «пошук» **FastAPI**.
-!!! note "Примітка"
- Django REST Framework створив Том Крісті. Той самий творець Starlette і Uvicorn, на яких базується **FastAPI**.
+/// note | Примітка
+Django REST Framework створив Том Крісті. Той самий творець Starlette і Uvicorn, на яких базується **FastAPI**.
-!!! check "Надихнуло **FastAPI** на"
- Мати автоматичний веб-інтерфейс документації API.
+///
+
+/// check | Надихнуло **FastAPI** на
+
+Мати автоматичний веб-інтерфейс документації API.
+
+///
### Flask
@@ -51,11 +56,13 @@ Flask — це «мікрофреймворк», він не включає ін
Враховуючи простоту Flask, він здавався хорошим підходом для створення API. Наступним, що знайшов, був «Django REST Framework» для Flask.
-!!! check "Надихнуло **FastAPI** на"
- Бути мікрофреймоворком. Зробити легким комбінування та поєднання необхідних інструментів та частин.
+/// check | Надихнуло **FastAPI** на
- Мати просту та легку у використанні систему маршрутизації.
+Бути мікрофреймоворком. Зробити легким комбінування та поєднання необхідних інструментів та частин.
+ Мати просту та легку у використанні систему маршрутизації.
+
+///
### Requests
@@ -91,11 +98,13 @@ def read_url():
Зверніть увагу на схожість у `requests.get(...)` і `@app.get(...)`.
-!!! check "Надихнуло **FastAPI** на"
- * Майте простий та інтуїтивно зрозумілий API.
- * Використовуйте імена (операції) методів HTTP безпосередньо, простим та інтуїтивно зрозумілим способом.
- * Розумні параметри за замовчуванням, але потужні налаштування.
+/// check | Надихнуло **FastAPI** на
+* Майте простий та інтуїтивно зрозумілий API.
+ * Використовуйте імена (операції) методів HTTP безпосередньо, простим та інтуїтивно зрозумілим способом.
+ * Розумні параметри за замовчуванням, але потужні налаштування.
+
+///
### Swagger / OpenAPI
@@ -109,15 +118,18 @@ def read_url():
Тому, коли говорять про версію 2.0, прийнято говорити «Swagger», а про версію 3+ «OpenAPI».
-!!! check "Надихнуло **FastAPI** на"
- Прийняти і використовувати відкритий стандарт для специфікацій API замість спеціальної схеми.
+/// check | Надихнуло **FastAPI** на
- Інтегрувати інструменти інтерфейсу на основі стандартів:
+Прийняти і використовувати відкритий стандарт для специфікацій API замість спеціальної схеми.
- * Інтерфейс Swagger
- * ReDoc
+ Інтегрувати інструменти інтерфейсу на основі стандартів:
- Ці два було обрано через те, що вони досить популярні та стабільні, але, виконавши швидкий пошук, ви можете знайти десятки додаткових альтернативних інтерфейсів для OpenAPI (які можна використовувати з **FastAPI**).
+ * Інтерфейс Swagger
+ * ReDoc
+
+ Ці два було обрано через те, що вони досить популярні та стабільні, але, виконавши швидкий пошук, ви можете знайти десятки додаткових альтернативних інтерфейсів для OpenAPI (які можна використовувати з **FastAPI**).
+
+///
### Фреймворки REST для Flask
@@ -135,8 +147,11 @@ Marshmallow створено для забезпечення цих функці
Але він був створений до того, як існували підказки типу Python. Отже, щоб визначити кожну схему, вам потрібно використовувати спеціальні утиліти та класи, надані Marshmallow.
-!!! check "Надихнуло **FastAPI** на"
- Використовувати код для автоматичного визначення "схем", які надають типи даних і перевірку.
+/// check | Надихнуло **FastAPI** на
+
+Використовувати код для автоматичного визначення "схем", які надають типи даних і перевірку.
+
+///
### Webargs
@@ -148,11 +163,17 @@ Webargs — це інструмент, створений, щоб забезпе
Це чудовий інструмент, і я також часто використовував його, перш ніж створити **FastAPI**.
-!!! info "Інформація"
- Webargs був створений тими ж розробниками Marshmallow.
+/// info | Інформація
-!!! check "Надихнуло **FastAPI** на"
- Мати автоматичну перевірку даних вхідного запиту.
+Webargs був створений тими ж розробниками Marshmallow.
+
+///
+
+/// check | Надихнуло **FastAPI** на
+
+Мати автоматичну перевірку даних вхідного запиту.
+
+///
### APISpec
@@ -172,12 +193,17 @@ Marshmallow і Webargs забезпечують перевірку, аналіз
Редактор тут нічим не може допомогти. І якщо ми змінимо параметри чи схеми Marshmallow і забудемо також змінити цю строку документа YAML, згенерована схема буде застарілою.
-!!! info "Інформація"
- APISpec був створений тими ж розробниками Marshmallow.
+/// info | Інформація
+APISpec був створений тими ж розробниками Marshmallow.
-!!! check "Надихнуло **FastAPI** на"
- Підтримувати відкритий стандарт API, OpenAPI.
+///
+
+/// check | Надихнуло **FastAPI** на
+
+Підтримувати відкритий стандарт API, OpenAPI.
+
+///
### Flask-apispec
@@ -199,11 +225,17 @@ Marshmallow і Webargs забезпечують перевірку, аналіз
І ці самі генератори повного стеку були основою [**FastAPI** генераторів проектів](project-generation.md){.internal-link target=_blank}.
-!!! info "Інформація"
- Flask-apispec був створений тими ж розробниками Marshmallow.
+/// info | Інформація
-!!! check "Надихнуло **FastAPI** на"
- Створення схеми OpenAPI автоматично з того самого коду, який визначає серіалізацію та перевірку.
+Flask-apispec був створений тими ж розробниками Marshmallow.
+
+///
+
+/// check | Надихнуло **FastAPI** на
+
+Створення схеми OpenAPI автоматично з того самого коду, який визначає серіалізацію та перевірку.
+
+///
### NestJS (та Angular)
@@ -219,24 +251,33 @@ Marshmallow і Webargs забезпечують перевірку, аналіз
Він не дуже добре обробляє вкладені моделі. Отже, якщо тіло JSON у запиті є об’єктом JSON із внутрішніми полями, які, у свою чергу, є вкладеними об’єктами JSON, його неможливо належним чином задокументувати та перевірити.
-!!! check "Надихнуло **FastAPI** на"
- Використовувати типи Python, щоб мати чудову підтримку редактора.
+/// check | Надихнуло **FastAPI** на
- Мати потужну систему впровадження залежностей. Знайдіть спосіб звести до мінімуму повторення коду.
+Використовувати типи Python, щоб мати чудову підтримку редактора.
+
+ Мати потужну систему впровадження залежностей. Знайдіть спосіб звести до мінімуму повторення коду.
+
+///
### Sanic
Це був один із перших надзвичайно швидких фреймворків Python на основі `asyncio`. Він був дуже схожий на Flask.
-!!! note "Технічні деталі"
- Він використовував `uvloop` замість стандартного циклу Python `asyncio`. Ось що зробило його таким швидким.
+/// note | Технічні деталі
- Це явно надихнуло Uvicorn і Starlette, які зараз швидші за Sanic у відкритих тестах.
+Він використовував `uvloop` замість стандартного циклу Python `asyncio`. Ось що зробило його таким швидким.
-!!! check "Надихнуло **FastAPI** на"
- Знайти спосіб отримати божевільну продуктивність.
+ Це явно надихнуло Uvicorn і Starlette, які зараз швидші за Sanic у відкритих тестах.
- Ось чому **FastAPI** базується на Starlette, оскільки це найшвидша доступна структура (перевірена тестами сторонніх розробників).
+///
+
+/// check | Надихнуло **FastAPI** на
+
+Знайти спосіб отримати божевільну продуктивність.
+
+ Ось чому **FastAPI** базується на Starlette, оскільки це найшвидша доступна структура (перевірена тестами сторонніх розробників).
+
+///
### Falcon
@@ -246,12 +287,15 @@ Falcon — ще один високопродуктивний фреймворк
Таким чином, перевірка даних, серіалізація та документація повинні виконуватися в коді, а не автоматично. Або вони повинні бути реалізовані як фреймворк поверх Falcon, як Hug. Така сама відмінність спостерігається в інших фреймворках, натхненних дизайном Falcon, що мають один об’єкт запиту та один об’єкт відповіді як параметри.
-!!! check "Надихнуло **FastAPI** на"
- Знайти способи отримати чудову продуктивність.
+/// check | Надихнуло **FastAPI** на
- Разом із Hug (оскільки Hug базується на Falcon) надихнув **FastAPI** оголосити параметр `response` у функціях.
+Знайти способи отримати чудову продуктивність.
- Хоча у FastAPI це необов’язково, і використовується в основному для встановлення заголовків, файлів cookie та альтернативних кодів стану.
+ Разом із Hug (оскільки Hug базується на Falcon) надихнув **FastAPI** оголосити параметр `response` у функціях.
+
+ Хоча у FastAPI це необов’язково, і використовується в основному для встановлення заголовків, файлів cookie та альтернативних кодів стану.
+
+///
### Molten
@@ -269,12 +313,15 @@ Falcon — ще один високопродуктивний фреймворк
Маршрути оголошуються в одному місці з використанням функцій, оголошених в інших місцях (замість використання декораторів, які можна розмістити безпосередньо поверх функції, яка обробляє кінцеву точку). Це ближче до того, як це робить Django, ніж до Flask (і Starlette). Він розділяє в коді речі, які відносно тісно пов’язані.
-!!! check "Надихнуло **FastAPI** на"
- Визначити додаткові перевірки для типів даних, використовуючи значення "за замовчуванням" атрибутів моделі. Це покращує підтримку редактора, а раніше вона була недоступна в Pydantic.
+/// check | Надихнуло **FastAPI** на
- Це фактично надихнуло оновити частини Pydantic, щоб підтримувати той самий стиль оголошення перевірки (всі ці функції вже доступні в Pydantic).
+Визначити додаткові перевірки для типів даних, використовуючи значення "за замовчуванням" атрибутів моделі. Це покращує підтримку редактора, а раніше вона була недоступна в Pydantic.
-### Hug
+ Це фактично надихнуло оновити частини Pydantic, щоб підтримувати той самий стиль оголошення перевірки (всі ці функції вже доступні в Pydantic).
+
+///
+
+### Hug
Hug був одним із перших фреймворків, який реалізував оголошення типів параметрів API за допомогою підказок типу Python. Це була чудова ідея, яка надихнула інші інструменти зробити те саме.
@@ -288,15 +335,21 @@ Hug був одним із перших фреймворків, який реа
Оскільки він заснований на попередньому стандарті для синхронних веб-фреймворків Python (WSGI), він не може працювати з Websockets та іншими речами, хоча він також має високу продуктивність.
-!!! info "Інформація"
- Hug створив Тімоті Крослі, той самий творець `isort`, чудовий інструмент для автоматичного сортування імпорту у файлах Python.
+/// info | Інформація
-!!! check "Надихнуло **FastAPI** на"
- Hug надихнув частину APIStar і був одним із найбільш перспективних інструментів, поряд із APIStar.
+Hug створив Тімоті Крослі, той самий творець `isort`, чудовий інструмент для автоматичного сортування імпорту у файлах Python.
- Hug надихнув **FastAPI** на використання підказок типу Python для оголошення параметрів і автоматичного створення схеми, що визначає API.
+///
- Hug надихнув **FastAPI** оголосити параметр `response` у функціях для встановлення заголовків і файлів cookie.
+/// check | Надихнуло **FastAPI** на
+
+Hug надихнув частину APIStar і був одним із найбільш перспективних інструментів, поряд із APIStar.
+
+ Hug надихнув **FastAPI** на використання підказок типу Python для оголошення параметрів і автоматичного створення схеми, що визначає API.
+
+ Hug надихнув **FastAPI** оголосити параметр `response` у функціях для встановлення заголовків і файлів cookie.
+
+///
### APIStar (<= 0,5)
@@ -322,21 +375,27 @@ Hug був одним із перших фреймворків, який реа
Тепер APIStar — це набір інструментів для перевірки специфікацій OpenAPI, а не веб-фреймворк.
-!!! info "Інформація"
- APIStar створив Том Крісті. Той самий хлопець, який створив:
+/// info | Інформація
- * Django REST Framework
- * Starlette (на якому базується **FastAPI**)
- * Uvicorn (використовується Starlette і **FastAPI**)
+APIStar створив Том Крісті. Той самий хлопець, який створив:
-!!! check "Надихнуло **FastAPI** на"
- Існувати.
+ * Django REST Framework
+ * Starlette (на якому базується **FastAPI**)
+ * Uvicorn (використовується Starlette і **FastAPI**)
- Ідею оголошення кількох речей (перевірки даних, серіалізації та документації) за допомогою тих самих типів Python, які в той же час забезпечували чудову підтримку редактора, я вважав геніальною ідеєю.
+///
- І після тривалого пошуку подібної структури та тестування багатьох різних альтернатив, APIStar став найкращим доступним варіантом.
+/// check | Надихнуло **FastAPI** на
- Потім APIStar перестав існувати як сервер, і було створено Starlette, який став новою кращою основою для такої системи. Це стало останнім джерелом натхнення для створення **FastAPI**. Я вважаю **FastAPI** «духовним спадкоємцем» APIStar, удосконалюючи та розширюючи функції, систему введення тексту та інші частини на основі досвіду, отриманого від усіх цих попередніх інструментів.
+Існувати.
+
+ Ідею оголошення кількох речей (перевірки даних, серіалізації та документації) за допомогою тих самих типів Python, які в той же час забезпечували чудову підтримку редактора, я вважав геніальною ідеєю.
+
+ І після тривалого пошуку подібної структури та тестування багатьох різних альтернатив, APIStar став найкращим доступним варіантом.
+
+ Потім APIStar перестав існувати як сервер, і було створено Starlette, який став новою кращою основою для такої системи. Це стало останнім джерелом натхнення для створення **FastAPI**. Я вважаю **FastAPI** «духовним спадкоємцем» APIStar, удосконалюючи та розширюючи функції, систему введення тексту та інші частини на основі досвіду, отриманого від усіх цих попередніх інструментів.
+
+///
## Використовується **FastAPI**
@@ -348,10 +407,13 @@ Pydantic — це бібліотека для визначення переві
Його можна порівняти з Marshmallow. Хоча він швидший за Marshmallow у тестах. Оскільки він базується на тих самих підказках типу Python, підтримка редактора чудова.
-!!! check "**FastAPI** використовує його для"
- Виконання перевірки всіх даних, серіалізації даних і автоматичної документацію моделі (на основі схеми JSON).
+/// check | **FastAPI** використовує його для
- Потім **FastAPI** бере ці дані схеми JSON і розміщує їх у OpenAPI, окремо від усіх інших речей, які він робить.
+Виконання перевірки всіх даних, серіалізації даних і автоматичної документацію моделі (на основі схеми JSON).
+
+ Потім **FastAPI** бере ці дані схеми JSON і розміщує їх у OpenAPI, окремо від усіх інших речей, які він робить.
+
+///
### Starlette
@@ -380,17 +442,23 @@ Starlette надає всі основні функції веб-мікрофр
Це одна з головних речей, які **FastAPI** додає зверху, все на основі підказок типу Python (з використанням Pydantic). Це, а також система впровадження залежностей, утиліти безпеки, створення схеми OpenAPI тощо.
-!!! note "Технічні деталі"
- ASGI — це новий «стандарт», який розробляється членами основної команди Django. Це ще не «стандарт Python» (PEP), хоча вони в процесі цього.
+/// note | Технічні деталі
- Тим не менш, він уже використовується як «стандарт» кількома інструментами. Це значно покращує сумісність, оскільки ви можете переключити Uvicorn на будь-який інший сервер ASGI (наприклад, Daphne або Hypercorn), або ви можете додати інструменти, сумісні з ASGI, як-от `python-socketio`.
+ASGI — це новий «стандарт», який розробляється членами основної команди Django. Це ще не «стандарт Python» (PEP), хоча вони в процесі цього.
-!!! check "**FastAPI** використовує його для"
- Керування всіма основними веб-частинами. Додавання функцій зверху.
+ Тим не менш, він уже використовується як «стандарт» кількома інструментами. Це значно покращує сумісність, оскільки ви можете переключити Uvicorn на будь-який інший сервер ASGI (наприклад, Daphne або Hypercorn), або ви можете додати інструменти, сумісні з ASGI, як-от `python-socketio`.
- Сам клас `FastAPI` безпосередньо успадковує клас `Starlette`.
+///
- Отже, усе, що ви можете робити зі Starlette, ви можете робити це безпосередньо за допомогою **FastAPI**, оскільки це, по суті, Starlette на стероїдах.
+/// check | **FastAPI** використовує його для
+
+Керування всіма основними веб-частинами. Додавання функцій зверху.
+
+ Сам клас `FastAPI` безпосередньо успадковує клас `Starlette`.
+
+ Отже, усе, що ви можете робити зі Starlette, ви можете робити це безпосередньо за допомогою **FastAPI**, оскільки це, по суті, Starlette на стероїдах.
+
+///
### Uvicorn
@@ -400,12 +468,15 @@ Uvicorn — це блискавичний сервер ASGI, побудован
Це рекомендований сервер для Starlette і **FastAPI**.
-!!! check "**FastAPI** рекомендує це як"
- Основний веб-сервер для запуску програм **FastAPI**.
+/// check | **FastAPI** рекомендує це як
- Ви можете поєднати його з Gunicorn, щоб мати асинхронний багатопроцесний сервер.
+Основний веб-сервер для запуску програм **FastAPI**.
- Додаткову інформацію див. у розділі [Розгортання](deployment/index.md){.internal-link target=_blank}.
+ Ви можете поєднати його з Gunicorn, щоб мати асинхронний багатопроцесний сервер.
+
+ Додаткову інформацію див. у розділі [Розгортання](deployment/index.md){.internal-link target=_blank}.
+
+///
## Орієнтири та швидкість
diff --git a/docs/uk/docs/fastapi-cli.md b/docs/uk/docs/fastapi-cli.md
new file mode 100644
index 000000000..6bbbbc326
--- /dev/null
+++ b/docs/uk/docs/fastapi-cli.md
@@ -0,0 +1,83 @@
+# FastAPI CLI
+
+**FastAPI CLI** це програма командного рядка, яку Ви можете використовувати, щоб обслуговувати Ваш додаток FastAPI, керувати Вашими FastApi проектами, тощо.
+
+Коли Ви встановлюєте FastApi (тобто виконуєте `pip install "fastapi[standard]"`), Ви також встановлюєте пакунок `fastapi-cli`, цей пакунок надає команду `fastapi` в терміналі.
+
+Для запуску Вашого FastAPI проекту для розробки, Ви можете скористатись командою `fastapi dev`:
+
+
-
+
@@ -88,7 +88,7 @@ FastAPI - це сучасний, швидкий (високопродуктив
"_Honestly, what you've built looks super solid and polished. In many ways, it's what I wanted **Hug** to be - it's really inspiring to see someone build that._"
-
+
---
@@ -437,7 +437,7 @@ item: Item
Pydantic використовує:
-*
email_validator - для валідації електронної пошти.
+* email-validator - для валідації електронної пошти.
* pydantic-settings - для управління налаштуваннями.
* pydantic-extra-types - для додаткових типів, що можуть бути використані з Pydantic.
diff --git a/docs/uk/docs/learn/index.md b/docs/uk/docs/learn/index.md
new file mode 100644
index 000000000..7f9f21e57
--- /dev/null
+++ b/docs/uk/docs/learn/index.md
@@ -0,0 +1,5 @@
+# Навчання
+
+У цьому розділі надані вступні та навчальні матеріали для вивчення FastAPI.
+
+Це можна розглядати як **книгу**, **курс**, або **офіційний** та рекомендований спосіб освоїти FastAPI. 😎
diff --git a/docs/uk/docs/python-types.md b/docs/uk/docs/python-types.md
index d0adadff3..676bafb15 100644
--- a/docs/uk/docs/python-types.md
+++ b/docs/uk/docs/python-types.md
@@ -12,16 +12,18 @@ Python підтримує додаткові "підказки типу" ("type
Але навіть якщо ви ніколи не використаєте **FastAPI**, вам буде корисно дізнатись трохи про них.
-!!! note
- Якщо ви експерт у Python і ви вже знаєте усе про анотації типів - перейдіть до наступного розділу.
+/// note
+
+Якщо ви експерт у Python і ви вже знаєте усе про анотації типів - перейдіть до наступного розділу.
+
+///
## Мотивація
Давайте почнемо з простого прикладу:
-```Python
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py *}
+
Виклик цієї програми виводить:
@@ -35,9 +37,8 @@ John Doe
* Конвертує кожну літеру кожного слова у верхній регістр за допомогою `title()`.
* Конкатенує їх разом із пробілом по середині.
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py hl[2] *}
+
### Редагуйте це
@@ -79,9 +80,8 @@ John Doe
Це "type hints":
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial002.py!}
-```
+{* ../../docs_src/python_types/tutorial002.py hl[1] *}
+
Це не те саме, що оголошення значень за замовчуванням, як це було б з:
@@ -109,9 +109,8 @@ John Doe
Перевірте цю функцію, вона вже має анотацію типу:
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial003.py!}
-```
+{* ../../docs_src/python_types/tutorial003.py hl[1] *}
+
Оскільки редактор знає типи змінних, ви не тільки отримаєте автозаповнення, ви також отримаєте перевірку помилок:
@@ -119,9 +118,8 @@ John Doe
Тепер ви знаєте, щоб виправити це, вам потрібно перетворити `age` у строку з допомогою `str(age)`:
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial004.py!}
-```
+{* ../../docs_src/python_types/tutorial004.py hl[2] *}
+
## Оголошення типів
@@ -140,9 +138,8 @@ John Doe
* `bool`
* `bytes`
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial005.py!}
-```
+{* ../../docs_src/python_types/tutorial005.py hl[1] *}
+
### Generic-типи з параметрами типів
@@ -164,45 +161,55 @@ John Doe
Наприклад, давайте визначимо змінну, яка буде `list` із `str`.
-=== "Python 3.8 і вище"
+//// tab | Python 3.8 і вище
- З модуля `typing`, імпортуємо `List` (з великої літери `L`):
+З модуля `typing`, імпортуємо `List` (з великої літери `L`):
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial006.py!}
- ```
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial006.py!}
+```
- Оголосимо змінну з тим самим синтаксисом двокрапки (`:`).
+Оголосимо змінну з тим самим синтаксисом двокрапки (`:`).
- Як тип вкажемо `List`, який ви імпортували з `typing`.
+Як тип вкажемо `List`, який ви імпортували з `typing`.
- Оскільки список є типом, який містить деякі внутрішні типи, ви поміщаєте їх у квадратні дужки:
+Оскільки список є типом, який містить деякі внутрішні типи, ви поміщаєте їх у квадратні дужки:
- ```Python hl_lines="4"
- {!> ../../../docs_src/python_types/tutorial006.py!}
- ```
+```Python hl_lines="4"
+{!> ../../docs_src/python_types/tutorial006.py!}
+```
-=== "Python 3.9 і вище"
+////
- Оголосимо змінну з тим самим синтаксисом двокрапки (`:`).
+//// tab | Python 3.9 і вище
- Як тип вкажемо `list`.
+Оголосимо змінну з тим самим синтаксисом двокрапки (`:`).
- Оскільки список є типом, який містить деякі внутрішні типи, ви поміщаєте їх у квадратні дужки:
+Як тип вкажемо `list`.
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial006_py39.py!}
- ```
+Оскільки список є типом, який містить деякі внутрішні типи, ви поміщаєте їх у квадратні дужки:
-!!! info
- Ці внутрішні типи в квадратних дужках називаються "параметрами типу".
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial006_py39.py!}
+```
- У цьому випадку, `str` це параметр типу переданий у `List` (або `list` у Python 3.9 і вище).
+////
+
+/// info
+
+Ці внутрішні типи в квадратних дужках називаються "параметрами типу".
+
+У цьому випадку, `str` це параметр типу переданий у `List` (або `list` у Python 3.9 і вище).
+
+///
Це означає: "змінна `items` це `list`, і кожен з елементів у цьому списку - `str`".
-!!! tip
- Якщо ви використовуєте Python 3.9 і вище, вам не потрібно імпортувати `List` з `typing`, ви можете використовувати натомість тип `list`.
+/// tip
+
+Якщо ви використовуєте Python 3.9 і вище, вам не потрібно імпортувати `List` з `typing`, ви можете використовувати натомість тип `list`.
+
+///
Зробивши це, ваш редактор може надати підтримку навіть під час обробки елементів зі списку:
@@ -218,17 +225,21 @@ John Doe
Ви повинні зробити те ж саме, щоб оголосити `tuple` і `set`:
-=== "Python 3.8 і вище"
+//// tab | Python 3.8 і вище
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial007.py!}
- ```
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial007.py!}
+```
-=== "Python 3.9 і вище"
+////
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial007_py39.py!}
- ```
+//// tab | Python 3.9 і вище
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial007_py39.py!}
+```
+
+////
Це означає:
@@ -243,17 +254,21 @@ John Doe
Другий параметр типу для значення у `dict`:
-=== "Python 3.8 і вище"
+//// tab | Python 3.8 і вище
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial008.py!}
- ```
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial008.py!}
+```
-=== "Python 3.9 і вище"
+////
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial008_py39.py!}
- ```
+//// tab | Python 3.9 і вище
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008_py39.py!}
+```
+
+////
Це означає:
@@ -269,17 +284,21 @@ John Doe
У Python 3.10 також є **альтернативний синтаксис**, у якому ви можете розділити можливі типи за допомогою вертикальної смуги (`|`).
-=== "Python 3.8 і вище"
+//// tab | Python 3.8 і вище
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial008b.py!}
- ```
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial008b.py!}
+```
-=== "Python 3.10 і вище"
+////
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial008b_py310.py!}
- ```
+//// tab | Python 3.10 і вище
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008b_py310.py!}
+```
+
+////
В обох випадках це означає, що `item` може бути `int` або `str`.
@@ -290,7 +309,7 @@ John Doe
У Python 3.6 і вище (включаючи Python 3.10) ви можете оголосити його, імпортувавши та використовуючи `Optional` з модуля `typing`.
```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial009.py!}
+{!../../docs_src/python_types/tutorial009.py!}
```
Використання `Optional[str]` замість просто `str` дозволить редактору допомогти вам виявити помилки, коли ви могли б вважати, що значенням завжди є `str`, хоча насправді воно також може бути `None`.
@@ -299,69 +318,81 @@ John Doe
Це також означає, що в Python 3.10 ви можете використовувати `Something | None`:
-=== "Python 3.8 і вище"
+//// tab | Python 3.8 і вище
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial009.py!}
- ```
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial009.py!}
+```
-=== "Python 3.8 і вище - альтернатива"
+////
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial009b.py!}
- ```
+//// tab | Python 3.8 і вище - альтернатива
-=== "Python 3.10 і вище"
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial009b.py!}
+```
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial009_py310.py!}
- ```
+////
+
+//// tab | Python 3.10 і вище
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial009_py310.py!}
+```
+
+////
#### Generic типи
Ці типи, які приймають параметри типу у квадратних дужках, називаються **Generic types** or **Generics**, наприклад:
-=== "Python 3.8 і вище"
+//// tab | Python 3.8 і вище
- * `List`
- * `Tuple`
- * `Set`
- * `Dict`
- * `Union`
- * `Optional`
- * ...та інші.
+* `List`
+* `Tuple`
+* `Set`
+* `Dict`
+* `Union`
+* `Optional`
+* ...та інші.
-=== "Python 3.9 і вище"
+////
- Ви можете використовувати ті самі вбудовані типи, як generic (з квадратними дужками та типами всередині):
+//// tab | Python 3.9 і вище
- * `list`
- * `tuple`
- * `set`
- * `dict`
+Ви можете використовувати ті самі вбудовані типи, як generic (з квадратними дужками та типами всередині):
- І те саме, що й у Python 3.8, із модуля `typing`:
+* `list`
+* `tuple`
+* `set`
+* `dict`
- * `Union`
- * `Optional`
- * ...та інші.
+І те саме, що й у Python 3.8, із модуля `typing`:
-=== "Python 3.10 і вище"
+* `Union`
+* `Optional`
+* ...та інші.
- Ви можете використовувати ті самі вбудовані типи, як generic (з квадратними дужками та типами всередині):
+////
- * `list`
- * `tuple`
- * `set`
- * `dict`
+//// tab | Python 3.10 і вище
- І те саме, що й у Python 3.8, із модуля `typing`:
+Ви можете використовувати ті самі вбудовані типи, як generic (з квадратними дужками та типами всередині):
- * `Union`
- * `Optional` (так само як у Python 3.8)
- * ...та інші.
+* `list`
+* `tuple`
+* `set`
+* `dict`
- У Python 3.10, як альтернатива використанню `Union` та `Optional`, ви можете використовувати вертикальну смугу (`|`) щоб оголосити об'єднання типів.
+І те саме, що й у Python 3.8, із модуля `typing`:
+
+* `Union`
+* `Optional` (так само як у Python 3.8)
+* ...та інші.
+
+У Python 3.10, як альтернатива використанню `Union` та `Optional`, ви можете використовувати вертикальну смугу (`|`) щоб оголосити об'єднання типів.
+
+////
### Класи як типи
@@ -369,15 +400,13 @@ John Doe
Скажімо, у вас є клас `Person` з імʼям:
-```Python hl_lines="1-3"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
+
Потім ви можете оголосити змінну типу `Person`:
-```Python hl_lines="6"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[6] *}
+
І знову ж таки, ви отримуєте всю підтримку редактора:
@@ -397,26 +426,35 @@ John Doe
Приклад з документації Pydantic:
-=== "Python 3.8 і вище"
+//// tab | Python 3.8 і вище
- ```Python
- {!> ../../../docs_src/python_types/tutorial011.py!}
- ```
+```Python
+{!> ../../docs_src/python_types/tutorial011.py!}
+```
-=== "Python 3.9 і вище"
+////
- ```Python
- {!> ../../../docs_src/python_types/tutorial011_py39.py!}
- ```
+//// tab | Python 3.9 і вище
-=== "Python 3.10 і вище"
+```Python
+{!> ../../docs_src/python_types/tutorial011_py39.py!}
+```
- ```Python
- {!> ../../../docs_src/python_types/tutorial011_py310.py!}
- ```
+////
-!!! info
- Щоб дізнатись більше про Pydantic, перегляньте його документацію.
+//// tab | Python 3.10 і вище
+
+```Python
+{!> ../../docs_src/python_types/tutorial011_py310.py!}
+```
+
+////
+
+/// info
+
+Щоб дізнатись більше про Pydantic, перегляньте його документацію.
+
+///
**FastAPI** повністю базується на Pydantic.
@@ -444,5 +482,8 @@ John Doe
Важливо те, що за допомогою стандартних типів Python в одному місці (замість того, щоб додавати більше класів, декораторів тощо), **FastAPI** зробить багато роботи за вас.
-!!! info
- Якщо ви вже пройшли весь навчальний посібник і повернулися, щоб дізнатися більше про типи, ось хороший ресурс "шпаргалка" від `mypy`.
+/// info
+
+Якщо ви вже пройшли весь навчальний посібник і повернулися, щоб дізнатися більше про типи, ось хороший ресурс "шпаргалка" від `mypy`.
+
+///
diff --git a/docs/uk/docs/tutorial/background-tasks.md b/docs/uk/docs/tutorial/background-tasks.md
new file mode 100644
index 000000000..912ba8c2a
--- /dev/null
+++ b/docs/uk/docs/tutorial/background-tasks.md
@@ -0,0 +1,85 @@
+# Фонові задачі
+
+Ви можете створювати фонові задачі, які будуть виконуватися *після* повернення відповіді.
+
+Це корисно для операцій, які потрібно виконати після обробки запиту, але клієнту не обов’язково чекати завершення цієї операції перед отриманням відповіді.
+
+Приклади використання:
+
+* Надсилання email-сповіщень після виконання певної дії:
+ * Підключення до поштового сервера та надсилання листа може займати кілька секунд. Ви можете відразу повернути відповідь, а email відправити у фоні.
+* Обробка даних:
+ * Наприклад, якщо отримано файл, який потрібно обробити довготривалим процесом, можна повернути відповідь "Accepted" ("Прийнято", HTTP 202) і виконати обробку файлу у фоні.
+
+## Використання `BackgroundTasks`
+
+Спочатку імпортуйте `BackgroundTasks` і додайте його як параметр у Вашу *функцію операції шляху* (path operation function) до `BackgroundTasks`:
+
+{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *}
+
+**FastAPI** автоматично створить об'єкт `BackgroundTasks` і передасть його у цей параметр.
+
+
+## Створення функції задачі
+
+Створіть функцію, яка буде виконувати фонову задачу.
+
+Це звичайна функція, яка може отримувати параметри.
+
+Вона може бути асинхронною `async def` або звичайною `def` функцією – **FastAPI** обробить її правильно.
+
+У нашому випадку функція записує у файл (імітуючи надсилання email).
+
+І оскільки операція запису не використовує `async` та `await`, ми визначаємо функцію як звичайну `def`:
+
+{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *}
+
+## Додавання фонової задачі
+
+Усередині Вашої *функції обробки шляху*, передайте функцію задачі в об'єкт *background tasks*, використовуючи метод `.add_task()`:
+
+{* ../../docs_src/background_tasks/tutorial001.py hl[14] *}
+
+`.add_task()` приймає аргументи:
+
+* Функція задача, яка буде виконуватися у фоновому режимі (`write_notification`). Зверніть увагу, що передається обʼєкт без дужок.
+* Будь-яка послідовність аргументів, які потрібно передати у функцію завдання у відповідному порядку (`email`).
+* Будь-які іменовані аргументи, які потрібно передати у функцію задачу (`message="some notification"`).
+
+## Впровадження залежностей
+
+Використання `BackgroundTasks` також працює з системою впровадження залежностей. Ви можете оголосити параметр типу `BackgroundTasks` на різних рівнях: у *функції операції шляху*, у залежності (dependable), у під залежності тощо.
+
+**FastAPI** знає, як діяти в кожному випадку і як повторно використовувати один і той самий об'єкт, щоб усі фонові задачі були об’єднані та виконувалися у фоновому режимі після завершення основного запиту.
+
+{* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *}
+
+У цьому прикладі повідомлення будуть записані у файл `log.txt` *після* того, як відповідь буде надіслана.
+
+Якщо у запиті був переданий query-параметр, він буде записаний у лог у фоновій задачі.
+
+А потім інша фонова задача, яка створюється у *функції операції шляху*, запише повідомлення з використанням path параметра `email`.
+
+## Технічні деталі
+
+Клас `BackgroundTasks` походить безпосередньо з `starlette.background`.
+
+Він імпортується безпосередньо у FastAPI, щоб Ви могли використовувати його з `fastapi` і випадково не імпортували `BackgroundTask` (без s в кінці) з `starlette.background`.
+
+Якщо використовувати лише `BackgroundTasks` (а не `BackgroundTask`), то його можна передавати як параметр у *функції операції шляху*, і **FastAPI** подбає про все інше, так само як і про використання об'єкта `Request`.
+
+Також можна використовувати `BackgroundTask` окремо в FastAPI, але для цього Вам доведеться створити об'єкт у коді та повернути Starlette `Response`, включаючи його.
+
+Детальніше можна почитати в офіційній документації Starlette про фонові задачі .
+
+## Застереження
+
+Якщо Вам потрібно виконувати складні фонові обчислення, і при цьому нема потреби запускати їх у тому ж процесі (наприклад, не потрібно спільного доступу до пам’яті чи змінних), можливо, варто скористатися більш потужними інструментами, такими як Celery.
+
+Такі інструменти зазвичай потребують складнішої конфігурації та менеджера черги повідомлень/завдань, наприклад, RabbitMQ або Redis. Однак вони дозволяють виконувати фонові задачі в кількох процесах і навіть на кількох серверах.
+
+Якщо ж Вам потрібно отримати доступ до змінних і об’єктів із тієї ж **FastAPI** - програми або виконувати невеликі фонові завдання (наприклад, надсилати сповіщення електронною поштою), достатньо просто використовувати `BackgroundTasks`.
+
+## Підсумок
+
+Імпортуйте та використовуйте `BackgroundTasks` як параметр у *функціях операції шляху* та залежностях, щоб додавати фонові задачі.
diff --git a/docs/uk/docs/tutorial/body-fields.md b/docs/uk/docs/tutorial/body-fields.md
index eee993cbe..7ddd9d104 100644
--- a/docs/uk/docs/tutorial/body-fields.md
+++ b/docs/uk/docs/tutorial/body-fields.md
@@ -6,98 +6,39 @@
Спочатку вам потрібно імпортувати це:
-=== "Python 3.10+"
+{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[4] *}
- ```Python hl_lines="4"
- {!> ../../../docs_src/body_fields/tutorial001_an_py310.py!}
- ```
+/// warning
-=== "Python 3.9+"
+Зверніть увагу, що `Field` імпортується прямо з `pydantic`, а не з `fastapi`, як всі інші (`Query`, `Path`, `Body` тощо).
- ```Python hl_lines="4"
- {!> ../../../docs_src/body_fields/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="4"
- {!> ../../../docs_src/body_fields/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Варто користуватись `Annotated` версією, якщо це можливо.
-
- ```Python hl_lines="2"
- {!> ../../../docs_src/body_fields/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Варто користуватись `Annotated` версією, якщо це можливо.
-
- ```Python hl_lines="4"
- {!> ../../../docs_src/body_fields/tutorial001.py!}
- ```
-
-!!! warning
- Зверніть увагу, що `Field` імпортується прямо з `pydantic`, а не з `fastapi`, як всі інші (`Query`, `Path`, `Body` тощо).
+///
## Оголошення атрибутів моделі
Ви можете використовувати `Field` з атрибутами моделі:
-=== "Python 3.10+"
-
- ```Python hl_lines="11-14"
- {!> ../../../docs_src/body_fields/tutorial001_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="11-14"
- {!> ../../../docs_src/body_fields/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="12-15"
- {!> ../../../docs_src/body_fields/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Варто користуватись `Annotated` версією, якщо це можливо..
-
- ```Python hl_lines="9-12"
- {!> ../../../docs_src/body_fields/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Варто користуватись `Annotated` версією, якщо це можливо..
-
- ```Python hl_lines="11-14"
- {!> ../../../docs_src/body_fields/tutorial001.py!}
- ```
+{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[11:14] *}
`Field` працює так само, як `Query`, `Path` і `Body`, у нього такі самі параметри тощо.
-!!! note "Технічні деталі"
- Насправді, `Query`, `Path` та інші, що ви побачите далі, створюють об'єкти підкласів загального класу `Param`, котрий сам є підкласом класу `FieldInfo` з Pydantic.
+/// note | Технічні деталі
- І `Field` від Pydantic також повертає екземпляр `FieldInfo`.
+Насправді, `Query`, `Path` та інші, що ви побачите далі, створюють об'єкти підкласів загального класу `Param`, котрий сам є підкласом класу `FieldInfo` з Pydantic.
- `Body` також безпосередньо повертає об'єкти підкласу `FieldInfo`. І є інші підкласи, які ви побачите пізніше, що є підкласами класу Body.
+І `Field` від Pydantic також повертає екземпляр `FieldInfo`.
- Пам'ятайте, що коли ви імпортуєте 'Query', 'Path' та інше з 'fastapi', вони фактично є функціями, які повертають спеціальні класи.
+`Body` також безпосередньо повертає об'єкти підкласу `FieldInfo`. І є інші підкласи, які ви побачите пізніше, що є підкласами класу Body.
-!!! tip
- Зверніть увагу, що кожен атрибут моделі із типом, значенням за замовчуванням та `Field` має ту саму структуру, що й параметр *функції обробки шляху*, з `Field` замість `Path`, `Query` і `Body`.
+Пам'ятайте, що коли ви імпортуєте 'Query', 'Path' та інше з 'fastapi', вони фактично є функціями, які повертають спеціальні класи.
+
+///
+
+/// tip
+
+Зверніть увагу, що кожен атрибут моделі із типом, значенням за замовчуванням та `Field` має ту саму структуру, що й параметр *функції обробки шляху*, з `Field` замість `Path`, `Query` і `Body`.
+
+///
## Додавання додаткової інформації
@@ -105,9 +46,12 @@
Ви дізнаєтеся більше про додавання додаткової інформації пізніше у документації, коли вивчатимете визначення прикладів.
-!!! warning
- Додаткові ключі, передані в `Field`, також будуть присутні у згенерованій схемі OpenAPI для вашого додатка.
- Оскільки ці ключі не обов'язково можуть бути частиною специфікації OpenAPI, деякі інструменти OpenAPI, наприклад, [OpenAPI валідатор](https://validator.swagger.io/), можуть не працювати з вашою згенерованою схемою.
+/// warning
+
+Додаткові ключі, передані в `Field`, також будуть присутні у згенерованій схемі OpenAPI для вашого додатка.
+Оскільки ці ключі не обов'язково можуть бути частиною специфікації OpenAPI, деякі інструменти OpenAPI, наприклад, [OpenAPI валідатор](https://validator.swagger.io/), можуть не працювати з вашою згенерованою схемою.
+
+///
## Підсумок
diff --git a/docs/uk/docs/tutorial/body-multiple-params.md b/docs/uk/docs/tutorial/body-multiple-params.md
new file mode 100644
index 000000000..e2acf8a70
--- /dev/null
+++ b/docs/uk/docs/tutorial/body-multiple-params.md
@@ -0,0 +1,170 @@
+# Тіло запиту - Декілька параметрів
+
+Тепер, коли ми розглянули використання `Path` та `Query`, розгляньмо більш просунуті способи оголошення тіла запиту в **FastAPI**.
+
+## Змішування `Path`, `Query` та параметрів тіла запиту
+
+По-перше, звісно, Ви можете вільно змішувати оголошення параметрів `Path`, `Query` та тіла запиту, і **FastAPI** правильно їх обробить.
+
+Також Ви можете оголосити параметри тіла як необов’язкові, встановивши для них значення за замовчуванням `None`:
+
+{* ../../docs_src/body_multiple_params/tutorial001_an_py310.py hl[18:20] *}
+
+/// note | Примітка
+
+Зверніть увагу, що в цьому випадку параметр `item`, який береться з тіла запиту, є необов'язковим, оскільки має значення за замовчуванням `None`.
+
+///
+
+## Декілька параметрів тіла запиту
+
+У попередньому прикладі *операція шляху* очікувала JSON з атрибутами `Item`, наприклад:
+
+```JSON
+{
+ "name": "Foo",
+ "description": "The pretender",
+ "price": 42.0,
+ "tax": 3.2
+}
+```
+Але Ви також можете оголосити декілька параметрів тіла, наприклад `item` та `user`:
+
+{* ../../docs_src/body_multiple_params/tutorial002_py310.py hl[20] *}
+
+У цьому випадку **FastAPI** розпізнає, що є кілька параметрів тіла (два параметри є моделями Pydantic).
+
+Тому він використає назви параметрів як ключі (назви полів) у тілі запиту, очікуючи:
+
+```JSON
+{
+ "item": {
+ "name": "Foo",
+ "description": "The pretender",
+ "price": 42.0,
+ "tax": 3.2
+ },
+ "user": {
+ "username": "dave",
+ "full_name": "Dave Grohl"
+ }
+}
+```
+
+/// note | Примітка
+
+Зверніть увагу, що хоча `item` оголошено, так само як і раніше, тепер він очікується в тілі під ключем `item`.
+
+///
+
+**FastAPI** автоматично конвертує дані із запиту таким чином, щоб параметр `item` отримав свій вміст, і те ж саме стосується `user`.
+
+Він виконає валідацію складених даних і задокументує їх відповідним чином у схемі OpenAPI та в автоматичній документації.
+
+## Одиничні значення в тілі запиту
+
+Так само як є `Query` і `Path` для визначення додаткових даних для параметрів запиту та шляху, **FastAPI** надає еквівалентний `Body`.
+
+Наприклад, розширюючи попередню модель, Ви можете вирішити додати ще один ключ `importance` в те ж саме тіло запиту разом із `item` і `user`.
+
+Якщо Ви оголосите його як є, то, оскільки це одиничне значення, **FastAPI** припускатиме, що це параметр запиту (query parameter).
+
+Але Ви можете вказати **FastAPI** обробляти його як інший ключ тіла (body key), використовуючи `Body`:
+
+{* ../../docs_src/body_multiple_params/tutorial003_an_py310.py hl[23] *}
+
+У цьому випадку **FastAPI** очікуватиме тіло запиту у такому вигляді:
+
+```JSON
+{
+ "item": {
+ "name": "Foo",
+ "description": "The pretender",
+ "price": 42.0,
+ "tax": 3.2
+ },
+ "user": {
+ "username": "dave",
+ "full_name": "Dave Grohl"
+ },
+ "importance": 5
+}
+```
+Знову ж таки, **FastAPI** конвертуватиме типи даних, перевірятиме їх, створюватиме документацію тощо.
+
+## Декілька body та query параметрів
+
+Звісно, Ви можете оголошувати додаткові query параметри запиту, коли це необхідно, на додаток до будь-яких параметрів тіла запиту.
+
+Оскільки за замовчуванням окремі значення інтерпретуються як параметри запиту, Вам не потрібно явно додавати `Query`, можна просто використати:
+
+```Python
+q: Union[str, None] = None
+```
+
+Або в Python 3.10 та вище:
+
+```Python
+q: str | None = None
+```
+
+Наприклад:
+
+{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[28] *}
+
+
+/// info | Інформація
+
+`Body` також має ті самі додаткові параметри валідації та метаданих, що й `Query`, `Path` та інші, які Ви побачите пізніше.
+
+///
+
+## Вкладений поодинокий параметр тіла запиту
+
+Припустимо, у вас є лише один параметр тіла запиту `item` з моделі Pydantic `Item`.
+
+За замовчуванням **FastAPI** очікуватиме, що тіло запиту міститиме вміст безпосередньо.
+
+Але якщо Ви хочете, щоб він очікував JSON з ключем `item`, а всередині — вміст моделі (так, як це відбувається при оголошенні додаткових параметрів тіла), Ви можете використати спеціальний параметр `Body` — `embed`:
+
+```Python
+item: Item = Body(embed=True)
+```
+
+як у прикладі:
+
+{* ../../docs_src/body_multiple_params/tutorial005_an_py310.py hl[17] *}
+
+У цьому випадку **FastAPI** очікуватиме тіло запиту такого вигляду:
+
+```JSON hl_lines="2"
+{
+ "item": {
+ "name": "Foo",
+ "description": "The pretender",
+ "price": 42.0,
+ "tax": 3.2
+ }
+}
+```
+
+замість:
+
+```JSON
+{
+ "name": "Foo",
+ "description": "The pretender",
+ "price": 42.0,
+ "tax": 3.2
+}
+```
+
+## Підсумок
+
+Ви можете додавати кілька параметрів тіла до Вашої *функції операції шляху* (*path operation function*), навіть якщо запит може мати лише одне тіло.
+
+Але **FastAPI** обробить це, надасть Вам потрібні дані у функції, перевірить їх та задокументує коректну схему в *операції шляху*.
+
+Також Ви можете оголошувати окремі значення, які будуть отримані як частина тіла запиту.
+
+Крім того, Ви можете вказати **FastAPI** вбудовувати тіло в ключ, навіть якщо оголошено лише один параметр.
diff --git a/docs/uk/docs/tutorial/body-nested-models.md b/docs/uk/docs/tutorial/body-nested-models.md
new file mode 100644
index 000000000..abc33f2eb
--- /dev/null
+++ b/docs/uk/docs/tutorial/body-nested-models.md
@@ -0,0 +1,245 @@
+# Тіло запиту - Вкладені моделі
+
+З **FastAPI** Ви можете визначати, перевіряти, документувати та використовувати моделі, які можуть бути вкладені на будь-яку глибину (завдяки Pydantic).
+
+## Поля списку
+
+Ви можете визначити атрибут як підтип. Наприклад, Python-список (`list`):
+
+{* ../../docs_src/body_nested_models/tutorial001_py310.py hl[12] *}
+
+Це зробить `tags` списком, хоча не визначається тип елементів списку.
+
+## Поля списку з параметром типу
+
+Але Python має специфічний спосіб оголошення списків з внутрішніми типами або "параметрами типу":
+### Імпортуємо `List` з модуля typing
+
+У Python 3.9 і вище можна використовувати стандартний `list` для оголошення таких типів, як ми побачимо нижче. 💡
+
+Але в Python версії до 3.9 (від 3.6 і вище) спочатку потрібно імпортувати `List` з модуля стандартної бібліотеки Python `typing`:
+
+{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *}
+
+### Оголошення `list` з параметром типу
+
+Щоб оголосити типи з параметрами типу (внутрішніми типами), такими як `list`, `dict`, `tuple`:
+
+* Якщо Ви використовуєте версію Python до 3.9, імпортуйте їх відповідну версію з модуля `typing`.
+* Передайте внутрішні типи як "параметри типу", використовуючи квадратні дужки: `[` and `]`.
+
+У Python 3.9 це буде виглядати так:
+
+```Python
+my_list: list[str]
+```
+
+У версіях Python до 3.9 це виглядає так:
+
+```Python
+from typing import List
+
+my_list: List[str]
+```
+
+Це стандартний синтаксис Python для оголошення типів.
+
+Використовуйте той самий стандартний синтаксис для атрибутів моделей з внутрішніми типами.
+
+Отже, у нашому прикладі, ми можемо зробити `tags` саме "списком рядків":
+
+{* ../../docs_src/body_nested_models/tutorial002_py310.py hl[12] *}
+
+## Типи множин
+
+Але потім ми подумали, що теги не повинні повторюватися, вони, ймовірно, повинні бути унікальними рядками.
+
+І Python має спеціальний тип даних для множин унікальних елементів — це `set`.
+
+Тому ми можемо оголосити `tags` як множину рядків:
+
+{* ../../docs_src/body_nested_models/tutorial003_py310.py hl[12] *}
+
+Навіть якщо Ви отримаєте запит з дубльованими даними, він буде перетворений у множину унікальних елементів.
+
+І коли Ви будете виводити ці дані, навіть якщо джерело містить дублікати, вони будуть виведені як множина унікальних елементів.
+
+І це буде анотовано/документовано відповідно.
+
+## Вкладені моделі
+
+Кожен атрибут моделі Pydantic має тип.
+
+Але цей тип сам може бути іншою моделлю Pydantic.
+
+Отже, Ви можете оголосити глибоко вкладені JSON "об'єкти" з конкретними іменами атрибутів, типами та перевірками.
+
+Усе це, вкладене без обмежень.
+
+### Визначення підмоделі
+
+Наприклад, ми можемо визначити модель `Image`:
+
+{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[7:9] *}
+
+### Використання підмоделі як типу
+
+А потім ми можемо використовувати її як тип атрибута:
+
+{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[18] *}
+
+Це означатиме, що **FastAPI** очікуватиме тіло запиту такого вигляду:
+
+```JSON
+{
+ "name": "Foo",
+ "description": "The pretender",
+ "price": 42.0,
+ "tax": 3.2,
+ "tags": ["rock", "metal", "bar"],
+ "image": {
+ "url": "http://example.com/baz.jpg",
+ "name": "The Foo live"
+ }
+}
+```
+
+Завдяки такій декларації у **FastAPI** Ви отримуєте:
+
+* Підтримку в редакторі (автозавершення тощо), навіть для вкладених моделей
+* Конвертацію даних
+* Валідацію даних
+* Автоматичну документацію
+
+## Спеціальні типи та валідація
+
+Окрім звичайних типів, таких як `str`, `int`, `float`, та ін. Ви можете використовувати складніші типи, які наслідують `str`.
+
+Щоб побачити всі доступні варіанти, ознайомтеся з оглядом типів у Pydantic. Деякі приклади будуть у наступних розділах.
+
+Наприклад, у моделі `Image` є поле `url`, тому ми можемо оголосити його як `HttpUrl` від Pydantic замість `str`:
+
+{* ../../docs_src/body_nested_models/tutorial005_py310.py hl[2,8] *}
+
+Рядок буде перевірено як дійсну URL-адресу і задокументовано в JSON Schema / OpenAPI як URL.
+
+## Атрибути зі списками підмоделей
+
+У Pydantic Ви можете використовувати моделі як підтипи для `list`, `set` тощо:
+
+{* ../../docs_src/body_nested_models/tutorial006_py310.py hl[18] *}
+
+Це означає, що **FastAPI** буде очікувати (конвертувати, валідувати, документувати тощо) JSON тіло запиту у вигляді:
+
+```JSON hl_lines="11"
+{
+ "name": "Foo",
+ "description": "The pretender",
+ "price": 42.0,
+ "tax": 3.2,
+ "tags": [
+ "rock",
+ "metal",
+ "bar"
+ ],
+ "images": [
+ {
+ "url": "http://example.com/baz.jpg",
+ "name": "The Foo live"
+ },
+ {
+ "url": "http://example.com/dave.jpg",
+ "name": "The Baz"
+ }
+ ]
+}
+```
+
+/// info | Інформація
+
+Зверніть увагу, що тепер ключ `images` містить список об'єктів зображень.
+
+///
+
+## Глибоко вкладені моделі
+
+Ви можете визначати вкладені моделі довільної глибини:
+
+{* ../../docs_src/body_nested_models/tutorial007_py310.py hl[7,12,18,21,25] *}
+
+/// info | Інформація
+
+Зверніть увагу, що в моделі `Offer` є список `Item`ів, які, своєю чергою, можуть мати необов'язковий список `Image`ів.
+
+///
+
+## Тіла запитів, що складаються зі списків
+
+Якщо верхній рівень JSON тіла, яке Ви очікуєте, є JSON `масивом` (у Python — `list`), Ви можете оголосити тип у параметрі функції, як і в моделях Pydantic:
+
+```Python
+images: List[Image]
+```
+або в Python 3.9 і вище:
+
+```Python
+images: list[Image]
+```
+
+наприклад:
+
+{* ../../docs_src/body_nested_models/tutorial008_py39.py hl[13] *}
+
+## Підтримка в редакторі всюди
+
+Ви отримаєте підтримку в редакторі всюди.
+
+Навіть для елементів у списках:
+
+
+
+Ви не змогли б отримати таку підтримку в редакторі, якби працювали напряму зі `dict`, а не з моделями Pydantic.
+
+Але Вам не потрібно турбуватися про це: вхідні dict'и автоматично конвертуються, а вихідні дані автоматично перетворюються в JSON.
+
+## Тіла з довільними `dict`
+
+Ви також можете оголосити тіло як `dict` з ключами одного типу та значеннями іншого типу.
+
+Це корисно, якщо Ви не знаєте наперед, які імена полів будуть дійсними (як у випадку з моделями Pydantic).
+
+Це буде корисно, якщо Ви хочете приймати ключі, які заздалегідь невідомі.
+
+---
+
+Це також зручно, якщо Ви хочете мати ключі іншого типу (наприклад, `int`).
+
+Ось що ми розглянемо далі.
+
+У цьому випадку Ви можете приймати будь-який `dict`, якщо його ключі — це `int`, а значення — `float`:
+
+{* ../../docs_src/body_nested_models/tutorial009_py39.py hl[7] *}
+
+/// tip | Порада
+
+Майте на увазі, що в JSON тілі ключі можуть бути лише рядками (`str`).
+
+Але Pydantic автоматично конвертує дані.
+
+Це означає, що навіть якщо клієнти вашого API надсилатимуть ключі у вигляді рядків, якщо вони містять цілі числа, Pydantic конвертує їх і проведе валідацію.
+
+Тобто `dict`, який Ви отримаєте як `weights`, матиме ключі типу `int` та значення типу `float`.
+
+///
+
+## Підсумок
+
+З **FastAPI** Ви маєте максимальну гнучкість завдяки моделям Pydantic, зберігаючи при цьому код простим, коротким та елегантним.
+
+А також отримуєте всі переваги:
+
+* Підтримка в редакторі (автодоповнення всюди!)
+* Конвертація даних (парсинг/сериалізація)
+* Валідація даних
+* Документація схем
+* Автоматичне створення документації
diff --git a/docs/uk/docs/tutorial/body.md b/docs/uk/docs/tutorial/body.md
index 11e94e929..38fed7bb8 100644
--- a/docs/uk/docs/tutorial/body.md
+++ b/docs/uk/docs/tutorial/body.md
@@ -8,28 +8,21 @@
Щоб оголосити тіло **запиту**, ви використовуєте Pydantic моделі з усією їх потужністю та перевагами.
-!!! info
- Щоб надіслати дані, ви повинні використовувати один із: `POST` (більш поширений), `PUT`, `DELETE` або `PATCH`.
+/// info
- Надсилання тіла із запитом `GET` має невизначену поведінку в специфікаціях, проте воно підтримується FastAPI лише для дуже складних/екстремальних випадків використання.
+Щоб надіслати дані, ви повинні використовувати один із: `POST` (більш поширений), `PUT`, `DELETE` або `PATCH`.
- Оскільки це не рекомендується, інтерактивна документація з Swagger UI не відображатиме документацію для тіла запиту під час використання `GET`, і проксі-сервери в середині можуть не підтримувати її.
+Надсилання тіла із запитом `GET` має невизначену поведінку в специфікаціях, проте воно підтримується FastAPI лише для дуже складних/екстремальних випадків використання.
+
+Оскільки це не рекомендується, інтерактивна документація з Swagger UI не відображатиме документацію для тіла запиту під час використання `GET`, і проксі-сервери в середині можуть не підтримувати її.
+
+///
## Імпортуйте `BaseModel` від Pydantic
Спочатку вам потрібно імпортувати `BaseModel` з `pydantic`:
-=== "Python 3.8 і вище"
-
- ```Python hl_lines="4"
- {!> ../../../docs_src/body/tutorial001.py!}
- ```
-
-=== "Python 3.10 і вище"
-
- ```Python hl_lines="2"
- {!> ../../../docs_src/body/tutorial001_py310.py!}
- ```
+{* ../../docs_src/body/tutorial001.py hl[4] *}
## Створіть свою модель даних
@@ -37,17 +30,7 @@
Використовуйте стандартні типи Python для всіх атрибутів:
-=== "Python 3.8 і вище"
-
- ```Python hl_lines="7-11"
- {!> ../../../docs_src/body/tutorial001.py!}
- ```
-
-=== "Python 3.10 і вище"
-
- ```Python hl_lines="5-9"
- {!> ../../../docs_src/body/tutorial001_py310.py!}
- ```
+{* ../../docs_src/body/tutorial001.py hl[7:11] *}
Так само, як і при оголошенні параметрів запиту, коли атрибут моделі має значення за замовчуванням, він не є обов’язковим. В іншому випадку це потрібно. Використовуйте `None`, щоб зробити його необов'язковим.
@@ -75,17 +58,7 @@
Щоб додати модель даних до вашої *операції шляху*, оголосіть її так само, як ви оголосили параметри шляху та запиту:
-=== "Python 3.8 і вище"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body/tutorial001.py!}
- ```
-
-=== "Python 3.10 і вище"
-
- ```Python hl_lines="16"
- {!> ../../../docs_src/body/tutorial001_py310.py!}
- ```
+{* ../../docs_src/body/tutorial001.py hl[18] *}
...і вкажіть її тип як модель, яку ви створили, `Item`.
@@ -134,32 +107,25 @@
-!!! tip
- Якщо ви використовуєте PyCharm як ваш редактор, ви можете використати Pydantic PyCharm Plugin.
+/// tip
- Він покращує підтримку редакторів для моделей Pydantic за допомогою:
+Якщо ви використовуєте PyCharm як ваш редактор, ви можете використати Pydantic PyCharm Plugin.
- * автозаповнення
- * перевірки типу
- * рефакторингу
- * пошуку
- * інспекції
+Він покращує підтримку редакторів для моделей Pydantic за допомогою:
+
+* автозаповнення
+* перевірки типу
+* рефакторингу
+* пошуку
+* інспекції
+
+///
## Використовуйте модель
Усередині функції ви можете отримати прямий доступ до всіх атрибутів об’єкта моделі:
-=== "Python 3.8 і вище"
-
- ```Python hl_lines="21"
- {!> ../../../docs_src/body/tutorial002.py!}
- ```
-
-=== "Python 3.10 і вище"
-
- ```Python hl_lines="19"
- {!> ../../../docs_src/body/tutorial002_py310.py!}
- ```
+{* ../../docs_src/body/tutorial002.py hl[21] *}
## Тіло запиту + параметри шляху
@@ -167,17 +133,7 @@
**FastAPI** розпізнає, що параметри функції, які відповідають параметрам шляху, мають бути **взяті з шляху**, а параметри функції, які оголошуються як моделі Pydantic, **взяті з тіла запиту**.
-=== "Python 3.8 і вище"
-
- ```Python hl_lines="17-18"
- {!> ../../../docs_src/body/tutorial003.py!}
- ```
-
-=== "Python 3.10 і вище"
-
- ```Python hl_lines="15-16"
- {!> ../../../docs_src/body/tutorial003_py310.py!}
- ```
+{* ../../docs_src/body/tutorial003.py hl[17:18] *}
## Тіло запиту + шлях + параметри запиту
@@ -185,17 +141,7 @@
**FastAPI** розпізнає кожен з них і візьме дані з потрібного місця.
-=== "Python 3.8 і вище"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body/tutorial004.py!}
- ```
-
-=== "Python 3.10 і вище"
-
- ```Python hl_lines="16"
- {!> ../../../docs_src/body/tutorial004_py310.py!}
- ```
+{* ../../docs_src/body/tutorial004.py hl[18] *}
Параметри функції будуть розпізнаватися наступним чином:
@@ -203,10 +149,13 @@
* Якщо параметр має **сингулярний тип** (наприклад, `int`, `float`, `str`, `bool` тощо), він буде інтерпретуватися як параметр **запиту**.
* Якщо параметр оголошується як тип **Pydantic моделі**, він інтерпретується як **тіло** запиту.
-!!! note
- FastAPI буде знати, що значення "q" не є обов'язковим через значення за замовчуванням "= None".
+/// note
- `Optional` у `Optional[str]` не використовується FastAPI, але дозволить вашому редактору надати вам кращу підтримку та виявляти помилки.
+FastAPI буде знати, що значення "q" не є обов'язковим через значення за замовчуванням "= None".
+
+`Optional` у `Optional[str]` не використовується FastAPI, але дозволить вашому редактору надати вам кращу підтримку та виявляти помилки.
+
+///
## Без Pydantic
diff --git a/docs/uk/docs/tutorial/cookie-param-models.md b/docs/uk/docs/tutorial/cookie-param-models.md
new file mode 100644
index 000000000..f070b6ac8
--- /dev/null
+++ b/docs/uk/docs/tutorial/cookie-param-models.md
@@ -0,0 +1,76 @@
+# Моделі для Cookie-параметрів
+
+Якщо у Вас є група **cookies** параметрів, які пов'язані між собою, Ви можете створити **Pydantic-модель**, щоб оголосити їх. 🍪
+
+Це дозволить Вам повторно **використовувати модель** у **різних місцях**, а також оголосити валідацію та метадані для всіх параметрів одночасно. 😎
+
+/// note | Нотатки
+
+Це підтримується з версії FastAPI `0.115.0`. 🤓
+
+///
+
+/// tip | Порада
+
+Ця ж техніка застосовується до `Query`, `Cookie`, та `Header`. 😎
+
+///
+
+## Cookie з Pydantic-моделлю
+
+Оголосіть **cookie-параметри**, які Вам потрібні, у **Pydantic-моделі**, а потім оголосіть параметр як `Cookie`:
+
+{* ../../docs_src/cookie_param_models/tutorial001_an_py310.py hl[9:12,16] *}
+
+**FastAPI** буде **витягувати** дані для **кожного поля** з **cookie** параметрів, отриманих у запиті, і передавати Вам Pydantic-модель, яку Ви визначили.
+
+## Перевірка у документації
+
+Ви можете побачити визначені cookie в інтерфейсі документації за адресою `/docs`:
+
+
+
+
+---
+Якщо Ви використовуєте PyCharm, ви можете:
+
+* Відкрити меню "Run".
+* Вибрати опцію "Debug...".
+* Потім з'явиться контекстне меню.
+* Вибрати файл для налагодження (у цьому випадку, `main.py`).
+
+Це запустить сервер з Вашим **FastAPI** кодом, зупиниться на точках зупину тощо.
+
+Ось як це може виглядати:
+
+
diff --git a/docs/uk/docs/tutorial/encoder.md b/docs/uk/docs/tutorial/encoder.md
index 49321ff11..f202c7989 100644
--- a/docs/uk/docs/tutorial/encoder.md
+++ b/docs/uk/docs/tutorial/encoder.md
@@ -20,17 +20,7 @@
Вона приймає об'єкт, такий як Pydantic model, і повертає його версію, сумісну з JSON:
-=== "Python 3.10+"
-
- ```Python hl_lines="4 21"
- {!> ../../../docs_src/encoder/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="5 22"
- {!> ../../../docs_src/encoder/tutorial001.py!}
- ```
+{* ../../docs_src/encoder/tutorial001_py310.py hl[4,21] *}
У цьому прикладі вона конвертує Pydantic model у `dict`, а `datetime` у `str`.
@@ -38,5 +28,8 @@
Вона не повертає велику строку `str`, яка містить дані у форматі JSON (як строка). Вона повертає стандартну структуру даних Python (наприклад `dict`) із значеннями та підзначеннями, які є сумісними з JSON.
-!!! note "Примітка"
- `jsonable_encoder` фактично використовується **FastAPI** внутрішньо для перетворення даних. Проте вона корисна в багатьох інших сценаріях.
+/// note | Примітка
+
+`jsonable_encoder` фактично використовується **FastAPI** внутрішньо для перетворення даних. Проте вона корисна в багатьох інших сценаріях.
+
+///
diff --git a/docs/uk/docs/tutorial/extra-data-types.md b/docs/uk/docs/tutorial/extra-data-types.md
index 01852803a..5da942b6e 100644
--- a/docs/uk/docs/tutorial/extra-data-types.md
+++ b/docs/uk/docs/tutorial/extra-data-types.md
@@ -55,76 +55,8 @@
Ось приклад *path operation* з параметрами, використовуючи деякі з вищезазначених типів.
-=== "Python 3.10+"
-
- ```Python hl_lines="1 3 12-16"
- {!> ../../../docs_src/extra_data_types/tutorial001_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="1 3 12-16"
- {!> ../../../docs_src/extra_data_types/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="1 3 13-17"
- {!> ../../../docs_src/extra_data_types/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Бажано використовувати `Annotated` версію, якщо це можливо.
-
- ```Python hl_lines="1 2 11-15"
- {!> ../../../docs_src/extra_data_types/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Бажано використовувати `Annotated` версію, якщо це можливо.
-
- ```Python hl_lines="1 2 12-16"
- {!> ../../../docs_src/extra_data_types/tutorial001.py!}
- ```
+{* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[1,3,12:16] *}
Зверніть увагу, що параметри всередині функції мають свій звичайний тип даних, і ви можете, наприклад, виконувати звичайні маніпуляції з датами, такі як:
-=== "Python 3.10+"
-
- ```Python hl_lines="18-19"
- {!> ../../../docs_src/extra_data_types/tutorial001_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="18-19"
- {!> ../../../docs_src/extra_data_types/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="19-20"
- {!> ../../../docs_src/extra_data_types/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Бажано використовувати `Annotated` версію, якщо це можливо.
-
- ```Python hl_lines="17-18"
- {!> ../../../docs_src/extra_data_types/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Бажано використовувати `Annotated` версію, якщо це можливо.
-
- ```Python hl_lines="18-19"
- {!> ../../../docs_src/extra_data_types/tutorial001.py!}
- ```
+{* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[18:19] *}
diff --git a/docs/uk/docs/tutorial/first-steps.md b/docs/uk/docs/tutorial/first-steps.md
index 725677e42..e910c4ccc 100644
--- a/docs/uk/docs/tutorial/first-steps.md
+++ b/docs/uk/docs/tutorial/first-steps.md
@@ -2,9 +2,7 @@
Найпростіший файл FastAPI може виглядати так:
-```Python
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py *}
Скопіюйте це до файлу `main.py`.
@@ -157,22 +155,21 @@ OpenAPI описує схему для вашого API. І ця схема вк
### Крок 1: імпортуємо `FastAPI`
-```Python hl_lines="1"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[1] *}
`FastAPI` це клас у Python, який надає всю функціональність для API.
-!!! note "Технічні деталі"
- `FastAPI` це клас, який успадковується безпосередньо від `Starlette`.
+/// note | Технічні деталі
- Ви також можете використовувати всю функціональність Starlette у `FastAPI`.
+`FastAPI` це клас, який успадковується безпосередньо від `Starlette`.
+
+Ви також можете використовувати всю функціональність Starlette у `FastAPI`.
+
+///
### Крок 2: створюємо екземпляр `FastAPI`
-```Python hl_lines="3"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[3] *}
Змінна `app` є екземпляром класу `FastAPI`.
Це буде головна точка для створення і взаємодії з API.
@@ -195,8 +192,11 @@ https://example.com/items/foo
/items/foo
```
-!!! info "Додаткова інформація"
- "Шлях" (path) також зазвичай називають "ендпоінтом" (endpoint) або "маршрутом" (route).
+/// info | Додаткова інформація
+
+"Шлях" (path) також зазвичай називають "ендпоінтом" (endpoint) або "маршрутом" (route).
+
+///
При створенні API, "шлях" є основним способом розділення "завдань" і "ресурсів".
#### Operation
@@ -236,24 +236,25 @@ https://example.com/items/foo
#### Визначте декоратор операції шляху (path operation decorator)
-```Python hl_lines="6"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[6] *}
Декоратор `@app.get("/")` вказує **FastAPI**, що функція нижче, відповідає за обробку запитів, які надходять до неї:
* шлях `/`
* використовуючи get операцію
-!!! info "`@decorator` Додаткова інформація"
- Синтаксис `@something` у Python називається "декоратором".
+/// info | `@decorator` Додаткова інформація
- Ви розташовуєте його над функцією. Як гарний декоративний капелюх (мабуть, звідти походить термін).
+Синтаксис `@something` у Python називається "декоратором".
- "Декоратор" приймає функцію нижче і виконує з нею якусь дію.
+Ви розташовуєте його над функцією. Як гарний декоративний капелюх (мабуть, звідти походить термін).
- У нашому випадку, цей декоратор повідомляє **FastAPI**, що функція нижче відповідає **шляху** `/` і **операції** `get`.
+"Декоратор" приймає функцію нижче і виконує з нею якусь дію.
- Це і є "декоратор операції шляху (path operation decorator)".
+У нашому випадку, цей декоратор повідомляє **FastAPI**, що функція нижче відповідає **шляху** `/` і **операції** `get`.
+
+Це і є "декоратор операції шляху (path operation decorator)".
+
+///
Можна також використовувати операції:
@@ -268,15 +269,17 @@ https://example.com/items/foo
* `@app.patch()`
* `@app.trace()`
-!!! tip "Порада"
- Ви можете використовувати кожну операцію (HTTP-метод) на свій розсуд.
+/// tip | Порада
- **FastAPI** не нав'язує жодного певного значення для кожного методу.
+Ви можете використовувати кожну операцію (HTTP-метод) на свій розсуд.
- Наведена тут інформація є рекомендацією, а не обов'язковою вимогою.
+**FastAPI** не нав'язує жодного певного значення для кожного методу.
- Наприклад, під час використання GraphQL зазвичай усі дії виконуються тільки за допомогою `POST` операцій.
+Наведена тут інформація є рекомендацією, а не обов'язковою вимогою.
+Наприклад, під час використання GraphQL зазвичай усі дії виконуються тільки за допомогою `POST` операцій.
+
+///
### Крок 4: визначте **функцію операції шляху (path operation function)**
@@ -286,9 +289,7 @@ https://example.com/items/foo
* **операція**: це `get`.
* **функція**: це функція, яка знаходиться нижче "декоратора" (нижче `@app.get("/")`).
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[7] *}
Це звичайна функція Python.
@@ -300,18 +301,17 @@ FastAPI викликатиме її щоразу, коли отримає зап
Ви також можете визначити її як звичайну функцію замість `async def`:
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial003.py!}
-```
+{* ../../docs_src/first_steps/tutorial003.py hl[7] *}
-!!! note "Примітка"
- Якщо не знаєте в чому різниця, подивіться [Конкурентність: *"Поспішаєш?"*](../async.md#in-a-hurry){.internal-link target=_blank}.
+/// note | Примітка
+
+Якщо не знаєте в чому різниця, подивіться [Конкурентність: *"Поспішаєш?"*](../async.md#in-a-hurry){.internal-link target=_blank}.
+
+///
### Крок 5: поверніть результат
-```Python hl_lines="8"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[8] *}
Ви можете повернути `dict`, `list`, а також окремі значення `str`, `int`, ітд.
diff --git a/docs/uk/docs/tutorial/handling-errors.md b/docs/uk/docs/tutorial/handling-errors.md
new file mode 100644
index 000000000..12a356cd0
--- /dev/null
+++ b/docs/uk/docs/tutorial/handling-errors.md
@@ -0,0 +1,255 @@
+# Обробка Помилок
+
+Є багато ситуацій, коли потрібно повідомити клієнта, який використовує Ваш API, про помилку.
+
+Цим клієнтом може бути браузер із фронтендом, код іншого розробника, IoT-пристрій тощо.
+
+Можливо, Вам потрібно повідомити клієнта, що:
+
+* У нього недостатньо прав для виконання цієї операції.
+* Він не має доступу до цього ресурсу.
+* Елемент, до якого він намагається отримати доступ, не існує.
+* тощо.
+
+У таких випадках зазвичай повертається **HTTP статус-код** в діапазоні **400** (від 400 до 499).
+
+Це схоже на HTTP статус-коди 200 (від 200 до 299). Ці "200" статус-коди означають, що запит пройшов успішно.
+
+Статус-коди в діапазоні 400 означають, що сталася помилка з боку клієнта.
+
+Пам'ятаєте всі ці помилки **404 Not Found** (і жарти про них)?
+
+## Використання `HTTPException`
+
+Щоб повернути HTTP-відповіді з помилками клієнту, використовуйте `HTTPException`.
+
+### Імпорт `HTTPException`
+
+{* ../../docs_src/handling_errors/tutorial001.py hl[1] *}
+
+### Використання `HTTPException` у коді
+
+`HTTPException` — це звичайна помилка Python із додатковими даними, які стосуються API.
+
+Оскільки це помилка Python, Ви не `повертаєте` його, а `генеруєте` (генеруєте помилку).
+
+Це також означає, що якщо Ви перебуваєте всередині допоміжної функції, яку викликаєте всередині своєї *функції операції шляху*, і там генеруєте `HTTPException`, всередині цієї допоміжної функції, то решта коду в *функції операції шляху* не буде виконана. Запит одразу завершиться, і HTTP-помилка з `HTTPException` буде надіслана клієнту.
+
+Перевага використання `генерації` (raise) помилки замість `повернення` значення (return) стане більш очевидним в розділі про Залежності та Безпеку.
+
+У цьому прикладі, якщо клієнт запитує елемент за ID, якого не існує, буде згенеровано помилку зі статус-кодом `404`:
+
+{* ../../docs_src/handling_errors/tutorial001.py hl[11] *}
+
+### Отримана відповідь
+
+Якщо клієнт робить запит за шляхом `http://example.com/items/foo` (де `item_id` `"foo"`), він отримає статус-код 200 і JSON відповідь:
+
+```JSON
+{
+ "item": "The Foo Wrestlers"
+}
+```
+
+Але якщо клієнт робить запит на `http://example.com/items/bar` (де `item_id` має не існуюче значення `"bar"`), то отримає статус-код 404 (помилка "не знайдено") та відповідь:
+
+```JSON
+{
+ "detail": "Item not found"
+}
+```
+
+/// tip | Порада
+
+Під час виклику `HTTPException` Ви можете передати будь-яке значення, яке може бути перетворене в JSON, як параметр `detail`, а не лише рядок (`str`).
+
+Ви можете передати `dict`, `list` тощо.
+
+Вони обробляються автоматично за допомогою **FastAPI** та перетворюються в JSON.
+
+///
+
+## Додавання власних заголовків
+
+Іноді потрібно додати власні заголовки до HTTP-помилки, наприклад, для певних типів безпеки.
+
+Ймовірно, Вам не доведеться використовувати це безпосередньо у своєму коді.
+
+Але якщо Вам знадобиться це для складного сценарію, Ви можете додати власні заголовки:
+
+{* ../../docs_src/handling_errors/tutorial002.py hl[14] *}
+
+## Встановлення власних обробників помилок
+
+Ви можете додати власні обробники помилок за допомогою тих самих утиліт обробки помилок зі Starlette.
+
+Припустимо, у Вас є власний обʼєкт помилки `UnicornException`, яке Ви (або бібліотека, яку Ви використовуєте) може `згенерувати` (`raise`).
+
+І Ви хочете обробляти це виключення глобально за допомогою FastAPI.
+
+Ви можете додати власний обробник виключень за допомогою `@app.exception_handler()`:
+
+{* ../../docs_src/handling_errors/tutorial003.py hl[5:7,13:18,24] *}
+
+Тут, якщо Ви звернетеся до `/unicorns/yolo`, то згенерується помилка `UnicornException`.
+
+Але вона буде оброблена функцією-обробником `unicorn_exception_handler`.
+
+Отже, Ви отримаєте зрозумілу помилку зі HTTP-статусом `418` і JSON-відповіддю:
+
+```JSON
+{"message": "Oops! yolo did something. There goes a rainbow..."}
+```
+
+/// note | Технічні деталі
+
+Ви також можете використовувати `from starlette.requests import Request` і `from starlette.responses import JSONResponse`.
+
+**FastAPI** надає ті самі `starlette.responses`, що й `fastapi.responses`, просто для зручності розробника. Але більшість доступних відповідей надходять безпосередньо зі Starlette. Те ж саме стосується і `Request`.
+
+///
+
+## Перевизначення обробників помилок за замовчуванням
+
+**FastAPI** має кілька обробників помилок за замовчуванням.
+
+Ці обробники відповідають за повернення стандартних JSON-відповідей, коли Ви `генеруєте` (`raise`) `HTTPException`, а також коли запит містить некоректні дані.
+
+Ви можете перевизначити ці обробники, створивши власні.
+
+### Перевизначення помилок валідації запиту
+
+Коли запит містить некоректні дані, **FastAPI** генерує `RequestValidationError`.
+
+І також включає обробник помилок за замовчуванням для нього.
+
+Щоб перевизначити його, імпортуйте `RequestValidationError` і використовуйте його з `@app.exception_handler(RequestValidationError)` для декорування обробника помилок.
+
+Обробник помилок отримує `Request` і саму помилку.
+
+{* ../../docs_src/handling_errors/tutorial004.py hl[2,14:16] *}
+
+Тепер, якщо Ви перейдете за посиланням `/items/foo`, замість того, щоб отримати стандартну JSON-помилку:
+
+```JSON
+{
+ "detail": [
+ {
+ "loc": [
+ "path",
+ "item_id"
+ ],
+ "msg": "value is not a valid integer",
+ "type": "type_error.integer"
+ }
+ ]
+}
+```
+
+Ви отримаєте текстову версію:
+
+```
+1 validation error
+path -> item_id
+ value is not a valid integer (type=type_error.integer)
+```
+
+#### `RequestValidationError` проти `ValidationError`
+
+/// warning | Увага
+
+Це технічні деталі, які Ви можете пропустити, якщо вони зараз не важливі для Вас.
+
+///
+
+`RequestValidationError` є підкласом Pydantic `ValidationError`.
+
+**FastAPI** використовує його для того, якщо Ви використовуєте модель Pydantic у `response_model` і у ваших даних є помилка, Ви побачили помилку у своєму журналі.
+
+Але клієнт/користувач не побачить її. Натомість клієнт отримає "Internal Server Error" зі статусом HTTP `500`.
+
+Так має бути, якщо у Вас виникла `ValidationError` Pydantic у *відповіді* або деінде у вашому коді (не у *запиті* клієнта), це насправді є помилкою у Вашому коді.
+
+І поки Ви її виправляєте, клієнти/користувачі не повинні мати доступу до внутрішньої інформації про помилку, оскільки це може призвести до вразливості безпеки.
+
+### Перевизначення обробника помилок `HTTPException`
+
+Аналогічно, Ви можете перевизначити обробник `HTTPException`.
+
+Наприклад, Ви можете захотіти повернути текстову відповідь замість JSON для цих помилок:
+
+{* ../../docs_src/handling_errors/tutorial004.py hl[3:4,9:11,22] *}
+
+/// note | Технічні деталі
+
+Ви також можете використовувати `from starlette.responses import PlainTextResponse`.
+
+**FastAPI** надає ті самі `starlette.responses`, що й `fastapi.responses`, просто для зручності розробника. Але більшість доступних відповідей надходять безпосередньо зі Starlette.
+
+///
+
+### Використання тіла `RequestValidationError`
+
+`RequestValidationError` містить `body`, який він отримав із некоректними даними.
+
+Ви можете використовувати це під час розробки свого додатка, щоб логувати тіло запиту та налагоджувати його, повертати користувачеві тощо.
+
+{* ../../docs_src/handling_errors/tutorial005.py hl[14] *}
+
+Тепер спробуйте надіслати некоректний елемент, наприклад:
+
+```JSON
+{
+ "title": "towel",
+ "size": "XL"
+}
+```
+Ви отримаєте відповідь, яка повідомить Вам, які саме дані є некоректні у вашому тілі запиту:
+
+
+```JSON hl_lines="12-15"
+{
+ "detail": [
+ {
+ "loc": [
+ "body",
+ "size"
+ ],
+ "msg": "value is not a valid integer",
+ "type": "type_error.integer"
+ }
+ ],
+ "body": {
+ "title": "towel",
+ "size": "XL"
+ }
+}
+```
+
+#### `HTTPException` FastAPI проти `HTTPException` Starlette
+
+**FastAPI** має власний `HTTPException`.
+
+І клас помилки `HTTPException` в **FastAPI** успадковується від класу помилки `HTTPException` в Starlette.
+
+Єдина різниця полягає в тому, що `HTTPException` в **FastAPI** приймає будь-які дані, які можна перетворити на JSON, для поля `detail`, тоді як `HTTPException` у Starlette приймає тільки рядки.
+
+Отже, Ви можете продовжувати використовувати `HTTPException` в **FastAPI** як зазвичай у своєму коді.
+
+Але коли Ви реєструєте обробник виключень, слід реєструвати його для `HTTPException` зі Starlette.
+
+Таким чином, якщо будь-яка частина внутрішнього коду Starlette або розширення чи плагін Starlette згенерує (raise) `HTTPException`, Ваш обробник зможе перехопити та обробити її.
+
+У цьому прикладі, щоб мати можливість використовувати обидва `HTTPException` в одному коді, помилка Starlette перейменовується на `StarletteHTTPException`:
+
+```Python
+from starlette.exceptions import HTTPException as StarletteHTTPException
+```
+
+### Повторне використання обробників помилок **FastAPI**
+
+Якщо Ви хочете використовувати помилки разом із такими ж обробниками помилок за замовчуванням, як у **FastAPI**, Ви можете імпортувати та повторно використовувати їх із `fastapi.exception_handlers`:
+
+{* ../../docs_src/handling_errors/tutorial006.py hl[2:5,15,21] *}
+
+У цьому прикладі Ви просто використовуєте `print` для виведення дуже інформативного повідомлення, але Ви зрозуміли основну ідею. Ви можете обробити помилку та повторно використовувати обробники помилок за замовчуванням.
diff --git a/docs/uk/docs/tutorial/header-param-models.md b/docs/uk/docs/tutorial/header-param-models.md
new file mode 100644
index 000000000..6f7b0bdae
--- /dev/null
+++ b/docs/uk/docs/tutorial/header-param-models.md
@@ -0,0 +1,58 @@
+# Моделі Параметрів Заголовків
+
+Якщо у Вас є група пов’язаних параметрів заголовків, Ви можете створити **Pydantic модель** для їх оголошення.
+
+Це дозволить Вам повторно **використовувати модель** в **різних місцях**, а також оголосити валідації та метадані для всіх параметрів одночасно. 😎
+
+/// note | Нотатки
+
+Ця можливість підтримується починаючи з версії FastAPI `0.115.0`. 🤓
+
+///
+
+## Параметри Заголовків з Використанням Pydantic Model
+
+Оголосіть потрібні **параметри заголовків** у **Pydantic моделі**, а потім оголосіть параметр як `Header`:
+
+{* ../../docs_src/header_param_models/tutorial001_an_py310.py hl[9:14,18] *}
+
+FastAPI буде витягувати дані для кожного поля з заголовків у запиті та передавати їх у створену Вами Pydantic модель.
+
+**FastAPI** буде **витягувати** дані для **кожного поля** з **заголовків** у запиті та передавати їх у створену Вами Pydantic модель.
+
+## Перевірка в Документації
+
+Ви можете побачити необхідні заголовки в інтерфейсі документації за адресою `/docs`:
+
+
+contact поля| Параметр | Тип | Опис |
|---|---|---|
name | str | Ім'я контактної особи або організації. |
url | str | URL з інформацією для контакту. Повинен бути у форматі URL. |
email | str | Email контактної особи або організації. Повинен бути у форматі електронної пошти. |
license_info поля| Параметр | Тип | Опис |
|---|---|---|
name | str | ОБОВ'ЯЗКОВО (якщо встановлено license_info). Назва ліцензії для API. |
identifier | str | Ліцензійний вираз за SPDX для API. Поле identifier взаємовиключне з полем url. Доступно з OpenAPI 3.1.0, FastAPI 0.99.0. |
url | str | URL до ліцензії, яка використовується для API. Повинен бути у форматі URL. |
+
+## Ідентифікатор ліцензії
+
+З початку використання OpenAPI 3.1.0 та FastAPI 0.99.0 Ви також можете налаштувати `license_info` за допомогою `identifier` замість `url`.
+
+Наприклад:
+
+{* ../../docs_src/metadata/tutorial001_1.py hl[31] *}
+
+## Метадані для тегів
+
+Ви також можете додати додаткові метадані для різних тегів, які використовуються для групування операцій шляхів, за допомогою параметра `openapi_tags`.
+
+Він приймає список, який містить один словник для кожного тега.
+
+Кожен словник може містити:
+
+* `name` (**обов'язково**): `str` з тією ж назвою тегу, яку Ви використовуєте у параметрі `tags` у Ваших *операціях шляху* та `APIRouter`s.
+* `description`: `str` з коротким описом тегу. Може містити Markdown і буде відображено в інтерфейсі документації.
+* `externalDocs`: `dict` який описує зовнішню документацію з такими полями:
+ * `description`: `str` з коротким описом зовнішньої документації.
+ * `url` (**обов'язково**): `str`з URL-адресою зовнішньої документації.
+
+### Створення метаданих для тегів
+
+Спробуймо це на прикладі з тегами для `users` та `items`.
+
+Створіть метадані для своїх тегів і передайте їх у параметр `openapi_tags`:
+
+{* ../../docs_src/metadata/tutorial004.py hl[3:16,18] *}
+
+Зверніть увагу, що в описах можна використовувати Markdown, наприклад, "login" буде показано жирним шрифтом (**login**), а "fancy" буде показано курсивом (_fancy_).
+
+/// tip | Порада
+
+Не обов'язково додавати метадані для всіх тегів, які Ви використовуєте.
+
+///
+
+### Використання тегів
+
+Використовуйте параметр `tags` зі своїми *операціями шляху* (і `APIRouter`) для призначення їх до різних тегів:
+
+{* ../../docs_src/metadata/tutorial004.py hl[21,26] *}
+
+/// info | Інформація
+
+Детальніше про теги читайте в розділі [Конфігурація шляхів операцій](path-operation-configuration.md#tags){.internal-link target=_blank}.
+
+///
+
+### Перевірка документації
+
+Якщо Ви зараз перевірите документацію, вона покаже всі додаткові метадані:
+
+
+
+### Порядок тегів
+
+Порядок кожного словника метаданих тегу також визначає порядок відображення в інтерфейсі документації.
+
+Наприклад, хоча `users` мав би йти після `items` в алфавітному порядку, він відображається перед ними, оскільки ми додали його метадані як перший словник у списку.
+
+## URL для OpenAPI
+
+За замовчуванням схема OpenAPI надається за адресою `/openapi.json`.
+
+Але Ви можете налаштувати це за допомогою параметра `openapi_url`.
+
+Наприклад, щоб налаштувати його на `/api/v1/openapi.json`:
+
+{* ../../docs_src/metadata/tutorial002.py hl[3] *}
+
+Якщо Ви хочете повністю вимкнути схему OpenAPI, Ви можете встановити `openapi_url=None`, це також вимкне інтерфейси документації, які її використовують.
+
+## URL-адреси документації
+
+Ви можете налаштувати два інтерфейси користувача для документації, які включені:
+
+* **Swagger UI**: доступний за адресою `/docs`.
+ * Ви можете змінити його URL за допомогою параметра `docs_url`.
+ * Ви можете вимкнути його, встановивши `docs_url=None`.
+* **ReDoc**: доступний за адресою `/redoc`.
+ * Ви можете змінити його URL за допомогою параметра `redoc_url`.
+ * Ви можете вимкнути його, встановивши `redoc_url=None`.
+
+Наприклад, щоб налаштувати Swagger UI на `/documentation` і вимкнути ReDoc:
+
+{* ../../docs_src/metadata/tutorial003.py hl[3] *}
diff --git a/docs/uk/docs/tutorial/middleware.md b/docs/uk/docs/tutorial/middleware.md
new file mode 100644
index 000000000..807be484a
--- /dev/null
+++ b/docs/uk/docs/tutorial/middleware.md
@@ -0,0 +1,75 @@
+# Middleware (Проміжний шар)
+
+У **FastAPI** можна додавати middleware (проміжний шар).
+
+"Middleware" — це функція, яка працює з кожним **запитом** перед його обробкою будь-якою конкретною *операцією шляху* (*path operation*), а також з кожною **відповіддю** перед її поверненням.
+
+* Middleware отримує кожен **запит**, що надходить до Вашого застосунку.
+* Може виконати певні дії із цим **запитом** або запустити необхідний код.
+* Далі передає **запит** для обробки основним застосунком (*операцією шляху*).
+* Отримує **відповідь**, сформовану застосунком (*операцією шляху*).
+* Може змінити цю **відповідь** або виконати додатковий код.
+* Повертає **відповідь** клієнту.
+
+/// note | Технічні деталі
+
+Якщо у Вас є залежності з `yield`, код виходу виконається *після* middleware.
+
+Якщо були заплановані фонові задачі (background tasks - розглянуто далі), вони виконаються *після* всіх middleware.
+
+///
+
+## Створення middleware
+
+Щоб створити middleware, Ви використовуєте декоратор `@app.middleware("http")` на функції.
+
+Функція middleware отримує:
+
+* `Запит`.
+* Функцію `call_next`, яка приймає `запит` як параметр.
+ * Ця функція передає `запит` відповідній *операції шляху*.
+ * Потім вона повертає `відповідь`, згенеровану цією *операцією шляху*.
+
+* Ви можете ще змінити `відповідь` перед тим, як повернути її.
+
+
+{* ../../docs_src/middleware/tutorial001.py hl[8:9,11,14] *}
+
+/// tip | Порада
+
+Не забувайте, що власні заголовки можна додавати, використовуючи префікс 'X-'.
+
+Але якщо у Вас є власні заголовки, які Ви хочете, щоб браузерний клієнт міг побачити, потрібно додати їх до Вашої конфігурації CORS (див. [CORS (Обмін ресурсами між різними джерелами)](cors.md){.internal-link target=_blank} за допомогою параметра `expose_headers`, описаного в документації Starlette по CORS.
+
+///
+
+/// note | Технічні деталі
+
+Ви також можете використати `from starlette.requests import Request`.
+
+**FastAPI** надає це для Вашої зручності як розробника. Але він походить безпосередньо зі Starlette.
+
+///
+
+### До і після `response`(`відповіді`)
+
+Ви можете додати код, який буде виконуватися з `запитом` (`request`), до того, як його обробить будь-яка *операція шляху* (*path operation*).
+
+Також Ви можете додати код, який буде виконуватися після того, як `відповідь` (`response`) буде згенеровано, перед тим як його повернути.
+
+Наприклад, Ви можете додати власний заголовок `X-Process-Time`, який міститиме час у секундах, який витратився на обробку запиту та генерацію відповіді:
+
+{* ../../docs_src/middleware/tutorial001.py hl[10,12:13] *}
+
+
+/// tip | Підказка
+
+Тут ми використовуємо `time.perf_counter()` замість `time.time()` оскільки він може бути більш точним для таких випадків. 🤓
+
+///
+
+## Інші middlewares
+
+Ви можете пізніше прочитати більше про інші middlewares в [Advanced User Guide: Advanced Middleware](../advanced/middleware.md){.internal-link target=_blank}.
+
+Ви дізнаєтесь, як обробляти CORS за допомогою middleware в наступному розділі.
diff --git a/docs/uk/docs/tutorial/path-params-numeric-validations.md b/docs/uk/docs/tutorial/path-params-numeric-validations.md
new file mode 100644
index 000000000..281ee183c
--- /dev/null
+++ b/docs/uk/docs/tutorial/path-params-numeric-validations.md
@@ -0,0 +1,165 @@
+# Path Параметри та валідація числових даних
+
+Так само як Ви можете оголошувати додаткові перевірки та метадані для query параметрів за допомогою `Query`, Ви можете оголошувати той самий тип перевірок і метаданих для параметрів шляху за допомогою `Path`.
+
+## Імпорт Path
+
+Спочатку імпортуйте `Path` з `fastapi` і імпортуйте `Annotated`:
+
+{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[1,3] *}
+
+/// info | Інформація
+
+FastAPI додав підтримку `Annotated` (і почав рекомендувати його використання) у версії 0.95.0.
+
+Якщо у Вас стара версія, при спробі використати `Annotated` можуть виникати помилки.
+
+Переконайтеся, що Ви [оновили версію FastAPI](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank} принаймні до версії 0.95.1 перед використанням `Annotated`.
+
+///
+
+## Оголошення метаданих
+
+Ви можете оголошувати всі ті ж параметри, що і для `Query`.
+
+Наприклад, щоб оголосити значення метаданих `title` для параметра шляху `item_id`, Ви можете написати:
+
+{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[10] *}
+
+/// note | Примітка
+
+Параметр шляху завжди є обов’язковим, оскільки він має бути частиною шляху. Навіть якщо Ви оголосите його зі значенням `None` або встановите значення за замовчуванням — він все одно залишатиметься обов’язковим.
+
+///
+
+## Упорядковуйте параметри, як Вам потрібно
+
+/// tip | Підказка
+
+Це, мабуть, не настільки важливо або необхідно, якщо Ви використовуєте `Annotated`.
+
+///
+
+Припустимо, Ви хочете оголосити параметр запиту `q` як обов’язковий `str`.
+
+І Вам не потрібно оголошувати нічого іншого для цього параметра, тому немає потреби використовувати `Query`.
+
+Але Вам все одно потрібно використовувати `Path` для параметра шляху `item_id`. І з певних причин Ви не хочете використовувати `Annotated`.
+
+Python видасть помилку, якщо розмістити значення з "default" перед значенням, яке не має "default".
+
+Але Ви можете змінити порядок і розмістити значення без значення за замовчуванням (параметр запиту `q`) першим.
+
+
+Для **FastAPI** порядок не має значення. Він визначає параметри за їх іменами, типами та значеннями за замовчуванням (`Query`, `Path` тощо) і не звертає уваги на порядок.
+
+Тому Ви можете оголосити Вашу функцію так:
+
+//// tab | Python 3.8 non-Annotated
+
+/// tip | Підказка
+
+За можливості віддавайте перевагу версії з використанням `Annotated`.
+
+///
+
+{* ../../docs_src/path_params_numeric_validations/tutorial002.py hl[7] *}
+
+////
+
+Але майте на увазі, що якщо Ви використовуєте `Annotated`, ця проблема не виникне, оскільки Ви не використовуєте значення за замовчуванням для параметрів `Query()` або `Path()`.
+
+{* ../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py *}
+
+## Упорядковуйте параметри за потребою, хитрощі
+
+/// tip | Підказка
+
+Це, мабуть, не настільки важливо або необхідно, якщо Ви використовуєте `Annotated`.
+
+///
+
+Ось **невелика хитрість**, яка може стати в пригоді, хоча вона рідко знадобиться.
+
+Якщо Ви хочете:
+
+* оголосити параметр запиту `q` без використання `Query` або значення за замовчуванням
+* оголосити параметр шляху `item_id`, використовуючи `Path`
+* розмістити їх у різному порядку
+* не використовувати `Annotated`
+
+...у Python є спеціальний синтаксис для цього.
+
+Передайте `*` як перший параметр функції.
+
+Python нічого не зробить із цією `*`, але розпізнає, що всі наступні параметри слід викликати як аргументи за ключовим словом (пари ключ-значення), також відомі як kwargs. Навіть якщо вони не мають значення за замовчуванням.
+
+{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *}
+
+### Краще з `Annotated`
+
+Майте на увазі, якщо Ви використовуєте `Annotated`, оскільки Ви не використовуєте значення за замовчуванням для параметрів функції, цієї проблеми не виникне, і, швидше за все, Вам не потрібно буде використовувати `*`.
+
+{* ../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py hl[10] *}
+
+## Валідація числових даних: більше або дорівнює
+
+За допомогою `Query` і `Path` (та інших, які Ви побачите пізніше) можна оголошувати числові обмеження.
+
+Тут, завдяки `ge=1`, `item_id` має бути цілим числом, яке "`g`reater than or `e`qual" (більше або дорівнює) `1`.
+
+{* ../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py hl[10] *}
+
+## Валідація числових даних: більше ніж і менше або дорівнює
+
+Те саме застосовується до:
+
+* `gt`: `g`reater `t`han (більше ніж)
+* `le`: `l`ess than or `e`qual (менше або дорівнює)
+
+{* ../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py hl[10] *}
+
+## Валідація числових даних: float, більше ніж і менше ніж
+
+Валідація чисел також працює для значень типу `float`.
+
+Ось де стає важливо мати можливість оголошувати gt, а не тільки ge. Це дозволяє, наприклад, вимагати, щоб значення було більше `0`, навіть якщо воно менше `1`.
+
+Таким чином, значення `0.5` буде допустимим. Але `0.0` або `0` — ні.
+
+Те саме стосується lt.
+
+{* ../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py hl[13] *}
+
+## Підсумок
+
+За допомогою `Query`, `Path` (і інших параметрів, які Ви ще не бачили) можна оголошувати метадані та перевірки рядків, так само як у [Query параметри та валідація рядків](query-params-str-validations.md){.internal-link target=_blank}.
+
+Також можна оголошувати числові перевірки:
+
+* `gt`: `g`reater `t`han (більше ніж)
+* `ge`: `g`reater than or `e`qual (більше або дорівнює)
+* `lt`: `l`ess `t`han (менше ніж)
+* `le`: `l`ess than or `e`qual (менше або дорівнює)
+
+/// info | Інформація
+
+`Query`, `Path` та інші класи, які Ви побачите пізніше, є підкласами спільного класу `Param`.
+
+Всі вони мають однакові параметри для додаткових перевірок і метаданих, які Ви вже бачили.
+
+///
+
+/// note | Технічні деталі
+
+Коли Ви імпортуєте `Query`, `Path` та інші з `fastapi`, насправді це функції.
+
+При виклику вони повертають екземпляри класів з такими ж іменами.
+
+Тобто Ви імпортуєте `Query`, яка є функцією. А коли Ви її викликаєте, вона повертає екземпляр класу, який теж називається `Query`.
+
+Ці функції створені таким чином (замість використання класів напряму), щоб Ваш редактор не відзначав їхні типи як помилки.
+
+Таким чином, Ви можете користуватися своїм звичайним редактором і інструментами для програмування без додаткових налаштувань для ігнорування таких помилок.
+
+///
diff --git a/docs/uk/docs/tutorial/path-params.md b/docs/uk/docs/tutorial/path-params.md
new file mode 100644
index 000000000..e7df1f19a
--- /dev/null
+++ b/docs/uk/docs/tutorial/path-params.md
@@ -0,0 +1,261 @@
+# Path Параметри
+
+Ви можете визначити "параметри" або "змінні" шляху, використовуючи синтаксис форматованих рядків:
+
+{* ../../docs_src/path_params/tutorial001.py hl[6:7] *}
+
+Значення параметра шляху `item_id` передається у функцію як аргумент `item_id`.
+
+Якщо запустити цей приклад та перейти за посиланням http://127.0.0.1:8000/items/foo, то отримаємо таку відповідь:
+
+```JSON
+{"item_id":"foo"}
+```
+
+## Path параметри з типами
+
+Ви можете визначити тип параметра шляху у функції, використовуючи стандартні анотації типів Python:
+
+{* ../../docs_src/path_params/tutorial002.py hl[7] *}
+
+У такому випадку `item_id` визначається як `int`.
+
+/// check | Примітка
+
+Це дасть можливість підтримки редактора всередині функції з перевірками помилок, автодоповнення тощо.
+
+///
+
+## Перетворення даних
+
+Якщо запустити цей приклад і перейти за посиланням http://127.0.0.1:8000/items/3, то отримаєте таку відповідь:
+
+```JSON
+{"item_id":3}
+```
+
+/// check | Примітка
+
+Зверніть увагу, що значення, яке отримала (і повернула) ваша функція, — це `3`. Це Python `int`, а не рядок `"3"`.
+
+Отже, з таким оголошенням типу **FastAPI** автоматично виконує "парсинг" запитів.
+
+///
+
+## Перевірка даних
+
+Якщо ж відкрити у браузері посилання http://127.0.0.1:8000/items/foo, то побачимо цікаву HTTP-помилку:
+
+```JSON
+{
+ "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"
+ }
+ ]
+}
+```
+тому що параметр шляху має значення `"foo"`, яке не є типом `int`.
+
+Таку саму помилку отримаємо, якщо передати `float` замість `int`, як бачимо, у цьому прикладі: http://127.0.0.1:8000/items/4.2
+
+/// check | Примітка
+
+Отже, **FastAPI** надає перевірку типів з таким самим оголошенням типу в Python.
+
+Зверніть увагу, що помилка також чітко вказує саме на те місце, де валідація не пройшла.
+
+Це неймовірно корисно під час розробки та дебагінгу коду, що взаємодіє з вашим API.
+
+///
+
+## Документація
+
+Тепер коли відкриєте свій браузер за посиланням http://127.0.0.1:8000/docs, то побачите автоматично згенеровану, інтерактивну API-документацію:
+
+
+
+/// check | Примітка
+
+Знову ж таки, лише з цим самим оголошенням типу в Python, FastAPI надає вам автоматичну, інтерактивну документацію (з інтеграцією Swagger UI).
+
+Зверніть увагу, що параметр шляху оголошений як ціле число.
+
+
+///
+
+## Переваги стандартизації, альтернативна документація
+
+І оскільки згенерована схема відповідає стандарту OpenAPI, існує багато сумісних інструментів.
+
+З цієї причини FastAPI також надає альтернативну документацію API (використовуючи ReDoc), до якої можна отримати доступ за посиланням http://127.0.0.1:8000/redoc:
+
+
+
+Таким чином, існує багато сумісних інструментів, включаючи інструменти для генерації коду для багатьох мов.
+
+
+## Pydantic
+
+Вся валідація даних виконується за лаштунками за допомогою Pydantic, тому Ви отримуєте всі переваги від його використання. І можете бути впевнені, що все в надійних руках.
+
+Ви можете використовувати ті самі оголошення типів з `str`, `float`, `bool` та багатьма іншими складними типами даних.
+
+Декілька з них будуть розглянуті в наступних розділах посібника.
+
+## Порядок має значення
+
+При створенні *операцій шляху* можуть виникати ситуації, коли шлях фіксований.
+
+Наприклад, `/users/me`. Припустимо, що це шлях для отримання даних про поточного користувача.
+
+А також у вас може бути шлях `/users/{user_id}`, щоб отримати дані про конкретного користувача за його ID.
+
+Оскільки *операції шляху* оцінюються по черзі, Ви повинні переконатися, що шлях для `/users/me` оголошений перед шляхом для `/users/{user_id}`:
+
+{* ../../docs_src/path_params/tutorial003.py hl[6,11] *}
+
+Інакше шлях для `/users/{user_id}` також буде відповідати для `/users/me`, "вважаючи", що він отримує параметр `user_id` зі значенням `"me"`.
+
+Аналогічно, Ви не можете оголосити операцію шляху:
+
+{* ../../docs_src/path_params/tutorial003b.py hl[6,11] *}
+
+Перша операція буде завжди використовуватися, оскільки шлях збігається першим.
+## Попередньо визначені значення
+
+Якщо у вас є *операція шляху*, яка приймає *параметр шляху*, але Ви хочете, щоб можливі допустимі значення *параметра шляху* були попередньо визначені, Ви можете використати стандартний Python Enum.
+
+### Створення класу `Enum`
+
+Імпортуйте `Enum` і створіть підклас, що наслідується від `str` та `Enum`.
+
+Наслідуючи від `str`, документація API зможе визначити, що значення повинні бути типу `string`, і правильно їх відобразить.
+
+Після цього створіть атрибути класу з фіксованими значеннями, які будуть доступними допустимими значеннями:
+
+{* ../../docs_src/path_params/tutorial005.py hl[1,6:9] *}
+
+/// info | Додаткова інформація
+
+Перелічення (або enums) доступні в Python починаючи з версії 3.4.
+
+///
+
+/// tip | Порада
+
+Якщо вам цікаво, "AlexNet", "ResNet" та "LeNet" — це просто назви ML моделей Machine Learning.
+
+///
+
+
+### Оголосіть *параметр шляху*
+
+Потім створіть *параметр шляху* з анотацією типу, використовуючи створений вами клас enum (`ModelName`):
+
+{* ../../docs_src/path_params/tutorial005.py hl[16] *}
+
+### Перевірка документації
+
+Оскільки доступні значення для *параметра шляху* визначені заздалегідь, інтерактивна документація зможе красиво їх відобразити:
+
+
+
+### Робота з *перелічуваннями* у Python
+
+Значення *параметра шляху* буде елементом *перелічування*.
+
+#### Порівняння *елементів перелічування*
+
+Ви можете порівнювати його з *елементами перелічування* у створеному вами enum `ModelName`:
+
+{* ../../docs_src/path_params/tutorial005.py hl[17] *}
+
+#### Отримання *значення перелічування*
+
+Ви можете отримати фактичне значення (у цьому випадку це `str`), використовуючи `model_name.value`, або загалом `your_enum_member.value`:
+
+{* ../../docs_src/path_params/tutorial005.py hl[20] *}
+
+/// tip | Порада
+
+Ви також можете отримати доступ до значення `"lenet"`, використовуючи `ModelName.lenet.value`.
+
+///
+
+
+#### Повернення *елементів перелічування*
+
+Ви можете повертати *елементи перелічування* з вашої *операції шляху*, навіть вкладені у JSON-тіло (наприклад, `dict`).
+
+Вони будуть перетворені на відповідні значення (у цьому випадку рядки) перед поверненням клієнту:
+
+{* ../../docs_src/path_params/tutorial005.py hl[18,21,23] *}
+
+На стороні клієнта Ви отримаєте відповідь у форматі JSON, наприклад:
+
+```JSON
+{
+ "model_name": "alexnet",
+ "message": "Deep Learning FTW!"
+}
+```
+
+## Path-параметри, що містять шляхи
+
+Припустимо, у вас є *операція шляху* з маршрутом `/files/{file_path}`.
+
+Але вам потрібно, щоб `file_path` містив *шлях*, наприклад `home/johndoe/myfile.txt`.
+
+Отже, URL для цього файлу виглядатиме так: `/files/home/johndoe/myfile.txt`.
+
+
+
+### Підтримка OpenAPI
+
+OpenAPI не підтримує спосіб оголошення *параметра шляху*, що містить *шлях* всередині, оскільки це може призвести до сценаріїв, які складно тестувати та визначати.
+
+Однак (одначе), Ви все одно можете зробити це в **FastAPI**, використовуючи один із внутрішніх інструментів Starlette.
+
+Документація все ще працюватиме, хоча й не додаватиме опису про те, що параметр повинен містити шлях.
+
+### Конвертер шляху
+
+Використовуючи опцію безпосередньо зі Starlette, Ви можете оголосити *параметр шляху*, що містить *шлях*, використовуючи URL на кшталт:
+
+```
+/files/{file_path:path}
+```
+У цьому випадку ім'я параметра — `file_path`, а остання частина `:path` вказує на те, що параметр повинен відповідати будь-якому *шляху*.
+
+Отже, Ви можете використати його так:
+
+{* ../../docs_src/path_params/tutorial004.py hl[6] *}
+
+/// tip | Порада
+
+Вам може знадобитися, щоб параметр містив `/home/johndoe/myfile.txt` із початковою косою рискою (`/`).
+
+У такому випадку URL виглядатиме так: `/files//home/johndoe/myfile.txt`, із подвійною косою рискою (`//`) між `files` і `home`.
+
+///
+
+## Підсумок
+
+З **FastAPI**, використовуючи короткі, інтуїтивно зрозумілі та стандартні оголошення типів Python, Ви отримуєте:
+
+* Підтримку в редакторі: перевірка помилок, автодоповнення тощо.
+* "Парсинг" даних
+* Валідацію даних
+* Анотацію API та автоматичну документацію
+
+І вам потрібно оголосити їх лише один раз.
+
+Це, ймовірно, основна видима перевага **FastAPI** порівняно з альтернативними фреймворками (окрім високої продуктивності).
diff --git a/docs/uk/docs/tutorial/query-param-models.md b/docs/uk/docs/tutorial/query-param-models.md
new file mode 100644
index 000000000..97eb82fa1
--- /dev/null
+++ b/docs/uk/docs/tutorial/query-param-models.md
@@ -0,0 +1,68 @@
+# Моделі Query параметрів
+
+Якщо у Вас є група **query параметрів**, які пов’язані між собою, Ви можете створити **Pydantic-модель** для їх оголошення.
+
+Це дозволить Вам **повторно використовувати модель** у **різних місцях**, а також оголошувати перевірки та метадані для всіх параметрів одночасно. 😎
+
+/// note | Примітка
+
+Ця можливість підтримується, починаючи з версії FastAPI `0.115.0`. 🤓
+
+///
+
+## Query параметри з Pydantic-моделлю
+
+Оголосіть **query параметри**, які Вам потрібні, у **Pydantic-моделі**, а потім оголосіть цей параметр як `Query`:
+
+{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *}
+
+**FastAPI** буде **витягувати** дані для **кожного поля** з **query параметрів** у запиті та передавати їх у визначену вами Pydantic-модель.
+
+## Перевірте документацію
+
+Ви можете побачити параметри запиту в UI документації за `/docs`:
+
+
+
+
+### Список параметрів запиту / кілька значень за замовчуванням
+
+Ви також можете визначити значення за замовчуванням для `list`, якщо жодне значення не було передане:
+
+{* ../../docs_src/query_params_str_validations/tutorial012_an_py39.py hl[9] *}
+
+Якщо Ви перейдете за посиланням:
+
+```
+http://localhost:8000/items/
+```
+
+то значення `q` за замовчуванням буде: `["foo", "bar"]`, і Ваша відповідь виглядатиме так:
+
+```JSON
+{
+ "q": [
+ "foo",
+ "bar"
+ ]
+}
+```
+
+#### Використання тільки `list`
+
+Ви також можете використовувати `list` без уточнення типу, замість `list[str]`:
+
+{* ../../docs_src/query_params_str_validations/tutorial013_an_py39.py hl[9] *}
+
+/// note | Технічні деталі
+
+Майте на увазі, що в цьому випадку FastAPI не перевірятиме вміст списку.
+
+Наприклад, `list[int]` перевірятиме (і документуватиме), що всі елементи списку є цілими числами. Але `list` без уточнення цього не робитиме.
+
+///
+
+## Додавання додаткових метаданих
+
+Ви можете додати більше інформації про параметр.
+
+Ця інформація буде включена у згенерований OpenAPI та використана в інтерфейсах документації та зовнішніх інструментах.
+
+/// note | Технічні деталі
+
+Майте на увазі, що різні інструменти можуть мати різний рівень підтримки OpenAPI.
+
+Деякі з них можуть ще не відображати всю додаткову інформацію, хоча в більшості випадків ця функція вже запланована для розробки.
+
+///
+
+Ви можете додати `title` :
+
+{* ../../docs_src/query_params_str_validations/tutorial007_an_py310.py hl[10] *}
+
+А також `description`:
+
+{* ../../docs_src/query_params_str_validations/tutorial008_an_py310.py hl[14] *}
+
+## Аліаси параметрів
+
+Уявіть, що Ви хочете, щоб параметр називався `item-query`.
+
+Наприклад:
+
+```
+http://127.0.0.1:8000/items/?item-query=foobaritems
+```
+
+Але `item-query` — це некоректна назва змінної в Python.
+
+Найближчий допустимий варіант — `item_query`.
+
+Проте Вам потрібно, щоб параметр залишався саме `item-query`...
+
+У такому випадку можна оголосити `alias`, і саме він буде використовуватися для отримання значення параметра:
+
+{* ../../docs_src/query_params_str_validations/tutorial009_an_py310.py hl[9] *}
+
+## Виведення параметрів як застарілих
+
+Припустимо, що Ви більше не хочете використовувати цей параметр.
+
+Вам потрібно залишити його на деякий час, оскільки ним користуються клієнти, але Ви хочете, щоб документація чітко показувала, що він є застарілим.
+
+Тоді Ви можете передати параметр `deprecated=True` до `Query`:
+
+{* ../../docs_src/query_params_str_validations/tutorial010_an_py310.py hl[19] *}
+
+Документація буде показувати це таким чином:
+
+
+
+## Виняток параметрів з OpenAPI
+
+Щоб виключити параметр запиту зі згенерованої схеми OpenAPI (і, таким чином, з автоматичних систем документації), встановіть параметр `include_in_schema` для `Query` в `False`:
+
+{* ../../docs_src/query_params_str_validations/tutorial014_an_py310.py hl[10] *}
+
+## Кастомна валідація
+
+Можуть бути випадки, коли Вам потрібно провести **кастомну валідацію**, яку не можна реалізувати за допомогою параметрів, показаних вище.
+
+У таких випадках ви можете використати **кастомну функцію валідації**, яка буде застосована після звичайної валідації (наприклад, після перевірки, що значення є типом `str`).
+
+Це можна досягти за допомогою Pydantic's `AfterValidator` в середині `Annotated`.
+
+/// tip | Підказка
+
+Pydantic також має `BeforeValidator` та інші. 🤓
+
+///
+
+Наприклад, цей кастомний валідатор перевіряє, чи починається ID елемента з `isbn-` для номера книги ISBN або з `imdb-` для ID URL фільму на IMDB:
+
+{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py hl[5,16:19,24] *}
+
+/// info | Інформація
+
+Це доступно з версії Pydantic 2 або вище. 😎
+
+///
+
+/// tip | Підказка
+
+Якщо Вам потрібно виконати будь-яку валідацію, яка вимагає взаємодії з будь-яким **зовнішнім компонентом**, таким як база даних чи інший API, ви повинні замість цього використовувати **FastAPI Dependencies**. Ви дізнаєтесь про них пізніше.
+
+Ці кастомні валідатори використовуються для речей, які можна перевірити лише з **тими даними**, що надані в запиті.
+
+///
+
+### Зрозумійте цей код
+
+Головний момент – це використання **`AfterValidator` з функцією всередині `Annotated`**. Можете пропустити цю частину, якщо хочете. 🤸
+
+---
+
+Але якщо Вам цікаво розібратися в цьому конкретному прикладі коду і Вам ще не набридло, ось кілька додаткових деталей.
+
+#### Рядок із `value.startswith()`
+
+Звернули увагу? Рядок із `value.startswith()` може приймати кортеж, і тоді він перевірятиме кожне значення в кортежі:
+
+{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py ln[16:19] hl[17] *}
+
+#### Випадковий елемент
+
+За допомогою `data.items()` ми отримуємо ітерабельний об'єкт із кортежами, що містять ключ і значення для кожного елемента словника.
+
+Ми перетворюємо цей ітерабельний об'єкт у звичайний `list` за допомогою `list(data.items())`.
+
+Потім, використовуючи `random.choice()`, ми можемо отримати випадкове значення зі списку, тобто отримуємо кортеж із `(id, name)`. Це може бути щось на зразок `("imdb-tt0371724", "The Hitchhiker's Guide to the Galaxy")`.
+
+Далі ми **присвоюємо ці два значення** кортежу змінним `id` і `name`.
+
+Тож, якщо користувач не вказав ID елемента, він все одно отримає випадкову рекомендацію.
+
+...і все це реалізовано в **одному рядку коду**. 🤯 Хіба не прекрасний Python? 🐍
+
+{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py ln[22:30] hl[29] *}
+
+## Підсумок
+
+Ви можете оголошувати додаткові валідації та метаінформацію для своїх параметрів.
+
+Загальні валідації та метаінформація:
+
+* `alias`
+* `title`
+* `description`
+* `deprecated`
+
+Валідації, специфічні для рядків:
+
+* `min_length`
+* `max_length`
+* `pattern`
+
+Кастомні валідації за допомогою `AfterValidator`.
+
+У цих прикладах Ви побачили, як оголошувати валідації для значень `str`.
+
+Дивіться наступні розділи, щоб дізнатися, як оголошувати валідації для інших типів, наприклад чисел.
diff --git a/docs/uk/docs/tutorial/query-params.md b/docs/uk/docs/tutorial/query-params.md
new file mode 100644
index 000000000..16bb42af3
--- /dev/null
+++ b/docs/uk/docs/tutorial/query-params.md
@@ -0,0 +1,192 @@
+# Query Параметри
+
+Коли Ви оголошуєте інші параметри функції, які не є частиною параметрів шляху, вони автоматично інтерпретуються як "query" параметри.
+
+{* ../../docs_src/query_params/tutorial001.py hl[9] *}
+
+Query параметри — це набір пар ключ-значення, що йдуть після символу `?` в URL, розділені символами `&`.
+
+Наприклад, в URL:
+
+```
+http://127.0.0.1:8000/items/?skip=0&limit=10
+```
+
+...query параметрами є:
+
+* `skip`: зі значенням `0`
+* `limit`: зі значенням `10`
+
+Оскільки вони є частиною URL, вони "за замовчуванням" є рядками.
+
+Але коли Ви оголошуєте їх із типами Python (у наведеному прикладі як `int`), вони перетворюються на цей тип і проходять перевірку відповідності.
+
+Увесь той самий процес, який застосовується до параметрів шляху, також застосовується до query параметрів:
+
+* Підтримка в редакторі (автодоповнення, перевірка помилок)
+* "Парсинг" даних
+* Валідація даних
+* Автоматична документація
+
+
+## Значення за замовчуванням
+
+Оскільки query параметри не є фіксованою частиною шляху, вони можуть бути необов’язковими та мати значення за замовчуванням.
+
+У наведеному вище прикладі вони мають значення за замовчуванням: `skip=0` і `limit=10`.
+
+Отже, результат переходу за URL:
+
+```
+http://127.0.0.1:8000/items/
+```
+буде таким самим, як і перехід за посиланням:
+
+```
+http://127.0.0.1:8000/items/?skip=0&limit=10
+```
+
+Але якщо Ви перейдете, наприклад, за посиланням:
+
+```
+http://127.0.0.1:8000/items/?skip=20
+```
+
+Значення параметрів у вашій функції будуть такими:
+
+* `skip=20`: оскільки Ви вказали його в URL
+* `limit=10`: оскільки це значення за замовчуванням
+
+## Необов'язкові параметри
+
+Аналогічно, Ви можете оголосити необов’язкові query параметри, встановивши для них значення за замовчуванням `None`:
+
+{* ../../docs_src/query_params/tutorial002_py310.py hl[7] *}
+
+У цьому випадку параметр функції `q` буде необов’язковим і за замовчуванням матиме значення `None`.
+
+/// check | Примітка
+
+Також зверніть увагу, що **FastAPI** достатньо розумний, щоб визначити, що параметр шляху `item_id` є параметром шляху, а `q` — ні, отже, це query параметр.
+
+///
+
+## Перетворення типу Query параметра
+
+Ви також можете оголошувати параметри типу `bool`, і вони будуть автоматично конвертовані:
+
+{* ../../docs_src/query_params/tutorial003_py310.py hl[7] *}
+
+У цьому випадку, якщо Ви звернетесь до:
+
+
+```
+http://127.0.0.1:8000/items/foo?short=1
+```
+
+або
+
+```
+http://127.0.0.1:8000/items/foo?short=True
+```
+
+або
+
+```
+http://127.0.0.1:8000/items/foo?short=true
+```
+
+або
+
+```
+http://127.0.0.1:8000/items/foo?short=on
+```
+
+або
+
+```
+http://127.0.0.1:8000/items/foo?short=yes
+```
+
+або будь-який інший варіант написання (великі літери, перша літера велика тощо), ваша функція побачить параметр `short` зі значенням `True` з типом даних `bool`. В іншому випадку – `False`.
+
+## Кілька path і query параметрів
+
+Ви можете одночасно оголошувати кілька path і query параметрів, і **FastAPI** автоматично визначить, який з них до чого належить.
+
+
+Не потрібно дотримуватись певного порядку їх оголошення.
+
+Вони визначаються за назвою:
+
+{* ../../docs_src/query_params/tutorial004_py310.py hl[6,8] *}
+
+## Обов’язкові Query параметри
+
+Якщо Ви оголошуєте значення за замовчуванням для параметрів, які не є path-параметрами (у цьому розділі ми бачили поки що лише path параметри), тоді вони стають необов’язковими.
+
+Якщо Ви не хочете вказувати конкретні значення, але хочете зробити параметр опціональним, задайте `None` як значення за замовчуванням.
+
+Але якщо Ви хочете зробити query параметр обов’язковим, просто не вказуйте для нього значення за замовчуванням:
+
+{* ../../docs_src/query_params/tutorial005.py hl[6:7] *}
+
+Тут `needy` – обов’язковий query параметр типу `str`.
+
+Якщо Ви відкриєте у браузері URL-адресу:
+
+```
+http://127.0.0.1:8000/items/foo-item
+```
+
+...без додавання обов’язкового параметра `needy`, Ви побачите помилку:
+
+```JSON
+{
+ "detail": [
+ {
+ "type": "missing",
+ "loc": [
+ "query",
+ "needy"
+ ],
+ "msg": "Field required",
+ "input": null,
+ "url": "https://errors.pydantic.dev/2.1/v/missing"
+ }
+ ]
+}
+```
+
+Оскільки `needy` є обов’язковим параметром, вам потрібно вказати його в URL:
+
+```
+http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
+```
+
+...цей запит поверне:
+
+```JSON
+{
+ "item_id": "foo-item",
+ "needy": "sooooneedy"
+}
+```
+
+
+Звичайно, Ви можете визначити деякі параметри як обов’язкові, інші зі значенням за замовчуванням, а ще деякі — повністю опціональні:
+
+{* ../../docs_src/query_params/tutorial006_py310.py hl[8] *}
+
+У цьому випадку є 3 query параметри:
+
+* `needy`, обов’язковий `str`.
+* `skip`, `int` зі значенням за замовчуванням `0`.
+* `limit`, опціональний `int`.
+
+
+/// tip | Підказка
+
+Ви також можете використовувати `Enum`-и, так само як і з [Path Parameters](path-params.md#predefined-values){.internal-link target=_blank}.
+
+///
diff --git a/docs/uk/docs/tutorial/request-files.md b/docs/uk/docs/tutorial/request-files.md
new file mode 100644
index 000000000..18b7cc01c
--- /dev/null
+++ b/docs/uk/docs/tutorial/request-files.md
@@ -0,0 +1,175 @@
+# Запит файлів
+
+Ви можете визначити файли, які будуть завантажуватися клієнтом, використовуючи `File`.
+
+/// info | Інформація
+
+Щоб отримувати завантажені файли, спочатку встановіть python-multipart.
+
+Переконайтеся, що Ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його та встановили пакет, наприклад:
+
+```console
+$ pip install python-multipart
+```
+
+Це необхідно, оскільки завантажені файли передаються у вигляді "форматованих даних форми".
+
+///
+
+## Імпорт `File`
+
+Імпортуйте `File` та `UploadFile` з `fastapi`:
+
+{* ../../docs_src/request_files/tutorial001_an_py39.py hl[3] *}
+
+## Визначення параметрів `File`
+
+Створіть параметри файлів так само як Ви б створювали `Body` або `Form`:
+
+{* ../../docs_src/request_files/tutorial001_an_py39.py hl[9] *}
+
+/// info | Інформація
+
+`File` — це клас, який безпосередньо успадковує `Form`.
+
+Але пам’ятайте, що коли Ви імпортуєте `Query`, `Path`, `File` та інші з `fastapi`, це насправді функції, які повертають спеціальні класи.
+
+///
+
+/// tip | Підказка
+
+Щоб оголосити тіла файлів, Вам потрібно використовувати `File`, тому що інакше параметри будуть інтерпретовані як параметри запиту або параметри тіла (JSON).
+
+///
+
+Файли будуть завантажені у вигляді "форматованих даних форми".
+
+Якщо Ви оголосите тип параметра функції обробника маршруту як `bytes`, **FastAPI** прочитає файл за Вас, і Ви отримаєте його вміст у вигляді `bytes`.
+
+Однак майте на увазі, що весь вміст буде збережено в пам'яті. Це працюватиме добре для малих файлів.
+
+Але в деяких випадках Вам може знадобитися `UploadFile`.
+
+## Параметри файлу з `UploadFile`
+
+Визначте параметр файлу з типом `UploadFile`:
+
+{* ../../docs_src/request_files/tutorial001_an_py39.py hl[14] *}
+
+Використання `UploadFile` має кілька переваг перед `bytes`:
+
+* Вам не потрібно використовувати `File()` у значенні за замовчуванням параметра.
+* Використовується "буферизований" файл:
+ * Файл зберігається в пам'яті до досягнення певного обмеження, після чого він записується на диск.
+* Це означає, що він добре працює для великих файлів, таких як зображення, відео, великі двійкові файли тощо, не споживаючи всю пам'ять.
+Ви можете отримати метадані про завантажений файл.
+* Він має file-like `асинхронний файловий інтерфейс` interface.
+* Він надає фактичний об'єкт Python `SpooledTemporaryFile`, який можна передавати безпосередньо іншим бібліотекам.
+
+### `UploadFile`
+
+`UploadFile` має такі атрибути:
+
+* `filename`: Рядок `str` з оригінальною назвою файлу, який був завантажений (наприклад, `myimage.jpg`).
+* `content_type`: Рядок `str` з MIME-типом (наприклад, `image/jpeg`).
+* `file`: Об'єкт SpooledTemporaryFile (файлоподібний об'єкт). Це фактичний файловий об'єкт Python, який можна безпосередньо передавати іншим функціям або бібліотекам, що очікують "файлоподібний" об'єкт.
+
+`UploadFile` має такі асинхронні `async` методи. Вони викликають відповідні методи файлу під капотом (використовуючи внутрішній `SpooledTemporaryFile`).
+
+* `write(data)`: Записує `data` (`str` або `bytes`) у файл.
+* `read(size)`: Читає `size` (`int`) байтів/символів з файлу.
+* `seek(offset)`: Переміщується до позиції `offset` (`int`) у файлі.
+ * Наприклад, `await myfile.seek(0)` поверне курсор на початок файлу.
+ * This is especially useful if you run `await myfile.read()` once and then need to read the contents again. Це особливо корисно, якщо Ви виконуєте await `await myfile.read()` один раз, а потім потрібно знову прочитати вміст.
+* `close()`: Закриває файл.
+
+Оскільки всі ці методи є асинхронними `async`, Вам потрібно використовувати "await":
+
+Наприклад, всередині `async` *функції обробки шляху* Ви можете отримати вміст за допомогою:
+
+```Python
+contents = await myfile.read()
+```
+Якщо Ви знаходитесь у звичайній `def` *функції обробки шляху*, Ви можете отримати доступ до `UploadFile.file` безпосередньо, наприклад:
+
+```Python
+contents = myfile.file.read()
+```
+
+/// note | Технічні деталі `async`
+
+Коли Ви використовуєте `async` методи, **FastAPI** виконує файлові операції у пулі потоків та очікує їх завершення.
+
+///
+
+/// note | Технічні деталі Starlette
+
+`UploadFile` у **FastAPI** успадковується безпосередньо від `UploadFile` у **Starlette**, але додає деякі необхідні частини, щоб зробити його сумісним із **Pydantic** та іншими компонентами FastAPI.
+
+///
+
+## Що таке "Form Data"
+
+Спосіб, у який HTML-форми (``) надсилають дані на сервер, зазвичай використовує "спеціальне" кодування, відмінне від JSON.
+
+**FastAPI** забезпечує правильне зчитування цих даних з відповідної частини запиту, а не з JSON.
+
+/// note | Технічні деталі
+
+Дані з форм зазвичай кодуються за допомогою "media type" `application/x-www-form-urlencoded`, якщо вони не містять файлів.
+
+Але якщо форма містить файли, вона кодується у форматі `multipart/form-data`. Якщо Ви використовуєте `File`, **FastAPI** визначить, що потрібно отримати файли з відповідної частини тіла запиту.
+
+Щоб дізнатися більше про ці типи кодування та формові поля, ознайомтеся з документацією MDN щодо POST.
+
+///
+
+/// warning | Увага
+
+Ви можете оголосити кілька параметрів `File` і `Form` в *операції шляху*, але Ви не можете одночасно оголошувати поля `Body`, які мають надходити у форматі JSON, оскільки тіло запиту буде закодоване у форматі `multipart/form-data`, а не `application/json`.
+
+Це не обмеження **FastAPI**, а особливість протоколу HTTP.
+
+///
+
+## Опціональне Завантаження Файлів
+
+Файл можна зробити необов’язковим, використовуючи стандартні анотації типів і встановлюючи значення за замовчуванням `None`:
+
+{* ../../docs_src/request_files/tutorial001_02_an_py310.py hl[9,17] *}
+
+## `UploadFile` із Додатковими Мета Даними
+
+Ви також можете використовувати `File()` разом із `UploadFile`, наприклад, для встановлення додаткових метаданих:
+
+{* ../../docs_src/request_files/tutorial001_03_an_py39.py hl[9,15] *}
+
+## Завантаження Кількох Файлів
+
+Можна завантажувати кілька файлів одночасно.
+
+Вони будуть пов’язані з одним і тим самим "form field", який передається у вигляді "form data".
+
+Щоб це реалізувати, потрібно оголосити список `bytes` або `UploadFile`:
+
+{* ../../docs_src/request_files/tutorial002_an_py39.py hl[10,15] *}
+
+Ви отримаєте, як і було оголошено, `list` із `bytes` або `UploadFile`.
+
+/// note | Технічні деталі
+
+Ви також можете використати `from starlette.responses import HTMLResponse`.
+
+**FastAPI** надає ті ж самі `starlette.responses`, що й `fastapi.responses`, для зручності розробників. Однак більшість доступних відповідей надходять безпосередньо від Starlette.
+
+///
+
+### Завантаження декількох файлів із додатковими метаданими
+
+Так само як і раніше, Ви можете використовувати `File()`, щоб встановити додаткові параметри навіть для `UploadFile`:
+
+{* ../../docs_src/request_files/tutorial003_an_py39.py hl[11,18:20] *}
+
+## Підсумок
+
+Використовуйте `File`, `bytes`та `UploadFile`, щоб оголошувати файли для завантаження у запитах, які надсилаються у вигляді form data.
diff --git a/docs/uk/docs/tutorial/request-form-models.md b/docs/uk/docs/tutorial/request-form-models.md
new file mode 100644
index 000000000..7f5759e79
--- /dev/null
+++ b/docs/uk/docs/tutorial/request-form-models.md
@@ -0,0 +1,78 @@
+# Моделі форм (Form Models)
+
+У FastAPI Ви можете використовувати **Pydantic-моделі** для оголошення **полів форми**.
+
+/// info | Інформація
+
+Щоб використовувати форми, спочатку встановіть python-multipart.
+
+Переконайтеся, що Ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, а потім встановили бібліотеку, наприклад:
+
+```console
+$ pip install python-multipart
+```
+
+///
+
+/// note | Підказка
+
+Ця функція підтримується, починаючи з FastAPI версії `0.113.0`. 🤓
+
+///
+
+## Використання Pydantic-моделей для форм
+
+Вам просто потрібно оголосити **Pydantic-модель** з полями, які Ви хочете отримати як **поля форми**, а потім оголосити параметр як `Form`:
+
+{* ../../docs_src/request_form_models/tutorial001_an_py39.py hl[9:11,15] *}
+
+**FastAPI** **витягне** дані для **кожного поля** з **формових даних** у запиті та надасть вам Pydantic-модель, яку Ви визначили.
+
+## Перевірка документації
+
+Ви можете перевірити це в UI документації за `/docs`:
+
+
+POST.
+
+///
+
+/// warning | Попередження
+
+Ви можете оголосити кілька параметрів `Form` в *операції шляху*, але не можете одночасно оголосити поля `Body`, які Ви очікуєте отримати у форматі JSON, оскільки тіло запиту буде закодовано у форматі `application/x-www-form-urlencoded`, а не `application/json`.
+
+Це не обмеження **FastAPI**, а частина HTTP-протоколу.
+
+///
+
+## Підсумок
+
+Використовуйте `Form` для оголошення вхідних параметрів у вигляді даних форми.
diff --git a/docs/uk/docs/tutorial/response-status-code.md b/docs/uk/docs/tutorial/response-status-code.md
new file mode 100644
index 000000000..1ed69d6f2
--- /dev/null
+++ b/docs/uk/docs/tutorial/response-status-code.md
@@ -0,0 +1,100 @@
+# Статус коди Відповідей
+
+Так само як Ви можете вказати модель відповіді, Ви також можете оголосити HTTP код статусу для відповіді за допомогою параметра `status_code` в будь-якій з *операцій шляху*:
+
+* `@app.get()`
+* `@app.post()`
+* `@app.put()`
+* `@app.delete()`
+* тощо.
+
+{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
+
+/// note | Нотатка
+
+Зверніть увагу, що `status_code` є параметром методу "декоратора" (`get`, `post` і т.д.), а не Вашої *функції операції шляху*, як усі інші параметри та тіло запиту.
+
+///
+
+Параметр `status_code` приймає число, яке відповідає HTTP коду статусу.
+
+/// info | Інформація
+`status_code` також може отримувати значення з `IntEnum`, наприклад, з Python `http.HTTPStatus`.
+
+///
+
+Він буде:
+
+* Повертати вказаний код статусу у відповіді.
+* Документувати його як такий у схемі OpenAPI (і, таким чином, в інтерфейсі користувача):
+
+
+
+/// note | Нотатка
+
+Деякі коди відповіді (див. наступний розділ) вказують, що відповідь не має тіла.
+
+FastAPI знає про це і створить OpenAPI документацію, яка вказує, що тіла відповіді немає.
+
+///
+
+## Про HTTP статус коди
+
+/// note | Нотатка
+
+Якщо Ви вже знаєте, що таке HTTP коди статусу, переходьте до наступного розділу.
+
+///
+
+В HTTP Ви надсилаєте числовий код статусу з 3 цифр як частину відповіді.
+
+Ці коди статусу мають пов’язану назву для їх розпізнавання, але найважливішою частиною є саме число.
+
+Коротко:
+
+* **`100 - 199`** "Інформаційні" відповіді. Ви рідко використовуєте їх напряму. Відповіді з такими кодами не можуть мати тіла.
+* **`200 - 299`** "Успішні" відповіді. Це ті, які Ви використовуватимете найчастіше.
+ * `200` - код за замовчуванням, який означає, що все пройшло "OK".
+ * Інший приклад – `201`, "Created" (створено). Його зазвичай використовують після створення нового запису в базі даних.
+ * Особливий випадок – `204`, "No Content" (немає вмісту). Ця відповідь використовується, коли немає даних для повернення клієнту, тому відповідь не повинна мати тіла.
+* **`300 - 399`** "Перенаправлення". Відповіді з цими кодами можуть мати або не мати тіла, за винятком `304`, "Not Modified" (не змінено), яка не повинна мати тіла.
+* **`400 - 499`** "Помилка клієнта". Це другий тип, який Ви, ймовірно, будете використовувати найчастіше.
+ * Приклад `404`, "Not Found" (не знайдено).
+ * Для загальних помилок клієнта можна використовувати `400`.
+* `500 - 599` "Помилки сервера". Ви майже ніколи не використовуєте їх напряму. Якщо в коді Вашого застосунку або на сервері щось пішло не так, автоматично буде повернено один із цих кодів статусу.
+
+/// tip | Порада
+
+Щоб дізнатися більше про кожен код статусу і призначення кожного з них, перегляньте документацію MDN про HTTP коди статусу.
+
+///
+
+## Легкий спосіб запам'ятати назви
+
+Розглянемо ще раз попередній приклад:
+
+{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
+
+`201` - це код статусу для "Created" (створено).
+
+Але Вам не потрібно запам'ятовувати, що означає кожен із цих кодів.
+
+Ви можете використовувати зручні змінні з `fastapi.status`
+
+{* ../../docs_src/response_status_code/tutorial002.py hl[1,6] *}
+
+Ці змінні просто для зручності. Вони містять ті ж самі числа, але Ви можете скористатися автозаповненням в редакторі:
+
+
+
+/// note | Технічні деталі
+
+Ви також можете використати `from starlette import status`.
+
+**FastAPI** надає ті ж самі змінні `starlette.status` як `fastapi.status`, просто для зручності розробника. Однак вони походять безпосередньо зі Starlette.
+
+///
+
+## Зміна значення за замовчуванням
+
+Далі, у Посібнику для досвідчених користувачів{.internal-link target=_blank}, Ви дізнаєтесь, як повернути інший код статусу, ніж той, який Ви оголосили тут.
diff --git a/docs/uk/docs/tutorial/schema-extra-example.md b/docs/uk/docs/tutorial/schema-extra-example.md
new file mode 100644
index 000000000..853fd5e65
--- /dev/null
+++ b/docs/uk/docs/tutorial/schema-extra-example.md
@@ -0,0 +1,222 @@
+# Декларування прикладів вхідних даних
+
+Ви можете задати приклади даних, які Ваш застосунок може отримувати.
+
+Ось кілька способів, як це зробити.
+
+## Додаткові дані JSON-схеми в моделях Pydantic
+
+Ви можете задати `examples` для моделі Pydantic, які буде додано до згенерованої JSON-схеми.
+
+//// tab | Pydantic v2
+
+{* ../../docs_src/schema_extra_example/tutorial001_py310.py hl[13:24] *}
+
+////
+
+//// tab | Pydantic v1
+
+{* ../../docs_src/schema_extra_example/tutorial001_pv1_py310.py hl[13:23] *}
+
+////
+
+Ця додаткова інформація буде додана як є до **JSON-схеми**, і вона буде використовуватися в документації до API.
+
+//// tab | Pydantic v2
+
+У версії Pydantic 2 використовується атрибут `model_config`, який приймає `dict`, як описано в документації Pydantic: Конфігурація.
+
+Ви можете встановити `"json_schema_extra"` як `dict`, що містить будь-які додаткові дані, які Ви хочете відобразити у згенерованій JSON-схемі, включаючи `examples`.
+
+////
+
+//// tab | Pydantic v1
+
+У версії Pydantic 1 використовується внутрішній клас `Config` і параметр `schema_extra`, як описано в документації Pydantic: Налаштування схеми.
+
+Ви можете задати `schema_extra` як `dict`, що містить будь-які додаткові дані, які Ви хочете бачити у згенерованій JSON-схемі, включаючи `examples`.
+
+////
+
+/// tip | Підказка
+
+Ви можете використати ту ж техніку, щоб розширити JSON-схему і додати власну додаткову інформацію.
+
+Наприклад, Ви можете використати її для додавання метаданих для інтерфейсу користувача на фронтенді тощо.
+
+///
+
+/// info | Інформація
+
+OpenAPI 3.1.0 (який використовується починаючи з FastAPI 0.99.0) додав підтримку `examples`, що є частиною стандарту **JSON-схеми**.
+
+До цього підтримувався лише ключ `example` з одним прикладом. Він все ще підтримується в OpenAPI 3.1.0, але є застарілим і не входить до стандарту JSON Schema. Тому рекомендується перейти з `example` на `examples`. 🤓
+
+Більше про це можна прочитати в кінці цієї сторінки.
+
+///
+
+## Додаткові аргументи `Field`
+
+Коли ви використовуєте `Field()` у моделях Pydantic, Ви також можете вказати додаткові `examples`:
+
+{* ../../docs_src/schema_extra_example/tutorial002_py310.py hl[2,8:11] *}
+
+## `examples` у JSON-схемі — OpenAPI
+
+При використанні будь-кого з наступного:
+
+* `Path()`
+* `Query()`
+* `Header()`
+* `Cookie()`
+* `Body()`
+* `Form()`
+* `File()`
+
+Ви також можете задати набір `examples` з додатковою інформацією, яка буде додана до їхніх **JSON-схем** у **OpenAPI**.
+
+### `Body` з `examples`
+
+Тут ми передаємо `examples`, які містять один приклад очікуваних даних у `Body()`:
+
+{* ../../docs_src/schema_extra_example/tutorial003_an_py310.py hl[22:29] *}
+
+### Приклад у UI документації
+
+За допомогою будь-якого з наведених вище методів це виглядатиме так у документації за `/docs`:
+
+
+
+### `Body` з кількома `examples`
+
+Звичайно, Ви також можете передати кілька `examples`:
+
+{* ../../docs_src/schema_extra_example/tutorial004_an_py310.py hl[23:38] *}
+
+Коли Ви це робите, приклади будуть частиною внутрішньої **JSON-схеми** для цих даних.
+
+Втім, на момент написання цього (26 серпня 2023), Swagger UI — інструмент, який відповідає за відображення UI документації — не підтримує показ кількох прикладів у **JSON-схеми**. Але нижче можна прочитати про обхідний шлях.
+
+### Специфічні для OpenAPI `examples`
+
+Ще до того, як **JSON-схема** почала підтримувати `examples`, OpenAPI вже мала підтримку поля з такою ж назвою — `examples`.
+
+Це **специфічне для OpenAPI** поле `examples` розміщується в іншій частині специфікації OpenAPI — у **деталях кожної *операції шляху***, а не всередині самої JSON-схеми.
+
+Swagger UI вже давно підтримує це поле `examples`. Тому Ви можете використовувати його, щоб **відображати** кілька **прикладів у документації**.
+
+Це поле `examples` у специфікації OpenAPI — це `dict` (словник) з **кількома прикладами** (а не список `list`), кожен із яких може містити додаткову інформацію, що буде додана до **OpenAPI**.
+
+Воно не включається до JSON Schema кожного параметра, а розміщується зовні, безпосередньо в *операції шляху*.
+
+### Використання параметра `openapi_examples`
+
+Ви можете оголосити специфічні для OpenAPI `examples` у FastAPI за допомогою параметра `openapi_examples` для:
+
+* `Path()`
+* `Query()`
+* `Header()`
+* `Cookie()`
+* `Body()`
+* `Form()`
+* `File()`
+
+Ключі словника (`dict`) ідентифікують кожен приклад, а кожне значення `dict` — кожен специфічний словник `dict` в `examples` може містити:
+
+* `summary`: короткий опис прикладу.
+* `description`: розгорнутий опис (може містити Markdown).
+* `value`: сам приклад, наприклад, словник (`dict`).
+* `externalValue`: альтернатива `value`, URL-адреса, що вказує на приклад. Проте ця опція може не підтримуватися більшістю інструментів, на відміну від `value`.
+
+Використання виглядає так:
+
+{* ../../docs_src/schema_extra_example/tutorial005_an_py310.py hl[23:49] *}
+
+### Приклади OpenAPI у UI документації
+
+З параметром `openapi_examples`, доданим до `Body()`, документація `/docs` виглядатиме так:
+
+
+
+## Технічні деталі
+
+/// tip | Підказка
+
+Якщо Ви вже використовуєте **FastAPI** версії **0.99.0 або вище**, Ви можете **пропустити** цей розділ.
+
+Він більш актуальний для старих версій, до появи OpenAPI 3.1.0.
+
+Можна вважати це коротким **історичним екскурсом** у OpenAPI та JSON Schema. 🤓
+
+///
+
+/// warning | Попередження
+
+Це дуже технічна інформація про стандарти **JSON Schema** і **OpenAPI**.
+
+Якщо вищезгадані ідеї вже працюють у Вас — можете не заглиблюватися в ці деталі.
+
+///
+
+До OpenAPI 3.1.0 специфікація використовувала стару та модифіковану версію **JSON Schema**.
+
+Оскільки JSON Schema раніше не підтримувала `examples`, OpenAPI додала власне поле `examples`.
+
+OpenAPI також додала `example` і `examples` до інших частин специфікації:
+
+* `Parameter Object` (в специфікації) використовується FastAPI для:
+ * `Path()`
+ * `Query()`
+ * `Header()`
+ * `Cookie()`
+* `Request Body Object`, в полі `content`, в `Media Type Object` (в специфікації) використовується FastAPI для:
+ * `Body()`
+ * `File()`
+ * `Form()`
+
+/// info | Інформація
+
+Цей старий параметр `examples`, специфічний для OpenAPI, тепер називається `openapi_examples`, починаючи з FastAPI версії `0.103.0`.
+
+///
+
+### Поле `examples` у JSON Schema
+
+Пізніше JSON Schema додала поле `examples` у нову версію специфікації.
+
+І вже OpenAPI 3.1.0 базується на цій новій версії (JSON Schema 2020-12), яка включає поле `examples`.
+
+Тепер це поле `examples` є пріоритетним і замінює старе (і кастомне) поле `example`, яке стало застарілим.
+
+Нове поле `examples` у JSON Schema — це **просто список (`list`)** прикладів, без додаткових метаданих (на відміну від OpenAPI).
+
+/// info | Інформація
+
+Навіть після того, як з'явився OpenAPI 3.1.0, який підтримував examples у JSON Schema, інструмент Swagger UI ще деякий час не підтримував цю версію (підтримка з’явилась з версії 5.0.0 🎉).
+
+Через це версії FastAPI до 0.99.0 все ще використовували версії OpenAPI нижчі за 3.1.0.
+
+///
+
+### `Examples` в Pydantic і FastAPI
+
+Коли Ви додаєте `examples` у модель Pydantic через `schema_extra` або `Field(examples=["something"])`, ці приклади додаються до **JSON Schema** цієї моделі.
+
+І ця **JSON Schema** Pydantic-моделі включається до **OpenAPI** Вашого API, а потім використовується в UI документації (docs UI).
+
+У версіях FastAPI до 0.99.0 (починаючи з 0.99.0 використовується новіший OpenAPI 3.1.0), коли Ви використовували `example` або `examples` з іншими утилітами (`Query()`, `Body()` тощо), ці приклади не додавалися до JSON Schema, який описує ці дані (навіть не до власної версії JSON Schema у OpenAPI). Натомість вони додавалися безпосередньо до опису *обробника шляху* *(path operation)* в OpenAPI (тобто поза межами частин, які використовують JSON Schema).
+
+Але тепер, коли FastAPI 0.99.0 і вище використовують OpenAPI 3.1.0, а той — JSON Schema 2020-12, разом із Swagger UI 5.0.0 і вище — все стало більш узгодженим, і examples тепер включаються до JSON Schema.
+
+### Swagger UI та специфічні для OpenAPI `examples`
+
+Раніше (станом на 26 серпня 2023 року) Swagger UI не підтримував кілька прикладів у JSON Schema, тому користувачі не мали можливості показати декілька прикладів у документації.
+
+Щоб вирішити це, FastAPI починаючи з версії 0.103.0 **додав підтримку** старого **OpenAPI-специфічного** поля `examples` через новий параметр `openapi_examples`. 🤓
+
+### Підсумок
+
+Раніше я казав, що не люблю історію... а тепер ось я — розповідаю "технічні історичні" лекції. 😅
+
+Коротко: **оновіться до FastAPI 0.99.0 або вище** — і все стане значно **простішим, узгодженим та інтуїтивно зрозумілим**, і Вам не доведеться знати всі ці історичні деталі. 😎
diff --git a/docs/uk/docs/tutorial/static-files.md b/docs/uk/docs/tutorial/static-files.md
new file mode 100644
index 000000000..a84782d8f
--- /dev/null
+++ b/docs/uk/docs/tutorial/static-files.md
@@ -0,0 +1,40 @@
+# Статичні файли
+
+Ви можете автоматично надавати статичні файли з каталогу, використовуючи `StaticFiles`.
+
+## Використання `StaticFiles`
+
+* Імпортуйте `StaticFiles`.
+* "Під'єднати" екземпляр `StaticFiles()` з вказанням необхідного шляху.
+
+{* ../../docs_src/static_files/tutorial001.py hl[2,6] *}
+
+/// note | Технічні деталі
+
+Ви також можете використовувати `from starlette.staticfiles import StaticFiles`.
+
+**FastAPI** надає той самий `starlette.staticfiles`, що й `fastapi.staticfiles` для зручності розробників. Але фактично він безпосередньо походить із Starlette.
+
+///
+
+### Що таке "Під'єднання"
+
+"Під'єднання" означає додавання повноцінного "незалежного" застосунку за певним шляхом, який потім обробляє всі під шляхи.
+
+Це відрізняється від використання `APIRouter`, оскільки під'єднаний застосунок є повністю незалежним. OpenAPI та документація вашого основного застосунку не будуть знати нічого про ваш під'єднаний застосунок.
+
+Ви можете дізнатися більше про це в [Посібнику для просунутих користувачів](../advanced/index.md){.internal-link target=_blank}.
+
+## Деталі
+
+Перше `"/static"` вказує на під шлях, за яким буде "під'єднано" цей новий "застосунок". Тому будь-який шлях, який починається з `"/static"`, буде оброблятися ним.
+
+`directory="static"` визначає каталог, що містить ваші статичні файли.
+
+`name="static"` це ім'я, яке можна використовувати всередині **FastAPI**.
+
+Усі ці параметри можуть бути змінені відповідно до потреб і особливостей вашого застосунку.
+
+## Додаткова інформація
+
+Детальніше про налаштування та можливості можна дізнатися в документації Starlette про статичні файли.
diff --git a/docs/uk/docs/tutorial/testing.md b/docs/uk/docs/tutorial/testing.md
new file mode 100644
index 000000000..25fc370d6
--- /dev/null
+++ b/docs/uk/docs/tutorial/testing.md
@@ -0,0 +1,240 @@
+# Тестування
+
+Тестування **FastAPI** додатків є простим та ефективним завдяки бібліотеці Starlette, яка базується на HTTPX.
+Оскільки HTTPX розроблений на основі Requests, його API є інтуїтивно зрозумілим для тих, хто вже знайомий з Requests.
+
+З його допомогою Ви можете використовувати pytest безпосередньо з **FastAPI**.
+
+## Використання `TestClient`
+
+/// info | Інформація
+
+Щоб використовувати `TestClient`, спочатку встановіть `httpx`.
+
+Переконайтеся, що Ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, а потім встановили саму бібліотеку, наприклад:
+
+```console
+$ pip install httpx
+```
+
+///
+
+Імпортуйте `TestClient`.
+
+Створіть `TestClient`, передавши йому Ваш застосунок **FastAPI**.
+
+Створюйте функції з іменами, що починаються з `test_` (це стандартна угода для `pytest`).
+
+Використовуйте об'єкт `TestClient` так само як і `httpx`.
+
+Записуйте прості `assert`-вирази зі стандартними виразами Python, які потрібно перевірити (це також стандарт для `pytest`).
+
+{* ../../docs_src/app_testing/tutorial001.py hl[2,12,15:18] *}
+
+
+/// tip | Порада
+
+Зверніть увагу, що тестові функції — це звичайні `def`, а не `async def`.
+
+Виклики клієнта також звичайні, без використання `await`.
+
+Це дозволяє використовувати `pytest` без зайвих ускладнень.
+
+///
+
+/// note | Технічні деталі
+
+Ви також можете використовувати `from starlette.testclient import TestClient`.
+
+**FastAPI** надає той самий `starlette.testclient` під назвою `fastapi.testclient` для зручності розробників, але він безпосередньо походить із Starlette.
+
+///
+
+/// tip | Порада
+
+Якщо Вам потрібно викликати `async`-функції у ваших тестах, окрім відправлення запитів до FastAPI-застосунку (наприклад, асинхронні функції роботи з базою даних), перегляньте [Асинхронні тести](../advanced/async-tests.md){.internal-link target=_blank} у розширеному керівництві.
+
+///
+
+## Розділення тестів
+
+У реальному застосунку Ваші тести, ймовірно, будуть в окремому файлі.
+
+Також Ваш **FastAPI**-застосунок може складатися з кількох файлів або модулів тощо.
+
+### Файл застосунку **FastAPI**
+
+Припустимо, у Вас є структура файлів, описана в розділі [Більші застосунки](bigger-applications.md){.internal-link target=_blank}:
+
+```
+.
+├── app
+│ ├── __init__.py
+│ └── main.py
+```
+У файлі `main.py` знаходиться Ваш застосунок **FastAPI** :
+
+{* ../../docs_src/app_testing/main.py *}
+
+### Файл тестування
+
+Ви можете створити файл `test_main.py` з Вашими тестами. Він може знаходитися в тому ж пакеті Python (у тій самій директорії з файлом `__init__.py`):
+
+
+``` hl_lines="5"
+.
+├── app
+│ ├── __init__.py
+│ ├── main.py
+│ └── test_main.py
+```
+
+Оскільки цей файл знаходиться в тому ж пакеті, Ви можете використовувати відносний імпорт, щоб імпортувати об'єкт `app` із модуля `main` (`main.py`):
+
+{* ../../docs_src/app_testing/test_main.py hl[3] *}
+
+
+...і написати код для тестів так само як і раніше.
+
+## Тестування: розширений приклад
+
+Тепер розширимо цей приклад і додамо більше деталей, щоб побачити, як тестувати різні частини.
+
+### Розширений файл застосунку **FastAPI**
+
+Залишимо ту саму структуру файлів:
+
+```
+.
+├── app
+│ ├── __init__.py
+│ ├── main.py
+│ └── test_main.py
+```
+
+Припустимо, що тепер файл `main.py` із Вашим **FastAPI**-застосунком містить додаткові операції шляху (**path operations**).
+
+Він має `GET`-операцію, яка може повертати помилку.
+
+Він має `POST`-операцію, яка може повертати кілька помилок.
+
+Обидві операції шляху вимагають заголовок `X-Token`.
+
+//// tab | Python 3.10+
+
+```Python
+{!> ../../docs_src/app_testing/app_b_an_py310/main.py!}
+```
+
+////
+
+//// tab | Python 3.9+
+
+```Python
+{!> ../../docs_src/app_testing/app_b_an_py39/main.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python
+{!> ../../docs_src/app_testing/app_b_an/main.py!}
+```
+
+////
+
+//// tab | Python 3.10+ non-Annotated
+
+/// tip | Порада
+
+Бажано використовувати версію з `Annotated`, якщо це можливо
+
+///
+
+```Python
+{!> ../../docs_src/app_testing/app_b_py310/main.py!}
+```
+
+////
+
+//// tab | Python 3.8+ non-Annotated
+
+/// tip | Порада
+
+Бажано використовувати версію з `Annotated`, якщо це можливо
+
+///
+
+```Python
+{!> ../../docs_src/app_testing/app_b/main.py!}
+```
+
+////
+
+### Розширений тестовий файл
+
+Потім Ви можете оновити `test_main.py`, додавши розширені тести:
+
+{* ../../docs_src/app_testing/app_b/test_main.py *}
+
+Коли Вам потрібно передати клієнту інформацію в запиті, але Ви не знаєте, як це зробити, Ви можете пошукати (наприклад, у Google) спосіб реалізації в `httpx`, або навіть у `requests`, оскільки HTTPX розроблений на основі дизайну Requests.
+
+Далі Ви просто повторюєте ці ж дії у ваших тестах.
+
+Наприклад:
+
+* Щоб передати *path* або *query* параметр, додайте його безпосередньо до URL.
+* Щоб передати тіло JSON, передайте Python-об'єкт (наприклад, `dict`) у параметр `json`.
+* Якщо потрібно надіслати *Form Data* замість JSON, використовуйте параметр `data`.
+* Щоб передати заголовки *headers*, використовуйте `dict` у параметрі `headers`.
+* Для *cookies* використовуйте `dict` у параметрі `cookies`.
+
+Докладніше про передачу даних у бекенд (за допомогою `httpx` або `TestClient`) можна знайти в документації HTTPX.
+
+/// info | Інформація
+
+Зверніть увагу, що `TestClient` отримує дані, які можна конвертувати в JSON, а не Pydantic-моделі.
+Якщо у Вас є Pydantic-модель у тесті, і Ви хочете передати її дані в додаток під час тестування, Ви можете використати `jsonable_encoder`, описаний у розділі [JSON Compatible Encoder](encoder.md){.internal-link target=_blank}.
+
+///
+
+## Запуск тестів
+
+Після цього вам потрібно встановити `pytest`.
+
+Переконайтеся, що Ви створили [віртуальне середовище]{.internal-link target=_blank}, активували його і встановили необхідні пакети, наприклад:
+
+
-
+
@@ -93,7 +93,7 @@ Những tính năng như:
"_Thành thật, những gì bạn đã xây dựng nhìn siêu chắc chắn và bóng bẩy. Theo nhiều cách, nó là những gì tôi đã muốn Hug trở thành - thật sự truyền cảm hứng để thấy ai đó xây dựng nó._"
-
+
---
@@ -452,7 +452,7 @@ Independent TechEmpower benchmarks cho thấy các ứng dụng **FastAPI** ch
Sử dụng bởi Pydantic:
-*
email_validator - cho email validation.
+* email-validator - cho email validation.
Sử dụng Starlette:
diff --git a/docs/vi/docs/python-types.md b/docs/vi/docs/python-types.md
index 84d14de55..403e89930 100644
--- a/docs/vi/docs/python-types.md
+++ b/docs/vi/docs/python-types.md
@@ -12,16 +12,18 @@ Bằng việc khai báo kiểu dữ liệu cho các biến của bạn, các tr
Nhưng thậm chí nếu bạn không bao giờ sử dụng **FastAPI**, bạn sẽ được lợi từ việc học một ít về chúng.
-!!! note
- Nếu bạn là một chuyên gia về Python, và bạn đã biết mọi thứ về gợi ý kiểu dữ liệu, bỏ qua và đi tới chương tiếp theo.
+/// note
+
+Nếu bạn là một chuyên gia về Python, và bạn đã biết mọi thứ về gợi ý kiểu dữ liệu, bỏ qua và đi tới chương tiếp theo.
+
+///
## Động lực
Hãy bắt đầu với một ví dụ đơn giản:
-```Python
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py *}
+
Kết quả khi gọi chương trình này:
@@ -35,9 +37,8 @@ Hàm thực hiện như sau:
* Chuyển đổi kí tự đầu tiên của mỗi biến sang kiểu chữ hoa với `title()`.
* Nối chúng lại với nhau bằng một kí tự trắng ở giữa.
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py hl[2] *}
+
### Sửa đổi
@@ -79,9 +80,8 @@ Chính là nó.
Những thứ đó là "type hints":
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial002.py!}
-```
+{* ../../docs_src/python_types/tutorial002.py hl[1] *}
+
Đó không giống như khai báo những giá trị mặc định giống như:
@@ -109,9 +109,8 @@ Với cái đó, bạn có thể cuộn, nhìn thấy các lựa chọn, cho đ
Kiểm tra hàm này, nó đã có gợi ý kiểu dữ liệu:
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial003.py!}
-```
+{* ../../docs_src/python_types/tutorial003.py hl[1] *}
+
Bởi vì trình soạn thảo biết kiểu dữ liệu của các biến, bạn không chỉ có được completion, bạn cũng được kiểm tra lỗi:
@@ -119,9 +118,8 @@ Bởi vì trình soạn thảo biết kiểu dữ liệu của các biến, bạ
Bây giờ bạn biết rằng bạn phải sửa nó, chuyển `age` sang một xâu với `str(age)`:
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial004.py!}
-```
+{* ../../docs_src/python_types/tutorial004.py hl[2] *}
+
## Khai báo các kiểu dữ liệu
@@ -140,9 +138,8 @@ Bạn có thể sử dụng, ví dụ:
* `bool`
* `bytes`
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial005.py!}
-```
+{* ../../docs_src/python_types/tutorial005.py hl[1] *}
+
### Các kiểu dữ liệu tổng quát với tham số kiểu dữ liệu
@@ -170,45 +167,55 @@ Nếu bạn có thể sử dụng **phiên bản cuối cùng của Python**, s
Ví dụ, hãy định nghĩa một biến là `list` các `str`.
-=== "Python 3.9+"
+//// tab | Python 3.9+
- Khai báo biến với cùng dấu hai chấm (`:`).
+Khai báo biến với cùng dấu hai chấm (`:`).
- Tương tự kiểu dữ liệu `list`.
+Tương tự kiểu dữ liệu `list`.
- Như danh sách là một kiểu dữ liệu chứa một vài kiểu dữ liệu có sẵn, bạn đặt chúng trong các dấu ngoặc vuông:
+Như danh sách là một kiểu dữ liệu chứa một vài kiểu dữ liệu có sẵn, bạn đặt chúng trong các dấu ngoặc vuông:
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial006_py39.py!}
- ```
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial006_py39.py!}
+```
-=== "Python 3.8+"
+////
- Từ `typing`, import `List` (với chữ cái `L` viết hoa):
+//// tab | Python 3.8+
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial006.py!}
- ```
+Từ `typing`, import `List` (với chữ cái `L` viết hoa):
- Khai báo biến với cùng dấu hai chấm (`:`).
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial006.py!}
+```
- Tương tự như kiểu dữ liệu, `List` bạn import từ `typing`.
+Khai báo biến với cùng dấu hai chấm (`:`).
- Như danh sách là một kiểu dữ liệu chứa các kiểu dữ liệu có sẵn, bạn đặt chúng bên trong dấu ngoặc vuông:
+Tương tự như kiểu dữ liệu, `List` bạn import từ `typing`.
- ```Python hl_lines="4"
- {!> ../../../docs_src/python_types/tutorial006.py!}
- ```
+Như danh sách là một kiểu dữ liệu chứa các kiểu dữ liệu có sẵn, bạn đặt chúng bên trong dấu ngoặc vuông:
-!!! info
- Các kiểu dữ liệu có sẵn bên trong dấu ngoặc vuông được gọi là "tham số kiểu dữ liệu".
+```Python hl_lines="4"
+{!> ../../docs_src/python_types/tutorial006.py!}
+```
- Trong trường hợp này, `str` là tham số kiểu dữ liệu được truyền tới `List` (hoặc `list` trong Python 3.9 trở lên).
+////
+
+/// info
+
+Các kiểu dữ liệu có sẵn bên trong dấu ngoặc vuông được gọi là "tham số kiểu dữ liệu".
+
+Trong trường hợp này, `str` là tham số kiểu dữ liệu được truyền tới `List` (hoặc `list` trong Python 3.9 trở lên).
+
+///
Có nghĩa là: "biến `items` là một `list`, và mỗi phần tử trong danh sách này là một `str`".
-!!! tip
- Nếu bạn sử dụng Python 3.9 hoặc lớn hơn, bạn không phải import `List` từ `typing`, bạn có thể sử dụng `list` để thay thế.
+/// tip
+
+Nếu bạn sử dụng Python 3.9 hoặc lớn hơn, bạn không phải import `List` từ `typing`, bạn có thể sử dụng `list` để thay thế.
+
+///
Bằng cách này, trình soạn thảo của bạn có thể hỗ trợ trong khi xử lí các phần tử trong danh sách:
@@ -224,17 +231,21 @@ Và do vậy, trình soạn thảo biết nó là một `str`, và cung cấp s
Bạn sẽ làm điều tương tự để khai báo các `tuple` và các `set`:
-=== "Python 3.9+"
+//// tab | Python 3.9+
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial007_py39.py!}
- ```
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial007_py39.py!}
+```
-=== "Python 3.8+"
+////
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial007.py!}
- ```
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial007.py!}
+```
+
+////
Điều này có nghĩa là:
@@ -249,17 +260,21 @@ Tham số kiểu dữ liệu đầu tiên dành cho khóa của `dict`.
Tham số kiểu dữ liệu thứ hai dành cho giá trị của `dict`.
-=== "Python 3.9+"
+//// tab | Python 3.9+
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial008_py39.py!}
- ```
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008_py39.py!}
+```
-=== "Python 3.8+"
+////
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial008.py!}
- ```
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial008.py!}
+```
+
+////
Điều này có nghĩa là:
@@ -278,17 +293,21 @@ In Python 3.10 there's also a **new syntax** where you can put the possible type
Trong Python 3.10 cũng có một **cú pháp mới** mà bạn có thể đặt những kiểu giá trị khả thi phân cách bởi một dấu sổ dọc (`|`).
-=== "Python 3.10+"
+//// tab | Python 3.10+
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial008b_py310.py!}
- ```
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008b_py310.py!}
+```
-=== "Python 3.8+"
+////
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial008b.py!}
- ```
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial008b.py!}
+```
+
+////
Trong cả hai trường hợp có nghĩa là `item` có thể là một `int` hoặc `str`.
@@ -299,7 +318,7 @@ Bạn có thể khai báo một giá trị có thể có một kiểu dữ liệ
Trong Python 3.6 hoặc lớn hơn (bao gồm Python 3.10) bạn có thể khai báo nó bằng các import và sử dụng `Optional` từ mô đun `typing`.
```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial009.py!}
+{!../../docs_src/python_types/tutorial009.py!}
```
Sử dụng `Optional[str]` thay cho `str` sẽ cho phép trình soạn thảo giúp bạn phát hiện các lỗi mà bạn có thể gặp như một giá trị luôn là một `str`, trong khi thực tế nó rất có thể là `None`.
@@ -308,23 +327,29 @@ Sử dụng `Optional[str]` thay cho `str` sẽ cho phép trình soạn thảo g
Điều này cũng có nghĩa là trong Python 3.10, bạn có thể sử dụng `Something | None`:
-=== "Python 3.10+"
+//// tab | Python 3.10+
- ```Python hl_lines="1"
- {!> ../../../docs_src/python_types/tutorial009_py310.py!}
- ```
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial009_py310.py!}
+```
-=== "Python 3.8+"
+////
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial009.py!}
- ```
+//// tab | Python 3.8+
-=== "Python 3.8+ alternative"
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial009.py!}
+```
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial009b.py!}
- ```
+////
+
+//// tab | Python 3.8+ alternative
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial009b.py!}
+```
+
+////
#### Sử dụng `Union` hay `Optional`
@@ -343,9 +368,8 @@ Nó chỉ là về các từ và tên. Nhưng những từ đó có thể ảnh
Cho một ví dụ, hãy để ý hàm này:
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial009c.py!}
-```
+{* ../../docs_src/python_types/tutorial009c.py hl[1,4] *}
+
Tham số `name` được định nghĩa là `Optional[str]`, nhưng nó **không phải là tùy chọn**, bạn không thể gọi hàm mà không có tham số:
@@ -361,9 +385,8 @@ say_hi(name=None) # This works, None is valid 🎉
Tin tốt là, khi bạn sử dụng Python 3.10, bạn sẽ không phải lo lắng về điều đó, bạn sẽ có thể sử dụng `|` để định nghĩa hợp của các kiểu dữ liệu một cách đơn giản:
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial009c_py310.py!}
-```
+{* ../../docs_src/python_types/tutorial009c_py310.py hl[1,4] *}
+
Và sau đó, bạn sẽ không phải lo rằng những cái tên như `Optional` và `Union`. 😎
@@ -372,47 +395,53 @@ Và sau đó, bạn sẽ không phải lo rằng những cái tên như `Optiona
Những kiểu dữ liệu này lấy tham số kiểu dữ liệu trong dấu ngoặc vuông được gọi là **Kiểu dữ liệu tổng quát**, cho ví dụ:
-=== "Python 3.10+"
+//// tab | Python 3.10+
- Bạn có thể sử dụng các kiểu dữ liệu có sẵn như là kiểu dữ liệu tổng quát (với ngoặc vuông và kiểu dữ liệu bên trong):
+Bạn có thể sử dụng các kiểu dữ liệu có sẵn như là kiểu dữ liệu tổng quát (với ngoặc vuông và kiểu dữ liệu bên trong):
- * `list`
- * `tuple`
- * `set`
- * `dict`
+* `list`
+* `tuple`
+* `set`
+* `dict`
- Và tương tự với Python 3.6, từ mô đun `typing`:
+Và tương tự với Python 3.6, từ mô đun `typing`:
- * `Union`
- * `Optional` (tương tự như Python 3.6)
- * ...và các kiểu dữ liệu khác.
+* `Union`
+* `Optional` (tương tự như Python 3.6)
+* ...và các kiểu dữ liệu khác.
- Trong Python 3.10, thay vì sử dụng `Union` và `Optional`, bạn có thể sử dụng sổ dọc ('|') để khai báo hợp của các kiểu dữ liệu, điều đó tốt hơn và đơn giản hơn nhiều.
+Trong Python 3.10, thay vì sử dụng `Union` và `Optional`, bạn có thể sử dụng sổ dọc ('|') để khai báo hợp của các kiểu dữ liệu, điều đó tốt hơn và đơn giản hơn nhiều.
-=== "Python 3.9+"
+////
- Bạn có thể sử dụng các kiểu dữ liệu có sẵn tương tự như (với ngoặc vuông và kiểu dữ liệu bên trong):
+//// tab | Python 3.9+
- * `list`
- * `tuple`
- * `set`
- * `dict`
+Bạn có thể sử dụng các kiểu dữ liệu có sẵn tương tự như (với ngoặc vuông và kiểu dữ liệu bên trong):
- Và tương tự với Python 3.6, từ mô đun `typing`:
+* `list`
+* `tuple`
+* `set`
+* `dict`
- * `Union`
- * `Optional`
- * ...and others.
+Và tương tự với Python 3.6, từ mô đun `typing`:
-=== "Python 3.8+"
+* `Union`
+* `Optional`
+* ...and others.
- * `List`
- * `Tuple`
- * `Set`
- * `Dict`
- * `Union`
- * `Optional`
- * ...và các kiểu khác.
+////
+
+//// tab | Python 3.8+
+
+* `List`
+* `Tuple`
+* `Set`
+* `Dict`
+* `Union`
+* `Optional`
+* ...và các kiểu khác.
+
+////
### Lớp như kiểu dữ liệu
@@ -420,15 +449,13 @@ Bạn cũng có thể khai báo một lớp như là kiểu dữ liệu của m
Hãy nói rằng bạn muốn có một lớp `Person` với một tên:
-```Python hl_lines="1-3"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
+
Sau đó bạn có thể khai báo một biến có kiểu là `Person`:
-```Python hl_lines="6"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[6] *}
+
Và lại một lần nữa, bạn có được tất cả sự hỗ trợ từ trình soạn thảo:
@@ -452,56 +479,71 @@ Và bạn nhận được tất cả sự hỗ trợ của trình soạn thảo
Một ví dụ từ tài liệu chính thức của Pydantic:
-=== "Python 3.10+"
+//// tab | Python 3.10+
- ```Python
- {!> ../../../docs_src/python_types/tutorial011_py310.py!}
- ```
+```Python
+{!> ../../docs_src/python_types/tutorial011_py310.py!}
+```
-=== "Python 3.9+"
+////
- ```Python
- {!> ../../../docs_src/python_types/tutorial011_py39.py!}
- ```
+//// tab | Python 3.9+
-=== "Python 3.8+"
+```Python
+{!> ../../docs_src/python_types/tutorial011_py39.py!}
+```
- ```Python
- {!> ../../../docs_src/python_types/tutorial011.py!}
- ```
+////
-!!! info
- Để học nhiều hơn về Pydantic, tham khảo tài liệu của nó.
+//// tab | Python 3.8+
+
+```Python
+{!> ../../docs_src/python_types/tutorial011.py!}
+```
+
+////
+
+/// info
+
+Để học nhiều hơn về Pydantic, tham khảo tài liệu của nó.
+
+///
**FastAPI** được dựa hoàn toàn trên Pydantic.
Bạn sẽ thấy nhiều ví dụ thực tế hơn trong [Hướng dẫn sử dụng](tutorial/index.md){.internal-link target=_blank}.
-!!! tip
- Pydantic có một hành vi đặc biệt khi bạn sử dụng `Optional` hoặc `Union[Something, None]` mà không có giá trị mặc dịnh, bạn có thể đọc nhiều hơn về nó trong tài liệu của Pydantic về Required Optional fields.
+/// tip
+Pydantic có một hành vi đặc biệt khi bạn sử dụng `Optional` hoặc `Union[Something, None]` mà không có giá trị mặc dịnh, bạn có thể đọc nhiều hơn về nó trong tài liệu của Pydantic về Required Optional fields.
+
+///
## Type Hints với Metadata Annotations
Python cũng có một tính năng cho phép đặt **metadata bổ sung** trong những gợi ý kiểu dữ liệu này bằng cách sử dụng `Annotated`.
-=== "Python 3.9+"
+//// tab | Python 3.9+
- Trong Python 3.9, `Annotated` là một phần của thư viện chuẩn, do đó bạn có thể import nó từ `typing`.
+Trong Python 3.9, `Annotated` là một phần của thư viện chuẩn, do đó bạn có thể import nó từ `typing`.
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial013_py39.py!}
- ```
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial013_py39.py!}
+```
-=== "Python 3.8+"
+////
- Ở phiên bản dưới Python 3.9, bạn import `Annotated` từ `typing_extensions`.
+//// tab | Python 3.8+
- Nó đã được cài đặt sẵng cùng với **FastAPI**.
+Ở phiên bản dưới Python 3.9, bạn import `Annotated` từ `typing_extensions`.
- ```Python hl_lines="1 4"
- {!> ../../../docs_src/python_types/tutorial013.py!}
- ```
+Nó đã được cài đặt sẵng cùng với **FastAPI**.
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial013.py!}
+```
+
+////
Python bản thân nó không làm bất kì điều gì với `Annotated`. Với các trình soạn thảo và các công cụ khác, kiểu dữ liệu vẫn là `str`.
@@ -514,10 +556,13 @@ Bây giờ, bạn chỉ cần biết rằng `Annotated` tồn tại, và nó là
Sau đó, bạn sẽ thấy sự **mạnh mẽ** mà nó có thể làm.
-!!! tip
- Thực tế, cái này là **tiêu chuẩn của Python**, nghĩa là bạn vẫn sẽ có được **trải nghiệm phát triển tốt nhất có thể** với trình soạn thảo của bạn, với các công cụ bạn sử dụng để phân tích và tái cấu trúc code của bạn, etc. ✨
+/// tip
- Và code của bạn sẽ tương thích với nhiều công cụ và thư viện khác của Python. 🚀
+Thực tế, cái này là **tiêu chuẩn của Python**, nghĩa là bạn vẫn sẽ có được **trải nghiệm phát triển tốt nhất có thể** với trình soạn thảo của bạn, với các công cụ bạn sử dụng để phân tích và tái cấu trúc code của bạn, etc. ✨
+
+Và code của bạn sẽ tương thích với nhiều công cụ và thư viện khác của Python. 🚀
+
+///
## Các gợi ý kiểu dữ liệu trong **FastAPI**
@@ -541,5 +586,8 @@ Với **FastAPI**, bạn khai báo các tham số với gợi ý kiểu và bạ
Điều quan trọng là bằng việc sử dụng các kiểu dữ liệu chuẩn của Python (thay vì thêm các lớp, decorators,...), **FastAPI** sẽ thực hiện nhiều công việc cho bạn.
-!!! info
- Nếu bạn đã đi qua toàn bộ các hướng dẫn và quay trở lại để tìm hiểu nhiều hơn về các kiểu dữ liệu, một tài nguyên tốt như "cheat sheet" từ `mypy`.
+/// info
+
+Nếu bạn đã đi qua toàn bộ các hướng dẫn và quay trở lại để tìm hiểu nhiều hơn về các kiểu dữ liệu, một tài nguyên tốt như "cheat sheet" từ `mypy`.
+
+///
diff --git a/docs/vi/docs/tutorial/first-steps.md b/docs/vi/docs/tutorial/first-steps.md
index 712f00852..901c8fd59 100644
--- a/docs/vi/docs/tutorial/first-steps.md
+++ b/docs/vi/docs/tutorial/first-steps.md
@@ -2,9 +2,7 @@
Tệp tin FastAPI đơn giản nhất có thể trông như này:
-```Python
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py *}
Sao chép sang một tệp tin `main.py`.
@@ -24,12 +22,15 @@ $ uvicorn main:app --reload
-!!! note
- Câu lệnh `uvicorn main:app` được giải thích như sau:
+/// note
- * `main`: tệp tin `main.py` (một Python "mô đun").
- * `app`: một object được tạo ra bên trong `main.py` với dòng `app = FastAPI()`.
- * `--reload`: làm server khởi động lại sau mỗi lần thay đổi. Chỉ sử dụng trong môi trường phát triển.
+Câu lệnh `uvicorn main:app` được giải thích như sau:
+
+* `main`: tệp tin `main.py` (một Python "mô đun").
+* `app`: một object được tạo ra bên trong `main.py` với dòng `app = FastAPI()`.
+* `--reload`: làm server khởi động lại sau mỗi lần thay đổi. Chỉ sử dụng trong môi trường phát triển.
+
+///
Trong output, có một dòng giống như:
@@ -130,22 +131,21 @@ Bạn cũng có thể sử dụng nó để sinh code tự động, với các c
### Bước 1: import `FastAPI`
-```Python hl_lines="1"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[1] *}
`FastAPI` là một Python class cung cấp tất cả chức năng cho API của bạn.
-!!! note "Chi tiết kĩ thuật"
- `FastAPI` là một class kế thừa trực tiếp `Starlette`.
+/// note | Chi tiết kĩ thuật
- Bạn cũng có thể sử dụng tất cả Starlette chức năng với `FastAPI`.
+`FastAPI` là một class kế thừa trực tiếp `Starlette`.
+
+Bạn cũng có thể sử dụng tất cả Starlette chức năng với `FastAPI`.
+
+///
### Bước 2: Tạo một `FastAPI` "instance"
-```Python hl_lines="3"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[3] *}
Biến `app` này là một "instance" của class `FastAPI`.
@@ -165,9 +165,7 @@ $ uvicorn main:app --reload
Nếu bạn tạo ứng dụng của bạn giống như:
-```Python hl_lines="3"
-{!../../../docs_src/first_steps/tutorial002.py!}
-```
+{* ../../docs_src/first_steps/tutorial002.py hl[3] *}
Và đặt nó trong một tệp tin `main.py`, sau đó bạn sẽ gọi `uvicorn` giống như:
@@ -199,8 +197,11 @@ https://example.com/items/foo
/items/foo
```
-!!! info
- Một đường dẫn cũng là một cách gọi chung cho một "endpoint" hoặc một "route".
+/// info
+
+Một đường dẫn cũng là một cách gọi chung cho một "endpoint" hoặc một "route".
+
+///
Trong khi xây dựng một API, "đường dẫn" là các chính để phân tách "mối quan hệ" và "tài nguyên".
@@ -241,25 +242,26 @@ Chúng ta cũng sẽ gọi chúng là "**các toán tử**".
#### Định nghĩa moojt *decorator cho đường dẫn toán tử*
-```Python hl_lines="6"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[6] *}
`@app.get("/")` nói **FastAPI** rằng hàm bên dưới có trách nhiệm xử lí request tới:
* đường dẫn `/`
* sử dụng một toán tửget
-!!! info Thông tin về "`@decorator`"
- Cú pháp `@something` trong Python được gọi là một "decorator".
+/// info | Thông tin về "`@decorator`"
- Bạn đặt nó trên một hàm. Giống như một chiếc mũ xinh xắn (Tôi ddonas đó là lí do mà thuật ngữ này ra đời).
+Cú pháp `@something` trong Python được gọi là một "decorator".
- Một "decorator" lấy một hàm bên dưới và thực hiện một vài thứ với nó.
+Bạn đặt nó trên một hàm. Giống như một chiếc mũ xinh xắn (Tôi ddonas đó là lí do mà thuật ngữ này ra đời).
- Trong trường hợp của chúng ta, decorator này nói **FastAPI** rằng hàm bên dưới ứng với **đường dẫn** `/` và một **toán tử** `get`.
+Một "decorator" lấy một hàm bên dưới và thực hiện một vài thứ với nó.
- Nó là một "**decorator đường dẫn toán tử**".
+Trong trường hợp của chúng ta, decorator này nói **FastAPI** rằng hàm bên dưới ứng với **đường dẫn** `/` và một **toán tử** `get`.
+
+Nó là một "**decorator đường dẫn toán tử**".
+
+///
Bạn cũng có thể sử dụng với các toán tử khác:
@@ -274,14 +276,17 @@ Và nhiều hơn với các toán tử còn lại:
* `@app.patch()`
* `@app.trace()`
-!!! tip
- Bạn thoải mái sử dụng mỗi toán tử (phương thức HTTP) như bạn mơ ước.
+/// tip
- **FastAPI** không bắt buộc bất kì ý nghĩa cụ thể nào.
+Bạn thoải mái sử dụng mỗi toán tử (phương thức HTTP) như bạn mơ ước.
- Thông tin ở đây được biểu thị như là một chỉ dẫn, không phải là một yêu cầu bắt buộc.
+**FastAPI** không bắt buộc bất kì ý nghĩa cụ thể nào.
- Ví dụ, khi sử dụng GraphQL bạn thông thường thực hiện tất cả các hành động chỉ bằng việc sử dụng các toán tử `POST`.
+Thông tin ở đây được biểu thị như là một chỉ dẫn, không phải là một yêu cầu bắt buộc.
+
+Ví dụ, khi sử dụng GraphQL bạn thông thường thực hiện tất cả các hành động chỉ bằng việc sử dụng các toán tử `POST`.
+
+///
### Step 4: Định nghĩa **hàm cho đường dẫn toán tử**
@@ -291,9 +296,7 @@ Và nhiều hơn với các toán tử còn lại:
* **toán tử**: là `get`.
* **hàm**: là hàm bên dưới "decorator" (bên dưới `@app.get("/")`).
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[7] *}
Đây là một hàm Python.
@@ -305,18 +308,17 @@ Trong trường hợp này, nó là một hàm `async`.
Bạn cũng có thể định nghĩa nó như là một hàm thông thường thay cho `async def`:
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial003.py!}
-```
+{* ../../docs_src/first_steps/tutorial003.py hl[7] *}
-!!! note
- Nếu bạn không biết sự khác nhau, kiểm tra [Async: *"Trong khi vội vàng?"*](../async.md#in-a-hurry){.internal-link target=_blank}.
+/// note
+
+Nếu bạn không biết sự khác nhau, kiểm tra [Async: *"Trong khi vội vàng?"*](../async.md#in-a-hurry){.internal-link target=_blank}.
+
+///
### Bước 5: Nội dung trả về
-```Python hl_lines="8"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[8] *}
Bạn có thể trả về một `dict`, `list`, một trong những giá trị đơn như `str`, `int`,...
diff --git a/docs/vi/docs/tutorial/index.md b/docs/vi/docs/tutorial/index.md
index e8a93fe40..dfeeed8c5 100644
--- a/docs/vi/docs/tutorial/index.md
+++ b/docs/vi/docs/tutorial/index.md
@@ -52,22 +52,25 @@ $ pip install "fastapi[all]"
...dó cũng bao gồm `uvicorn`, bạn có thể sử dụng như một server để chạy code của bạn.
-!!! note
- Bạn cũng có thể cài đặt nó từng phần.
+/// note
- Đây là những gì bạn có thể sẽ làm một lần duy nhất bạn muốn triển khai ứng dụng của bạn lên production:
+Bạn cũng có thể cài đặt nó từng phần.
- ```
- pip install fastapi
- ```
+Đây là những gì bạn có thể sẽ làm một lần duy nhất bạn muốn triển khai ứng dụng của bạn lên production:
- Cũng cài đặt `uvicorn` để làm việc như một server:
+```
+pip install fastapi
+```
- ```
- pip install "uvicorn[standard]"
- ```
+Cũng cài đặt `uvicorn` để làm việc như một server:
- Và tương tự với từng phụ thuộc tùy chọn mà bạn muốn sử dụng.
+```
+pip install "uvicorn[standard]"
+```
+
+Và tương tự với từng phụ thuộc tùy chọn mà bạn muốn sử dụng.
+
+///
## Hướng dẫn nâng cao
diff --git a/docs/vi/docs/tutorial/static-files.md b/docs/vi/docs/tutorial/static-files.md
new file mode 100644
index 000000000..ecf8c2485
--- /dev/null
+++ b/docs/vi/docs/tutorial/static-files.md
@@ -0,0 +1,40 @@
+# Tệp tĩnh (Static Files)
+
+Bạn có thể triển khai tệp tĩnh tự động từ một thư mục bằng cách sử dụng StaticFiles.
+
+## Sử dụng `Tệp tĩnh`
+
+- Nhập `StaticFiles`.
+- "Mount" a `StaticFiles()` instance in a specific path.
+
+{* ../../docs_src/static_files/tutorial001.py hl[2,6] *}
+
+/// note | Chi tiết kỹ thuật
+
+Bạn cũng có thể sử dụng `from starlette.staticfiles import StaticFiles`.
+
+**FastAPI** cung cấp cùng `starlette.staticfiles` như `fastapi.staticfiles` giúp đơn giản hóa việc sử dụng, nhưng nó thực sự đến từ Starlette.
+
+///
+
+### "Mounting" là gì
+
+"Mounting" có nghĩa là thêm một ứng dụng "độc lập" hoàn chỉnh vào một đường dẫn cụ thể, sau đó ứng dụng đó sẽ chịu trách nhiệm xử lý tất cả các đường dẫn con.
+
+Điều này khác với việc sử dụng `APIRouter` vì một ứng dụng được gắn kết là hoàn toàn độc lập. OpenAPI và tài liệu từ ứng dụng chính của bạn sẽ không bao gồm bất kỳ thứ gì từ ứng dụng được gắn kết, v.v.
+
+Bạn có thể đọc thêm về điều này trong [Hướng dẫn Người dùng Nâng cao](../advanced/index.md){.internal-link target=\_blank}.
+
+## Chi tiết
+
+Đường dẫn đầu tiên `"/static"` là đường dẫn con mà "ứng dụng con" này sẽ được "gắn" vào. Vì vậy, bất kỳ đường dẫn nào bắt đầu bằng `"/static"` sẽ được xử lý bởi nó.
+
+Đường dẫn `directory="static"` là tên của thư mục chứa tệp tĩnh của bạn.
+
+Tham số `name="static"` đặt tên cho nó để có thể được sử dụng bên trong **FastAPI**.
+
+Tất cả các tham số này có thể khác với `static`, điều chỉnh chúng với phù hợp với ứng dụng của bạn.
+
+## Thông tin thêm
+
+Để biết thêm chi tiết và tùy chọn, hãy xem Starlette's docs about Static Files.
diff --git a/docs/vi/docs/virtual-environments.md b/docs/vi/docs/virtual-environments.md
new file mode 100644
index 000000000..22d8e153e
--- /dev/null
+++ b/docs/vi/docs/virtual-environments.md
@@ -0,0 +1,842 @@
+# Môi trường ảo (Virtual Environments)
+
+Khi bạn làm việc trong các dự án Python, bạn có thể sử dụng một **môi trường ảo** (hoặc một cơ chế tương tự) để cách ly các gói bạn cài đặt cho mỗi dự án.
+
+/// info
+Nếu bạn đã biết về các môi trường ảo, cách tạo chúng và sử dụng chúng, bạn có thể bỏ qua phần này. 🤓
+
+///
+
+/// tip
+
+Một **môi trường ảo** khác với một **biến môi trường (environment variable)**.
+
+Một **biến môi trường** là một biến trong hệ thống có thể được sử dụng bởi các chương trình.
+
+Một **môi trường ảo** là một thư mục với một số tệp trong đó.
+
+///
+
+/// info
+
+Trang này sẽ hướng dẫn bạn cách sử dụng các **môi trường ảo** và cách chúng hoạt động.
+
+Nếu bạn đã sẵn sàng sử dụng một **công cụ có thể quản lý tất cả mọi thứ** cho bạn (bao gồm cả việc cài đặt Python), hãy thử uv.
+
+///
+
+## Tạo một Dự án
+
+Đầu tiên, tạo một thư mục cho dự án của bạn.
+
+Cách tôi thường làm là tạo một thư mục có tên `code` trong thư mục `home/user`.
+
+Và trong thư mục đó, tôi tạo một thư mục cho mỗi dự án.
+
+
-
+
@@ -93,7 +93,7 @@ FastAPI jẹ́ ìgbàlódé, tí ó yára (iṣẹ-giga), ìlànà wẹ́ẹ́b
"_Ní tòótọ́, ohun tí o kọ dára ó sì tún dán. Ní ọ̀pọ̀lọpọ̀ ọ̀nà, ohun tí mo fẹ́ kí **Hug** jẹ́ nìyẹn - ó wúni lórí gan-an láti rí ẹnìkan tí ó kọ́ nǹkan bí èyí._"
-
+
---
@@ -449,7 +449,7 @@ Láti ní òye síi nípa rẹ̀, wo abala àwọn
email_validator - fún ifọwọsi ímeèlì.
+* email-validator - fún ifọwọsi ímeèlì.
* pydantic-settings - fún ètò ìsàkóso.
* pydantic-extra-types - fún àfikún oríṣi láti lọ pẹ̀lú Pydantic.
diff --git a/docs/zh-hant/docs/about/index.md b/docs/zh-hant/docs/about/index.md
new file mode 100644
index 000000000..5dcee68f2
--- /dev/null
+++ b/docs/zh-hant/docs/about/index.md
@@ -0,0 +1,3 @@
+# 關於 FastAPI
+
+關於 FastAPI、其設計、靈感來源等更多資訊。 🤓
diff --git a/docs/zh-hant/docs/async.md b/docs/zh-hant/docs/async.md
new file mode 100644
index 000000000..6ab75d2ab
--- /dev/null
+++ b/docs/zh-hant/docs/async.md
@@ -0,0 +1,442 @@
+# 並行與 async / await
+
+有關*路徑操作函式*的 `async def` 語法的細節與非同步 (asynchronous) 程式碼、並行 (concurrency) 與平行 (parallelism) 的一些背景知識。
+
+## 趕時間嗎?
+
+TL;DR:
+
+如果你正在使用要求你以 `await` 語法呼叫的第三方函式庫,例如:
+
+```Python
+results = await some_library()
+```
+
+然後,使用 `async def` 宣告你的*路徑操作函式*:
+
+
+```Python hl_lines="2"
+@app.get('/')
+async def read_results():
+ results = await some_library()
+ return results
+```
+
+/// note | 注意
+
+你只能在 `async def` 建立的函式內使用 `await`。
+
+///
+
+---
+
+如果你使用的是第三方函式庫並且它需要與某些外部資源(例如資料庫、API、檔案系統等)進行通訊,但不支援 `await`(目前大多數資料庫函式庫都是這樣),在這種情況下,你可以像平常一樣使用 `def` 宣告*路徑操作函式*,如下所示:
+
+```Python hl_lines="2"
+@app.get('/')
+def results():
+ results = some_library()
+ return results
+```
+
+---
+
+如果你的應用程式不需要與外部資源進行任何通訊並等待其回應,請使用 `async def`。
+
+---
+
+如果你不確定該用哪個,直接用 `def` 就好。
+
+---
+
+**注意**:你可以在*路徑操作函式*中混合使用 `def` 和 `async def` ,並使用最適合你需求的方式來定義每個函式。FastAPI 會幫你做正確的處理。
+
+無論如何,在上述哪種情況下,FastAPI 仍將以非同步方式運行,並且速度非常快。
+
+但透過遵循上述步驟,它將能進行一些效能最佳化。
+
+## 技術細節
+
+現代版本的 Python 支援使用 **「協程」** 的 **`async` 和 `await`** 語法來寫 **「非同步程式碼」**。
+
+接下來我們逐一介紹:
+
+* **非同步程式碼**
+* **`async` 和 `await`**
+* **協程**
+
+## 非同步程式碼
+
+非同步程式碼僅意味著程式語言 💬 有辦法告訴電腦/程式 🤖 在程式碼中的某個點,它 🤖 需要等待某些事情完成。讓我們假設這些事情被稱為「慢速檔案」📝。
+
+因此,在等待「慢速檔案」📝 完成的這段時間,電腦可以去處理一些其他工作。
+
+接著程式 🤖 會在有空檔時回來查看是否有等待的工作已經完成,並執行必要的後續操作。
+
+接下來,它 🤖 完成第一個工作(例如我們的「慢速檔案」📝)並繼續執行相關的所有操作。
+這個「等待其他事情」通常指的是一些相對較慢的(與處理器和 RAM 記憶體的速度相比)的 I/O 操作,比如說:
+
+* 透過網路傳送來自用戶端的資料
+* 從網路接收來自用戶端的資料
+* 從磁碟讀取檔案內容
+* 將內容寫入磁碟
+* 遠端 API 操作
+* 資料庫操作
+* 資料庫查詢
+* 等等
+
+由於大部分的執行時間都消耗在等待 I/O 操作上,因此這些操作被稱為 "I/O 密集型" 操作。
+
+之所以稱為「非同步」,是因為電腦/程式不需要與那些耗時的任務「同步」,等待任務完成的精確時間,然後才能取得結果並繼續工作。
+
+相反地,非同步系統在任務完成後,可以讓任務稍微等一下(幾微秒),等待電腦/程式完成手頭上的其他工作,然後再回來取得結果繼續進行。
+
+相對於「非同步」(asynchronous),「同步」(synchronous)也常被稱作「順序性」(sequential),因為電腦/程式會依序執行所有步驟,即便這些步驟涉及等待,才會切換到其他任務。
+
+### 並行與漢堡
+
+上述非同步程式碼的概念有時也被稱為「並行」,它不同於「平行」。
+
+並行和平行都與 "不同的事情或多或少同時發生" 有關。
+
+但並行和平行之間的細節是完全不同的。
+
+為了理解差異,請想像以下有關漢堡的故事:
+
+### 並行漢堡
+
+你和你的戀人去速食店,排隊等候時,收銀員正在幫排在你前面的人點餐。😍
+
+
+
+輪到你了,你給你與你的戀人點了兩個豪華漢堡。🍔🍔
+
+
+
+收銀員通知廚房準備你的漢堡(儘管他們還在為前面其他顧客準備食物)。
+
+
+
+之後你完成付款。💸
+
+收銀員給你一個號碼牌。
+
+
+
+在等待漢堡的同時,你可以與戀人選一張桌子,然後坐下來聊很長一段時間(因為漢堡十分豪華,準備特別費工。)
+
+這段時間,你還能欣賞你的戀人有多麼的可愛、聰明與迷人。✨😍✨
+
+
+
+當你和戀人邊聊天邊等待時,你會不時地查看櫃檯上的顯示的號碼,確認是否已經輪到你了。
+
+然後在某個時刻,終於輪到你了。你走到櫃檯,拿了漢堡,然後回到桌子上。
+
+
+
+你和戀人享用這頓大餐,整個過程十分開心✨
+
+
+
+/// info
+
+漂亮的插畫來自 Ketrina Thompson. 🎨
+
+///
+
+---
+
+想像你是故事中的電腦或程式 🤖。
+
+當你排隊時,你在放空😴,等待輪到你,沒有做任何「生產性」的事情。但這沒關係,因為收銀員只是接單(而不是準備食物),所以排隊速度很快。
+
+然後,當輪到你時,你開始做真正「有生產力」的工作,處理菜單,決定你想要什麼,替戀人選擇餐點,付款,確認你給了正確的帳單或信用卡,檢查你是否被正確收費,確認訂單中的項目是否正確等等。
+
+但是,即使你還沒有拿到漢堡,你與收銀員的工作已經「暫停」了 ⏸,因為你必須等待 🕙 漢堡準備好。
+
+但當你離開櫃檯,坐到桌子旁,拿著屬於你的號碼等待時,你可以把注意力 🔀 轉移到戀人身上,並開始「工作」⏯ 🤓——也就是和戀人調情 😍。這時你又開始做一些非常「有生產力」的事情。
+
+接著,收銀員 💁 將你的號碼顯示在櫃檯螢幕上,並告訴你「漢堡已經做好了」。但你不會瘋狂地立刻跳起來,因為顯示的號碼變成了你的。你知道沒有人會搶走你的漢堡,因為你有自己的號碼,他們也有他們的號碼。
+
+所以你會等戀人講完故事(完成當前的工作 ⏯/正在進行的任務 🤓),然後微笑著溫柔地說你要去拿漢堡了 ⏸。
+
+然後你走向櫃檯 🔀,回到已經完成的最初任務 ⏯,拿起漢堡,說聲謝謝,並帶回桌上。這就結束了與櫃檯的互動步驟/任務 ⏹,接下來會產生一個新的任務,「吃漢堡」 🔀 ⏯,而先前的「拿漢堡」任務已經完成了 ⏹。
+
+### 平行漢堡
+
+現在,讓我們來想像這裡不是「並行漢堡」,而是「平行漢堡」。
+
+你和戀人一起去吃平行的速食餐。
+
+你們站在隊伍中,前面有幾位(假設有 8 位)既是收銀員又是廚師的員工,他們同時接單並準備餐點。
+
+所有排在你前面的人都在等著他們的漢堡準備好後才會離開櫃檯,因為每位收銀員在接完單後,馬上會去準備漢堡,然後才回來處理下一個訂單。
+
+
+
+終於輪到你了,你為你和你的戀人點了兩個非常豪華的漢堡。
+
+你付款了 💸。
+
+
+
+收銀員走進廚房準備食物。
+
+你站在櫃檯前等待 🕙,以免其他人先拿走你的漢堡,因為這裡沒有號碼牌系統。
+
+
+
+由於你和戀人都忙著不讓別人搶走你的漢堡,等漢堡準備好時,你根本無法專心和戀人互動。😞
+
+這是「同步」(synchronous)工作,你和收銀員/廚師 👨🍳 是「同步化」的。你必須等到 🕙 收銀員/廚師 👨🍳 完成漢堡並交給你的那一刻,否則別人可能會拿走你的餐點。
+
+
+
+最終,經過長時間的等待 🕙,收銀員/廚師 👨🍳 拿著漢堡回來了。
+
+
+
+你拿著漢堡,和你的戀人回到餐桌。
+
+你們僅僅是吃完漢堡,然後就結束了。⏹
+
+
+
+整個過程中沒有太多的談情說愛,因為大部分時間 🕙 都花在櫃檯前等待。😞
+
+/// info
+
+漂亮的插畫來自 Ketrina Thompson. 🎨
+
+///
+
+---
+
+在這個平行漢堡的情境下,你是一個程式 🤖 且有兩個處理器(你和戀人),兩者都在等待 🕙 並專注於等待櫃檯上的餐點 🕙,等待的時間非常長。
+
+這家速食店有 8 個處理器(收銀員/廚師)。而並行漢堡店可能只有 2 個處理器(一位收銀員和一位廚師)。
+
+儘管如此,最終的體驗並不是最理想的。😞
+
+---
+
+這是與漢堡類似的故事。🍔
+
+一個更「現實」的例子,想像一間銀行。
+
+直到最近,大多數銀行都有多位出納員 👨💼👨💼👨💼👨💼,以及一條長長的隊伍 🕙🕙🕙🕙🕙🕙🕙🕙。
+
+所有的出納員都在一個接一個地滿足每位客戶的所有需求 👨💼⏯。
+
+你必須長時間排隊 🕙,不然就會失去機會。
+
+所以,你不會想帶你的戀人 😍 一起去銀行辦事 🏦。
+
+### 漢堡結論
+
+在「和戀人一起吃速食漢堡」的這個場景中,由於有大量的等待 🕙,使用並行系統 ⏸🔀⏯ 更有意義。
+
+這也是大多數 Web 應用的情況。
+
+許多用戶正在使用你的應用程式,而你的伺服器則在等待 🕙 這些用戶不那麼穩定的網路來傳送請求。
+
+接著,再次等待 🕙 回應。
+
+這種「等待」 🕙 通常以微秒來衡量,但累加起來,最終還是花費了很多等待時間。
+
+這就是為什麼對於 Web API 來說,使用非同步程式碼 ⏸🔀⏯ 是非常有意義的。
+
+這種類型的非同步性正是 NodeJS 成功的原因(儘管 NodeJS 不是平行的),這也是 Go 語言作為程式語言的一個強大優勢。
+
+這與 **FastAPI** 所能提供的性能水平相同。
+
+你可以同時利用並行性和平行性,進一步提升效能,這比大多數已測試的 NodeJS 框架都更快,並且與 Go 語言相當,而 Go 是一種更接近 C 的編譯語言(感謝 Starlette)。
+
+### 並行比平行更好嗎?
+
+不是的!這不是故事的本意。
+
+並行與平行不同。並行在某些 **特定** 的需要大量等待的情境下表現更好。正因如此,並行在 Web 應用程式開發中通常比平行更有優勢。但並不是所有情境都如此。
+
+因此,為了平衡報導,想像下面這個短故事
+
+> 你需要打掃一間又大又髒的房子。
+
+*是的,這就是全部的故事。*
+
+---
+
+這裡沒有任何需要等待 🕙 的地方,只需要在房子的多個地方進行大量的工作。
+
+你可以像漢堡的例子那樣輪流進行,先打掃客廳,再打掃廚房,但由於你不需要等待 🕙 任何事情,只需要持續地打掃,輪流並不會影響任何結果。
+
+無論輪流執行與否(並行),你都需要相同的工時完成任務,同時需要執行相同工作量。
+
+但是,在這種情境下,如果你可以邀請8位前收銀員/廚師(現在是清潔工)來幫忙,每個人(加上你)負責房子的某個區域,這樣你就可以 **平行** 地更快完成工作。
+
+在這個場景中,每個清潔工(包括你)都是一個處理器,完成工作的一部分。
+
+由於大多數的執行時間都花在實際的工作上(而不是等待),而電腦中的工作由 CPU 完成,因此這些問題被稱為「CPU 密集型」。
+
+---
+
+常見的 CPU 密集型操作範例包括那些需要進行複雜數學計算的任務。
+
+例如:
+
+* **音訊**或**圖像處理**;
+* **電腦視覺**:一張圖片由數百萬個像素組成,每個像素有 3 個值/顏色,處理這些像素通常需要同時進行大量計算;
+* **機器學習**: 通常需要大量的「矩陣」和「向量」運算。想像一個包含數字的巨大電子表格,並所有的數字同時相乘;
+* **深度學習**: 這是機器學習的子領域,同樣適用。只不過這不僅僅是一張數字表格,而是大量的數據集合,並且在很多情況下,你會使用特殊的處理器來構建或使用這些模型。
+
+### 並行 + 平行: Web + 機器學習
+
+使用 **FastAPI**,你可以利用並行的優勢,這在 Web 開發中非常常見(這也是 NodeJS 的最大吸引力)。
+
+但你也可以利用平行與多行程 (multiprocessing)(讓多個行程同時運行) 的優勢來處理機器學習系統中的 **CPU 密集型**工作。
+
+這一點,再加上 Python 是 **資料科學**、機器學習,尤其是深度學習的主要語言,讓 **FastAPI** 成為資料科學/機器學習 Web API 和應用程式(以及許多其他應用程式)的絕佳選擇。
+
+想了解如何在生產環境中實現這種平行性,請參見 [部屬](deployment/index.md){.internal-link target=_blank}。
+
+## `async` 和 `await`
+
+現代 Python 版本提供一種非常直觀的方式定義非同步程式碼。這使得它看起來就像正常的「順序」程式碼,並在適當的時機「等待」。
+
+當某個操作需要等待才能回傳結果,並且支援這些新的 Python 特性時,你可以像這樣編寫程式碼:
+
+```Python
+burgers = await get_burgers(2)
+```
+
+這裡的關鍵是 `await`。它告訴 Python 必須等待 ⏸ `get_burgers(2)` 完成它的工作 🕙, 然後將結果儲存在 `burgers` 中。如此,Python 就可以在此期間去處理其他事情 🔀 ⏯ (例如接收另一個請求)。
+
+要讓 `await` 運作,它必須位於支持非同步功能的函式內。為此,只需使用 `async def` 宣告函式:
+
+```Python hl_lines="1"
+async def get_burgers(number: int):
+ # Do some asynchronous stuff to create the burgers
+ return burgers
+```
+
+...而不是 `def`:
+
+```Python hl_lines="2"
+# This is not asynchronous
+def get_sequential_burgers(number: int):
+ # Do some sequential stuff to create the burgers
+ return burgers
+```
+
+使用 `async def`,Python Python 知道在該函式內需要注意 `await`,並且它可以「暫停」 ⏸ 執行該函式,然後執行其他任務 🔀 後回來。
+
+當你想要呼叫 `async def` 函式時,必須使用「await」。因此,這樣寫將無法運行:
+
+```Python
+# This won't work, because get_burgers was defined with: async def
+burgers = get_burgers(2)
+```
+
+---
+
+如果你正在使用某個函式庫,它告訴你可以使用 `await` 呼叫它,那麼你需要用 `async def` 定義*路徑操作函式*,如:
+
+```Python hl_lines="2-3"
+@app.get('/burgers')
+async def read_burgers():
+ burgers = await get_burgers(2)
+ return burgers
+```
+
+### 更多技術細節
+
+你可能已經注意到,`await` 只能在 `async def` 定義的函式內使用。
+
+但同時,使用 `async def` 定義的函式本身也必須被「等待」。所以,帶有 `async def` 函式只能在其他使用 `async def` 定義的函式內呼叫。
+
+那麼,這就像「先有雞還是先有蛋」的問題,要如何呼叫第一個 `async` 函式呢?
+
+如果你使用 FastAPI,無需擔心這個問題,因為「第一個」函式將是你的*路徑操作函式*,FastAPI 會知道如何正確處理這個問題。
+
+但如果你想在沒有 FastAPI 的情況下使用 `async` / `await`,你也可以這樣做。
+
+### 編寫自己的非同步程式碼
+
+Starlette (和 **FastAPI**) 是基於 AnyIO 實作的,這使得它們與 Python 標準函式庫相容 asyncio 和 Trio。
+
+特別是,你可以直接使用 AnyIO 來處理更複雜的並行使用案例,這些案例需要你在自己的程式碼中使用更高階的模式。
+
+即使你不使用 **FastAPI**,你也可以使用 AnyIO 來撰寫自己的非同步應用程式,並獲得高相容性及一些好處(例如結構化並行)。
+
+### 其他形式的非同步程式碼
+
+使用 `async` 和 `await` 的風格在語言中相對較新。
+
+但它使處理異步程式碼變得更加容易。
+
+相同的語法(或幾乎相同的語法)最近也被包含在現代 JavaScript(無論是瀏覽器還是 NodeJS)中。
+
+但在此之前,處理異步程式碼要更加複雜和困難。
+
+在較舊的 Python 版本中,你可能會使用多執行緒或 Gevent。但這些程式碼要更難以理解、調試和思考。
+
+在較舊的 NodeJS / 瀏覽器 JavaScript 中,你會使用「回呼」,這可能會導致回呼地獄。
+
+## 協程
+
+**協程** 只是 `async def` 函式所回傳的非常特殊的事物名稱。Python 知道它是一個類似函式的東西,可以啟動它,並且在某個時刻它會結束,但它也可能在內部暫停 ⏸,只要遇到 `await`。
+
+這種使用 `async` 和 `await` 的非同步程式碼功能通常被概括為「協程」。這與 Go 語言的主要特性「Goroutines」相似。
+
+## 結論
+
+讓我們再次回顧之前的句子:
+
+> 現代版本的 Python 支持使用 **"協程"** 的 **`async` 和 `await`** 語法來寫 **"非同步程式碼"**。
+
+現在應該能明白其含意了。✨
+
+這些就是驅動 FastAPI(通過 Starlette)運作的原理,也讓它擁有如此驚人的效能。
+
+## 非常技術性的細節
+
+/// warning
+
+你大概可以跳過這段。
+
+這裡是有關 FastAPI 內部技術細節。
+
+如果你有相當多的技術背景(例如協程、執行緒、阻塞等),並且對 FastAPI 如何處理 `async def` 與常規 `def` 感到好奇,請繼續閱讀。
+
+///
+
+### 路徑操作函数
+
+當你使用 `def` 而不是 `async def` 宣告*路徑操作函式*時,該函式會在外部的執行緒池(threadpool)中執行,然後等待結果,而不是直接呼叫(因為這樣會阻塞伺服器)。
+
+如果你來自於其他不以這種方式運作的非同步框架,而且你習慣於使用普通的 `def` 定義僅進行簡單計算的*路徑操作函式*,目的是獲得微小的性能增益(大約 100 奈秒),請注意,在 FastAPI 中,效果會完全相反。在這些情況下,最好使用 `async def`除非你的*路徑操作函式*執行阻塞的 I/O 的程式碼。
+
+不過,在這兩種情況下,**FastAPI** [仍然很快](index.md#_11){.internal-link target=_blank}至少與你之前的框架相當(或者更快)。
+
+### 依賴項(Dependencies)
+
+同樣適用於[依賴項](tutorial/dependencies/index.md){.internal-link target=_blank}。如果依賴項是一個標準的 `def` 函式,而不是 `async def`,那麼它在外部的執行緒池被運行。
+
+### 子依賴項
+
+你可以擁有多個相互依賴的依賴項和[子依賴項](tutorial/dependencies/sub-dependencies.md){.internal-link target=_blank} (作為函式定義的參數),其中一些可能是用 `async def` 宣告,也可能是用 `def` 宣告。它們仍然可以正常運作,用 `def` 定義的那些將會在外部的執行緒中呼叫(來自執行緒池),而不是被「等待」。
+
+### 其他輔助函式
+
+你可以直接呼叫任何使用 `def` 或 `async def` 建立的其他輔助函式,FastAPI 不會影響你呼叫它們的方式。
+
+這與 FastAPI 為你呼叫*路徑操作函式*和依賴項的邏輯有所不同。
+
+如果你的輔助函式是用 `def` 宣告的,它將會被直接呼叫(按照你在程式碼中撰寫的方式),而不是在執行緒池中。如果該函式是用 `async def` 宣告,那麼你在呼叫時應該使用 `await` 等待其結果。
+
+---
+
+再一次強調,這些都是非常技術性的細節,如果你特地在尋找這些資訊,這些內容可能會對你有幫助。
+
+否則,只需遵循上面提到的指引即可:趕時間嗎?.
diff --git a/docs/zh-hant/docs/benchmarks.md b/docs/zh-hant/docs/benchmarks.md
index cbd5a6cde..c59e8e71c 100644
--- a/docs/zh-hant/docs/benchmarks.md
+++ b/docs/zh-hant/docs/benchmarks.md
@@ -1,34 +1,34 @@
-# 基準測試
-
-由第三方機構 TechEmpower 的基準測試表明在 Uvicorn 下運行的 **FastAPI** 應用程式是 最快的 Python 可用框架之一,僅次於 Starlette 和 Uvicorn 本身(於 FastAPI 內部使用)。
-
-但是在查看基準得分和對比時,請注意以下幾點。
-
-## 基準測試和速度
-
-當你查看基準測試時,時常會見到幾個不同類型的工具被同時進行測試。
-
-具體來說,是將 Uvicorn、Starlette 和 FastAPI 同時進行比較(以及許多其他工具)。
-
-該工具解決的問題越簡單,其效能就越好。而且大多數基準測試不會測試該工具提供的附加功能。
-
-層次結構如下:
-
-* **Uvicorn**:ASGI 伺服器
- * **Starlette**:(使用 Uvicorn)一個網頁微框架
- * **FastAPI**:(使用 Starlette)一個 API 微框架,具有用於建立 API 的多個附加功能、資料驗證等。
-
-* **Uvicorn**:
- * 具有最佳效能,因為除了伺服器本身之外,它沒有太多額外的程式碼。
- * 你不會直接在 Uvicorn 中編寫應用程式。這意味著你的程式碼必須或多或少地包含 Starlette(或 **FastAPI**)提供的所有程式碼。如果你這樣做,你的最終應用程式將具有與使用框架相同的開銷並最大限度地減少應用程式程式碼和錯誤。
- * 如果你要比較 Uvicorn,請將其與 Daphne、Hypercorn、uWSGI 等應用程式伺服器進行比較。
-* **Starlette**:
- * 繼 Uvicorn 之後的次佳表現。事實上,Starlette 使用 Uvicorn 來運行。因此它將可能只透過執行更多程式碼而變得比 Uvicorn「慢」。
- * 但它為你提供了建立簡單網頁應用程式的工具,以及基於路徑的路由等。
- * 如果你要比較 Starlette,請將其與 Sanic、Flask、Django 等網頁框架(或微框架)進行比較。
-* **FastAPI**:
- * 就像 Starlette 使用 Uvicorn 並不能比它更快一樣, **FastAPI** 使用 Starlette,所以它不能比它更快。
- * FastAPI 在 Starlette 基礎之上提供了更多功能。包含建構 API 時所需要的功能,例如資料驗證和序列化。FastAPI 可以幫助你自動產生 API 文件,(應用程式啟動時將會自動生成文件,所以不會增加應用程式運行時的開銷)。
- * 如果你沒有使用 FastAPI 而是直接使用 Starlette(或其他工具,如 Sanic、Flask、Responder 等),你將必須自行實現所有資料驗證和序列化。因此,你的最終應用程式仍然具有與使用 FastAPI 建置相同的開銷。在許多情況下,這種資料驗證和序列化是應用程式中編寫最大量的程式碼。
- * 因此透過使用 FastAPI,你可以節省開發時間、錯誤與程式碼數量,並且相比不使用 FastAPI 你很大可能會獲得相同或更好的效能(因為那樣你必須在程式碼中實現所有相同的功能)。
- * 如果你要與 FastAPI 比較,請將其與能夠提供資料驗證、序列化和文件的網頁應用程式框架(或工具集)進行比較,例如 Flask-apispec、NestJS、Molten 等框架。
+# 基準測試
+
+由第三方機構 TechEmpower 的基準測試表明在 Uvicorn 下運行的 **FastAPI** 應用程式是 最快的 Python 可用框架之一,僅次於 Starlette 和 Uvicorn 本身(於 FastAPI 內部使用)。
+
+但是在查看基準得分和對比時,請注意以下幾點。
+
+## 基準測試和速度
+
+當你查看基準測試時,時常會見到幾個不同類型的工具被同時進行測試。
+
+具體來說,是將 Uvicorn、Starlette 和 FastAPI 同時進行比較(以及許多其他工具)。
+
+該工具解決的問題越簡單,其效能就越好。而且大多數基準測試不會測試該工具提供的附加功能。
+
+層次結構如下:
+
+* **Uvicorn**:ASGI 伺服器
+ * **Starlette**:(使用 Uvicorn)一個網頁微框架
+ * **FastAPI**:(使用 Starlette)一個 API 微框架,具有用於建立 API 的多個附加功能、資料驗證等。
+
+* **Uvicorn**:
+ * 具有最佳效能,因為除了伺服器本身之外,它沒有太多額外的程式碼。
+ * 你不會直接在 Uvicorn 中編寫應用程式。這意味著你的程式碼必須或多或少地包含 Starlette(或 **FastAPI**)提供的所有程式碼。如果你這樣做,你的最終應用程式將具有與使用框架相同的開銷並最大限度地減少應用程式程式碼和錯誤。
+ * 如果你要比較 Uvicorn,請將其與 Daphne、Hypercorn、uWSGI 等應用程式伺服器進行比較。
+* **Starlette**:
+ * 繼 Uvicorn 之後的次佳表現。事實上,Starlette 使用 Uvicorn 來運行。因此它將可能只透過執行更多程式碼而變得比 Uvicorn「慢」。
+ * 但它為你提供了建立簡單網頁應用程式的工具,以及基於路徑的路由等。
+ * 如果你要比較 Starlette,請將其與 Sanic、Flask、Django 等網頁框架(或微框架)進行比較。
+* **FastAPI**:
+ * 就像 Starlette 使用 Uvicorn 並不能比它更快一樣, **FastAPI** 使用 Starlette,所以它不能比它更快。
+ * FastAPI 在 Starlette 基礎之上提供了更多功能。包含建構 API 時所需要的功能,例如資料驗證和序列化。FastAPI 可以幫助你自動產生 API 文件,(應用程式啟動時將會自動生成文件,所以不會增加應用程式運行時的開銷)。
+ * 如果你沒有使用 FastAPI 而是直接使用 Starlette(或其他工具,如 Sanic、Flask、Responder 等),你將必須自行實現所有資料驗證和序列化。因此,你的最終應用程式仍然具有與使用 FastAPI 建置相同的開銷。在許多情況下,這種資料驗證和序列化是應用程式中編寫最大量的程式碼。
+ * 因此透過使用 FastAPI,你可以節省開發時間、錯誤與程式碼數量,並且相比不使用 FastAPI 你很大可能會獲得相同或更好的效能(因為那樣你必須在程式碼中實現所有相同的功能)。
+ * 如果你要與 FastAPI 比較,請將其與能夠提供資料驗證、序列化和文件的網頁應用程式框架(或工具集)進行比較,例如 Flask-apispec、NestJS、Molten 等框架。
diff --git a/docs/zh-hant/docs/deployment/cloud.md b/docs/zh-hant/docs/deployment/cloud.md
new file mode 100644
index 000000000..29ebe3ff5
--- /dev/null
+++ b/docs/zh-hant/docs/deployment/cloud.md
@@ -0,0 +1,17 @@
+# 在雲端部署 FastAPI
+
+你幾乎可以使用**任何雲端供應商**來部署你的 FastAPI 應用程式。
+
+在大多數情況下,主要的雲端供應商都有部署 FastAPI 的指南。
+
+## 雲端供應商 - 贊助商
+
+一些雲端供應商 ✨ [**贊助 FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨,這確保了 FastAPI 及其**生態系統**持續健康地**發展**。
+
+這也展現了他們對 FastAPI 和其**社群**(包括你)的真正承諾,他們不僅希望為你提供**優質的服務**,還希望確保你擁有一個**良好且健康的框架**:FastAPI。🙇
+
+你可能會想嘗試他們的服務,以下有他們的指南:
+
+* Platform.sh
+* Porter
+* Coherence
diff --git a/docs/zh-hant/docs/deployment/index.md b/docs/zh-hant/docs/deployment/index.md
new file mode 100644
index 000000000..1726562b4
--- /dev/null
+++ b/docs/zh-hant/docs/deployment/index.md
@@ -0,0 +1,21 @@
+# 部署
+
+部署 **FastAPI** 應用程式相對容易。
+
+## 部署是什麼意思
+
+**部署**應用程式指的是執行一系列必要的步驟,使其能夠**讓使用者存取和使用**。
+
+對於一個 **Web API**,部署通常涉及將其放置在**遠端伺服器**上,並使用性能優良且穩定的**伺服器程式**,確保使用者能夠高效、無中斷地存取應用程式,且不會遇到問題。
+
+這與**開發**階段形成鮮明對比,在**開發**階段,你會不斷更改程式碼、破壞程式碼、修復程式碼,然後停止和重新啟動伺服器等。
+
+## 部署策略
+
+根據你的使用場景和使用工具,有多種方法可以實現此目的。
+
+你可以使用一些工具自行**部署伺服器**,你也可以使用能為你完成部分工作的**雲端服務**,或其他可能的選項。
+
+我將向你展示在部署 **FastAPI** 應用程式時你可能應該記住的一些主要概念(儘管其中大部分適用於任何其他類型的 Web 應用程式)。
+
+在接下來的部分中,你將看到更多需要記住的細節以及一些技巧。 ✨
diff --git a/docs/zh-hant/docs/environment-variables.md b/docs/zh-hant/docs/environment-variables.md
new file mode 100644
index 000000000..a1598fc01
--- /dev/null
+++ b/docs/zh-hant/docs/environment-variables.md
@@ -0,0 +1,298 @@
+# 環境變數
+
+/// tip
+
+如果你已經知道什麼是「環境變數」並且知道如何使用它們,你可以放心跳過這一部分。
+
+///
+
+環境變數(也稱為「**env var**」)是一個獨立於 Python 程式碼**之外**的變數,它存在於**作業系統**中,可以被你的 Python 程式碼(或其他程式)讀取。
+
+環境變數對於處理應用程式**設定**(作為 Python **安裝**的一部分等方面)非常有用。
+
+## 建立和使用環境變數
+
+你在 **shell(終端機)**中就可以**建立**和使用環境變數,並不需要用到 Python:
+
+//// tab | Linux, macOS, Windows Bash
+
+
-
+
@@ -87,7 +87,7 @@ FastAPI 是一個現代、快速(高效能)的 web 框架,用於 Python
"_老實說,你建造的東西看起來非常堅固和精緻。在很多方面,這就是我想要的,看到有人建造它真的很鼓舞人心。_"
-
+
---
@@ -443,7 +443,7 @@ item: Item
用於 Pydantic:
--
email_validator - 用於電子郵件驗證。
+- email-validator - 用於電子郵件驗證。
- pydantic-settings - 用於設定管理。
- pydantic-extra-types - 用於與 Pydantic 一起使用的額外型別。
diff --git a/docs/zh-hant/docs/resources/index.md b/docs/zh-hant/docs/resources/index.md
new file mode 100644
index 000000000..f4c70a3a0
--- /dev/null
+++ b/docs/zh-hant/docs/resources/index.md
@@ -0,0 +1,3 @@
+# 資源
+
+額外的資源、外部連結、文章等。 ✈️
diff --git a/docs/zh-hant/docs/tutorial/first-steps.md b/docs/zh-hant/docs/tutorial/first-steps.md
new file mode 100644
index 000000000..a557fa369
--- /dev/null
+++ b/docs/zh-hant/docs/tutorial/first-steps.md
@@ -0,0 +1,331 @@
+# 第一步
+
+最簡單的 FastAPI 檔案可能看起來像這樣:
+
+{* ../../docs_src/first_steps/tutorial001.py *}
+
+將其複製到一個名為 `main.py` 的文件中。
+
+執行即時重新載入伺服器(live server):
+
+
get操作
+
+/// info | `@decorator` Info
+
+Python 中的 `@something` 語法被稱為「裝飾器」。
+
+你把它放在一個函式上面。像一個漂亮的裝飾帽子(我猜這是術語的來源)。
+
+一個「裝飾器」會對下面的函式做一些事情。
+
+在這種情況下,這個裝飾器告訴 **FastAPI** 那個函式對應於 **路徑** `/` 和 **操作** `get`.
+
+這就是「**路徑操作裝飾器**」。
+
+///
+
+你也可以使用其他的操作:
+
+* `@app.post()`
+* `@app.put()`
+* `@app.delete()`
+
+以及更少見的:
+
+* `@app.options()`
+* `@app.head()`
+* `@app.patch()`
+* `@app.trace()`
+
+/// tip
+
+你可以自由地使用每個操作(HTTP 方法)。
+
+**FastAPI** 不強制任何特定的意義。
+
+這裡的資訊作為一個指南,而不是要求。
+
+例如,當使用 GraphQL 時,你通常只使用 `POST` 操作。
+
+///
+
+### 第四步:定義 **路徑操作函式**
+
+這是我們的「**路徑操作函式**」:
+
+* **path**: 是 `/`.
+* **operation**: 是 `get`.
+* **function**: 是裝飾器下面的函式(在 `@app.get("/")` 下面)。
+
+{* ../../docs_src/first_steps/tutorial001.py h1[7] *}
+
+這就是一個 Python 函式。
+
+它將會在 **FastAPI** 收到一個請求時被呼叫,使用 `GET` 操作。
+
+在這種情況下,它是一個 `async` 函式。
+
+---
+
+你可以將它定義為一個正常的函式,而不是 `async def`:
+
+{* ../../docs_src/first_steps/tutorial003.py h1[7] *}
+
+/// note
+
+如果你不知道差別,請查看 [Async: *"In a hurry?"*](../async.md#in-a-hurry){.internal-link target=_blank}.
+
+///
+
+### 第五步:回傳內容
+
+{* ../../docs_src/first_steps/tutorial001.py h1[8] *}
+
+你可以返回一個 `dict`、`list`、單個值作為 `str`、`int` 等。
+
+你也可以返回 Pydantic 模型(稍後你會看到更多關於這方面的內容)。
+
+有很多其他物件和模型會自動轉換為 JSON(包括 ORMs,等等)。試用你最喜歡的,很有可能它們已經有支援。
+
+## 回顧
+
+* 引入 `FastAPI`.
+* 建立一個 `app` 實例。
+* 寫一個 **路徑操作裝飾器** 使用裝飾器像 `@app.get("/")`。
+* 定義一個 **路徑操作函式**;例如,`def root(): ...`。
+* 使用命令 `fastapi dev` 執行開發伺服器。
diff --git a/docs/zh-hant/docs/tutorial/index.md b/docs/zh-hant/docs/tutorial/index.md
new file mode 100644
index 000000000..ae0056f52
--- /dev/null
+++ b/docs/zh-hant/docs/tutorial/index.md
@@ -0,0 +1,102 @@
+# 教學 - 使用者指南
+
+本教學將一步一步展示如何使用 **FastAPI** 及其大多數功能。
+
+每個部分都是在前一部分的基礎上逐步建置的,但內容結構是按主題分開的,因此你可以直接跳到任何特定的部分,解決你具體的 API 需求。
+
+它也被設計成可作為未來的參考,讓你隨時回來查看所需的內容。
+
+## 運行程式碼
+
+所有程式碼區塊都可以直接複製和使用(它們實際上是經過測試的 Python 檔案)。
+
+要運行任何範例,請將程式碼複製到 `main.py` 檔案,並使用以下命令啟動 `fastapi dev`:
+
+
+
-!!! tip "提示"
+/// tip | 提示
- API 文档与所选的服务器进行交互。
+API 文档与所选的服务器进行交互。
+
+///
### 从 `root_path` 禁用自动服务器
如果不想让 **FastAPI** 包含使用 `root_path` 的自动服务器,则要使用参数 `root_path_in_servers=False`:
-```Python hl_lines="9"
-{!../../../docs_src/behind_a_proxy/tutorial004.py!}
-```
+{* ../../docs_src/behind_a_proxy/tutorial004.py hl[9] *}
这样,就不会在 OpenAPI 概图中包含服务器了。
diff --git a/docs/zh/docs/advanced/custom-response.md b/docs/zh/docs/advanced/custom-response.md
index 155ce2882..22a9b4b51 100644
--- a/docs/zh/docs/advanced/custom-response.md
+++ b/docs/zh/docs/advanced/custom-response.md
@@ -12,8 +12,11 @@
并且如果该 `Response` 有一个 JSON 媒体类型(`application/json`),比如使用 `JSONResponse` 或者 `UJSONResponse` 的时候,返回的数据将使用你在路径操作装饰器中声明的任何 Pydantic 的 `response_model` 自动转换(和过滤)。
-!!! note "说明"
- 如果你使用不带有任何媒体类型的响应类,FastAPI 认为你的响应没有任何内容,所以不会在生成的OpenAPI文档中记录响应格式。
+/// note | 说明
+
+如果你使用不带有任何媒体类型的响应类,FastAPI 认为你的响应没有任何内容,所以不会在生成的OpenAPI文档中记录响应格式。
+
+///
## 使用 `ORJSONResponse`
@@ -21,21 +24,23 @@
导入你想要使用的 `Response` 类(子类)然后在 *路径操作装饰器* 中声明它。
-```Python hl_lines="2 7"
-{!../../../docs_src/custom_response/tutorial001b.py!}
-```
+{* ../../docs_src/custom_response/tutorial001b.py hl[2,7] *}
-!!! info "提示"
- 参数 `response_class` 也会用来定义响应的「媒体类型」。
+/// info | 提示
- 在这个例子中,HTTP 头的 `Content-Type` 会被设置成 `application/json`。
+参数 `response_class` 也会用来定义响应的「媒体类型」。
- 并且在 OpenAPI 文档中也会这样记录。
+在这个例子中,HTTP 头的 `Content-Type` 会被设置成 `application/json`。
-!!! tip "小贴士"
- `ORJSONResponse` 目前只在 FastAPI 中可用,而在 Starlette 中不可用。
+并且在 OpenAPI 文档中也会这样记录。
+///
+/// tip | 小贴士
+
+`ORJSONResponse` 目前只在 FastAPI 中可用,而在 Starlette 中不可用。
+
+///
## HTML 响应
@@ -44,16 +49,17 @@
* 导入 `HTMLResponse`。
* 将 `HTMLResponse` 作为你的 *路径操作* 的 `response_class` 参数传入。
-```Python hl_lines="2 7"
-{!../../../docs_src/custom_response/tutorial002.py!}
-```
+{* ../../docs_src/custom_response/tutorial002.py hl[2,7] *}
-!!! info "提示"
- 参数 `response_class` 也会用来定义响应的「媒体类型」。
+/// info | 提示
- 在这个例子中,HTTP 头的 `Content-Type` 会被设置成 `text/html`。
+参数 `response_class` 也会用来定义响应的「媒体类型」。
- 并且在 OpenAPI 文档中也会这样记录。
+在这个例子中,HTTP 头的 `Content-Type` 会被设置成 `text/html`。
+
+并且在 OpenAPI 文档中也会这样记录。
+
+///
### 返回一个 `Response`
@@ -61,15 +67,19 @@
和上面一样的例子,返回一个 `HTMLResponse` 看起来可能是这样:
-```Python hl_lines="2 7 19"
-{!../../../docs_src/custom_response/tutorial003.py!}
-```
+{* ../../docs_src/custom_response/tutorial003.py hl[2,7,19] *}
-!!! warning "警告"
- *路径操作函数* 直接返回的 `Response` 不会被 OpenAPI 的文档记录(比如,`Content-Type` 不会被文档记录),并且在自动化交互文档中也是不可见的。
+/// warning | 警告
-!!! info "提示"
- 当然,实际的 `Content-Type` 头,状态码等等,将来自于你返回的 `Response` 对象。
+*路径操作函数* 直接返回的 `Response` 不会被 OpenAPI 的文档记录(比如,`Content-Type` 不会被文档记录),并且在自动化交互文档中也是不可见的。
+
+///
+
+/// info | 提示
+
+当然,实际的 `Content-Type` 头,状态码等等,将来自于你返回的 `Response` 对象。
+
+///
### OpenAPI 中的文档和重载 `Response`
@@ -81,9 +91,7 @@
比如像这样:
-```Python hl_lines="7 23 21"
-{!../../../docs_src/custom_response/tutorial004.py!}
-```
+{* ../../docs_src/custom_response/tutorial004.py hl[7,23,21] *}
在这个例子中,函数 `generate_html_response()` 已经生成并返回 `Response` 对象而不是在 `str` 中返回 HTML。
@@ -99,10 +107,13 @@
要记得你可以使用 `Response` 来返回任何其他东西,甚至创建一个自定义的子类。
-!!! note "技术细节"
- 你也可以使用 `from starlette.responses import HTMLResponse`。
+/// note | 技术细节
- **FastAPI** 提供了同 `fastapi.responses` 相同的 `starlette.responses` 只是为了方便开发者。但大多数可用的响应都直接来自 Starlette。
+你也可以使用 `from starlette.responses import HTMLResponse`。
+
+**FastAPI** 提供了同 `fastapi.responses` 相同的 `starlette.responses` 只是为了方便开发者。但大多数可用的响应都直接来自 Starlette。
+
+///
### `Response`
@@ -120,9 +131,7 @@
FastAPI(实际上是 Starlette)将自动包含 Content-Length 的头。它还将包含一个基于 media_type 的 Content-Type 头,并为文本类型附加一个字符集。
-```Python hl_lines="1 18"
-{!../../../docs_src/response_directly/tutorial002.py!}
-```
+{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
### `HTMLResponse`
@@ -132,9 +141,7 @@ FastAPI(实际上是 Starlette)将自动包含 Content-Length 的头。它
接受文本或字节并返回纯文本响应。
-```Python hl_lines="2 7 9"
-{!../../../docs_src/custom_response/tutorial005.py!}
-```
+{* ../../docs_src/custom_response/tutorial005.py hl[2,7,9] *}
### `JSONResponse`
@@ -151,31 +158,31 @@ FastAPI(实际上是 Starlette)将自动包含 Content-Length 的头。它
`UJSONResponse` 是一个使用 `ujson` 的可选 JSON 响应。
-!!! warning "警告"
- 在处理某些边缘情况时,`ujson` 不如 Python 的内置实现那么谨慎。
+/// warning | 警告
-```Python hl_lines="2 7"
-{!../../../docs_src/custom_response/tutorial001.py!}
-```
+在处理某些边缘情况时,`ujson` 不如 Python 的内置实现那么谨慎。
-!!! tip "小贴士"
- `ORJSONResponse` 可能是一个更快的选择。
+///
+
+{* ../../docs_src/custom_response/tutorial001.py hl[2,7] *}
+
+/// tip | 小贴士
+
+`ORJSONResponse` 可能是一个更快的选择。
+
+///
### `RedirectResponse`
返回 HTTP 重定向。默认情况下使用 307 状态代码(临时重定向)。
-```Python hl_lines="2 9"
-{!../../../docs_src/custom_response/tutorial006.py!}
-```
+{* ../../docs_src/custom_response/tutorial006.py hl[2,9] *}
### `StreamingResponse`
采用异步生成器或普通生成器/迭代器,然后流式传输响应主体。
-```Python hl_lines="2 14"
-{!../../../docs_src/custom_response/tutorial007.py!}
-```
+{* ../../docs_src/custom_response/tutorial007.py hl[2,14] *}
#### 对类似文件的对象使用 `StreamingResponse`
@@ -183,12 +190,13 @@ FastAPI(实际上是 Starlette)将自动包含 Content-Length 的头。它
包括许多与云存储,视频处理等交互的库。
-```Python hl_lines="2 10-12 14"
-{!../../../docs_src/custom_response/tutorial008.py!}
-```
+{* ../../docs_src/custom_response/tutorial008.py hl[2,10:12,14] *}
-!!! tip "小贴士"
- 注意在这里,因为我们使用的是不支持 `async` 和 `await` 的标准 `open()`,我们使用普通的 `def` 声明了路径操作。
+/// tip | 小贴士
+
+注意在这里,因为我们使用的是不支持 `async` 和 `await` 的标准 `open()`,我们使用普通的 `def` 声明了路径操作。
+
+///
### `FileResponse`
@@ -203,9 +211,7 @@ FastAPI(实际上是 Starlette)将自动包含 Content-Length 的头。它
文件响应将包含适当的 `Content-Length`,`Last-Modified` 和 `ETag` 的响应头。
-```Python hl_lines="2 10"
-{!../../../docs_src/custom_response/tutorial009.py!}
-```
+{* ../../docs_src/custom_response/tutorial009.py hl[2,10] *}
## 额外文档
diff --git a/docs/zh/docs/advanced/dataclasses.md b/docs/zh/docs/advanced/dataclasses.md
index 5a93877cc..c74ce65c3 100644
--- a/docs/zh/docs/advanced/dataclasses.md
+++ b/docs/zh/docs/advanced/dataclasses.md
@@ -4,9 +4,7 @@ FastAPI 基于 **Pydantic** 构建,前文已经介绍过如何使用 Pydantic
但 FastAPI 还可以使用数据类(`dataclasses`):
-```Python hl_lines="1 7-12 19-20"
-{!../../../docs_src/dataclasses/tutorial001.py!}
-```
+{* ../../docs_src/dataclasses/tutorial001.py hl[1,7:12,19:20] *}
这还是借助于 **Pydantic** 及其内置的 `dataclasses`。
@@ -20,21 +18,21 @@ FastAPI 基于 **Pydantic** 构建,前文已经介绍过如何使用 Pydantic
数据类的和运作方式与 Pydantic 模型相同。实际上,它的底层使用的也是 Pydantic。
-!!! info "说明"
+/// info | 说明
- 注意,数据类不支持 Pydantic 模型的所有功能。
+注意,数据类不支持 Pydantic 模型的所有功能。
- 因此,开发时仍需要使用 Pydantic 模型。
+因此,开发时仍需要使用 Pydantic 模型。
- 但如果数据类很多,这一技巧能给 FastAPI 开发 Web API 增添不少助力。🤓
+但如果数据类很多,这一技巧能给 FastAPI 开发 Web API 增添不少助力。🤓
+
+///
## `response_model` 使用数据类
在 `response_model` 参数中使用 `dataclasses`:
-```Python hl_lines="1 7-13 19"
-{!../../../docs_src/dataclasses/tutorial002.py!}
-```
+{* ../../docs_src/dataclasses/tutorial002.py hl[1,7:13,19] *}
本例把数据类自动转换为 Pydantic 数据类。
@@ -51,7 +49,7 @@ API 文档中也会显示相关概图:
本例把标准的 `dataclasses` 直接替换为 `pydantic.dataclasses`:
```{ .python .annotate hl_lines="1 5 8-11 14-17 23-25 28" }
-{!../../../docs_src/dataclasses/tutorial003.py!}
+{!../../docs_src/dataclasses/tutorial003.py!}
```
1. 本例依然要从标准的 `dataclasses` 中导入 `field`;
diff --git a/docs/zh/docs/advanced/events.md b/docs/zh/docs/advanced/events.md
index 8e5fa7d12..5ade0f0ff 100644
--- a/docs/zh/docs/advanced/events.md
+++ b/docs/zh/docs/advanced/events.md
@@ -1,20 +1,118 @@
-# 事件:启动 - 关闭
+# 生命周期事件
-**FastAPI** 支持定义在应用启动前,或应用关闭后执行的事件处理器(函数)。
+你可以定义在应用**启动**前执行的逻辑(代码)。这意味着在应用**开始接收请求**之前,这些代码只会被执行**一次**。
+
+同样地,你可以定义在应用**关闭**时应执行的逻辑。在这种情况下,这段代码将在**处理可能的多次请求后**执行**一次**。
+
+因为这段代码在应用开始接收请求**之前**执行,也会在处理可能的若干请求**之后**执行,它覆盖了整个应用程序的**生命周期**("生命周期"这个词很重要😉)。
+
+这对于设置你需要在整个应用中使用的**资源**非常有用,这些资源在请求之间**共享**,你可能需要在之后进行**释放**。例如,数据库连接池,或加载一个共享的机器学习模型。
+
+## 用例
+
+让我们从一个示例用例开始,看看如何解决它。
+
+假设你有几个**机器学习的模型**,你想要用它们来处理请求。
+
+相同的模型在请求之间是共享的,因此并非每个请求或每个用户各自拥有一个模型。
+
+假设加载模型可能**需要相当长的时间**,因为它必须从**磁盘**读取大量数据。因此你不希望每个请求都加载它。
+
+你可以在模块/文件的顶部加载它,但这也意味着即使你只是在运行一个简单的自动化测试,它也会**加载模型**,这样测试将**变慢**,因为它必须在能够独立运行代码的其他部分之前等待模型加载完成。
+
+这就是我们要解决的问题——在处理请求前加载模型,但只是在应用开始接收请求前,而不是代码执行时。
+
+## 生命周期 lifespan
+
+你可以使用`FastAPI()`应用的`lifespan`参数和一个上下文管理器(稍后我将为你展示)来定义**启动**和**关闭**的逻辑。
+
+让我们从一个例子开始,然后详细介绍。
+
+我们使用`yield`创建了一个异步函数`lifespan()`像这样:
+
+```Python hl_lines="16 19"
+{!../../docs_src/events/tutorial003.py!}
+```
+
+在这里,我们在 `yield` 之前将(虚拟的)模型函数放入机器学习模型的字典中,以此模拟加载模型的耗时**启动**操作。这段代码将在应用程序**开始处理请求之前**执行,即**启动**期间。
+
+然后,在 `yield` 之后,我们卸载模型。这段代码将会在应用程序**完成处理请求后**执行,即在**关闭**之前。这可以释放诸如内存或 GPU 之类的资源。
+
+/// tip | 提示
+
+**关闭**事件只会在你停止应用时触发。
+
+可能你需要启动一个新版本,或者你只是你厌倦了运行它。 🤷
+
+///
+
+## 生命周期函数
+
+首先要注意的是,我们定义了一个带有 `yield` 的异步函数。这与带有 `yield` 的依赖项非常相似。
+
+```Python hl_lines="14-19"
+{!../../docs_src/events/tutorial003.py!}
+```
+
+这个函数在 `yield`之前的部分,会在应用启动前执行。
+
+剩下的部分在 `yield` 之后,会在应用完成后执行。
+
+## 异步上下文管理器
+
+如你所见,这个函数有一个装饰器 `@asynccontextmanager` 。
+
+它将函数转化为所谓的“**异步上下文管理器**”。
+
+```Python hl_lines="1 13"
+{!../../docs_src/events/tutorial003.py!}
+```
+
+在 Python 中, **上下文管理器**是一个你可以在 `with` 语句中使用的东西,例如,`open()` 可以作为上下文管理器使用。
+
+```Python
+with open("file.txt") as file:
+ file.read()
+```
+
+Python 的最近几个版本也有了一个**异步上下文管理器**,你可以通过 `async with` 来使用:
+
+```Python
+async with lifespan(app):
+ await do_stuff()
+```
+
+你可以像上面一样创建了一个上下文管理器或者异步上下文管理器,它的作用是在进入 `with` 块时,执行 `yield` 之前的代码,并且在离开 `with` 块时,执行 `yield` 后面的代码。
+
+但在我们上面的例子里,我们并不是直接使用,而是传递给 FastAPI 来供其使用。
+
+`FastAPI()` 的 `lifespan` 参数接受一个**异步上下文管理器**,所以我们可以把我们新定义的上下文管理器 `lifespan` 传给它。
+
+```Python hl_lines="22"
+{!../../docs_src/events/tutorial003.py!}
+```
+
+## 替代事件(弃用)
+
+/// warning | 警告
+
+配置**启动**和**关闭**事件的推荐方法是使用 `FastAPI()` 应用的 `lifespan` 参数,如前所示。如果你提供了一个 `lifespan` 参数,启动(`startup`)和关闭(`shutdown`)事件处理器将不再生效。要么使用 `lifespan`,要么配置所有事件,两者不能共用。
+
+你可以跳过这一部分。
+
+///
+
+有一种替代方法可以定义在**启动**和**关闭**期间执行的逻辑。
+
+**FastAPI** 支持定义在应用启动前,或应用关闭时执行的事件处理器(函数)。
事件函数既可以声明为异步函数(`async def`),也可以声明为普通函数(`def`)。
-!!! warning "警告"
-
- **FastAPI** 只执行主应用中的事件处理器,不执行[子应用 - 挂载](sub-applications.md){.internal-link target=_blank}中的事件处理器。
-
-## `startup` 事件
+### `startup` 事件
使用 `startup` 事件声明 `app` 启动前运行的函数:
-```Python hl_lines="8"
-{!../../../docs_src/events/tutorial001.py!}
-```
+{* ../../docs_src/events/tutorial001.py hl[8] *}
本例中,`startup` 事件处理器函数为项目数据库(只是**字典**)提供了一些初始值。
@@ -22,30 +120,54 @@
只有所有 `startup` 事件处理器运行完毕,**FastAPI** 应用才开始接收请求。
-## `shutdown` 事件
+### `shutdown` 事件
使用 `shutdown` 事件声明 `app` 关闭时运行的函数:
-```Python hl_lines="6"
-{!../../../docs_src/events/tutorial002.py!}
-```
+{* ../../docs_src/events/tutorial002.py hl[6] *}
此处,`shutdown` 事件处理器函数在 `log.txt` 中写入一行文本 `Application shutdown`。
-!!! info "说明"
+/// info | 说明
- `open()` 函数中,`mode="a"` 指的是**追加**。因此这行文本会添加在文件已有内容之后,不会覆盖之前的内容。
+`open()` 函数中,`mode="a"` 指的是**追加**。因此这行文本会添加在文件已有内容之后,不会覆盖之前的内容。
-!!! tip "提示"
+///
- 注意,本例使用 Python `open()` 标准函数与文件交互。
+/// tip | 提示
- 这个函数执行 I/O(输入/输出)操作,需要等待内容写进磁盘。
+注意,本例使用 Python `open()` 标准函数与文件交互。
- 但 `open()` 函数不支持使用 `async` 与 `await`。
+这个函数执行 I/O(输入/输出)操作,需要等待内容写进磁盘。
- 因此,声明事件处理函数要使用 `def`,不能使用 `asnyc def`。
+但 `open()` 函数不支持使用 `async` 与 `await`。
-!!! info "说明"
+因此,声明事件处理函数要使用 `def`,不能使用 `asnyc def`。
- 有关事件处理器的详情,请参阅 Starlette 官档 - 事件。
+///
+
+### `startup` 和 `shutdown` 一起使用
+
+启动和关闭的逻辑很可能是连接在一起的,你可能希望启动某个东西然后结束它,获取一个资源然后释放它等等。
+
+在不共享逻辑或变量的不同函数中处理这些逻辑比较困难,因为你需要在全局变量中存储值或使用类似的方式。
+
+因此,推荐使用 `lifespan` 。
+
+## 技术细节
+
+只是为好奇者提供的技术细节。🤓
+
+在底层,这部分是生命周期协议的一部分,参见 ASGI 技术规范,定义了称为启动(`startup`)和关闭(`shutdown`)的事件。
+
+/// info | 说明
+
+有关事件处理器的详情,请参阅 Starlette 官档 - 事件。
+
+包括如何处理生命周期状态,这可以用于程序的其他部分。
+
+///
+
+## 子应用
+
+🚨 **FastAPI** 只会触发主应用中的生命周期事件,不包括[子应用 - 挂载](sub-applications.md){.internal-link target=_blank}中的。
diff --git a/docs/zh/docs/advanced/generate-clients.md b/docs/zh/docs/advanced/generate-clients.md
index c4ffcb46c..bcb9ba2bf 100644
--- a/docs/zh/docs/advanced/generate-clients.md
+++ b/docs/zh/docs/advanced/generate-clients.md
@@ -16,17 +16,7 @@
让我们从一个简单的 FastAPI 应用开始:
-=== "Python 3.9+"
-
- ```Python hl_lines="7-9 12-13 16-17 21"
- {!> ../../../docs_src/generate_clients/tutorial001_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9-11 14-15 18 19 23"
- {!> ../../../docs_src/generate_clients/tutorial001.py!}
- ```
+{* ../../docs_src/generate_clients/tutorial001_py39.py hl[7:9,12:13,16:17,21] *}
请注意,*路径操作* 定义了他们所用于请求数据和回应数据的模型,所使用的模型是`Item` 和 `ResponseMessage`。
@@ -111,8 +101,11 @@ frontend-app@1.0.0 generate-client /home/user/code/frontend-app
-!!! tip
- 请注意, `name` 和 `price` 的自动补全,是通过其在`Item`模型(FastAPI)中的定义实现的。
+/// tip
+
+请注意, `name` 和 `price` 的自动补全,是通过其在`Item`模型(FastAPI)中的定义实现的。
+
+///
如果发送的数据字段不符,你也会看到编辑器的错误提示:
@@ -128,17 +121,7 @@ frontend-app@1.0.0 generate-client /home/user/code/frontend-app
例如,您可以有一个用 `items` 的部分和另一个用于 `users` 的部分,它们可以用标签来分隔:
-=== "Python 3.9+"
-
- ```Python hl_lines="21 26 34"
- {!> ../../../docs_src/generate_clients/tutorial002_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="23 28 36"
- {!> ../../../docs_src/generate_clients/tutorial002.py!}
- ```
+{* ../../docs_src/generate_clients/tutorial002_py39.py hl[21,26,34] *}
### 生成带有标签的 TypeScript 客户端
@@ -185,17 +168,7 @@ FastAPI为每个*路径操作*使用一个**唯一ID**,它用于**操作ID**
然后,你可以将这个自定义函数作为 `generate_unique_id_function` 参数传递给 **FastAPI**:
-=== "Python 3.9+"
-
- ```Python hl_lines="6-7 10"
- {!> ../../../docs_src/generate_clients/tutorial003_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="8-9 12"
- {!> ../../../docs_src/generate_clients/tutorial003.py!}
- ```
+{* ../../docs_src/generate_clients/tutorial003_py39.py hl[6:7,10] *}
### 使用自定义操作ID生成TypeScript客户端
@@ -217,9 +190,7 @@ FastAPI为每个*路径操作*使用一个**唯一ID**,它用于**操作ID**
我们可以将 OpenAPI JSON 下载到一个名为`openapi.json`的文件中,然后使用以下脚本**删除此前缀的标签**:
-```Python
-{!../../../docs_src/generate_clients/tutorial004.py!}
-```
+{* ../../docs_src/generate_clients/tutorial004.py *}
通过这样做,操作ID将从类似于 `items-get_items` 的名称重命名为 `get_items` ,这样客户端生成器就可以生成更简洁的方法名称。
diff --git a/docs/zh/docs/advanced/index.md b/docs/zh/docs/advanced/index.md
index e39eed805..6525802fc 100644
--- a/docs/zh/docs/advanced/index.md
+++ b/docs/zh/docs/advanced/index.md
@@ -6,10 +6,13 @@
你会在接下来的章节中了解到其他的选项、配置以及额外的特性。
-!!! tip
- 接下来的章节**并不一定是**「高级的」。
+/// tip
- 而且对于你的使用场景来说,解决方案很可能就在其中。
+接下来的章节**并不一定是**「高级的」。
+
+而且对于你的使用场景来说,解决方案很可能就在其中。
+
+///
## 先阅读教程
diff --git a/docs/zh/docs/advanced/middleware.md b/docs/zh/docs/advanced/middleware.md
index 06232fe17..c7b15b929 100644
--- a/docs/zh/docs/advanced/middleware.md
+++ b/docs/zh/docs/advanced/middleware.md
@@ -43,11 +43,13 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow")
**FastAPI** 为常见用例提供了一些中间件,下面介绍怎么使用这些中间件。
-!!! note "技术细节"
+/// note | 技术细节
- 以下几个示例中也可以使用 `from starlette.middleware.something import SomethingMiddleware`。
+以下几个示例中也可以使用 `from starlette.middleware.something import SomethingMiddleware`。
- **FastAPI** 在 `fastapi.middleware` 中提供的中间件只是为了方便开发者使用,但绝大多数可用的中间件都直接继承自 Starlette。
+**FastAPI** 在 `fastapi.middleware` 中提供的中间件只是为了方便开发者使用,但绝大多数可用的中间件都直接继承自 Starlette。
+
+///
## `HTTPSRedirectMiddleware`
@@ -55,17 +57,13 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow")
任何传向 `http` 或 `ws` 的请求都会被重定向至安全方案。
-```Python hl_lines="2 6"
-{!../../../docs_src/advanced_middleware/tutorial001.py!}
-```
+{* ../../docs_src/advanced_middleware/tutorial001.py hl[2,6] *}
## `TrustedHostMiddleware`
强制所有传入请求都必须正确设置 `Host` 请求头,以防 HTTP 主机头攻击。
-```Python hl_lines="2 6-8"
-{!../../../docs_src/advanced_middleware/tutorial002.py!}
-```
+{* ../../docs_src/advanced_middleware/tutorial002.py hl[2,6:8] *}
支持以下参数:
@@ -79,9 +77,7 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow")
中间件会处理标准响应与流响应。
-```Python hl_lines="2 6"
-{!../../../docs_src/advanced_middleware/tutorial003.py!}
-```
+{* ../../docs_src/advanced_middleware/tutorial003.py hl[2,6] *}
支持以下参数:
@@ -93,7 +89,6 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow")
例如:
-* Sentry
* Uvicorn 的 `ProxyHeadersMiddleware`
* MessagePack
diff --git a/docs/zh/docs/advanced/openapi-callbacks.md b/docs/zh/docs/advanced/openapi-callbacks.md
index e2dadbfb0..f021eb10a 100644
--- a/docs/zh/docs/advanced/openapi-callbacks.md
+++ b/docs/zh/docs/advanced/openapi-callbacks.md
@@ -31,13 +31,13 @@ API 的用户 (外部开发者)要在您的 API 内使用 POST 请求创建
这部分代码很常规,您对绝大多数代码应该都比较熟悉了:
-```Python hl_lines="10-14 37-54"
-{!../../../docs_src/openapi_callbacks/tutorial001.py!}
-```
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[10:14,37:54] *}
-!!! tip "提示"
+/// tip | 提示
- `callback_url` 查询参数使用 Pydantic 的 URL 类型。
+`callback_url` 查询参数使用 Pydantic 的 URL 类型。
+
+///
此处唯一比较新的内容是*路径操作装饰器*中的 `callbacks=invoices_callback_router.routes` 参数,下文介绍。
@@ -62,11 +62,13 @@ requests.post(callback_url, json={"description": "Invoice paid", "paid": True})
本例没有实现回调本身(只是一行代码),只有文档部分。
-!!! tip "提示"
+/// tip | 提示
- 实际的回调只是 HTTP 请求。
+实际的回调只是 HTTP 请求。
- 实现回调时,要使用 HTTPX 或 Requests。
+实现回调时,要使用 HTTPX 或 Requests。
+
+///
## 编写回调文档代码
@@ -76,19 +78,19 @@ requests.post(callback_url, json={"description": "Invoice paid", "paid": True})
我们要使用与存档*外部 API* 相同的知识……通过创建外部 API 要实现的*路径操作*(您的 API 要调用的)。
-!!! tip "提示"
+/// tip | 提示
- 编写存档回调的代码时,假设您是*外部开发者*可能会用的上。并且您当前正在实现的是*外部 API*,不是*您自己的 API*。
+编写存档回调的代码时,假设您是*外部开发者*可能会用的上。并且您当前正在实现的是*外部 API*,不是*您自己的 API*。
- 临时改变(为外部开发者的)视角能让您更清楚该如何放置*外部 API* 响应和请求体的参数与 Pydantic 模型等。
+临时改变(为外部开发者的)视角能让您更清楚该如何放置*外部 API* 响应和请求体的参数与 Pydantic 模型等。
+
+///
### 创建回调的 `APIRouter`
首先,新建包含一些用于回调的 `APIRouter`。
-```Python hl_lines="5 26"
-{!../../../docs_src/openapi_callbacks/tutorial001.py!}
-```
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[5,26] *}
### 创建回调*路径操作*
@@ -99,9 +101,7 @@ requests.post(callback_url, json={"description": "Invoice paid", "paid": True})
* 声明要接收的请求体,例如,`body: InvoiceEvent`
* 还要声明要返回的响应,例如,`response_model=InvoiceEventReceived`
-```Python hl_lines="17-19 22-23 29-33"
-{!../../../docs_src/openapi_callbacks/tutorial001.py!}
-```
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[17:19,22:23,29:33] *}
回调*路径操作*与常规*路径操作*有两点主要区别:
@@ -157,9 +157,11 @@ JSON 请求体包含如下内容:
}
```
-!!! tip "提示"
+/// tip | 提示
- 注意,回调 URL包含 `callback_url` (`https://www.external.org/events`)中的查询参数,还有 JSON 请求体内部的发票 ID(`2expen51ve`)。
+注意,回调 URL包含 `callback_url` (`https://www.external.org/events`)中的查询参数,还有 JSON 请求体内部的发票 ID(`2expen51ve`)。
+
+///
### 添加回调路由
@@ -167,13 +169,13 @@ JSON 请求体包含如下内容:
现在使用 API *路径操作装饰器*的参数 `callbacks`,从回调路由传递属性 `.routes`(实际上只是路由/路径操作的**列表**):
-```Python hl_lines="36"
-{!../../../docs_src/openapi_callbacks/tutorial001.py!}
-```
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[36] *}
-!!! tip "提示"
+/// tip | 提示
- 注意,不能把路由本身(`invoices_callback_router`)传递给 `callback=`,要传递 `invoices_callback_router.routes` 中的 `.routes` 属性。
+注意,不能把路由本身(`invoices_callback_router`)传递给 `callback=`,要传递 `invoices_callback_router.routes` 中的 `.routes` 属性。
+
+///
### 查看文档
diff --git a/docs/zh/docs/advanced/openapi-webhooks.md b/docs/zh/docs/advanced/openapi-webhooks.md
new file mode 100644
index 000000000..92ae8db15
--- /dev/null
+++ b/docs/zh/docs/advanced/openapi-webhooks.md
@@ -0,0 +1,55 @@
+# OpenAPI 网络钩子
+
+有些情况下,您可能想告诉您的 API **用户**,您的应用程序可以携带一些数据调用*他们的*应用程序(给它们发送请求),通常是为了**通知**某种**事件**。
+
+这意味着,除了您的用户向您的 API 发送请求的一般情况,**您的 API**(或您的应用)也可以向**他们的系统**(他们的 API、他们的应用)**发送请求**。
+
+这通常被称为**网络钩子**(Webhook)。
+
+## 使用网络钩子的步骤
+
+通常的过程是**您**在代码中**定义**要发送的消息,即**请求的主体**。
+
+您还需要以某种方式定义您的应用程序将在**何时**发送这些请求或事件。
+
+**用户**会以某种方式(例如在某个网页仪表板上)定义您的应用程序发送这些请求应该使用的 **URL**。
+
+所有关于注册网络钩子的 URL 的**逻辑**以及发送这些请求的实际代码都由您决定。您可以在**自己的代码**中以任何想要的方式来编写它。
+
+## 使用 `FastAPI` 和 OpenAPI 文档化网络钩子
+
+使用 **FastAPI**,您可以利用 OpenAPI 来自定义这些网络钩子的名称、您的应用可以发送的 HTTP 操作类型(例如 `POST`、`PUT` 等)以及您的应用将发送的**请求体**。
+
+这能让您的用户更轻松地**实现他们的 API** 来接收您的**网络钩子**请求,他们甚至可能能够自动生成一些自己的 API 代码。
+
+/// info
+
+网络钩子在 OpenAPI 3.1.0 及以上版本中可用,FastAPI `0.99.0` 及以上版本支持。
+
+///
+
+## 带有网络钩子的应用程序
+
+当您创建一个 **FastAPI** 应用程序时,有一个 `webhooks` 属性可以用来定义网络钩子,方式与您定义*路径操作*的时候相同,例如使用 `@app.webhooks.post()` 。
+
+{* ../../docs_src/openapi_webhooks/tutorial001.py hl[9:13,36:53] *}
+
+您定义的网络钩子将被包含在 `OpenAPI` 的架构中,并出现在自动生成的**文档 UI** 中。
+
+/// info
+
+`app.webhooks` 对象实际上只是一个 `APIRouter` ,与您在使用多个文件来构建应用程序时所使用的类型相同。
+
+///
+
+请注意,使用网络钩子时,您实际上并没有声明一个*路径*(比如 `/items/` ),您传递的文本只是这个网络钩子的**标识符**(事件的名称)。例如在 `@app.webhooks.post("new-subscription")` 中,网络钩子的名称是 `new-subscription` 。
+
+这是因为我们预计**您的用户**会以其他方式(例如通过网页仪表板)来定义他们希望接收网络钩子的请求的实际 **URL 路径**。
+
+### 查看文档
+
+现在您可以启动您的应用程序并访问 http://127.0.0.1:8000/docs.
+
+您会看到您的文档不仅有正常的*路径操作*显示,现在还多了一些**网络钩子**:
+
+
diff --git a/docs/zh/docs/advanced/path-operation-advanced-configuration.md b/docs/zh/docs/advanced/path-operation-advanced-configuration.md
index 7da9f251e..12600eddb 100644
--- a/docs/zh/docs/advanced/path-operation-advanced-configuration.md
+++ b/docs/zh/docs/advanced/path-operation-advanced-configuration.md
@@ -2,16 +2,17 @@
## OpenAPI 的 operationId
-!!! warning
- 如果你并非 OpenAPI 的「专家」,你可能不需要这部分内容。
+/// warning
+
+如果你并非 OpenAPI 的「专家」,你可能不需要这部分内容。
+
+///
你可以在路径操作中通过参数 `operation_id` 设置要使用的 OpenAPI `operationId`。
务必确保每个操作路径的 `operation_id` 都是唯一的。
-```Python hl_lines="6"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial001.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial001.py hl[6] *}
### 使用 *路径操作函数* 的函数名作为 operationId
@@ -19,25 +20,27 @@
你应该在添加了所有 *路径操作* 之后执行此操作。
-```Python hl_lines="2 12 13 14 15 16 17 18 19 20 21 24"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial002.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial002.py hl[2,12,13,14,15,16,17,18,19,20,21,24] *}
-!!! tip
- 如果你手动调用 `app.openapi()`,你应该在此之前更新 `operationId`。
+/// tip
-!!! warning
- 如果你这样做,务必确保你的每个 *路径操作函数* 的名字唯一。
+如果你手动调用 `app.openapi()`,你应该在此之前更新 `operationId`。
- 即使它们在不同的模块中(Python 文件)。
+///
+
+/// warning
+
+如果你这样做,务必确保你的每个 *路径操作函数* 的名字唯一。
+
+即使它们在不同的模块中(Python 文件)。
+
+///
## 从 OpenAPI 中排除
使用参数 `include_in_schema` 并将其设置为 `False` ,来从生成的 OpenAPI 方案中排除一个 *路径操作*(这样一来,就从自动化文档系统中排除掉了)。
-```Python hl_lines="6"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial003.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial003.py hl[6] *}
## docstring 的高级描述
@@ -48,6 +51,4 @@
剩余部分不会出现在文档中,但是其他工具(比如 Sphinx)可以使用剩余部分。
-```Python hl_lines="19 20 21 22 23 24 25 26 27 28 29"
-{!../../../docs_src/path_operation_advanced_configuration/tutorial004.py!}
-```
+{* ../../docs_src/path_operation_advanced_configuration/tutorial004.py hl[19,20,21,22,23,24,25,26,27,28,29] *}
diff --git a/docs/zh/docs/advanced/response-change-status-code.md b/docs/zh/docs/advanced/response-change-status-code.md
index a289cf201..cc1f2a73e 100644
--- a/docs/zh/docs/advanced/response-change-status-code.md
+++ b/docs/zh/docs/advanced/response-change-status-code.md
@@ -20,9 +20,7 @@
然后你可以在这个*临时*响应对象中设置`status_code`。
-```Python hl_lines="1 9 12"
-{!../../../docs_src/response_change_status_code/tutorial001.py!}
-```
+{* ../../docs_src/response_change_status_code/tutorial001.py hl[1,9,12] *}
然后你可以像平常一样返回任何你需要的对象(例如一个`dict`或者一个数据库模型)。如果你声明了一个`response_model`,它仍然会被用来过滤和转换你返回的对象。
diff --git a/docs/zh/docs/advanced/response-cookies.md b/docs/zh/docs/advanced/response-cookies.md
index 3e53c5319..d4b93d003 100644
--- a/docs/zh/docs/advanced/response-cookies.md
+++ b/docs/zh/docs/advanced/response-cookies.md
@@ -4,9 +4,7 @@
你可以在 *路径函数* 中定义一个类型为 `Response`的参数,这样你就可以在这个临时响应对象中设置cookie了。
-```Python hl_lines="1 8-9"
-{!../../../docs_src/response_cookies/tutorial002.py!}
-```
+{* ../../docs_src/response_cookies/tutorial002.py hl[1,8:9] *}
而且你还可以根据你的需要响应不同的对象,比如常用的 `dict`,数据库model等。
@@ -24,24 +22,28 @@
然后设置Cookies,并返回:
-```Python hl_lines="10-12"
-{!../../../docs_src/response_cookies/tutorial001.py!}
-```
+{* ../../docs_src/response_cookies/tutorial001.py hl[10:12] *}
-!!! tip
- 需要注意,如果你直接反馈一个response对象,而不是使用`Response`入参,FastAPI则会直接反馈你封装的response对象。
+/// tip
- 所以你需要确保你响应数据类型的正确性,如:你可以使用`JSONResponse`来兼容JSON的场景。
+需要注意,如果你直接反馈一个response对象,而不是使用`Response`入参,FastAPI则会直接反馈你封装的response对象。
- 同时,你也应当仅反馈通过`response_model`过滤过的数据。
+所以你需要确保你响应数据类型的正确性,如:你可以使用`JSONResponse`来兼容JSON的场景。
+
+同时,你也应当仅反馈通过`response_model`过滤过的数据。
+
+///
### 更多信息
-!!! note "技术细节"
- 你也可以使用`from starlette.responses import Response` 或者 `from starlette.responses import JSONResponse`。
+/// note | 技术细节
- 为了方便开发者,**FastAPI** 封装了相同数据类型,如`starlette.responses` 和 `fastapi.responses`。不过大部分response对象都是直接引用自Starlette。
+你也可以使用`from starlette.responses import Response` 或者 `from starlette.responses import JSONResponse`。
- 因为`Response`对象可以非常便捷的设置headers和cookies,所以 **FastAPI** 同时也封装了`fastapi.Response`。
+为了方便开发者,**FastAPI** 封装了相同数据类型,如`starlette.responses` 和 `fastapi.responses`。不过大部分response对象都是直接引用自Starlette。
+
+因为`Response`对象可以非常便捷的设置headers和cookies,所以 **FastAPI** 同时也封装了`fastapi.Response`。
+
+///
如果你想查看所有可用的参数和选项,可以参考 Starlette帮助文档
diff --git a/docs/zh/docs/advanced/response-directly.md b/docs/zh/docs/advanced/response-directly.md
index 797a878eb..4d9cd53f2 100644
--- a/docs/zh/docs/advanced/response-directly.md
+++ b/docs/zh/docs/advanced/response-directly.md
@@ -14,8 +14,11 @@
事实上,你可以返回任意 `Response` 或者任意 `Response` 的子类。
-!!! tip "小贴士"
- `JSONResponse` 本身是一个 `Response` 的子类。
+/// tip | 小贴士
+
+`JSONResponse` 本身是一个 `Response` 的子类。
+
+///
当你返回一个 `Response` 时,**FastAPI** 会直接传递它。
@@ -32,14 +35,15 @@
对于这些情况,在将数据传递给响应之前,你可以使用 `jsonable_encoder` 来转换你的数据。
-```Python hl_lines="4 6 20 21"
-{!../../../docs_src/response_directly/tutorial001.py!}
-```
+{* ../../docs_src/response_directly/tutorial001.py hl[4,6,20,21] *}
-!!! note "技术细节"
- 你也可以使用 `from starlette.responses import JSONResponse`。
+/// note | 技术细节
- 出于方便,**FastAPI** 会提供与 `starlette.responses` 相同的 `fastapi.responses` 给开发者。但是大多数可用的响应都直接来自 Starlette。
+你也可以使用 `from starlette.responses import JSONResponse`。
+
+出于方便,**FastAPI** 会提供与 `starlette.responses` 相同的 `fastapi.responses` 给开发者。但是大多数可用的响应都直接来自 Starlette。
+
+///
## 返回自定义 `Response`
@@ -51,9 +55,7 @@
你可以把你的 XML 内容放到一个字符串中,放到一个 `Response` 中,然后返回。
-```Python hl_lines="1 18"
-{!../../../docs_src/response_directly/tutorial002.py!}
-```
+{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
## 说明
diff --git a/docs/zh/docs/advanced/response-headers.md b/docs/zh/docs/advanced/response-headers.md
index 229efffcb..fe2cb0da8 100644
--- a/docs/zh/docs/advanced/response-headers.md
+++ b/docs/zh/docs/advanced/response-headers.md
@@ -5,9 +5,7 @@
你可以在你的*路径操作函数*中声明一个`Response`类型的参数(就像你可以为cookies做的那样)。
然后你可以在这个*临时*响应对象中设置头部。
-```Python hl_lines="1 7-8"
-{!../../../docs_src/response_headers/tutorial002.py!}
-```
+{* ../../docs_src/response_headers/tutorial002.py hl[1,7:8] *}
然后你可以像平常一样返回任何你需要的对象(例如一个`dict`或者一个数据库模型)。如果你声明了一个`response_model`,它仍然会被用来过滤和转换你返回的对象。
@@ -20,17 +18,19 @@
你也可以在直接返回`Response`时添加头部。
按照[直接返回响应](response-directly.md){.internal-link target=_blank}中所述创建响应,并将头部作为附加参数传递:
-```Python hl_lines="10-12"
-{!../../../docs_src/response_headers/tutorial001.py!}
-```
+
+{* ../../docs_src/response_headers/tutorial001.py hl[10:12] *}
-!!! note "技术细节"
- 你也可以使用`from starlette.responses import Response`或`from starlette.responses import JSONResponse`。
+/// note | 技术细节
- **FastAPI**提供了与`fastapi.responses`相同的`starlette.responses`,只是为了方便开发者。但是,大多数可用的响应都直接来自Starlette。
+你也可以使用`from starlette.responses import Response`或`from starlette.responses import JSONResponse`。
- 由于`Response`经常用于设置头部和cookies,因此**FastAPI**还在`fastapi.Response`中提供了它。
+**FastAPI**提供了与`fastapi.responses`相同的`starlette.responses`,只是为了方便开发者。但是,大多数可用的响应都直接来自Starlette。
+
+由于`Response`经常用于设置头部和cookies,因此**FastAPI**还在`fastapi.Response`中提供了它。
+
+///
## 自定义头部
diff --git a/docs/zh/docs/advanced/security/http-basic-auth.md b/docs/zh/docs/advanced/security/http-basic-auth.md
index ab8961e7c..599429f9d 100644
--- a/docs/zh/docs/advanced/security/http-basic-auth.md
+++ b/docs/zh/docs/advanced/security/http-basic-auth.md
@@ -20,26 +20,7 @@ HTTP 基础授权让浏览器显示内置的用户名与密码提示。
* 返回类型为 `HTTPBasicCredentials` 的对象:
* 包含发送的 `username` 与 `password`
-=== "Python 3.9+"
-
- ```Python hl_lines="4 8 12"
- {!> ../../../docs_src/security/tutorial006_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="2 7 11"
- {!> ../../../docs_src/security/tutorial006_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
-
- ```Python hl_lines="2 6 10"
- {!> ../../../docs_src/security/tutorial006.py!}
- ```
+{* ../../docs_src/security/tutorial006_an_py39.py hl[4,8,12] *}
第一次打开 URL(或在 API 文档中点击 **Execute** 按钮)时,浏览器要求输入用户名与密码:
@@ -59,26 +40,8 @@ HTTP 基础授权让浏览器显示内置的用户名与密码提示。
然后我们可以使用 `secrets.compare_digest()` 来确保 `credentials.username` 是 `"stanleyjobson"`,且 `credentials.password` 是`"swordfish"`。
-=== "Python 3.9+"
+{* ../../docs_src/security/tutorial007_an_py39.py hl[1,12:24] *}
- ```Python hl_lines="1 12-24"
- {!> ../../../docs_src/security/tutorial007_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="1 12-24"
- {!> ../../../docs_src/security/tutorial007_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
-
- ```Python hl_lines="1 11-21"
- {!> ../../../docs_src/security/tutorial007.py!}
- ```
这类似于:
```Python
@@ -141,23 +104,4 @@ if "stanleyjobsox" == "stanleyjobson" and "love123" == "swordfish":
检测到凭证不正确后,返回 `HTTPException` 及状态码 401(与无凭证时返回的内容一样),并添加请求头 `WWW-Authenticate`,让浏览器再次显示登录提示:
-=== "Python 3.9+"
-
- ```Python hl_lines="26-30"
- {!> ../../../docs_src/security/tutorial007_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="26-30"
- {!> ../../../docs_src/security/tutorial007_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
-
- ```Python hl_lines="23-27"
- {!> ../../../docs_src/security/tutorial007.py!}
- ```
+{* ../../docs_src/security/tutorial007_an_py39.py hl[26:30] *}
diff --git a/docs/zh/docs/advanced/security/index.md b/docs/zh/docs/advanced/security/index.md
index e2bef4765..267e7ced7 100644
--- a/docs/zh/docs/advanced/security/index.md
+++ b/docs/zh/docs/advanced/security/index.md
@@ -4,10 +4,13 @@
除 [教程 - 用户指南: 安全性](../../tutorial/security/index.md){.internal-link target=_blank} 中涵盖的功能之外,还有一些额外的功能来处理安全性.
-!!! tip "小贴士"
- 接下来的章节 **并不一定是 "高级的"**.
+/// tip | 小贴士
- 而且对于你的使用场景来说,解决方案很可能就在其中。
+接下来的章节 **并不一定是 "高级的"**.
+
+而且对于你的使用场景来说,解决方案很可能就在其中。
+
+///
## 先阅读教程
diff --git a/docs/zh/docs/advanced/security/oauth2-scopes.md b/docs/zh/docs/advanced/security/oauth2-scopes.md
index e5eeffb0a..784c38490 100644
--- a/docs/zh/docs/advanced/security/oauth2-scopes.md
+++ b/docs/zh/docs/advanced/security/oauth2-scopes.md
@@ -10,19 +10,21 @@ OAuth2 也是脸书、谷歌、GitHub、微软、推特等第三方身份验证
本章介绍如何在 **FastAPI** 应用中使用 OAuth2 作用域管理验证与授权。
-!!! warning "警告"
+/// warning | 警告
- 本章内容较难,刚接触 FastAPI 的新手可以跳过。
+本章内容较难,刚接触 FastAPI 的新手可以跳过。
- OAuth2 作用域不是必需的,没有它,您也可以处理身份验证与授权。
+OAuth2 作用域不是必需的,没有它,您也可以处理身份验证与授权。
- 但 OAuth2 作用域与 API(通过 OpenAPI)及 API 文档集成地更好。
+但 OAuth2 作用域与 API(通过 OpenAPI)及 API 文档集成地更好。
- 不管怎么说,**FastAPI** 支持在代码中使用作用域或其它安全/授权需求项。
+不管怎么说,**FastAPI** 支持在代码中使用作用域或其它安全/授权需求项。
- 很多情况下,OAuth2 作用域就像一把牛刀。
+很多情况下,OAuth2 作用域就像一把牛刀。
- 但如果您确定要使用作用域,或对它有兴趣,请继续阅读。
+但如果您确定要使用作用域,或对它有兴趣,请继续阅读。
+
+///
## OAuth2 作用域与 OpenAPI
@@ -44,23 +46,23 @@ OpenAPI 中(例如 API 文档)可以定义**安全方案**。
* 脸书和 Instagram 使用 `instagram_basic`
* 谷歌使用 `https://www.googleapis.com/auth/drive`
-!!! info "说明"
+/// info | 说明
- OAuth2 中,**作用域**只是声明特定权限的字符串。
+OAuth2 中,**作用域**只是声明特定权限的字符串。
- 是否使用冒号 `:` 等符号,或是不是 URL 并不重要。
+是否使用冒号 `:` 等符号,或是不是 URL 并不重要。
- 这些细节只是特定的实现方式。
+这些细节只是特定的实现方式。
- 对 OAuth2 来说,它们都只是字符串而已。
+对 OAuth2 来说,它们都只是字符串而已。
+
+///
## 全局纵览
首先,快速浏览一下以下代码与**用户指南**中 [OAuth2 实现密码哈希与 Bearer JWT 令牌验证](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank}一章中代码的区别。以下代码使用 OAuth2 作用域:
-```Python hl_lines="2 4 8 12 46 64 105 107-115 121-124 128-134 139 153"
-{!../../../docs_src/security/tutorial005.py!}
-```
+{* ../../docs_src/security/tutorial005.py hl[2,4,8,12,46,64,105,107:115,121:124,128:134,139,153] *}
下面,我们逐步说明修改的代码内容。
@@ -70,9 +72,7 @@ OpenAPI 中(例如 API 文档)可以定义**安全方案**。
`scopes` 参数接收**字典**,键是作用域、值是作用域的描述:
-```Python hl_lines="62-65"
-{!../../../docs_src/security/tutorial005.py!}
-```
+{* ../../docs_src/security/tutorial005.py hl[62:65] *}
因为声明了作用域,所以登录或授权时会在 API 文档中显示。
@@ -90,15 +90,15 @@ OpenAPI 中(例如 API 文档)可以定义**安全方案**。
这样,返回的 JWT 令牌中就包含了作用域。
-!!! danger "危险"
+/// danger | 危险
- 为了简明起见,本例把接收的作用域直接添加到了令牌里。
+为了简明起见,本例把接收的作用域直接添加到了令牌里。
- 但在您的应用中,为了安全,应该只把作用域添加到确实需要作用域的用户,或预定义的用户。
+但在您的应用中,为了安全,应该只把作用域添加到确实需要作用域的用户,或预定义的用户。
-```Python hl_lines="153"
-{!../../../docs_src/security/tutorial005.py!}
-```
+///
+
+{* ../../docs_src/security/tutorial005.py hl[153] *}
## 在*路径操作*与依赖项中声明作用域
@@ -116,23 +116,25 @@ OpenAPI 中(例如 API 文档)可以定义**安全方案**。
本例要求使用作用域 `me`(还可以使用更多作用域)。
-!!! note "笔记"
+/// note | 笔记
- 不必在不同位置添加不同的作用域。
+不必在不同位置添加不同的作用域。
- 本例使用的这种方式只是为了展示 **FastAPI** 如何处理在不同层级声明的作用域。
+本例使用的这种方式只是为了展示 **FastAPI** 如何处理在不同层级声明的作用域。
-```Python hl_lines="4 139 166"
-{!../../../docs_src/security/tutorial005.py!}
-```
+///
-!!! info "技术细节"
+{* ../../docs_src/security/tutorial005.py hl[4,139,166] *}
- `Security` 实际上是 `Depends` 的子类,而且只比 `Depends` 多一个参数。
+/// info | 技术细节
- 但使用 `Security` 代替 `Depends`,**FastAPI** 可以声明安全作用域,并在内部使用这些作用域,同时,使用 OpenAPI 存档 API。
+`Security` 实际上是 `Depends` 的子类,而且只比 `Depends` 多一个参数。
- 但实际上,从 `fastapi` 导入的 `Query`、`Path`、`Depends`、`Security` 等对象,只是返回特殊类的函数。
+但使用 `Security` 代替 `Depends`,**FastAPI** 可以声明安全作用域,并在内部使用这些作用域,同时,使用 OpenAPI 存档 API。
+
+但实际上,从 `fastapi` 导入的 `Query`、`Path`、`Depends`、`Security` 等对象,只是返回特殊类的函数。
+
+///
## 使用 `SecurityScopes`
@@ -144,13 +146,11 @@ OpenAPI 中(例如 API 文档)可以定义**安全方案**。
该依赖项函数本身不需要作用域,因此,可以使用 `Depends` 和 `oauth2_scheme`。不需要指定安全作用域时,不必使用 `Security`。
-此处还声明了从 `fastapin.security` 导入的 `SecurityScopes` 类型的特殊参数。
+此处还声明了从 `fastapi.security` 导入的 `SecurityScopes` 类型的特殊参数。
`SecuriScopes` 类与 `Request` 类似(`Request` 用于直接提取请求对象)。
-```Python hl_lines="8 105"
-{!../../../docs_src/security/tutorial005.py!}
-```
+{* ../../docs_src/security/tutorial005.py hl[8,105] *}
## 使用 `scopes`
@@ -164,9 +164,7 @@ OpenAPI 中(例如 API 文档)可以定义**安全方案**。
该异常包含了作用域所需的(如有),以空格分割的字符串(使用 `scope_str`)。该字符串要放到包含作用域的 `WWW-Authenticate` 请求头中(这也是规范的要求)。
-```Python hl_lines="105 107-115"
-{!../../../docs_src/security/tutorial005.py!}
-```
+{* ../../docs_src/security/tutorial005.py hl[105,107:115] *}
## 校验 `username` 与数据形状
@@ -182,9 +180,7 @@ OpenAPI 中(例如 API 文档)可以定义**安全方案**。
还可以使用用户名验证用户,如果没有用户,也会触发之前创建的异常。
-```Python hl_lines="46 116-127"
-{!../../../docs_src/security/tutorial005.py!}
-```
+{* ../../docs_src/security/tutorial005.py hl[46,116:127] *}
## 校验 `scopes`
@@ -192,9 +188,7 @@ OpenAPI 中(例如 API 文档)可以定义**安全方案**。
为此,要使用包含所有作用域**字符串列表**的 `security_scopes.scopes`, 。
-```Python hl_lines="128-134"
-{!../../../docs_src/security/tutorial005.py!}
-```
+{* ../../docs_src/security/tutorial005.py hl[128:134] *}
## 依赖项树与作用域
@@ -221,11 +215,13 @@ OpenAPI 中(例如 API 文档)可以定义**安全方案**。
* `security_scopes.scopes` 包含*路径操作* `read_users_me` 的 `["me"]`,因为它在依赖项里被声明
* `security_scopes.scopes` 包含用于*路径操作* `read_system_status` 的 `[]`(空列表),并且它的依赖项 `get_current_user` 也没有声明任何 `scope`
-!!! tip "提示"
+/// tip | 提示
- 此处重要且**神奇**的事情是,`get_current_user` 检查每个*路径操作*时可以使用不同的 `scopes` 列表。
+此处重要且**神奇**的事情是,`get_current_user` 检查每个*路径操作*时可以使用不同的 `scopes` 列表。
- 所有这些都依赖于在每个*路径操作*和指定*路径操作*的依赖树中的每个依赖项。
+所有这些都依赖于在每个*路径操作*和指定*路径操作*的依赖树中的每个依赖项。
+
+///
## `SecurityScopes` 的更多细节
@@ -263,11 +259,13 @@ OpenAPI 中(例如 API 文档)可以定义**安全方案**。
最安全的是代码流,但实现起来更复杂,而且需要更多步骤。因为它更复杂,很多第三方身份验证应用最终建议使用隐式流。
-!!! note "笔记"
+/// note | 笔记
- 每个身份验证应用都会采用不同方式会命名流,以便融合入自己的品牌。
+每个身份验证应用都会采用不同方式会命名流,以便融合入自己的品牌。
- 但归根结底,它们使用的都是 OAuth2 标准。
+但归根结底,它们使用的都是 OAuth2 标准。
+
+///
**FastAPI** 的 `fastapi.security.oauth2` 里包含了所有 OAuth2 身份验证流工具。
diff --git a/docs/zh/docs/advanced/settings.md b/docs/zh/docs/advanced/settings.md
index d793b9c7f..e33da136f 100644
--- a/docs/zh/docs/advanced/settings.md
+++ b/docs/zh/docs/advanced/settings.md
@@ -8,44 +8,51 @@
## 环境变量
-!!! tip
- 如果您已经知道什么是"环境变量"以及如何使用它们,请随意跳到下面的下一节。
+/// tip
+
+如果您已经知道什么是"环境变量"以及如何使用它们,请随意跳到下面的下一节。
+
+///
环境变量(也称为"env var")是一种存在于 Python 代码之外、存在于操作系统中的变量,可以被您的 Python 代码(或其他程序)读取。
您可以在 shell 中创建和使用环境变量,而无需使用 Python:
-=== "Linux、macOS、Windows Bash"
+//// tab | Linux、macOS、Windows Bash
-
-!!! info
- 漂亮的插画来自 Ketrina Thompson. 🎨
+/// info
+
+漂亮的插画来自 Ketrina Thompson. 🎨
+
+///
---
@@ -199,8 +205,11 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和
没有太多的交谈或调情,因为大部分时间 🕙 都在柜台前等待😞。
-!!! info
- 漂亮的插画来自 Ketrina Thompson. 🎨
+/// info
+
+漂亮的插画来自 Ketrina Thompson. 🎨
+
+///
---
@@ -242,7 +251,7 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和
这与 **FastAPI** 的性能水平相同。
-您可以同时拥有并行性和异步性,您可以获得比大多数经过测试的 NodeJS 框架更高的性能,并且与 Go 不相上下, Go 是一种更接近于 C 的编译语言(全部归功于 Starlette)。
+你可以同时拥有并行性和异步性,你可以获得比大多数经过测试的 NodeJS 框架更高的性能,并且与 Go 不相上下, Go 是一种更接近于 C 的编译语言(全部归功于 Starlette)。
### 并发比并行好吗?
@@ -266,7 +275,7 @@ Python 的现代版本支持通过一种叫**"协程"**——使用 `async` 和
但在这种情况下,如果你能带上 8 名前收银员/厨师,现在是清洁工一起清扫,他们中的每一个人(加上你)都能占据房子的一个区域来清扫,你就可以在额外的帮助下并行的更快地完成所有工作。
-在这个场景中,每个清洁工(包括您)都将是一个处理器,完成这个工作的一部分。
+在这个场景中,每个清洁工(包括你)都将是一个处理器,完成这个工作的一部分。
由于大多数执行时间是由实际工作(而不是等待)占用的,并且计算机中的工作是由 CPU 完成的,所以他们称这些问题为"CPU 密集型"。
@@ -283,9 +292,9 @@ CPU 密集型操作的常见示例是需要复杂的数学处理。
### 并发 + 并行: Web + 机器学习
-使用 **FastAPI**,您可以利用 Web 开发中常见的并发机制的优势(NodeJS 的主要吸引力)。
+使用 **FastAPI**,你可以利用 Web 开发中常见的并发机制的优势(NodeJS 的主要吸引力)。
-并且,您也可以利用并行和多进程(让多个进程并行运行)的优点来处理与机器学习系统中类似的 **CPU 密集型** 工作。
+并且,你也可以利用并行和多进程(让多个进程并行运行)的优点来处理与机器学习系统中类似的 **CPU 密集型** 工作。
这一点,再加上 Python 是**数据科学**、机器学习(尤其是深度学习)的主要语言这一简单事实,使得 **FastAPI** 与数据科学/机器学习 Web API 和应用程序(以及其他许多应用程序)非常匹配。
@@ -295,7 +304,7 @@ CPU 密集型操作的常见示例是需要复杂的数学处理。
现代版本的 Python 有一种非常直观的方式来定义异步代码。这使它看起来就像正常的"顺序"代码,并在适当的时候"等待"。
-当有一个操作需要等待才能给出结果,且支持这个新的 Python 特性时,您可以编写如下代码:
+当有一个操作需要等待才能给出结果,且支持这个新的 Python 特性时,你可以编写如下代码:
```Python
burgers = await get_burgers(2)
@@ -331,7 +340,7 @@ burgers = get_burgers(2)
---
-因此,如果您使用的库告诉您可以使用 `await` 调用它,则需要使用 `async def` 创建路径操作函数 ,如:
+因此,如果你使用的库告诉你可以使用 `await` 调用它,则需要使用 `async def` 创建路径操作函数 ,如:
```Python hl_lines="2-3"
@app.get('/burgers')
@@ -342,15 +351,15 @@ async def read_burgers():
### 更多技术细节
-您可能已经注意到,`await` 只能在 `async def` 定义的函数内部使用。
+你可能已经注意到,`await` 只能在 `async def` 定义的函数内部使用。
但与此同时,必须"等待"通过 `async def` 定义的函数。因此,带 `async def` 的函数也只能在 `async def` 定义的函数内部调用。
那么,这关于先有鸡还是先有蛋的问题,如何调用第一个 `async` 函数?
-如果您使用 **FastAPI**,你不必担心这一点,因为"第一个"函数将是你的路径操作函数,FastAPI 将知道如何做正确的事情。
+如果你使用 **FastAPI**,你不必担心这一点,因为"第一个"函数将是你的路径操作函数,FastAPI 将知道如何做正确的事情。
-但如果您想在没有 FastAPI 的情况下使用 `async` / `await`,则可以这样做。
+但如果你想在没有 FastAPI 的情况下使用 `async` / `await`,则可以这样做。
### 编写自己的异步代码
@@ -358,7 +367,9 @@ Starlette (和 **FastAPI**) 是基于 AnyIO 来处理高级的并发用例,这些用例需要在自己的代码中使用更高级的模式。
-即使您没有使用 **FastAPI**,您也可以使用 AnyIO 编写自己的异步程序,使其拥有较高的兼容性并获得一些好处(例如, 结构化并发)。
+即使你没有使用 **FastAPI**,你也可以使用 AnyIO 编写自己的异步程序,使其拥有较高的兼容性并获得一些好处(例如, 结构化并发)。
+
+我(指原作者 —— 译者注)基于 AnyIO 新建了一个库,作为一个轻量级的封装层,用来优化类型注解,同时提供了更好的**自动补全**、**内联错误提示**等功能。这个库还附带了一个友好的入门指南和教程,能帮助你**理解**并编写**自己的异步代码**:Asyncer。如果你有**结合使用异步代码和常规**(阻塞/同步)代码的需求,这个库会特别有用。
### 其他形式的异步代码
@@ -392,20 +403,23 @@ Starlette (和 **FastAPI**) 是基于 I/O 的代码。
+如果你使用过另一个不以上述方式工作的异步框架,并且你习惯于用普通的 `def` 定义普通的仅计算路径操作函数,以获得微小的性能增益(大约100纳秒),请注意,在 FastAPI 中,效果将完全相反。在这些情况下,最好使用 `async def`,除非路径操作函数内使用执行阻塞 I/O 的代码。
-在这两种情况下,与您之前的框架相比,**FastAPI** 可能[仍然很快](index.md#_11){.internal-link target=_blank}。
+在这两种情况下,与你之前的框架相比,**FastAPI** 可能[仍然很快](index.md#_11){.internal-link target=_blank}。
### 依赖
@@ -417,9 +431,9 @@ Starlette (和 **FastAPI**) 是基于 赶时间吗?.
+否则,你最好应该遵守的指导原则赶时间吗?.
diff --git a/docs/zh/docs/contributing.md b/docs/zh/docs/contributing.md
deleted file mode 100644
index 91be2edbb..000000000
--- a/docs/zh/docs/contributing.md
+++ /dev/null
@@ -1,435 +0,0 @@
-# 开发 - 贡献
-
-首先,你可能想了解 [帮助 FastAPI 及获取帮助](help-fastapi.md){.internal-link target=_blank}的基本方式。
-
-## 开发
-
-如果你已经克隆了源码仓库,并且需要深入研究代码,下面是设置开发环境的指南。
-
-### 通过 `venv` 管理虚拟环境
-
-你可以使用 Python 的 `venv` 模块在一个目录中创建虚拟环境:
-
-
-
-
+
+
-
-
+
+
@@ -94,7 +94,7 @@ FastAPI 是一个用于构建 API 的现代、快速(高性能)的 web 框
「_老实说,你的作品看起来非常可靠和优美。在很多方面,这就是我想让 **Hug** 成为的样子 - 看到有人实现了它真的很鼓舞人心。_」
-
+
---
@@ -446,7 +446,7 @@ item: Item
用于 Pydantic:
-*
email_validator - 用于 email 校验。
+* email-validator - 用于 email 校验。
用于 Starlette:
diff --git a/docs/zh/docs/project-generation.md b/docs/zh/docs/project-generation.md
index 0655cb0a9..48eb990df 100644
--- a/docs/zh/docs/project-generation.md
+++ b/docs/zh/docs/project-generation.md
@@ -1,84 +1,28 @@
-# 项目生成 - 模板
+# FastAPI全栈模板
-项目生成器一般都会提供很多初始设置、安全措施、数据库,甚至还准备好了第一个 API 端点,能帮助您快速上手。
+模板通常带有特定的设置,而且被设计为灵活和可定制的。这允许您根据项目的需求修改和调整它们,使它们成为一个很好的起点。🏁
-项目生成器的设置通常都很主观,您可以按需更新或修改,但对于您的项目来说,它是非常好的起点。
+您可以使用此模板开始,因为它包含了许多已经为您完成的初始设置、安全性、数据库和一些API端点。
-## 全栈 FastAPI + PostgreSQL
+代码仓: Full Stack FastAPI Template
-GitHub:https://github.com/tiangolo/full-stack-fastapi-postgresql
+## FastAPI全栈模板 - 技术栈和特性
-### 全栈 FastAPI + PostgreSQL - 功能
-
-* 完整的 **Docker** 集成(基于 Docker)
-* Docker Swarm 开发模式
-* **Docker Compose** 本地开发集成与优化
-* **生产可用**的 Python 网络服务器,使用 Uvicorn 或 Gunicorn
-* Python **FastAPI** 后端:
-* * **速度快**:可与 **NodeJS** 和 **Go** 比肩的极高性能(归功于 Starlette 和 Pydantic)
- * **直观**:强大的编辑器支持,处处皆可自动补全,减少调试时间
- * **简单**:易学、易用,阅读文档所需时间更短
- * **简短**:代码重复最小化,每次参数声明都可以实现多个功能
- * **健壮**: 生产级别的代码,还有自动交互文档
- * **基于标准**:完全兼容并基于 API 开放标准:OpenAPI 和 JSON Schema
- * **更多功能**包括自动验证、序列化、交互文档、OAuth2 JWT 令牌身份验证等
-* **安全密码**,默认使用密码哈希
-* **JWT 令牌**身份验证
-* **SQLAlchemy** 模型(独立于 Flask 扩展,可直接用于 Celery Worker)
-* 基础的用户模型(可按需修改或删除)
-* **Alembic** 迁移
-* **CORS**(跨域资源共享)
-* **Celery** Worker 可从后端其它部分有选择地导入并使用模型和代码
-* REST 后端测试基于 Pytest,并与 Docker 集成,可独立于数据库实现完整的 API 交互测试。因为是在 Docker 中运行,每次都可从头构建新的数据存储(使用 ElasticSearch、MongoDB、CouchDB 等数据库,仅测试 API 运行)
-* Python 与 **Jupyter Kernels** 集成,用于远程或 Docker 容器内部开发,使用 Atom Hydrogen 或 Visual Studio Code 的 Jupyter 插件
-* **Vue** 前端:
- * 由 Vue CLI 生成
- * **JWT 身份验证**处理
- * 登录视图
- * 登录后显示主仪表盘视图
- * 主仪表盘支持用户创建与编辑
- * 用户信息编辑
- * **Vuex**
- * **Vue-router**
- * **Vuetify** 美化组件
- * **TypeScript**
- * 基于 **Nginx** 的 Docker 服务器(优化了 Vue-router 配置)
- * Docker 多阶段构建,无需保存或提交编译的代码
- * 在构建时运行前端测试(可禁用)
- * 尽量模块化,开箱即用,但仍可使用 Vue CLI 重新生成或创建所需项目,或复用所需内容
-* 使用 **PGAdmin** 管理 PostgreSQL 数据库,可轻松替换为 PHPMyAdmin 或 MySQL
-* 使用 **Flower** 监控 Celery 任务
-* 使用 **Traefik** 处理前后端负载平衡,可把前后端放在同一个域下,按路径分隔,但在不同容器中提供服务
-* Traefik 集成,包括自动生成 Let's Encrypt **HTTPS** 凭证
-* GitLab **CI**(持续集成),包括前后端测试
-
-## 全栈 FastAPI + Couchbase
-
-GitHub:https://github.com/tiangolo/full-stack-fastapi-couchbase
-
-⚠️ **警告** ⚠️
-
-如果您想从头开始创建新项目,建议使用以下备选方案。
-
-例如,项目生成器全栈 FastAPI + PostgreSQL 会更适用,这个项目的维护积极,用的人也多,还包括了所有新功能和改进内容。
-
-当然,您也可以放心使用这个基于 Couchbase 的生成器,它也能正常使用。就算用它生成项目也没有任何问题(为了更好地满足需求,您可以自行更新这个项目)。
-
-详见资源仓库中的文档。
-
-## 全栈 FastAPI + MongoDB
-
-……敬请期待,得看我有没有时间做这个项目。😅 🎉
-
-## FastAPI + spaCy 机器学习模型
-
-GitHub:https://github.com/microsoft/cookiecutter-spacy-fastapi
-
-### FastAPI + spaCy 机器学习模型 - 功能
-
-* 集成 **spaCy** NER 模型
-* 内置 **Azure 认知搜索**请求格式
-* **生产可用**的 Python 网络服务器,使用 Uvicorn 与 Gunicorn
-* 内置 **Azure DevOps** Kubernetes (AKS) CI/CD 开发
-* **多语**支持,可在项目设置时选择 spaCy 内置的语言
-* 不仅局限于 spaCy,可**轻松扩展**至其它模型框架(Pytorch、TensorFlow)
+- ⚡ [**FastAPI**](https://fastapi.tiangolo.com) 用于Python后端API.
+ - 🧰 [SQLModel](https://sqlmodel.tiangolo.com) 用于Python和SQL数据库的集成(ORM)。
+ - 🔍 [Pydantic](https://docs.pydantic.dev) FastAPI的依赖项之一,用于数据验证和配置管理。
+ - 💾 [PostgreSQL](https://www.postgresql.org) 作为SQL数据库。
+- 🚀 [React](https://react.dev) 用于前端。
+ - 💃 使用了TypeScript、hooks、[Vite](https://vitejs.dev)和其他一些现代化的前端技术栈。
+ - 🎨 [Chakra UI](https://chakra-ui.com) 用于前端组件。
+ - 🤖 一个自动化生成的前端客户端。
+ - 🧪 [Playwright](https://playwright.dev)用于端到端测试。
+ - 🦇 支持暗黑主题(Dark mode)。
+- 🐋 [Docker Compose](https://www.docker.com) 用于开发环境和生产环境。
+- 🔒 默认使用密码哈希来保证安全。
+- 🔑 JWT令牌用于权限验证。
+- 📫 使用邮箱来进行密码恢复。
+- ✅ 单元测试用了[Pytest](https://pytest.org).
+- 📞 [Traefik](https://traefik.io) 用于反向代理和负载均衡。
+- 🚢 部署指南(Docker Compose)包含了如何起一个Traefik前端代理来自动化HTTPS认证。
+- 🏭 CI(持续集成)和 CD(持续部署)基于GitHub Actions。
diff --git a/docs/zh/docs/python-types.md b/docs/zh/docs/python-types.md
index 214b47611..ba767da87 100644
--- a/docs/zh/docs/python-types.md
+++ b/docs/zh/docs/python-types.md
@@ -12,16 +12,18 @@
但即使你不会用到 **FastAPI**,了解一下类型提示也会让你从中受益。
-!!! note
- 如果你已经精通 Python,并且了解关于类型提示的一切知识,直接跳到下一章节吧。
+/// note
+
+如果你已经精通 Python,并且了解关于类型提示的一切知识,直接跳到下一章节吧。
+
+///
## 动机
让我们从一个简单的例子开始:
-```Python
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py *}
+
运行这段程序将输出:
@@ -35,9 +37,8 @@ John Doe
* 通过 `title()` 将每个参数的第一个字母转换为大写形式。
* 中间用一个空格来拼接它们。
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial001.py!}
-```
+{* ../../docs_src/python_types/tutorial001.py hl[2] *}
+
### 修改示例
@@ -79,9 +80,8 @@ John Doe
这些就是"类型提示":
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial002.py!}
-```
+{* ../../docs_src/python_types/tutorial002.py hl[1] *}
+
这和声明默认值是不同的,例如:
@@ -109,9 +109,8 @@ John Doe
下面是一个已经有类型提示的函数:
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial003.py!}
-```
+{* ../../docs_src/python_types/tutorial003.py hl[1] *}
+
因为编辑器已经知道了这些变量的类型,所以不仅能对代码进行补全,还能检查其中的错误:
@@ -119,9 +118,8 @@ John Doe
现在你知道了必须先修复这个问题,通过 `str(age)` 把 `age` 转换成字符串:
-```Python hl_lines="2"
-{!../../../docs_src/python_types/tutorial004.py!}
-```
+{* ../../docs_src/python_types/tutorial004.py hl[2] *}
+
## 声明类型
@@ -140,9 +138,8 @@ John Doe
* `bool`
* `bytes`
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial005.py!}
-```
+{* ../../docs_src/python_types/tutorial005.py hl[1] *}
+
### 嵌套类型
@@ -158,9 +155,8 @@ John Doe
从 `typing` 模块导入 `List`(注意是大写的 `L`):
-```Python hl_lines="1"
-{!../../../docs_src/python_types/tutorial006.py!}
-```
+{* ../../docs_src/python_types/tutorial006.py hl[1] *}
+
同样以冒号(`:`)来声明这个变量。
@@ -168,9 +164,8 @@ John Doe
由于列表是带有"子类型"的类型,所以我们把子类型放在方括号中:
-```Python hl_lines="4"
-{!../../../docs_src/python_types/tutorial006.py!}
-```
+{* ../../docs_src/python_types/tutorial006.py hl[4] *}
+
这表示:"变量 `items` 是一个 `list`,并且这个列表里的每一个元素都是 `str`"。
@@ -188,9 +183,8 @@ John Doe
声明 `tuple` 和 `set` 的方法也是一样的:
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial007.py!}
-```
+{* ../../docs_src/python_types/tutorial007.py hl[1,4] *}
+
这表示:
@@ -205,9 +199,8 @@ John Doe
第二个子类型声明 `dict` 的所有值:
-```Python hl_lines="1 4"
-{!../../../docs_src/python_types/tutorial008.py!}
-```
+{* ../../docs_src/python_types/tutorial008.py hl[1,4] *}
+
这表示:
@@ -221,15 +214,13 @@ John Doe
假设你有一个名为 `Person` 的类,拥有 name 属性:
-```Python hl_lines="1-3"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
+
接下来,你可以将一个变量声明为 `Person` 类型:
-```Python hl_lines="6"
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py hl[6] *}
+
然后,你将再次获得所有的编辑器支持:
@@ -237,7 +228,7 @@ John Doe
## Pydantic 模型
-Pydantic 是一个用来用来执行数据校验的 Python 库。
+Pydantic 是一个用来执行数据校验的 Python 库。
你可以将数据的"结构"声明为具有属性的类。
@@ -249,12 +240,14 @@ John Doe
下面的例子来自 Pydantic 官方文档:
-```Python
-{!../../../docs_src/python_types/tutorial010.py!}
-```
+{* ../../docs_src/python_types/tutorial010.py *}
-!!! info
- 想进一步了解 Pydantic,请阅读其文档.
+
+/// info
+
+想进一步了解 Pydantic,请阅读其文档.
+
+///
整个 **FastAPI** 建立在 Pydantic 的基础之上。
@@ -282,5 +275,8 @@ John Doe
最重要的是,通过使用标准的 Python 类型,只需要在一个地方声明(而不是添加更多的类、装饰器等),**FastAPI** 会为你完成很多的工作。
-!!! info
- 如果你已经阅读了所有教程,回过头来想了解有关类型的更多信息,来自 `mypy` 的"速查表"是不错的资源。
+/// info
+
+如果你已经阅读了所有教程,回过头来想了解有关类型的更多信息,来自 `mypy` 的"速查表"是不错的资源。
+
+///
diff --git a/docs/zh/docs/tutorial/background-tasks.md b/docs/zh/docs/tutorial/background-tasks.md
index 94b75d4fd..40e61add7 100644
--- a/docs/zh/docs/tutorial/background-tasks.md
+++ b/docs/zh/docs/tutorial/background-tasks.md
@@ -15,9 +15,7 @@
首先导入 `BackgroundTasks` 并在 *路径操作函数* 中使用类型声明 `BackgroundTasks` 定义一个参数:
-```Python hl_lines="1 13"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[1, 13] *}
**FastAPI** 会创建一个 `BackgroundTasks` 类型的对象并作为该参数传入。
@@ -33,17 +31,13 @@
由于写操作不使用 `async` 和 `await`,我们用普通的 `def` 定义函数:
-```Python hl_lines="6-9"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *}
## 添加后台任务
在你的 *路径操作函数* 里,用 `.add_task()` 方法将任务函数传到 *后台任务* 对象中:
-```Python hl_lines="14"
-{!../../../docs_src/background_tasks/tutorial001.py!}
-```
+{* ../../docs_src/background_tasks/tutorial001.py hl[14] *}
`.add_task()` 接收以下参数:
@@ -57,41 +51,47 @@
**FastAPI** 知道在每种情况下该做什么以及如何复用同一对象,因此所有后台任务被合并在一起并且随后在后台运行:
-=== "Python 3.10+"
+//// tab | Python 3.10+
- ```Python hl_lines="13 15 22 25"
- {!> ../../../docs_src/background_tasks/tutorial002_an_py310.py!}
- ```
+{* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13, 15, 22, 25] *}
-=== "Python 3.9+"
+////
- ```Python hl_lines="13 15 22 25"
- {!> ../../../docs_src/background_tasks/tutorial002_an_py39.py!}
- ```
+//// tab | Python 3.9+
-=== "Python 3.8+"
+{* ../../docs_src/background_tasks/tutorial002_an_py39.py hl[13, 15, 22, 25] *}
- ```Python hl_lines="14 16 23 26"
- {!> ../../../docs_src/background_tasks/tutorial002_an.py!}
- ```
+////
-=== "Python 3.10+ 没Annotated"
+//// tab | Python 3.8+
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
+{* ../../docs_src/background_tasks/tutorial002_an.py hl[14, 16, 23, 26] *}
- ```Python hl_lines="11 13 20 23"
- {!> ../../../docs_src/background_tasks/tutorial002_py310.py!}
- ```
+////
-=== "Python 3.8+ 没Annotated"
+//// tab | Python 3.10+ 没Annotated
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
+/// tip
- ```Python hl_lines="13 15 22 25"
- {!> ../../../docs_src/background_tasks/tutorial002.py!}
- ```
+尽可能选择使用 `Annotated` 的版本。
+
+///
+
+{* ../../docs_src/background_tasks/tutorial002_py310.py hl[11, 13, 20, 23] *}
+
+////
+
+//// tab | Python 3.8+ 没Annotated
+
+/// tip
+
+尽可能选择使用 `Annotated` 的版本。
+
+///
+
+{* ../../docs_src/background_tasks/tutorial002.py hl[13, 15, 22, 25] *}
+
+////
该示例中,信息会在响应发出 *之后* 被写到 `log.txt` 文件。
@@ -117,8 +117,6 @@
它们往往需要更复杂的配置,即消息/作业队列管理器,如RabbitMQ或Redis,但它们允许您在多个进程中运行后台任务,甚至是在多个服务器中。
-要查看示例,查阅 [Project Generators](../project-generation.md){.internal-link target=_blank},它们都包括已经配置的Celery。
-
但是,如果您需要从同一个**FastAPI**应用程序访问变量和对象,或者您需要执行小型后台任务(如发送电子邮件通知),您只需使用 `BackgroundTasks` 即可。
## 回顾
diff --git a/docs/zh/docs/tutorial/bigger-applications.md b/docs/zh/docs/tutorial/bigger-applications.md
index 422cd7c16..554bc654f 100644
--- a/docs/zh/docs/tutorial/bigger-applications.md
+++ b/docs/zh/docs/tutorial/bigger-applications.md
@@ -4,8 +4,11 @@
**FastAPI** 提供了一个方便的工具,可以在保持所有灵活性的同时构建你的应用程序。
-!!! info
- 如果你来自 Flask,那这将相当于 Flask 的 Blueprints。
+/// info
+
+如果你来自 Flask,那这将相当于 Flask 的 Blueprints。
+
+///
## 一个文件结构示例
@@ -26,16 +29,19 @@
│ └── admin.py
```
-!!! tip
- 上面有几个 `__init__.py` 文件:每个目录或子目录中都有一个。
+/// tip
- 这就是能将代码从一个文件导入到另一个文件的原因。
+上面有几个 `__init__.py` 文件:每个目录或子目录中都有一个。
- 例如,在 `app/main.py` 中,你可以有如下一行:
+这就是能将代码从一个文件导入到另一个文件的原因。
- ```
- from app.routers import items
- ```
+例如,在 `app/main.py` 中,你可以有如下一行:
+
+```
+from app.routers import items
+```
+
+///
* `app` 目录包含了所有内容。并且它有一个空文件 `app/__init__.py`,因此它是一个「Python 包」(「Python 模块」的集合):`app`。
* 它包含一个 `app/main.py` 文件。由于它位于一个 Python 包(一个包含 `__init__.py` 文件的目录)中,因此它是该包的一个「模块」:`app.main`。
@@ -46,7 +52,7 @@
* 还有一个子目录 `app/internal/` 包含另一个 `__init__.py` 文件,因此它是又一个「Python 子包」:`app.internal`。
* `app/internal/admin.py` 是另一个子模块:`app.internal.admin`。
-
+
带有注释的同一文件结构:
@@ -80,7 +86,7 @@
你可以导入它并通过与 `FastAPI` 类相同的方式创建一个「实例」:
```Python hl_lines="1 3" title="app/routers/users.py"
-{!../../../docs_src/bigger_applications/app/routers/users.py!}
+{!../../docs_src/bigger_applications/app/routers/users.py!}
```
### 使用 `APIRouter` 的*路径操作*
@@ -90,7 +96,7 @@
使用方式与 `FastAPI` 类相同:
```Python hl_lines="6 11 16" title="app/routers/users.py"
-{!../../../docs_src/bigger_applications/app/routers/users.py!}
+{!../../docs_src/bigger_applications/app/routers/users.py!}
```
你可以将 `APIRouter` 视为一个「迷你 `FastAPI`」类。
@@ -99,8 +105,11 @@
所有相同的 `parameters`、`responses`、`dependencies`、`tags` 等等。
-!!! tip
- 在此示例中,该变量被命名为 `router`,但你可以根据你的想法自由命名。
+/// tip
+
+在此示例中,该变量被命名为 `router`,但你可以根据你的想法自由命名。
+
+///
我们将在主 `FastAPI` 应用中包含该 `APIRouter`,但首先,让我们来看看依赖项和另一个 `APIRouter`。
@@ -113,13 +122,16 @@
现在我们将使用一个简单的依赖项来读取一个自定义的 `X-Token` 请求首部:
```Python hl_lines="1 4-6" title="app/dependencies.py"
-{!../../../docs_src/bigger_applications/app/dependencies.py!}
+{!../../docs_src/bigger_applications/app/dependencies.py!}
```
-!!! tip
- 我们正在使用虚构的请求首部来简化此示例。
+/// tip
- 但在实际情况下,使用集成的[安全性实用工具](security/index.md){.internal-link target=_blank}会得到更好的效果。
+我们正在使用虚构的请求首部来简化此示例。
+
+但在实际情况下,使用集成的[安全性实用工具](security/index.md){.internal-link target=_blank}会得到更好的效果。
+
+///
## 其他使用 `APIRouter` 的模块
@@ -144,7 +156,7 @@
因此,我们可以将其添加到 `APIRouter` 中,而不是将其添加到每个路径操作中。
```Python hl_lines="5-10 16 21" title="app/routers/items.py"
-{!../../../docs_src/bigger_applications/app/routers/items.py!}
+{!../../docs_src/bigger_applications/app/routers/items.py!}
```
由于每个*路径操作*的路径都必须以 `/` 开头,例如:
@@ -163,8 +175,11 @@ async def read_item(item_id: str):
我们可以添加一个 `dependencies` 列表,这些依赖项将被添加到路由器中的所有*路径操作*中,并将针对向它们发起的每个请求执行/解决。
-!!! tip
- 请注意,和[*路径操作装饰器*中的依赖项](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}很类似,没有值会被传递给你的*路径操作函数*。
+/// tip
+
+请注意,和[*路径操作装饰器*中的依赖项](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}很类似,没有值会被传递给你的*路径操作函数*。
+
+///
最终结果是项目相关的路径现在为:
@@ -181,11 +196,17 @@ async def read_item(item_id: str):
* 路由器的依赖项最先执行,然后是[装饰器中的 `dependencies`](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank},再然后是普通的参数依赖项。
* 你还可以添加[具有 `scopes` 的 `Security` 依赖项](../advanced/security/oauth2-scopes.md){.internal-link target=_blank}。
-!!! tip
- 在 `APIRouter`中具有 `dependencies` 可以用来,例如,对一整组的*路径操作*要求身份认证。即使这些依赖项并没有分别添加到每个路径操作中。
+/// tip
-!!! check
- `prefix`、`tags`、`responses` 以及 `dependencies` 参数只是(和其他很多情况一样)**FastAPI** 的一个用于帮助你避免代码重复的功能。
+在 `APIRouter`中具有 `dependencies` 可以用来,例如,对一整组的*路径操作*要求身份认证。即使这些依赖项并没有分别添加到每个路径操作中。
+
+///
+
+/// check
+
+`prefix`、`tags`、`responses` 以及 `dependencies` 参数只是(和其他很多情况一样)**FastAPI** 的一个用于帮助你避免代码重复的功能。
+
+///
### 导入依赖项
@@ -196,13 +217,16 @@ async def read_item(item_id: str):
因此,我们通过 `..` 对依赖项使用了相对导入:
```Python hl_lines="3" title="app/routers/items.py"
-{!../../../docs_src/bigger_applications/app/routers/items.py!}
+{!../../docs_src/bigger_applications/app/routers/items.py!}
```
#### 相对导入如何工作
-!!! tip
- 如果你完全了解导入的工作原理,请从下面的下一部分继续。
+/// tip
+
+如果你完全了解导入的工作原理,请从下面的下一部分继续。
+
+///
一个单点 `.`,例如:
@@ -220,7 +244,7 @@ from .dependencies import get_token_header
请记住我们的程序/文件结构是怎样的:
-
+
---
@@ -266,13 +290,16 @@ from ...dependencies import get_token_header
但是我们仍然可以添加*更多*将会应用于特定的*路径操作*的 `tags`,以及一些特定于该*路径操作*的额外 `responses`:
```Python hl_lines="30-31" title="app/routers/items.py"
-{!../../../docs_src/bigger_applications/app/routers/items.py!}
+{!../../docs_src/bigger_applications/app/routers/items.py!}
```
-!!! tip
- 最后的这个路径操作将包含标签的组合:`["items","custom"]`。
+/// tip
- 并且在文档中也会有两个响应,一个用于 `404`,一个用于 `403`。
+最后的这个路径操作将包含标签的组合:`["items","custom"]`。
+
+并且在文档中也会有两个响应,一个用于 `404`,一个用于 `403`。
+
+///
## `FastAPI` 主体
@@ -291,7 +318,7 @@ from ...dependencies import get_token_header
我们甚至可以声明[全局依赖项](dependencies/global-dependencies.md){.internal-link target=_blank},它会和每个 `APIRouter` 的依赖项组合在一起:
```Python hl_lines="1 3 7" title="app/main.py"
-{!../../../docs_src/bigger_applications/app/main.py!}
+{!../../docs_src/bigger_applications/app/main.py!}
```
### 导入 `APIRouter`
@@ -299,7 +326,7 @@ from ...dependencies import get_token_header
现在,我们导入具有 `APIRouter` 的其他子模块:
```Python hl_lines="5" title="app/main.py"
-{!../../../docs_src/bigger_applications/app/main.py!}
+{!../../docs_src/bigger_applications/app/main.py!}
```
由于文件 `app/routers/users.py` 和 `app/routers/items.py` 是同一 Python 包 `app` 一个部分的子模块,因此我们可以使用单个点 ` .` 通过「相对导入」来导入它们。
@@ -328,20 +355,23 @@ from .routers import items, users
from app.routers import items, users
```
-!!! info
- 第一个版本是「相对导入」:
+/// info
- ```Python
- from .routers import items, users
- ```
+第一个版本是「相对导入」:
- 第二个版本是「绝对导入」:
+```Python
+from .routers import items, users
+```
- ```Python
- from app.routers import items, users
- ```
+第二个版本是「绝对导入」:
- 要了解有关 Python 包和模块的更多信息,请查阅关于 Modules 的 Python 官方文档。
+```Python
+from app.routers import items, users
+```
+
+要了解有关 Python 包和模块的更多信息,请查阅关于 Modules 的 Python 官方文档。
+
+///
### 避免名称冲突
@@ -361,7 +391,7 @@ from .routers.users import router
因此,为了能够在同一个文件中使用它们,我们直接导入子模块:
```Python hl_lines="5" title="app/main.py"
-{!../../../docs_src/bigger_applications/app/main.py!}
+{!../../docs_src/bigger_applications/app/main.py!}
```
### 包含 `users` 和 `items` 的 `APIRouter`
@@ -369,29 +399,38 @@ from .routers.users import router
现在,让我们来包含来自 `users` 和 `items` 子模块的 `router`。
```Python hl_lines="10-11" title="app/main.py"
-{!../../../docs_src/bigger_applications/app/main.py!}
+{!../../docs_src/bigger_applications/app/main.py!}
```
-!!! info
- `users.router` 包含了 `app/routers/users.py` 文件中的 `APIRouter`。
+/// info
- `items.router` 包含了 `app/routers/items.py` 文件中的 `APIRouter`。
+`users.router` 包含了 `app/routers/users.py` 文件中的 `APIRouter`。
+
+`items.router` 包含了 `app/routers/items.py` 文件中的 `APIRouter`。
+
+///
使用 `app.include_router()`,我们可以将每个 `APIRouter` 添加到主 `FastAPI` 应用程序中。
它将包含来自该路由器的所有路由作为其一部分。
-!!! note "技术细节"
- 实际上,它将在内部为声明在 `APIRouter` 中的每个*路径操作*创建一个*路径操作*。
+/// note | 技术细节
- 所以,在幕后,它实际上会像所有的东西都是同一个应用程序一样工作。
+实际上,它将在内部为声明在 `APIRouter` 中的每个*路径操作*创建一个*路径操作*。
-!!! check
- 包含路由器时,你不必担心性能问题。
+所以,在幕后,它实际上会像所有的东西都是同一个应用程序一样工作。
- 这将花费几微秒时间,并且只会在启动时发生。
+///
- 因此,它不会影响性能。⚡
+/// check
+
+包含路由器时,你不必担心性能问题。
+
+这将花费几微秒时间,并且只会在启动时发生。
+
+因此,它不会影响性能。⚡
+
+///
### 包含一个有自定义 `prefix`、`tags`、`responses` 和 `dependencies` 的 `APIRouter`
@@ -402,7 +441,7 @@ from .routers.users import router
对于此示例,它将非常简单。但是假设由于它是与组织中的其他项目所共享的,因此我们无法对其进行修改,以及直接在 `APIRouter` 中添加 `prefix`、`dependencies`、`tags` 等:
```Python hl_lines="3" title="app/internal/admin.py"
-{!../../../docs_src/bigger_applications/app/internal/admin.py!}
+{!../../docs_src/bigger_applications/app/internal/admin.py!}
```
但是我们仍然希望在包含 `APIRouter` 时设置一个自定义的 `prefix`,以便其所有*路径操作*以 `/admin` 开头,我们希望使用本项目已经有的 `dependencies` 保护它,并且我们希望它包含自定义的 `tags` 和 `responses`。
@@ -410,7 +449,7 @@ from .routers.users import router
我们可以通过将这些参数传递给 `app.include_router()` 来完成所有的声明,而不必修改原始的 `APIRouter`:
```Python hl_lines="14-17" title="app/main.py"
-{!../../../docs_src/bigger_applications/app/main.py!}
+{!../../docs_src/bigger_applications/app/main.py!}
```
这样,原始的 `APIRouter` 将保持不变,因此我们仍然可以与组织中的其他项目共享相同的 `app/internal/admin.py` 文件。
@@ -433,21 +472,24 @@ from .routers.users import router
这里我们这样做了...只是为了表明我们可以做到🤷:
```Python hl_lines="21-23" title="app/main.py"
-{!../../../docs_src/bigger_applications/app/main.py!}
+{!../../docs_src/bigger_applications/app/main.py!}
```
它将与通过 `app.include_router()` 添加的所有其他*路径操作*一起正常运行。
-!!! info "特别的技术细节"
- **注意**:这是一个非常技术性的细节,你也许可以**直接跳过**。
+/// info | 特别的技术细节
- ---
+**注意**:这是一个非常技术性的细节,你也许可以**直接跳过**。
- `APIRouter` 没有被「挂载」,它们与应用程序的其余部分没有隔离。
+---
- 这是因为我们想要在 OpenAPI 模式和用户界面中包含它们的*路径操作*。
+`APIRouter` 没有被「挂载」,它们与应用程序的其余部分没有隔离。
- 由于我们不能仅仅隔离它们并独立于其余部分来「挂载」它们,因此*路径操作*是被「克隆的」(重新创建),而不是直接包含。
+这是因为我们想要在 OpenAPI 模式和用户界面中包含它们的*路径操作*。
+
+由于我们不能仅仅隔离它们并独立于其余部分来「挂载」它们,因此*路径操作*是被「克隆的」(重新创建),而不是直接包含。
+
+///
## 查看自动化的 API 文档
diff --git a/docs/zh/docs/tutorial/body-fields.md b/docs/zh/docs/tutorial/body-fields.md
index 6c68f1008..4cff58bfc 100644
--- a/docs/zh/docs/tutorial/body-fields.md
+++ b/docs/zh/docs/tutorial/body-fields.md
@@ -6,101 +6,39 @@
首先,从 Pydantic 中导入 `Field`:
-=== "Python 3.10+"
+{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[4] *}
- ```Python hl_lines="4"
- {!> ../../../docs_src/body_fields/tutorial001_an_py310.py!}
- ```
+/// warning | 警告
-=== "Python 3.9+"
+注意,与从 `fastapi` 导入 `Query`,`Path`、`Body` 不同,要直接从 `pydantic` 导入 `Field` 。
- ```Python hl_lines="4"
- {!> ../../../docs_src/body_fields/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="4"
- {!> ../../../docs_src/body_fields/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
-
- ```Python hl_lines="2"
- {!> ../../../docs_src/body_fields/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
-
- ```Python hl_lines="4"
- {!> ../../../docs_src/body_fields/tutorial001.py!}
- ```
-
-!!! warning "警告"
-
- 注意,与从 `fastapi` 导入 `Query`,`Path`、`Body` 不同,要直接从 `pydantic` 导入 `Field` 。
+///
## 声明模型属性
然后,使用 `Field` 定义模型的属性:
-=== "Python 3.10+"
-
- ```Python hl_lines="11-14"
- {!> ../../../docs_src/body_fields/tutorial001_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="11-14"
- {!> ../../../docs_src/body_fields/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="12-15"
- {!> ../../../docs_src/body_fields/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="9-12"
- {!> ../../../docs_src/body_fields/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="11-14"
- {!> ../../../docs_src/body_fields/tutorial001.py!}
- ```
+{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[11:14] *}
`Field` 的工作方式和 `Query`、`Path`、`Body` 相同,参数也相同。
-!!! note "技术细节"
+/// note | 技术细节
- 实际上,`Query`、`Path` 都是 `Params` 的子类,而 `Params` 类又是 Pydantic 中 `FieldInfo` 的子类。
+实际上,`Query`、`Path` 都是 `Params` 的子类,而 `Params` 类又是 Pydantic 中 `FieldInfo` 的子类。
- Pydantic 的 `Field` 返回也是 `FieldInfo` 的类实例。
+Pydantic 的 `Field` 返回也是 `FieldInfo` 的类实例。
- `Body` 直接返回的也是 `FieldInfo` 的子类的对象。后文还会介绍一些 `Body` 的子类。
+`Body` 直接返回的也是 `FieldInfo` 的子类的对象。后文还会介绍一些 `Body` 的子类。
- 注意,从 `fastapi` 导入的 `Query`、`Path` 等对象实际上都是返回特殊类的函数。
+注意,从 `fastapi` 导入的 `Query`、`Path` 等对象实际上都是返回特殊类的函数。
-!!! tip "提示"
+///
- 注意,模型属性的类型、默认值及 `Field` 的代码结构与*路径操作函数*的参数相同,只不过是用 `Field` 替换了`Path`、`Query`、`Body`。
+/// tip | 提示
+
+注意,模型属性的类型、默认值及 `Field` 的代码结构与*路径操作函数*的参数相同,只不过是用 `Field` 替换了`Path`、`Query`、`Body`。
+
+///
## 添加更多信息
diff --git a/docs/zh/docs/tutorial/body-multiple-params.md b/docs/zh/docs/tutorial/body-multiple-params.md
index c93ef2f5c..b4356fdcb 100644
--- a/docs/zh/docs/tutorial/body-multiple-params.md
+++ b/docs/zh/docs/tutorial/body-multiple-params.md
@@ -8,44 +8,13 @@
你还可以通过将默认值设置为 `None` 来将请求体参数声明为可选参数:
-=== "Python 3.10+"
+{* ../../docs_src/body_multiple_params/tutorial001_an_py310.py hl[18:20] *}
- ```Python hl_lines="18-20"
- {!> ../../../docs_src/body_multiple_params/tutorial001_an_py310.py!}
- ```
+/// note
-=== "Python 3.9+"
+请注意,在这种情况下,将从请求体获取的 `item` 是可选的。因为它的默认值为 `None`。
- ```Python hl_lines="18-20"
- {!> ../../../docs_src/body_multiple_params/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="19-21"
- {!> ../../../docs_src/body_multiple_params/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
-
- ```Python hl_lines="17-19"
- {!> ../../../docs_src/body_multiple_params/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
-
- ```Python hl_lines="19-21"
- {!> ../../../docs_src/body_multiple_params/tutorial001.py!}
- ```
-
-!!! note
- 请注意,在这种情况下,将从请求体获取的 `item` 是可选的。因为它的默认值为 `None`。
+///
## 多个请求体参数
@@ -62,17 +31,7 @@
但是你也可以声明多个请求体参数,例如 `item` 和 `user`:
-=== "Python 3.10+"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_multiple_params/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/body_multiple_params/tutorial002.py!}
- ```
+{* ../../docs_src/body_multiple_params/tutorial002_py310.py hl[20] *}
在这种情况下,**FastAPI** 将注意到该函数中有多个请求体参数(两个 Pydantic 模型参数)。
@@ -93,9 +52,11 @@
}
```
-!!! note
- 请注意,即使 `item` 的声明方式与之前相同,但现在它被期望通过 `item` 键内嵌在请求体中。
+/// note
+请注意,即使 `item` 的声明方式与之前相同,但现在它被期望通过 `item` 键内嵌在请求体中。
+
+///
**FastAPI** 将自动对请求中的数据进行转换,因此 `item` 参数将接收指定的内容,`user` 参数也是如此。
@@ -112,41 +73,7 @@
但是你可以使用 `Body` 指示 **FastAPI** 将其作为请求体的另一个键进行处理。
-=== "Python 3.10+"
-
- ```Python hl_lines="23"
- {!> ../../../docs_src/body_multiple_params/tutorial003_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="23"
- {!> ../../../docs_src/body_multiple_params/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="24"
- {!> ../../../docs_src/body_multiple_params/tutorial003_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_multiple_params/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/body_multiple_params/tutorial003.py!}
- ```
+{* ../../docs_src/body_multiple_params/tutorial003_an_py310.py hl[23] *}
在这种情况下,**FastAPI** 将期望像这样的请求体:
@@ -181,45 +108,13 @@ q: str = None
比如:
-=== "Python 3.10+"
+{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[27] *}
- ```Python hl_lines="27"
- {!> ../../../docs_src/body_multiple_params/tutorial004_an_py310.py!}
- ```
+/// info
-=== "Python 3.9+"
-
- ```Python hl_lines="27"
- {!> ../../../docs_src/body_multiple_params/tutorial004_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="28"
- {!> ../../../docs_src/body_multiple_params/tutorial004_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
-
- ```Python hl_lines="25"
- {!> ../../../docs_src/body_multiple_params/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
-
- ```Python hl_lines="27"
- {!> ../../../docs_src/body_multiple_params/tutorial004.py!}
- ```
-
-!!! info
- `Body` 同样具有与 `Query`、`Path` 以及其他后面将看到的类完全相同的额外校验和元数据参数。
+`Body` 同样具有与 `Query`、`Path` 以及其他后面将看到的类完全相同的额外校验和元数据参数。
+///
## 嵌入单个请求体参数
@@ -235,41 +130,7 @@ item: Item = Body(embed=True)
比如:
-=== "Python 3.10+"
-
- ```Python hl_lines="17"
- {!> ../../../docs_src/body_multiple_params/tutorial005_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="17"
- {!> ../../../docs_src/body_multiple_params/tutorial005_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body_multiple_params/tutorial005_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
-
- ```Python hl_lines="15"
- {!> ../../../docs_src/body_multiple_params/tutorial005_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
-
- ```Python hl_lines="17"
- {!> ../../../docs_src/body_multiple_params/tutorial005.py!}
- ```
+{* ../../docs_src/body_multiple_params/tutorial005_an_py310.py hl[17] *}
在这种情况下,**FastAPI** 将期望像这样的请求体:
diff --git a/docs/zh/docs/tutorial/body-nested-models.md b/docs/zh/docs/tutorial/body-nested-models.md
index 3f519ae33..df96d96b4 100644
--- a/docs/zh/docs/tutorial/body-nested-models.md
+++ b/docs/zh/docs/tutorial/body-nested-models.md
@@ -6,17 +6,7 @@
你可以将一个属性定义为拥有子元素的类型。例如 Python `list`:
-=== "Python 3.10+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/body_nested_models/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="14"
- {!> ../../../docs_src/body_nested_models/tutorial001.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial001_py310.py hl[12] *}
这将使 `tags` 成为一个由元素组成的列表。不过它没有声明每个元素的类型。
@@ -28,9 +18,7 @@
首先,从 Python 的标准库 `typing` 模块中导入 `List`:
-```Python hl_lines="1"
-{!> ../../../docs_src/body_nested_models/tutorial002.py!}
-```
+{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *}
### 声明具有子类型的 List
@@ -51,23 +39,7 @@ my_list: List[str]
因此,在我们的示例中,我们可以将 `tags` 明确地指定为一个「字符串列表」:
-=== "Python 3.10+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/body_nested_models/tutorial002_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="14"
- {!> ../../../docs_src/body_nested_models/tutorial002_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="14"
- {!> ../../../docs_src/body_nested_models/tutorial002.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial002_py310.py hl[12] *}
## Set 类型
@@ -77,23 +49,7 @@ Python 具有一种特殊的数据类型来保存一组唯一的元素,即 `se
然后我们可以导入 `Set` 并将 `tag` 声明为一个由 `str` 组成的 `set`:
-=== "Python 3.10+"
-
- ```Python hl_lines="12"
- {!> ../../../docs_src/body_nested_models/tutorial003_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="14"
- {!> ../../../docs_src/body_nested_models/tutorial003_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="1 14"
- {!> ../../../docs_src/body_nested_models/tutorial003.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial003_py310.py hl[12] *}
这样,即使你收到带有重复数据的请求,这些数据也会被转换为一组唯一项。
@@ -115,45 +71,13 @@ Pydantic 模型的每个属性都具有类型。
例如,我们可以定义一个 `Image` 模型:
-=== "Python 3.10+"
-
- ```Python hl_lines="7-9"
- {!> ../../../docs_src/body_nested_models/tutorial004_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="9-11"
- {!> ../../../docs_src/body_nested_models/tutorial004_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9-11"
- {!> ../../../docs_src/body_nested_models/tutorial004.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[7:9] *}
### 将子模型用作类型
然后我们可以将其用作一个属性的类型:
-=== "Python 3.10+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body_nested_models/tutorial004_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_nested_models/tutorial004_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_nested_models/tutorial004.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[18] *}
这意味着 **FastAPI** 将期望类似于以下内容的请求体:
@@ -186,23 +110,7 @@ Pydantic 模型的每个属性都具有类型。
例如,在 `Image` 模型中我们有一个 `url` 字段,我们可以把它声明为 Pydantic 的 `HttpUrl`,而不是 `str`:
-=== "Python 3.10+"
-
- ```Python hl_lines="2 8"
- {!> ../../../docs_src/body_nested_models/tutorial005_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="4 10"
- {!> ../../../docs_src/body_nested_models/tutorial005_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="4 10"
- {!> ../../../docs_src/body_nested_models/tutorial005.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial005_py310.py hl[2,8] *}
该字符串将被检查是否为有效的 URL,并在 JSON Schema / OpenAPI 文档中进行记录。
@@ -210,23 +118,7 @@ Pydantic 模型的每个属性都具有类型。
你还可以将 Pydantic 模型用作 `list`、`set` 等的子类型:
-=== "Python 3.10+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body_nested_models/tutorial006_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_nested_models/tutorial006_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="20"
- {!> ../../../docs_src/body_nested_models/tutorial006.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial006_py310.py hl[18] *}
这将期望(转换,校验,记录文档等)下面这样的 JSON 请求体:
@@ -254,33 +146,23 @@ Pydantic 模型的每个属性都具有类型。
}
```
-!!! info
- 请注意 `images` 键现在具有一组 image 对象是如何发生的。
+/// info
+
+请注意 `images` 键现在具有一组 image 对象是如何发生的。
+
+///
## 深度嵌套模型
你可以定义任意深度的嵌套模型:
-=== "Python 3.10+"
+{* ../../docs_src/body_nested_models/tutorial007_py310.py hl[7,12,18,21,25] *}
- ```Python hl_lines="7 12 18 21 25"
- {!> ../../../docs_src/body_nested_models/tutorial007_py310.py!}
- ```
+/// info
-=== "Python 3.9+"
+请注意 `Offer` 拥有一组 `Item` 而反过来 `Item` 又是一个可选的 `Image` 列表是如何发生的。
- ```Python hl_lines="9 14 20 23 27"
- {!> ../../../docs_src/body_nested_models/tutorial007_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9 14 20 23 27"
- {!> ../../../docs_src/body_nested_models/tutorial007.py!}
- ```
-
-!!! info
- 请注意 `Offer` 拥有一组 `Item` 而反过来 `Item` 又是一个可选的 `Image` 列表是如何发生的。
+///
## 纯列表请求体
@@ -292,17 +174,7 @@ images: List[Image]
例如:
-=== "Python 3.9+"
-
- ```Python hl_lines="13"
- {!> ../../../docs_src/body_nested_models/tutorial008_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="15"
- {!> ../../../docs_src/body_nested_models/tutorial008.py!}
- ```
+{* ../../docs_src/body_nested_models/tutorial008_py39.py hl[13] *}
## 无处不在的编辑器支持
@@ -332,26 +204,19 @@ images: List[Image]
在下面的例子中,你将接受任意键为 `int` 类型并且值为 `float` 类型的 `dict`:
-=== "Python 3.9+"
+{* ../../docs_src/body_nested_models/tutorial009_py39.py hl[7] *}
- ```Python hl_lines="7"
- {!> ../../../docs_src/body_nested_models/tutorial009_py39.py!}
- ```
+/// tip
-=== "Python 3.8+"
+请记住 JSON 仅支持将 `str` 作为键。
- ```Python hl_lines="9"
- {!> ../../../docs_src/body_nested_models/tutorial009.py!}
- ```
+但是 Pydantic 具有自动转换数据的功能。
-!!! tip
- 请记住 JSON 仅支持将 `str` 作为键。
+这意味着,即使你的 API 客户端只能将字符串作为键发送,只要这些字符串内容仅包含整数,Pydantic 就会对其进行转换并校验。
- 但是 Pydantic 具有自动转换数据的功能。
+然后你接收的名为 `weights` 的 `dict` 实际上将具有 `int` 类型的键和 `float` 类型的值。
- 这意味着,即使你的 API 客户端只能将字符串作为键发送,只要这些字符串内容仅包含整数,Pydantic 就会对其进行转换并校验。
-
- 然后你接收的名为 `weights` 的 `dict` 实际上将具有 `int` 类型的键和 `float` 类型的值。
+///
## 总结
diff --git a/docs/zh/docs/tutorial/body-updates.md b/docs/zh/docs/tutorial/body-updates.md
index e529fc914..87f88f255 100644
--- a/docs/zh/docs/tutorial/body-updates.md
+++ b/docs/zh/docs/tutorial/body-updates.md
@@ -6,9 +6,7 @@
把输入数据转换为以 JSON 格式存储的数据(比如,使用 NoSQL 数据库时),可以使用 `jsonable_encoder`。例如,把 `datetime` 转换为 `str`。
-```Python hl_lines="30-35"
-{!../../../docs_src/body_updates/tutorial001.py!}
-```
+{* ../../docs_src/body_updates/tutorial001.py hl[30:35] *}
`PUT` 用于接收替换现有数据的数据。
@@ -34,15 +32,17 @@
即,只发送要更新的数据,其余数据保持不变。
-!!! note "笔记"
+/// note | 笔记
- `PATCH` 没有 `PUT` 知名,也怎么不常用。
+`PATCH` 没有 `PUT` 知名,也怎么不常用。
- 很多人甚至只用 `PUT` 实现部分更新。
+很多人甚至只用 `PUT` 实现部分更新。
- **FastAPI** 对此没有任何限制,可以**随意**互换使用这两种操作。
+**FastAPI** 对此没有任何限制,可以**随意**互换使用这两种操作。
- 但本指南也会分别介绍这两种操作各自的用途。
+但本指南也会分别介绍这两种操作各自的用途。
+
+///
### 使用 Pydantic 的 `exclude_unset` 参数
@@ -54,9 +54,7 @@
然后再用它生成一个只含已设置(在请求中所发送)数据,且省略了默认值的 `dict`:
-```Python hl_lines="34"
-{!../../../docs_src/body_updates/tutorial002.py!}
-```
+{* ../../docs_src/body_updates/tutorial002.py hl[34] *}
### 使用 Pydantic 的 `update` 参数
@@ -64,9 +62,7 @@
例如,`stored_item_model.copy(update=update_data)`:
-```Python hl_lines="35"
-{!../../../docs_src/body_updates/tutorial002.py!}
-```
+{* ../../docs_src/body_updates/tutorial002.py hl[35] *}
### 更新部分数据小结
@@ -83,19 +79,21 @@
* 把数据保存至数据库;
* 返回更新后的模型。
-```Python hl_lines="30-37"
-{!../../../docs_src/body_updates/tutorial002.py!}
-```
+{* ../../docs_src/body_updates/tutorial002.py hl[30:37] *}
-!!! tip "提示"
+/// tip | 提示
- 实际上,HTTP `PUT` 也可以完成相同的操作。
- 但本节以 `PATCH` 为例的原因是,该操作就是为了这种用例创建的。
+实际上,HTTP `PUT` 也可以完成相同的操作。
+但本节以 `PATCH` 为例的原因是,该操作就是为了这种用例创建的。
-!!! note "笔记"
+///
- 注意,输入模型仍需验证。
+/// note | 笔记
- 因此,如果希望接收的部分更新数据可以省略其他所有属性,则要把模型中所有的属性标记为可选(使用默认值或 `None`)。
+注意,输入模型仍需验证。
- 为了区分用于**更新**所有可选值的模型与用于**创建**包含必选值的模型,请参照[更多模型](extra-models.md){.internal-link target=_blank} 一节中的思路。
+因此,如果希望接收的部分更新数据可以省略其他所有属性,则要把模型中所有的属性标记为可选(使用默认值或 `None`)。
+
+为了区分用于**更新**所有可选值的模型与用于**创建**包含必选值的模型,请参照[更多模型](extra-models.md){.internal-link target=_blank} 一节中的思路。
+
+///
diff --git a/docs/zh/docs/tutorial/body.md b/docs/zh/docs/tutorial/body.md
index 65d459cd1..3820fc747 100644
--- a/docs/zh/docs/tutorial/body.md
+++ b/docs/zh/docs/tutorial/body.md
@@ -8,29 +8,21 @@ API 基本上肯定要发送**响应体**,但是客户端不一定发送**请
使用 Pydantic 模型声明**请求体**,能充分利用它的功能和优点。
-!!! info "说明"
+/// info | 说明
- 发送数据使用 `POST`(最常用)、`PUT`、`DELETE`、`PATCH` 等操作。
+发送数据使用 `POST`(最常用)、`PUT`、`DELETE`、`PATCH` 等操作。
- 规范中没有定义使用 `GET` 发送请求体的操作,但不管怎样,FastAPI 也支持这种方式,只不过仅用于非常复杂或极端的用例。
+规范中没有定义使用 `GET` 发送请求体的操作,但不管怎样,FastAPI 也支持这种方式,只不过仅用于非常复杂或极端的用例。
- 我们不建议使用 `GET`,因此,在 Swagger UI 交互文档中不会显示有关 `GET` 的内容,而且代理协议也不一定支持 `GET`。
+我们不建议使用 `GET`,因此,在 Swagger UI 交互文档中不会显示有关 `GET` 的内容,而且代理协议也不一定支持 `GET`。
+
+///
## 导入 Pydantic 的 `BaseModel`
从 `pydantic` 中导入 `BaseModel`:
-=== "Python 3.10+"
-
- ```Python hl_lines="2"
- {!> ../../../docs_src/body/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="4"
- {!> ../../../docs_src/body/tutorial001.py!}
- ```
+{* ../../docs_src/body/tutorial001_py310.py hl[2] *}
## 创建数据模型
@@ -38,17 +30,7 @@ API 基本上肯定要发送**响应体**,但是客户端不一定发送**请
使用 Python 标准类型声明所有属性:
-=== "Python 3.10+"
-
- ```Python hl_lines="5-9"
- {!> ../../../docs_src/body/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="7-11"
- {!> ../../../docs_src/body/tutorial001.py!}
- ```
+{* ../../docs_src/body/tutorial001_py310.py hl[5:9] *}
与声明查询参数一样,包含默认值的模型属性是可选的,否则就是必选的。默认值为 `None` 的模型属性也是可选的。
@@ -76,17 +58,7 @@ API 基本上肯定要发送**响应体**,但是客户端不一定发送**请
使用与声明路径和查询参数相同的方式声明请求体,把请求体添加至*路径操作*:
-=== "Python 3.10+"
-
- ```Python hl_lines="16"
- {!> ../../../docs_src/body/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body/tutorial001.py!}
- ```
+{* ../../docs_src/body/tutorial001_py310.py hl[16] *}
……此处,请求体参数的类型为 `Item` 模型。
@@ -135,33 +107,25 @@ Pydantic 模型的 JSON 概图是 OpenAPI 生成的概图部件,可在 API 文
-!!! tip "提示"
+/// tip | 提示
- 使用 PyCharm 编辑器时,推荐安装 Pydantic PyCharm 插件。
+使用 PyCharm 编辑器时,推荐安装 Pydantic PyCharm 插件。
- 该插件用于完善 PyCharm 对 Pydantic 模型的支持,优化的功能如下:
+该插件用于完善 PyCharm 对 Pydantic 模型的支持,优化的功能如下:
- * 自动补全
- * 类型检查
- * 代码重构
- * 查找
- * 代码审查
+* 自动补全
+* 类型检查
+* 代码重构
+* 查找
+* 代码审查
+
+///
## 使用模型
在*路径操作*函数内部直接访问模型对象的属性:
-=== "Python 3.10+"
-
- ```Python hl_lines="19"
- {!> ../../../docs_src/body/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="21"
- {!> ../../../docs_src/body/tutorial002.py!}
- ```
+{* ../../docs_src/body/tutorial002_py310.py hl[19] *}
## 请求体 + 路径参数
@@ -169,17 +133,7 @@ Pydantic 模型的 JSON 概图是 OpenAPI 生成的概图部件,可在 API 文
**FastAPI** 能识别与**路径参数**匹配的函数参数,还能识别从**请求体**中获取的类型为 Pydantic 模型的函数参数。
-=== "Python 3.10+"
-
- ```Python hl_lines="15-16"
- {!> ../../../docs_src/body/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="17-18"
- {!> ../../../docs_src/body/tutorial003.py!}
- ```
+{* ../../docs_src/body/tutorial003_py310.py hl[15:16] *}
## 请求体 + 路径参数 + 查询参数
@@ -187,17 +141,7 @@ Pydantic 模型的 JSON 概图是 OpenAPI 生成的概图部件,可在 API 文
**FastAPI** 能够正确识别这三种参数,并从正确的位置获取数据。
-=== "Python 3.10+"
-
- ```Python hl_lines="16"
- {!> ../../../docs_src/body/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/body/tutorial004.py!}
- ```
+{* ../../docs_src/body/tutorial004_py310.py hl[16] *}
函数参数按如下规则进行识别:
@@ -205,11 +149,13 @@ Pydantic 模型的 JSON 概图是 OpenAPI 生成的概图部件,可在 API 文
- 类型是(`int`、`float`、`str`、`bool` 等)**单类型**的参数,是**查询**参数
- 类型是 **Pydantic 模型**的参数,是**请求体**
-!!! note "笔记"
+/// note | 笔记
- 因为默认值是 `None`, FastAPI 会把 `q` 当作可选参数。
+因为默认值是 `None`, FastAPI 会把 `q` 当作可选参数。
- FastAPI 不使用 `Optional[str]` 中的 `Optional`, 但 `Optional` 可以让编辑器提供更好的支持,并检测错误。
+FastAPI 不使用 `Optional[str]` 中的 `Optional`, 但 `Optional` 可以让编辑器提供更好的支持,并检测错误。
+
+///
## 不使用 Pydantic
diff --git a/docs/zh/docs/tutorial/cookie-param-models.md b/docs/zh/docs/tutorial/cookie-param-models.md
new file mode 100644
index 000000000..6a7b09e25
--- /dev/null
+++ b/docs/zh/docs/tutorial/cookie-param-models.md
@@ -0,0 +1,76 @@
+# Cookie 参数模型
+
+如果您有一组相关的 **cookie**,您可以创建一个 **Pydantic 模型**来声明它们。🍪
+
+这将允许您在**多个地方**能够**重用模型**,并且可以一次性声明所有参数的验证方式和元数据。😎
+
+/// note
+
+自 FastAPI 版本 `0.115.0` 起支持此功能。🤓
+
+///
+
+/// tip
+
+此技术同样适用于 `Query` 、 `Cookie` 和 `Header` 。😎
+
+///
+
+## 带有 Pydantic 模型的 Cookie
+
+在 **Pydantic** 模型中声明所需的 **cookie** 参数,然后将参数声明为 `Cookie` :
+
+{* ../../docs_src/cookie_param_models/tutorial001_an_py310.py hl[9:12,16] *}
+
+**FastAPI** 将从请求中接收到的 **cookie** 中**提取**出**每个字段**的数据,并提供您定义的 Pydantic 模型。
+
+## 查看文档
+
+您可以在文档 UI 的 `/docs` 中查看定义的 cookie:
+
+
+get 操作
-!!! info "`@decorator` Info"
- `@something` 语法在 Python 中被称为「装饰器」。
+/// info | `@decorator` Info
- 像一顶漂亮的装饰帽一样,将它放在一个函数的上方(我猜测这个术语的命名就是这么来的)。
+`@something` 语法在 Python 中被称为「装饰器」。
- 装饰器接收位于其下方的函数并且用它完成一些工作。
+像一顶漂亮的装饰帽一样,将它放在一个函数的上方(我猜测这个术语的命名就是这么来的)。
- 在我们的例子中,这个装饰器告诉 **FastAPI** 位于其下方的函数对应着**路径** `/` 加上 `get` **操作**。
+装饰器接收位于其下方的函数并且用它完成一些工作。
- 它是一个「**路径操作装饰器**」。
+在我们的例子中,这个装饰器告诉 **FastAPI** 位于其下方的函数对应着**路径** `/` 加上 `get` **操作**。
+
+它是一个「**路径操作装饰器**」。
+
+///
你也可以使用其他的操作:
@@ -276,14 +264,17 @@ https://example.com/items/foo
* `@app.patch()`
* `@app.trace()`
-!!! tip
- 您可以随意使用任何一个操作(HTTP方法)。
+/// tip
- **FastAPI** 没有强制要求操作有任何特定的含义。
+你可以随意使用任何一个操作(HTTP方法)。
- 此处提供的信息仅作为指导,而不是要求。
+**FastAPI** 没有强制要求操作有任何特定的含义。
- 比如,当使用 GraphQL 时通常你所有的动作都通过 `post` 一种方法执行。
+此处提供的信息仅作为指导,而不是要求。
+
+比如,当使用 GraphQL 时通常你所有的动作都通过 `POST` 一种方法执行。
+
+///
### 步骤 4:定义**路径操作函数**
@@ -293,9 +284,7 @@ https://example.com/items/foo
* **操作**:是 `get`。
* **函数**:是位于「装饰器」下方的函数(位于 `@app.get("/")` 下方)。
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[7] *}
这是一个 Python 函数。
@@ -307,18 +296,17 @@ https://example.com/items/foo
你也可以将其定义为常规函数而不使用 `async def`:
-```Python hl_lines="7"
-{!../../../docs_src/first_steps/tutorial003.py!}
-```
+{* ../../docs_src/first_steps/tutorial003.py hl[7] *}
-!!! note
- 如果你不知道两者的区别,请查阅 [Async: *"In a hurry?"*](https://fastapi.tiangolo.com/async/#in-a-hurry){.internal-link target=_blank}。
+/// note
+
+如果你不知道两者的区别,请查阅 [并发: *赶时间吗?*](../async.md#_1){.internal-link target=_blank}。
+
+///
### 步骤 5:返回内容
-```Python hl_lines="8"
-{!../../../docs_src/first_steps/tutorial001.py!}
-```
+{* ../../docs_src/first_steps/tutorial001.py hl[8] *}
你可以返回一个 `dict`、`list`,像 `str`、`int` 一样的单个值,等等。
@@ -330,6 +318,6 @@ https://example.com/items/foo
* 导入 `FastAPI`。
* 创建一个 `app` 实例。
-* 编写一个**路径操作装饰器**(如 `@app.get("/")`)。
-* 编写一个**路径操作函数**(如上面的 `def root(): ...`)。
-* 运行开发服务器(如 `uvicorn main:app --reload`)。
+* 编写一个**路径操作装饰器**,如 `@app.get("/")`。
+* 定义一个**路径操作函数**,如 `def root(): ...`。
+* 使用命令 `fastapi dev` 运行开发服务器。
diff --git a/docs/zh/docs/tutorial/handling-errors.md b/docs/zh/docs/tutorial/handling-errors.md
index 701cd241e..0b887c292 100644
--- a/docs/zh/docs/tutorial/handling-errors.md
+++ b/docs/zh/docs/tutorial/handling-errors.md
@@ -25,10 +25,7 @@
### 导入 `HTTPException`
-```Python hl_lines="1"
-{!../../../docs_src/handling_errors/tutorial001.py!}
-
-```
+{* ../../docs_src/handling_errors/tutorial001.py hl[1] *}
### 触发 `HTTPException`
@@ -42,10 +39,7 @@
本例中,客户端用 `ID` 请求的 `item` 不存在时,触发状态码为 `404` 的异常:
-```Python hl_lines="11"
-{!../../../docs_src/handling_errors/tutorial001.py!}
-
-```
+{* ../../docs_src/handling_errors/tutorial001.py hl[11] *}
### 响应结果
@@ -67,14 +61,15 @@
```
-!!! tip "提示"
+/// tip | 提示
- 触发 `HTTPException` 时,可以用参数 `detail` 传递任何能转换为 JSON 的值,不仅限于 `str`。
+触发 `HTTPException` 时,可以用参数 `detail` 传递任何能转换为 JSON 的值,不仅限于 `str`。
- 还支持传递 `dict`、`list` 等数据结构。
+还支持传递 `dict`、`list` 等数据结构。
- **FastAPI** 能自动处理这些数据,并将之转换为 JSON。
+**FastAPI** 能自动处理这些数据,并将之转换为 JSON。
+///
## 添加自定义响应头
@@ -84,10 +79,7 @@
但对于某些高级应用场景,还是需要添加自定义响应头:
-```Python hl_lines="14"
-{!../../../docs_src/handling_errors/tutorial002.py!}
-
-```
+{* ../../docs_src/handling_errors/tutorial002.py hl[14] *}
## 安装自定义异常处理器
@@ -99,10 +91,7 @@
此时,可以用 `@app.exception_handler()` 添加自定义异常控制器:
-```Python hl_lines="5-7 13-18 24"
-{!../../../docs_src/handling_errors/tutorial003.py!}
-
-```
+{* ../../docs_src/handling_errors/tutorial003.py hl[5:7,13:18,24] *}
请求 `/unicorns/yolo` 时,路径操作会触发 `UnicornException`。
@@ -115,12 +104,13 @@
```
-!!! note "技术细节"
+/// note | 技术细节
- `from starlette.requests import Request` 和 `from starlette.responses import JSONResponse` 也可以用于导入 `Request` 和 `JSONResponse`。
+`from starlette.requests import Request` 和 `from starlette.responses import JSONResponse` 也可以用于导入 `Request` 和 `JSONResponse`。
- **FastAPI** 提供了与 `starlette.responses` 相同的 `fastapi.responses` 作为快捷方式,但大部分响应操作都可以直接从 Starlette 导入。同理,`Request` 也是如此。
+**FastAPI** 提供了与 `starlette.responses` 相同的 `fastapi.responses` 作为快捷方式,但大部分响应操作都可以直接从 Starlette 导入。同理,`Request` 也是如此。
+///
## 覆盖默认异常处理器
@@ -140,10 +130,7 @@
这样,异常处理器就可以接收 `Request` 与异常。
-```Python hl_lines="2 14-16"
-{!../../../docs_src/handling_errors/tutorial004.py!}
-
-```
+{* ../../docs_src/handling_errors/tutorial004.py hl[2,14:16] *}
访问 `/items/foo`,可以看到默认的 JSON 错误信息:
@@ -174,10 +161,11 @@ path -> item_id
### `RequestValidationError` vs `ValidationError`
-!!! warning "警告"
+/// warning | 警告
- 如果您觉得现在还用不到以下技术细节,可以先跳过下面的内容。
+如果您觉得现在还用不到以下技术细节,可以先跳过下面的内容。
+///
`RequestValidationError` 是 Pydantic 的 `ValidationError` 的子类。
@@ -195,17 +183,15 @@ path -> item_id
例如,只为错误返回纯文本响应,而不是返回 JSON 格式的内容:
-```Python hl_lines="3-4 9-11 22"
-{!../../../docs_src/handling_errors/tutorial004.py!}
+{* ../../docs_src/handling_errors/tutorial004.py hl[3:4,9:11,22] *}
-```
+/// note | 技术细节
-!!! note "技术细节"
+还可以使用 `from starlette.responses import PlainTextResponse`。
- 还可以使用 `from starlette.responses import PlainTextResponse`。
-
- **FastAPI** 提供了与 `starlette.responses` 相同的 `fastapi.responses` 作为快捷方式,但大部分响应都可以直接从 Starlette 导入。
+**FastAPI** 提供了与 `starlette.responses` 相同的 `fastapi.responses` 作为快捷方式,但大部分响应都可以直接从 Starlette 导入。
+///
### 使用 `RequestValidationError` 的请求体
@@ -213,10 +199,7 @@ path -> item_id
开发时,可以用这个请求体生成日志、调试错误,并返回给用户。
-```Python hl_lines="14"
-{!../../../docs_src/handling_errors/tutorial005.py!}
-
-```
+{* ../../docs_src/handling_errors/tutorial005.py hl[14] *}
现在试着发送一个无效的 `item`,例如:
@@ -279,10 +262,7 @@ FastAPI 支持先对异常进行某些处理,然后再使用 **FastAPI** 中
从 `fastapi.exception_handlers` 中导入要复用的默认异常处理器:
-```Python hl_lines="2-5 15 21"
-{!../../../docs_src/handling_errors/tutorial006.py!}
-
-```
+{* ../../docs_src/handling_errors/tutorial006.py hl[2:5,15,21] *}
虽然,本例只是输出了夸大其词的错误信息。
diff --git a/docs/zh/docs/tutorial/header-param-models.md b/docs/zh/docs/tutorial/header-param-models.md
new file mode 100644
index 000000000..13366aebc
--- /dev/null
+++ b/docs/zh/docs/tutorial/header-param-models.md
@@ -0,0 +1,56 @@
+# Header 参数模型
+
+如果您有一组相关的 **header 参数**,您可以创建一个 **Pydantic 模型**来声明它们。
+
+这将允许您在**多个地方**能够**重用模型**,并且可以一次性声明所有参数的验证和元数据。😎
+
+/// note
+
+自 FastAPI 版本 `0.115.0` 起支持此功能。🤓
+
+///
+
+## 使用 Pydantic 模型的 Header 参数
+
+在 **Pydantic 模型**中声明所需的 **header 参数**,然后将参数声明为 `Header` :
+
+{* ../../docs_src/header_param_models/tutorial001_an_py310.py hl[9:14,18] *}
+
+**FastAPI** 将从请求中接收到的 **headers** 中**提取**出**每个字段**的数据,并提供您定义的 Pydantic 模型。
+
+## 查看文档
+
+您可以在文档 UI 的 `/docs` 中查看所需的 headers:
+
+
+contact 字段| 参数 | Type | 描述 |
|---|---|---|
name | str | 联系人/组织的识别名称。 |
url | str | 指向联系信息的 URL。必须采用 URL 格式。 |
email | str | 联系人/组织的电子邮件地址。必须采用电子邮件地址的格式。 |
license_info 字段| 参数 | 类型 | 描述 |
|---|---|---|
name | str | 必须的 (如果设置了license_info). 用于 API 的许可证名称。 |
identifier | str | 一个API的SPDX许可证表达。 The identifier field is mutually exclusive of the url field. 自 OpenAPI 3.1.0、FastAPI 0.99.0 起可用。 |
url | str | 用于 API 的许可证的 URL。必须采用 URL 格式。 |
-
-## 标签元数据
-
-### 创建标签元数据
-
-让我们在带有标签的示例中为 `users` 和 `items` 试一下。
-
-创建标签元数据并把它传递给 `openapi_tags` 参数:
-
-```Python hl_lines="3-16 18"
-{!../../../docs_src/metadata/tutorial004.py!}
-```
-
-注意你可以在描述内使用 Markdown,例如「login」会显示为粗体(**login**)以及「fancy」会显示为斜体(_fancy_)。
-
-!!! tip "提示"
- 不必为你使用的所有标签都添加元数据。
-
-### 使用你的标签
-
-将 `tags` 参数和*路径操作*(以及 `APIRouter`)一起使用,将其分配给不同的标签:
-
-```Python hl_lines="21 26"
-{!../../../docs_src/metadata/tutorial004.py!}
-```
-
-!!! info "信息"
- 阅读更多关于标签的信息[路径操作配置](path-operation-configuration.md#tags){.internal-link target=_blank}。
-
-### 查看文档
-
-如果你现在查看文档,它们会显示所有附加的元数据:
-
-
-
-### 标签顺序
-
-每个标签元数据字典的顺序也定义了在文档用户界面显示的顺序。
-
-例如按照字母顺序,即使 `users` 排在 `items` 之后,它也会显示在前面,因为我们将它的元数据添加为列表内的第一个字典。
-
-## OpenAPI URL
-
-默认情况下,OpenAPI 模式服务于 `/openapi.json`。
-
-但是你可以通过参数 `openapi_url` 对其进行配置。
-
-例如,将其设置为服务于 `/api/v1/openapi.json`:
-
-```Python hl_lines="3"
-{!../../../docs_src/metadata/tutorial002.py!}
-```
-
-如果你想完全禁用 OpenAPI 模式,可以将其设置为 `openapi_url=None`,这样也会禁用使用它的文档用户界面。
-
-## 文档 URLs
-
-你可以配置两个文档用户界面,包括:
-
-* **Swagger UI**:服务于 `/docs`。
- * 可以使用参数 `docs_url` 设置它的 URL。
- * 可以通过设置 `docs_url=None` 禁用它。
-* ReDoc:服务于 `/redoc`。
- * 可以使用参数 `redoc_url` 设置它的 URL。
- * 可以通过设置 `redoc_url=None` 禁用它。
-
-例如,设置 Swagger UI 服务于 `/documentation` 并禁用 ReDoc:
-
-```Python hl_lines="3"
-{!../../../docs_src/metadata/tutorial003.py!}
-```
+# 元数据和文档 URL
+
+你可以在 FastAPI 应用程序中自定义多个元数据配置。
+
+## API 元数据
+
+你可以在设置 OpenAPI 规范和自动 API 文档 UI 中使用的以下字段:
+
+| 参数 | 类型 | 描述 |
+|------------|------|-------------|
+| `title` | `str` | API 的标题。 |
+| `summary` | `str` | API 的简短摘要。 自 OpenAPI 3.1.0、FastAPI 0.99.0 起可用。. |
+| `description` | `str` | API 的简短描述。可以使用Markdown。 |
+| `version` | `string` | API 的版本。这是您自己的应用程序的版本,而不是 OpenAPI 的版本。例如 `2.5.0` 。 |
+| `terms_of_service` | `str` | API 服务条款的 URL。如果提供,则必须是 URL。 |
+| `contact` | `dict` | 公开的 API 的联系信息。它可以包含多个字段。contact 字段| 参数 | Type | 描述 |
|---|---|---|
name | str | 联系人/组织的识别名称。 |
url | str | 指向联系信息的 URL。必须采用 URL 格式。 |
email | str | 联系人/组织的电子邮件地址。必须采用电子邮件地址的格式。 |
license_info 字段| 参数 | 类型 | 描述 |
|---|---|---|
name | str | 必须的 (如果设置了license_info). 用于 API 的许可证名称。 |
identifier | str | 一个API的SPDX许可证表达。 The identifier field is mutually exclusive of the url field. 自 OpenAPI 3.1.0、FastAPI 0.99.0 起可用。 |
url | str | 用于 API 的许可证的 URL。必须采用 URL 格式。 |
+
+## 标签元数据
+
+### 创建标签元数据
+
+让我们在带有标签的示例中为 `users` 和 `items` 试一下。
+
+创建标签元数据并把它传递给 `openapi_tags` 参数:
+
+{* ../../docs_src/metadata/tutorial004.py hl[3:16,18] *}
+
+注意你可以在描述内使用 Markdown,例如「login」会显示为粗体(**login**)以及「fancy」会显示为斜体(_fancy_)。
+
+/// tip | 提示
+
+不必为你使用的所有标签都添加元数据。
+
+///
+
+### 使用你的标签
+
+将 `tags` 参数和*路径操作*(以及 `APIRouter`)一起使用,将其分配给不同的标签:
+
+{* ../../docs_src/metadata/tutorial004.py hl[21,26] *}
+
+/// info | 信息
+
+阅读更多关于标签的信息[路径操作配置](path-operation-configuration.md#tags){.internal-link target=_blank}。
+
+///
+
+### 查看文档
+
+如果你现在查看文档,它们会显示所有附加的元数据:
+
+
+
+### 标签顺序
+
+每个标签元数据字典的顺序也定义了在文档用户界面显示的顺序。
+
+例如按照字母顺序,即使 `users` 排在 `items` 之后,它也会显示在前面,因为我们将它的元数据添加为列表内的第一个字典。
+
+## OpenAPI URL
+
+默认情况下,OpenAPI 模式服务于 `/openapi.json`。
+
+但是你可以通过参数 `openapi_url` 对其进行配置。
+
+例如,将其设置为服务于 `/api/v1/openapi.json`:
+
+{* ../../docs_src/metadata/tutorial002.py hl[3] *}
+
+如果你想完全禁用 OpenAPI 模式,可以将其设置为 `openapi_url=None`,这样也会禁用使用它的文档用户界面。
+
+## 文档 URLs
+
+你可以配置两个文档用户界面,包括:
+
+* **Swagger UI**:服务于 `/docs`。
+ * 可以使用参数 `docs_url` 设置它的 URL。
+ * 可以通过设置 `docs_url=None` 禁用它。
+* ReDoc:服务于 `/redoc`。
+ * 可以使用参数 `redoc_url` 设置它的 URL。
+ * 可以通过设置 `redoc_url=None` 禁用它。
+
+例如,设置 Swagger UI 服务于 `/documentation` 并禁用 ReDoc:
+
+{* ../../docs_src/metadata/tutorial003.py hl[3] *}
diff --git a/docs/zh/docs/tutorial/middleware.md b/docs/zh/docs/tutorial/middleware.md
index c9a7e7725..258ca7482 100644
--- a/docs/zh/docs/tutorial/middleware.md
+++ b/docs/zh/docs/tutorial/middleware.md
@@ -11,10 +11,13 @@
* 它可以对该**响应**做些什么或者执行任何需要的代码.
* 然后它返回这个 **响应**.
-!!! note "技术细节"
- 如果你使用了 `yield` 关键字依赖, 依赖中的退出代码将在执行中间件*后*执行.
+/// note | 技术细节
- 如果有任何后台任务(稍后记录), 它们将在执行中间件*后*运行.
+如果你使用了 `yield` 关键字依赖, 依赖中的退出代码将在执行中间件*后*执行.
+
+如果有任何后台任务(稍后记录), 它们将在执行中间件*后*运行.
+
+///
## 创建中间件
@@ -28,19 +31,23 @@
* 然后它将返回由相应的*路径操作*生成的 `response`.
* 然后你可以在返回 `response` 前进一步修改它.
-```Python hl_lines="8-9 11 14"
-{!../../../docs_src/middleware/tutorial001.py!}
-```
+{* ../../docs_src/middleware/tutorial001.py hl[8:9,11,14] *}
-!!! tip
- 请记住可以 用'X-' 前缀添加专有自定义请求头.
+/// tip
- 但是如果你想让浏览器中的客户端看到你的自定义请求头, 你需要把它们加到 CORS 配置 ([CORS (Cross-Origin Resource Sharing)](cors.md){.internal-link target=_blank}) 的 `expose_headers` 参数中,在 Starlette's CORS docs文档中.
+请记住可以 用'X-' 前缀添加专有自定义请求头.
-!!! note "技术细节"
- 你也可以使用 `from starlette.requests import Request`.
+但是如果你想让浏览器中的客户端看到你的自定义请求头, 你需要把它们加到 CORS 配置 ([CORS (Cross-Origin Resource Sharing)](cors.md){.internal-link target=_blank}) 的 `expose_headers` 参数中,在 Starlette's CORS docs文档中.
- **FastAPI** 为了开发者方便提供了该对象. 但其实它直接来自于 Starlette.
+///
+
+/// note | 技术细节
+
+你也可以使用 `from starlette.requests import Request`.
+
+**FastAPI** 为了开发者方便提供了该对象. 但其实它直接来自于 Starlette.
+
+///
### 在 `response` 的前和后
@@ -50,9 +57,7 @@
例如你可以添加自定义请求头 `X-Process-Time` 包含以秒为单位的接收请求和生成响应的时间:
-```Python hl_lines="10 12-13"
-{!../../../docs_src/middleware/tutorial001.py!}
-```
+{* ../../docs_src/middleware/tutorial001.py hl[10,12:13] *}
## 其他中间件
diff --git a/docs/zh/docs/tutorial/path-operation-configuration.md b/docs/zh/docs/tutorial/path-operation-configuration.md
index f79b0e692..adeca2d3f 100644
--- a/docs/zh/docs/tutorial/path-operation-configuration.md
+++ b/docs/zh/docs/tutorial/path-operation-configuration.md
@@ -2,9 +2,11 @@
*路径操作装饰器*支持多种配置参数。
-!!! warning "警告"
+/// warning | 警告
- 注意:以下参数应直接传递给**路径操作装饰器**,不能传递给*路径操作函数*。
+注意:以下参数应直接传递给**路径操作装饰器**,不能传递给*路径操作函数*。
+
+///
## `status_code` 状态码
@@ -14,25 +16,23 @@
如果记不住数字码的涵义,也可以用 `status` 的快捷常量:
-```Python hl_lines="3 17"
-{!../../../docs_src/path_operation_configuration/tutorial001.py!}
-```
+{* ../../docs_src/path_operation_configuration/tutorial001.py hl[3,17] *}
状态码在响应中使用,并会被添加到 OpenAPI 概图。
-!!! note "技术细节"
+/// note | 技术细节
- 也可以使用 `from starlette import status` 导入状态码。
+也可以使用 `from starlette import status` 导入状态码。
- **FastAPI** 的`fastapi.status` 和 `starlette.status` 一样,只是快捷方式。实际上,`fastapi.status` 直接继承自 Starlette。
+**FastAPI** 的`fastapi.status` 和 `starlette.status` 一样,只是快捷方式。实际上,`fastapi.status` 直接继承自 Starlette。
+
+///
## `tags` 参数
`tags` 参数的值是由 `str` 组成的 `list` (一般只有一个 `str` ),`tags` 用于为*路径操作*添加标签:
-```Python hl_lines="17 22 27"
-{!../../../docs_src/path_operation_configuration/tutorial002.py!}
-```
+{* ../../docs_src/path_operation_configuration/tutorial002.py hl[17,22,27] *}
OpenAPI 概图会自动添加标签,供 API 文档接口使用:
@@ -42,9 +42,7 @@ OpenAPI 概图会自动添加标签,供 API 文档接口使用:
路径装饰器还支持 `summary` 和 `description` 这两个参数:
-```Python hl_lines="20-21"
-{!../../../docs_src/path_operation_configuration/tutorial003.py!}
-```
+{* ../../docs_src/path_operation_configuration/tutorial003.py hl[20:21] *}
## 文档字符串(`docstring`)
@@ -52,9 +50,7 @@ OpenAPI 概图会自动添加标签,供 API 文档接口使用:
文档字符串支持 Markdown,能正确解析和显示 Markdown 的内容,但要注意文档字符串的缩进。
-```Python hl_lines="19-27"
-{!../../../docs_src/path_operation_configuration/tutorial004.py!}
-```
+{* ../../docs_src/path_operation_configuration/tutorial004.py hl[19:27] *}
下图为 Markdown 文本在 API 文档中的显示效果:
@@ -64,19 +60,21 @@ OpenAPI 概图会自动添加标签,供 API 文档接口使用:
`response_description` 参数用于定义响应的描述说明:
-```Python hl_lines="21"
-{!../../../docs_src/path_operation_configuration/tutorial005.py!}
-```
+{* ../../docs_src/path_operation_configuration/tutorial005.py hl[21] *}
-!!! info "说明"
+/// info | 说明
- 注意,`response_description` 只用于描述响应,`description` 一般则用于描述*路径操作*。
+注意,`response_description` 只用于描述响应,`description` 一般则用于描述*路径操作*。
-!!! check "检查"
+///
- OpenAPI 规定每个*路径操作*都要有响应描述。
+/// check | 检查
- 如果没有定义响应描述,**FastAPI** 则自动生成内容为 "Successful response" 的响应描述。
+OpenAPI 规定每个*路径操作*都要有响应描述。
+
+如果没有定义响应描述,**FastAPI** 则自动生成内容为 "Successful response" 的响应描述。
+
+///
@@ -84,9 +82,7 @@ OpenAPI 概图会自动添加标签,供 API 文档接口使用:
`deprecated` 参数可以把*路径操作*标记为弃用,无需直接删除:
-```Python hl_lines="16"
-{!../../../docs_src/path_operation_configuration/tutorial006.py!}
-```
+{* ../../docs_src/path_operation_configuration/tutorial006.py hl[16] *}
API 文档会把该路径操作标记为弃用:
diff --git a/docs/zh/docs/tutorial/path-params-numeric-validations.md b/docs/zh/docs/tutorial/path-params-numeric-validations.md
index 9b41ad7cf..ff6242835 100644
--- a/docs/zh/docs/tutorial/path-params-numeric-validations.md
+++ b/docs/zh/docs/tutorial/path-params-numeric-validations.md
@@ -6,41 +6,7 @@
首先,从 `fastapi` 导入 `Path`:
-=== "Python 3.10+"
-
- ```Python hl_lines="1 3"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="1 3"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="3-4"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
-
- ```Python hl_lines="1"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
-
- ```Python hl_lines="3"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001.py!}
- ```
+{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[1,3] *}
## 声明元数据
@@ -48,48 +14,17 @@
例如,要声明路径参数 `item_id`的 `title` 元数据值,你可以输入:
-=== "Python 3.10+"
+{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[10] *}
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py!}
- ```
+/// note
-=== "Python 3.9+"
+路径参数总是必需的,因为它必须是路径的一部分。
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an_py39.py!}
- ```
+所以,你应该在声明时使用 `...` 将其标记为必需参数。
-=== "Python 3.8+"
+然而,即使你使用 `None` 声明路径参数或设置一个其他默认值也不会有任何影响,它依然会是必需参数。
- ```Python hl_lines="11"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
-
- ```Python hl_lines="8"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
-
- ```Python hl_lines="10"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial001.py!}
- ```
-
-!!! note
- 路径参数总是必需的,因为它必须是路径的一部分。
-
- 所以,你应该在声明时使用 `...` 将其标记为必需参数。
-
- 然而,即使你使用 `None` 声明路径参数或设置一个其他默认值也不会有任何影响,它依然会是必需参数。
+///
## 按需对参数排序
@@ -107,14 +42,7 @@
因此,你可以将函数声明为:
-=== "Python 3.8 non-Annotated"
-
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/path_params_numeric_validations/tutorial002.py!}
- ```
+{* ../../docs_src/path_params_numeric_validations/tutorial002.py hl[7] *}
## 按需对参数排序的技巧
@@ -124,9 +52,7 @@
Python 不会对该 `*` 做任何事情,但是它将知道之后的所有参数都应作为关键字参数(键值对),也被称为 kwargs,来调用。即使它们没有默认值。
-```Python hl_lines="7"
-{!../../../docs_src/path_params_numeric_validations/tutorial003.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *}
## 数值校验:大于等于
@@ -134,9 +60,7 @@ Python 不会对该 `*` 做任何事情,但是它将知道之后的所有参
像下面这样,添加 `ge=1` 后,`item_id` 将必须是一个大于(`g`reater than)或等于(`e`qual)`1` 的整数。
-```Python hl_lines="8"
-{!../../../docs_src/path_params_numeric_validations/tutorial004.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial004.py hl[8] *}
## 数值校验:大于和小于等于
@@ -145,9 +69,7 @@ Python 不会对该 `*` 做任何事情,但是它将知道之后的所有参
* `gt`:大于(`g`reater `t`han)
* `le`:小于等于(`l`ess than or `e`qual)
-```Python hl_lines="9"
-{!../../../docs_src/path_params_numeric_validations/tutorial005.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial005.py hl[9] *}
## 数值校验:浮点数、大于和小于
@@ -159,9 +81,7 @@ Python 不会对该 `*` 做任何事情,但是它将知道之后的所有参
对于 lt 也是一样的。
-```Python hl_lines="11"
-{!../../../docs_src/path_params_numeric_validations/tutorial006.py!}
-```
+{* ../../docs_src/path_params_numeric_validations/tutorial006.py hl[11] *}
## 总结
@@ -174,18 +94,24 @@ Python 不会对该 `*` 做任何事情,但是它将知道之后的所有参
* `lt`:小于(`l`ess `t`han)
* `le`:小于等于(`l`ess than or `e`qual)
-!!! info
- `Query`、`Path` 以及你后面会看到的其他类继承自一个共同的 `Param` 类(不需要直接使用它)。
+/// info
- 而且它们都共享相同的所有你已看到并用于添加额外校验和元数据的参数。
+`Query`、`Path` 以及你后面会看到的其他类继承自一个共同的 `Param` 类(不需要直接使用它)。
-!!! note "技术细节"
- 当你从 `fastapi` 导入 `Query`、`Path` 和其他同类对象时,它们实际上是函数。
+而且它们都共享相同的所有你已看到并用于添加额外校验和元数据的参数。
- 当被调用时,它们返回同名类的实例。
+///
- 如此,你导入 `Query` 这个函数。当你调用它时,它将返回一个同样命名为 `Query` 的类的实例。
+/// note | 技术细节
- 因为使用了这些函数(而不是直接使用类),所以你的编辑器不会标记有关其类型的错误。
+当你从 `fastapi` 导入 `Query`、`Path` 和其他同类对象时,它们实际上是函数。
- 这样,你可以使用常规的编辑器和编码工具,而不必添加自定义配置来忽略这些错误。
+当被调用时,它们返回同名类的实例。
+
+如此,你导入 `Query` 这个函数。当你调用它时,它将返回一个同样命名为 `Query` 的类的实例。
+
+因为使用了这些函数(而不是直接使用类),所以你的编辑器不会标记有关其类型的错误。
+
+这样,你可以使用常规的编辑器和编码工具,而不必添加自定义配置来忽略这些错误。
+
+///
diff --git a/docs/zh/docs/tutorial/path-params.md b/docs/zh/docs/tutorial/path-params.md
index 12a08b4a3..ac9df0831 100644
--- a/docs/zh/docs/tutorial/path-params.md
+++ b/docs/zh/docs/tutorial/path-params.md
@@ -2,9 +2,7 @@
FastAPI 支持使用 Python 字符串格式化语法声明**路径参数**(**变量**):
-```Python hl_lines="6-7"
-{!../../../docs_src/path_params/tutorial001.py!}
-```
+{* ../../docs_src/path_params/tutorial001.py hl[6:7] *}
这段代码把路径参数 `item_id` 的值传递给路径函数的参数 `item_id`。
@@ -18,15 +16,15 @@ FastAPI 支持使用 Python 字符串格式化语法声明**路径参数**(**
使用 Python 标准类型注解,声明路径操作函数中路径参数的类型。
-```Python hl_lines="7"
-{!../../../docs_src/path_params/tutorial002.py!}
-```
+{* ../../docs_src/path_params/tutorial002.py hl[7] *}
本例把 `item_id` 的类型声明为 `int`。
-!!! check "检查"
+/// check | 检查
- 类型声明将为函数提供错误检查、代码补全等编辑器支持。
+类型声明将为函数提供错误检查、代码补全等编辑器支持。
+
+///
## 数据转换
@@ -36,11 +34,13 @@ FastAPI 支持使用 Python 字符串格式化语法声明**路径参数**(**
{"item_id":3}
```
-!!! check "检查"
+/// check | 检查
- 注意,函数接收并返回的值是 `3`( `int`),不是 `"3"`(`str`)。
+注意,函数接收并返回的值是 `3`( `int`),不是 `"3"`(`str`)。
- **FastAPI** 通过类型声明自动**解析**请求中的数据。
+**FastAPI** 通过类型声明自动**解析**请求中的数据。
+
+///
## 数据校验
@@ -65,13 +65,15 @@ FastAPI 支持使用 Python 字符串格式化语法声明**路径参数**(**
值的类型不是 `int ` 而是浮点数(`float`)时也会显示同样的错误,比如: http://127.0.0.1:8000/items/4.2。
-!!! check "检查"
+/// check | 检查
- **FastAPI** 使用 Python 类型声明实现了数据校验。
+**FastAPI** 使用 Python 类型声明实现了数据校验。
- 注意,上面的错误清晰地指出了未通过校验的具体原因。
+注意,上面的错误清晰地指出了未通过校验的具体原因。
- 这在开发调试与 API 交互的代码时非常有用。
+这在开发调试与 API 交互的代码时非常有用。
+
+///
## 查看文档
@@ -79,11 +81,13 @@ FastAPI 支持使用 Python 字符串格式化语法声明**路径参数**(**
-!!! check "检查"
+/// check | 检查
- 还是使用 Python 类型声明,**FastAPI** 提供了(集成 Swagger UI 的)API 文档。
+还是使用 Python 类型声明,**FastAPI** 提供了(集成 Swagger UI 的)API 文档。
- 注意,路径参数的类型是整数。
+注意,路径参数的类型是整数。
+
+///
## 基于标准的好处,备选文档
@@ -113,9 +117,7 @@ FastAPI 充分地利用了 枚举(即 enums)。
+Python 3.4 及之后版本支持枚举(即 enums)。
-!!! tip "提示"
+///
- **AlexNet**、**ResNet**、**LeNet** 是机器学习模型。
+/// tip | 提示
+
+**AlexNet**、**ResNet**、**LeNet** 是机器学习模型。
+
+///
### 声明*路径参数*
使用 Enum 类(`ModelName`)创建使用类型注解的*路径参数*:
-```Python hl_lines="16"
-{!../../../docs_src/path_params/tutorial005.py!}
-```
+{* ../../docs_src/path_params/tutorial005.py hl[16] *}
### 查看文档
@@ -165,21 +167,19 @@ FastAPI 充分地利用了
+
+
+
+## 禁止额外的查询参数
+
+在一些特殊的使用场景中(可能不是很常见),你可能希望**限制**你要接收的查询参数。
+
+你可以使用 Pydantic 的模型配置来 `forbid`(意为禁止 —— 译者注)任何 `extra`(意为额外的 —— 译者注)字段:
+
+{* ../../docs_src/query_param_models/tutorial002_an_py310.py hl[10] *}
+
+假设有一个客户端尝试在**查询参数**中发送一些**额外的**数据,它将会收到一个**错误**响应。
+
+例如,如果客户端尝试发送一个值为 `plumbus` 的 `tool` 查询参数,如:
+
+```http
+https://example.com/items/?limit=10&tool=plumbus
+```
+
+他们将收到一个**错误**响应,告诉他们查询参数 `tool` 是不允许的:
+
+```json
+{
+ "detail": [
+ {
+ "type": "extra_forbidden",
+ "loc": ["query", "tool"],
+ "msg": "Extra inputs are not permitted",
+ "input": "plumbus"
+ }
+ ]
+}
+```
+
+## 总结
+
+你可以使用 **Pydantic 模型**在 **FastAPI** 中声明**查询参数**。😎
+
+/// tip
+
+剧透警告:你也可以使用 Pydantic 模型来声明 cookie 和 headers,但你将在本教程的后面部分阅读到这部分内容。🤫
+
+///
diff --git a/docs/zh/docs/tutorial/query-params-str-validations.md b/docs/zh/docs/tutorial/query-params-str-validations.md
index af0428837..c2f9a7e9f 100644
--- a/docs/zh/docs/tutorial/query-params-str-validations.md
+++ b/docs/zh/docs/tutorial/query-params-str-validations.md
@@ -4,17 +4,7 @@
让我们以下面的应用程序为例:
-=== "Python 3.10+"
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params_str_validations/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params_str_validations/tutorial001.py!}
- ```
+{* ../../docs_src/query_params_str_validations/tutorial001_py310.py hl[7] *}
查询参数 `q` 的类型为 `str`,默认值为 `None`,因此它是可选的。
@@ -26,17 +16,13 @@
为此,首先从 `fastapi` 导入 `Query`:
-```Python hl_lines="1"
-{!../../../docs_src/query_params_str_validations/tutorial002.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial002.py hl[1] *}
## 使用 `Query` 作为默认值
现在,将 `Query` 用作查询参数的默认值,并将它的 `max_length` 参数设置为 50:
-```Python hl_lines="9"
-{!../../../docs_src/query_params_str_validations/tutorial002.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial002.py hl[9] *}
由于我们必须用 `Query(default=None)` 替换默认值 `None`,`Query` 的第一个参数同样也是用于定义默认值。
@@ -66,17 +52,13 @@ q: Union[str, None] = Query(default=None, max_length=50)
你还可以添加 `min_length` 参数:
-```Python hl_lines="10"
-{!../../../docs_src/query_params_str_validations/tutorial003.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial003.py hl[10] *}
## 添加正则表达式
你可以定义一个参数值必须匹配的正则表达式:
-```Python hl_lines="11"
-{!../../../docs_src/query_params_str_validations/tutorial004.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial004.py hl[11] *}
这个指定的正则表达式通过以下规则检查接收到的参数值:
@@ -94,12 +76,13 @@ q: Union[str, None] = Query(default=None, max_length=50)
假设你想要声明查询参数 `q`,使其 `min_length` 为 `3`,并且默认值为 `fixedquery`:
-```Python hl_lines="7"
-{!../../../docs_src/query_params_str_validations/tutorial005.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial005.py hl[7] *}
-!!! note
- 具有默认值还会使该参数成为可选参数。
+/// note
+
+具有默认值还会使该参数成为可选参数。
+
+///
## 声明为必需参数
@@ -123,23 +106,7 @@ q: Union[str, None] = Query(default=None, min_length=3)
因此,当你在使用 `Query` 且需要声明一个值是必需的时,只需不声明默认参数:
-```Python hl_lines="7"
-{!../../../docs_src/query_params_str_validations/tutorial006.py!}
-```
-
-### 使用省略号(`...`)声明必需参数
-
-有另一种方法可以显式的声明一个值是必需的,即将默认参数的默认值设为 `...` :
-
-```Python hl_lines="7"
-{!../../../docs_src/query_params_str_validations/tutorial006b.py!}
-```
-
-!!! info
- 如果你之前没见过 `...` 这种用法:它是一个特殊的单独值,它是 Python 的一部分并且被称为「省略号」。
- Pydantic 和 FastAPI 使用它来显式的声明需要一个值。
-
-这将使 **FastAPI** 知道此查询参数是必需的。
+{* ../../docs_src/query_params_str_validations/tutorial006.py hl[7] *}
### 使用`None`声明必需参数
@@ -147,24 +114,13 @@ q: Union[str, None] = Query(default=None, min_length=3)
为此,你可以声明`None`是一个有效的类型,并仍然使用`default=...`:
-```Python hl_lines="9"
-{!../../../docs_src/query_params_str_validations/tutorial006c.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial006c.py hl[9] *}
-!!! tip
- Pydantic 是 FastAPI 中所有数据验证和序列化的核心,当你在没有设默认值的情况下使用 `Optional` 或 `Union[Something, None]` 时,它具有特殊行为,你可以在 Pydantic 文档中阅读有关必需可选字段的更多信息。
+/// tip
-### 使用Pydantic中的`Required`代替省略号(`...`)
-
-如果你觉得使用 `...` 不舒服,你也可以从 Pydantic 导入并使用 `Required`:
-
-```Python hl_lines="2 8"
-{!../../../docs_src/query_params_str_validations/tutorial006d.py!}
-```
-
-!!! tip
- 请记住,在大多数情况下,当你需要某些东西时,可以简单地省略 `default` 参数,因此你通常不必使用 `...` 或 `Required`
+Pydantic 是 FastAPI 中所有数据验证和序列化的核心,当你在没有设默认值的情况下使用 `Optional` 或 `Union[Something, None]` 时,它具有特殊行为,你可以在 Pydantic 文档中阅读有关必需可选字段的更多信息。
+///
## 查询参数列表 / 多个值
@@ -172,9 +128,7 @@ q: Union[str, None] = Query(default=None, min_length=3)
例如,要声明一个可在 URL 中出现多次的查询参数 `q`,你可以这样写:
-```Python hl_lines="9"
-{!../../../docs_src/query_params_str_validations/tutorial011.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial011.py hl[9] *}
然后,输入如下网址:
@@ -195,8 +149,11 @@ http://localhost:8000/items/?q=foo&q=bar
}
```
-!!! tip
- 要声明类型为 `list` 的查询参数,如上例所示,你需要显式地使用 `Query`,否则该参数将被解释为请求体。
+/// tip
+
+要声明类型为 `list` 的查询参数,如上例所示,你需要显式地使用 `Query`,否则该参数将被解释为请求体。
+
+///
交互式 API 文档将会相应地进行更新,以允许使用多个值:
@@ -206,9 +163,7 @@ http://localhost:8000/items/?q=foo&q=bar
你还可以定义在没有任何给定值时的默认 `list` 值:
-```Python hl_lines="9"
-{!../../../docs_src/query_params_str_validations/tutorial012.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial012.py hl[9] *}
如果你访问:
@@ -231,14 +186,15 @@ http://localhost:8000/items/
你也可以直接使用 `list` 代替 `List [str]`:
-```Python hl_lines="7"
-{!../../../docs_src/query_params_str_validations/tutorial013.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial013.py hl[7] *}
-!!! note
- 请记住,在这种情况下 FastAPI 将不会检查列表的内容。
+/// note
- 例如,`List[int]` 将检查(并记录到文档)列表的内容必须是整数。但是单独的 `list` 不会。
+请记住,在这种情况下 FastAPI 将不会检查列表的内容。
+
+例如,`List[int]` 将检查(并记录到文档)列表的内容必须是整数。但是单独的 `list` 不会。
+
+///
## 声明更多元数据
@@ -246,22 +202,21 @@ http://localhost:8000/items/
这些信息将包含在生成的 OpenAPI 模式中,并由文档用户界面和外部工具所使用。
-!!! note
- 请记住,不同的工具对 OpenAPI 的支持程度可能不同。
+/// note
- 其中一些可能不会展示所有已声明的额外信息,尽管在大多数情况下,缺少的这部分功能已经计划进行开发。
+请记住,不同的工具对 OpenAPI 的支持程度可能不同。
+
+其中一些可能不会展示所有已声明的额外信息,尽管在大多数情况下,缺少的这部分功能已经计划进行开发。
+
+///
你可以添加 `title`:
-```Python hl_lines="10"
-{!../../../docs_src/query_params_str_validations/tutorial007.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial007.py hl[10] *}
以及 `description`:
-```Python hl_lines="13"
-{!../../../docs_src/query_params_str_validations/tutorial008.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial008.py hl[13] *}
## 别名参数
@@ -281,9 +236,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems
这时你可以用 `alias` 参数声明一个别名,该别名将用于在 URL 中查找查询参数值:
-```Python hl_lines="9"
-{!../../../docs_src/query_params_str_validations/tutorial009.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial009.py hl[9] *}
## 弃用参数
@@ -293,9 +246,7 @@ http://127.0.0.1:8000/items/?item-query=foobaritems
那么将参数 `deprecated=True` 传入 `Query`:
-```Python hl_lines="18"
-{!../../../docs_src/query_params_str_validations/tutorial010.py!}
-```
+{* ../../docs_src/query_params_str_validations/tutorial010.py hl[18] *}
文档将会像下面这样展示它:
diff --git a/docs/zh/docs/tutorial/query-params.md b/docs/zh/docs/tutorial/query-params.md
index 77138de51..cc2e74b9e 100644
--- a/docs/zh/docs/tutorial/query-params.md
+++ b/docs/zh/docs/tutorial/query-params.md
@@ -2,9 +2,7 @@
声明的参数不是路径参数时,路径操作函数会把该参数自动解释为**查询**参数。
-```Python hl_lines="9"
-{!../../../docs_src/query_params/tutorial001.py!}
-```
+{* ../../docs_src/query_params/tutorial001.py hl[9] *}
查询字符串是键值对的集合,这些键值对位于 URL 的 `?` 之后,以 `&` 分隔。
@@ -63,38 +61,30 @@ http://127.0.0.1:8000/items/?skip=20
同理,把默认值设为 `None` 即可声明**可选的**查询参数:
-=== "Python 3.10+"
-
- ```Python hl_lines="7"
- {!> ../../../docs_src/query_params/tutorial002_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9"
- {!> ../../../docs_src/query_params/tutorial002.py!}
- ```
-
+{* ../../docs_src/query_params/tutorial002_py310.py hl[7] *}
本例中,查询参数 `q` 是可选的,默认值为 `None`。
-!!! check "检查"
+/// check | 检查
- 注意,**FastAPI** 可以识别出 `item_id` 是路径参数,`q` 不是路径参数,而是查询参数。
+注意,**FastAPI** 可以识别出 `item_id` 是路径参数,`q` 不是路径参数,而是查询参数。
-!!! note "笔记"
+///
- 因为默认值为 `= None`,FastAPI 把 `q` 识别为可选参数。
+/// note | 笔记
- FastAPI 不使用 `Optional[str]` 中的 `Optional`(只使用 `str`),但 `Optional[str]` 可以帮助编辑器发现代码中的错误。
+因为默认值为 `= None`,FastAPI 把 `q` 识别为可选参数。
+
+FastAPI 不使用 `Optional[str]` 中的 `Optional`(只使用 `str`),但 `Optional[str]` 可以帮助编辑器发现代码中的错误。
+
+///
## 查询参数类型转换
参数还可以声明为 `bool` 类型,FastAPI 会自动转换参数类型:
-```Python hl_lines="9"
-{!../../../docs_src/query_params/tutorial003.py!}
-```
+
+{* ../../docs_src/query_params/tutorial003_py310.py hl[7] *}
本例中,访问:
@@ -137,9 +127,7 @@ http://127.0.0.1:8000/items/foo?short=yes
FastAPI 通过参数名进行检测:
-```Python hl_lines="8 10"
-{!../../../docs_src/query_params/tutorial004.py!}
-```
+{* ../../docs_src/query_params/tutorial004_py310.py hl[6,8] *}
## 必选查询参数
@@ -149,9 +137,7 @@ FastAPI 通过参数名进行检测:
如果要把查询参数设置为**必选**,就不要声明默认值:
-```Python hl_lines="6-7"
-{!../../../docs_src/query_params/tutorial005.py!}
-```
+{* ../../docs_src/query_params/tutorial005.py hl[6:7] *}
这里的查询参数 `needy` 是类型为 `str` 的必选查询参数。
@@ -195,9 +181,7 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
当然,把一些参数定义为必选,为另一些参数设置默认值,再把其它参数定义为可选,这些操作都是可以的:
-```Python hl_lines="10"
-{!../../../docs_src/query_params/tutorial006.py!}
-```
+{* ../../docs_src/query_params/tutorial006_py310.py hl[8] *}
本例中有 3 个查询参数:
@@ -205,5 +189,8 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
* `skip`,默认值为 `0` 的 `int` 类型参数
* `limit`,可选的 `int` 类型参数
-!!! tip "提示"
- 还可以像在[路径参数](path-params.md#_8){.internal-link target=_blank} 中那样使用 `Enum`。
+/// tip | 提示
+
+还可以像在[路径参数](path-params.md#_8){.internal-link target=_blank} 中那样使用 `Enum`。
+
+///
diff --git a/docs/zh/docs/tutorial/request-files.md b/docs/zh/docs/tutorial/request-files.md
index 1cd3518cf..81ddc7238 100644
--- a/docs/zh/docs/tutorial/request-files.md
+++ b/docs/zh/docs/tutorial/request-files.md
@@ -2,39 +2,41 @@
`File` 用于定义客户端的上传文件。
-!!! info "说明"
+/// info | 说明
- 因为上传文件以「表单数据」形式发送。
+因为上传文件以「表单数据」形式发送。
- 所以接收上传文件,要预先安装 `python-multipart`。
+所以接收上传文件,要预先安装 `python-multipart`。
- 例如: `pip install python-multipart`。
+例如: `pip install python-multipart`。
+
+///
## 导入 `File`
从 `fastapi` 导入 `File` 和 `UploadFile`:
-```Python hl_lines="1"
-{!../../../docs_src/request_files/tutorial001.py!}
-```
+{* ../../docs_src/request_files/tutorial001.py hl[1] *}
## 定义 `File` 参数
创建文件(`File`)参数的方式与 `Body` 和 `Form` 一样:
-```Python hl_lines="7"
-{!../../../docs_src/request_files/tutorial001.py!}
-```
+{* ../../docs_src/request_files/tutorial001.py hl[7] *}
-!!! info "说明"
+/// info | 说明
- `File` 是直接继承自 `Form` 的类。
+`File` 是直接继承自 `Form` 的类。
- 注意,从 `fastapi` 导入的 `Query`、`Path`、`File` 等项,实际上是返回特定类的函数。
+注意,从 `fastapi` 导入的 `Query`、`Path`、`File` 等项,实际上是返回特定类的函数。
-!!! tip "提示"
+///
- 声明文件体必须使用 `File`,否则,FastAPI 会把该参数当作查询参数或请求体(JSON)参数。
+/// tip | 提示
+
+声明文件体必须使用 `File`,否则,FastAPI 会把该参数当作查询参数或请求体(JSON)参数。
+
+///
文件作为「表单数据」上传。
@@ -48,9 +50,7 @@
定义文件参数时使用 `UploadFile`:
-```Python hl_lines="12"
-{!../../../docs_src/request_files/tutorial001.py!}
-```
+{* ../../docs_src/request_files/tutorial001.py hl[12] *}
`UploadFile` 与 `bytes` 相比有更多优势:
@@ -92,13 +92,17 @@ contents = await myfile.read()
contents = myfile.file.read()
```
-!!! note "`async` 技术细节"
+/// note | `async` 技术细节
- 使用 `async` 方法时,**FastAPI** 在线程池中执行文件方法,并 `await` 操作完成。
+使用 `async` 方法时,**FastAPI** 在线程池中执行文件方法,并 `await` 操作完成。
-!!! note "Starlette 技术细节"
+///
- **FastAPI** 的 `UploadFile` 直接继承自 **Starlette** 的 `UploadFile`,但添加了一些必要功能,使之与 **Pydantic** 及 FastAPI 的其它部件兼容。
+/// note | Starlette 技术细节
+
+**FastAPI** 的 `UploadFile` 直接继承自 **Starlette** 的 `UploadFile`,但添加了一些必要功能,使之与 **Pydantic** 及 FastAPI 的其它部件兼容。
+
+///
## 什么是 「表单数据」
@@ -106,43 +110,35 @@ contents = myfile.file.read()
**FastAPI** 要确保从正确的位置读取数据,而不是读取 JSON。
-!!! note "技术细节"
+/// note | 技术细节
- 不包含文件时,表单数据一般用 `application/x-www-form-urlencoded`「媒体类型」编码。
+不包含文件时,表单数据一般用 `application/x-www-form-urlencoded`「媒体类型」编码。
- 但表单包含文件时,编码为 `multipart/form-data`。使用了 `File`,**FastAPI** 就知道要从请求体的正确位置获取文件。
+但表单包含文件时,编码为 `multipart/form-data`。使用了 `File`,**FastAPI** 就知道要从请求体的正确位置获取文件。
- 编码和表单字段详见 MDN Web 文档的 POST 小节。
+编码和表单字段详见 MDN Web 文档的 POST 小节。
-!!! warning "警告"
+///
- 可在一个*路径操作*中声明多个 `File` 和 `Form` 参数,但不能同时声明要接收 JSON 的 `Body` 字段。因为此时请求体的编码是 `multipart/form-data`,不是 `application/json`。
+/// warning | 警告
- 这不是 **FastAPI** 的问题,而是 HTTP 协议的规定。
+可在一个*路径操作*中声明多个 `File` 和 `Form` 参数,但不能同时声明要接收 JSON 的 `Body` 字段。因为此时请求体的编码是 `multipart/form-data`,不是 `application/json`。
+
+这不是 **FastAPI** 的问题,而是 HTTP 协议的规定。
+
+///
## 可选文件上传
您可以通过使用标准类型注解并将 None 作为默认值的方式将一个文件参数设为可选:
-=== "Python 3.9+"
-
- ```Python hl_lines="7 14"
- {!> ../../../docs_src/request_files/tutorial001_02_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9 17"
- {!> ../../../docs_src/request_files/tutorial001_02.py!}
- ```
+{* ../../docs_src/request_files/tutorial001_02_py310.py hl[7,14] *}
## 带有额外元数据的 `UploadFile`
您也可以将 `File()` 与 `UploadFile` 一起使用,例如,设置额外的元数据:
-```Python hl_lines="13"
-{!../../../docs_src/request_files/tutorial001_03.py!}
-```
+{* ../../docs_src/request_files/tutorial001_03.py hl[13] *}
## 多文件上传
@@ -152,42 +148,24 @@ FastAPI 支持同时上传多个文件。
上传多个文件时,要声明含 `bytes` 或 `UploadFile` 的列表(`List`):
-=== "Python 3.9+"
-
- ```Python hl_lines="8 13"
- {!> ../../../docs_src/request_files/tutorial002_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="10 15"
- {!> ../../../docs_src/request_files/tutorial002.py!}
- ```
+{* ../../docs_src/request_files/tutorial002_py39.py hl[8,13] *}
接收的也是含 `bytes` 或 `UploadFile` 的列表(`list`)。
-!!! note "技术细节"
+/// note | 技术细节
- 也可以使用 `from starlette.responses import HTMLResponse`。
+也可以使用 `from starlette.responses import HTMLResponse`。
- `fastapi.responses` 其实与 `starlette.responses` 相同,只是为了方便开发者调用。实际上,大多数 **FastAPI** 的响应都直接从 Starlette 调用。
+`fastapi.responses` 其实与 `starlette.responses` 相同,只是为了方便开发者调用。实际上,大多数 **FastAPI** 的响应都直接从 Starlette 调用。
+
+///
### 带有额外元数据的多文件上传
和之前的方式一样, 您可以为 `File()` 设置额外参数, 即使是 `UploadFile`:
-=== "Python 3.9+"
-
- ```Python hl_lines="16"
- {!> ../../../docs_src/request_files/tutorial003_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="18"
- {!> ../../../docs_src/request_files/tutorial003.py!}
- ```
+{* ../../docs_src/request_files/tutorial003_py39.py hl[16] *}
## 小结
diff --git a/docs/zh/docs/tutorial/request-form-models.md b/docs/zh/docs/tutorial/request-form-models.md
new file mode 100644
index 000000000..e639e4b9f
--- /dev/null
+++ b/docs/zh/docs/tutorial/request-form-models.md
@@ -0,0 +1,78 @@
+# 表单模型
+
+您可以使用 **Pydantic 模型**在 FastAPI 中声明**表单字段**。
+
+/// info
+
+要使用表单,需预先安装 `python-multipart` 。
+
+确保您创建、激活一个[虚拟环境](../virtual-environments.md){.internal-link target=_blank}后再安装。
+
+```console
+$ pip install python-multipart
+```
+
+///
+
+/// note
+
+自 FastAPI 版本 `0.113.0` 起支持此功能。🤓
+
+///
+
+## 表单的 Pydantic 模型
+
+您只需声明一个 **Pydantic 模型**,其中包含您希望接收的**表单字段**,然后将参数声明为 `Form` :
+
+{* ../../docs_src/request_form_models/tutorial001_an_py39.py hl[9:11,15] *}
+
+**FastAPI** 将从请求中的**表单数据**中**提取**出**每个字段**的数据,并提供您定义的 Pydantic 模型。
+
+## 检查文档
+
+您可以在文档 UI 中验证它,地址为 `/docs` :
+
+
+POST小节。
+编码和表单字段详见 MDN Web 文档的 POST小节。
-!!! warning "警告"
+///
- 可在一个*路径操作*中声明多个 `Form` 参数,但不能同时声明要接收 JSON 的 `Body` 字段。因为此时请求体的编码是 `application/x-www-form-urlencoded`,不是 `application/json`。
+/// warning | 警告
- 这不是 **FastAPI** 的问题,而是 HTTP 协议的规定。
+可在一个*路径操作*中声明多个 `Form` 参数,但不能同时声明要接收 JSON 的 `Body` 字段。因为此时请求体的编码是 `application/x-www-form-urlencoded`,不是 `application/json`。
+
+这不是 **FastAPI** 的问题,而是 HTTP 协议的规定。
+
+///
## 小结
diff --git a/docs/zh/docs/tutorial/response-model.md b/docs/zh/docs/tutorial/response-model.md
index 0f1b3b4b9..049cd1223 100644
--- a/docs/zh/docs/tutorial/response-model.md
+++ b/docs/zh/docs/tutorial/response-model.md
@@ -8,26 +8,13 @@
* `@app.delete()`
* 等等。
-=== "Python 3.10+"
+{* ../../docs_src/response_model/tutorial001_py310.py hl[17,22,24:27] *}
- ```Python hl_lines="17 22 24-27"
- {!> ../../../docs_src/response_model/tutorial001_py310.py!}
- ```
+/// note
-=== "Python 3.9+"
+注意,`response_model`是「装饰器」方法(`get`,`post` 等)的一个参数。不像之前的所有参数和请求体,它不属于*路径操作函数*。
- ```Python hl_lines="17 22 24-27"
- {!> ../../../docs_src/response_model/tutorial001_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="17 22 24-27"
- {!> ../../../docs_src/response_model/tutorial001.py!}
- ```
-
-!!! note
- 注意,`response_model`是「装饰器」方法(`get`,`post` 等)的一个参数。不像之前的所有参数和请求体,它不属于*路径操作函数*。
+///
它接收的类型与你将为 Pydantic 模型属性所声明的类型相同,因此它可以是一个 Pydantic 模型,但也可以是一个由 Pydantic 模型组成的 `list`,例如 `List[Item]`。
@@ -42,22 +29,21 @@ FastAPI 将使用此 `response_model` 来:
* 会将输出数据限制在该模型定义内。下面我们会看到这一点有多重要。
-!!! note "技术细节"
- 响应模型在参数中被声明,而不是作为函数返回类型的注解,这是因为路径函数可能不会真正返回该响应模型,而是返回一个 `dict`、数据库对象或其他模型,然后再使用 `response_model` 来执行字段约束和序列化。
+/// note | 技术细节
+
+响应模型在参数中被声明,而不是作为函数返回类型的注解,这是因为路径函数可能不会真正返回该响应模型,而是返回一个 `dict`、数据库对象或其他模型,然后再使用 `response_model` 来执行字段约束和序列化。
+
+///
## 返回与输入相同的数据
现在我们声明一个 `UserIn` 模型,它将包含一个明文密码属性。
-```Python hl_lines="9 11"
-{!../../../docs_src/response_model/tutorial002.py!}
-```
+{* ../../docs_src/response_model/tutorial002.py hl[9,11] *}
我们正在使用此模型声明输入数据,并使用同一模型声明输出数据:
-```Python hl_lines="17-18"
-{!../../../docs_src/response_model/tutorial002.py!}
-```
+{* ../../docs_src/response_model/tutorial002.py hl[17:18] *}
现在,每当浏览器使用一个密码创建用户时,API 都会在响应中返回相同的密码。
@@ -65,52 +51,25 @@ FastAPI 将使用此 `response_model` 来:
但是,如果我们在其他的*路径操作*中使用相同的模型,则可能会将用户的密码发送给每个客户端。
-!!! danger
- 永远不要存储用户的明文密码,也不要在响应中发送密码。
+/// danger
+
+永远不要存储用户的明文密码,也不要在响应中发送密码。
+
+///
## 添加输出模型
相反,我们可以创建一个有明文密码的输入模型和一个没有明文密码的输出模型:
-=== "Python 3.10+"
-
- ```Python hl_lines="9 11 16"
- {!> ../../../docs_src/response_model/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="9 11 16"
- {!> ../../../docs_src/response_model/tutorial003.py!}
- ```
+{* ../../docs_src/response_model/tutorial003_py310.py hl[9,11,16] *}
这样,即便我们的*路径操作函数*将会返回包含密码的相同输入用户:
-=== "Python 3.10+"
-
- ```Python hl_lines="24"
- {!> ../../../docs_src/response_model/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="24"
- {!> ../../../docs_src/response_model/tutorial003.py!}
- ```
+{* ../../docs_src/response_model/tutorial003_py310.py hl[24] *}
...我们已经将 `response_model` 声明为了不包含密码的 `UserOut` 模型:
-=== "Python 3.10+"
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/response_model/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="22"
- {!> ../../../docs_src/response_model/tutorial003.py!}
- ```
+{* ../../docs_src/response_model/tutorial003_py310.py hl[22] *}
因此,**FastAPI** 将会负责过滤掉未在输出模型中声明的所有数据(使用 Pydantic)。
@@ -128,9 +87,7 @@ FastAPI 将使用此 `response_model` 来:
你的响应模型可以具有默认值,例如:
-```Python hl_lines="11 13-14"
-{!../../../docs_src/response_model/tutorial004.py!}
-```
+{* ../../docs_src/response_model/tutorial004.py hl[11,13:14] *}
* `description: Union[str, None] = None` 具有默认值 `None`。
* `tax: float = 10.5` 具有默认值 `10.5`.
@@ -144,9 +101,7 @@ FastAPI 将使用此 `response_model` 来:
你可以设置*路径操作装饰器*的 `response_model_exclude_unset=True` 参数:
-```Python hl_lines="24"
-{!../../../docs_src/response_model/tutorial004.py!}
-```
+{* ../../docs_src/response_model/tutorial004.py hl[24] *}
然后响应中将不会包含那些默认值,而是仅有实际设置的值。
@@ -159,16 +114,22 @@ FastAPI 将使用此 `response_model` 来:
}
```
-!!! info
- FastAPI 通过 Pydantic 模型的 `.dict()` 配合 该方法的 `exclude_unset` 参数 来实现此功能。
+/// info
-!!! info
- 你还可以使用:
+FastAPI 通过 Pydantic 模型的 `.dict()` 配合 该方法的 `exclude_unset` 参数 来实现此功能。
- * `response_model_exclude_defaults=True`
- * `response_model_exclude_none=True`
+///
- 参考 Pydantic 文档 中对 `exclude_defaults` 和 `exclude_none` 的描述。
+/// info
+
+你还可以使用:
+
+* `response_model_exclude_defaults=True`
+* `response_model_exclude_none=True`
+
+参考 Pydantic 文档 中对 `exclude_defaults` 和 `exclude_none` 的描述。
+
+///
#### 默认值字段有实际值的数据
@@ -203,10 +164,13 @@ FastAPI 将使用此 `response_model` 来:
因此,它们将包含在 JSON 响应中。
-!!! tip
- 请注意默认值可以是任何值,而不仅是`None`。
+/// tip
- 它们可以是一个列表(`[]`),一个值为 `10.5`的 `float`,等等。
+请注意默认值可以是任何值,而不仅是`None`。
+
+它们可以是一个列表(`[]`),一个值为 `10.5`的 `float`,等等。
+
+///
### `response_model_include` 和 `response_model_exclude`
@@ -216,29 +180,31 @@ FastAPI 将使用此 `response_model` 来:
如果你只有一个 Pydantic 模型,并且想要从输出中移除一些数据,则可以使用这种快捷方法。
-!!! tip
- 但是依然建议你使用上面提到的主意,使用多个类而不是这些参数。
+/// tip
- 这是因为即使使用 `response_model_include` 或 `response_model_exclude` 来省略某些属性,在应用程序的 OpenAPI 定义(和文档)中生成的 JSON Schema 仍将是完整的模型。
+但是依然建议你使用上面提到的主意,使用多个类而不是这些参数。
- 这也适用于作用类似的 `response_model_by_alias`。
+这是因为即使使用 `response_model_include` 或 `response_model_exclude` 来省略某些属性,在应用程序的 OpenAPI 定义(和文档)中生成的 JSON Schema 仍将是完整的模型。
-```Python hl_lines="31 37"
-{!../../../docs_src/response_model/tutorial005.py!}
-```
+这也适用于作用类似的 `response_model_by_alias`。
-!!! tip
- `{"name", "description"}` 语法创建一个具有这两个值的 `set`。
+///
- 等同于 `set(["name", "description"])`。
+{* ../../docs_src/response_model/tutorial005.py hl[31,37] *}
+
+/// tip
+
+`{"name", "description"}` 语法创建一个具有这两个值的 `set`。
+
+等同于 `set(["name", "description"])`。
+
+///
#### 使用 `list` 而不是 `set`
如果你忘记使用 `set` 而是使用 `list` 或 `tuple`,FastAPI 仍会将其转换为 `set` 并且正常工作:
-```Python hl_lines="31 37"
-{!../../../docs_src/response_model/tutorial006.py!}
-```
+{* ../../docs_src/response_model/tutorial006.py hl[31,37] *}
## 总结
diff --git a/docs/zh/docs/tutorial/response-status-code.md b/docs/zh/docs/tutorial/response-status-code.md
index cc23231b4..aa8032ada 100644
--- a/docs/zh/docs/tutorial/response-status-code.md
+++ b/docs/zh/docs/tutorial/response-status-code.md
@@ -8,19 +8,21 @@
* `@app.delete()`
* 等……
-```Python hl_lines="6"
-{!../../../docs_src/response_status_code/tutorial001.py!}
-```
+{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
-!!! note "笔记"
+/// note | 笔记
- 注意,`status_code` 是(`get`、`post` 等)**装饰器**方法中的参数。与之前的参数和请求体不同,不是*路径操作函数*的参数。
+注意,`status_code` 是(`get`、`post` 等)**装饰器**方法中的参数。与之前的参数和请求体不同,不是*路径操作函数*的参数。
+
+///
`status_code` 参数接收表示 HTTP 状态码的数字。
-!!! info "说明"
+/// info | 说明
- `status_code` 还能接收 `IntEnum` 类型,比如 Python 的 `http.HTTPStatus`。
+`status_code` 还能接收 `IntEnum` 类型,比如 Python 的 `http.HTTPStatus`。
+
+///
它可以:
@@ -29,17 +31,21 @@
-!!! note "笔记"
+/// note | 笔记
- 某些响应状态码表示响应没有响应体(参阅下一章)。
+某些响应状态码表示响应没有响应体(参阅下一章)。
- FastAPI 可以进行识别,并生成表明无响应体的 OpenAPI 文档。
+FastAPI 可以进行识别,并生成表明无响应体的 OpenAPI 文档。
+
+///
## 关于 HTTP 状态码
-!!! note "笔记"
+/// note | 笔记
- 如果已经了解 HTTP 状态码,请跳到下一章。
+如果已经了解 HTTP 状态码,请跳到下一章。
+
+///
在 HTTP 协议中,发送 3 位数的数字状态码是响应的一部分。
@@ -58,17 +64,17 @@
* 对于来自客户端的一般错误,可以只使用 `400`
* `500` 及以上的状态码用于表示服务器端错误。几乎永远不会直接使用这些状态码。应用代码或服务器出现问题时,会自动返回这些状态代码
-!!! tip "提示"
+/// tip | 提示
- 状态码及适用场景的详情,请参阅 MDN 的 HTTP 状态码文档。
+状态码及适用场景的详情,请参阅 MDN 的 HTTP 状态码文档。
+
+///
## 状态码名称快捷方式
再看下之前的例子:
-```Python hl_lines="6"
-{!../../../docs_src/response_status_code/tutorial001.py!}
-```
+{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
`201` 表示**已创建**的状态码。
@@ -76,19 +82,19 @@
可以使用 `fastapi.status` 中的快捷变量。
-```Python hl_lines="1 6"
-{!../../../docs_src/response_status_code/tutorial002.py!}
-```
+{* ../../docs_src/response_status_code/tutorial002.py hl[1,6] *}
这只是一种快捷方式,具有相同的数字代码,但它可以使用编辑器的自动补全功能:
-!!! note "技术细节"
+/// note | 技术细节
- 也可以使用 `from starlette import status`。
+也可以使用 `from starlette import status`。
- 为了让开发者更方便,**FastAPI** 提供了与 `starlette.status` 完全相同的 `fastapi.status`。但它直接来自于 Starlette。
+为了让开发者更方便,**FastAPI** 提供了与 `starlette.status` 完全相同的 `fastapi.status`。但它直接来自于 Starlette。
+
+///
## 更改默认状态码
diff --git a/docs/zh/docs/tutorial/schema-extra-example.md b/docs/zh/docs/tutorial/schema-extra-example.md
index ae204dc61..6c132eed3 100644
--- a/docs/zh/docs/tutorial/schema-extra-example.md
+++ b/docs/zh/docs/tutorial/schema-extra-example.md
@@ -10,17 +10,7 @@
您可以使用 `Config` 和 `schema_extra` 为Pydantic模型声明一个示例,如Pydantic 文档:定制 Schema 中所述:
-=== "Python 3.10+"
-
- ```Python hl_lines="13-21"
- {!> ../../../docs_src/schema_extra_example/tutorial001_py310.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="15-23"
- {!> ../../../docs_src/schema_extra_example/tutorial001.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial001_py310.py hl[13:21] *}
这些额外的信息将按原样添加到输出的JSON模式中。
@@ -28,20 +18,13 @@
在 `Field`, `Path`, `Query`, `Body` 和其他你之后将会看到的工厂函数,你可以为JSON 模式声明额外信息,你也可以通过给工厂函数传递其他的任意参数来给JSON 模式声明额外信息,比如增加 `example`:
-=== "Python 3.10+"
+{* ../../docs_src/schema_extra_example/tutorial002_py310.py hl[2,8:11] *}
- ```Python hl_lines="2 8-11"
- {!> ../../../docs_src/schema_extra_example/tutorial002_py310.py!}
- ```
+/// warning
-=== "Python 3.8+"
+请记住,传递的那些额外参数不会添加任何验证,只会添加注释,用于文档的目的。
- ```Python hl_lines="4 10-13"
- {!> ../../../docs_src/schema_extra_example/tutorial002.py!}
- ```
-
-!!! warning
- 请记住,传递的那些额外参数不会添加任何验证,只会添加注释,用于文档的目的。
+///
## `Body` 额外参数
@@ -49,41 +32,7 @@
比如,你可以将请求体的一个 `example` 传递给 `Body`:
-=== "Python 3.10+"
-
- ```Python hl_lines="22-27"
- {!> ../../../docs_src/schema_extra_example/tutorial003_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="22-27"
- {!> ../../../docs_src/schema_extra_example/tutorial003_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="23-28"
- {!> ../../../docs_src/schema_extra_example/tutorial003_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
-
- ```Python hl_lines="18-23"
- {!> ../../../docs_src/schema_extra_example/tutorial003_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
-
- ```Python hl_lines="20-25"
- {!> ../../../docs_src/schema_extra_example/tutorial003.py!}
- ```
+{* ../../docs_src/schema_extra_example/tutorial003_an_py310.py hl[22:27] *}
## 文档 UI 中的例子
diff --git a/docs/zh/docs/tutorial/security/first-steps.md b/docs/zh/docs/tutorial/security/first-steps.md
index f28cc24f8..225eb2695 100644
--- a/docs/zh/docs/tutorial/security/first-steps.md
+++ b/docs/zh/docs/tutorial/security/first-steps.md
@@ -20,36 +20,19 @@
把下面的示例代码复制到 `main.py`:
-=== "Python 3.9+"
-
- ```Python
- {!> ../../../docs_src/security/tutorial001_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python
- {!> ../../../docs_src/security/tutorial001_an.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- 尽可能选择使用 `Annotated` 的版本。
-
- ```Python
- {!> ../../../docs_src/security/tutorial001.py!}
- ```
+{* ../../docs_src/security/tutorial001_an_py39.py *}
## 运行
-!!! info "说明"
+/// info | 说明
- 先安装 `python-multipart`。
+先安装 `python-multipart`。
- 安装命令: `pip install python-multipart`。
+安装命令: `pip install python-multipart`。
- 这是因为 **OAuth2** 使用**表单数据**发送 `username` 与 `password`。
+这是因为 **OAuth2** 使用**表单数据**发送 `username` 与 `password`。
+
+///
用下面的命令运行该示例:
@@ -71,19 +54,23 @@ $ uvicorn main:app --reload
-!!! check "Authorize 按钮!"
+/// check | Authorize 按钮!
- 页面右上角出现了一个「**Authorize**」按钮。
+页面右上角出现了一个「**Authorize**」按钮。
- *路径操作*的右上角也出现了一个可以点击的小锁图标。
+*路径操作*的右上角也出现了一个可以点击的小锁图标。
+
+///
点击 **Authorize** 按钮,弹出授权表单,输入 `username` 与 `password` 及其它可选字段:
-!!! note "笔记"
+/// note | 笔记
- 目前,在表单中输入内容不会有任何反应,后文会介绍相关内容。
+目前,在表单中输入内容不会有任何反应,后文会介绍相关内容。
+
+///
虽然此文档不是给前端最终用户使用的,但这个自动工具非常实用,可在文档中与所有 API 交互。
@@ -125,39 +112,43 @@ OAuth2 的设计目标是为了让后端或 API 独立于服务器验证用户
本例使用 **OAuth2** 的 **Password** 流以及 **Bearer** 令牌(`Token`)。为此要使用 `OAuth2PasswordBearer` 类。
-!!! info "说明"
+/// info | 说明
- `Bearer` 令牌不是唯一的选择。
+`Bearer` 令牌不是唯一的选择。
- 但它是最适合这个用例的方案。
+但它是最适合这个用例的方案。
- 甚至可以说,它是适用于绝大多数用例的最佳方案,除非您是 OAuth2 的专家,知道为什么其它方案更合适。
+甚至可以说,它是适用于绝大多数用例的最佳方案,除非您是 OAuth2 的专家,知道为什么其它方案更合适。
- 本例中,**FastAPI** 还提供了构建工具。
+本例中,**FastAPI** 还提供了构建工具。
+
+///
创建 `OAuth2PasswordBearer` 的类实例时,要传递 `tokenUrl` 参数。该参数包含客户端(用户浏览器中运行的前端) 的 URL,用于发送 `username` 与 `password`,并获取令牌。
-```Python hl_lines="6"
-{!../../../docs_src/security/tutorial001.py!}
-```
+{* ../../docs_src/security/tutorial001.py hl[6] *}
-!!! tip "提示"
+/// tip | 提示
- 在此,`tokenUrl="token"` 指向的是暂未创建的相对 URL `token`。这个相对 URL 相当于 `./token`。
+在此,`tokenUrl="token"` 指向的是暂未创建的相对 URL `token`。这个相对 URL 相当于 `./token`。
- 因为使用的是相对 URL,如果 API 位于 `https://example.com/`,则指向 `https://example.com/token`。但如果 API 位于 `https://example.com/api/v1/`,它指向的就是`https://example.com/api/v1/token`。
+因为使用的是相对 URL,如果 API 位于 `https://example.com/`,则指向 `https://example.com/token`。但如果 API 位于 `https://example.com/api/v1/`,它指向的就是`https://example.com/api/v1/token`。
- 使用相对 URL 非常重要,可以确保应用在遇到[使用代理](../../advanced/behind-a-proxy.md){.internal-link target=_blank}这样的高级用例时,也能正常运行。
+使用相对 URL 非常重要,可以确保应用在遇到[使用代理](../../advanced/behind-a-proxy.md){.internal-link target=_blank}这样的高级用例时,也能正常运行。
+
+///
该参数不会创建端点或*路径操作*,但会声明客户端用来获取令牌的 URL `/token` 。此信息用于 OpenAPI 及 API 文档。
接下来,学习如何创建实际的路径操作。
-!!! info "说明"
+/// info | 说明
- 严苛的 **Pythonista** 可能不喜欢用 `tokenUrl` 这种命名风格代替 `token_url`。
+严苛的 **Pythonista** 可能不喜欢用 `tokenUrl` 这种命名风格代替 `token_url`。
- 这种命名方式是因为要使用与 OpenAPI 规范中相同的名字。以便在深入校验安全方案时,能通过复制粘贴查找更多相关信息。
+这种命名方式是因为要使用与 OpenAPI 规范中相同的名字。以便在深入校验安全方案时,能通过复制粘贴查找更多相关信息。
+
+///
`oauth2_scheme` 变量是 `OAuth2PasswordBearer` 的实例,也是**可调用项**。
@@ -173,19 +164,19 @@ oauth2_scheme(some, parameters)
接下来,使用 `Depends` 把 `oauth2_scheme` 传入依赖项。
-```Python hl_lines="10"
-{!../../../docs_src/security/tutorial001.py!}
-```
+{* ../../docs_src/security/tutorial001.py hl[10] *}
该依赖项使用字符串(`str`)接收*路径操作函数*的参数 `token` 。
**FastAPI** 使用依赖项在 OpenAPI 概图(及 API 文档)中定义**安全方案**。
-!!! info "技术细节"
+/// info | 技术细节
- **FastAPI** 使用(在依赖项中声明的)类 `OAuth2PasswordBearer` 在 OpenAPI 中定义安全方案,这是因为它继承自 `fastapi.security.oauth2.OAuth2`,而该类又是继承自`fastapi.security.base.SecurityBase`。
+**FastAPI** 使用(在依赖项中声明的)类 `OAuth2PasswordBearer` 在 OpenAPI 中定义安全方案,这是因为它继承自 `fastapi.security.oauth2.OAuth2`,而该类又是继承自`fastapi.security.base.SecurityBase`。
- 所有与 OpenAPI(及 API 文档)集成的安全工具都继承自 `SecurityBase`, 这就是为什么 **FastAPI** 能把它们集成至 OpenAPI 的原因。
+所有与 OpenAPI(及 API 文档)集成的安全工具都继承自 `SecurityBase`, 这就是为什么 **FastAPI** 能把它们集成至 OpenAPI 的原因。
+
+///
## 实现的操作
diff --git a/docs/zh/docs/tutorial/security/get-current-user.md b/docs/zh/docs/tutorial/security/get-current-user.md
index 1f17f5bd9..1f254a103 100644
--- a/docs/zh/docs/tutorial/security/get-current-user.md
+++ b/docs/zh/docs/tutorial/security/get-current-user.md
@@ -2,9 +2,7 @@
上一章中,(基于依赖注入系统的)安全系统向*路径操作函数*传递了 `str` 类型的 `token`:
-```Python hl_lines="10"
-{!../../../docs_src/security/tutorial001.py!}
-```
+{* ../../docs_src/security/tutorial001.py hl[10] *}
但这并不实用。
@@ -17,9 +15,7 @@
与使用 Pydantic 声明请求体相同,并且可在任何位置使用:
-```Python hl_lines="5 12-16"
-{!../../../docs_src/security/tutorial002.py!}
-```
+{* ../../docs_src/security/tutorial002.py hl[5,12:16] *}
## 创建 `get_current_user` 依赖项
@@ -31,42 +27,39 @@
与之前直接在路径操作中的做法相同,新的 `get_current_user` 依赖项从子依赖项 `oauth2_scheme` 中接收 `str` 类型的 `token`:
-```Python hl_lines="25"
-{!../../../docs_src/security/tutorial002.py!}
-```
+{* ../../docs_src/security/tutorial002.py hl[25] *}
## 获取用户
`get_current_user` 使用创建的(伪)工具函数,该函数接收 `str` 类型的令牌,并返回 Pydantic 的 `User` 模型:
-```Python hl_lines="19-22 26-27"
-{!../../../docs_src/security/tutorial002.py!}
-```
+{* ../../docs_src/security/tutorial002.py hl[19:22,26:27] *}
## 注入当前用户
在*路径操作* 的 `Depends` 中使用 `get_current_user`:
-```Python hl_lines="31"
-{!../../../docs_src/security/tutorial002.py!}
-```
+{* ../../docs_src/security/tutorial002.py hl[31] *}
注意,此处把 `current_user` 的类型声明为 Pydantic 的 `User` 模型。
这有助于在函数内部使用代码补全和类型检查。
-!!! tip "提示"
+/// tip | 提示
- 还记得请求体也是使用 Pydantic 模型声明的吧。
+还记得请求体也是使用 Pydantic 模型声明的吧。
- 放心,因为使用了 `Depends`,**FastAPI** 不会搞混。
+放心,因为使用了 `Depends`,**FastAPI** 不会搞混。
-!!! check "检查"
+///
- 依赖系统的这种设计方式可以支持不同的依赖项返回同一个 `User` 模型。
+/// check | 检查
- 而不是局限于只能有一个返回该类型数据的依赖项。
+依赖系统的这种设计方式可以支持不同的依赖项返回同一个 `User` 模型。
+而不是局限于只能有一个返回该类型数据的依赖项。
+
+///
## 其它模型
@@ -101,9 +94,7 @@
所有*路径操作*只需 3 行代码就可以了:
-```Python hl_lines="30-32"
-{!../../../docs_src/security/tutorial002.py!}
-```
+{* ../../docs_src/security/tutorial002.py hl[30:32] *}
## 小结
diff --git a/docs/zh/docs/tutorial/security/index.md b/docs/zh/docs/tutorial/security/index.md
index 0595f5f63..e888a4fe9 100644
--- a/docs/zh/docs/tutorial/security/index.md
+++ b/docs/zh/docs/tutorial/security/index.md
@@ -32,9 +32,11 @@ OAuth2是一个规范,它定义了几种处理身份认证和授权的方法
OAuth2 没有指定如何加密通信,它期望你为应用程序使用 HTTPS 进行通信。
-!!! tip
- 在有关**部署**的章节中,你将了解如何使用 Traefik 和 Let's Encrypt 免费设置 HTTPS。
+/// tip
+在有关**部署**的章节中,你将了解如何使用 Traefik 和 Let's Encrypt 免费设置 HTTPS。
+
+///
## OpenID Connect
@@ -87,10 +89,13 @@ OpenAPI 定义了以下安全方案:
* 此自动发现机制是 OpenID Connect 规范中定义的内容。
-!!! tip
- 集成其他身份认证/授权提供者(例如Google,Facebook,Twitter,GitHub等)也是可能的,而且较为容易。
+/// tip
- 最复杂的问题是创建一个像这样的身份认证/授权提供程序,但是 **FastAPI** 为你提供了轻松完成任务的工具,同时为你解决了重活。
+集成其他身份认证/授权提供者(例如Google,Facebook,Twitter,GitHub等)也是可能的,而且较为容易。
+
+最复杂的问题是创建一个像这样的身份认证/授权提供程序,但是 **FastAPI** 为你提供了轻松完成任务的工具,同时为你解决了重活。
+
+///
## **FastAPI** 实用工具
diff --git a/docs/zh/docs/tutorial/security/oauth2-jwt.md b/docs/zh/docs/tutorial/security/oauth2-jwt.md
index 117f74d3e..7d338419b 100644
--- a/docs/zh/docs/tutorial/security/oauth2-jwt.md
+++ b/docs/zh/docs/tutorial/security/oauth2-jwt.md
@@ -40,11 +40,13 @@ $ pip install pyjwt
-!!! info "说明"
+/// info | 说明
- 如果您打算使用类似 RSA 或 ECDSA 的数字签名算法,您应该安装加密库依赖项 `pyjwt[crypto]`。
+如果您打算使用类似 RSA 或 ECDSA 的数字签名算法,您应该安装加密库依赖项 `pyjwt[crypto]`。
- 您可以在 PyJWT Installation docs 获得更多信息。
+您可以在 PyJWT Installation docs 获得更多信息。
+
+///
## 密码哈希
@@ -80,13 +82,15 @@ $ pip install passlib[bcrypt]
-!!! tip "提示"
+/// tip | 提示
- `passlib` 甚至可以读取 Django、Flask 的安全插件等工具创建的密码。
+`passlib` 甚至可以读取 Django、Flask 的安全插件等工具创建的密码。
- 例如,把 Django 应用的数据共享给 FastAPI 应用的数据库。或利用同一个数据库,可以逐步把应用从 Django 迁移到 FastAPI。
+例如,把 Django 应用的数据共享给 FastAPI 应用的数据库。或利用同一个数据库,可以逐步把应用从 Django 迁移到 FastAPI。
- 并且,用户可以同时从 Django 应用或 FastAPI 应用登录。
+并且,用户可以同时从 Django 应用或 FastAPI 应用登录。
+
+///
## 密码哈希与校验
@@ -94,13 +98,15 @@ $ pip install passlib[bcrypt]
创建用于密码哈希和身份校验的 PassLib **上下文**。
-!!! tip "提示"
+/// tip | 提示
- PassLib 上下文还支持使用不同哈希算法的功能,包括只能校验的已弃用旧算法等。
+PassLib 上下文还支持使用不同哈希算法的功能,包括只能校验的已弃用旧算法等。
- 例如,用它读取和校验其它系统(如 Django)生成的密码,但要使用其它算法,如 Bcrypt,生成新的哈希密码。
+例如,用它读取和校验其它系统(如 Django)生成的密码,但要使用其它算法,如 Bcrypt,生成新的哈希密码。
- 同时,这些功能都是兼容的。
+同时,这些功能都是兼容的。
+
+///
接下来,创建三个工具函数,其中一个函数用于哈希用户的密码。
@@ -108,45 +114,13 @@ $ pip install passlib[bcrypt]
第三个函数用于身份验证,并返回用户。
-=== "Python 3.10+"
+{* ../../docs_src/security/tutorial004_an_py310.py hl[8,49,56:57,60:61,70:76] *}
- ```Python hl_lines="8 49 56-57 60-61 70-76"
- {!> ../../../docs_src/security/tutorial004_an_py310.py!}
- ```
+/// note | 笔记
-=== "Python 3.9+"
+查看新的(伪)数据库 `fake_users_db`,就能看到哈希后的密码:`"$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW"`。
- ```Python hl_lines="8 49 56-57 60-61 70-76"
- {!> ../../../docs_src/security/tutorial004_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="8 50 57-58 61-62 71-77"
- {!> ../../../docs_src/security/tutorial004_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="7 48 55-56 59-60 69-75"
- {!> ../../../docs_src/security/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="8 49 56-57 60-61 70-76"
- {!> ../../../docs_src/security/tutorial004.py!}
- ```
-
-!!! note "笔记"
-
- 查看新的(伪)数据库 `fake_users_db`,就能看到哈希后的密码:`"$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW"`。
+///
## 处理 JWT 令牌
@@ -176,9 +150,7 @@ $ openssl rand -hex 32
创建生成新的访问令牌的工具函数。
-```Python hl_lines="6 12-14 28-30 78-86"
-{!../../../docs_src/security/tutorial004.py!}
-```
+{* ../../docs_src/security/tutorial004.py hl[6,12:14,28:30,78:86] *}
## 更新依赖项
@@ -188,41 +160,7 @@ $ openssl rand -hex 32
如果令牌无效,则直接返回 HTTP 错误。
-=== "Python 3.10+"
-
- ```Python hl_lines="4 7 13-15 29-31 79-87"
- {!> ../../../docs_src/security/tutorial004_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="4 7 13-15 29-31 79-87"
- {!> ../../../docs_src/security/tutorial004_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="4 7 14-16 30-32 80-88"
- {!> ../../../docs_src/security/tutorial004_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="3 6 12-14 28-30 78-86"
- {!> ../../../docs_src/security/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="4 7 13-15 29-31 79-87"
- {!> ../../../docs_src/security/tutorial004.py!}
- ```
+{* ../../docs_src/security/tutorial004_an_py310.py hl[4,7,13:15,29:31,79:87] *}
## 更新 `/token` *路径操作*
@@ -230,41 +168,7 @@ $ openssl rand -hex 32
创建并返回真正的 JWT 访问令牌。
-=== "Python 3.10+"
-
- ```Python hl_lines="118-133"
- {!> ../../../docs_src/security/tutorial004_an_py310.py!}
- ```
-
-=== "Python 3.9+"
-
- ```Python hl_lines="118-133"
- {!> ../../../docs_src/security/tutorial004_an_py39.py!}
- ```
-
-=== "Python 3.8+"
-
- ```Python hl_lines="119-134"
- {!> ../../../docs_src/security/tutorial004_an.py!}
- ```
-
-=== "Python 3.10+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="115-130"
- {!> ../../../docs_src/security/tutorial004_py310.py!}
- ```
-
-=== "Python 3.8+ non-Annotated"
-
- !!! tip
- Prefer to use the `Annotated` version if possible.
-
- ```Python hl_lines="116-131"
- {!> ../../../docs_src/security/tutorial004.py!}
- ```
+{* ../../docs_src/security/tutorial004_an_py310.py hl[118:133] *}
### JWT `sub` 的技术细节
@@ -302,9 +206,11 @@ JWT 规范还包括 `sub` 键,值是令牌的主题。
用户名: `johndoe` 密码: `secret`
-!!! check "检查"
+/// check | 检查
- 注意,代码中没有明文密码**`secret`**,只保存了它的哈希值。
+注意,代码中没有明文密码**`secret`**,只保存了它的哈希值。
+
+///
@@ -325,9 +231,11 @@ JWT 规范还包括 `sub` 键,值是令牌的主题。
-!!! note "笔记"
+/// note | 笔记
- 注意,请求中 `Authorization` 响应头的值以 `Bearer` 开头。
+注意,请求中 `Authorization` 响应头的值以 `Bearer` 开头。
+
+///
## `scopes` 高级用法
diff --git a/docs/zh/docs/tutorial/security/simple-oauth2.md b/docs/zh/docs/tutorial/security/simple-oauth2.md
index 751767ea2..f70678df8 100644
--- a/docs/zh/docs/tutorial/security/simple-oauth2.md
+++ b/docs/zh/docs/tutorial/security/simple-oauth2.md
@@ -32,15 +32,17 @@ OAuth2 还支持客户端发送**`scope`**表单字段。
* 脸书和 Instagram 使用 `instagram_basic`
* 谷歌使用 `https://www.googleapis.com/auth/drive`
-!!! info "说明"
+/// info | 说明
- OAuth2 中,**作用域**只是声明指定权限的字符串。
+OAuth2 中,**作用域**只是声明指定权限的字符串。
- 是否使用冒号 `:` 等符号,或是不是 URL 并不重要。
+是否使用冒号 `:` 等符号,或是不是 URL 并不重要。
- 这些细节只是特定的实现方式。
+这些细节只是特定的实现方式。
- 对 OAuth2 来说,都只是字符串而已。
+对 OAuth2 来说,都只是字符串而已。
+
+///
## 获取 `username` 和 `password` 的代码
@@ -50,9 +52,7 @@ OAuth2 还支持客户端发送**`scope`**表单字段。
首先,导入 `OAuth2PasswordRequestForm`,然后,在 `/token` *路径操作* 中,用 `Depends` 把该类作为依赖项。
-```Python hl_lines="4 76"
-{!../../../docs_src/security/tutorial003.py!}
-```
+{* ../../docs_src/security/tutorial003.py hl[4,76] *}
`OAuth2PasswordRequestForm` 是用以下几项内容声明表单请求体的类依赖项:
@@ -61,32 +61,38 @@ OAuth2 还支持客户端发送**`scope`**表单字段。
* 可选的 `scope` 字段,由多个空格分隔的字符串组成的长字符串
* 可选的 `grant_type`
-!!! tip "提示"
+/// tip | 提示
- 实际上,OAuth2 规范*要求* `grant_type` 字段使用固定值 `password`,但 `OAuth2PasswordRequestForm` 没有作强制约束。
+实际上,OAuth2 规范*要求* `grant_type` 字段使用固定值 `password`,但 `OAuth2PasswordRequestForm` 没有作强制约束。
- 如需强制使用固定值 `password`,则不要用 `OAuth2PasswordRequestForm`,而是用 `OAuth2PasswordRequestFormStrict`。
+如需强制使用固定值 `password`,则不要用 `OAuth2PasswordRequestForm`,而是用 `OAuth2PasswordRequestFormStrict`。
+
+///
* 可选的 `client_id`(本例未使用)
* 可选的 `client_secret`(本例未使用)
-!!! info "说明"
+/// info | 说明
- `OAuth2PasswordRequestForm` 与 `OAuth2PasswordBearer` 一样,都不是 FastAPI 的特殊类。
+`OAuth2PasswordRequestForm` 与 `OAuth2PasswordBearer` 一样,都不是 FastAPI 的特殊类。
- **FastAPI** 把 `OAuth2PasswordBearer` 识别为安全方案。因此,可以通过这种方式把它添加至 OpenAPI。
+**FastAPI** 把 `OAuth2PasswordBearer` 识别为安全方案。因此,可以通过这种方式把它添加至 OpenAPI。
- 但 `OAuth2PasswordRequestForm` 只是可以自行编写的类依赖项,也可以直接声明 `Form` 参数。
+但 `OAuth2PasswordRequestForm` 只是可以自行编写的类依赖项,也可以直接声明 `Form` 参数。
- 但由于这种用例很常见,FastAPI 为了简便,就直接提供了对它的支持。
+但由于这种用例很常见,FastAPI 为了简便,就直接提供了对它的支持。
+
+///
### 使用表单数据
-!!! tip "提示"
+/// tip | 提示
- `OAuth2PasswordRequestForm` 类依赖项的实例没有以空格分隔的长字符串属性 `scope`,但它支持 `scopes` 属性,由已发送的 scope 字符串列表组成。
+`OAuth2PasswordRequestForm` 类依赖项的实例没有以空格分隔的长字符串属性 `scope`,但它支持 `scopes` 属性,由已发送的 scope 字符串列表组成。
- 本例没有使用 `scopes`,但开发者也可以根据需要使用该属性。
+本例没有使用 `scopes`,但开发者也可以根据需要使用该属性。
+
+///
现在,即可使用表单字段 `username`,从(伪)数据库中获取用户数据。
@@ -94,9 +100,7 @@ OAuth2 还支持客户端发送**`scope`**表单字段。
本例使用 `HTTPException` 异常显示此错误:
-```Python hl_lines="3 77-79"
-{!../../../docs_src/security/tutorial003.py!}
-```
+{* ../../docs_src/security/tutorial003.py hl[3,77:79] *}
### 校验密码
@@ -122,9 +126,7 @@ OAuth2 还支持客户端发送**`scope`**表单字段。
这样一来,窃贼就无法在其它应用中使用窃取的密码,要知道,很多用户在所有系统中都使用相同的密码,风险超大。
-```Python hl_lines="80-83"
-{!../../../docs_src/security/tutorial003.py!}
-```
+{* ../../docs_src/security/tutorial003.py hl[80:83] *}
#### 关于 `**user_dict`
@@ -142,9 +144,11 @@ UserInDB(
)
```
-!!! info "说明"
+/// info | 说明
- `user_dict` 的说明,详见[**更多模型**一章](../extra-models.md#user_indict){.internal-link target=_blank}。
+`user_dict` 的说明,详见[**更多模型**一章](../extra-models.md#user_indict){.internal-link target=_blank}。
+
+///
## 返回 Token
@@ -156,25 +160,27 @@ UserInDB(
本例只是简单的演示,返回的 Token 就是 `username`,但这种方式极不安全。
-!!! tip "提示"
+/// tip | 提示
- 下一章介绍使用哈希密码和 JWT Token 的真正安全机制。
+下一章介绍使用哈希密码和 JWT Token 的真正安全机制。
- 但现在,仅关注所需的特定细节。
+但现在,仅关注所需的特定细节。
-```Python hl_lines="85"
-{!../../../docs_src/security/tutorial003.py!}
-```
+///
-!!! tip "提示"
+{* ../../docs_src/security/tutorial003.py hl[85] *}
- 按规范的要求,应像本示例一样,返回带有 `access_token` 和 `token_type` 的 JSON 对象。
+/// tip | 提示
- 这是开发者必须在代码中自行完成的工作,并且要确保使用这些 JSON 的键。
+按规范的要求,应像本示例一样,返回带有 `access_token` 和 `token_type` 的 JSON 对象。
- 这几乎是唯一需要开发者牢记在心,并按规范要求正确执行的事。
+这是开发者必须在代码中自行完成的工作,并且要确保使用这些 JSON 的键。
- **FastAPI** 则负责处理其它的工作。
+这几乎是唯一需要开发者牢记在心,并按规范要求正确执行的事。
+
+**FastAPI** 则负责处理其它的工作。
+
+///
## 更新依赖项
@@ -188,25 +194,25 @@ UserInDB(
因此,在端点中,只有当用户存在、通过身份验证、且状态为激活时,才能获得该用户:
-```Python hl_lines="58-67 69-72 90"
-{!../../../docs_src/security/tutorial003.py!}
-```
+{* ../../docs_src/security/tutorial003.py hl[58:67,69:72,90] *}
-!!! info "说明"
+/// info | 说明
- 此处返回值为 `Bearer` 的响应头 `WWW-Authenticate` 也是规范的一部分。
+此处返回值为 `Bearer` 的响应头 `WWW-Authenticate` 也是规范的一部分。
- 任何 401**UNAUTHORIZED**HTTP(错误)状态码都应返回 `WWW-Authenticate` 响应头。
+任何 401**UNAUTHORIZED**HTTP(错误)状态码都应返回 `WWW-Authenticate` 响应头。
- 本例中,因为使用的是 Bearer Token,该响应头的值应为 `Bearer`。
+本例中,因为使用的是 Bearer Token,该响应头的值应为 `Bearer`。
- 实际上,忽略这个附加响应头,也不会有什么问题。
+实际上,忽略这个附加响应头,也不会有什么问题。
- 之所以在此提供这个附加响应头,是为了符合规范的要求。
+之所以在此提供这个附加响应头,是为了符合规范的要求。
- 说不定什么时候,就有工具用得上它,而且,开发者或用户也可能用得上。
+说不定什么时候,就有工具用得上它,而且,开发者或用户也可能用得上。
- 这就是遵循标准的好处……
+这就是遵循标准的好处……
+
+///
## 实际效果
diff --git a/docs/zh/docs/tutorial/sql-databases.md b/docs/zh/docs/tutorial/sql-databases.md
index 8629b23fa..fbdf3be6c 100644
--- a/docs/zh/docs/tutorial/sql-databases.md
+++ b/docs/zh/docs/tutorial/sql-databases.md
@@ -1,791 +1,360 @@
-# SQL (关系型) 数据库
+# SQL(关系型)数据库
-!!! info
- 这些文档即将被更新。🎉
+**FastAPI** 并不要求您使用 SQL(关系型)数据库。您可以使用**任何**想用的数据库。
- 当前版本假设Pydantic v1和SQLAlchemy版本小于2。
+这里,我们来看一个使用 SQLModel 的示例。
- 新的文档将包括Pydantic v2以及 SQLModel(也是基于SQLAlchemy),一旦SQLModel更新为为使用Pydantic v2。
+**SQLModel** 是基于 SQLAlchemy 和 Pydantic 构建的。它由 **FastAPI** 的同一作者制作,旨在完美匹配需要使用 **SQL 数据库**的 FastAPI 应用程序。
-**FastAPI**不需要你使用SQL(关系型)数据库。
+/// tip
-但是您可以使用任何您想要的关系型数据库。
+您可以使用任何其他您想要的 SQL 或 NoSQL 数据库(在某些情况下称为 “ORM”),FastAPI 不会强迫您使用任何东西。😎
-在这里,让我们看一个使用着[SQLAlchemy](https://www.sqlalchemy.org/)的示例。
+///
-您可以很容易地将其调整为任何SQLAlchemy支持的数据库,如:
+由于 SQLModel 基于 SQLAlchemy,因此您可以轻松使用任何由 SQLAlchemy **支持的数据库**(这也让它们被 SQLModel 支持),例如:
* PostgreSQL
* MySQL
* SQLite
* Oracle
-* Microsoft SQL Server,等等其它数据库
+* Microsoft SQL Server 等.
-在此示例中,我们将使用**SQLite**,因为它使用单个文件并且 在Python中具有集成支持。因此,您可以复制此示例并按原样来运行它。
+在这个例子中,我们将使用 **SQLite**,因为它使用单个文件,并且 Python 对其有集成支持。因此,您可以直接复制这个例子并运行。
-稍后,对于您的产品级别的应用程序,您可能会要使用像**PostgreSQL**这样的数据库服务器。
+之后,对于您的生产应用程序,您可能会想要使用像 PostgreSQL 这样的数据库服务器。
-!!! tip
- 这儿有一个**FastAPI**和**PostgreSQL**的官方项目生成器,全部基于**Docker**,包括前端和更多工具:https://github.com/tiangolo/full-stack-fastapi-postgresql
+/// tip
-!!! note
- 请注意,大部分代码是`SQLAlchemy`的标准代码,您可以用于任何框架。FastAPI特定的代码和往常一样少。
+有一个使用 **FastAPI** 和 **PostgreSQL** 的官方的项目生成器,其中包括了前端和更多工具: https://github.com/fastapi/full-stack-fastapi-template
-## ORMs(对象关系映射)
+///
-**FastAPI**可与任何数据库在任何样式的库中一起与 数据库进行通信。
+这是一个非常简单和简短的教程。如果您想了解一般的数据库、SQL 或更高级的功能,请查看 SQLModel 文档。
-一种常见的模式是使用“ORM”:对象关系映射。
+## 安装 `SQLModel`
-ORM 具有在代码和数据库表(“*关系型”)中的**对象**之间转换(“*映射*”)的工具。
-
-使用 ORM,您通常会在 SQL 数据库中创建一个代表映射的类,该类的每个属性代表一个列,具有名称和类型。
-
-例如,一个类`Pet`可以表示一个 SQL 表`pets`。
-
-该类的每个*实例对象都代表数据库中的一行数据。*
-
-又例如,一个对象`orion_cat`(`Pet`的一个实例)可以有一个属性`orion_cat.type`, 对标数据库中的`type`列。并且该属性的值可以是其它,例如`"cat"`。
-
-这些 ORM 还具有在表或实体之间建立关系的工具(比如创建多表关系)。
-
-这样,您还可以拥有一个属性`orion_cat.owner`,它包含该宠物所有者的数据,这些数据取自另外一个表。
-
-因此,`orion_cat.owner.name`可能是该宠物主人的姓名(来自表`owners`中的列`name`)。
-
-它可能有一个像`"Arquilian"`(一种业务逻辑)。
-
-当您尝试从您的宠物对象访问它时,ORM 将完成所有工作以从相应的表*所有者那里再获取信息。*
-
-常见的 ORM 例如:Django-ORM(Django 框架的一部分)、SQLAlchemy ORM(SQLAlchemy 的一部分,独立于框架)和 Peewee(独立于框架)等。
-
-在这里,我们将看到如何使用**SQLAlchemy ORM**。
-
-以类似的方式,您也可以使用任何其他 ORM。
-
-!!! tip
- 在文档中也有一篇使用 Peewee 的等效的文章。
-
-## 文件结构
-
-对于这些示例,假设您有一个名为的目录`my_super_project`,其中包含一个名为的子目录`sql_app`,其结构如下:
-
-```
-.
-└── sql_app
- ├── __init__.py
- ├── crud.py
- ├── database.py
- ├── main.py
- ├── models.py
- └── schemas.py
-```
-
-该文件`__init__.py`只是一个空文件,但它告诉 Python `sql_app` 是一个包。
-
-现在让我们看看每个文件/模块的作用。
-
-## 安装 SQLAlchemy
-
-首先你需要安装`SQLAlchemy`:
+首先,确保您创建并激活了[虚拟环境](../virtual-environments.md){.internal-link target=_blank},然后安装了 `sqlmodel` :
+
+